Les cookies nous permettent de vous proposer nos services plus facilement. En utilisant nos services, vous nous donnez expressément votre accord pour exploiter ces cookies.En savoir plus OK

Microchip MPLAB-Harmony-Help-Peripheral-Libraries-MPLAB-Harmony-Integrated-Software-Framework-v1-11 Manuel

Microchip- MPLAB-Harmony-Help-Peripheral-Libraries-MPLAB-Harmony-Integrated-Software-Framework-v1-11 - Manuel

Voir également : 
[TXT] Microchip-AN1476-Com..> 2018-11-13 18:55  499K  
[TXT] Microchip-Atmel-ATUC64L4U-32-bit-Atmel-AVR-Microcontroller-Manuel 2018-11-20 16:26  1.9M  
[TXT] Microchip-CAP1188-8-Channel-Capacitive-Touch-Sensor-with-8-LED-Drivers-Manuel 2018-11-13 19:07  1.4M  
[TXT] Microchip-CAP1203-3-..> 2018-11-13 19:06  1.2M  
[TXT] Microchip-CAP1206-6-..> 2018-11-13 18:58  736K  
[TXT] Microchip-CAP1208-8-..> 2018-11-13 19:01  1.0M  
[TXT] Microchip-CAP1293-3-..> 2018-11-13 18:57  620K  
[TXT] Microchip-CAP1296-6-..> 2018-11-13 19:00  883K  
[TXT] Microchip-CAP1298-8-..> 2018-11-13 19:03  1.1M  
[TXT] Microchip-SEC1110-Sm..> 2018-11-13 18:48  479K  
[TXT] Microchip-SEC1210-Sm..> 2018-11-13 18:52  479K

Au format texte :

MPLAB® Harmony Help - Peripheral Libraries MPLAB Harmony Integrated Software Framework v1.11 © 2013-2017 Microchip Technology Inc. All rights reserved. Peripheral Libraries Help This section provides descriptions of the peripheral libraries that are available in MPLAB Harmony. Description The source code for the MPLAB Harmony Peripheral Libraries (PLIBs) is distributed in the installation (/framework/peripheral). Each PLIB folder has (at least) two sub-folders: processor and templates. The files within the processor directory are generated mechanically during the MPLAB Harmony development process. These files define register macro translations and translate between the API function prototypes and different variants of the "inline" function implementations that are contained in the templates folder. With a few exceptions PLIBs are implemented as C-language inline functions and translated by the preprocessor at build time. If almost any optimization is used and constants are passed into them, each call will normally compile away to just a few bytes of code. Prebuilt binary (.a) files are also provided (built at a -O3 optimization level) for times when no optimization is used or any time the compiler decides to generate a true function call instead of inlining the function. The prebuilt binary (.a) libraries are generated by changing the definitions of the PLIB_INLINE and PLIB_INLINE_API macros attached to the PLIB implementations from "inline extern" to just "extern" when the binaries are built. A MPLAB X IDE project is provided in the /build/framework/peripheral folder to allow a user to rebuild these binaries, if desired. Be sure to inspect the compiler settings and post-build steps, to see how this is done and to ensure the desired settings are used. Peripheral Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2 Peripheral Library Overview This topic provides an overview of the peripheral libraries that are available in MPLAB Harmony. Introduction This topic provides an overview of the peripheral libraries in MPLAB Harmony. Description Supported PIC32 Devices and Release Type Note: Refer to the Release Contents > Peripheral Libraries section in the MPLAB Harmony Release Notes for the list of supported PIC32 devices and their release type. A PDF copy of the release notes is provided in the /doc folder of your installation. 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) UART peripheral module may have three features, as shown in the following diagram. Every feature of a peripheral will have one or more primitive operations that can be performed using that feature. These operations are named in a way that identifies the module, feature, and operation and the fact that they are Peripheral Library functions, as shown in the following figure. The simplified UART peripheral example has a "baud rate" feature. That feature may have two operations that it can perform. 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. Example C-language function signatures of these operations is as follows: 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 give 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. Peripheral Libraries Help Peripheral Library Overview Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 3 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 a the peripheral on the microcontroller in use, the functions will be supported; however, 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. Peripheral libraries are primarily implemented as C-language "inline" functions. This allows the implementation of each function to be selected at build time, based upon the processor selection. To facilitate this, MPLAB Harmony peripheral libraries are implemented in layers of C-language header (.h) files, as shown in the following diagram. For a given peripheral, "Interface Header" defines set of functions and data types (although, potentially not all of the data types, as discussed in a following section) that make up the interface to that peripheral library. To select the correct implementation for each processor, a "Peripheral Processor Selector Header" includes only the appropriate "Peripheral Processor Header" for the selected processor. This header then acts as a "mapping" header that translates the interface functions defined in the interface header to the correct implementation variant template for each function in the "Template Implementation" files. This may seem a little confusing at first, but since all functions are implemented in header files as "inline" functions, the compiler can perform all of the mapping at build time, resulting in very small static implementations when static data is passed to the PLIB functions. One more key concept is that, although peripheral libraries do provide a level of abstraction, they are still very low level. PLIBs combine accesses to multiple registers to implement a single operation when possible. They hiding register details from the caller and provide a consistent "functional" interface to a peripheral that hides differences in implementation variants. But, PLIBs do not manage the state of the peripheral to keep it running and they do not control access to the peripheral to prevent conflicts between different clients. Those jobs belong to the device drivers. 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. And, 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 Peripheral Libraries Help Peripheral Library Overview Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 4 module in the system that does this and it then becomes responsible for the correct operation that peripheral instance in that system. 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. Configuring a Library The library is configured for the supported processor when the processor is chosen in the MPLAB X IDE. Description Peripheral library interfaces are common across all supported processors. But, their implementations are part specific and are provided in two forms that must normally be used together to avoid the possibility of build errors. The first form of the PLIB implementation is as a set of C-language "inline" functions found in .h header files in the /framework/peripheral folder in the MPLAB Harmony installation. The correct implementation template files for the functions supported by each variant of a feature found on a selected processor is selected and included in the header file hierarchy when a PLIB interface header is included in a source file that uses it (either directly or by including peripheral.h). The second form in which the peripheral library implementations are provided is as a set of part-specific prebuilt binary library .a files (available in the /bin/framework/peripheral folder in the MPLAB Harmony installation. To ensure that your MPLAB Harmony project builds correctly (regardless of the level of optimization selected), you must do two things. You must include the appropriate PLIB interface header file (either by including peripheral.h or the specific PLIB interface header) in any C-language file that calls a PLIB function. And, you must include the appropriate prebuilt binary library file (the one whose file name includes the appropriate part name) for the processor you selected in your MPLAB X IDE project. Both of these steps are necessary because the compiler decides at build time if it will generate an actual function call to each PLIB function or if it will generate the function directly in line with the code that calls it. When the optimization level is high enough, the compiler will directly generate the PLIB function code inline with the calling code and no prebuilt library would be required. But, if the compiler "judges" that the function is too large to inline (or if optimizations are turned off), it will generate an actual function call. When this happens, the prebuilt library is required or the linker will generate an error when it tries to link the function call to an actual implementation. Since the compiler makes this determination for each function call it encounters, the safest choice is to always include the prebuilt binary .a file in your project. Fortunately, the MPLAB Harmony installation provides prebuilt binary .a forms of the peripheral libraries that were built using a "-O3" level of optimization so that users of free versions of the compiler, which do not support this advanced level of optimization, can benefit from them. This level of optimization usually provides the best over-all compromise between code size and speed. However, if a different level of optimization is desired, users of the pro version of the compiler can rebuild the peripheral library .a file using the MPLAB X IDE project provided in the /build/framework/peripheral folder of the MPLAB Harmony installation. To build the binary .a form of the peripheral libraries, the PLIBs require the project to define two macros before any file that includes any PLIB header. These macros are used to enable or disable the "inline" attribute on the peripheral library function definitions so that they can be built into a binary .a file that exports the PLIB API function symbols. These macros, their usage, and their default definitions are described as follows. Macro: PLIB_INLINE_API Summary: Determines if PLIB interface (API) functions are treated by the compiler as inline or extern (called) functions. Description: This macro is used as an attribute of every peripheral library interface (API) function. Its default definition allows the compiler to choose to either generate the function directly in line with the calling code or to generate an actual function call which must later be linked to an actual function implementation, based on the size of the code generated with the current optimization settings. Remarks: The default definition of this macro is: #ifndef PLIB_INLINE_API #define PLIB_INLINE_API extern inline #endif To build a binary .a form of the peripheral libraries, define this macro as shown in the following example to export all PLIB API functions so that calls to them can be linked to the library generated. #define PLIB_INLINE_API extern Macro: PLIB_INLINE Summary: Determines if PLIB support functions are generated as static inline or extern inline functions. Peripheral Libraries Help Peripheral Library Overview Configuring a Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 5 Description: This macro is used as an attribute of every peripheral library (PLIB) support function. PLIB support functions are functions that are called by the PLIB interface (API) functions, but are not themselves intended to be exported as PLIB interface functions. This macro’s default definition prevents the compiler from generating superfluous error messages that would occur if the PLIB support functions were declared with a different scope (static versus extern) from the PLIB interface functions, which would occur when the PLIB headers are included in calling code. This superfluous error message would occur because, the support functions do not need to be exported when a binary .a file is generated (and, thus should be declared with "static" scope). But, the compiler would detect the mismatch between the scope of the support functions when the API functions are declared with external scope when the PLIBs are directly included in calling code. Remarks: The default definition of this macro is: #ifndef PLIB_INLINE #define PLIB_INLINE extern inline #endif To build a binary .a form of the peripheral libraries, define this macro as shown in the following example. This prevents the binary .a library from exporting all PLIB support functions, dramatically reducing the size of the generated library’s symbol table. #define PLIB_INLINE static inline Peripheral Libraries Help Peripheral Library Overview Configuring a Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 6 Peripheral Library Porting Example Peripheral Library Porting Example Help Introduction Provides an example on how to port a legacy (i.e., prior to MPLAB Harmony) USART Peripheral Library (PLIB) demonstration application to a MPLAB Harmony application using the MPLAB Harmony Configurator (MHC). Description This section describes the process to port the legacy UART PLIB Interrupt demonstration application (/examples/plib_examples/uart/uart_interrupt) to MPLAB Harmony. The following assumptions are made: • The PIC32MX795F512L device will be used; however, the process described in this section is applicable for other PIC32 devices with appropriate changes • The Explorer 16 Development Board is the hardware used in this example • For the v1.33 MPLAB XC32 C/C++ Compiler, the examples folder is not present. To view the legacy USART PLIB example, refer to v1.31 or earlier of the MPLAB XC32 C/C++ compiler. Porting Procedure Describes the steps to set up the porting process. Description Step 1: Install the latest version of MPLAB Harmony. Throughout this porting guide, it is assumed that MPLAB Harmony is installed in its default location: C:/microchip/harmony/. The folder is assumed to be the root directory and all further steps will be explained relative to this root folder. Step 2: Open MPLAB X IDE. Step 3: Since the project will be created using the MHC, ensure that the MHC plug-in has been installed in MPLAB X IDE. You can verify the installation by selecting Tools > Embedded. If MHC is installed, you will see MPLAB Harmony Configurator is available as an option. Refer to Installing a Plug-in Module for information on installing the plug-in. Step 4: Select File > New Project or click the New Project icon in MPLAB X IDE. In Categories, select Microchip Embedded and in Projects select MPLAB Harmony Project from the list of available project templates, and then click Next to launch the Microchip Harmony Configurator Project Wizard. Step 5: Specify the following in the New Project dialog: Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 7 • Project Location: /apps/examples/peripheral/usart • Project Name: uart_basic • Configuration Name: pic32mx795_pim_e16 • Target Device of PIC32MX795F512L Step 6: Once the project is created, the configuration name will be set as "pic32mx795_pim_e16", as shown in the following figure. Step 7: In the MPLAB Harmony Configurator tab, click Configuration. The Configuration Management dialog appears, which lists the folder path where the default configurator file (.mhc) will be saved. It is recommended not to modify the default path. Click Save to continue. Step 8: In the MPLAB Harmony Configuration tab, configure the Device Configuration, Harmony Framework Configuration and BSP Configuration by selecting appropriate items from each drop down menu. • Device Configuration: Since the controller should be running at 80 MHz with an 8 MHz external crystal, the configuration bits are set from the drop down menu, as shown in the following figure Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 8 • Harmony Framework Configuration: To enabler use of the UART Peripheral Library, the UART driver should be selected in the STATIC configuration in Interrupt mode, as shown in the following figure • UART Configuration: Configure the UART2 with baud rate set to 9600, and interrupt enabled only for RX and Error. Also, set the other UART parameters, as shown in the following figure. Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 9 • BSP Configuration: Configure the BSP to use the PIC32MX795F512L and Explorer 16 Development Board, as shown in the following figure Step 9: Click Generate. Since, the configurations were modified from the default values, MHC will ask whether or not the new configuration setting file (.mhc) should be saved. Click Save to continue. Step 10: Click Generate. Once the files are generated, the header, source, and library files will be added to the uart_basic project. The explanation of each logical folder is as follows: • app – Contains all application specific source files • bsp – Contains all board specific source files • framework – Contains all framework files from MPLAB Harmony • system_config – Contains the system and application configuration, initialization, and Interrupt Service Routine (ISR) Step 11: At this point in the process, the system_init.c file will have functions/code to initialize the device clock and initialize the UART2. The code will be consistent to the settings previously done with MHC in Step 8. Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 10 Step 12: Since the LEDs on the Explorer 16 Development Board are controlled by pins of PIC32MX795F512L device, which are shared with the JTAG function, JTAG should be disabled by manually adding the PLIB_DEVCON_JTAGPortDisable function in system_init.c. In addition, manually add the functions to set Multi-vector mode (PLIB_INT_MultiVectorSelect) and enable interrupt (PLIB_INT_Enable). /* Initialize System Services */ PLIB_DEVCON_JTAGPortDisable(DEVCON_ID_0); /* Enable multi-vectored interrupts, enable the generation of interrupts to the CPU */ PLIB_INT_MultiVectorSelect(INT_ID_0); PLIB_INT_Enable(INT_ID_0); Step 13: In the ISR function of the system_interrupt.c file, add code to echo back the received character. Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 11 /* Make sure receive buffer has data available */ if (PLIB_USART_ReceiverDataIsAvailable(USART_ID_2)) { /* Get the data from the buffer */ appData.data = PLIB_USART_ReceiverByteReceive(USART_ID_2); } appData.InterruptFlag = true; ; Step 14: In the file app.h, define the application-specific members of the APP_STATES enumeration. /* USART Enable State */ USART_ENABLE, /* USART Transmit First string */ USART_TRANSMIT_FIRST_STRING, /* USART Transmit Second string */ USART_TRANSMIT_SECOND_STRING, /* USART Receive State */ USART_RECEIVE_DONE Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 12 Step 15: For APP_DATA structure, define three variables. The first variable is of type Boolean to act as a flag for interrupt indication, the second pointer variable will hold the address of the string that needs to be transmitted to the UART, and the third variable will hold the data received from the UART. const char *stringPointer; char data; bool InterruptFlag; Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 13 Step 16: Towards the end of the file, insert the prototype declaration for two functions: PutCharacter and WriteString. These functions will later be added to app.c (in Step 20). Also, declare the extern APP_DATA appData, so that the appData variable is available across the project. bool PutCharacter(const char character); bool WriteString(void); extern APP_DATA appData; Step 17: In the APP_Initialize of the app.c file, add code to set the initial state of application. /* Place the App state machine in its initial state. */ appData.state = USART_ENABLE; appData.InterruptFlag = false; Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 14 Step 18: Declare two global strings: string1 and string2. const char *string1 = "*** UART Interrupt-driven Application Example ***\r\n"; const char *string2 = "*** Type some characters and observe the LED turn ON ***\r\n"; Step 19: Next, add application-specific code to the APP_Tasks function. void APP_Tasks ( void ) { /* check the application state*/ switch ( appData.state ) { case USART_ENABLE: /* Enable the UART module*/ PLIB_USART_Enable(USART_ID_2); appData.stringPointer = string1; appData.state = USART_TRANSMIT_FIRST_STRING; break; case USART_TRANSMIT_FIRST_STRING: if(true == WriteString()) { appData.state = USART_TRANSMIT_SECOND_STRING; appData.stringPointer = string2; } break; case USART_TRANSMIT_SECOND_STRING: if(true == WriteString()) Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 15 { appData.state = USART_RECEIVE_DONE; } break; case USART_RECEIVE_DONE: if (appData.InterruptFlag) { if(true == PutCharacter(appData.data)) { BSP_LEDOn(BSP_LED_3); appData.InterruptFlag = false; } } break; default: SYS_DEBUG (SYS_ERROR_FATAL,"ERROR! Invalid state\r\n"); while (1); } } Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 16 Step 20: Next, add functions for PutCharacter and WriteString. bool WriteString(void) { if(*appData.stringPointer == '\0') { return true; } /* Write a character at a time, only if transmitter is empty */ while (PLIB_USART_TransmitterIsEmpty(USART_ID_2)) { /* Send character */ PLIB_USART_TransmitterByteSend(USART_ID_2, *appData.stringPointer); /* Increment to address of next character */ appData.stringPointer++; if(*appData.stringPointer == '\0') { return true; Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 17 } } return false; } bool PutCharacter(const char character) { /* Check if buffer is empty for a new transmission */ if(PLIB_USART_TransmitterIsEmpty(USART_ID_2)) { /* Send character */ PLIB_USART_TransmitterByteSend(USART_ID_2, character); return true; } else return false; } Step 21: At this point in the process, all of the files have been added to the project with the proper code. Once the project is built, it should build without any errors or warnings. Step 22: Once the device is programmed and run, a serial cable should be connected to the Explorer 16 Development Board. The appropriate COM port is selected with a baud rate of 9600. As shown in the following RealTerm example, the terminal will echo the typed characters and the LED on the Explorer 16 Development Board will illuminate. Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 18 Notes: 1. Refer to the USART Peripheral Library section in the MPLAB Harmony help for a detailed explanation and the example code for the peripheral library functions used in the application. 2. The demonstration code is provided at the same location /apps/examples/peripheral/usart. Peripheral Libraries Help Peripheral Library Porting Example Porting Procedure © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 19 ADC Peripheral Library This section describes the Analog-to-Digital Converter (ADC) Peripheral Library. Introduction This library provides a low-level abstraction of the Analog-to-Digital Converter (ADC) module, which is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description An ADC is an analog peripheral that converts a continuous quantity to a discrete digital number. An ADC is a signal conversion process that periodically samples and converts a continuously varying signal - analog level into digital values. An ADC might be used to make an isolated measurement. ADCs are also used to quantize time-varying signals by turning them into a sequence of digital samples. This results in the signal being quantized in both time and value. The resolution of a converter indicates the number of discrete values it can produce over the range of analog values. Using the Library This topic describes the basic architecture of the ADC Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_adc.h The interface to the ADC library is defined in the plib_adc.h header file, which is included by the peripheral.h peripheral library header file. Any C language source (.c) file that uses the ADC library must include peripheral.h. Library File: The ADC peripheral library is part of the processor-specific peripheral library installed with the compiler. This library is automatically available (in the default search path) for any project built using a Microchip compiler. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the ADC module on Microchip microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The ADC module accepts an analog signal at any one instance and converts it to a corresponding 10-bit digital value. It can accommodate a number of analog inputs and separate reference inputs; the actual number available on a particular device depends on the package size. Hardware Abstraction Block Diagram A combination of input multiplexers can select the signal to be converted from multiple analog input pins. The entire multiplexer path includes provision for differential analog input, although the number of negative input pins is limited, and the signal difference must remain positive (i.e., unipolar). Sampling Logic An internal Sample and Hold (S&H) circuit acquires a sample of an input signal, and then holds that value constant during the conversion process. The purpose of the S&H circuitry is to take a snapshot of the sensor signal and hold the value. The sampled voltage is held and converted to a digital value, which strictly speaking, represents the ratio of that input voltage to a reference voltage. Configuration choices can allow connection of an external reference or use of the device power and ground (AVDD and AVSS). Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 20 Conversion Logic The heart of the ADC is the conversion logic that converts the analog signal value into its equivalent discrete representation. Conversions can be started individually by program control, continuously free-running, or triggered by selected hardware events. A single channel may be repeatedly converted, alternate conversions may be performed on two channels, or any or all of the channels may be sequentially scanned and converted according to a user-defined bit map. Result Handling The resulting conversion output is 10-bit digital number in a 16-bit word. ADC Timing Details Sample time is the time that the ADC module’s S&H circuit is connected to the analog input pin. The sample time may be started and ended automatically by the ADC’s hardware or under direct program control. There is a minimum sample time to ensure that the S&H circuit will provide sufficient accuracy for the analog-to-digital conversion. Conversion time is the time required for the ADC to convert the voltage held by the S&H circuit. The conversion trigger ends the sampling time and begins an analog-to-digital conversion or a repeating sequence. The conversion trigger sources can be taken from a variety of hardware sources or can be controlled directly in software. Once the conversion is complete, the S&H circuit can be reconnected to the input pin and a CPU interrupt may be generated. The sum of the sample time and the analog-to-digital conversion time provides the total ADC sequence time. The following figure shows the basic conversion sequence and the relationship between intervals. ADC Sample/Convert Sequence The conversion trigger sources can be taken from a variety of hardware sources, or can be controlled directly by software. One of the conversion trigger options is an auto-conversion, which uses a counter and the ADC clock to set the time between auto-conversions. The Auto-Sample mode and auto-conversion trigger can be used together to provide continuous automatic conversions without software intervention. A sample/convert sequence that uses multiple S&H channels can be simultaneously sampled or sequentially sampled. Simultaneously sampling multiple signals ensures that the snapshot of the analog inputs occurs at precisely the same time for all inputs. Sequential sampling takes a snapshot of each analog input just before conversion starts on that input. The sampling of multiple inputs is not correlated. Channel Multiplexers On some devices, S&H circuits have analog multiplexers on both their non-inverting and inverting inputs to select which analog input(s) are sampled. The ADC of some devices incorporate two independent sets of input multiplexers (MUX A and MUX B), which allow users to choose the analog channels that are to be sampled. Functionally, MUX A and MUX B are very similar to each other. Both multiplexers allow any of the analog input channels to be selected for individual sampling and allow selection of a negative reference source for differential signals. In addition, MUX A can be configured for sequential analog channel scanning. By default the ADC only samples and converts the inputs selected by MUX A. There is also a possibility to alternate between two sets of inputs selected by MUX A and MUX B during successive samples. MUX Abstraction Model Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 21 When using MUX A to select analog inputs, the ADC module has the ability to scan multiple analog channels sequentially. Input Selection The ADC module provides a flexible mechanism to select analog inputs for conversion: • Fixed input selection • Alternate input selection • Channel scanning Fixed Input Selection This is achieved through one or more of the S&H channels available in the device. The S&H channels are connected to the analog input pins through the analog multiplexer. Alternate Sampling In an Alternate Input Selection mode, the ADC completes one sweep using the MUX A selection, and then another sweep using the MUX B selection, and then another sweep using the MUX A selection, and so on. Alternate Input Selection in 2-Channel Sequential Sampling Configuration Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 22 Channel Scanning On some devices, the ADC module supports the Channel Scan mode using S&H Channel 0 (CH0). The number of inputs scanned is software selectable. Any subset of the analog inputs from AN0 to AN31 (depending on the number of analog inputs present on a specific device) can be selected for conversion. The selected inputs are converted in ascending order. For example, if the input selection includes AN4, AN1, and AN3, the conversion sequence is AN1, AN3, and AN4. Scan Four Analog Inputs Using CH0 Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the ADC Peripheral Library. Library Interface Section Description General Configuration Interface routines for: • Voltage reference selection (positive/negative) • Channel group selection • Positive/negative channel selection • Add/remove channels for scan • Enabling/disabling the ADC module • Enabling/disabling the calibration • Stop in Idle enable/disable • Internal reference channel enable/disable MUX Selection and Channel Scan Interface routines for: • Channel 0 positive/negative input selection for MUX A/MUX B • MUX A scan enable/disable Sample and Hold Control Logic Interface routines for: • Sampling start/stop, status • Enabling/disabling of sample auto start • Acquisition/auto-sample time selection • Sample per interrupt selection Conversion Control Logic Interface routines for: • Conversion start/status • Conversion clock selection set/get • Conversion clock source selection • Conversion trigger source selection • Conversion stop sequence enable/disable Output Configuration Interface routines for: • Result format selection • Result buffer fill status • Result buffer mode select • Result based on the buffer index Feature Existence Functions These functions determine whether or not a particular feature is supported by the device. Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 23 How the Library Works How the Library Works The following processes are involved while using an ADC module: • Initialization • Controlling the sampling process • Controlling the conversion process • Accessing the results buffer General The ADC conversion process can be thought of in terms of a finite state machine. The sample state represents the time that the input channel is connected to the S&H circuit and the signal is passed to the converter input. The convert state is transitory; the module enters this state as soon as it exits the sample state and transitions to a different state when that is done. The inactive state is the default state prior to module initialization and following a software-controlled conversion; it can be avoided in operation by using Auto-Sample mode. Description ADC Conversion Sequence or State Machine Initialization This topic provides information on the different processes needed to perform an analog-to-digital conversion. Description The following processes should be followed for performing an analog-to-digital conversion: Initialize the ADC Module: Number Description Functions associated 1 Selecting the voltage reference source Idle mode control PLIB_ADC_VoltageReferenceSelect PLIB_ADC_StopInIdleEnable PLIB_ADC_StopInIdleDisable 2 Selecting the ADC conversion clock PLIB_ADC_ConversionClockSet Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 24 3 Input channel selection Configuring MUX A and MUX B inputs, Alternating MUX A and MUX B input selections, Scanning through several inputs Scan Mask Selection PLIB_ADC_InputScanMaskAdd PLIB_ADC_InputScanMaskRemove Positive Inputs PLIB_ADC_MuxChannel0InputPositiveSelect Negative Inputs PLIB_ADC_MuxChannel0InputNegativeSelect Scan Mode Selection PLIB_ADC_MuxAInputScanEnable PLIB_ADC_MuxAInputScanDisable 4 Enabling the ADC module PLIB_ADC_Enable 5 Determine how sampling will occur Sampling Control PLIB_ADC_SamplingModeSelect PLIB_ADC_SampleAcquisitionTimeSet 6 Selecting Manual or Auto-Sampling PLIB_ADC_SampleAutoStartEnable PLIB_ADC_SampleAutoStartDisable PLIB_ADC_SamplingStart 7 Select conversion trigger and sampling time PLIB_ADC_ConversionStart PLIB_ADC_ConversionClockSourceSelect PLIB_ADC_ConversionTriggerSourceSelect PLIB_ADC_ConversionStopSequenceEnable PLIB_ADC_ConversionStopSequenceDisable 8 Select how conversion results are stored in buffer PLIB_ADC_ResultBufferModeSelect 9 Select the result format PLIB_ADC_ResultFormatSelect 10 Select the number of readings per interrupt PLIB_ADC_SamplesPerInterruptSelect The ADC is configured by the following steps: 1. Select the acquisition time using PLIB_ADC_SampleAcquisitionTimeSet. 2. Select the conversion clock for ADC using PLIB_ADC_ConversionClockSet. 3. The reference for ADC can be set using the function PLIB_ADC_VoltageReferenceSelect. 4. Select the appropriate analog MUX and analog input where the analog voltage is connected. 5. Select the appropriate trigger source using PLIB_ADC_ConversionTriggerSourceSelect. 6. Configure the ADC interrupt (if required): • Clear the interrupt status flag • Select the ADC interrupt priority • Enable ADC interrupt 7. Turn on the ADC module using PLIB_ADC_Enable. Example Initialization: // Include all channels in scan PLIB_ADC_InputScanMaskAdd(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcquisitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 20000000); // Set the interrupt every 16 samples PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_16SAMPLES_PER_INTERRUPT); // Enable scanning of channels PLIB_ADC_MuxAInputScanEnable(MY_ADC_INSTANCE); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 25 Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. Controlling the Sampling Process This topic describes the modes and related sampling functionality for the sampling process. Description The sampling process can be set up using the following two modes: Manual Sampling Calling PLIB_ADC_SamplingStart causes the ADC to begin sampling. One of several options as discussed in "Controlling the Conversion Process" can be used to end sampling and complete conversions. Sampling does not resume until PLIB_ADC_SamplingStart is called again. Automatic Sampling Setting the ADC in the Auto-Sampling mode using PLIB_ADC_SampleAutoStartEnable automatically begins sampling a channel whenever a conversion is not active on that channel. One of several options can be used to end sampling and complete conversions, as discussed in "Controlling the Conversion Process". If the simultaneous sampling is selected using PLIB_ADC_SamplingModeSelect with parameter ADC_SAMPLING_MODE_SIMULTANEOUS, sampling on a channel resumes after the conversion of all channels completes. Other sampling related functionality: • Monitoring Sample Status: PLIB_ADC_SamplingIsActive obtains the status as sampling or holding for the ADC module. • Aborting a Sample: While in Manual Sampling mode, calling PLIB_ADC_SamplingStop will terminate sampling. If the conversion trigger source is selected as ADC_CONVERSION_TRIGGER_SAMP_CLEAR using PLIB_ADC_ConversionTriggerSourceSelect, this causes a conversion to start automatically. While in Auto-Sampling mode, calling PLIB_ADC_SampleAutoStartEnable does not terminate an outgoing sample/convert sequence; however, sampling will not resume after a subsequent conversion. • Sampling Modes: Different sampling modes can be changed using PLIB_ADC_SamplingModeSelect with the appropriate parameter such as ADC_SAMPLING_MODE_ALTERNATE_INPUT for alternate input mode, ADC_SAMPLING_MODE_SIMULTANEOUS for simultaneous sampling mode, or ADC_SAMPLING_MODE_SEQUENTIAL for the sequential sampling mode. There is a possibility to combine the sampling modes say the Alternate input mode with either the simultaneous or the sequential sampling modes. Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. Controlling the Conversion Process The conversion trigger source will terminate sampling and start a selected sequence of conversions. It is also possible to obtain the value of the conversion clock, which is obtained by calling PLIB_ADC_ConversionClockGet. 'PLIB_ADC_ConversionTriggerSourceSelect' selects the source of the conversion trigger. Description Conversion can be started in one of the following three ways: Manual Conversion Sequence Manual Sample Start, Manual Conversion Start When ADC_CONVERSION_TRIGGER_SAMP_CLEAR is selected using PLIB_ADC_ConversionTriggerSourceSelect, the conversion trigger is under software control. Calls to PLIB_ADC_SamplingStop will stop the sampling and start the conversion sequence. The user must call PLIB_ADC_SamplingStart and PLIB_ADC_SamplingStop in a timed manner, to ensure adequate sampling time. Converting One Channel, Manual Sample Start, Manual Conversion Start Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 26 Automatic Sample Start, Manual Conversion Start Automatic sampling is initiated using PLIB_ADC_SampleAutoStartEnable, calling PLIB_ADC_SamplingStop will terminate sampling and start conversion. After the conversion, the sampling starts again automatically. The user must call PLIB_ADC_SamplingStop in a timed manner, to ensure adequate sampling time. Wait for required acquisition/auto sample time (minimum of 1 TAD), and then call PLIB_ADC_SamplingStop to start the conversion process. Converting One Channel, Automatic Sample Start, Manual Conversion Start Clocked Conversion Sequence Manual Sample Start and TAD based Conversion Start When ADC_CONVERSION_TRIGGER_INTERNAL_COUNT is selected using PLIB_ADC_ConversionTriggerSourceSelect, the conversion trigger is under analog-to-digital clock control. PLIB_ADC_SampleAcquisitionTimeSet selects the TAD clock cycles between the start of sampling and the start of conversion. [Minimum 1 clock cycle has to be selected to ensure the sampling requirements are met]. PLIB_ADC_SamplingStart starts the sampling for the configured acquisition time, and then PLIB_ADC_SamplingStop starts the conversion process. Converting One Channel, Manual Sample Start, TAD-Based Conversion Start Auto Sample Start and TAD based Conversion Start or Free Running Sample Conversion With the selection of ADC_CONVERSION_TRIGGER_INTERNAL_COUNT using PLIB_ADC_ConversionTriggerSourceSelect and Automatic sampling initiation using PLIB_ADC_SampleAutoStartEnable allows the ADC module to schedule sample/conversion sequences with no intervention by the user or other device resources. Converting One Channel, Auto-Sample Start, TAD-Based Conversion Start Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 27 Event Trigger Conversion Start It may be necessary to synchronize the end of sampling and the start of conversion with some other time event. The ADC module may use one of following as conversion trigger sequences: • External Pin Trigger: When ADC_CONVERSION_TRIGGER_INT0_TRANSITION is selected using PLIB_ADC_ConversionTriggerSourceSelect • General Purpose Timer Compare Match: When ADC_CONVERSION_TRIGGER_TMR3_COMPARE_MATCH or ADC_CONVERSION_TRIGGER_TMR5_COMPARE_MATCH is selected using PLIB_ADC_ConversionTriggerSourceSelect Both of the event trigger conversion modes previously described can be used in combination with auto-sampling (PLIB_ADC_SampleAutoStartEnable) to cause the ADC to synchronize the sample conversion events to the trigger pulse source. Users should note that some devices have additional conversion trigger sources as part of the enumeration ADC_CONVERSION_TRIGGER_SOURCE. Other Operations During Conversion Process • Monitoring Conversion process: The status of the conversion can be obtained using PLIB_ADC_ConversionHasCompleted • Generating ADC Interrupt: PLIB_ADC_SamplesPerInterruptSelect controls the generation of the ADC interrupt. To enable the interrupt it is also essential to enable the ADC interrupt. • Aborting the Conversion: Calling PLIB_ADC_Disable will abort the current conversion. The result buffer is not updated with the partially completed ADC conversion sequence. Timing Details TAD - The ADC module has a maximum rate at which conversions may be completed. An analog module clock, TAD, controls the conversion timing. TSAMP - The time required to sample and hold the sampled analog signal, configured through PLIB_ADC_SampleAcquisitionTimeSet. TCONV - The time required to convert the sampled analog signal, configured through PLIB_ADC_ConversionClockSet. The conversion clock can be verified using PLIB_ADC_ConversionClockGet. Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. Accessing the Result Buffers The result buffers can be formatted to the desired format using the function PLIB_ADC_ResultFormatSelect. Description As the analog-to-digital conversions are completed, the ADC module writes the results of the conversions into the ADC result buffer. This buffer is a RAM array of 16 words, accessed through the Special Function Register (SFR) space. User software may attempt to read each ADC conversion result as it is generated; however, this might consume too much CPU time. Generally, to minimize software overhead, the ADC module will fill the buffer with results, and then generate an interrupt when the buffer is filled. There are two different modes for accessing the result buffers. Note: Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet to determine the correct mode for accessing the result buffer for your device. Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 28 Single Buffer Mode Conversion results are automatically stored in a dedicated buffer. The module sets its interrupt flag after the conversion is complete, it also marks the conversion status as complete. After the interrupt, the conversion sequence can restart. The converted values are available through PLIB_ADC_ResultGetByIndex. Multiple Buffer Mode Conversion results are automatically stored in a dedicated position in the result buffer comprising an array of 16 words, allowing for multiple successive readings to be taken before software service is needed. Successive conversions are placed into sequential buffer positions. Alternatively, the buffer can be split into two arrays of 8 words for simultaneous conversion and read operations. The ADC module sets its interrupt flag after a selectable number of conversions, from 1 to 16, when the all buffer positions can be read. After the interrupt, the sequence restarts at the beginning of the buffer. When the interrupt flag is set, scan selections and the output buffer pointer return to their starting positions. The ADC result buffer is a set of 16 words, accessed through PLIB_ADC_ResultGetByIndex , where buffer index can be can be any value ranging from 0 to 15. PLIB_ADC_SamplesPerInterruptSelect selects how many analog-to-digital conversions will take place before the CPU is interrupted. The buffer fill mode can be selected using PLIB_ADC_ResultBufferModeSelect with the parameter of the type ADC_BUFFER_MODE. When the conversion result buffer is split (ADC_BUFFER_MODE_TWO_8WORD_BUFFERS used as the parameter for PLIB_ADC_ResultBufferModeSelect), PLIB_ADC_ResultBufferStatusGet indicates which half of the buffer is being currently written by the ADC module. Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. Power-Saving Modes This topic provides information on the power-saving modes available for use with the ADC module. Description Operation in Sleep Mode Operation in Sleep mode requires that the internal RC clock is selected using PLIB_ADC_ConversionClockSourceSelect with the parameter ADC_CLOCK_SOURCE_INTERNAL_RC. If the ADC interrupt is enabled, the device will wake up from Sleep mode on the ADC interrupt. On some microcontrollers, operation in Sleep mode requires that ADC_CONVERSION_CLOCK_FRC is selected using PLIB_ADC_ConversionClockSourceSelect. If the ADC interrupt is enabled, the device will wake up from Sleep mode on the ADC interrupt. Operation in Idle Mode PLIB_ADC_StopInIdleEnable and PLIB_ADC_StopInIdleDisable determine if the ADC module stops or continues operation in Idle mode. If PLIB_ADC_StopInIdleDisable is used, the module will continue operation in Idle mode. If the ADC interrupt is enabled, the device will wake up from Idle mode on the ADC interrupt. If PLIB_ADC_StopInIdleEnable is used, the module will stop in Idle mode. If the device enters Idle mode in the middle of conversion, the conversion is aborted. Operation in other Power-Saving modes If the ADC module is expected to operate in a power-saving mode, configure the acquisition time and the conversion clock using the functions in accordance with the power-saving mode clock that will be used. After the power-saving mode is entered, an analog-to-digital acquisition can be started. Once the acquisition is started, the device can continue to be clocked by the same power-saving source until the conversion has completed. If desired, the device may be placed in the power-saving Idle mode during conversion. Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. Conversion Sequence Examples This topic provides examples on how the sampling and conversion will occur in various configurations. Description Converting Single Channel, Manual Sample Start, Manual Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int16_t ADCValue; Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 29 // Enabling the sampling manually PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_SAMP_CLEAR); // Disabling ADC Input channels for Scan PLIB_ADC_InputScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Connect AN2 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN2); // Manual Sample and TAD = 2TCY PLIB_ADC_SampleAcquisitionTimeSet(MY_ADC_INSTANCE, 2); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 20000000); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { // Start Sampling PLIB_ADC_SamplingStart(MY_ADC_INSTANCE); Delay(); // Ensure, correct sampling time has elapsed before starting conversion. // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); ADCValue = PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 0); } Converting Single Channel, Manual Sample Start, TAD-based Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int16_t ADCValue; // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_InputScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcquisitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 20000000); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { // Start Sampling PLIB_ADC_SamplingStart(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); ADCValue = PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 0); } Converting Single Channel, Automatic Sample Start, TAD-based Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int16_t ADCValue; Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 30 uint8_t index; // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_InputScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcquisitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000,20000000); // Set the interrupt every 3 samples PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_3SAMPLES_PER_INTERRUPT); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { ADCValue = 0; // Auto Start Sampling and then go to conversion PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); // Yes, stop sample/convert PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); // Average the 2 ADC values for(index = 0; index < 2; index++) { ADCValue = ADCValue + PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, index); } ADCValue = ADCValue >> 1; } // Repeat Converting Single Channel, Automatic Sample Start, Conversion Trigger-based Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int16_t ADCValue; // General Purpose Timer 3 compare match ends sampling and starts conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_TMR3_COMPARE_MATCH); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_InputScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcquisitionTimeSelect(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSelect(MY_ADC_INSTANCE, 1); // Configure the timer to generate period match as per the acquisition requirements TMR3 = 0x0000; // set TMR3 to time out every 125 ms PR3 = 0x3FFF; T3CON = 0x8010; // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 31 { // Auto Start Sampling and then go to conversion PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); // Yes, stop sample/convert PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); ADCValue += PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 0); } Sampling and Converting a Single Channel Multiple Times // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int16_t ADCValue; uint8_t index; // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_InputScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcquisitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 20000000); // Set the interrupt every 16 samples PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_16SAMPLES_PER_INTERRUPT); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { ADCValue = 0; // Auto Start Sampling and then go to conversion PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); // Yes, stop sample/convert PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); // Average the 16 ADC value for(index = 0; index < 16; index++) { ADCValue = ADCValue + PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, index); } ADCValue = ADCValue >> 4; } // Repeat Sampling and Converting all Channels // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int ADCValue, index; // Include all channels in scan PLIB_ADC_InputScanMaskAdd(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 32 // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcquisitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 20000000); // Set the interrupt every 16 samples PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_16SAMPLES_PER_INTERRUPT); // Enable scanning of channels PLIB_ADC_MuxAInputScanEnable(MY_ADC_INSTANCE); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { ADCValue = 0; // Auto Start Sampling and then go to conversion PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); // Yes, stop sample/convert PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); // Average the 16 ADC value for(index = 0; index < 16; index++) { ADCValue = ADCValue + PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, index); } ADCValue = ADCValue >> 4; } // Repeat Wait for Sample, Manual Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID uint8_t ADCValue; // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_InputScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcquisitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 20000000); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { Delay(); // Ensure, correct sampling time has elapsed before starting conversion. // Start Sampling PLIB_ADC_SamplingStop(MY_ADC_INSTANCE); // Is Conversion Done ?? Peripheral Libraries Help ADC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 33 while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); ADCValue = PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 0); } Wait for Sample, Triggered Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID uint8_t ADCValue; // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Manual Sample and Conversion Clock PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 20000000); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { Delay(); // Ensure, correct sampling time has elapsed PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INT0_TRANSITION); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); ADCValue = PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 0); } Manual Sample Start, TAD-based Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID uint8_t ADCValue; // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Sample Time = 1TAD and TAD = 2TCY PLIB_ADC_SampleAcquisitionTimeSet(MY_ADC_INSTANCE, 0); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 20000000); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { // Start Sampling PLIB_ADC_SamplingStart(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); ADCValue = PLIB_ADC_ResultGet(MY_ADC_INSTANCE); } Configuring the Library The library is configured for the supported ADC modules with the multi-buffer interface when the processor is chosen in the MPLAB X IDE. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 34 Library Interface a) General Configuration Name Description PLIB_ADC_Enable ADC module is enabled (turned ON). PLIB_ADC_Disable ADC module is disabled (turned OFF). PLIB_ADC_StopInIdleDisable Continue ADC module operation when the device is in Idle mode. PLIB_ADC_StopInIdleEnable Discontinue ADC module operation when device enters Idle mode. PLIB_ADC_VoltageReferenceSelect Voltage reference configuration. PLIB_ADC_CalibrationEnable Calibration is performed on the next ADC conversion. PLIB_ADC_CalibrationDisable Normal ADC module operation (no calibration is performed). PLIB_ADC_InputScanMaskAdd Select ADC analog channel for input scan. PLIB_ADC_InputScanMaskRemove Omits ADC analog channel for input scan. PLIB_ADC_InputScanMaskAddExtended Select extended ADC analog channel for input scan. PLIB_ADC_InputScanMaskRemoveExtended Omits extended ADC analog channel for input scan. c) Conversion Control Logic Name Description PLIB_ADC_ConversionStart Starts ADC module manual conversion process. PLIB_ADC_ConversionHasCompleted Provides the conversion completion status of the ADC. PLIB_ADC_ConversionTriggerSourceSelect Selects the conversion trigger source. PLIB_ADC_ConversionStopSequenceEnable Stop conversion sequence (when the first ADC module interrupt is generated). PLIB_ADC_ConversionStopSequenceDisable Normal conversion sequence. PLIB_ADC_ConversionClockSet Sets the ADC module conversion clock. PLIB_ADC_ConversionClockGet Obtains the conversion clock. PLIB_ADC_ConversionClockSourceSelect Selects the ADC module conversion clock source. d) Sample and Hold Control Logic Name Description PLIB_ADC_SampleAutoStartDisable Sampling auto-start is disabled. PLIB_ADC_SampleAutoStartEnable Sampling auto-start is enabled. PLIB_ADC_SamplesPerInterruptSelect Interrupts at the completion of conversion for each nth sample. PLIB_ADC_SamplingIsActive Provides the ADC sampling status. PLIB_ADC_SamplingModeSelect Enable the selected sampling mode. PLIB_ADC_SamplingStart Sampling is enabled. PLIB_ADC_SamplingStop Holding is enabled. PLIB_ADC_SampleAcquisitionTimeSet Sets the ADC acquisition/auto-sample time in TADs. f) Output Configuration Name Description PLIB_ADC_ResultBufferModeSelect Selects the result buffer mode. PLIB_ADC_ResultBufferStatusGet Provides the buffer fill status. PLIB_ADC_ResultFormatSelect Selects the result format. PLIB_ADC_ResultGetByIndex Provides the ADC conversion result based on the buffer index. g) MUX Selection and Channel Scan Name Description PLIB_ADC_MuxAInputScanDisable Do not scan input selections for CH0+ of MUX A. PLIB_ADC_MuxAInputScanEnable Scan input selections for CH0+ of MUX A. PLIB_ADC_MuxChannel0InputNegativeSelect Channel 0 negative input select for multiplexer setting. PLIB_ADC_MuxChannel0InputPositiveSelect Channel 0 positive input select for multiplexer setting. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 35 h) Feature Existence Functions Name Description PLIB_ADC_ExistsCalibrationControl Identifies whether the CalibrationControl feature exists on the ADC module PLIB_ADC_ExistsConversionClock Identifies whether the ConversionClock feature exists on the ADC module PLIB_ADC_ExistsConversionClockSource Identifies whether the ConversionClockSource feature exists on the ADC module PLIB_ADC_ExistsConversionControl Identifies whether the ConversionControl feature exists on the ADC module PLIB_ADC_ExistsConversionStatus Identifies whether the ConversionStatus feature exists on the ADC module PLIB_ADC_ExistsConversionStopSequenceControl Identifies whether the ConversionStopSequenceControl feature exists on the ADC module PLIB_ADC_ExistsConversionTriggerSource Identifies whether the ConversionTriggerSource feature exists on the ADC module PLIB_ADC_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADC module PLIB_ADC_ExistsMuxChannel0NegativeInput Identifies whether the MuxChannel0NegativeInput feature exists on the ADC module PLIB_ADC_ExistsMuxChannel0PositiveInput Identifies whether the MuxChannel0PositiveInput feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanControl Identifies whether the MuxInputScanControl feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanSelect Identifies whether the MuxInputScanSelect feature exists on the ADC module PLIB_ADC_ExistsResultBufferFillStatus Identifies whether the ResultBufferFillStatus feature exists on the ADC module PLIB_ADC_ExistsResultBufferMode Identifies whether the ResultBufferMode feature exists on the ADC module PLIB_ADC_ExistsResultFormat Identifies whether the ResultFormat feature exists on the ADC module PLIB_ADC_ExistsResultGetByIndex Identifies whether the ResultGetByIndex feature exists on the ADC module PLIB_ADC_ExistsSamplesPerInterruptSelect Identifies whether the SamplesPerInterruptSelect feature exists on the ADC module PLIB_ADC_ExistsSamplingAcquisitionTime Identifies whether the SamplingAcquisitionTime feature exists on the ADC module PLIB_ADC_ExistsSamplingAutoStart Identifies whether the SamplingAutoStart feature exists on the ADC module PLIB_ADC_ExistsSamplingControl Identifies whether the SamplingControl feature exists on the ADC module PLIB_ADC_ExistsSamplingModeControl Identifies whether the SamplingModeControl feature exists on the ADC module PLIB_ADC_ExistsSamplingStatus Identifies whether the SamplingStatus feature exists on the ADC module PLIB_ADC_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the ADC module PLIB_ADC_ExistsVoltageReference Identifies whether the VoltageReference feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanSelectExtended Identifies whether the MuxInputScanSelectExtended feature exists on the ADC module i) Data Types & Constants Name Description ADC_MODULE_ID Identifies the available ADC modules. ADC_VOLTAGE_REFERENCE Defining the different ADC Voltage Reference by which the ADC can be configured. ADC_INPUTS_NEGATIVE Defines the different ADC Negative Input Enumeration. ADC_SAMPLES_PER_INTERRUPT Defining the Samples Per Interrupt Enumeration. ADC_CLOCK_SOURCE Defines the ADC Clock Source Select. ADC_CONVERSION_TRIGGER_SOURCE Defines the ADC Conversion Trigger Source. ADC_BUFFER_MODE Defines the ADC Buffer Mode. ADC_RESULT_BUF_STATUS Defines the ADC Result Buffer Status ADC_MUX Defining the different ADC MUX Enumeration. ADC_SAMPLING_MODE Defines the ADC Sampling Mode Select. ADC_INPUTS_SCAN Defines the ADC Scan inputs. ADC_RESULT_FORMAT Defines the ADC Result Format. ADC_INPUTS_POSITIVE Defines the ADC inputs. ADC_ACQUISITION_TIME Data type defining the different ADC acquisition times by which the ADC can be configured. ADC_CONVERSION_CLOCK Data type defines the different ADC Conversion clock ADC_SAMPLE Data type defining the size of the ADC sample register. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 36 Description This section describes the Application Programming Interface (API) functions of the Pipelined Analog-to-Digital Converter (ADC) Peripheral Library. Refer to each section for a detailed description. a) General Configuration PLIB_ADC_Enable Function ADC module is enabled (turned ON). File plib_adc.h C void PLIB_ADC_Enable(ADC_MODULE_ID index); Returns None. Description This function enables (turns ON) the selected ADC module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_Enable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_Enable( ADC_MODULE_ID index ) PLIB_ADC_Disable Function ADC module is disabled (turned OFF). File plib_adc.h C void PLIB_ADC_Disable(ADC_MODULE_ID index); Returns None. Description This function disables (turns OFF) the selected ADC module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsEnableControl in your application to determine whether this feature is available. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 37 Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_Disable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_Disable( ADC_MODULE_ID index ) PLIB_ADC_StopInIdleDisable Function Continue ADC module operation when the device is in Idle mode. File plib_adc.h C void PLIB_ADC_StopInIdleDisable(ADC_MODULE_ID index); Returns None. Description This function enables the ADC module to continue operation when the device is in Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsStopInIdleControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_StopInIdleDisable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_StopInIdleDisable( ADC_MODULE_ID index ) PLIB_ADC_StopInIdleEnable Function Discontinue ADC module operation when device enters Idle mode. File plib_adc.h C void PLIB_ADC_StopInIdleEnable(ADC_MODULE_ID index); Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 38 Returns None. Description This function discontinues ADC module operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsStopInIdleControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_StopInIdleEnable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_StopInIdleEnable( ADC_MODULE_ID index ) PLIB_ADC_VoltageReferenceSelect Function Voltage reference configuration. File plib_adc.h C void PLIB_ADC_VoltageReferenceSelect(ADC_MODULE_ID index, ADC_VOLTAGE_REFERENCE configValue); Returns None. Description This function configures the ADC module voltage reference. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsVoltageReference in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_VoltageReferenceSelect(MY_ADC_INSTANCE, ADC_REFERENCE_VREFPLUS_TO_AVSS); Parameters Parameters Description index Identifier for the device instance to be configured configValue One of the possible values from ADC_VOLTAGE_REFERENCE Function void PLIB_ADC_VoltageReferenceSelect( ADC_MODULE_ID index, ADC_VOLTAGE_REFERENCE configValue ) Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 39 PLIB_ADC_CalibrationEnable Function Calibration is performed on the next ADC conversion. File plib_adc.h C void PLIB_ADC_CalibrationEnable(ADC_MODULE_ID index); Returns None. Description This function enables calibration to be performed on the next ADC conversion. When the Calibration bit is enabled, inputs are disconnected and tied to AVss. This sets the inputs of the ADC to zero. Then, the user can perform a conversion. Use of the Calibration mode is not affected if the ADC line has been configured as analog or digital, nor by channel input selection. Any analog input switches are disconnected from the ADC module in this mode. The conversion result is stored by the user software and is used to compensate subsequent conversions. This can be done by adding the two’s complement of the result obtained during calibration to all normal ADC conversions. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsCalibrationControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_CalibrationEnable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_CalibrationEnable( ADC_MODULE_ID index ) PLIB_ADC_CalibrationDisable Function Normal ADC module operation (no calibration is performed). File plib_adc.h C void PLIB_ADC_CalibrationDisable(ADC_MODULE_ID index); Returns None. Description This function enables normal ADC module operation without any calibration. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsCalibrationControl in your application to determine whether this feature is available. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 40 Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_CalibrationDisable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_CalibrationDisable( ADC_MODULE_ID index ) PLIB_ADC_InputScanMaskAdd Function Select ADC analog channel for input scan. File plib_adc.h C void PLIB_ADC_InputScanMaskAdd(ADC_MODULE_ID index, ADC_INPUTS_SCAN scanInputs); Returns None. Description This function selects the ADC analog channel for input scanning. Remarks Multiple channels can be added simultaneously by ORing. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanSelect in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. // Single channel addition PLIB_ADC_InputScanMaskAdd(MY_ADC_INSTANCE, ADC_INPUT_SCAN_AN2); // Multiple channels addition PLIB_ADC_InputScanMaskAdd(ADC_ID_1, ADC_INPUT_SCAN_AN2 | ADC_INPUT_SCAN_AN2); Parameters Parameters Description index Identifier for the device instance to be configured scanInputs One of the possible values from ADC_INPUTS_SCAN. Inputs are added for scanning. Function void PLIB_ADC_InputScanMaskAdd( ADC_MODULE_ID index, ADC_INPUTS_SCAN scanInputs ) PLIB_ADC_InputScanMaskRemove Function Omits ADC analog channel for input scan. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 41 File plib_adc.h C void PLIB_ADC_InputScanMaskRemove(ADC_MODULE_ID index, ADC_INPUTS_SCAN scanInputs); Returns None. Description This function allows the ADC analog channel to be omitted from input scanning. Remarks Multiple channels can be removed simultaneously by ORing. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanSelect in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. // Single channel removing PLIB_ADC_InputScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_AN2); // Multiple channels removing PLIB_ADC_InputScanMaskRemove(ADC_ID_1, ADC_INPUT_SCAN_AN2 | ADC_INPUT_SCAN_AN3); Parameters Parameters Description index Identifier for the device instance to be configured scanInputs One of the possible values from ADC_INPUTS_SCAN. Inputs are removed from scanning. Function void PLIB_ADC_InputScanMaskRemove( ADC_MODULE_ID index, ADC_INPUTS_SCAN scanInputs ) PLIB_ADC_InputScanMaskAddExtended Function Select extended ADC analog channel for input scan. File plib_adc.h C void PLIB_ADC_InputScanMaskAddExtended(ADC_MODULE_ID index, ADC_INPUTS_SCAN_EXTENDED scanInputs); Returns None. Description This function selects the extended ADC analog channel for input scanning. Remarks Multiple channels can be added simultaneously by ORing. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanSelectExtended in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 42 Example // Single channel addition PLIB_ADC_InputScanMaskAddExtended(ADC_ID_1, ADC_INPUT_SCAN_AN36); // Multiple channels addition PLIB_ADC_InputScanMaskAddExtended(ADC_ID_1, ADC_INPUT_SCAN_AN36 | ADC_INPUT_SCAN_AN39); Parameters Parameters Description index Identifier for the device instance to be configured scanInputs One of the possible values from ADC_INPUTS_SCAN_EXTENDED. Inputs are added for scanning. Function void PLIB_ADC_InputScanMaskAddExtended( ADC_MODULE_ID index, ADC_INPUTS_SCAN_EXTENDED scanInputs ) PLIB_ADC_InputScanMaskRemoveExtended Function Omits extended ADC analog channel for input scan. File plib_adc.h C void PLIB_ADC_InputScanMaskRemoveExtended(ADC_MODULE_ID index, ADC_INPUTS_SCAN_EXTENDED scanInputs); Returns None. Description This function allows the extended ADC analog channel to be omitted from input scanning. Remarks Multiple channels can be removed simultaneously by ORing. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanSelectExtended in your application to determine whether this feature is available. Preconditions None. Example // Single channel removing PLIB_ADC_InputScanMaskRemove(ADC_ID_1, ADC_INPUT_SCAN_AN36); // Multiple channels removing PLIB_ADC_InputScanMaskRemove(ADC_ID_1, ADC_INPUT_SCAN_AN36 | ADC_INPUT_SCAN_AN39); Parameters Parameters Description index Identifier for the device instance to be configured scanInputs One of the possible values from ADC_INPUTS_SCAN_EXTENDED. Inputs are removed from scanning. Function void PLIB_ADC_InputScanMaskRemove( ADC_MODULE_ID index, ADC_INPUTS_SCAN_EXTENDED scanInputs ) b) DMA Transactions c) Conversion Control Logic Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 43 PLIB_ADC_ConversionStart Function Starts ADC module manual conversion process. File plib_adc.h C void PLIB_ADC_ConversionStart(ADC_MODULE_ID index); Returns None. Description This function starts the ADC module manual conversion process. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionControl in your application to determine whether this feature is available. Preconditions Automatic sampling must be disabled. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionStart(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_ConversionStart( ADC_MODULE_ID index ) PLIB_ADC_ConversionHasCompleted Function Provides the conversion completion status of the ADC. File plib_adc.h C bool PLIB_ADC_ConversionHasCompleted(ADC_MODULE_ID index); Returns Boolean: • true - ADC conversion is done/completed • false - ADC conversion is in progress or has not started Description This function provides the completion status of analog-to-digital conversion. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionStatus in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 44 Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. bool my_status = PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_ADC_ConversionHasCompleted( ADC_MODULE_ID index ) PLIB_ADC_ConversionTriggerSourceSelect Function Selects the conversion trigger source. File plib_adc.h C void PLIB_ADC_ConversionTriggerSourceSelect(ADC_MODULE_ID index, ADC_CONVERSION_TRIGGER_SOURCE source); Returns None. Description This function selects the ADC module conversion trigger source. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionTriggerSource in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); Parameters Parameters Description index Identifier for the device instance to be configured source One of the possible values from ADC_CONVERSION_TRIGGER_SOURCE Function void PLIB_ADC_ConversionTriggerSourceSelect( ADC_MODULE_ID index, ADC_CONVERSION_TRIGGER_SOURCE source ) PLIB_ADC_ConversionStopSequenceEnable Function Stop conversion sequence (when the first ADC module interrupt is generated). File plib_adc.h C void PLIB_ADC_ConversionStopSequenceEnable(ADC_MODULE_ID index); Returns None. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 45 Description This function stops conversions when the first ADC module interrupt is generated. Hardware clears the Automatic Sampling bit when the ADC interrupt is generated. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionStopSequenceControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionStopSequenceEnable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_ConversionStopSequenceEnable( ADC_MODULE_ID index ) PLIB_ADC_ConversionStopSequenceDisable Function Normal conversion sequence. File plib_adc.h C void PLIB_ADC_ConversionStopSequenceDisable(ADC_MODULE_ID index); Returns None. Description This function enables normal operation, wherein the buffer contents will be overwritten by the next conversion sequence. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionStopSequenceControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionStopSequenceDisable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_ConversionStopSequenceDisable( ADC_MODULE_ID index ) PLIB_ADC_ConversionClockSet Function Sets the ADC module conversion clock. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 46 File plib_adc.h C void PLIB_ADC_ConversionClockSet(ADC_MODULE_ID index, uint32_t baseFrequency, ADC_CONVERSION_CLOCK value); Returns None. Description This function sets the ADC module conversion clock prescaler. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionClock in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. // Following functions passed the input clock to ADC as 80MHz and // required conversion clock as 20MHz. PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 20000000); Parameters Parameters Description index Identifier for the device instance to be configured baseFrequency Input clock frequency in Hertz (Hz). This is the input clock to ADC module. value Unsigned value of type ADC_CONVERSION_CLOCK. This is the required conversion clock of ADC module in Hz. Function void PLIB_ADC_ConversionClockSet( ADC_MODULE_ID index, uint32_t baseFrequency, ADC_CONVERSION_CLOCK value ) PLIB_ADC_ConversionClockGet Function Obtains the conversion clock. File plib_adc.h C ADC_CONVERSION_CLOCK PLIB_ADC_ConversionClockGet(ADC_MODULE_ID index, uint32_t baseFrequency); Returns ADC_CONVERSION_CLOCK - ADC Conversion clock value (in Hz) of type ADC_CONVERSION_CLOCK Description This function obtains the conversion clock that is being used by the ADC module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionClock in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 47 Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. // baseFrequency is the peripheral input frequency ADC_CONVERSION_CLOCK conversionClock; // To store the conversion clock value conversionClock = PLIB_ADC_ConversionClockGet(MY_ADC_INSTANCE, 8000000); Parameters Parameters Description index Identifier for the device instance to be configured baseFrequencyHz Input clock frequency to the ADC module in Hz Function ADC_CONVERSION_CLOCK PLIB_ADC_ConversionClockGet( ADC_MODULE_ID index, uint32_t baseFrequencyHz ) PLIB_ADC_ConversionClockSourceSelect Function Selects the ADC module conversion clock source. File plib_adc.h C void PLIB_ADC_ConversionClockSourceSelect(ADC_MODULE_ID index, ADC_CLOCK_SOURCE source); Returns None. Description This function selects the ADC module conversion clock source. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionClockSource in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionClockSourceSelect(MY_ADC_INSTANCE, ADC_CLOCK_SOURCE_PERIPHERAL_BUS_CLOCK); Parameters Parameters Description index Identifier for the device instance to be configured source One of the possible values from ADC_CLOCK_SOURCE Function void PLIB_ADC_ConversionClockSourceSelect( ADC_MODULE_ID index, ADC_CLOCK_SOURCE source ) d) Sample and Hold Control Logic PLIB_ADC_SampleAutoStartDisable Function Sampling auto-start is disabled. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 48 File plib_adc.h C void PLIB_ADC_SampleAutoStartDisable(ADC_MODULE_ID index); Returns None. Description This function disables auto-sampling and enables manual sampling. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingAutoStart in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_SampleAutoStartDisable( ADC_MODULE_ID index ) PLIB_ADC_SampleAutoStartEnable Function Sampling auto-start is enabled. File plib_adc.h C void PLIB_ADC_SampleAutoStartEnable(ADC_MODULE_ID index); Returns None. Description This function enables auto-sampling. Sampling begins immediately after the last conversion is completed. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingAutoStart in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 49 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_SampleAutoStartEnable( ADC_MODULE_ID index ) PLIB_ADC_SamplesPerInterruptSelect Function Interrupts at the completion of conversion for each nth sample. File plib_adc.h C void PLIB_ADC_SamplesPerInterruptSelect(ADC_MODULE_ID index, ADC_SAMPLES_PER_INTERRUPT value); Returns None. Description This function interrupts at the completion of conversion for each nth sample/convert sequence. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplesPerInterruptSelect in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_16SAMPLES_PER_INTERRUPT); Parameters Parameters Description index Identifier for the device instance to be configured value Possible values from ADC_SAMPLES_PER_INTERRUPT Function void PLIB_ADC_SamplesPerInterruptSelect( ADC_MODULE_ID index, ADC_SAMPLES_PER_INTERRUPT value ) PLIB_ADC_SamplingIsActive Function Provides the ADC sampling status. File plib_adc.h C bool PLIB_ADC_SamplingIsActive(ADC_MODULE_ID index); Returns Boolean: • true - ADC Sample and Hold circuit is sampling • false - ADC Sample and Hold circuit is holding Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 50 Description This function returns the ADC sampling status on whether the ADC is sampling or holding. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingStatus in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. bool my_status = PLIB_ADC_SamplingIsActive(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_ADC_SamplingIsActive( ADC_MODULE_ID index ) PLIB_ADC_SamplingModeSelect Function Enable the selected sampling mode. File plib_adc.h C void PLIB_ADC_SamplingModeSelect(ADC_MODULE_ID index, ADC_SAMPLING_MODE mode); Returns None. Description This function selects the sampling mode. Remarks Sampling mode could be alternate input or Simultaneous or Sequential mode. Alternate input can be combined with Simultaneous or Sequential modes. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingModeControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SamplingModeSelect(MY_ADC_INSTANCE, ADC_SAMPLING_MODE_ALTERNATE_INPUT); Parameters Parameters Description index Identifier for the device instance to be configured mode One of the possible values from ADC_SAMPLING_MODE Function void PLIB_ADC_SamplingModeSelect( ADC_MODULE_ID index, ADC_SAMPLING_MODE mode ) Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 51 PLIB_ADC_SamplingStart Function Sampling is enabled. File plib_adc.h C void PLIB_ADC_SamplingStart(ADC_MODULE_ID index); Returns None. Description This function starts the ADC Sample and Hold circuit to sample the input channel. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingControl in your application to determine whether this feature is available. Preconditions Automatic sampling must be disabled. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SamplingStart(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_SamplingStart( ADC_MODULE_ID index ) PLIB_ADC_SamplingStop Function Holding is enabled. File plib_adc.h C void PLIB_ADC_SamplingStop(ADC_MODULE_ID index); Returns None. Description This function stops the ADC Sample and Hold circuit from sampling and holds the sampled data. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingControl in your application to determine whether this feature is available. Preconditions Automatic sampling must be disabled. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 52 PLIB_ADC_SamplingStop(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_SamplingStop( ADC_MODULE_ID index ) PLIB_ADC_SampleAcquisitionTimeSet Function Sets the ADC acquisition/auto-sample time in TADs. File plib_adc.h C void PLIB_ADC_SampleAcquisitionTimeSet(ADC_MODULE_ID index, ADC_ACQUISITION_TIME acqTime); Returns None. Description This function sets the ADC acquisition/auto-sample time in TADs. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingAcquisitionTime in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SampleAcquisitionTimeSet(MY_ADC_INSTANCE, 2); Parameters Parameters Description index Identifier for the device instance to be configured acqTime Unsigned value of type ADC_ACQUISITION_TIME Function void PLIB_ADC_SampleAcquisitionTimeSet( ADC_MODULE_ID index, ADC_ACQUISITION_TIME acqTime ) e) Channel Pairs Control f) Output Configuration PLIB_ADC_ResultBufferModeSelect Function Selects the result buffer mode. File plib_adc.h C void PLIB_ADC_ResultBufferModeSelect(ADC_MODULE_ID index, ADC_BUFFER_MODE mode); Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 53 Returns None. Description This function selects the result buffer mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultBufferMode in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ResultBufferModeSelect(MY_ADC_INSTANCE, ADC_BUFFER_MODE_TWO_8WORD_BUFFERS); Parameters Parameters Description index Identifier for the device instance to be configured mode One of the possible values from ADC_BUFFER_MODE Function void PLIB_ADC_ResultBufferModeSelect( ADC_MODULE_ID index, ADC_BUFFER_MODE mode ) PLIB_ADC_ResultBufferStatusGet Function Provides the buffer fill status. File plib_adc.h C ADC_RESULT_BUF_STATUS PLIB_ADC_ResultBufferStatusGet(ADC_MODULE_ID index); Returns Boolean: • true = ADC is currently filling buffer 08-0F, user should access data in 00-07 • false = ADC is currently filling buffer 00-07, user should access data in 08-0F Description This function obtains the buffer fill status. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultBufferFillStatus in your application to determine whether this feature is available. Preconditions ADC multi-buffer support is available and configured. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. ADC_RESULT_BUF_STATUS my_status; my_status = PLIB_ADC_ResultBufferStatusGet(MY_ADC_INSTANCE); Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 54 Parameters Parameters Description index Identifier for the device instance to be configured Function ADC_RESULT_BUF_STATUS PLIB_ADC_ResultBufferStatusGet( ADC_MODULE_ID index ) PLIB_ADC_ResultFormatSelect Function Selects the result format. File plib_adc.h C void PLIB_ADC_ResultFormatSelect(ADC_MODULE_ID index, ADC_RESULT_FORMAT resultFormat); Returns None. Description This function selects the result format. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultFormat in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ResultFormatSelect(MY_ADC_INSTANCE, ADC_RESULT_FORMAT_INTEGER_16BIT); Parameters Parameters Description index Identifier for the device instance to be configured resultFormat One of the possible values from ADC_RESULT_FORMAT Function void PLIB_ADC_ResultFormatSelect( ADC_MODULE_ID index, ADC_RESULT_FORMAT resultFormat ) PLIB_ADC_ResultGetByIndex Function Provides the ADC conversion result based on the buffer index. File plib_adc.h C ADC_SAMPLE PLIB_ADC_ResultGetByIndex(ADC_MODULE_ID index, uint8_t bufferIndex); Returns int16_t - ADC Conversion result at the respective bufferIndex Description This function provides the ADC module conversion result based on the buffer index. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 55 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultGetByIndex in your application to determine whether this feature is available. Preconditions ADC multi-buffer support available and configured. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. ADC_SAMPLE my_res = PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 15); Parameters Parameters Description index Identifier for the device instance to be configured bufferIndex Value ranging from 0 to 15 Function ADC_SAMPLE PLIB_ADC_ResultGetByIndex( ADC_MODULE_ID index, uint8_t bufferIndex ) g) MUX Selection and Channel Scan PLIB_ADC_MuxAInputScanDisable Function Do not scan input selections for CH0+ of MUX A. File plib_adc.h C void PLIB_ADC_MuxAInputScanDisable(ADC_MODULE_ID index); Returns None. Description This function disables scan input for CH0+ of MUX A. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_MuxAInputScanDisable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_MuxAInputScanDisable( ADC_MODULE_ID index ) Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 56 PLIB_ADC_MuxAInputScanEnable Function Scan input selections for CH0+ of MUX A. File plib_adc.h C void PLIB_ADC_MuxAInputScanEnable(ADC_MODULE_ID index); Returns None. Description This function enables scan input for CH0+ of MUX A. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_MuxAInputScanEnable(MY_ADC_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_ADC_MuxAInputScanEnable( ADC_MODULE_ID index ) PLIB_ADC_MuxChannel0InputNegativeSelect Function Channel 0 negative input select for multiplexer setting. File plib_adc.h C void PLIB_ADC_MuxChannel0InputNegativeSelect(ADC_MODULE_ID index, ADC_MUX muxType, ADC_INPUTS_NEGATIVE input); Returns None. Description This function selects the negative input for channel 0 of MUX A or MUX B. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxChannel0NegativeInput in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 57 PLIB_ADC_MuxChannel0InputNegativeSelect(MY_ADC_INSTANCE, ADC_MUX_A, ADC_INPUT_NEGATIVE_VREF_MINUS); Parameters Parameters Description index Identifier for the device instance to be configured muxType One of the possible values from ADC_MUX Function void PLIB_ADC_MuxChannel0InputNegativeSelect( ADC_MODULE_ID index, ADC_MUX muxType, ADC_INPUTS_NEGATIVE input ) PLIB_ADC_MuxChannel0InputPositiveSelect Function Channel 0 positive input select for multiplexer setting. File plib_adc.h C void PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_MODULE_ID index, ADC_MUX muxType, ADC_INPUTS_POSITIVE input); Returns None. Description This function selects the positive input for channel 0 of MUX A or MUX B. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxChannel0PositiveInput in your application to determine whether this feature is available. Preconditions None. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_MuxChannel0InputPositiveSelect(MY_ADC_INSTANCE, ADC_MUX_A, ADC_INPUT_POSITIVE_AN2); Parameters Parameters Description index Identifier for the device instance to be configured muxType One of the possible values from ADC_MUX Function void PLIB_ADC_MuxChannel0InputPositiveSelect( ADC_MODULE_ID index, ADC_MUX muxType, ADC_INPUTS_POSITIVE input ) h) Feature Existence Functions PLIB_ADC_ExistsCalibrationControl Function Identifies whether the CalibrationControl feature exists on the ADC module File plib_adc.h Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 58 C bool PLIB_ADC_ExistsCalibrationControl(ADC_MODULE_ID index); Returns • true - The CalibrationControl feature is supported on the device • false - The CalibrationControl feature is not supported on the device Description This function identifies whether the CalibrationControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_CalibrationEnable • PLIB_ADC_CalibrationDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsCalibrationControl( ADC_MODULE_ID index ) PLIB_ADC_ExistsConversionClock Function Identifies whether the ConversionClock feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsConversionClock(ADC_MODULE_ID index); Returns • true - The ConversionClock feature is supported on the device • false - The ConversionClock feature is not supported on the device Description This function identifies whether the ConversionClock feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ConversionClockSet • PLIB_ADC_ConversionClockGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsConversionClock( ADC_MODULE_ID index ) Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 59 PLIB_ADC_ExistsConversionClockSource Function Identifies whether the ConversionClockSource feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsConversionClockSource(ADC_MODULE_ID index); Returns • true - The ConversionClockSource feature is supported on the device • false - The ConversionClockSource feature is not supported on the device Description This function identifies whether the ConversionClockSource feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_ConversionClockSourceSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsConversionClockSource( ADC_MODULE_ID index ) PLIB_ADC_ExistsConversionControl Function Identifies whether the ConversionControl feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsConversionControl(ADC_MODULE_ID index); Returns • true - The ConversionControl feature is supported on the device • false - The ConversionControl feature is not supported on the device Description This function identifies whether the ConversionControl feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_ConversionStart Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 60 Function PLIB_ADC_ExistsConversionControl( ADC_MODULE_ID index ) PLIB_ADC_ExistsConversionStatus Function Identifies whether the ConversionStatus feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsConversionStatus(ADC_MODULE_ID index); Returns • true - The ConversionStatus feature is supported on the device • false - The ConversionStatus feature is not supported on the device Description This function identifies whether the ConversionStatus feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_ConversionHasCompleted Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsConversionStatus( ADC_MODULE_ID index ) PLIB_ADC_ExistsConversionStopSequenceControl Function Identifies whether the ConversionStopSequenceControl feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsConversionStopSequenceControl(ADC_MODULE_ID index); Returns • true - The ConversionStopSequenceControl feature is supported on the device • false - The ConversionStopSequenceControl feature is not supported on the device Description This function identifies whether the ConversionStopSequenceControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ConversionStopSequenceEnable • PLIB_ADC_ConversionStopSequenceDisable Remarks None. Preconditions None. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 61 Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsConversionStopSequenceControl( ADC_MODULE_ID index ) PLIB_ADC_ExistsConversionTriggerSource Function Identifies whether the ConversionTriggerSource feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsConversionTriggerSource(ADC_MODULE_ID index); Returns • true - The ConversionTriggerSource feature is supported on the device • false - The ConversionTriggerSource feature is not supported on the device Description This function identifies whether the ConversionTriggerSource feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_ConversionTriggerSourceSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsConversionTriggerSource( ADC_MODULE_ID index ) PLIB_ADC_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsEnableControl(ADC_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_Enable • PLIB_ADC_Disable Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 62 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsEnableControl( ADC_MODULE_ID index ) PLIB_ADC_ExistsMuxChannel0NegativeInput Function Identifies whether the MuxChannel0NegativeInput feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsMuxChannel0NegativeInput(ADC_MODULE_ID index); Returns • true - The MuxChannel0NegativeInput feature is supported on the device • false - The MuxChannel0NegativeInput feature is not supported on the device Description This function identifies whether the MuxChannel0NegativeInput feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_MuxChannel0InputNegativeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsMuxChannel0NegativeInput( ADC_MODULE_ID index ) PLIB_ADC_ExistsMuxChannel0PositiveInput Function Identifies whether the MuxChannel0PositiveInput feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsMuxChannel0PositiveInput(ADC_MODULE_ID index); Returns • true - The MuxChannel0PositiveInput feature is supported on the device • false - The MuxChannel0PositiveInput feature is not supported on the device Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 63 Description This function identifies whether the MuxChannel0PositiveInput feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_MuxChannel0InputPositiveSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsMuxChannel0PositiveInput( ADC_MODULE_ID index ) PLIB_ADC_ExistsMuxInputScanControl Function Identifies whether the MuxInputScanControl feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsMuxInputScanControl(ADC_MODULE_ID index); Returns • true - The MuxInputScanControl feature is supported on the device • false - The MuxInputScanControl feature is not supported on the device Description This function identifies whether the MuxInputScanControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_MuxAInputScanEnable • PLIB_ADC_MuxAInputScanDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsMuxInputScanControl( ADC_MODULE_ID index ) PLIB_ADC_ExistsMuxInputScanSelect Function Identifies whether the MuxInputScanSelect feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsMuxInputScanSelect(ADC_MODULE_ID index); Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 64 Returns • true - The MuxInputScanSelect feature is supported on the device • false - The MuxInputScanSelect feature is not supported on the device Description This function identifies whether the MuxInputScanSelect feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_InputScanMaskAdd • PLIB_ADC_InputScanMaskRemove Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsMuxInputScanSelect( ADC_MODULE_ID index ) PLIB_ADC_ExistsResultBufferFillStatus Function Identifies whether the ResultBufferFillStatus feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsResultBufferFillStatus(ADC_MODULE_ID index); Returns • true - The ResultBufferFillStatus feature is supported on the device • false - The ResultBufferFillStatus feature is not supported on the device Description This function identifies whether the ResultBufferFillStatus feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_ResultBufferStatusGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsResultBufferFillStatus( ADC_MODULE_ID index ) PLIB_ADC_ExistsResultBufferMode Function Identifies whether the ResultBufferMode feature exists on the ADC module Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 65 File plib_adc.h C bool PLIB_ADC_ExistsResultBufferMode(ADC_MODULE_ID index); Returns • true - The ResultBufferMode feature is supported on the device • false - The ResultBufferMode feature is not supported on the device Description This function identifies whether the ResultBufferMode feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_ResultBufferModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsResultBufferMode( ADC_MODULE_ID index ) PLIB_ADC_ExistsResultFormat Function Identifies whether the ResultFormat feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsResultFormat(ADC_MODULE_ID index); Returns • true - The ResultFormat feature is supported on the device • false - The ResultFormat feature is not supported on the device Description This function identifies whether the ResultFormat feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_ResultFormatSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsResultFormat( ADC_MODULE_ID index ) Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 66 PLIB_ADC_ExistsResultGetByIndex Function Identifies whether the ResultGetByIndex feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsResultGetByIndex(ADC_MODULE_ID index); Returns • true - The ResultGetByIndex feature is supported on the device • false - The ResultGetByIndex feature is not supported on the device Description This function identifies whether the ResultGetByIndex feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_ResultGetByIndex Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsResultGetByIndex( ADC_MODULE_ID index ) PLIB_ADC_ExistsSamplesPerInterruptSelect Function Identifies whether the SamplesPerInterruptSelect feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsSamplesPerInterruptSelect(ADC_MODULE_ID index); Returns • true - The SamplesPerInterruptSelect feature is supported on the device • false - The SamplesPerInterruptSelect feature is not supported on the device Description This function identifies whether the SamplesPerInterruptSelect feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_SamplesPerInterruptSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 67 Function PLIB_ADC_ExistsSamplesPerInterruptSelect( ADC_MODULE_ID index ) PLIB_ADC_ExistsSamplingAcquisitionTime Function Identifies whether the SamplingAcquisitionTime feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsSamplingAcquisitionTime(ADC_MODULE_ID index); Returns • true - The SamplingAcquisitionTime feature is supported on the device • false - The SamplingAcquisitionTime feature is not supported on the device Description This function identifies whether the SamplingAcquisitionTime feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_SampleAcquisitionTimeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsSamplingAcquisitionTime( ADC_MODULE_ID index ) PLIB_ADC_ExistsSamplingAutoStart Function Identifies whether the SamplingAutoStart feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsSamplingAutoStart(ADC_MODULE_ID index); Returns • true - The SamplingAutoStart feature is supported on the device • false - The SamplingAutoStart feature is not supported on the device Description This function identifies whether the SamplingAutoStart feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_SampleAutoStartEnable • PLIB_ADC_SampleAutoStartDisable Remarks None. Preconditions None. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 68 Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsSamplingAutoStart( ADC_MODULE_ID index ) PLIB_ADC_ExistsSamplingControl Function Identifies whether the SamplingControl feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsSamplingControl(ADC_MODULE_ID index); Returns • true - The SamplingControl feature is supported on the device • false - The SamplingControl feature is not supported on the device Description This function identifies whether the SamplingControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_SamplingStart • PLIB_ADC_SamplingStop Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsSamplingControl( ADC_MODULE_ID index ) PLIB_ADC_ExistsSamplingModeControl Function Identifies whether the SamplingModeControl feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsSamplingModeControl(ADC_MODULE_ID index); Returns • true - The SamplingModeControl feature is supported on the device • false - The SamplingModeControl feature is not supported on the device Description This function identifies whether the SamplingModeControl feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_SamplingModeSelect Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 69 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsSamplingModeControl( ADC_MODULE_ID index ) PLIB_ADC_ExistsSamplingStatus Function Identifies whether the SamplingStatus feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsSamplingStatus(ADC_MODULE_ID index); Returns • true - The SamplingStatus feature is supported on the device • false - The SamplingStatus feature is not supported on the device Description This function identifies whether the SamplingStatus feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_SamplingIsActive Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsSamplingStatus( ADC_MODULE_ID index ) PLIB_ADC_ExistsStopInIdleControl Function Identifies whether the StopInIdle feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsStopInIdleControl(ADC_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 70 Description This function identifies whether the StopInIdle feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_StopInIdleEnable • PLIB_ADC_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsStopInIdleControl( ADC_MODULE_ID index ) PLIB_ADC_ExistsVoltageReference Function Identifies whether the VoltageReference feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsVoltageReference(ADC_MODULE_ID index); Returns • true - The VoltageReference feature is supported on the device • false - The VoltageReference feature is not supported on the device Description This function identifies whether the VoltageReference feature is available on the ADC module. When this function returns true, this function is supported on the device: • PLIB_ADC_VoltageReferenceSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsVoltageReference( ADC_MODULE_ID index ) PLIB_ADC_ExistsMuxInputScanSelectExtended Function Identifies whether the MuxInputScanSelectExtended feature exists on the ADC module File plib_adc.h C bool PLIB_ADC_ExistsMuxInputScanSelectExtended(ADC_MODULE_ID index); Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 71 Returns • true - The MuxInputScanSelectExtended feature is supported on the device • false - The MuxInputScanSelectExtended feature is not supported on the device Description This function identifies whether the MuxInputScanSelectExtended feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_InputScanMaskAddExtended • PLIB_ADC_InputScanMaskRemoveExtended Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADC_ExistsMuxInputScanSelectExtended( ADC_MODULE_ID index ) i) Data Types & Constants ADC_MODULE_ID Enumeration Identifies the available ADC modules. File help_plib_adc.h C typedef enum { ADC_ID_1, ADC_ID_2, ADC_ID_3, ADC_ID_4, ADC_ID_5, ADC_NUMBER_OF_MODULES } ADC_MODULE_ID; Members Members Description ADC_ID_1 ADC Module 1 ID ADC_ID_2 ADC Module 2 ID ADC_ID_3 ADC Module 3 ID ADC_ID_4 ADC Module 4 ID ADC_ID_5 ADC Module 5 ID ADC_NUMBER_OF_MODULES Number of available ADC modules. Description ADC Module ID This enumeration identifies the available ADC modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules are available on all devices. Refer to the specific device data sheet to determine which modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 72 ADC_VOLTAGE_REFERENCE Enumeration Defining the different ADC Voltage Reference by which the ADC can be configured. File help_plib_adc.h C typedef enum { ADC_REFERENCE_VDD_TO_AVSS, ADC_REFERENCE_VREFPLUS_TO_AVSS, ADC_REFERENCE_AVDD_TO_VREF_NEG, ADC_REFERENCE_VREFPLUS_TO_VREFNEG } ADC_VOLTAGE_REFERENCE; Members Members Description ADC_REFERENCE_VDD_TO_AVSS Positive voltage reference supplied internally by VDD and Negative voltage reference supplied internally through VSS ADC_REFERENCE_VREFPLUS_TO_AVSS Positive voltage reference supplied externally through VREF+ pin and Negative voltage reference supplied internally through VSS ADC_REFERENCE_AVDD_TO_VREF_NEG Positive voltage reference supplied internally by VDD and Negative voltage reference supplied externally through VREF- pin ADC_REFERENCE_VREFPLUS_TO_VREFNEG Positive voltage reference supplied externally through VREF+ pin and Negative voltage reference supplied externally through VREF- pin Description ADC Voltage Reference Enumeration This data type defines the different ADC Voltage Reference by which the ADC can be configured. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_INPUTS_NEGATIVE Enumeration Defines the different ADC Negative Input Enumeration. File help_plib_adc.h C typedef enum { ADC_INPUT_NEGATIVE_VREF_MINUS, ADC_INPUT_NEGATIVE_AN1, ADC_INPUT_NEGATIVE_AN2, ADC_INPUT_NEGATIVE_AN3, ADC_INPUT_NEGATIVE_AN4, ADC_INPUT_NEGATIVE_AN5, ADC_INPUT_NEGATIVE_AN6 } ADC_INPUTS_NEGATIVE; Members Members Description ADC_INPUT_NEGATIVE_VREF_MINUS Negative input is VREF ADC_INPUT_NEGATIVE_AN1 Negative input is AN1 ADC_INPUT_NEGATIVE_AN2 Negative input is AN2 ADC_INPUT_NEGATIVE_AN3 Negative input is AN3 ADC_INPUT_NEGATIVE_AN4 Negative input is AN4 ADC_INPUT_NEGATIVE_AN5 Negative input is AN5 ADC_INPUT_NEGATIVE_AN6 Negative input is AN6 Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 73 Description ADC Negative Input Enumeration This data type defines the different ADC Negative Input Enumeration. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_SAMPLES_PER_INTERRUPT Enumeration Defining the Samples Per Interrupt Enumeration. File help_plib_adc.h C typedef enum { ADC_1SAMPLE_PER_INTERRUPT, ADC_2SAMPLES_PER_INTERRUPT, ADC_3SAMPLES_PER_INTERRUPT, ADC_4SAMPLES_PER_INTERRUPT, ADC_5SAMPLES_PER_INTERRUPT, ADC_6SAMPLES_PER_INTERRUPT, ADC_7SAMPLES_PER_INTERRUPT, ADC_8SAMPLES_PER_INTERRUPT, ADC_9SAMPLES_PER_INTERRUPT, ADC_10SAMPLES_PER_INTERRUPT, ADC_11SAMPLES_PER_INTERRUPT, ADC_12SAMPLES_PER_INTERRUPT, ADC_13SAMPLES_PER_INTERRUPT, ADC_14SAMPLES_PER_INTERRUPT, ADC_15SAMPLES_PER_INTERRUPT, ADC_16SAMPLES_PER_INTERRUPT } ADC_SAMPLES_PER_INTERRUPT; Members Members Description ADC_1SAMPLE_PER_INTERRUPT Interrupts at the completion of conversion for each sample/convert sequence ADC_2SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 2nd sample/convert sequence ADC_3SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 3rd sample/convert sequence ADC_4SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 4th sample/convert sequence ADC_5SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 5th sample/convert sequence ADC_6SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 6th sample/convert sequence ADC_7SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 7th sample/convert sequence ADC_8SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 8th sample/convert sequence ADC_9SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 9th sample/convert sequence ADC_10SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 10th sample/convert sequence ADC_11SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 11th sample/convert sequence ADC_12SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 12th sample/convert sequence ADC_13SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 13th sample/convert sequence ADC_14SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 14th sample/convert sequence ADC_15SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 15th sample/convert sequence ADC_16SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 16th sample/convert sequence Description ADC samples per Interrupt Enumeration This data type defines the Samples Per Interrupt Enumeration. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 74 ADC_CLOCK_SOURCE Enumeration Defines the ADC Clock Source Select. File help_plib_adc.h C typedef enum { ADC_CLOCK_SOURCE_PERIPHERAL_BUS_CLOCK, ADC_CLOCK_SOURCE_SYSTEM_CLOCK, ADC_CLOCK_SOURCE_INTERNAL_RC } ADC_CLOCK_SOURCE; Members Members Description ADC_CLOCK_SOURCE_PERIPHERAL_BUS_CLOCK A/D Peripheral clock ADC_CLOCK_SOURCE_SYSTEM_CLOCK This option is deprecated, use ADC_CLOCK_SOURCE_PERIPHERAL_BUS_CLOCK ADC_CLOCK_SOURCE_INTERNAL_RC A/D internal RC clock Description ADC Clock Source Select This data type defines the ADC Clock Source Select. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_CONVERSION_TRIGGER_SOURCE Enumeration Defines the ADC Conversion Trigger Source. File help_plib_adc.h C typedef enum { ADC_CONVERSION_TRIGGER_SAMP_CLEAR, ADC_CONVERSION_TRIGGER_INT0_TRANSITION, ADC_CONVERSION_TRIGGER_TMR3_COMPARE_MATCH, ADC_CONVERSION_TRIGGER_CTMU_EVENT, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT } ADC_CONVERSION_TRIGGER_SOURCE; Members Members Description ADC_CONVERSION_TRIGGER_SAMP_CLEAR Clearing SAMP bit (full program control) ADC_CONVERSION_TRIGGER_INT0_TRANSITION Active transition on INT0 pin (basic sync convert) ADC_CONVERSION_TRIGGER_TMR3_COMPARE_MATCH Timer3 compare match ADC_CONVERSION_TRIGGER_CTMU_EVENT CTMU event ADC_CONVERSION_TRIGGER_INTERNAL_COUNT Internal counter (auto-convert) Description ADC Conversion Trigger Source This data type defines the ADC Conversion Trigger Source. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_BUFFER_MODE Enumeration Defines the ADC Buffer Mode. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 75 File help_plib_adc.h C typedef enum { ADC_BUFFER_MODE_ONE_16WORD_BUFFER, ADC_BUFFER_MODE_TWO_8WORD_BUFFERS } ADC_BUFFER_MODE; Members Members Description ADC_BUFFER_MODE_ONE_16WORD_BUFFER Buffer configured as one 16-word buffer (ADC1BUF0 to ADC1BUFF) ADC_BUFFER_MODE_TWO_8WORD_BUFFERS Buffer configured as two 8-word buffers (ADC1BUF0 to ADC1BUF7 and ADC1BUF8 to ADC1BUFF) Description ADC Buffer Mode This data type defines the ADC Buffer Mode. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_RESULT_BUF_STATUS Enumeration Defines the ADC Result Buffer Status File help_plib_adc.h C typedef enum { ADC_FILLING_BUF_0TO7, ADC_FILLING_BUF_8TOF } ADC_RESULT_BUF_STATUS; Members Members Description ADC_FILLING_BUF_0TO7 Buffers 0x0 to 0x7 are getting filled ADC_FILLING_BUF_8TOF Buffers 0x8 to 0xF are getting filled Description ADC Result Buffer Status This data type defines the elements that specify which group of eight buffers the ADC is currently filling. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_MUX Enumeration Defining the different ADC MUX Enumeration. File help_plib_adc.h C typedef enum { ADC_MUX_A, ADC_MUX_B } ADC_MUX; Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 76 Members Members Description ADC_MUX_A ADC Mux A Selection ADC_MUX_B ADC Mux B Selection Description ADC MUX Enumeration This data type defines the different ADC MUX Enumeration. Remarks None. ADC_SAMPLING_MODE Enumeration Defines the ADC Sampling Mode Select. File help_plib_adc.h C typedef enum { ADC_SAMPLING_MODE_MUXA, ADC_SAMPLING_MODE_ALTERNATE_INPUT } ADC_SAMPLING_MODE; Members Members Description ADC_SAMPLING_MODE_MUXA Always Mux A Sampling Mode ADC_SAMPLING_MODE_ALTERNATE_INPUT Alternate Input Sampling Mode Description ADC Sampling Mode Select This data type defines the ADC Sampling Mode Select. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_INPUTS_SCAN Enumeration Defines the ADC Scan inputs. File help_plib_adc.h C typedef enum { ADC_INPUT_SCAN_AN0, ADC_INPUT_SCAN_AN1, ADC_INPUT_SCAN_AN2, ADC_INPUT_SCAN_AN3, ADC_INPUT_SCAN_AN4, ADC_INPUT_SCAN_AN5, ADC_INPUT_SCAN_AN6, ADC_INPUT_SCAN_AN7, ADC_INPUT_SCAN_AN8, ADC_INPUT_SCAN_AN9, ADC_INPUT_SCAN_AN10, ADC_INPUT_SCAN_AN11, ADC_INPUT_SCAN_AN12, ADC_INPUT_SCAN_AN13, ADC_INPUT_SCAN_AN14, ADC_INPUT_SCAN_AN15, ADC_INPUT_SCAN_AN16, Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 77 ADC_INPUT_SCAN_AN17, ADC_INPUT_SCAN_AN18, ADC_INPUT_SCAN_AN19, ADC_INPUT_SCAN_AN20, ADC_INPUT_SCAN_AN21, ADC_INPUT_SCAN_AN22, ADC_INPUT_SCAN_AN23, ADC_INPUT_SCAN_AN24, ADC_INPUT_SCAN_AN25, ADC_INPUT_SCAN_AN26, ADC_INPUT_SCAN_AN27, ADC_INPUT_SCAN_AN28, ADC_INPUT_SCAN_AN29, ADC_INPUT_SCAN_AN30, ADC_INPUT_SCAN_AN31, ADC_INPUT_SCAN_IVREF, ADC_INPUT_SCAN_CTMU, ADC_INPUT_SCAN_VSS } ADC_INPUTS_SCAN; Members Members Description ADC_INPUT_SCAN_AN0 Scan input is AN0 ADC_INPUT_SCAN_AN1 Scan input is AN1 ADC_INPUT_SCAN_AN2 Scan input is AN2 ADC_INPUT_SCAN_AN3 Scan input is AN3 ADC_INPUT_SCAN_AN4 Scan input is AN4 ADC_INPUT_SCAN_AN5 Scan input is AN5 ADC_INPUT_SCAN_AN6 Scan input is AN6 ADC_INPUT_SCAN_AN7 Scan input is AN7 ADC_INPUT_SCAN_AN8 Scan input is AN8 ADC_INPUT_SCAN_AN9 Scan input is AN9 ADC_INPUT_SCAN_AN10 Scan input is AN10 ADC_INPUT_SCAN_AN11 Scan input is AN11 ADC_INPUT_SCAN_AN12 Scan input is AN12 ADC_INPUT_SCAN_AN13 Scan input is AN13 ADC_INPUT_SCAN_AN14 Scan input is AN14 ADC_INPUT_SCAN_AN15 Scan input is AN15 ADC_INPUT_SCAN_AN16 Scan input is AN16 ADC_INPUT_SCAN_AN17 Scan input is AN17 ADC_INPUT_SCAN_AN18 Scan input is AN18 ADC_INPUT_SCAN_AN19 Scan input is AN19 ADC_INPUT_SCAN_AN20 Scan input is AN20 ADC_INPUT_SCAN_AN21 Scan input is AN21 ADC_INPUT_SCAN_AN22 Scan input is AN22 ADC_INPUT_SCAN_AN23 Scan input is AN23 ADC_INPUT_SCAN_AN24 Scan input is AN24 ADC_INPUT_SCAN_AN25 Scan input is AN25 ADC_INPUT_SCAN_AN26 Scan input is AN26 ADC_INPUT_SCAN_AN27 Scan input is AN27 ADC_INPUT_SCAN_AN28 Scan input is AN28 ADC_INPUT_SCAN_AN29 Scan input is AN29 ADC_INPUT_SCAN_AN30 Scan input is AN30 ADC_INPUT_SCAN_AN31 Scan input is AN31 ADC_INPUT_SCAN_IVREF Scan input is IVref ADC_INPUT_SCAN_CTMU Scan input is CTMU input ADC_INPUT_SCAN_VSS Scan input is VSS Description ADC Scan Inputs Enumeration This data type defines the ADC Scan inputs. Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 78 Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_RESULT_FORMAT Enumeration Defines the ADC Result Format. File help_plib_adc.h C typedef enum { ADC_RESULT_FORMAT_INTEGER_16BIT, ADC_RESULT_FORMAT_SIGNED_INTEGER_16BIT, ADC_RESULT_FORMAT_FRACTIONAL_16BIT, ADC_RESULT_FORMAT_SIGNED_FRACTIONAL_16BIT, ADC_RESULT_FORMAT_INTEGER_32BIT, ADC_RESULT_FORMAT_SIGNED_INTEGER_32BIT, ADC_RESULT_FORMAT_FRACTIONAL_32BIT, ADC_RESULT_FORMAT_SIGNED_FRACTIONAL_32BIT } ADC_RESULT_FORMAT; Members Members Description ADC_RESULT_FORMAT_INTEGER_16BIT Integer 16-bit ADC_RESULT_FORMAT_SIGNED_INTEGER_16BIT Signed Integer 16-bit ADC_RESULT_FORMAT_FRACTIONAL_16BIT Fractional 16-bit ADC_RESULT_FORMAT_SIGNED_FRACTIONAL_16BIT Signed Fractional 16-bit ADC_RESULT_FORMAT_INTEGER_32BIT Integer 32-bit ADC_RESULT_FORMAT_SIGNED_INTEGER_32BIT Signed Integer 32-bit ADC_RESULT_FORMAT_FRACTIONAL_32BIT Fractional 32-bit ADC_RESULT_FORMAT_SIGNED_FRACTIONAL_32BIT Signed Fractional 32-bit Description ADC Result Format This data type defines the ADC Result Format. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_INPUTS_POSITIVE Enumeration Defines the ADC inputs. File help_plib_adc.h C typedef enum { ADC_INPUT_POSITIVE_AN0, ADC_INPUT_POSITIVE_AN1, ADC_INPUT_POSITIVE_AN2, ADC_INPUT_POSITIVE_AN3, ADC_INPUT_POSITIVE_AN4, ADC_INPUT_POSITIVE_AN5, ADC_INPUT_POSITIVE_AN6, ADC_INPUT_POSITIVE_AN7, ADC_INPUT_POSITIVE_AN8, ADC_INPUT_POSITIVE_AN9, ADC_INPUT_POSITIVE_AN10, ADC_INPUT_POSITIVE_AN11, ADC_INPUT_POSITIVE_AN12, ADC_INPUT_POSITIVE_AN13, ADC_INPUT_POSITIVE_AN14, Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 79 ADC_INPUT_POSITIVE_AN15 , ADC_INPUT_POSITIVE_AN16 , ADC_INPUT_POSITIVE_AN17 , ADC_INPUT_POSITIVE_AN18 , ADC_INPUT_POSITIVE_AN19 , ADC_INPUT_POSITIVE_AN20 , ADC_INPUT_POSITIVE_AN21 , ADC_INPUT_POSITIVE_AN22 , ADC_INPUT_POSITIVE_AN23 , ADC_INPUT_POSITIVE_AN24 , ADC_INPUT_POSITIVE_AN25 , ADC_INPUT_POSITIVE_AN26 , ADC_INPUT_POSITIVE_AN27 , ADC_INPUT_POSITIVE_AN28 , ADC_INPUT_POSITIVE_AN29 , ADC_INPUT_POSITIVE_AN30 , ADC_INPUT_POSITIVE_AN31 , ADC_INPUT_POSITIVE_AN32 , ADC_INPUT_POSITIVE_AN33 , ADC_INPUT_POSITIVE_AN34 , ADC_INPUT_POSITIVE_AN35 , ADC_INPUT_POSITIVE_AN36 , ADC_INPUT_POSITIVE_AN37 , ADC_INPUT_POSITIVE_AN38 , ADC_INPUT_POSITIVE_AN39 , ADC_INPUT_POSITIVE_AN40 , ADC_INPUT_POSITIVE_AN41 , ADC_INPUT_POSITIVE_AN42 , ADC_INPUT_POSITIVE_AN43 , ADC_INPUT_POSITIVE_AN44 , ADC_INPUT_POSITIVE_AN45 , ADC_INPUT_POSITIVE_AN46 , ADC_INPUT_POSITIVE_AN47 , ADC_INPUT_POSITIVE_CTMU , ADC_INPUT_POSITIVE_IVREF , ADC_INPUT_POSITIVE_OPEN } ADC_INPUTS_POSITIVE; Members Members Description ADC_INPUT_POSITIVE_AN0 Positive input is AN0 ADC_INPUT_POSITIVE_AN1 Positive input is AN1 ADC_INPUT_POSITIVE_AN2 Positive input is AN2 ADC_INPUT_POSITIVE_AN3 Positive input is AN3 ADC_INPUT_POSITIVE_AN4 Positive input is AN4 ADC_INPUT_POSITIVE_AN5 Positive input is AN5 ADC_INPUT_POSITIVE_AN6 Positive input is AN6 ADC_INPUT_POSITIVE_AN7 Positive input is AN7 ADC_INPUT_POSITIVE_AN8 Positive input is AN8 ADC_INPUT_POSITIVE_AN9 Positive input is AN9 ADC_INPUT_POSITIVE_AN10 Positive input is AN10 ADC_INPUT_POSITIVE_AN11 Positive input is AN11 ADC_INPUT_POSITIVE_AN12 Positive input is AN12 ADC_INPUT_POSITIVE_AN13 Positive input is AN13 ADC_INPUT_POSITIVE_AN14 Positive input is AN14 ADC_INPUT_POSITIVE_AN15 Positive input is AN15 ADC_INPUT_POSITIVE_AN16 Positive input is AN16 ADC_INPUT_POSITIVE_AN17 Positive input is AN17 ADC_INPUT_POSITIVE_AN18 Positive input is AN18 ADC_INPUT_POSITIVE_AN19 Positive input is AN19 ADC_INPUT_POSITIVE_AN20 Positive input is AN20 ADC_INPUT_POSITIVE_AN21 Positive input is AN21 ADC_INPUT_POSITIVE_AN22 Positive input is AN22 ADC_INPUT_POSITIVE_AN23 Positive input is AN23 ADC_INPUT_POSITIVE_AN24 Positive input is AN24 Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 80 ADC_INPUT_POSITIVE_AN25 Positive input is AN25 ADC_INPUT_POSITIVE_AN26 Positive input is AN26 ADC_INPUT_POSITIVE_AN27 Positive input is AN27 ADC_INPUT_POSITIVE_AN28 Positive input is AN28 ADC_INPUT_POSITIVE_AN29 Positive input is AN29 ADC_INPUT_POSITIVE_AN30 Positive input is AN30 ADC_INPUT_POSITIVE_AN31 Positive input is AN31 ADC_INPUT_POSITIVE_AN32 Positive input is AN32 ADC_INPUT_POSITIVE_AN33 Positive input is AN33 ADC_INPUT_POSITIVE_AN34 Positive input is AN34 ADC_INPUT_POSITIVE_AN35 Positive input is AN35 ADC_INPUT_POSITIVE_AN36 Positive input is AN36 ADC_INPUT_POSITIVE_AN37 Positive input is AN37 ADC_INPUT_POSITIVE_AN38 Positive input is AN38 ADC_INPUT_POSITIVE_AN39 Positive input is AN39 ADC_INPUT_POSITIVE_AN40 Positive input is AN40 ADC_INPUT_POSITIVE_AN41 Positive input is AN41 ADC_INPUT_POSITIVE_AN42 Positive input is AN42 ADC_INPUT_POSITIVE_AN43 Positive input is AN43 ADC_INPUT_POSITIVE_AN44 Positive input is AN44 ADC_INPUT_POSITIVE_AN45 Positive input is AN45 ADC_INPUT_POSITIVE_AN46 Positive input is AN46 ADC_INPUT_POSITIVE_AN47 Positive input is AN47 ADC_INPUT_POSITIVE_CTMU Positive input is from CTMU ADC_INPUT_POSITIVE_IVREF Positive input is IVref ADC_INPUT_POSITIVE_OPEN Positive input is Open Description ADC Inputs Enumeration This data type defines the ADC inputs. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADC_ACQUISITION_TIME Type Data type defining the different ADC acquisition times by which the ADC can be configured. File plib_adc.h C typedef uint32_t ADC_ACQUISITION_TIME; Description ADC Acquisition Time Selection Data Type This data type defines the different ADC acquisition times by which the ADC can be configured. Remarks None. ADC_CONVERSION_CLOCK Type Data type defines the different ADC Conversion clock File plib_adc.h Peripheral Libraries Help ADC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 81 C typedef uint32_t ADC_CONVERSION_CLOCK; Description ADC Conversion Clock Selection Data Type This data type defines the different ADC Conversion clock Remarks None. ADC_SAMPLE Type Data type defining the size of the ADC sample register. File plib_adc.h C typedef uint32_t ADC_SAMPLE; Description ADC Sample size This data type defines the size of the ADC sample register. Remarks None. Files Files Name Description plib_adc.h ADC PLIB interface header for definitions common to the ADC peripheral. help_plib_adc.h This is file help_plib_adc.h. Description This section lists the source and header files used by the library. plib_adc.h ADC PLIB interface header for definitions common to the ADC peripheral. Functions Name Description PLIB_ADC_CalibrationDisable Normal ADC module operation (no calibration is performed). PLIB_ADC_CalibrationEnable Calibration is performed on the next ADC conversion. PLIB_ADC_ConversionClockGet Obtains the conversion clock. PLIB_ADC_ConversionClockSet Sets the ADC module conversion clock. PLIB_ADC_ConversionClockSourceSelect Selects the ADC module conversion clock source. PLIB_ADC_ConversionHasCompleted Provides the conversion completion status of the ADC. PLIB_ADC_ConversionStart Starts ADC module manual conversion process. PLIB_ADC_ConversionStopSequenceDisable Normal conversion sequence. PLIB_ADC_ConversionStopSequenceEnable Stop conversion sequence (when the first ADC module interrupt is generated). PLIB_ADC_ConversionTriggerSourceSelect Selects the conversion trigger source. PLIB_ADC_Disable ADC module is disabled (turned OFF). PLIB_ADC_Enable ADC module is enabled (turned ON). PLIB_ADC_ExistsCalibrationControl Identifies whether the CalibrationControl feature exists on the ADC module PLIB_ADC_ExistsConversionClock Identifies whether the ConversionClock feature exists on the ADC module Peripheral Libraries Help ADC Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 82 PLIB_ADC_ExistsConversionClockSource Identifies whether the ConversionClockSource feature exists on the ADC module PLIB_ADC_ExistsConversionControl Identifies whether the ConversionControl feature exists on the ADC module PLIB_ADC_ExistsConversionStatus Identifies whether the ConversionStatus feature exists on the ADC module PLIB_ADC_ExistsConversionStopSequenceControl Identifies whether the ConversionStopSequenceControl feature exists on the ADC module PLIB_ADC_ExistsConversionTriggerSource Identifies whether the ConversionTriggerSource feature exists on the ADC module PLIB_ADC_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADC module PLIB_ADC_ExistsMuxChannel0NegativeInput Identifies whether the MuxChannel0NegativeInput feature exists on the ADC module PLIB_ADC_ExistsMuxChannel0PositiveInput Identifies whether the MuxChannel0PositiveInput feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanControl Identifies whether the MuxInputScanControl feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanSelect Identifies whether the MuxInputScanSelect feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanSelectExtended Identifies whether the MuxInputScanSelectExtended feature exists on the ADC module PLIB_ADC_ExistsResultBufferFillStatus Identifies whether the ResultBufferFillStatus feature exists on the ADC module PLIB_ADC_ExistsResultBufferMode Identifies whether the ResultBufferMode feature exists on the ADC module PLIB_ADC_ExistsResultFormat Identifies whether the ResultFormat feature exists on the ADC module PLIB_ADC_ExistsResultGetByIndex Identifies whether the ResultGetByIndex feature exists on the ADC module PLIB_ADC_ExistsSamplesPerInterruptSelect Identifies whether the SamplesPerInterruptSelect feature exists on the ADC module PLIB_ADC_ExistsSamplingAcquisitionTime Identifies whether the SamplingAcquisitionTime feature exists on the ADC module PLIB_ADC_ExistsSamplingAutoStart Identifies whether the SamplingAutoStart feature exists on the ADC module PLIB_ADC_ExistsSamplingControl Identifies whether the SamplingControl feature exists on the ADC module PLIB_ADC_ExistsSamplingModeControl Identifies whether the SamplingModeControl feature exists on the ADC module PLIB_ADC_ExistsSamplingStatus Identifies whether the SamplingStatus feature exists on the ADC module PLIB_ADC_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the ADC module PLIB_ADC_ExistsVoltageReference Identifies whether the VoltageReference feature exists on the ADC module PLIB_ADC_InputScanMaskAdd Select ADC analog channel for input scan. PLIB_ADC_InputScanMaskAddExtended Select extended ADC analog channel for input scan. PLIB_ADC_InputScanMaskRemove Omits ADC analog channel for input scan. PLIB_ADC_InputScanMaskRemoveExtended Omits extended ADC analog channel for input scan. PLIB_ADC_MuxAInputScanDisable Do not scan input selections for CH0+ of MUX A. PLIB_ADC_MuxAInputScanEnable Scan input selections for CH0+ of MUX A. PLIB_ADC_MuxChannel0InputNegativeSelect Channel 0 negative input select for multiplexer setting. PLIB_ADC_MuxChannel0InputPositiveSelect Channel 0 positive input select for multiplexer setting. PLIB_ADC_ResultBufferModeSelect Selects the result buffer mode. PLIB_ADC_ResultBufferStatusGet Provides the buffer fill status. PLIB_ADC_ResultFormatSelect Selects the result format. PLIB_ADC_ResultGetByIndex Provides the ADC conversion result based on the buffer index. PLIB_ADC_SampleAcquisitionTimeSet Sets the ADC acquisition/auto-sample time in TADs. PLIB_ADC_SampleAutoStartDisable Sampling auto-start is disabled. PLIB_ADC_SampleAutoStartEnable Sampling auto-start is enabled. PLIB_ADC_SamplesPerInterruptSelect Interrupts at the completion of conversion for each nth sample. PLIB_ADC_SamplingIsActive Provides the ADC sampling status. PLIB_ADC_SamplingModeSelect Enable the selected sampling mode. PLIB_ADC_SamplingStart Sampling is enabled. PLIB_ADC_SamplingStop Holding is enabled. PLIB_ADC_StopInIdleDisable Continue ADC module operation when the device is in Idle mode. PLIB_ADC_StopInIdleEnable Discontinue ADC module operation when device enters Idle mode. PLIB_ADC_VoltageReferenceSelect Voltage reference configuration. Peripheral Libraries Help ADC Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 83 Types Name Description ADC_ACQUISITION_TIME Data type defining the different ADC acquisition times by which the ADC can be configured. ADC_CONVERSION_CLOCK Data type defines the different ADC Conversion clock ADC_SAMPLE Data type defining the size of the ADC sample register. Description ADC Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the ADC PLIB for all families of Microchip microcontrollers. The definitions in this file are common to the ADC peripheral. File Name plib_adc.h Company Microchip Technology Inc. help_plib_adc.h Enumerations Name Description ADC_BUFFER_MODE Defines the ADC Buffer Mode. ADC_CLOCK_SOURCE Defines the ADC Clock Source Select. ADC_CONVERSION_TRIGGER_SOURCE Defines the ADC Conversion Trigger Source. ADC_INPUTS_NEGATIVE Defines the different ADC Negative Input Enumeration. ADC_INPUTS_POSITIVE Defines the ADC inputs. ADC_INPUTS_SCAN Defines the ADC Scan inputs. ADC_MODULE_ID Identifies the available ADC modules. ADC_MUX Defining the different ADC MUX Enumeration. ADC_RESULT_BUF_STATUS Defines the ADC Result Buffer Status ADC_RESULT_FORMAT Defines the ADC Result Format. ADC_SAMPLES_PER_INTERRUPT Defining the Samples Per Interrupt Enumeration. ADC_SAMPLING_MODE Defines the ADC Sampling Mode Select. ADC_VOLTAGE_REFERENCE Defining the different ADC Voltage Reference by which the ADC can be configured. Description This is file help_plib_adc.h. Peripheral Libraries Help ADC Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 84 ADCHS Peripheral Library This section describes the 12-bit High-Speed Successive Approximation Register (SAR) Analog-to-Digital Converter (ADCHS) Peripheral Library. Introduction This library provides a low-level abstraction of the High-Speed SAR ADC (ADCHS) Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the registers, thereby hiding differences from one microcontroller variant to another. Description The ADCHS is used to convert an analog input into a digital number that represents that input voltage. When the input is periodically converted, the result is a sequence of digital values that have converted a continuous-time and continuous-amplitude analog signal to a discrete-time and discrete-amplitude digital signal. This particular ADC architecture consists of multiple SAR channels (maximum of eight). The SAR channels are numbered from Channel 0 to Channel 7. Out of these channels, Channels 0 through 6 have dedicated sample and hold (S&H) circuits connected to a single (selectable) analog input. These SAR channels work independently from each other and are designed to capture time sensitive or transitory analog signals. The remaining channel, Channel 7, has its S&H circuit connected to multiple analog inputs through a multiplexer. Channel 7 is used to convert analog signals that do not need a high conversion rate. Features of the ADCHS module include: • Channels 0 through 6 have selectable analog inputs (default, alternate), which can be connected to a S&H circuit • Channel 7 has multiple analog inputs connected to a S&H circuit • Analog inputs connected to Channels 0 through 6 are Class 1 analog inputs. Analog inputs connected to Channel 7 are classified as Class 2 and Class 3 analog inputs. • Class 1 analog inputs have their individual trigger source and are converted by dedicated Channels (0 through 6). • Class 2 analog inputs have their individual trigger source, but are converted by shared channel-7 • Class 3 analog inputs do not have individual trigger source and are converted by scan mode using Channel 7 • Analog input scan is available, which allows a single trigger to start a sample/conversion sequence of multiple analog inputs using a predefined scan list • The inputs to a S&H can be configured as unipolar/bipolar and single-ended/differential mode • For each channel, the converted data resolution can be set as 6, 8, 10, or 12-bits • Each channel (0 through 7) can have its individual conversion clock and sample time setting • A voltage reference is required for the ADCHS module. The voltage reference setting is a global setting for the ADCHS module and does not vary across channels. • Result registers store the conversion results and can be read by the software application. Software is notified of ready results by either polling or through the use of interrupts. • For Channels 0 through 6, the converted data can be stored in an optional FIFO or directly to RAM using the dedicated DMA interface • Optional Digital Filters can be used to provide increased resolution at the sacrifice of sample rate. Digital Filters also have an averaging mode. • Optional Digital Comparators can be used to test conversion results against set high and low limits, which are independent of software, and generate interrupts based on predefined conditions • Digital Comparators also have Capacitive Voltage Divider (CVD) mode, which can be used to detect a touch event in touch sense application • Early interrupt generation, providing extremely fast processing of converted data A block diagram of the ADCHS module is provided in the following figure. Peripheral Libraries Help ADCHS Peripheral Library Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 85 Using the Library This topic describes the basic architecture of the ADCHS Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_adchs.h The interface to the ADCHS Peripheral library is defined in the plib_adchs.h header file, which is included by the peripheral.h file. Any C Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 86 language source (.c) file that uses the ADCHS Peripheral library must include peripheral.h. Library File: The ADCHS Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the ADCHS module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all the functionality of the available ADCHS module on the device. Refer to the "ADC" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine the set of functions that are supported for each ADCHS module on the device. Description High-Speed SAR Analog-to-Digital Converter (ADCHS) Software Abstraction Block Diagram Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the ADCHS module. Library Interface Section Description Configuration Functions These functions are used to configure, enable, and disable the ADCHS. Analog Input Functions These functions are used to configure analog input features. Analog Input Selection Functions These functions select and configure the ANx inputs to the ADCHS. CVD Functions These functions configure the Capacitive Voltage Divider (CVD) mode. DMA Functions These functions are used to configure and enable/disable the DMA, enable/ disable interrupts linked to the DMA, and to get the DMA status. Channel Related Functions These functions configure Channels 0 through 7, enable/disable the analog and digital circuitry, and control interrupt generation. Digital Comparator Functions These functions are used to configure and query the digital comparators. Digital Filter Functions These functions are used to configure the Oversampling Digital Filter and fetch results from it. FIFO Functions These functions configure the FIFO and control the interrupt generation. Status Functions These functions return status information related to the ADCHS. Interrupt Functions These functions control interrupt generation. Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 87 Turbo Mode Functions These functions are used to configure, enable, and disable Turbo mode. Triggering Functions These functions configure the trigger source for various cores. Voltage Reference Functions These functions control the Voltage Reference (VREF) input for the ADC cores and query VREF status and interrupt generation. Feature Existence Functions These functions determine whether or not a particular feature is supported by the device. How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. Functionality This topic describes the functionality of the ADCHS Peripheral Library. Description Analog-to-Digital conversion using the ADCHS involves the following three steps: 1. Sampling of the input signal. 2. Capture of the input signal by the S&H circuit and transfer to the converter. 3. Conversion of the analog signal to its digital representation. Sampling of the input signal involves charging of the S&H capacitor. The sampling time must be adequate so that the capacitor charges to a value equal to the input voltage. At the appropriate time, the input is disconnected and the capacitor voltage is transferred to the converter. The converter then digitizes the analog signal and provides the result. The converter requires a clock source (common input to individual clock setting of all channels) and a reference voltage. The common input clock is referred to as the control clock and has a period of TQ. The control clock and reference voltage sources are selectable, as well as the clock prescaling that determines the TQ. The ADCHS has multiple SAR channels. Each channel has independent clocks named TAD0 through TAD7. The analog inputs connected to the SAR channels can be divided as Class 1, Class 2, and Class 3. • Class 1 inputs are associated with a SAR Channel 0 through 6. Each SAR channel has a single (selectable) Class 1 input associated with it. Each Class 1 input has a unique trigger selection register. Class 1 inputs can also be part of a channel scan list, triggered by the common scan trigger source. • Class 2 inputs are connected to Channel 7 and are either individually triggered or as part of a channel scan list. When used individually their trigger source is selected by their unique trigger register. • Class 3 inputs are connected to Channel 7 and are used in channel scan exclusively. They share a common trigger source. When using channel scan it is possible to combine Class 1, Class 2, and Class 3 inputs in the scan list. Note: For details regarding configuration and triggering options was well as sampling requirements, refer to the "ADC" chapter in the specific device data sheet and the family reference manual section specified in that chapter. Example - Simultaneous Sampling and Conversion of Three Class 1 Inputs Simultaneous sampling and conversion is used when the application requires capture of more than one signal at the same instance of time. Simultaneous sampling and conversion requires the use of multiple Class 1 inputs where each is assigned the same trigger source. The following example illustrates simultaneous sampling of AN0, AN1 and AN2 using the global software trigger as the trigger source. The respective SAR channels are configured for single-ended input and a unipolar (unsigned) output. No interrupts are used so the results are polled for ready status. { int result[3]; // storage for results // Configure the ADC PLIB_ADCHS_Setup ( MY_ADCHS_INSTANCE, ADCHS_VREF_AVDD_AVSS, // AVDD and AVSS as reference ADCHS_CHARGEPUMP_DISABLE, // No charge pump ADCHS_OUTPUT_DATA_FORMAT_FRACTIONAL, // Use fractional format true, // Do stop in idle ADCHS_FAST_SYNC_SYSTEM_CLOCK_ENABLE, // Enable Fast synchronous system clock ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_DISABLE, // Disable Fast synchronous peripheral clock ADCHS_INTERRUPT_BIT_SHIFT_LEFT_0_BITS, // vector shift unused, interrupt not used 0, // vector base address unused, interrupt not used Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 88 ADCHS_CLOCK_SOURCE_SYSCLK, // SYSCLK is the clock source 1, // TQ = 1/SYSCLK * 2 ADCHS_WARMUP_CLOCK_32 // Warm-up time = 32 clocks ); // Configure the ADC SAR Channel-0 PLIB_ADCHS_ChannelSetup ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0, // Channel - 0 ADCHS_DATA_RESOLUTION_12BIT, // resolution is set to 12bits 1, // clock divider bit is, TAD0 = 2 * TQ 1, // Sample time is 3 * TAD ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 // 1 clock early interrupt (ignored, interrupt not used) ); // Configure the synchronous sampling for Channel-0 if(false == PLIB_ADCHS_ChannelTriggerSampleSelect( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0, // channel - 0 ADCHS_CHANNEL_SYNC_SAMPLING)) // Synchronous sampling selected { // error has occurred while(1); } // Configure the ADC SAR Channel-1 PLIB_ADCHS_ChannelSetup ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1, // Channel - 1 ADCHS_DATA_RESOLUTION_12BIT, // resolution is set to 12bits 1, // clock divider bit is, TAD1 = 2 * TQ 1, // Sample time is 3 * TAD ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 // 1 clock early interrupt (ignored, interrupt not used) ); // Configure the synchronous sampling for Channel-1 if(false == PLIB_ADCHS_ChannelTriggerSampleSelect( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1, // channel - 1 ADCHS_CHANNEL_SYNC_SAMPLING)) // Synchronous sampling selected { // error has occurred while(1); } // Configure the ADC SAR Channel-2 PLIB_ADCHS_ChannelSetup ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_2, // Channel - 2 ADCHS_DATA_RESOLUTION_12BIT, // resolution is set to 12bits 1, // clock divider bit is, TAD2 = 2 * TQ 1, // Sample time is 3 * TAD ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 // 1 clock early interrupt (ignored, interrupt not used) ); // Configure the synchronous sampling for Channel-2 if(false == PLIB_ADCHS_ChannelTriggerSampleSelect( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_2, // channel - 2 ADCHS_CHANNEL_SYNC_SAMPLING)) // Synchronous sampling selected { // error has occurred while(1); } // Select inputs for Channel if(false == PLIB_ADCHS_ChannelInputSelect ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0, ADCHS_CHANNEL_0_DEFAULT_INP_AN0 // Select AN0 for channel-0 )) { // error has occurred while(1); } Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 89 if(false == PLIB_ADCHS_ChannelInputSelect ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1, ADCHS_CHANNEL_0_DEFAULT_INP_AN1 // Select AN1 for channel-1 )) { // error has occurred while(1); } if(false == PLIB_ADCHS_ChannelInputSelect ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_2, ADCHS_CHANNEL_0_DEFAULT_INP_AN2 // Select AN2 for channel-2 )) { // error has occurred while(1); } // Select input mode for AN0, AN1, AN2 PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN0, ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR ); PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN1, ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR ); PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN2, ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR ); // Select AN0, AN1 and AN2 as edge trigger PLIB_ADCHS_AnalogInputEdgeTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN0 ); PLIB_ADCHS_AnalogInputEdgeTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN1 ); PLIB_ADCHS_AnalogInputEdgeTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN2 ); // Select AN0, AN1 and AN2 to be software triggered PLIB_ADCHS_AnalogInputTriggerSourceSelect ( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN0, ADCHS_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE ); PLIB_ADCHS_AnalogInputTriggerSourceSelect ( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN1, ADCHS_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE ); PLIB_ADCHS_AnalogInputTriggerSourceSelect ( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN2, ADCHS_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE ); // Enable ADC PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); // Check VREF to be ready While(!PLIB_ADCHS_VREFIsReady(MY_ADCHS_INSTANCE)); // Check for VREF Fault While(PLIB_ADCHS_VREFFaultHasOccurred(MY_ADCHS_INSTANCE)); // Enable analog circuit for channel-0, 1 and 2 Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 90 PLIB_ADCHS_ChannelAnalogFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0 ); PLIB_ADCHS_ChannelAnalogFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); PLIB_ADCHS_ChannelAnalogFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_2 ); // Wait for the channels to be ready while(!PLIB_ADCHS_ChannelIsReady ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0 ) ); while(!PLIB_ADCHS_ChannelIsReady ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ) ); while(!PLIB_ADCHS_ChannelIsReady ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_2 ) ); // Enable digital circuit for channels 0, 1, 2 PLIB_ADCHS_ChannelDigitalFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0 ); PLIB_ADCHS_ChannelDigitalFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); PLIB_ADCHS_ChannelDigitalFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_2 ); while(1) { // Enable global software trigger PLIB_ADCHS_GlobalSoftwareTriggerEnable( MY_ADCHS_INSTANCE ); // Wait for conversion complete for AN0 while(!PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN0)); result[0] = PLIB_ADCHS_AnalogInputResultGet( MY_ADCHS_INSTANCE, ADCHS_AN0 ); // Wait for conversion complete for AN1 while(!PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN1)); result[1] = PLIB_ADCHS_AnalogInputResultGet( MY_ADCHS_INSTANCE, ADCHS_AN1 ); // Wait for conversion complete for AN2 while(!PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN2)); result[2] = PLIB_ADCHS_AnalogInputResultGet( MY_ADCHS_INSTANCE, ADCHS_AN2 ); } return(1); } Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 91 Example - Channel Scanning Channel scanning is used in applications where precise timing of the sample to an external source is not needed. Channel scanning allows a large number of analog inputs to be sampled and converted in sequence each time a single trigger occurs. The following example illustrates how to configure channel scanning of multiple Class 2 and Class 3 inputs using Channel 7. This example uses inputs AN8, AN31 through AN33. AN8 is Class 2 inputs. AN31 to AN33 are Class 3 inputs. The global software trigger is used to initiate the scan. A 3 TAD7 sample time is specified for Channel 7, which is configured for single-ended operation and a unipolar output. No interrupts are used so the results are polled for ready status. { int result[4]; // storage for results // Configure the ADC PLIB_ADCHS_Setup ( MY_ADCHS_INSTANCE, ADCHS_VREF_AVDD_AVSS, // AVDD and AVSS as reference ADCHS_CHARGEPUMP_DISABLE, // No charge pump ADCHS_OUTPUT_DATA_FORMAT_FRACTIONAL, // Use fractional format true, // Do stop in idle ADCHS_FAST_SYNC_SYSTEM_CLOCK_ENABLE, // Enable Fast synchronous system clock ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_DISABLE, // Disable Fast synchronous peripheral clock ADCHS_INTERRUPT_BIT_SHIFT_LEFT_0_BITS, // vector shift unused, interrupt not used 0, // vector base address unused, interrupt not used ADCHS_CLOCK_SOURCE_SYSCLK, // SYSCLK is the clock source 1, // TQ = 1/SYSCLK * 2 ADCHS_WARMUP_CLOCK_32 // Warm-up time = 32 clocks ); // Configure the ADC SAR Channel-7 PLIB_ADCHS_ChannelSetup ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7, // Channel - 7 ADCHS_DATA_RESOLUTION_12BIT, // resolution is set to 12bits 1, // clock divider bit is, TAD7 = 2 * TQ 1, // Sample time is 3 * TAD7 ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 // 1 clock early interrupt (ignored, interrupt not used) ); // Select analog channel AN8 and scan sequence to be triggered with global scan trigger PLIB_ADCHS_AnalogInputScanSetup ( MY_ADCHS_INSTANCE, ADCHS_AN8, ADCHS_SCAN_TRIGGER_SENSITIVE_EDGE, ADCHS_SCAN_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE ); // Now, add further analog inputs, AN31, AN32, AN33 to scan list PLIB_ADCHS_AnalogInputScanSelect(MY_ADCHS_INSTANCE, ADCHS_AN31); PLIB_ADCHS_AnalogInputScanSelect(MY_ADCHS_INSTANCE, ADCHS_AN32); PLIB_ADCHS_AnalogInputScanSelect(MY_ADCHS_INSTANCE, ADCHS_AN33); // Select input mode for AN8, AN31, AN32, AN33 PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN8, ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR ); PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN31, ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR ); PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN32, ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR ); Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 92 PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN33, ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR ); // Select individual trigger for class-2 channels viz. AN8 to be scan trigger. // AN31, AN32 and AN33 are class-3 channels, and do not have individual trigger PLIB_ADCHS_AnalogInputTriggerSourceSelect ( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN8, ADCHS_TRIGGER_SOURCE_SCAN ); // Select AN8 to be edge trigger (not level trigger). // Calling this function is needed for class-1 and 2 analog inputs PLIB_ADCHS_AnalogInputEdgeTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN8); // Enable ADC PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); // Check VREF to be ready While(!PLIB_ADCHS_VREFIsReady(MY_ADCHS_INSTANCE)); // Check for VREF Fault While(PLIB_ADCHS_VREFFaultHasOccurred(MY_ADCHS_INSTANCE)); // Enable analog circuit for channel-7 PLIB_ADCHS_ChannelAnalogFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7 ); // Wait for the channel-7 to be ready while(!PLIB_ADCHS_ChannelIsReady ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7 ) ); // Enable digital circuit for channels 7 PLIB_ADCHS_ChannelDigitalFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7 ); while(1) { // Enable global software trigger PLIB_ADCHS_GlobalSoftwareTriggerEnable( MY_ADCHS_INSTANCE ); // Wait for conversion complete for AN8 while(!PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN8)); result[0] = PLIB_ADCHS_AnalogInputResultGet( MY_ADCHS_INSTANCE, ADCHS_AN8 ); // Wait for conversion complete for AN31 while(!PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN31)); result[1] = PLIB_ADCHS_AnalogInputResultGet( MY_ADCHS_INSTANCE, ADCHS_AN31 ); // Wait for conversion complete for AN32 while(!PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN32)); result[2] = PLIB_ADCHS_AnalogInputResultGet( MY_ADCHS_INSTANCE, ADCHS_AN32 ); // Wait for conversion complete for AN33 while(!PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN33)); result[3] = PLIB_ADCHS_AnalogInputResultGet( MY_ADCHS_INSTANCE, ADCHS_AN33 ); } return(1); } Example - Digital Filter The Digital Oversampling filter can be used to increase resolution of the conversion result at the expense of throughput. The following example shows how two extra bits of resolution can be obtained using 16x oversampling (sixteen samples are used to create one higher resolution result). AN0 is used for the input. The sampling time for the retriggers is set to 3 TAD0. { Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 93 int result; // storage for results bool eventFlag = false; // Digital comparator event flag // Configure the ADC PLIB_ADCHS_Setup ( MY_ADCHS_INSTANCE, ADCHS_VREF_AVDD_AVSS, // AVDD and AVSS as reference ADCHS_CHARGEPUMP_DISABLE, // No charge pump ADCHS_OUTPUT_DATA_FORMAT_FRACTIONAL, // Use fractional format true, // Do stop in idle ADCHS_FAST_SYNC_SYSTEM_CLOCK_ENABLE, // Enable Fast synchronous system clock ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_DISABLE, // Disable Fast synchronous peripheral clock ADCHS_INTERRUPT_BIT_SHIFT_LEFT_0_BITS, // vector shift not used since interrupt not used 0, // vector base address unused, interrupt not used ADCHS_CLOCK_SOURCE_SYSCLK, // SYSCLK is the clock source 1, // TQ = 1/SYSCLK * 2 ADCHS_WARMUP_CLOCK_32 // Warm-up time = 32 clocks ); // Configure the ADC SAR Channel-0 PLIB_ADCHS_ChannelSetup ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0, // Channel - 0 ADCHS_DATA_RESOLUTION_12BIT, // resolution is set to 12bits 1, // clock divider bit is, TAD0 = 2 * TQ 1, // Sample time is 3 * TAD ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 // 1 clock early interrupt (ignored, interrupt not used) ); // Configure the synchronous sampling for Channel-0 if(false == PLIB_ADCHS_ChannelTriggerSampleSelect( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0, // channel - 0 ADCHS_CHANNEL_SYNC_SAMPLING)) // Synchronous sampling selected { // error has occurred while(1); } // Select inputs for Channel if(false == PLIB_ADCHS_ChannelInputSelect ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0, ADCHS_CHANNEL_0_DEFAULT_INP_AN0 // Select AN0 for channel-0 )) { // error has occurred while(1); } // Select input mode for AN0 PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN0, ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR ); // Select AN0 as edge trigger PLIB_ADCHS_AnalogInputEdgeTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN0 ); // Select AN0 to be software triggered PLIB_ADCHS_AnalogInputTriggerSourceSelect ( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN0, ADCHS_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE ); // Configure digital filter in oversampling mode for 16x sampling PLIB_ADCHS_DigitalFilterOversamplingModeSetup ( MY_ADCHS_INSTANCE, // ADCHS channel ID ADCHS_DIGITAL_FILTER_1, // Filter ID ADCHS_AN0, // Oversample AN4 Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 94 ADCHS_DIGITAL_FILTER_SIGNIFICANT_ALL_16BITS, // all 16bits significant ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_16X, // 16 x oversampling false // No Global Int Enable ); // Enable digital filter PLIB_ADCHS_DigitalFilterEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); // Enable ADC PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); // Check VREF to be ready While(!PLIB_ADCHS_VREFIsReady(MY_ADCHS_INSTANCE)); // Check for VREF Fault While(PLIB_ADCHS_VREFFaultHasOccurred(MY_ADCHS_INSTANCE)); // Enable analog circuit for channel-0 PLIB_ADCHS_ChannelAnalogFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0 ); // Wait for the channels to be ready while(!PLIB_ADCHS_ChannelIsReady ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0 ) ); // Enable digital circuit for channels 0 PLIB_ADCHS_ChannelDigitalFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0 ); while(1) { // Enable global software trigger PLIB_ADCHS_GlobalSoftwareTriggerEnable( MY_ADCHS_INSTANCE ); // Wait for filter result to be ready while(!PLIB_ADCHS_DigitalFilterDataIsReady(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1)); result = PLIB_ADCHS_DigitalFilterDataGet(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); } return(1); } Example - Digital Comparator The Digital Comparator is used to automatically evaluate results as they are output by the converter. The following example illustrates an automated test of AN8 for values that are greater than or equal to 80% of full scale or less than 20% of full scale. A count is incremented each time an event occurs. { int result; // storage for results bool eventFlag = false; // Digital comparator event flag // Configure the ADC PLIB_ADCHS_Setup ( MY_ADCHS_INSTANCE, ADCHS_VREF_AVDD_AVSS, // AVDD and AVSS as reference ADCHS_CHARGEPUMP_DISABLE, // No charge pump ADCHS_OUTPUT_DATA_FORMAT_FRACTIONAL, // Use fractional format true, // Do stop in idle ADCHS_FAST_SYNC_SYSTEM_CLOCK_ENABLE, // Enable Fast synchronous system clock ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_DISABLE, // Disable Fast synchronous peripheral clock ADCHS_INTERRUPT_BIT_SHIFT_LEFT_0_BITS, // vector shift not used since interrupt not used 0, // vector base address unused, interrupt not used ADCHS_CLOCK_SOURCE_SYSCLK, // SYSCLK is the clock source 1, // TQ = 1/SYSCLK * 2 ADCHS_WARMUP_CLOCK_32 // Warm-up time = 32 clocks ); // Configure the ADC SAR Channel-7 PLIB_ADCHS_ChannelSetup Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 95 ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7, // Channel - 7 ADCHS_DATA_RESOLUTION_12BIT, // resolution is set to 12bits 1, // clock divider bit is, TAD7 = 2 * TQ 1, // Sample time is 3 * TAD7 ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 // 1 clock early interrupt (ignored, interrupt not used) ); // Select input mode for AN8 PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN8, ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR ); // Configure the digital comparator - 1 PLIB_ADCHS_DigitalComparatorSetup ( MY_ADCHS_INSTANCE, // ADCHS channel ID ADCHS_DIGITAL_COMPARATOR_1, // Comparator ID false, // Global Int Enable true, // test for between low and high false, // no test for greater than equal to high false, // no test for less than high false, // no test for greater than equal to low false, // no test for less than low ADCHS_AN8, // select AN8 0xFFF - (0xFFF/5), // high limit, 80% of full scale (0xFFF/5) // low limit, 20% of full scale ); // Select individual trigger for class-2 channels viz. AN8 to be global software trigger. PLIB_ADCHS_AnalogInputTriggerSourceSelect ( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN8, ADCHS_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE ); // Select edge trigger PLIB_ADCHS_AnalogInputEdgeTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN8 ); // Enable the digital comparator PLIB_ADCHS_DigitalComparatorEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_1); // Enable ADC PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); // Check VREF to be ready While(!PLIB_ADCHS_VREFIsReady(MY_ADCHS_INSTANCE)); // Check for VREF Fault While(PLIB_ADCHS_VREFFaultHasOccurred(MY_ADCHS_INSTANCE)); // Enable analog circuit for channel-7 PLIB_ADCHS_ChannelAnalogFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7 ); // Wait for the channel-7 to be ready while(!PLIB_ADCHS_ChannelIsReady ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7 ) ); // Enable digital circuit for channels 7 PLIB_ADCHS_ChannelDigitalFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7 ); while(1) { // Enable global software trigger Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 96 PLIB_ADCHS_GlobalSoftwareTriggerEnable( MY_ADCHS_INSTANCE ); // Wait for conversion complete for AN8 while(!PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN8)); result = PLIB_ADCHS_AnalogInputResultGet( MY_ADCHS_INSTANCE, ADCHS_AN8 ); // Note: It is not necessary to read the conversion result for digital comparator // to work // See if we have comparator event if(PLIB_ADCHS_DigitalComparatorEventHasOccurred( MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_1 )) { eventFlag = true; } } return(1); } Example - CVD Mode The CVD mode is used to detect a touch event by measuring the voltage across external capacitor using the capacitive voltage divider method. The Digital Comparator used in conjunction with CVD mode automatically compares the voltage with set limits. Once the voltage is beyond the set limit, a comparator event is generated. In the following example, AN40 is used as an analog input. Physically, the AN40 pin should be connected to a touch sense pad. Once a touch is detected, a comparator event will be generated. { int result; // storage for result // Configure the ADC PLIB_ADCHS_Setup ( MY_ADCHS_INSTANCE, ADCHS_VREF_AVDD_AVSS, // AVDD and AVSS as reference ADCHS_CHARGEPUMP_DISABLE, // No charge pump ADCHS_OUTPUT_DATA_FORMAT_FRACTIONAL, // Use fractional format true, // Do stop in idle ADCHS_FAST_SYNC_SYSTEM_CLOCK_ENABLE, // Enable Fast synchronous system clock ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_DISABLE, // Disable Fast synchronous peripheral clock ADCHS_INTERRUPT_BIT_SHIFT_LEFT_0_BITS, // vector shift unused, interrupt not used 0, // vector base address unused, interrupt not used ADCHS_CLOCK_SOURCE_SYSCLK, // SYSCLK is the clock source 1, // TQ = 1/SYSCLK * 2 ADCHS_WARMUP_CLOCK_32 // Warm-up time = 32 clocks ); // Configure the ADC SAR Channel-7 PLIB_ADCHS_ChannelSetup ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7, // Channel - 7 ADCHS_DATA_RESOLUTION_12BIT, // resolution is set to 12bits 1, // clock divider bit is, TAD7 = 2 * TQ 1, // Sample time is 3 * TAD7 ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 // 1 clock early interrupt (ignored, interrupt not used) ); // Select analog channels as bipolar and single ended // Since CVD measures difference in voltages, the setting should be bipolar PLIB_ADCHS_AnalogInputModeSelect ( MY_ADCHS_INSTANCE, ADCHS_AN40, ADCHS_INPUT_MODE_SINGLE_ENDED_BIPOLAR ); // Select AN40 for scanning, as CVD needs scanning to be enabled PLIB_ADCHS_AnalogInputScanSetup ( MY_ADCHS_INSTANCE, ADCHS_AN40, ADCHS_SCAN_TRIGGER_SENSITIVE_EDGE, ADCHS_SCAN_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE ); PLIB_ADCHS_CVDSetup ( MY_ADCHS_INSTANCE, Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 97 ADCHS_CVD_CAPACITOR_5PF, false, // no test for between low and high true, // Once touch event occurs, CVD output will // be higher than the set limits false, // no test for less than high false, // no test for greater than equal to low false, // no test for less than low ADCHS_AN40, // select AN40 0xFFF - (0xFFF/5), // high limit, 80% of full scale (0xFFF/5) // low limit, 20% of full scale ); // Enable the digital comparator-1, since SVD works with comparator-1 PLIB_ADCHS_DigitalComparatorEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_1); // Enable CVD mode PLIB_ADCHS_CVDEnable(MY_ADCHS_INSTANCE); // Enable ADC PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); // Check VREF to be ready While(!PLIB_ADCHS_VREFIsReady(MY_ADCHS_INSTANCE)); // Check for VREF Fault While(PLIB_ADCHS_VREFFaultHasOccurred(MY_ADCHS_INSTANCE)); // Enable analog circuit for channel-7 PLIB_ADCHS_ChannelAnalogFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7 ); // Wait for the channel-7 to be ready while(!PLIB_ADCHS_ChannelIsReady ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7 ) ); // Enable digital circuit for channels 7 PLIB_ADCHS_ChannelDigitalFeatureEnable ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_7 ); while(1) { // Enable global software trigger PLIB_ADCHS_GlobalSoftwareTriggerEnable( MY_ADCHS_INSTANCE ); // Wait, if there is no touch event sensed by CVD + comparator while(!PLIB_ADCHS_DigitalComparatorEventHasOccurred ( MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_1 ) ); // Verify of the CVD selected input is AN40 // This is not required, but provided as an example if(ADCHS_AN40 == PLIB_ADCHS_DigitalComparatorAnalogInputGet( MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_1 )) { result == PLIB_ADCHS_CVDResultGet( MY_ADCHS_INSTANCE ); } } return(1); } Other Functionality This topic provides information on additional functionality. Description The ADCHS also implements the following additional functionalities: Peripheral Libraries Help ADCHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 98 • Digital Filter • Digital Comparator • Capacitive Voltage Divider (CVD) mode • Turbo mode • FIFO and DMA Interface for dedicated cores Digital Filter The Digital Filter consists of an accumulator and a decimator (downsampler), which function together as a low-pass filter. By sampling an analog input at a higher-than-required sample rate (oversampling), and then processing the data through the oversampling digital filter, the number of usable bits of the ADC channel can be increased at the expense of decreased conversion throughput. For example, using 4x oversampling yields one extra usable bit, 16x oversampling yields two extra usable bits, 64x oversampling provides three extra usable bits, and 256x oversampling provides four extra usable bits. Once configured, the application provides a single trigger to the analog input specified for oversampling, and then fetches the result when the process is complete. Digital Comparator The ADCHS module features multiple Digital Comparators that can be used to monitor selected analog input conversion results and generate an interrupt when a conversion result matches the user-specified limits. Conversion triggers are still required to initiate conversions. The comparison occurs automatically once the conversion is complete. When using a hardware source as a periodic trigger, it is possible to monitor analog inputs and create an interrupt when the converted level matches specified criteria without any software overhead. CVD Mode The CVD mode allows the ADCHS module to detect a touch event by measuring the voltage difference of internal and external capacitors by alternately connecting it to VDD and GND. The CVD mode works in conjunction with the Digital Comparator and can generate an event (interrupt) once the voltage difference is more than the set value (indicating a touch event). Turbo Mode The Turbo mode allows two Class 1 analog inputs to work in an interleaved manner to generate converted data at almost double the maximum throughput of a single Class 1 analog input. FIFO and DMA Interfaces for Channels 0 through 6 The FIFO and DMA interfaces are applicable only for Channel 0 through 6. Using the FIFO, Channel 0 through 6 can save converted data into a FIFO. Using the DMA interface, Channel 0 through 6 can save the converted data directly into RAM. Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB X IDE. Library Interface a) Configuration Functions Name Description PLIB_ADCHS_Disable High-Speed SAR ADC module is disabled (turned OFF). PLIB_ADCHS_Enable Enables the High-Speed SAR ADC module. PLIB_ADCHS_Setup Configures the High-Speed SAR ADC converter. PLIB_ADCHS_ControlRegistersCanBeUpdated Returns the status of update-ready. PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptDisable Disables the update-ready interrupt. PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptEnable Enables the update-ready interrupt. PLIB_ADCHS_ExternalConversionRequestDisable Disables the external conversion request. PLIB_ADCHS_ExternalConversionRequestEnable Enables the external conversion request. PLIB_ADCHS_GlobalLevelSoftwareTriggerDisable Disables the global level software trigger. PLIB_ADCHS_GlobalLevelSoftwareTriggerEnable Initiates a global level software trigger. PLIB_ADCHS_GlobalSoftwareTriggerEnable Initiate a Global Software Trigger. PLIB_ADCHS_ScanCompleteInterruptDisable Disables the end of scan interrupt. PLIB_ADCHS_ScanCompleteInterruptEnable Enables the end of scan interrupt. PLIB_ADCHS_SoftwareConversionInputSelect Selects the analog input of Channel 7 for manual conversion. PLIB_ADCHS_SoftwareConversionStart Triggers the conversion of analog input signal connected to Channel 7. PLIB_ADCHS_SoftwareSamplingStart Enables sampling of analog input for Channel 7. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 99 PLIB_ADCHS_SoftwareSamplingStop Disables sampling of analog input for Channel 7, which places Channel 7 into Hold mode. PLIB_ADCHS_TriggerSuspendDisable Disables trigger suspend. PLIB_ADCHS_TriggerSuspendEnable Suspends all trigger for all ADCHS channels. b) CVD Functions Name Description PLIB_ADCHS_CVDDisable Disables the CVD feature. PLIB_ADCHS_CVDEnable Enables the CVD feature. PLIB_ADCHS_CVDResultGet Returns a CVD result measured by an ADCHS instance. PLIB_ADCHS_CVDSetup Configures the CVD related setting of ADCHS channel. c) Analog Input Functions Name Description PLIB_ADCHS_AnalogInputDataIsReady Returns the data ready status of analog inputs. PLIB_ADCHS_AnalogInputDataReadyInterruptDisable Disables the data ready interrupt for the selected analog inputs. PLIB_ADCHS_AnalogInputDataReadyInterruptEnable Enables the data ready interrupt for the selected analog input. PLIB_ADCHS_AnalogInputEarlyInterruptDisable Disables the early interrupt for the analog input. PLIB_ADCHS_AnalogInputEarlyInterruptEnable Enables the early interrupt for the analog input. PLIB_ADCHS_AnalogInputEarlyInterruptIsReady Returns the early interrupt ready status of analog input. PLIB_ADCHS_AnalogInputIsAvailable Returns the analog input configuration of ADCHS channel. PLIB_ADCHS_AnalogInputModeGet Returns the mode for the specified analog input. PLIB_ADCHS_AnalogInputResultGet Returns a ADC conversion result. PLIB_ADCHS_AnalogInputScanIsComplete Returns the state of End of scan completion. PLIB_ADCHS_AnalogInputScanIsSelected Returns whether or note an analog input is selected for scanning. PLIB_ADCHS_AnalogInputScanRemove Removes the analog input from scanning selection. d) Analog Input Selection Functions Name Description PLIB_ADCHS_AnalogInputModeSelect Selects the mode for the specified analog input. PLIB_ADCHS_AnalogInputScanSelect Selects the analog input for scanning. PLIB_ADCHS_ChannelTriggerSampleSelect Selects the trigger and sampling modes for channels of High-Speed SAR ADC PLIB_ADCHS_AnalogInputEdgeTriggerSet Sets the trigger as edge sensitive for selected class 1 and 2 analog input. PLIB_ADCHS_AnalogInputLevelTriggerSet Sets the trigger as level sensitive for selected Class 1 and 2 analog input. PLIB_ADCHS_AnalogInputScanSetup Selects input to include in Analog Input Scan mode. PLIB_ADCHS_AnalogInputTriggerSourceSelect Selects a trigger Source for analog input (Class 1 or Class 2 analog inputs only). e) Digital Comparator Functions Name Description PLIB_ADCHS_DigitalComparatorAnalogInputGet Returns the analog input ID used by the digital comparator. PLIB_ADCHS_DigitalComparatorAnalogInputSelect Selects analog inputs, whose converted data will be processed by the comparator. PLIB_ADCHS_DigitalComparatorDisable Disables the specified digital comparator. PLIB_ADCHS_DigitalComparatorEnable Enables the specified digital comparator. PLIB_ADCHS_DigitalComparatorEventHasOccurred Returns the status of the selected digital comparator. PLIB_ADCHS_DigitalComparatorInterruptDisable Disables the interrupt for the selected digital comparator. PLIB_ADCHS_DigitalComparatorInterruptEnable Enables the interrupt for the selected digital comparator. PLIB_ADCHS_DigitalComparatorLimitSet Sets the limit for the specified digital comparator. PLIB_ADCHS_DigitalComparatorSetup Configures the Digital Comparator on the High-Speed SAR ADC converter. f) Digital Filter Functions Name Description PLIB_ADCHS_DigitalFilterAveragingModeSampleCountSelect Selects the number of samples which are averaged by the Digital Filter. PLIB_ADCHS_DigitalFilterAveragingModeSetup Configures the Digital Filter on the High-Speed SAR ADC converter in Averaging mode. PLIB_ADCHS_DigitalFilterDataGet Used to fetch the data result from the Digital Filter. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 100 PLIB_ADCHS_DigitalFilterDataIsReady Used to determine if the Digital Filter has data ready. PLIB_ADCHS_DigitalFilterDataReadyInterruptDisable Disables the interrupt for the selected Digital Filter. PLIB_ADCHS_DigitalFilterDataReadyInterruptEnable Enables the interrupt for the selected Digital Filter. PLIB_ADCHS_DigitalFilterDisable Disables the Digital Filter. PLIB_ADCHS_DigitalFilterEnable Enables the Digital Filter. PLIB_ADCHS_DigitalFilterOversamplingModeRatioSelect Selects the oversampling ratio for the Digital Filter. PLIB_ADCHS_DigitalFilterOversamplingModeSetup Configures the Digital Filter on the High-Speed SAR ADC converter in Oversampling mode. g) DMA Functions Name Description PLIB_ADCHS_DMABuffer_A_InterruptDisable Disables the DMA Buffer A full interrupt for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_A_InterruptEnable Enables the DMA Buffer A full interrupt for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_A_IsFull Used to determine if the DMA Buffer A is full, for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_B_InterruptDisable Disables the DMA Buffer B full interrupt for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_B_InterruptEnable Enables the DMA Buffer B full interrupt for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_B_IsFull Used to determine if the DMA Buffer B is full, for the specified Channel 0 to 6. PLIB_ADCHS_DMADisable Disables the DMA in the High-Speed SAR ADC module. PLIB_ADCHS_DMAEnable Enables the DMA in the High-Speed SAR ADC module. PLIB_ADCHS_DMAOverflowErrorHasOccurred Used to determine if the DMA Buff had an overflow error. PLIB_ADCHS_DMASetup Configures the DMA on the High-Speed SAR ADC. PLIB_ADCHS_DMASourceRemove Disables the DMA for the specified Channel 0 to 6. PLIB_ADCHS_DMASourceSelect Enables the DMA for the specified Channel 0 to 6. h) Channel Related Functions Name Description PLIB_ADCHS_ChannelAnalogFeatureDisable Disables the analog circuit for channels of High-Speed SAR ADC. PLIB_ADCHS_ChannelAnalogFeatureEnable Enables the analog circuit for High-Speed SAR ADC channels. PLIB_ADCHS_ChannelConfigurationGet Used to get the configuration for the specified channel. PLIB_ADCHS_ChannelConfigurationSet Used to set the configuration for the specified channel. PLIB_ADCHS_ChannelDigitalFeatureDisable Disables the digital circuit for channels of High-Speed SAR ADC. PLIB_ADCHS_ChannelDigitalFeatureEnable Enables (turns ON) the digital circuit for channels. PLIB_ADCHS_ChannelIsReady Returns the state of the channel. PLIB_ADCHS_ChannelIsReadyInterruptDisable Disables the Channel ready interrupt for the specified channel. PLIB_ADCHS_ChannelIsReadyInterruptEnable Enables the Channel ready interrupt for the specified channel. PLIB_ADCHS_ChannelSetup Configures the High-Speed SAR ADC channels. PLIB_ADCHS_ChannelInputSelect Selects the analog input for Channel 0 to 6. i) FIFO Functions Name Description PLIB_ADCHS_FIFODataCountGet Returns the number of data to be read from FIFO. PLIB_ADCHS_FIFODataIsAvailable Used to determine if the FIFO has data ready. PLIB_ADCHS_FIFODataIsNegative Returns the sign of data stored in FIFO. PLIB_ADCHS_FIFODataReadyInterruptDisable Disables the interrupt for FIFO. PLIB_ADCHS_FIFODataReadyInterruptEnable Enables the interrupt for FIFO. PLIB_ADCHS_FIFODisable Disables the FIFO in the High-Speed SAR ADC. PLIB_ADCHS_FIFOEnable Enables the FIFO in the High-Speed SAR ADC PLIB_ADCHS_FIFOErrorHasOccurred Used to determine if the FIFO has encountered an overflow error. PLIB_ADCHS_FIFORead Used to fetch the data result from the FIFO. PLIB_ADCHS_FIFOSourceGet Returns the channel ID using the FIFO. PLIB_ADCHS_FIFOSourceSelect Sets the Channel 0 to 6 using the FIFO. j) Interrupt Functions Name Description PLIB_ADCHS_EarlyInterruptDisable Disables the early interrupt for the ADCHS. PLIB_ADCHS_EarlyInterruptEnable Enables the early interrupt for the ADCHS. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 101 k) Turbo Mode Functions Name Description PLIB_ADCHS_TurboModeChannelSelect Configures the channels for Turbo mode. PLIB_ADCHS_TurboModeDisable Disables Turbo mode for High-Speed SAR ADC module. PLIB_ADCHS_TurboModeEnable Enables Turbo mode for the High-Speed SAR ADC module. PLIB_ADCHS_TurboModeErrorHasOccurred Returns the error state of Turbo mode. l) Voltage Reference Functions Name Description PLIB_ADCHS_VREFFaultHasOccurred Returns the state of VREF fault. PLIB_ADCHS_VREFFaultInterruptDisable Disables the VREF Fault interrupt. PLIB_ADCHS_VREFFaultInterruptEnable Enables the VREF fault interrupt. PLIB_ADCHS_VREFIsReady Returns the state of VREF. PLIB_ADCHS_VREFReadyInterruptDisable Disables the VREF ready interrupt. PLIB_ADCHS_VREFReadyInterruptEnable Enables the VREF ready interrupt. m) Feature Existence Functions Name Description PLIB_ADCHS_ExistsAnalogInputCheck Identifies whether the System Configuration feature exists on the ADCHS module. PLIB_ADCHS_ExistsAnalogInputModeControl Identifies whether the analog input mode control exists on the ADCHS module. PLIB_ADCHS_ExistsAnalogInputScan Identifies whether the Analog input Scan exists on the ADCHS module. PLIB_ADCHS_ExistsChannelAnalogControl Identifies whether the Channel Analog control exists on the ADCHS module. PLIB_ADCHS_ExistsChannelConfiguration Identifies whether the Channel Configuration feature exists on the ADCHS module. PLIB_ADCHS_ExistsChannelDigitalControl Identifies whether the Channel Digital control exists on the ADCHS module. PLIB_ADCHS_ExistsChannelInputSelectControl Identifies whether the Channel 0 to 6 Input select feature exists on the ADCHS module. PLIB_ADCHS_ExistsConfiguration Identifies whether the Configuration feature exists on the ADCHS module. PLIB_ADCHS_ExistsConversionResults Identifies whether the Conversion Results feature exists on the ADCHS module. PLIB_ADCHS_ExistsCVD Identifies whether the CVD exists on the ADCHS module. PLIB_ADCHS_ExistsDigitalComparator Identifies whether the Digital Comparator feature exists on the ADCHS module . PLIB_ADCHS_ExistsDigitalFilter Identifies whether the Digital Filter feature exists on the ADCHS module. PLIB_ADCHS_ExistsDMA Identifies whether the DMA exists on the ADCHS module. PLIB_ADCHS_ExistsEarlyInterruptControl Identifies whether the Early Interrupt control exists on the ADCHS module. PLIB_ADCHS_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADCHS module PLIB_ADCHS_ExistsExternalConversionRequestControl Identifies whether the External Convert feature exists on the ADCHS module. PLIB_ADCHS_ExistsFIFO Identifies whether the FIFO exists on the ADCHS module. PLIB_ADCHS_ExistsManualControl Identifies whether the Manual control exists on the ADCHS module. PLIB_ADCHS_ExistsTriggerControl Identifies whether the Trigger control exists on the ADCHS module. PLIB_ADCHS_ExistsTriggerSampleControl Identifies whether the Trigger Sample control feature exists on the ADCHS module. PLIB_ADCHS_ExistsTurboMode Identifies whether the Turbo mode feature exists on the ADCHS module. PLIB_ADCHS_ExistsUpdateReadyControl Identifies whether the Update Ready feature exists on the ADCHS module. PLIB_ADCHS_ExistsVREFControl Identifies whether the VREF control exists on the ADCHS module. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 102 n) Data Types and Constants Name Description ADCHS_AN_INPUT_ID Type for identifying the available ADC Inputs ADCHS_CHARGEPUMP_MODE Defines the selection for the charge pump. ADCHS_CLOCK_SOURCE Defines the ADCHS Clock Source Select. ADCHS_CVD_CAPACITOR Defines the value of the internal capacitor during CVD mode. ADCHS_DATA_RESOLUTION Identifies the resolution of the ADC output. ADCHS_DIGITAL_COMPARATOR_ID Identifies the supported Digital Comparators. ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT Identifies the Digital Filter averaging sample count. ADCHS_DIGITAL_FILTER_ID Identifies the supported Digital Filters. ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO Identifies the supported Digital Filter oversampling ratios. ADCHS_DIGITAL_FILTER_SIGNIFICANT_BITS Data length of digital filter. ADCHS_DMA_BUFFER_LENGTH Defines the length of the DMA buffer length. ADCHS_DMA_COUNT Defines the enable/disable of the count feature for DMA. ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK Defines the number of clocks prior to the arrival of valid data that the associated interrupt is generated. ADCHS_FAST_SYNC_PERIPHERAL_CLOCK Defines the selection of the fast synchronous peripheral clock. ADCHS_FAST_SYNC_SYSTEM_CLOCK Defines the selection of the fast synchronous system clock. ADCHS_INPUT_MODE Defines the available modes for the selected input. ADCHS_INTERRUPT_BIT_SHIFT_LEFT Identifies the bits shift for calculating the interrupt vector. ADCHS_OUTPUT_DATA_FORMAT Defines the selection for the output data format. ADCHS_SCAN_TRIGGER_SENSITIVE Trigger level for scan trigger. ADCHS_SCAN_TRIGGER_SOURCE Defines the ADCHS Channel Scan Trigger Source Selections. ADCHS_TRIGGER_SOURCE Defines the ADCHS Trigger Source Selections. ADCHS_VREF_SOURCE Defines the ADCHS VREF Source Select. ADCHS_WARMUP_CLOCK Identifies the number of clocks before the channel can be ready ADCHS_MODULE_ID Identifies the number of ADC supported. ADCHS_CHANNEL_INP_SEL Defines the alternate input selection for channels 0 to 6. ADCHS_CHANNEL_ID Identifies the ADC channel from 0 to 7. ADCHS_CHANNEL_TRIGGER_SAMPLING_SEL Defines the selection of trigger and sampling for channels 0 to 6. ADCHS_CLASS12_AN_INPUT_ID Type for identifying the available Class 1 and 2 analog Inputs. Description This section describes the Application Programming Interface (API) functions of the ADCHS Peripheral Library. Refer to each section for a detailed description. a) Configuration Functions PLIB_ADCHS_Disable Function High-Speed SAR ADC module is disabled (turned OFF). File plib_adchs.h C void PLIB_ADCHS_Disable(ADCHS_MODULE_ID index); Returns None. Description This function disables (turns OFF) the selected High-Speed SAR ADC module. Remarks Not all functionality is available on all devices. Please refer to the specific device data sheet for the list of available features. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 103 Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. PLIB_ADCHS_Disable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_Disable( ADCHS_MODULE_ID index ) PLIB_ADCHS_Enable Function Enables the High-Speed SAR ADC module. File plib_adchs.h C void PLIB_ADCHS_Enable(ADCHS_MODULE_ID index); Returns None. Description This function enables (turns ON) the selected High-Speed SAR ADC module. There are many ADCHS functionalities which should be set/ selected before the ADCHS module is turned ON. Once the ADCHS is turned ON, the application code should check if the VREF is ready and without any fault. Subsequently, the analog bias circuitry for the required channel should be enabled followed by enabling the digital section. Remarks None. Preconditions All channels and analog input related selections should be made before enabling the ADCHS module. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_Enable( ADCHS_MODULE_ID index ) PLIB_ADCHS_Setup Function Configures the High-Speed SAR ADC converter. File plib_adchs.h C void PLIB_ADCHS_Setup(ADCHS_MODULE_ID index, ADCHS_VREF_SOURCE voltageRefSelect, ADCHS_CHARGEPUMP_MODE chargePump, ADCHS_OUTPUT_DATA_FORMAT outputFormat, bool stopInIdle, ADCHS_FAST_SYNC_SYSTEM_CLOCK sysClk, Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 104 ADCHS_FAST_SYNC_PERIPHERAL_CLOCK periClk, ADCHS_INTERRUPT_BIT_SHIFT_LEFT intVectorShift, uint16_t intVectorBase, ADCHS_CLOCK_SOURCE adcClockSource, int8_t adcClockDivider, ADCHS_WARMUP_CLOCK warmUpClock); Returns None. Description Configures all ADC parameters which are common to all ADC channels (from 0 to 7). This configuration must occur prior to enabling the ADC and therefore must be called when the ADC is disabled. Remarks This function must be called when the ADC is disabled. Preconditions The ADCHS module is disabled when calling this function. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the ADC PLIB_ADCHS_Setup ( MY_ADCHS_INSTANCE, ADCHS_VREF_AVDD_AVSS, // AVDD and AVSS as reference ADCHS_CHARGEPUMP_DISABLE, // Charge pump is disabled ADCHS_OUTPUT_DATA_FORMAT_FRACTIONAL, // Use fractional format true, // Stop in idle ADCHS_FAST_SYNC_SYSTEM_CLOCK_ENABLE, // Enable Fast synchronous system clock ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_DISABLE, // Disable Fast synchronous peripheral clock ADCHS_INTERRUPT_BIT_SHIFT_LEFT_2_BITS, // vector left shift set to 2 0x1600, // vector base address set to 0x1600 ADCHS_CLOCK_SOURCE_SYSCLK, // SYSCLK is the clock source 1, // Control clock, TQ = 1/SYSCLK * 2 ADCHS_WARMUP_CLOCK_32 // Warm-up up time = 32 clocks ); // Enable the ADC PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. voltageRefSelect VREF Source Selection. chargePump Enables/ disables the charge pump. This variable is of ADCHS_CHARGEPUMP_MODE type. Use when VREFH VREFL < .64 (AVDD - AVSS). This feature is not available on all devices. outputFormat Sets output data format to be integer or fractional. This parameter is of ADCHS_OUTPUT_DATA_FORMAT type. stopInIdle Sets ADC to stop when device is in Idle mode if true sysClk Sets the Fast synchronous system clock to ADC control clock. This variable is of type ADCHS_FAST_SYNC_SYSTEM_CLOCK. periClk Sets the Fast synchronous peripheral clock to ADC control clock. This variable is of type ADCHS_FAST_SYNC_PERIPHERAL_CLOCK. intVectorShift Sets the interrupt vector shift left shift. This variable is of ADCHS_INTERRUPT_BIT_SHIFT_LEFT type. intVectorBase Sets the interrupt vector base address. adcClockSource Clock source selection. This variable is of type ADCHS_CLOCK_SOURCE. adcClockDivider Clock source divider. Values range from 0 to 63. This divider determines the input clock frequency which goes as input to all ADC channels (all ADC channels, 0 to 7). This clock is also known as the "control clock" of ADC. The frequency of control clock for ADC, as per the following equation Control clock frequency = (frequency of "adcClockSource")/(adcClockDivider * 2) For adcClockDivider = 0, control clock frequency is same as frequency of "adcClockSource". Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 105 warmUpClock This parameter determines the number of channel clock (not control clock) which is required as warm up time for the ADC channel, once the analog feature of that ADC channel is enabled. The variable is of type ADCHS_WARMUP_CLOCK. Function void PLIB_ADCHS_Setup ( ADCHS_MODULE_ID index, ADCHS_VREF_SOURCE voltageRefSelect, // voltage reference ADCHS_CHARGEPUMP_MODE chargePump, // Charge pump enabled/disabled ADCHS_OUTPUT_DATA_FORMAT outputFormat, // result format fractional bool stopInIdle, // stop in idle ADCHS_FAST_SYNC_SYSTEM_CLOCK sysClk, // Fast synchronous system clock // to ADC control clock ADCHS_FAST_SYNC_PERIPHERAL_CLOCK periClk, // Fast synchronous peripheral // clock to ADC control clock ADCHS_INTERRUPT_BIT_SHIFT_LEFT intVectorShift, // Interrupt vector shift bits uint16_t intVectorBase, // Interrupt vector base address ADCHS_CLOCK_SOURCE adcClockSource, // clock source int8_t adcClockDivider, // clock divider ADCHS_WARMUP_CLOCK warmUpClock // Analog channel warm-up clocks. ) PLIB_ADCHS_ControlRegistersCanBeUpdated Function Returns the status of update-ready. File plib_adchs.h C bool PLIB_ADCHS_ControlRegistersCanBeUpdated(ADCHS_MODULE_ID index); Returns • true - The ADCHS module can be safely updated (settings can be configured) • false - The ADCHS module is not yet ready to be safely updated Description Once the triggers are suspended, the ADCHS raises an update-ready flag indicating that the updates to ADCHS registers can be performed. This function returns the status of update ready. Remarks None. Preconditions None. Example // Suspend trigger PLIB_ADCHS_TriggerSuspendEnable(MY_ADCHS_INSTANCE); // Wait until the channel registers can be updated while(!PLIB_ADCHS_ControlRegistersCanBeUpdated(MY_ADCHS_INSTANCE)); // Once the function returns true, update the configurations of ADCHS //.... // Enable triggers PLIB_ADCHS_TriggerSuspendDisable(MY_ADCHS_INSTANCE); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 106 Parameters Parameters Description index Identifier for the ADCHS instance. Function bool PLIB_ADCHS_ControlRegistersCanBeUpdated( ADCHS_MODULE_ID index ) PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptDisable Function Disables the update-ready interrupt. File plib_adchs.h C void PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptDisable(ADCHS_MODULE_ID index); Returns None. Description This function disables the update-ready interrupt. Remarks None. Preconditions None. Example PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptDisable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptEnable Function Enables the update-ready interrupt. File plib_adchs.h C void PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptEnable(ADCHS_MODULE_ID index); Returns None. Description Once the triggers are suspended, the ADC channel raises an update ready flag indicating that the updates to ADCHS registers can be performed. This function enables the interrupt which occurs once the flag is raised. Remarks None. Preconditions None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 107 Example PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptEnable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExternalConversionRequestDisable Function Disables the external conversion request. File plib_adchs.h C void PLIB_ADCHS_ExternalConversionRequestDisable(ADCHS_MODULE_ID index); Returns None. Description This function disables (turns OFF) the external conversion request. Once disabled, the external sources such as PTG cannot request a conversion. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable external conversion request PLIB_ADCHS_ExternalConversionRequestDisable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_ExternalConversionRequestDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExternalConversionRequestEnable Function Enables the external conversion request. File plib_adchs.h C void PLIB_ADCHS_ExternalConversionRequestEnable(ADCHS_MODULE_ID index); Returns None. Description This function enables (turns ON) the external conversion request. Once enabled, the ADCHS can accept conversion request from external sources Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 108 such as the PTG module. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable external conversion request PLIB_ADCHS_ExternalConversionRequestEnable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_ExternalConversionRequestEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_GlobalLevelSoftwareTriggerDisable Function Disables the global level software trigger. File plib_adchs.h C void PLIB_ADCHS_GlobalLevelSoftwareTriggerDisable(ADCHS_MODULE_ID index); Returns None. Description This function disables the global level software trigger on the specified channel. Remarks None. Preconditions None. Example PLIB_ADCHS_GlobalLevelSoftwareTriggerDisable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_GlobalLevelSoftwareTriggerDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_GlobalLevelSoftwareTriggerEnable Function Initiates a global level software trigger. File plib_adchs.h Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 109 C void PLIB_ADCHS_GlobalLevelSoftwareTriggerEnable(ADCHS_MODULE_ID index); Returns None. Description This function initiates a global level software trigger. All inputs or the scan list configured to trigger on the global level software trigger are triggered. Once initiated, the trigger continues until the global level trigger is disabled using the function PLIB_ADCHS_GlobalLevelSoftwareTriggerDisable. Remarks None. Preconditions None. Example PLIB_ADCHS_GlobalLevelSoftwareTriggerEnable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_GlobalLevelSoftwareTriggerEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_GlobalSoftwareTriggerEnable Function Initiate a Global Software Trigger. File plib_adchs.h C void PLIB_ADCHS_GlobalSoftwareTriggerEnable(ADCHS_MODULE_ID index); Returns None. Description All inputs or scan list that is configured to trigger on the global software trigger are triggered. Once enabled, the trigger automatically gets disabled (edge sensitive). Remarks None. Preconditions None. Example PLIB_ADCHS_GlobalSoftwareTriggerEnable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_GlobalSoftwareTriggerEnable( ADCHS_MODULE_ID index ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 110 PLIB_ADCHS_ScanCompleteInterruptDisable Function Disables the end of scan interrupt. File plib_adchs.h C void PLIB_ADCHS_ScanCompleteInterruptDisable(ADCHS_MODULE_ID index); Returns None. Description This function disables (turns OFF) the end of scan interrupt. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable EOS interrupt PLIB_ADCHS_ScanCompleteInterruptDisable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_ScanCompleteInterruptDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_ScanCompleteInterruptEnable Function Enables the end of scan interrupt. File plib_adchs.h C void PLIB_ADCHS_ScanCompleteInterruptEnable(ADCHS_MODULE_ID index); Returns None. Description This function enables (turns ON) the end of scan interrupt. The interrupt is generated when scanning of all of the selected analog inputs has completed. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 111 // application developer. // Enable EOS interrupt PLIB_ADCHS_ScanCompleteInterruptEnable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_ScanCompleteInterruptEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_SoftwareConversionInputSelect Function Selects the analog input of Channel 7 for manual conversion. File plib_adchs.h C void PLIB_ADCHS_SoftwareConversionInputSelect(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID anInput); Returns None. Description This function selects the analog input for Channel 7, which is used for manual conversion (using software control). Remarks None. Preconditions None. Example // Select AN24 for manual conversion PLIB_ADCHS_SoftwareConversionInputSelect(MY_ADCHS_INSTANCE, ADCHS_AN24); // Place S&H into Sampling mode PLIB_ADCHS_SoftwareSamplingStart(MY_ADCHS_INSTANCE); // Wait for the required sampling time int del; for(del = 0; del<=20; del++); // Now, make the S&H into Hold mode PLIB_ADCHS_SoftwareSamplingStop(MY_ADCHS_INSTANCE); // Now, start conversion PLIB_ADCHS_SoftwareConversionStart(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. anInput Analog input of type ADCHS_AN_INPUT_ID. Function void PLIB_ADCHS_SoftwareConversionInputSelect ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID anInput ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 112 PLIB_ADCHS_SoftwareConversionStart Function Triggers the conversion of analog input signal connected to Channel 7. File plib_adchs.h C void PLIB_ADCHS_SoftwareConversionStart(ADCHS_MODULE_ID index); Returns None. Description After a signal is held on the S&H of Channel 7, the conversion can be triggered manually using software by using this function. Remarks None. Preconditions None. Example PLIB_ADCHS_SoftwareConversionStart(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_SoftwareConversionStart( ADCHS_MODULE_ID index ) PLIB_ADCHS_SoftwareSamplingStart Function Enables sampling of analog input for Channel 7. File plib_adchs.h C void PLIB_ADCHS_SoftwareSamplingStart(ADCHS_MODULE_ID index); Returns None. Description This function can be used if Channel 7 needs to be brought to Sampling mode manually (i.e., through software). Remarks None. Preconditions None. Example PLIB_ADCHS_SoftwareSamplingStart(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 113 Function void PLIB_ADCHS_SoftwareSamplingStart( ADCHS_MODULE_ID index ) PLIB_ADCHS_SoftwareSamplingStop Function Disables sampling of analog input for Channel 7, which places Channel 7 into Hold mode. File plib_adchs.h C void PLIB_ADCHS_SoftwareSamplingStop(ADCHS_MODULE_ID index); Returns None. Description After sampling for a significant time (using the function PLIB_ADCHS_SoftwareSamplingStart), the sampling can be disabled, which will bring the channel to Hold mode. Remarks None. Preconditions None. Example PLIB_ADCHS_SoftwareSamplingStop(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_SoftwareSamplingStop( ADCHS_MODULE_ID index ) PLIB_ADCHS_TriggerSuspendDisable Function Disables trigger suspend. File plib_adchs.h C void PLIB_ADCHS_TriggerSuspendDisable(ADCHS_MODULE_ID index); Returns None. Description By calling this function, all triggers are allowed to reach the channel and triggers are not suspended. Remarks None. Preconditions None. Example PLIB_ADCHS_TriggerSuspendDisable(MY_ADCHS_INSTANCE); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 114 Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_TriggerSuspendDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_TriggerSuspendEnable Function Suspends all trigger for all ADCHS channels. File plib_adchs.h C void PLIB_ADCHS_TriggerSuspendEnable(ADCHS_MODULE_ID index); Returns None. Description This function suspends all triggers for all channels on the ADCHS module. The trigger needs to be suspended so that the channels could be configured without disabling (and subsequently enabling) the channels. Remarks None. Preconditions None. Example PLIB_ADCHS_TriggerSuspendEnable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_TriggerSuspendEnable( ADCHS_MODULE_ID index ) b) CVD Functions PLIB_ADCHS_CVDDisable Function Disables the CVD feature. File plib_adchs.h C void PLIB_ADCHS_CVDDisable(ADCHS_MODULE_ID index); Returns None. Description This function disables the CVD feature of an ADCHS instance. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 115 Remarks None. Preconditions None. Example PLIB_ADCHS_CVDDisable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_CVDDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_CVDEnable Function Enables the CVD feature. File plib_adchs.h C void PLIB_ADCHS_CVDEnable(ADCHS_MODULE_ID index); Returns None. Description ADCHS channel supports the Capacitive Voltage Divider (CVD) mode. This function enables the CVD feature of an ADCHS instance. Remarks None. Preconditions None. Example PLIB_ADCHS_CVDEnable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_CVDEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_CVDResultGet Function Returns a CVD result measured by an ADCHS instance. File plib_adchs.h C int16_t PLIB_ADCHS_CVDResultGet(ADCHS_MODULE_ID index); Returns The conversion result expressed as a signed 16-bit integer. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 116 Description During CVD measurement, the difference between the voltage measured during positive and negative phases is calculated. This function return the difference value. Remarks None. Preconditions CVD must be enabled and a comparator event linked to CVD should have occurred. Example int16_t result; ... // fetch result for CVD result = PLIB_ADCHS_CVDResultGet( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance. Function int16_t PLIB_ADCHS_CVDResultGet( ADCHS_MODULE_ID index ) PLIB_ADCHS_CVDSetup Function Configures the CVD related setting of ADCHS channel. File plib_adchs.h C void PLIB_ADCHS_CVDSetup(ADCHS_MODULE_ID index, ADCHS_CVD_CAPACITOR capSel, bool inBetweenOrEqual, bool greaterEqualHi, bool lessThanHi, bool greaterEqualLo, bool lessThanLo, ADCHS_AN_INPUT_ID inputEnable, int16_t hiLimit, int16_t loLimit); Returns None. Description While selecting the CVD mode, the internal capacitor should be similar in magnitude to the external capacitor being sensed. This function configures the internal capacitance. Additionally, the functions sets the limits for CVD measurement and the condition to detect a touch event. Since, CVD is implemented with digital comparator 0, using the CVD functionality also needs that digital comparator is enabled. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the CVD mode // Creates an event when the reading of AN3 is between 20% to 80% of the // full scale 12-bit output. This will be the touch event. PLIB_ADCHS_CVDSetup( MY_ADCHS_INSTANCE, ADCHS_CVD_CAPACITOR_5PF, false, // no test for between low and high true, // Once touch event occurs, CVD output will // be higher than the set limits false, // no test for less than high Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 117 false, // no test for greater than equal to low false, // no test for less than low ADCHS_AN3, // enable AN3 0x0CCD, // high limit, 80% of full scale 0x0333); // low limit, 20% of full scale Parameters Parameters Description index Identifier for the ADCHS instance. capSel Selection of value of input capacitor of type ADCHS_CVD_CAPACITOR. inBetweenOrEqual Event is generated when result is greater than or equal to loLimit and less than hiLimit. greaterEqualHi Event is generated when result is greater than or equal to hiLimit. lessThanHi Event is generated when result is less than hiLimit. greaterEqualLo Event is generated when result is greater than or equal to loLimit. lessThanLo Event is generated when result is less than loLimit. inputEnable Bit field which determines which analog inputs are tested by this comparator. This parameter is of type ADCHS_AN_INPUT_ID. hiLimit High limit in the same format as the conversion result. loLimit Low limit in the same format as the conversion result. Function void PLIB_ADCHS_CVDSetup ( ADCHS_MODULE_ID index, ADCHS_CVD_CAPACITOR capSel, // Input capacitor bool inBetweenOrEqual, // between low and high bool greaterEqualHi, // greater than equal to high bool lessThanHi, // less than high bool greaterEqualLo, // greater than equal to low bool lessThanLo, // less than low ADCHS_AN_INPUT_ID inputEnable, // input enable bit int16_t hiLimit, // high limit int16_t loLimit // low limit ) c) Analog Input Functions PLIB_ADCHS_AnalogInputDataIsReady Function Returns the data ready status of analog inputs. File plib_adchs.h C bool PLIB_ADCHS_AnalogInputDataIsReady(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns • true - Converted data is ready for selected analog input • false - Conversion is not yet complete and data is not ready Description This function returns if the converted data is ready for the analog input. Remarks None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 118 Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Check if data is ready for AN10 if(PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN10) == true) { // Do further processing } Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function bool PLIB_ADCHS_AnalogInputDataIsReady ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputDataReadyInterruptDisable Function Disables the data ready interrupt for the selected analog inputs. File plib_adchs.h C void PLIB_ADCHS_AnalogInputDataReadyInterruptDisable(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns None. Description This function disables (turns OFF) the data ready interrupt for the selected analog input. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable interrupt for AN10 and AN11 PLIB_ADCHS_AnalogInputDataReadyInterruptDisable(MY_ADCHS_INSTANCE, ADCHS_AN10); PLIB_ADCHS_AnalogInputDataReadyInterruptDisable(MY_ADCHS_INSTANCE, ADCHS_AN11); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 119 Function void PLIB_ADCHS_AnalogInputDataReadyInterruptDisable ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputDataReadyInterruptEnable Function Enables the data ready interrupt for the selected analog input. File plib_adchs.h C void PLIB_ADCHS_AnalogInputDataReadyInterruptEnable(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns None. Description This function enables (turns ON) the data ready interrupt for the selected analog input. The interrupt is generated when the converted data is ready for the selected analog input. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable interrupt for AN10 and AN11 PLIB_ADCHS_AnalogInputDataReadyInterruptEnable(MY_ADCHS_INSTANCE, ADCHS_AN10); PLIB_ADCHS_AnalogInputDataReadyInterruptEnable(MY_ADCHS_INSTANCE, ADCHS_AN11); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function void PLIB_ADCHS_AnalogInputDataReadyInterruptEnable ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputEarlyInterruptDisable Function Disables the early interrupt for the analog input. File plib_adchs.h C void PLIB_ADCHS_AnalogInputEarlyInterruptDisable(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 120 Returns None. Description This function disables (turns OFF) the early interrupt for the selected analog input. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable interrupt for AN10 and AN11 PLIB_ADCHS_AnalogInputEarlyInterruptDisable(MY_ADCHS_INSTANCE, ADCHS_AN10); PLIB_ADCHS_AnalogInputEarlyInterruptDisable(MY_ADCHS_INSTANCE, ADCHS_AN11); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function void PLIB_ADCHS_AnalogInputEarlyInterruptDisable ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputEarlyInterruptEnable Function Enables the early interrupt for the analog input. File plib_adchs.h C void PLIB_ADCHS_AnalogInputEarlyInterruptEnable(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns None. Description This function enables (turns ON) the early interrupt for the selected analog input. The interrupt is generated at a set number of clock prior to conversion complete. The number of clock for early interrupt is set using the "configure" function for a specific channel. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable interrupt for AN10 and AN11 PLIB_ADCHS_AnalogInputEarlyInterruptEnable(MY_ADCHS_INSTANCE, ADCHS_AN10); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 121 PLIB_ADCHS_AnalogInputEarlyInterruptEnable(MY_ADCHS_INSTANCE, ADCHS_AN11); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function void PLIB_ADCHS_AnalogInputEarlyInterruptEnable ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputEarlyInterruptIsReady Function Returns the early interrupt ready status of analog input. File plib_adchs.h C bool PLIB_ADCHS_AnalogInputEarlyInterruptIsReady(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns • true - Early interrupt event is ready • false - Early interrupt event has not occurred Description This function returns the status of early interrupt for the selected analog input. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Check if early interrupt is ready for AN10 if(PLIB_ADCHS_AnalogInputEarlyInterruptIsReady(MY_ADCHS_INSTANCE, ADCHS_AN10)) { // Do further processing } Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function bool PLIB_ADCHS_AnalogInputEarlyInterruptIsReady ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 122 PLIB_ADCHS_AnalogInputIsAvailable Function Returns the analog input configuration of ADCHS channel. File plib_adchs.h C bool PLIB_ADCHS_AnalogInputIsAvailable(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns • true - Selected analog input is available. • false - Selected analog input is not available in the ADCHS channel. Description This function returns the if the selected analog input is available in the ADCHS channel. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Check if AN10 is available in the ADCHS channel if(PLIB_ADCHS_AnalogInputIsAvailable(MY_ADCHS_INSTANCE, ADCHS_AN10)) { // do further processing } Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function bool PLIB_ADCHS_AnalogInputIsAvailable ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputModeGet Function Returns the mode for the specified analog input. File plib_adchs.h C ADCHS_INPUT_MODE PLIB_ADCHS_AnalogInputModeGet(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns Mode of the selected analog input of type ADCHS_INPUT_MODE type. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 123 Description This function returns the mode (single ended or differential) and encoding (unipolar or two's compliment) for the specified analog input. When getting the mode of analog input which is meant to be alternate input for an ADC channel, the default analog input ID should be passed to this function. For example, for CHANNEL_0, the default analog input is AN0 and alternate analog input is AN45. If the mode for AN45 needs to be obtained, the default input ID (i.e., AN0) should be passed. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Declare a variable of type "ADCHS_INPUT_MODE" ADCHS_INPUT_MODE mode; // Get mode for AN10 mode = PLIB_ADCHS_AnalogInputModeGet(MY_ADCHS_INSTANCE, ADCHS_AN10); Parameters Parameters Description index Identifier for the ADCHS instance analogInput An analog input selection of type ADCHS_AN_INPUT_ID Function ADCHS_INPUT_MODE PLIB_ADCHS_AnalogInputModeGet ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputResultGet Function Returns a ADC conversion result. File plib_adchs.h C uint32_t PLIB_ADCHS_AnalogInputResultGet(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns The conversion result expressed as a 32-bit integer. Description This function returns the converted result for the specified analog input. Remarks None. Preconditions A valid conversion is ready to be fetched. Example uint32_t result; //... Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 124 // Check if data is ready for AN10 if(PLIB_ADCHS_AnalogInputDataIsReady(MY_ADCHS_INSTANCE, ADCHS_AN10)) { result = PLIB_ADCHS_AnalogInputResultGet( MY_ADCHS_INSTANCE, ADCHS_AN10 ); } Parameters Parameters Description index Identifier for the ADCHS instance. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function uint32_t PLIB_ADCHS_AnalogInputResultGet ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputScanIsComplete Function Returns the state of End of scan completion. File plib_adchs.h C bool PLIB_ADCHS_AnalogInputScanIsComplete(ADCHS_MODULE_ID index); Returns • true - Analog input scanning is complete for the selected analog inputs • false - Analog input scanning is not complete Description This function returns 'true', if all of the selected Analog Inputs have completed scanning. Remarks None. Preconditions The ADCHS module should have Analog Inputs Scanning mode selected and enabled for scanning to occur. Example bool EOSState = PLIB_ADCHS_AnalogInputScanIsComplete(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance Function bool PLIB_ADCHS_AnalogInputScanIsComplete( ADCHS_MODULE_ID index ) PLIB_ADCHS_AnalogInputScanIsSelected Function Returns whether or note an analog input is selected for scanning. File plib_adchs.h Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 125 C bool PLIB_ADCHS_AnalogInputScanIsSelected(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns • true - Analog input is in selected for scanning • false - Analog input is not selected for scanning Description This function returns whether or not an analog input is included in the scanning queue. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Determine if AN10 is selected for scanning or not if(PLIB_ADCHS_AnalogInputScanIsSelected(MY_ADCHS_INSTANCE, ADCHS_AN10) == true) { // Perform further operations } Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function bool PLIB_ADCHS_AnalogInputScanIsSelected ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputScanRemove Function Removes the analog input from scanning selection. File plib_adchs.h C void PLIB_ADCHS_AnalogInputScanRemove(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns None. Description This function removes the analog input for scanning queue. Therefore, the analog input is no longer used for scanning. Remarks None. Preconditions None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 126 Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Remove AN10 and AN11 from scanning PLIB_ADCHS_AnalogInputScanRemove(MY_ADCHS_INSTANCE, ADCHS_AN10); PLIB_ADCHS_AnalogInputScanRemove(MY_ADCHS_INSTANCE, ADCHS_AN11); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function void PLIB_ADCHS_AnalogInputScanRemove ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) d) Analog Input Selection Functions PLIB_ADCHS_AnalogInputModeSelect Function Selects the mode for the specified analog input. File plib_adchs.h C void PLIB_ADCHS_AnalogInputModeSelect(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput, ADCHS_INPUT_MODE mode); Returns None. Description This function selects the mode (single ended or differential) and encoding (unipolar or two's compliment) for the specified analog input. When selecting the mode of analog input which is meant to be alternate input for an ADC channel, the default analog input ID should be passed to this function. For example, for CHANNEL_0, the default analog input is AN0 and the alternate analog input is AN45. If the mode for AN45 needs to be changed, the default input ID (i.e., AN0) should be passed. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Set AN10 and AN11 to use the single ended, two's complement mode // selection. PLIB_ADCHS_AnalogInputModeSelect(MY_ADCHS_INSTANCE, ADCHS_AN10, ADCHS_INPUT_MODE_SINGLE_ENDED_TWOS_COMP); PLIB_ADCHS_AnalogInputModeSelect(MY_ADCHS_INSTANCE, Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 127 ADCHS_AN11, ADCHS_INPUT_MODE_SINGLE_ENDED_TWOS_COMP); Parameters Parameters Description index Identifier for the ADCHS instance analogInput Analog input ID for which the input mode is to be selected. It is of type ADCHS_AN_INPUT_ID. mode An ADCHS_INPUT_MODE type indicating the mode selection Function void PLIB_ADCHS_AnalogInputModeSelect ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput, ADCHS_INPUT_MODE mode ) PLIB_ADCHS_AnalogInputScanSelect Function Selects the analog input for scanning. File plib_adchs.h C void PLIB_ADCHS_AnalogInputScanSelect(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput); Returns None. Description This function selects the analog input for scanning. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Select for AN10 and AN11 for scanning PLIB_ADCHS_AnalogInputScanSelect(MY_ADCHS_INSTANCE, ADCHS_AN10); PLIB_ADCHS_AnalogInputScanSelect(MY_ADCHS_INSTANCE, ADCHS_AN11); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Function void PLIB_ADCHS_AnalogInputScanSelect ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 128 PLIB_ADCHS_ChannelTriggerSampleSelect Function Selects the trigger and sampling modes for channels of High-Speed SAR ADC File plib_adchs.h C bool PLIB_ADCHS_ChannelTriggerSampleSelect(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID, ADCHS_CHANNEL_TRIGGER_SAMPLING_SEL sampSel); Returns • true - The function successfully selected the sampling and trigger mode • false - The function could not select the sampling and trigger mode because Channel 7 was selected and Channel 7 does not implement this feature Description The channels from 0 through 6 have features to select the trigger as presynchronized or unsynchronized. Also, the sampling can be selected as synchronous. This function provides the functionality to select the trigger and sampling for ADC channels. The valid channels for selecting trigger and sampling is 0 to 6. Channel 7 does not have the feature. Therefore, calling this function for Channel 7 will result in failure. This selection must occur prior to enabling the ADC and therefore must be called when the ADC is disabled. Also, this selection must occur prior to enabling the digital circuit and analog bias circuit for the specified ADC channel. Remarks This function must be called when the ADC is disabled. Preconditions The channel is disabled when calling this function. Example bool status = false; // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the ADC PLIB_ADCHS_ChannelSetup( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1, // channel - 1 ADCHS_DATA_RESOLUTION_12BIT, // resolution is set to 12bits 1, // channel clock divider bit is, TAD = 2 * TQ 1, // Sample time is 3 * TAD ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1); // Interrupt, 1 clock early status = PLIB_ADCHS_ChannelTriggerSampleSelect( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1, // channel - 1 ADCHS_CHANNEL_SYNC_SAMPLING); // Synchronous sampling selected if( false == status) { // error has occurred while(1); } // Enable the ADC PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); // Wait until the reference voltage is ready while(!PLIB_ADCHS_VREFIsReady(MY_ADCHS_INSTANCE)); //Check if there is a fault in reference voltage if(PLIB_ADCHS_VREFFaultHasOccurred(MY_ADCHS_INSTANCE)) { // process fault accordingly while(1); } Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 129 // Enable the analog circuit PLIB_ADCHS_ChannelAnalogFeatureEnable(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1); // Wait until the channel wakes up after warm-up while(!PLIB_ADCHS_ChannelIsReady(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1)); // Enable the digital circuit PLIB_ADCHS_ChannelDigitalFeatureEnable(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1); // ADC will begin conversion now, after a valid trigger Parameters Parameters Description index Identifier for the ADCHS instance. channelID Channel ID from 0 to 6. sampSel Sets the presync trigger or sync sampling options. This variable is of type ADCHS_CHANNEL_TRIGGER_SAMPLING_SEL. Function bool PLIB_ADCHS_ChannelTriggerSampleSelect ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID, ADCHS_CHANNEL_TRIGGER_SAMPLING_SEL sampSel ) PLIB_ADCHS_AnalogInputEdgeTriggerSet Function Sets the trigger as edge sensitive for selected class 1 and 2 analog input. File plib_adchs.h C void PLIB_ADCHS_AnalogInputEdgeTriggerSet(ADCHS_MODULE_ID index, ADCHS_CLASS12_AN_INPUT_ID analogInput); Returns None. Description This function sets the trigger as edge sensitive for selected Class 1 and 2 analog input. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Set for AN10 and AN11 for edge trigger PLIB_ADCHS_AnalogInputEdgeTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN10 ); PLIB_ADCHS_AnalogInputEdgeTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN11 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 130 analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Since the trigger level can be selected only for Class 1 and 2 analog inputs. Function void PLIB_ADCHS_AnalogInputEdgeTriggerSet ( ADCHS_MODULE_ID index, ADCHS_CLASS12_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputLevelTriggerSet Function Sets the trigger as level sensitive for selected Class 1 and 2 analog input. File plib_adchs.h C void PLIB_ADCHS_AnalogInputLevelTriggerSet(ADCHS_MODULE_ID index, ADCHS_CLASS12_AN_INPUT_ID analogInput); Returns None. Description This function sets the trigger as level sensitive for selected Class 1 and 2 analog input. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Set for AN5 and AN6 for level trigger PLIB_ADCHS_AnalogInputLevelTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN5 ); PLIB_ADCHS_AnalogInputLevelTriggerSet( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN6 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. Since the trigger level can be selected only for Class 1 and 2 analog inputs. Function void PLIB_ADCHS_AnalogInputLevelTriggerSet ( ADCHS_MODULE_ID index, ADCHS_CLASS12_AN_INPUT_ID analogInput ) PLIB_ADCHS_AnalogInputScanSetup Function Selects input to include in Analog Input Scan mode. File plib_adchs.h Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 131 C void PLIB_ADCHS_AnalogInputScanSetup(ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput, ADCHS_SCAN_TRIGGER_SENSITIVE trgSensitive, ADCHS_SCAN_TRIGGER_SOURCE triggerSource); Returns None. Description Selects inputs, as determined by the low and high enable scan list for inclusion in the analog input scan sequence. If the input is a Class 1 or Class 2 type, it will also select the trigger source for that input to be the scan trigger, which is required if included in analog input scanning. This function configures the scan functionality with a single ADC input. If more inputs are required to be added for scanning, the PLIB_ADCHS_AnalogInputScanSelect function should be used. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure analog input Scanning // Analog inputs 10 through 13 // Trigger on Timer 1 match. PLIB_ADCHS_AnalogInputScanSetup(MY_ADCHS_INSTANCE, ADCHS_AN10, ADCHS_SCAN_TRIGGER_SENSITIVE_EDGE, // Edge sensitive ADCHS_SCAN_TRIGGER_SOURCE_TMR1_MATCH); PLIB_ADCHS_AnalogInputScanSelect(MY_ADCHS_INSTANCE, ADCHS_AN11); PLIB_ADCHS_AnalogInputScanSelect(MY_ADCHS_INSTANCE, ADCHS_AN12); PLIB_ADCHS_AnalogInputScanSelect(MY_ADCHS_INSTANCE, ADCHS_AN13); Parameters Parameters Description index Identifier for the ADCHS instance. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. trgSensitive Enables level/edge sensitive scan trigger. triggerSource Trigger source used to initiate analog input scan. Function void PLIB_ADCHS_AnalogInputScanSetup ( ADCHS_MODULE_ID index, ADCHS_AN_INPUT_ID analogInput, ADCHS_SCAN_TRIGGER_SENSITIVE trgSensitive, ADCHS_SCAN_TRIGGER_SOURCE triggerSource ) PLIB_ADCHS_AnalogInputTriggerSourceSelect Function Selects a trigger Source for analog input (Class 1 or Class 2 analog inputs only). File plib_adchs.h C void PLIB_ADCHS_AnalogInputTriggerSourceSelect(ADCHS_MODULE_ID index, ADCHS_CLASS12_AN_INPUT_ID inputId, ADCHS_TRIGGER_SOURCE triggerSource); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 132 Returns None. Description This function selects the trigger source for Class 1 or Class 2 inputs. A call to this function is not required when the input is being used as part of an analog input scan, as the input scan configure function also configures all trigger sources. Remarks None. Preconditions The function only applies to Class 1 and Class 2 inputs. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure AN4 for triggering from INT0. PLIB_ADCHS_AnalogInputTriggerSourceSelect( MY_ADCHS_INSTANCE, ADCHS_CLASS12_AN4, ADCHS_TRIGGER_SOURCE_INT0 ); Parameters Parameters Description index Identifier for the ADCHS instance. inputId Class 1 or Class 2 input trigger to be configured. triggerSource Trigger source to use for this input of type ADCHS_TRIGGER_SOURCE. Function void PLIB_ADCHS_AnalogInputTriggerSourceSelect ( ADCHS_MODULE_ID index, ADCHS_CLASS12_AN_INPUT_ID inputId, ADCHS_TRIGGER_SOURCE triggerSource ) e) Digital Comparator Functions PLIB_ADCHS_DigitalComparatorAnalogInputGet Function Returns the analog input ID used by the digital comparator. File plib_adchs.h C ADCHS_AN_INPUT_ID PLIB_ADCHS_DigitalComparatorAnalogInputGet(ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator); Returns An analog input ID of type ADCHS_AN_INPUT_ID. Description This function returns the analog input ID, whose converted data is being compared by the specified digital comparator. In a typical application, when a comparator event is recorded, the application will need to know the analog input which caused the event. This function returns the value of type ADCHS_AN_INPUT_ID, indicating the analog input ID. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 133 Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. ADCHS_AN_INPUT_ID input; // Get analog input tied to digital comparator 2 input = PLIB_ADCHS_DigitalComparatorAnalogInputGet( MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_2 ); Parameters Parameters Description index Identifier for the ADCHS instance. digComparator Digital comparator ID of type ADCHS_DIGITAL_COMPARATOR_ID. Function ADCHS_AN_INPUT_ID PLIB_ADCHS_DigitalComparatorAnalogInputGet ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator ) PLIB_ADCHS_DigitalComparatorAnalogInputSelect Function Selects analog inputs, whose converted data will be processed by the comparator. File plib_adchs.h C void PLIB_ADCHS_DigitalComparatorAnalogInputSelect(ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator, ADCHS_AN_INPUT_ID analogInput); Returns None. Description This function selects the analog input, whose converted data (once available) will be processed by the specified digital comparator. This function should be called only when the comparator is in a disabled state. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Set digital comparator 2 to process the output of AN2 PLIB_ADCHS_DigitalComparatorAnalogInputSelect( MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_2, ADCHS_AN2); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 134 Parameters Parameters Description index Identifier for the ADCHS instance to be configured. digComparator Digital comparator ID of type ADCHS_DIGITAL_COMPARATOR_ID. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. The valid input range for "analogInput" is from ADCHS_AN0 to ADCHS_AN31. Values from ADCHS_AN32 and higher will be ignored. Function void PLIB_ADCHS_DigitalComparatorAnalogInputSelect ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator, ADCHS_AN_INPUT_ID analogInput ) PLIB_ADCHS_DigitalComparatorDisable Function Disables the specified digital comparator. File plib_adchs.h C void PLIB_ADCHS_DigitalComparatorDisable(ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator); Returns None. Description This function disables (turns OFF) the specified digital comparator. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. PLIB_ADCHS_DigitalComparatorDisable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_2); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. digComparator Digital comparator of type ADCHS_DIGITAL_COMPARATOR_ID. Function void PLIB_ADCHS_DigitalComparatorDisable ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator ) PLIB_ADCHS_DigitalComparatorEnable Function Enables the specified digital comparator. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 135 File plib_adchs.h C void PLIB_ADCHS_DigitalComparatorEnable(ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator); Returns None. Description This function enables (turns ON) the specified digital comparator. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. PLIB_ADCHS_DigitalComparatorEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_2); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. digComparator Digital comparator of type ADCHS_DIGITAL_COMPARATOR_ID. Function void PLIB_ADCHS_DigitalComparatorEnable ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator ) PLIB_ADCHS_DigitalComparatorEventHasOccurred Function Returns the status of the selected digital comparator. File plib_adchs.h C bool PLIB_ADCHS_DigitalComparatorEventHasOccurred(ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID id); Returns None. Description This function returns the status of the selected digital comparator, whether or not an event related to this comparator has occurred. A comparator event will occur if the analog input selected for the comparator is outside the set limits. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 136 // Check, if comparator event has occurred for digital comparator 2 if(PLIB_ADCHS_DigitalComparatorEventHasOccurred( MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_2 )) { // Perform related tasks } Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the digital comparator in this device. Function bool PLIB_ADCHS_DigitalComparatorEventHasOccurred ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID id ) PLIB_ADCHS_DigitalComparatorInterruptDisable Function Disables the interrupt for the selected digital comparator. File plib_adchs.h C void PLIB_ADCHS_DigitalComparatorInterruptDisable(ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator); Returns None. Description This function disables (turns OFF) the interrupt for the selected digital comparator. The interrupt will not be generated, once a comparator event occurs. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable interrupt for comparator 2 PLIB_ADCHS_DigitalComparatorInterruptDisable( MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_2 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. digComparator Digital comparator of type ADCHS_DIGITAL_COMPARATOR_ID. Function void PLIB_ADCHS_DigitalComparatorInterruptDisable ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 137 PLIB_ADCHS_DigitalComparatorInterruptEnable Function Enables the interrupt for the selected digital comparator. File plib_adchs.h C void PLIB_ADCHS_DigitalComparatorInterruptEnable(ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator); Returns None. Description This function enables (turns ON) the interrupt for the selected digital comparator. The interrupt is generated when the converted analog data for the related analog input goes out of the specified limits (set for comparator). Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable interrupt for comparator 2 PLIB_ADCHS_DigitalComparatorInterruptEnable( MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_2 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. digComparator Digital comparator of type ADCHS_DIGITAL_COMPARATOR_ID. Function void PLIB_ADCHS_DigitalComparatorInterruptEnable ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID digComparator ) PLIB_ADCHS_DigitalComparatorLimitSet Function Sets the limit for the specified digital comparator. File plib_adchs.h C void PLIB_ADCHS_DigitalComparatorLimitSet(ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID id, int16_t hiLimit, int16_t loLimit); Returns None. Description This function sets the high and low limits for the specified digital comparator. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 138 Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the Digital Comparator // Creates an event when the reading of AN3 is between 20% to 80% of the // full scale 12-bit output. PLIB_ADCHS_DigitalComparatorLimitSet( MY_ADCHS_INSTANCE, // ADCHS module ID ADCHS_DIGITAL_COMPARATOR_1, // Comparator ID 0x0CCD, // high limit, 80% of full scale 0x0333); // low limit, 20% of full scale Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the digital comparator in this device. hiLimit High limit in the same format as the conversion result. loLimit Low limit in the same format as the conversion result. Function void PLIB_ADCHS_DigitalComparatorLimitSet ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID id, int16_t hiLimit, int16_t loLimit ) PLIB_ADCHS_DigitalComparatorSetup Function Configures the Digital Comparator on the High-Speed SAR ADC converter. File plib_adchs.h C void PLIB_ADCHS_DigitalComparatorSetup(ADCHS_MODULE_ID index, ADCHS_DIGITAL_COMPARATOR_ID id, bool intEnable, bool inBetweenOrEqual, bool greaterEqualHi, bool lessThanHi, bool greaterEqualLo, bool lessThanLo, ADCHS_AN_INPUT_ID analogInput, int16_t hiLimit, int16_t loLimit); Returns None. Description This function configures all parameters for the Digital Comparator of the ADCHS module. Remarks This function must be called when the ADC is disabled. The format of hiLimit and loLimit must match the output format of analog input specified in analogInput. Preconditions The module is disabled when calling this function. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 139 Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the Digital Comparator // Creates an event when the reading of AN3 is between 20% to 80% of the // full scale 12-bit output. PLIB_ADCHS_DigitalComparatorSetup( MY_ADCHS_INSTANCE, // ADCHS module ID ADCHS_DIGITAL_COMPARATOR_1, // Comparator ID false, // No Int Enable true, // test for between low and high false, // no test for greater than equal to high false, // no test for less than high false, // no test for greater than equal to low false, // no test for less than low ADCHS_AN3, // select AN3 0x0CCD, // high limit, 80% of full scale 0x0333); // low limit, 20% of full scale // Enable Digital Comparator 1 PLIB_ADCHS_DigitalComparatorEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_COMPARATOR_1); Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the digital comparator specified. intEnable When true, comparator events generates interrupt. inBetweenOrEqual Event is generated when result is greater than or equal to loLimit and less than hiLimit. greaterEqualHi Event is generated when result is greater than or equal to hiLimit. lessThanHi Event is generated when result is less than hiLimit. greaterEqualLo Event is generated when result is greater than or equal to loLimit. lessThanLo Event is generated when result is less than loLimit. analogInput An analog input selection of type ADCHS_AN_INPUT_ID. The valid input range for "analogInput" is from ADCHS_AN0 to ADCHS_AN31. Values from ADCHS_AN32 and higher will be ignored. hiLimit High limit in the same format as the conversion result. loLimit Low limit in the same format as the conversion result. Function void PLIB_ADCHS_DigitalComparatorSetup ( ADCHS_MODULE_ID index, // ADCHS channel ID ADCHS_DIGITAL_COMPARATOR_ID id, // Comparator ID bool intEnable, // Int Enable bool inBetweenOrEqual, // between low and high bool greaterEqualHi, // greater than equal to high bool lessThanHi, // less than high bool greaterEqualLo, // greater than equal to low bool lessThanLo, // less than low ADCHS_AN_INPUT_ID analogInput, // input enable bits int16_t hiLimit, // high limit int16_t loLimit // low limit ) f) Digital Filter Functions Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 140 PLIB_ADCHS_DigitalFilterAveragingModeSampleCountSelect Function Selects the number of samples which are averaged by the Digital Filter. File plib_adchs.h C void PLIB_ADCHS_DigitalFilterAveragingModeSampleCountSelect(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID id, ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT count); Returns None. Description This function selects the number of samples which are averaged by the Digital Filter, when the Digital Filter is configured for Averaging mode. Remarks This function must be called when the ADC is disabled. Preconditions The Digital Filter is disabled when calling this function. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable Digital Filter PLIB_ADCHS_DigitalFilterDisable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); // Select the sample count to be 64 samples PLIB_ADCHS_DigitalFilterAveragingModeSampleCountSelect( MY_ADCHS_INSTANCE, // ADCHS module ID ADCHS_DIGITAL_FILTER_1, // Filter ID ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_64); // 64 samples averaged // Enable Digital Filter-1 PLIB_ADCHS_DigitalFilterEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the Digital Filter in this device. count Sets the number of samples which will be averaged by the Digital Filter. This variable is of type. ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT. Function void PLIB_ADCHS_DigitalFilterAveragingModeSampleCountSelect ( ADCHS_MODULE_ID index, // ADCHS module ID ADCHS_DIGITAL_FILTER_ID id, // Filter ID ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT count // Sample count ) PLIB_ADCHS_DigitalFilterAveragingModeSetup Function Configures the Digital Filter on the High-Speed SAR ADC converter in Averaging mode. File plib_adchs.h Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 141 C void PLIB_ADCHS_DigitalFilterAveragingModeSetup(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID id, ADCHS_AN_INPUT_ID analogInput, ADCHS_DIGITAL_FILTER_SIGNIFICANT_BITS length, ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT count, bool intEnable); Returns None. Description This function configures the Digital Filter on the High-Speed SAR ADC converter in Averaging mode. Remarks This function must be called when the ADC is disabled. Preconditions The Digital Filter is disabled when calling this function. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the Digital Filter in Averaging mode // AN4 is averaged with 64 samples. No global interrupt is enabled. PLIB_ADCHS_DigitalFilterAveragingModeSetup( MY_ADCHS_INSTANCE, // ADCHS module ID ADCHS_DIGITAL_FILTER_1, // Filter ID ADCHS_AN4, // Oversample AN4 ADCHS_DIGITAL_FILTER_SIGNIFICANT_ALL_16BITS, // all 16bits significant ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_64, // 64 samples averaged false ); // No Int Enable // Enable Digital Filter-1 PLIB_ADCHS_DigitalFilterEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the Digital Filter in this device. analogInput Identifier for the analog input to be filtered. length Sets the significant date length. count Sets the number of samples which will be averaged by Digital Filter. This variable is of type. ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT. intEnable When set, Filter events generated interrupt. Function void PLIB_ADCHS_DigitalFilterAveragingModeSetup ( ADCHS_MODULE_ID index, // ADCHS module ID ADCHS_DIGITAL_FILTER_ID id, // Filter ID ADCHS_AN_INPUT_ID analogInput, // analog input ID ADCHS_DIGITAL_FILTER_SIGNIFICANT_BITS length, // Significant data bit ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT count, // Sample count bool intEnable // Int Enable ) PLIB_ADCHS_DigitalFilterDataGet Function Used to fetch the data result from the Digital Filter. File plib_adchs.h Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 142 C int16_t PLIB_ADCHS_DigitalFilterDataGet(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID dfltrID); Returns A 16-bit result in the format specified by the filter's configuration setting. Description This function is used to fetch data from the Digital Filter. Remarks None. Preconditions This function will function only if the Digital Filter was already configured (in Oversampling mode or Averaging mode) and the Digital Filter was enabled. Example int16_t myDFLTRResult; if (PLIB_ADCHS_DigitalFilterDataIsReady(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1)) { // fetch data myDFLTRResult = PLIB_ADCHS_DigitalFilterDataGet(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); // process result ... } Parameters Parameters Description index Identifier for the ADCHS instance. dfltrID Identifier for the Digital Filter in this device. Function int16_t PLIB_ADCHS_DigitalFilterDataGet ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID dfltrID ) PLIB_ADCHS_DigitalFilterDataIsReady Function Used to determine if the Digital Filter has data ready. File plib_adchs.h C bool PLIB_ADCHS_DigitalFilterDataIsReady(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID id); Returns • true - Digital Filter has filtered data ready to be read • false - Digital Filter data is not yet ready Description This function can be used to determine if the ADCHS Digital Filter has data ready. A 'true' is returned when data is available, which can be fetched using PLIB_ADCHS_DigitalFilterDataGet. Remarks None. Preconditions None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 143 Example if (PLIB_ADCHS_DigitalFilterDataIsReady(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1)) { // fetch and process data } Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the Digital Filter in this device. Function bool PLIB_ADCHS_DigitalFilterDataIsReady ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID id ) PLIB_ADCHS_DigitalFilterDataReadyInterruptDisable Function Disables the interrupt for the selected Digital Filter. File plib_adchs.h C void PLIB_ADCHS_DigitalFilterDataReadyInterruptDisable(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID digFilter); Returns None. Description This function disables (turns OFF) the interrupt for the selected Digital Filter. The interrupt will not be generated, once filter data is ready. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable interrupt for filter 2 PLIB_ADCHS_DigitalFilterDataReadyInterruptDisable( MY_ADCHS_INSTANCE, ADCHS_DFLTR2 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. digFilter Digital Filter of type ADCHS_DIGITAL_FILTER_ID. Function void PLIB_ADCHS_DigitalFilterDataReadyInterruptDisable ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID digFilter ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 144 PLIB_ADCHS_DigitalFilterDataReadyInterruptEnable Function Enables the interrupt for the selected Digital Filter. File plib_adchs.h C void PLIB_ADCHS_DigitalFilterDataReadyInterruptEnable(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID digFilter); Returns None. Description This function enables (turns ON) the interrupt for the selected Digital Filter. The interrupt is generated when the Digital Filter completes the filtering and data is ready in the register (to be read). Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable interrupt for filter - 2 PLIB_ADCHS_DigitalFilterDataReadyInterruptEnable( MY_ADCHS_INSTANCE, ADCHS_DFLTR2 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. digFilter Digital Filter of type ADCHS_DIGITAL_FILTER_ID. Function void PLIB_ADCHS_DigitalFilterDataReadyInterruptEnable ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID digFilter ) PLIB_ADCHS_DigitalFilterDisable Function Disables the Digital Filter. File plib_adchs.h C void PLIB_ADCHS_DigitalFilterDisable(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID id); Returns None. Description This function Disables (turns OFF) the selected Digital Filter. Remarks None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 145 Preconditions None.. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable Digital Filter 1 PLIB_ADCHS_DigitalFilterDisable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the Digital Filter in the ADCHS channel. Function void PLIB_ADCHS_DigitalFilterDisable ( ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID id ) PLIB_ADCHS_DigitalFilterEnable Function Enables the Digital Filter. File plib_adchs.h C void PLIB_ADCHS_DigitalFilterEnable(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID id); Returns None. Description This function enables (turns ON) the selected Digital Filter. Remarks None. Preconditions The ADC channel should be configured using the PLIB_ADCHS_Setup function prior to enabling. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable Digital Filter-1 PLIB_ADCHS_DigitalFilterEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the digital Filter in the ADCHS channel. Function void PLIB_ADCHS_DigitalFilterEnable ( ADCHS_MODULE_ID index, Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 146 ADCHS_DIGITAL_FILTER_ID id ) PLIB_ADCHS_DigitalFilterOversamplingModeRatioSelect Function Selects the oversampling ratio for the Digital Filter. File plib_adchs.h C void PLIB_ADCHS_DigitalFilterOversamplingModeRatioSelect(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID id, ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO ratio); Returns None. Description This function selects the oversampling ratio for the Digital Filter. This function can be used to change the oversampling ratio of the Digital Filter, when set in Oversampling mode. Remarks This function must be called when the ADC is disabled. Preconditions The Digital Filter is disabled when calling this function. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable Digital Filter PLIB_ADCHS_DigitalFilterDisable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); // Select the oversampling ratio PLIB_ADCHS_DigitalFilterOversamplingModeRatioSelect( MY_ADCHS_INSTANCE, // ADCHS module ID ADCHS_DIGITAL_FILTER_1, // Filter ID ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_16X); // 16 x oversampling // Enable Digital Filter-1 PLIB_ADCHS_DigitalFilterEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the Digital Filter in this device. ratio Sets the oversampling filter ratio. This variable is of type ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO. Function void PLIB_ADCHS_DigitalFilterOversamplingModeRatioSelect ( ADCHS_MODULE_ID index, // ADCHS module ID ADCHS_DIGITAL_FILTER_ID id, // Filter ID ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO ratio // Oversampling ratio ) PLIB_ADCHS_DigitalFilterOversamplingModeSetup Function Configures the Digital Filter on the High-Speed SAR ADC converter in Oversampling mode. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 147 File plib_adchs.h C void PLIB_ADCHS_DigitalFilterOversamplingModeSetup(ADCHS_MODULE_ID index, ADCHS_DIGITAL_FILTER_ID id, ADCHS_AN_INPUT_ID analogInput, ADCHS_DIGITAL_FILTER_SIGNIFICANT_BITS length, ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO ratio, bool intEnable); Returns None. Description This function configures the Digital Filter on the High-Speed SAR ADC converter in Oversampling mode. Remarks This function must be called when the ADC is disabled. Preconditions The Digital Filter channel is disabled when calling this function. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the Digital Filter in Oversampling mode // AN4 is oversampled at a 16X rate. No global interrupt is enabled. PLIB_ADCHS_DigitalFilterOversamplingModeSetup( MY_ADCHS_INSTANCE, // ADCHS module ID ADCHS_DIGITAL_FILTER_1, // Filter ID ADCHS_AN4, // Oversample AN4 ADCHS_DIGITAL_FILTER_SIGNIFICANT_ALL_16BITS, // all 16bits significant ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_16X, // 16 x oversampling false ); // No Int Enable // Enable Digital Filter-1 PLIB_ADCHS_DigitalFilterEnable(MY_ADCHS_INSTANCE, ADCHS_DIGITAL_FILTER_1); Parameters Parameters Description index Identifier for the ADCHS instance. id Identifier for the Digital Filter in this device. analogInput Identifier for the analog input to be filtered. length Sets the significant data length. ratio Sets the oversampling filter ratio. This variable is of type ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO. intEnable When set, Filter events generated interrupt. Function void PLIB_ADCHS_DigitalFilterOversamplingModeSetup ( ADCHS_MODULE_ID index, // ADCHS ID ADCHS_DIGITAL_FILTER_ID id, // Filter ID ADCHS_AN_INPUT_ID analogInput, // analog input ID ADCHS_DIGITAL_FILTER_SIGNIFICANT_BITS length, // Significant data bit ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO ratio, // Oversampling ratio bool intEnable // Int Enable ) g) DMA Functions Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 148 PLIB_ADCHS_DMABuffer_A_InterruptDisable Function Disables the DMA Buffer A full interrupt for the specified Channel 0 to 6. File plib_adchs.h C bool PLIB_ADCHS_DMABuffer_A_InterruptDisable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • true - The function successfully disabled interrupt • false - The function could not disable the interrupt, as the selected Channel is 7, which does not implement this feature Description This function disables (turns OFF) the DMA Buffer A full interrupt for the specified Channel 0 to 6. Since Channel 7 does not implement this feature, passing Channel 7 will result in an error. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable DMA interrupt PLIB_ADCHS_DMABuffer_A_InterruptDisable( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID Channel ID from 0 to 6. Function bool PLIB_ADCHS_DMABuffer_A_InterruptDisable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // Channel ID 0 to 6 ) PLIB_ADCHS_DMABuffer_A_InterruptEnable Function Enables the DMA Buffer A full interrupt for the specified Channel 0 to 6. File plib_adchs.h C bool PLIB_ADCHS_DMABuffer_A_InterruptEnable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • true - The function successfully enabled interrupt • false - The function could not enable the interrupt, as the selected Channel is 7, which does not implement this feature Description This function enables (turns ON) the DMA Buffer A full interrupt for the specified Channel 0 to 6. The interrupt is generated when the DMA buffer A is full. Since Channel 7 does not implement this feature, passing Channel 7 will result in an error. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 149 Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable DMA interrupt PLIB_ADCHS_DMABuffer_A_InterruptEnable( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID Channel ID from 0 to 6. Function bool PLIB_ADCHS_DMABuffer_A_InterruptEnable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // Channel ID 0 to 6 ) PLIB_ADCHS_DMABuffer_A_IsFull Function Used to determine if the DMA Buffer A is full, for the specified Channel 0 to 6. File plib_adchs.h C int8_t PLIB_ADCHS_DMABuffer_A_IsFull(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • 1 - Buffer is full • 0 - Buffer is empty • -1 - Invalid channel ID passed Description This function can be used to determine if the ADCHS DMA Buffer A is full for the specified Channel 0 to 6. A value of '1' is returned when the Buffer A is full. A value of '0' is returned when the Buffer A is empty. This feature is not implemented for Channel 7. Therefore, passing Channel 7 returns an error. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. if (1 == PLIB_ADCHS_DMABuffer_A_IsFull(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 )) { // process data, if DMA Buffer A is full } Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 150 Parameters Parameters Description index Identifier for the ADCHS instance. channelID Channel ID from 0 to 6. Function int8_t PLIB_ADCHS_DMABuffer_A_IsFull ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // channel ID 0 to 6 ) PLIB_ADCHS_DMABuffer_B_InterruptDisable Function Disables the DMA Buffer B full interrupt for the specified Channel 0 to 6. File plib_adchs.h C bool PLIB_ADCHS_DMABuffer_B_InterruptDisable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • true - The function successfully disabled interrupt • false - The function could not disable the interrupt, as the selected Channel is 7, which does not implement this feature Description This function disables (turns OFF) the DMA Buffer B full interrupt for specified Channel 0 to 6. Since Channel 7 does not implement this feature, passing Channel 7 will result in an error. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable DMA interrupt PLIB_ADCHS_DMABuffer_B_InterruptDisable( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID Channel ID from 0 to 6. Function bool PLIB_ADCHS_DMABuffer_B_InterruptDisable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // Channel ID 0 to 6 ) PLIB_ADCHS_DMABuffer_B_InterruptEnable Function Enables the DMA Buffer B full interrupt for the specified Channel 0 to 6. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 151 File plib_adchs.h C bool PLIB_ADCHS_DMABuffer_B_InterruptEnable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • true - The function successfully enabled interrupt • false - The function could not enable the interrupt, as the selected Channel is 7, which does not implement this feature Description This function enables (turns ON) the DMA Buffer B full interrupt for specified Channel 0 to 6. The interrupt is generated when the DMA Buffer B is full. Since Channel 7 does not implement this feature, passing Channel 7 will result in an error. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable DMA interrupt PLIB_ADCHS_DMABuffer_B_InterruptEnable( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID Channel ID from 0 to 6. Function void PLIB_ADCHS_DMABuffer_B_InterruptEnable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // Channel ID 0 to 6 ) PLIB_ADCHS_DMABuffer_B_IsFull Function Used to determine if the DMA Buffer B is full, for the specified Channel 0 to 6. File plib_adchs.h C int8_t PLIB_ADCHS_DMABuffer_B_IsFull(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • 1 - Buffer is full • 0 - Buffer is empty • -1 - Invalid channel ID passed Description This functino is used to determine if the ADCHS DMA Buffer B is full for the specified Channel 0 to 6. A value of '1' is returned when Buffer B is full. A value of '0' is returned when Buffer B is empty. This feature is not implemented for Channel 7. Therefore, passing Channel 7 returns an error. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 152 Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. if (1 == PLIB_ADCHS_DMABuffer_B_IsFull(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 )) { // process data, if DMA Buffer B is full } Parameters Parameters Description index Identifier for the ADCHS instance. channelID Channel ID from 0 to 6. Function int8_t PLIB_ADCHS_DMABuffer_B_IsFull ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // Channel ID 0 to 6 ) PLIB_ADCHS_DMADisable Function Disables the DMA in the High-Speed SAR ADC module. File plib_adchs.h C void PLIB_ADCHS_DMADisable(ADCHS_MODULE_ID index); Returns None. Description This function disables (turns OFF) the DMA in the High-Speed SAR ADC module. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable DMA PLIB_ADCHS_DMADisable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 153 Function void PLIB_ADCHS_DMADisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_DMAEnable Function Enables the DMA in the High-Speed SAR ADC module. File plib_adchs.h C void PLIB_ADCHS_DMAEnable(ADCHS_MODULE_ID index); Returns None. Description This function enables (turns ON) the DMA in the High-Speed SAR ADC module. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable DMA PLIB_ADCHS_DMAEnable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_DMAEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_DMAOverflowErrorHasOccurred Function Used to determine if the DMA Buff had an overflow error. File plib_adchs.h C bool PLIB_ADCHS_DMAOverflowErrorHasOccurred(ADCHS_MODULE_ID index); Returns Boolean: • true - If an overflow error occurred • false - If an overflow error has not occurred Description DMA Buffers are circular in nature. If reading the data from DMA buffer is slower as compared to filling the buffer, the newer data will overwrite the previous data (before the data is read). This function returns 'true' if an overflow error has occurred. Remarks None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 154 Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. if (PLIB_ADCHS_DMAOverflowErrorHasOccurred(MY_ADCHS_INSTANCE) { // Error occurred while(1); } Parameters Parameters Description index Identifier for the ADCHS instance Function bool PLIB_ADCHS_DMAOverflowErrorHasOccurred( ADCHS_MODULE_ID index ) PLIB_ADCHS_DMASetup Function Configures the DMA on the High-Speed SAR ADC. File plib_adchs.h C void PLIB_ADCHS_DMASetup(ADCHS_MODULE_ID index, ADCHS_DMA_BUFFER_LENGTH bufferLengthBytes, uint32_t baseAddress, ADCHS_DMA_COUNT countMode, uint32_t countBaseAddress); Returns None. Description This functin configures all parameters for the DMA of the High-Speed SAR ADC. Remarks This function must be called when the ADC is disabled. Preconditions The ADC channel and the Channel 0 to 6 using DMA are disabled. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the DMA void PLIB_ADCHS_DMASetup( MY_ADCHS_INSTANCE, // ADCHS module ID ADCHS_DMA_BUFFER_LENGTH_8BYTES, // buffer length is 8 Bytes 0xA002, // Base address is 0xA002 ADCHS_DMA_COUNT_ENABLE, // count is enabled 0xC400 ); // Count base address is 0xC400 // Enable DMA PLIB_ADCHS_DMAEnable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. bufferLengthBytes Length of DMA Buffer in number of bytes. Buffer is saved on RAM. The variable is of type ADCHS_DMA_BUFFER_LENGTH. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 155 baseAddress Address of RAM, which holds the buffer. countMode Enable/ Disable the DMA feature to keep count of number of converted data saved by DMA. countBaseAddress Address of RAM, which holds the counts. Function void PLIB_ADCHS_DMASetup ( ADCHS_MODULE_ID index, // ADCHS module ID ADCHS_DMA_BUFFER_LENGTH bufferLengthBytes, // Buffer length uint32_t baseAddress, // Base address for data ADCHS_DMA_COUNT countMode, // Enable/ Disable count uint32_t countBaseAddress // Base address for count ) PLIB_ADCHS_DMASourceRemove Function Disables the DMA for the specified Channel 0 to 6. File plib_adchs.h C bool PLIB_ADCHS_DMASourceRemove(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • true - The function successfully removed the DMA source • false - The function could not remove the DMA source, as selected Channel is 7, which does not implement this feature Description This function disables (turns OFF) the DMA for specified Channel 0 to 6. If Channel 7 is selected, this function returns error. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // DMA for Channel 1 if(!PLIB_ADCHS_DMASourceRemove( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 )) { // error while(1); } Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID Channel ID from 0 to 6. Function bool PLIB_ADCHS_DMASourceRemove ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // Channel ID 0 to 6 ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 156 PLIB_ADCHS_DMASourceSelect Function Enables the DMA for the specified Channel 0 to 6. File plib_adchs.h C bool PLIB_ADCHS_DMASourceSelect(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • true - The function successfully selected the DMA source • false - The function could not select the DMA source, as selected Channel is 7, which does not implement this feature Description This function enables (turns ON) the DMA for specified Channel 0 to 6. If selected Channel is 7, this function return error. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // DMA for Channel 1 if(!PLIB_ADCHS_DMASourceSelect( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 )) { // error while(1); } Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID Channel ID from 0 to 6. Function bool PLIB_ADCHS_DMASourceSelect ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // Channel ID 0 to 6 ) h) Channel Related Functions PLIB_ADCHS_ChannelAnalogFeatureDisable Function Disables the analog circuit for channels of High-Speed SAR ADC. File plib_adchs.h C void PLIB_ADCHS_ChannelAnalogFeatureDisable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 157 Returns None. Description This function disables (turns OFF) the analog circuit for channels. The analog circuit for unused channels can be disabled to reduce current consumption. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. PLIB_ADCHS_ChannelAnalogFeatureDisable(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID ID of the required channel. Function void PLIB_ADCHS_ChannelAnalogFeatureDisable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID ) PLIB_ADCHS_ChannelAnalogFeatureEnable Function Enables the analog circuit for High-Speed SAR ADC channels. File plib_adchs.h C void PLIB_ADCHS_ChannelAnalogFeatureEnable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns None. Description This function enables (turns ON) the analog circuit for channels. The analog circuit can be disabled (when not required) to reduce current consumption by the channel. Since, each channel has the feature to individually enable/disable the analog circuit, the unused channel's analog circuit can be disabled. When the analog circuit for a channel is enabled, it needs a minimum warm-up time before which the channel is ready to perform conversion. Once the channel analog feature (circuit) is enabled, its ready status can be check with PLIB_ADCHS_ChannelIsReady function. Remarks None. Preconditions The ADCHS module should be enabled before calling this function. The ADCHS module can be enabled by calling the PLIB_ADCHS_Enable function. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. PLIB_ADCHS_ChannelAnalogFeatureEnable(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 158 // wait until the channel is ready while(!PLIB_ADCHS_ChannelIsReady(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1)); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID ID of the required channel. Function void PLIB_ADCHS_ChannelAnalogFeatureEnable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID ) PLIB_ADCHS_ChannelConfigurationGet Function Used to get the configuration for the specified channel. File plib_adchs.h C uint32_t PLIB_ADCHS_ChannelConfigurationGet(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns 32-bit value of the configuration for ADCHS channel. Description This functions returns the configuration for the specified channel. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. uint32_t config; config = PLIB_ADCHS_ChannelConfigurationGet(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1); Parameters Parameters Description index Identifier for the ADCHS instance. channelID Channel ID. Function uint32_t PLIB_ADCHS_ChannelConfigurationGet ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // Channel ID ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 159 PLIB_ADCHS_ChannelConfigurationSet Function Used to set the configuration for the specified channel. File plib_adchs.h C void PLIB_ADCHS_ChannelConfigurationSet(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID, uint32_t config); Returns None. Description This functions sets the configuration for the specified channel. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. uint32_t config = 0x12345678; PLIB_ADCHS_ChannelConfigurationSet(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1, config); Parameters Parameters Description index Identifier for the ADCHS instance. channelID Channel ID. config 32-bit value for the configuration of channel. Function void PLIB_ADCHS_ChannelConfigurationSet ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID, uint32_t config ) PLIB_ADCHS_ChannelDigitalFeatureDisable Function Disables the digital circuit for channels of High-Speed SAR ADC. File plib_adchs.h C void PLIB_ADCHS_ChannelDigitalFeatureDisable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns None. Description This function disables (turns OFF) the digital circuit for channels. The digital feature (circuit) of unused channels can be disabled to reduce current Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 160 consumption. The advantage of disabling the digital feature is that re-enabling the digital feature does not require any warm up time and the channel can be immediately used for conversion. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. PLIB_ADCHS_ChannelDigitalFeatureDisable( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID ID of the required channel. Function void PLIB_ADCHS_ChannelDigitalFeatureDisable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID ) PLIB_ADCHS_ChannelDigitalFeatureEnable Function Enables (turns ON) the digital circuit for channels. File plib_adchs.h C void PLIB_ADCHS_ChannelDigitalFeatureEnable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns None. Description This function enables (turns ON) the digital circuit for channels. Unlike enabling the analog feature, enabling the digital feature does not require any warm-up time. Remarks None. Preconditions The ADCHS module should be enabled before calling this function. The ADCHS module can be enabled by calling PLIB_ADCHS_Enable function. Also, for the channel to perform conversion, the analog features of the channel should be enabled using PLIB_ADCHS_ChannelAnalogFeatureEnable, prior to enabling the digital feature. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable analog feature for Channel 1 PLIB_ADCHS_ChannelAnalogFeatureEnable( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); // wait until channel is ready while(!PLIB_ADCHS_ChannelIsReady( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 )); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 161 // Enable the digital Channel 1 PLIB_ADCHS_ChannelDigitalFeatureEnable( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID ID of the required channel. Function void PLIB_ADCHS_ChannelDigitalFeatureEnable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID ) PLIB_ADCHS_ChannelIsReady Function Returns the state of the channel. File plib_adchs.h C bool PLIB_ADCHS_ChannelIsReady(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • true - Channel is ready after warm-up time has elapsed • false - Channel is not ready Description This function returns the state, indicating whether the channel is awake and ready after the warm-up time is complete. When a analog feature (circuit) of a channel is enabled, there is a warm-up time required before the channel is ready and can be used for conversion. The ready state of the channel can be acquired using this function. Remarks None. Preconditions The analog feature for the channel should be enabled using the PLIB_ADCHS_ChannelAnalogFeatureEnable function. Also, the ADCHS module should be enabled before calling this function. Example // Enable the analog feature for Channel 1 PLIB_ADCHS_ChannelAnalogFeatureEnable(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1); // wait until the channel is ready while(!PLIB_ADCHS_ChannelIsReady(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1)); Parameters Parameters Description index Identifier for the ADCHS instance to be configured channelID ID of the required channel Function bool PLIB_ADCHS_ChannelIsReady ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 162 PLIB_ADCHS_ChannelIsReadyInterruptDisable Function Disables the Channel ready interrupt for the specified channel. File plib_adchs.h C void PLIB_ADCHS_ChannelIsReadyInterruptDisable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns None. Description This function disables (turns OFF) the channel ready interrupt for the specified channel. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable wakeup interrupt for Channel 1 PLIB_ADCHS_ChannelIsReadyInterruptDisable( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID Channel ID. Function void PLIB_ADCHS_ChannelIsReadyInterruptDisable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // channel ID ) PLIB_ADCHS_ChannelIsReadyInterruptEnable Function Enables the Channel ready interrupt for the specified channel. File plib_adchs.h C void PLIB_ADCHS_ChannelIsReadyInterruptEnable(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns None. Description This function enables (turns ON) the channel ready interrupt for the specified channel. The interrupt is generated when the channel is ready after wake-up (following warm-up time). Remarks None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 163 Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable wakeup interrupt for Channel 1 PLIB_ADCHS_ChannelIsReadyInterruptEnable( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID Channel ID. Function void PLIB_ADCHS_ChannelIsReadyInterruptEnable ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // channel ID ) PLIB_ADCHS_ChannelSetup Function Configures the High-Speed SAR ADC channels. File plib_adchs.h C void PLIB_ADCHS_ChannelSetup(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID, ADCHS_DATA_RESOLUTION res, uint8_t channelClockDivider, uint16_t sampleTimeCount, ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK earlyInterruptClk); Returns None. Description This function configures all ADC parameters that are common to the specified ADC Channel 0 to 7. This configuration must occur prior to enabling the ADC, and therefore, must be called when the ADC is disabled. Also, this configuration must occur prior to enabling the digital circuit and analog bias circuit for the specified ADC Channel 0 to 7. Remarks This function must be called when the ADC is disabled. Preconditions The channel is disabled when calling this function. Example bool status = false; // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the ADC PLIB_ADCHS_ChannelSetup( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1, // channel - 1 ADCHS_DATA_RESOLUTION_12BIT, // resolution is set to 12bits 1, // channel clock divider bit is, TAD = 2 * TQ 1, // Sample time is 3 * TAD ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1); // Interrupt, 1 clock early status = PLIB_ADCHS_ChannelTriggerSampleSelect( MY_ADCHS_INSTANCE, Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 164 ADCHS_CHANNEL_1, // channel - 1 ADCHS_CHANNEL_SYNC_SAMPLING); // Synchronous sampling selected if( false == status) { // error has occurred while(1); } // Enable the ADC PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); // Wait until the reference voltage is ready while(!PLIB_ADCHS_VREFIsReady(MY_ADCHS_INSTANCE)); //Check if there is a fault in reference voltage if(PLIB_ADCHS_VREFFaultHasOccurred(MY_ADCHS_INSTANCE)) { // process fault accordingly while(1); } // Enable the analog circuit PLIB_ADCHS_ChannelAnalogFeatureEnable(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1); // Wait until the channel wakes up after warm-up while(!PLIB_ADCHS_ChannelIsReady(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1)); // Enable the digital circuit PLIB_ADCHS_ChannelDigitalFeatureEnable(MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1); // ADC will begin conversion now, after a valid trigger Parameters Parameters Description index Identifier for the ADCHS instance. channelID Channel ID of the required ADC channel. res Sets the output data resolution. channelClockDivider Channel Clock source divider. Values range from 1 to 127. This divider determines the channel clock (clock frequency at which the channel 0 to 7 is running). The frequency of channel clock, as per following equation Channel clock frequency = (control clock frequency)/(channelClockDivider * 2). Please note that value of "0" for channelClockDivider is not allowed. The minimum value of channelClockDivider is "1", which also means that the highest channel clock frequency is half of control clock frequency. sampleTimeCount Sets the sample time for ADC channel, 0 to 7. Values range from 0 to 1023. The sample time is given by the equation Sample time = ((1/Channel clock frequency) * (sampleTimeCount + 2)). earlyInterruptClk Sets the number of channel clocks prior to the availability of actual data that the early interrupt is generated. This variable if of type ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK. The selection of this parameter is dependent on the resolution of output data. Function void PLIB_ADCHS_ChannelSetup ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID, // channel ID 0 to 7 ADCHS_DATA_RESOLUTION res, // Output data resolution uint8_t channelClockDivider, // Clock divider uint16_t sampleTimeCount, // Sample time ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK earlyInterruptClk // early interrupt clock setting ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 165 PLIB_ADCHS_ChannelInputSelect Function Selects the analog input for Channel 0 to 6. File plib_adchs.h C bool PLIB_ADCHS_ChannelInputSelect(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID, ADCHS_CHANNEL_INP_SEL sel); Returns • true - The function successfully selected the analog input for the channel • false - The function could not select the input, as selected channel is 7, which does not implement this feature. Otherwise, the selected analog input is not available for the selected channel. Description Selects the analog input for Channel 0 to 6. The inputs for Channel 0 to 6 can be changed between different inputs. This feature is not available for Channel 7; therefore, calling this function for Channel 7 will result in an error. Also, the input selected should match the ones available for the selected channel. Selecting an input which is not available for the channel will return an error. Remarks None. Preconditions None. Example bool status = false; // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Set Channel-0 to use the first input. status = PLIB_ADCHS_ChannelInputSelect ( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0, ADCHS_CHANNEL_0_DEFAULT_INP_AN0 ); if(false == status) { // error while(1); } Parameters Parameters Description index Identifier for the ADCHS instance. channelID Channel ID. sel Selection of inputs of type ADCHS_CHANNEL_INP_SEL. Function bool PLIB_ADCHS_ChannelInputSelect ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID, ADCHS_CHANNEL_INP_SEL sel ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 166 i) FIFO Functions PLIB_ADCHS_FIFODataCountGet Function Returns the number of data to be read from FIFO. File plib_adchs.h C uint8_t PLIB_ADCHS_FIFODataCountGet(ADCHS_MODULE_ID index); Returns The number of the data stored in the FIFO. Description This function returns the number of data which can be read from FIFO. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // variable to save data uint32_t convData; // Check, if FIFO has some data while(!PLIB_ADCHS_FIFODataIsAvailable(MY_ADCHS_INSTANCE)); // Once data is available, check if the data belongs to channel ID -1 if(PLIB_ADCHS_FIFOSourceGet(MY_ADCHS_INSTANCE) == ADCHS_CHANNEL_1) { // Continue reading FIFO, until the count is zero while(PLIB_ADCHS_FIFODataCountGet(MY_ADCHS_INSTANCE) != 0) { // Read from FIFO. For each read, the count is decremented convData = PLIB_ADCHS_FIFORead(MY_ADCHS_INSTANCE); } } Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function uint8_t PLIB_ADCHS_FIFODataCountGet( ADCHS_MODULE_ID index ) PLIB_ADCHS_FIFODataIsAvailable Function Used to determine if the FIFO has data ready. File plib_adchs.h C bool PLIB_ADCHS_FIFODataIsAvailable(ADCHS_MODULE_ID index); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 167 Returns Boolean: • true - If data is ready • false - If data is not ready Description Used to determine if the ADCHS FIFO has data ready. A 'true' is returned when data is available, which can be fetched using PLIB_ADCHS_FIFORead. Remarks None. Preconditions None. Example if (PLIB_ADCHS_FIFODataIsAvailable(MY_ADCHS_INSTANCE)) { // fetch and process data } Parameters Parameters Description index Identifier for the ADCHS instance. Function bool PLIB_ADCHS_FIFODataIsAvailable( ADCHS_MODULE_ID index ) PLIB_ADCHS_FIFODataIsNegative Function Returns the sign of data stored in FIFO. File plib_adchs.h C bool PLIB_ADCHS_FIFODataIsNegative(ADCHS_MODULE_ID index); Returns Boolean: • true - If sign is negative • false - If sign is not negative Description This function returns the sign of data stored in the FIFO. Remarks None. Preconditions None. Example if (PLIB_ADCHS_FIFODataIsNegative(MY_ADCHS_INSTANCE)) { //process data } Parameters Parameters Description index Identifier for the ADCHS instance. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 168 Function bool PLIB_ADCHS_FIFODataIsNegative( ADCHS_MODULE_ID index ) PLIB_ADCHS_FIFODataReadyInterruptDisable Function Disables the interrupt for FIFO. File plib_adchs.h C void PLIB_ADCHS_FIFODataReadyInterruptDisable(ADCHS_MODULE_ID index); Returns None. Description This function disables (turns OFF) the interrupt for FIFO. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable interrupt for FIFO PLIB_ADCHS_FIFODataReadyInterruptDisable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_FIFODataReadyInterruptDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_FIFODataReadyInterruptEnable Function Enables the interrupt for FIFO. File plib_adchs.h C void PLIB_ADCHS_FIFODataReadyInterruptEnable(ADCHS_MODULE_ID index); Returns None. Description This function enables (turns ON) the interrupt for FIFO. The interrupt is generated when the FIFO has data to be read. Remarks None. Preconditions None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 169 Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable interrupt for FIFO PLIB_ADCHS_FIFODataReadyInterruptEnable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_FIFODataReadyInterruptEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_FIFODisable Function Disables the FIFO in the High-Speed SAR ADC. File plib_adchs.h C void PLIB_ADCHS_FIFODisable(ADCHS_MODULE_ID index); Returns None. Description This function disables (turns OFF) the FIFO. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable FIFO PLIB_ADCHS_FIFODisable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_FIFODisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_FIFOEnable Function Enables the FIFO in the High-Speed SAR ADC File plib_adchs.h C void PLIB_ADCHS_FIFOEnable(ADCHS_MODULE_ID index); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 170 Returns None. Description This function enables (turns ON) the FIFO. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable FIFO PLIB_ADCHS_FIFOEnable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance. Function void PLIB_ADCHS_FIFOEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_FIFOErrorHasOccurred Function Used to determine if the FIFO has encountered an overflow error. File plib_adchs.h C bool PLIB_ADCHS_FIFOErrorHasOccurred(ADCHS_MODULE_ID index); Returns • true - An error has occurred • false - No error occurred has in the FIFO Description This function can be used to determine if the ADCHS FIFO had a data, which was overwritten by the next round of a FIFO write (overflow error). A 'true' is returned when an overflow error has occurred. Remarks None. Preconditions None. Example if (!PLIB_ADCHS_FIFOErrorHasOccurred(MY_ADCHS_INSTANCE)) { // process data, if overflow error did not occur } Parameters Parameters Description index Identifier for the ADCHS instance. Function bool PLIB_ADCHS_FIFOErrorHasOccurred( ADCHS_MODULE_ID index ) Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 171 PLIB_ADCHS_FIFORead Function Used to fetch the data result from the FIFO. File plib_adchs.h C int32_t PLIB_ADCHS_FIFORead(ADCHS_MODULE_ID index); Returns A 32-bit result in the format specified by the ADC configuration for the module using the FIFO. Description This function is used to fetch data from the FIFO. The FIFO can only be assigned to a Class 1 ADC analog input. Remarks None. Preconditions The FIFO should have data ready to be read from it. Example int32_t myFIFOResult; if (PLIB_ADCHS_FIFODataIsAvailable(MY_ADCHS_INSTANCE)) { // fetch data myDFLTRResult = PLIB_ADCHS_FIFORead(MY_ADCHS_INSTANCE); // process result ... } Parameters Parameters Description index Identifier for the ADCHS instance. Function int32_t PLIB_ADCHS_FIFORead( ADCHS_MODULE_ID index ) PLIB_ADCHS_FIFOSourceGet Function Returns the channel ID using the FIFO. File plib_adchs.h C ADCHS_CHANNEL_ID PLIB_ADCHS_FIFOSourceGet(ADCHS_MODULE_ID index); Returns The Channel ID of data type ADCHS_CHANNEL_ID. Description This function returns the channel ID of Channel 0 to 6, whose data is stored on the FIFO. Remarks None. Preconditions None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 172 Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // variable to save data uint32_t convData; // Check, if FIFO has some data while(!PLIB_ADCHS_FIFODataIsAvailable(MY_ADCHS_INSTANCE)); // Once data is available, check if the data belongs to channel ID -1 if(PLIB_ADCHS_FIFOSourceGet(MY_ADCHS_INSTANCE) == ADCHS_CHANNEL_1) { // Continue reading FIFO, until the count is zero while(PLIB_ADCHS_FIFODataCountGet(MY_ADCHS_INSTANCE) != 0) { // Read from FIFO. For each read, the count is decremented convData = PLIB_ADCHS_FIFORead(MY_ADCHS_INSTANCE); } } Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function ADCHS_CHANNEL_ID PLIB_ADCHS_FIFOSourceGet( ADCHS_MODULE_ID index ) PLIB_ADCHS_FIFOSourceSelect Function Sets the Channel 0 to 6 using the FIFO. File plib_adchs.h C bool PLIB_ADCHS_FIFOSourceSelect(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID); Returns • true - The function successfully selected the FIFO source • false - The function could not select the FIFO source, as selected Channel is 7, which does not implement this feature Description This function sets the Channel 0 to 6 ID, which would be storing data into FIFO. If this function is called with Channel ID as 7, the function will return an error. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Set Channel 1 to be storing data into FIFO if(!PLIB_ADCHS_FIFOSourceSelect( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_1 )) { // error has occurred while(1); } Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 173 Parameters Parameters Description index Identifier for the ADCHS instance to be configured. channelID Channel ID from 0 to 6. Function bool PLIB_ADCHS_FIFOSourceSelect ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID channelID // Channel ID from 0 to 6 ) j) Interrupt Functions PLIB_ADCHS_EarlyInterruptDisable Function Disables the early interrupt for the ADCHS. File plib_adchs.h C void PLIB_ADCHS_EarlyInterruptDisable(ADCHS_MODULE_ID index); Returns None. Description This function Disables (turns OFF) the early interrupt for the entire ADCHS. Since early interrupt function is disabled, setting early interrupt enable for individual analog input will not work. Further selection (enabling/disabling) of interrupt feature for individual analog input is possible through the functions PLIB_ADCHS_AnalogInputDataReadyInterruptEnable or PLIB_ADCHS_AnalogInputDataReadyInterruptDisable. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable early interrupt PLIB_ADCHS_EarlyInterruptDisable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_EarlyInterruptDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_EarlyInterruptEnable Function Enables the early interrupt for the ADCHS. File plib_adchs.h Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 174 C void PLIB_ADCHS_EarlyInterruptEnable(ADCHS_MODULE_ID index); Returns None. Description This function enables (turns ON) the early interrupt for the entire ADCHS. Further selection (enabling/disabling) of early interrupt feature for individual analog input through the functions PLIB_ADCHS_AnalogInputEarlyInterruptEnable or PLIB_ADCHS_AnalogInputEarlyInterruptDisable. The interrupt is generated at a set number of clock prior to conversion complete. The number of clock for early interrupt is set using the "configure" function for specific channel. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable early interrupt PLIB_ADCHS_EarlyInterruptEnable( MY_ADCHS_INSTANCE ); // Now, enable the early interrupt for each analog inputs PLIB_ADCHS_AnalogInputEarlyInterruptEnable(MY_ADCHS_INSTANCE, ADCHS_AN10); PLIB_ADCHS_AnalogInputEarlyInterruptEnable(MY_ADCHS_INSTANCE, ADCHS_AN11); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_EarlyInterruptEnable( ADCHS_MODULE_ID index ) k) Turbo Mode Functions PLIB_ADCHS_TurboModeChannelSelect Function Configures the channels for Turbo mode. File plib_adchs.h C bool PLIB_ADCHS_TurboModeChannelSelect(ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID masterChannelID, ADCHS_CHANNEL_ID slaveChannelID); Returns • true - The function successfully selected the channels for Turbo mode • false - The function could not select the channels for Turbo mode for the following reasons: • Both the master and slave channels are the same • Channel 7 was used to set up Turbo mode (either as a master or a slave or both) Description While running the High-Speed SAR ADC in Turbo mode, two channels (from 0 to 6) are interleaved to get higher throughput. This function configures the two channels. This configuration must occur prior to enabling the ADC and prior to enabling Turbo mode. Only valid channels from 0 to 6 can be made as master or slave. If Channel 7 is used, the function will return error Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 175 Remarks This function must be called when the ADC is disabled. Preconditions The channels are disabled and Turbo mode is disabled when calling this function. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Configure the ADC with Channel 0 as master and Channel 1 as slave if(!PLIB_ADCHS_TurboModeChannelSelect( MY_ADCHS_INSTANCE, ADCHS_CHANNEL_0, ADCHS_CHANNEL_1)) { // Error occurred while setting up Turbo mode while(1); } // Enable Turbo mode PLIB_ADCHS_TurboModeEnable(MY_ADCHS_INSTANCE); // Check for Turbo mode error if(PLIB_ADCHS_TurboModeErrorHasOccurred(MY_ADCHS_INSTANCE); { // Configuration of Turbo mode has caused an error // Process error here or reconfigure Turbo Mode while(1); } // Enable the ADC PLIB_ADCHS_Enable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. masterChannelID Channel ID of master channel. Valid channel IDs are from 0 to 6. slaveChannelID Channel ID of slave channel. Valid channel IDs are from 0 to 6. Function bool PLIB_ADCHS_TurboModeChannelSelect ( ADCHS_MODULE_ID index, ADCHS_CHANNEL_ID masterChannelID, ADCHS_CHANNEL_ID slaveChannelID ) PLIB_ADCHS_TurboModeDisable Function Disables Turbo mode for High-Speed SAR ADC module. File plib_adchs.h C void PLIB_ADCHS_TurboModeDisable(ADCHS_MODULE_ID index); Returns None. Description This function disables (turns OFF) Turbo mode on the High-Speed SAR ADC module. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 176 Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. PLIB_ADCHS_TurboModeDisable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_TurboModeDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_TurboModeEnable Function Enables Turbo mode for the High-Speed SAR ADC module. File plib_adchs.h C void PLIB_ADCHS_TurboModeEnable(ADCHS_MODULE_ID index); Returns None. Description This function enables (turns ON) Turbo mode on the High-Speed SAR ADC module. Remarks None. Preconditions The master and slave channels must be selected to work in Turbo mode, before enabling Turbo mode. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. PLIB_ADCHS_TurboModeEnable(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_TurboModeEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_TurboModeErrorHasOccurred Function Returns the error state of Turbo mode. File plib_adchs.h C bool PLIB_ADCHS_TurboModeErrorHasOccurred(ADCHS_MODULE_ID index); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 177 Returns • true - Turbo mode error has occurred • false - Turbo mode error has not occurred Description Returns the state of error bit for Turbo mode. When Turbo mode is enabled, some parameters of master and slave channels should be same. They are ADC channel clock divisor, ADC resolution, and Sampling time. Also, both master and slave channels should use synchronous sampling. If any or all these conditions are not met, the Turbo mode error will be set, which can be read by calling Remarks None. Preconditions None. Example bool errorState = PLIB_ADCHS_TurboModeErrorHasOccurred(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance. Function bool PLIB_ADCHS_TurboModeErrorHasOccurred( ADCHS_MODULE_ID index ) l) Voltage Reference Functions PLIB_ADCHS_VREFFaultHasOccurred Function Returns the state of VREF fault. File plib_adchs.h C bool PLIB_ADCHS_VREFFaultHasOccurred(ADCHS_MODULE_ID index); Returns • true - A VREF Fault has occurred • false - No Fault occurred on VREF Description This function returns the Fault state for VREF, Band Gap, or AVDD BOR. Remarks None. Preconditions The ADCHS module should be enabled before calling this function. The ADCHS module can be enabled by calling the PLIB_ADCHS_Enable function. Example bool vrefFaultState = PLIB_ADCHS_VREFFaultHasOccurred(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 178 Function bool PLIB_ADCHS_VREFFaultHasOccurred( ADCHS_MODULE_ID index ) PLIB_ADCHS_VREFFaultInterruptDisable Function Disables the VREF Fault interrupt. File plib_adchs.h C void PLIB_ADCHS_VREFFaultInterruptDisable(ADCHS_MODULE_ID index); Returns None. Description This function disables (turns OFF) the VREF Fault interrupt. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable VREF fault interrupt PLIB_ADCHS_VREFFaultInterruptDisable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_VREFFaultInterruptDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_VREFFaultInterruptEnable Function Enables the VREF fault interrupt. File plib_adchs.h C void PLIB_ADCHS_VREFFaultInterruptEnable(ADCHS_MODULE_ID index); Returns None. Description This function enables (turns ON) the VREF fault interrupt. The interrupt is generated when a fault is encountered with VREF (mostly by BOR of the analog supply). Remarks None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 179 Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable VREF fault interrupt PLIB_ADCHS_VREFFaultInterruptEnable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_VREFFaultInterruptEnable( ADCHS_MODULE_ID index ) PLIB_ADCHS_VREFIsReady Function Returns the state of VREF. File plib_adchs.h C bool PLIB_ADCHS_VREFIsReady(ADCHS_MODULE_ID index); Returns • true - Both band gap reference voltage and ADC VREF are ready • false - Either band gap reference voltage or ADC VREF is not ready Description This function returns the VREF state. Remarks None. Preconditions The ADCHS module should be enabled before checking for VREF status. The ADCHS module can be enabled by calling the PLIB_ADCHS_Enable function. Example bool vrefState = PLIB_ADCHS_VREFIsReady(MY_ADCHS_INSTANCE); Parameters Parameters Description index Identifier for the ADCHS instance Function bool PLIB_ADCHS_VREFIsReady( ADCHS_MODULE_ID index ) PLIB_ADCHS_VREFReadyInterruptDisable Function Disables the VREF ready interrupt. File plib_adchs.h C void PLIB_ADCHS_VREFReadyInterruptDisable(ADCHS_MODULE_ID index); Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 180 Returns None. Description This function disables (turns OFF) the VREF ready interrupt. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Disable VREF interrupt PLIB_ADCHS_VREFReadyInterruptDisable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Function void PLIB_ADCHS_VREFReadyInterruptDisable( ADCHS_MODULE_ID index ) PLIB_ADCHS_VREFReadyInterruptEnable Function Enables the VREF ready interrupt. File plib_adchs.h C void PLIB_ADCHS_VREFReadyInterruptEnable(ADCHS_MODULE_ID index); Returns None. Description This function enables (turns ON) the VREF ready interrupt. The interrupt is generated when the Band gap voltage/VREF is ready to be used by the ADCHS instance. Remarks None. Preconditions None. Example // Where MY_ADCHS_INSTANCE, is the ADCHS instance selected for use by the // application developer. // Enable VREF ready interrupt PLIB_ADCHS_VREFReadyInterruptEnable( MY_ADCHS_INSTANCE ); Parameters Parameters Description index Identifier for the ADCHS instance to be configured. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 181 Function void PLIB_ADCHS_VREFReadyInterruptEnable( ADCHS_MODULE_ID index ) m) Feature Existence Functions PLIB_ADCHS_ExistsAnalogInputCheck Function Identifies whether the System Configuration feature exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsAnalogInputCheck(ADCHS_MODULE_ID index); Returns Existence of the System Configuration feature: • true - The System Configuration feature is supported on the device • false - The System Configuration feature is not supported on the device Description This function identifies whether the System Configuration feature is available on the ADCHS module. When this function returns true, this function is supported on the device: • PLIB_ADCHS_AnalogInputIsAvailable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsAnalogInputCheck( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsAnalogInputModeControl Function Identifies whether the analog input mode control exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsAnalogInputModeControl(ADCHS_MODULE_ID index); Returns Existence of the input mode control feature: • true - The analog input mode control feature is supported on the device • false - The analog input mode control feature is not supported on the device Description This function identifies whether the analog input mode control feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_AnalogInputModeSelect • PLIB_ADCHS_AnalogInputModeGet Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 182 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsAnalogInputModeControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsAnalogInputScan Function Identifies whether the Analog input Scan exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsAnalogInputScan(ADCHS_MODULE_ID index); Returns Existence of the Scan feature: • true - The Analog Input Scan feature is supported on the device • false - The Analog Input Scan feature is not supported on the device Description This function identifies whether the Analog Input Scan feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_AnalogInputScanIsComplete • PLIB_ADCHS_AnalogInputScanSelect • PLIB_ADCHS_AnalogInputScanRemove • PLIB_ADCHS_AnalogInputScanIsSelected • PLIB_ADCHS_AnalogInputScanSetup • PLIB_ADCHS_ScanCompleteInterruptEnable • PLIB_ADCHS_ScanCompleteInterruptDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsAnalogInputScan( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsChannelAnalogControl Function Identifies whether the Channel Analog control exists on the ADCHS module. File plib_adchs.h Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 183 C bool PLIB_ADCHS_ExistsChannelAnalogControl(ADCHS_MODULE_ID index); Returns Existence of the Channel Analog control feature: • true - The Channel Analog control feature is supported on the device • false - The Channel Analog control feature is not supported on the device Description This function identifies whether the Channel Analog control feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_ChannelAnalogFeatureEnable • PLIB_ADCHS_ChannelAnalogFeatureDisable • PLIB_ADCHS_ChannelIsReady • PLIB_ADCHS_ChannelIsReadyInterruptEnable • PLIB_ADCHS_ChannelIsReadyInterruptDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsChannelAnalogControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsChannelConfiguration Function Identifies whether the Channel Configuration feature exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsChannelConfiguration(ADCHS_MODULE_ID index); Returns Existence of the Channel Configuration feature: • true - The Channel Configuration feature is supported on the device • false - The Channel Configuration feature is not supported on the device Description This function identifies whether the Channel Configuration feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_ChannelConfigurationGet • PLIB_ADCHS_ChannelConfigurationSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 184 Function PLIB_ADCHS_ExistsChannelConfiguration( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsChannelDigitalControl Function Identifies whether the Channel Digital control exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsChannelDigitalControl(ADCHS_MODULE_ID index); Returns Existence of the Channel Digital control feature: • true - The Channel Digital control feature is supported on the device • false - The Channel Digital control feature is not supported on the device Description This function identifies whether the Channel Digital control feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_ChannelDigitalFeatureEnable • PLIB_ADCHS_ChannelDigitalFeatureDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsChannelDigitalControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsChannelInputSelectControl Function Identifies whether the Channel 0 to 6 Input select feature exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsChannelInputSelectControl(ADCHS_MODULE_ID index); Returns Existence of the Channel 0 to 6 Input feature: • true - The Channel 0 to 6 Input Select feature is supported on the device • false - The Channel 0 to 6 Input Select feature is not supported on the device Description This function identifies whether the Channel 0 to 6 Input select feature is available on the ADCHS module. When this function returns true, this function is supported on the device: • PLIB_ADCHS_ChannelInputSelect Remarks None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 185 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCHS_ExistsChannelInputSelectControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsConfiguration Function Identifies whether the Configuration feature exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsConfiguration(ADCHS_MODULE_ID index); Returns Existence of the Configuration feature: • true - The Configuration feature is supported on the device • false - The Configuration feature is not supported on the device Description This function identifies whether the Configuration feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_Setup • PLIB_ADCHS_ChannelSetup Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsConfiguration( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsConversionResults Function Identifies whether the Conversion Results feature exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsConversionResults(ADCHS_MODULE_ID index); Returns Existence of the ConversionResults feature: • true - The ConversionResults feature is supported on the device • false - The ConversionResults feature is not supported on the device Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 186 Description This function identifies whether the Conversion Results feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_AnalogInputDataReadyInterruptEnable • PLIB_ADCHS_AnalogInputDataReadyInterruptDisable • PLIB_ADCHS_AnalogInputDataIsReady • PLIB_ADCHS_AnalogInputResultGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsConversionResults( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsCVD Function Identifies whether the CVD exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsCVD(ADCHS_MODULE_ID index); Returns Existence of the CVD feature: • true - The CVD feature is supported on the device • false - The CVD feature is not supported on the device Description This function identifies whether the CVD feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_CVDEnable • PLIB_ADCHS_CVDDisable • PLIB_ADCHS_CVDSetup • PLIB_ADCHS_CVDResultGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsCVD( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsDigitalComparator Function Identifies whether the Digital Comparator feature exists on the ADCHS module . Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 187 File plib_adchs.h C bool PLIB_ADCHS_ExistsDigitalComparator(ADCHS_MODULE_ID index); Returns Existence of the Digital Comparator feature: • true - The Digital Comparator feature is supported on the device • false - The Digital Comparator feature is not supported on the device Description This function identifies whether the Digital Comparator feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_DigitalComparatorAnalogInputSelect • PLIB_ADCHS_DigitalComparatorAnalogInputGet • PLIB_ADCHS_DigitalComparatorEnable • PLIB_ADCHS_DigitalComparatorDisable • PLIB_ADCHS_DigitalComparatorInterruptEnable • PLIB_ADCHS_DigitalComparatorInterruptDisable • PLIB_ADCHS_DigitalComparatorSetup • PLIB_ADCHS_DigitalComparatorEventHasOccurred • PLIB_ADCHS_DigitalComparatorLimitSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsDigitalComparator( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsDigitalFilter Function Identifies whether the Digital Filter feature exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsDigitalFilter(ADCHS_MODULE_ID index); Returns Existence of the Digital Filter feature: • true - The Digital Filter feature is supported on the device • false - The Digital Filter feature is not supported on the device Description This function identifies whether the Digital Filter feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_DigitalFilterEnable • PLIB_ADCHS_DigitalFilterDisable • PLIB_ADCHS_DigitalFilterOversamplingModeSetup • PLIB_ADCHS_DigitalFilterAveragingModeSetup • PLIB_ADCHS_DigitalFilterOversamplingModeRatioSelect Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 188 • PLIB_ADCHS_DigitalFilterAveragingModeSampleCountSelect • PLIB_ADCHS_DigitalFilterDataIsReady • PLIB_ADCHS_DigitalFilterDataGet • PLIB_ADCHS_DigitalFilterDataReadyInterruptEnable • PLIB_ADCHS_DigitalFilterDataReadyInterruptDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsDigitalFilter( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsDMA Function Identifies whether the DMA exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsDMA(ADCHS_MODULE_ID index); Returns Existence of the DMA feature: • true - The DMA feature is supported on the device • false - The DMA feature is not supported on the device Description This function identifies whether the DMA feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_DMAEnable • PLIB_ADCHS_DMADisable • PLIB_ADCHS_DMASetup • PLIB_ADCHS_DMASourceSelect • PLIB_ADCHS_DMASourceRemove • PLIB_ADCHS_DMABuffer_A_InterruptEnable • PLIB_ADCHS_DMABuffer_A_InterruptDisable • PLIB_ADCHS_DMABuffer_B_InterruptEnable • PLIB_ADCHS_DMABuffer_B_InterruptDisable • PLIB_ADCHS_DMABuffer_A_IsFull • PLIB_ADCHS_DMABuffer_B_IsFull • PLIB_ADCHS_DMAOverflowErrorHasOccurred Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 189 Function PLIB_ADCHS_ExistsDMA( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsEarlyInterruptControl Function Identifies whether the Early Interrupt control exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsEarlyInterruptControl(ADCHS_MODULE_ID index); Returns Existence of the Early Interrupt control feature: • true - The Early Interrupt control feature is supported on the device • false - The Early Interrupt control feature is not supported on the device Description This function identifies whether the Early Interrupt control feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_EarlyInterruptEnable • PLIB_ADCHS_EarlyInterruptDisable • PLIB_ADCHS_AnalogInputEarlyInterruptEnable • PLIB_ADCHS_AnalogInputEarlyInterruptDisable • PLIB_ADCHS_AnalogInputEarlyInterruptIsReady Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsEarlyInterruptControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the ADCHS module File plib_adchs.h C bool PLIB_ADCHS_ExistsEnableControl(ADCHS_MODULE_ID index); Returns Existence of the EnableControl feature: • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_Enable • PLIB_ADCHS_Disable Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 190 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsEnableControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsExternalConversionRequestControl Function Identifies whether the External Convert feature exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsExternalConversionRequestControl(ADCHS_MODULE_ID index); Returns Existence of the External Convert feature: • true - The External Convert feature is supported on the device • false - The External Convert feature is not supported on the device Description This function identifies whether the External Convert feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_ExternalConversionRequestEnable • PLIB_ADCHS_ExternalConversionRequestDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsExternalConversionRequestControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsFIFO Function Identifies whether the FIFO exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsFIFO(ADCHS_MODULE_ID index); Returns Existence of the FIFO feature: • true - The FIFO feature is supported on the device Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 191 • false - The FIFO feature is not supported on the device Description This function identifies whether the FIFO feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_FIFORead • PLIB_ADCHS_FIFODataIsAvailable • PLIB_ADCHS_FIFODataReadyInterruptEnable • PLIB_ADCHS_FIFODataReadyInterruptDisable • PLIB_ADCHS_FIFOEnable • PLIB_ADCHS_FIFODisable • PLIB_ADCHS_FIFOSourceSelect • PLIB_ADCHS_FIFODataCountGet • PLIB_ADCHS_FIFOSourceGet • PLIB_ADCHS_FIFOErrorHasOccurred • PLIB_ADCHS_FIFODataIsNegative Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsFIFO( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsManualControl Function Identifies whether the Manual control exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsManualControl(ADCHS_MODULE_ID index); Returns Existence of the Manual control feature: • true - The Manual control feature is supported on the device • false - The Manual control feature is not supported on the device Description This function identifies whether the Manual control feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_SoftwareSamplingStart • PLIB_ADCHS_SoftwareSamplingStop • PLIB_ADCHS_SoftwareConversionStart • PLIB_ADCHS_SoftwareConversionInputSelect Remarks None. Preconditions None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 192 Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsManualControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsTriggerControl Function Identifies whether the Trigger control exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsTriggerControl(ADCHS_MODULE_ID index); Returns Existence of the Trigger control feature: • true - The Trigger control feature is supported on the device • false - The Trigger control feature is not supported on the device Description This function identifies whether the Trigger control feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_AnalogInputLevelTriggerSet • PLIB_ADCHS_AnalogInputEdgeTriggerSet • PLIB_ADCHS_AnalogInputTriggerSourceSelect • PLIB_ADCHS_GlobalSoftwareTriggerEnable • PLIB_ADCHS_GlobalLevelSoftwareTriggerEnable • PLIB_ADCHS_GlobalLevelSoftwareTriggerDisable • PLIB_ADCHS_TriggerSuspendEnable • PLIB_ADCHS_TriggerSuspendDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsTriggerControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsTriggerSampleControl Function Identifies whether the Trigger Sample control feature exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsTriggerSampleControl(ADCHS_MODULE_ID index); Returns Existence of the Trigger Sample control feature: • true - The Trigger Sample control feature is supported on the device Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 193 • false - The Trigger Sample control feature is not supported on the device Description This function whether the Trigger Sample control feature exists on the ADCHS module. When this function returns true, this function is supported on the device: • PLIB_ADCHS_ChannelTriggerSampleSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsTriggerSampleControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsTurboMode Function Identifies whether the Turbo mode feature exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsTurboMode(ADCHS_MODULE_ID index); Returns Existence of the Turbo mode feature: • true - The Turbo mode feature is supported on the device • false - The Turbo mode feature is not supported on the device Description This function identifies whether the Turbo mode feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_TurboModeEnable • PLIB_ADCHS_TurboModeDisable • PLIB_ADCHS_TurboModeErrorHasOccurred • PLIB_ADCHS_TurboModeChannelSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsTurboMode( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsUpdateReadyControl Function Identifies whether the Update Ready feature exists on the ADCHS module. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 194 File plib_adchs.h C bool PLIB_ADCHS_ExistsUpdateReadyControl(ADCHS_MODULE_ID index); Returns Existence of the Update Ready feature: • true - The Update Ready feature is supported on the device • false - The Update Ready feature is not supported on the device Description This function identifies whether the Update Ready feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptEnable • PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptDisable • PLIB_ADCHS_ControlRegistersCanBeUpdated Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsUpdateReadyControl( ADCHS_MODULE_ID index ) PLIB_ADCHS_ExistsVREFControl Function Identifies whether the VREF control exists on the ADCHS module. File plib_adchs.h C bool PLIB_ADCHS_ExistsVREFControl(ADCHS_MODULE_ID index); Returns Existence of the VREF control feature: • true - The VREF control feature is supported on the device • false - The VREF control feature is not supported on the device Description This function identifies whether the VREF control feature is available on the ADCHS module. When this function returns true, these functions are supported on the device: • PLIB_ADCHS_VREFIsReady • PLIB_ADCHS_VREFFaultHasOccurred • PLIB_ADCHS_VREFReadyInterruptEnable • PLIB_ADCHS_VREFReadyInterruptDisable • PLIB_ADCHS_VREFFaultInterruptEnable • PLIB_ADCHS_VREFFaultInterruptDisable Remarks None. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 195 Preconditions None. Parameters Parameters Description index Identifier for the device instance. Function PLIB_ADCHS_ExistsVREFControl( ADCHS_MODULE_ID index ) n) Data Types and Constants ADCHS_AN_INPUT_ID Enumeration Type for identifying the available ADC Inputs File help_plib_adchs.h C typedef enum { ADCHS_AN0, ADCHS_AN1, ADCHS_AN2, ADCHS_AN3, ADCHS_AN4, ADCHS_AN5, ADCHS_AN6, ADCHS_AN7, ADCHS_AN8, ADCHS_AN9, ADCHS_AN10, ADCHS_AN11, ADCHS_AN12, ADCHS_AN13, ADCHS_AN14, ADCHS_AN15, ADCHS_AN16, ADCHS_AN17, ADCHS_AN18, ADCHS_AN19, ADCHS_AN20, ADCHS_AN21, ADCHS_AN22, ADCHS_AN23, ADCHS_AN24, ADCHS_AN25, ADCHS_AN26, ADCHS_AN27, ADCHS_AN28, ADCHS_AN29, ADCHS_AN30, ADCHS_AN31, ADCHS_AN32, ADCHS_AN33, ADCHS_AN34, ADCHS_AN35, ADCHS_AN36, ADCHS_AN37, ADCHS_AN38, ADCHS_AN39, ADCHS_AN40, ADCHS_AN41, ADCHS_AN42, ADCHS_AN43, ADCHS_AN44, ADCHS_AN50, Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 196 ADCHS_AN51 , ADCHS_AN52 , ADCHS_AN53 , ADCHS_AN54 , ADCHS_AN55 , ADCHS_AN56 , ADCHS_AN57 , ADCHS_AN58 , ADCHS_AN59 , ADCHS_AN60 , ADCHS_AN61 , ADCHS_AN62 , ADCHS_AN63 } ADCHS_AN_INPUT_ID; Members Members Description ADCHS_AN0 Analog Input AN0 ADCHS_AN1 Analog Input AN1 ADCHS_AN2 Analog Input AN2 ADCHS_AN3 Analog Input AN3 ADCHS_AN4 Analog Input AN4 ADCHS_AN5 Analog Input AN5 ADCHS_AN6 Analog Input AN6 ADCHS_AN7 Analog Input AN7 ADCHS_AN8 Analog Input AN8 ADCHS_AN9 Analog Input AN9 ADCHS_AN10 Analog Input AN10 ADCHS_AN11 Analog Input AN11 ADCHS_AN12 Analog Input AN12 ADCHS_AN13 Analog Input AN13 ADCHS_AN14 Analog Input AN14 ADCHS_AN15 Analog Input AN15 ADCHS_AN16 Analog Input AN16 ADCHS_AN17 Analog Input AN17 ADCHS_AN18 Analog Input AN18 ADCHS_AN19 Analog Input AN19 ADCHS_AN20 Analog Input AN20 ADCHS_AN21 Analog Input AN21 ADCHS_AN22 Analog Input AN22 ADCHS_AN23 Analog Input AN23 ADCHS_AN24 Analog Input AN24 ADCHS_AN25 Analog Input AN25 ADCHS_AN26 Analog Input AN26 ADCHS_AN27 Analog Input AN27 ADCHS_AN28 Analog Input AN28 ADCHS_AN29 Analog Input AN29 ADCHS_AN30 Analog Input AN30 ADCHS_AN31 Analog Input AN31 ADCHS_AN32 Analog Input AN32 ADCHS_AN33 Analog Input AN33 ADCHS_AN34 Analog Input AN34 ADCHS_AN35 Analog Input AN35 ADCHS_AN36 Analog Input AN36 ADCHS_AN37 Analog Input AN37 ADCHS_AN38 Analog Input AN38 ADCHS_AN39 Analog Input AN39 ADCHS_AN40 Analog Input AN40 ADCHS_AN41 Analog Input AN41 Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 197 ADCHS_AN42 Analog Input AN42 ADCHS_AN43 Analog Input AN43 ADCHS_AN44 Analog Input AN44 ADCHS_AN50 Analog Input AN50 ADCHS_AN51 Analog Input AN51 ADCHS_AN52 Analog Input AN52 ADCHS_AN53 Analog Input AN53 ADCHS_AN54 Analog Input AN54 ADCHS_AN55 Analog Input AN55 ADCHS_AN56 Analog Input AN56 ADCHS_AN57 Analog Input AN57 ADCHS_AN58 Analog Input AN58 ADCHS_AN59 Analog Input AN59 ADCHS_AN60 Analog Input AN60 ADCHS_AN61 Analog Input AN61 ADCHS_AN62 Analog Input AN62 ADCHS_AN63 Analog Input AN63 Description ADC Analog Input ID Type for identifying the available ADC Inputs, regardless of Class. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_CHARGEPUMP_MODE Enumeration Defines the selection for the charge pump. File help_plib_adchs.h C typedef enum { ADCHS_CHARGEPUMP_DISABLE, ADCHS_CHARGEPUMP_ENABLE } ADCHS_CHARGEPUMP_MODE; Members Members Description ADCHS_CHARGEPUMP_DISABLE Charge pump is disabled ADCHS_CHARGEPUMP_ENABLE Charge pump is enabled Description ADCHS Charge pump setting This data type defines the state of the charge pump as either enabled or disabled. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_CLOCK_SOURCE Enumeration Defines the ADCHS Clock Source Select. File help_plib_adchs.h C typedef enum { Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 198 ADCHS_CLOCK_SOURCE_PBCLK, ADCHS_CLOCK_SOURCE_FRC, ADCHS_CLOCK_SOURCE_RFCLK3, ADCHS_CLOCK_SOURCE_SYSCLK } ADCHS_CLOCK_SOURCE; Members Members Description ADCHS_CLOCK_SOURCE_PBCLK TAD clock set to peripheral bus clock (PBCLK) ADCHS_CLOCK_SOURCE_FRC TAD clock set to FRC ADCHS_CLOCK_SOURCE_RFCLK3 TAD clock set to REFCLK3 ADCHS_CLOCK_SOURCE_SYSCLK TAD clock set to SYSCLK (TCY) Description ADCHS Clock source selection This enumeration data type defines the ADCHS Clock Source Select. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_CVD_CAPACITOR Enumeration Defines the value of the internal capacitor during CVD mode. File help_plib_adchs.h C typedef enum { ADCHS_CVD_CAPACITOR_0PF, ADCHS_CVD_CAPACITOR_2_5PF, ADCHS_CVD_CAPACITOR_5PF, ADCHS_CVD_CAPACITOR_7_5PF, ADCHS_CVD_CAPACITOR_10PF, ADCHS_CVD_CAPACITOR_12_5PF, ADCHS_CVD_CAPACITOR_15PF, ADCHS_CVD_CAPACITOR_17_5PF } ADCHS_CVD_CAPACITOR; Members Members Description ADCHS_CVD_CAPACITOR_0PF While in CVD mode, internal capacitor is 0pF ADCHS_CVD_CAPACITOR_2_5PF While in CVD mode, internal capacitor is 2.5pF ADCHS_CVD_CAPACITOR_5PF While in CVD mode, internal capacitor is 5pF ADCHS_CVD_CAPACITOR_7_5PF While in CVD mode, internal capacitor is 7.5pF ADCHS_CVD_CAPACITOR_10PF While in CVD mode, internal capacitor is 10pF ADCHS_CVD_CAPACITOR_12_5PF While in CVD mode, internal capacitor is 12.5pF ADCHS_CVD_CAPACITOR_15PF While in CVD mode, internal capacitor is 15pF ADCHS_CVD_CAPACITOR_17_5PF While in CVD mode, internal capacitor is 17.5pF Description ADCHS CVD capacitor selection This data type defines the value of the internal capacitor during CVD mode. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_DATA_RESOLUTION Enumeration Identifies the resolution of the ADC output. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 199 File help_plib_adchs.h C typedef enum { ADCHS_DATA_RESOLUTION_6BIT, ADCHS_DATA_RESOLUTION_8BIT, ADCHS_DATA_RESOLUTION_10BIT, ADCHS_DATA_RESOLUTION_12BIT } ADCHS_DATA_RESOLUTION; Members Members Description ADCHS_DATA_RESOLUTION_6BIT ADC Output Data resolution is 6 bits ADCHS_DATA_RESOLUTION_8BIT ADC Output Data resolution is 8 bits ADCHS_DATA_RESOLUTION_10BIT ADC Output Data resolution is 10 bits ADCHS_DATA_RESOLUTION_12BIT ADC Output Data resolution is 12 bits Description ADC Data Resolution This data type is used to identify the resolution of the ADC output. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_DIGITAL_COMPARATOR_ID Enumeration Identifies the supported Digital Comparators. File help_plib_adchs.h C typedef enum { ADCHS_DIGITAL_COMPARATOR_1, ADCHS_DIGITAL_COMPARATOR_2, ADCHS_DIGITAL_COMPARATOR_3, ADCHS_DIGITAL_COMPARATOR_4, ADCHS_DIGITAL_COMPARATOR_5, ADCHS_DIGITAL_COMPARATOR_6, ADCHS_NUMBER_OF_DIGITAL_COMPARATOR } ADCHS_DIGITAL_COMPARATOR_ID; Members Members Description ADCHS_DIGITAL_COMPARATOR_1 Digital Comparator 1 ADCHS_DIGITAL_COMPARATOR_2 Digital Comparator 2 ADCHS_DIGITAL_COMPARATOR_3 Digital Comparator 3 ADCHS_DIGITAL_COMPARATOR_4 Digital Comparator 4 ADCHS_DIGITAL_COMPARATOR_5 Digital Comparator 5 ADCHS_DIGITAL_COMPARATOR_6 Digital Comparator 6 ADCHS_NUMBER_OF_DIGITAL_COMPARATOR Number of Digital Comparators Description ADCHS Digital Comparator This enumeration identifies all supported Digital Comparators for this ADCHS channel. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 200 ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT Enumeration Identifies the Digital Filter averaging sample count. File help_plib_adchs.h C typedef enum { ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_2, ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_4, ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_8, ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_16, ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_32, ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_64, ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_128, ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_256 } ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT; Members Members Description ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_2 Averaging is performed on 2 samples ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_4 Averaging is performed on 4 samples ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_8 Averaging is performed on 8 samples ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_16 Averaging is performed on 16 samples ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_32 Averaging is performed on 32 samples ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_64 Averaging is performed on 64 samples ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_128 Averaging is performed on 128 samples ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT_256 Averaging is performed on 256 samples Description ADCHS Averaging sample This enumeration identifies all supported digital Filter averaging sample count for this ADCHS channel. Once, the set number of samples are acquired by ADC channel, it starts the averaging process. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_DIGITAL_FILTER_ID Enumeration Identifies the supported Digital Filters. File help_plib_adchs.h C typedef enum { ADCHS_DIGITAL_FILTER_1, ADCHS_DIGITAL_FILTER_2, ADCHS_DIGITAL_FILTER_3, ADCHS_DIGITAL_FILTER_4, ADCHS_DIGITAL_FILTER_5, ADCHS_DIGITAL_FILTER_6, ADCHS_NUMBER_OF_DIGITAL_FILTER } ADCHS_DIGITAL_FILTER_ID; Members Members Description ADCHS_DIGITAL_FILTER_1 Digital Filter 1 ADCHS_DIGITAL_FILTER_2 Digital Filter 2 ADCHS_DIGITAL_FILTER_3 Digital Filter 3 ADCHS_DIGITAL_FILTER_4 Digital Filter 4 Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 201 ADCHS_DIGITAL_FILTER_5 Digital Filter 5 ADCHS_DIGITAL_FILTER_6 Digital Filter 6 ADCHS_NUMBER_OF_DIGITAL_FILTER Number of Digital Filters Description ADCHS Digital Filter This enumeration identifies all supported digital Filters for this ADCHS channel. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO Enumeration Identifies the supported Digital Filter oversampling ratios. File help_plib_adchs.h C typedef enum { ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_4X, ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_16X, ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_64X, ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_256X, ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_2X, ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_8X, ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_32X, ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_128X } ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO; Members Members Description ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_4X 4x oversampling, shift sum 1 bit to right, output data is 13 bits ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_16X 16x oversampling, shift sum 2 bits to right, output data is 14 bits ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_64X 64x oversampling, shift sum 3 bits to right, output data is 15 bits ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_256X 256x oversampling, shift sum 4 bits to right, output data is 16 bits ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_2X 2x oversampling, shift sum 0 bits to right, output data is in 12.1 format ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_8X 8x oversampling, shift sum 1 bit to right, output data is in 13.1 format ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_32X 32x oversampling, shift sum 2 bits to right, output data is in 14.1 format ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO_128X 128x oversampling, shift sum 3 bit to right, output data is in 15.1 format Description ADCHS Oversampling Ratio This enumeration identifies all supported digital Filter oversampling ratios for this ADCHS channel. Oversampling ratios determine the number of samples used to generate a single output and the resulting resolution and format. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_DIGITAL_FILTER_SIGNIFICANT_BITS Enumeration Data length of digital filter. File help_plib_adchs.h C typedef enum { ADCHS_DIGITAL_FILTER_SIGNIFICANT_FIRST_12BITS, ADCHS_DIGITAL_FILTER_SIGNIFICANT_ALL_16BITS } ADCHS_DIGITAL_FILTER_SIGNIFICANT_BITS; Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 202 Members Members Description ADCHS_DIGITAL_FILTER_SIGNIFICANT_FIRST_12BITS Output of digital filter has only first 12 bits significant (remaining 4 zeros) ADCHS_DIGITAL_FILTER_SIGNIFICANT_ALL_16BITS Output of digital filter has all 16 bits significant Description ADCHS Digital filter data length The output of digital filter can be set as all 16-bit to be significant or only first 12-bit significant followed by 4 zeros. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_DMA_BUFFER_LENGTH Enumeration Defines the length of the DMA buffer length. File help_plib_adchs.h C typedef enum { ADCHS_DMA_BUFFER_LENGTH_2BYTES, ADCHS_DMA_BUFFER_LENGTH_4BYTES, ADCHS_DMA_BUFFER_LENGTH_8BYTES, ADCHS_DMA_BUFFER_LENGTH_16BYTES, ADCHS_DMA_BUFFER_LENGTH_32BYTES, ADCHS_DMA_BUFFER_LENGTH_64BYTES, ADCHS_DMA_BUFFER_LENGTH_128BYTES, ADCHS_DMA_BUFFER_LENGTH_256BYTES } ADCHS_DMA_BUFFER_LENGTH; Members Members Description ADCHS_DMA_BUFFER_LENGTH_2BYTES Allocate 2 bytes in RAM for each analog input ADCHS_DMA_BUFFER_LENGTH_4BYTES Allocate 4 bytes in RAM for each analog input ADCHS_DMA_BUFFER_LENGTH_8BYTES Allocate 8 bytes in RAM for each analog input ADCHS_DMA_BUFFER_LENGTH_16BYTES Allocate 16 bytes in RAM for each analog input ADCHS_DMA_BUFFER_LENGTH_32BYTES Allocate 32 bytes in RAM for each analog input ADCHS_DMA_BUFFER_LENGTH_64BYTES Allocate 64 bytes in RAM for each analog input ADCHS_DMA_BUFFER_LENGTH_128BYTES Allocate 128 bytes in RAM for each analog input ADCHS_DMA_BUFFER_LENGTH_256BYTES Allocate 256 bytes in RAM for each analog input Description ADCHS Class-1 DMA buffer length This data type defines the length of the DMA buffer (in bytes). Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_DMA_COUNT Enumeration Defines the enable/disable of the count feature for DMA. File help_plib_adchs.h C typedef enum { ADCHS_DMA_COUNT_DISABLE, ADCHS_DMA_COUNT_ENABLE } ADCHS_DMA_COUNT; Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 203 Members Members Description ADCHS_DMA_COUNT_DISABLE DMA does not keep count of number of data saved by DMA ADCHS_DMA_COUNT_ENABLE DMA keeps count of number of data saved by DMA Description ADCHS DMA count enable This data type defines whether or not the DMA should count the number of samples and store it in DMA RAM location. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK Enumeration Defines the number of clocks prior to the arrival of valid data that the associated interrupt is generated. File help_plib_adchs.h C typedef enum { ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1, ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_2, ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_3, ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_4, ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_5, ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_6, ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_7, ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_8 } ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK; Members Members Description ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 The data ready interrupt is generated 1 ADC clock prior to end of conversion ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_2 The data ready interrupt is generated 2 ADC clock prior to end of conversion ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_3 The data ready interrupt is generated 3 ADC clock prior to end of conversion ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_4 The data ready interrupt is generated 4 ADC clock prior to end of conversion ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_5 The data ready interrupt is generated 5 ADC clock prior to end of conversion ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_6 The data ready interrupt is generated 6 ADC clock prior to end of conversion ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_7 The data ready interrupt is generated 7 ADC clock prior to end of conversion ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_8 The data ready interrupt is generated 8 ADC clock prior to end of conversion Description ADCHS Early interrupt prior clock selection This data type defines the number of clocks prior to the arrival of valid data that the associated interrupt is generated. All options are available when the selected resolution for converted data is 12-bit or 10-bit. For a resolution of 8-bit, options from ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 to ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_6 are valid. For a resolution of 6-bit, options from ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_1 to ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK_4 are valid. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_FAST_SYNC_PERIPHERAL_CLOCK Enumeration Defines the selection of the fast synchronous peripheral clock. File help_plib_adchs.h C typedef enum { Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 204 ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_DISABLE, ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_ENABLE } ADCHS_FAST_SYNC_PERIPHERAL_CLOCK; Members Members Description ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_DISABLE Peripheral clock is not used for ADCHS ADCHS_FAST_SYNC_PERIPHERAL_CLOCK_ENABLE Peripheral clock is used for ADCHS Description ADCHS Fast synchronous peripheral clock mode This data type defines whether the fast synchronous peripheral clock to the ADCHS channel is enabled or disabled. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_FAST_SYNC_SYSTEM_CLOCK Enumeration Defines the selection of the fast synchronous system clock. File help_plib_adchs.h C typedef enum { ADCHS_FAST_SYNC_SYSTEM_CLOCK_DISABLE, ADCHS_FAST_SYNC_SYSTEM_CLOCK_ENABLE } ADCHS_FAST_SYNC_SYSTEM_CLOCK; Members Members Description ADCHS_FAST_SYNC_SYSTEM_CLOCK_DISABLE System clock is not used for ADCHS ADCHS_FAST_SYNC_SYSTEM_CLOCK_ENABLE System clock is used for ADCHS Description ADCHS Fast synchronous system clock mode This data type defines whether the fast synchronous system clock to ADCHS channel is enabled or disabled. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_INPUT_MODE Enumeration Defines the available modes for the selected input. File help_plib_adchs.h C typedef enum { ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR, ADCHS_INPUT_MODE_SINGLE_ENDED_TWOS_COMP, ADCHS_INPUT_MODE_DIFFERENTIAL_UNIPOLAR, ADCHS_INPUT_MODE_DIFFERENTIAL_TWOS_COMP } ADCHS_INPUT_MODE; Members Members Description ADCHS_INPUT_MODE_SINGLE_ENDED_UNIPOLAR Single-ended input, Unipolar encoded ADCHS_INPUT_MODE_SINGLE_ENDED_TWOS_COMP Single-ended input, two's compliment encoded ADCHS_INPUT_MODE_DIFFERENTIAL_UNIPOLAR Differential input, Unipolar encoded ADCHS_INPUT_MODE_DIFFERENTIAL_TWOS_COMP Differential input, two's compliment encoded Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 205 Description ADCHS Input Mode This data type defines the available modes for the selected input. Remarks None. ADCHS_INTERRUPT_BIT_SHIFT_LEFT Enumeration Identifies the bits shift for calculating the interrupt vector. File help_plib_adchs.h C typedef enum { ADCHS_INTERRUPT_BIT_SHIFT_LEFT_0_BITS, ADCHS_INTERRUPT_BIT_SHIFT_LEFT_1_BITS, ADCHS_INTERRUPT_BIT_SHIFT_LEFT_2_BITS, ADCHS_INTERRUPT_BIT_SHIFT_LEFT_3_BITS, ADCHS_INTERRUPT_BIT_SHIFT_LEFT_4_BITS, ADCHS_INTERRUPT_BIT_SHIFT_LEFT_5_BITS, ADCHS_INTERRUPT_BIT_SHIFT_LEFT_6_BITS, ADCHS_INTERRUPT_BIT_SHIFT_LEFT_7_BITS } ADCHS_INTERRUPT_BIT_SHIFT_LEFT; Members Members Description ADCHS_INTERRUPT_BIT_SHIFT_LEFT_0_BITS Bit shift by 0 bits ADCHS_INTERRUPT_BIT_SHIFT_LEFT_1_BITS Bit shift by 1 bits ADCHS_INTERRUPT_BIT_SHIFT_LEFT_2_BITS Bit shift by 2 bits ADCHS_INTERRUPT_BIT_SHIFT_LEFT_3_BITS Bit shift by 3 bits ADCHS_INTERRUPT_BIT_SHIFT_LEFT_4_BITS Bit shift by 4 bits ADCHS_INTERRUPT_BIT_SHIFT_LEFT_5_BITS Bit shift by 5 bits ADCHS_INTERRUPT_BIT_SHIFT_LEFT_6_BITS Bit shift by 6 bits ADCHS_INTERRUPT_BIT_SHIFT_LEFT_7_BITS Bit shift by 7 bits Description ADCHS Interrupt vector shift bits Interrupt vector address, is calculated by (Base_Address + x << vector_shift), where 'x' is the smallest active channel ID from the status register (AD1DSTAT1 or 2) registers (which has highest priority). This enumeration identifies all the possible bits shift. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_OUTPUT_DATA_FORMAT Enumeration Defines the selection for the output data format. File help_plib_adchs.h C typedef enum { ADCHS_OUTPUT_DATA_FORMAT_INTEGER, ADCHS_OUTPUT_DATA_FORMAT_FRACTIONAL } ADCHS_OUTPUT_DATA_FORMAT; Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 206 Members Members Description ADCHS_OUTPUT_DATA_FORMAT_INTEGER Output data format is integer ADCHS_OUTPUT_DATA_FORMAT_FRACTIONAL Output data format is fractional Description ADCHS output data format The output of ADC can be specified as either integer or fractional. This enum defines the setting of the output data format. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_SCAN_TRIGGER_SENSITIVE Enumeration Trigger level for scan trigger. File help_plib_adchs.h C typedef enum { ADCHS_SCAN_TRIGGER_SENSITIVE_EDGE, ADCHS_SCAN_TRIGGER_SENSITIVE_LEVEL } ADCHS_SCAN_TRIGGER_SENSITIVE; Members Members Description ADCHS_SCAN_TRIGGER_SENSITIVE_EDGE Scan trigger is edge sensitive ADCHS_SCAN_TRIGGER_SENSITIVE_LEVEL Scan trigger is level sensitive Description ADCHS scan trigger level The scan trigger can be configured to be sensitive to level or sensitive to edge. This data type defines the different configurations. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_SCAN_TRIGGER_SOURCE Enumeration Defines the ADCHS Channel Scan Trigger Source Selections. File help_plib_adchs.h C typedef enum { ADCHS_SCAN_TRIGGER_SOURCE_NONE, ADCHS_SCAN_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE, ADCHS_SCAN_TRIGGER_SOURCE_SOFTWARE_LEVEL, ADCHS_SCAN_TRIGGER_SOURCE_INT0, ADCHS_SCAN_TRIGGER_SOURCE_TMR1_MATCH, ADCHS_SCAN_TRIGGER_SOURCE_TMR3_MATCH, ADCHS_SCAN_TRIGGER_SOURCE_TMR5_MATCH, ADCHS_SCAN_TRIGGER_SOURCE_OC1, ADCHS_SCAN_TRIGGER_SOURCE_OC3, ADCHS_SCAN_TRIGGER_SOURCE_OC5, ADCHS_SCAN_TRIGGER_SOURCE_COUT1, ADCHS_SCAN_TRIGGER_SOURCE_COUT2 } ADCHS_SCAN_TRIGGER_SOURCE; Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 207 Members Members Description ADCHS_SCAN_TRIGGER_SOURCE_NONE No scan trigger source is selected ADCHS_SCAN_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE Global Software edge trigger selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_SOFTWARE_LEVEL Level Software trigger selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_INT0 Interrupt 0 (INT0) selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_TMR1_MATCH Timer 1 Match (TMR1) selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_TMR3_MATCH Timer 3 Match (TMR3) selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_TMR5_MATCH Timer 5 Match (TMR5) selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_OC1 Output Compare 1(OC1) period end selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_OC3 Output Compare 3 (OC3) period end selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_OC5 Output Compare 5 (OC5) period end selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_COUT1 Comparator Output 1 selected as scan trigger source ADCHS_SCAN_TRIGGER_SOURCE_COUT2 Comparator Output 2 selected as scan trigger source Description ADCHS Channel Scan Trigger Source Select This data type defines the ADCHS Channel Scan Trigger Source Selections. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_TRIGGER_SOURCE Enumeration Defines the ADCHS Trigger Source Selections. File help_plib_adchs.h C typedef enum { ADCHS_TRIGGER_SOURCE_NONE, ADCHS_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE, ADCHS_TRIGGER_SOURCE_SOFTWARE_LEVEL, ADCHS_TRIGGER_SOURCE_STRIG, ADCHS_TRIGGER_SOURCE_INT0, ADCHS_TRIGGER_SOURCE_TMR1_MATCH, ADCHS_TRIGGER_SOURCE_TMR3_MATCH, ADCHS_TRIGGER_SOURCE_TMR5_MATCH, ADCHS_TRIGGER_SOURCE_OC1, ADCHS_TRIGGER_SOURCE_OC3, ADCHS_TRIGGER_SOURCE_OC5, ADCHS_TRIGGER_SOURCE_COUT1, ADCHS_TRIGGER_SOURCE_COUT2 } ADCHS_TRIGGER_SOURCE; Members Members Description ADCHS_TRIGGER_SOURCE_NONE No trigger source is selected ADCHS_TRIGGER_SOURCE_GLOBAL_SOFTWARE_EDGE Global Software edge trigger selected as trigger source ADCHS_TRIGGER_SOURCE_SOFTWARE_LEVEL Level Software trigger selected as trigger source ADCHS_TRIGGER_SOURCE_STRIG Scan trigger source ADCHS_TRIGGER_SOURCE_INT0 Interrupt 0 (INT0) selected as trigger source ADCHS_TRIGGER_SOURCE_TMR1_MATCH Timer 1 Match (TMR1) selected as trigger source ADCHS_TRIGGER_SOURCE_TMR3_MATCH Timer 3 Match (TMR3) selected as trigger source ADCHS_TRIGGER_SOURCE_TMR5_MATCH Timer 5 Match (TMR5) selected as trigger source ADCHS_TRIGGER_SOURCE_OC1 Output Compare 1(OC1) period end selected as trigger source ADCHS_TRIGGER_SOURCE_OC3 Output Compare 3 (OC3) period end selected as trigger source ADCHS_TRIGGER_SOURCE_OC5 Output Compare 5 (OC5) period end selected as trigger source ADCHS_TRIGGER_SOURCE_COUT1 Comparator Output 1 selected as trigger source Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 208 ADCHS_TRIGGER_SOURCE_COUT2 Comparator Output 2 selected as trigger source Description ADCHS Trigger Source Select This data type defines the ADCHS Trigger Source Selections. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_VREF_SOURCE Enumeration Defines the ADCHS VREF Source Select. File help_plib_adchs.h C typedef enum { ADCHS_VREF_AVDD_AVSS, ADCHS_VREF_EXTVREFP_AVSS, ADCHS_VREF_AVDD_EXTVREFN, ADCHS_VREF_EXTVREFP_EXTVREFN, ADCHS_VREF_INTVREFP_INTVREFN, ADCHS_VREF_INTVREFP_EXTVREFN, ADCHS_VREF_INTVREFP_AVSS, ADCHS_VREF_AVDD_INTVREFN } ADCHS_VREF_SOURCE; Members Members Description ADCHS_VREF_AVDD_AVSS Reference voltage set to AVDD and AVSS ADCHS_VREF_EXTVREFP_AVSS Reference voltage set to external VREF positive and AVSS ADCHS_VREF_AVDD_EXTVREFN Reference voltage set to AVDD and external VREF negative ADCHS_VREF_EXTVREFP_EXTVREFN Reference voltage set to external VREF positive and external VREF negative ADCHS_VREF_INTVREFP_INTVREFN Reference voltage set to internal VREF positive and internal VREF negative ADCHS_VREF_INTVREFP_EXTVREFN Reference voltage set to internal VREF positive and external VREF negative ADCHS_VREF_INTVREFP_AVSS Reference voltage set to internal VREF positive and AVSS ADCHS_VREF_AVDD_INTVREFN Reference voltage set to AVDD positive and internal VREF negative Description ADCHS VREF Source Select This data type defines the ADCHS Reference Voltage (VREF) Source Select. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_WARMUP_CLOCK Enumeration Identifies the number of clocks before the channel can be ready File help_plib_adchs.h C typedef enum { ADCHS_WARMUP_CLOCK_16, ADCHS_WARMUP_CLOCK_32, ADCHS_WARMUP_CLOCK_64, ADCHS_WARMUP_CLOCK_128, ADCHS_WARMUP_CLOCK_256, ADCHS_WARMUP_CLOCK_512, ADCHS_WARMUP_CLOCK_1024, ADCHS_WARMUP_CLOCK_2048, Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 209 ADCHS_WARMUP_CLOCK_4096, ADCHS_WARMUP_CLOCK_8192, ADCHS_WARMUP_CLOCK_16384, ADCHS_WARMUP_CLOCK_32768 } ADCHS_WARMUP_CLOCK; Members Members Description ADCHS_WARMUP_CLOCK_16 Warm-up time is 16 ADC clocks ADCHS_WARMUP_CLOCK_32 Warm-up time is 32 ADC clocks ADCHS_WARMUP_CLOCK_64 Warm-up time is 64 ADC clocks ADCHS_WARMUP_CLOCK_128 Warm-up time is 128 ADC clocks ADCHS_WARMUP_CLOCK_256 Warm-up time is 256 ADC clocks ADCHS_WARMUP_CLOCK_512 Warm-up time is 512 ADC clocks ADCHS_WARMUP_CLOCK_1024 Warm-up time is 1024 ADC clocks ADCHS_WARMUP_CLOCK_2048 Warm-up time is 2048 ADC clocks ADCHS_WARMUP_CLOCK_4096 Warm-up time is 4096 ADC clocks ADCHS_WARMUP_CLOCK_8192 Warm-up time is 8192 ADC clocks ADCHS_WARMUP_CLOCK_16384 Warm-up time is 16384 ADC clocks ADCHS_WARMUP_CLOCK_32768 Warm-up time is 32768 ADC clocks Description ADCHS Wakeup warm-up clocks When the analog section of an ADC channel is enabled, the channel needs a certain amount of warm-up time before it can be ready to perform conversion. This enumeration contains the various warm-up time in terms of the number of clocks. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_MODULE_ID Enumeration Identifies the number of ADC supported. File help_plib_adchs.h C typedef enum { ADCHS_ID_0, ADCHS_NUMBER_OF_MODULES } ADCHS_MODULE_ID; Members Members Description ADCHS_ID_0 ADC ID 0 ADCHS_NUMBER_OF_MODULES Number of available ADC. Description This enumeration identifies the available ADC. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Refer to the specific device data sheet to determine how many ADC modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. ADCHS_CHANNEL_INP_SEL Enumeration Defines the alternate input selection for channels 0 to 6. File help_plib_adchs.h Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 210 C typedef enum { ADCHS_CHANNEL_0_DEFAULT_INP_AN0, ADCHS_CHANNEL_0_ALTERNATE_INP_AN45, ADCHS_CHANNEL_1_DEFAULT_INP_AN1, ADCHS_CHANNEL_1_ALTERNATE_INP_AN46, ADCHS_CHANNEL_2_DEFAULT_INP_AN2, ADCHS_CHANNEL_2_ALTERNATE_INP_AN47, ADCHS_CHANNEL_3_DEFAULT_INP_AN3, ADCHS_CHANNEL_3_ALTERNATE_INP_AN48, ADCHS_CHANNEL_4_DEFAULT_INP_AN4, ADCHS_CHANNEL_4_ALTERNATE_INP_AN49 } ADCHS_CHANNEL_INP_SEL; Members Members Description ADCHS_CHANNEL_0_DEFAULT_INP_AN0 AN0 is the default input for Channel 0 ADCHS_CHANNEL_0_ALTERNATE_INP_AN45 AN45 is the alternate input for Channel 0 ADCHS_CHANNEL_1_DEFAULT_INP_AN1 AN1 is the default input for Channel 1 ADCHS_CHANNEL_1_ALTERNATE_INP_AN46 AN46 is the alternate input for Channel 1 ADCHS_CHANNEL_2_DEFAULT_INP_AN2 AN2 is the default input for Channel 2 ADCHS_CHANNEL_2_ALTERNATE_INP_AN47 AN47 is the alternate input for Channel 2 ADCHS_CHANNEL_3_DEFAULT_INP_AN3 AN3 is the default input for Channel 3 ADCHS_CHANNEL_3_ALTERNATE_INP_AN48 AN48 is the alternate input for Channel 3 ADCHS_CHANNEL_4_DEFAULT_INP_AN4 AN4 is the default input for Channel 4 ADCHS_CHANNEL_4_ALTERNATE_INP_AN49 AN49 is the alternate input for Channel 4 Description ADCHS Alternate input selection for channel- 0 to 6. This data type defines the possible alternate input selections for channels 0 to 6. For channel 7, alternate selection does not exist. Passing the values for channel 7 will return an error. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_CHANNEL_ID Enumeration Identifies the ADC channel from 0 to 7. File help_plib_adchs.h C typedef enum { ADCHS_CHANNEL_0, ADCHS_CHANNEL_1, ADCHS_CHANNEL_2, ADCHS_CHANNEL_3, ADCHS_CHANNEL_4, ADCHS_CHANNEL_5, ADCHS_CHANNEL_6, ADCHS_CHANNEL_7, ADCHS_NUMBER_OF_CHANNEL } ADCHS_CHANNEL_ID; Members Members Description ADCHS_CHANNEL_0 ADCHS channel 0 ADCHS_CHANNEL_1 ADCHS channel 1 ADCHS_CHANNEL_2 ADCHS channel 2 ADCHS_CHANNEL_3 ADCHS channel 3 Peripheral Libraries Help ADCHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 211 ADCHS_CHANNEL_4 ADCHS channel 4 ADCHS_CHANNEL_5 ADCHS channel 5 ADCHS_CHANNEL_6 ADCHS channel 6 ADCHS_CHANNEL_7 ADCHS channel 7 ADCHS_NUMBER_OF_CHANNEL Number of channels Description ADCHS channel Select This enumeration identifies the ADC channels from 0 to 7. Not all devices have all ADCHS channels. Refer to the specific device data sheet for the number of available channels. Some features that are available in channels 0 to 6 may not be available on channel 7. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_CHANNEL_TRIGGER_SAMPLING_SEL Enumeration Defines the selection of trigger and sampling for channels 0 to 6. File help_plib_adchs.h C typedef enum { ADCHS_CHANNEL_UNSYNC_TRIGGER_UNSYNC_SAMPLING, ADCHS_CHANNEL_SYNC_SAMPLING, ADCHS_CHANNEL_SYNC_TRIGGER_UNSYNC_SAMPLING } ADCHS_CHANNEL_TRIGGER_SAMPLING_SEL; Members Members Description ADCHS_CHANNEL_UNSYNC_TRIGGER_UNSYNC_SAMPLING Unsynchronized trigger and unsynchronous sampling ADCHS_CHANNEL_SYNC_SAMPLING Synchronous sampling (trigger selection is ignored) ADCHS_CHANNEL_SYNC_TRIGGER_UNSYNC_SAMPLING Synchronized trigger and unsynchronous sampling Description ADCHS channel trigger and sampling selection This data type defines the selection of trigger and sampling for ADCHS channels 0 to 6. Passing this value for channel 7 will result in an error. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCHS_CLASS12_AN_INPUT_ID Enumeration Type for identifying the available Class 1 and 2 analog Inputs. File help_plib_adchs.h C typedef enum { } ADCHS_CLASS12_AN_INPUT_ID; Description ADC Analog Input ID of type class-1 and class-2 These enums are passed to functions meant to control or enable/disable "triggers". This is because only Class 1 and Class 2 analog inputs have individual triggers associated with them. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. Peripheral Libraries Help ADCHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 212 Files Files Name Description help_plib_adchs.h ADCHS Peripheral Library interface header file template. plib_adchs.h ADCHS Peripheral Library Interface Header for ADCHS common definitions. Description This section lists the source and header files used by the library. help_plib_adchs.h ADCHS Peripheral Library interface header file template. Enumerations Name Description ADCHS_AN_INPUT_ID Type for identifying the available ADC Inputs ADCHS_CHANNEL_ID Identifies the ADC channel from 0 to 7. ADCHS_CHANNEL_INP_SEL Defines the alternate input selection for channels 0 to 6. ADCHS_CHANNEL_TRIGGER_SAMPLING_SEL Defines the selection of trigger and sampling for channels 0 to 6. ADCHS_CHARGEPUMP_MODE Defines the selection for the charge pump. ADCHS_CLASS12_AN_INPUT_ID Type for identifying the available Class 1 and 2 analog Inputs. ADCHS_CLOCK_SOURCE Defines the ADCHS Clock Source Select. ADCHS_CVD_CAPACITOR Defines the value of the internal capacitor during CVD mode. ADCHS_DATA_RESOLUTION Identifies the resolution of the ADC output. ADCHS_DIGITAL_COMPARATOR_ID Identifies the supported Digital Comparators. ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT Identifies the Digital Filter averaging sample count. ADCHS_DIGITAL_FILTER_ID Identifies the supported Digital Filters. ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO Identifies the supported Digital Filter oversampling ratios. ADCHS_DIGITAL_FILTER_SIGNIFICANT_BITS Data length of digital filter. ADCHS_DMA_BUFFER_LENGTH Defines the length of the DMA buffer length. ADCHS_DMA_COUNT Defines the enable/disable of the count feature for DMA. ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK Defines the number of clocks prior to the arrival of valid data that the associated interrupt is generated. ADCHS_FAST_SYNC_PERIPHERAL_CLOCK Defines the selection of the fast synchronous peripheral clock. ADCHS_FAST_SYNC_SYSTEM_CLOCK Defines the selection of the fast synchronous system clock. ADCHS_INPUT_MODE Defines the available modes for the selected input. ADCHS_INTERRUPT_BIT_SHIFT_LEFT Identifies the bits shift for calculating the interrupt vector. ADCHS_MODULE_ID Identifies the number of ADC supported. ADCHS_OUTPUT_DATA_FORMAT Defines the selection for the output data format. ADCHS_SCAN_TRIGGER_SENSITIVE Trigger level for scan trigger. ADCHS_SCAN_TRIGGER_SOURCE Defines the ADCHS Channel Scan Trigger Source Selections. ADCHS_TRIGGER_SOURCE Defines the ADCHS Trigger Source Selections. ADCHS_VREF_SOURCE Defines the ADCHS VREF Source Select. ADCHS_WARMUP_CLOCK Identifies the number of clocks before the channel can be ready Description ADCHS Peripheral Library Interface Header File Template This file is provided for documentation purposes. File Name help_plib_adchs.h Company Microchip Technology Inc. Peripheral Libraries Help ADCHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 213 plib_adchs.h ADCHS Peripheral Library Interface Header for ADCHS common definitions. Functions Name Description PLIB_ADCHS_AnalogInputDataIsReady Returns the data ready status of analog inputs. PLIB_ADCHS_AnalogInputDataReadyInterruptDisable Disables the data ready interrupt for the selected analog inputs. PLIB_ADCHS_AnalogInputDataReadyInterruptEnable Enables the data ready interrupt for the selected analog input. PLIB_ADCHS_AnalogInputEarlyInterruptDisable Disables the early interrupt for the analog input. PLIB_ADCHS_AnalogInputEarlyInterruptEnable Enables the early interrupt for the analog input. PLIB_ADCHS_AnalogInputEarlyInterruptIsReady Returns the early interrupt ready status of analog input. PLIB_ADCHS_AnalogInputEdgeTriggerSet Sets the trigger as edge sensitive for selected class 1 and 2 analog input. PLIB_ADCHS_AnalogInputIsAvailable Returns the analog input configuration of ADCHS channel. PLIB_ADCHS_AnalogInputLevelTriggerSet Sets the trigger as level sensitive for selected Class 1 and 2 analog input. PLIB_ADCHS_AnalogInputModeGet Returns the mode for the specified analog input. PLIB_ADCHS_AnalogInputModeSelect Selects the mode for the specified analog input. PLIB_ADCHS_AnalogInputResultGet Returns a ADC conversion result. PLIB_ADCHS_AnalogInputScanIsComplete Returns the state of End of scan completion. PLIB_ADCHS_AnalogInputScanIsSelected Returns whether or note an analog input is selected for scanning. PLIB_ADCHS_AnalogInputScanRemove Removes the analog input from scanning selection. PLIB_ADCHS_AnalogInputScanSelect Selects the analog input for scanning. PLIB_ADCHS_AnalogInputScanSetup Selects input to include in Analog Input Scan mode. PLIB_ADCHS_AnalogInputTriggerSourceSelect Selects a trigger Source for analog input (Class 1 or Class 2 analog inputs only). PLIB_ADCHS_ChannelAnalogFeatureDisable Disables the analog circuit for channels of High-Speed SAR ADC. PLIB_ADCHS_ChannelAnalogFeatureEnable Enables the analog circuit for High-Speed SAR ADC channels. PLIB_ADCHS_ChannelConfigurationGet Used to get the configuration for the specified channel. PLIB_ADCHS_ChannelConfigurationSet Used to set the configuration for the specified channel. PLIB_ADCHS_ChannelDigitalFeatureDisable Disables the digital circuit for channels of High-Speed SAR ADC. PLIB_ADCHS_ChannelDigitalFeatureEnable Enables (turns ON) the digital circuit for channels. PLIB_ADCHS_ChannelInputSelect Selects the analog input for Channel 0 to 6. PLIB_ADCHS_ChannelIsReady Returns the state of the channel. PLIB_ADCHS_ChannelIsReadyInterruptDisable Disables the Channel ready interrupt for the specified channel. PLIB_ADCHS_ChannelIsReadyInterruptEnable Enables the Channel ready interrupt for the specified channel. PLIB_ADCHS_ChannelSetup Configures the High-Speed SAR ADC channels. PLIB_ADCHS_ChannelTriggerSampleSelect Selects the trigger and sampling modes for channels of High-Speed SAR ADC PLIB_ADCHS_ControlRegistersCanBeUpdated Returns the status of update-ready. PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptDisable Disables the update-ready interrupt. PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptEnable Enables the update-ready interrupt. PLIB_ADCHS_CVDDisable Disables the CVD feature. PLIB_ADCHS_CVDEnable Enables the CVD feature. PLIB_ADCHS_CVDResultGet Returns a CVD result measured by an ADCHS instance. PLIB_ADCHS_CVDSetup Configures the CVD related setting of ADCHS channel. PLIB_ADCHS_DigitalComparatorAnalogInputGet Returns the analog input ID used by the digital comparator. PLIB_ADCHS_DigitalComparatorAnalogInputSelect Selects analog inputs, whose converted data will be processed by the comparator. PLIB_ADCHS_DigitalComparatorDisable Disables the specified digital comparator. PLIB_ADCHS_DigitalComparatorEnable Enables the specified digital comparator. PLIB_ADCHS_DigitalComparatorEventHasOccurred Returns the status of the selected digital comparator. PLIB_ADCHS_DigitalComparatorInterruptDisable Disables the interrupt for the selected digital comparator. PLIB_ADCHS_DigitalComparatorInterruptEnable Enables the interrupt for the selected digital comparator. PLIB_ADCHS_DigitalComparatorLimitSet Sets the limit for the specified digital comparator. Peripheral Libraries Help ADCHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 214 PLIB_ADCHS_DigitalComparatorSetup Configures the Digital Comparator on the High-Speed SAR ADC converter. PLIB_ADCHS_DigitalFilterAveragingModeSampleCountSelect Selects the number of samples which are averaged by the Digital Filter. PLIB_ADCHS_DigitalFilterAveragingModeSetup Configures the Digital Filter on the High-Speed SAR ADC converter in Averaging mode. PLIB_ADCHS_DigitalFilterDataGet Used to fetch the data result from the Digital Filter. PLIB_ADCHS_DigitalFilterDataIsReady Used to determine if the Digital Filter has data ready. PLIB_ADCHS_DigitalFilterDataReadyInterruptDisable Disables the interrupt for the selected Digital Filter. PLIB_ADCHS_DigitalFilterDataReadyInterruptEnable Enables the interrupt for the selected Digital Filter. PLIB_ADCHS_DigitalFilterDisable Disables the Digital Filter. PLIB_ADCHS_DigitalFilterEnable Enables the Digital Filter. PLIB_ADCHS_DigitalFilterOversamplingModeRatioSelect Selects the oversampling ratio for the Digital Filter. PLIB_ADCHS_DigitalFilterOversamplingModeSetup Configures the Digital Filter on the High-Speed SAR ADC converter in Oversampling mode. PLIB_ADCHS_Disable High-Speed SAR ADC module is disabled (turned OFF). PLIB_ADCHS_DMABuffer_A_InterruptDisable Disables the DMA Buffer A full interrupt for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_A_InterruptEnable Enables the DMA Buffer A full interrupt for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_A_IsFull Used to determine if the DMA Buffer A is full, for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_B_InterruptDisable Disables the DMA Buffer B full interrupt for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_B_InterruptEnable Enables the DMA Buffer B full interrupt for the specified Channel 0 to 6. PLIB_ADCHS_DMABuffer_B_IsFull Used to determine if the DMA Buffer B is full, for the specified Channel 0 to 6. PLIB_ADCHS_DMADisable Disables the DMA in the High-Speed SAR ADC module. PLIB_ADCHS_DMAEnable Enables the DMA in the High-Speed SAR ADC module. PLIB_ADCHS_DMAOverflowErrorHasOccurred Used to determine if the DMA Buff had an overflow error. PLIB_ADCHS_DMASetup Configures the DMA on the High-Speed SAR ADC. PLIB_ADCHS_DMASourceRemove Disables the DMA for the specified Channel 0 to 6. PLIB_ADCHS_DMASourceSelect Enables the DMA for the specified Channel 0 to 6. PLIB_ADCHS_EarlyInterruptDisable Disables the early interrupt for the ADCHS. PLIB_ADCHS_EarlyInterruptEnable Enables the early interrupt for the ADCHS. PLIB_ADCHS_Enable Enables the High-Speed SAR ADC module. PLIB_ADCHS_ExistsAnalogInputCheck Identifies whether the System Configuration feature exists on the ADCHS module. PLIB_ADCHS_ExistsAnalogInputModeControl Identifies whether the analog input mode control exists on the ADCHS module. PLIB_ADCHS_ExistsAnalogInputScan Identifies whether the Analog input Scan exists on the ADCHS module. PLIB_ADCHS_ExistsChannelAnalogControl Identifies whether the Channel Analog control exists on the ADCHS module. PLIB_ADCHS_ExistsChannelConfiguration Identifies whether the Channel Configuration feature exists on the ADCHS module. PLIB_ADCHS_ExistsChannelDigitalControl Identifies whether the Channel Digital control exists on the ADCHS module. PLIB_ADCHS_ExistsChannelInputSelectControl Identifies whether the Channel 0 to 6 Input select feature exists on the ADCHS module. PLIB_ADCHS_ExistsConfiguration Identifies whether the Configuration feature exists on the ADCHS module. PLIB_ADCHS_ExistsConversionResults Identifies whether the Conversion Results feature exists on the ADCHS module. PLIB_ADCHS_ExistsCVD Identifies whether the CVD exists on the ADCHS module. PLIB_ADCHS_ExistsDigitalComparator Identifies whether the Digital Comparator feature exists on the ADCHS module . PLIB_ADCHS_ExistsDigitalFilter Identifies whether the Digital Filter feature exists on the ADCHS module. Peripheral Libraries Help ADCHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 215 PLIB_ADCHS_ExistsDMA Identifies whether the DMA exists on the ADCHS module. PLIB_ADCHS_ExistsEarlyInterruptControl Identifies whether the Early Interrupt control exists on the ADCHS module. PLIB_ADCHS_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADCHS module PLIB_ADCHS_ExistsExternalConversionRequestControl Identifies whether the External Convert feature exists on the ADCHS module. PLIB_ADCHS_ExistsFIFO Identifies whether the FIFO exists on the ADCHS module. PLIB_ADCHS_ExistsManualControl Identifies whether the Manual control exists on the ADCHS module. PLIB_ADCHS_ExistsTriggerControl Identifies whether the Trigger control exists on the ADCHS module. PLIB_ADCHS_ExistsTriggerSampleControl Identifies whether the Trigger Sample control feature exists on the ADCHS module. PLIB_ADCHS_ExistsTurboMode Identifies whether the Turbo mode feature exists on the ADCHS module. PLIB_ADCHS_ExistsUpdateReadyControl Identifies whether the Update Ready feature exists on the ADCHS module. PLIB_ADCHS_ExistsVREFControl Identifies whether the VREF control exists on the ADCHS module. PLIB_ADCHS_ExternalConversionRequestDisable Disables the external conversion request. PLIB_ADCHS_ExternalConversionRequestEnable Enables the external conversion request. PLIB_ADCHS_FIFODataCountGet Returns the number of data to be read from FIFO. PLIB_ADCHS_FIFODataIsAvailable Used to determine if the FIFO has data ready. PLIB_ADCHS_FIFODataIsNegative Returns the sign of data stored in FIFO. PLIB_ADCHS_FIFODataReadyInterruptDisable Disables the interrupt for FIFO. PLIB_ADCHS_FIFODataReadyInterruptEnable Enables the interrupt for FIFO. PLIB_ADCHS_FIFODisable Disables the FIFO in the High-Speed SAR ADC. PLIB_ADCHS_FIFOEnable Enables the FIFO in the High-Speed SAR ADC PLIB_ADCHS_FIFOErrorHasOccurred Used to determine if the FIFO has encountered an overflow error. PLIB_ADCHS_FIFORead Used to fetch the data result from the FIFO. PLIB_ADCHS_FIFOSourceGet Returns the channel ID using the FIFO. PLIB_ADCHS_FIFOSourceSelect Sets the Channel 0 to 6 using the FIFO. PLIB_ADCHS_GlobalLevelSoftwareTriggerDisable Disables the global level software trigger. PLIB_ADCHS_GlobalLevelSoftwareTriggerEnable Initiates a global level software trigger. PLIB_ADCHS_GlobalSoftwareTriggerEnable Initiate a Global Software Trigger. PLIB_ADCHS_ScanCompleteInterruptDisable Disables the end of scan interrupt. PLIB_ADCHS_ScanCompleteInterruptEnable Enables the end of scan interrupt. PLIB_ADCHS_Setup Configures the High-Speed SAR ADC converter. PLIB_ADCHS_SoftwareConversionInputSelect Selects the analog input of Channel 7 for manual conversion. PLIB_ADCHS_SoftwareConversionStart Triggers the conversion of analog input signal connected to Channel 7. PLIB_ADCHS_SoftwareSamplingStart Enables sampling of analog input for Channel 7. PLIB_ADCHS_SoftwareSamplingStop Disables sampling of analog input for Channel 7, which places Channel 7 into Hold mode. PLIB_ADCHS_TriggerSuspendDisable Disables trigger suspend. PLIB_ADCHS_TriggerSuspendEnable Suspends all trigger for all ADCHS channels. PLIB_ADCHS_TurboModeChannelSelect Configures the channels for Turbo mode. PLIB_ADCHS_TurboModeDisable Disables Turbo mode for High-Speed SAR ADC module. PLIB_ADCHS_TurboModeEnable Enables Turbo mode for the High-Speed SAR ADC module. PLIB_ADCHS_TurboModeErrorHasOccurred Returns the error state of Turbo mode. PLIB_ADCHS_VREFFaultHasOccurred Returns the state of VREF fault. PLIB_ADCHS_VREFFaultInterruptDisable Disables the VREF Fault interrupt. PLIB_ADCHS_VREFFaultInterruptEnable Enables the VREF fault interrupt. PLIB_ADCHS_VREFIsReady Returns the state of VREF. PLIB_ADCHS_VREFReadyInterruptDisable Disables the VREF ready interrupt. PLIB_ADCHS_VREFReadyInterruptEnable Enables the VREF ready interrupt. Peripheral Libraries Help ADCHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 216 Description High-Speed Successive Approximation Register Analog-to-Digital Converter (ADCHS) Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the ADCHS PLIB for all families of Microchip microcontrollers.The definitions in this file are common to ADCHS peripheral. File Name plib_adchs.h Company Microchip Technology Inc. Peripheral Libraries Help ADCHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 217 ADCP Peripheral Library This section describes the Pipelined Analog-to-Digital Converter (ADCP) Peripheral Library. Introduction This library provides a low-level abstraction of the Pipelined Analog-to-Digital Converter (ADCP) Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The Pipelined Analog-to-Digital Converter (ADCP) peripheral is used to convert an analog input into a digital number that represents that input voltage. When the input is periodically converted, the result is a sequence of digital values that have converted a continuous-time and continuous-amplitude analog signal to a discrete-time and discrete-amplitude digital signal. This particular ADC architecture is pipelined allowing it to simultaneously convert up to six samples, each at a different stage of conversion resulting in a low overall latency of multiple sampled inputs. The structure of the ADCP is shown in the following diagram. • Analog input pins_connect_to the sample and hold (S&H) circuits. These circuits capture the analog signal so that it can be passed to the pipeline converter. • The S&H circuits are controlled by predefined trigger sources. These trigger sources switch the sample and hold circuit to hold and queue the conversion of the sample. • Channel scan is available which allows a single trigger to start a sample/conversion sequence of multiple analog inputs using a predefined scan list • A conversion clock is required for the pipeline converter. This clock determines the conversion speed and latency and affects power consumption. • A voltage reference is required for the pipeline converter. This voltage reference determines allowable input range of the analog signal. • Result registers store the conversion results and can be read by the software application. Software is notified of ready results by either polling or through the use of interrupts. • Optional Oversampling Digital Filters can be used to provide increased measurement accuracy at the sacrifice of sample rate. Software is notified of ready oversampling results by either polling or through the use of interrupts. • Optional digital comparators can be used to test conversion results independent of software and generate interrupts based on predefined conditions Using the Library This topic describes the basic architecture of the Pipelined Analog-to-Digital Converter (ADCP) Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_adcp.h The interface to the ADCP Peripheral library is defined in the plib_adcp.h header file, which is included by the peripheral.h file. Any C language source (.c) file that uses the Pipelined Analog-to-Digital Converter (ADCP) Peripheral library must include peripheral.h. Library File: The ADCP Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Peripheral Libraries Help ADCP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 218 Hardware Abstraction Model This library provides the low-level abstraction of the ADCP module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a super set of all the functionality of the available Pipelined Analog-to-Digital Converter (ADCP) on the device. Refer to the "ADC" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine the set of functions that are supported for each ADCP module on the device. Description Pipelined Analog-to-Digital Converter (ADCP) Software Abstraction Block Diagram Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the ADCP module. Library Interface Section Description Configuration Functions These library functions are used to configure the ADC, enable and disable it, initiate a calibration and manage low power states. Status Functions These library functions return status information related to the ADC. Input Selection Functions These library functions select and configure the ANx inputs to the ADC. Channel Scan Functions These library functions are used to configure the channel scan feature. Triggering Functions These library functions are used to configure and initiate conversion triggers. Analog Input Conversion Results Functions These library function are used to retrieve individual conversion results for ANx pins. Digital Comparator Functions These library functions are used to configure and query the digital comparators. Oversampling Digital Filter Functions These library functions are used to configure the Oversampling Digital Filter and fetch results from it. Peripheral Libraries Help ADCP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 219 How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. Core Functionality This topic describes the core functionality of the ADCP Peripheral Library. Description Analog-to-Digital conversion using the ADCP involves the following three steps: 1. Sampling of the input signal. 2. Capture of the input signal by the sample and hold (S&H) circuit and transfer to the converter. 3. Conversion of the analog signal to its digital representation. Sampling of the input signal involves charging of the S&H capacitor. The sampling time must be adequate so that the capacitor charges to a value equal to the input voltage. At the appropriate time, the input is disconnected and the capacitor voltage is transferred to the converter. The converter then digitizes the analog signal and provides the result. The converter requires a clock source and a reference voltage. The clock is referred to as the ADC clock and has a period of TAD. The clock and reference voltage sources are selectable, as well as the clock prescaling that determines the TAD. The ADCP uses two types of S&H circuits: dedicated and shared. Each ADC implementation includes up to five dedicated S&H circuits and a single shared S&H. Analog inputs connected to the S&H circuits are categorized into three types: Class 1, Class 2, and Class 3. • Class 1 inputs are associated with a dedicated S&H circuit. Each dedicated S&H has a single Class 1 input associated with it. Each Class 1 input has a unique trigger selection register. Class 1 inputs can also be part of a channel scan list, triggered by the common scan trigger source. • Class 2 inputs are sampled only on the shared S&H and are either individually triggered or as part of a channel scan list. When used individually their trigger source is selected by their unique trigger register. • Class 3 inputs are sampled only on the shared S&H and are used in channel scan exclusively. They share a common trigger source. When using channel scan it is possible to combine Class 1, Class 2, and Class 3 inputs in the scan list. Note: For details regarding configuration and triggering options was well as sampling requirements, refer to the "ADC" chapter in the specific device data sheet or the family reference manual section specified in that chapter. Example - Simultaneous Sampling Three Class 1 Inputs Simultaneous sampling is used when the application requires capture of more than one signal at the same instance of time. Simultaneous sampling requires the use of multiple Class 1 inputs where each is assigned the same trigger source. The following example illustrates simultaneous sampling of AN0, AN1 and AN2 using the global software trigger as the trigger source. The dedicated Sample and Holds (S&H) circuits are configured for single-ended input and a unipolar (unsigned) output. No interrupts are used so the results are polled for ready status. Example: int32_t results[3] ; // storage for results // This structure is used to simplify testing for a ready channel AN_READY anReady ; // Configure the ADC // AVDD/AVSS reference, ADC clock is system clock (SYSCLK) divided by 8 // No need to specify sample time for class 2/3 inputs or oversampling // sample time as Class 2/3 inputs and oversampling is not used. PLIB_ADCP_Configure ( ADCP_ID_1 , ADCP_VREF_AVDD_AVSS , // AVDD and AVSS as reference FALSE , // No VREF boost FALSE , // Do not use fractional format FALSE , // Do not stop in idle ADCP_CLK_SRC_SYSCLK , // SYSCLK is the clock source 4 , // TAD = 1/SYSCLK * 2 * 4 // or ADC Clock = SYSCLK / (2 * 4) 0 , // Oversampling is not used. 0 , // No early interrupt. 0 ); // No class 2 or 3 channels are used // Set up the triggers // Configure AN0 for triggering from software. PLIB_ADCP_Class12TriggerConfigure ( ADCP_ID_1 , Peripheral Libraries Help ADCP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 220 ADCP_CLASS12_AN0 , ADCP_TRG_SRC_SOFTWARE ) ; // Configure AN1 for triggering from software. PLIB_ADCP_Class12TriggerConfigure ( ADCP_ID_1 , ADCP_CLASS12_AN1 , ADCP_TRG_SRC_SOFTWARE ) ; // Configure AN2 for triggering from software. PLIB_ADCP_Class12TriggerConfigure ( ADCP_ID_1 , ADCP_CLASS12_AN2 , ADCP_TRG_SRC_SOFTWARE ) ; // Set S&H modes PLIB_ADCP_SHModeSelect ( ADCP_ID_1 , ADCP_SH0 , ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR ) ; PLIB_ADCP_SHModeSelect ( ADCP_ID_1 , ADCP_SH1 , ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR ) ; PLIB_ADCP_SHModeSelect ( ADCP_ID_1 , ADCP_SH2 , ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR ) ; // Enable the ADC Module PLIB_ADCP_Enable ( ADCP_ID_1 ) ; // Wait for a ready status while (!PLIB_ADCP_ModuleIsReady ( ADCP_ID_1 )) ; while (1) { // Initiate a trigger PLIB_ADCP_GlobalSoftwareTrigger ( ADCP_ID_1 ) ; // Wait for a data results to be ready // if lowest priority channel is done then all are done. do { anReady = PLIB_ADCP_ResultReady ( ADCP_ID_1 ) ; } while (anReady.AN2 == 0) ; // fetch AN0 if (anReady.AN0 == 1) results[0] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN0 ) ; // fetch AN1 if (anReady.AN1 == 1) results[1] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN1 ) ; // fetch AN2 if (anReady.AN2 == 1) results[2] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN2 ) ; } Example - Channel Scanning Channel scanning is used in applications where precise timing of the sample to an external source is not needed. Channel scanning allows a large number of analog inputs to be sampled and converted in sequence each time a single trigger occurs. The following example illustrates how to configure channel scanning of multiple Class 2 and Class 3 inputs using the shared S&H. This example uses inputs AN5, AN11 - AN14. AN5 and AN11 are Class 2 inputs. AN13 and AN 14 are Class 3 inputs. The global software trigger is used to initiate the scan. A 4 TAD sample time is specified for the shared S&H. The shared S&H is configured for single-ended operation and a unipolar output. No interrupts are used so the results are polled for ready status. Example: int32_t results[5] ; // storage for results // This structure is used to simplify testing of the ready status AN_READY anReady ; // This structure is used to simplify specifying channels for scan // AN5, AN11, AN12, AN13 and AN14 are selected for scanning. AN_SELECT anSelect ; anSelect.highWord = 0 ; anSelect.lowWord = 0 ; anSelect.AN5 = 1 ; anSelect.AN11 = 1 ; anSelect.AN12 = 1 ; Peripheral Libraries Help ADCP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 221 anSelect.AN13 = 1 ; anSelect.AN14 = 1 ; // Configure the ADC // AVDD/AVSS reference, ADC clock is system clock (SYSCLK) divided by 8 // The sample for the shared S&H must be adequate for all inputs. // In this example it is set to 4 TAD. // No need to specify sample time for oversampling as it is not used. PLIB_ADCP_Configure ( ADCP_ID_1 , ADCP_VREF_AVDD_AVSS , // AVDD and AVSS as reference FALSE , // No VREF boost FALSE , // Do not use fractional format FALSE , // Do not stop in idle ADCP_CLK_SRC_SYSCLK , // SYSCLK is the clock source 4 , // TAD = 1/SYSCLK * 2 * 4 // or ADC Clock = SYSCLK / (2 * 4) 0 , // Oversampling is not used. 0 , // No early interrupt. 3 ) ; // 3 + 1 = 4 TAD for Class 2 and 3 // Sample Time. // Specify the inputs to include in the Channel Scan using the selections made when // initializing anSelect. Use the software trigger to initiate the scan. PLIB_ADCP_ChannelScanConfigure ( ADCP_ID_1 , anSelect.lowWord , anSelect.highWord , ADCP_SCAN_TRG_SRC_SOFTWARE ) ; // Set S&H 5 (shared S&H) to use the single ended, unipolar mode PLIB_ADCP_SHModeSelect ( ADCP_ID_1 , ADCP_SH5 , ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR ) ; // Enable the ADC Module PLIB_ADCP_Enable ( ADCP_ID_1 ) ; // Wait for a ready status while (!PLIB_ADCP_ModuleIsReady ( ADCP_ID_1 )) ; while (1) { // Initiate a trigger PLIB_ADCP_GlobalSoftwareTrigger ( ADCP_ID_1 ) ; // Wait for a data results to be ready // if lowest priority channel is done then all are done. do { anReady = PLIB_ADCP_ResultReady ( ADCP_ID_1 ) ; } while (anReady.AN14 == 0) ; // fetch AN5 if (anReady.AN5 == 1) results[0] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN5 ) ; // fetch AN11 if (anReady.AN11 == 1) results[1] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN11 ) ; // fetch AN12 if (anReady.AN12 == 1) results[2] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN12 ) ; // fetch AN13 if (anReady.AN13 == 1) results[3] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN13 ) ; // fetch AN14 if (anReady.AN14 == 1) results[4] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN14 ) ; } Peripheral Libraries Help ADCP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 222 Other Functionality This topic provides information on additional functionality. Description The ADCP also implements a Digital Oversampling Filter and Digital Comparator. The oversampling digital filter consists of an accumulator and a decimator (down-sampler), which function together as a low-pass filter. By sampling an analog input at a higher-than-required sample rate, and then processing the data through the oversampling digital filter, the number of usable bits of the ADCP module can be increased at the expense of decreased conversion throughput. For example, using 4x oversampling yields one extra usable bit , 16x oversampling yields two extra usable bits, 64x oversampling provides three extra usable bits, and 256x oversampling provides four extra usable bits. Once configured, the application provides a single trigger to the analog input specified for oversampling, it then fetches the result when the process is complete. The ADCP module features a digital comparator that can be used to monitor selected analog input conversion results and generate an interrupt when a conversion result matches the user-specified limits. Conversion triggers are still required to initiate conversions. The comparison occurs automatically once the conversion is complete. When using a hardware source as a periodic trigger, it is possible to monitor analog inputs and create an interrupt when the converted level matches specified criteria without any software overhead. Example - Digital Oversampling Filter The Digital Oversampling filter can be used to increase resolution of the conversion result at the expense of throughput. The following example shows how two extra bits of resolution can be obtained using 16X oversampling (sixteen samples are used to create one higher resolution result). AN0 is used for the input. The sampling time for the retriggers is set to 3.5 TAD. Example: int32_t result; // storage for result // Configure the ADC // AVDD/AVSS reference, ADC clock is system clock (SYSCLK) divided by 8 // No need to specify sample time for Class 2/3 inputs as they are not used. // Oversampling sample time is set to 3.5 TAD. PLIB_ADCP_Configure(ADCP_ID_1, ADCP_VREF_AVDD_AVSS, // AVDD and AVSS as reference FALSE, // No VREF boost FALSE, // Do not use fractional format FALSE, // Do not stop in idle ADCP_CLK_SRC_SYSCLK, // SYSCLK is the clock source 4, // TAD = 1/SYSCLK * 2 * 4 // or ADC Clock = SYSCLK / (2 * 4) 2, // 2 + 1.5 = 3.5 TAD between // oversampling triggers 0, // No early interrupt. 0); // No Class 2 and 3 are used. // Set up the triggers // Configure AN0 for triggering from software. PLIB_ADCP_Class12TriggerConfigure(ADCP_ID_1, ADCP_CLASS12_AN0, ADCP_TRG_SRC_SOFTWARE); // Set S&H modes // Set S&H 0 to use the single ended, unipolar mode PLIB_ADCP_SHModeSelect(ADCP_ID_1, ADCP_SH0, ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR); // Configure the Oversampling Filter PLIB_ADCP_OsampDigFilterConfig(ADCP_ID_1, // ADCP module ID ADCP_ODFLTR1, // Filter ID ADCP_AN0, // Oversample AN0 ADCP_ODFLTR_16X, // 16 x oversampling FALSE); // No Global Int Enable // Enable ODFLTR0 PLIB_ADCP_OsampDigFilterEnable(ADCP_ID_1, ADCP_ODFLTR1); // Enable the ADC Module PLIB_ADCP_Enable(ADCP_ID_1); // Wait for a ready status Peripheral Libraries Help ADCP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 223 while (!PLIB_ADCP_ModuleIsReady(ADCP_ID_1)); while (1) { // Initiate a trigger PLIB_ADCP_GlobalSoftwareTrigger(ADCP_ID_1); // Wait for data to be ready while (PLIB_ADCP_OsampDigFilterDataRdy(ADCP_ID_1, ADCP_ODFLTR1) == FALSE); // get the result result = PLIB_ADCP_OsampDigFilterDataGet(ADCP_ID_1, ADCP_ODFLTR1); } Example - Digital Comparator The Digital Comparator is used to automatically evaluate results as they are output by the converter. The following example illustrates an automated test of AN5 for values >= 80% of full scale or < 20% of full scale. A count is incremented each time an event occurs. Example: int32_t result; // storage for result int32_t count = 0; /* This structure is used to simplify testing for a ready channel */ AN_READY anReady; // Configure the ADC // AVDD/AVSS reference, ADC clock is system clock (SYSCLK) divided by 8 // The sample for the shared S&H must be adequate for all inputs. // In this example it is set to 4 TAD. // No need to specify sample time for oversampling as it is not used. PLIB_ADCP_Configure(ADCP_ID_1, ADCP_VREF_AVDD_AVSS, // AVDD and AVSS as reference FALSE, // No VREF boost FALSE, // Do not use fractional format FALSE, // Do not stop in idle ADCP_CLK_SRC_SYSCLK, // SYSCLK is the clock source 4, // TAD = 1/SYSCLK * 2 * 4 or // ADC Clock = SYSCLK / (2 * 4) 0, // no oversampling 0, // No early interrupt. 3); // 3 + 1 = 4 TAD for Class 2 and 3 Sample Time. // Set up the triggers // Configure AN5 for triggering from software. PLIB_ADCP_Class12TriggerConfigure(ADCP_ID_1, ADCP_CLASS12_AN5, ADCP_TRG_SRC_SOFTWARE); // Set S&H modes // Set S&H 5 to use the single ended, unipolar mode PLIB_ADCP_SHModeSelect(ADCP_ID_1, ADCP_SH5, ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR); // Configure the Digital Comparator // Creates an event when the reading of AN5 is less than 20% or // greater than or equal to 80% of the full scale 12-bit output. PLIB_ADCP_DigCmpConfig(ADCP_ID_1, // ADCP module ID ADCP_DCMP1, // Comparator ID FALSE, // No Global Int Enable FALSE, // no test for between low and high TRUE, // test for greater than or equal to high FALSE, // no test for less than high FALSE, // no test for greater than or equal to low TRUE, // test for less than low 1 << 5, // enable AN5 for comparison 0xFFF - (0xFFF / 5), // high limit is 80% of full scale 0xFFF / 5); // low limit is 20% of full scale // Enable DigCmp1 Peripheral Libraries Help ADCP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 224 PLIB_ADCP_DigCmpEnable(ADCP_ID_1, ADCP_DCMP1); // Enable the ADC Module PLIB_ADCP_Enable(ADCP_ID_1); // Wait for a ready status while (!PLIB_ADCP_ModuleIsReady(ADCP_ID_1)); while (1) { // Initiate a trigger PLIB_ADCP_GlobalSoftwareTrigger(ADCP_ID_1); // wait for conversion to complete do { anReady = PLIB_ADCP_ResultReady(ADCP_ID_1); } while (anReady.AN5 == 0); // Check result and increment count if an out of range event // occurred on digital comparator 1 for AN5 if (PLIB_ADCP_DigCmpAIdGet(ADCP_ID_1, ADCP_DCMP1) == 5) { count++; } } Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB X IDE. Library Interface a) Configuration Functions Name Description PLIB_ADCP_Configure Configures the Pipelined ADC module including the ADC calibration registers. PLIB_ADCP_Enable Enables the Pipelined ADC module. PLIB_ADCP_Disable Pipelined ADC module is disabled (turned OFF). PLIB_ADCP_CalibrationStart Initiates Pipelined ADC Calibration. PLIB_ADCP_LowPowerStateEnter Places the Pipelined ADC module in a low power state. PLIB_ADCP_LowPowerStateExit Takes the Pipelined ADC module out of low power state and puts it into an operational mode. PLIB_ADCP_LowPowerStateGet Returns the state of the low power setting. PLIB_ADCP_ExistsCalibration Identifies whether the Calibration feature exists on the ADCP module. PLIB_ADCP_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADCP module. PLIB_ADCP_ExistsLowPowerControl Identifies whether the LowPowerControl feature exists on the ADCP module. PLIB_ADCP_ExistsConfiguration Identifies whether the Configuration feature exists on the ADCP module. b) Status Functions Name Description PLIB_ADCP_ModuleIsReady Returns the overall ready status of the module. PLIB_ADCP_ExistsReadyStatus Identifies whether the ReadyStatus feature exists on the ADCP module. c) Input Selection Functions Name Description PLIB_ADCP_AlternateInputSelect Selects the alternate physical input for the specified dedicated (Class 1) S&H. PLIB_ADCP_DefaultInputSelect Selects the default physical input for the specified dedicated (Class 1) S&H. PLIB_ADCP_ExistsInputSelect Identifies whether the InputSelect feature exists on the ADCP module. PLIB_ADCP_ExistsModeSelect Identifies whether the ModeSelect feature exists on the ADCP module. PLIB_ADCP_SHModeSelect Selects the mode for the specified S&H. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 225 d) Channel Scan Functions Name Description PLIB_ADCP_ChannelScanConfigure Selects input to include in Channel Scan Mode PLIB_ADCP_ExistsChannelScan Identifies whether the ChannelScan feature exists on the ADCP module. e) Triggering Functions Name Description PLIB_ADCP_GlobalSoftwareTrigger Initiates a Global Software Trigger on the specified module. PLIB_ADCP_IndividualTrigger Triggers an individual channel independent of the configured trigger source PLIB_ADCP_Class12TriggerConfigure Configures a Class 1 or Class 2 Trigger Source. PLIB_ADCP_ExistsTriggering Identifies whether the Triggering feature exists on the ADCP module. f) Individual Analog Input Conversion Results Functions Name Description PLIB_ADCP_ResultReady Returns the ADC conversion result ready bits for the module. PLIB_ADCP_ResultGet Returns a Pipelined ADC conversion result. PLIB_ADCP_ResultReadyGrpIntConfigure Selects input to include in global interrupt. PLIB_ADCP_ExistsConversionResults Identifies whether the ConversionResults feature exists on the ADCP module. g) Digital Comparator Functions Name Description PLIB_ADCP_DigCmpEnable Enables the Digital Comparator in the Pipelined ADC module. PLIB_ADCP_DigCmpDisable Disables the Digital Comparator in the Pipelined ADC module. PLIB_ADCP_DigCmpAIdGet Returns the Analog Input ID of for the Comparator Event PLIB_ADCP_DigCmpConfig Configures the Digital Comparator on the Pipelined ADC converter. PLIB_ADCP_ExistsDigCmp Identifies whether the DigitalComparator feature exists on the ADCP module. h) Oversampling Digital Filter Functions Name Description PLIB_ADCP_OsampDigFilterEnable Enables the Oversampling Digital Filter in the Pipelined ADC module PLIB_ADCP_OsampDigFilterDisable Disables the Oversampling Digital Filter in the Pipelined ADC module. PLIB_ADCP_OsampDigFilterDataRdy Determines if the Oversampling Digital Filter has data ready. PLIB_ADCP_OsampDigFilterDataGet Fetches the data result from the Oversampling Digital Filter. PLIB_ADCP_ExistsOsampDigFilter Identifies whether the OsampDigitalFilter feature exists on the ADCP module. PLIB_ADCP_OsampDigFilterConfig Configures the Oversampling Digital Filter on the Pipelined ADC converter. i) Data Types and Constants Name Description ADCP_MODULE_ID Identifies the number of ADC Modules Supported. ADCP_VREF_SOURCE Defines the ADCP VREF Source Select. ADCP_CLOCK_SOURCE Defines the ADCP Clock Source Select. ADCP_CLASS12_INPUT_ID Identifies the Class 1 and Class 2 ADC Inputs. ADCP_SH_ID Identifies the supported S&H circuits regardless of type. ADCP_DSH_ID Identifies the supported Dedicated Sample and Hold (S&H) circuits. ADCP_SH_MODE Defines the available modes for the S&H. ADCP_INPUT_ID Identifies the available ADC Inputs. ADCP_DCMP_ID Identifies the supported Digital Comparators. ADCP_ODFLTR_ID Identifies the supported Oversampling Digital Filters. ADCP_ODFLTR_OSR Identifies the supported Digital Filter oversampling ratios. ADCP_SCAN_TRG_SRC Defines the ADCP Channel Scan Trigger Source Selections. ADCP_TRG_SRC Defines the ADCP Trigger Source Selections. AN_SELECT This union of structures is provided to simply selection of analog inputs for inclusion in a particular function. AN_READY This union (identical to the AN_SELECT union) is used as the return value by the PLIB_ADCP_Result_Ready function. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 226 Description This section describes the Application Programming Interface (API) functions of the Pipelined Analog-to-Digital Converter (ADCP) Peripheral Library. Refer to each section for a detailed description. a) Configuration Functions PLIB_ADCP_Configure Function Configures the Pipelined ADC module including the ADC calibration registers. File plib_adcp.h C void PLIB_ADCP_Configure(ADCP_MODULE_ID index, ADCP_VREF_SOURCE voltageRefSelect, bool boostVref, bool fractionalOutputOn, bool stopInIdle, ADCP_CLOCK_SOURCE adcClockSource, int8_t adcClockDivider, int8_t oversampleDigFilterSamTime, int8_t earlyIntEnable, int8_t class2and3SampleTime); Returns None. Description This function configures all ADC parameters common to all inputs. This configuration must occur prior to enabling the ADC and therefore must be called when the ADC is disabled. Remarks This function must be called when the ADC is disabled. Preconditions The module is disabled when calling this function. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure the ADC PLIB_ADCP_Configure( MY_ADCP_INSTANCE, ADCP_VREF_VREFP_VREFN, // VREF+ and VREF- as reference FALSE, // No VREF boost TRUE, // Use fractional format TRUE, // Do stop in idle ADCP_CLK_SRC_SYSCLK, // SYSCLK is the clock source 3, // TAD = 1/SYSCLK * 2 * 3 // or ADC Clock = SYSCLK / (2 * 3) 2, // 2 + 1.5 = 3.5 TAD between // oversampling triggers 0, // No early interrupt. 3 ); // 3 + 1 = 4 TAD for Class 2 and 3 // Sample Time. // Enable the ADC PLIB_ADCP_Enable(MY_ADCP_INSTANCE); Parameters Parameters Description index Identifier for the ADCP instance voltageRefSelect VREF Source Selection boostVref Enables the VREF boost if TRUE. Use when VREFH VREFL < .64 (AVDD - AVSS) fractionalOutputOn sets output to a fractional format if TRUE Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 227 stopInIdle sets ADC to stop when device is in idle mode if TRUE adcClockSource Clock source selection adcClockDivider Clock source divider. Values range from 0 to 254. oversampleDigFilterSamTime Sets the delay (sample time) between automatically generated oversampling filter triggers. Values range from 0 to 31 for 1.5 TAD to 32.5 TAD respectively. earlyIntEnable Sets the number of clocks prior to the actual arrival of data that the ADRDY bit is set. Range is 0 to 7. Used to generate an early interrupt. class2and3SampleTime Set the sample time for Class 2 and Class 3 inputs. Range is 0 to 255 for a sample time of 1 to 256, respectively. Function void PLIB_ADCP_Configure( ADCP_MODULE_ID index, ADCP_VREF_SOURCE voltageRefSelect, // voltage reference bool boostVref, // VREF boost bool fractionalOutputOn, // result format fractional bool stopInIdle, // stop in idle ADCP_CLOCK_SOURCE adcClockSource, // clock source int8_t adcClockDivider, // clock divider int8_t oversampleDigFilterSamTime, // sample time between digital filter samples int8_t earlyIntEnable, // early interrupt enable int8_t class2and3SampleTime ) // Class 2&3 Sample time PLIB_ADCP_Enable Function Enables the Pipelined ADC module. File plib_adcp.h C void PLIB_ADCP_Enable(ADCP_MODULE_ID index); Returns None. Description This function enables (turns ON) the selected Pipelined ADC module. Remarks None Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. PLIB_ADCP_Enable(MY_ADCP_INSTANCE); Parameters Parameters Description index Identifier for the ADCP instance to be configured Function void PLIB_ADCP_Enable( ADCP_MODULE_ID index ) PLIB_ADCP_Disable Function Pipelined ADC module is disabled (turned OFF). Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 228 File plib_adcp.h C void PLIB_ADCP_Disable(ADCP_MODULE_ID index); Returns None. Description This function disables (turns OFF) the selected Pipelined ADC module. Remarks Not all functionality is available on all devices. Please refer to the specific device data sheet for the list of available features. Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. PLIB_ADCP_Disable(MY_ADCP_INSTANCE); Parameters Parameters Description index Identifier for the ADCP instance to be configured Function void PLIB_ADCP_Disable( ADCP_MODULE_ID index ) PLIB_ADCP_CalibrationStart Function Initiates Pipelined ADC Calibration. File plib_adcp.h C void PLIB_ADCP_CalibrationStart(ADCP_MODULE_ID index); Returns None. Description This function initiates calibration of the module. During calibration the module cannot perform conversion. Remarks Calibration is complete when PLIB_ADCP_ModuleIsReady() returns a TRUE result. Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. PLIB_ADCP_CalibrationStart(MY_ADCP_INSTANCE); while (!PLIB_ADCP_ModuleIsRead(MY_ADCP_INSTANCE)); Parameters Parameters Description index Identifier for the ADCP instance to be configured Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 229 Function void PLIB_ADCP_CalibrationStart( ADCP_MODULE_ID index ) PLIB_ADCP_LowPowerStateEnter Function Places the Pipelined ADC module in a low power state. File plib_adcp.h C void PLIB_ADCP_LowPowerStateEnter(ADCP_MODULE_ID index); Returns None. Description This function places the Pipelined ADC module in a low power state. The feature is used in place of disabling the ADC when power reduction is needed. The Pipelined ADC can come out of low power state and be operational much faster since recalibration is not required. Remarks None. Preconditions The Pipelined ADC must be enabled. Example PLIB_ADCP_LowPowerStateEnter(MY_ADCP_INSTANCE); Parameters Parameters Description index Identifier for the ADCP instance Function void PLIB_ADCP_LowPowerStateEnter ( ADCP_MODULE_ID index ) PLIB_ADCP_LowPowerStateExit Function Takes the Pipelined ADC module out of low power state and puts it into an operational mode. File plib_adcp.h C void PLIB_ADCP_LowPowerStateExit(ADCP_MODULE_ID index); Returns None. Description This function takes the Pipelined ADC module out of a low power state and places it into an operational mode. Remarks The first five conversions following the exit from ADC Low-power mode may be subject to lower accuracy than specified in the device data sheet. Preconditions None. Example PLIB_ADCP_LowPowerStateExit(MY_ADCP_INSTANCE); Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 230 Parameters Parameters Description index Identifier for the ADCP instance Function void PLIB_ADCP_LowPowerStateExit( ADCP_MODULE_ID index ) PLIB_ADCP_LowPowerStateGet Function Returns the state of the low power setting. File plib_adcp.h C bool PLIB_ADCP_LowPowerStateGet(ADCP_MODULE_ID index); Returns A Boolean indicating the state of the low power setting. Description This function returns the state of the low power setting. Remarks None. Preconditions None. Example bool lowPowerSate = PLIB_ADCP_LowPowerStateGet(MY_ADCP_INSTANCE); Parameters Parameters Description index Identifier for the ADCP instance Function bool PLIB_ADCP_LowPowerStateGet( ADCP_MODULE_ID index ) PLIB_ADCP_ExistsCalibration Function Identifies whether the Calibration feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsCalibration(ADCP_MODULE_ID index); Returns Existence of the Calibration feature: • true - When Calibration feature is supported on the device • false - When Calibration feature is not supported on the device Description This function identifies whether the Calibration feature is available on the ADCP module. When this function returns true, this function is supported on the device: • PLIB_ADCP_CalibrationStart Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 231 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsCalibration( ADCP_MODULE_ID index ) PLIB_ADCP_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsEnableControl(ADCP_MODULE_ID index); Returns Existence of the EnableControl feature: • true - When EnableControl feature is supported on the device • false - When EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_Enable • PLIB_ADCP_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsEnableControl( ADCP_MODULE_ID index ) PLIB_ADCP_ExistsLowPowerControl Function Identifies whether the LowPowerControl feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsLowPowerControl(ADCP_MODULE_ID index); Returns Existence of the LowPowerControl feature: • true - When LowPowerControl feature is supported on the device Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 232 • false - When LowPowerControl feature is not supported on the device Description This function identifies whether the LowPowerControl feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_LowPowerStateEnter • PLIB_ADCP_LowPowerStateExit • PLIB_ADCP_LowPowerStateGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsLowPowerControl( ADCP_MODULE_ID index ) PLIB_ADCP_ExistsConfiguration Function Identifies whether the Configuration feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsConfiguration(ADCP_MODULE_ID index); Returns Existence of the Configuration feature: • true - When Configuration feature is supported on the device • false - When Configuration feature is not supported on the device Description This function identifies whether the Configuration feature is available on the ADCP module. When this function returns true, this function is supported on the device: • PLIB_ADCP_Configure Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsConfiguration( ADCP_MODULE_ID index ) b) Status Functions PLIB_ADCP_ModuleIsReady Function Returns the overall ready status of the module. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 233 File plib_adcp.h C bool PLIB_ADCP_ModuleIsReady(ADCP_MODULE_ID index); Returns Boolean indicating ready status. Description This function returns the ready status of the Pipelined ADC. The ADC must be ready before operation. Remarks None. Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Enable the module PLIB_ADCP_Enable(MY_ADCP_INSTANCE); // wait for calibration to complete while (!PLIB_ADCP_ModuleIsReady(MY_ADCP_INSTANCE)); // begin sampling ... Parameters Parameters Description index Identifier for the ADCP instance Function bool PLIB_ADCP_ModuleIsReady( ADCP_MODULE_ID index ) PLIB_ADCP_ExistsReadyStatus Function Identifies whether the ReadyStatus feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsReadyStatus(ADCP_MODULE_ID index); Returns Existence of the ReadyStatus feature: • true - When ReadyStatus feature is supported on the device • false - When ReadyStatus feature is not supported on the device Description This function identifies whether the ReadyStatus feature is available on the ADCP module. When this function returns true, this function is supported on the device: • PLIB_ADCP_ModuleIsReady Remarks None. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 234 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsReadyStatus( ADCP_MODULE_ID index ) c) Input Selection Functions PLIB_ADCP_AlternateInputSelect Function Selects the alternate physical input for the specified dedicated (Class 1) S&H. File plib_adcp.h C void PLIB_ADCP_AlternateInputSelect(ADCP_MODULE_ID index, ADCP_DSH_ID id); Returns None. Description This function selects the alternate physical input for the specified S&H. Remarks None. Preconditions The function only applies to dedicated S&H circuits (Class 1 Inputs). Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Set S&H 1 to use the alternate input. PLIB_ADCP_AlternateInputSelect(MY_ADCP_INSTANCE, ADCP_DSH1) Parameters Parameters Description index Identifier for the ADCP instance id An ADCP_DSH_ID type indicating which dedicated Class 1 S&H to configure for its alternate input source. Function void PLIB_ADCP_AlternateInputSelect( ADCP_MODULE_ID index, ADCP_DSH_ID id) PLIB_ADCP_DefaultInputSelect Function Selects the default physical input for the specified dedicated (Class 1) S&H. File plib_adcp.h C void PLIB_ADCP_DefaultInputSelect(ADCP_MODULE_ID index, ADCP_DSH_ID id); Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 235 Returns None. Description This function selects the default physical input for the specified S&H. Remarks None. Preconditions The function only applies to dedicated S&H circuits (Class 1 Inputs). Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Set S&H 1 to use the default input. PLIB_ADCP_DefaultInputSelect(MY_ADCP_INSTANCE, ADCP_DSH1) Parameters Parameters Description index Identifier for the ADCP instance id An ADCP_DSH_ID type indicating which dedicated Class 1 S&H to configure for its alternate input source. Function void PLIB_ADCP_DefaultInputSelect( ADCP_MODULE_ID index, ADCP_DSH_ID id) PLIB_ADCP_ExistsInputSelect Function Identifies whether the InputSelect feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsInputSelect(ADCP_MODULE_ID index); Returns Existence of the InputSelect feature: • true - When InputSelect feature is supported on the device • false - When InputSelect feature is not supported on the device Description This function identifies whether the InputSelect feature is available on the ADCP module. When this function returns true, this function is supported on the device: • PLIB_ADCP_DedicatedSHInputSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsInputSelect( ADCP_MODULE_ID index ) Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 236 PLIB_ADCP_ExistsModeSelect Function Identifies whether the ModeSelect feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsModeSelect(ADCP_MODULE_ID index); Returns Existence of the ModeSelect feature: • true - When ModeSelect feature is supported on the device • false - When ModeSelect feature is not supported on the device Description This function identifies whether the ModeSelect feature is available on the ADCP module. When this function returns true, this function is supported on the device: • PLIB_ADCP_SHModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsModeSelect( ADCP_MODULE_ID index ) PLIB_ADCP_SHModeSelect Function Selects the mode for the specified S&H. File plib_adcp.h C void PLIB_ADCP_SHModeSelect(ADCP_MODULE_ID index, ADCP_DSH_ID id, ADCP_SH_MODE mode); Returns None. Description This function selects the mode (single ended or differential) and encoding (unipolar or two's compliment) for the specified S&H. Remarks None. Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Set S&H 1 to use the single ended, two's complement mode // selection. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 237 PLIB_ADCP_SHModeSelect(MY_ADCP_INSTANCE, ADCP_SH1, ADCP_SH_MODE_SINGLE_ENDED_TWOS_COMP) Parameters Parameters Description index Identifier for the ADCP instance id An ADCP_DSH_ID type indicating which dedicated S&H to configure to use its alternate source mode An ADCP_SH_MODE type indicating the mode selection Function void PLIB_ADCP_SHModeSelect( ADCP_MODULE_ID index, ADCP_SH_ID id, ADCP_SH_MODE mode) d) Channel Scan Functions PLIB_ADCP_ChannelScanConfigure Function Selects input to include in Channel Scan Mode File plib_adcp.h C void PLIB_ADCP_ChannelScanConfigure(ADCP_MODULE_ID index, uint32_t lowEnable, uint32_t highEnable, ADCP_SCAN_TRG_SRC triggerSource); Returns None. Description This function selects inputs, as determined by the low and high enable scan list for inclusion in the channel scan sequence. If the input is a Class 1 or Class 2 type, it will also select the trigger source for that input to be the scan trigger, which is required if included in channel scanning. Remarks The type def AN_SELECT can be used to create a variable to simplify selection of the inputs to include in the channel scan. This typedef creates bit field structures for each ANx input that are joined with unions for the low and high 32-bit words. See the code example for Channel scan in the ADCP PLIB help documentation for details on its use. Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure Channel Scanning // Channels 10 through 13 // Trigger on Timer 1 match. PLIB_ADCP_ChannelScanConfigure(MY_ADCP_INSTANCE, 0XF000, // AN12 - AN15 0X0F00, // AN24 - AN27 ADCP_SCAN_TRG_SRC_TMR1_MATCH) Parameters Parameters Description index Identifier for the ADCP instance lowEnable bit mask for selecting low order scan channels Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 238 highEnable bit mask for selecting high order scan channels triggerSource Trigger source used to initiate channel scan Function void PLIB_ADCP_ChannelScanConfigure( ADCP_MODULE_ID index, uint32_t lowEnable, uint32_t highEnable, ADCP_SCAN_TRG_SRC triggerSource) PLIB_ADCP_ExistsChannelScan Function Identifies whether the ChannelScan feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsChannelScan(ADCP_MODULE_ID index); Returns Existence of the ChannelScan feature: • true - When ChannelScan feature is supported on the device • false - When ChannelScan feature is not supported on the device Description This function identifies whether the ChannelScan feature is available on the ADCP module. When this function returns true, this function is supported on the device: • PLIB_ADCP_ChannelScanConfigure Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsChannelScan( ADCP_MODULE_ID index ) e) Triggering Functions PLIB_ADCP_GlobalSoftwareTrigger Function Initiates a Global Software Trigger on the specified module. File plib_adcp.h C void PLIB_ADCP_GlobalSoftwareTrigger(ADCP_MODULE_ID index); Returns None. Description All inputs or scan list that is configured to trigger on the global software trigger are triggered by this function. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 239 Remarks None. Preconditions None. Example PLIB_ADCP_GlobalSoftwareTrigger(MY_ADCP_INSTANCE); Parameters Parameters Description index Identifier for the ADCP instance Function void PLIB_ADCP_GlobalSoftwareTrigger( ADCP_MODULE_ID index ) PLIB_ADCP_IndividualTrigger Function Triggers an individual channel independent of the configured trigger source File plib_adcp.h C void PLIB_ADCP_IndividualTrigger(ADCP_MODULE_ID index, ADCP_INPUT_ID inputId); Returns None. Description This function forces a trigger of an individual Class 1 or Class 2 channel independent of its configured trigger source. Remarks None. Preconditions The function only applies to Class 1 and Class 2 inputs. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Force a trigger of AN5 PLIB_ADCP_IndividualTrigger(MY_ADCP_INSTANCE, ADCP_CLASS12_AN5) Parameters Parameters Description index Identifier for the ADCP instance inputId An ADCP_INPUT_ID type indicating which input to trigger. Function void PLIB_ADCP_IndividualTrigger( ADCP_MODULE_ID index, ADCP_INPUT_ID inputId) PLIB_ADCP_Class12TriggerConfigure Function Configures a Class 1 or Class 2 Trigger Source. File plib_adcp.h Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 240 C void PLIB_ADCP_Class12TriggerConfigure(ADCP_MODULE_ID index, ADCP_CLASS12_INPUT_ID inputId, ADCP_TRG_SRC triggerSource); Returns none. Description This function configures the trigger source for Class 1 or Class 2 inputs. A call to this function is not required when the input is being used as part of a channel scan as the channel scan configure function also configures all trigger sources. Remarks None. Preconditions The function only applies to Class 1 and Class 2 inputs. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure AN0 for triggering from INT0. PLIB_ADCP_Class12TriggerConfigure(MY_ADCP_INSTANCE, ADCP_CLASS12_AN0, ADCP_TRG_SRC_INT0); Parameters Parameters Description index Identifier for the ADCP instance inputId Class 1 or Class 2 input to configure the trigger for. triggerSource Trigger source to use for this input. Function void PLIB_ADCP_Class12TriggerConfigure( ADCP_MODULE_ID index, ADCP_CLASS12_INPUT_ID inputId, ADCP_TRG_SRC triggerSource) PLIB_ADCP_ExistsTriggering Function Identifies whether the Triggering feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsTriggering(ADCP_MODULE_ID index); Returns Existence of the Triggering feature: • true - When Triggering feature is supported on the device • false - When Triggering feature is not supported on the device Description This function identifies whether the Triggering feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_Class12TriggerConfigure • PLIB_ADCP_GlobalSoftwareTrigger • PLIB_ADCP_IndividualTrigger Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 241 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsTriggering( ADCP_MODULE_ID index ) f) Individual Analog Input Conversion Results Functions PLIB_ADCP_ResultReady Function Returns the ADC conversion result ready bits for the module. File plib_adcp.h C AN_READY PLIB_ADCP_ResultReady(ADCP_MODULE_ID index); Returns A AN_READY type indicating conversion result status. Description This function returns a result indicating which analog inputs have conversion results ready. Remarks This function returns individual conversion results. It does not return results from the module. Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. AN_READY MyRdyStatus; // check for data and process it if ((MyRdyStatus = PLIB_ADCP_ResultReady(MY_ADCP_INSTANCE)) != 0) { // fetch the results and process } Parameters Parameters Description index Identifier for the ADCP instance Function AN_READY PLIB_ADCP_ResultReady( ADCP_MODULE_ID index ) PLIB_ADCP_ResultGet Function Returns a Pipelined ADC conversion result. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 242 File plib_adcp.h C int32_t PLIB_ADCP_ResultGet(ADCP_MODULE_ID index, ADCP_INPUT_ID inputId); Returns The conversion result expressed as a 32-bit integer. Description This function returns the specified Pipelined ADC analog input conversion result. Remarks None. Preconditions A valid conversion is ready to be fetched. Example int32_t result; ... // fetch result for AN31 result = PLIB_ADCP_ResultGet( MY_ADCP_INSTANCE, ADCP_AN31 ); Parameters Parameters Description index Identifier for the ADCP instance inputId Identifier for the input Function int32_t PLIB_ADCP_ResultGet( ADCP_MODULE_ID index, ADCP_INPUT_ID inputId ) PLIB_ADCP_ResultReadyGrpIntConfigure Function Selects input to include in global interrupt. File plib_adcp.h C void PLIB_ADCP_ResultReadyGrpIntConfigure(ADCP_MODULE_ID index, uint32_t lowEnable, uint32_t highEnable); Returns None. Description This function selects inputs, as determined by the input mask channel scan list for inclusion in the global or global interrupt. Remarks The type def AN_SELECT can be used to create a variable to simplify selection of the inputs to include in the global interrupt. This typedef creates bit field structures for each ANx input that are joined with unions for the low and high 32-bit words. See the code example for Channel scan in the ADCP PLIB help documentation for details on its use. Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure Global Interrupts // Analog inputs 10 through 13 are included in the global interrupt. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 243 PLIB_ADCP_ResultReadyGrpIntConfigure(MY_ADCP_INSTANCE, 0x0F00, // inputs AN8 - AN11 0x000F ); // inputs AN16 - AN19 Parameters Parameters Description index Identifier for the ADCP instance lowEnable bit mask for selecting low order scan channels highEnable bit mask for selecting high order scan channels Function void PLIB_ADCP_ResultReadyGrpIntConfigure( ADCP_MODULE_ID index, uint32_t lowEnable, uint32_t highEnable) PLIB_ADCP_ExistsConversionResults Function Identifies whether the ConversionResults feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsConversionResults(ADCP_MODULE_ID index); Returns Existence of the ConversionResults feature: • true - When ConversionResults feature is supported on the device • false - When ConversionResults feature is not supported on the device Description This function identifies whether the ConversionResults feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_ResultReady • PLIB_ADCP_ResultGet • PLIB_ADCP_ResultReadyGrpIntConfigure Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsConversionResults( ADCP_MODULE_ID index ) g) Digital Comparator Functions PLIB_ADCP_DigCmpEnable Function Enables the Digital Comparator in the Pipelined ADC module. File plib_adcp.h Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 244 C void PLIB_ADCP_DigCmpEnable(ADCP_MODULE_ID index, ADCP_DCMP_ID id); Returns None. Description This function enables (turns ON) the selected Digital Comparator in the specified Pipelined ADC module. Remarks None Preconditions The digital comparator should be configured using the PLIB_ADCP_Configure() function prior to enabling. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Enable Digital Comparator 1 PLIB_ADCP_DigCmpEnable(MY_ADCP_INSTANCE, ADCP_DCMP1); Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital comparator in the ADCP module. Function void PLIB_ADCP_DigCmpEnable( ADCP_MODULE_ID index, ADCP_DCMP_ID id ) PLIB_ADCP_DigCmpDisable Function Disables the Digital Comparator in the Pipelined ADC module. File plib_adcp.h C void PLIB_ADCP_DigCmpDisable(ADCP_MODULE_ID index, ADCP_DCMP_ID id); Returns None. Description This function Disables (turns OFF) the selected Digital Comparator in the specified Pipelined ADC module. Remarks None Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Disable Digital Comparator 1 PLIB_ADCP_DigCmpDisable(MY_ADCP_INSTANCE, ADCP_DCMP1); Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 245 Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital comparator in the ADCP module. Function void PLIB_ADCP_DigCmpDisable( ADCP_MODULE_ID index, ADCP_DCMP_ID id ) PLIB_ADCP_DigCmpAIdGet Function Returns the Analog Input ID of for the Comparator Event File plib_adcp.h C int16_t PLIB_ADCP_DigCmpAIdGet(ADCP_MODULE_ID index, ADCP_DCMP_ID id); Returns Value 'x' of type int16_t where 'x' is the index to the analog input ANx, which caused the event or -1 if no event has occurred. Description This function tests the DigCmp Event Flag and if true, returns the ANx Identifier for the input that caused the event, or -1 if there was no pending DigCmp event. The ID value returned corresponds to numeric portion of the analog input ID, ANx. Remarks None. Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. int16_t DigCmpResult; // Get Digital Comparator 1 result. DigCmpResult = PLIB_ADCP_DigCmpAIdGet(MY_ADCP_INSTANCE, ADCP_DCMP1); if (DigCmpResult != -1) { // process event } Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital comparator in the ADCP module Function int16_t PLIB_ADCP_DigCmpAIdGet( ADCP_MODULE_ID index, ADCP_DCMP_ID id ) PLIB_ADCP_DigCmpConfig Function Configures the Digital Comparator on the Pipelined ADC converter. File plib_adcp.h C void PLIB_ADCP_DigCmpConfig(ADCP_MODULE_ID index, ADCP_DCMP_ID id, bool globalIntEnable, bool inBetweenOrEqual, bool greaterEqualHi, bool lessThanHi, bool greaterEqualLo, bool lessThanLo, uint32_t inputEnable, int32_t hiLimit, int32_t loLimit); Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 246 Returns None. Description This function configures all parameters for the Digital Comparator module of the pipelined ADC. Remarks This function must be called when the ADC is disabled. The format of hiLimit and loLimit must match the output format of the channel(s) specified in inputEnable. Preconditions The module is disabled when calling this function. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure the Digital Comparator // Creates an event when the reading of AN0 is between 20% to 80% of the // full scale 12-bit output. PLIB_ADCP_DigCmpConfig( MY_ADCP_INSTANCE, // ADCP module ID ADCP_DCMP1, // Comparator ID FALSE, // Global Int Enable TRUE, // test for between low and high FALSE, // no test for greater than equal to high FALSE, // no test for less than high FALSE, // no test for greater than equal to low FALSE, // no test for less than low 1 << 3, // enable AN3 0x0CCD, // high limit, 80% of full scale 0x0333); // low limit, 20% of full scale // Enable Digital Comparator 1 PLIB_ADCP_DigCmpEnable(MY_ADCP_INSTANCE, ADCP_DCMP1); Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital comparator in this device globalIntEnable When set, comparator events are included in the Global Interrupt inBetweenOrEqual Event is generated when result is greater than or equal to loLimit and less than hiLimit greaterEqualHi Event is generated when result is greater than or equal to hiLimit lessThanHi Event is generated when result is less than hiLimit greaterEqualLo Event is generated when result is greater than or equal to loLimit lessThanLo Event is generated when result is less than loLimit inputEnable Bit field which determines which analog inputs are tested by this comparator module. Bit 0 applies to AN0 and bit 31 to AN31. hiLimit High limit in the same format as the conversion result. loLimit Low limit in the same format as the conversion result. Function void PLIB_ADCP_DigCmpConfig( ADCP_MODULE_ID index, // ADCP module ID ADCP_DCMP_ID id, // Comparator ID bool globalIntEnable, // Global Int Enable bool inBetweenOrEqual, // between low and high bool greaterEqualHi, // greater than equal to high bool lessThanHi, // less than high bool greaterEqualLo, // greater than equal to low bool lessThanLo, // less than low uint32_t inputEnable, // input enable bits Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 247 int32_t hiLimit, // high limit int32_t loLimit ) // low limit PLIB_ADCP_ExistsDigCmp Function Identifies whether the DigitalComparator feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsDigCmp(ADCP_MODULE_ID index); Returns Existence of the DigitalComparator feature: • true - When DigitalComparator feature is supported on the device • false - When DigitalComparator feature is not supported on the device Description This function identifies whether the DigitalComparator feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_DigCmpConfig • PLIB_ADCP_DigCmpEnable • PLIB_ADCP_DigCmpDisable • PLIB_ADCP_DigCmpAIdGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsDigCmp( ADCP_MODULE_ID index ) h) Oversampling Digital Filter Functions PLIB_ADCP_OsampDigFilterEnable Function Enables the Oversampling Digital Filter in the Pipelined ADC module File plib_adcp.h C void PLIB_ADCP_OsampDigFilterEnable(ADCP_MODULE_ID index, ADCP_ODFLTR_ID id); Returns None. Description This function enables (turns ON) the selected Oversampling Digital Filter in the specified Pipelined ADC module. Remarks None. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 248 Preconditions The Oversampling Digital Filter should be configured using the PLIB_ADCP_Configure() function prior to enabling. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Enable OsampDigFilter1 PLIB_ADCP_OsampDigFilterEnable(MY_ADCP_INSTANCE, ADCP_ODFLTR1); Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital Filter in the ADCP module Function void PLIB_ADCP_OsampDigFilterEnable( ADCP_MODULE_ID index, ADCP_ODFLTR_ID id ) PLIB_ADCP_OsampDigFilterDisable Function Disables the Oversampling Digital Filter in the Pipelined ADC module. File plib_adcp.h C void PLIB_ADCP_OsampDigFilterDisable(ADCP_MODULE_ID index, ADCP_ODFLTR_ID id); Returns None. Description This function Disables (turns OFF) the selected Oversampling Digital Filter in the specified Pipelined ADC module. Remarks None. Preconditions None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Disable OsampDigFilter1 PLIB_ADCP_OsampDigFilterDisable(MY_ADCP_INSTANCE, ADCP_ODFLTR1); Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital Filter in the ADCP module Function void PLIB_ADCP_OsampDigFilterDisable( ADCP_MODULE_ID index, ADCP_ODFLTR_ID id ) PLIB_ADCP_OsampDigFilterDataRdy Function Determines if the Oversampling Digital Filter has data ready. File plib_adcp.h Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 249 C bool PLIB_ADCP_OsampDigFilterDataRdy(ADCP_MODULE_ID index, ADCP_ODFLTR_ID id); Returns Boolean: • true - Data is ready • false - Data is not ready Description This function can be used to determine if the ADCP digital filter has data ready. A TRUE is returned when data is available, which can be fetched using PLIB_ADCP_OsampDigFilterDataGet. Remarks None. Preconditions None. Example if (PLIB_ADCP_OsampDigFilterDataRdy(MY_ADCP_INSTANCE, ADCP_ODFLTR_ID_0)) { // fetch and process data } Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital Filter in this device Function bool PLIB_ADCP_OsampDigFilterDataRdy( ADCP_MODULE_ID index, ADCP_ODFLTR_ID id ) PLIB_ADCP_OsampDigFilterDataGet Function Fetches the data result from the Oversampling Digital Filter. File plib_adcp.h C int16_t PLIB_ADCP_OsampDigFilterDataGet(ADCP_MODULE_ID index, ADCP_ODFLTR_ID id); Returns A 16-bit result in the format specified by the filter's oversampling setting. Description This function is used to fetch data from the Oversampling Digital Filter. The format of the data is determined by the oversampling setting configuration defined in the call of PLIB_ADCP_OsampDigFilterConfig. Remarks None. Preconditions None. Example int16_t myODFLTRResult; if (PLIB_ADCP_OsampDigFilterDataRdy(MY_ADCP_INSTANCE, ADCP_ODFLTR1)) { // fetch data myODFLTRResult = PLIB_ADCP_OsampDigFilterDataGet(MY_ADCP_INSTANCE, ADCP_ODFLTR1); // process result ... Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 250 } Parameters Parameters Description index Identifier for the ADCP instance dfltrID Identifier for the digital Filter in this device Function int16_t PLIB_ADCP_OsampDigFilterDataGet( ADCP_MODULE_ID index, ADCP_ODFLTR_ID dfltrID ) PLIB_ADCP_ExistsOsampDigFilter Function Identifies whether the OsampDigitalFilter feature exists on the ADCP module. File plib_adcp.h C bool PLIB_ADCP_ExistsOsampDigFilter(ADCP_MODULE_ID index); Returns Existence of the OsampDigitalFilter feature: • true - When OsampDigitalFilter feature is supported on the device • false - When OsampDigitalFilter feature is not supported on the device Description This function identifies whether the OsampDigitalFilter feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_OsampDigFilterConfig • PLIB_ADCP_OsampDigFilterEnable • PLIB_ADCP_OsampDigFilterDisable • PLIB_ADCP_OsampDigFilterDataRdy • PLIB_ADCP_OsampDigFilterDataGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ADCP_ExistsOsampDigFilter( ADCP_MODULE_ID index ) PLIB_ADCP_OsampDigFilterConfig Function Configures the Oversampling Digital Filter on the Pipelined ADC converter. File plib_adcp.h C void PLIB_ADCP_OsampDigFilterConfig(ADCP_MODULE_ID index, ADCP_ODFLTR_ID id, ADCP_INPUT_ID inputId, ADCP_ODFLTR_SAMPLE_RATIO oversampleRatio, bool globalIntEnable); Returns None. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 251 Description Configures all parameters for the Oversampling Digital Filter module of the pipelined ADC. Remarks This function must be called when the ADC is disabled. Preconditions The Oversampling Digital Filter module is disabled when calling this function. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure the Oversampling Digital Filter // AN4 is oversampled at a 16X rate. No global interrupt is enabled. PLIB_ADCP_OsampDigFilterConfig( MY_ADCP_INSTANCE, // ADCP module ID ADCP_ODFLTR1, // Filter ID ADCP_AN4, // Oversample AN4 ADCP_ODFLTR_16X, // 16 x oversampling FALSE ); // No Global Int Enable // Enable OsampDigFilter1 PLIB_ADCP_OsampDigFilterEnable(MY_ADCP_INSTANCE, ADCP_ODFLTR1); Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital Filter in this device inputId Identifier for the analog input to be oversampled oversampleRatio Enumerator specifying the oversampling ratio globalIntEnable When set, Filter events are included in the Global Interrupt Function void PLIB_ADCP_OsampDigFilterConfig( ADCP_MODULE_ID index, // ADCP module ID ADCP_ODFLTR_ID id, // Filter ID ADCP_INPUT_ID inputId, // Input Id ADCP_ODFLTR_OSR oversampleRatio, // Oversampling ratio bool globalIntEnable ) // Global Int Enable i) Data Types and Constants ADCP_MODULE_ID Enumeration Identifies the number of ADC Modules Supported. File help_plib_adcp.h C typedef enum { ADCP_ID_1, ADC_NUMBER_OF_MODULES } ADCP_MODULE_ID; Members Members Description ADCP_ID_1 ADC Module 1 ID ADC_NUMBER_OF_MODULES Number of available ADC modules. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 252 Description This enumeration identifies the available ADC modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. ADCP_VREF_SOURCE Enumeration Defines the ADCP VREF Source Select. File help_plib_adcp.h C typedef enum { ADCP_VREF_AVDD_AVSS, ADCP_VREF_VREFP_AVSS, ADCP_VREF_AVDD_VREFN, ADCP_VREF_VREFP_VREFN } ADCP_VREF_SOURCE; Members Members Description ADCP_VREF_AVDD_AVSS Reference voltage set to AVDD and AVSS ADCP_VREF_VREFP_AVSS Reference voltage set to VREF positive and AVSS ADCP_VREF_AVDD_VREFN Reference voltage set to AVDD and VREF negative ADCP_VREF_VREFP_VREFN Reference voltage set to VREF positive and VREF negative Description ADCP VREF Source Select This data type defines the ADCP Reference Voltage (VREF) Source Select. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCP_CLOCK_SOURCE Enumeration Defines the ADCP Clock Source Select. File help_plib_adcp.h C typedef enum { ADCP_CLK_SRC_NONE, ADCP_CLK_SRC_SYSCLK, ADCP_CLK_SRC_RFCLK3, ADCP_CLK_SRC_FRC } ADCP_CLOCK_SOURCE; Members Members Description ADCP_CLK_SRC_NONE TAD clock disabled ADCP_CLK_SRC_SYSCLK TAD clock set to SYSCLK (TCY) ADCP_CLK_SRC_RFCLK3 TAD clock set to REFCLK3 ADCP_CLK_SRC_FRC TAD clock set to FRC Description This enumeration data type defines the ADCP Clock Source Select. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 253 Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCP_CLASS12_INPUT_ID Enumeration Identifies the Class 1 and Class 2 ADC Inputs. File help_plib_adcp.h C typedef enum { ADCP_CLASS12_AN0, ADCP_CLASS12_AN1, ADCP_CLASS12_AN2, ADCP_CLASS12_AN3, ADCP_CLASS12_AN4, ADCP_CLASS12_AN5, ADCP_CLASS12_AN6, ADCP_CLASS12_AN7, ADCP_CLASS12_AN8, ADCP_CLASS12_AN9, ADCP_CLASS12_AN10, ADCP_CLASS12_AN11 } ADCP_CLASS12_INPUT_ID; Members Members Description ADCP_CLASS12_AN0 Analog Input AN0 ADCP_CLASS12_AN1 Analog Input AN1 ADCP_CLASS12_AN2 Analog Input AN2 ADCP_CLASS12_AN3 Analog Input AN3 ADCP_CLASS12_AN4 Analog Input AN4 ADCP_CLASS12_AN5 Analog Input AN5 ADCP_CLASS12_AN6 Analog Input AN6 ADCP_CLASS12_AN7 Analog Input AN7 ADCP_CLASS12_AN8 Analog Input AN8 ADCP_CLASS12_AN9 Analog Input AN9 ADCP_CLASS12_AN10 Analog Input AN10 ADCP_CLASS12_AN11 Analog Input AN11 Description ADC Class 1 and Class 2 Input ID This data type identifies the Class 1 and Class 2 ADC analog inputs. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCP_SH_ID Enumeration Identifies the supported S&H circuits regardless of type. File help_plib_adcp.h C typedef enum { ADCP_SH0, ADCP_SH1, ADCP_SH2, ADCP_SH3, ADCP_SH4, Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 254 ADCP_SH5, ADCP_NUMBER_OF_SH } ADCP_SH_ID; Members Members Description ADCP_SH0 S&H 0 ADCP_SH1 S&H 1 ADCP_SH2 S&H 2 ADCP_SH3 S&H 3 ADCP_SH4 S&H 4 ADCP_SH5 S&H 5 ADCP_NUMBER_OF_SH Number of S&H circuits Description ADCP S&H Select This enumeration identifies all supported S&H circuits. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCP_DSH_ID Enumeration Identifies the supported Dedicated Sample and Hold (S&H) circuits. File help_plib_adcp.h C typedef enum { ADCP_DSH0, ADCP_DSH1, ADCP_DSH2, ADCP_DSH3, ADCP_DSH4, ADCP_NUMBER_OF_DSH } ADCP_DSH_ID; Members Members Description ADCP_DSH0 Dedicated S&H 0 ADCP_DSH1 Dedicated S&H 1 ADCP_DSH2 Dedicated S&H 2 ADCP_DSH3 Dedicated S&H 3 ADCP_DSH4 Dedicated S&H 4 ADCP_NUMBER_OF_DSH Number of Dedicated S&H circuits Description ADCP Dedicated S&H Select This enumeration identifies the supported Dedicated S&H circuits. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCP_SH_MODE Enumeration Defines the available modes for the S&H. File help_plib_adcp.h Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 255 C typedef enum { ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR, ADCP_SH_MODE_SINGLE_ENDED_TWOS_COMP, ADCP_SH_MODE_DIFFERENTIAL_UNIPOLAR, ADCP_SH_MODE_DIFFERENTIAL_TWOS_COMP } ADCP_SH_MODE; Members Members Description ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR Single-ended input, Unipolar encoded ADCP_SH_MODE_SINGLE_ENDED_TWOS_COMP Single-ended input, two's compliment encoded ADCP_SH_MODE_DIFFERENTIAL_UNIPOLAR Differential input, Unipolar encoded ADCP_SH_MODE_DIFFERENTIAL_TWOS_COMP Differential input, two's compliment encoded Description ADCP S&H Mode This data type defines the available modes for the S&H. Remarks None. ADCP_INPUT_ID Enumeration Identifies the available ADC Inputs. File help_plib_adcp.h C typedef enum { ADCP_AN0, ADCP_AN1, ADCP_AN2, ADCP_AN3, ADCP_AN4, ADCP_AN5, ADCP_AN6, ADCP_AN7, ADCP_AN8, ADCP_AN9, ADCP_AN10, ADCP_AN11, ADCP_AN12, ADCP_AN13, ADCP_AN14, ADCP_AN15, ADCP_AN16, ADCP_AN17, ADCP_AN18, ADCP_AN19, ADCP_AN20, ADCP_AN21, ADCP_AN22, ADCP_AN23, ADCP_AN24, ADCP_AN25, ADCP_AN26, ADCP_AN27, ADCP_AN28, ADCP_AN29, ADCP_AN30, ADCP_AN31, ADCP_AN32, ADCP_AN33, ADCP_AN34, ADCP_AN35, ADCP_AN36, Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 256 ADCP_AN37 , ADCP_AN38 , ADCP_AN39 , ADCP_AN40 , ADCP_AN41 , ADCP_AN42 , ADCP_AN43 , ADCP_AN44 , ADCP_AN45 , ADCP_AN46 , ADCP_AN47 , ADCP_AN48 , ADCP_AN49 , ADCP_AN50 , ADCP_AN51 , ADCP_AN52 , ADCP_AN53 , ADCP_AN54 , ADCP_AN55 , ADCP_AN56 , ADCP_AN57 , ADCP_AN58 , ADCP_AN59 , ADCP_AN60 , ADCP_AN61 , ADCP_AN62 , ADCP_AN63 , ADCP_IVREF , ADCP_IVTEMP } ADCP_INPUT_ID; Members Members Description ADCP_AN0 Analog Input AN0 ADCP_AN1 Analog Input AN1 ADCP_AN2 Analog Input AN2 ADCP_AN3 Analog Input AN3 ADCP_AN4 Analog Input AN4 ADCP_AN5 Analog Input AN5 ADCP_AN6 Analog Input AN6 ADCP_AN7 Analog Input AN7 ADCP_AN8 Analog Input AN8 ADCP_AN9 Analog Input AN9 ADCP_AN10 Analog Input AN10 ADCP_AN11 Analog Input AN11 ADCP_AN12 Analog Input AN12 ADCP_AN13 Analog Input AN13 ADCP_AN14 Analog Input AN14 ADCP_AN15 Analog Input AN15 ADCP_AN16 Analog Input AN16 ADCP_AN17 Analog Input AN17 ADCP_AN18 Analog Input AN18 ADCP_AN19 Analog Input AN19 ADCP_AN20 Analog Input AN20 ADCP_AN21 Analog Input AN21 ADCP_AN22 Analog Input AN22 ADCP_AN23 Analog Input AN23 ADCP_AN24 Analog Input AN24 ADCP_AN25 Analog Input AN25 ADCP_AN26 Analog Input AN26 ADCP_AN27 Analog Input AN27 ADCP_AN28 Analog Input AN28 ADCP_AN29 Analog Input AN29 Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 257 ADCP_AN30 Analog Input AN30 ADCP_AN31 Analog Input AN31 ADCP_AN32 Analog Input AN32 ADCP_AN33 Analog Input AN33 ADCP_AN34 Analog Input AN34 ADCP_AN35 Analog Input AN35 ADCP_AN36 Analog Input AN36 ADCP_AN37 Analog Input AN37 ADCP_AN38 Analog Input AN38 ADCP_AN39 Analog Input AN39 ADCP_AN40 Analog Input AN40 ADCP_AN41 Analog Input AN41 ADCP_AN42 Analog Input AN42 ADCP_AN43 Analog Input AN43 ADCP_AN44 Analog Input AN44 ADCP_AN45 Analog Input AN45 ADCP_AN46 Analog Input AN46 ADCP_AN47 Analog Input AN47 ADCP_AN48 Analog Input AN48 ADCP_AN49 Analog Input AN49 ADCP_AN50 Analog Input AN50 ADCP_AN51 Analog Input AN51 ADCP_AN52 Analog Input AN52 ADCP_AN53 Analog Input AN53 ADCP_AN54 Analog Input AN54 ADCP_AN55 Analog Input AN55 ADCP_AN56 Analog Input AN56 ADCP_AN57 Analog Input AN57 ADCP_AN58 Analog Input AN58 ADCP_AN59 Analog Input AN59 ADCP_AN60 Analog Input AN60 ADCP_AN61 Analog Input AN61 ADCP_AN62 Analog Input AN62 ADCP_AN63 Analog Input AN63 ADCP_IVREF Analog Input for Internal Voltage Reference ADCP_IVTEMP Analog Input for Internal Temperature Sensor Description ADC Input ID This data type identifies the available ADC Inputs, regardless of Class. Remarks These are the super set enumerations provided for documentation, not all constants are available on all device. ADCP_DCMP_ID Enumeration Identifies the supported Digital Comparators. File help_plib_adcp.h C typedef enum { ADCP_DCMP1, ADCP_DCMP2, ADCP_DCMP3, ADCP_DCMP4, ADCP_DCMP5, Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 258 ADCP_DCMP6, ADCP_NUMBER_OF_DCMP } ADCP_DCMP_ID; Members Members Description ADCP_DCMP1 DCMP1 ADCP_DCMP2 DCMP2 ADCP_DCMP3 DCMP3 ADCP_DCMP4 DCMP4 ADCP_DCMP5 DCMP5 ADCP_DCMP6 DCMP6 ADCP_NUMBER_OF_DCMP Number of Digital Comparators Description ADCP Digital Comparator This enumeration identifies all supported Digital Comparators for this ADCP module. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCP_ODFLTR_ID Enumeration Identifies the supported Oversampling Digital Filters. File help_plib_adcp.h C typedef enum { ADCP_ODFLTR1, ADCP_ODFLTR2, ADCP_ODFLTR3, ADCP_ODFLTR4, ADCP_ODFLTR5, ADCP_ODFLTR6, ADCP_NUMBER_OF_ODFLTR } ADCP_ODFLTR_ID; Members Members Description ADCP_ODFLTR1 ODFLTR1 ADCP_ODFLTR2 ODFLTR2 ADCP_ODFLTR3 ODFLTR3 ADCP_ODFLTR4 ODFLTR4 ADCP_ODFLTR5 ODFLTR5 ADCP_ODFLTR6 ODFLTR6 ADCP_NUMBER_OF_ODFLTR Number of Oversampling Digital Filters Description ADCP Oversampling Digital Filter This enumeration identifies all supported Digital Filters for this ADCP module. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCP_ODFLTR_OSR Enumeration Identifies the supported Digital Filter oversampling ratios. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 259 File help_plib_adcp.h C typedef enum { ADCP_ODFLTR_4X, ADCP_ODFLTR_16X, ADCP_ODFLTR_64X, ADCP_ODFLTR_256X, ADCP_ODFLTR_2X, ADCP_ODFLTR_8X, ADCP_ODFLTR_32X, ADCP_ODFLTR_128X } ADCP_ODFLTR_OSR; Members Members Description ADCP_ODFLTR_4X 4x oversampling, shift sum 1 bit to right, output data is 13 bits ADCP_ODFLTR_16X 16x oversampling, shift sum 2 bits to right, output data is 14 bits ADCP_ODFLTR_64X 64x oversampling, shift sum 3 bits to right, output data is 15 bits ADCP_ODFLTR_256X 256x oversampling, shift sum 4 bits to right, output data is 16 bits ADCP_ODFLTR_2X 2x oversampling, shift sum 0 bits to right, output data is in 12.1 format ADCP_ODFLTR_8X 8x oversampling, shift sum 1 bit to right, output data is in 13.1 format ADCP_ODFLTR_32X 32x oversampling, shift sum 2 bits to right, output data is in 14.1 format ADCP_ODFLTR_128X 128x oversampling, shift sum 3 bit to right, output data is in 15.1 format Description ADCP Oversampling Ratio This enumeration identifies all supported Digital Filter oversampling ratios for this ADCP module. Oversampling ratios determine the number of samples used to generate a single output and the resulting resolution and format. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCP_SCAN_TRG_SRC Enumeration Defines the ADCP Channel Scan Trigger Source Selections. File help_plib_adcp.h C typedef enum { ADCP_SCAN_TRG_SRC_NONE, ADCP_SCAN_TRG_SRC_SOFTWARE, ADCP_SCAN_TRG_SRC_INT0, ADCP_SCAN_TRG_SRC_TMR1_MATCH, ADCP_SCAN_TRG_SRC_TMR3_MATCH, ADCP_SCAN_TRG_SRC_TMR5_MATCH, ADCP_SCAN_TRG_SRC_OCMP1, ADCP_SCAN_TRG_SRC_OCMP3, ADCP_SCAN_TRG_SRC_OCMP5, ADCP_SCAN_TRG_SRC_COMP1_COUT, ADCP_SCAN_TRG_SRC_COMP2_COUT } ADCP_SCAN_TRG_SRC; Members Members Description ADCP_SCAN_TRG_SRC_NONE No scan trigger source is selected ADCP_SCAN_TRG_SRC_SOFTWARE Global Software trigger selected as scan trigger source ADCP_SCAN_TRG_SRC_INT0 Interrupt 0 (INT0) selected as scan trigger source ADCP_SCAN_TRG_SRC_TMR1_MATCH Timer 1 Match (TMR1) selected as scan trigger source ADCP_SCAN_TRG_SRC_TMR3_MATCH Timer 3 Match (TMR3) selected as scan trigger source Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 260 ADCP_SCAN_TRG_SRC_TMR5_MATCH Timer 5 Match (TMR5) selected as scan trigger source ADCP_SCAN_TRG_SRC_OCMP1 Output Compare 1 (OCMP1) selected as scan trigger source ADCP_SCAN_TRG_SRC_OCMP3 Output Compare 3 (OCMP3) selected as scan trigger source ADCP_SCAN_TRG_SRC_OCMP5 Output Compare 5 (OCMP5) selected as scan trigger source ADCP_SCAN_TRG_SRC_COMP1_COUT Analog Comparator 1 (COUT) selected as scan trigger source ADCP_SCAN_TRG_SRC_COMP2_COUT Analog Comparator 2 (COUT) selected as scan trigger source Description ADCP Channel Scan Trigger Source Select This data type defines the ADCP Channel Scan Trigger Source Selections. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. ADCP_TRG_SRC Enumeration Defines the ADCP Trigger Source Selections. File help_plib_adcp.h C typedef enum { ADCP_TRG_SRC_NONE, ADCP_TRG_SRC_SOFTWARE, ADCP_TRG_SRC_SCAN_TRG, ADCP_TRG_SRC_INT0, ADCP_TRG_SRC_TMR1_MATCH, ADCP_TRG_SRC_TMR3_MATCH, ADCP_TRG_SRC_TMR5_MATCH, ADCP_TRG_SRC_OCMP1, ADCP_TRG_SRC_OCMP3, ADCP_TRG_SRC_OCMP5, ADCP_TRG_SRC_COMP1_COUT, ADCP_TRG_SRC_COMP2_COUT } ADCP_TRG_SRC; Members Members Description ADCP_TRG_SRC_NONE No trigger source is selected ADCP_TRG_SRC_SOFTWARE Global Software trigger selected as the trigger source ADCP_TRG_SRC_SCAN_TRG Use the Channel Scan Trigger as the trigger source (input is part of ch scan) ADCP_TRG_SRC_INT0 Interrupt 0 (INT0) selected as the trigger source ADCP_TRG_SRC_TMR1_MATCH Timer 1 Match (TMR1) selected as the trigger source ADCP_TRG_SRC_TMR3_MATCH Timer 3 Match (TMR3) selected as the trigger source ADCP_TRG_SRC_TMR5_MATCH Timer 5 Match (TMR5) selected as the trigger source ADCP_TRG_SRC_OCMP1 Output Compare 1 (OCMP1) selected as the trigger source ADCP_TRG_SRC_OCMP3 Output Compare 3 (OCMP3) selected as the trigger source ADCP_TRG_SRC_OCMP5 Output Compare 5 (OCMP5) selected as the trigger source ADCP_TRG_SRC_COMP1_COUT Analog Comparator 1 (COUT) selected as the trigger source ADCP_TRG_SRC_COMP2_COUT Analog Comparator 2 (COUT) selected as the trigger source Description ADCP Trigger Source Select This data type defines the ADCP Trigger Source Selections. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 261 AN_SELECT Union This union of structures is provided to simply selection of analog inputs for inclusion in a particular function. File plib_adcp.h C union AN_SELECT { int ret_val; struct { uint32_t lowWord; uint32_t highWord; }; struct { uint32_t AN0 : 1; uint32_t AN1 : 1; uint32_t AN2 : 1; uint32_t AN3 : 1; uint32_t AN4 : 1; uint32_t AN5 : 1; uint32_t AN6 : 1; uint32_t AN7 : 1; uint32_t AN8 : 1; uint32_t AN9 : 1; uint32_t AN10 : 1; uint32_t AN11 : 1; uint32_t AN12 : 1; uint32_t AN13 : 1; uint32_t AN14 : 1; uint32_t AN15 : 1; uint32_t AN16 : 1; uint32_t AN17 : 1; uint32_t AN18 : 1; uint32_t AN19 : 1; uint32_t AN20 : 1; uint32_t AN21 : 1; uint32_t AN22 : 1; uint32_t AN23 : 1; uint32_t AN24 : 1; uint32_t AN25 : 1; uint32_t AN26 : 1; uint32_t AN27 : 1; uint32_t AN28 : 1; uint32_t AN29 : 1; uint32_t AN30 : 1; uint32_t AN31 : 1; uint32_t AN32 : 1; uint32_t AN33 : 1; uint32_t AN34 : 1; uint32_t AN35 : 1; uint32_t AN36 : 1; uint32_t AN37 : 1; uint32_t AN38 : 1; uint32_t AN39 : 1; uint32_t AN40 : 1; uint32_t AN41 : 1; uint32_t AN42 : 1; uint32_t AN43 : 1; uint32_t AN44 : 1; uint32_t AN45 : 1; uint32_t AN46 : 1; uint32_t AN47 : 1; uint32_t AN48 : 1; uint32_t AN49 : 1; uint32_t AN50 : 1; uint32_t AN51 : 1; uint32_t AN52 : 1; uint32_t AN53 : 1; uint32_t AN54 : 1; uint32_t AN55 : 1; uint32_t AN56 : 1; Peripheral Libraries Help ADCP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 262 uint32_t AN57 : 1; uint32_t AN58 : 1; uint32_t AN59 : 1; uint32_t AN60 : 1; uint32_t AN61 : 1; uint32_t AN62 : 1; uint32_t AN63 : 1; }; }; Description ADCP AN Select Union The structure labels identify the analog inputs associated with each bit when initializing the structure. Unsigned 32-bit integers, lowWord and highWord are used as arguments to the function. Remarks See the Channel Scanning example in the ADCP Help documentation regarding use of this type define. AN_READY Type This union (identical to the AN_SELECT union) is used as the return value by the PLIB_ADCP_Result_Ready function. File plib_adcp.h C typedef AN_SELECT AN_READY; Description ADCP AN Ready Union The structure labels identify the analog inputs associated with each bit for testing ready status of individual inputs. Unsigned 32-bit integers, lowWord and highWord allow for testing ready status of groups of bits using a mask. Remarks See the Simultaneous Sampling or Channel Scanning examples in the ADCP Help documentation regarding use of this type define. Files Files Name Description plib_adcp.h ADCP Peripheral Library Interface Header for ADCP common definitions help_plib_adcp.h ADCP Peripheral Library interface header file template. Description This section lists the source and header files used by the library. plib_adcp.h ADCP Peripheral Library Interface Header for ADCP common definitions Functions Name Description PLIB_ADCP_AlternateInputSelect Selects the alternate physical input for the specified dedicated (Class 1) S&H. PLIB_ADCP_CalibrationStart Initiates Pipelined ADC Calibration. PLIB_ADCP_ChannelScanConfigure Selects input to include in Channel Scan Mode PLIB_ADCP_Class12TriggerConfigure Configures a Class 1 or Class 2 Trigger Source. PLIB_ADCP_Configure Configures the Pipelined ADC module including the ADC calibration registers. PLIB_ADCP_DefaultInputSelect Selects the default physical input for the specified dedicated (Class 1) S&H. PLIB_ADCP_DigCmpAIdGet Returns the Analog Input ID of for the Comparator Event PLIB_ADCP_DigCmpConfig Configures the Digital Comparator on the Pipelined ADC converter. Peripheral Libraries Help ADCP Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 263 PLIB_ADCP_DigCmpDisable Disables the Digital Comparator in the Pipelined ADC module. PLIB_ADCP_DigCmpEnable Enables the Digital Comparator in the Pipelined ADC module. PLIB_ADCP_Disable Pipelined ADC module is disabled (turned OFF). PLIB_ADCP_Enable Enables the Pipelined ADC module. PLIB_ADCP_ExistsCalibration Identifies whether the Calibration feature exists on the ADCP module. PLIB_ADCP_ExistsChannelScan Identifies whether the ChannelScan feature exists on the ADCP module. PLIB_ADCP_ExistsConfiguration Identifies whether the Configuration feature exists on the ADCP module. PLIB_ADCP_ExistsConversionResults Identifies whether the ConversionResults feature exists on the ADCP module. PLIB_ADCP_ExistsDigCmp Identifies whether the DigitalComparator feature exists on the ADCP module. PLIB_ADCP_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADCP module. PLIB_ADCP_ExistsInputSelect Identifies whether the InputSelect feature exists on the ADCP module. PLIB_ADCP_ExistsLowPowerControl Identifies whether the LowPowerControl feature exists on the ADCP module. PLIB_ADCP_ExistsModeSelect Identifies whether the ModeSelect feature exists on the ADCP module. PLIB_ADCP_ExistsOsampDigFilter Identifies whether the OsampDigitalFilter feature exists on the ADCP module. PLIB_ADCP_ExistsReadyStatus Identifies whether the ReadyStatus feature exists on the ADCP module. PLIB_ADCP_ExistsTriggering Identifies whether the Triggering feature exists on the ADCP module. PLIB_ADCP_GlobalSoftwareTrigger Initiates a Global Software Trigger on the specified module. PLIB_ADCP_IndividualTrigger Triggers an individual channel independent of the configured trigger source PLIB_ADCP_LowPowerStateEnter Places the Pipelined ADC module in a low power state. PLIB_ADCP_LowPowerStateExit Takes the Pipelined ADC module out of low power state and puts it into an operational mode. PLIB_ADCP_LowPowerStateGet Returns the state of the low power setting. PLIB_ADCP_ModuleIsReady Returns the overall ready status of the module. PLIB_ADCP_OsampDigFilterConfig Configures the Oversampling Digital Filter on the Pipelined ADC converter. PLIB_ADCP_OsampDigFilterDataGet Fetches the data result from the Oversampling Digital Filter. PLIB_ADCP_OsampDigFilterDataRdy Determines if the Oversampling Digital Filter has data ready. PLIB_ADCP_OsampDigFilterDisable Disables the Oversampling Digital Filter in the Pipelined ADC module. PLIB_ADCP_OsampDigFilterEnable Enables the Oversampling Digital Filter in the Pipelined ADC module PLIB_ADCP_ResultGet Returns a Pipelined ADC conversion result. PLIB_ADCP_ResultReady Returns the ADC conversion result ready bits for the module. PLIB_ADCP_ResultReadyGrpIntConfigure Selects input to include in global interrupt. PLIB_ADCP_SHModeSelect Selects the mode for the specified S&H. Types Name Description AN_READY This union (identical to the AN_SELECT union) is used as the return value by the PLIB_ADCP_Result_Ready function. Unions Name Description AN_SELECT This union of structures is provided to simply selection of analog inputs for inclusion in a particular function. Description Pipelined Analog-to-Digital Converter (ADCP) Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the ADCP PLIB for all families of Microchip microcontrollers. The definitions in this file are common to the ADCP peripheral. File Name plib_adcp.h Company Microchip Technology Inc. help_plib_adcp.h ADCP Peripheral Library interface header file template. Peripheral Libraries Help ADCP Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 264 Enumerations Name Description ADCP_CLASS12_INPUT_ID Identifies the Class 1 and Class 2 ADC Inputs. ADCP_CLOCK_SOURCE Defines the ADCP Clock Source Select. ADCP_DCMP_ID Identifies the supported Digital Comparators. ADCP_DSH_ID Identifies the supported Dedicated Sample and Hold (S&H) circuits. ADCP_INPUT_ID Identifies the available ADC Inputs. ADCP_MODULE_ID Identifies the number of ADC Modules Supported. ADCP_ODFLTR_ID Identifies the supported Oversampling Digital Filters. ADCP_ODFLTR_OSR Identifies the supported Digital Filter oversampling ratios. ADCP_SCAN_TRG_SRC Defines the ADCP Channel Scan Trigger Source Selections. ADCP_SH_ID Identifies the supported S&H circuits regardless of type. ADCP_SH_MODE Defines the available modes for the S&H. ADCP_TRG_SRC Defines the ADCP Trigger Source Selections. ADCP_VREF_SOURCE Defines the ADCP VREF Source Select. Description ADCP Peripheral Library Interface Header File Template This file is used by the DOM project. File Name help_plib_adcp.h Company Microchip Technology Inc. Peripheral Libraries Help ADCP Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 265 BMX Peripheral Library This section describes the Bus Matrix (BMX) Peripheral Library. Introduction This library provides a low-level abstraction of the Bus Matrix (BMX) modules on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description The Bus Matrix is essentially a high-speed switch that establishes connections between devices. Devices can be either master (initiator) or slave (target). The Bus Matrix also performs these other important functions: • Partition memory - The Bus Matrix provides the ability to partition both RAM and Flash memory into kernel and user areas. It also controls the type of access, program or data, for each memory area. • Enable/disable program Flash memory cache for Direct Memory Access (DMA) • Enable/disable bus error exceptions - The Bus Matrix provides the ability to disable bus error exceptions for debugging. They are enabled by default. • Set Bus Arbitration mode - The Bus Matrix provides the ability to select between arbitration modes. The arbitration modes control the order and priority of initiator access to peripherals. Using the Library This topic describes the basic architecture of the BMX Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_bmx.h The interface to the BMX library is defined in the plib_bmx.h header file, which is included by the peripheral.h peripheral library header file. Any C language source (.c) file that uses the BMX library must include peripheral.h. Library File: The BMX Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the BMX module on Microchip family microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The following figure shows the Bus Matrix hardware abstraction model. Hardware Abstraction Model Peripheral Libraries Help BMX Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 266 The BMX Peripheral Library provides interface routines to interact with the blocks shown in the previous diagram. The Exception Generator generates a bus error exception for unmapped address accesses from all Bus Matrix initiators: • Initiator Expansion Interface (IXI) shared bus • In-Circuit Debug (ICD) unit • Direct Memory Access (DMA) controller • CPU data bus • CPU instruction bus Each of the initiators can be individually enabled or disabled with Exception Generator peripheral library routines. All are enabled by default. The Cache Control simply enables/disables program Flash memory (PFM) data cacheability for DMA accesses. The default setting is disabled. When enabled, the PCACHE module must have data caching enabled. The Bus Arbitrator assigns priority levels to bus initiators following one of three priority schemes: • Fixed, with CPU higher than DMA • Fixed, with DMA higher than CPU (default) • Rotating between four priority sequences The Memory Access Control partitions program Flash memory and RAM into kernel and user areas. The RAM can be further partitioned into data and program segments for both kernel and user areas. By default, the full PFM and RAM are mapped to Kernel mode. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the BMX module. Library Interface Section Description Bus Exception Routines Provide an interface to individually enable or disable initiator access to unmapped memory. Program Flash Cache Routines Provide an interface to enable or disable caching of DMA accesses to Program Flash Memory. Arbiter Routines Provide an interface to set or change the bus initiator priority sequence. Memory Access Control Routines Provide an interface to partition Program Flash and Data Memories into user and kernel regions. Provide an interface to read the size of the Boot Flash, Program Flash and Data SRAM memories. Feature Existence Routines These functions determine whether or not a particular feature is supported by the device. How the Library Works The Bus Matrix is initialized in the start-up code, before an application is invoked. Most applications will not need to modify the Bus Matrix default settings. The BMX Peripheral Library is available for those applications requiring more complex memory partitioning, including operating systems and applications requiring specialized memory access. The ability to disable exceptions for unmapped memory access may be useful for debugging, but is not recommended for normal use. Changes to the arbitration scheme may improve performance for CPU or DMA intensive applications. Peripheral Libraries Help BMX Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 267 Exception Generator Any unmapped address access by a Bus Matrix initiator will by default generate an exception. These exceptions may be individually enabled or disabled with the peripheral library. Example: Enable CPU instruction exception // Enable CPU instruction exception PLIB_BMX_ISBusExceptionEnable(); Cache Control This peripheral library function enables program Flash memory (data) cacheability for DMA accesses. Data caching must be enabled in the Pcache. Hits are still read from the cache, but misses do not update the cache. This function is disabled by default. Example: Enable PFM Cacheability for DMA access PLIB_BMX_EnablePfmCacheDma() Bus Arbiter Since there can be more than one initiator attempting to access the same target, an arbitration scheme must be used to control access to the target. The arbitration modes assign priority levels to all the initiators. The initiator with the higher priority level will always win target access over a lower priority initiator. The BMX Bus Arbitrator allows the programmer to select from one of three arbitration modes. PLIB_BMX_ARB_MODE_INST Arbitration mode 0 is a fixed priority scheme, with the CPU given higher priority than DMA. This mode can starve the DMA, so choose this mode when DMA is not being used. PLIB_BMX_ARB_MODE_DMA Arbitration Mode 1 is a fixed priority scheme like Mode 0, except that the CPU is always the lowest priority. Mode 1 is the default mode. Peripheral Libraries Help BMX Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 268 PLIB_BMX_ARB_MODE_ROT Mode 2 arbitration supports rotating priority assignments to all initiators. Instead of a fixed priority assignment, each initiator is assigned the highest priority in a rotating fashion. In this mode, the rotating priority is applied with the following exceptions: 1. CPU data is always selected over CPU instruction. 2. ICD is always the highest priority. 3. When the CPU is processing an exception (EXL = 1) or an error (ERL = 1), the arbitrator temporarily reverts to Mode 0. Note: Priority Sequence 2 is not selected in the rotation priority scheme if there is a pending CPU data access. In this case, once the data access is complete, Sequence 2 is selected. Example: Set Bus Arbitration Mode to Rotating Priority PLIB_BMX_SetArbitrationMode(PLIB_BMX_ARB_ROT); Memory Access Control The Bus Matrix allows the programmer to partition program Flash memory into user and kernel partitions. It also allows the programmer to partition data RAM into user and kernel partitions, each of which can be sub-divided into program and data partitions. At reset, the entire program Flash memory is one kernel partition and the entire data RAM is one kernel data partition. Peripheral Libraries Help BMX Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 269 Program Flash Memory Partitioning Partitioning of the program Flash memory is accomplished by setting the offset of the user partition within the program Flash memory using the PLIB_BMX_ProgramFlashPartitionSet function. The size of the program Flash memory varies among devices, but can be retrieved with the PLIB_BMX_ProgramFlashMemorySizeGet function. The offset must be a multiple of the program Flash memory block size. The program Flash memory block size may vary among devices. If programmed with a value that is not a multiple of the block size, the value will automatically be truncated to a block size boundary. At reset, the entire program Flash memory is mapped to Kernel mode. Example: Create a User Mode Partition of 12K in Program Flash Memory size_t pfmSize; size_t userSize = (6 * PLIB_PCACHE_PFM_BLOCK_SIZE); size_t userOffset; // Get size of PFM pfmSize = PLIB_BMX_ProgramFlashMemorySizeGet(); userOffset = pfmSize - userSize; if (userOffset > 0) { PLIB_BMX_ProgramFlashPartitionSet(userOffset); } Data RAM Memory Partitioning The Data RAM Can be partitioned into four sections: • Kernel Data • Kernel Program • User Data • User Program Similar to the program Flash memory partitioning, the data RAM partitions are created by setting the base addresses of the various partitions. The BMX Peripheral Library provides a function to set all of the partitions at once. The size of the data RAM varies among devices, but may be retrieved with the PLIB_BMX_DataRAMSizeGet function. The partitions must be a multiple of the Data RAM memory block size. The data RAM memory block size may vary among devices. If programmed with a value that is not a multiple of the block size, the partition will automatically be truncated to a block size boundary. At reset, the entire data RAM is mapped to Kernel mode. Note: At Reset, the entire data RAM is mapped to Kernel mode and all of the offsets are set to zero. To partition the data RAM, all of the offsets must be programmed. If any of the offsets are set to zero, the entire data RAM is allocated to kernel data. Peripheral Libraries Help BMX Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 270 Example: RAM Partitioned as Kernel Data, Kernel Program, User Data and User Program //Total Data RAM = 32KB. size_t totalRamSize; size_t kernProgOffset; size_t userDataOffset; size_t userProgOffset; size_t kernDataRamSize = (3 * PLIB_PCACHE_DRM_BLOCK_SIZE); //Kernel Data RAM = 6KB size_t kernProgRamSize = (2 * PLIB_PCACHE_DRM_BLOCK_SIZE); //Kernel Program RAM = 4KB size_t userDataRamSize = (6 * PLIB_PCACHE_DRM_BLOCK_SIZE); //User Data RAM = 12KB size_t userProgRamSize = (5 * PLIB_PCACHE_DRM_BLOCK_SIZE); //User Program RAM = 10KB //Get Size of Data RAM totalRamSize = PLIB_BMX_DataRAMSizeGet(); //Verify our partition sizes fit our RAM if ((kernDataRamSize + kernProgRamSize + userDataRamSize + userProgRamSize) != totalRamSize) { printf("RAM Partitioning Error\n"); return -1; } kernProgOffset = kernDataRamSize; userDataOffset = kernDataRamSize + kernProgRamSize; userProgOffset = userDataOffset + userDataRamSize; PLIB_BMX_DataRAMPartitionSet(kernProgOffset, userDataOffset, userProgOffset); Example: Determine the size of Data RAM partitions size_t kernProgOffset; size_t userDataOffset; size_t userProgOffset; size_t kernDataPart; size_t kernProgPart; size_t userDataPart; size_t userProgPart; size_t totalRamSize; totalRamSize = PLIB_BMX_DataRAMSizeGet(); kernProgOffset = PLIB_BMX_DataRAMKernelProgramOffsetGet(); userDataOffset = PLIB_BMX_DataRAMUserDataOffsetGet(); userProgOffset = PLIB_BMX_DataRAMUserProgramOffsetGet(); kernDataPart = kernProgOffset; kernProgPart = userDataOffset - kernProgOffset; Peripheral Libraries Help BMX Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 271 userDataPart = userProgOffset - userDataOffset; userProgPart = totalRamSize - userProgOffset; Configuring the Library The library is configured for the supported BMX module when the processor is chosen in the MPLAB X IDE. Library Interface a) Bus Exception Functions Name Description PLIB_BMX_BusExceptionDataDisable Disables the data bus exception. PLIB_BMX_BusExceptionDataEnable Enables the Data bus exception. PLIB_BMX_BusExceptionDMADisable Disables the DMA bus exception. PLIB_BMX_BusExceptionDMAEnable Enables the DMA bus exception. PLIB_BMX_BusExceptionICDDisable Disables the ICD bus exception. PLIB_BMX_BusExceptionICDEnable Enables the ICD bus exception. PLIB_BMX_BusExceptionInstructionDisable Disables the instruction bus exception. PLIB_BMX_BusExceptionInstructionEnable Enables the instruction bus exception. PLIB_BMX_BusExceptionIXIDisable Disables the IXI bus exception. PLIB_BMX_BusExceptionIXIEnable Enables the IXI bus exception. b) Program Flash Cache Functions Name Description PLIB_BMX_ProgramFlashMemoryCacheDmaDisable Disables the bus matrix program Flash cacheability for DMA. PLIB_BMX_ProgramFlashMemoryCacheDmaEnable Enables the bus matrix program Flash cacheability for DMA. c) Arbiter Functions Name Description PLIB_BMX_ArbitrationModeGet Returns the bus matrix arbitration mode. PLIB_BMX_ArbitrationModeSet Sets the bus matrix arbitration mode. d) Memory Access Control Functions Name Description PLIB_BMX_DataRAMKernelProgramOffsetGet Gets the offset (from start of RAM) of the kernel program partition. PLIB_BMX_DataRAMPartitionSet Sets the size of the kernel and user partitions in data RAM memory. PLIB_BMX_DataRAMSizeGet Gets the size of data RAM memory. PLIB_BMX_DataRAMUserDataOffsetGet Gets the offset (from start of RAM) of the user data partition. PLIB_BMX_DataRAMUserProgramOffsetGet Gets the offset (from start of RAM) of the user program partition. PLIB_BMX_DataRamWaitStateGet Returns the number of data RAM Wait states. PLIB_BMX_DataRamWaitStateSet Sets the number of data RAM Wait states. PLIB_BMX_ProgramFlashBootSizeGet Gets the size of boot program Flash memory. PLIB_BMX_ProgramFlashMemorySizeGet Gets the size of program Flash memory. PLIB_BMX_ProgramFlashPartitionGet Gets the size of the kernel partition in program Flash memory. PLIB_BMX_ProgramFlashPartitionSet Sets the size of the kernel and user partitions in program Flash memory. e) Feature Existence Functions Name Description PLIB_BMX_ExistsArbitrationMode Identifies that the ArbitrationMode feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionData Identifies that the BusExceptionData feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionDMA Identifies that the BusExceptionDMA feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionICD Identifies that the BusExceptionICD feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionInstruction Identifies that the BusExceptionInstruction feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionIXI Identifies that the BusExceptionIXI feature exists on the BMX module. PLIB_BMX_ExistsDataRAMPartition Identifies that the DataRAMPartition feature exists on the BMX module. PLIB_BMX_ExistsDataRAMSize Identifies that the DataRAMSize feature exists on the BMX module. Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 272 PLIB_BMX_ExistsDataRamWaitState Identifies that the DataRamWaitState feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashBootSize Identifies that the ProgramFlashBootSize feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashMemoryCacheDma Identifies that the ProgramFlashMemoryCacheDma feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashMemorySize Identifies that the ProgramFlashMemorySize feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashPartition Identifies that the ProgramFlashPartition feature exists on the BMX module. f) Data Types and Constants Name Description BMX_MODULE_ID Lists the possible Module IDs for the bus matrix. PLIB_BMX_ARB_MODE Lists the possible arbitration modes for the bus matrix. PLIB_BMX_DATA_RAM_WAIT_STATES Defines the number of data RAM wait states for address setup. PLIB_BMX_EXCEPTION_SRC Defines which events trigger a bus exception. PLIB_BMX_DRM_BLOCK_SIZE Defines the minimum partition block size in data RAM memory. PLIB_BMX_PFM_BLOCK_SIZE Defines the minimum partition block size in program Flash memory. Description This section describes the Application Programming Interface (API) functions of the BMX Peripheral Library. Refer to each section for a detailed description. a) Bus Exception Functions PLIB_BMX_BusExceptionDataDisable Function Disables the data bus exception. File plib_bmx.h C void PLIB_BMX_BusExceptionDataDisable(BMX_MODULE_ID index); Returns None. Description This function disables the data bus exception. Remarks This function implements an operation of the BusExceptionData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionData in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_BusExceptionDataDisable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be disabled Function void PLIB_BMX_BusExceptionDataDisable( BMX_MODULE_ID index ) Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 273 PLIB_BMX_BusExceptionDataEnable Function Enables the Data bus exception. File plib_bmx.h C void PLIB_BMX_BusExceptionDataEnable(BMX_MODULE_ID index); Returns None. Description This function enables the Data bus exception. Remarks This function implements an operation of the BusExceptionData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionData in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_BusExceptionDataEnable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be enabled Function void PLIB_BMX_BusExceptionDataEnable( BMX_MODULE_ID index ) PLIB_BMX_BusExceptionDMADisable Function Disables the DMA bus exception. File plib_bmx.h C void PLIB_BMX_BusExceptionDMADisable(BMX_MODULE_ID index); Returns None. Description This function disables the DMA bus exception. Remarks This function implements an operation of the BusExceptionDMA feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionDMA in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_BusExceptionDMADisable(BMX_ID_0); Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 274 Parameters Parameters Description index Identifier for the device instance to be disabled Function void PLIB_BMX_BusExceptionDMADisable( BMX_MODULE_ID index ) PLIB_BMX_BusExceptionDMAEnable Function Enables the DMA bus exception. File plib_bmx.h C void PLIB_BMX_BusExceptionDMAEnable(BMX_MODULE_ID index); Returns None. Description This function enables the DMA bus exception. Remarks This function implements an operation of the BusExceptionDMA feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionDMA in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_BusExceptionDMAEnable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be enabled Function void PLIB_BMX_BusExceptionDMAEnable( BMX_MODULE_ID index ) PLIB_BMX_BusExceptionICDDisable Function Disables the ICD bus exception. File plib_bmx.h C void PLIB_BMX_BusExceptionICDDisable(BMX_MODULE_ID index); Returns None. Description This function disables the ICD bus exception. Remarks This function implements an operation of the BusExceptionICD feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionICD in your application to automatically determine whether this feature is available. Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 275 Preconditions None. Example PLIB_BMX_BusExceptionICDDisable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be disabled Function void PLIB_BMX_BusExceptionICDDisable( BMX_MODULE_ID index ) PLIB_BMX_BusExceptionICDEnable Function Enables the ICD bus exception. File plib_bmx.h C void PLIB_BMX_BusExceptionICDEnable(BMX_MODULE_ID index); Returns None. Description This function enables the ICD bus exception. Remarks This function implements an operation of the BusExceptionICD feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionICD in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_BusExceptionICDEnable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be enabled Function void PLIB_BMX_BusExceptionICDEnable( BMX_MODULE_ID index ) PLIB_BMX_BusExceptionInstructionDisable Function Disables the instruction bus exception. File plib_bmx.h C void PLIB_BMX_BusExceptionInstructionDisable(BMX_MODULE_ID index); Returns None. Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 276 Description This function disables the instruction bus exception. Remarks This function implements an operation of the BusExceptionInstruction feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionInstruction in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_BusExceptionInstructionDisable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be disabled Function void PLIB_BMX_BusExceptionInstructionDisable( BMX_MODULE_ID index ) PLIB_BMX_BusExceptionInstructionEnable Function Enables the instruction bus exception. File plib_bmx.h C void PLIB_BMX_BusExceptionInstructionEnable(BMX_MODULE_ID index); Returns None. Description This function enables the instruction bus exception. Remarks This function implements an operation of the BusExceptionInstruction feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionInstruction in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_BusExceptionInstructionEnable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be enabled Function void PLIB_BMX_BusExceptionInstructionEnable( BMX_MODULE_ID index ) PLIB_BMX_BusExceptionIXIDisable Function Disables the IXI bus exception. File plib_bmx.h Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 277 C void PLIB_BMX_BusExceptionIXIDisable(BMX_MODULE_ID index); Returns None. Description This function disables the IXI bus exception. Remarks This function implements an operation of the BusExceptionIXI feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionIXI in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_BusExceptionIXIDisable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be disabled Function void PLIB_BMX_BusExceptionIXIDisable( BMX_MODULE_ID index ) PLIB_BMX_BusExceptionIXIEnable Function Enables the IXI bus exception. File plib_bmx.h C void PLIB_BMX_BusExceptionIXIEnable(BMX_MODULE_ID index); Returns None. Description This function enables the IXI bus exception. Remarks This function implements an operation of the BusExceptionIXI feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionIXI in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_BusExceptionIXIEnable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be enabled Function void PLIB_BMX_BusExceptionIXIEnable( BMX_MODULE_ID index ) Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 278 b) Program Flash Cache Functions PLIB_BMX_ProgramFlashMemoryCacheDmaDisable Function Disables the bus matrix program Flash cacheability for DMA. File plib_bmx.h C void PLIB_BMX_ProgramFlashMemoryCacheDmaDisable(BMX_MODULE_ID index); Returns None. Description This function disables the program Flash cacheability for DMA. Remarks This function implements an operation of the ProgramFlashMemoryCacheDma feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashMemoryCacheDma in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_ProgramFlashMemoryCacheDmaDisable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be disabled Function void PLIB_BMX_ProgramFlashMemoryCacheDmaDisable( BMX_MODULE_ID index ) PLIB_BMX_ProgramFlashMemoryCacheDmaEnable Function Enables the bus matrix program Flash cacheability for DMA. File plib_bmx.h C void PLIB_BMX_ProgramFlashMemoryCacheDmaEnable(BMX_MODULE_ID index); Returns None. Description This function enables the program Flash cacheability for DMA. Remarks This function implements an operation of the ProgramFlashMemoryCacheDma feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashMemoryCacheDma in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 279 Example PLIB_BMX_ProgramFlashMemoryCacheDmaEnable(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be enabled Function void PLIB_BMX_ProgramFlashMemoryCacheDmaEnable( BMX_MODULE_ID index ) c) Arbiter Functions PLIB_BMX_ArbitrationModeGet Function Returns the bus matrix arbitration mode. File plib_bmx.h C PLIB_BMX_ARB_MODE PLIB_BMX_ArbitrationModeGet(BMX_MODULE_ID index); Returns PLIB_BMX_ARB_MODE enumerator value representing the arbitration mode. Description This function returns the bus matrix arbitration mode. Remarks This function implements an operation of the ArbitrationMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsArbitrationMode in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_ARB_MODE mode; mode = PLIB_BMX_ArbitrationModeGet(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function PLIB_BMX_ARB_MODE PLIB_BMX_ArbitrationModeGet ( BMX_MODULE_ID index ) PLIB_BMX_ArbitrationModeSet Function Sets the bus matrix arbitration mode. File plib_bmx.h C void PLIB_BMX_ArbitrationModeSet(BMX_MODULE_ID index, PLIB_BMX_ARB_MODE mode); Returns None. Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 280 Description This function sets the bus matrix arbitration mode. Remarks This function implements an operation of the ArbitrationMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsArbitrationMode in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_ArbitrationModeSet(BMX_ID_0, PLIB_BMX_ARB_MODE_DMA); Parameters Parameters Description index Identifier for the device instance to be configured mode Identifies the desired arbitration mode Function void PLIB_BMX_ArbitrationModeSet ( BMX_MODULE_ID index, PLIB_BMX_ARB_MODE mode ) d) Memory Access Control Functions PLIB_BMX_DataRAMKernelProgramOffsetGet Function Gets the offset (from start of RAM) of the kernel program partition. File plib_bmx.h C size_t PLIB_BMX_DataRAMKernelProgramOffsetGet(BMX_MODULE_ID index); Returns Offset of kernel program partition from base of RAM. Description This function returns the offset of start address of the kernel program RAM partition. This represents the size of the kernel data RAM partition. Remarks This function implements an operation of the DataRAMPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMPartition in your application to automatically determine whether this feature is available. Preconditions None. Example size_t kernProgOffset; kernProgOffset = PLIB_BMX_DataRAMKernelProgramOffsetGet(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function size_t PLIB_BMX_DataRAMKernelProgramOffsetGet( BMX_MODULE_ID index ) Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 281 PLIB_BMX_DataRAMPartitionSet Function Sets the size of the kernel and user partitions in data RAM memory. File plib_bmx.h C void PLIB_BMX_DataRAMPartitionSet(BMX_MODULE_ID index, size_t kernProgOffset, size_t userDataOffset, size_t userProgOffset); Returns None. Description This function sets the size of the kernel and user partitions in the data RAM memory (DRM). By default, the entire data RAM is mapped to Kernel mode and all of the offsets are zero. To partition the data RAM, all of the offsets must be set to a minimum of one DRM block size. If any of the offsets are set to zero, the entire data RAM is allocated to kernel data. The partitions must be a multiple of PLIB_BMX_DRM_BLOCK_SIZE. If programmed with a value that is not a multiple of PLIB_BMX_DRM_BLOCK_SIZE, the value will be automatically truncated to PLIB_BMX_DRM_BLOCK_SIZE. Remarks This function implements an operation of the DataRAMPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMPartition in your application to automatically determine whether this feature is available. Preconditions None. Example //Total Data RAM = 32 KB. size_t totalRamSize; size_t kernDataRamSize = (3 * PLIB_BMX_DRM_BLOCK_SIZE); size_t kernProgRamSize = (2 * PLIB_BMX_DRM_BLOCK_SIZE); size_t userDataRamSize = (6 * PLIB_BMX_DRM_BLOCK_SIZE); size_t userProgRamSize = (5 * PLIB_BMX_DRM_BLOCK_SIZE); //Get Size of Data RAM totalRamSize = PLIB_BMX_DataRAMSizeGet(BMX_ID_0); //Verify our partition sizes fit our RAM if ((kernDataRamSize + kernProgRamSize + userDataRamSize + userProgRamSize) != totalRamSize) { printf("RAM Partitioning Errorn"); } size_t kernProgOffset; size_t userDataOffset; size_t userProgOffset; kernProgOffset = kernDataRamSize; userDataOffset = kernDataRamSize + kernProgRamSize; userProgOffset = userDataOffset + userDataRamSize; PLIB_BMX_DataRAMPartitionSet(BMX_ID_0, kernProgOffset, userDataOffset, userProgOffset); Parameters Parameters Description index Identifier for the device instance to be configured kernProgOffset Size of the offset of the Kernel Program partition userDataOffset Size of the offset of the User Data partition userProgOffset Size of the offset of the User Program partition Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 282 Function void PLIB_BMX_DataRAMPartitionSet( BMX_MODULE_ID index, size_t kernProgOffset, size_t userDataOffset, size_t userProgOffset ) PLIB_BMX_DataRAMSizeGet Function Gets the size of data RAM memory. File plib_bmx.h C size_t PLIB_BMX_DataRAMSizeGet(BMX_MODULE_ID index); Returns Size of data RAM memory. Description This function returns the size of the data RAM memory. Remarks This function implements an operation of the DataRAMSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMSize in your application to automatically determine whether this feature is available. Preconditions None. Example size_t drmSize; drmSize = PLIB_BMX_DataRAMSizeGet(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function size_t PLIB_BMX_DataRAMSizeGet ( BMX_MODULE_ID index ) PLIB_BMX_DataRAMUserDataOffsetGet Function Gets the offset (from start of RAM) of the user data partition. File plib_bmx.h C size_t PLIB_BMX_DataRAMUserDataOffsetGet(BMX_MODULE_ID index); Returns Offset of user data partition from base of RAM. Description This function returns the offset of start address of the user data RAM partition. Subtracting the kernel program offset from the user data offset gives the size of the kernel program RAM partition. Remarks This function implements an operation of the DataRAMPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMPartition in your application to automatically determine Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 283 whether this feature is available. Preconditions None. Example size_t userDataOffset; userDataOffset = PLIB_BMX_DataRAMUserDataOffsetGet(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function size_t PLIB_BMX_DataRAMUserDataOffsetGet( BMX_MODULE_ID index ) PLIB_BMX_DataRAMUserProgramOffsetGet Function Gets the offset (from start of RAM) of the user program partition. File plib_bmx.h C size_t PLIB_BMX_DataRAMUserProgramOffsetGet(BMX_MODULE_ID index); Returns Offset of user data partition from base of RAM. Description This function returns the offset of start address of the user program RAM partition. Subtracting the user data offset from the user program offset gives the size of the user data RAM partition. Remarks This function implements an operation of the DataRAMPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMPartition in your application to automatically determine whether this feature is available. Preconditions None. Example size_t userProgOffset; userProgOffset = PLIB_BMX_DataRAMUserProgramOffsetGet(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function size_t PLIB_BMX_DataRAMUserProgramOffsetGet( BMX_MODULE_ID index ) PLIB_BMX_DataRamWaitStateGet Function Returns the number of data RAM Wait states. File plib_bmx.h C PLIB_BMX_DATA_RAM_WAIT_STATES PLIB_BMX_DataRamWaitStateGet(BMX_MODULE_ID index); Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 284 Returns PLIB_BMX_DATA_RAM_WAIT_STATES enumeration representing the number of wait states. Description This function returns the number of data RAM Wait states. Remarks This function implements an operation of the DataRamWaitState feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRamWaitState in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_DATA_RAM_WAIT_STATES wait; wait = PLIB_BMX_DataRamWaitStateGet(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function PLIB_BMX_DATA_RAM_WAIT_STATES PLIB_BMX_DataRamWaitStateGet( BMX_MODULE_ID index ) PLIB_BMX_DataRamWaitStateSet Function Sets the number of data RAM Wait states. File plib_bmx.h C void PLIB_BMX_DataRamWaitStateSet(BMX_MODULE_ID index, PLIB_BMX_DATA_RAM_WAIT_STATES wait); Returns None. Description This function sets the number of data RAM Wait states. Remarks This function implements an operation of the DataRamWaitState feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRamWaitState in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_BMX_DataRamWaitStateSet(BMX_ID_0, PLIB_BMX_DATA_RAM_WAIT_ONE); Parameters Parameters Description index Identifier for the device instance to be configured PLIB_BMX_DATA_RAM_WAIT_STATES Enumeration representing the number of Wait states Function void PLIB_BMX_DataRamWaitStateSet( BMX_MODULE_ID index, PLIB_BMX_DATA_RAM_WAIT_STATES wait ) Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 285 PLIB_BMX_ProgramFlashBootSizeGet Function Gets the size of boot program Flash memory. File plib_bmx.h C size_t PLIB_BMX_ProgramFlashBootSizeGet(BMX_MODULE_ID index); Returns Size of boot program Flash memory. Description This function returns the size of the boot program Flash memory. Remarks This function implements an operation of the ProgramFlashBootSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashBootSize in your application to automatically determine whether this feature is available. Preconditions None. Example size_t bootSize; bootSize = PLIB_BMX_ProgramFlashBootSizeGet(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function size_t PLIB_BMX_ProgramFlashBootSizeGet ( BMX_MODULE_ID index ) PLIB_BMX_ProgramFlashMemorySizeGet Function Gets the size of program Flash memory. File plib_bmx.h C size_t PLIB_BMX_ProgramFlashMemorySizeGet(BMX_MODULE_ID index); Returns Size of program Flash memory. Description This function returns the size of the program Flash memory. Remarks This function implements an operation of the ProgramFlashMemorySize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashMemorySize in your application to automatically determine whether this feature is available. Preconditions None. Example size_t pfmSize; Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 286 pfmSize = PLIB_BMX_ProgramFlashMemorySizeGet(BMX_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function size_t PLIB_BMX_ProgramFlashMemorySizeGet ( BMX_MODULE_ID index ) PLIB_BMX_ProgramFlashPartitionGet Function Gets the size of the kernel partition in program Flash memory. File plib_bmx.h C size_t PLIB_BMX_ProgramFlashPartitionGet(BMX_MODULE_ID index); Returns Size of the kernel partition in program Flash memory. Description This function gets the size of the kernel partition in the program Flash memory. The remaining Flash is set to user mode, and may be accessed by user programs. On reset, the entire Flash is mapped to Kernel mode, and this function will return zero. Remarks This function implements an operation of the ProgramFlashPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashPartition in your application to automatically determine whether this feature is available. Preconditions None. Example size_t pfmSize; size_t userPfmSize; size_t kernPfmSize; // Get size of PFM pfmSize = PLIB_BMX_ProgramFlashMemorySizeGet(BMX_ID_0); kernPfmSize = PLIB_BMX_ProgramFlashPartitionGet(BMX_ID_0); userPfmSize = pfmSize - kernPfmSize; Parameters Parameters Description index Identifier for the device instance to be read Function size_t PLIB_BMX_ProgramFlashPartitionGet( BMX_MODULE_ID index ) PLIB_BMX_ProgramFlashPartitionSet Function Sets the size of the kernel and user partitions in program Flash memory. File plib_bmx.h C void PLIB_BMX_ProgramFlashPartitionSet(BMX_MODULE_ID index, size_t user_size); Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 287 Returns None. Description This function sets the size of the kernel and user partitions in program Flash memory (PFM). Kernel programs may access both partitions, but user programs may not access the kernel partition (including peripheral registers). By default, the entire Flash is mapped to Kernel mode. If called with a non-zero value, a user partition of size user_size is created, and the remaining PFM remains in Kernel mode. The user partition must be a multiple of PLIB_BMX_PFM_BLOCK_SIZE. If programmed with a value that is not a multiple of PLIB_BMX_PFM_BLOCK_SIZE, the value will be truncated to a PLIB_BMX_PFM_BLOCK_SIZE boundary. Remarks This function implements an operation of the ProgramFlashPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashPartition in your application to automatically determine whether this feature is available. Preconditions None. Example size_t pfm_size; size_t userSize = (6 * PLIB_BMX_PFM_BLOCK_SIZE); size_t userOffset; // Get size of PFM size_t pfmSize; pfmSize = PLIB_BMX_ProgramFlashMemorySizeGet(BMX_ID_0); userOffset = pfmSize - userSize; if (userOffset > 0) { PLIB_BMX_ProgramFlashPartitionSet(BMX_ID_0, userOffset); } Parameters Parameters Description index Identifier for the device instance to be configured userSize Size of the user partition in PFM Function void PLIB_BMX_ProgramFlashPartitionSet( BMX_MODULE_ID index, size_t userSize ) e) Feature Existence Functions PLIB_BMX_ExistsArbitrationMode Function Identifies that the ArbitrationMode feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsArbitrationMode(BMX_MODULE_ID index); Returns • true = The ArbitrationMode feature is supported on the device • false = The ArbitrationMode feature is not supported on the device Description This interface identifies that the ArbitrationMode feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_ArbitrationModeSet Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 288 • PLIB_BMX_ArbitrationModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsArbitrationMode( BMX_MODULE_ID index ) PLIB_BMX_ExistsBusExceptionData Function Identifies that the BusExceptionData feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsBusExceptionData(BMX_MODULE_ID index); Returns • true = The BusExceptionData feature is supported on the device • false = The BusExceptionData feature is not supported on the device Description This interface identifies that the BusExceptionData feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionDataEnable • PLIB_BMX_BusExceptionDataDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsBusExceptionData( BMX_MODULE_ID index ) PLIB_BMX_ExistsBusExceptionDMA Function Identifies that the BusExceptionDMA feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsBusExceptionDMA(BMX_MODULE_ID index); Returns • true = The BusExceptionDMA feature is supported on the device • false = The BusExceptionDMA feature is not supported on the device Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 289 Description This interface identifies that the BusExceptionDMA feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionDMAEnable • PLIB_BMX_BusExceptionDMADisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsBusExceptionDMA( BMX_MODULE_ID index ) PLIB_BMX_ExistsBusExceptionICD Function Identifies that the BusExceptionICD feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsBusExceptionICD(BMX_MODULE_ID index); Returns • true = The BusExceptionICD feature is supported on the device • false = The BusExceptionICD feature is not supported on the device Description This interface identifies that the BusExceptionICD feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionICDEnable • PLIB_BMX_BusExceptionICDDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsBusExceptionICD( BMX_MODULE_ID index ) PLIB_BMX_ExistsBusExceptionInstruction Function Identifies that the BusExceptionInstruction feature exists on the BMX module. File plib_bmx.h Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 290 C bool PLIB_BMX_ExistsBusExceptionInstruction(BMX_MODULE_ID index); Returns • true = The BusExceptionInstruction feature is supported on the device • false = The BusExceptionInstruction feature is not supported on the device Description This interface identifies that the BusExceptionInstruction feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionInstructionEnable • PLIB_BMX_BusExceptionInstructionDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsBusExceptionInstruction( BMX_MODULE_ID index ) PLIB_BMX_ExistsBusExceptionIXI Function Identifies that the BusExceptionIXI feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsBusExceptionIXI(BMX_MODULE_ID index); Returns true = The BusExceptionIXI feature is supported on the device • false = The BusExceptionIXI feature is not supported on the device Description This interface identifies that the BusExceptionIXI feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionIXIEnable • PLIB_BMX_BusExceptionIXIDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsBusExceptionIXI( BMX_MODULE_ID index ) Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 291 PLIB_BMX_ExistsDataRAMPartition Function Identifies that the DataRAMPartition feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsDataRAMPartition(BMX_MODULE_ID index); Returns • true = The DataRAMPartition feature is supported on the device • false = The DataRAMPartition feature is not supported on the device Description This interface identifies that the DataRAMPartition feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_DataRAMPartitionSet • PLIB_BMX_DataRAMKernelProgramOffsetGet • PLIB_BMX_DataRAMUserDataOffsetGet • PLIB_BMX_DataRAMUserProgramOffsetGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsDataRAMPartition( BMX_MODULE_ID index ) PLIB_BMX_ExistsDataRAMSize Function Identifies that the DataRAMSize feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsDataRAMSize(BMX_MODULE_ID index); Returns • true = The DataRAMSize feature is supported on the device • false = The DataRAMSize feature is not supported on the device Description This interface identifies that the DataRAMSize feature is available on the BMX module. When this interface returns true, this function is supported on the device: • PLIB_BMX_DataRAMSizeGet Remarks None. Preconditions None. Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 292 Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsDataRAMSize( BMX_MODULE_ID index ) PLIB_BMX_ExistsDataRamWaitState Function Identifies that the DataRamWaitState feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsDataRamWaitState(BMX_MODULE_ID index); Returns • true = The DataRamWaitState feature is supported on the device • false = The DataRamWaitState feature is not supported on the device Description This interface identifies that the DataRamWaitState feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_DataRamWaitStateSet • PLIB_BMX_DataRamWaitStateGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsDataRamWaitState( BMX_MODULE_ID index ) PLIB_BMX_ExistsProgramFlashBootSize Function Identifies that the ProgramFlashBootSize feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsProgramFlashBootSize(BMX_MODULE_ID index); Returns • true = The ProgramFlashBootSize feature is supported on the device • false = The ProgramFlashBootSize feature is not supported on the device Description This interface identifies that the ProgramFlashBootSize feature is available on the BMX module. When this interface returns true, this function is supported on the device: • PLIB_BMX_ProgramFlashBootSizeGet Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 293 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsProgramFlashBootSize( BMX_MODULE_ID index ) PLIB_BMX_ExistsProgramFlashMemoryCacheDma Function Identifies that the ProgramFlashMemoryCacheDma feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsProgramFlashMemoryCacheDma(BMX_MODULE_ID index); Returns • true = The ProgramFlashMemoryCacheDma feature is supported on the device • false = The ProgramFlashMemoryCacheDma feature is not supported on the device Description This interface identifies that the ProgramFlashMemoryCacheDma feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_ProgramFlashMemoryCacheDmaEnable • PLIB_BMX_ProgramFlashMemoryCacheDmaDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsProgramFlashMemoryCacheDma( BMX_MODULE_ID index ) PLIB_BMX_ExistsProgramFlashMemorySize Function Identifies that the ProgramFlashMemorySize feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsProgramFlashMemorySize(BMX_MODULE_ID index); Returns • true = The ProgramFlashMemorySize feature is supported on the device • false = The ProgramFlashMemorySize feature is not supported on the device Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 294 Description This interface identifies that the ProgramFlashMemorySize feature is available on the BMX module. When this interface returns true, this function is supported on the device: • PLIB_BMX_ProgramFlashMemorySizeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsProgramFlashMemorySize( BMX_MODULE_ID index ) PLIB_BMX_ExistsProgramFlashPartition Function Identifies that the ProgramFlashPartition feature exists on the BMX module. File plib_bmx.h C bool PLIB_BMX_ExistsProgramFlashPartition(BMX_MODULE_ID index); Returns • true = The ProgramFlashPartition feature is supported on the device • false = The ProgramFlashPartition feature is not supported on the device Description This interface identifies that the ProgramFlashPartition feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_ProgramFlashPartitionGet • PLIB_BMX_ProgramFlashPartitionSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_BMX_ExistsProgramFlashPartition( BMX_MODULE_ID index ) f) Data Types and Constants BMX_MODULE_ID Enumeration Lists the possible Module IDs for the bus matrix. File help_plib_bmx.h Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 295 C typedef enum { BMX_ID_0, BMX_NUMBER_OF_MODULES } BMX_MODULE_ID; Description Module ID This enumeration lists the possible Module IDs for the bus matrix. Remarks Refer to the specific device data sheet to obtain the correct number of modules defined for the desired device. PLIB_BMX_ARB_MODE Enumeration Lists the possible arbitration modes for the bus matrix. File plib_bmx.h C typedef enum { PLIB_BMX_ARB_MODE_INST, PLIB_BMX_ARB_MODE_DMA, PLIB_BMX_ARB_MODE_ROT } PLIB_BMX_ARB_MODE; Members Members Description PLIB_BMX_ARB_MODE_INST Arbitration Mode 0 PLIB_BMX_ARB_MODE_DMA Arbitration Mode 1 PLIB_BMX_ARB_MODE_ROT Arbitration Mode 2 Description Arbitration Mode This enumeration lists the possible arbitration modes for the bus matrix. PLIB_BMX_DATA_RAM_WAIT_STATES Enumeration Defines the number of data RAM wait states for address setup. File plib_bmx.h C typedef enum { PLIB_BMX_DATA_RAM_WAIT_ZERO, PLIB_BMX_DATA_RAM_WAIT_ONE } PLIB_BMX_DATA_RAM_WAIT_STATES; Members Members Description PLIB_BMX_DATA_RAM_WAIT_ZERO Zero wait states for address setup PLIB_BMX_DATA_RAM_WAIT_ONE One wait state for address setup Description Wait States This definition specifies the number of data RAM wait states for address setup. Peripheral Libraries Help BMX Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 296 PLIB_BMX_EXCEPTION_SRC Enumeration Defines which events trigger a bus exception. File plib_bmx.h C typedef enum { PLIB_BMX_ERR_IXI, PLIB_BMX_ERR_ICD, PLIB_BMX_ERR_DMA, PLIB_BMX_ERR_DATA, PLIB_BMX_ERR_INST } PLIB_BMX_EXCEPTION_SRC; Members Members Description PLIB_BMX_ERR_IXI IXI Shared Bus PLIB_BMX_ERR_ICD In-Circuit Debugger PLIB_BMX_ERR_DMA DMA Controller PLIB_BMX_ERR_DATA CPU Data Bus PLIB_BMX_ERR_INST CPU Instruction Bus Description Exception Bits This definition specifies which events trigger a bus exception. PLIB_BMX_DRM_BLOCK_SIZE Macro Defines the minimum partition block size in data RAM memory. File plib_bmx.h C #define PLIB_BMX_DRM_BLOCK_SIZE 2048 Description Program Flash Partition Block Size This definition specifies the minimum partition block size in data RAM memory. PLIB_BMX_PFM_BLOCK_SIZE Macro Defines the minimum partition block size in program Flash memory. File plib_bmx.h C #define PLIB_BMX_PFM_BLOCK_SIZE 2048 Description Program Flash Partition Block Size This definition specifies the minimum partition block size in program Flash memory. Peripheral Libraries Help BMX Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 297 Files Files Name Description plib_bmx.h Defines the Bus Matrix (BMX) Peripheral Library interface help_plib_bmx.h This file is used for documentation purposes Description This section lists the source and header files used by the library. plib_bmx.h Defines the Bus Matrix (BMX) Peripheral Library interface Enumerations Name Description PLIB_BMX_ARB_MODE Lists the possible arbitration modes for the bus matrix. PLIB_BMX_DATA_RAM_WAIT_STATES Defines the number of data RAM wait states for address setup. PLIB_BMX_EXCEPTION_SRC Defines which events trigger a bus exception. Functions Name Description PLIB_BMX_ArbitrationModeGet Returns the bus matrix arbitration mode. PLIB_BMX_ArbitrationModeSet Sets the bus matrix arbitration mode. PLIB_BMX_BusExceptionDataDisable Disables the data bus exception. PLIB_BMX_BusExceptionDataEnable Enables the Data bus exception. PLIB_BMX_BusExceptionDMADisable Disables the DMA bus exception. PLIB_BMX_BusExceptionDMAEnable Enables the DMA bus exception. PLIB_BMX_BusExceptionICDDisable Disables the ICD bus exception. PLIB_BMX_BusExceptionICDEnable Enables the ICD bus exception. PLIB_BMX_BusExceptionInstructionDisable Disables the instruction bus exception. PLIB_BMX_BusExceptionInstructionEnable Enables the instruction bus exception. PLIB_BMX_BusExceptionIXIDisable Disables the IXI bus exception. PLIB_BMX_BusExceptionIXIEnable Enables the IXI bus exception. PLIB_BMX_DataRAMKernelProgramOffsetGet Gets the offset (from start of RAM) of the kernel program partition. PLIB_BMX_DataRAMPartitionSet Sets the size of the kernel and user partitions in data RAM memory. PLIB_BMX_DataRAMSizeGet Gets the size of data RAM memory. PLIB_BMX_DataRAMUserDataOffsetGet Gets the offset (from start of RAM) of the user data partition. PLIB_BMX_DataRAMUserProgramOffsetGet Gets the offset (from start of RAM) of the user program partition. PLIB_BMX_DataRamWaitStateGet Returns the number of data RAM Wait states. PLIB_BMX_DataRamWaitStateSet Sets the number of data RAM Wait states. PLIB_BMX_ExistsArbitrationMode Identifies that the ArbitrationMode feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionData Identifies that the BusExceptionData feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionDMA Identifies that the BusExceptionDMA feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionICD Identifies that the BusExceptionICD feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionInstruction Identifies that the BusExceptionInstruction feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionIXI Identifies that the BusExceptionIXI feature exists on the BMX module. PLIB_BMX_ExistsDataRAMPartition Identifies that the DataRAMPartition feature exists on the BMX module. PLIB_BMX_ExistsDataRAMSize Identifies that the DataRAMSize feature exists on the BMX module. PLIB_BMX_ExistsDataRamWaitState Identifies that the DataRamWaitState feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashBootSize Identifies that the ProgramFlashBootSize feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashMemoryCacheDma Identifies that the ProgramFlashMemoryCacheDma feature exists on the BMX module. Peripheral Libraries Help BMX Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 298 PLIB_BMX_ExistsProgramFlashMemorySize Identifies that the ProgramFlashMemorySize feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashPartition Identifies that the ProgramFlashPartition feature exists on the BMX module. PLIB_BMX_ProgramFlashBootSizeGet Gets the size of boot program Flash memory. PLIB_BMX_ProgramFlashMemoryCacheDmaDisable Disables the bus matrix program Flash cacheability for DMA. PLIB_BMX_ProgramFlashMemoryCacheDmaEnable Enables the bus matrix program Flash cacheability for DMA. PLIB_BMX_ProgramFlashMemorySizeGet Gets the size of program Flash memory. PLIB_BMX_ProgramFlashPartitionGet Gets the size of the kernel partition in program Flash memory. PLIB_BMX_ProgramFlashPartitionSet Sets the size of the kernel and user partitions in program Flash memory. Macros Name Description PLIB_BMX_DRM_BLOCK_SIZE Defines the minimum partition block size in data RAM memory. PLIB_BMX_PFM_BLOCK_SIZE Defines the minimum partition block size in program Flash memory. Description Bus Matrix Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Bus Matrix (BMX) Peripheral Library (PLIB) for Microchip microcontrollers. The definitions in this file are for the bus matrix controller module. File Name plib_bmx.h Company Microchip Technology Inc. help_plib_bmx.h Enumerations Name Description BMX_MODULE_ID Lists the possible Module IDs for the bus matrix. Description This file is used for documentation purposes Peripheral Libraries Help BMX Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 299 CAN Peripheral Library This section describes the CAN Peripheral Library. Introduction This library provides a low-level abstraction of the CAN module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description The Controller Area Network (CAN) is used primarily in industrial and automotive applications. It is an asynchronous serial data communication protocol that provides reliable communication in an electrically noisy environment. Note: Trademarks and Intellectual Property are property of their respective owners. Customers are responsible for obtaining appropriate licensing or rights before using this software. Refer to the MPLAB Harmony Software License Agreement for complete licensing information. A copy of this agreement is available in the /doc folder of your MPLAB Harmony installation. Using the Library This topic describes the basic architecture of the CAN Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_can.h The interface to the CAN Peripheral library is defined in the plib_can.h header file, which is included in the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the CAN Peripheral library must include peripheral.h. Library File: The CAN Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the Peripheral interacts with the framework. Hardware Abstraction Model Note: The interface provided is a super set of all of the functionality of the available CAN on the device. Refer to the specific device data sheet or the related family reference manual to determine the set of functions that are supported for each CAN module on the device. This library provides the low-level abstraction of the CAN module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. CAN Software Abstraction Block Diagram Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 300 Software Model: The CAN Peripheral Library provides interface routines to interact with the blocks shown in the previous diagram. A channel can be either a transmit channel or a receive channel. The size of a CAN message is typically 16 bytes (8 bytes for data-only receive messages). The size of a channel (the number of messages it can buffer) is configurable. Each channel has a minimum size of one message buffer. The message buffer area for all channels is assigned at configuration time. The CAN Peripheral Library then provides access to these channels and buffers via the library interface. The user code must enable and configure message acceptance filters to receive messages. These filters compare the ID field of the incoming message with configured value and accepts the messages if IDs match. The message is then stored in a selectable receive channel. At least one message acceptance filter and one filter mask should be enabled for the CAN module to receive messages. A filter mask allows specified filter bits to be ignored during the comparison process. This allows the filter to_accept_a message with an ID range. The CAN Peripheral Library allows the CAN module to generate events. Events can be generated at the channel level and at the module level. Events: The CAN module is capable of notifying the user application when specific events occur in the module. The following diagram shows these events and how they are organized. There are two types of events in the CAN module: Channel events and Module events. Channel events are generated by transmit and receive channels. Module events are generated by various sources (including channels) within the CAN module. Each event can be enabled or disabled. Enabling a channel event will cause the CAN module to generate a module event. An enabled module level event will cause the CAN module to generate an interrupt to the CPU. Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 301 The application can also poll channel events to check if these are active. This may be done in cases where a polling scheme (rather than an interrupt scheme) needs to be implemented. In this case, the CAN module provides events status on a channel basis. If a channel event is found active, the application can then use library API calls to inspect which channel condition caused the channel event. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the CAN module. Library Interface Section Description Basic Configuration Functions APIs that are used for basic control of the module, such as enabling and disabling the module. Advanced Configuration Functions These functions enable advanced configuration, such as selection of the operation mode. Bus Speed Configuration Functions These functions enable bus speed configuration. Event Management Functions These functions can be used to manage the events. Message Transmit Functions These functions can be used for message transmission. Message Receive Functions These functions are related to data reception. Error State Tracking Functions These functions are used for error tracking. Information Functions These functions provide information about the module. Feature Existence Functions These functions determine whether or not a particular feature is supported by the device. How the Library Works Note: Not all modes are available on all the devices. Please refer to the specific device data sheet to determine the set of modes that are supported for your device. About CAN Protocol This section briefly discusses the CAN Protocol briefly. For complete details on the CAN protocol, refer to the CAN 2.0 specification available from Bosch. Description The CAN bus protocol uses asynchronous communication. Information is passed from transmitters to receivers in data frames, which are composed of byte fields that define the contents of the data frame. This is shown in the following figure. Each frame begins with a Start-of-Frame (SOF) bit and terminates with an End-of-Frame (EOF) bit field. The SOF is followed by arbitration and control fields, which identify the message type, format, length and priority. This information allows each node on the CAN bus to respond appropriately to the message. The data field conveys the message content and is of variable length, ranging from 0 to 8 bytes. Error protection is provided by the Cyclic Redundancy Check (CRC) and acknowledgement (ACK) fields. Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 302 Standard ID Message Format The Standard ID message begins with a Start-of-Frame bit followed by a 12-bit arbitration field. The arbitration field contains an 11-bit identifier and the Remote Transmit Request (RTR) bit. The identifier defines the type of information contained in the message and is used by each receiving node to determine if the message is of interest. The RTR bit distinguishes a data frame from a remote frame. For a standard data frame, the RTR bit is clear. Following the arbitration field is a 6-bit control field, which provides more information about the contents of the message. The first bit in the control field is an Identifier Extension (IDE) bit, which distinguishes the message as either a standard or extended data frame. A standard data frame is indicated by a dominant state (logic level ‘0’) during transmission of the IDE bit. The second bit in the control field is a reserved (RB0) bit, which is in the dominant state (logic level ‘0’). The last 4 bits in the control field represent the Data Length Code (DLC), which specifies the number of data bytes present in the message. The data field follows the control field. This field carries the message data – the actual payload of the data frame. This field is of variable length, ranging from 0 to 8 bytes. The number of bytes is user-selectable. The data field is followed by the Cyclic Redundancy Check (CRC) field, which is a 15-bit CRC sequence with one delimiter bit. The acknowledgement (ACK) field is sent as a recessive bit (logic level ‘1’) and is overwritten as a dominant bit by any receiver that has received the data correctly. The message is acknowledged by the receiver regardless of the result of the acceptance filter comparison. The last field is the End-of-Frame field, which consists of 7 recessive bits that indicate the end of message. Extended ID Message Format The Extended ID Message frame begins with an SOF bit followed by a 31-bit arbitration field. The arbitration field for the extended data frame contains 29 identifier bits in two fields separated by a Substitute Remote Request (SRR) bit and an IDE bit. The SRR bit determines if the message is a remote frame. SRR = 1 for extended data frames. The IDE bit indicates the data frame type. For the extended data frame, IDE = 1. The extended data frame Control field consists of 7 bits. The first bit is the RTR. For the extended data frame, RTR = 0. The next two bits, RB1 and RB0, are reserved bits that are in the dominant state (logic level ‘0’). The last 4 bits in the Control field are the Data Length Code, which specifies the number of data bytes present in the message. The remaining fields in an extended data frame are identical to a standard data frame. Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 303 CAN Bit Time Quanta The nominal bit rate is the number of bits per second transmitted on the CAN bus. Nominal bit time = 1 ÷ Nominal Bit Rate. There are four time segments in a bit time to compensate for any phase shifts due to oscillator drifts or propagation delays. These time segments do not overlap each other and are represented in terms of Time Quantum (TQ). One TQ is a fixed unit of time derived from the oscillator clock. The total number of time quanta in a nominal bit time must be programmed between 8 and 25 TQ. Each bit transmission time consists of four time segments: Synchronization Segment – This time segment synchronizes the different nodes connected on the CAN bus. A bit edge is expected to be within this segment. Based on CAN protocol, the Synchronization Segment is assumed to be one Time Quantum. Propagation Segment – This time segment compensates for any time delay that may occur due to the bus line or due to the various transceivers connected on that bus. Phase Segment 1 – This time segment compensates for errors that may occur due to phase shift in the edges. The time segment may be lengthened during resynchronization to compensate for the phase shift. Phase Segment 2 – This time segment compensates for errors that may occur due to phase shift in the edges. The time segment may be shortened during resynchronization to compensate for the phase shift. The Phase Segment 2 time can be configured to be either programmable or specified by the Phase Segment 1 time. Two types of synchronization are used – Hard Synchronization and Resynchronization. A Hard Synchronization occurs once at the start of a frame. Resynchronization occurs inside a frame. Hard synchronization takes place on the recessive-to-dominant transition of the start bit. The bit time is restarted from that edge. Resynchronization takes place when a bit edge does not occur within the Synchronization Segment in a message. One of the Phase Segments is shortened or lengthened by an amount that depends on the phase error in the signal. The maximum amount that can be used is determined by the Synchronization Jump Width parameter. The length of Phase Segment 1 and Phase Segment 2 can be changed depending on oscillator tolerances of the transmitting and receiving node. Resynchronization compensates for any phase shifts that may occur due to the different oscillators used by the transmitting and receiving nodes. Bit Lengthening – If the transmitting node in CAN has a slower oscillator than the receiving node, the next falling edge, and therefore, the sample point, can be delayed by lengthening Phase Segment 1 in the bit time. Bit Shortening – If the transmitting node in CAN has a faster oscillator than the receiving node, the next falling edge, and therefore, the sample point of the next bit, can be reduced by shortening the Phase Segment 2 in the bit time. Synchronization Jump Width (SJW) – This determines the synchronization jump width by limiting the amount of lengthening or shortening that can be applied to the Phase Segment 1 and Phase Segment 2 time intervals. This segment should not be longer than Phase Segment 2 time. The width can be 1-4 TQ Initialization of CAN This section provides information on initializing CAN, including channel, filters, masks, and mode configuration, setting the bus speed, assigning buffer memory, and enabling events. Mode Configuration The CAN module must be enabled before configuration. Enabling the CAN module gives it control over the CAN pins of the device. The following code example shows how the PLIB_CAN_Enable function is used to enable the module. /* This code expects the data direction settings to be done from other modules */ /* Switch the CAN module ON */ PLIB_CAN_Enable(CAN_ID_1); The CAN module must be placed in Configuration mode before attempting to configure it. The following features are available in Configuration mode only: • Configuring the CAN module clock and CAN bus speed • Configuring the message acceptance filter mask Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 304 • Assigning the channel buffer memory • Configuring channel size and Receive Channel Data-only mode. The CAN module operating mode can be changed by using the PLIB_CAN_OperationModeSelect function. The caller should wait until the operating mode is set before proceeding. The PLIB_CAN_OperationModeGet function can be used to obtain the current operating mode of the CAN module. /* Switch the CAN module to Configuration mode. Wait until the switch is complete */ PLIB_CAN_Enable(CAN_ID_1); PLIB_CAN_OperationModeSelect(CAN_ID_1, CAN_CONFIGURATION_MODE); while(PLIB_CAN_OperationModeGet(CAN_ID_1) != CAN_CONFIGURATION_MODE); The CAN module must be placed in Normal mode to be able to send and receive messages. The caller should wait until the Normal operating mode is set before proceeding. The PLIB_CAN_OperationModeSelect function can be used to obtain the current operating mode of the CAN module. /* Switch the CAN module to Normal mode. Wait until the switch is complete */ PLIB_CAN_OperationModeSelect(CAN_ID_1, CAN_NORMAL_MODE); while(PLIB_CAN_OperationModeGet(CAN_ID_1) != CAN_NORMAL_MODE); Setting Bus Speed The bus speed at which the CAN node operates is determined by the CAN module clock and the number of Bit Time Quanta (TQ) assigned to the CAN bit. The following code shows an example of setting the CAN module clock and CAN bus speed. In this example, the number of TQ is 11. /*The CPU core frequency is 80000000 Hz and the desired CAN bus speed is 500 kbps. Use ECAN Bit Rate Calculator plug-in to get parameter values for 500 kbps Baud rate*/ #define MY_CAN_ID CAN_ID_1 #define PRESCALE 6 #define SYNCJUMPWIDTH 1 #define PROPAGATION 2 #define SEGMENT1 4 #define SEGMENT2 4 #define CAN_CLOCK 80000000ul uint32_t baudRate; bool result; if (CAN_CONFIGURATION_MODE == PLIB_CAN_OperationModeGet(MY_CAN_ID)) { result = PLIB_CAN_PrecalculatedBitRateSetup( MY_CAN_ID, PRESCALE, SYNCJUMPWIDTH, PROPAGATION, SEGMENT1, SEGMENT2 ); if(false == result) { // Error occurred, handle accordingly } else { baudRate = PLIB_CAN_BaudRateGet(MY_CAN_ID, CAN_CLOCK); } } Assigning Buffer Memory The CAN module requires RAM memory to store received messages and queue message that need to be transmitted. The total amount of memory required depends on the size of each channel. While each channel has a minimum size of one message buffer (16 bytes), to simplify usage issues, channels should be used in a sequentially ascending order starting with channel 0. To better understand the buffer memory requirements of the CAN module, consider the following examples: Example 1: Two transmit channels (each with eight message buffers) and one full receive channel (with 10 message buffers): • Two transmit channels with eight message buffers: 2 * 8 * 16 = 256 bytes • One receive channel with 10 message buffers: 1 * 10 * 16 = 160 bytes • Total memory required in bytes = 416 bytes Example 2: Four transmit channels (two with eight message buffers and other two with 10 message buffers) and two full receive channels (one with 10 message buffers and one with 20 message buffers): Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 305 • Two transmit channels with eight message buffers: 2 * 8 * 16 = 256 bytes • Two transmit channels with 10 message buffers: 2 * 10 * 16 = 320 bytes • One receive channel with 10 message buffers: 1 * 10 * 16 = 160 bytes • One receive channel with 20 message buffers: 1 * 20 * 16 = 320 bytes • Total memory required in bytes = 1056 bytes Example 3: One transmit channel (with maximum message buffers) and two receive Channels (one full receive with 10 message buffers and one data-only channel with maximum message buffers): • One transmit channel with maximum (32) message buffers: 1 * 32 * 16 = 512 bytes • One receive channel with 10 message buffers: 1 * 10 * 16 = 160 bytes • One data-only receive channel with 32 message buffers: 1 * 32 * 8 = 256 bytes • Total memory required in bytes = 928 bytes The PLIB_CAN_MemoryBufferAssign function is used to assign a memory buffer to the CAN module, which is shown in the following example. /* Assign the buffer area to the CAN module. * In this case assign enough memory for 2 * channels, each with 8 message buffers.*/ uint8_t MY_CAN_MessageFifoArea[2 * 8 * 16]; PLIB_CAN_MemoryBufferAssign(CAN_ID_1, MY_CAN_MessageFifoArea); Channel Configuration To transmit and receive CAN messages, the user application must configure channels. The PLIB_CAN_ChannelForTransmitSet function is used to configure a channel for transmit operation. The PLIB_CAN_ChannelForReceiveSet function is used to configure a channel for receive operation. Note: To receive CAN messages, at least one message acceptance filter with a receive channel must be configured. A CAN Transmit channel can be enabled to process a Remote Transmit Request (RTR). In this case, the transmit channel will automatically transmit all queued messages when an RTR message is accepted by the CAN module. The following code shows an example of configuring a CAN Transmit channel. /* Configure CAN1 Channel 0 for Transmit operation. Allocate 8 message buffer, * disable the RTR feature and assign low medium priority for transmissions. */ PLIB_CAN_ChannelForTransmitSet(CAN_ID_1, CAN_CHANNEL0, 8, CAN_TX_RTR_DISABLED, CAN_LOW_MEDIUM_PRIORITY); A CAN receive channel can be enabled to store the data payload portion of an accepted message. This mode is called the Data-only mode. The CAN module otherwise stores both the ID and data payload portion of the accepted message. The following code shows an example of configuring a CAN Receive channel. /* Configure CAN1 Channel 1 for Receive operation. Allocate 8 message buffers, * disable the Data-only feature (specify full receive mode). */ PLIB_CAN_ChannelForReceiveSet(CAN_ID_1, CAN_CHANNEL1, 8, CAN_RX_FULL_RECEIVE); Filters and Masks Configuration The CAN message acceptance filter allows an application to_accept_only selected messages from the CAN bus. The CAN module achieves this by comparing the Standard or Extended ID of a message with the configured filter ID. The message is accepted on an ID match. The accepted message is stored in the configured destination channel. The CAN message acceptance filter mask directs the CAN module to ignore specified bits in the filter comparison. This allows the application to_accept_messages within an ID range. At least one filter and one mask must be configured for the CAN module to be able to receive messages. The destination channel for a filter must be a receive channel unless the channel is a transmit channel with the RTR feature enabled. The PLIB_CAN_FilterConfigure function is used to configure a message acceptance filter. The PLIB_CAN_FilterMaskConfigure function is used to configure a message acceptance filter mask. The filter and mask must be linked together to a channel. This is done using the PLIB_CAN_FilterToChannelLink function. The CAN filter should be enabled to allow messages to be processed. This is done using the PLIB_CAN_FilterEnable function. To better understand how the filter and masks can be used to implement filtering, consider the following code examples: Example 1: Configure a CAN filter to_accept_a Standard ID message with ID 0x201 /* Only one message ID is to be accepted. All bits are to be compared * therefore, the mask value should be 0x7FF. The message type is Standard ID. * Configure CAN1, Filter 0, Mask 0 and set the destination channel as * Channel 1. */ PLIB_CAN_FilterConfigure(CAN_ID_1, CAN_FILTER0, 0x201, CAN_SID); Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 306 PLIB_CAN_FilterMaskConfigure(CAN_ID_1, CAN_FILTER_MASK0, 0x7FF, CAN_SID, CAN_FILTER_MASK_IDE_TYPE); PLIB_CAN_FilterToChannelLink(CAN_ID_1, CAN_FILTER0, CAN_FILTER_MASK0, CAN_CHANNEL1); PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER0); Example 2: Configure a CAN filter to_accept_an Extended ID message with ID 0x8004001 /* Only one message ID is to be accepted. All bits are to be compared * therefore, the mask value should be 0x8004001. The message type is Extended ID. * Configure CAN1, Filter 0, Mask 0 and set the destination channel as * Channel 1. */ PLIB_CAN_FilterConfigure(CAN_ID_1, CAN_FILTER0, 0x8004001, CAN_EID); PLIB_CAN_FilterMaskConfigure(CAN_ID_1, CAN_FILTER_MASK0, 0x3FFFFFFF, CAN_EID, CAN_FILTER_MASK_IDE_TYPE); PLIB_CAN_FilterToChannelLink(CAN_ID_1, CAN_FILTER0, CAN_FILTER_MASK0, CAN_CHANNEL1); PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER0); Example 3: Configure a CAN filter to_accept_an Extended ID message within ID range 0x8004000 - 0x8004003 /* A message ID range is to be implemented. The 2 least significant bits can be * ignored. Therefore, the mask value should be 0x3FFFFFFC. The message type is * Extended ID. Configure CAN1, Filter 0, Mask 0 and set the destination channel * as Channel 1. */ PLIB_CAN_FilterConfigure(CAN_ID_1, CAN_FILTER0, 0x8004000, CAN_EID); PLIB_CAN_FilterMaskConfigure(CAN_ID_1, CAN_FILTER_MASK0, 0x3FFFFFFC, CAN_EID, CAN_FILTER_MASK_IDE_TYPE); PLIB_CAN_FilterToChannelLink(CAN_ID_1, CAN_FILTER0, CAN_FILTER_MASK0, CAN_CHANNEL1); PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER0); Note: Refer to About CAN Protocol for more information on Standard and Extended ID addressing. Enabling Events The CAN module can generate events that indicate the status of the module. Events can be generated at the channel level and at the module level. Enabling a channel event will cause the CAN module to generate a module level event when the channel event occurs. Enabling a module event will cause the CAN module to interrupt the CPU. The following code shows an example of using the PLIB_CAN_ChannelEventEnable and PLIB_CAN_ModuleEventEnable functions to enable channel and module events. /* Enable the Receive channel not empty and Receive channel * full events at the channel level. Enable the Receive event * at the module level. */ PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL1, (CAN_RX_CHANNEL_NOT_EMPTY|CAN_RX_CHANNEL_FULL)); PLIB_CAN_ModuleEventEnable (CAN_ID_1, CAN_RX_EVENT); Note: The caller must use the Interrupt Peripheral Library to enable the CAN CPU interrupt. Transmitting a CAN Message The caller application can transmit a CAN message by queuing the message in a transmit channel, updating the channel, and then flushing it. Flushing a transmit channel will cause the CAN module to transmit all of the CAN messages that are queued in the channel. The PLIB_CAN_TransmitBufferGet function should be used to obtain a CAN_TX_MSG_BUFFER handle type to an empty message buffer. The application should then populate this buffer. The PLIB_CAN_ChannelUpdate function must be called when the buffer has been populated. Finally, the PLIB_CAN_TransmitChannelFlush function is called to flush the channel. The following code shows an example of transmitting an Extended ID message using Channel 0 on the CAN1 module. CAN_TX_MSG_BUFFER * My_Message; /* Get a pointer to the next buffer in the Transmit channel * check if the returned value is null. */ My_Message = PLIB_CAN_TransmitBufferGet(CAN_ID_1, CAN_CHANNEL0); if(My_Message != NULL) { Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 307 /* Form a Extended ID CAN message. Start by clearing the buffer. Set the IDE bit to 1 to indicate extended ID message. Clear RTR bit as this is not a RTR message. */ My_Message->messageWord[0] = 0; My_Message->messageWord[1] = 0; My_Message->messageWord[2] = 0; My_Message->messageWord[3] = 0; My_Message->msgSID.sid = 0x200; My_Message->msgEID.eid = 0x4002; My_Message->msgEID.ide = 1; My_Message->msgEID.sub_remote_req = 0; My_Message->msgEID.data_length_code = 1; My_Message->data[0] = 0xAA; /* This function lets the CAN module know that the message processing is done.*/ PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL0); /* Direct the CAN module to flush the Transmit channel. This will send any pending message in the Transmit channel. */ PLIB_CAN_TransmitChannelFlush(CAN_ID_1, CAN_CHANNEL0); } Note: The PLIB_CAN_TransmitBufferGet function will return NULL if the transmit channel is full. In this occurs, the PLIB_CAN_TransmitChannelFlush function should be called to empty the channel. The following code shows an example of transmitting a Standard ID message using Channel 0 on the CAN1 module. CAN_TX_MSG_BUFFER * myMessage; /* Get a pointer to the next buffer in the channel check if the returned value is null. */ myMessage = PLIB_CAN_TransmitBufferGet(CAN_ID_1, CAN_CHANNEL0); if(myMessage != NULL) { /* Form a Standard ID CAN message. Start by clearing the buffer. Send message to the CAN2 module. IDE = 0 means Standard ID message. Send one byte of data. */ myMessage->messageWord[0] = 0; myMessage->messageWord[1] = 0; myMessage->messageWord[2] = 0; myMessage->messageWord[3] = 0; myMessage->msgSID.sid = 0x202; myMessage->msgEID.ide = 0; myMessage->msgEID.data_length_code = 1; myMessage->data[0] = 0x23; /* This function lets the CAN module know that the message processing is done and message is ready to be processed. */ PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL0); /* Direct the CAN module to flush the Transmit channel. This will send any pending message in the Transmit channel. */ PLIB_CAN_TransmitChannelFlush(CAN_ID_1, CAN_CHANNEL0); } Receiving a CAN Message The caller application can use either the interrupt or polling technique to detect when a message has been received. The following code shows how the PLIB_CAN_ReceivedMessageGet function can be used to read a received message. CAN_RX_MSG_BUFFER * message; Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 308 message = (CAN_RX_MSG_BUFFER *)PLIB_CAN_ReceivedMessageGet(CAN_ID_1, CAN_CHANNEL1); if(message != NULL) { //Process the message received /* Call the PLIB_CAN_ChannelUpdate function to let the CAN module know that the message processing is done. */ PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL1); } The PLIB_CAN_ReceivedMessageGet function returns an address pointer after converting it from physical address space to virtual address space. Handling Events The CAN module can generate events at the channel level and at the module level. An enabled channel event will cause a module event. An enabled module event will cause a CAN CPU interrupt. See Channel Events and Module Events more information on each type of event. Channel Events Each channel in the module has its own set of events. The type of events are common to all channels. While a specific channel event may be active and can be inspected, it will cause a module event only if the channel event is enabled. The following code shows an example of enabling and disabling channel events using the PLIB_CAN_ChannelEventEnable function. /* CAN 1 Channel 1 and 3 are Transmit channels and Channel 2 and 4 are Receive channels */ /* Enable Channel 1 empty event and channel not full event. Disable Channel 2 full and overflow event */ /* Enable all Transmit events on Channel 2 and disable all RX events on Channel 4 */ PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL1, (CAN_TX_CHANNEL_EMPTY | CAN_TX_CHANNEL_NOT_FULL)); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL2, (CAN_RX_CHANNEL_FULL | CAN_RX_CHANNEL_OVERFLOW)); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL3, CAN_TX_CHANNEL_ANY_EVENT); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL4, CAN_RX_CHANNEL_ANY_EVENT); The PLIB_CAN_ModuleEventGet function can be used to check if a specific event is active in a specific channel. It is only necessary for the event to be active and not enabled for this to work, as shown in the following code example. // Check if RX Channel 2 of CAN module 1 is not empty or if its full. CAN_CHANNEL_EVENT channelEvent; channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_1, CAN_CHANNEL2); if((channelEvent & (CAN_RX_CHANNEL_NOT_EMPTY | CAN_RX_CHANNEL_FULL)) != 0) { // This means that either RX Channel 2 is not empty // or the Channel is full. } If a channel event is enabled and is active, it will set a channel event status flag. This flag indicates that some event in the channel is active. The following code example shows how the PLIB_CAN_AllChannelEventsGet function is used to check if any channel event is active. /* Check if RX Channel 2 of CAN module 1 is not empty or if its full */ CAN_CHANNEL_EVENT channelEvent; channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_1, CAN_CHANNEL2); if((channelEvent & (CAN_RX_CHANNEL_NOT_EMPTY | CAN_RX_CHANNEL_FULL)) != 0) { // This means that either RX Channel 2 is not empty // or the Channel is full. } A receive channel overflow condition is special channel event and is available as a module event as well. The PLIB_CAN_AllChannelOverflowStatusGet function returns the status of all channels that have an active overflow event. Only channels with enabled overflow events will be reflected. The following code shows an example of how this function is used. /* Check if Channel 2 or 3 of CAN module 1 have any active events */ CAN_CHANNEL_MASK channelEvents; Peripheral Libraries Help CAN Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 309 channelEvents = PLIB_CAN_AllChannelEventsGet(CAN_ID_1); if((channelEvents & (CAN_CHANNEL2_MASK | CAN_CHANNEL3_MASK)) != 0) { // Either Channel 2 or 3 has an active event. // The PLIB_CAN_ChannelEventGet function can be // used to query the channel for more details. } Module Events The CAN module has various sources of events, which includes the channel events. The PLIB_CAN_ModuleEventEnable function can be used to enable and disable module level events. Enabling a module event will cause the CAN module to generate a CPU interrupt, as shown in the following code example. // Enable CAN1 module Transmit Event and Receive Events. // Disable Receive Overflow event and operation // mode change event. PLIB_CAN_ModuleEventEnable(CAN_ID_1, (CAN_TX_EVENT | CAN_RX_EVENT)); PLIB_CAN_ModuleEventDisable(CAN_ID_1, (CAN_OPERATION_MODE_CHANGE_EVENT | CAN_RX_OVERFLOW_EVENT)); The PLIB_CAN_ModuleEventGet function can be used to check if any module level events are active. This is shown in the following code example. // Check if the CAN Module 1 Receive event // or if Transmit event is active if((PLIB_CAN_ModuleEventGet(CAN_ID_1) & (CAN_RX_EVENT | CAN_TX_EVENT)) != 0) { // Handle the Receive or Transmit module Event here. } The CAN module also provides code to indicate the highest priority pending event in the CAN module. The PLIB_CAN_PendingEventsGet function can be used to read and analyze this code, as shown in the following code example. /* Implement a switch to check and process any active CAN module events */ CAN_EVENT_CODE eventCode; eventCode = PLIB_CAN_PendingEventsGet(CAN_ID_1); switch(eventCode) { case CAN_NO_EVENT: /* Procedure to handle no CAN events */ break; case CAN_WAKEUP_EVENT: /* Procedure to handle device wake-up on CAN bus activity event */ break; default: break; } Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB X IDE. Library Interface a) Basic Configuration Functions Name Description PLIB_CAN_BusActivityWakeupDisable Disables the wake-up on bus activity receive line filter. PLIB_CAN_BusActivityWakeupEnable Enables the wake-up on bus activity receive line filter. PLIB_CAN_Disable Disables the specified CAN module. PLIB_CAN_Enable Enables the specified CAN module. PLIB_CAN_IsActive Returns 'true' if the CAN module is active. PLIB_CAN_OperationModeGet Obtains the current CAN operating mode. PLIB_CAN_OperationModeSelect Sets the CAN operating mode. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 310 PLIB_CAN_StopInIdleDisable Disables the Stop in Idle feature. PLIB_CAN_StopInIdleEnable Enables the CAN module to stop when the processor enters Idle mode. PLIB_CAN_TimeStampDisable Disables the time stamp feature for the CAN module. PLIB_CAN_TimeStampEnable Enables the time stamp feature for the CAN module. PLIB_CAN_ExistsTimeStampPrescaler Identifies whether the TimeStampPrescaler feature exists on the CAN module. PLIB_CAN_TimeStampPrescalerSet Sets the CAN receive message time stamp timer prescaler. PLIB_CAN_MemoryBufferAssign Assigns buffer memory to the CAN module. b) Advanced Configuration Functions Name Description PLIB_CAN_ChannelResetIsComplete Returns 'true' if the specified channel reset is complete. PLIB_CAN_DeviceNetConfigure Configures the CAN module DeviceNet(TM) filter feature. PLIB_CAN_TimeStampValueGet Returns the current value of the CAN receive message time stamp timer value. PLIB_CAN_TimeStampValueSet Sets the CAN receive message time stamp timer value. c) Bus Speed Configuration Functions Name Description PLIB_CAN_BusLine3TimesSamplingDisable Disables the bus line three times sampling. PLIB_CAN_BusLine3TimesSamplingEnable Enables the bus line three times sampling. PLIB_CAN_BaudRateGet Returns the current CAN module Baud rate. PLIB_CAN_BaudRatePrescaleSetup Sets the prescale divisor applied to the CAN module's input clock before it is used to determine the CAN baud rate. PLIB_CAN_PrecalculatedBitRateSetup Sets the desired Baud rate for the respective CAN module. PLIB_CAN_BitSamplePhaseSet Sets the CAN bit-sampling phase parameters. d) Channel Configuration Functions Name Description PLIB_CAN_ChannelForReceiveSet Configures a CAN channel for receive operation. PLIB_CAN_ChannelForTransmitSet Configures a CAN channel for transmission. PLIB_CAN_ChannelReset Resets a CAN channel. PLIB_CAN_ChannelUpdate Updates the CAN Channel internal pointers. PLIB_CAN_ChannelEventDisable Enables channel level events. e) Event Management Functions Name Description PLIB_CAN_ModuleEventClear Clears the CAN module level events. PLIB_CAN_ModuleEventDisable Disables the module level events. PLIB_CAN_ModuleEventEnable Enables the module level events. PLIB_CAN_ModuleEventGet Returns the status of the CAN module events. PLIB_CAN_AllChannelEventsGet Returns a value representing the event status of all CAN channels. PLIB_CAN_AllChannelOverflowStatusGet Returns a value representing the receive overflow event status of all CAN channels. PLIB_CAN_ChannelEventClear Clears CAN channel events. PLIB_CAN_ChannelEventEnable Enables channel level events. PLIB_CAN_ChannelEventGet Returns a value representing the event status of a CAN channel. PLIB_CAN_PendingEventsGet Returns a value representing the highest priority active event in the module. f) Message Transmit Functions Name Description PLIB_CAN_PendingTransmissionsAbort Aborts any pending transmit operations. PLIB_CAN_TransmissionIsAborted Returns 'true' if the transmit abort operation is complete. PLIB_CAN_TransmitBufferGet Returns a pointer to an empty transmit buffer. PLIB_CAN_TransmitChannelFlush Causes all messages in the specified transmit channel to be transmitted. PLIB_CAN_TransmitChannelStatusGet Returns the condition of the transmit channel. PLIB_CAN_TransmitErrorCountGet Returns the CAN transmit error count Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 311 g) Message Receive Functions Name Description PLIB_CAN_ReceivedMessageGet Returns a pointer to a message to be read from the CAN channel. h) Message Filtering Functions Name Description PLIB_CAN_FilterConfigure Configures a CAN message acceptance filter. PLIB_CAN_FilterDisable Disables a CAN message acceptance filter. PLIB_CAN_FilterEnable Enables a CAN message acceptance filter. PLIB_CAN_FilterIsDisabled Returns 'true' if the specified filter is disabled. PLIB_CAN_FilterMaskConfigure Configures a CAN filter mask. PLIB_CAN_FilterToChannelLink Links a filter to a channel. PLIB_CAN_LatestFilterMatchGet Returns the index of the filter that accepted the latest message. i) Error State Tracking Functions Name Description PLIB_CAN_ReceiveErrorCountGet Returns the CAN receive error count. PLIB_CAN_ErrorStateGet Returns the CAN error status word. j) Information Functions Name Description PLIB_CAN_TotalChannelsGet Returns the total number of CAN channels per CAN module. PLIB_CAN_TotalFiltersGet Returns the total number of CAN Filters per CAN module. PLIB_CAN_TotalMasksGet Returns the total number of CAN masks per CAN module. k) Feature Existence Functions Name Description PLIB_CAN_ExistsActiveStatus Identifies whether the ActiveStatus feature exists on the CAN module. PLIB_CAN_ExistsAllChannelEvents Identifies whether the AllChannelEvents feature exists on the CAN module. PLIB_CAN_ExistsAllChannelOverflow Identifies whether the AllChannelOverflow feature exists on the CAN module. PLIB_CAN_ExistsBusActivityWakeup Identifies whether the BusActivityWakeup feature exists on the CAN module. PLIB_CAN_ExistsBusLine3TimesSampling Identifies whether the BusLine3TimesSampling feature exists on the CAN module. PLIB_CAN_ExistsChannelEvent Identifies whether the ChannelEventGet feature exists on the CAN module. PLIB_CAN_ExistsChannelEventEnable Identifies whether the ChannelEventEnable feature exists on the CAN module. PLIB_CAN_ExistsChannelForReceiveSet Identifies whether the ChannelForReceiveSet feature exists on the CAN module. PLIB_CAN_ExistsChannelForTransmitSet Identifies whether the ChannelForTransmitSet feature exists on the CAN module. PLIB_CAN_ExistsChannelReset Identifies whether the ChannelReset feature exists on the CAN module. PLIB_CAN_ExistsChannelUpdate Identifies whether the ChannelUpdate feature exists on the CAN module. PLIB_CAN_ExistsDeviceNet Identifies whether the DeviceNet feature exists on the CAN module. PLIB_CAN_ExistsEnableControl Identifies whether the EnableControl feature exists on the CAN module. PLIB_CAN_ExistsErrorState Identifies whether the ErrorStateGet feature exists on the CAN module. PLIB_CAN_ExistsFilterConfigure Identifies whether the FilterConfigure feature exists on the CAN module. PLIB_CAN_ExistsFilterEnable Identifies whether the FilterEnable feature exists on the CAN module. PLIB_CAN_ExistsFilterMaskConfigure Identifies whether the FilterMaskConfigure feature exists on the CAN module. PLIB_CAN_ExistsFilterToChannelLink Identifies whether the FilterToChannelLink feature exists on the CAN module. PLIB_CAN_ExistsLatestFilterMatchGet Identifies whether the LatestFilterMatchGet feature exists on the CAN module. PLIB_CAN_ExistsMemoryBufferAssign Identifies whether the MemoryBufferAssign feature exists on the CAN module. PLIB_CAN_ExistsModuleEventClear Identifies whether the ModuleEvents feature exists on the CAN module. PLIB_CAN_ExistsModuleEventEnable Identifies whether the ModuleEventEnable feature exists on the CAN module. PLIB_CAN_ExistsModuleInfo Identifies whether the ModuleInformation feature exists on the CAN module. PLIB_CAN_ExistsOperationModeRead Identifies whether the OperationModeRead feature exists on the CAN module. PLIB_CAN_ExistsOperationModeWrite Identifies whether the OperationModeSet feature exists on the CAN module. PLIB_CAN_ExistsPendingEventsGet Identifies whether the PendingEventsGet feature exists on the CAN module. PLIB_CAN_ExistsPendingTransmissionsAbort Identifies whether the PendingTransmissionsAbort feature exists on the CAN module. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 312 PLIB_CAN_ExistsReceivedMessageGet Identifies whether the ReceivedMessageGet feature exists on the CAN module. PLIB_CAN_ExistsReceiveErrorCount Identifies whether the ReceiveErrorCount feature exists on the CAN module. PLIB_CAN_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the CAN module. PLIB_CAN_ExistsTimeStampEnable Identifies whether the TimeStampEnable feature exists on the CAN module PLIB_CAN_ExistsTimeStampValue Identifies whether the TimeStampValue feature exists on the CAN module. PLIB_CAN_ExistsTransmissionIsAborted Identifies whether the TransmissionAbortStatus feature exists on the CAN module. PLIB_CAN_ExistsTransmitBufferGet Identifies whether the TransmitBufferGet feature exists on the CAN module. PLIB_CAN_ExistsTransmitChannelFlush Identifies whether the TransmitChannelFlush feature exists on the CAN module. PLIB_CAN_ExistsTransmitChannelStatus Identifies whether the TransmitChannelStatus feature exists on the CAN module. PLIB_CAN_ExistsTransmitErrorCountGet Identifies whether the TransmitErrorCountGet feature exists on the CAN module. PLIB_CAN_ExistsBaudRateGet Identifies whether the BaudRateGet feature exists on the CAN module. PLIB_CAN_ExistsBaudRatePrescaleSetup Identifies whether the BaudRatePrescaleSetup feature exists on the CAN module. PLIB_CAN_ExistsBitSamplePhaseSet Identifies whether the BitSamplePhaseSet feature exists on the CAN module. PLIB_CAN_ExistsPrecalculatedBitRateSetup Identifies whether the PrecalculatedBitRateSetup feature exists on the CAN module. l) Data Types and Constants Name Description CAN_CHANNEL Identifies the supported CAN Channels. CAN_CHANNEL_EVENT Identifies all Layer 3 interrupts. CAN_CHANNEL_MASK Lists the series of useful masks. CAN_DNET_FILTER_SIZE Specifies the size of the DeviceNet filter. CAN_ERROR_STATE Specifies the CAN module error states. CAN_FILTER CAN event code returned by the CAN module. CAN_FILTER_MASK Identifies the available CAN filter masks. CAN_FILTER_MASK_TYPE Specifies the CAN filter mask type. CAN_ID_TYPE Specifies the CAN ID type. CAN_MODULE_EVENT Specifies the CAN module events CAN_MODULE_ID Enumeration: CAN_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to get the correct number of modules defined for the desired microcontroller. CAN_MSG_EID Defines the structure of the EID word section of the transmit and receive message. CAN_OPERATION_MODES Lists all possible CAN module operational modes. CAN_RECEIVE_CHANNEL Lists all possible CAN module receive channels. CAN_RECEIVE_MODES Lists all possible CAN module receive modes. CAN_RX_DATA_MODE Enables the Data-only Receive mode or Full Receive mode of a CAN receive channel. CAN_RX_MSG_BUFFER Defines the structure of the CAN receive message buffer CAN_RX_MSG_SID Defines the structure of the SID word section of the receive message. CAN_TIME_SEGMENT_LENGTH All possible values for the assignable number of Time Quanta. CAN_TX_CHANNEL_STATUS Identifies possible transmit channel-specific conditions. CAN_TX_MSG_BUFFER Defines the structure of the CAN transmit message buffer. CAN_TX_MSG_SID Defines the structure of the SID word section of the transmit message. CAN_TX_RTR Specifies the status of the CAN Remote Transmit Request (RTR) feature for a CAN transmit channel. CAN_TXCHANNEL_PRIORITY Specifies the priority of a transmit channel. CAN_RX_DATA_ONLY_SIZE_BYTES Used as the size of the CAN data-only receive message buffer in bytes. CAN_TX_RX_MESSAGE_SIZE_BYTES Used as the array size of the CAN transmit and full receive message buffer. Description This section describes the Application Programming Interface (API) functions of the CAN Peripheral Library. Refer to each section for a detailed description. a) Basic Configuration Functions Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 313 PLIB_CAN_BusActivityWakeupDisable Function Disables the wake-up on bus activity receive line filter. File plib_can.h C void PLIB_CAN_BusActivityWakeupDisable(CAN_MODULE_ID index); Returns None. Description This function disables the Wake up on bus activity receive line filter. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBusActivityWakeup in your application to determine whether this feature is available. Preconditions None. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_BusActivityWakeupDisable(MY_CAN_ID); Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_BusActivityWakeupDisable ( CAN_MODULE_ID index ) PLIB_CAN_BusActivityWakeupEnable Function Enables the wake-up on bus activity receive line filter. File plib_can.h C void PLIB_CAN_BusActivityWakeupEnable(CAN_MODULE_ID index); Returns None. Description This function enables the wake-up on bus activity receive line filter. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBusActivityWakeup in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 314 Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_BusActivityWakeupEnable(MY_CAN_ID); Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_BusActivityWakeupEnable ( CAN_MODULE_ID index ) PLIB_CAN_Disable Function Disables the specified CAN module. File plib_can.h C void PLIB_CAN_Disable(CAN_MODULE_ID index); Returns None. Description This function disables the specified CAN module. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). If the user application clears this bit, it may take a number of cycles before the CAN module completes the current transaction and responds to this request. The user application should check this using the PLIB_CAN_IsActive function to verify that the request has been honored. This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_Disable(MY_CAN_ID); Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_Disable ( CAN_MODULE_ID index ) PLIB_CAN_Enable Function Enables the specified CAN module. File plib_can.h Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 315 C void PLIB_CAN_Enable(CAN_MODULE_ID index); Returns None. Description This function enables the specified CAN module. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). Some of the CAN module settings can be done only when the module is off. Therefore, always call the PLIB_CAN_Enable Function after all other configurations are complete. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsEnableControl in your application to determine whether this feature is available. Preconditions The module should be appropriately configured before being enabled. Example #define MY_CAN_ID CAN_ID_1 //Do all the other configurations before enabling. PLIB_CAN_Enable(MY_CAN_ID); Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_Enable ( CAN_MODULE_ID index ) PLIB_CAN_IsActive Function Returns 'true' if the CAN module is active. File plib_can.h C bool PLIB_CAN_IsActive(CAN_MODULE_ID index); Returns • true = The module is still active • false = The module is completely disabled Description This function returns 'true' if the CAN module is active. This function is typically called after the CAN module is disabled using the PLIB_CAN_Disable function. The CAN module disable request does not complete immediately when requested and depends on the CAN bus status. This function should be called to check whether the module disable is completed. Remarks The CAN module disable operation should not be confused with placing the CAN module in the Disable mode using the PLIB_CAN_OperationModeSelect function. The Disable mode is one of the operating modes of the CAN module. The CAN module is still enabled while in Disable mode. The module disable operation switches the CAN module off. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsActiveStatus in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 316 Example // Disable CAN module 1. Wait until the module is completely disabled. PLIB_CAN_Disable(CAN_ID_1); while(PLIB_CAN_IsActive(CAN_ID_1) == true); Parameters Parameters Description index Identifies the desired CAN module Function bool PLIB_CAN_IsActive ( CAN_MODULE_ID index ) PLIB_CAN_OperationModeGet Function Obtains the current CAN operating mode. File plib_can.h C CAN_OPERATION_MODES PLIB_CAN_OperationModeGet(CAN_MODULE_ID index); Returns The current CAN_OP_MODE type of operation mode of the CAN module. Description This function obtains the current CAN operating mode. This function is typically called after the PLIB_CAN_OperationModeSelect function to check if the requested operation mode change is complete. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsOperationModeRead in your application to determine whether this feature is available. Preconditions None. Example // Check and wait until the CAN module is in Disable Mode. while(PLIB_CAN_OperationModeGet(CAN_ID_1) != CAN_DISABLE_MODE); Parameters Parameters Description index Identifies the desired CAN module Function CAN_OPERATION_MODES PLIB_CAN_OperationModeGet ( CAN_MODULE_ID index ) PLIB_CAN_OperationModeSelect Function Sets the CAN operating mode. File plib_can.h C void PLIB_CAN_OperationModeSelect(CAN_MODULE_ID index, CAN_OPERATION_MODES opMode); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 317 Returns None. Description This function sets the CAN operating mode. The CAN module requires itself to be in certain modes to gain access to module functionality. For example, the module should be in Normal mode to send and receive messages. Note that after this function is called, it should be checked to determine whether the mode was set by using the PLIB_CAN_OperationModeGet function. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsOperationModeWrite in your application to determine whether this feature is available. Preconditions None. Example // Set the CAN_ID_1 operating mode to Configuration mode. PLIB_CAN_OperationModeSelect(CAN_ID_1, CAN_CONFIGURATION_MODE); Parameters Parameters Description module Identifies the desired CAN module opMode Desired CAN_OP_MODE type of the mode to be set Function void PLIB_CAN_OperationModeSelect ( CAN_MODULE_ID index, CAN_OPERATION_MODES opMode ) PLIB_CAN_StopInIdleDisable Function Disables the Stop in Idle feature. File plib_can.h C void PLIB_CAN_StopInIdleDisable(CAN_MODULE_ID index); Returns None. Description This function disables the CAN module from stopping operation when the system enters Idle mode. The module continues operation when the system enters Idle mode. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_StopInIdleDisable(MY_CAN_ID); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 318 Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_StopInIdleDisable ( CAN_MODULE_ID index ) PLIB_CAN_StopInIdleEnable Function Enables the CAN module to stop when the processor enters Idle mode. File plib_can.h C void PLIB_CAN_StopInIdleEnable(CAN_MODULE_ID index); Returns None. Description This function configures the CAN module to stop operation when the system enters Idle mode. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_StopInIdleEnable(MY_CAN_ID); Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_StopInIdleEnable ( CAN_MODULE_ID index ) PLIB_CAN_TimeStampDisable Function Disables the time stamp feature for the CAN module. File plib_can.h C void PLIB_CAN_TimeStampDisable(CAN_MODULE_ID index); Returns None. Description This function disables time stamp capture feature for the CAN module. This conserves power by stopping the CAN timer. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 319 Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_TimeStampDisable(MY_CAN_ID); Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_TimeStampDisable ( CAN_MODULE_ID index ) PLIB_CAN_TimeStampEnable Function Enables the time stamp feature for the CAN module. File plib_can.h C void PLIB_CAN_TimeStampEnable(CAN_MODULE_ID index); Returns None. Description This function enables the time stamp capture feature for the CAN module. The CAN timer value will be stored on valid message reception and is stored with the message. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampEnable in your application to determine whether this feature is available. Preconditions None Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_TimeStampEnable(MY_CAN_ID); Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_TimeStampEnable ( CAN_MODULE_ID index ) Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 320 PLIB_CAN_ExistsTimeStampPrescaler Function Identifies whether the TimeStampPrescaler feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsTimeStampPrescaler(CAN_MODULE_ID index); Returns • true = The TimeStampPrescaler feature is supported on the device • false = The TimeStampPrescaler feature is not supported on the device Description This function identifies whether the TimeStampPrescaler feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TimeStampPrescalerSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsTimeStampPrescaler( CAN_MODULE_ID index ) PLIB_CAN_TimeStampPrescalerSet Function Sets the CAN receive message time stamp timer prescaler. File plib_can.h C void PLIB_CAN_TimeStampPrescalerSet(CAN_MODULE_ID index, unsigned preScaler); Returns None. Description This function sets the CAN receive message time stamp timer prescaler. This prescaler determines the rate at the which the time stamp timer is incremented. For example, if the prescaler value is 0xFF, the time stamp timer is incremented by 1 every 255 system clock periods. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampPrescaler in your application to determine whether this feature is available. Preconditions None. Example // Set the CAN_ID_1 Receive Message Time Stamp Timer prescaler to increment //the Time Stamp Timer every 1024 system clock periods. PLIB_CAN_TimeStampPrescalerSet(CAN_ID_1, 1024); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 321 Parameters Parameters Description module Identifies the desired CAN module preScaler Prescaler for the CAN receive message time stamp timer. This value should be between 0x0 and 0xFFFF. Function void PLIB_CAN_TimeStampPrescalerSet( CAN_MODULE_ID index, unsigned preScaler ) PLIB_CAN_MemoryBufferAssign Function Assigns buffer memory to the CAN module. File plib_can.h C void PLIB_CAN_MemoryBufferAssign(CAN_MODULE_ID index, void * buffer); Returns None. Description This function assigns buffer memory address to the CAN module. The CAN module uses this buffer memory to store messages to be transmitted and received. The size of the memory buffer should be enough to accommodate the required number of message buffers and channels. Remarks This API is useful only if the CAN module uses device RAM for message buffers and message FIFO location is software configurable. This should not be used if the device message buffer is part of SFR. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsMemoryBufferAssign in your application to determine whether this feature is available. Preconditions The module should be in Configuration mode (using the PLIB_CAN_OperationModeSelect function). Example // Define and assign a CAN 1 memory buffer for 2 Transmit channels and 1 Receive // channel, each with 4 message buffers uint8_t canMemoryBuffer [3 * 4 * CAN_TX_RX_MESSAGE_SIZE_BYTES]; PLIB_CAN_MemoryBufferAssign(CAN_ID_1, canMemoryBuffer); Parameters Parameters Description index Identifies the desired CAN module buffer Pointer to the buffer memory area Function void PLIB_CAN_MemoryBufferAssign ( CAN_MODULE_ID index, void * buffer ) b) Advanced Configuration Functions PLIB_CAN_ChannelResetIsComplete Function Returns 'true' if the specified channel reset is complete. File plib_can.h Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 322 C bool PLIB_CAN_ChannelResetIsComplete(CAN_MODULE_ID index, CAN_CHANNEL channel); Returns • true = Channel reset is complete • false = Channel reset is in progress Description This function returns 'true' if the specified channel reset is complete. This function should preferably be called after calling the PLIB_CAN_ChannelReset function. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelReset in your application to determine whether this feature is available. Preconditions None. Example // Reset channel 4 of CAN_ID_1 module // and wait until the reset is complete PLIB_CAN_ChannelReset(CAN_ID_1,CAN_CHANNEL4); while(PLIB_CAN_ChannelResetIsComplete(CAN_ID_1,CAN_CHANNEL4) != true); Parameters Parameters Description index Identifies the desired CAN module channel Identifies the CAN Channel to be inspected for reset Function bool PLIB_CAN_ChannelResetIsComplete ( CAN_MODULE_ID index, CAN_CHANNEL channel ) PLIB_CAN_DeviceNetConfigure Function Configures the CAN module DeviceNet(TM) filter feature. File plib_can.h C void PLIB_CAN_DeviceNetConfigure(CAN_MODULE_ID index, CAN_DNET_FILTER_SIZE dncnt); Returns None. Description This function configures the CAN module DeviceNet filter feature. DeviceNet filtering allows a portion of the data payload to be used as a filter criteria. This function allows the size of this filter to be configured in bits. The filter can also be disabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsDeviceNet in your application to determine whether this feature is available. Preconditions The CAN module should preferably be in Configuration mode (using the PLIB_CAN_OperationModeSelect function). Example // Disable the CAN_ID_1 DeviceNet filter feature. PLIB_CAN_DeviceNetConfigure(CAN_ID_1, CAN_DNET_FILTER_DISABLE); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 323 // Set the CAN_ID_2 Device Net Filter Size to 10 bits. PLIB_CAN_DeviceNetConfigure(CAN_ID_2, CAN_DNET_FILTER_SIZE_10_BIT); Parameters Parameters Description index Identifies the desired CAN module dncnt Specifies the CAN_DNET_FILTER_SIZE size of the DeviceNet filter in bits Function void PLIB_CAN_DeviceNetConfigure ( CAN_MODULE_ID index, CAN_DNET_FILTER_SIZE dncnt ) PLIB_CAN_TimeStampValueGet Function Returns the current value of the CAN receive message time stamp timer value. File plib_can.h C unsigned PLIB_CAN_TimeStampValueGet(CAN_MODULE_ID index); Returns The current value of the CAN receive message time stamp timer. Description This function gets the current value of the CAN receive message time stamp timer value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampValue in your application to determine whether this feature is available. Preconditions None. Example unsigned int timeStampTimerVal; // Get the current time stamp timer value. timeStampTimerVal = PLIB_CAN_TimeStampValueGet(CAN_ID_1); Parameters Parameters Description index Identifies the desired CAN module Function unsigned PLIB_CAN_TimeStampValueGet ( CAN_MODULE_ID index ) PLIB_CAN_TimeStampValueSet Function Sets the CAN receive message time stamp timer value. File plib_can.h C void PLIB_CAN_TimeStampValueSet(CAN_MODULE_ID index, unsigned value); Returns None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 324 Description This function sets the CAN receive message time stamp timer value. The timer will then start counting up from this value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampValue in your application to determine whether this feature is available. Preconditions None. Example // Set start value of CAN_ID_1 Receive Message Time Stamp Timer to 0x100 PLIB_CAN_TimeStampValueSet(CAN_ID_1, 0x0100); Parameters Parameters Description index Identifies the desired CAN module value Start value of the receive message time stamp timer. This value should be between 0x0 and 0xFFFF. Function void PLIB_CAN_TimeStampValueSet ( CAN_MODULE_ID index, unsigned value ) c) Bus Speed Configuration Functions PLIB_CAN_BusLine3TimesSamplingDisable Function Disables the bus line three times sampling. File plib_can.h C void PLIB_CAN_BusLine3TimesSamplingDisable(CAN_MODULE_ID index); Returns None. Description The bus line will be sampled three times at the sampling point. If this is disabled, the bus line will be sampled only once. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This API may not function if the baud rate prescale value is more than a certain limit. Refer to the specific device data sheet to determine the maximum prescale that allows three times sampling. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBusLine3TimesSampling in your application to determine whether this feature is available. Preconditions This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE == PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_BusLine3TimesSamplingDisable(MY_CAN_ID); } Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 325 Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_BusLine3TimesSamplingDisable ( CAN_MODULE_ID index ) PLIB_CAN_BusLine3TimesSamplingEnable Function Enables the bus line three times sampling. File plib_can.h C void PLIB_CAN_BusLine3TimesSamplingEnable(CAN_MODULE_ID index); Returns None. Description The bus line will be sampled three times at the sampling point. If this is disabled, the bus line will be sampled only once. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This API may not function if the baud rate prescale value is more than a certain limit. Refer to the specific device data sheet to determine the maximum prescale that allows three times sampling. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBusLine3TimesSampling in your application to determine whether this feature is available. Preconditions This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE == PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_BusLine3TimesSamplingEnable(MY_CAN_ID); } Parameters Parameters Description index Identifies the desired CAN module Function void PLIB_CAN_BusLine3TimesSamplingEnable ( CAN_MODULE_ID index ) PLIB_CAN_BaudRateGet Function Returns the current CAN module Baud rate. File plib_can.h C uint32_t PLIB_CAN_BaudRateGet(CAN_MODULE_ID index, uint32_t sysclock); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 326 Returns Current Baud rate value in kbps. Description This function returns the current baud rate of the CAN module. Remarks The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBaudRateGet in your application to determine whether this feature is available. Preconditions None. Example #define MY_CAN_ID CAN_ID_1 #define CAN_CLOCK 80000000 uint32_t baudRate; baudRate = PLIB_CAN_BaudRateGet(MY_CAN_ID, CAN_CLOCK); Parameters Parameters Description index Identifies the desired CAN module sysclock CAN input clock frequency Function uint32_t PLIB_CAN_BaudRateGet( CAN_MODULE_ID index, uint32_t clock); PLIB_CAN_BaudRatePrescaleSetup Function Sets the prescale divisor applied to the CAN module's input clock before it is used to determine the CAN baud rate. File plib_can.h C bool PLIB_CAN_BaudRatePrescaleSetup(CAN_MODULE_ID index, uint16_t prescale); Returns • true = BaudRate prescale Setup success • false = BaudRate prescale Setup failure, arguments passed are beyond the possible limits Description Sets the prescale divisor applied to the CAN module's input clock before it is used to determine the CAN baud rate. Remarks The prescale value is the actual input clock divisor value. baud rate = input clock / divisor However, the values must be chosen carefully so that the desired resultant baud rate is an integral number (not fractional). The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBaudRatePrescaleSetup in your application to determine whether this feature is available. Preconditions This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 327 Example #define MY_CAN_ID CAN_ID_1 #define PRESCALE 7 bool result; if (CAN_CONFIGURATION_MODE == PLIB_CAN_OperationModeGet(MY_CAN_ID)) { result = PLIB_CAN_BaudRatePrescaleSetup(MY_CAN_ID, PRESCALE); if(false == result) { // Error occurred } } Parameters Parameters Description index Identifies the desired CAN module prescale Prescale value by which the input clock to the CAN module is divided to determine the CAN baud rate. Function bool PLIB_CAN_BaudRatePrescaleSetup( CAN_MODULE_ID index, uint16_t prescale ) PLIB_CAN_PrecalculatedBitRateSetup Function Sets the desired Baud rate for the respective CAN module. File plib_can.h C bool PLIB_CAN_PrecalculatedBitRateSetup(CAN_MODULE_ID index, uint8_t prescale, uint8_t syncjumpWidth, uint8_t propagation, uint8_t segment1, uint8_t segment2); Returns • true = Baud rate setup success • false = Baud rate setup failure, arguments passed are beyond the possible limits Description This function sets the configuration register with the desired Baud rate. Remarks This function's parameters must be precalculated for the desired baud rate and properly encoded for the registers of the CAN module that is in use. This function is primarily intended to be used in conjunction with the MPLAB X IDE ECAN Baud Rate calculator or the MPLAB Harmony Configurator (MHC), which precalculates and correctly encodes these values. The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPrecalculatedBitRateSetup in your application to determine whether this feature is available. Preconditions Use the "ECAN Bit Rate Calculator" MPLAB X IDE plug-in to get all of the parameters needed for the function. This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. Example // Use ECAN Bit Rate Calculator plug-in to get parameter values for 500kbps // Baud rate. #define MY_CAN_ID CAN_ID_1 #define PRESCALE 6 #define SYNCJUMPWIDTH 1 Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 328 #define PROPAGATION 2 #define SEGMENT1 4 #define SEGMENT2 4 bool result; if (CAN_CONFIGURATION_MODE == PLIB_CAN_OperationModeGet(MY_CAN_ID)) { result = PLIB_CAN_PrecalculatedBitRateSetup( MY_CAN_ID, PRESCALE, SYNCJUMPWIDTH, PROPAGATION, SEGMENT1, SEGMENT2 ); if(false == result) { // Error occurred, handle accordingly } } Parameters Parameters Description index Identifies the desired CAN module prescale The CAN module input clock prescale divisor. syncJumpWidth The synchronization jump width is the number of time quanta by which the CAN module may adjust phase segment 1 and segment 2 to compensate for jitter in the bit phase. propagation Propagation segment length is the number of time quanta allocated to allow for propagation variation in the bit sampling phase. segment1 Phase segment 1 length(in time quanta) after the propagation segment before sampling of the bit begins. segment2 Phase segment 2 length (in time quanta) after sampling has begun. Function bool PLIB_CAN_PrecalculatedBitRateSetup( CAN_MODULE_ID index, uint8_t prescale, uint8_t syncjumpWidth, uint8_t propagation, uint8_t segment1, uint8_t segment2 ); PLIB_CAN_BitSamplePhaseSet Function Sets the CAN bit-sampling phase parameters. File plib_can.h C bool PLIB_CAN_BitSamplePhaseSet(CAN_MODULE_ID index, uint8_t syncJumpWidth, uint8_t propagation, uint8_t segment1, uint8_t segment2); Returns • true = BitSamplePhase Setup success • false = BitSamplePhase Setup failure, arguments passed are beyond the possible limits Description This function selects the CAN bit-sampling phase parameters that determine the Baud rate setting. For a given baud rate setting, a single bit time is divided into a number segments or phases of equal time length called "time quanta". The bit time for a given baud rate (i.e. 1/baud) is divided into a number of time quanta of equal length. 1 time quantum = (one bit time) / (total number of time quanta) These time quanta are then partitioned into different phases of the bit sample time called synchronization phase (always 1 time quantum long), the propagation phase, and the segment 1 and segment 2 phases. Thus, the total number of time quanta equals the sum of the time quanta allocated to each phase. total number of time quanta = (1 + propagation + segment1 + segment2) (Sampling of the bit occurs at the end of the segment 1 phase.) This function determines the length of each phase (in time quanta) as well as the synchronization jump width, the number of time quanta by which Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 329 the CAN module may move time from segment 1 to segment 2 (or vice versa) to adjust for jitter in the bit sampling phase timing. Remarks The values of the syncJumpWidth, propagation, segment1 and segment2 parameters should passed as a number of time quanta for each. These values will be encoded by this function correctly for the the part in use before they are written to the registers of the CAN peripheral. To pass in precalculated values that are already encoded for the physical registers of the CAN controller (such as the values provided by the ECAN Baud Rate Calculator or the MPLAB Harmony Configurator (MHC) utility), use the PLIB_CAN_PrecalculatedBitRateSetup function instead. The MY_CAN_ID macro in the example above is used as a place holder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBitSamplePhaseSet in your application to determine whether this feature is available. Preconditions This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. Example #define MY_CAN_ID CAN_ID_1 #define SYNCJUMPWIDTH 1 #define PROPAGATION 2 #define SEGMENT1 4 #define SEGMENT2 4 bool result; if (CAN_CONFIGURATION_MODE == PLIB_CAN_OperationModeGet(MY_CAN_ID)) { result = PLIB_CAN_BitSamplePhaseSet(MY_CAN_ID, SYNCJUMPWIDTH, PROPAGATION, SEGMENT1, SEGMENT2); if(false == result) { // Error occurred } } Parameters Parameters Description index Identifies the desired CAN module syncJumpWidth The synchronization jump width is the number of time quanta by which the CAN module may adjust phase segment 1 and segment 2 to compensate for jitter in the bit phase to achieve a valid sampling point. propagation Propagation segment length is the number of time quanta allocated to allow for propagation variation in the bit sampling phase. segment1 Phase segment 1 length(in time quanta) after the propagation segment before sampling of the bit begins. segment2 Phase segment 2 length (in time quanta) after sampling has begun. Function bool PLIB_CAN_BitSamplePhaseSet( CAN_MODULE_ID index, uint8_t syncJumpWidth, uint8_t propagation, uint8_t segment1, uint8_t segment2) d) Channel Configuration Functions PLIB_CAN_ChannelForReceiveSet Function Configures a CAN channel for receive operation. File plib_can.h Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 330 C void PLIB_CAN_ChannelForReceiveSet(CAN_MODULE_ID index, CAN_CHANNEL channel, uint32_t channelSize, CAN_RX_DATA_MODE dataOnly); Returns None. Description This function configures a CAN channel for receive operation. A receive channel can be either a full CAN message receive channel, which receives an entire CAN message (Arbitration field + Data field) or a data-only message channel, which receives only the data payload section of the message. A receive channel can buffer up to 32 messages. The number of messages to buffer (i.e., the size of the channel) is set by the channelSize parameter. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelForReceiveSet in your application to determine whether this feature is available. Preconditions The CAN module should be in Configuration mode. This is achieved by using the PLIB_CAN_OperationModeSelect function. Example // Configure channel 4 of CAN module for receive operation. Set channel // size to buffer 10 messages. // Channel should be data only receive channel PLIB_CAN_ChannelForReceiveSet(CAN_ID_1, CAN_CHANNEL4, 10, CAN_RX_DATA_ONLY); Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Receive channel channelSize Specifies the number of received messages that the channel can buffer before it overflows. This should be a value between 1 and 32. dataOnly Specifies a full CAN message Receive channel or a data-only message channel. • CAN_RX_DATA_ONLY - Channel will be a data-only message receive channel • CAN_RX_FULL_RECEIVE - Channel will be a full CAN message receive channel Function void PLIB_CAN_ChannelForReceiveSet( CAN_MODULE_ID index, CAN_CHANNEL channel, uint32_t channelSize, CAN_RX_DATA_MODE dataOnly ) PLIB_CAN_ChannelForTransmitSet Function Configures a CAN channel for transmission. File plib_can.h C void PLIB_CAN_ChannelForTransmitSet(CAN_MODULE_ID index, CAN_CHANNEL channel, uint8_t channelSize, CAN_TX_RTR rtren, CAN_TXCHANNEL_PRIORITY priority); Returns None. Description This function configures a CAN Channel for transmission. The size of the channel specifies the number of messages that the channel can buffer. The channel is a First In First Out (FIFO) type of buffer. The remote transmit request feature allows the transmit channel to start transmitting when an associated filter has received a message. The transmit channel priority determines the priority as compared to other transmit channels. If two transmit channels have the same priority, the natural channel priority determines which channel transmits first. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 331 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelForTransmitSet in your application to determine whether this feature is available. Preconditions The CAN Module should be in Configuration mode. This is achieved by using the PLIB_CAN_OperationModeSelect function. Example // Configure CAN 1 Channel 2 for Transmit operation. Set the channel size to 15 // and enable remote transmit request. Set the priority to low medium // priority. PLIB_CAN_ChannelForTransmitSet (CAN_ID_1, CAN_CHANNEL2, 15, CAN_TX_RTR_ENABLED, CAN_LOW_MEDIUM_PRIORITY); Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel channelSize Size of the channel in messages. This value should be between 1 and 32. rtren Enables disables Remote Transmit Request: • CAN_TX_RTR_ENABLED - Remote Transmit Request is enabled • CAN_TX_RTR_DISABLED - Remote Transmit Request is disabled priority Specifies the priority of the Transmit channel Function void PLIB_CAN_ChannelForTransmitSet ( CAN_MODULE_ID index, CAN_CHANNEL channel, uint8_t channelSize, CAN_TX_RTR rtren, CAN_TXCHANNEL_PRIORITY priority ) PLIB_CAN_ChannelReset Function Resets a CAN channel. File plib_can.h C void PLIB_CAN_ChannelReset(CAN_MODULE_ID index, CAN_CHANNEL channel); Returns None. Description This function resets a CAN channel. Resetting a CAN channel causes it to discard any unread received messages or any messages that have not been transmitted yet. The reset operation will wait if a message is being currently transmitted or is being received. The PLIB_CAN_ChannelResetIsComplete function can be used to check if the channel reset is complete. Remarks Attempting to read from a channel that is reset will return messages that may have already been read or may not have been read at all. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelReset in your application to determine whether this feature is available. Preconditions None. Example // Reset channel 4 of CAN_ID_1 module // and wait until the reset is complete PLIB_CAN_ChannelReset(CAN_ID_1,CAN_CHANNEL4); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 332 while(PLIB_CAN_ChannelResetIsComplete(CAN_ID_1,CAN_CHANNEL4) != true); Parameters Parameters Description index Identifies the desired CAN module channel Identifies the CAN channel to be reset Function void PLIB_CAN_ChannelReset( CAN_MODULE_ID index, CAN_CHANNEL channel ) PLIB_CAN_ChannelUpdate Function Updates the CAN Channel internal pointers. File plib_can.h C void PLIB_CAN_ChannelUpdate(CAN_MODULE_ID index, CAN_CHANNEL channel); Returns None. Description This function updates the CAN Channel internal pointers. This function should be called when a message has been read or processed completely from a CAN receive channel (using the PLIB_CAN_ReceivedMessageGet function). It should be called after a new message has been written to a CAN transmit channel (using the PLIB_CAN_TransmitBufferGet function) and before the PLIB_CAN_TransmitChannelFlush function. Trying to read a CAN receive channel that has not been updated will cause the PLIB_CAN_ReceivedMessageGet function to return the same message. Writing to a CAN transmit channel that has not been updated will cause the last written message to be overwritten. Remarks The PLIB_CAN_ChannelUpdate function should be called on a CAN receive channel only after the message obtained using the PLIB_CAN_ReceivedMessageGet function has been read or processed completely. The CAN module peripheral library does not provide access to older messages once the PLIB_CAN_ChannelUpdate function has been called. When using the PLIB_CAN_TransmitMessageBuffer function to write to a CAN transmit channel the PLIB_CAN_ChannelUpdate function should be called only when a valid message has been written to the channel. Calling the update function without writing to the CAN channel will cause an incorrect message to be output on the CAN channel when the transmit channel is flushed. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelUpdate in your application to determine whether this feature is available. Preconditions This function is effective only when the CAN module is not in Configuration mode or Disable mode. Example // CAN_ID_1 Channel 1 is a Receive channel and Channel 2 is a Transmit // channel. Read and update Channel 1. Write a message to Channel 2 and then // update and flush the channel. CAN_TX_MSG_BUFFER * TransmitMessage; CAN_RX_MSG_BUFFER * rxMessage; rxMessage = PLIB_CAN_ReceivedMessageGet(CAN_ID_1, CAN_CHANNEL1); if(rxMessage != NULL) { // Process the received message. PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL1); } TransmitMessage = PLIB_CAN_TransmitBufferGet(CAN_ID_1, CAN_CHANNEL2); if(TransmitMessage != NULL) { Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 333 // Write a message to buffer PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL2); PLIB_CAN_TransmitChannelFlush(CAN_ID_1, CAN_CHANNEL2); } Parameters Parameters Description index Identifies the desired CAN module channel Identifies the CAN channel to be updated Function void PLIB_CAN_ChannelUpdate ( CAN_MODULE_ID index, CAN_CHANNEL channel ) PLIB_CAN_ChannelEventDisable Function Enables channel level events. File plib_can.h C void PLIB_CAN_ChannelEventDisable(CAN_MODULE_ID index, CAN_CHANNEL channel, CAN_CHANNEL_EVENT flags); Returns None. Description This function disables channel level events. Any enabled channel event will cause a CAN module event. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelEventEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_CAN_ChannelEventDisable(CAN_ID_1, CAN_CHANNEL1, CAN_TX_CHANNEL_EMPTY); Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel flags Identifies the CAN channel event(s) to be affected. Several events can be controlled by logically ORed combination of events. Function void PLIB_CAN_ChannelEventDisable ( CAN_MODULE_ID index, CAN_CHANNEL channel, CAN_CHANNEL_EVENT flags ) e) Event Management Functions PLIB_CAN_ModuleEventClear Function Clears the CAN module level events. File plib_can.h Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 334 C void PLIB_CAN_ModuleEventClear(CAN_MODULE_ID index, CAN_MODULE_EVENT flags); Returns None. Description This function clears module level events. If the event condition is persistent, clearing the event will have no effect. The event condition itself should be cleared. The CAN_SYSTEM_ERROR_EVENT can only be cleared by disabling the CAN module using the PLIB_CAN_Enable function. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleEventClear in your application to determine whether this feature is available. Preconditions None. Example // Clear CAN_ID_1 Transmit Event and Receive Events. PLIB_CAN_ModuleEventClear(CAN_ID_1, (CAN_TX_EVENT | CAN_RX_EVENT)); Parameters Parameters Description index Identifies the desired CAN module flags Identifies the CAN module level events to be affected. Several events can be cleared by specifying a logically ORed combination of events. Function void PLIB_CAN_ModuleEventClear ( CAN_MODULE_ID index, CAN_MODULE_EVENT flags ) PLIB_CAN_ModuleEventDisable Function Disables the module level events. File plib_can.h C void PLIB_CAN_ModuleEventDisable(CAN_MODULE_ID index, CAN_MODULE_EVENT flags); Returns None. Description This function disables module level events. Any enabled module event will cause the CAN module to generate a CPU interrupt. Remarks An event can be active regardless of it being enabled or disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleEventEnable in your application to determine whether this feature is available. Preconditions None. Example // Enable CAN_ID_1 Transmit Event and Receive Events. // Disable Receive Overflow event and operation // mode change event. PLIB_CAN_ModuleEventDisable(CAN_ID_1, (CAN_TX_EVENT | CAN_RX_EVENT)); PLIB_CAN_ModuleEventDisable(CAN_ID_1, (CAN_OPERATION_MODE_CHANGE_EVENT | Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 335 CAN_RX_OVERFLOW_EVENT)); Parameters Parameters Description index Identifies the desired CAN module flags Identifies the CAN module level events to be affected. Several events can be controlled by logically ORed combination of events. Function void PLIB_CAN_ModuleEventDisable ( CAN_MODULE_ID index, CAN_MODULE_EVENT flags ) PLIB_CAN_ModuleEventEnable Function Enables the module level events. File plib_can.h C void PLIB_CAN_ModuleEventEnable(CAN_MODULE_ID index, CAN_MODULE_EVENT flags); Returns None. Description This function enables module level events. Any enabled module event will cause the CAN module to generate a CPU interrupt. Remarks An event can be active regardless of it being enabled or disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleEventEnable in your application to determine whether this feature is available. Preconditions None. Example // Enable CAN_ID_1 Transmit Event and Receive Events. // Disable Receive Overflow event and operation // mode change event. PLIB_CAN_ModuleEventEnable(CAN_ID_1, (CAN_TX_EVENT | CAN_RX_EVENT)); PLIB_CAN_ModuleEventEnable(CAN_ID_1, (CAN_OPERATION_MODE_CHANGE_EVENT | CAN_RX_OVERFLOW_EVENT)); Parameters Parameters Description index Identifies the desired CAN module flags Identifies the CAN module level events to be affected. Several events can be controlled by logically ORed combination of events. Function void PLIB_CAN_ModuleEventEnable ( CAN_MODULE_ID index, CAN_MODULE_EVENT flags ) PLIB_CAN_ModuleEventGet Function Returns the status of the CAN module events. File plib_can.h C CAN_MODULE_EVENT PLIB_CAN_ModuleEventGet(CAN_MODULE_ID index); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 336 Returns A status word representing the status of the CAN module events. Description This function returns the status of the CAN module events. The routine returns a status word. This word should be logically ANDed with the desired CAN_MODULE_EVENT event mask. A non-zero result of such an operation would mean that the events specified in the event mask are active. An event mask can contain one event or can be a logical OR combination of multiple events. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleEventClear in your application to determine whether this feature is available. Preconditions None. Example // Check if the CAN_ID_1 Module Receive event // or if Transmit event is active if((PLIB_CAN_ModuleEventGet(CAN_ID_1) & (CAN_RX_EVENT | CAN_TX_EVENT)) != 0) { // Handle the Receive or Transmit module Event here. } // Check if the CAN_ID_2 System Error Event // is active if((PLIB_CAN_ModuleEventGet(CAN_ID_2) & CAN_SYSTEM_ERROR_EVENT) != 0) { // CAN_ID_2 System error event is active. } Parameters Parameters Description index Identifies the desired CAN module Function CAN_MODULE_EVENT PLIB_CAN_ModuleEventGet( CAN_MODULE_ID index ) PLIB_CAN_AllChannelEventsGet Function Returns a value representing the event status of all CAN channels. File plib_can.h C CAN_CHANNEL_MASK PLIB_CAN_AllChannelEventsGet(CAN_MODULE_ID index); Returns Returns a value that can be logically ANDed with a CAN_CHANNEL_MASK mask value to check if any event on a channel is active. Description This function returns a value representing the event status of all of the CAN channels. The return value can be logically ANDed with a CAN_CHANNEL_MASK type to check whether the channel has any active events. Only an enabled channel event will cause the bit to be updated. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsAllChannelEvents in your application to determine whether this feature is available. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 337 Preconditions None. Example // Check if Channel 2 or 3 of CAN_ID_1 module // have any active events CAN_CHANNEL_MASK channelEvents; channelEvents = PLIB_CAN_AllChannelEventsGet(CAN_ID_1); if((channelEvents & (CAN_CHANNEL2_MASK | CAN_CHANNEL3_MASK)) != 0) { // Either Channel 2 or 3 has an active event. // The PLIB_CAN_ChannelEventGet function can be // used to query the channel for more details. } // Check if Channel 31 of CAN_ID_2 module // has an any active events channelEvents = PLIB_CAN_AllChannelEventsGet(CAN_ID_2); if((channelEvents & CAN_CHANNEL31_MASK) != 0) { // Channel 31 of CAN_ID_2 module // has an active event. } Parameters Parameters Description index Identifies the desired CAN module Function CAN_CHANNEL_MASK PLIB_CAN_AllChannelEventsGet( CAN_MODULE_ID index ) PLIB_CAN_AllChannelOverflowStatusGet Function Returns a value representing the receive overflow event status of all CAN channels. File plib_can.h C CAN_CHANNEL_MASK PLIB_CAN_AllChannelOverflowStatusGet(CAN_MODULE_ID index); Returns Returns a value that can be logically ANDed with a CAN_CHANNEL_MASK mask value to check if a receive channel overflow event is active. Description This function returns a value representing the Receive overflow event status of all the CAN Channels. The return value can be logically ANDed with a CAN_CHANNEL_MASK type to check whether a channel has any active receive overflow events. The return value will reflect the channel status only if the receive overflow event of the channel is enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsAllChannelOverflow in your application to determine whether this feature is available. Preconditions None. Example // Check if Receive Channel 2 or 3 of CAN_ID_1 module // have overflowed Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 338 CAN_CHANNEL_MASK channelOverflowEvent; channelOverflowEvent = PLIB_CAN_AllChannelOverflowStatusGet(CAN_ID_1); if((channelOverflowEvent & (CAN_CHANNEL2_MASK | CAN_CHANNEL3_MASK)) != 0) { // Either Receive Channel 2 or 3 has overflowed. // The PLIB_CAN_ChannelEventGet function can be // used to query the channel for more details. } // Check if Receive Channel 31 of CAN_ID_2 module // has overflowed channelOverflowEvent = PLIB_CAN_AllChannelOverflowStatusGet(CAN_ID_2); if((channelOverflowEvent & CAN_CHANNEL31_MASK) != 0) { // Channel 31 of CAN_ID_2 module // has overflowed. } Parameters Parameters Description index Identifies the desired CAN module Function CAN_CHANNEL_MASK PLIB_CAN_AllChannelOverflowStatusGet ( CAN_MODULE_ID index ) PLIB_CAN_ChannelEventClear Function Clears CAN channel events. File plib_can.h C void PLIB_CAN_ChannelEventClear(CAN_MODULE_ID index, CAN_CHANNEL channel, CAN_CHANNEL_EVENT events); Returns None. Description This function clears channel events. The events to be cleared are specified as mask. Note that only the receive overflow event is clearable. Attempting to clear other events will have no effect since these events are persistent and clear only when the event condition is cleared. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelEvent in your application to determine whether this feature is available. Preconditions None. Example // Clear CAN_ID_2 Receive Channel 3 overflow event PLIB_CAN_ChannelEventClear(CAN_ID_2, CAN_CHANNEL3, CAN_RX_CHANNEL_OVERFLOW); Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel events Mask specifying the events to be cleared Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 339 Function void PLIB_CAN_ChannelEventClear ( CAN_MODULE_ID index, CAN_CHANNEL channel, CAN_CHANNEL_EVENT events ) PLIB_CAN_ChannelEventEnable Function Enables channel level events. File plib_can.h C void PLIB_CAN_ChannelEventEnable(CAN_MODULE_ID index, CAN_CHANNEL channel, CAN_CHANNEL_EVENT flags); Returns None. Description This function enables channel level events. Any enabled channel event will cause a CAN module event. An event can be active regardless of it being enabled or disabled. Enabling a transmit type of event for a receive channel will have no any effect. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelEventEnable in your application to determine whether this feature is available. Preconditions None. Example // CAN_ID_1 Channel 1 and 3 are Transmit channels and Channel 2 and 4 are // Receive channels. Enable Channel 1 empty event and channel not full // event. Disable Channel 2 full and overflow event. // Enable all Transmit events on Channel 2 and disable all Receive events on // on Channel 4. PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL1, (CAN_TX_CHANNEL_EMPTY | CAN_TX_CHANNEL_NOT_FULL)); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL2, (CAN_RX_CHANNEL_FULL | CAN_RX_CHANNEL_OVERFLOW)); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL3, CAN_TX_CHANNEL_ANY_EVENT); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL4, CAN_RX_CHANNEL_ANY_EVENT); Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel flags Identifies the CAN channel event(s) to be affected. Several events can be controlled by logically ORed combination of events. Function void PLIB_CAN_ChannelEventEnable ( CAN_MODULE_ID index, CAN_CHANNEL channel, CAN_CHANNEL_EVENT flags ) PLIB_CAN_ChannelEventGet Function Returns a value representing the event status of a CAN channel. File plib_can.h Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 340 C CAN_CHANNEL_EVENT PLIB_CAN_ChannelEventGet(CAN_MODULE_ID index, CAN_CHANNEL channel); Returns Returns a value that can be logically ANDed with a CAN_CHANNEL_EVENT type to check if specific CAN channel events are active. Description This function returns a value representing the event status of a CAN channel. The return value can be logically ANDed with CAN_CHANNEL_EVENT type to check for a specific event(s). Channels events are affected regardless of whether the event itself is enabled or disabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelEvent in your application to determine whether this feature is available. Preconditions None. Example // Check if Receive Channel 2 of CAN_ID_1 module // is not empty or if its full. CAN_CHANNEL_EVENT channelEvent; channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_1,CAN_CHANNEL2); if((channelEvent & (CAN_RX_CHANNEL_NOT_EMPTY | CAN_RX_CHANNEL_FULL)) != 0) { // This means that either Receive Channel 2 is not empty // or the Channel is full. } // Check if Transmit Channel 3 of CAN_ID_2 module // has any active events channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_2, CAN_CHANNEL3); if((channelEvent & CAN_TX_CHANNEL_ANY_EVENT) != 0) { // This means that some event is active } // Check if Transmit Channel 6 of CAN_ID_2 module is not full channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_2, CAN_CHANNEL6); if((channelEvent & CAN_TX_CHANNEL_NOT_FULL) != 0) { // This means the Channel is not full. } Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel Function CAN_CHANNEL_EVENT PLIB_CAN_ChannelEventGet ( CAN_MODULE_ID index, CAN_CHANNEL channel ) Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 341 PLIB_CAN_PendingEventsGet Function Returns a value representing the highest priority active event in the module. File plib_can.h C CAN_EVENT_CODE PLIB_CAN_PendingEventsGet(CAN_MODULE_ID index); Returns Returns a CAN_EVENT_CODE type representing the highest priority active event in the module. Description This function returns a value representing the highest priority active event in the module. The return value is a CAN_EVENT_CODE type. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPendingEventsGet in your application to determine whether this feature is available. Preconditions None. Example // Implement a switch to check and process // any active CAN module events. CAN_EVENT_CODE eventCode; eventCode = PLIB_CAN_PendingEventsGet(CAN_ID_1); switch(eventCode) { case CAN_NO_EVENT: // Procedure to handle no CAN events break; case CAN_WAKEUP_EVENT: // Procedure to handle device wake-up // on CAN bus activity event break; default: break; } Parameters Parameters Description index Identifies the desired CAN module Function CAN_EVENT_CODE PLIB_CAN_PendingEventsGet ( CAN_MODULE_ID index ) f) Message Transmit Functions PLIB_CAN_PendingTransmissionsAbort Function Aborts any pending transmit operations. File plib_can.h Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 342 C void PLIB_CAN_PendingTransmissionsAbort(CAN_MODULE_ID index, CAN_CHANNEL channel); Returns None. Description This function aborts any pending transmit operations. Any messages that are yet to be transmitted will not be transmitted. The messages will still be present in the respective channel. Any message that is in the process of being transmitted will be transmitted completely. Either one channel or all channels can be specified. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPendingTransmissionsAbort in your application to determine whether this feature is available. Preconditions None. Example // Abort any pending transmissions on CAN_ID_1 Channel 4 and // Channel 5. PLIB_CAN_PendingTransmissionsAbort(CAN_ID_1, CAN_CHANNEL4); PLIB_CAN_PendingTransmissionsAbort(CAN_ID_1, CAN_CHANNEL5); Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel. By specifying CAN_ALL_CHANNELS, transmission on all transmit channels will be aborted. Function void PLIB_CAN_PendingTransmissionsAbort ( CAN_MODULE_ID index, CAN_CHANNEL channel ) PLIB_CAN_TransmissionIsAborted Function Returns 'true' if the transmit abort operation is complete. File plib_can.h C bool PLIB_CAN_TransmissionIsAborted(CAN_MODULE_ID index, CAN_CHANNEL channel); Returns • true - If channel = CAN_ALL_CHANNELS, Transmit Abort is complete. If channel = CAN_CHANNELx, Transmit Abort was successful. • false - If channel = CAN_ALL_CHANNELS, Transmit Abort is in progress. If channel = CAN_CHANNELx, Transmit Abort was not successful. Description This function returns 'true' if the transmit abort operation is complete. Either individual channels can be specified or all channels can be specified. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmissionIsAborted in your application to determine whether this feature is available. Preconditions None. Example // Abort any pending transmissions on CAN_ID_1 Channel 4 and // check if the current message transmission was aborted. PLIB_CAN_PendingTransmissionsAbort(CAN_ID_1, CAN_CHANNEL4); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 343 if(PLIB_CAN_TransmissionIsAborted(CAN_ID_1, CAN_CHANNEL4) == false) { // The message was not aborted. } else { // The message was aborted. } Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel. By specifying CAN_ALL_CHANNELS the status of transmit abort on all transmit channels will be returned. Function bool PLIB_CAN_TransmissionIsAborted ( CAN_MODULE_ID index, CAN_CHANNEL channel ) PLIB_CAN_TransmitBufferGet Function Returns a pointer to an empty transmit buffer. File plib_can.h C CAN_TX_MSG_BUFFER * PLIB_CAN_TransmitBufferGet(CAN_MODULE_ID index, CAN_CHANNEL channel); Returns Returns a CAN_TX_MSG_BUFFER type pointer to an empty message buffer in the Transmit channel. Returns NULL if the channel is full and there aren't any empty message buffers. Description This function returns a pointer to an empty transmit buffer. The routine will return a NULL pointer if there aren't any empty transmit buffers. In such a case, the application should flush the channel and wait until the transmit channel has at least one empty buffer. In order to function correctly, it is essential that the PLIB_CAN_ChannelUpdate function is called in the proper sequence for the PLIB_CAN_TransmitBufferGet function to return a pointer to an empty buffer. Remarks Calling the PLIB_CAN_TransmitBufferGet function on a channel that has not been updated after a message was written to the channel, will cause the function to return a pointer to the written message in case of transmit buffer FIFO. Therefore, a non-transmitted message could get overwritten. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmitBufferGet in your application to determine whether this feature is available. Preconditions PLIB_CAN_MemoryBufferAssign must be called if the 'transmit buffer' should be in the device RAM. It is not required if the 'transmit buffer' is in SFR space. Example // Transmit a message through CAN_ID_1 Channel 4 CAN_TX_MSG_BUFFER * msgBuffer; msgBuffer = PLIB_CAN_TransmitBufferGet(CAN_ID_1, CAN_CHANNEL4); if(msgBuffer != NULL) { // Load the message here } else { // No space in the channel // wait until a message Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 344 // buffer is free. while((PLIB_CAN_ChannelEventGet(CAN_ID_1, CAN_CHANNEL4) & CAN_TX_CHANNEL_NOT_FULL) == 0); } Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel Function CAN_TX_MSG_BUFFER * PLIB_CAN_TransmitBufferGet( CAN_MODULE_ID index, CAN_CHANNEL channel ) PLIB_CAN_TransmitChannelFlush Function Causes all messages in the specified transmit channel to be transmitted. File plib_can.h C void PLIB_CAN_TransmitChannelFlush(CAN_MODULE_ID index, CAN_CHANNEL channel); Returns None. Description This function causes all messages in the specified transmit channel to be transmitted. All messages in the channel at the time of the flush operation will be transmitted. The transmit channel flush operation should preferably be called immediately after the PLIB_CAN_ChannelUpdate function. This will ensure that messages are transmitted promptly. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmitChannelFlush in your application to determine whether this feature is available. Preconditions None. Example // Flush CAN_ID_1 Transmit Channel 4. PLIB_CAN_TransmitChannelFlush(CAN_ID_1, CAN_CHANNEL4); Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel Function void PLIB_CAN_TransmitChannelFlush ( CAN_MODULE_ID index, CAN_CHANNEL channel ) PLIB_CAN_TransmitChannelStatusGet Function Returns the condition of the transmit channel. File plib_can.h C CAN_TX_CHANNEL_STATUS PLIB_CAN_TransmitChannelStatusGet(CAN_MODULE_ID index, CAN_CHANNEL channel); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 345 Returns Returns a status word that can be logically ANDed with the CAN_TX_CHANNEL_STATUS type to check whether a condition exists. Description This function returns the condition of the transmit channel. The return value can be logically ANDed with CAN_TX_CHANNEL_STATUS type values. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmitChannelStatus in your application to determine whether this feature is available. Preconditions None. Example // Check if CAN_ID_1 Transmit Channel 4 // is still transmitting CAN_TX_CHANNEL_STATUS status; status = PLIB_CAN_TransmitChannelStatusGet(CAN_ID_1, CAN_CHANNEL4); if((status & CAN_TX_CHANNEL_TRANSMITTING) != 0) { // This means that channel is still // transmitting. } // Check if CAN_ID_2 Transmit Channel 5 has lost arbitration // or other Transmit errors. status = PLIB_CAN_TransmitChannelStatusGet(CAN_ID_2, CAN_CHANNEL5); if((status & (CAN_TX_CHANNEL_ARBITRATION_LOST | CAN_TX_CHANNEL_ERROR)) != 0) { // This means that the Transmit channel has either // lost arbitration or a Transmit error has occurred. } Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel Function CAN_TX_CHANNEL_STATUS PLIB_CAN_TransmitChannelStatusGet( CAN_MODULE_ID index, CAN_CHANNEL channel ) PLIB_CAN_TransmitErrorCountGet Function Returns the CAN transmit error count File plib_can.h C int PLIB_CAN_TransmitErrorCountGet(CAN_MODULE_ID index); Returns Returns the CAN transmit error count. Description This function returns the CAN transmit error count. Refer to CAN 2.0B specification for more details on the CAN transmit error count and its Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 346 significance. Remarks There are multiple bus conditions, which could cause the transmit error count to increase. Please refer to the CAN 2.0B specification for details. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmitErrorCountGet in your application to determine whether this feature is available. Preconditions None. Example // Check if the CAN_ID_1 Transmit error count is more than 200 int errorCount; errorCount = PLIB_CAN_TransmitErrorCountGet(CAN_ID_1); if(errorCount > 200) { // This error count is high. // Do some diagnostics. } Parameters Parameters Description index Identifies the desired CAN module Function int PLIB_CAN_TransmitErrorCountGet( CAN_MODULE_ID index ) g) Message Receive Functions PLIB_CAN_ReceivedMessageGet Function Returns a pointer to a message to be read from the CAN channel. File plib_can.h C CAN_RX_MSG_BUFFER * PLIB_CAN_ReceivedMessageGet(CAN_MODULE_ID index, CAN_CHANNEL channel); Returns Returns a pointer to a message to be read from the CAN channel; returns a CAN_RX_MSG_BUFFER type pointer to a received CAN message. If the receive channel is a full CAN message receive channel, the caller should use the msgSID, msgEID and data members of the CAN_RX_MSG_BUFFER data structure to access the received CAN message. If the receive channel is a data-only channel, the message will only contain 8 payload data bytes (even if the message was placed on the bus with less than 8 bytes). The caller in this case should use the dataOnlyMsgData member of the CAN_RX_MSG_BUFFER data structure to read the data contained in the received CAN message. Description This function returns a CAN_RX_MSG_BUFFER pointer to a message to be read from the CAN channel. The PLIB_CAN_ChannelUpdate routine should be called after the received message has been processed. Remarks The CAN receive channel is configured as a full CAN message receive channel or a data-Only channel while configuring the channel using the PLIB_CAN_ChannelForReceiveSet function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsReceivedMessageGet in your application to determine whether this feature is available. Preconditions None. Example // Read a message from the CAN_ID_1 Channel 8 Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 347 // which is configured as full CAN message // receive channel. CAN_RX_MSG_BUFFER * receivedMsg; receivedMsg = (CAN_RX_MSG_BUFFER *)PLIB_CAN_ReceivedMessageGet(CAN_ID_1, CAN_CHANNEL8); if(receivedMsg != NULL) { // rxMsg is pointing to // a CAN message. Process // the message and then update // the CAN channel. PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL8); } // Read a message from the CAN_ID_2 Channel 9 // which is configured as data only message // receive channel. Access the message // as bytes; CAN_RX_MSG_BUFFER * rxMsg; rxMsg = PLIB_CAN_ReceivedMessageGet(CAN_ID_2, CAN_CHANNEL9); if(rxMsg != NULL) { // rxMsg is pointing to // a CAN message. Process // the message and then update // the CAN channel. // rxMsg->dataOnlyMsgData[0] is the first byte of message // data payload. rxMsg->dataOnlyMsgData[0] is the second // byte of message data payload and so on. PLIB_CAN_ChannelUpdate(CAN_ID_2, CAN_CHANNEL9); } Parameters Parameters Description index Identifies the desired CAN module. channel Identifies the desired CAN Receive channel. Function CAN_RX_MSG_BUFFER * PLIB_CAN_ReceivedMessageGet( CAN_MODULE_ID index, CAN_CHANNEL channel ) h) Message Filtering Functions PLIB_CAN_FilterConfigure Function Configures a CAN message acceptance filter. File plib_can.h C void PLIB_CAN_FilterConfigure(CAN_MODULE_ID index, CAN_FILTER filter, uint32_t id, CAN_ID_TYPE filterType); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 348 Returns None. Description This function configures a CAN message acceptance filter. The ID field of the incoming message must match the filter bits for the CAN module to accept the message. A filter can be a EID type filter, which filters EID messages or a SID filter, which in turn filters SID messages. The filter mask bits (configured using the PLIB_CAN_FilterMaskConfigure function) additionally allow specified message ID bits to be ignored in the filtering process. Remarks A CAN message acceptance filter can be configured in Normal operation mode. The filter must be disabled before this is done. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterConfigure in your application to determine whether this feature is available. Preconditions None. Example // Configure CAN_ID_2 filter 4 to accept standard ID messages // with SID 0x100 PLIB_CAN_FilterConfigure(CAN_ID_2, CAN_FILTER4, 0x100, CAN_SID); Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN receive filter id A value in the range 0x0 to 0x7FF for SID filter type or 0x0 to 0x1FFFFFFF for EID filter type. filterType Specifies the type of filter • CAN_EID - Filter is an extended ID message filter • CAN_SID - Filter is an standard ID message filter Function void PLIB_CAN_FilterConfigure ( CAN_MODULE_ID index, CAN_FILTER filter, uint32_t id, CAN_ID_TYPE filterType ) PLIB_CAN_FilterDisable Function Disables a CAN message acceptance filter. File plib_can.h C void PLIB_CAN_FilterDisable(CAN_MODULE_ID index, CAN_FILTER filter); Returns None. Description This function disables a CAN message acceptance filter. At least one filter must be enabled for the CAN module to receive messages. A receive channel associated with a filter will not receive messages unless the filter is enabled. After a filter is disabled, the PLIB_CAN_FilterIsDisabled function should be called to verify that the filter is disabled. A filter must be disabled before it can be configured. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterEnable in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 349 Example // Enable filter 6 of CAN_ID_2 PLIB_CAN_FilterDisable (CAN_ID_2, CAN_FILTER6); while(PLIB_CAN_FilterIsDisabled(CAN_ID_1, CAN_FILTER4)); Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN Message Acceptance Filter Function void PLIB_CAN_FilterDisable( CAN_MODULE_ID index, CAN_FILTER filter ) PLIB_CAN_FilterEnable Function Enables a CAN message acceptance filter. File plib_can.h C void PLIB_CAN_FilterEnable(CAN_MODULE_ID index, CAN_FILTER filter); Returns None. Description This function enables a CAN message acceptance filter. At least one filter must be enabled for the CAN module to receive messages. A receive channel associated with a filter will not receive messages unless the filter is enabled. After a filter is disabled, the PLIB_CAN_FilterIsDisabled function should be called to verify that the filter is disabled. A filter must be disabled before it can be configured. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterEnable in your application to determine whether this feature is available. Preconditions None. Example // Enable filter 6 of CAN_ID_2 PLIB_CAN_FilterEnable (CAN_ID_2, CAN_FILTER6); while(!PLIB_CAN_FilterIsDisabled(CAN_ID_1, CAN_FILTER4)); Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN message acceptance filter Function void PLIB_CAN_FilterEnable( CAN_MODULE_ID index, CAN_FILTER filter ) PLIB_CAN_FilterIsDisabled Function Returns 'true' if the specified filter is disabled. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 350 File plib_can.h C bool PLIB_CAN_FilterIsDisabled(CAN_MODULE_ID index, CAN_FILTER filter); Returns • true = The filter is disabled • false = The filter is enabled Description Returns 'true' if the specified filter is disabled. This function should be called to check if the filter is disabled before calling the PLIB_CAN_FilterConfigure function and PLIB_CAN_FilterToChannelLink function. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterEnable in your application to determine whether this feature is available. Preconditions None. Example // Disable CAN_ID_1 filter 3 and wait until the filter is disabled. PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER3); while(PLIB_CAN_FilterIsDisabled(CAN_ID_1, CAN_FILTER3) == false); Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN filter Function bool PLIB_CAN_FilterIsDisabled( CAN_MODULE_ID index, CAN_FILTER filter ) PLIB_CAN_FilterMaskConfigure Function Configures a CAN filter mask. File plib_can.h C void PLIB_CAN_FilterMaskConfigure(CAN_MODULE_ID index, CAN_FILTER_MASK mask, uint32_t maskBits, CAN_ID_TYPE idType, CAN_FILTER_MASK_TYPE mide); Returns None. Description This function configures a CAN filter mask. The mask bits determine which message ID bits are ignored and compared during the filtering process. Remarks A mask bit value of zero essentially means that all messages with any ID are accepted. The mode and idType input parameters are still relevant in such a case. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterMaskConfigure in your application to determine whether this feature is available. Preconditions The CAN module should be in Configuration mode. This is achieved by using the PLIB_CAN_OperationModeSelect function. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 351 Example // Configure CAN_ID_1 Filter Mask 2 to accept // extended ID messages in the range 0x4F1DE8 - 0x4F1DEC. // On analyzing this address range it can be seen that only // the last two bits of the incoming CAN message should ignored. // Therefore the mask value should 0x1FFFFFFC. // This mask will be used with a extended ID filter. // Set the masking option to filter IDE type. PLIB_CAN_FilterMaskConfigure(CAN_ID_1, CAN_FILTER_MASK2, 0x1FFFFFFC, CAN_EID, CAN_FILTER_MASK_IDE_TYPE); Parameters Parameters Description index Identifies the desired CAN module mask Identifies the desired CAN receive filter mask. maskBits A value in the range 0x0 to 0x7FF for SID range or 0x0 to 0x1FFFFFFF for the EID range. Each set bit will mean that the corresponding bit in the filter will be compared to the corresponding bit in the message ID. A clear mask bit means the corresponding bit in the incoming message ID field will be ignored. idType Specifies the value range of maskBits parameter. • CAN_EID - Value range of maskBits parameter is 0x0 (ignore all 29 bits of the incoming message ID) to 0x1FFFFFFF (compare all 29 bits of the incoming message ID). • CAN_SID - Value range of maskBits parameter is 0x0 (ignore all 11 bits of the incoming message ID) to 0x7FF (compare all 11 bits of the incoming message ID). mide Specifies ID masking options • CAN_FILTER_MASK_IDE_TYPE - Masking will be performed by filter type only. If the filter is set up for SID messages, the mask will decline all incoming EID messages. If the filter is set up for EID messages, the mask will decline all incoming SID messages • CAN_FILTER_MASK_ANY_TYPE - Masking will be performed regardless of the incoming message ID type. The message will be accepted on a Filter and Message SID match or a filter and message SID/EID match. Function void PLIB_CAN_FilterMaskConfigure( CAN_MODULE_ID index, CAN_FILTER_MASK mask, uint32_t maskBits, CAN_ID_TYPE idType, CAN_FILTER_MASK_TYPE mide ) PLIB_CAN_FilterToChannelLink Function Links a filter to a channel. File plib_can.h C void PLIB_CAN_FilterToChannelLink(CAN_MODULE_ID index, CAN_FILTER filter, CAN_FILTER_MASK mask, CAN_CHANNEL channel); Returns None. Description This function links a filter to a channel. A filter is typically linked to a receive channel. This allows the channel to receive messages accepted by the filter. A filter can also be linked to a transmit channel if the transmit channel is configured for remote request transmit. In this case, a message accepted by the filter will automatically cause the linked transmit channel to transmit CAN messages that are buffered in the channel. Note that a filter should be enabled using the PLIB_CAN_FilterEnable function after the filter has been linked to the desired channel. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterToChannelLink in your application to determine whether this feature is available. Preconditions Filter should have been disabled using the PLIB_CAN_FilterDisable function. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 352 Example // Configure CAN_ID_1 filter 3 to accept extended ID messages // with EID 0x1D400 and link the filter to CAN_ID_1 Channel 5. // Note the sequence in which the steps are performed. // Disable the filter and check if its disabled. // Configure the filter. Link it to the Channel and then // enable the filter. PLIB_CAN_FilterDisable(CAN_ID_1, CAN_FILTER3); while(PLIB_CAN_FilterIsDisabled(CAN_ID_1, CAN_FILTER3) == false); PLIB_CAN_FilterConfigure(CAN_ID_1, CAN_FILTER3, 0x1D400, CAN_EID); PLIB_CAN_FilterToChannelLink(CAN_ID_1, CAN_FILTER3, CAN_FILTER_MASK0, CAN_CHANNEL5); PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER3); Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN Filter mask Identifies the mask to be used with this filter channel Identifies the channel to be linked to this filter. If a transmit channel is linked, the transmit channel should have its remote transmit request feature enabled. Function void PLIB_CAN_FilterToChannelLink( CAN_MODULE_ID index, CAN_FILTER filter, CAN_FILTER_MASK mask, CAN_CHANNEL channel ) PLIB_CAN_LatestFilterMatchGet Function Returns the index of the filter that accepted the latest message. File plib_can.h C CAN_FILTER PLIB_CAN_LatestFilterMatchGet(CAN_MODULE_ID index); Returns Index of the filter that accepted the latest message Description This function returns the index of the filter that accepted the latest message. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsLatestFilterMatchGet in your application to determine whether this feature is available. Preconditions None. Example // Check if CAN_ID_2 module Receive Buffer event // is active and if so check which filter // accepted the message. CAN_FILTER filter; if((PLIB_CAN_ModuleEventGet(CAN_ID_1) & CAN_RX_EVENT) != 0) { Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 353 // Check which filter accepted the message filter = PLIB_CAN_LatestFilterMatchGet(CAN_ID_1); } Parameters Parameters Description index Identifies the desired CAN module Function CAN_FILTER PLIB_CAN_LatestFilterMatchGet( CAN_MODULE_ID index ) i) Error State Tracking Functions PLIB_CAN_ReceiveErrorCountGet Function Returns the CAN receive error count. File plib_can.h C int PLIB_CAN_ReceiveErrorCountGet(CAN_MODULE_ID index); Returns Returns the CAN receive error count. Description This function returns the CAN receive error count. Refer to the CAN 2.0B specification for more details on the CAN receive error count and its significance. Remarks There are multiple bus conditions, which could cause the receive error count to increase. Please refer to the CAN 2.0b specification for details. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsReceiveErrorCount in your application to determine whether this feature is available. Preconditions None. Example // Check if CAN_ID_1 Receive error count is more than 200. int errCount; errCount = PLIB_CAN_ReceiveErrorCountGet(CAN_ID_1); if(errCount > 200) { // This error count is high. // Do some diagnostics. } Parameters Parameters Description index Identifies the desired CAN module Function int PLIB_CAN_ReceiveErrorCountGet( CAN_MODULE_ID index ) PLIB_CAN_ErrorStateGet Function Returns the CAN error status word. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 354 File plib_can.h C CAN_ERROR_STATE PLIB_CAN_ErrorStateGet(CAN_MODULE_ID index); Returns Returns the CAN_ERROR_STATE word, which can be logically ANDed with the desired CAN_ERROR_STATE member to check whether the CAN module is in a specific error state. Description This function returns the CAN error status word. The return word can be logically ANDed with the desired CAN_ERROR_STATE member to check if the CAN module is in a specific error state. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsErrorState in your application to determine whether this feature is available. Preconditions None. Example // Check if CAN_ID_1 is in the Transmit or Receive warning state. CAN_ERROR_STATE errorState; errorState = PLIB_CAN_ErrorStateGet(CAN_ID_1); if((errorState & CAN_TX_RX_WARNING_STATE) != 0) { // CAN_ID_1 is in either Transmit or Receive warning state. } // Check if CAN_ID_2 is in the Receive Bus Passive or Transmit Bus passive // state. errorState = PLIB_CAN_ErrorStateGet(CAN_ID_2); if((errorState & (CAN_TX_BUS_PASSIVE_STATE | CAN_RX_BUS_PASSIVE_STATE)) != 0) { // This means that the CAN module is in Transmit Bus Passive // or Receive Bus Passive state. } Parameters Parameters Description index Identifies the desired CAN module Function CAN_ERROR_STATE PLIB_CAN_ErrorStateGet( CAN_MODULE_ID index ) j) Information Functions PLIB_CAN_TotalChannelsGet Function Returns the total number of CAN channels per CAN module. File plib_can.h C char PLIB_CAN_TotalChannelsGet(CAN_MODULE_ID index); Returns The total number of CAN channels per CAN module. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 355 Description This function returns the total number of CAN channels per CAN module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleInfo in your application to determine whether this feature is available. Preconditions None. Example char totalChannels; totalChannels = PLIB_CAN_TotalChannelsGet(CAN_ID_1); Parameters Parameters Description index Identifies the desired CAN module Function char PLIB_CAN_TotalChannelsGet( CAN_MODULE_ID index ) PLIB_CAN_TotalFiltersGet Function Returns the total number of CAN Filters per CAN module. File plib_can.h C char PLIB_CAN_TotalFiltersGet(CAN_MODULE_ID index); Returns The total number of CAN Filters per CAN module. Description This function returns the total number of CAN filters per CAN module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleInfo in your application to determine whether this feature is available. Preconditions None. Example char totalFilters; totalFilters = PLIB_CAN_TotalFiltersGet(CAN_ID_1); Parameters Parameters Description index Identifies the desired CAN module Function char PLIB_CAN_TotalFiltersGet( CAN_MODULE_ID index ) PLIB_CAN_TotalMasksGet Function Returns the total number of CAN masks per CAN module. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 356 File plib_can.h C char PLIB_CAN_TotalMasksGet(CAN_MODULE_ID index); Returns The total number of CAN Masks per CAN module. Description This function returns the total number of CAN masks per CAN module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleInfo in your application to determine whether this feature is available. Preconditions None. Example char totalMasks; totalMasks = PLIB_CAN_TotalMasksGet(CAN_ID_1); Parameters Parameters Description index Identifies the desired CAN module Function char PLIB_CAN_TotalMasksGet( CAN_MODULE_ID index ) k) Feature Existence Functions PLIB_CAN_ExistsActiveStatus Function Identifies whether the ActiveStatus feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsActiveStatus(CAN_MODULE_ID index); Returns • true = The ActiveStatus feature is supported on the device • false = The ActiveStatus feature is not supported on the device Description This function identifies whether the ActiveStatus feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_IsActive Remarks None. Preconditions None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 357 Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsActiveStatus( CAN_MODULE_ID index ) PLIB_CAN_ExistsAllChannelEvents Function Identifies whether the AllChannelEvents feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsAllChannelEvents(CAN_MODULE_ID index); Returns • true = The AllChannelEvents feature is supported on the device • false = The AllChannelEvents feature is not supported on the device Description This function identifies whether the AllChannelEvents feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_AllChannelEventsGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsAllChannelEvents( CAN_MODULE_ID index ) PLIB_CAN_ExistsAllChannelOverflow Function Identifies whether the AllChannelOverflow feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsAllChannelOverflow(CAN_MODULE_ID index); Returns • true = The AllChannelOverflow feature is supported on the device • false = The AllChannelOverflow feature is not supported on the device Description This function identifies whether the AllChannelOverflow feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_AllChannelOverflowStatusGet Remarks None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 358 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsAllChannelOverflow( CAN_MODULE_ID index ) PLIB_CAN_ExistsBusActivityWakeup Function Identifies whether the BusActivityWakeup feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsBusActivityWakeup(CAN_MODULE_ID index); Returns • true = The BusActivityWakeup feature is supported on the device • false = The BusActivityWakeup feature is not supported on the device Description This function identifies whether the BusActivityWakeup feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_BusActivityWakeupEnable • PLIB_CAN_BusActivityWakeupDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsBusActivityWakeup( CAN_MODULE_ID index ) PLIB_CAN_ExistsBusLine3TimesSampling Function Identifies whether the BusLine3TimesSampling feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsBusLine3TimesSampling(CAN_MODULE_ID index); Returns • true = The BusLine3TimesSampling feature is supported on the device • false = The BusLine3TimesSampling feature is not supported on the device Description This function identifies whether the BusLine3TimesSampling feature is available on the CAN module. When this function returns true, these functions are supported on the device: Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 359 • PLIB_CAN_BusLine3TimesSamplingEnable • PLIB_CAN_BusLine3TimesSamplingDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsBusLine3TimesSampling( CAN_MODULE_ID index ) PLIB_CAN_ExistsChannelEvent Function Identifies whether the ChannelEventGet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsChannelEvent(CAN_MODULE_ID index); Returns • true = The ChannelEventGet feature is supported on the device • false = The ChannelEventGet feature is not supported on the device Description This function identifies whether the ChannelEventGet feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ChannelEventGet • PLIB_CAN_ChannelEventClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsChannelEvent( CAN_MODULE_ID index ) PLIB_CAN_ExistsChannelEventEnable Function Identifies whether the ChannelEventEnable feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsChannelEventEnable(CAN_MODULE_ID index); Returns • true = The ChannelEventEnable feature is supported on the device Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 360 • false = The ChannelEventEnable feature is not supported on the device Description This function identifies whether the ChannelEventEnable feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ChannelEventEnable • PLIB_CAN_ChannelEventDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsChannelEventEnable( CAN_MODULE_ID index ) PLIB_CAN_ExistsChannelForReceiveSet Function Identifies whether the ChannelForReceiveSet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsChannelForReceiveSet(CAN_MODULE_ID index); Returns • true = The ChannelForReceiveSet feature is supported on the device • false = The ChannelForReceiveSet feature is not supported on the device Description This function identifies whether the ChannelForReceiveSet feature is available on the CAN module. When this function returns true, this function is are supported on the device: • PLIB_CAN_ChannelForReceiveSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsChannelForReceiveSet( CAN_MODULE_ID index ) PLIB_CAN_ExistsChannelForTransmitSet Function Identifies whether the ChannelForTransmitSet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsChannelForTransmitSet(CAN_MODULE_ID index); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 361 Returns • true = The ChannelForTransmitSet feature is supported on the device • false = The ChannelForTransmitSet feature is not supported on the device Description This function identifies whether the ChannelForTransmitSet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ChannelForTransmitSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsChannelForTransmitSet( CAN_MODULE_ID index ) PLIB_CAN_ExistsChannelReset Function Identifies whether the ChannelReset feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsChannelReset(CAN_MODULE_ID index); Returns • true = The ChannelReset feature is supported on the device • false = The ChannelReset feature is not supported on the device Description This function identifies whether the ChannelReset feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ChannelReset • PLIB_CAN_ChannelResetIsComplete Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsChannelReset( CAN_MODULE_ID index ) PLIB_CAN_ExistsChannelUpdate Function Identifies whether the ChannelUpdate feature exists on the CAN module. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 362 File plib_can.h C bool PLIB_CAN_ExistsChannelUpdate(CAN_MODULE_ID index); Returns • true = The ChannelUpdate feature is supported on the device • false = The ChannelUpdate feature is not supported on the device Description This function identifies whether the ChannelUpdate feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ChannelUpdate Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsChannelUpdate( CAN_MODULE_ID index ) PLIB_CAN_ExistsDeviceNet Function Identifies whether the DeviceNet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsDeviceNet(CAN_MODULE_ID index); Returns • true = The DeviceNet feature is supported on the device • false = The DeviceNet feature is not supported on the device Description This function identifies whether the DeviceNet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_DeviceNetConfigure Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsDeviceNet( CAN_MODULE_ID index ) Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 363 PLIB_CAN_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsEnableControl(CAN_MODULE_ID index); Returns • true = The EnableControl feature is supported on the device • false = The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_Enable • PLIB_CAN_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsEnableControl( CAN_MODULE_ID index ) PLIB_CAN_ExistsErrorState Function Identifies whether the ErrorStateGet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsErrorState(CAN_MODULE_ID index); Returns • true = The ErrorStateGet feature is supported on the device • false = The ErrorStateGet feature is not supported on the device Description This function identifies whether the ErrorStateGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ErrorStateGet Remarks None. Preconditions None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 364 Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsErrorState( CAN_MODULE_ID index ) PLIB_CAN_ExistsFilterConfigure Function Identifies whether the FilterConfigure feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsFilterConfigure(CAN_MODULE_ID index); Returns • true = The FilterConfigure feature is supported on the device • false = The FilterConfigure feature is not supported on the device Description This function identifies whether the FilterConfigure feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_FilterConfigure Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsFilterConfigure( CAN_MODULE_ID index ) PLIB_CAN_ExistsFilterEnable Function Identifies whether the FilterEnable feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsFilterEnable(CAN_MODULE_ID index); Returns • true = The FilterEnable feature is supported on the device • false = The FilterEnable feature is not supported on the device Description This function identifies whether the FilterEnable feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_FilterEnable • PLIB_CAN_FilterDisable • PLIB_CAN_FilterIsDisabled Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 365 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsFilterEnable( CAN_MODULE_ID index ) PLIB_CAN_ExistsFilterMaskConfigure Function Identifies whether the FilterMaskConfigure feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsFilterMaskConfigure(CAN_MODULE_ID index); Returns • true = The FilterMaskConfigure feature is supported on the device • false = The FilterMaskConfigure feature is not supported on the device Description This function identifies whether the FilterMaskConfigure feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_FilterMaskConfigure Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsFilterMaskConfigure( CAN_MODULE_ID index ) PLIB_CAN_ExistsFilterToChannelLink Function Identifies whether the FilterToChannelLink feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsFilterToChannelLink(CAN_MODULE_ID index); Returns • true = The FilterToChannelLink feature is supported on the device • false = The FilterToChannelLink feature is not supported on the device Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 366 Description This function identifies whether the FilterToChannelLink feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_FilterToChannelLink Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsFilterToChannelLink( CAN_MODULE_ID index ) PLIB_CAN_ExistsLatestFilterMatchGet Function Identifies whether the LatestFilterMatchGet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsLatestFilterMatchGet(CAN_MODULE_ID index); Returns • true = The LatestFilterMatchGet feature is supported on the device • false = The LatestFilterMatchGet feature is not supported on the device Description This function identifies whether the LatestFilterMatchGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_LatestFilterMatchGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsLatestFilterMatchGet( CAN_MODULE_ID index ) PLIB_CAN_ExistsMemoryBufferAssign Function Identifies whether the MemoryBufferAssign feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsMemoryBufferAssign(CAN_MODULE_ID index); Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 367 Returns • true = The MemoryBufferAssign feature is supported on the device • false = The MemoryBufferAssign feature is not supported on the device Description This function identifies whether the MemoryBufferAssign feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_MemoryBufferAssign Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsMemoryBufferAssign( CAN_MODULE_ID index ) PLIB_CAN_ExistsModuleEventClear Function Identifies whether the ModuleEvents feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsModuleEventClear(CAN_MODULE_ID index); Returns • true = The ModuleEvents feature is supported on the device • false = The ModuleEvents feature is not supported on the device Description This function identifies whether the ModuleEvents feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ModuleEventClear • PLIB_CAN_ModuleEventGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsModuleEventClear( CAN_MODULE_ID index ) PLIB_CAN_ExistsModuleEventEnable Function Identifies whether the ModuleEventEnable feature exists on the CAN module. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 368 File plib_can.h C bool PLIB_CAN_ExistsModuleEventEnable(CAN_MODULE_ID index); Returns • true = The ModuleEventEnable feature is supported on the device • false = The ModuleEventEnable feature is not supported on the device Description This function identifies whether the ModuleEventEnable feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ModuleEventEnable • PLIB_CAN_ModuleEventDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsModuleEventEnable( CAN_MODULE_ID index ) PLIB_CAN_ExistsModuleInfo Function Identifies whether the ModuleInformation feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsModuleInfo(CAN_MODULE_ID index); Returns • true = The ModuleInformation feature is supported on the device • false = The ModuleInformation feature is not supported on the device Description This function identifies whether the ModuleInformation feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_TotalChannelsGet • PLIB_CAN_TotalFiltersGet • PLIB_CAN_TotalMasksGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 369 Function PLIB_CAN_ExistsModuleInfo( CAN_MODULE_ID index ) PLIB_CAN_ExistsOperationModeRead Function Identifies whether the OperationModeRead feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsOperationModeRead(CAN_MODULE_ID index); Returns • true = The OperationModeRead feature is supported on the device • false = The OperationModeRead feature is not supported on the device Description This function identifies whether the OperationModeRead feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_OperationModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsOperationModeRead( CAN_MODULE_ID index ) PLIB_CAN_ExistsOperationModeWrite Function Identifies whether the OperationModeSet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsOperationModeWrite(CAN_MODULE_ID index); Returns • true = The OperationModeSet feature is supported on the device • false = The OperationModeSet feature is not supported on the device Description This function identifies whether the OperationModeSet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_OperationModeSelect Remarks None. Preconditions None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 370 Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsOperationModeWrite( CAN_MODULE_ID index ) PLIB_CAN_ExistsPendingEventsGet Function Identifies whether the PendingEventsGet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsPendingEventsGet(CAN_MODULE_ID index); Returns • true = The PendingEventsGet feature is supported on the device • false = The PendingEventsGet feature is not supported on the device Description This function identifies whether the PendingEventsGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_PendingEventsGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsPendingEventsGet( CAN_MODULE_ID index ) PLIB_CAN_ExistsPendingTransmissionsAbort Function Identifies whether the PendingTransmissionsAbort feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsPendingTransmissionsAbort(CAN_MODULE_ID index); Returns • true = The PendingTransmissionsAbort feature is supported on the device • false = The PendingTransmissionsAbort feature is not supported on the device Description This function identifies whether the PendingTransmissionsAbort feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_PendingTransmissionsAbort Remarks None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 371 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsPendingTransmissionsAbort( CAN_MODULE_ID index ) PLIB_CAN_ExistsReceivedMessageGet Function Identifies whether the ReceivedMessageGet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsReceivedMessageGet(CAN_MODULE_ID index); Returns • true = The ReceivedMessageGet feature is supported on the device • false = The ReceivedMessageGet feature is not supported on the device Description This function identifies whether the ReceivedMessageGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ReceivedMessageGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsReceivedMessageGet( CAN_MODULE_ID index ) PLIB_CAN_ExistsReceiveErrorCount Function Identifies whether the ReceiveErrorCount feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsReceiveErrorCount(CAN_MODULE_ID index); Returns • true = The ReceiveErrorCount feature is supported on the device • false = The ReceiveErrorCount feature is not supported on the device Description This function identifies whether the ReceiveErrorCount feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ReceiveErrorCountGet Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 372 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsReceiveErrorCount( CAN_MODULE_ID index ) PLIB_CAN_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsStopInIdle(CAN_MODULE_ID index); Returns • true = The StopInIdle feature is supported on the device • false = The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_StopInIdleEnable • PLIB_CAN_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsStopInIdle( CAN_MODULE_ID index ) PLIB_CAN_ExistsTimeStampEnable Function Identifies whether the TimeStampEnable feature exists on the CAN module File plib_can.h C bool PLIB_CAN_ExistsTimeStampEnable(CAN_MODULE_ID index); Returns • true = The TimeStampEnable feature is supported on the device • false = The TimeStampEnable feature is not supported on the device Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 373 Description This function identifies whether the TimeStampEnable feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_TimeStampEnable • PLIB_CAN_TimeStampDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsTimeStampEnable( CAN_MODULE_ID index ) PLIB_CAN_ExistsTimeStampValue Function Identifies whether the TimeStampValue feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsTimeStampValue(CAN_MODULE_ID index); Returns • true = The TimeStampValue feature is supported on the device • false = The TimeStampValue feature is not supported on the device Description This function identifies whether the TimeStampValue feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_TimeStampValueSet • PLIB_CAN_TimeStampValueGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsTimeStampValue( CAN_MODULE_ID index ) PLIB_CAN_ExistsTransmissionIsAborted Function Identifies whether the TransmissionAbortStatus feature exists on the CAN module. File plib_can.h Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 374 C bool PLIB_CAN_ExistsTransmissionIsAborted(CAN_MODULE_ID index); Returns • true = The TransmissionAbortStatus feature is supported on the device • false = The TransmissionAbortStatus feature is not supported on the device Description This function identifies whether the TransmissionAbortStatus feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmissionIsAborted Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsTransmissionIsAborted( CAN_MODULE_ID index ) PLIB_CAN_ExistsTransmitBufferGet Function Identifies whether the TransmitBufferGet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsTransmitBufferGet(CAN_MODULE_ID index); Returns • true = The TransmitBufferGet feature is supported on the device • false = The TransmitBufferGet feature is not supported on the device Description This function identifies whether the TransmitBufferGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmitBufferGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsTransmitBufferGet( CAN_MODULE_ID index ) PLIB_CAN_ExistsTransmitChannelFlush Function Identifies whether the TransmitChannelFlush feature exists on the CAN module. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 375 File plib_can.h C bool PLIB_CAN_ExistsTransmitChannelFlush(CAN_MODULE_ID index); Returns • true = The TransmitChannelFlush feature is supported on the device • false = The TransmitChannelFlush feature is not supported on the device Description This function identifies whether the TransmitChannelFlush feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmitChannelFlush Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsTransmitChannelFlush( CAN_MODULE_ID index ) PLIB_CAN_ExistsTransmitChannelStatus Function Identifies whether the TransmitChannelStatus feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsTransmitChannelStatus(CAN_MODULE_ID index); Returns • true = The TransmitChannelStatus feature is supported on the device • false = The TransmitChannelStatus feature is not supported on the device Description This function identifies whether the TransmitChannelStatus feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmitChannelStatusGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsTransmitChannelStatus( CAN_MODULE_ID index ) Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 376 PLIB_CAN_ExistsTransmitErrorCountGet Function Identifies whether the TransmitErrorCountGet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsTransmitErrorCountGet(CAN_MODULE_ID index); Returns • true = The TransmitErrorCountGet feature is supported on the device • false = The TransmitErrorCountGet feature is not supported on the device Description This function identifies whether the TransmitErrorCountGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmitErrorCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsTransmitErrorCountGet( CAN_MODULE_ID index ) PLIB_CAN_ExistsBaudRateGet Function Identifies whether the BaudRateGet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsBaudRateGet(CAN_MODULE_ID index); Returns • true = The BaudRateGet feature is supported on the device. • false = The BaudRateGet feature is not supported on the device. Description This function identifies whether the BaudRateGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_BaudRateGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 377 Function PLIB_CAN_ExistsBaudRateGet( CAN_MODULE_ID index ) PLIB_CAN_ExistsBaudRatePrescaleSetup Function Identifies whether the BaudRatePrescaleSetup feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsBaudRatePrescaleSetup(CAN_MODULE_ID index); Returns • true = The BaudRatePrescaleSetup feature is supported on the device. • false = The BaudRatePrescaleSetup feature is not supported on the device. Description This function identifies whether the BaudRatePrescaleSetup feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_BaudRatePrescaleSetup Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsBaudRatePrescaleSetup( CAN_MODULE_ID index ) PLIB_CAN_ExistsBitSamplePhaseSet Function Identifies whether the BitSamplePhaseSet feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsBitSamplePhaseSet(CAN_MODULE_ID index); Returns • true = The BitSamplePhaseSet feature is supported on the device. • false = The BitSamplePhaseSet feature is not supported on the device. Description This function identifies whether the BitSamplePhaseSet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_BitSamplePhaseSet Remarks None. Preconditions None. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 378 Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsBitSamplePhaseSet( CAN_MODULE_ID index ) PLIB_CAN_ExistsPrecalculatedBitRateSetup Function Identifies whether the PrecalculatedBitRateSetup feature exists on the CAN module. File plib_can.h C bool PLIB_CAN_ExistsPrecalculatedBitRateSetup(CAN_MODULE_ID index); Returns • true = The PrecalculatedBitRateSetup feature is supported on the device. • false = The PrecalculatedBitRateSetup feature is not supported on the device. Description This function identifies whether the PrecalculatedBitRateSetup feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_PrecalculatedBitRateSetup Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CAN_ExistsPrecalculatedBitRateSetup( CAN_MODULE_ID index ) l) Data Types and Constants CAN_CHANNEL Enumeration Identifies the supported CAN Channels. File plib_can_help.h C typedef enum { CAN_CHANNEL0, CAN_CHANNEL1, CAN_CHANNEL2, CAN_CHANNEL3, CAN_CHANNEL4, CAN_CHANNEL5, CAN_CHANNEL6, CAN_CHANNEL7, CAN_CHANNEL8, CAN_CHANNEL9, CAN_CHANNEL10, Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 379 CAN_CHANNEL11, CAN_CHANNEL12, CAN_CHANNEL13, CAN_CHANNEL14, CAN_CHANNEL15, CAN_CHANNEL16, CAN_CHANNEL17, CAN_CHANNEL18, CAN_CHANNEL19, CAN_CHANNEL20, CAN_CHANNEL21, CAN_CHANNEL22, CAN_CHANNEL23, CAN_CHANNEL24, CAN_CHANNEL25, CAN_CHANNEL26, CAN_CHANNEL27, CAN_CHANNEL28, CAN_CHANNEL29, CAN_CHANNEL30, CAN_CHANNEL31 } CAN_CHANNEL; Members Members Description CAN_CHANNEL0 Channel 0 ID CAN_CHANNEL1 Channel 1 ID CAN_CHANNEL2 Channel 2 ID CAN_CHANNEL3 Channel 3 ID CAN_CHANNEL4 Channel 4 ID CAN_CHANNEL5 Channel 5 ID CAN_CHANNEL6 Channel 6 ID CAN_CHANNEL7 Channel 7 ID CAN_CHANNEL8 Channel 8 ID CAN_CHANNEL9 Channel 9 ID CAN_CHANNEL10 Channel 10 ID CAN_CHANNEL11 Channel 11 ID CAN_CHANNEL12 Channel 12 ID CAN_CHANNEL13 Channel 13 ID CAN_CHANNEL14 Channel 14 ID CAN_CHANNEL15 Channel 15 ID CAN_CHANNEL16 Channel 16 ID CAN_CHANNEL17 Channel 17 ID CAN_CHANNEL18 Channel 18 ID CAN_CHANNEL19 Channel 19 ID CAN_CHANNEL20 Channel 20 ID CAN_CHANNEL21 Channel 21 ID CAN_CHANNEL22 Channel 22 ID CAN_CHANNEL23 Channel 23 ID CAN_CHANNEL24 Channel 24 ID CAN_CHANNEL25 Channel 25 ID CAN_CHANNEL26 Channel 26 ID CAN_CHANNEL27 Channel 27 ID CAN_CHANNEL28 Channel 28 ID CAN_CHANNEL29 Channel 29 ID CAN_CHANNEL30 Channel 30 ID CAN_CHANNEL31 Channel 31 ID Description CAN Channel This enumeration identifies the available CAN channels. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 380 CAN_CHANNEL_EVENT Enumeration Identifies all Layer 3 interrupts. File plib_can_help.h C typedef enum { CAN_RX_CHANNEL_NOT_EMPTY, CAN_RX_CHANNEL_HALF_FULL, CAN_RX_CHANNEL_FULL, CAN_RX_CHANNEL_OVERFLOW, CAN_RX_CHANNEL_ANY_EVENT, CAN_TX_CHANNEL_EMPTY, CAN_TX_CHANNEL_HALF_EMPTY, CAN_TX_CHANNEL_NOT_FULL, CAN_TX_CHANNEL_ANY_EVENT } CAN_CHANNEL_EVENT; Members Members Description CAN_RX_CHANNEL_NOT_EMPTY CAN Receive Channel Not Empty Event Mask CAN_RX_CHANNEL_HALF_FULL CAN Receive Channel Half Full Event Mask CAN_RX_CHANNEL_FULL CAN Receive Channel Full Event Mask CAN_RX_CHANNEL_OVERFLOW CAN Receive Channel Overflow Event Mask CAN_RX_CHANNEL_ANY_EVENT CAN Receive Channel Any Event Mask CAN_TX_CHANNEL_EMPTY CAN Transmit Channel Empty Event Mask CAN_TX_CHANNEL_HALF_EMPTY CAN Transmit Channel Half Empty Event Mask CAN_TX_CHANNEL_NOT_FULL CAN Transmit Channel Not Full Event Mask CAN_TX_CHANNEL_ANY_EVENT CAN Transmit Channel Any Event Mask Description CAN Layer 3 Interrupts This enumerates all the leading interrupts generated due to CAN transmit and receive events. This enumeration can be used to enable or disable channel events and as a mask to check if a channel event is active. A single or a combination of the interrupts can be logically ORed to specify the interrupt(s) to be enabled disabled or events to check. This enumeration is used by PLIB_CAN_ChannelEventEnable, PLIB_CAN_ChannelEventDisable, PLIB_CAN_ChannelEventClear, and PLIB_CAN_ChannelEventGet functions. CAN_CHANNEL_MASK Enumeration Lists the series of useful masks. File plib_can_help.h C typedef enum { CAN_CHANNEL0_MASK, CAN_CHANNEL1_MASK, CAN_CHANNEL2_MASK, CAN_CHANNEL3_MASK, CAN_CHANNEL4_MASK, CAN_CHANNEL5_MASK, CAN_CHANNEL6_MASK, CAN_CHANNEL7_MASK, CAN_CHANNEL8_MASK, CAN_CHANNEL9_MASK, CAN_CHANNEL10_MASK, CAN_CHANNEL11_MASK, CAN_CHANNEL12_MASK, CAN_CHANNEL13_MASK, CAN_CHANNEL14_MASK, Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 381 CAN_CHANNEL15_MASK, CAN_CHANNEL16_MASK, CAN_CHANNEL17_MASK, CAN_CHANNEL18_MASK, CAN_CHANNEL19_MASK, CAN_CHANNEL20_MASK, CAN_CHANNEL21_MASK, CAN_CHANNEL22_MASK, CAN_CHANNEL23_MASK, CAN_CHANNEL24_MASK, CAN_CHANNEL25_MASK, CAN_CHANNEL26_MASK, CAN_CHANNEL27_MASK, CAN_CHANNEL28_MASK, CAN_CHANNEL29_MASK, CAN_CHANNEL30_MASK, CAN_CHANNEL31_MASK, CAN_ANYCHANNEL_MASK } CAN_CHANNEL_MASK; Members Members Description CAN_CHANNEL0_MASK Channel 0 Mask CAN_CHANNEL1_MASK Channel 1 Mask CAN_CHANNEL2_MASK Channel 2 Mask CAN_CHANNEL3_MASK Channel 3 Mask CAN_CHANNEL4_MASK Channel 4 Mask CAN_CHANNEL5_MASK Channel 5 Mask CAN_CHANNEL6_MASK Channel 6 Mask CAN_CHANNEL7_MASK Channel 7 Mask CAN_CHANNEL8_MASK Channel 8 Mask CAN_CHANNEL9_MASK Channel 9 Mask CAN_CHANNEL10_MASK Channel 10 Mask CAN_CHANNEL11_MASK Channel 11 Mask CAN_CHANNEL12_MASK Channel 12 Mask CAN_CHANNEL13_MASK Channel 13 Mask CAN_CHANNEL14_MASK Channel 14 Mask CAN_CHANNEL15_MASK Channel 15 Mask CAN_CHANNEL16_MASK Channel 16 Mask CAN_CHANNEL17_MASK Channel 17 Mask CAN_CHANNEL18_MASK Channel 18 Mask CAN_CHANNEL19_MASK Channel 19 Mask CAN_CHANNEL20_MASK Channel 20 Mask CAN_CHANNEL21_MASK Channel 21 Mask CAN_CHANNEL22_MASK Channel 22 Mask CAN_CHANNEL23_MASK Channel 23 Mask CAN_CHANNEL24_MASK Channel 24 Mask CAN_CHANNEL25_MASK Channel 25 Mask CAN_CHANNEL26_MASK Channel 26 Mask CAN_CHANNEL27_MASK Channel 27 Mask CAN_CHANNEL28_MASK Channel 28 Mask CAN_CHANNEL29_MASK Channel 29 Mask CAN_CHANNEL30_MASK Channel 30 Mask CAN_CHANNEL31_MASK Channel 31 Mask CAN_ANYCHANNEL_MASK Channel any channel Mask Description CAN Channel Masks This enumeration identifies a series of useful masks. Each mask represents a CAN channel. These masks are used with the PLIB_CAN_AllChannelEventsGet and PLIB_CAN_AllChannelOverflowStatusGet functions. The value returned by these functions can be logically ANDed with any of these masks to check if an event or overflow event for that channel is active. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 382 CAN_DNET_FILTER_SIZE Enumeration Specifies the size of the DeviceNet filter. File plib_can_help.h C typedef enum { CAN_DNET_FILTER_SIZE_18_BIT, CAN_DNET_FILTER_SIZE_17_BIT, CAN_DNET_FILTER_SIZE_16_BIT, CAN_DNET_FILTER_SIZE_15_BIT, CAN_DNET_FILTER_SIZE_14_BIT, CAN_DNET_FILTER_SIZE_13_BIT, CAN_DNET_FILTER_SIZE_12_BIT, CAN_DNET_FILTER_SIZE_11_BIT, CAN_DNET_FILTER_SIZE_10_BIT, CAN_DNET_FILTER_SIZE_9_BIT, CAN_DNET_FILTER_SIZE_8_BIT, CAN_DNET_FILTER_SIZE_7_BIT, CAN_DNET_FILTER_SIZE_6_BIT, CAN_DNET_FILTER_SIZE_5_BIT, CAN_DNET_FILTER_SIZE_4_BIT, CAN_DNET_FILTER_SIZE_3_BIT, CAN_DNET_FILTER_SIZE_2_BIT, CAN_DNET_FILTER_SIZE_1_BIT, CAN_DNET_FILTER_DISABLE } CAN_DNET_FILTER_SIZE; Members Members Description CAN_DNET_FILTER_SIZE_18_BIT Compare up to data byte 2 bit 6 with filter mask bit 17 CAN_DNET_FILTER_SIZE_17_BIT Compare up to data byte 2 bit 7 with filter mask bit 16 CAN_DNET_FILTER_SIZE_16_BIT Compare up to data byte 1 bit 0 with filter mask bit 15 CAN_DNET_FILTER_SIZE_15_BIT Compare up to data byte 1 bit 1 with filter mask bit 14 CAN_DNET_FILTER_SIZE_14_BIT Compare up to data byte 1 bit 2 with filter mask bit 13 CAN_DNET_FILTER_SIZE_13_BIT Compare up to data byte 1 bit 3 with filter mask bit 12 CAN_DNET_FILTER_SIZE_12_BIT Compare up to data byte 1 bit 4 with filter mask bit 11 CAN_DNET_FILTER_SIZE_11_BIT Compare up to data byte 1 bit 5 with filter mask bit 10 CAN_DNET_FILTER_SIZE_10_BIT Compare up to data byte 1 bit 6 with filter mask bit 9 CAN_DNET_FILTER_SIZE_9_BIT Compare up to data byte 1 bit 7 with filter mask bit 8 CAN_DNET_FILTER_SIZE_8_BIT Compare up to data byte 0 bit 0 with filter mask bit 7 CAN_DNET_FILTER_SIZE_7_BIT Compare up to data byte 0 bit 1 with filter mask bit 6 CAN_DNET_FILTER_SIZE_6_BIT Compare up to data byte 0 bit 2 with filter mask bit 5 CAN_DNET_FILTER_SIZE_5_BIT Compare up to data byte 0 bit 3 with filter mask bit 4 CAN_DNET_FILTER_SIZE_4_BIT Compare up to data byte 0 bit 4 with filter mask bit 3 CAN_DNET_FILTER_SIZE_3_BIT Compare up to data byte 0 bit 5 with filter mask bit 2 CAN_DNET_FILTER_SIZE_2_BIT Compare up to data byte 0 bit 6 with filter mask bit 1 CAN_DNET_FILTER_SIZE_1_BIT Compare up to data byte 0 bit 7 with filter mask bit 0 CAN_DNET_FILTER_DISABLE Do not compare data bytes, Device Net Filtering is disabled Description CAN DeviceNet filter bit numbers. This enumeration identifies the size of the DeviceNet filter in bits. If the size of the DeviceNet filter is "n", the "n" most significant bits of the data payload are compared with the EID field of enabled filters. CAN_ERROR_STATE Enumeration Specifies the CAN module error states. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 383 File plib_can_help.h C typedef enum { CAN_TX_RX_WARNING_STATE, CAN_RX_WARNING_STATE, CAN_TX_WARNING_STATE, CAN_RX_BUS_PASSIVE_STATE, CAN_TX_BUS_PASSIVE_STATE, CAN_TX_BUS_OFF_STATE } CAN_ERROR_STATE; Members Members Description CAN_TX_RX_WARNING_STATE CAN Module is in a Transmit or Receive warning state. CAN_RX_WARNING_STATE CAN Module is in a Receive warning state. CAN_TX_WARNING_STATE CAN Module is in a Transmit warning state. CAN_RX_BUS_PASSIVE_STATE CAN Receive is in a Bus Passive state. CAN_TX_BUS_PASSIVE_STATE CAN Transmit is in a Bus Passive state. CAN_TX_BUS_OFF_STATE CAN Transmit is in Bus Off state. Description CAN Error States This enumeration identifies all of the CAN module error states events. The CAN module enters or exits an error state as the transmit and receive error counter values change. Refer to the CAN 2.0B specification for more details on the error states. This enumeration is used with the PLIB_CAN_ErrorStateGet function. CAN_FILTER Enumeration CAN event code returned by the CAN module. File plib_can_help.h C typedef enum { CAN_CHANNEL0_EVENT, CAN_CHANNEL1_EVENT, CAN_CHANNEL2_EVENT, CAN_CHANNEL3_EVENT, CAN_CHANNEL4_EVENT, CAN_CHANNEL5_EVENT, CAN_CHANNEL6_EVENT, CAN_CHANNEL7_EVENT, CAN_CHANNEL8_EVENT, CAN_CHANNEL9_EVENT, CAN_CHANNEL10_EVENT, CAN_CHANNEL11_EVENT, CAN_CHANNEL12_EVENT, CAN_CHANNEL13_EVENT, CAN_CHANNEL14_EVENT, CAN_CHANNEL15_EVENT, CAN_CHANNEL16_EVENT, CAN_CHANNEL17_EVENT, CAN_CHANNEL18_EVENT, CAN_CHANNEL19_EVENT, CAN_CHANNEL20_EVENT, CAN_CHANNEL21_EVENT, CAN_CHANNEL22_EVENT, CAN_CHANNEL23_EVENT, CAN_CHANNEL24_EVENT, CAN_CHANNEL25_EVENT, CAN_CHANNEL26_EVENT, CAN_CHANNEL27_EVENT, CAN_CHANNEL28_EVENT, Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 384 CAN_CHANNEL29_EVENT , CAN_CHANNEL30_EVENT , CAN_CHANNEL31_EVENT , CAN_NO_EVENT , CAN_ERROR_EVENT , CAN_WAKEUP_EVENT , CAN_RX_CHANNEL_OVERFLOW_EVENT , CAN_ADDRESS_ERROR_EVENT , CAN_BUS_BANDWIDTH_ERROR , CAN_TIMESTAMP_TIMER_EVENT , CAN_MODE_CHANGE_EVENT , CAN_FILTER0 , CAN_FILTER1 , CAN_FILTER2 , CAN_FILTER3 , CAN_FILTER4 , CAN_FILTER5 , CAN_FILTER6 , CAN_FILTER7 , CAN_FILTER8 , CAN_FILTER9 , CAN_FILTER10 , CAN_FILTER11 , CAN_FILTER12 , CAN_FILTER13 , CAN_FILTER14 , CAN_FILTER15 , CAN_FILTER16 , CAN_FILTER17 , CAN_FILTER18 , CAN_FILTER19 , CAN_FILTER20 , CAN_FILTER21 , CAN_FILTER22 , CAN_FILTER23 , CAN_FILTER24 , CAN_FILTER25 , CAN_FILTER26 , CAN_FILTER27 , CAN_FILTER28 , CAN_FILTER29 , CAN_FILTER30 , CAN_FILTER31 } CAN_FILTER; Members Members Description CAN_CHANNEL0_EVENT An event on Channel 0 is active CAN_CHANNEL1_EVENT An event on Channel 1 is active CAN_CHANNEL2_EVENT An event on Channel 2 is active CAN_CHANNEL3_EVENT An event on Channel 3 is active CAN_CHANNEL4_EVENT An event on Channel 4 is active CAN_CHANNEL5_EVENT An event on Channel 5 is active CAN_CHANNEL6_EVENT An event on Channel 6 is active CAN_CHANNEL7_EVENT An event on Channel 7 is active CAN_CHANNEL8_EVENT An event on Channel 8 is active CAN_CHANNEL9_EVENT An event on Channel 9 is active CAN_CHANNEL10_EVENT An event on Channel 10 is active CAN_CHANNEL11_EVENT An event on Channel 11 is active CAN_CHANNEL12_EVENT An event on Channel 12 is active CAN_CHANNEL13_EVENT An event on Channel 13 is active CAN_CHANNEL14_EVENT An event on Channel 14 is active CAN_CHANNEL15_EVENT An event on Channel 15 is active CAN_CHANNEL16_EVENT An event on Channel 16 is active CAN_CHANNEL17_EVENT An event on Channel 17 is active CAN_CHANNEL18_EVENT An event on Channel 18 is active CAN_CHANNEL19_EVENT An event on Channel 19 is active Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 385 CAN_CHANNEL20_EVENT An event on Channel 20 is active CAN_CHANNEL21_EVENT An event on Channel 21 is active CAN_CHANNEL22_EVENT An event on Channel 22 is active CAN_CHANNEL23_EVENT An event on Channel 23 is active CAN_CHANNEL24_EVENT An event on Channel 24 is active CAN_CHANNEL25_EVENT An event on Channel 25 is active CAN_CHANNEL26_EVENT An event on Channel 26 is active CAN_CHANNEL27_EVENT An event on Channel 27 is active CAN_CHANNEL28_EVENT An event on Channel 28 is active CAN_CHANNEL29_EVENT An event on Channel 29 is active CAN_CHANNEL30_EVENT An event on Channel 30 is active CAN_CHANNEL31_EVENT An event on Channel 31 is active CAN_NO_EVENT No Event is active CAN_ERROR_EVENT CAN Bus Error Event is active CAN_WAKEUP_EVENT CAN Bus Wakeup Event is active CAN_RX_CHANNEL_OVERFLOW_EVENT CAN Receive Channel Overflow Event is active CAN_ADDRESS_ERROR_EVENT CAN Address Error Event is active CAN_BUS_BANDWIDTH_ERROR CAN Bus Bandwidth Error is active CAN_TIMESTAMP_TIMER_EVENT CAN Time Stamp Timer Overflow event is active CAN_MODE_CHANGE_EVENT CAN Module Mode Change is active Description CAN Event Code This enumeration identifies all of the event codes returned by the PLIB_CAN_PendingEventsGet function. CAN_FILTER_MASK Enumeration Identifies the available CAN filter masks. File plib_can_help.h C typedef enum { CAN_FILTER_MASK0, CAN_FILTER_MASK1, CAN_FILTER_MASK2, CAN_FILTER_MASK3, CAN_NUMBER_OF_FILTER_MASKS } CAN_FILTER_MASK; Members Members Description CAN_FILTER_MASK0 CAN Filter Mask 0 CAN_FILTER_MASK1 CAN Filter Mask 1 CAN_FILTER_MASK2 CAN Filter Mask 2 CAN_FILTER_MASK3 CAN Filter Mask 3 CAN_NUMBER_OF_FILTER_MASKS Total number of filter masks in the module Description CAN Filter Masks This enumeration identifies the available filters masks in each CAN module. CAN_FILTER_MASK_TYPE Enumeration Specifies the CAN filter mask type. File plib_can_help.h Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 386 C typedef enum { CAN_FILTER_MASK_IDE_TYPE, CAN_FILTER_MASK_ANY_TYPE } CAN_FILTER_MASK_TYPE; Members Members Description CAN_FILTER_MASK_IDE_TYPE Mask processes only Filter type of message CAN_FILTER_MASK_ANY_TYPE Mask processes any type (SID or EID) of message Description CAN Filter Mask Type This enumeration specifies the filter mask type. The filter mask can either process messages with any type of ID (extended or standard) or can only process by ID specified in the filter configuration. For example, if the filter associated with the mask only accepts EID type messages and if the mask is configured to process by ID type, then SID messages will not be accepted. If the mask is configured to process any type of message, both SID and EID messages will be accepted on a filter match. CAN_ID_TYPE Enumeration Specifies the CAN ID type. File plib_can_help.h C typedef enum { CAN_EID, CAN_SID } CAN_ID_TYPE; Members Members Description CAN_EID CAN Extended ID CAN_SID CAN Standard ID Description CAN ID Type This enumeration specifies the two CAN ID types: Standard and Extended. The Standard Type ID is 11 bits long and the Extended ID is 29 bits long. This enumeration then specifies the type of the ID specified while configuring filters and filter masks. CAN_MODULE_EVENT Enumeration Specifies the CAN module events File plib_can_help.h C typedef enum { CAN_TX_EVENT, CAN_RX_EVENT, CAN_TIMESTAMP_TIMER_OVERFLOW_EVENT, CAN_OPERATION_MODE_CHANGE_EVENT, CAN_RX_OVERFLOW_EVENT, CAN_SYSTEM_ERROR_EVENT, CAN_BUS_ERROR_EVENT, CAN_BUS_ACTIVITY_WAKEUP_EVENT, CAN_INVALID_RX_MESSAGE_EVENT } CAN_MODULE_EVENT; Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 387 Members Members Description CAN_TX_EVENT Transmit channel event. This event will occur if any of the Transmit Channel events are active. CAN_RX_EVENT Receive channel event. This event will occur if any of the Receive Channel events are active. CAN_TIMESTAMP_TIMER_OVERFLOW_EVENT CAN Time Stamp Timer Overflow event occurs. This event occurs when the Time Stamp Timer has overflowed. CAN_OPERATION_MODE_CHANGE_EVENT CAN Operation Mode Change Event. This event occurs when the CAN module has changed its operating mode successfully. CAN_RX_OVERFLOW_EVENT CAN Receive Channel Overflow Event. This event occurs when any of the Receive Channel has overflowed. CAN_SYSTEM_ERROR_EVENT CAN System Error Event. This event occurs when CAN module tries to access an invalid Device RAM location. CAN_BUS_ERROR_EVENT CAN Bus Error Event. This event occurs when the CAN module cannot access the system bus. CAN_BUS_ACTIVITY_WAKEUP_EVENT CAN Bus Activity Wakeup. This event occurs when the device is in Sleep mode and bus activity is detected on the CAN bus. CAN_INVALID_RX_MESSAGE_EVENT CAN Bus Invalid Receive Message Event. This event occurs when the CAN module receives an Invalid message. Description CAN Module Events This enumeration identifies all of the CAN module events. A combination of listed events can be logically ORed to enable or disable module level events. Similarly, a combination of events can be checked if active. This enumeration is used with the PLIB_CAN_ModuleEventEnable function and PLIB_CAN_ModuleEventGet function. CAN_MODULE_ID Enumeration File plib_can_help.h C typedef enum { CAN_ID_1, CAN_ID_2, CAN_ID_3, CAN_NUMBER_OF_MODULES } CAN_MODULE_ID; Members Members Description CAN_NUMBER_OF_MODULES The total number of modules available. Description Enumeration: CAN_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to get the correct number of modules defined for the desired microcontroller. CAN_MSG_EID Structure Defines the structure of the EID word section of the transmit and receive message. File plib_can.h C typedef struct { unsigned data_length_code : 4; unsigned reserved0 : 1; unsigned unimplemented1 : 3; unsigned reserved1 : 1; Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 388 unsigned remote_request : 1; unsigned eid : 18; unsigned ide : 1; unsigned sub_remote_req : 1; unsigned unimplemented2 : 2; } CAN_MSG_EID; Members Members Description unsigned data_length_code : 4; Data Length Control. Specifies the size of the data payload section of the CAN packet. Valid values are 0x0 - 0x8 unsigned reserved0 : 1; Reserved bit. Should be always 0. unsigned unimplemented1 : 3; Unimplemented bit. Should be always 0. unsigned reserved1 : 1; Reserved bit. Should be always 0. unsigned remote_request : 1; Remote Transmit Request bit. Should be set for RTR messages, clear otherwise. unsigned eid : 18; CAN Transmit and Receive Extended ID field. Valid values are in range 0x0 - 0x3FFFF unsigned ide : 1; Identifier bit. If 0 means that message is SID. If 1 means that message is EID type. unsigned sub_remote_req : 1; Substitute Remote request bit. This bit should always be clear for an EID message. It is ignored for an SID message. unsigned unimplemented2 : 2; Unimplemented bit. Should be always 0. Description CAN Message EID Word This data structure represents the EID section of the CAN transmit and receive message. The data structure is an element of the CAN_TX_MSG_BUFFER and CAN_RX_MSG_BUFFER data structure. CAN_OPERATION_MODES Enumeration Lists all possible CAN module operational modes. File plib_can_help.h C typedef enum { CAN_LISTEN_ALL_MESSAGES_MODE, CAN_CONFIGURATION_MODE, CAN_LISTEN_ONLY_MODE, CAN_LOOPBACK_MODE, CAN_DISABLE_MODE, CAN_NORMAL_MODE } CAN_OPERATION_MODES; Members Members Description CAN_LISTEN_ALL_MESSAGES_MODE CAN Listen All Message Mode. The CAN module listens to all messages, regardless of errors CAN_CONFIGURATION_MODE CAN Configuration Mode. Various CAN module settings can be configured in this mode CAN_LISTEN_ONLY_MODE CAN Listen Only Mode. In this mode, the CAN module will not acknowledge signal and will not participate in error signaling. All messages are captured CAN_LOOPBACK_MODE CAN Loopback Mode. In this mode, the CAN module Transmit is internally connected to the Receive line. This mode is useful for debugging operation CAN_DISABLE_MODE CAN Disable Mode. The CAN module does not transmit or receive messages in this mode CAN_NORMAL_MODE CAN Normal Operation Mode. The CAN module transmits and receives messages in this mode Description CAN Operation Modes This enumerates all operating modes of the CAN module. The application should set the desired mode using the PLIB_CAN_OperationModeSelect function, and should then use the PLIB_CAN_OperationModeGet function to check if the CAN module has entered the requested mode. Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 389 CAN_RECEIVE_CHANNEL Enumeration Lists all possible CAN module receive channels. File plib_can_help.h C typedef enum { CAN_RECEIVE_CHANNEL0, CAN_RECEIVE_CHANNEL1 } CAN_RECEIVE_CHANNEL; Members Members Description CAN_RECEIVE_CHANNEL0 CAN receive channel 0 CAN_RECEIVE_CHANNEL1 CAN receive channel 1 Description CAN Receive Channels This enumerates all CAN module receive channels(channels that are not allowed to be configured for transmit). CAN_RECEIVE_MODES Enumeration Lists all possible CAN module receive modes. File plib_can_help.h C typedef enum { CAN_RECEIVE_ALL_MSG_MODE, CAN_RECEIVE_VALID_EID_MODE, CAN_RECEIVE_VALID_STD_MODE, CAN_RECEIVE_VALID_MODE } CAN_RECEIVE_MODES; Members Members Description CAN_RECEIVE_ALL_MSG_MODE Receive all messages(Including with errors). The message filters will not be considered CAN_RECEIVE_VALID_EID_MODE Receive only valid messages(with error will be discarded, filter will be considered) with extended identifier. This is applicable only for functional mode 0 CAN_RECEIVE_VALID_STD_MODE Receive only valid messages(with error will be discarded, filter will be considered) with standard identifier. This is applicable only for functional mode 0 CAN_RECEIVE_VALID_MODE Receive only valid messages(with error will be discarded, filter will be considered) with extended identifier/standard identifier Based on the configuration Description CAN Receive Modes This enumerates all operating modes of the CAN module. The application should set the desired mode using the PLIB_CAN_ReceiveModeSelect function, and should then use the PLIB_CAN_ReceiveModeGet function to check if the CAN module has entered the requested mode. CAN_RX_DATA_MODE Enumeration Enables the Data-only Receive mode or Full Receive mode of a CAN receive channel. File plib_can_help.h C typedef enum { Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 390 CAN_RX_DATA_ONLY, CAN_RX_FULL_RECEIVE } CAN_RX_DATA_MODE; Members Members Description CAN_RX_DATA_ONLY CAN Receive Channel Data Only Mode is enabled CAN_RX_FULL_RECEIVE CAN Receive Channel Full Receive Mode is enabled Description CAN Receive Channel Data Only Mode This enumeration specifies the status of the CAN receive channel data-only feature. If the feature is enabled, the CAN module will store only the data payload portion of the received CAN message. If the Full Receive mode is specified, the CAN module stores the entire CAN message (ID field plus data payload). The receive channel can be either in Data-Only mode or Full Receive mode. CAN_RX_MSG_BUFFER Union Defines the structure of the CAN receive message buffer File plib_can.h C typedef union { struct { CAN_RX_MSG_SID msgSID; CAN_MSG_EID msgEID; uint8_t data[8]; } uint8_t dataOnlyMsgData[8]; uint32_t messageWord[4]; } CAN_RX_MSG_BUFFER; Members Members Description CAN_RX_MSG_SID msgSID; This is SID portion of the CAN Receive message CAN_MSG_EID msgEID; This is EID portion of the CAN Receive message uint8_t data[8]; This is the data payload section of the received message uint8_t dataOnlyMsgData[8]; This can be used if the message buffer is to be read from a Data-Only type of CAN Receive Channel uint32_t messageWord[4]; This is CAN Receive message organized as a set of 32-bit words Description CAN Receive Message Buffer This data structure represents the CAN receive message buffer. Received messages could be either full-receive messages or data-only messages. A full-receive message contains the message header and data payload section. For a full-receive CAN receive channel, the caller should use the msgSID, msgEID and data members. A data-only message contains only an 8-byte data payload. While using this data structure with a data-only type of CAN receive channel, the caller should use the dataOnlyMsgData member of the structure and should read only 8 bytes of data. CAN_RX_MSG_SID Structure Defines the structure of the SID word section of the receive message. File plib_can.h C typedef struct { unsigned sid : 11; unsigned filter_hit : 5; unsigned msg_timestamp : 16; } CAN_RX_MSG_SID; Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 391 Members Members Description unsigned sid : 11; SID of the Received CAN Message unsigned filter_hit : 5; Filter which accepted this message unsigned msg_timestamp : 16; Time stamp of the received message. This is valid only if the Timestamping is enabled Description CAN Receive Message SID Word This data structure represents the SID section of the CAN receive message. The data structure is an element of the CAN_RX_MSG_BUFFER data structure. CAN_TIME_SEGMENT_LENGTH Enumeration All possible values for the assignable number of Time Quanta. File plib_can_help.h C typedef enum { CAN_TIME_SEGMENT_LEN_8TQ, CAN_TIME_SEGMENT_LEN_7TQ, CAN_TIME_SEGMENT_LEN_6TQ, CAN_TIME_SEGMENT_LEN_5TQ, CAN_TIME_SEGMENT_LEN_4TQ, CAN_TIME_SEGMENT_LEN_3TQ, CAN_TIME_SEGMENT_LEN_2TQ, CAN_TIME_SEGMENT_LEN_1TQ } CAN_TIME_SEGMENT_LENGTH; Members Members Description CAN_TIME_SEGMENT_LEN_8TQ Segment length is 8 x TQ CAN_TIME_SEGMENT_LEN_7TQ Segment length is 7 x TQ CAN_TIME_SEGMENT_LEN_6TQ Segment length is 6 x TQ CAN_TIME_SEGMENT_LEN_5TQ Segment length is 5 x TQ CAN_TIME_SEGMENT_LEN_4TQ Segment length is 4 x TQ CAN_TIME_SEGMENT_LEN_3TQ Segment length is 3 x TQ CAN_TIME_SEGMENT_LEN_2TQ Segment length is 2 x TQ CAN_TIME_SEGMENT_LEN_1TQ Segment length is 1 x TQ Description CAN Segment length This enumeration defines values that can be assigned while defining the number of Time Quanta in a bit. CAN_TX_CHANNEL_STATUS Enumeration Identifies possible transmit channel-specific conditions. File plib_can_help.h C typedef enum { CAN_TX_CHANNEL_TRANSMITTING, CAN_TX_CHANNEL_ERROR, CAN_TX_CHANNEL_ARBITRATION_LOST } CAN_TX_CHANNEL_STATUS; Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 392 Members Members Description CAN_TX_CHANNEL_TRANSMITTING CAN Transmit Channel is currently Transmitting. CAN_TX_CHANNEL_ERROR CAN Transmit Channel Error has occurred. CAN_TX_CHANNEL_ARBITRATION_LOST CAN Transmit Channel lost arbitration. Description CAN Transmit Channel Condition This enumeration identifies the possible transmit channel condition. These masks can be logically ANDed with values returned by the PLIB_CAN_TransmitChannelStatusGet function to check if a condition is active. CAN_TX_MSG_BUFFER Union Defines the structure of the CAN transmit message buffer. File plib_can.h C typedef union { struct { CAN_TX_MSG_SID msgSID; CAN_MSG_EID msgEID; unsigned char data[8]; } uint32_t messageWord[4]; } CAN_TX_MSG_BUFFER; Members Members Description CAN_TX_MSG_SID msgSID; This is SID portion of the CAN Transmit message CAN_MSG_EID msgEID; This is EID portion of the CAN Transmit message unsigned char data[8]; This is the data portion of the CAN Transmit message uint32_t messageWord[4]; This is CAN Transmit message organized as a set of 32 bit words Description CAN Transmit Message Buffer This data structure represents the CAN transmit message buffer. This should be used for writing data to a CAN transmit channel and transmitting data. A pointer to this type of data structure is returned by the PLIB_CAN_TransmitBufferGet function. The data structure allows the transmit message buffer to be accessed as fields of a CAN transmit message and also as an array of four 32-bit words. The latter allows for quick initialization of the message buffer. CAN_TX_MSG_SID Structure Defines the structure of the SID word section of the transmit message. File plib_can.h C typedef struct { unsigned sid : 11; } CAN_TX_MSG_SID; Members Members Description unsigned sid : 11; CAN Transmit Message Standard ID. This value should be between 0x0 - 0x7FF Description CAN Transmit Message SID Word Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 393 This data structure represents the SID section of the CAN transmit message. The data structure is an element of the CAN_TX_MSG_BUFFER data structure. CAN_TX_RTR Enumeration Specifies the status of the CAN Remote Transmit Request (RTR) feature for a CAN transmit channel. File plib_can_help.h C typedef enum { CAN_TX_RTR_ENABLED, CAN_TX_RTR_DISABLED } CAN_TX_RTR; Members Members Description CAN_TX_RTR_ENABLED CAN Transmit Channel RTR Feature is enabled CAN_TX_RTR_DISABLED CAN Transmit Channel RTR Feature is disabled Description CAN Transmit Channel Remote Transmit Request (RTR) This enumeration specifies the status of the CAN RTR feature for a CAN transmit channel. The RTR feature allows a node on the CAN Bus to request a transmission from another node on the bus. The responding node in this case should have a RTR enabled Transmit Channel in order to be able to respond to this request. CAN_TXCHANNEL_PRIORITY Enumeration Specifies the priority of a transmit channel. File plib_can_help.h C typedef enum { CAN_LOWEST_PRIORITY, CAN_LOW_MEDIUM_PRIORITY, CAN_HIGH_MEDIUM_PRIORITY, CAN_HIGHEST_PRIORITY } CAN_TXCHANNEL_PRIORITY; Members Members Description CAN_LOWEST_PRIORITY CAN lowest priority CAN_LOW_MEDIUM_PRIORITY CAN low medium priority CAN_HIGH_MEDIUM_PRIORITY CAN high medium priority CAN_HIGHEST_PRIORITY CAN highest priority Description CAN Transmit Channel Priority This enumeration identifies the available transmit channel priorities. A transmit channel has its own natural priority order, which determines priority when two or more transmit channels are assigned the same priority level. Channel 1 has higher natural priority than channel 0 and channel 2 has a natural priority than channel 1, and so on. CAN_RX_DATA_ONLY_SIZE_BYTES Macro Used as the size of the CAN data-only receive message buffer in bytes. File plib_can.h Peripheral Libraries Help CAN Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 394 C #define CAN_RX_DATA_ONLY_SIZE_BYTES 8 Description CAN Data-Only Receive Message Buffer This constant is used as the size of the CAN data-only receive message buffer in bytes. CAN_TX_RX_MESSAGE_SIZE_BYTES Macro Used as the array size of the CAN transmit and full receive message buffer. File plib_can.h C #define CAN_TX_RX_MESSAGE_SIZE_BYTES 16 Description CAN Transmit and Receive Message Buffer size This constant is used as the array size of the CAN transmit and full receive message buffer. Files Files Name Description plib_can.h This file contains the interface definition for the CAN Peripheral Library. plib_can_help.h This file contains the enumerations for the CAN Peripheral Library help file. Description This section lists the source and header files used by the library. plib_can.h This file contains the interface definition for the CAN Peripheral Library. Functions Name Description PLIB_CAN_AllChannelEventsGet Returns a value representing the event status of all CAN channels. PLIB_CAN_AllChannelOverflowStatusGet Returns a value representing the receive overflow event status of all CAN channels. PLIB_CAN_BaudRateGet Returns the current CAN module Baud rate. PLIB_CAN_BaudRatePrescaleSetup Sets the prescale divisor applied to the CAN module's input clock before it is used to determine the CAN baud rate. PLIB_CAN_BitSamplePhaseSet Sets the CAN bit-sampling phase parameters. PLIB_CAN_BusActivityWakeupDisable Disables the wake-up on bus activity receive line filter. PLIB_CAN_BusActivityWakeupEnable Enables the wake-up on bus activity receive line filter. PLIB_CAN_BusLine3TimesSamplingDisable Disables the bus line three times sampling. PLIB_CAN_BusLine3TimesSamplingEnable Enables the bus line three times sampling. PLIB_CAN_ChannelEventClear Clears CAN channel events. PLIB_CAN_ChannelEventDisable Enables channel level events. PLIB_CAN_ChannelEventEnable Enables channel level events. PLIB_CAN_ChannelEventGet Returns a value representing the event status of a CAN channel. PLIB_CAN_ChannelForReceiveSet Configures a CAN channel for receive operation. PLIB_CAN_ChannelForTransmitSet Configures a CAN channel for transmission. PLIB_CAN_ChannelReset Resets a CAN channel. PLIB_CAN_ChannelResetIsComplete Returns 'true' if the specified channel reset is complete. PLIB_CAN_ChannelUpdate Updates the CAN Channel internal pointers. PLIB_CAN_DeviceNetConfigure Configures the CAN module DeviceNet(TM) filter feature. Peripheral Libraries Help CAN Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 395 PLIB_CAN_Disable Disables the specified CAN module. PLIB_CAN_Enable Enables the specified CAN module. PLIB_CAN_ErrorStateGet Returns the CAN error status word. PLIB_CAN_ExistsActiveStatus Identifies whether the ActiveStatus feature exists on the CAN module. PLIB_CAN_ExistsAllChannelEvents Identifies whether the AllChannelEvents feature exists on the CAN module. PLIB_CAN_ExistsAllChannelOverflow Identifies whether the AllChannelOverflow feature exists on the CAN module. PLIB_CAN_ExistsBaudRateGet Identifies whether the BaudRateGet feature exists on the CAN module. PLIB_CAN_ExistsBaudRatePrescaleSetup Identifies whether the BaudRatePrescaleSetup feature exists on the CAN module. PLIB_CAN_ExistsBitSamplePhaseSet Identifies whether the BitSamplePhaseSet feature exists on the CAN module. PLIB_CAN_ExistsBusActivityWakeup Identifies whether the BusActivityWakeup feature exists on the CAN module. PLIB_CAN_ExistsBusLine3TimesSampling Identifies whether the BusLine3TimesSampling feature exists on the CAN module. PLIB_CAN_ExistsChannelEvent Identifies whether the ChannelEventGet feature exists on the CAN module. PLIB_CAN_ExistsChannelEventEnable Identifies whether the ChannelEventEnable feature exists on the CAN module. PLIB_CAN_ExistsChannelForReceiveSet Identifies whether the ChannelForReceiveSet feature exists on the CAN module. PLIB_CAN_ExistsChannelForTransmitSet Identifies whether the ChannelForTransmitSet feature exists on the CAN module. PLIB_CAN_ExistsChannelReset Identifies whether the ChannelReset feature exists on the CAN module. PLIB_CAN_ExistsChannelUpdate Identifies whether the ChannelUpdate feature exists on the CAN module. PLIB_CAN_ExistsDeviceNet Identifies whether the DeviceNet feature exists on the CAN module. PLIB_CAN_ExistsEnableControl Identifies whether the EnableControl feature exists on the CAN module. PLIB_CAN_ExistsErrorState Identifies whether the ErrorStateGet feature exists on the CAN module. PLIB_CAN_ExistsFilterConfigure Identifies whether the FilterConfigure feature exists on the CAN module. PLIB_CAN_ExistsFilterEnable Identifies whether the FilterEnable feature exists on the CAN module. PLIB_CAN_ExistsFilterMaskConfigure Identifies whether the FilterMaskConfigure feature exists on the CAN module. PLIB_CAN_ExistsFilterToChannelLink Identifies whether the FilterToChannelLink feature exists on the CAN module. PLIB_CAN_ExistsLatestFilterMatchGet Identifies whether the LatestFilterMatchGet feature exists on the CAN module. PLIB_CAN_ExistsMemoryBufferAssign Identifies whether the MemoryBufferAssign feature exists on the CAN module. PLIB_CAN_ExistsModuleEventClear Identifies whether the ModuleEvents feature exists on the CAN module. PLIB_CAN_ExistsModuleEventEnable Identifies whether the ModuleEventEnable feature exists on the CAN module. PLIB_CAN_ExistsModuleInfo Identifies whether the ModuleInformation feature exists on the CAN module. PLIB_CAN_ExistsOperationModeRead Identifies whether the OperationModeRead feature exists on the CAN module. PLIB_CAN_ExistsOperationModeWrite Identifies whether the OperationModeSet feature exists on the CAN module. PLIB_CAN_ExistsPendingEventsGet Identifies whether the PendingEventsGet feature exists on the CAN module. PLIB_CAN_ExistsPendingTransmissionsAbort Identifies whether the PendingTransmissionsAbort feature exists on the CAN module. PLIB_CAN_ExistsPrecalculatedBitRateSetup Identifies whether the PrecalculatedBitRateSetup feature exists on the CAN module. PLIB_CAN_ExistsReceivedMessageGet Identifies whether the ReceivedMessageGet feature exists on the CAN module. PLIB_CAN_ExistsReceiveErrorCount Identifies whether the ReceiveErrorCount feature exists on the CAN module. PLIB_CAN_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the CAN module. PLIB_CAN_ExistsTimeStampEnable Identifies whether the TimeStampEnable feature exists on the CAN module PLIB_CAN_ExistsTimeStampPrescaler Identifies whether the TimeStampPrescaler feature exists on the CAN module. PLIB_CAN_ExistsTimeStampValue Identifies whether the TimeStampValue feature exists on the CAN module. PLIB_CAN_ExistsTransmissionIsAborted Identifies whether the TransmissionAbortStatus feature exists on the CAN module. PLIB_CAN_ExistsTransmitBufferGet Identifies whether the TransmitBufferGet feature exists on the CAN module. PLIB_CAN_ExistsTransmitChannelFlush Identifies whether the TransmitChannelFlush feature exists on the CAN module. PLIB_CAN_ExistsTransmitChannelStatus Identifies whether the TransmitChannelStatus feature exists on the CAN module. PLIB_CAN_ExistsTransmitErrorCountGet Identifies whether the TransmitErrorCountGet feature exists on the CAN module. PLIB_CAN_FilterConfigure Configures a CAN message acceptance filter. PLIB_CAN_FilterDisable Disables a CAN message acceptance filter. PLIB_CAN_FilterEnable Enables a CAN message acceptance filter. PLIB_CAN_FilterIsDisabled Returns 'true' if the specified filter is disabled. PLIB_CAN_FilterMaskConfigure Configures a CAN filter mask. PLIB_CAN_FilterToChannelLink Links a filter to a channel. PLIB_CAN_IsActive Returns 'true' if the CAN module is active. PLIB_CAN_LatestFilterMatchGet Returns the index of the filter that accepted the latest message. Peripheral Libraries Help CAN Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 396 PLIB_CAN_MemoryBufferAssign Assigns buffer memory to the CAN module. PLIB_CAN_ModuleEventClear Clears the CAN module level events. PLIB_CAN_ModuleEventDisable Disables the module level events. PLIB_CAN_ModuleEventEnable Enables the module level events. PLIB_CAN_ModuleEventGet Returns the status of the CAN module events. PLIB_CAN_OperationModeGet Obtains the current CAN operating mode. PLIB_CAN_OperationModeSelect Sets the CAN operating mode. PLIB_CAN_PendingEventsGet Returns a value representing the highest priority active event in the module. PLIB_CAN_PendingTransmissionsAbort Aborts any pending transmit operations. PLIB_CAN_PrecalculatedBitRateSetup Sets the desired Baud rate for the respective CAN module. PLIB_CAN_ReceivedMessageGet Returns a pointer to a message to be read from the CAN channel. PLIB_CAN_ReceiveErrorCountGet Returns the CAN receive error count. PLIB_CAN_StopInIdleDisable Disables the Stop in Idle feature. PLIB_CAN_StopInIdleEnable Enables the CAN module to stop when the processor enters Idle mode. PLIB_CAN_TimeStampDisable Disables the time stamp feature for the CAN module. PLIB_CAN_TimeStampEnable Enables the time stamp feature for the CAN module. PLIB_CAN_TimeStampPrescalerSet Sets the CAN receive message time stamp timer prescaler. PLIB_CAN_TimeStampValueGet Returns the current value of the CAN receive message time stamp timer value. PLIB_CAN_TimeStampValueSet Sets the CAN receive message time stamp timer value. PLIB_CAN_TotalChannelsGet Returns the total number of CAN channels per CAN module. PLIB_CAN_TotalFiltersGet Returns the total number of CAN Filters per CAN module. PLIB_CAN_TotalMasksGet Returns the total number of CAN masks per CAN module. PLIB_CAN_TransmissionIsAborted Returns 'true' if the transmit abort operation is complete. PLIB_CAN_TransmitBufferGet Returns a pointer to an empty transmit buffer. PLIB_CAN_TransmitChannelFlush Causes all messages in the specified transmit channel to be transmitted. PLIB_CAN_TransmitChannelStatusGet Returns the condition of the transmit channel. PLIB_CAN_TransmitErrorCountGet Returns the CAN transmit error count Macros Name Description CAN_RX_DATA_ONLY_SIZE_BYTES Used as the size of the CAN data-only receive message buffer in bytes. CAN_TX_RX_MESSAGE_SIZE_BYTES Used as the array size of the CAN transmit and full receive message buffer. Structures Name Description CAN_MSG_EID Defines the structure of the EID word section of the transmit and receive message. CAN_RX_MSG_SID Defines the structure of the SID word section of the receive message. CAN_TX_MSG_SID Defines the structure of the SID word section of the transmit message. Unions Name Description CAN_RX_MSG_BUFFER Defines the structure of the CAN receive message buffer CAN_TX_MSG_BUFFER Defines the structure of the CAN transmit message buffer. Description CAN Peripheral Library Interface Header This library provides a low-level abstraction of the Controller Area Network (CAN) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences between one microcontroller variant and another. File Name plib_can.h Company Microchip Technology Inc. Peripheral Libraries Help CAN Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 397 plib_can_help.h This file contains the enumerations for the CAN Peripheral Library help file. Enumerations Name Description CAN_CHANNEL Identifies the supported CAN Channels. CAN_CHANNEL_EVENT Identifies all Layer 3 interrupts. CAN_CHANNEL_MASK Lists the series of useful masks. CAN_DNET_FILTER_SIZE Specifies the size of the DeviceNet filter. CAN_ERROR_STATE Specifies the CAN module error states. CAN_FILTER CAN event code returned by the CAN module. CAN_FILTER_MASK Identifies the available CAN filter masks. CAN_FILTER_MASK_TYPE Specifies the CAN filter mask type. CAN_ID_TYPE Specifies the CAN ID type. CAN_MODULE_EVENT Specifies the CAN module events CAN_MODULE_ID Enumeration: CAN_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to get the correct number of modules defined for the desired microcontroller. CAN_OPERATION_MODES Lists all possible CAN module operational modes. CAN_RECEIVE_CHANNEL Lists all possible CAN module receive channels. CAN_RECEIVE_MODES Lists all possible CAN module receive modes. CAN_RX_DATA_MODE Enables the Data-only Receive mode or Full Receive mode of a CAN receive channel. CAN_TIME_SEGMENT_LENGTH All possible values for the assignable number of Time Quanta. CAN_TX_CHANNEL_STATUS Identifies possible transmit channel-specific conditions. CAN_TX_RTR Specifies the status of the CAN Remote Transmit Request (RTR) feature for a CAN transmit channel. CAN_TXCHANNEL_PRIORITY Specifies the priority of a transmit channel. Description CAN Peripheral Library help file This file contains the enumerations for the CAN Peripheral Library help file. File Name plib_can_help.h Company Microchip Technology Inc. Peripheral Libraries Help CAN Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 398 Comparator Peripheral Library This section describes the Comparator Peripheral Library. Introduction The Comparator module is comprised of several identical analog comparator blocks, each complete with its own supporting input selectors and output logic. Each Comparator can be configured in a variety of ways, independent of the other comparators. The input voltage to the module can be either fed externally or it can be configured to use the internal voltage. Description This library provides a low-level abstraction of the Comparator module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby abstracting hardware differences from one microcontroller variant to another. Using the Library This topic describes the basic architecture of the Comparator Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_cmp.h The interface to the Comparator Peripheral Library is defined in the plib_cmp.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Comparator Peripheral Library must include peripheral.h. Library File: The Comparator Peripheral Library is part of the processor-specific peripheral library installed with the compiler. This library is automatically available (in the default search path) for any project built using the Microchip compilers. Peripheral Module IDs Peripheral libraries are indexed to allow a single library to control any number of instances of a peripheral in a single microcontroller. The first parameter to each operation in a peripheral library is the module instance ID. The module instance ID is defined by an enumeration that is defined in the processor-specific header files (included by the library's interface header). For the Comparator Peripheral Library, the module instance IDs are defined by the Comparator module enumeration. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the Comparator (CMP) module on Microchip PIC microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model Diagram Peripheral Libraries Help Comparator Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 399 Hardware Abstraction Model Description The Comparator Peripheral Library provides interface routines to interact with the blocks shown in the previous diagram. The Comparator VIN+ and VIN- block selects the Comparator non-inverting and inverting inputs, which can be either external or internal inputs. The Comparator module block compares the voltage level on the inputs and produce an output. If the input VIN+ > VIN-, the output will be high. The output will be low when VIN+ < VIN-. The Comparator Output Polarity block selects the Comparator output polarity. The Comparator Output Control block enables/disables the Comparator output pin. The Comparator Interrupt Logic Control block decide the comparator interrupt generation. The interrupt can happen at Low-to-high, High-to-Low, and for both transitions of the Comparator output. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Comparator module Library Interface Section Description General Configuration Provides the configuration routines for: • Enabling and disabling the module • Enabling and disabling Comparator output • Selecting Comparator input • Comparator status Comparator Feature Configuration Provides the configuration routines for various features in the Comparator: • Enabling and disabling Comparator Stop in Idle mode • Selecting Comparator speed/power • Enabling and disabling Comparator hysteresis • Enabling and disabling Comparator filters Feature Existence Functions These functions determine whether or not a particular feature is supported by the device. How the Library Works The following processes are involved while using a Comparator module: • CVREF Setup • Initialization • Configuring the Comparator interrupt (optional) • Power-Saving modes • Turning on the Comparator module CVREF Setup This topic describes how to configure the Comparator Voltage Reference (CVREF) if it is to be used as one of the inputs for the Comparator module. Peripheral Libraries Help Comparator Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 400 Description The CVREF is one of the internal voltage references available for the Comparator module, which can be configured for the required voltage value. Do the following to set up the CVREF: 1. Select the voltage source for CVREF using PLIB_CMP_CVREF_SourceVoltageSelect. 2. Select the CVREF voltage range using PLIB_CMP_CVREF_WideRangeEnable and/or PLIB_CMP_CVREF_WideRangeDisable. 3. Select the CVREF value using PLIB_CMP_CVREF_ValueSelect. 4. Enable or disable the CVREF pin output using PLIB_CMP_CVREF_OutputEnable or PLIB_CMP_CVREF_OutputDisable. 5. Turn on the CVREF module using PLIB_CMP_CVREF_Enable. Example #define MY_CMP_ID CMP_ID_1 //Select the CVREF source PLIB_CMP_CVREF_SourceVoltageSelect(MY_CMP_ID, CMP_CVREF_VOLTAGE_SOURCE_VDD); //Select the CVREF for wide range PLIB_CMP_CVREF_WideRangeEnable(MY_CMP_ID); //Select the CVREF value PLIB_CMP_CVREF_ValueSelect(MY_CMP_ID, CMP_CVREF_VALUE_15); //Enable the CVREF output pin PLIB_CMP_CVREF_OutputEnable(MY_CMP_ID); //Turn on the CVREF module PLIB_CMP_CVREF_Enable(MY_CMP_ID); Initialization This section describes Comparator module initialization. Description Do the following when using a Comparator module: 1. Select the Comparator inverting input using PLIB_CMP_InvertingInputChannelSelect. 2. Select the Comparator non-inverting input using PLIB_CMP_NonInvertingInputChannelSelect. 3. Select the Comparator output polarity using PLIB_CMP_OutputInvertEnable and/or PLIB_CMP_OutputInvertDisable. 4. Select the Comparator output pin using PLIB_CMP_OutputEnable and/or PLIB_CMP_OutputDisable. 5. Turn on the Comparator module using PLIB_CMP_Enable. Example #define MY_CMP_ID CMP_ID_1 //Select the comparator inverting input PLIB_CMP_InvertingInputChannelSelect(MY_CMP_INSTANCE,CMP_INVERTING_INPUT_CHANNEL_B); //Select the comparator non-inverting input PLIB_CMP_NonInvertingInputChannelSelect(MY_CMP_INSTANCE,CMP_NON_INVERTING_INPUT_A); //Select the comparator output polarity PLIB_CMP_OutputInvertDisable(MY_CMP_INSTANCE); //Enable the comparator output pin PLIB_CMP_OutputEnable(MY_CMP_INSTANCE); //Turn on the comparator module PLIB_CMP_Enable(MY_CMP_INSTANCE); Configuring the Comparator Interrupts This section describes the configuration of Comparator module interrupts. Description The comparator interrupt can happen for three events. The user must configure the event-detection logic to report changes to the output state of the Comparator, which can in turn be used for event or interrupt generation. The options include event generation on rising state changes (low-to-high), falling state changes (high-to-low), and all state changes. When a configured event occurs, it is flagged by the event detection flag. Peripheral Libraries Help Comparator Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 401 The user must clear this flag for the next interrupt generation. The following step is involved while configuring a Comparator interrupt: 1. Select the Comparator interrupt event using PLIB_CMP_InterruptEventSelect. Example #define MY_CMP_ID CMP_ID_1 //This code expects the comparator interrupt //enabled in the interrupt module //Select the comparator interrupt event PLIB_CMP_InterruptEventSelect(MY_CMP_INSTANCE, CMP_LOW_TO_HIGH); // If the event meets, interrupt will occur. Do the respective operation in the ISR and clear the interrupt flag. Note: Not all functionality is available on all devices. Please refer to the specific device data sheet for availability. Power-Saving Modes This section provides information on the Power-Saving modes for the Comparator module. Description Operation in Sleep mode: If the Comparator interrupt is enabled, the device will wake up from Sleep mode on the Comparator interrupt. If the Comparator interrupt is disabled,the comparator will work, but it will not wake up the device from sleep. Operation in Idle mode: The functions PLIB_CMP_StopInIdleModeEnable and PLIB_CMP_StopInIdleModeDisable determine if the Comparator module stops or continues operation in Idle mode. If the function PLIB_CMP_StopInIdleModeDisable is used, the module will continue operation in the Idle mode. If the Comparator interrupt is enabled, the device will wake up from Idle mode on the Comparator interrupt. If the function PLIB_CMP_StopInIdleModeEnable is used, the module will work in Idle mode but the interrupt will not generate if it is enabled. # Description Function Associated 1 Enable Comparator Stop in Idle mode. PLIB_CMP_StopInIdleModeEnable 2 Disable Comparator Stop in Idle mode. PLIB_CMP_StopInIdleModeDisable Example //Select comparator stop in idle mode PLIB_CMP_StopInIdleModeEnable(MY_CMP_INSTANCE); Note: Not all functionality is available on all devices. Please refer to the specific device data sheet for availability. Configuring the Library The library is configured for the supported Comparator module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Configuration Functions Name Description PLIB_CMP_CVREF_BandGapReferenceSourceSelect Selects the band gap reference voltage source. PLIB_CMP_CVREF_Enable Enables the voltage reference of the Comparator module. PLIB_CMP_CVREF_OutputDisable Disables the output voltage. PLIB_CMP_CVREF_OutputEnable Enables the voltage output. PLIB_CMP_CVREF_ReferenceVoltageSelect Selects the voltage reference value, CVref. PLIB_CMP_CVREF_SourceNegativeInputSelect Configures the Comparator module to use the selected input as a negative reference. PLIB_CMP_CVREF_SourceVoltageSelect Connects the Comparator module to the selected voltage source. PLIB_CMP_CVREF_ValueSelect Selects the voltage reference value. PLIB_CMP_CVREF_WideRangeDisable Disables the wide range. PLIB_CMP_CVREF_WideRangeEnable Enables the wide range. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 402 PLIB_CMP_CVREF_WideRangeIsEnabled Returns whether the wide range is selected for the reference voltage. PLIB_CMP_CVREF_Disable Disables the voltage reference of the Comparator module. PLIB_CMP_Disable Disables the Comparator module. PLIB_CMP_Enable Enables the Comparator module. PLIB_CMP_InterruptEventSelect Comparator interrupt event select. PLIB_CMP_InvertingInputChannelSelect Comparator inverting input channel select. PLIB_CMP_NonInvertingInputChannelSelect Comparator input channel select. PLIB_CMP_OutputDisable Disables the Comparator output. PLIB_CMP_OutputEnable Enables the Comparator output. PLIB_CMP_OutputStatusGet Comparator output status. PLIB_CMP_OutputInvertDisable Comparator output is non-inverted. PLIB_CMP_OutputInvertEnable Comparator output is inverted. PLIB_CMP_OutputLogicHigh Comparator output bit will give a 'logic high' on satisfying the input condition. PLIB_CMP_OutputLogicLow Comparator will be set to give 'logic low' on satisfying the input condition. b) Comparator Feature Configuration Functions Name Description PLIB_CMP_StopInIdleModeDisable Disables Stop in Idle mode. PLIB_CMP_StopInIdleModeEnable Enables Stop in Idle mode. c) Feature Existence Functions Name Description PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect Identifies whether the CVREFBGRefVoltageRangeSelect feature exists on the CMP module. PLIB_CMP_ExistsCVREFEnableControl Identifies whether the CVREFEnableControl feature exists on the CMP module. PLIB_CMP_ExistsCVREFOutputEnableControl Identifies whether the CVREFOutputEnableControl feature exists on the CMP module. PLIB_CMP_ExistsCVREFRefVoltageRangeSelect Identifies whether the CVREFRefVoltageRangeSelect feature exists on the CMP module. PLIB_CMP_ExistsCVREFValueSelect Identifies whether the CVREFValueSelect feature exists on the CMP module. PLIB_CMP_ExistsCVREFVoltageRangeSelect Identifies whether the CVREFVoltageRangeSelect feature exists on the CMP module. PLIB_CMP_ExistsCVREFWideRangeControl Identifies whether the CVREFWideRangeControl feature exists on the CMP module. PLIB_CMP_ExistsEnableControl Identifies whether the ComparatorEnableControl feature exists on the CMP module. PLIB_CMP_ExistsInterruptEventSelect Identifies whether the InterruptEventSelect feature exists on the CMP module. PLIB_CMP_ExistsInvertingInputSelect Identifies whether the InvertingInputSelect feature exists on the CMP module. PLIB_CMP_ExistsInvertOutputControl Identifies whether the InvertOutputSelectControl feature exists on the CMP module. PLIB_CMP_ExistsNonInvertingInputSelect Identifies whether the NonInvertingInputSelect feature exists on the CMP module. PLIB_CMP_ExistsOutputEnableControl Identifies whether the ComparatorOutputEnableControl feature exists on the CMP module. PLIB_CMP_ExistsOutputLevelControl Identifies whether the OutputLevelSelectControl feature exists on the CMP module. PLIB_CMP_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the CMP module. PLIB_CMP_ExistsOutputStatusGet Identifies whether the OutputStatusGet feature exists on the CMP module. d) Data Types and Constants Name Description CMP_CLOCK_DIVIDE Defines Comparator Filter Clock Divide. CMP_CVREF_BANDGAP_SELECT Lists the band gap selection options. CMP_CVREF_REFERENCE_SELECT Lists the reference selection options. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 403 CMP_CVREF_VALUE Lists the voltage reference value selection options. CMP_CVREF_VOLTAGE_SOURCE Lists the Voltage source options. CMP_FILTER_CLOCK Defines Comparator filter input clock CMP_INTERRUPT_EVENT Defines Comparator interrupt events. CMP_INVERTING_INPUT Defines the list of Comparator inverting Input. CMP_MASK_A Defines Comparator Mask A Input. CMP_MASK_B Defines Comparator Mask B Input. CMP_MASK_C Defines Comparator Mask C Input. CMP_MODULE_ID Identifies the Comparator modules supported CMP_NON_INVERTING_INPUT Defines the list of Comparator non-inverting Input. CMP_SPEED_POWER Defines the Speed/Power of the Comparator Description This section describes the Application Programming Interface (API) functions of the Comparator Peripheral Library. Refer to each section for a detailed description. a) General Configuration Functions PLIB_CMP_CVREF_BandGapReferenceSourceSelect Function Selects the band gap reference voltage source. File plib_cmp.h C void PLIB_CMP_CVREF_BandGapReferenceSourceSelect(CMP_MODULE_ID index, CMP_CVREF_BANDGAP_SELECT select); Returns None. Description This function selects the band gap reference voltage source from the available options from CMP_CVREF_BANDGAP_SELECT. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect in your application to determine whether this feature is available. Preconditions None. Example PLIB_CMP_CVREF_BandGapReferenceSourceSelect ( CMP_ID_1, CMP_CVREF_BANDGAP_0_6V ); Parameters Parameters Description index Identifier for the device instance to be configured select Select a band gap reference source from CMP_CVREF_BANDGAP_SELECT Function void PLIB_CMP_CVREF_BandGapReferenceSourceSelect ( CMP_MODULE_ID index, CMP_CVREF_BANDGAP_SELECT bandGap ); PLIB_CMP_CVREF_Enable Function Enables the voltage reference of the Comparator module. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 404 File plib_cmp.h C void PLIB_CMP_CVREF_Enable(CMP_MODULE_ID index); Returns None. Description This function enables the voltage reference of the Comparator module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFEnableControl in your application to determine whether this feature is available. Preconditions The Comparator module should be appropriately configured before being enabled. Example PLIB_CMP_CVREF_Enable ( CMP_ID_1 ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_CVREF_Enable ( CMP_CVREF_MOD index ) PLIB_CMP_CVREF_OutputDisable Function Disables the output voltage. File plib_cmp.h C void PLIB_CMP_CVREF_OutputDisable(CMP_MODULE_ID index); Returns None. Description This function disables the reference voltage output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFOutputEnableControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_CMP_CVREF_OutputDisable ( CMP_ID_1 ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_CVREF_OutputDisable ( CMP_MODULE_ID index ) Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 405 PLIB_CMP_CVREF_OutputEnable Function Enables the voltage output. File plib_cmp.h C void PLIB_CMP_CVREF_OutputEnable(CMP_MODULE_ID index); Returns None. Description This function enables the voltage output Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFOutputEnableControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_CMP_CVREF_OutputEnable(CMP_ID_1); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_CVREF_OutputEnable ( CMP_MODULE_ID index ) PLIB_CMP_CVREF_ReferenceVoltageSelect Function Selects the voltage reference value, CVref. File plib_cmp.h C void PLIB_CMP_CVREF_ReferenceVoltageSelect(CMP_MODULE_ID index, CMP_CVREF_REFERENCE_SELECT reference); Returns None. Description This function selects the voltage reference value, CVref. This value decides which voltage source should be taken as reference voltage from the set CMP_CVREF_REFERENCE_SELECT. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsCVREFRefVoltageRangeSelect in your application to determine whether this feature is available. Preconditions Determine the correct value that should be passed. Example PLIB_CMP_CVREF_ReferenceVoltageSelect ( CMP_ID_1, CMP_CVREF_RESISTOR_LADDER_VOLTAGE ); Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 406 Parameters Parameters Description index Identifier for the device instance to be configured value Select value from CMP_CVREF_REFERENCE_SELECT Function void PLIB_CMP_CVREF_ReferenceVoltageSelect ( CMP_MODULE_ID index, CMP_CVREF_REFERENCE_SELECT reference ); PLIB_CMP_CVREF_SourceNegativeInputSelect Function Configures the Comparator module to use the selected input as a negative reference. File plib_cmp.h C void PLIB_CMP_CVREF_SourceNegativeInputSelect(CMP_MODULE_ID index, CMP_CVREF_VOLTAGE_SOURCE_NEG_REFERENCE negInput); Returns None. Description This function configures the Comparator module to use the selected input as a negative reference for the voltage source. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. For such devices, selecting the positive source will automatically select the negative input. Preconditions None. Example PLIB_CMP_CVREF_SourceNegativeInputSelect ( CMP_ID_1, CMP_CVREF_VOLTAGE_SOURCE_NEG_REF_GROUND ); Parameters Parameters Description index Identifier for the device instance to be configured negInput Select the voltage source negative reference from CMP_CVREF_VOLTAGE_SOURCE_NEG_REFERENCE Function void PLIB_CMP_CVREF_SourceNegativeInputSelect ( CMP_MODULE_ID index, CMP_CVREF_VOLTAGE_SOURCE_NEG_REFERENCE negInput ) PLIB_CMP_CVREF_SourceVoltageSelect Function Connects the Comparator module to the selected voltage source. File plib_cmp.h C void PLIB_CMP_CVREF_SourceVoltageSelect(CMP_MODULE_ID index, CMP_CVREF_VOLTAGE_SOURCE source); Returns None. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 407 Description This function connects the Comparator module to the selected voltage source. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFVoltageRangeSelect in your application to determine whether this feature is available. Preconditions None. Example PLIB_CMP_CVREF_SourceVoltageSelect ( CMP_ID_1, CMP_CVREF_VOLTAGE_SOURCE_INTERNAL ); Parameters Parameters Description index Identifier for the device instance to be configured source Select the voltage source from CMP_CVREF_VOLTAGE_SOURCE Function void PLIB_CMP_CVREF_SourceVoltageSelect ( CMP_MODULE_ID index, CMP_CVREF_VOLTAGE_SOURCE source ) PLIB_CMP_CVREF_ValueSelect Function Selects the voltage reference value. File plib_cmp.h C void PLIB_CMP_CVREF_ValueSelect(CMP_MODULE_ID index, CMP_CVREF_VALUE value); Returns None. Description This function selects the voltage reference value. This value decides how many resistance units will be added and therefore, decides the output voltage. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFValueSelect in your application to determine whether this feature is available. Preconditions Determine the correct value that should be passed. Example PLIB_CMP_CVREF_ValueSelect ( CMP_ID_1, CMP_CVREF_VALUE_13 ); Parameters Parameters Description index Identifier for the device instance to be configured value Select value from CMP_CVREF_VALUE Function void PLIB_CMP_CVREF_ValueSelect ( CMP_MODULE_ID index, CMP_CVREF_VALUE value ); PLIB_CMP_CVREF_WideRangeDisable Function Disables the wide range. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 408 File plib_cmp.h C void PLIB_CMP_CVREF_WideRangeDisable(CMP_MODULE_ID index); Returns None. Description This function disables the wide range for reference voltage. The range of possible voltages will become narrower, and finer voltage options can be achieved in this case. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFWideRangeControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_CMP_CVREF_WideRangeDisable ( CMP_ID_1 ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_CVREF_WideRangeDisable ( CMP_MODULE_ID index ) PLIB_CMP_CVREF_WideRangeEnable Function Enables the wide range. File plib_cmp.h C void PLIB_CMP_CVREF_WideRangeEnable(CMP_MODULE_ID index); Returns None. Description This function enables the wide range for reference voltage. The voltage range starts from zero if the wide range is selected. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFWideRangeControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_CMP_CVREF_WideRangeEnable(CMP_ID_1); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 409 Function void PLIB_CMP_CVREF_WideRangeEnable ( CMP_MODULE_ID index ) PLIB_CMP_CVREF_WideRangeIsEnabled Function Returns whether the wide range is selected for the reference voltage. File plib_cmp.h C bool PLIB_CMP_CVREF_WideRangeIsEnabled(CMP_MODULE_ID index); Returns • true = The wide range is enabled • false = The wide range is not enabled Description This function returns whether the wide range is enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFWideRangeControl in your application to determine whether this feature is available. Preconditions None. Example bool range; range = PLIB_CMP_CVREF_WideRangeIsEnabled ( MY_CMP_CVREF_ID ); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_CMP_CVREF_WideRangeIsEnabled ( CMP_MODULE_ID index ); PLIB_CMP_CVREF_Disable Function Disables the voltage reference of the Comparator module. File plib_cmp.h C void PLIB_CMP_CVREF_Disable(CMP_MODULE_ID index); Returns None. Description This function disables the voltage reference of the Comparator module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFEnableControl in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 410 Example PLIB_CMP_CVREF_Disable ( CMP_ID_1 ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_CVREF_Disable ( CMP_MODULE_ID index ) PLIB_CMP_Disable Function Disables the Comparator module. File plib_cmp.h C void PLIB_CMP_Disable(CMP_MODULE_ID index); Returns None. Description This function disables (turns OFF) the selected Comparator module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_Disable ( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_Disable ( CMP_MODULE_ID index ) PLIB_CMP_Enable Function Enables the Comparator module. File plib_cmp.h C void PLIB_CMP_Enable(CMP_MODULE_ID index); Returns None. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 411 Description This function enables (turns ON) the selected Comparator module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_Enable ( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_Enable ( CMP_MODULE_ID index ) PLIB_CMP_InterruptEventSelect Function Comparator interrupt event select. File plib_cmp.h C void PLIB_CMP_InterruptEventSelect(CMP_MODULE_ID index, CMP_INTERRUPT_EVENT event); Returns None. Description This function will select when the Comparator interrupt should occur. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsInterruptEventSelect in your application to determine whether this feature is available. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // CMP_INTERRUPT_EVENT - CMP_LOW_TO_HIGH PLIB_CMP_InterruptEventSelect ( MY_CMP_INSTANCE, CMP_INTERRUPT_GENERATION_LOW_TO_HIGH ); Parameters Parameters Description index Identifier for the device instance to be configured event One of the possible values from CMP_INTERRUPT_EVENT Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 412 Function void PLIB_CMP_InterruptEventSelect ( CMP_MODULE_ID index, CMP_INTERRUPT_EVENT event ) PLIB_CMP_InvertingInputChannelSelect Function Comparator inverting input channel select. File plib_cmp.h C void PLIB_CMP_InvertingInputChannelSelect(CMP_MODULE_ID index, CMP_INVERTING_INPUT channel); Returns None. Description This function will select the inverting input channels for the Comparator. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsInvertingInputSelect in your application to determine whether this feature is available. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_InvertingInputChannelSelect ( MY_CMP_INSTANCE, CMP_INVERTING_INPUT_IVREF ); Parameters Parameters Description index Identifier for the device instance to be configured channel One of the possible values from CMP_INVERTING_INPUT Function void PLIB_CMP_InvertingInputChannelSelect ( CMP_MODULE_ID index, CMP_INVERTING_INPUT channel ) PLIB_CMP_NonInvertingInputChannelSelect Function Comparator input channel select. File plib_cmp.h C void PLIB_CMP_NonInvertingInputChannelSelect(CMP_MODULE_ID index, CMP_NON_INVERTING_INPUT input); Returns None. Description This function will select the non-inverting input channels for the Comparator. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 413 PLIB_CMP_ExistsNonInvertingInputSelect in your application to determine whether this feature is available.s Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_NonInvertingInputChannelSelect ( MY_CMP_INSTANCE, CMP_NON_INVERTING_INPUT_CVREF ); Parameters Parameters Description index Identifier for the device instance to be configured channel One of the possible values from CMP_NON_INVERTING_INPUT Function void PLIB_CMP_NonInvertingInputChannelSelect ( CMP_MODULE_ID index, CMP_NON_INVERTING_INPUT input ) PLIB_CMP_OutputDisable Function Disables the Comparator output. File plib_cmp.h C void PLIB_CMP_OutputDisable(CMP_MODULE_ID index); Returns None. Description This function disables (turns OFF) the Comparator output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputEnableControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputDisable ( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_OutputDisable ( CMP_MODULE_ID index ) PLIB_CMP_OutputEnable Function Enables the Comparator output. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 414 File plib_cmp.h C void PLIB_CMP_OutputEnable(CMP_MODULE_ID index); Returns None. Description This function enables (turns ON) the Comparator output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputEnableControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputEnable( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_OutputEnable ( CMP_MODULE_ID index ) PLIB_CMP_OutputStatusGet Function Comparator output status. File plib_cmp.h C bool PLIB_CMP_OutputStatusGet(CMP_MODULE_ID index); Returns • true - The status flag is set • false - The status flag is clear Description This function will return the current status of the Comparator output. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 bool cmp_status; // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 415 cmp_status=PLIB_CMP_OutputStatusGet ( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_CMP_OutputStatusGet ( CMP_MODULE_ID index ) PLIB_CMP_OutputInvertDisable Function Comparator output is non-inverted. File plib_cmp.h C void PLIB_CMP_OutputInvertDisable(CMP_MODULE_ID index); Returns None. Description This function will select the non-inverted comparator output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputEnableControlExistsInvertOutputControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputInvertDisable ( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_OutputInvertDisable ( CMP_MODULE_ID index ) PLIB_CMP_OutputInvertEnable Function Comparator output is inverted. File plib_cmp.h C void PLIB_CMP_OutputInvertEnable(CMP_MODULE_ID index); Returns None. Description Calling this function will set the comparator to make its output inverted. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 416 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputEnableControlExistsInvertOutputControl in your application to determine whether this feature is available. Setting this bit will invert the signal to the comparator interrupt generator as well. This will result in an interrupt being generated on the opposite edge from the one selected by PLIB_CMP_InterruptEventSelect function. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputDisable ( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_OutputInvertEnable ( CMP_MODULE_ID index) PLIB_CMP_OutputLogicHigh Function Comparator output bit will give a 'logic high' on satisfying the input condition. File plib_cmp.h C void PLIB_CMP_OutputLogicHigh(CMP_MODULE_ID index); Returns None. Description Calling this API will set the Comparator module to output a 'logic high' on satisfying the input condition. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputLevelControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputLogicHigh ( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_OutputLogicHigh ( CMP_MODULE_ID index ) Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 417 PLIB_CMP_OutputLogicLow Function Comparator will be set to give 'logic low' on satisfying the input condition. File plib_cmp.h C void PLIB_CMP_OutputLogicLow(CMP_MODULE_ID index); Returns None. Description This function will set the Comparator to give 'logic low' on satisfying the input condition. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputLevelControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputLogicLow( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_OutputLogicLow ( CMP_MODULE_ID index ) b) Comparator Feature Configuration Functions PLIB_CMP_StopInIdleModeDisable Function Disables Stop in Idle mode. File plib_cmp.h C void PLIB_CMP_StopInIdleModeDisable(CMP_MODULE_ID index); Returns None. Description This function will continue operation of all enabled comparators when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsStopInIdle in your application to determine whether this feature is available. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 418 Preconditions None. Example #define MY_CMP_INSTANCE CMP_ID_1 // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_StopInIdleModeDisable ( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_StopInIdleModeDisable ( CMP_MODULE_ID index ) PLIB_CMP_StopInIdleModeEnable Function Enables Stop in Idle mode. File plib_cmp.h C void PLIB_CMP_StopInIdleModeEnable(CMP_MODULE_ID index); Returns None. Description This function will discontinue operation of all comparators when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_StopInIdleModeEnable ( MY_CMP_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_CMP_StopInIdleModeEnable ( CMP_MODULE_ID index ) c) Feature Existence Functions PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect Function Identifies whether the CVREFBGRefVoltageRangeSelect feature exists on the CMP module. File plib_cmp.h Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 419 C bool PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect(CMP_MODULE_ID index); Returns • true - The CVREFBGRefVoltageRangeSelect feature is supported on the device • false - The CVREFBGRefVoltageRangeSelect feature is not supported on the device Description This function identifies whether the CVREFBGRefVoltageRangeSelect feature is available on the CMP module. When this function returns true, this function is supported on the device: • PLIB_CMP_CVREF_BandGapReferenceSourceSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect( CMP_MODULE_ID index ) PLIB_CMP_ExistsCVREFEnableControl Function Identifies whether the CVREFEnableControl feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsCVREFEnableControl(CMP_MODULE_ID index); Returns • true - The CVREFEnableControl feature is supported on the device • false - The CVREFEnableControl feature is not supported on the device Description This function identifies whether the CVREFEnableControl feature is available on the CMP module. When this function returns true, these functions are supported on the device: • PLIB_CMP_CVREF_Enable • PLIB_CMP_CVREF_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsCVREFEnableControl( CMP_MODULE_ID index ) Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 420 PLIB_CMP_ExistsCVREFOutputEnableControl Function Identifies whether the CVREFOutputEnableControl feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsCVREFOutputEnableControl(CMP_MODULE_ID index); Returns • true - The CVREFOutputEnableControl feature is supported on the device • false - The CVREFOutputEnableControl feature is not supported on the device Description This function identifies whether the CVREFOutputEnableControl feature is available on the CMP module. When this function returns true, these functions are supported on the device: • PLIB_CMP_CVREF_OutputEnable • PLIB_CMP_CVREF_OutputDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsCVREFOutputEnableControl( CMP_MODULE_ID index ) PLIB_CMP_ExistsCVREFRefVoltageRangeSelect Function Identifies whether the CVREFRefVoltageRangeSelect feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsCVREFRefVoltageRangeSelect(CMP_MODULE_ID index); Returns • true - The CVREFRefVoltageRangeSelect feature is supported on the device • false - The CVREFRefVoltageRangeSelect feature is not supported on the device Description This function identifies whether the CVREFRefVoltageRangeSelect feature is available on the CMP module. When this function returns true, this function is supported on the device: • PLIB_CMP_CVREF_ReferenceVoltageSelect Remarks None. Preconditions None. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 421 Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsCVREFRefVoltageRangeSelect( CMP_MODULE_ID index ) PLIB_CMP_ExistsCVREFValueSelect Function Identifies whether the CVREFValueSelect feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsCVREFValueSelect(CMP_MODULE_ID index); Returns • true - The CVREFValueSelect feature is supported on the device • false - The CVREFValueSelect feature is not supported on the device Description This function identifies whether the CVREFValueSelect feature is available on the CMP module. When this function returns true, this function is supported on the device: • PLIB_CMP_CVREF_ValueSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsCVREFValueSelect( CMP_MODULE_ID index ) PLIB_CMP_ExistsCVREFVoltageRangeSelect Function Identifies whether the CVREFVoltageRangeSelect feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsCVREFVoltageRangeSelect(CMP_MODULE_ID index); Returns • true - The CVREFVoltageRangeSelect feature is supported on the device • false - The CVREFVoltageRangeSelect feature is not supported on the device Description This function identifies whether the CVREFVoltageRangeSelect feature is available on the CMP module. When this function returns true, this function is supported on the device: • PLIB_CMP_CVREF_SourceVoltageSelect Remarks None. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 422 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsCVREFVoltageRangeSelect( CMP_MODULE_ID index ) PLIB_CMP_ExistsCVREFWideRangeControl Function Identifies whether the CVREFWideRangeControl feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsCVREFWideRangeControl(CMP_MODULE_ID index); Returns • true - The CVREFWideRangeControl feature is supported on the device • false - The CVREFWideRangeControl feature is not supported on the device Description This function identifies whether the CVREFWideRangeControl feature is available on the CMP module. When this function returns true, these functions are supported on the device: • PLIB_CMP_CVREF_WideRangeEnable • PLIB_CMP_CVREF_WideRangeDisable • PLIB_CMP_CVREF_WideRangeIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsCVREFWideRangeControl( CMP_MODULE_ID index ) PLIB_CMP_ExistsEnableControl Function Identifies whether the ComparatorEnableControl feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsEnableControl(CMP_MODULE_ID index); Returns • true - The ComparatorEnableControl feature is supported on the device • false - The ComparatorEnableControl feature is not supported on the device Description This function identifies whether the ComparatorEnableControl feature is available on the CMP module. When this function returns true, these Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 423 functions are supported on the device: • PLIB_CMP_Enable • PLIB_CMP_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsEnableControl( CMP_MODULE_ID index ) PLIB_CMP_ExistsInterruptEventSelect Function Identifies whether the InterruptEventSelect feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsInterruptEventSelect(CMP_MODULE_ID index); Returns • true - The InterruptEventSelect feature is supported on the device • false - The InterruptEventSelect feature is not supported on the device Description This function identifies whether the InterruptEventSelect feature is available on the CMP module. When this function returns true, this function is supported on the device: • PLIB_CMP_InterruptEventSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsInterruptEventSelect( CMP_MODULE_ID index ) PLIB_CMP_ExistsInvertingInputSelect Function Identifies whether the InvertingInputSelect feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsInvertingInputSelect(CMP_MODULE_ID index); Returns • true - The InvertingInputSelect feature is supported on the device Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 424 • false - The InvertingInputSelect feature is not supported on the device Description This function identifies whether the InvertingInputSelect feature is available on the CMP module. When this function returns true, this function is supported on the device: • PLIB_CMP_InvertingInputChannelSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsInvertingInputSelect( CMP_MODULE_ID index ) PLIB_CMP_ExistsInvertOutputControl Function Identifies whether the InvertOutputSelectControl feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsInvertOutputControl(CMP_MODULE_ID index); Returns • true - The InvertOutputSelectControl feature is supported on the device • false - The InvertOutputSelectControl feature is not supported on the device Description This function identifies whether the InvertOutputSelectControl feature is available on the CMP module. When this function returns true, these functions are supported on the device: • PLIB_CMP_OutputInvertEnable • PLIB_CMP_OutputInvertDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsInvertOutputControl( CMP_MODULE_ID index ) PLIB_CMP_ExistsNonInvertingInputSelect Function Identifies whether the NonInvertingInputSelect feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsNonInvertingInputSelect(CMP_MODULE_ID index); Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 425 Returns • true - The NonInvertingInputSelect feature is supported on the device • false - The NonInvertingInputSelect feature is not supported on the device Description This function identifies whether the NonInvertingInputSelect feature is available on the CMP module. When this function returns true, this function is supported on the device: • PLIB_CMP_NonInvertingInputChannelSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsNonInvertingInputSelect( CMP_MODULE_ID index ) PLIB_CMP_ExistsOutputEnableControl Function Identifies whether the ComparatorOutputEnableControl feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsOutputEnableControl(CMP_MODULE_ID index); Returns • true - The ComparatorOutputEnableControl feature is supported on the device • false - The ComparatorOutputEnableControl feature is not supported on the device Description This function identifies whether the ComparatorOutputEnableControl feature is available on the CMP module. When this function returns true, these functions are supported on the device: • PLIB_CMP_OutputEnable • PLIB_CMP_OutputDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsOutputEnableControl( CMP_MODULE_ID index ) PLIB_CMP_ExistsOutputLevelControl Function Identifies whether the OutputLevelSelectControl feature exists on the CMP module. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 426 File plib_cmp.h C bool PLIB_CMP_ExistsOutputLevelControl(CMP_MODULE_ID index); Returns • true - The OutputLevelSelectControl feature is supported on the device • false - The OutputLevelSelectControl feature is not supported on the device Description This function identifies whether the OutputLevelSelectControl feature is available on the CMP module. When this function returns true, these functions are supported on the device: • PLIB_CMP_OutputLogicHigh • PLIB_CMP_OutputLogicLow Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsOutputLevelControl( CMP_MODULE_ID index ) PLIB_CMP_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsStopInIdle(CMP_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the CMP module. When this function returns true, these functions are supported on the device: • PLIB_CMP_StopInIdleModeEnable • PLIB_CMP_StopInIdleModeDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsStopInIdle( CMP_MODULE_ID index ) Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 427 PLIB_CMP_ExistsOutputStatusGet Function Identifies whether the OutputStatusGet feature exists on the CMP module. File plib_cmp.h C bool PLIB_CMP_ExistsOutputStatusGet(CMP_MODULE_ID index); Returns • true - The OutputStatusGet feature is supported on the device • false - The OutputStatusGet feature is not supported on the device Description This function identifies whether the OutputStatusGet feature is available on the CMP module. When this function returns true, these functions are supported on the device: • PLIB_CMP_OutputStatusGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CMP_ExistsOutputStatusGet( CMP_MODULE_ID index ) d) Data Types and Constants CMP_CLOCK_DIVIDE Enumeration Defines Comparator Filter Clock Divide. File help_plib_cmp.h C typedef enum { CMP_FILTER_CLOCK_DIVIDE_1_1, CMP_FILTER_CLOCK_DIVIDE_1_2, CMP_FILTER_CLOCK_DIVIDE_1_4, CMP_FILTER_CLOCK_DIVIDE_1_8, CMP_FILTER_CLOCK_DIVIDE_1_16, CMP_FILTER_CLOCK_DIVIDE_1_32, CMP_FILTER_CLOCK_DIVIDE_1_64, CMP_FILTER_CLOCK_DIVIDE_1_128 } CMP_CLOCK_DIVIDE; Members Members Description CMP_FILTER_CLOCK_DIVIDE_1_1 Comparator Filter Clock Division is 1:1 CMP_FILTER_CLOCK_DIVIDE_1_2 Comparator Filter Clock Division is 1:2 CMP_FILTER_CLOCK_DIVIDE_1_4 Comparator Filter Clock Division is 1:4 CMP_FILTER_CLOCK_DIVIDE_1_8 Comparator Filter Clock Division is 1:8 CMP_FILTER_CLOCK_DIVIDE_1_16 Comparator Filter Clock Division is 1:16 Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 428 CMP_FILTER_CLOCK_DIVIDE_1_32 Comparator Filter Clock Division is 1:32 CMP_FILTER_CLOCK_DIVIDE_1_64 Comparator Filter Clock Division is 1:64 CMP_FILTER_CLOCK_DIVIDE_1_128 Comparator Filter Clock Division is 1:128 Description Comparator Filter Clock Divide Select This macro defines the Comparator filter clock divide. CMP_CVREF_BANDGAP_SELECT Enumeration Lists the band gap selection options. File help_plib_cmp.h C typedef enum { CMP_CVREF_BANDGAP_1_2V, CMP_CVREF_BANDGAP_0_6V, CMP_CVREF_BANDGAP_VREFPLUS } CMP_CVREF_BANDGAP_SELECT; Members Members Description CMP_CVREF_BANDGAP_1_2V Select the Band Gap Reference Source as 1.2 V CMP_CVREF_BANDGAP_0_6V Select the Band Gap Reference Source as 0.6 V CMP_CVREF_BANDGAP_VREFPLUS Select the Band Gap Reference Source as VREF Description CVREF band gap select enumeration This enumeration lists the possible band gap selection options. Remarks None. CMP_CVREF_REFERENCE_SELECT Enumeration Lists the reference selection options. File help_plib_cmp.h C typedef enum { CMP_CVREF_RESISTOR_LADDER_VOLTAGE, CMP_CVREF_POSITIVE_REFERENCE_VOLTAGE } CMP_CVREF_REFERENCE_SELECT; Members Members Description CMP_CVREF_RESISTOR_LADDER_VOLTAGE Select the Band Gap Reference Source as 1.2 V CMP_CVREF_POSITIVE_REFERENCE_VOLTAGE Select the Band Gap Reference Source as 0.6 V Description CVREF reference select enumeration This enumeration lists the possible reference selection options. Remarks None. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 429 CMP_CVREF_VALUE Enumeration Lists the voltage reference value selection options. File help_plib_cmp.h C typedef enum { CMP_CVREF_VALUE_0, CMP_CVREF_VALUE_1, CMP_CVREF_VALUE_2, CMP_CVREF_VALUE_3, CMP_CVREF_VALUE_4, CMP_CVREF_VALUE_5, CMP_CVREF_VALUE_6, CMP_CVREF_VALUE_7, CMP_CVREF_VALUE_8, CMP_CVREF_VALUE_9, CMP_CVREF_VALUE_10, CMP_CVREF_VALUE_11, CMP_CVREF_VALUE_12, CMP_CVREF_VALUE_13, CMP_CVREF_VALUE_14, CMP_CVREF_VALUE_15 } CMP_CVREF_VALUE; Members Members Description CMP_CVREF_VALUE_0 Voltage reference value 0 CMP_CVREF_VALUE_1 Voltage reference value 1 CMP_CVREF_VALUE_2 Voltage reference value 2 CMP_CVREF_VALUE_3 Voltage reference value 3 CMP_CVREF_VALUE_4 Voltage reference value 4 CMP_CVREF_VALUE_5 Voltage reference value 5 CMP_CVREF_VALUE_6 Voltage reference value 6 CMP_CVREF_VALUE_7 Voltage reference value 7 CMP_CVREF_VALUE_8 Voltage reference value 8 CMP_CVREF_VALUE_9 Voltage reference value 9 CMP_CVREF_VALUE_10 Voltage reference value 10 CMP_CVREF_VALUE_11 Voltage reference value 11 CMP_CVREF_VALUE_12 Voltage reference value 12 CMP_CVREF_VALUE_13 Voltage reference value 13 CMP_CVREF_VALUE_14 Voltage reference value 14 CMP_CVREF_VALUE_15 Voltage reference value 15 Description CVREF voltage reference value selection enumeration This enumeration lists the possible Voltage reference value selection options. Remarks None. CMP_CVREF_VOLTAGE_SOURCE Enumeration Lists the Voltage source options. File help_plib_cmp.h Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 430 C typedef enum { CMP_CVREF_VOLTAGE_SOURCE_INTERNAL, CMP_CVREF_VOLTAGE_SOURCE_EXTERNAL } CMP_CVREF_VOLTAGE_SOURCE; Members Members Description CMP_CVREF_VOLTAGE_SOURCE_INTERNAL Select VDD/VSS source CMP_CVREF_VOLTAGE_SOURCE_EXTERNAL Select external voltage source Description CVREF Voltage source selection enumeration This enumeration lists the possible Voltage source selection options. Remarks None. CMP_FILTER_CLOCK Enumeration Defines Comparator filter input clock File help_plib_cmp.h C typedef enum { CMP_FILTER_CLOCK_FP, CMP_FILTER_CLOCK_FOSC, CMP_FILTER_CLOCK_SYNCO1, CMP_FILTER_CLOCK_T2CLK, CMP_FILTER_CLOCK_T3CLK, CMP_FILTER_CLOCK_T4CLK, CMP_FILTER_CLOCK_T5CLK } CMP_FILTER_CLOCK; Members Members Description CMP_FILTER_CLOCK_FP FP will be the Comparator filter input clock CMP_FILTER_CLOCK_FOSC FOSC will be the Comparator filter input clock CMP_FILTER_CLOCK_SYNCO1 SYNCO1 will be the Comparator filter input clock CMP_FILTER_CLOCK_T2CLK T2CLK will be the Comparator filter input clock CMP_FILTER_CLOCK_T3CLK T3CLK will be the Comparator filter input clock CMP_FILTER_CLOCK_T4CLK T4CLK will be the Comparator filter input clock CMP_FILTER_CLOCK_T5CLK T5CLK will be the Comparator filter input clock Description Comparator Filter Input Clock Select This macro defines the Comparator filter input clock CMP_INTERRUPT_EVENT Enumeration Defines Comparator interrupt events. File help_plib_cmp.h C typedef enum { CMP_INTERRUPT_GENERATION_DISABLED } CMP_INTERRUPT_EVENT; Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 431 Members Members Description CMP_INTERRUPT_GENERATION_DISABLED Select VDD/VSS source Description Comparator interrupt event Select This macro defines the Comparator interrupt events. CMP_INVERTING_INPUT Enumeration Defines the list of Comparator inverting Input. File help_plib_cmp.h C typedef enum { CMP_INVERTING_INPUT_EXTERNAL_PIN_B, CMP_INVERTING_INPUT_EXTERNAL_PIN_C, CMP_INVERTING_INPUT_EXTERNAL_PIN_D, CMP_INVERTING_INPUT_EXTERNAL_NEGATIVE_PIN, CMP_INVERTING_INPUT_EXTERNAL_POSITIVE_PIN, CMP_INVERTING_INPUT_OTHER_MODULE_EXTERNAL_POSITIVE_PIN, CMP_INVERTING_INPUT_IVREF, CMP_INPUT_C2IN_NEGATIVE, CMP_INPUT_C2IN_POSITIVE, CMP_INPUT_C1IN_POSITIVE, CMP_INPUT_IVREF } CMP_INVERTING_INPUT; Members Members Description CMP_INVERTING_INPUT_EXTERNAL_PIN_B Select external voltage source at pin CxINB as inverting input. If using CMP_ID_1 , this pin is C1INB CMP_INVERTING_INPUT_EXTERNAL_PIN_C Select external voltage source at pin CxINC as inverting input CMP_INVERTING_INPUT_EXTERNAL_PIN_D Select external voltage source at pin CxIND as inverting input CMP_INVERTING_INPUT_EXTERNAL_NEGATIVE_PIN Select external voltage source at pin CxIN- as inverting input CMP_INVERTING_INPUT_EXTERNAL_POSITIVE_PIN Select external voltage source at pin CxIN+ as inverting input. If using CMP_ID_1 , this pin is C1IN+ CMP_INVERTING_INPUT_OTHER_MODULE_EXTERNAL_POSITIVE_PIN Select external voltage source at pin CyIN+ as inverting input. If using CMP_ID_1 , this pin is C2IN+. If using CMP_ID_2 , this pin is C1IN+ CMP_INVERTING_INPUT_IVREF Select internal voltage ,VDD/VSS source as inverting input CMP_INPUT_C2IN_NEGATIVE The member is obsolete and maintained here only for the backward compatibility. CMP_INPUT_C2IN_POSITIVE The member is obsolete and maintained here only for the backward compatibility. CMP_INPUT_C1IN_POSITIVE The member is obsolete and maintained here only for the backward compatibility. CMP_INPUT_IVREF The member is obsolete and maintained here only for the backward compatibility. Description Comparator inverting input channel select This macro defines the super set of Comparator inverting Inputs. Not all options will be available on all microcontrollers. Refer to the processor header for the specific controller in use to determine which options are supported. CMP_MASK_A Enumeration Defines Comparator Mask A Input. Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 432 File help_plib_cmp.h C typedef enum { CMP_MASK_A_PWM1L, CMP_MASK_A_PWM1H, CMP_MASK_A_PWM2L, CMP_MASK_A_PWM2H, CMP_MASK_A_PWM3L, CMP_MASK_A_PWM3H, CMP_MASK_A_PTGO18, CMP_MASK_A_PTGO19, CMP_MASK_A_FLT2, CMP_MASK_A_FLT4 } CMP_MASK_A; Members Members Description CMP_MASK_A_PWM1L PWM1L will be the Comparator Mask A input CMP_MASK_A_PWM1H PWM1H will be the Comparator Mask A input CMP_MASK_A_PWM2L PWM2L will be the Comparator Mask A input CMP_MASK_A_PWM2H PWM2H will be the Comparator Mask A input CMP_MASK_A_PWM3L PWM3L will be the Comparator Mask A input CMP_MASK_A_PWM3H PWM3H will be the Comparator Mask A input CMP_MASK_A_PTGO18 PTGO18 will be the Comparator Mask A input CMP_MASK_A_PTGO19 PTGO19 will be the Comparator Mask A input CMP_MASK_A_FLT2 FLT2 will be the Comparator Mask A input CMP_MASK_A_FLT4 FLT4 will be the Comparator Mask A input Description Comparator Mask A Input Select This macro defines the Comparator Mask A Input. CMP_MASK_B Enumeration Defines Comparator Mask B Input. File help_plib_cmp.h C typedef enum { CMP_MASK_B_PWM1L, CMP_MASK_B_PWM1H, CMP_MASK_B_PWM2L, CMP_MASK_B_PWM2H, CMP_MASK_B_PWM3L, CMP_MASK_B_PWM3H, CMP_MASK_B_PTGO18, CMP_MASK_B_PTGO19, CMP_MASK_B_FLT2, CMP_MASK_B_FLT4 } CMP_MASK_B; Members Members Description CMP_MASK_B_PWM1L PWM1L will be the Comparator Mask B input CMP_MASK_B_PWM1H PWM1H will be the Comparator Mask B input CMP_MASK_B_PWM2L PWM2L will be the Comparator Mask B input CMP_MASK_B_PWM2H PWM2H will be the Comparator Mask B input CMP_MASK_B_PWM3L PWM3L will be the Comparator Mask B input Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 433 CMP_MASK_B_PWM3H PWM3H will be the Comparator Mask B input CMP_MASK_B_PTGO18 PTGO18 will be the Comparator Mask B input CMP_MASK_B_PTGO19 PTGO19 will be the Comparator Mask B input CMP_MASK_B_FLT2 FLT2 will be the Comparator Mask B input CMP_MASK_B_FLT4 FLT4 will be the Comparator Mask B input Description Comparator Mask B Input Select This macro defines the Comparator Mask B Input. CMP_MASK_C Enumeration Defines Comparator Mask C Input. File help_plib_cmp.h C typedef enum { CMP_MASK_C_PWM1L, CMP_MASK_C_PWM1H, CMP_MASK_C_PWM2L, CMP_MASK_C_PWM2H, CMP_MASK_C_PWM3L, CMP_MASK_C_PWM3H, CMP_MASK_C_PTGO18, CMP_MASK_C_PTGO19, CMP_MASK_C_FLT2, CMP_MASK_C_FLT4 } CMP_MASK_C; Members Members Description CMP_MASK_C_PWM1L PWM1L will be the Comparator mask C input CMP_MASK_C_PWM1H PWM1H will be the Comparator mask C input CMP_MASK_C_PWM2L PWM2L will be the Comparator mask C input CMP_MASK_C_PWM2H PWM2H will be the Comparator mask C input CMP_MASK_C_PWM3L PWM3L will be the Comparator mask C input CMP_MASK_C_PWM3H PWM3H will be the Comparator mask C input CMP_MASK_C_PTGO18 PTGO18 will be the Comparator mask C input CMP_MASK_C_PTGO19 PTGO19 will be the Comparator mask C input CMP_MASK_C_FLT2 FLT2 will be the Comparator mask C input CMP_MASK_C_FLT4 FLT4 will be the Comparator mask C input Description Comparator Mask C Input Select This macro defines the Comparator Mask C Input. CMP_MODULE_ID Enumeration Identifies the Comparator modules supported File help_plib_cmp.h C typedef enum { CMP_ID_1, CMP_ID_2, CMP_ID_3 } CMP_MODULE_ID; Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 434 Members Members Description CMP_ID_1 Comparator Module 1 ID CMP_ID_2 Comparator Module 2 ID CMP_ID_3 Comparator Module 3 ID Description Comparator Module ID This enumeration identifies the Comparator modules which are available on the microcontroller. This is the super set of all the possible instances that might be available on the Microchip microcontrollers. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. CMP_NON_INVERTING_INPUT Enumeration Defines the list of Comparator non-inverting Input. File help_plib_cmp.h C typedef enum { CMP_NON_INVERTING_INPUT_EXTERNAL_PIN_A, CMP_NON_INVERTING_INPUT_EXTERNAL_POSITIVE_PIN, CMP_NON_INVERTING_INPUT_CVREF, CMP_INPUT_C2IN_POSITIVE, CMP_INPUT_INTERNAL_CVREF } CMP_NON_INVERTING_INPUT; Members Members Description CMP_NON_INVERTING_INPUT_EXTERNAL_PIN_A Select external voltage source at pin CxINA as non-inverting input CMP_NON_INVERTING_INPUT_EXTERNAL_POSITIVE_PIN Select external voltage source at pin CxIN+ as non-inverting input CMP_NON_INVERTING_INPUT_CVREF Select internal voltage source CVREF as non-inverting input CMP_INPUT_C2IN_POSITIVE The member is obsolete and maintained here only for the backward compatibility. CMP_INPUT_INTERNAL_CVREF The member is obsolete and maintained here only for the backward compatibility. Description Comparator Non inverting input channel select This macro defines the super set of Comparator non-inverting Inputs. Not all options will be available on all microcontrollers. Refer to the processor header for the specific controller in use to determine which options are supported. CMP_SPEED_POWER Enumeration Defines the Speed/Power of the Comparator File help_plib_cmp.h C typedef enum { CMP_SPEED_POWER_LOWER, CMP_SPEED_POWER_HIGHER } CMP_SPEED_POWER; Peripheral Libraries Help Comparator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 435 Members Members Description CMP_SPEED_POWER_LOWER Comparator low-power, low-speed CMP_SPEED_POWER_HIGHER Comparator normal power, higher speed Description Comparator Speed/Power Select This macro defines the Speed/Power of the Comparator. Files Files Name Description plib_cmp.h Comparator Peripheral Library Interface Header for Comparator module definitions. help_plib_cmp.h Description This section lists the source and header files used by the library. plib_cmp.h Comparator Peripheral Library Interface Header for Comparator module definitions. Functions Name Description PLIB_CMP_CVREF_BandGapReferenceSourceSelect Selects the band gap reference voltage source. PLIB_CMP_CVREF_Disable Disables the voltage reference of the Comparator module. PLIB_CMP_CVREF_Enable Enables the voltage reference of the Comparator module. PLIB_CMP_CVREF_OutputDisable Disables the output voltage. PLIB_CMP_CVREF_OutputEnable Enables the voltage output. PLIB_CMP_CVREF_ReferenceVoltageSelect Selects the voltage reference value, CVref. PLIB_CMP_CVREF_SourceNegativeInputSelect Configures the Comparator module to use the selected input as a negative reference. PLIB_CMP_CVREF_SourceVoltageSelect Connects the Comparator module to the selected voltage source. PLIB_CMP_CVREF_ValueSelect Selects the voltage reference value. PLIB_CMP_CVREF_WideRangeDisable Disables the wide range. PLIB_CMP_CVREF_WideRangeEnable Enables the wide range. PLIB_CMP_CVREF_WideRangeIsEnabled Returns whether the wide range is selected for the reference voltage. PLIB_CMP_Disable Disables the Comparator module. PLIB_CMP_Enable Enables the Comparator module. PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect Identifies whether the CVREFBGRefVoltageRangeSelect feature exists on the CMP module. PLIB_CMP_ExistsCVREFEnableControl Identifies whether the CVREFEnableControl feature exists on the CMP module. PLIB_CMP_ExistsCVREFOutputEnableControl Identifies whether the CVREFOutputEnableControl feature exists on the CMP module. PLIB_CMP_ExistsCVREFRefVoltageRangeSelect Identifies whether the CVREFRefVoltageRangeSelect feature exists on the CMP module. PLIB_CMP_ExistsCVREFValueSelect Identifies whether the CVREFValueSelect feature exists on the CMP module. PLIB_CMP_ExistsCVREFVoltageRangeSelect Identifies whether the CVREFVoltageRangeSelect feature exists on the CMP module. PLIB_CMP_ExistsCVREFWideRangeControl Identifies whether the CVREFWideRangeControl feature exists on the CMP module. PLIB_CMP_ExistsEnableControl Identifies whether the ComparatorEnableControl feature exists on the CMP module. Peripheral Libraries Help Comparator Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 436 PLIB_CMP_ExistsInterruptEventSelect Identifies whether the InterruptEventSelect feature exists on the CMP module. PLIB_CMP_ExistsInvertingInputSelect Identifies whether the InvertingInputSelect feature exists on the CMP module. PLIB_CMP_ExistsInvertOutputControl Identifies whether the InvertOutputSelectControl feature exists on the CMP module. PLIB_CMP_ExistsNonInvertingInputSelect Identifies whether the NonInvertingInputSelect feature exists on the CMP module. PLIB_CMP_ExistsOutputEnableControl Identifies whether the ComparatorOutputEnableControl feature exists on the CMP module. PLIB_CMP_ExistsOutputLevelControl Identifies whether the OutputLevelSelectControl feature exists on the CMP module. PLIB_CMP_ExistsOutputStatusGet Identifies whether the OutputStatusGet feature exists on the CMP module. PLIB_CMP_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the CMP module. PLIB_CMP_InterruptEventSelect Comparator interrupt event select. PLIB_CMP_InvertingInputChannelSelect Comparator inverting input channel select. PLIB_CMP_NonInvertingInputChannelSelect Comparator input channel select. PLIB_CMP_OutputDisable Disables the Comparator output. PLIB_CMP_OutputEnable Enables the Comparator output. PLIB_CMP_OutputInvertDisable Comparator output is non-inverted. PLIB_CMP_OutputInvertEnable Comparator output is inverted. PLIB_CMP_OutputLogicHigh Comparator output bit will give a 'logic high' on satisfying the input condition. PLIB_CMP_OutputLogicLow Comparator will be set to give 'logic low' on satisfying the input condition. PLIB_CMP_OutputStatusGet Comparator output status. PLIB_CMP_StopInIdleModeDisable Disables Stop in Idle mode. PLIB_CMP_StopInIdleModeEnable Enables Stop in Idle mode. Description Comparator Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Comparator Peripheral Library for all families of Microchip microcontrollers. The definitions in this file are common to the Comparator peripheral. File Name plib_cmp.h Company Microchip Technology Inc. help_plib_cmp.h Enumerations Name Description CMP_CLOCK_DIVIDE Defines Comparator Filter Clock Divide. CMP_CVREF_BANDGAP_SELECT Lists the band gap selection options. CMP_CVREF_REFERENCE_SELECT Lists the reference selection options. CMP_CVREF_VALUE Lists the voltage reference value selection options. CMP_CVREF_VOLTAGE_SOURCE Lists the Voltage source options. CMP_FILTER_CLOCK Defines Comparator filter input clock CMP_INTERRUPT_EVENT Defines Comparator interrupt events. CMP_INVERTING_INPUT Defines the list of Comparator inverting Input. CMP_MASK_A Defines Comparator Mask A Input. CMP_MASK_B Defines Comparator Mask B Input. CMP_MASK_C Defines Comparator Mask C Input. CMP_MODULE_ID Identifies the Comparator modules supported CMP_NON_INVERTING_INPUT Defines the list of Comparator non-inverting Input. CMP_SPEED_POWER Defines the Speed/Power of the Comparator Peripheral Libraries Help Comparator Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 437 CTMU Peripheral Library This section describes the Charge Time Measurement Unit (CTMU) Library. Introduction Charge Time Measurement Unit (CTMU) for Microchip Microcontrollers This library provides a low-level abstraction of Charge Time Measurement Unit (CTMU) features. It provides a convenient C language interface, allowing the easy construction of CTMU code that can function across the full range of Microchip devices with CTMU modules. Description The CTMU is a flexible analog module that has a configurable current source with a digital configuration circuit built around it. Using its high precision current source the CTMU can support: • Pulse timing measurements - pulse to pulse, high pulse width, and low pulse width - using an on-chip ADC • Pulse regeneration with delays • Temperature measurement (on devices with a temperature diode) using an on-chip ADC • Capacitance measurement - capacitive touch, and capacitive sensor support - using an on-chip ADC The CTMU module has the following features: • On-chip precision current source with four ranges and trimmable output • Current source controllable by software or external triggers • Up to 32 input channels supported (ADC inputs) • Up to 16 sources for triggering • Level sensitive triggering with edge triggering available on some devices • Control of triggering polarity and direction • Two trigger channels with control of trigger sequence • Time measurement resolution of 1 nanosecond • Provides ADC capture strobe to automatically initiate ADC voltage measurements Using the Library This topic describes the basic architecture of the CTMU Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_can.h The interface to the CTMU Peripheral library is defined in the plib_can.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the CTMU Peripheral library must include peripheral.h. Library File: The CTMU Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the peripheral interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the CTMU module on Microchip microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The following figure shows a block diagram of the CTMU module, focusing on CTMU function rather than the bits in the interface: Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 438 The CTMU is built around a high precision current source (i.e., charge pump) and is closely integrated with the device's on-chip Analog-to-Digital Converter (ADC) module and an on-chip Comparator module. The ADC converts the voltage carried by the Sample and Hold (S&H) capacitor into a digital number representing ADC counts. These counts can be converted into a voltage and the voltage used by the embedded application. The Comparator module associated with the CTMU can compare the voltage on an external capacitor with a known voltage and output when the voltages match. See the Example Applications section, for details of these applications. In the previous block diagram, an analog multiplexer (MUX) controls where the charge pump sends current. This multiplexer is controlled by the CTMU's mode (Normal versus Pulse Generation) and edge status, as shown by the look-up table. In Normal mode, current is switched between the on-chip temperature sensor (CTMUT path) and the ADC's S&H capacitor (CTMUI path). In the Pulse Generation mode, current is switched on and off over the CTMUP path, with the "on" current going to the negative input of the associated comparator and its special input pin, labeled "Comparator Input/ANx" in the diagram. External triggers can be used to start and stop the charge pump using up to 16 edge sources. The charge pump is also controlled by manipulating two edge status bits in software. The block labeled Edge Control Logic determines the edge status based on the selected edge sources and edge control settings. Basically, current is off if the edges are equal, and on if the edges are unequal. In other words, Current (on/off) = Edge 1 XOR Edge 2. Sources can trigger an edge in the control logic based on levels or transitions and can trigger going high-low or low-high. The order of edge events can be controlled, with Edge 1 always occurring before Edge 2, or edge events can occur in any order. The Ground? control signal created by the CTMU Control Logic block enables the grounding of the CTMUI path, connecting the charge pump and the ADC's S&H capacitor. This is done before starting any capacitance or timing measurement to make sure there is no residual charge on the ADC's Sample and Hold capacitor and on any external capacitor, such as a button. To discharge the ADC's Sample and Hold capacitor the ADC must be sampling the input voltage (i.e., the switch before the S&H capacitor is closed). This is normally done by manually starting ADC sampling using the "Sampling" bit in one the ADC's control registers. In Normal mode, current flows from the charge pump to the ADC via the CTMUI path. Current flows to external capacitors (such as button capacitors) through the ADC's analog input multiplexer. The ADC input multiplexer has a special input signal, named "Open", which does not_connect_anything to the ADC's input. This minimizes stray capacitance and provides the smallest internal capacitance for very fast time measurements. In Pulse Generation mode, current flows directly to a special comparator/analog input pin via the CTMUP path, bypassing the ADC's input Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 439 multiplexer and its approximately 2500 ohm series resistance. This extra series resistance is why the charge pump should only be calibrated in Pulse Generation mode, as shown in the block diagram. Except in the lowest current settings, this series resistance causes an error that is too large in the overall calibration resistance value to provide useable charge pump current measurements. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the CTMU module. Library Interface Section Description CTMU Control Functions These functions can be used to enable, disable, and set CTMU features. Edge Control and Status Functions These functions can be used to configure CTMU edge control and status. Feature Existence Functions These functions can be used to determine whether or not a particular feature is available on the device. How the Library Works This section describes how the CTMU Peripheral Library works. Description The CTMU is a simple analog module, built around a high precision charge pump. The focus of the CTMU peripheral library is controlling the output of the charge pump and interfacing with the CTMU's associated on-chip ADC. The block diagram of the CTMU module is repeated here for reference. Next, we will discuss library primitives by functional group, starting with simple things such as turning the module on or off, and then proceeding to more complicated topics such as edge control. Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 440 CTMU On/Off and Reset These features are controlled by these functions: void PLIB_CTMU_Enable ( CTMU_MODULE_ID ctmu_id ) void PLIB_CTMU_Disable ( CTMU_MODULE_ID ctmu_id ) void PLIB_CTMU_PORDefaultsRestore ( CTMU_MODULE_ID ctmu_id ) The parameter ctmu_id identifies which CTMU module is referenced. Since all currently available devices only have a single CTMU, this parameter is primarily in support of future expansion. Operation in Idle Mode The CTMU can stop operating in Idle mode or operate when the chip is in Idle mode depending on: void PLIB_CTMU_StopInIdleEnable( CTMU_MODULE_ID ctmu_id ) void PLIB_CTMU_StopInIdleDisable( CTMU_MODULE_ID ctmu_id ) Current Source Charge pump output is controlled by a current range, and then a trim off of the nominal current of each of four current ranges. These functions control current range and current trim: void PLIB_CTMU_CurrentTrimSet( CTMU_MODULE_ID ctmu_id, signed short current_trim ) void PLIB_CTMU_CurrentRangeSet( CTMU_MODULE_ID ctmu_id, CTMU_CURRENT_RANGE current_range ) Current is shut off by grounding the charge pump or manipulating the status of two trigger edges, as shown previously. Edge status can be directly controlled in software or determined by two input signals. The charge pump is grounded or not grounded using: void PLIB_CTMU_CurrentSourceGrounded( CTMU_MODULE_ID ctmu_id ) void PLIB_CTMU_CurrentSourceNotGrounded( CTMU_MODULE_ID ctmu_id ) Edge Control The CTMU can use from four to 16 different sources to provide on and off triggers for the charge pump. How a source changes edge status is completely controlled. Edges can trigger on source signals going high-to-low or low-to-high. On some devices, source signal transitions can also trigger an edge. On these devices triggers can occur on for both high-low transitions and low-high transitions. The CTMU can require an edge sequence, with Edge 1 triggering before Edge 2 triggers, or can respond to either Edge 1 or Edge 2 in any order. After edge sources have caused the charge pump to start and then stop, edge status must be reset by software before the CTMU can respond to edge sources again. All CTMU edge control functions start with "PLIB_CTMU_Edge". Each type of control function is discussed in the following section. Control of the CTMU charge pump by the edges is enabled/disabled by: void PLIB_CTMU_EdgeEnable(CTMU_MODULE_ID ctmu_id) void PLIB_CTMU_EdgeDisable(CTMU_MODULE_ID ctmu_id) Even with edges disabled (the default setting after POR) the charge pump can be controlled in software by setting and clearing the module's edge status bits using: void PLIB_CTMU_EdgeStatusGotEdgeSet(CTMU_MODULE_ID ctmu_id, CTMU_EDGE_NUM edge_number) void PLIB_CTMU_EdgeStatusNoEdgeSet(CTMU_MODULE_ID ctmu_id, CTMU_EDGE_NUM edge_number) Since there are two edges and the charge pump is turned on when the edge status is unequal, there are two ways of turning the charge pump on/off in software. The first way is to leave one edge set to its POR default (off) and to manipulate the other status. Typically, Edge 1 is modified and Edge 2 is untouched, as shown in this code example: PLIB_CTMU_EdgeStatusGotEdgeSet( CTMU_ID_1, CTMU_Edge1 ); // Start charging button // TO DO: Charge Delay PLIB_CTMU_EdgeStatusNoEdgeSet( CTMU_ID_1, CTMU_Edge1 ); // Stop charging button The other way of turning the charge pump on/off in software mimics what happens when using external sources for edge signals. One edge is set to turn the charge pump on and then the other edge is set to turn the charge pump off: PLIB_CTMU_EdgeStatusGotEdgeSet( CTMU_ID_1, CTMU_Edge1 ); // Start charging button // TO DO: Charge Delay PLIB_CTMU_EdgeStatusGotEdgeSet( CTMU_ID_1, CTMU_Edge2 ); // Stop charging button To reset edge status for the next measurement you must clear both edges at the same time: void PLIB_CTMU_EdgeStatusNoEdgesAllSet(CTMU_MODULE_ID ctmu_id) (To use two calls to PLIB_CTMU_EdgeStatusSetNoEdge would cause the charge pump to pulse between the first call and the second call because in between the status would not be equal, thus enabling the charge pump again.) Edges can fire based on edges (i.e., transitions) or levels (POR default): void PLIB_CTMU_EdgeModeEdgeSensitiveSet(CTMU_MODULE_ID ctmu_id, CTMU_EDGE_NUM edge_number) void PLIB_CTMU_EdgeModeLevelSensitiveSet(CTMU_MODULE_ID ctmu_id, CTMU_EDGE_NUM edge_number) You can also determine whether a low-to-high change triggers an edge: void PLIB_CTMU_EdgePolarityPositiveSet(CTMU_MODULE_ID ctmu_id, CTMU_EDGE_NUM edge_number) Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 441 or whether a high-to-low change triggers an edge: void PLIB_CTMU_EdgePolarityNegativeSet(CTMU_MODULE_ID ctmu_id, CTMU_EDGE_NUM edge_number) If Edge 1 turns on the charge pump and Edge 2 turns it off, you must call: void PLIB_CTMU_EdgeSequenceEnable(CTMU_MODULE_ID ctmu_id) in setting up the CTMU. This feature can be disabled to reinstate the POR default behavior using: void PLIB_CTMU_EdgeSequenceDisable(CTMU_MODULE_ID ctmu_id) With edge sequencing disabled, either edge can be used to control the charge pump. Finally, the choice of signals for both edges is controlled by: void PLIB_CTMU_EdgeSourceSelect(CTMU_MODULE_ID ctmu_id, CTMU_EDGE_NUM edge_number, CTMU_EDGE_SOURCE edge_source) Current Output Control As shown in the previous block diagram, where the charge pump current goes is controlled by he CTMU mode as well as the edge status. Whether the CTMU is in capacitance/time or time pulse generation mode is controlled by: void PLIB_CTMU_TimePulseGenEnable( CTMU_MODULE_ID ctmu_id ) void PLIB_CTMU_TimePulseGenDisable( CTMU_MODULE_ID ctmu_id ) As shown in the previous block diagram, when the CTMU is in capacitance/time (normal) mode the charge pump runs when Edge 1 Status != Edge 2 Status and stops when Edge 1 Status = Edge 2 Status. (Actually what happens is the charge pump switches from the ADC S&H capacitor to the on-chip temperature diode (if available), but the effect is the same, charge stops flowing.) In pulse generation mode, the charge pump switches to a "no_connect" when Edge 1 Status = Edge 2 Status and is connected to CTMUP when Edge 1 Status != Edge 2 Status. The CTMU charge pump can be manually turned on by the call: PLIB_CTMU_EdgeStatusGotEdgeSet( CTMU_ID_1, PLIB_CTMU_Edge1 ); and turned off by the call: PLIB_CTMU_EdgeStatusNoEdgeSet( CTMU_ID_1, PLIB_CTMU_Edge1 ); assuming that Edge 2 status is "NoEdge". Interface with the ADC Absolute and relative capacitance measurements, as well as pulse timing measurements, require using the associated on-chip ADC to measure the resulting voltage across an ADC input pin. ADC conversion can be triggered by a special ADC trigger strobe signal between the CTMU and ADC modules. The ADC trigger strobe fires when the charge pump changes from running to stopped. Temperature measurements by the ADC involve switching the ADC to a special (internal) input pin attached to the voltage diode. The ADC trigger strobe is controlled by: void PLIB_CTMU_ADCTriggerEnable( CTMU_MODULE_ID ctmu_id ) void PLIB_CTMU_ADCTriggerDisable( CTMU_MODULE_ID ctmu_id ) Power On Reset (POR) Status The CTMU after a power on reset (POR) has its features configured as follows: PLIB_CTMU_Disable(CTMU_ID_1); // Turn CTMU off PLIB_CTMU_EdgeModeLevelSensitiveSet(CTMU_ID_1,CTMU_Edge1); PLIB_CTMU_EdgeModeLevelSensitiveSet(CTMU_ID_1,CTMU_Edge2); PLIB_CTMU_EdgePolarityNegativeSet(CTMU_ID_1,CTMU_Edge1); PLIB_CTMU_EdgePolarityNegativeSet(CTMU_ID_1,CTMU_Edge2); PLIB_CTMU_EdgeSourceSelect(CTMU_ID_1,CTMU_Edge1,CTMU_EdgeSource_0); PLIB_CTMU_EdgeSourceSelect(CTMU_ID_1,CTMU_Edge2,CTMU_EdgeSource_0); PLIB_CTMU_EdgeStatusNoEdgesAllSet(CTMU_ID_1); PLIB_CTMU_StopInIdleDisable(CTMU_ID_1); // Continue CTMU operation in Idle mode PLIB_CTMU_TimePulseGenDisable(CTMU_ID_1); // Capacitance/time measurement PLIB_CTMU_EdgeDisable(CTMU_ID_1); // Edges are blocked PLIB_CTMU_EdgeSequenceDisable(CTMU_ID_1); // Edges can fire in any order PLIB_CTMU_CurrentSourceNotGrounded(CTMU_ID_1); PLIB_CTMU_ADCTriggerDisable(CTMU_ID_1); PLIB_CTMU_CurrentTrimSet(CTMU_ID_1,0); PLIB_CTMU_CurrentRangeSet(CTMU_ID_1,CTMU_CurrentRangeBase_1000xBase); All of these functions can be accomplished by a single call to PLIB_CTMU_PORDefaultsRestore(CTMU_ID_1); Device-to-Device Variations Some devices do not have an on-chip temperature diode. Some devices only support edge triggering based on source signal levels rather than transitions. For these devices the function PLIB_CTMU_EdgeModeSetEdgeSensitive does not apply. The number of possible edge sources varies from device to device. Some have only four possible sources for Edge 1 and Edge 2. Other devices support up to 16 possible sources. Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 442 Refer to the "Charge Time Measurement Unit (CTMU)" chapter in the specific device data sheet for more information. CTMU Setup This section provides the CTMU setup sequence. Description The following sequence is a general guideline used to initialize the CTMU module: 1. Reset the CTMU back to POR defaults. (This step isn't necessary if the CTMU is not being reconfigured.) 2. Select the current source range. 3. Adjust the current source trim. 4. Select the operating mode (Normal or Pulse Generation). (If you are using the Comparator Input/ANx pin, you must use the Pulse Generation Mode; otherwise, use the Normal mode). 5. Clear the Edge Status bits. 6. Optional setups: • Clear the CTMU interrupt flag. • Configure the ADC to trigger on the CTMU's strobe. • Configure button/key circuit pins to be ADC inputs. • Configure the ADC input multiplexer to point to the first button/key pin. • Turn on the ADC module. 7. Turn on the CTMU module and wait 50 microseconds for the charge pump to stabilize. 8. Discharge the connected circuit by grounding the charge pump. (If using the ADC, enable ADC sampling to_connect_S&H capacitor to ground.) // 1. Reset CTMU back to POR defaults PLIB_CTMU_RestorePORDefaults(CTMU_ID_1); // POR defaults, turn CTMU off // 2. Select the current source range. PLIB_CTMU_CurrentRangeSet(CTMU_ID_1,CTMU_CurrentRangeBase_Base); // 3. Adjust the current source trim. PLIB_CTMU_CurrentTrimSet(CTMU_ID_1,10); // increase by 20% // 4. Select the operating mode (Normal or Pulse Generation) PLIB_CTMU_TimePulseGenDisable(CTMU_ID_1); // 5. Clear the Edge Status bits PLIB_CTMU_EdgeStatusSetAllNoEdges(CTMU_ID_1); // 6. Optional setups // Clear CTMU interrupt flag // Configure ADC to trigger on CTMU strobe // Configure button/key circuit pins to be ADC inputs // Configure ADC input multiplexer to point to first button/key pin // Turn on the ADC // 7. Turn on the CTMU module, wait 50 us for charge pump to stabilize PLIB_CTMU_Enable(CTMU_ID_1); // TO DO: Wait 50 microseconds // 8. Discharge the connected circuit by grounding the charge pump. PLIB_CTMU_CurrentSourceGrounded(CTMU_ID_1); // TO DO: Enable ADC sampling // TO DO: Wait for discharge to occur General Setup The following sequence is a general guideline used to initialize the CTMU module: 1. Reset CTMU back to POR defaults. (This step isn't necessary if the CTMU is not being reconfigured.) 2. Select the current source range. 3. Adjust the current source trim. 4. Select the operating mode (Normal or Pulse Generation). (If you are using the Comparator Input/ANx pin then you must use the Pulse Generation Mode, otherwise, use the Normal mode). 5. Clear the Edge Status bits. 6. Optional setups: Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 443 • Clear CTMU interrupt flag. • Configure ADC to trigger on CTMU strobe. • Configure button/key circuit pins to be ADC inputs. • Configure ADC input multiplexer to point to first button/key pin. • Turn on the ADC module. 7. Turn on the CTMU module, wait 50 microseconds for charge pump to stabilize. 8. Discharge the connected circuit by grounding the charge pump. (If using the ADC, enable ADC sampling to connect S&H capacitor to ground.) // 1. Reset CTMU back to POR defaults PLIB_CTMU_PORDefaultsRestore(CTMU_ID_1); // POR defaults, turn CTMU off // 2. Select the current source range. PLIB_CTMU_CurrentRangeSet(CTMU_ID_1,CTMU_CurrentRangeBase_Base); // 3. Adjust the current source trim. PLIB_CTMU_CurrentTrimSet(CTMU_ID_1,10); // increase by 20% // 4. Select the operating mode (Normal or Pulse Generation) PLIB_CTMU_TimePulseGenDisable(CTMU_ID_1); // 5. Clear the Edge Status bits PLIB_CTMU_EdgeStatusNoEdgesAllSet(CTMU_ID_1); // 6. Optional setups // Clear CTMU interrupt flag // Configure ADC to trigger on CTMU strobe // Configure button/key circuit pins to be ADC inputs // Configure ADC input multiplexer to point to first button/key pin // Turn on the ADC // 7. Turn on the CTMU module, wait 50 us for charge pump to stabilize PLIB_CTMU_Enable(CTMU_ID_1); // TO DO: Wait 50 microseconds // 8. Discharge the connected circuit by grounding the charge pump. PLIB_CTMU_CurrentSourceGrounded(CTMU_ID_1); // TO DO: Enable ADC sampling // TO DO: Wait for discharge to occur Measuring Time Between Pulses This section describes the process for measuring time between pulses. Description To measure the time between rising edges of two input signals, first calibrate the CTMU charge pump, using a calibration resistor on the Comparator/ANx input pin. Then replace the resistor with a calibrated capacitor of the correct size for the expected time delay and desired charge pump settings (charge range and trim). Do the following to set up the CTMU for these measurements: 1. Reset the CTMU back to its POR defaults. (This step isn't necessary if the CTMU is not being reconfigured.) 2. Select the current source range. 3. Adjust the current source trim. 4. Select the Pulse Generation generation. 5. Clear the Edge Status bits. 6. Select the input source for each edge. 7. Configure each edge to trigger on a rising edge. 8. Enable edge sequencing so Edge 1 occurs before Edge 2. 9. Enable edges to control the charge pump. 10. Turn on the CTMU module then wait 50 us for charge pump to stabilize. 11. Discharge the connected circuit by grounding the charge pump. (If using the ADC, enable ADC sampling to_connect_sample and hold capacitor to ground.) // 1. Reset CTMU back to POR defaults PLIB_CTMU_PORDefaultsRestore(CTMU_ID_1); // POR defaults, turn CTMU off // 2. Select the current source range. PLIB_CTMU_CurrentRangeSet(CTMU_ID_1,CTMU_CurrentRangeBase_Base); Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 444 // 3. Adjust the current source trim. PLIB_CTMU_CurrentTrimSet(CTMU_ID_1,+10); // increase by 20% = +10 * 2% // 4. Select the operating mode (Pulse Generation) PLIB_CTMU_TimePulseGenEnable(CTMU_ID_1); // Use Comparator Input/ANx pin // 5. Clear the Edge Status bits PLIB_CTMU_EdgeStatusNoEdgesAllSet(CTMU_ID_1); // 6. Configure the edge input sources for Edge 1 and Edge 2. PLIB_CTMU_EdgeSourceSelect(CTMU_ID_1,CTMU_Edge1,CTMU_EdgeSource_0); PLIB_CTMU_EdgeSourceSelect(CTMU_ID_1,CTMU_Edge2,CTMU_EdgeSource_1); // 7. Configure the input polarities: PLIB_CTMU_EdgePolarityPositiveSet(CTMU_ID_1,CTMU_Edge1); // Trigger on Rising Edge PLIB_CTMU_EdgePolarityPositiveSet(CTMU_ID_1,CTMU_Edge2); // Trigger on Rising Edge // 8. Enable edge sequencing so Edge1 (rising) occurs before Edge 2 (rising) PLIB_CTMU_EdgeSequenceEnable(CTMU_ID_1); // 9. Enable edges to control charge pump PLIB_CTMU_EdgeEnable(CTMU_ID_1); // 10. Turn on the CTMU module, wait 50 us for charge pump to stabilize PLIB_CTMU_Enable(CTMU_ID_1); // TO DO: Wait 50 microseconds // 11. Discharge the connected circuit by grounding the charge pump. PLIB_CTMU_CurrentSourceGrounded(CTMU_ID_1); // TO DO: Enable ADC sampling // TO DO: Wait for discharge to occur The time between the rising edge of each pulse is given by: Time = ( Capacitance * (VDD * ADC_Count / MaxADCCount) ) / Current Measuring Pulse Width This section describes the process for measuring pulse width. Description Measuring the pulse width of a single input is similar to measuring the time between two pulses. The only difference is that the same signal is used for both edges and Edge 2 is triggered on a falling edge rather than a rising edge. // 1. Reset CTMU back to POR defaults PLIB_CTMU_PORDefaultsRestore(CTMU_ID_1); // POR defaults, turn CTMU off // 2. Select the current source range. PLIB_CTMU_CurrentRangeSet(CTMU_ID_1,CTMU_CurrentRangeBase_Base); // 3. Adjust the current source trim. PLIB_CTMU_CurrentTrimSet(CTMU_ID_1,+10); // increase by 20% = +10 * 2% // 4. Select the operating mode (Pulse Generation) PLIB_CTMU_TimePulseGenEnable(CTMU_ID_1); // Use Comparator Input/ANx pin // 5. Clear the Edge Status bits PLIB_CTMU_EdgeStatusSetAllNoEdges(CTMU_ID_1); // 6. Use the same input source for both edges. PLIB_CTMU_EdgeSourceSelect(CTMU_ID_1,CTMU_Edge1,CTMU_EdgeSource_0); PLIB_CTMU_EdgeSourceSelect(CTMU_ID_1,CTMU_Edge2,CTMU_EdgeSource_0); // 7. Configure the input polarities: PLIB_CTMU_EdgePolarityPositiveSet(CTMU_ID_1,CTMU_Edge1); // Trigger on Rising Edge PLIB_CTMU_EdgePolarityPositiveSet(CTMU_ID_1,CTMU_Edge2); // Trigger on falling Edge // 8. Enable edge sequencing so Edge 1 (rising) occurs before Edge 2 (falling) PLIB_CTMU_EdgeSequenceEnable(CTMU_ID_1); Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 445 // 9. Enable edges to control charge pump PLIB_CTMU_EdgeEnable(CTMU_ID_1); // 10. Turn on the CTMU module, wait 50 us for charge pump to stabilize PLIB_CTMU_Enable(CTMU_ID_1); // TO DO: Wait 50 microseconds // 11. Discharge the connected circuit by grounding the charge pump. PLIB_CTMU_CurrentSourceGrounded(CTMU_ID_1); // TO DO: Enable ADC sampling // TO DO: Wait for discharge to occur Again, the time between the rising edge of the pulse and the falling edge is given by: Time = ( Capacitance * (VDD * ADC_Count / MaxADCCount) ) / Current Capacitive Touch Measurement This section describes how to measure the capacitance of a button. Description Assuming that the CTMU has been configured as previously described, the following code example shows how to measure the capacitance of a button. #define MAX_ADC_CHANNELS 13 // Mapping of port (A,B,C) and pin (0-15) for each ADC Channel unsigned short int PortPinADC[MAX_ADC_CHANNELS] = { 0xA0, 0xA1, 0xB0, 0xB1, 0xB2, 0xB3, 0xC0, 0xC1, 0xC2, 0xBF, 0xBE, 0xBD, 0xC3 }; unsigned short int Vpos; // ADC voltage measurement unsigned short int iChan, // ADC channel assigned to each button PortPinChan, // Entry in PortPinADC coding matrix for each button iPort, // Port for each button (0xA,0xB,0xC for ports A,B,C) iPin; // Pin for each ADC channel (0-15) iChan = ScanChannels[button_set_number]; // button_set_number = button to be scanned PortPinChan = PortPinADC[iChan]; iPort = (PortPinChan>>4) & 0x0F; iPin = PortPinChan & 0x0F; // TO DO: Switch ADC to sensor pin given by iChan switch ( iPort ) // Make sure pin is setup for input { case 0xA: // TO DO: Tri-state iPin for Port A break; case 0xB: // TO DO: Tri-state iPin for Port B break; case 0xC: // TO DO: Tri-state iPin for Port C break; } // TO DO: Start ADC sampling to connect sample and hold cap to charge pump PLIB_CTMU_CurrentSourceGrounded(CTMU_ID_1); // Ground charge pump // TO DO: Wait for discharge of any residual charge from ADC S&H cap and button cap PLIB_CTMU_CurrentSourceNotGrounded(CTMU_ID_1); // Unground charge pump // TO DO: Disable interrupts to prevent ISRs from corrupting charge timing PLIB_CTMU_EdgeStatusGotEdgeSet( CTMU_ID_1, CTMU_Edge1 ); // Start charging button // TO DO: Wait for charge of button capacitor PLIB_CTMU_EdgeStatusNoEdgeSet( CTMU_ID_1, CTMU_Edge1 ); // Stop charging button // Start A/D conversion // TO DO: Stop ADC sampling to initiate ADC conversion // TO DO: Enable interrupts, since timing is no longer critical Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 446 // TO DO: Wait until ADC conversion complete PLIB_CTMU_CurrentSourceGrounded(CTMU_ID_1); // Ground charge pump //Read new Vpos // TO DO: Read ADC results buffer for Vpos Having measured VPOS, the software can now compare it to a limit. If VPOS is less than limit, the button is being pressed by the user. Example Applications Examples of CTMU applications are discussed. Description In most applications, the CTMU module provides the current to a circuit and the ADC module measures the resulting voltage. Depending on the setup of the CTMU and the ADC modules, this voltage can represent many things, including: • On-chip temperature using the built-in temperature diode • Finger press or swipe on a button panel by measuring relative capacitance • True or absolute capacitance by measuring capacitance after calibrating the charge pump • Pulse timing by turning the charge pump on/off with the pulse and then measuring the charge collected by a known capacitor The CTMU External Edge Input pins, CTED1 and CTED2, are used for connecting two pulse signals to the CTMU. A calibrated capacitor, CKNOWN, is connected to an ADC analog input pin, ANx. The voltage captured by the ADC measures the time difference between the rising edge of the signal on CTED1, which turns on the CTMU's current source, and the rising edge of the signal on CTED2, which turns off the current source. The CTMU and Comparator can be used, without the ADC's help, to delay an input pulse by a variable amount of time, using a known delay capacitor and the charge pumps settings. In this example, an analog pulse on CTED1 is delayed by a fixed time using a special comparator associated with the CTMU (Comparator 2). Using a calibrated capacitor attached to a special comparator input pin, C2INB, a fixed delay can be added to the analog pulse based on the current and trim settings of the CTMU's charge pump. The time delay is based on the time required to bring the charge voltage on CDELAY up to CVREF. Once there, the comparator's output triggers the start of the output pulse. Capacitive Touch Capacitive touch is easy to implement with a CTMU module and its associated on-chip ADC. Since button assertion is a change in capacitance, no calibration is required. The software must merely detect the difference between an unpressed button and a button that is pressed. When the user's finger presses a capacitive touch button, the additional capacitance of the finger causes the ADC to see a lower voltage. So software interprets a button voltage drop as a button press by the user. Peripheral Libraries Help CTMU Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 447 Configuring the Library The library is configured for the supported CTMU module when the processor is chosen in the MPLAB X IDE. Library Interface a) CTMU Control Functions Name Description PLIB_CTMU_CurrentRangeSet Selects the current source range. PLIB_CTMU_Disable Disables the CTMU module. PLIB_CTMU_Enable Enables the CTMU module. PLIB_CTMU_StopInIdleDisable Sets the CTMU module to continue running when the device is in Idle mode. PLIB_CTMU_StopInIdleEnable Sets the CTMU module to not operate when the device is in Idle mode. PLIB_CTMU_AutomaticADCTriggerDisable Disables the module to automatically trigger an analog-to-digital conversion. PLIB_CTMU_AutomaticADCTriggerEnable Enables the module to automatically trigger an analog-to-digital conversion when the second edge event has occurred. PLIB_CTMU_CurrentDischargeDisable Disables the Current discharge by not connecting the current source output to ground. PLIB_CTMU_CurrentDischargeEnable Enables the Current discharge by connecting the current source output to ground. PLIB_CTMU_CurrentTrimSet Trims current source off of the nominal value. PLIB_CTMU_TimePulseGenerationDisable Disables generation of time pulses using Comparator 2. PLIB_CTMU_TimePulseGenerationEnable Enables the generation of time pulses. b) Edge Control and Status Functions Name Description PLIB_CTMU_EdgeDisable Disables the edges of the CTMU. PLIB_CTMU_EdgeEnable Enables the edges of the CTMU. PLIB_CTMU_EdgeSequenceDisable Disables the edge sequence of the CTMU. PLIB_CTMU_EdgeSequenceEnable Enables the edge sequence of the CTMU. PLIB_CTMU_EdgeIsSet Gets the status of a CTMU edge. PLIB_CTMU_EdgePolaritySet Sets a CTMU edge to fire on an edge/level with the selected polarity of signal. PLIB_CTMU_EdgeSensitivitySet Sets CTMU sensitivity for the selected edge. PLIB_CTMU_EdgeSet Sets the status of a CTMU edge. PLIB_CTMU_EdgeTriggerSourceSelect Assigns a trigger source for an edge. c) Feature Existence Functions Name Description PLIB_CTMU_ExistsAutomaticADCTrigger Identifies whether the AutomaticADCTrigger feature exists on the CTMU module. PLIB_CTMU_ExistsCurrentDischarge Identifies whether the CurrentDischarge feature exists on the CTMU module. PLIB_CTMU_ExistsCurrentRange Identifies whether the CurrentRange feature exists on the CTMU module. PLIB_CTMU_ExistsCurrentTrim Identifies whether the CurrentTrim feature exists on the CTMU module. PLIB_CTMU_ExistsEdgeEnable Identifies whether the EdgeEnable feature exists on the CTMU module. PLIB_CTMU_ExistsEdgePolarity Identifies whether the EdgePolarity feature exists on the CTMU module. PLIB_CTMU_ExistsEdgeSensitivity Identifies whether the EdgeSensitivity feature exists on the CTMU module, PLIB_CTMU_ExistsEdgeSequencing Identifies whether the EdgeSequencing feature exists on the CTMU module. PLIB_CTMU_ExistsEdgeStatus Identifies whether the EdgeStatus feature exists on the CTMU module. PLIB_CTMU_ExistsEdgeTriggerSource Identifies whether the EdgeTriggerSource feature exists on the CTMU module. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 448 PLIB_CTMU_ExistsModuleEnable Identifies whether the ModuleEnable feature exists on the CTMU module. PLIB_CTMU_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the CTMU module. PLIB_CTMU_ExistsTimePulseGeneration Identifies whether the TimePulseGeneration feature exists on the CTMU module. Description This section describes the Application Programming Interface (API) functions of the CTMU Peripheral Library. Refer to each section for a detailed description. a) CTMU Control Functions PLIB_CTMU_CurrentRangeSet Function Selects the current source range. File plib_ctmu.h C void PLIB_CTMU_CurrentRangeSet(CTMU_MODULE_ID index, CTMU_CURRENT_RANGE currentRange); Returns None. Description This function selects the current source range. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsCurrentRange in your application to determine whether this feature is available. Preconditions None. Example // Select current range PLIB_CTMU_CurrentRangeSet ( CTMU_ID_0, CTMU_CURRENT_RANGE_BASE ); Parameters Parameters Description index Identifier for the desired CTMU module currentRange Charge pump current range selected, one of the possible enumeration values from CTMU_CURRENT_RANGE enum Function void PLIB_CTMU_CurrentRangeSet ( CTMU_MODULE_ID index, CTMU_CURRENT_RANGE currentRange ) PLIB_CTMU_Disable Function Disables the CTMU module. File plib_ctmu.h C void PLIB_CTMU_Disable(CTMU_MODULE_ID index); Returns None. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 449 Description This function disables (turns OFF) the CTMU module. Typically, this function is called before reconfiguring the CTMU module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsModuleEnable in your application to determine whether this feature is available. Preconditions None. Example // Turn off (disable) CTMU PLIB_CTMU_Disable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_Disable ( CTMU_MODULE_ID index ) PLIB_CTMU_Enable Function Enables the CTMU module. File plib_ctmu.h C void PLIB_CTMU_Enable(CTMU_MODULE_ID index); Returns None. Description This function enables (turns ON) the CTMU module. This function is called after configuring the CTMU module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsModuleEnable in your application to determine whether this feature is available. Preconditions None. Example // Turn on (enable) CTMU Module PLIB_CTMU_Enable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_Enable ( CTMU_MODULE_ID index ) PLIB_CTMU_StopInIdleDisable Function Sets the CTMU module to continue running when the device is in Idle mode. File plib_ctmu.h Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 450 C void PLIB_CTMU_StopInIdleDisable(CTMU_MODULE_ID index); Returns None. Description This function sets the CTMU module to continue running when the device is in Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example // Enable CTMU to run when CPU is in Idle Mode PLIB_CTMU_StopInIdleDisable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_StopInIdleDisable ( CTMU_MODULE_ID index ) PLIB_CTMU_StopInIdleEnable Function Sets the CTMU module to not operate when the device is in Idle mode. File plib_ctmu.h C void PLIB_CTMU_StopInIdleEnable(CTMU_MODULE_ID index); Returns None. Description This function sets the CTMU module to not operate when the device is in Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example // Do not run in Idle mode PLIB_CTMU_StopInIdleEnable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_StopInIdleEnable ( CTMU_MODULE_ID index ) Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 451 PLIB_CTMU_AutomaticADCTriggerDisable Function Disables the module to automatically trigger an analog-to-digital conversion. File plib_ctmu.h C void PLIB_CTMU_AutomaticADCTriggerDisable(CTMU_MODULE_ID index); Returns None. Description This function disables the module to automatically trigger an analog-to-digital conversion. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsAutomaticADCTrigger in your application to determine whether this feature is available. Preconditions None. Example // Disable ADC trigger from CTMU PLIB_CTMU_AutomaticADCTriggerDisable ( CTMU_ID_0 ); //To Do: Tell ADC to use CTMU trigger Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_AutomaticADCTriggerDisable ( CTMU_MODULE_ID index ) PLIB_CTMU_AutomaticADCTriggerEnable Function Enables the module to automatically trigger an analog-to-digital conversion when the second edge event has occurred. File plib_ctmu.h C void PLIB_CTMU_AutomaticADCTriggerEnable(CTMU_MODULE_ID index); Returns None. Description This function enables the module to automatically trigger an analog-to-digital conversion when the second edge event has occurred. The ADC trigger is asserted whenever the CTMU current source switches from ON to OFF. The ADC can then end sampling and start converting the measured voltage into bits. Remarks The ADC must be configured to use the CTMU trigger signal generated. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsAutomaticADCTrigger in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 452 Example // Enable ADC trigger from CTMU PLIB_CTMU_AutomaticADCTriggerEnable ( CTMU_ID_0 ); //To Do: Tell ADC to use CTMU trigger Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_AutomaticADCTriggerEnable ( CTMU_MODULE_ID index ) PLIB_CTMU_CurrentDischargeDisable Function Disables the Current discharge by not connecting the current source output to ground. File plib_ctmu.h C void PLIB_CTMU_CurrentDischargeDisable(CTMU_MODULE_ID index); Returns None. Description This function disables the Current discharge by not connecting the current source output to ground. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsCurrentDischarge in your application to determine whether this feature is available. Preconditions None. Example // Measure button voltage // TO DO: Start ADC sampling to connect S&H capacitor to charge pump PLIB_CTMU_CurrentDischargeDisable ( CTMU_ID_0 ); // Ground charge pump Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_CurrentDischargeDisable ( CTMU_MODULE_ID index ) PLIB_CTMU_CurrentDischargeEnable Function Enables the Current discharge by connecting the current source output to ground. File plib_ctmu.h C void PLIB_CTMU_CurrentDischargeEnable(CTMU_MODULE_ID index); Returns None. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 453 Description This function enables the Current discharge by connecting the current source output to ground. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsCurrentDischarge in your application to determine whether this feature is available. Preconditions None. Example // Measure button voltage // TO DO: Start ADC sampling to connect S&H capacitor to charge pump PLIB_CTMU_CurrentDischargeEnable ( CTMU_ID_0 ); // Ground charge pump Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_CurrentDischargeEnable ( CTMU_MODULE_ID index ) PLIB_CTMU_CurrentTrimSet Function Trims current source off of the nominal value. File plib_ctmu.h C void PLIB_CTMU_CurrentTrimSet(CTMU_MODULE_ID index, int16_t currentTrim); Description This function trims current source off of the nominal value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsCurrentTrim in your application to determine whether this feature is available. Preconditions None. Example // Set current trim, adjust from nominal by -10 x 2% = -20% PLIB_CTMU_CurrentTrimSet ( CTMU_ID_0, -10 ); Parameters Parameters Description index Identifier for the desired CTMU module currentTrim Current trim index, from -31 to 31 Function void PLIB_CTMU_CurrentTrimSet ( CTMU_MODULE_ID index, int16_t currentTrim ) PLIB_CTMU_TimePulseGenerationDisable Function Disables generation of time pulses using Comparator 2. File plib_ctmu.h Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 454 C void PLIB_CTMU_TimePulseGenerationDisable(CTMU_MODULE_ID index); Returns None. Description This function disables generation of time pulses using Comparator 2. Current source is made available for other measurements, including capacitance, time, or temperature (if temperature sensor is available). Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsTimePulseGeneration in your application to determine whether this feature is available. Preconditions None. Example // Return to button relative capacitance measurements PLIB_CTMU_TimePulseGenerationDisable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_TimePulseGenerationDisable ( CTMU_MODULE_ID index ) PLIB_CTMU_TimePulseGenerationEnable Function Enables the generation of time pulses. File plib_ctmu.h C void PLIB_CTMU_TimePulseGenerationEnable(CTMU_MODULE_ID index); Returns None. Description This function enables generation of time pulses using Comparator 2. Current source will not be available for capacitance, time, or temperature measurements. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsTimePulseGeneration in your application to determine whether this feature is available. Preconditions None. Example // Send current to ADC S&H without going through ADC input MUX. PLIB_CTMU_TimePulseGenerationEnable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 455 Function void PLIB_CTMU_TimePulseGenerationEnable ( CTMU_MODULE_ID index ) b) Edge Control and Status Functions PLIB_CTMU_EdgeDisable Function Disables the edges of the CTMU. File plib_ctmu.h C void PLIB_CTMU_EdgeDisable(CTMU_MODULE_ID index); Returns None. Description This function disables the edges of the CTMU (makes them blocked). Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsEdgeEnable in your application to determine whether this feature is available. Preconditions None. Example // Disable edges, now can only turn CTMU on/off by modifying edge status PLIB_CTMU_EdgeDisable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_EdgeDisable ( CTMU_MODULE_ID index ) PLIB_CTMU_EdgeEnable Function Enables the edges of the CTMU. File plib_ctmu.h C void PLIB_CTMU_EdgeEnable(CTMU_MODULE_ID index); Returns None. Description This function enables the edges of the CTMU (makes it not blocked). Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsEdgeEnable in your application to determine whether this feature is available. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 456 Preconditions None. Example // Enable edges so that input signals can turn the CTMU charge pump on and off PLIB_CTMU_EdgeEnable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_EdgeEnable ( CTMU_MODULE_ID index ) PLIB_CTMU_EdgeSequenceDisable Function Disables the edge sequence of the CTMU. File plib_ctmu.h C void PLIB_CTMU_EdgeSequenceDisable(CTMU_MODULE_ID index); Returns None. Description This function disables the edge sequence of the CTMU. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsEdgeSequencing in your application to determine whether this feature is available. Preconditions None. Example // Trigger on Edge1 or Edge2, which ever one occurs first PLIB_CTMU_EdgeSequenceDisable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_EdgeSequenceDisable ( CTMU_MODULE_ID index ) PLIB_CTMU_EdgeSequenceEnable Function Enables the edge sequence of the CTMU. File plib_ctmu.h C void PLIB_CTMU_EdgeSequenceEnable(CTMU_MODULE_ID index); Returns None. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 457 Description This function enables the edge sequence of the CTMU. Edge 1 must occur before Edge 2 can occur. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsEdgeSequencing in your application to determine whether this feature is available. Preconditions None. Example // Trigger on Edge1 then Edge2, i.e., don't trigger on Edge 2 //until Edge 1 has occurred PLIB_CTMU_EdgeSequenceEnable ( CTMU_ID_0 ); Parameters Parameters Description index Identifier for the desired CTMU module Function void PLIB_CTMU_EdgeSequenceEnable ( CTMU_MODULE_ID index ) PLIB_CTMU_EdgeIsSet Function Gets the status of a CTMU edge. File plib_ctmu.h C bool PLIB_CTMU_EdgeIsSet(CTMU_MODULE_ID index, CTMU_EDGE_SELECT edgeNumber); Returns None. Description This function gets the status of the selected CTMU edge ( given by edgeNumber ). Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsEdgeStatus in your application to determine whether this feature is available. Preconditions None. Example bool edgeStatus; edgeStatus = PLIB_CTMU_EdgeIsSet ( CTMU_ID_0, CTMU_EDGE1 ); Parameters Parameters Description index Identifier for the desired CTMU module. edgeNumber CTMU Edge for which the trigger source to be set, one of the possible elements of the CTMU_EDGE_SELECT enum. Function bool PLIB_CTMU_EdgeIsSet ( CTMU_MODULE_ID index, CTMU_EDGE_SELECT edgeNumber ) Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 458 PLIB_CTMU_EdgePolaritySet Function Sets a CTMU edge to fire on an edge/level with the selected polarity of signal. File plib_ctmu.h C void PLIB_CTMU_EdgePolaritySet(CTMU_MODULE_ID index, CTMU_EDGE_SELECT edgeNumber, CTMU_EDGE_POLARITY edgePolarity); Returns None. Description This function sets a CTMU edge to fire on an edge/level with the selected polarity of signal. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsEdgePolarity in your application to determine whether this feature is available. Preconditions None. Example // Example to set both edges to trigger on positive level/edge. PLIB_CTMU_EdgePolaritySet ( CTMU_ID_0, CTMU_EDGE1, CTMU_EDGE_X_POSITIVE_EDGE ); PLIB_CTMU_EdgePolaritySet ( CTMU_ID_0, CTMU_EDGE2, CTMU_EDGE_X_POSITIVE_EDGE ); Parameters Parameters Description index Identifier for the desired CTMU module. edgeNumber CTMU Edge for which the polarity to be set, one of the possible elements of CTMU_EDGE_SELECT enum. edgeSense CTMU Edge polarity, one of the possible elements of the CTMU_EDGE_POLARITY enum. Function void PLIB_CTMU_EdgePolaritySet ( CTMU_MODULE_ID index,CTMU_EDGE_SELECT edgeNumber, CTMU_EDGE_POLARITY edgePolarity ); PLIB_CTMU_EdgeSensitivitySet Function Sets CTMU sensitivity for the selected edge. File plib_ctmu.h C void PLIB_CTMU_EdgeSensitivitySet(CTMU_MODULE_ID index, CTMU_EDGE_SELECT edgeNumber, CTMU_EDGE_SENSITIVITY edgeSense); Returns None. Description This function can be used to set the sensitivity of a particular edge to level-sensitive or edge sensitive. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsEdgeSensitivity in your application to determine whether this feature is available. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 459 Preconditions None. Example // Example to set both edges to trigger on edges rather than levels PLIB_CTMU_EdgeSensitivitySet ( CTMU_ID_0, CTMU_EDGE1, CTMU_EDGE_X_EDGE_SENSITIVE ); PLIB_CTMU_EdgeSensitivitySet ( CTMU_ID_0, CTMU_EDGE2, CTMU_EDGE_X_EDGE_SENSITIVE ); Parameters Parameters Description index Identifier for the desired CTMU module. edgeNumber CTMU edge for which the sensitivity to be set, one of the possible elements of the CTMU_EDGE_SELECT enum. edgeSense CTMU Edge sensitivity, one of the possible elements of the CTMU_EDGE_SENSITIVITY enum. Function void PLIB_CTMU_EdgeSensitivitySet ( CTMU_MODULE_ID index, CTMU_EDGE_SELECT edgeNumber, CTMU_EDGE_SENSITIVITY edgeSense ) PLIB_CTMU_EdgeSet Function Sets the status of a CTMU edge. File plib_ctmu.h C void PLIB_CTMU_EdgeSet(CTMU_MODULE_ID index, CTMU_EDGE_SELECT edgeNumber); Returns None. Description This function sets the status of the selected CTMU edge (given by edge_number). Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsEdgeStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_CTMU_EdgeSet ( CTMU_ID_0, CTMU_EDGE1 ); Parameters Parameters Description index Identifier for the desired CTMU module. edgeNumber CTMU Edge for which the trigger source to be set, one of the possible elements of the CTMU_EDGE_SELECT enum. Function void PLIB_CTMU_EdgeSet ( CTMU_MODULE_ID index, CTMU_EDGE_SELECT edgeNumber ) PLIB_CTMU_EdgeTriggerSourceSelect Function Assigns a trigger source for an edge. File plib_ctmu.h Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 460 C void PLIB_CTMU_EdgeTriggerSourceSelect(CTMU_MODULE_ID index, CTMU_EDGE_SELECT edgeNumber, CTMU_TRIGGER_SOURCES triggerSource); Returns None. Description This function will enable the CTMU edge (given by edge_number) to trigger on the signal provided by the trigger source selected. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CTMU_ExistsEdgeTriggerSource in your application to determine whether this feature is available. Preconditions None. Example //Set source 0 as the trigger source for both the edges PLIB_CTMU_EdgeTriggerSourceSelect ( CTMU_ID_0, CTMU_EDGE1, CTMU_TRIGGERSOURCE_0 ); PLIB_CTMU_EdgeTriggerSourceSelect ( CTMU_ID_0, CTMU_EDGE2, CTMU_TRIGGERSOURCE_0 ); Parameters Parameters Description index Identifier for the desired CTMU module. edgeNumber CTMU Edge for which the trigger source to be set, one of the possible elements of the CTMU_EDGE_SELECT enum. triggerSource CTMU Edge trigger source, one of the possible elements of the CTMU_TRIGGER_SOURCES enum. Function void PLIB_CTMU_EdgeTriggerSourceSelect ( CTMU_MODULE_ID index, CTMU_EDGE_SELECT edgeNumber, CTMU_TRIGGER_SOURCES triggerSource ) c) Feature Existence Functions PLIB_CTMU_ExistsAutomaticADCTrigger Function Identifies whether the AutomaticADCTrigger feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsAutomaticADCTrigger(CTMU_MODULE_ID index); Returns • true - The AutomaticADCTrigger feature is supported on the device • false - The AutomaticADCTrigger feature is not supported on the device Description This function identifies whether the AutomaticADCTrigger feature is available on the CTMU module. When this function returns true, these functions are supported on the device: • PLIB_CTMU_AutomaticADCTriggerDisable • PLIB_CTMU_AutomaticADCTriggerEnable Remarks None. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 461 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsAutomaticADCTrigger( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsCurrentDischarge Function Identifies whether the CurrentDischarge feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsCurrentDischarge(CTMU_MODULE_ID index); Returns • true - The CurrentDischarge feature is supported on the device • false - The CurrentDischarge feature is not supported on the device Description This function identifies whether the CurrentDischarge feature is available on the CTMU module. When this function returns true, these functions are supported on the device: • PLIB_CTMU_CurrentDischargeEnable • PLIB_CTMU_CurrentDischargeDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsCurrentDischarge( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsCurrentRange Function Identifies whether the CurrentRange feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsCurrentRange(CTMU_MODULE_ID index); Returns • true - The CurrentRange feature is supported on the device • false - The CurrentRange feature is not supported on the device Description This function identifies whether the CurrentRange feature is available on the CTMU module. When this function returns true, this function is supported on the device: Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 462 • PLIB_CTMU_CurrentRangeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsCurrentRange( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsCurrentTrim Function Identifies whether the CurrentTrim feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsCurrentTrim(CTMU_MODULE_ID index); Returns • true - The CurrentTrim feature is supported on the device • false - The CurrentTrim feature is not supported on the device Description This function identifies whether the CurrentTrim feature is available on the CTMU module. When this function returns true, this function is supported on the device: • PLIB_CTMU_CurrentTrimSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsCurrentTrim( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsEdgeEnable Function Identifies whether the EdgeEnable feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsEdgeEnable(CTMU_MODULE_ID index); Returns • true - The EdgeEnable feature is supported on the device • false - The EdgeEnable feature is not supported on the device Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 463 Description This function identifies whether the EdgeEnable feature is available on the CTMU module. When this function returns true, these functions are supported on the device: • PLIB_CTMU_EdgeDisable • PLIB_CTMU_EdgeEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsEdgeEnable( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsEdgePolarity Function Identifies whether the EdgePolarity feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsEdgePolarity(CTMU_MODULE_ID index); Returns • true - The EdgePolarity feature is supported on the device • false - The EdgePolarity feature is not supported on the device Description This function identifies whether the EdgePolarity feature is available on the CTMU module. When this function returns true, this function is supported on the device: • PLIB_CTMU_EdgePolaritySet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsEdgePolarity( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsEdgeSensitivity Function Identifies whether the EdgeSensitivity feature exists on the CTMU module, File plib_ctmu.h C bool PLIB_CTMU_ExistsEdgeSensitivity(CTMU_MODULE_ID index); Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 464 Returns • true - The EdgeSensitivity feature is supported on the device • false - The EdgeSensitivity feature is not supported on the device Description This function identifies whether the EdgeSensitivity feature is available on the CTMU module. When this function returns true, this function is supported on the device: • PLIB_CTMU_EdgeSensitivitySet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsEdgeSensitivity( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsEdgeSequencing Function Identifies whether the EdgeSequencing feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsEdgeSequencing(CTMU_MODULE_ID index); Returns • true - The EdgeSequencing feature is supported on the device • false - The EdgeSequencing feature is not supported on the device Description This function identifies whether the EdgeSequencing feature is available on the CTMU module. When this function returns true, these functions are supported on the device: • PLIB_CTMU_EdgeSequenceDisable • PLIB_CTMU_EdgeSequenceEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsEdgeSequencing( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsEdgeStatus Function Identifies whether the EdgeStatus feature exists on the CTMU module. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 465 File plib_ctmu.h C bool PLIB_CTMU_ExistsEdgeStatus(CTMU_MODULE_ID index); Returns • true - The EdgeStatus feature is supported on the device • false - The EdgeStatus feature is not supported on the device Description This function identifies whether the EdgeStatus feature is available on the CTMU module. When this function returns true, these functions are supported on the device: • PLIB_CTMU_EdgeIsSet • PLIB_CTMU_EdgeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsEdgeStatus( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsEdgeTriggerSource Function Identifies whether the EdgeTriggerSource feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsEdgeTriggerSource(CTMU_MODULE_ID index); Returns • true - The EdgeTriggerSource feature is supported on the device • false - The EdgeTriggerSource feature is not supported on the device Description This function identifies whether the EdgeTriggerSource feature is available on the CTMU module. When this function returns true, this function is supported on the device: • PLIB_CTMU_EdgeTriggerSourceSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsEdgeTriggerSource( CTMU_MODULE_ID index ) Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 466 PLIB_CTMU_ExistsModuleEnable Function Identifies whether the ModuleEnable feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsModuleEnable(CTMU_MODULE_ID index); Returns • true - The ModuleEnable feature is supported on the device • false - The ModuleEnable feature is not supported on the device Description This function identifies whether the ModuleEnable feature is available on the CTMU module. When this function returns true, these functions are supported on the device: • PLIB_CTMU_Disable • PLIB_CTMU_Enable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsModuleEnable( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsStopInIdle(CTMU_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the CTMU module. When this function returns true, these functions are supported on the device: • PLIB_CTMU_StopInIdleDisable • PLIB_CTMU_StopInIdleEnable Remarks None. Preconditions None. Peripheral Libraries Help CTMU Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 467 Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsStopInIdle( CTMU_MODULE_ID index ) PLIB_CTMU_ExistsTimePulseGeneration Function Identifies whether the TimePulseGeneration feature exists on the CTMU module. File plib_ctmu.h C bool PLIB_CTMU_ExistsTimePulseGeneration(CTMU_MODULE_ID index); Returns • true - The TimePulseGeneration feature is supported on the device • false - The TimePulseGeneration feature is not supported on the device Description This function identifies whether the TimePulseGeneration feature is available on the CTMU module. When this function returns true, these functions are supported on the device: • PLIB_CTMU_TimePulseGenerationDisable • PLIB_CTMU_TimePulseGenerationEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_CTMU_ExistsTimePulseGeneration( CTMU_MODULE_ID index ) Files Files Name Description plib_ctmu.h This file contains the interface definition for the CTMU Peripheral Library. Description This section lists the source and header files used by the library. plib_ctmu.h This file contains the interface definition for the CTMU Peripheral Library. Functions Name Description PLIB_CTMU_AutomaticADCTriggerDisable Disables the module to automatically trigger an analog-to-digital conversion. PLIB_CTMU_AutomaticADCTriggerEnable Enables the module to automatically trigger an analog-to-digital conversion when the second edge event has occurred. Peripheral Libraries Help CTMU Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 468 PLIB_CTMU_CurrentDischargeDisable Disables the Current discharge by not connecting the current source output to ground. PLIB_CTMU_CurrentDischargeEnable Enables the Current discharge by connecting the current source output to ground. PLIB_CTMU_CurrentRangeSet Selects the current source range. PLIB_CTMU_CurrentTrimSet Trims current source off of the nominal value. PLIB_CTMU_Disable Disables the CTMU module. PLIB_CTMU_EdgeDisable Disables the edges of the CTMU. PLIB_CTMU_EdgeEnable Enables the edges of the CTMU. PLIB_CTMU_EdgeIsSet Gets the status of a CTMU edge. PLIB_CTMU_EdgePolaritySet Sets a CTMU edge to fire on an edge/level with the selected polarity of signal. PLIB_CTMU_EdgeSensitivitySet Sets CTMU sensitivity for the selected edge. PLIB_CTMU_EdgeSequenceDisable Disables the edge sequence of the CTMU. PLIB_CTMU_EdgeSequenceEnable Enables the edge sequence of the CTMU. PLIB_CTMU_EdgeSet Sets the status of a CTMU edge. PLIB_CTMU_EdgeTriggerSourceSelect Assigns a trigger source for an edge. PLIB_CTMU_Enable Enables the CTMU module. PLIB_CTMU_ExistsAutomaticADCTrigger Identifies whether the AutomaticADCTrigger feature exists on the CTMU module. PLIB_CTMU_ExistsCurrentDischarge Identifies whether the CurrentDischarge feature exists on the CTMU module. PLIB_CTMU_ExistsCurrentRange Identifies whether the CurrentRange feature exists on the CTMU module. PLIB_CTMU_ExistsCurrentTrim Identifies whether the CurrentTrim feature exists on the CTMU module. PLIB_CTMU_ExistsEdgeEnable Identifies whether the EdgeEnable feature exists on the CTMU module. PLIB_CTMU_ExistsEdgePolarity Identifies whether the EdgePolarity feature exists on the CTMU module. PLIB_CTMU_ExistsEdgeSensitivity Identifies whether the EdgeSensitivity feature exists on the CTMU module, PLIB_CTMU_ExistsEdgeSequencing Identifies whether the EdgeSequencing feature exists on the CTMU module. PLIB_CTMU_ExistsEdgeStatus Identifies whether the EdgeStatus feature exists on the CTMU module. PLIB_CTMU_ExistsEdgeTriggerSource Identifies whether the EdgeTriggerSource feature exists on the CTMU module. PLIB_CTMU_ExistsModuleEnable Identifies whether the ModuleEnable feature exists on the CTMU module. PLIB_CTMU_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the CTMU module. PLIB_CTMU_ExistsTimePulseGeneration Identifies whether the TimePulseGeneration feature exists on the CTMU module. PLIB_CTMU_StopInIdleDisable Sets the CTMU module to continue running when the device is in Idle mode. PLIB_CTMU_StopInIdleEnable Sets the CTMU module to not operate when the device is in Idle mode. PLIB_CTMU_TimePulseGenerationDisable Disables generation of time pulses using Comparator 2. PLIB_CTMU_TimePulseGenerationEnable Enables the generation of time pulses. Description Charge Time Measurement Unit (CTMU) Peripheral Library Header This library provides a low-level abstraction of the Charge Time Measurement Unit(CTMU) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences between one microcontroller variant and another. File Name plib_ctmu.h Company Microchip Technology Inc. Peripheral Libraries Help CTMU Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 469 Deadman Timer Peripheral Library This section describes the Deadman Timer (DMT) Peripheral Library. Introduction This library provides a low-level abstraction of the DMT Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by abstracting differences from one microcontroller variant to another. Description The primary function of the Deadman Timer (DMT) is to reset the processor in the event of a software malfunction. Using the Library This topic describes the basic architecture of the DMT Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_dmt.h The interface to the DMT Peripheral Library is defined in the plib_dmt.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the DMT Peripheral Library must include peripheral.h. Library File: The DMT Peripheral Library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the Deadman Timer module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description The Deadman Timer is a free-running instruction fetch timer, which is clocked whenever an instruction fetch occurs. The Deadman Timer is active in the normal mode only. Since the Deadman Timer is only incremented by instruction fetches, the count value will not change when the core is inactive. So, the Deadman Timer remains inactive in Sleep and Idle modes. The Deadman Timer module uses the Deadman register as a timer. If there is no reset signal from the software and if the counter overflows, this results in the device Reset. For Windowed mode, resetting the counter when the count is not in the specified window will also lead to the device Reset. Deadman Timer Software Abstraction Block Diagram Peripheral Libraries Help Deadman Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 470 Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Deadman Timer module. Library Interface Section Description General Configuration Functions Includes module enable and disable functions. General Status Functions Status routines for the DMT. Feature Existence Functions Functions that determine existence of certain features. How the Library Works This section provides information on how the Deadman Timer Peripheral Library works. Configuring the Library The library is configured for the supported Deadman Timer module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Configuration Functions Name Description PLIB_DMT_ClearStep1 Resets the DMT module. PLIB_DMT_ClearStep2 Resets the DMT module. PLIB_DMT_Disable Disables the DMT module. PLIB_DMT_Enable Enables the DMT module. Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 471 b) General Status Functions Name Description PLIB_DMT_BAD1Get Returns BAD1 flag from the DMT Status Register. PLIB_DMT_BAD2Get Returns BAD2 flag from the DMT Status Register. PLIB_DMT_CounterGet Returns the DMT counter value. PLIB_DMT_IsEnabled Returns the Deadman Timer on/off(enable/disable) status. PLIB_DMT_PostscalerIntervalGet Returns the DMT postscaler interval value. PLIB_DMT_PostscalerValueGet Returns the DMT postscaler value. PLIB_DMT_WindowIsOpen Returns Window is Open flag from the DMT Status Register. PLIB_DMT_EventOccurred Returns Event flag from the DMT Status Register. c) Feature Existence Functions Name Description PLIB_DMT_ExistsCounter Identifies whether the Counter feature exists on the DMT module. PLIB_DMT_ExistsEnableControl Identifies whether the EnableControl feature exists on the DMT module. PLIB_DMT_ExistsPostscalerInterval Identifies whether the Postscaler Interval feature exists on the DMT module. PLIB_DMT_ExistsPostscalerValue Identifies whether the Postscaler Value feature exists on the DMT module. PLIB_DMT_ExistsStatus Identifies whether the Status feature exists on the DMT module. PLIB_DMT_ExistsStep1 Identifies whether the STEP1 Clear feature exists on the DMT module. PLIB_DMT_ExistsStep2 Identifies whether the STEP2 Clear feature exists on the DMT module. d) Data Types and Constants Name Description DMT_MODULE_ID Identifies the supported DMT modules. Description This section describes the Application Programming Interface (API) functions of the Deadman Timer Peripheral Library. Refer to each section for a detailed description. a) General Configuration Functions PLIB_DMT_ClearStep1 Function Resets the DMT module. File plib_dmt.h C void PLIB_DMT_ClearStep1(DMT_MODULE_ID index); Returns None. Description This function performs the STEP1 Clearing of the DMT module. The DMT module should be cleared in two steps, within the interval determined by the Count Window before the DMT forces an NMI or device reset. Remarks Resetting the device before the count reaches the window will cause a reset in Windowed mode. The example code does not include the settings that should be done through the Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsTimerClear in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 472 Example PLIB_DMT_Enable ( DMT_ID_0 ); //Application loop while(1) { PLIB_DMT_ClearStep1 ( DMT_ID_0 ); //user code PLIB_DMT_ClearStep2 ( DMT_ID_0 ); //user code } Parameters Parameters Description index Identifies the desired DMT module Function void PLIB_DMT_ClearStep1 ( DMT_MODULE_ID index ) PLIB_DMT_ClearStep2 Function Resets the DMT module. File plib_dmt.h C void PLIB_DMT_ClearStep2(DMT_MODULE_ID index); Returns None. Description This function performs the STEP2 Clearing of the DMT module. The DMT module should be cleared in two steps, within the interval determined by the Count Window before the DMT forces an NMI or device reset. Remarks Resetting the device before the count reaches the window will cause a reset in Windowed mode. The example code doesn't include the settings that should be done through the Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsTimerClear in your application to determine whether this feature is available. Preconditions None. Example PLIB_DMT_Enable ( DMT_ID_0 ); //Application loop while(1) { PLIB_DMT_ClearStep1 ( DMT_ID_0 ); //user code PLIB_DMT_ClearStep2 ( DMT_ID_0 ); //user code } Parameters Parameters Description index Identifies the desired DMT module Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 473 Function void PLIB_DMT_ClearStep2 ( DMT_MODULE_ID index ) PLIB_DMT_Disable Function Disables the DMT module. File plib_dmt.h C void PLIB_DMT_Disable(DMT_MODULE_ID index); Returns None. Description This function disables the DMT module if it is enabled in software. Remarks This function will not disable the DMT module if it is enabled through its Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsEnableControl in your application to determine whether this feature is available. Preconditions The DMT module must have been enabled through software. Example PLIB_DMT_Disable ( DMT_ID_0 ); Parameters Parameters Description index Identifies the desired DMT module Function void PLIB_DMT_Disable ( DMT_MODULE_ID index ) PLIB_DMT_Enable Function Enables the DMT module. File plib_dmt.h C void PLIB_DMT_Enable(DMT_MODULE_ID index); Returns None. Description This function enables the DMT module. If it is already enabled through the Configuration bits, it will keep it enabled. Remarks Calling this function is not necessary if it is enabled through its Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 474 Example PLIB_DMT_Enable ( DMT_ID_0 ); Parameters Parameters Description index Identifies the desired DMT module Function void PLIB_DMT_Enable ( DMT_MODULE_ID index ) b) General Status Functions PLIB_DMT_BAD1Get Function Returns BAD1 flag from the DMT Status Register. File plib_dmt.h C bool PLIB_DMT_BAD1Get(DMT_MODULE_ID index); Returns The flag value, true or false. Description This function returns the DMT BAD1 Flag. This flag is set when there is an incorrect write to STEP1, such as the wrong value, writing too early, or writing too late. Remarks The flag returned will indicated if a STEP1 write was not successful. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_DMT_Enable ( DMT_ID_0 ); //user code PLIB_DMT_ClearStep1(); if( PLIB_DMT_BAD1Get ( DMT_ID_0 )) { //user code } Parameters Parameters Description index Identifies the desired DMT module Function bool PLIB_DMT_BAD1Get ( DMT_MODULE_ID index ) PLIB_DMT_BAD2Get Function Returns BAD2 flag from the DMT Status Register. File plib_dmt.h Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 475 C bool PLIB_DMT_BAD2Get(DMT_MODULE_ID index); Returns The flag value, true or false. Description This function returns the DMT BAD2 Flag. This flag is set when there is an incorrect write to STEP2, such as the wrong value, writing too early, or writing too late. Remarks The flag returned will indicated if a STEP2 write was not successful. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_DMT_Enable ( DMT_ID_0 ); //user code PLIB_DMT_ClearStep1(); //user code PLIB_DMT_ClearStep2(); if( PLIB_DMT_BAD2Get ( DMT_ID_0 )) { //user code } Parameters Parameters Description index Identifies the desired DMT module Function bool PLIB_DMT_BAD2Get ( DMT_MODULE_ID index ) PLIB_DMT_CounterGet Function Returns the DMT counter value. File plib_dmt.h C uint32_t PLIB_DMT_CounterGet(DMT_MODULE_ID index); Returns The counter value. Description This function returns the DMT counter value. The value is the number of instructions counted since the count was last cleared. Remarks The value returned will be right-aligned. Refer the data sheet of the specific device to get the division factor corresponding to the value. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsCounterValue in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 476 Example uint32_t value; PLIB_DMT_Enable ( DMT_ID_0 ); value = PLIB_DMT_CounterGet ( DMT_ID_0 ); Parameters Parameters Description index Identifies the desired DMT module Function uint32_t PLIB_DMT_CounterGet ( DMT_MODULE_ID index ) PLIB_DMT_IsEnabled Function Returns the Deadman Timer on/off(enable/disable) status. File plib_dmt.h C bool PLIB_DMT_IsEnabled(DMT_MODULE_ID index); Returns true - If the Deadman Timer is on false - If the Deadman Timer is off Description Returns the 'true', if the Deadman Timer is already ON. Otherwise returns 'false'. Remarks This function returns 'true' if the device is enabled either though the Configuration bits or in the software. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_DMT_IsEnabled ( DMT_ID_0 ) ) { //Do some action } Parameters Parameters Description index Identifies the desired DMT module Function bool PLIB_DMT_IsEnabled ( DMT_MODULE_ID index ) PLIB_DMT_PostscalerIntervalGet Function Returns the DMT postscaler interval value. File plib_dmt.h C uint32_t PLIB_DMT_PostscalerIntervalGet(DMT_MODULE_ID index); Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 477 Returns The postscaler interval. Description This function returns the DMT postscaler interval. The value will correspond to a total number of instructions for DMT window, a value determined by configuration bits. Remarks The value returned will be right-aligned. Refer the data sheet of the specific device to get the association of the configuration bits corresponding to this postscaler value. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsPostscalerValue in your application to determine whether this feature is available. Preconditions None. Example uint32_t value; PLIB_DMT_Enable ( DMT_ID_0 ); value = PLIB_DMT_PostscalerIntervalGet ( DMT_ID_0 ); Parameters Parameters Description index Identifies the desired DMT module Function uint32_t PLIB_DMT_PostscalerIntervalGet ( DMT_MODULE_ID index ) PLIB_DMT_PostscalerValueGet Function Returns the DMT postscaler value. File plib_dmt.h C uint32_t PLIB_DMT_PostscalerValueGet(DMT_MODULE_ID index); Returns The postscaler value. Description This function returns the DMT postscaler value. The value will correspond to a total number of instructions for DMT timeout, a value determined by configuration bits. Remarks The value returned will be right-aligned. Refer to the specific device data sheet to get the association of the configuration bits corresponding to this postscaler value. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsPostscalerValue in your application to determine whether this feature is available. Preconditions None. Example uint32_t value; PLIB_DMT_Enable ( DMT_ID_0 ); value = PLIB_DMT_PostscalerValueGet ( DMT_ID_0 ); Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 478 Parameters Parameters Description index Identifies the desired DMT module Function uint32_t PLIB_DMT_PostscalerValueGet ( DMT_MODULE_ID index ) PLIB_DMT_WindowIsOpen Function Returns Window is Open flag from the DMT Status Register. File plib_dmt.h C bool PLIB_DMT_WindowIsOpen(DMT_MODULE_ID index); Returns The flag value, true or false. Description This function returns the flag indicating the DMT Window is open. Remarks The flag returned will indicated if the DMT window is open. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_DMT_Enable ( DMT_ID_0 ); //user code PLIB_DMT_ClearStep1(); //user code if( PLIB_DMT_WindowIsOpen( DMT_ID_0 )) { PLIB_DMT_ClearStep2(); } Parameters Parameters Description index Identifies the desired DMT module Function bool PLIB_DMT_WindowIsOpen( DMT_MODULE_ID index ) PLIB_DMT_EventOccurred Function Returns Event flag from the DMT Status Register. File plib_dmt.h C bool PLIB_DMT_EventOccurred(DMT_MODULE_ID index); Returns The flag value, true or false. Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 479 Description This function returns the flag indicating a DMT event has happened, such as a Window Open, or a Bad Flag is set. Remarks The flag returned will indicate if a DMT event has happened. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_DMT_ExistsStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_DMT_Enable ( DMT_ID_0 ); //user code PLIB_DMT_ClearStep1(); //user code if( PLIB_DMT_EventOccurred( DMT_ID_0 )) { //user code } Parameters Parameters Description index Identifies the desired DMT module Function bool PLIB_DMT_EventOccurred( DMT_MODULE_ID index ) c) Feature Existence Functions PLIB_DMT_ExistsCounter Function Identifies whether the Counter feature exists on the DMT module. File plib_dmt.h C bool PLIB_DMT_ExistsCounter(DMT_MODULE_ID index); Returns • true - The Counter feature is supported on the device • false - The Counter feature is not supported on the device Description This function identifies whether the Counter feature is available on the DMT module. When this function returns true, this function is supported on the device: • PLIB_DMT_CounterGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 480 Function PLIB_DMT_ExistsCounter( DMT_MODULE_ID index ) PLIB_DMT_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the DMT module. File plib_dmt.h C bool PLIB_DMT_ExistsEnableControl(DMT_MODULE_ID index); Returns Existence of the EnableControl feature: • true - When EnableControl feature is supported on the device • false - When EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the DMT module. When this function returns true, these functions are supported on the device: • PLIB_DMT_Enable • PLIB_DMT_Disable • PLIB_DMT_IsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMT_ExistsEnableControl( DMT_MODULE_ID index ) PLIB_DMT_ExistsPostscalerInterval Function Identifies whether the Postscaler Interval feature exists on the DMT module. File plib_dmt.h C bool PLIB_DMT_ExistsPostscalerInterval(DMT_MODULE_ID index); Returns • true - The Postscaler Interval feature is supported on the device • false - The Postscaler Interval feature is not supported on the device Description This function identifies whether the Postscaler Interval feature is available on the DMT module. When this function returns true, this function is supported on the device: • PLIB_DMT_PostscalerIntervalGet Remarks None. Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 481 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMT_ExistsInterval( DMT_MODULE_ID index ) PLIB_DMT_ExistsPostscalerValue Function Identifies whether the Postscaler Value feature exists on the DMT module. File plib_dmt.h C bool PLIB_DMT_ExistsPostscalerValue(DMT_MODULE_ID index); Returns • true - The Postscaler Value feature is supported on the device • false - The Postscaler Value feature is not supported on the device Description This function identifies whether the PostscalerValue feature is available on the DMT module. When this function returns true, this function is supported on the device: • PLIB_DMT_PostscalerValueGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMT_ExistsPostscalerValue( DMT_MODULE_ID index ) PLIB_DMT_ExistsStatus Function Identifies whether the Status feature exists on the DMT module. File plib_dmt.h C bool PLIB_DMT_ExistsStatus(DMT_MODULE_ID index); Returns Existence of the Status feature: • true - When Status feature is supported on the device • false - When Status feature is not supported on the device Description This function identifies whether the Status feature is available on the DMT module. When this function returns true, these functions are supported on the device: Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 482 • PLIB_DMT_WindowIsOpen • PLIB_DMT_EventOccurred • PLIB_DMT_BAD1Get • PLIB_DMT_BAD2Get Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMT_ExistsStatus( DMT_MODULE_ID index ) PLIB_DMT_ExistsStep1 Function Identifies whether the STEP1 Clear feature exists on the DMT module. File plib_dmt.h C bool PLIB_DMT_ExistsStep1(DMT_MODULE_ID index); Returns • true - The STEP1 Clear feature is supported on the device • false - The STEP1 Clear feature is not supported on the device Description This function identifies whether the Step 1 Clear feature is available on the DMT module. When this function returns true, this function is supported on the device: • PLIB_DMT_ClearStep1 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMT_ExistsStep1( DMT_MODULE_ID index ) PLIB_DMT_ExistsStep2 Function Identifies whether the STEP2 Clear feature exists on the DMT module. File plib_dmt.h C bool PLIB_DMT_ExistsStep2(DMT_MODULE_ID index); Peripheral Libraries Help Deadman Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 483 Returns • true - The STEP2 Clear feature is supported on the device • false - The STEP2 Clear feature is not supported on the device Description This function identifies whether the STEP2 Clear feature is available on the DMT module. When this function returns true, this function is supported on the device: • PLIB_DMT_ClearStep2 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMT_ExistsStep2( DMT_MODULE_ID index ) d) Data Types and Constants DMT_MODULE_ID Enumeration Identifies the supported DMT modules. File plib_dmt_help.h C typedef enum { DMT_ID_0, DMT_NUMBER_OF_MODULES } DMT_MODULE_ID; Members Members Description DMT_ID_0 DMT Module 0 ID DMT_NUMBER_OF_MODULES Number of available WDT modules. Description DMT Module ID This enumeration identifies the available DMT modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Files Files Name Description plib_dmt.h Deadman Timer (DMT) Peripheral Library interface header for Deadman Timer common definitions. plib_dmt_help.h Peripheral Libraries Help Deadman Timer Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 484 Description This section lists the source and header files used by the library. plib_dmt.h Deadman Timer (DMT) Peripheral Library interface header for Deadman Timer common definitions. Functions Name Description PLIB_DMT_BAD1Get Returns BAD1 flag from the DMT Status Register. PLIB_DMT_BAD2Get Returns BAD2 flag from the DMT Status Register. PLIB_DMT_ClearStep1 Resets the DMT module. PLIB_DMT_ClearStep2 Resets the DMT module. PLIB_DMT_CounterGet Returns the DMT counter value. PLIB_DMT_Disable Disables the DMT module. PLIB_DMT_Enable Enables the DMT module. PLIB_DMT_EventOccurred Returns Event flag from the DMT Status Register. PLIB_DMT_ExistsCounter Identifies whether the Counter feature exists on the DMT module. PLIB_DMT_ExistsEnableControl Identifies whether the EnableControl feature exists on the DMT module. PLIB_DMT_ExistsPostscalerInterval Identifies whether the Postscaler Interval feature exists on the DMT module. PLIB_DMT_ExistsPostscalerValue Identifies whether the Postscaler Value feature exists on the DMT module. PLIB_DMT_ExistsStatus Identifies whether the Status feature exists on the DMT module. PLIB_DMT_ExistsStep1 Identifies whether the STEP1 Clear feature exists on the DMT module. PLIB_DMT_ExistsStep2 Identifies whether the STEP2 Clear feature exists on the DMT module. PLIB_DMT_IsEnabled Returns the Deadman Timer on/off(enable/disable) status. PLIB_DMT_PostscalerIntervalGet Returns the DMT postscaler interval value. PLIB_DMT_PostscalerValueGet Returns the DMT postscaler value. PLIB_DMT_WindowIsOpen Returns Window is Open flag from the DMT Status Register. Description Deadman Timer (DMT) Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Deadman Timer Peripheral Library for all families of Microchip microcontrollers. The definitions in this file are common to the Deadman Timer peripheral. File Name plib_dmt.h Company Microchip Technology Inc. plib_dmt_help.h Enumerations Name Description DMT_MODULE_ID Identifies the supported DMT modules. Section Data Types & Constants Peripheral Libraries Help Deadman Timer Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 485 Device Control Peripheral Library This section describes the Device Control Peripheral Library. Introduction Device Control Peripheral Library for Microchip microcontrollers. Description This library provides a low-level abstraction of the Device Control module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby abstracting hardware differences from one microcontroller variant to another. Using the Library This topic describes the basic architecture of the Device Control Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_devcon.h The interface to the Device Control Peripheral Library is defined in the plib_devcon.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Device Control Peripheral Library must include peripheral.h. Library File: The Device Control Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the Device Control module on Microchip family microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The Device Control (DEVCON) peripheral library is a collection of functions that may be used by many different modules to perform tasks not specific to any given module. These functions include: • System Locking and Unlocking • JTAG, and Trace enable/disable • Reading of device ID and version • Other general device configuration settings Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Device Control module. Library Interface Section Description System Functions APIs that are used for general configuration of the module, such as enabling and disabling the Device Control Peripheral Library. Data Types and Constants These data types and constants are required while interacting and configuring the Device Control Peripheral Library. Feature Existence Functions These functions identify whether a particular feature exists on the Device Control Peripheral Library. How the Library Works Provides information on how the library works. Peripheral Libraries Help Device Control Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 486 Description System Locking an Unlocking Many operations require the system to be unlocked prior to the operation being performed. This is to prevent catastrophic failure due to an inadvertent register write. These operations include but are not limited to: • Software reset • Clock, oscillator and peripheral bus frequency changes • System bus access permissions • PPS and PMD control register locking The following functions provide simple APIs to perform system lock/unlock: • PLIB_DEVCON_SystemLock, PLIB_DEVCON_SystemUnlock • PLIB_DEVCON_DeviceRegistersLock, PLIB_DEVCON_DeviceRegistersUnlock (PPS/PMD) JTAG and Trace JTAG and Trace are enabled/disabled using the following functions: • PLIB_DEVCON_JTAGPortEnable, PLIB_DEVCON_JTAGPortEnable • PLIB_DEVCON_2WireJTAGEnableTDO, PLIB_DEVCON_2WireJTAGDisableTDO • PLIB_DEVCON_TraceOutputEnable, PLIB_DEVCON_TraceOutputDisable Device ID and Version Number The device ID and version number are obtained using the following functions: • PLIB_DEVCON_DeviceIdGet • PLIB_DEVCON_DeviceVersionGet General Device Configuration Settings The following functions provide general device configuration settings: • PLIB_DEVCON_AlternateClockEnable, PLIB_DEVCON_AlternateClockDisable • PLIB_DEVCON_FlashErrCorrectionModeSet • PLIB_DEVCON_IgnoreDebugFreezeEnable, PLIB_DEVCON_IgnoreDebugFreezeDisable Configuring the Library The library is configured for the supported Device Control module when the processor is chosen in the MPLAB X IDE. Library Interface a) System Functions Name Description PLIB_DEVCON_2WireJTAGDisableTDO Disables 2-Wire JTAG protocol use of TDO. PLIB_DEVCON_2WireJTAGEnableTDO Enables 2-Wire JTAG protocol to use TDO. PLIB_DEVCON_AlternateClockDisable Disables the alternate clock source for Input Capture or Output Compare modules, The primary clock source will be used instead. PLIB_DEVCON_AlternateClockEnable Selects the alternate clock source for Input Capture or Output Compare modules. PLIB_DEVCON_DeviceIdGet Gets the device identifier. PLIB_DEVCON_DeviceRegistersLock Locks device module registers, preventing modifications to the registers. PLIB_DEVCON_DeviceRegistersUnlock Unlocks device module registers, allowing modifications to the registers. PLIB_DEVCON_DeviceVersionGet Gets the device version. PLIB_DEVCON_FlashErrCorrectionModeSet Sets Flash error correction operation. PLIB_DEVCON_IgnoreDebugFreezeDisable Module stops when commanded by debugger. PLIB_DEVCON_IgnoreDebugFreezeEnable Allows module to ignore FREEZE command from debugger and continue running. PLIB_DEVCON_JTAGPortDisable Disables the JTAG port on the device. PLIB_DEVCON_JTAGPortEnable Enables the JTAG port on the device. PLIB_DEVCON_SystemLock Executes the system lock sequence. PLIB_DEVCON_SystemUnlock Executes the system unlock sequence. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 487 PLIB_DEVCON_TraceOutputDisable Disables trace outputs and the stop trace clock. PLIB_DEVCON_TraceOutputEnable Enables trace outputs and the start trace clock. PLIB_DEVCON_USBPHYSleepModeSet Selects USB PHY clocking during Sleep mode. PLIB_DEVCON_AnalogIOChargePumpDisable Disables the I/O Analog Charge Pump on the device. PLIB_DEVCON_AnalogIOChargePumpEnable Enables the I/O Analog Charge Pump on the device. PLIB_DEVCON_ExistsAnalogChargePumpControl Identifies whether the I/O Analog Charge Pump feature exists on the DEVCON module. PLIB_DEVCON_BootExtSelect Routes SPI0 pins to the PIC32WK pads. PLIB_DEVCON_BootIPFSelect Routes SPI0 pins to In-Package Flash. PLIB_DEVCON_HSUARTDisable Disables High Speed UART. PLIB_DEVCON_HSUARTEnable Enables High Speed UART. PLIB_DEVCON_OTPConfigLock Locks or unlocks the configuration registers. PLIB_DEVCON_OTPConfigUnlock unlocks the configuration registers. b) MPLL Functions Name Description PLIB_DEVCON_MPLLDisable Disables the MPLL. PLIB_DEVCON_MPLLEnable Enables the MPLL. PLIB_DEVCON_MPLLInputDivSet Sets the MPLL Input Divider bits. PLIB_DEVCON_MPLLIsReady Reads MPLL status. PLIB_DEVCON_MPLLMultiplierSet Sets the MPLL Multiplier bits. PLIB_DEVCON_MPLLODiv1Set Sets the MPLL output divider 1 bits. PLIB_DEVCON_MPLLODiv2Set Sets the MPLL output divider 2 bits. PLIB_DEVCON_MPLLVrefSet Sets the VREF control setting. PLIB_DEVCON_MPLLVregDisable Disables the MPLL VREG. PLIB_DEVCON_MPLLVregEnable Enables the MPLL VREG. PLIB_DEVCON_MPLLVregIsReady Reads the MPLL VREG status. c) Feature Existence Functions Name Description PLIB_DEVCON_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the DEVCON module. PLIB_DEVCON_ExistsDeviceRegsLockUnlock Identifies whether the DeviceRegsLockUnlock feature exists on the DEVCON module. PLIB_DEVCON_ExistsDeviceVerAndId Identifies whether the DeviceVerAndId feature exists on the DEVCON module. PLIB_DEVCON_ExistsECCModes Identifies whether the ECCModes feature exists on the DEVCON module. PLIB_DEVCON_ExistsIgnoreDebugFreeze Identifies whether the IgnoreDebugFreeze feature exists on the DEVCON module. PLIB_DEVCON_ExistsJTAGEnable Identifies whether the JTAGEnable feature exists on the DEVCON module. PLIB_DEVCON_ExistsJTAGUsesTDO Identifies whether the JTAGUsesTDO feature exists on the DEVCON module. PLIB_DEVCON_ExistsSystemLockUnlock Identifies whether the SysLockUnlock feature exists on the DEVCON module. PLIB_DEVCON_ExistsTraceOutput Identifies whether the TraceOutput feature exists on the DEVCON module. PLIB_DEVCON_ExistsUSB_PHY_SleepModeSet Identifies whether the USB_PHY_SleepModeSet feature exists on the DEVCON module. PLIB_DEVCON_ExistsMPLL Identifies whether the MPLL feature exists on the DEVCON module. PLIB_DEVCON_ExistsBootSelection Identifies whether the BootSelection feature exists on the DEVCON module PLIB_DEVCON_ExistsHSUARTControl Identifies whether the HSUARTControl feature exists on the DEVCON module PLIB_DEVCON_ExistsOTPConfigLockUnlock Identifies whether the OTPConfigLockUnlock feature exists on the DEVCON module d) Data Types and Constants Name Description DEVCON_ALT_CLOCK_TARGET Selects Input Capture or Output Compare modules. DEVCON_DEBUG_PERIPHERAL Sets modules to ignore debugger's freeze command. DEVCON_ECC_CONFIG Selects how ECC is applied to Flash memory. DEVCON_REGISTER_SET Selects module registers for write lock or unlock. DEVCON_USB_SLEEP_MODE Selects whether the USB clock operates in Sleep mode. DEVCON_MODULE_ID Identifies the supported DEVCON modules. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 488 DEVCON_MPLL_OUTPUT_DIVIDER Specifies the MPLL Output divider bits. DEVCON_MPLL_VREF_CONTROL VREF control. Description This section describes the Application Programming Interface (API) functions of the Device Control Peripheral Library. Refer to each section for a detailed description. a) System Functions PLIB_DEVCON_2WireJTAGDisableTDO Function Disables 2-Wire JTAG protocol use of TDO. File plib_devcon.h C void PLIB_DEVCON_2WireJTAGDisableTDO(DEVCON_MODULE_ID index); Returns None. Description This function disables 2-Wire JTAG protocol use of TDO. Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Parameters Parameters Description index Always DEVCON_ID Function void PLIB_DEVCON_2WireJTAGDisableTDO( DEVCON_MODULE_ID index) PLIB_DEVCON_2WireJTAGEnableTDO Function Enables 2-Wire JTAG protocol to use TDO. File plib_devcon.h C void PLIB_DEVCON_2WireJTAGEnableTDO(DEVCON_MODULE_ID index); Returns None. Description This function enables 2-Wire JTAG protocol to use TDO. Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 489 Parameters Parameters Description index Always DEVCON_ID Function void PLIB_DEVCON_2WireJTAGEnableTDO( DEVCON_MODULE_ID index) PLIB_DEVCON_AlternateClockDisable Function Disables the alternate clock source for Input Capture or Output Compare modules, The primary clock source will be used instead. File plib_devcon.h C void PLIB_DEVCON_AlternateClockDisable(DEVCON_MODULE_ID index, DEVCON_ALT_CLOCK_TARGET targetAltClock); Returns None. Description This function disables the alternate clock source for the Input Capture or Output Compare modules. The primary clock source will be used instead. Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. A system unlock must be performed before this function can be executed. Preconditions None. Example // Call system service to unlock oscillator PLIB_DEVCON_AlternateClockDisable(DEVCON_ID, DEVCON_ALT_CLOCK_IC || DEVCON_ALT_CLOCK_OC ); Parameters Parameters Description index Always DEVCON_ID targetAltClock DEVCON_ALT_CLOCK_IC or DEVCON_ALT_CLOCK_OC Function void PLIB_DEVCON_AlternateClockDisable( DEVCON_MODULE_ID index, DEVCON_ALT_CLOCK_TARGET targetAltClock ) PLIB_DEVCON_AlternateClockEnable Function Selects the alternate clock source for Input Capture or Output Compare modules. File plib_devcon.h C void PLIB_DEVCON_AlternateClockEnable(DEVCON_MODULE_ID index, DEVCON_ALT_CLOCK_TARGET targetAltClock); Returns None. Description This function selects the alternate clock source for the Input Capture or Output Compare modules. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 490 Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. A system unlock must be performed before this function can be executed. Preconditions None. Example // Call system service to unlock oscillator PLIB_DEVCON_AlternateClockEnable(DEVCON_ID, DEVCON_ALT_CLOCK_IC || DEVCON_ALT_CLOCK_OC ); Parameters Parameters Description index Always DEVCON_ID targetAltClock DEVCON_ALT_CLOCK_IC or DEVCON_ALT_CLOCK_OC Function void PLIB_DEVCON_AlternateClockEnable( DEVCON_MODULE_ID index, DEVCON_ALT_CLOCK_TARGET targetAltClock ) PLIB_DEVCON_DeviceIdGet Function Gets the device identifier. File plib_devcon.h C uint32_t PLIB_DEVCON_DeviceIdGet(DEVCON_MODULE_ID index); Returns The version of the device. Description This function returns the device identifier. Remarks None. Preconditions None. Parameters Parameters Description index Always DEVCON_ID Function uint32_t PLIB_DEVCON_DeviceIdGet( DEVCON_MODULE_ID index) PLIB_DEVCON_DeviceRegistersLock Function Locks device module registers, preventing modifications to the registers. File plib_devcon.h C void PLIB_DEVCON_DeviceRegistersLock(DEVCON_MODULE_ID index, DEVCON_REGISTER_SET registersToLock); Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 491 Returns None. Description This function locks device module registers, preventing modifications to the registers. Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. A system unlock must be performed before this function can be executed. Preconditions None. Example // Call system service to unlock oscillator PLIB_DEVCON_DeviceRegistersLock(DEVCON_ID, DEVCON_ALL_REGISTERS); PLIB_DEVCON_DeviceRegistersUnlock(DEVCON_ID,DEVCON_PPS_REGISTERS); Parameters Parameters Description index Always DEVCON_ID registersToLock element from DEVCON_REGISTER_SET, which can be ORed together Function void PLIB_DEVCON_DeviceRegistersLock( DEVCON_MODULE_ID index, DEVCON_REGISTER_SET registersToLock ) PLIB_DEVCON_DeviceRegistersUnlock Function Unlocks device module registers, allowing modifications to the registers. File plib_devcon.h C void PLIB_DEVCON_DeviceRegistersUnlock(DEVCON_MODULE_ID index, DEVCON_REGISTER_SET registersToLock); Returns None. Description This function unlocks device module registers, allowing modifications to the registers. Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. A system unlock must be performed before this function can be executed. Preconditions None. Example // Call system service to unlock oscillator PLIB_DEVCON_DeviceRegistersLock(DEVCON_ID, DEVCON_ALL_REGISTERS); PLIB_DEVCON_DeviceRegistersUnlock(DEVCON_ID,DEVCON_PPS_REGISTERS); Parameters Parameters Description index Always DEVCON_ID registersToLock element from DEVCON_REGISTER_SET, which can be ORed together Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 492 Function void PLIB_DEVCON_DeviceRegistersUnlock( DEVCON_MODULE_ID index, DEVCON_REGISTER_SET registersToLock ) PLIB_DEVCON_DeviceVersionGet Function Gets the device version. File plib_devcon.h C uint8_t PLIB_DEVCON_DeviceVersionGet(DEVCON_MODULE_ID index); Returns The version of the device. Description This functions returns the device version. Remarks None. Preconditions None. Parameters Parameters Description index Always DEVCON_ID Function uint8_t PLIB_DEVCON_DeviceVersionGet( DEVCON_MODULE_ID index) PLIB_DEVCON_FlashErrCorrectionModeSet Function Sets Flash error correction operation. File plib_devcon.h C void PLIB_DEVCON_FlashErrCorrectionModeSet(DEVCON_MODULE_ID index, DEVCON_ECC_CONFIG flashECC); Returns None. Description This function sets Flash error correction operation. Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. Once ECC has been locked, it cannot be unlocked except through a system reset. Preconditions None. Example Parameters Parameters Description index Always DEVCON_ID Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 493 flashECC DEVCON_ECC_DISABLED, DEVCON_ECC_DISABLED_LOCKED, DEVCON_DYN_ECC_ENABLED_LOCKED, or DEVCON_FLASH_ECC_ENABLED_LOCKED Function void PLIB_DEVCON_FlashErrCorrectionModeSet( DEVCON_MODULE_ID index, DEVCON_ECC_CONFIG flashECC) PLIB_DEVCON_IgnoreDebugFreezeDisable Function Module stops when commanded by debugger. File plib_devcon.h C void PLIB_DEVCON_IgnoreDebugFreezeDisable(DEVCON_MODULE_ID index, DEVCON_DEBUG_PERIPHERAL myPeripheral); Returns None. Description This function stops the module when commanded by the debugger. Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. Peripherals can be ORed together. Preconditions None. Example PLIB_DEVCON_DebugIgnoreFreezeEnable(DEVCON_ID,DEVCON_DEBUG_ALL); PLIB_DEVCON_DebugIgnoreFreezeDisable(DEVCON_ID,DEVCON_DEBUG_SPI1); Parameters Parameters Description index Always DEVCON_ID myPeripheral DEVCON_DEBUG_USB, DEVCON_DEBUG_UART1, DEVCON_DEBUG_UART2, DEVCON_DEBUG_SPI1, or DEVCON_DEBUG_ALL (for all modules) Function void PLIB_DEVCON_IgnoreDebugFreezeDisable( DEVCON_MODULE_ID index, DEVCON_DEBUG_PERIPHERAL myPeripheral ) PLIB_DEVCON_IgnoreDebugFreezeEnable Function Allows module to ignore FREEZE command from debugger and continue running. File plib_devcon.h C void PLIB_DEVCON_IgnoreDebugFreezeEnable(DEVCON_MODULE_ID index, DEVCON_DEBUG_PERIPHERAL myPeripheral); Returns None. Description This function allows the module to ignore the FREEZE command from the debugger and continue running. Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. Peripherals can be ORed together. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 494 Preconditions None. Example PLIB_DEVCON_DebugIgnoreFreezeEnable(DEVCON_ID,DEVCON_DEBUG_ALL); PLIB_DEVCON_DebugIgnoreFreezeDisable(DEVCON_ID,DEVCON_DEBUG_SPI1); Parameters Parameters Description index Always DEVCON_ID myPeripheral DEVCON_DEBUG_USB, DEVCON_DEBUG_UART1, DEVCON_DEBUG_UART2, DEVCON_DEBUG_SPI1, or DEVCON_DEBUG_ALL (for all modules) Function void PLIB_DEVCON_IgnoreDebugFreezeEnable( DEVCON_MODULE_ID index, DEVCON_DEBUG_PERIPHERAL myPeripheral ) PLIB_DEVCON_JTAGPortDisable Function Disables the JTAG port on the device. File plib_devcon.h C void PLIB_DEVCON_JTAGPortDisable(DEVCON_MODULE_ID index); Returns None. Description This function disables the JTAG port on the device. Remarks None. Preconditions None. Parameters Parameters Description index Always DEVCON_ID Function void PLIB_DEVCON_JTAGPortDisable( DEVCON_MODULE_ID index) PLIB_DEVCON_JTAGPortEnable Function Enables the JTAG port on the device. File plib_devcon.h C void PLIB_DEVCON_JTAGPortEnable(DEVCON_MODULE_ID index); Returns None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 495 Description This function enables the JTAG port on the device. Remarks None. Preconditions None. Parameters Parameters Description index Always DEVCON_ID Function void PLIB_DEVCON_JTAGPortEnable( DEVCON_MODULE_ID index) PLIB_DEVCON_SystemLock Function Executes the system lock sequence. File plib_devcon.h C void PLIB_DEVCON_SystemLock(DEVCON_MODULE_ID index); Returns None. Description This function executes the system lock sequence. Remarks Should only be called after PLIB_DEVCON_SystemUnlock and the action that required the unlock have been performed. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_SystemLock( DEVCON_MODULE_ID index ) PLIB_DEVCON_SystemUnlock Function Executes the system unlock sequence. File plib_devcon.h C void PLIB_DEVCON_SystemUnlock(DEVCON_MODULE_ID index); Returns None. Description This function executes the system unlock sequence. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 496 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_SystemUnlock( DEVCON_MODULE_ID index ) PLIB_DEVCON_TraceOutputDisable Function Disables trace outputs and the stop trace clock. File plib_devcon.h C void PLIB_DEVCON_TraceOutputDisable(DEVCON_MODULE_ID index); Returns None. Description This function disables trace outputs and the stop trace clock. Preconditions None. Parameters Parameters Description index Always DEVCON_ID Function void PLIB_DEVCON_TraceOutputDisable( DEVCON_MODULE_ID index) PLIB_DEVCON_TraceOutputEnable Function Enables trace outputs and the start trace clock. File plib_devcon.h C void PLIB_DEVCON_TraceOutputEnable(DEVCON_MODULE_ID index); Returns None. Description This function enables trace outputs and the start trace clock (trace probe must be present). Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 497 Parameters Parameters Description index Always DEVCON_ID Function void PLIB_DEVCON_TraceOutputEnable( DEVCON_MODULE_ID index) PLIB_DEVCON_USBPHYSleepModeSet Function Selects USB PHY clocking during Sleep mode. File plib_devcon.h C void PLIB_DEVCON_USBPHYSleepModeSet(DEVCON_MODULE_ID index, DEVCON_USB_SLEEP_MODE sleepOrRun); Returns None. Description This function selects USB PHY clocking during Sleep mode. Remarks The feature is not supported on all devices. Refer to the specific device data sheet to determine availability. A system unlock must be performed before this function can be executed. Preconditions None. Example // Call system service to unlock oscillator PLIB_DEVCON_USBPHYSleepModeSet(DEVCON_ID,DEVCON_USB_NO_CLOCK_IN_SLEEP) Parameters Parameters Description index Always DEVCON_ID sleepOrRun DEVCON_USB_NO_CLOCK_IN_SLEEP or DEVCON_USB_CLOCK_IN_SLEEP Function void PLIB_DEVCON_USBPHYSleepModeSet( DEVCON_MODULE_ID index, DEVCON_USB_SLEEP_MODE sleepOrRun) PLIB_DEVCON_AnalogIOChargePumpDisable Function Disables the I/O Analog Charge Pump on the device. File plib_devcon.h C void PLIB_DEVCON_AnalogIOChargePumpDisable(DEVCON_MODULE_ID index); Returns None. Description This function disables the I/O Analog Charge Pump on the device. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 498 Remarks None. Preconditions None. Parameters Parameters Description index Always DEVCON_ID Function void PLIB_DEVCON_AnalogIOChargePumpDisable( DEVCON_MODULE_ID index) PLIB_DEVCON_AnalogIOChargePumpEnable Function Enables the I/O Analog Charge Pump on the device. File plib_devcon.h C void PLIB_DEVCON_AnalogIOChargePumpEnable(DEVCON_MODULE_ID index); Returns None. Description This function enables the I/O Analog Charge Pump on the device. Remarks None. Preconditions None. Parameters Parameters Description index Always DEVCON_ID Function void PLIB_DEVCON_AnalogIOChargePumpEnable( DEVCON_MODULE_ID index) PLIB_DEVCON_ExistsAnalogChargePumpControl Function Identifies whether the I/O Analog Charge Pump feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsAnalogChargePumpControl(DEVCON_MODULE_ID index); Returns • true - The I/O Analog Charge Pump feature feature is supported on the device • false - The I/O Analog Charge Pump feature feature is not supported on the device Description This function identifies whether the I/O Analog Charge Pump feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_AnalogIOChargePumpEnable Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 499 • PLIB_DEVCON_AnalogIOChargePumpDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsAnalogChargePumpControl( DEVCON_MODULE_ID index ) PLIB_DEVCON_BootExtSelect Function Routes SPI0 pins to the PIC32WK pads. File plib_devcon.h C void PLIB_DEVCON_BootExtSelect(DEVCON_MODULE_ID index); Returns None. Description This function routes the SPI0 pins to the PIC32WK pads. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function void PLIB_DEVCON_BootExtSelect( DEVCON_MODULE_ID index) PLIB_DEVCON_BootIPFSelect Function Routes SPI0 pins to In-Package Flash. File plib_devcon.h C void PLIB_DEVCON_BootIPFSelect(DEVCON_MODULE_ID index); Returns None. Description This function routes the SPI0 pins to In-Package Flash. Remarks None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 500 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function void PLIB_DEVCON_BootIPFSelect( DEVCON_MODULE_ID index) PLIB_DEVCON_HSUARTDisable Function Disables High Speed UART. File plib_devcon.h C void PLIB_DEVCON_HSUARTDisable(DEVCON_MODULE_ID index); Returns None. Description This function disables the high speed UART and UART 1 can be configured with PPS. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function void PLIB_DEVCON_HSUARTDisable( DEVCON_MODULE_ID index) PLIB_DEVCON_HSUARTEnable Function Enables High Speed UART. File plib_devcon.h C void PLIB_DEVCON_HSUARTEnable(DEVCON_MODULE_ID index); Returns None. Description This function enables the high speed UART and UART 1 will be using dedicated UART pin. Remarks None. Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 501 Parameters Parameters Description index Identifier for the device instance Function void PLIB_DEVCON_HSUARTEnable( DEVCON_MODULE_ID index) PLIB_DEVCON_OTPConfigLock Function Locks or unlocks the configuration registers. File plib_devcon.h C void PLIB_DEVCON_OTPConfigLock(DEVCON_MODULE_ID index, DEVCON_CFGLOCK lockType); Returns None. Description This function locks or unlocks the configuration register as per the locktype specified. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance lockType Enumerated config lock value Function void PLIB_DEVCON_OTPConfigLock( DEVCON_MODULE_ID index, DEVCON_CFGLOCK lockType) PLIB_DEVCON_OTPConfigUnlock Function unlocks the configuration registers. File plib_devcon.h C void PLIB_DEVCON_OTPConfigUnlock(DEVCON_MODULE_ID index); Returns None. Description This function unlocks the configuration register provided, the CFGLOCK field is not to a value to locked until the reset. Remarks None. Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 502 Parameters Parameters Description index Identifier for the device instance Function void PLIB_DEVCON_OTPConfigUnlock( DEVCON_MODULE_ID index) b) MPLL Functions PLIB_DEVCON_MPLLDisable Function Disables the MPLL. File plib_devcon.h C void PLIB_DEVCON_MPLLDisable(DEVCON_MODULE_ID index); Returns None. Description This function disables the MPLL. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_MPLLDisable( DEVCON_MODULE_ID index ) PLIB_DEVCON_MPLLEnable Function Enables the MPLL. File plib_devcon.h C void PLIB_DEVCON_MPLLEnable(DEVCON_MODULE_ID index); Returns None. Description This function enables the MPLL. Remarks None. Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 503 Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_MPLLEnable( DEVCON_MODULE_ID index ) PLIB_DEVCON_MPLLInputDivSet Function Sets the MPLL Input Divider bits. File plib_devcon.h C void PLIB_DEVCON_MPLLInputDivSet(DEVCON_MODULE_ID index, uint8_t value); Returns None. Description This function sets the MPLL Input Divider bits. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance value Multiplier value (between 1 & 63) Function PLIB_DEVCON_MPLLInputDivSet( DEVCON_MODULE_ID index, uint8_t value ) PLIB_DEVCON_MPLLIsReady Function Reads MPLL status. File plib_devcon.h C bool PLIB_DEVCON_MPLLIsReady(DEVCON_MODULE_ID index); Returns • true - MPLL clock is stable • false - MPLL clock is not stable Description This function reads MPLL status. Remarks None. Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 504 Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_MPLLIsReady( DEVCON_MODULE_ID index ) PLIB_DEVCON_MPLLMultiplierSet Function Sets the MPLL Multiplier bits. File plib_devcon.h C void PLIB_DEVCON_MPLLMultiplierSet(DEVCON_MODULE_ID index, uint8_t value); Returns None. Description This function sets the MPLL Multiplier bits. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance value Multiplier value (between 16 & 160) Function PLIB_DEVCON_MPLLMultiplierSet( DEVCON_MODULE_ID index, uint8_t value ) PLIB_DEVCON_MPLLODiv1Set Function Sets the MPLL output divider 1 bits. File plib_devcon.h C void PLIB_DEVCON_MPLLODiv1Set(DEVCON_MODULE_ID index, DEVCON_MPLL_OUTPUT_DIVIDER bits); Returns None. Description This function sets the MPLL output divider 1 bits. Remarks None. Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 505 Parameters Parameters Description index Identifier for the device instance bits Enumerated divider value Function PLIB_DEVCON_MPLLODiv1Set( DEVCON_MODULE_ID index, DEVCON_MPLL_OUTPUT_DIVIDER bits ) PLIB_DEVCON_MPLLODiv2Set Function Sets the MPLL output divider 2 bits. File plib_devcon.h C void PLIB_DEVCON_MPLLODiv2Set(DEVCON_MODULE_ID index, DEVCON_MPLL_OUTPUT_DIVIDER bits); Returns None. Description This function sets the MPLL output divider 2 bits. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance bits Enumerated divider value Function PLIB_DEVCON_MPLLODiv2Set( DEVCON_MODULE_ID index, DEVCON_MPLL_OUTPUT_DIVIDER bits ) PLIB_DEVCON_MPLLVrefSet Function Sets the VREF control setting. File plib_devcon.h C void PLIB_DEVCON_MPLLVrefSet(DEVCON_MODULE_ID index, DEVCON_MPLL_VREF_CONTROL vref); Returns None. Description This function sets the VREF control setting. Remarks None. Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 506 Parameters Parameters Description index Identifier for the device instance value Enumerated VREF Control setting Function PLIB_DEVCON_MPLLVrefSet( DEVCON_MODULE_ID index, DEVCON_MPLL_VREF_CONTROL vref ) PLIB_DEVCON_MPLLVregDisable Function Disables the MPLL VREG. File plib_devcon.h C void PLIB_DEVCON_MPLLVregDisable(DEVCON_MODULE_ID index); Returns None. Description This function disables the MPLL VREG. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_MPLLVregDisable( DEVCON_MODULE_ID index ) PLIB_DEVCON_MPLLVregEnable Function Enables the MPLL VREG. File plib_devcon.h C void PLIB_DEVCON_MPLLVregEnable(DEVCON_MODULE_ID index); Returns None. Description This function enables the MPLL VREG. Remarks None. Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 507 Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_MPLLVregEnable( DEVCON_MODULE_ID index ) PLIB_DEVCON_MPLLVregIsReady Function Reads the MPLL VREG status. File plib_devcon.h C bool PLIB_DEVCON_MPLLVregIsReady(DEVCON_MODULE_ID index); Returns • true - MPLL VREG is ready • false - MPLL VREG is not ready Description This function reads the MPLL VREG status. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_MPLLVregIsReady( DEVCON_MODULE_ID index ) c) Feature Existence Functions PLIB_DEVCON_ExistsAlternateClock Function Identifies whether the AlternateClock feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsAlternateClock(DEVCON_MODULE_ID index); Returns • true - The AlternateClock feature is supported on the device • false - The AlternateClock feature is not supported on the device Description This function identifies whether the AlternateClock feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_AlternateClockEnable • PLIB_DEVCON_AlternateClockDisable Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 508 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsAlternateClock( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsDeviceRegsLockUnlock Function Identifies whether the DeviceRegsLockUnlock feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsDeviceRegsLockUnlock(DEVCON_MODULE_ID index); Returns • true - The DeviceRegsLockUnlock feature is supported on the device • false - The DeviceRegsLockUnlock feature is not supported on the device Description This function identifies whether the DeviceRegsLockUnlock feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_DeviceRegistersLock • PLIB_DEVCON_DeviceRegistersUnlock Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsDeviceRegsLockUnlock( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsDeviceVerAndId Function Identifies whether the DeviceVerAndId feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsDeviceVerAndId(DEVCON_MODULE_ID index); Returns • true - The DeviceVerAndId feature is supported on the device • false - The DeviceVerAndId feature is not supported on the device Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 509 Description This function identifies whether the DeviceVerAndId feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_DeviceVersionGet • PLIB_DEVCON_DeviceIdGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsDeviceVerAndId( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsECCModes Function Identifies whether the ECCModes feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsECCModes(DEVCON_MODULE_ID index); Returns • true - The ECCModes feature is supported on the device • false - The ECCModes feature is not supported on the device Description This function identifies whether the ECCModes feature is available on the DEVCON module. When this function returns true, this function is supported on the device: • PLIB_DEVCON_FlashErrCorrectionModeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsECCModes( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsIgnoreDebugFreeze Function Identifies whether the IgnoreDebugFreeze feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsIgnoreDebugFreeze(DEVCON_MODULE_ID index); Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 510 Returns • true - The IgnoreDebugFreeze feature is supported on the device • false - The IgnoreDebugFreeze feature is not supported on the device Description This function identifies whether the IgnoreDebugFreeze feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_DebugIgnoreFreezeEnable • PLIB_DEVCON_IgnoreDebugFreezeDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsIgnoreDebugFreeze( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsJTAGEnable Function Identifies whether the JTAGEnable feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsJTAGEnable(DEVCON_MODULE_ID index); Returns • true - The JTAGEnable feature is supported on the device • false - The JTAGEnable feature is not supported on the device Description This function identifies whether the JTAGEnable feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_JTAGPortEnable • PLIB_DEVCON_JTAGPortDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsJTAGEnable( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsJTAGUsesTDO Function Identifies whether the JTAGUsesTDO feature exists on the DEVCON module. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 511 File plib_devcon.h C bool PLIB_DEVCON_ExistsJTAGUsesTDO(DEVCON_MODULE_ID index); Returns • true - The JTAGUsesTDO feature is supported on the device • false - The JTAGUsesTDO feature is not supported on the device Description This function identifies whether the JTAGUsesTDO feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_2WireJTAGEnableTDO • PLIB_DEVCON_2WireJTAGDisableTDO Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsJTAGUsesTDO( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsSystemLockUnlock Function Identifies whether the SysLockUnlock feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsSystemLockUnlock(DEVCON_MODULE_ID index); Returns • true - The SysLockUnlock feature is supported on the device • false - The SysLockUnlock feature is not supported on the device Description This function identifies whether the SysLockUnlock feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_SystemUnlock • PLIB_DEVCON_SystemLock Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsSystemLockUnlock( DEVCON_MODULE_ID index ) Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 512 PLIB_DEVCON_ExistsTraceOutput Function Identifies whether the TraceOutput feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsTraceOutput(DEVCON_MODULE_ID index); Returns • true - The TraceOutput feature is supported on the device • false - The TraceOutput feature is not supported on the device Description This function identifies whether the TraceOutput feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_TraceOutputEnable • PLIB_DEVCON_TraceOutputDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsTraceOutput( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsUSB_PHY_SleepModeSet Function Identifies whether the USB_PHY_SleepModeSet feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsUSB_PHY_SleepModeSet(DEVCON_MODULE_ID index); Returns • true - The USB_PHY_SleepModeSet feature is supported on the device • false - The USB_PHY_SleepModeSet feature is not supported on the device Description This function identifies whether the USB_PHY_SleepModeSet feature is available on the DEVCON module. When this function returns true, this function is supported on the device: • PLIB_DEVCON_USBPHYSleepModeSet Remarks None. Preconditions None. Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 513 Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsUSB_PHY_SleepModeSet( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsMPLL Function Identifies whether the MPLL feature exists on the DEVCON module. File plib_devcon.h C bool PLIB_DEVCON_ExistsMPLL(DEVCON_MODULE_ID index); Returns • true - The MPLL feature is supported on the device • false - The MPLL feature is not supported on the device Description This function identifies whether the MPLL feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_MPLLIsReady • PLIB_DEVCON_MPLLEnable • PLIB_DEVCON_MPLLDisable • PLIB_DEVCON_MPLLODiv1Set • PLIB_DEVCON_MPLLODiv2Set • PLIB_DEVCON_MPLLVregIsReady • PLIB_DEVCON_MPLLVregEnable • PLIB_DEVCON_MPLLVregDisable • PLIB_DEVCON_MPLLMultiplierSet • PLIB_DEVCON_MPLLInputDivSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsMPLL( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsBootSelection Function Identifies whether the BootSelection feature exists on the DEVCON module File plib_devcon.h C bool PLIB_DEVCON_ExistsBootSelection(DEVCON_MODULE_ID index); Returns • true - The BootSelection feature is supported on the device Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 514 • false - The BootSelection feature is not supported on the device Description This function identifies whether the BootSelection feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_BootIPFSelect • PLIB_DEVCON_BootExtSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsBootSelection( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsHSUARTControl Function Identifies whether the HSUARTControl feature exists on the DEVCON module File plib_devcon.h C bool PLIB_DEVCON_ExistsHSUARTControl(DEVCON_MODULE_ID index); Returns • true - The HSUARTControl feature is supported on the device • false - The HSUARTControl feature is not supported on the device Description This function identifies whether the HSUARTControl feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_HSUARTEnable • PLIB_DEVCON_HSUARTDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsHSUARTControl( DEVCON_MODULE_ID index ) PLIB_DEVCON_ExistsOTPConfigLockUnlock Function Identifies whether the OTPConfigLockUnlock feature exists on the DEVCON module File plib_devcon.h Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 515 C bool PLIB_DEVCON_ExistsOTPConfigLockUnlock(DEVCON_MODULE_ID index); Returns • true - The OTPConfigLockUnlock feature is supported on the device • false - The OTPConfigLockUnlock feature is not supported on the device Description This function identifies whether the OTPConfigLockUnlock feature is available on the DEVCON module. When this function returns true, these functions are supported on the device: • PLIB_DEVCON_OTPConfigLock • PLIB_DEVCON_OTPConfigUnlock Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DEVCON_ExistsOTPConfigLockUnlock( DEVCON_MODULE_ID index ) d) Data Types and Constants DEVCON_ALT_CLOCK_TARGET Enumeration Selects Input Capture or Output Compare modules. File plib_devcon.h C typedef enum { DEVCON_ALT_CLOCK_IC, DEVCON_ALT_CLOCK_OC } DEVCON_ALT_CLOCK_TARGET; Members Members Description DEVCON_ALT_CLOCK_IC Input Capture DEVCON_ALT_CLOCK_OC Output Compare Description Alternate Clock Targets Enumeration This enumeration selects the Input Capture or Output Compare module for enabling or disabling the alternate clock. Remarks None. DEVCON_DEBUG_PERIPHERAL Enumeration Sets modules to ignore debugger's freeze command. File plib_devcon.h Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 516 C typedef enum { DEVCON_DEBUG_USB, DEVCON_DEBUG_UART1, DEVCON_DEBUG_UART2, DEVCON_DEBUG_SPI1, DEVCON_DEBUG_ALL } DEVCON_DEBUG_PERIPHERAL; Members Members Description DEVCON_DEBUG_USB USB module DEVCON_DEBUG_UART1 UART 1 DEVCON_DEBUG_UART2 UART 2 DEVCON_DEBUG_SPI1 SPI 1 DEVCON_DEBUG_ALL USB, UART 1, UART 2, and SPI 1 Description Ignore Debugger Freeze for Peripheral Module(s) enumeration This enumeration sets modules to ignore the debugger's freeze command. Remarks None. DEVCON_ECC_CONFIG Enumeration Selects how ECC is applied to Flash memory. File plib_devcon.h C typedef enum { DEVCON_ECC_DISABLED, DEVCON_ECC_DISABLED_LOCKED, DEVCON_DYN_ECC_ENABLED_LOCKED, DEVCON_FLASH_ECC_ENABLED_LOCKED } DEVCON_ECC_CONFIG; Members Members Description DEVCON_ECC_DISABLED ECC and dynamic ECC are disabled DEVCON_ECC_DISABLED_LOCKED ECC and dynamic ECC are disabled and the configuration locked DEVCON_DYN_ECC_ENABLED_LOCKED Dynamic Flash ECC is enabled and the configuration is locked DEVCON_FLASH_ECC_ENABLED_LOCKED Flash ECC is enabled, the configuration is locked, word Flash writes disabled Description Flash Error Correcting Code (ECC) Configuration enumeration This enumeration selects how ECC is applied to Flash memory. Remarks None. DEVCON_REGISTER_SET Enumeration Selects module registers for write lock or unlock. File plib_devcon.h Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 517 C typedef enum { DEVCON_PPS_REGISTERS, DEVCON_PMD_REGISTERS, DEVCON_PERMISSION_GROUP_REGISTERS, DEVCON_ALL_REGISTERS } DEVCON_REGISTER_SET; Members Members Description DEVCON_PPS_REGISTERS Peripheral Pin Select registers DEVCON_PMD_REGISTERS Peripheral Module Disable registers DEVCON_PERMISSION_GROUP_REGISTERS Permission Group registers DEVCON_ALL_REGISTERS All lockable registers Description Module Registers for Lock/Unlock enumeration. This enumeration selects the module registers for write lock or unlock. Remarks Can be ORed together. DEVCON_USB_SLEEP_MODE Enumeration Selects whether the USB clock operates in Sleep mode. File plib_devcon.h C typedef enum { DEVCON_USB_NO_CLOCK_IN_SLEEP, DEVCON_USB_CLOCK_IN_SLEEP } DEVCON_USB_SLEEP_MODE; Members Members Description DEVCON_USB_NO_CLOCK_IN_SLEEP USB PHY clock is shut down when Sleep mode is active. DEVCON_USB_CLOCK_IN_SLEEP USP PHY clock continues to run when Sleep mode is active Description USB Clock In Sleep Mode Enumeration This enumeration selects whether the USB clock operates in Sleep mode. Remarks None. DEVCON_MODULE_ID Enumeration Identifies the supported DEVCON modules. File help_plib_devcon.h C typedef enum { DEVCON_ID_0, DEVCON_NUMBER_OF_MODULES } DEVCON_MODULE_ID; Peripheral Libraries Help Device Control Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 518 Members Members Description DEVCON_ID_0 DEVCON Module 0 ID DEVCON_NUMBER_OF_MODULES Number of available DEVCON modules. Description DEVCON Module ID This enumeration identifies the DEVCON modules that are available on the microcontroller. This is the super set of all the possible instances that might be available on the Microchip microcontrollers. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. DEVCON_MPLL_OUTPUT_DIVIDER Enumeration Specifies the MPLL Output divider bits. File plib_devcon.h C typedef enum { DEVCON_MPLL_ODIV_1, DEVCON_MPLL_ODIV_2, DEVCON_MPLL_ODIV_3, DEVCON_MPLL_ODIV_4, DEVCON_MPLL_ODIV_5, DEVCON_MPLL_ODIV_6, DEVCON_MPLL_ODIV_7 } DEVCON_MPLL_OUTPUT_DIVIDER; Description MPLL Output Divider bits enumeration This enumeration specifies the MPLL Output divider bits. Remarks None. DEVCON_MPLL_VREF_CONTROL Enumeration VREF control. File plib_devcon.h C typedef enum { DEVCON_MPLL_VREF_EXT, DEVCON_MPLL_VREF_VDD, DEVCON_MPLL_VREF_VSS, DEVCON_MPLL_VREF_INT } DEVCON_MPLL_VREF_CONTROL; Description MPLL VREF Control enumeration This enumeration provides VREF control. Remarks None. Peripheral Libraries Help Device Control Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 519 Files Files Name Description plib_devcon.h Defines the Device Control Peripheral Library Interface. help_plib_devcon.h This is file help_plib_devcon.h. Description This section lists the source and header files used by the library. plib_devcon.h Defines the Device Control Peripheral Library Interface. Enumerations Name Description DEVCON_ALT_CLOCK_TARGET Selects Input Capture or Output Compare modules. DEVCON_DEBUG_PERIPHERAL Sets modules to ignore debugger's freeze command. DEVCON_ECC_CONFIG Selects how ECC is applied to Flash memory. DEVCON_MPLL_OUTPUT_DIVIDER Specifies the MPLL Output divider bits. DEVCON_MPLL_VREF_CONTROL VREF control. DEVCON_REGISTER_SET Selects module registers for write lock or unlock. DEVCON_USB_SLEEP_MODE Selects whether the USB clock operates in Sleep mode. Functions Name Description PLIB_DEVCON_2WireJTAGDisableTDO Disables 2-Wire JTAG protocol use of TDO. PLIB_DEVCON_2WireJTAGEnableTDO Enables 2-Wire JTAG protocol to use TDO. PLIB_DEVCON_AlternateClockDisable Disables the alternate clock source for Input Capture or Output Compare modules, The primary clock source will be used instead. PLIB_DEVCON_AlternateClockEnable Selects the alternate clock source for Input Capture or Output Compare modules. PLIB_DEVCON_AnalogIOChargePumpDisable Disables the I/O Analog Charge Pump on the device. PLIB_DEVCON_AnalogIOChargePumpEnable Enables the I/O Analog Charge Pump on the device. PLIB_DEVCON_BootExtSelect Routes SPI0 pins to the PIC32WK pads. PLIB_DEVCON_BootIPFSelect Routes SPI0 pins to In-Package Flash. PLIB_DEVCON_DeviceIdGet Gets the device identifier. PLIB_DEVCON_DeviceRegistersLock Locks device module registers, preventing modifications to the registers. PLIB_DEVCON_DeviceRegistersUnlock Unlocks device module registers, allowing modifications to the registers. PLIB_DEVCON_DeviceVersionGet Gets the device version. PLIB_DEVCON_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the DEVCON module. PLIB_DEVCON_ExistsAnalogChargePumpControl Identifies whether the I/O Analog Charge Pump feature exists on the DEVCON module. PLIB_DEVCON_ExistsBootSelection Identifies whether the BootSelection feature exists on the DEVCON module PLIB_DEVCON_ExistsDeviceRegsLockUnlock Identifies whether the DeviceRegsLockUnlock feature exists on the DEVCON module. PLIB_DEVCON_ExistsDeviceVerAndId Identifies whether the DeviceVerAndId feature exists on the DEVCON module. PLIB_DEVCON_ExistsECCModes Identifies whether the ECCModes feature exists on the DEVCON module. PLIB_DEVCON_ExistsHSUARTControl Identifies whether the HSUARTControl feature exists on the DEVCON module PLIB_DEVCON_ExistsIgnoreDebugFreeze Identifies whether the IgnoreDebugFreeze feature exists on the DEVCON module. PLIB_DEVCON_ExistsJTAGEnable Identifies whether the JTAGEnable feature exists on the DEVCON module. PLIB_DEVCON_ExistsJTAGUsesTDO Identifies whether the JTAGUsesTDO feature exists on the DEVCON module. PLIB_DEVCON_ExistsMPLL Identifies whether the MPLL feature exists on the DEVCON module. PLIB_DEVCON_ExistsOTPConfigLockUnlock Identifies whether the OTPConfigLockUnlock feature exists on the DEVCON module Peripheral Libraries Help Device Control Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 520 PLIB_DEVCON_ExistsSystemLockUnlock Identifies whether the SysLockUnlock feature exists on the DEVCON module. PLIB_DEVCON_ExistsTraceOutput Identifies whether the TraceOutput feature exists on the DEVCON module. PLIB_DEVCON_ExistsUSB_PHY_SleepModeSet Identifies whether the USB_PHY_SleepModeSet feature exists on the DEVCON module. PLIB_DEVCON_FlashErrCorrectionModeSet Sets Flash error correction operation. PLIB_DEVCON_HSUARTDisable Disables High Speed UART. PLIB_DEVCON_HSUARTEnable Enables High Speed UART. PLIB_DEVCON_IgnoreDebugFreezeDisable Module stops when commanded by debugger. PLIB_DEVCON_IgnoreDebugFreezeEnable Allows module to ignore FREEZE command from debugger and continue running. PLIB_DEVCON_JTAGPortDisable Disables the JTAG port on the device. PLIB_DEVCON_JTAGPortEnable Enables the JTAG port on the device. PLIB_DEVCON_MPLLDisable Disables the MPLL. PLIB_DEVCON_MPLLEnable Enables the MPLL. PLIB_DEVCON_MPLLInputDivSet Sets the MPLL Input Divider bits. PLIB_DEVCON_MPLLIsReady Reads MPLL status. PLIB_DEVCON_MPLLMultiplierSet Sets the MPLL Multiplier bits. PLIB_DEVCON_MPLLODiv1Set Sets the MPLL output divider 1 bits. PLIB_DEVCON_MPLLODiv2Set Sets the MPLL output divider 2 bits. PLIB_DEVCON_MPLLVrefSet Sets the VREF control setting. PLIB_DEVCON_MPLLVregDisable Disables the MPLL VREG. PLIB_DEVCON_MPLLVregEnable Enables the MPLL VREG. PLIB_DEVCON_MPLLVregIsReady Reads the MPLL VREG status. PLIB_DEVCON_OTPConfigLock Locks or unlocks the configuration registers. PLIB_DEVCON_OTPConfigUnlock unlocks the configuration registers. PLIB_DEVCON_SystemLock Executes the system lock sequence. PLIB_DEVCON_SystemUnlock Executes the system unlock sequence. PLIB_DEVCON_TraceOutputDisable Disables trace outputs and the stop trace clock. PLIB_DEVCON_TraceOutputEnable Enables trace outputs and the start trace clock. PLIB_DEVCON_USBPHYSleepModeSet Selects USB PHY clocking during Sleep mode. Description Device Control (DEVCON) Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Device Control Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Device Control module. File Name plib_devcon.h Company Microchip Technology Inc. help_plib_devcon.h Enumerations Name Description DEVCON_MODULE_ID Identifies the supported DEVCON modules. Description This is file help_plib_devcon.h. Peripheral Libraries Help Device Control Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 521 DMA Peripheral Library Help This section describes the Direct Memory Access (DMA) Peripheral Library. Introduction Direct Memory Access (DMA) is a feature (sub-system) of the microcontroller that allows certain hardware sub-systems within the microcontroller to access the system memory independently of the processor (or the CPU). Description DMA also assists in accessing peripheral memory along with the system memory (data RAM). The DMA sub-system in the PIC family of microcontrollers is optimized for high-performance, real-time, embedded applications where determinism and system latency are priorities. DMA Hardware Abstraction Model Using the Library This topic describes the basic architecture of the DMA Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_dma.h The interface to the DMA Peripheral Library is defined in the plib_dma.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the DMA Peripheral Library must include peripheral.h. Library File: The DMA Peripheral Library (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony?What is MPLAB Harmony? section for how the peripheral interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the DMA module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description The DMA Peripheral Library software is depicted using the following block diagram. DMA Software Abstraction Block Diagram Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 522 The DMA Peripheral Library takes requests from application software or the DMA device driver and controls the DMA core (the DMA hardware) as per the inputs passed to the library. The major components of the DMA Peripheral Library are: • Source/Destination/Peripheral Address Management • Source/Destination/Peripheral Data Management • DMA Operating/Addressing Mode Management • DMA Channel Management • Interrupt Control and Management The topic Library Overview explains in detail each block of the DMA Peripheral Library software architecture. Note: The interface provided is a superset of all the functionality of the available DMA module on the device. Refer to the "DMA" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine the set of functions that are supported for each DMA module on your device. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the DMA module. Library Interface Section Description Transfer/Abort (Synchronous) Handles the synchronous DMA transfer start and End. This force request is controlled fully by the software. Transfer/Abort (Asynchronous) Trigger Management Each DMA transaction can be asynchronously initiated or aborted by an interrupt. This feature handles the required configuration. Interrupt Control and Management Each DMA channel can be configured to respond to events such as address error (upper address error, lower address error, etc.), transfer count half done, transfer count done, source data completely transferred, etc. Operating/Addressing Mode Management Before initiating a DMA transaction, the addressing and operating modes of the DMA module need to be configured (per channel basis). As an example, the DMA module can be configured for one shot mode with peripheral indirect addressing mode for a DMA transaction. Channel Management Each DMA channel can be individually configured for a DMA transaction. Priorities can be assigned, a channel can be enabled or disabled, channel chaining can be used, etc. Source/Destination/Peripheral Address Management For each DMA transaction to start, the DMA core needs to know the source and destination addresses. This feature handles this type of configuration. Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 523 Source/Destination/Peripheral Data Management For each DMA transaction, the amount of data to be transferred, the source and destination size, the transaction type (byte/word), and transaction size can be configured by this feature. Special Function Modules (CRC) Certain high-end controllers support this CRC generator. This feature can be assigned to any of the available DMA channels. This feature handles the configuration of these aspects. Status (Including Channel) This feature specifies the application to access the status information of the DMA and each channel. Feature Existence Functions Lists the interface routines that determine whether or not the feature is supported by the device. How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine which modes are supported. General Configuration DMA General configuration includes enabling, disabling DMA module globally. It also involves DMA suspend control and behavior in Idle mode. Enable/Disable DMA Enabling and disabling the DMA are the basic routines that may be called during initialization and exit routines of the application. DMA Enable/Disable Example: // Enable the DMA controller PLIB_DMA_Enable ( DMA_ID_0 ); // Disable the DMA PLIB_DMA_Disable ( DMA_ID_0 ); // Check the enable status of the DMA controller. if(PLIB_DMA_IsEnabled( DMA_ID_0 )) { // application code } Transfer/Abort (Synchronous) A DMA transaction can be initiated/aborted asynchronously by configuring an interrupt for a channel. Refer to Transfer/Abort (Asynchronous) Trigger Management for details. In many instances, an application or a device driver needs to initiate a DMA transfer or abort an ongoing DMA transfer for reasons not necessarily known. To handle such cases, the DMA core supports a forceful DMA start and abort. Note: The DMA abort is not supported by all devices. Refer to the specific device data sheet to determine availability of this feature. When a DMA force start request is sent and the channel is already processing/pending to process an interrupt-based DMA transfer, the force transfer request will be ignored. In certain devices, a flag is raised to indicate a collision of DMA requests. Refer to Status (Including Channel) for details. In certain devices, an interrupt is issued to indicate that the active channel may not be able to keep up with the demands from the peripheral module being serviced. For more details refer to Interrupt Control and Management. A DMA force transfer is initiated by the PLIB_DMA_StartTransferSet function. A DMA force abort is initiated by the PLIB_DMA_AbortTransferSet function. DMA Transfer/Abort (Synchronous) Configuration A DMA transfer can be initiated or aborted forcefully by the software. Example: // Initiate a forced transfer on channel-3 PLIB_DMA_StartTransferSet ( DMA_ID_0, DMA_CHANNEL_3 ); // Abort a transfer on channel-3 PLIB_DMA_AbortTransferSet ( DMA_ID_0, DMA_CHANNEL_3 ); Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 524 Transfer/Abort (Asynchronous) Trigger Management DMA Start IRQ Each channel can be configured to initiate a DMA transaction based on the interrupt from a source. This can be enabled/disable per channel basis. To initiate a DMA transfer upon an interrupt trigger, the IRQ number needs to be configured as the start IRQ for this channel. Which source can act as the start IRQ is device-dependent. In certain devices, any of the available IRQs can be configured as the starting IRQ, while in other devices, there is restriction on which interrupt source can act as the start IRQ. Refer to the specific device data sheet to determine feature availability. The starting IRQ is enabled by the PLIB_DMA_ChannelXTriggerEnable function. A DMA channel can be configured to start a DMA transfer based on the event on an IRQ using the PLIB_DMA_ChannelXStartIRQSet function. DMA Abort IRQ Each channel can be configured to abort a DMA transaction based on the interrupt from a source. This can be enabled/disabled per channel basis. To abort a DMA transfer upon an interrupt trigger, the IRQ number needs to be configured as the abort IRQ for this channel. The abort IRQ is enabled by the PLIB_DMA_ChannelXTriggerEnable function. A DMA channel can be configured to abort a DMA transfer based on the event on an IRQ using the ChannelXAbortIRQSet function. DMA Pattern Matching Termination Pattern Match Termination mode allows the user to end a transfer if a byte of data written during a transaction matches a specific pattern. This feature is useful in applications where a variable data size is required and eases the setup of the DMA channel. The UART module is a good example of where this can be effectively used. For details about the pattern data configuration refer to Channel Management. DMA Pattern match mode is enabled using the PLIB_DMA_ChannelXTriggerEnable function. It can also be disabled using the PLIB_DMA_ChannelXTriggerDisable function. DMA Transfer/Abort (Asynchronous) Configuration A DMA transfer can also be triggered/aborted asynchronously by using an interrupt event. The interrupt event required to initiate/abort a DMA transfer for a channel needs to be set. Prior to this, the start IRQ and abort IRQ both need to be enabled. Example: // Enable the start IRQ. An interrupt event can trigger a DMA transfer. PLIB_DMA_ChannelXTriggerEnable ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_TRIGGER_TRANSFER_START ); // Enable the abort IRQ. An interrupt event can abort a DMA transfer on channel-3 PLIB_DMA_ChannelXTriggerEnable ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_TRIGGER_TRANSFER_ABORT ); // Set the start IRQ to UART-2 RX Interrupt PLIB_DMA_ChannelXStartIRQSet ( DMA_ID_0, DMA_CHANNEL_3, DMA_TRIGGER_USART_2_RECEIVE ); // Set the abort IRQ to UART-2 error Interrupt PLIB_DMA_ChannelXAbortIRQSet ( DMA_ID_0, DMA_CHANNEL_3, DMA_TRIGGER_USART_2_ERROR ); In some devices, abort IRQ trigger is not supported. Refer to the specific device data sheet to determine availability. DMA Transfer Pattern Match Abort Configuration The DMA transfer can also be aborted on a pattern match trigger (supported on PIC32 devices). Refer to Transfer/Abort (Asynchronous) Trigger Management for more information on pattern match abort. To use this feature, it must first be enabled. The pattern data needs to be programmed for the required channel. Once this is done, when a DMA transfer is in progress on that particular channel, if the DMA controller comes across the data matching the programmed data the transfer is automatically aborted. Example: // Enable the pattern match abort for channel-3 PLIB_DMA_ChannelXTriggerEnable ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_TRIGGER_PATTERN_MATCH_ABORT ); // Set a pattern data to match PLIB_DMA_ChannelXPatternDataSet ( DMA_ID_0, DMA_CHANNEL_3, 0xEE ); Interrupt Control and Management The DMA module has the ability to generate interrupts reflecting the events that occur during the channel's data transfer. The following are all of the possible interrupts generated during DMA operation. This topic provides information for configuring these interrupts. Error Interrupts This type of event is signalled when an address error has occurred during the channel transfer operation. An address error also can occur if a DMA operation accesses an address beyond configured address limits (low and high). Abort Interrupts This type of event is signalled when a DMA transfer is aborted because of a system event matching the abort IRQ configured for the current channel. Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 525 DMA Completion Interrupts (Block Completion Interrupts) This event occurs when a channel transfers a block of configured data. Call Complete Interrupts This event occurs when a channel completes a cell sized data transfer. DMA Midpoint Interrupts This event occurs when the channel is at the midpoint of completing the data transfer. Overrun Interrupts When a DMA channel receives a trigger (software or hardware) while it is servicing another request, an overrun condition occurs. This indicates that the channel is being requested before its current transaction is finished. An overrun condition will not result in termination of the current transaction. Source Address Pointer Activity Interrupts This event occurs when the channel source pointer reached the end of the source or when it reaches the midpoint of the source depending on the way this interrupt is configured. Destination Address Pointer Activity Interrupts This event occurs when the channel destination pointer reached the end of the destination or when it reaches the midpoint of the destination depending on the way this interrupt is configured. This feature helps in configuring the previously listed interrupts. Depending on the device selected, all or some of the interrupts can be individually enabled and disabled. In addition, this feature obtains the status of the interrupts previously mentioned. All of the interrupts belonging to the DMA channel map to the corresponding channel interrupt vector. In general, each channel of the DMA has a dedicated vectored interrupt. Therefore, the ISR for each channel should internally check for the status of the previously mentioned interrupts to respond to the corresponding events. DMA Interrupt Control and Management Each DMA channel has a vectored interrupt. However, each DMA channel internally generates various interrupts, which will invoke the same channel interrupt based on various events. This feature helps to enable/disable them and is also used to obtain the interrupt status. Example: // Enable the channel-3 source done interrupt PLIB_DMA_ChannelXINTSourceEnable ( DMA_ID_0, DMA_CHANNEL_3, DMA_INT_SOURCE_DONE ); // Get the status of address error on channel-3 if(PLIB_DMA_ChannelXINTSourceFlagGet ( DMA_ID_0, DMA_CHANNEL_3, DMA_INT_ADDRESS_ERROR )) { // application code for error handling } // Disable the channel abort interrupt PLIB_DMA_ChannelXINTSourceDisable (DMA_ID_0, DMA_CHANNEL_3, DMA_INT_TRANSFER_ABORT); Operating/Addressing Mode Management DMA Operating Modes The various operating/transfer modes supported are: • One-Shot mode • Repeated One-Shot mode • Continuous mode • Repeated Continuous mode • Ping-Pong mode • Null Data Write mode One-Shot Mode In One-Shot mode, a single transfer is performed for each trigger event. The trigger event can be synchronous (refer to Transfer/Abort (Synchronous) or asynchronous (refer to Transfer/Abort (Asynchronous) Trigger Management). When a single one-shot transfer occurs and the DMA count is decremented to zero, this disables the channel and requires the channel to be re-enabled to perform the next transaction. Repeated One-Shot Mode In Repeated One-Shot mode, single transfers occurs repeatedly so long as triggers are being provided. When the DMA count reaches zero, the Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 526 channel is not disabled as in One-Shot mode, but the count is reloaded and transfers begin again. Continuous Mode In Continuous mode, a single trigger starts a sequence of back-to-back transfers. These continue with each transfer decrementing the DMA count until it reaches zero. At this point, and like one-shot mode, the channel is disabled. Repeated Continuous Mode This mode can be seen as a combination of Continuous and Repeated One-Shot modes. Data transfers keep occurring so as long as triggers are provided and multiple transfers can occur with each trigger. When the DMA count reaches zero, the address and data registers are reloaded and the process is repeated. Ping-Pong Mode Certain devices support Ping-Pong mode, which allows the CPU to process one buffer while a second buffer operates with the DMA channel. The net result is that the CPU has the entire DMA block transfer time to process the buffer that is currently not being used by the DMA channel. The following figure demonstrates the data flow for four DMA transactions using Ping-Pong mode. Ping-Pong Mode When the DMA is filling buffer-B, the CPU can process buffer-A and vice-versa. Ping-Pong mode can be combined with One-Shot and Continuous modes (previously discussed) to create other combinations. Null Data Write Mode A DMA transfer operates only in one direction from the source address to the destination address. However, some communication protocols require symmetrical buffer accesses, meaning that for every read operation performed on a buffer, there must be an accompanying write operation. The Null Write mode is designed to satisfy this requirement. This mode works by transferring data from the source to the destination like any other DMA operation. Once this is done, the transferred data still with the DMA buffer is written back to the source. DMA Addressing Modes The addressing modes can be broadly classified into the following categories: • Register Indirect with Post Increment Addressing mode • Register Indirect without Post Increment Addressing mode • Source/destination increment based on size • Source/destination decrement based on size • Peripheral Indirect Addressing mode Register Indirect With Post Increment Addressing Mode In this mode, the source data address is incremented by one location after each DMA transaction. The starting address is provided by a start address offset register. Register Indirect Without Post Increment Addressing Mode In this mode, the source data address is not updated after each DMA transaction. Therefore, the next DMA transfer is initiated from the same RAM address. The starting address is provided by a start address offset register. Register Indirect Addressing With and Without Post-increment Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 527 Source/Destination Increment Based on Size After each DMA transaction, the source/destination (a separate configuration exist for each) address increments by the size of data (word/byte) configured. Source/Destination Decrement Based on Size After each DMA transaction, the source/destination (a separate configuration exist for each) address decrements by the size of data (word/byte) configured. Peripheral Indirect Addressing Mode Peripheral Indirect Addressing (PIA) is a special auto-incrementing mode for the transfer of data to and from a multi-level peripheral buffer. This mode is only available for specific peripherals designed with its use in mind. Refer to the specific device data sheet to determine availability of this mode. Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 528 PIA-capable peripherals - When selected, the PIA-enabled peripheral generates a short Indirect Address (IA) (size defined by the peripheral) to the DMA channel. The IA is logically ORed with either the contents of the source address or the destination address to define a specific address for the peripheral inside the DMA address space. DMA Operating/Transfer Modes: Refer to Operating/Addressing Mode Management for descriptions of the available operating modes. The following code demonstrates usage of Continuous mode. Example: // Enable the DMA PLIB_DMA_Enable ( DMA_ID_0 ); // disable the selected channel-3 PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_3 ); // program the source and destination addresses // Set the source starting address to 0x1000 PLIB_DMA_ChannelXSourceStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x1000 ); // Set the destination starting address to 0x2000 PLIB_DMA_ChannelXDestinationStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x2000 ); // Set the transfer count to 100. PLIB_DMA_ChannelXTransferCountSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); // set the data transfer mode to one-shot PLIB_DMA_ChannelXOperatingTransferModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_MODE_CONTINUOUS ); // select the source addressing mode PLIB_DMA_ChannelXSourceAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE ); // select the destination addressing mode PLIB_DMA_ChannelXDestinationAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_ADDRESSING_DESTINATION_INCREMENT_BASED_ON_SIZE ); // Enable the channel PLIB_DMA_ChannelXEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // Initiate the transfer PLIB_DMA_StartTransferSet ( DMA_ID_0, DMA_CHANNEL_3 ); DMA Addressing Modes: DMA addressing modes can be selected by using following code example. DMA Addressing mode Example: // set the source address to increment upon each transfer PLIB_DMA_ChannelXSourceAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE ); // Set the destination address to decrement upon each transfer PLIB_DMA_ChannelXDestinationAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_ADDRESSING_DESTINATION_DECREMENT_BASED_ON_SIZE ); Channel Management Each Channel in the DMA module is can be independently configured for a specific transaction with different properties. The following aspects of the channel can be configured using this feature. DMA Channel Enable/Disable Each channel can be enabled or disabled to control the transactions on the channel. A DMA transfer can only occur when the channel is enabled. A DMA channel can be enabled using the PLIB_DMA_ChannelXEnable function. When a channel is disabled by calling the PLIB_DMA_ChannelXDisable function, no data transfers can occur on the channel. DMA Channel Priority The DMA module has a natural priority associated with each of the channels. Channel 0 has the highest priority. Each DMA channel can be assigned priority. This priority scheme changes depending on the device selected. There are three ways in which priorities are assigned in PIC microcontrollers. In the first method, two bits are allocated for each channel for priority. Therefore, priorities 0 to 3 can be assigned to channels. The second is called round-robin. In this method, the module starts by giving Channel 0 preference in any data transfer conflicts. For each successive transfer conflict, the next higher channel receives preference, continuing as a cycle through all the channels. The third method is called fixed scheme, which always gives priority to the lowest requesting channel number. The channel priority can be set using the PLIB_DMA_ChannelPrioritySelect function or the PLIB_DMA_ChannelXPrioritySelect function depending on the device selected. DMA Channel Chaining Channel chaining is an enhancement to the DMA channel operation. A channel (slave channel) can be chained to an adjacent channel (master channel). The slave channel will be enabled when a block transfer of the master channel completes. At this point, any event on the slave channel Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 529 will initiate a DMA transfer. If the channel has an event pending, a DMA transfer will begin immediately. The channel chaining can be enabled or disabled using the PLIB_DMA_ChannelXChainEnable function and the PLIB_DMA_ChannelXChainDisable function, respectively. The channel chaining higher/lower channel number can be configured using the PLIB_DMA_ChannelXChainToHigher function and the PLIB_DMA_ChannelXChainToLower function. DMA Channel Transfer Direction Each DMA transfer will have a direction. It can be memory to peripheral, peripheral to memory, or memory to memory. This can be set using the PLIB_DMA_ChannelXTransferDirectionSelect function. DMA Channel Pattern Data On supported devices, a DMA transfer can be aborted by a pattern match (refer to Transfer/Abort (Asynchronous) Trigger Management). The pattern data is per channel basis. It can be set using the PLIB_DMA_ChannelXPatternDataSet function. Channel Auto Enable This feature can be used to keep the channel active even if a block transfer or pattern match occurs. This mode is useful for applications that do repeated pattern matching. To enable this feature use the PLIB_DMA_ChannelXAutoEnable function. To disable this feature use the PLIB_DMA_ChannelXAutoDisable function. DMA Channel Configuration The following example configures DMA Channel 3 by setting its priority to two, enabling the auto-enable feature (refer to Channel Management section), enabling the channel chain feature and chaining Channel 3 and Channel 2, and finally enabling Channel 3. Example: // Disable the channel-3 PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_3 ); // set the channel priority to 2 PLIB_DMA_ChannelXPrioritySelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_PRIORITY_2 ); // Configure the channel auto enable feature PLIB_DMA_ChannelXAutoEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // Enable the channel chain feature PLIB_DMA_ChannelXChainEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // chain channel 3 to channel 2 PLIB_DMA_ChannelXChainToLower ( DMA_ID_0, DMA_CHANNEL_3 ); // Enable channel-3 PLIB_DMA_ChannelXEnable ( DMA_ID_0, DMA_CHANNEL_3 ); In some devices it is required to select the DMA transfer direction before initiating DMA transfer. This can be done using the following code. Example: // Disable channel-3 PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_3 ); // Set the data transfer direction from memory to peripheral PLIB_DMA_ChannelXTransferDirectionSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_READ_FROM_MEMORY_WRITE_TO_PERIPHERAL ); // we can also check the current channels transfer direction // check the data transfer direction if ( DMA_READ_FROM_PERIPHERAL_WRITE_TO_MEMORY == PLIB_DMA_ChannelXTransferDirectionGet ( DMA_ID_0, DMA_CHANNEL_3 ) ) { // application code } Source/Destination/Peripheral Address Management This topic describes configuring the source/destination/peripheral addresses involved in the DMA transfer. Source/Destination Start Address Before initiating a DMA transfer, the channel should be programmed with the source and the destination addresses. In supported devices, this can be done using the PLIB_DMA_ChannelXSourceStartAddressSet Function and the PLIB_DMA_ChannelXDestinationStartAddressSet Function, respectively. At any point, the programmed addresses can be read using the PLIB_DMA_ChannelXSourceStartAddressGet Function and the PLIB_DMA_ChannelXDestinationStartAddressGet Function. Source/Destination Start Address Offset In some devices, a dedicated region of RAM is allocated for DMA transfers typically called DMA RAM. For any DMA transfer, the source or destination address needs to be defined as an offset from the starting of the DMA RAM for such devices. Use the Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 530 PLIB_DMA_ChannelXStartAddressOffsetSet Function to set the offset addresses of buffers A and B. Buffers A and B are used in Ping-Pong mode. To learn more, refer to Operating/Addressing Mode Management. Peripheral Address When DMA is used for a peripheral to memory or a memory to peripheral transfer, the peripheral address within a register must be set. This register needs to be programmed with the peripheral location where data transfers takes place. For example this can be the I2C buffer Special Function Register (SFR) location or the UART Receive register, etc. To set the peripheral address use the PLIB_DMA_ChannelXPeripheralAddressSet Function. DMA Source/Destination/Peripheral Address Control The first step in initiating a DMA transfer is to set the source and destination addresses. The following example sets the source address and the destination address for Channel 3. Example: // Set the source starting address to 0x1000 PLIB_DMA_ChannelXSourceStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x1000 ); // Set the destination starting address to 0x2000 PLIB_DMA_ChannelXDestinationStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x2000 ); On certain devices, the source starting address needs to be given as an offset from the start of the DMA RAM address (in such devices, only memory to peripheral transfers and vice-versa are possible). In such devices, the source start address is set using the PLIB_DMA_ChannelXStartAddressOffsetSet function, as shown in the following code. Example: // Set the offset-A register to 0x1000 PLIB_DMA_ChannelXStartAddressOffsetSet ( DMA_ID_0, DMA_CHANNEL_3, 0x1000, DMA_ADDRESS_OFFSET_PRIMARY); // If ping-pong mode is enabled we will make use of buffer-B, and in that case // we need to set an address for that also // Set the offset-B to 0x2000 PLIB_DMA_ChannelXStartAddressOffsetSet ( DMA_ID_0, DMA_CHANNEL_3, 0x2000, DMA_ADDRESS_OFFSET_SECONDARY); The following example sets the peripheral address when the DMA needs to be initiated between memory and peripheral. DMA Peripheral Address Set Example: // Set the peripheral address to ADC1 buffer for channel-3 transfers. PLIB_DMA_ChannelXPeripheralAddressSet ( DMA_ID_0, DMA_CHANNEL_3, (volatile uint16_t)(&ADC1BUF0)); There are also equivalent functions available within this library that read the source/destination/peripheral address set. Source/Destination/Peripheral Data Management This topic describes the data configuration. Source/Destination Transfer Size Configuration In supported devices, each channel can be programmed to read a particular sized data from a source, and write in a particular size to a destination. Both the source and destination sizes are configurable. Use the PLIB_DMA_ChannelXSourceSizeSet Function and the PLIB_DMA_ChannelXDestinationSizeSet Function for read size and write size configuration, respectively. For example, the source size can be 200 bytes and the destination size can be 100 bytes. However, it is logical to have both set to the same value. In some devices, the amount of data that needs to be transferred is independent of the source and destination, and is called transfer count. In such devices use the PLIB_DMA_ChannelXTransferCountSet Function to set the total amount of data (block transfer data). Cell Size Configuration In supported devices, when DMA transfer is initiated, the amount of data configured for a cell transfer will be delivered to the destination per trigger. This can be configured using the PLIB_DMA_ChannelXCellSizeSet Function. Channel Data Size The DMA controller can handle both byte and word (16-bit) transactions. Each DMA channel is individually configurable for the data size using the PLIB_DMA_ChannelXDataSizeSelect Function. Source/Destination Pointer Read In supported devices, the application can read the byte in source/destination to which the DMA core is currently pointing. This can be done using the PLIB_DMA_ChannelXSourcePointerGet Function and the PLIB_DMA_ChannelXDestinationPointerGet Function for source and destination, respectively. DMA Source/Destination/Peripheral Data Control After setting the source/destination address the amount of data that needs to be transferred is set in a DMA operation. However, prior to that the data transaction type (byte/word) needs to be configured on certain devices. Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 531 Example: // Set channel-3 transactions as byte transactions PLIB_DMA_ChannelXDataSizeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_DATA_8 ); // Set channel-3 transactions as 16-bit transactions PLIB_DMA_ChannelXDataSizeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_DATA_16 ); // Get the current data size configured if( DMA_CHANNEL_BYTE == PLIB_DMA_ChannelXDataSizeGet ( DMA_ID_0, DMA_CHANNEL_3 )) { // application code } Example: // Set the transfer count to 100. PLIB_DMA_ChannelXTransferCountSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); Some high-end microcontrollers (especially PIC32 devices) use the method of cell transfer and block transfer. A cell transfer is the amount of data a DMA channel transfers per an event. In such microcontrollers the application can configure the sizes of the source and destination (per channel basis). A block transfer is defined as the number of bytes transferred when a channel is enabled. A block transfer is comprised of several cell transfers. For example, if the source and destination size is 100 and the cell size is 10, it will take 10 cell transfers to complete the block transfer, which is 100 bytes (larger of source or destination sizes). DMA cell transfer configuration Example: // Set the source size to be 100 PLIB_DMA_ChannelXSourceSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); // Set the destination size to be 100 PLIB_DMA_ChannelXDestinationSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); // Set the cell size to be 10 PLIB_DMA_ChannelXCellSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 10 ); Special Function Modules (CRC) Selected high-end devices support a special feature called the CRC generator. Depending on the device, the is a highly configurable, 16-bit or 32-bit CRC generator. The CRC can be assigned to any available DMA channel using PLIB_DMA_CRCChannelSelect Function. The CRC is enabled using the PLIB_DMA_CRCEnable Function. Optionally, the data from the source can be subjected to byte reordering using the PLIB_DMA_CRCByteOrderSelect Function. The data is then optionally passed to the Linear Shift Feedback Register (LFSR) CRC or the IP header checksum blocks using the PLIB_DMA_CRCTypeSet Function. The CRC feature is attached to a channel in one of two possible modes, Background or Append. Background Mode The CRC is calculated in the background, with normal DMA behavior maintained. This can be selected by disabling the Append mode. Append Mode Data read from the source is not written to the destination, but the CRC data is accumulated in the CRC data register. The accumulated CRC is written to the location specified by the destination address when a block transfer completes. This mode is enabled by the PLIB_DMA_CRCAppendModeEnable Function. The following code shows DMA CRC calculation in Append mode. Example: // CRC of the Flash block uint32_t blockCRC; bool error = false; // disable the channel 0 interrupts using the Interrupts Peripheral Library // Enable the DMA controller PLIB_DMA_Enable ( DMA_ID_0 ); // disable the selected channel-3 PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_3 ); // set the channel priority to 2 PLIB_DMA_ChannelXPrioritySelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_PRIORITY_2 ); // Configure the channel auto enable feature PLIB_DMA_ChannelXAutoEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // Disable the channel chain feature PLIB_DMA_ChannelXChainDisable ( DMA_ID_0, DMA_CHANNEL_3 ); // Disable the start IRQ. PLIB_DMA_ChannelXTriggerDisable ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_TRIGGER_TRANSFER_START ); // Seed the CRC generator PLIB_DMA_CRCDataWrite ( DMA_ID_0, 0xFFFF ); // use the standard CCITT CRC 16 polynomial : X^16+X^12+X^5+1 PLIB_DMA_CRCXOREnableSet ( DMA_ID_0, 0x1021 ); Peripheral Libraries Help DMA Peripheral Library Help Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 532 // set polynomial length to 16 PLIB_DMA_CRCPolynomialLengthSet (DMA_ID_0, 16); // Enable append mode PLIB_DMA_CRCAppendModeEnable ( DMA_ID_0 ); // Attach CRC to DMA channel-3 PLIB_DMA_CRCChannelSelect (DMA_ID_0, DMA_CHANNEL_3); // Enable the CRC PLIB_DMA_CRCEnable ( DMA_ID_0 ); // Set the source starting address to 0x1000 PLIB_DMA_ChannelXSourceStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x1000 ); // Set the destination starting address to 0x2000 PLIB_DMA_ChannelXDestinationStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x2000 ); // set source and destination size to 100 PLIB_DMA_ChannelXSourceSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); PLIB_DMA_ChannelXDestinationSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); // Set cell size to 100 PLIB_DMA_ChannelXCellSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); //Enable channel-3 PLIB_DMA_ChannelXEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // Force initiate a transfer PLIB_DMA_StartTransferSet ( DMA_ID_0, DMA_CHANNEL_3 ); Status (including Channel) This module gives application access to various DMA and channel status information. Configuring the Library The library is configured for the supported DMA module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Configuration Functions Name Description PLIB_DMA_BusyActiveReset Resets the BUSY bit of the DMA controller. PLIB_DMA_BusyActiveSet Sets the BUSY bit of the DMA controller. PLIB_DMA_Disable DMA module is disabled. PLIB_DMA_Enable DMA module is enabled. PLIB_DMA_StopInIdleDisable DMA transfers continue during Idle mode. PLIB_DMA_StopInIdleEnable DMA transfers are halted during Idle mode. PLIB_DMA_SuspendDisable DMA suspend is disabled and the DMA module operates normally. PLIB_DMA_SuspendEnable DMA transfers are suspended to allow uninterrupted access by the CPU to the data bus. b) Transfer/Abort (Synchronous) Functions Name Description PLIB_DMA_AbortTransferSet Aborts transfer on the specified channel. PLIB_DMA_StartTransferSet Initiates transfer on the specified channel. c) Transfer/Abort (Asynchronous) Trigger Management Functions Name Description PLIB_DMA_ChannelXAbortIRQSet Sets the IRQ to abort the DMA transfer on the specified channel. PLIB_DMA_ChannelXStartIRQSet Sets the IRQ to initiate the DMA transfer on the specified channel. PLIB_DMA_ChannelXTriggerDisable Disables the DMA transfer abort via a matching interrupt (specified by the IRQ). PLIB_DMA_ChannelXTriggerEnable Enables the specified DMA channel trigger. PLIB_DMA_ChannelXTriggerIsEnabled Returns the enable status of the specified DMA transfer/abort trigger. PLIB_DMA_ChannelXTriggerSourceNumberGet Gets the source number for the DMA channel interrupts. d) Interrupt Control and Management Functions Name Description PLIB_DMA_ChannelXINTSourceDisable Disables the specified interrupt source for the specified channel. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 533 PLIB_DMA_ChannelXINTSourceEnable Enables the specified interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagClear Clears the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagGet Returns the status of the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagSet Sets the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceIsEnabled Returns the enable status of the specified interrupt source for the specified channel. e) Operating/Addressing Mode Configuration Functions Name Description PLIB_DMA_ChannelXAddressModeGet Gets the channel address mode. PLIB_DMA_ChannelXAddressModeSelect Sets the channel address mode. PLIB_DMA_ChannelXDestinationAddressModeGet Gets the source address mode of the specified channel. PLIB_DMA_ChannelXDestinationAddressModeSelect Sets the source address mode of the specified channel. PLIB_DMA_ChannelXNullWriteModeDisable Disables the Null Write mode. PLIB_DMA_ChannelXNullWriteModeEnable Enables the Null Write mode. PLIB_DMA_ChannelXOperatingTransferModeGet Returns the current transfer/operating mode for the specified channel. PLIB_DMA_ChannelXOperatingTransferModeSelect Selects the transfer/operating mode for the specified channel. PLIB_DMA_ChannelXReloadDisable Disables reloading of the address and count registers. PLIB_DMA_ChannelXReloadEnable Enables reloading of the address and count registers. PLIB_DMA_ChannelXSourceAddressModeGet Gets the source address mode of the specified channel. PLIB_DMA_ChannelXSourceAddressModeSelect Sets the source address mode of the specified channel. PLIB_DMA_ChannelXReloadIsEnabled Returns the address and count registers reload enable status. f) Source/Destination/Peripheral Address Control Interface Functions Name Description PLIB_DMA_ChannelXDestinationStartAddressGet Reads the destination start address configured for the specified channel. PLIB_DMA_ChannelXDestinationStartAddressSet Writes the specified destination start address into the register corresponding to the specified channel. PLIB_DMA_ChannelXPeripheralAddressGet Gets the peripheral address configured for the specified channel. PLIB_DMA_ChannelXPeripheralAddressSet Sets the peripheral address for the specified channel. PLIB_DMA_ChannelXSourceStartAddressGet Reads the source start address configured for the specified channel. PLIB_DMA_ChannelXSourceStartAddressSet Writes the specified source start address into the register corresponding to the specified channel. PLIB_DMA_ChannelXStartAddressOffsetGet Gets the primary/secondary start address (DPSRAM) offset. PLIB_DMA_ChannelXStartAddressOffsetSet Sets the primary/secondary start address (DPSRAM) offset to the value specified depending on the offset type specified for the specified channel. g) Source/Destination/Peripheral Data Management Functions Name Description PLIB_DMA_ChannelXCellProgressPointerGet Returns the number of bytes transferred since the last event. PLIB_DMA_ChannelXCellSizeGet Reads the cell size (in bytes) configured for the specified channel. PLIB_DMA_ChannelXCellSizeSet Writes the specified cell size into the register corresponding to the specified channel. PLIB_DMA_ChannelXDataSizeGet Returns the current data size for the specified channel. PLIB_DMA_ChannelXDataSizeSelect Selects the data size for the specified channel. PLIB_DMA_ChannelXDestinationPointerGet Reads the current byte of the destination being pointed to for the specified channel. PLIB_DMA_ChannelXDestinationSizeGet Reads the destination size configured for the specified channel. PLIB_DMA_ChannelXDestinationSizeSet Writes the specified destination size into the register corresponding to the specified channel. PLIB_DMA_ChannelXPatternDataGet Returns the pattern matching (for DMA abort) data programmed for the specified channel. PLIB_DMA_ChannelXPatternDataSet Writes the specified pattern matching data (for DMA abort) into the register corresponding to the specified channel. PLIB_DMA_ChannelXSourcePointerGet Reads the current byte of the source being pointed to for the specified channel. PLIB_DMA_ChannelXSourceSizeGet Reads the source size configured for the specified channel. PLIB_DMA_ChannelXSourceSizeSet Writes the specified source size into the register corresponding to the specified channel. PLIB_DMA_ChannelXTransferCountGet Gets the DMA data transfer count that is programmed for the specified channel. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 534 PLIB_DMA_ChannelXTransferCountSet Sets the DMA data transfer count for the specified channel. h) Channel Configuration Functions Name Description PLIB_DMA_ChannelPrioritySelect Sets the priority scheme of the DMA channels. PLIB_DMA_ChannelPriorityGet Gets the priority scheme of the DMA channels. PLIB_DMA_ChannelXAutoDisable Channel is disabled after a block transfer is complete. PLIB_DMA_ChannelXAutoEnable Channel is continuously enabled. PLIB_DMA_ChannelXBusyActiveSet Sets the Busy bit to active. PLIB_DMA_ChannelXBusyInActiveSet Sets the Busy bit to inactive. PLIB_DMA_ChannelXChainDisable Disables the channel chaining for the specified DMA channel. PLIB_DMA_ChannelXChainEnable Channel chain feature is enabled. PLIB_DMA_ChannelXChainToHigher Chains the specified channel to a channel higher in natural priority. PLIB_DMA_ChannelXChainToLower Chains the specified channel to a channel lower in natural priority. PLIB_DMA_ChannelXDisable Disable the specified channel. PLIB_DMA_ChannelXEnable Enable the specified channel. PLIB_DMA_ChannelXPriorityGet Gets the priority of the specified channel. PLIB_DMA_ChannelXPrioritySelect Sets the priority of the specified channel. PLIB_DMA_ChannelXTransferDirectionGet Returns the data transfer direction of the specified channel. PLIB_DMA_ChannelXTransferDirectionSelect Selects the data transfer direction of the specified channel. PLIB_DMA_ChannelXDisabledDisablesEvents Channel start/abort events will be ignored even if the channel is disabled. PLIB_DMA_ChannelXDisabledEnablesEvents Channel start/abort events will be registered even if the channel is disabled. PLIB_DMA_ChannelXPatternIgnoreByteDisable Disables the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreByteEnable Enables the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled Returns the state of the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreGet Returns the pattern match ignore value. PLIB_DMA_ChannelXPatternIgnoreSet Sets the pattern match ignore value. PLIB_DMA_ChannelXPatternLengthGet Returns the pattern match length. PLIB_DMA_ChannelXPatternLengthSet Sets the pattern match length. i) CRC Module Interface Functions Name Description PLIB_DMA_CRCAppendModeDisable Disables the CRC append mode. PLIB_DMA_CRCAppendModeEnable Enables the CRC append mode. PLIB_DMA_CRCAppendModeIsEnabled Gets the enable status of the CRC append mode. PLIB_DMA_CRCBitOrderSelect Selects the bit order for checksum calculation. PLIB_DMA_CRCByteOrderGet Gets the current byte order selected by the DMA module CRC feature. PLIB_DMA_CRCByteOrderSelect Selects the byte order. PLIB_DMA_CRCChannelGet Returns the current DMA channel to which the CRC is assigned. PLIB_DMA_CRCChannelSelect Assigns the CRC to the specified DMA channel. PLIB_DMA_CRCDataRead Reads the contents of the DMA CRC data register. PLIB_DMA_CRCDataWrite Writes the contents of the DMA CRC data register with the specified data. PLIB_DMA_CRCDisable Disables the DMA module CRC feature. PLIB_DMA_CRCEnable Enables the DMA module CRC feature. PLIB_DMA_CRCPolynomialLengthGet Gets the current polynomial length. PLIB_DMA_CRCPolynomialLengthSet Selects the polynomial length. PLIB_DMA_CRCTypeGet Gets the current DMA module CRC feature type. PLIB_DMA_CRCTypeSet Selects the DMA module CRC feature type. PLIB_DMA_CRCWriteByteOrderAlter The source data is written to the destination reordered as defined by the BYTO<1:0> bits. PLIB_DMA_CRCWriteByteOrderMaintain The source data is written to the destination unaltered. PLIB_DMA_CRCXOREnableGet Reads the CRC XOR register. PLIB_DMA_CRCXOREnableSet Writes to the CRC XOR enable register as per the specified enable mask. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 535 j) Global Status Functions Name Description PLIB_DMA_CRCIsEnabled Gets the enable status of the CRC feature. PLIB_DMA_IsBusy Gets the BUSY bit of the DMA controller. PLIB_DMA_IsEnabled Returns the DMA module enable status. PLIB_DMA_LastBusAccessIsRead Returns true if the last DMA bus access was a read. PLIB_DMA_LastBusAccessIsWrite Returns true if the last DMA bus access was a write. PLIB_DMA_RecentAddressAccessed Returns the address of the most recent DMA access. PLIB_DMA_SuspendIsEnabled Returns the DMA suspend status. k) Channel Status Functions Name Description PLIB_DMA_ChannelXAutoIsEnabled Returns the channel automatic enable status. PLIB_DMA_ChannelXBufferedDataIsWritten Returns the buffered data write status for the specified channel. PLIB_DMA_ChannelXBusyIsBusy Returns the busy status of the specified channel. PLIB_DMA_ChannelXChainIsEnabled Returns the chain status of the specified channel. PLIB_DMA_ChannelXCollisionStatus Returns the status of the specified collision type for the specified channel. PLIB_DMA_ChannelXEventIsDetected Returns the event status on the specified channel. PLIB_DMA_ChannelXIsEnabled Return the enable status of the specified channel. PLIB_DMA_ChannelXNullWriteModeIsEnabled Returns the enable status of the Null Write mode for the specified channel. PLIB_DMA_ChannelXPingPongModeGet Returns the Ping-Pong mode status for the specified channel. PLIB_DMA_ChannelBitsGet Returns the DMA channel bits. l) Feature Existence Functions Name Description PLIB_DMA_ExistsAbortTransfer Identifies whether the AbortTransfer feature exists on the DMA module. PLIB_DMA_ExistsBusy Identifies whether the Busy feature exists on the DMA module. PLIB_DMA_ExistsChannelBits Identifies whether the ChannelBits feature exists on the DMA module. PLIB_DMA_ExistsChannelX Identifies whether the ChannelX feature exists on the DMA module. PLIB_DMA_ExistsChannelXAbortIRQ Identifies whether the ChannelXAbortIRQ feature exists on the DMA module. PLIB_DMA_ExistsChannelXAuto Identifies whether the ChannelXAuto feature exists on the DMA module. PLIB_DMA_ExistsChannelXBusy Identifies whether the ChannelXBusy feature exists on the DMA module. PLIB_DMA_ExistsChannelXCellProgressPointer Identifies whether the ChannelXCellProgressPointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXCellSize Identifies whether the ChannelXCellSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXChain Identifies whether the ChannelXChain feature exists on the DMA module. PLIB_DMA_ExistsChannelXChainEnbl Identifies whether the ChannelXChainEnbl feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationPointer Identifies whether the ChannelXDestinationPointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationSize Identifies whether the ChannelXDestinationSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationStartAddress Identifies whether the ChannelXDestinationStartAddress feature exists on the DMA module. PLIB_DMA_ExistsChannelXDisabled Identifies whether the ChannelXDisabled feature exists on the DMA module. PLIB_DMA_ExistsChannelXEvent Identifies whether the ChannelXEvent feature exists on the DMA module. PLIB_DMA_ExistsChannelXINTSource Identifies whether the ChannelXINTSource feature exists on the DMA module. PLIB_DMA_ExistsChannelXINTSourceFlag Identifies whether the ChannelXINTSourceFlag feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternData Identifies whether the ChannelXPatternData feature exists on the DMA module PLIB_DMA_ExistsChannelXPatternIgnore Identifies whether the ChannelXPatternIgnore feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternIgnoreByte Identifies whether the ChannelXPatternIgnoreByte feature exists on the DMA module. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 536 PLIB_DMA_ExistsChannelXPatternLength Identifies whether the ChannelXPatternLength feature exists on the DMA module. PLIB_DMA_ExistsChannelXPriority Identifies whether the ChannelXPriority feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourcePointer Identifies whether the ChannelXSourcePointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourceSize Identifies whether the ChannelXSourceSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourceStartAddress Identifies whether the ChannelXSourceStartAddress feature exists on the DMA module. PLIB_DMA_ExistsChannelXStartIRQ Identifies whether the ChannelXStartIRQ feature exists on the DMA module. PLIB_DMA_ExistsChannelXTrigger Identifies whether the ChannelXTrigger feature exists on the DMA module. PLIB_DMA_ExistsCRC Identifies whether the CRC feature exists on the DMA module. PLIB_DMA_ExistsCRCAppendMode Identifies whether the CRCAppendMode feature exists on the DMA module. PLIB_DMA_ExistsCRCBitOrder Identifies whether the CRCBitOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCByteOrder Identifies whether the CRCByteOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCChannel Identifies whether the CRCChannel feature exists on the DMA module. PLIB_DMA_ExistsCRCData Identifies whether the CRCData feature exists on the DMA module. PLIB_DMA_ExistsCRCPolynomialLength Identifies whether the CRCPolynomialLength feature exists on the DMA module. PLIB_DMA_ExistsCRCType Identifies whether the CRCType feature exists on the DMA module. PLIB_DMA_ExistsCRCWriteByteOrder Identifies whether the CRCWriteByteOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCXOREnable Identifies whether the CRCXOREnable feature exists on the DMA module. PLIB_DMA_ExistsEnableControl Identifies whether the EnableControl feature exists on the DMA module. PLIB_DMA_ExistsLastBusAccess Identifies whether the LastBusAccess feature exists on the DMA module. PLIB_DMA_ExistsRecentAddress Identifies whether the RecentAddress feature exists on the DMA module. PLIB_DMA_ExistsStartTransfer Identifies whether the StartTransfer feature exists on the DMA module. PLIB_DMA_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the DMA module. PLIB_DMA_ExistsSuspend Identifies whether the Suspend feature exists on the DMA module. m) Data Types and Constants Name Description DMA_ADDRESS_OFFSET_TYPE Lists the possible DMA address offsets. DMA_CHANNEL Lists the possible DMA channels available. DMA_CHANNEL_ADDRESSING_MODE Lists the possible channel addressing modes. DMA_CHANNEL_COLLISION Lists the possible channel collision types. DMA_CHANNEL_DATA_SIZE Lists the possible data sizes for the DMA channel. DMA_CHANNEL_PRIORITY Lists the possible channel priorities. DMA_CHANNEL_TRANSFER_DIRECTION Lists the possible data transfer directions. DMA_CHANNEL_TRIGGER_TYPE Lists the possible DMA channel triggers. DMA_CRC_BIT_ORDER Lists the possible CRC calculation bit orders DMA_CRC_BYTE_ORDER Lists the possible byte orders. DMA_CRC_TYPE Lists the possible checksums. DMA_DESTINATION_ADDRESSING_MODE Lists the possible destination addressing modes. DMA_INT_TYPE Lists the possible Interrupt types for a particular channel-X DMA_MODULE_ID Possible instances of the DMA module. DMA_PATTERN_LENGTH Gives the DMA pattern length DMA_PING_PONG_MODE Lists the possible ping-pong modes. DMA_SOURCE_ADDRESSING_MODE Lists the possible source addressing modes. DMA_TRANSFER_MODE Lists the possible DMA transfer/operating modes. DMA_TRIGGER_SOURCE Lists the possible DMA trigger sources. DMA_CHANNEL_INT_SOURCE Lists the Interrupt Source number for the available DMA channels. Description This section describes the Application Programming Interface (API) functions of the DMA Peripheral Library. Refer to each section for a detailed description. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 537 a) General Configuration Functions PLIB_DMA_BusyActiveReset Function Resets the BUSY bit of the DMA controller. File plib_dma.h C void PLIB_DMA_BusyActiveReset(DMA_MODULE_ID index); Returns None. Description This function resets the BUSY bit of the DMA controller. The DMA module is disabled and is not actively transferring data. Remarks This function implements an operation of the Busy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsBusy function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_BusyActiveReset( DMA_ID_0 ); Function void PLIB_DMA_BusyActiveReset ( DMA_MODULE_ID index ) PLIB_DMA_BusyActiveSet Function Sets the BUSY bit of the DMA controller. File plib_dma.h C void PLIB_DMA_BusyActiveSet(DMA_MODULE_ID index); Returns None. Description This function sets the BUSY bit of the DMA controller. The DMA module is active. Remarks This function implements an operation of the Busy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsBusy function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_BusyActiveSet( DMA_ID_0 ); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 538 Function void PLIB_DMA_BusyActiveSet ( DMA_MODULE_ID index ) PLIB_DMA_Disable Function DMA module is disabled. File plib_dma.h C void PLIB_DMA_Disable(DMA_MODULE_ID index); Returns None. Description This function disables the DMA module. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsEnableControl function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_Disable( DMA_ID_0 ); Function void PLIB_DMA_Disable ( DMA_MODULE_ID index ) PLIB_DMA_Enable Function DMA module is enabled. File plib_dma.h C void PLIB_DMA_Enable(DMA_MODULE_ID index); Returns None. Description This function enables the DMA module. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsEnableControl function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_Enable( DMA_ID_0 ); Function void PLIB_DMA_Enable ( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 539 PLIB_DMA_StopInIdleDisable Function DMA transfers continue during Idle mode. File plib_dma.h C void PLIB_DMA_StopInIdleDisable(DMA_MODULE_ID index); Returns None. Description This function causes DMA transfers to continue during Idle mode. Remarks This function implements an operation of the StopInIdle feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsStopInIdle function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_StopInIdleDisable( DMA_ID_0 ); Function void PLIB_DMA_StopInIdleDisable ( DMA_MODULE_ID index ) PLIB_DMA_StopInIdleEnable Function DMA transfers are halted during Idle mode. File plib_dma.h C void PLIB_DMA_StopInIdleEnable(DMA_MODULE_ID index); Returns None. Description This function halts DMA transfers during Idle mode. Remarks This function implements an operation of the StopInIdle feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsStopInIdle function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_StopInIdleEnable( DMA_ID_0 ); Function void PLIB_DMA_StopInIdleEnable ( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 540 PLIB_DMA_SuspendDisable Function DMA suspend is disabled and the DMA module operates normally. File plib_dma.h C void PLIB_DMA_SuspendDisable(DMA_MODULE_ID index); Returns None. Description This function disables the DMA suspend. The DMA module continues to operate normally. Remarks This function implements an operation of the Suspend feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsSuspend function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_SuspendDisable( DMA_ID_0 ); Function void PLIB_DMA_SuspendDisable ( DMA_MODULE_ID index ) PLIB_DMA_SuspendEnable Function DMA transfers are suspended to allow uninterrupted access by the CPU to the data bus. File plib_dma.h C void PLIB_DMA_SuspendEnable(DMA_MODULE_ID index); Returns None. Description This function suspends the DMA transfers to allow uninterrupted access by the CPU to the data bus. Remarks This function implements an operation of the Suspend feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsSuspend function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_SuspendEnable( DMA_ID_0 ); Function void PLIB_DMA_SuspendEnable ( DMA_MODULE_ID index ) b) Transfer/Abort (Synchronous) Functions Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 541 PLIB_DMA_AbortTransferSet Function Aborts transfer on the specified channel. File plib_dma.h C void PLIB_DMA_AbortTransferSet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function aborts transfer on the specified channel. This is a forced abort controlled via software. Remarks This function implements an operation of the AbortTransfer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsAbortTransfer function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_AbortTransferSet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_AbortTransferSet ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_StartTransferSet Function Initiates transfer on the specified channel. File plib_dma.h C void PLIB_DMA_StartTransferSet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function initiates transfer on the specified channel. This is a forced transfer controlled via software. Remarks This function implements an operation of the StartTransfer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsStartTransfer function in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 542 Example PLIB_DMA_StartTransferSet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_StartTransferSet ( DMA_MODULE_ID index, DMA_CHANNEL channel ) c) Transfer/Abort (Asynchronous) Trigger Management Functions PLIB_DMA_ChannelXAbortIRQSet Function Sets the IRQ to abort the DMA transfer on the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXAbortIRQSet(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_TRIGGER_SOURCE IRQ); Returns None. Description This function sets the IRQ to abort the DMA transfer on the specified channel. (IRQ to start the channel transfer.) Remarks This function implements an operation of the ChannelXAbortIRQ feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXAbortIRQ function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_TRIGGER_SOURCE irq = DMA_TRIGGER_TIMER_CORE; PLIB_DMA_ChannelXAbortIRQSet ( DMA_ID_0, DMA_CHANNEL_4, irq ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL IRQnum The IRQ number of the trigger source of type DMA_TRIGGER_SOURCE Function void PLIB_DMA_ChannelXAbortIRQSet ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_TRIGGER_SOURCE IRQ ) PLIB_DMA_ChannelXStartIRQSet Function Sets the IRQ to initiate the DMA transfer on the specified channel. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 543 File plib_dma.h C void PLIB_DMA_ChannelXStartIRQSet(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_TRIGGER_SOURCE IRQnum); Returns None. Description This function sets the IRQ to initiate the DMA transfer on the specified channel. (IRQ to start the channel transfer.) Remarks This function implements an operation of the ChannelXStartIRQ feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXStartIRQ function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_TRIGGER_SOURCE irq = DMA_TRIGGER_OUTPUT_COMPARE_1; PLIB_DMA_ChannelXStartIRQSet ( DMA_ID_0, DMA_CHANNEL_4, irq ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL IRQnum The IRQ number of the trigger source of type DMA_TRIGGER_SOURCE Function void PLIB_DMA_ChannelXStartIRQSet ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_TRIGGER_SOURCE IRQnum ) PLIB_DMA_ChannelXTriggerDisable Function Disables the DMA transfer abort via a matching interrupt (specified by the IRQ). File plib_dma.h C void PLIB_DMA_ChannelXTriggerDisable(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRIGGER_TYPE trigger); Returns None. Description This function disables the DMA transfer abort via a matching interrupt (specified by the IRQ). The interrupt number IRQ is ignored and does not terminate a transfer. Remarks This function implements an operation of the ChannelXTrigger feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXTrigger function in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 544 Example PLIB_DMA_ChannelXTriggerDisable ( DMA_ID_0, DMA_CHANNEL_4, DMA_CHANNEL_TRIGGER_PATTERN_MATCH_ABORT ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL trigger Type of trigger (transfer start/abort/pattern match abort) Function void PLIB_DMA_ChannelXTriggerDisable ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRIGGER_TYPE trigger ) PLIB_DMA_ChannelXTriggerEnable Function Enables the specified DMA channel trigger. File plib_dma.h C void PLIB_DMA_ChannelXTriggerEnable(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRIGGER_TYPE trigger); Returns None. Description This function enables the specified DMA channel trigger. Remarks This function implements an operation of the ChannelXTrigger feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXTrigger function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXTriggerEnable ( DMA_ID_0, DMA_CHANNEL_4, DMA_CHANNEL_TRIGGER_TRANSFER_ABORT ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL trigger Type of trigger (transfer start/abort/pattern match abort) Function void PLIB_DMA_ChannelXTriggerEnable ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRIGGER_TYPE trigger ) PLIB_DMA_ChannelXTriggerIsEnabled Function Returns the enable status of the specified DMA transfer/abort trigger. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 545 File plib_dma.h C bool PLIB_DMA_ChannelXTriggerIsEnabled(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRIGGER_TYPE trigger); Returns • true - The specified trigger is enabled • false - The specified trigger is disabled Description This function returns the enable status of the specified DMA transfer/abort trigger. Remarks This function implements an operation of the ChannelXTrigger feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXTrigger function in your application to automatically determine whether this feature is available. Preconditions None. Example bool startTriggerstatus; startTriggerstatus = PLIB_DMA_ChannelXTriggerIsEnabled ( DMA_ID_0, DMA_CHANNEL_4, DMA_CHANNEL_TRIGGER_TRANSFER_START ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL trigger Type of trigger (transfer start/abort/pattern match abort) Function bool PLIB_DMA_ChannelXTriggerIsEnabled( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRIGGER_TYPE trigger ) PLIB_DMA_ChannelXTriggerSourceNumberGet Function Gets the source number for the DMA channel interrupts. File plib_dma.h C DMA_CHANNEL_INT_SOURCE PLIB_DMA_ChannelXTriggerSourceNumberGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function returns the interrupt source number for the specified DMA channel. Remarks This function implements an operation of the ChannelXTrigger feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXTrigger function in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 546 Example PLIB_DMA_ChannelXTriggerSourceNumberGet ( DMA_ID_0, DMA_CHANNEL_4); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXTriggerSourceNumberGet ( DMA_MODULE_ID index, DMA_CHANNEL channel) d) Interrupt Control and Management Functions PLIB_DMA_ChannelXINTSourceDisable Function Disables the specified interrupt source for the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXINTSourceDisable(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource); Returns None. Description This function disables the specified interrupt source for the specified channel. Remarks This function implements an operation of the ChannelXINTSource feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSource function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXINTSourceDisable ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Function void PLIB_DMA_ChannelXINTSourceDisable ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ) PLIB_DMA_ChannelXINTSourceEnable Function Enables the specified interrupt source for the specified channel. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 547 File plib_dma.h C void PLIB_DMA_ChannelXINTSourceEnable(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource); Returns None. Description This function enables the specified interrupt source for the specified channel. Remarks This function implements an operation of the ChannelXINTSource feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSource function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXINTSourceEnable ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Function void PLIB_DMA_ChannelXINTSourceEnable ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ) PLIB_DMA_ChannelXINTSourceFlagClear Function Clears the interrupt flag of the specified DMA interrupt source for the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXINTSourceFlagClear(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource); Returns None. Description This function clears the interrupt flag of the specified DMA interrupt source for the specified channel. Remarks This function implements an operation of the ChannelXINTSourceFlag feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSourceFlag function in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 548 Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXINTSourceFlagClear ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Function void PLIB_DMA_ChannelXINTSourceFlagClear ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ) PLIB_DMA_ChannelXINTSourceFlagGet Function Returns the status of the interrupt flag of the specified DMA interrupt source for the specified channel. File plib_dma.h C bool PLIB_DMA_ChannelXINTSourceFlagGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource); Returns • true - The interrupt flag is set • false - The interrupt flag is not set Description This function returns the status of the interrupt flag of the specified DMA interrupt source for the specified channel. Remarks This function implements an operation of the ChannelXINTSourceFlag feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSourceFlag function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; bool AddressErrorINTStatus; AddressErrorINTStatus = PLIB_DMA_ChannelXINTSourceFlagGet ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Function bool PLIB_DMA_ChannelXINTSourceFlagGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 549 PLIB_DMA_ChannelXINTSourceFlagSet Function Sets the interrupt flag of the specified DMA interrupt source for the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXINTSourceFlagSet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource); Returns None. Description This function sets the interrupt flag of the specified DMA interrupt source for the specified channel. Remarks This function implements an operation of the ChannelXINTSourceFlag feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSourceFlag function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXINTSourceFlagSet ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Function void PLIB_DMA_ChannelXINTSourceFlagSet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ) PLIB_DMA_ChannelXINTSourceIsEnabled Function Returns the enable status of the specified interrupt source for the specified channel. File plib_dma.h C bool PLIB_DMA_ChannelXINTSourceIsEnabled(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource); Returns • true - The interrupt is enabled • false - The interrupt is not enabled Description This function returns the enable status of the specified interrupt source for the specified channel. Remarks This function implements an operation of the ChannelXINTSource feature. This feature may not be available on all devices. Please refer to the Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 550 specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSource function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; bool dmaINTSourceEnableStatus; dmaINTSourceEnableStatus = PLIB_DMA_ChannelXINTSourceIsEnabled ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Function bool PLIB_DMA_ChannelXINTSourceIsEnabled ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ) e) Operating/Addressing Mode Configuration Functions PLIB_DMA_ChannelXAddressModeGet Function Gets the channel address mode. File plib_dma.h C DMA_CHANNEL_ADDRESSING_MODE PLIB_DMA_ChannelXAddressModeGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • channelAddressMode - One of the possible source addressing modes listed by DMA_CHANNEL_ADDRESSING_MODE Description This function gets the channel address mode. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example DMA_CHANNEL_ADDRESSING_MODE channelAddressMode; channelAddressMode = PLIB_DMA_ChannelXAddressModeGet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function DMA_CHANNEL_ADDRESSING_MODE PLIB_DMA_ChannelXAddressModeGet ( DMA_MODULE_ID index, Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 551 DMA_CHANNEL channel ) PLIB_DMA_ChannelXAddressModeSelect Function Sets the channel address mode. File plib_dma.h C void PLIB_DMA_ChannelXAddressModeSelect(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_ADDRESSING_MODE channelAddressMode); Returns None. Description This function sets the channel address mode. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DMA_ChannelXAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_4, DMA_ADDRESSING_REGISTER_INDIRECT_WITH_POST_INCREMENT ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL channelAddressMode One of the possible channel addressing modes listed by DMA_CHANNEL_ADDRESSING_MODE Function void PLIB_DMA_ChannelXAddressModeSelect ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_ADDRESSING_MODE channelAddressMode ) PLIB_DMA_ChannelXDestinationAddressModeGet Function Gets the source address mode of the specified channel. File plib_dma.h C DMA_DESTINATION_ADDRESSING_MODE PLIB_DMA_ChannelXDestinationAddressModeGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • destinationAddressMode - One of the possible source addressing modes listed by DMA_DESTINATION_ADDRESSING_MODE Description This function gets the source address mode of the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 552 Preconditions None. Example DMA_SOURCE_ADDRESSING_MODE destinationAddressMode; destinationAddressMode = PLIB_DMA_ChannelXDestinationAddressModeGet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function DMA_DESTINATION_ADDRESSING_MODE PLIB_DMA_ChannelXDestinationAddressModeGet ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXDestinationAddressModeSelect Function Sets the source address mode of the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXDestinationAddressModeSelect(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_DESTINATION_ADDRESSING_MODE destinationAddressMode); Returns None. Description This function Sets the source address mode of the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DMA_ChannelXDestinationAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_4, DMA_ADDRESSING_DESTINATION_INCREMENT_BASED_ON_SIZE ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL destinationAddressMode One of the possible source addressing modes listed by DMA_DESTINATION_ADDRESSING_MODE Function void PLIB_DMA_ChannelXDestinationAddressModeSelect ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_DESTINATION_ADDRESSING_MODE destinationAddressMode ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 553 PLIB_DMA_ChannelXNullWriteModeDisable Function Disables the Null Write mode. File plib_dma.h C void PLIB_DMA_ChannelXNullWriteModeDisable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function disables the Null Write mode. No dummy write is initiated. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DMA_ChannelXNullWriteModeDisable ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXNullWriteModeDisable( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXNullWriteModeEnable Function Enables the Null Write mode. File plib_dma.h C void PLIB_DMA_ChannelXNullWriteModeEnable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function enables the Null Write mode. A dummy write is initiated to the source address for every write to the destination address. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DMA_ChannelXNullWriteModeEnable ( DMA_ID_0, DMA_CHANNEL_4 ); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 554 Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXNullWriteModeEnable ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXOperatingTransferModeGet Function Returns the current transfer/operating mode for the specified channel. File plib_dma.h C DMA_TRANSFER_MODE PLIB_DMA_ChannelXOperatingTransferModeGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • channeltransferMode - One of the possible operating/transfer modes listed by DMA_TRANSFER_MODE Description This function returns the current transfer/operating mode for the specified channel. (Transfer mode and operating mode are used interchangeably.) Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example DMA_TRANSFER_MODE channeltransferMode; channeltransferMode = PLIB_DMA_ChannelXOperatingTransferModeGet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function DMA_TRANSFER_MODE PLIB_DMA_ChannelXOperatingTransferModeGet ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXOperatingTransferModeSelect Function Selects the transfer/operating mode for the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXOperatingTransferModeSelect(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_TRANSFER_MODE channeltransferMode); Returns None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 555 Description This function selects the transfer/operating mode for the specified channel. (Transfer mode and operating mode are used interchangeably.) Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example DMA_TRANSFER_MODE channeltransferMode = DMA_MODE_REPEATED_CONTINUOUS; PLIB_DMA_ChannelXOperatingTransferModeSelect ( DMA_ID_0, DMA_CHANNEL_4, channeltransferMode ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL channeltransferMode One of the possible operating/transfer modes listed by DMA_TRANSFER_MODE Function void PLIB_DMA_ChannelXOperatingTransferModeSelect ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_TRANSFER_MODE channeltransferMode ) PLIB_DMA_ChannelXReloadDisable Function Disables reloading of the address and count registers. File plib_dma.h C void PLIB_DMA_ChannelXReloadDisable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function disables reloading of the address and count registers. The source, destination address, and the DMA count registers are not reloaded to their previous values upon the start of the next operation. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DMA_ChannelXReloadDisable ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXReloadDisable ( DMA_MODULE_ID index, DMA_CHANNEL channel ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 556 PLIB_DMA_ChannelXReloadEnable Function Enables reloading of the address and count registers. File plib_dma.h C void PLIB_DMA_ChannelXReloadEnable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function enables reloading of the address and count registers. The source, destination address, and the DMA count registers are reloaded to their previous values upon the start of the next operation. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DMA_ChannelXReloadEnable ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXReloadEnable( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXSourceAddressModeGet Function Gets the source address mode of the specified channel. File plib_dma.h C DMA_SOURCE_ADDRESSING_MODE PLIB_DMA_ChannelXSourceAddressModeGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • DMA_SOURCE_ADDRESSING_MODE - One of the possible source addressing modes listed by DMA_SOURCE_ADDRESSING_MODE Description This function gets the source address mode of the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example DMA_SOURCE_ADDRESSING_MODE sourceAddressMode; sourceAddressMode = PLIB_DMA_ChannelXSourceAddressModeGet ( DMA_ID_0, DMA_CHANNEL_4 ); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 557 Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function DMA_SOURCE_ADDRESSING_MODE PLIB_DMA_ChannelXSourceAddressModeGet ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXSourceAddressModeSelect Function Sets the source address mode of the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXSourceAddressModeSelect(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_SOURCE_ADDRESSING_MODE sourceAddressMode); Returns None. Description This function sets the source address mode of the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DMA_ChannelXSourceAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_4, DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL sourceAddressMode One of the possible source addressing modes listed by DMA_SOURCE_ADDRESSING_MODE Function void PLIB_DMA_ChannelXSourceAddressModeSelect ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_SOURCE_ADDRESSING_MODE sourceAddressMode ) PLIB_DMA_ChannelXReloadIsEnabled Function Returns the address and count registers reload enable status. File plib_dma.h C bool PLIB_DMA_ChannelXReloadIsEnabled(DMA_MODULE_ID index, DMA_CHANNEL channel); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 558 Returns • true - The address and count registers reload is enabled • false - The address and count registers reload is disabled Description This function returns the address and count registers reload enable status. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example bool chAddressCountReloadStatus; chAddressCountReloadStatus = PLIB_DMA_ChannelXReloadIsEnabled ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function bool PLIB_DMA_ChannelXReloadIsEnabled ( DMA_MODULE_ID index, DMA_CHANNEL channel ) f) Source/Destination/Peripheral Address Control Interface Functions PLIB_DMA_ChannelXDestinationStartAddressGet Function Reads the destination start address configured for the specified channel. File plib_dma.h C uint32_t PLIB_DMA_ChannelXDestinationStartAddressGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Returns • uint32_t - The destination start address configured for this channel Description This function reads the destination start address configured for the specified channel. Remarks This function implements an operation of the ChannelXDestinationStartAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationStartAddress function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint32_t DestinationStartAddress; DestinationStartAddress = PLIB_DMA_ChannelXDestinationStartAddressGet ( DMA_ID_0, spiDMAChannel ); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 559 Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function uint32_t PLIB_DMA_ChannelXDestinationStartAddressGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ) PLIB_DMA_ChannelXDestinationStartAddressSet Function Writes the specified destination start address into the register corresponding to the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXDestinationStartAddressSet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint32_t destinationStartAddress); Returns None. Description This function writes the specified destination start address into the register corresponding to the specified channel. Remarks This function implements an operation of the ChannelXDestinationStartAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationStartAddress function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint32_t destinationStartAddress = 0x00FDEA00; PLIB_DMA_ChannelXDestinationStartAddressSet( DMA_ID_0, spiDMAChannel, destinationStartAddress ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL destinationStartAddress The destination start address Function void PLIB_DMA_ChannelXDestinationStartAddressSet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint32_t destinationStartAddress) PLIB_DMA_ChannelXPeripheralAddressGet Function Gets the peripheral address configured for the specified channel. File plib_dma.h C uint16_t PLIB_DMA_ChannelXPeripheralAddressGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 560 Returns • uint16_t - The peripheral address configured for the specified channel Description This function gets the peripheral address configured for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint16_t peripheraladdress; peripheraladdress = PLIB_DMA_ChannelXPeripheralAddressGet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function uint16_t PLIB_DMA_ChannelXPeripheralAddressGet( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXPeripheralAddressSet Function Sets the peripheral address for the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXPeripheralAddressSet(DMA_MODULE_ID index, DMA_CHANNEL channel, uint16_t peripheraladdress); Returns None. Description This function sets the peripheral address for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint16_t peripheraladdress = 0x100; PLIB_DMA_ChannelXPeripheralAddressSet ( DMA_ID_0, DMA_CHANNEL_4, peripheraladdress ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL peripheraladdress The peripheral address for the specified channel Function void PLIB_DMA_ChannelXPeripheralAddressSet( DMA_MODULE_ID index, Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 561 DMA_CHANNEL channel , uint16_t peripheraladdress ) PLIB_DMA_ChannelXSourceStartAddressGet Function Reads the source start address configured for the specified channel. File plib_dma.h C uint32_t PLIB_DMA_ChannelXSourceStartAddressGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Returns • uint32_t - The source start address configured for this channel Description This function reads the source start address configured for the specified channel. Remarks This function implements an operation of the ChannelXSourceStartAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourceStartAddress function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint32_t SourceStartAddress; SourceStartAddress = PLIB_DMA_ChannelXSourceStartAddressGet(DMA_ID_0, spiDMAChannel ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function uint32_t PLIB_DMA_ChannelXSourceStartAddressGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ) PLIB_DMA_ChannelXSourceStartAddressSet Function Writes the specified source start address into the register corresponding to the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXSourceStartAddressSet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint32_t sourceStartAddress); Returns None. Description This function writes the specified Source start address into the register corresponding to the specified channel. Remarks This function implements an operation of the ChannelXSourceStartAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourceStartAddress function in your application to automatically determine whether this feature is available. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 562 Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint32_t sourceStartAddress = 0x00FDEA00; PLIB_DMA_ChannelXSourceStartAddressSet ( DMA_ID_0, spiDMAChannel, sourceStartAddress ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL sourceStartAddress The source start address Function void PLIB_DMA_ChannelXSourceStartAddressSet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint32_t sourceStartAddress) PLIB_DMA_ChannelXStartAddressOffsetGet Function Gets the primary/secondary start address (DPSRAM) offset. File plib_dma.h C uint16_t PLIB_DMA_ChannelXStartAddressOffsetGet(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_ADDRESS_OFFSET_TYPE offset); Returns • uint16_t - The primary/secondary DPSRAM start address offset Description This function gets the primary/secondary start address (DPSRAM) offset. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint16_t addressOffsetA; addressOffsetA = PLIB_DMA_ChannelXStartAddressOffsetGet ( DMA_ID_0, DMA_CHANNEL_4, address, DMA_ADDRESS_OFFSET_PRIMARY ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL offset The type of the address offset (primary/secondary) Function uint16_t PLIB_DMA_ChannelXStartAddressOffsetGet ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_ADDRESS_OFFSET_TYPE offset) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 563 PLIB_DMA_ChannelXStartAddressOffsetSet Function Sets the primary/secondary start address (DPSRAM) offset to the value specified depending on the offset type specified for the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXStartAddressOffsetSet(DMA_MODULE_ID index, DMA_CHANNEL channel, uint16_t address, DMA_ADDRESS_OFFSET_TYPE offset); Returns None. Description This function sets the primary/secondary start address (DPSRAM) offset to the value specified depending on the offset type specified for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint16_t address = 0x100; PLIB_DMA_ChannelXStartAddressOffsetSet ( DMA_ID_0, DMA_CHANNEL_4, address, DMA_ADDRESS_OFFSET_PRIMARY ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL address The primary/secondary DPSRAM start address offset offset The type of the address offset (primary/secondary) Function void PLIB_DMA_ChannelXStartAddressOffsetSet( DMA_MODULE_ID index, DMA_CHANNEL channel , uint16_t address, DMA_ADDRESS_OFFSET_TYPE offset ) g) Source/Destination/Peripheral Data Management Functions PLIB_DMA_ChannelXCellProgressPointerGet Function Returns the number of bytes transferred since the last event. File plib_dma.h C uint16_t PLIB_DMA_ChannelXCellProgressPointerGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Returns • uint16_t - The number of bytes transferred since the last event. The cell progress pointer (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 564 Description This function returns the number of bytes transferred since the last event. Remarks This function implements an operation of the ChannelXCellProgressPointer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXCellProgressPointer function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t CellProgress; CellProgress = PLIB_DMA_ChannelXCellProgressPointerGet ( DMA_ID_0, spiDMAChannel ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function uint16_t PLIB_DMA_ChannelXCellProgressPointerGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ) PLIB_DMA_ChannelXCellSizeGet Function Reads the cell size (in bytes) configured for the specified channel. File plib_dma.h C uint16_t PLIB_DMA_ChannelXCellSizeGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Returns • uint16_t - The cell size configured (in bytes) for this channel The cell size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Description This function reads the cell size (in bytes) configured for the specified channel. Remarks This function implements an operation of the ChannelXCellSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXCellSize function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t cellSize; cellSize = PLIB_DMA_ChannelXCellSizeGet ( DMA_ID_0, spiDMAChannel ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 565 Function uint16_t PLIB_DMA_ChannelXCellSizeGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ) PLIB_DMA_ChannelXCellSizeSet Function Writes the specified cell size into the register corresponding to the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXCellSizeSet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t CellSize); Returns None. Description This function writes the specified cell size into the register corresponding to the specified channel. Remarks This function implements an operation of the ChannelXCellSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXCellSize function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t cellSize = 0x10; PLIB_DMA_ChannelXCellSizeSet ( DMA_ID_0, spiDMAChannel, cellSize ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL cellSize The cell size in bytes. The cell size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Function void PLIB_DMA_ChannelXCellSizeSet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t cellSize) PLIB_DMA_ChannelXDataSizeGet Function Returns the current data size for the specified channel. File plib_dma.h C DMA_CHANNEL_DATA_SIZE PLIB_DMA_ChannelXDataSizeGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • channelDataSize - One of the possible data sizes listed by DMA_CHANNEL_DATA_SIZE Description This function returns the current data size for the specified channel. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 566 Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example DMA_CHANNEL_DATA_SIZE channelDataSize; channelDataSize = PLIB_DMA_ChannelXDataSizeGet( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function DMA_CHANNEL_DATA_SIZE PLIB_DMA_ChannelXDataSizeGet ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXDataSizeSelect Function Selects the data size for the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXDataSizeSelect(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_DATA_SIZE channelDataSize); Returns None. Description This function selects the data size for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example DMA_CHANNEL_DATA_SIZE channelDataSize = DMA_CHANNEL_DATA_8; PLIB_DMA_ChannelXDataSizeSelect ( DMA_ID_0, DMA_CHANNEL_4, channelDataSize ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL channelDataSize One of the possible data sizes listed by DMA_CHANNEL_DATA_SIZE Function void PLIB_DMA_ChannelXDataSizeSelect ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_DATA_SIZE channelDataSize ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 567 PLIB_DMA_ChannelXDestinationPointerGet Function Reads the current byte of the destination being pointed to for the specified channel. File plib_dma.h C uint16_t PLIB_DMA_ChannelXDestinationPointerGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Returns • uint16_t - The destination byte being pointed to for this channel. The destination pointer (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Description This function reads the current byte of the destination being pointed to for the specified channel. Remarks This function implements an operation of the ChannelXDestinationPointer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationPointer function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t destinationbyte; destinationbyte = PLIB_DMA_ChannelXDestinationPointerGet ( DMA_ID_0, spiDMAChannel ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function uint16_t PLIB_DMA_ChannelXDestinationPointerGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ) PLIB_DMA_ChannelXDestinationSizeGet Function Reads the destination size configured for the specified channel. File plib_dma.h C uint16_t PLIB_DMA_ChannelXDestinationSizeGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Returns • uint16_t - The destination size configured (in bytes) for this channel. The destination size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Description This function reads the destination size configured for the specified channel. Remarks This function implements an operation of the ChannelXDestinationSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationSize function in your application to automatically determine whether this feature is available. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 568 Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t DestinationSize; DestinationSize = PLIB_DMA_ChannelXDestinationSizeGet ( DMA_ID_0, spiDMAChannel ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function uint16_t PLIB_DMA_ChannelXDestinationSizeGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ) PLIB_DMA_ChannelXDestinationSizeSet Function Writes the specified destination size into the register corresponding to the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXDestinationSizeSet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t destinationSize); Returns None. Description This function writes the specified destination size into the register corresponding to the specified channel. Remarks This function implements an operation of the ChannelXDestinationSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationSize function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t destinationSize = 0xA00; PLIB_DMA_ChannelXDestinationSizeSet( DMA_ID_0, spiDMAChannel, destinationSize ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL destinationSize The destination size. The destination size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Function void PLIB_DMA_ChannelXDestinationSizeSet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t destinationSize) PLIB_DMA_ChannelXPatternDataGet Function Returns the pattern matching (for DMA abort) data programmed for the specified channel. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 569 File plib_dma.h C uint16_t PLIB_DMA_ChannelXPatternDataGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Returns • uint16_t - The pattern matching data programmed for the current channel. The size of pattern matching data(8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Description This function returns pattern matching (for DMA abort) data programmed for the specified channel. (The size of pattern matching data(8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the ChannelXPatternData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternData function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t patternData; patternData = PLIB_DMA_ChannelXPatternDataGet ( DMA_ID_0, spiDMAChannel ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function uint16_t PLIB_DMA_ChannelXPatternDataGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ) PLIB_DMA_ChannelXPatternDataSet Function Writes the specified pattern matching data (for DMA abort) into the register corresponding to the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXPatternDataSet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t patternData); Returns None. Description This function writes the specified pattern matching data (for DMA abort) into the register corresponding to the specified channel. (The size of pattern matching data(8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the ChannelXPatternData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternData function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 570 uint16_t patternData = '0'; PLIB_DMA_ChannelXPatternDataSet ( DMA_ID_0, spiDMAChannel, patternData ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL patternData The pattern matching DATA programmed for the current channel (The size of pattern matching data(8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Function void PLIB_DMA_ChannelXPatternDataSet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t patternData) PLIB_DMA_ChannelXSourcePointerGet Function Reads the current byte of the source being pointed to for the specified channel. File plib_dma.h C uint16_t PLIB_DMA_ChannelXSourcePointerGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Returns • uint16_t - The source byte being pointed to for this channel. The source pointer (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Description This function reads the current byte of the source being pointed to for the specified channel. Remarks This function implements an operation of the ChannelXSourcePointer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourcePointer function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t sourcebyte; sourcebyte = PLIB_DMA_ChannelXSourcePointerGet ( DMA_ID_0, spiDMAChannel ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function uint16_t PLIB_DMA_ChannelXSourcePointerGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ) PLIB_DMA_ChannelXSourceSizeGet Function Reads the source size configured for the specified channel. File plib_dma.h C uint16_t PLIB_DMA_ChannelXSourceSizeGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 571 Returns • uint16_t - The Source size configured (in bytes) for this channel. The source size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Description This function reads the source size configured for the specified channel. Remarks This function implements an operation of the ChannelXSourceSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourceSize function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t sourceSize; sourceSize = PLIB_DMA_ChannelXSourceSizeGet ( DMA_ID_0, spiDMAChannel ); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function uint16_t PLIB_DMA_ChannelXSourceSizeGet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ) PLIB_DMA_ChannelXSourceSizeSet Function Writes the specified source size into the register corresponding to the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXSourceSizeSet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t sourceSize); Returns None. Description This function writes the specified source size into the register corresponding to the specified channel. Remarks This function implements an operation of the ChannelXSourceSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourceSize function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t sourceSize = 0xA00; PLIB_DMA_ChannelXSourceSizeSet ( DMA_ID_0, spiDMAChannel, sourceSize ); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 572 Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL sourceSize The source size. The source size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Function void PLIB_DMA_ChannelXSourceSizeSet ( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t sourceSize) PLIB_DMA_ChannelXTransferCountGet Function Gets the DMA data transfer count that is programmed for the specified channel. File plib_dma.h C uint16_t PLIB_DMA_ChannelXTransferCountGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • uint16_t - The DMA transfer count for the channel Description This function gets the DMA data transfer count that is programmed for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint16_t transferCount; transferCount = PLIB_DMA_ChannelXTransferCountGet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function uint16_t PLIB_DMA_ChannelXTransferCountGet( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXTransferCountSet Function Sets the DMA data transfer count for the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXTransferCountSet(DMA_MODULE_ID index, DMA_CHANNEL channel, uint16_t transferCount); Returns None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 573 Description This function sets the DMA data transfer count for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint16_t transferCount = 0x10; PLIB_DMA_ChannelXTransferCountSet ( DMA_ID_0, DMA_CHANNEL_4, transferCount ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL transferCount The DMA transfer count for the channel Function void PLIB_DMA_ChannelXTransferCountSet( DMA_MODULE_ID index, DMA_CHANNEL channel , uint16_t transferCount ) h) Channel Configuration Functions PLIB_DMA_ChannelPrioritySelect Function Sets the priority scheme of the DMA channels. File plib_dma.h C void PLIB_DMA_ChannelPrioritySelect(DMA_MODULE_ID index, DMA_CHANNEL_PRIORITY channelPriority); Returns None. Description This function sets the priority scheme of the DMA channels at the global level. This function is used in devices that do not have the per channel priority feature. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example DMA_CHANNEL_PRIORITY channelPriority = DMA_CHANNEL_ROUND_ROBIN; PLIB_DMA_ChannelPrioritySelect( DMA_ID_0, channelPriority ); Parameters Parameters Description channelPriority One of the supported priorities listed by DMA_CHANNEL_PRIORITY Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 574 Function void PLIB_DMA_ChannelPrioritySelect ( DMA_MODULE_ID index, DMA_CHANNEL_PRIORITY channelPriority ) PLIB_DMA_ChannelPriorityGet Function Gets the priority scheme of the DMA channels. File plib_dma.h C DMA_CHANNEL_PRIORITY PLIB_DMA_ChannelPriorityGet(DMA_MODULE_ID index); Returns • channelPriority - One of the supported priorities listed by DMA_CHANNEL_PRIORITY Description This function gets the priority scheme of the DMA channels at the global level. This function is used in devices that do not have the per channel priority feature. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example DMA_CHANNEL_PRIORITY channelPriority; channelPriority = PLIB_DMA_ChannelPriorityGet( DMA_ID_0 ); Function DMA_CHANNEL_PRIORITY PLIB_DMA_ChannelPriorityGet ( DMA_MODULE_ID index ) PLIB_DMA_ChannelXAutoDisable Function Channel is disabled after a block transfer is complete. File plib_dma.h C void PLIB_DMA_ChannelXAutoDisable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function disables a channel after a block transfer is complete. Remarks This function implements an operation of the ChannelXAuto feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXAuto function in your application to determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXAutoDisable( DMA_ID_0, DMA_CHANNEL_2 ); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 575 Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXAutoDisable ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXAutoEnable Function Channel is continuously enabled. File plib_dma.h C void PLIB_DMA_ChannelXAutoEnable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function enables the channel continuously. The channel is not automatically disabled after a block transfer is complete. Remarks This function implements an operation of the ChannelXAuto feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXAuto function in your application to determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXAutoEnable( DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXAutoEnable ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXBusyActiveSet Function Sets the Busy bit to active. File plib_dma.h C void PLIB_DMA_ChannelXBusyActiveSet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function sets the Busy bit to active, indicating the channel is active or has been enabled. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 576 Remarks This function implements an operation of the ChannelXBusy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXBusy function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXBusyActiveSet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXBusyActiveSet ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXBusyInActiveSet Function Sets the Busy bit to inactive. File plib_dma.h C void PLIB_DMA_ChannelXBusyInActiveSet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function sets the Busy bit to inactive, indicating the channel is inactive or has been disabled. Remarks This function implements an operation of the ChannelXBusy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXBusy function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXBusyInActiveSet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXBusyInActiveSet ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXChainDisable Function Disables the channel chaining for the specified DMA channel. File plib_dma.h Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 577 C void PLIB_DMA_ChannelXChainDisable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function disables the channel chaining for the specified DMA channel. Remarks This function implements an operation of the ChannelXChainEnbl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXChainEnbl function in your application to determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXChainDisable( DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXChainDisable( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXChainEnable Function Channel chain feature is enabled. File plib_dma.h C void PLIB_DMA_ChannelXChainEnable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function enables the channel chain feature. Remarks This function implements an operation of the ChannelXChainEnbl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXChainEnbl function in your application to determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXChainEnable( DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXChainEnable ( DMA_MODULE_ID index, Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 578 DMA_CHANNEL channel ) PLIB_DMA_ChannelXChainToHigher Function Chains the specified channel to a channel higher in natural priority. File plib_dma.h C void PLIB_DMA_ChannelXChainToHigher(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function will chain the specified channel to a channel higher in natural priority. CH5 will be enabled by a CH4 transfer complete. Remarks This function implements an operation of the ChannelXChain feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXChain function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXChainToHigher ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXChainToHigher ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXChainToLower Function Chains the specified channel to a channel lower in natural priority. File plib_dma.h C void PLIB_DMA_ChannelXChainToLower(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function will chain the specified channel to a channel lower in natural priority. CH3 will be enabled by a CH4 transfer complete. Remarks This function implements an operation of the ChannelXChain feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXChain function in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 579 Example PLIB_DMA_ChannelXChainToLower ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXChainToLower( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXDisable Function Disable the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXDisable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function will disable the specified channel. Remarks This function implements an operation of the ChannelX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelX function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXDisable ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXEnable Function Enable the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXEnable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 580 Description This function will enable the specified channel. Remarks This function implements an operation of the ChannelX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelX function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXEnable ( DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXEnable ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXPriorityGet Function Gets the priority of the specified channel. File plib_dma.h C DMA_CHANNEL_PRIORITY PLIB_DMA_ChannelXPriorityGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • channelPriority - One of the supported priorities listed by DMA_CHANNEL_PRIORITY Description This function gets the priority of the specified channel. Remarks This function implements an operation of the ChannelXPriority feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPriority function in your application to determine whether this feature is available. Preconditions None. Example DMA_CHANNEL channel = DMA_CHANNEL_0; DMA_CHANNEL_PRIORITY channelPriority; channelPriority = PLIB_DMA_ChannelXPriorityGet( DMA_ID_0, channel ); Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL Function DMA_CHANNEL_PRIORITY PLIB_DMA_ChannelXPriorityGet ( DMA_MODULE_ID index, DMA_CHANNEL channel ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 581 PLIB_DMA_ChannelXPrioritySelect Function Sets the priority of the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXPrioritySelect(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_PRIORITY channelPriority); Returns None. Description This function sets the priority of the specified channel. Remarks This function implements an operation of the ChannelXPriority feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPriority function in your application to determine whether this feature is available. Preconditions None. Example DMA_CHANNEL channel = DMA_CHANNEL_0; DMA_CHANNEL_PRIORITY channelPriority = DMA_CHANNEL_PRIORITY_3; PLIB_DMA_ChannelXPrioritySelect( DMA_ID_0, channel, channelPriority ); Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL channelPriority One of the supported priorities listed by DMA_CHANNEL_PRIORITY Function void PLIB_DMA_ChannelXPrioritySelect ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_PRIORITY channelPriority ) PLIB_DMA_ChannelXTransferDirectionGet Function Returns the data transfer direction of the specified channel. File plib_dma.h C DMA_CHANNEL_TRANSFER_DIRECTION PLIB_DMA_ChannelXTransferDirectionGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • DMA_CHANNEL_TRANSFER_DIRECTION - The transfer direction indicated by the DMA_CHANNEL_TRANSFER_DIRECTION Description This function returns the data transfer direction of the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 582 Preconditions None. Example DMA_CHANNEL_TRANSFER_DIRECTION chTransferDirection; chTransferDirection = PLIB_DMA_ChannelXTransferDirectionGet ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function DMA_CHANNEL_TRANSFER_DIRECTION PLIB_DMA_ChannelXTransferDirectionGet ( DMA_MODULE_ID index, DMA_CHANNEL channel) PLIB_DMA_ChannelXTransferDirectionSelect Function Selects the data transfer direction of the specified channel. File plib_dma.h C void PLIB_DMA_ChannelXTransferDirectionSelect(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRANSFER_DIRECTION chTransferDirection); Returns None. Description This function selects the data transfer direction of the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DMA_ChannelXTransferDirectionSelect ( DMA_ID_0, DMA_CHANNEL_4, DMA_READ_FROM_MEMORY_WRITE_TO_PERIPHERAL ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL chTransferDirection The transfer direction indicated by DMA_CHANNEL_TRANSFER_DIRECTION Function void PLIB_DMA_ChannelXTransferDirectionSelect ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRANSFER_DIRECTION chTransferDirection ) PLIB_DMA_ChannelXDisabledDisablesEvents Function Channel start/abort events will be ignored even if the channel is disabled. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 583 File plib_dma.h C void PLIB_DMA_ChannelXDisabledDisablesEvents(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function will allow the channel start/abort events to be ignored even if the channel is disabled. Remarks This function implements an operation of the ChannelXDisabled feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDisabled function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXDisabledDisablesEvents ( DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXDisabledDisablesEvents ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXDisabledEnablesEvents Function Channel start/abort events will be registered even if the channel is disabled. File plib_dma.h C void PLIB_DMA_ChannelXDisabledEnablesEvents(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function will allow the channel register start/abort events even if the channel is disabled. Remarks This function implements an operation of the ChannelXDisabled feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDisabled function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_ChannelXDisabledEnablesEvents ( DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 584 Function void PLIB_DMA_ChannelXDisabledEnablesEvents ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXPatternIgnoreByteDisable Function Disables the pattern match ignore byte. File plib_dma.h C void PLIB_DMA_ChannelXPatternIgnoreByteDisable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function disables the pattern match ignore byte. Remarks This function implements an operation of the ChannelXPatternIgnoreByte feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnoreByte function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXPatternIgnoreByteDisable(DMA_ID_0, dmaChannel); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXPatternIgnoreByteDisable ( DMA_MODULE_ID index, DMA_CHANNEL channel ); PLIB_DMA_ChannelXPatternIgnoreByteEnable Function Enables the pattern match ignore byte. File plib_dma.h C void PLIB_DMA_ChannelXPatternIgnoreByteEnable(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function enables the pattern match ignore byte. Remarks This function implements an operation of the ChannelXPatternIgnoreByte feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnoreByte function in your application to Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 585 automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXPatternIgnoreByteEnable(DMA_ID_0, dmaChannel); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_ChannelXPatternIgnoreByteEnable ( DMA_MODULE_ID index, DMA_CHANNEL channel ); PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled Function Returns the state of the pattern match ignore byte. File plib_dma.h C bool PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • true - The pattern match ignore byte is enabled • false - The pattern match ignore byte is disabled Description This function returns the state (enabled or disabled) of the pattern match ignore byte. Remarks This function implements an operation of the ChannelXPatternIgnoreByte feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnoreByte function in your application to automatically determine whether this feature is available. Preconditions None. Example bool patternIsEnabled; DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; patternIsEnabled = PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled(DMA_ID_0, dmaChannel); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function bool PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled ( DMA_MODULE_ID index, DMA_CHANNEL channel ); PLIB_DMA_ChannelXPatternIgnoreGet Function Returns the pattern match ignore value. File plib_dma.h Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 586 C uint8_t PLIB_DMA_ChannelXPatternIgnoreGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • uint8_t - Pattern match ignore value Description This function returns the value of the pattern match ignore. Remarks This function implements an operation of the ChannelXPatternIgnore feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnore function in your application to automatically determine whether this feature is available. Preconditions None. Example uint8_t patternMatch; DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; patternMatch = PLIB_DMA_ChannelXPatternIgnoreGet ( DMA_ID_0, dmaChannel); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function uint8_t PLIB_DMA_ChannelXPatternIgnoreGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); PLIB_DMA_ChannelXPatternIgnoreSet Function Sets the pattern match ignore value. File plib_dma.h C void PLIB_DMA_ChannelXPatternIgnoreSet(DMA_MODULE_ID index, DMA_CHANNEL channel, uint8_t pattern); Returns None. Description This function sets the value of the pattern match ignore. Remarks This function implements an operation of the ChannelXPatternIgnore feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnore function in your application to automatically determine whether this feature is available. Preconditions None. Example uint8_t patternMatch = 0x8; DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXPatternIgnoreSet ( DMA_ID_0, dmaChannel,patternMatch); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 587 Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL pattern Pattern match ignore value Function void PLIB_DMA_ChannelXPatternIgnoreSet ( DMA_MODULE_ID index, DMA_CHANNEL channel, uint8_t pattern ); PLIB_DMA_ChannelXPatternLengthGet Function Returns the pattern match length. File plib_dma.h C DMA_PATTERN_LENGTH PLIB_DMA_ChannelXPatternLengthGet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); Returns • patternLen - Length of pattern match (either 1 or 2) Description This function returns the length of the byte matching the CHPIGN bits during a pattern match that may be ignored during the pattern match determination when the CHPIGNEN bit is set. Remarks This function implements an operation of the ChannelXPatternLength feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternLength function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; DMA_PATTERN_LENGTH patternLen; patternLen = PLIB_DMA_ChannelXPatternLengthGet(DMA_ID_0, dmaChannel); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Function DMA_PATTERN_LENGTH PLIB_DMA_ChannelXPatternLengthGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel); PLIB_DMA_ChannelXPatternLengthSet Function Sets the pattern match length. File plib_dma.h C void PLIB_DMA_ChannelXPatternLengthSet(DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_PATTERN_LENGTH patternLen); Returns None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 588 Description This function sets the length of the pattern match ignore to 1 or 2 bytes. Remarks This function implements an operation of the ChannelXPatternLength feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternLength function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; DMA_PATTERN_LENGTH patternLen; patternLen = DMA_PATTERN_MATCH_LENGTH_1BYTE; PLIB_DMA_ChannelXPatternLengthSet(DMA_ID_0, dmaChannel, patternLen); Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL patternLen Length of pattern match (either 1 or 2) Function void PLIB_DMA_ChannelXPatternLengthSet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel,DMA_PATTERN_LENGTH patternLen ) i) CRC Module Interface Functions PLIB_DMA_CRCAppendModeDisable Function Disables the CRC append mode. File plib_dma.h C void PLIB_DMA_CRCAppendModeDisable(DMA_MODULE_ID index); Returns None. Description This function disables the CRC append mode. The DMA transfers data from the source through the CRC obeying WBO (DMA_MODULE_ID index, write byte order) as it writes the data to the destination. Remarks This function implements an operation of the CRCAppendMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCAppendMode function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_CRCAppendModeDisable( DMA_ID_0 ); Function void PLIB_DMA_CRCAppendModeDisable ( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 589 PLIB_DMA_CRCAppendModeEnable Function Enables the CRC append mode. File plib_dma.h C void PLIB_DMA_CRCAppendModeEnable(DMA_MODULE_ID index); Returns None. Description This function enables the CRC append mode. The DMA transfers data from the source into the CRC, but not to the destination. When a block transfer completes, the DMA writes the calculated CRC value to the location specified by the CHxDSA register. Remarks This function implements an operation of the CRCAppendMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCAppendMode function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_CRCAppendModeEnable( DMA_ID_0 ); Function void PLIB_DMA_CRCAppendModeEnable ( DMA_MODULE_ID index ) PLIB_DMA_CRCAppendModeIsEnabled Function Gets the enable status of the CRC append mode. File plib_dma.h C bool PLIB_DMA_CRCAppendModeIsEnabled(DMA_MODULE_ID index); Returns • true - CRC append mode is enabled • false - CRC append mode is disabled Description This function gets the enable status of the CRC append mode. Remarks This function implements an operation of the CRCAppendMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCAppendMode function in your application to automatically determine whether this feature is available. Preconditions None. Example bool DMAcrcAppendMode; DMAcrcAppendMode = PLIB_DMA_CRCAppendModeIsEnabled( DMA_ID_0 ); Function bool PLIB_DMA_CRCAppendModeIsEnabled ( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 590 PLIB_DMA_CRCBitOrderSelect Function Selects the bit order for checksum calculation. File plib_dma.h C void PLIB_DMA_CRCBitOrderSelect(DMA_MODULE_ID index, DMA_CRC_BIT_ORDER bitOrder); Returns None. Description This function selects the bit order for checksum calculation. Remarks This function implements an operation of the CRCBitOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCBitOrder function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_CRCBitOrderSelect ( DMA_ID_0,DMA_CRC_BIT_ORDER_LSB ); Parameters Parameters Description bitOrder Specifies the bit order for CRC calculation Function void PLIB_DMA_CRCBitOrderSelect ( DMA_MODULE_ID index, DMA_CRC_BIT_ORDER bitOrder ) PLIB_DMA_CRCByteOrderGet Function Gets the current byte order selected by the DMA module CRC feature. File plib_dma.h C DMA_CRC_BYTE_ORDER PLIB_DMA_CRCByteOrderGet(DMA_MODULE_ID index); Returns • byteOrder - One of the possible byte orders specified by DMA_CRC_BYTE_ORDER Description This function gets the current byte order selected by the DMA module CRC feature. Remarks This function implements an operation of the CRCByteOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCByteOrder function in your application to automatically determine whether this feature is available. Preconditions The WBO bit must be set to use this function. Example DMA_CRC_BYTE_ORDER byteOrder; Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 591 byteOrder = PLIB_DMA_CRCByteOrderGet ( DMA_ID_0 ); Function DMA_CRC_BYTE_ORDER PLIB_DMA_CRCByteOrderGet ( DMA_MODULE_ID index ) PLIB_DMA_CRCByteOrderSelect Function Selects the byte order. File plib_dma.h C void PLIB_DMA_CRCByteOrderSelect(DMA_MODULE_ID index, DMA_CRC_BYTE_ORDER byteOrder); Returns None. Description This function selects the byte order. Remarks This function implements an operation of the CRCByteOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCByteOrder function in your application to automatically determine whether this feature is available. Preconditions The WBO bit must be set to use this function. Example PLIB_DMA_CRCByteOrderSelect ( DMA_ID_0, DMA_CRC_SWAP_HALF_WORD_ON_WORD_BOUNDARY ); Parameters Parameters Description byteOrder One of the possible byte orders specified by DMA_CRC_BYTE_ORDER Function void PLIB_DMA_CRCByteOrderSelect ( DMA_MODULE_ID index, DMA_CRC_BYTE_ORDER byteOrder ) PLIB_DMA_CRCChannelGet Function Returns the current DMA channel to which the CRC is assigned. File plib_dma.h C DMA_CHANNEL PLIB_DMA_CRCChannelGet(DMA_MODULE_ID index); Returns crcChannel - One of the possible DMA channels listed by DMA_CHANNEL Description This function returns the current DMA channel to which the CRC is assigned. Remarks This function implements an operation of the CRCChannel feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCChannel function in your application to automatically determine whether this feature is available. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 592 Preconditions None. Example DMA_CHANNEL crcChannel; crcChannel = PLIB_DMA_CRCChannelGet( DMA_ID_0 ); Function DMA_CHANNEL PLIB_DMA_CRCChannelGet ( DMA_MODULE_ID index ) PLIB_DMA_CRCChannelSelect Function Assigns the CRC to the specified DMA channel. File plib_dma.h C void PLIB_DMA_CRCChannelSelect(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns None. Description This function assigns the CRC feature to the specified channel. Remarks This function implements an operation of the CRCChannel feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCChannel function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_CRCChannelSelect( DMA_ID_0, DMA_CHANNEL_5 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function void PLIB_DMA_CRCChannelSelect( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_CRCDataRead Function Reads the contents of the DMA CRC data register. File plib_dma.h C uint32_t PLIB_DMA_CRCDataRead(DMA_MODULE_ID index); Returns • uint32_t - 32-bit CRC data The CRC data (16-bit, 32-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 593 Description This function reads the contents of the DMA CRC data register. Remarks This function implements an operation of the CRCData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCData function in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t DMACRCdata; DMACRCdata = PLIB_DMA_CRCDataRead ( DMA_ID_0 ); Function uint32_t PLIB_DMA_CRCDataRead ( DMA_MODULE_ID index ) PLIB_DMA_CRCDataWrite Function Writes the contents of the DMA CRC data register with the specified data. File plib_dma.h C void PLIB_DMA_CRCDataWrite(DMA_MODULE_ID index, uint32_t DMACRCdata); Returns None. Description This function writes the contents of the DMA CRC data register. Remarks This function implements an operation of the CRCData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCData function in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t DMACRCdata = 0x0E0E0E; PLIB_DMA_CRCDataWrite ( DMA_ID_0, DMACRCdata ); Function void PLIB_DMA_CRCDataWrite ( DMA_MODULE_ID index, uint32_t DMACRCdata ) PLIB_DMA_CRCDisable Function Disables the DMA module CRC feature. File plib_dma.h C void PLIB_DMA_CRCDisable(DMA_MODULE_ID index); Returns None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 594 Description This function disables the DMA module CRC feature. The channel transfers proceed normally. Remarks This function implements an operation of the CRC feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRC function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_CRCDisable( DMA_ID_0 ); Function void PLIB_DMA_CRCDisable ( DMA_MODULE_ID index ) PLIB_DMA_CRCEnable Function Enables the DMA module CRC feature. File plib_dma.h C void PLIB_DMA_CRCEnable(DMA_MODULE_ID index); Returns None. Description This function enables the DMA module CRC feature. The channel transfers are routed through the CRC. Remarks This function implements an operation of the CRC feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRC function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_CRCEnable( DMA_ID_0 ); Function void PLIB_DMA_CRCEnable ( DMA_MODULE_ID index ) PLIB_DMA_CRCPolynomialLengthGet Function Gets the current polynomial length. File plib_dma.h C uint8_t PLIB_DMA_CRCPolynomialLengthGet(DMA_MODULE_ID index); Returns • uint8_t - Polynomial length Description This function gets the current polynomial length. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 595 Remarks This function implements an operation of the CRCPolynomialLength feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCPolynomialLength function in your application to automatically determine whether this feature is available. Preconditions None. Example uint8_t polyLength; polyLength = PLIB_DMA_CRCPolynomialLengthGet( DMA_ID_0 ); Function uint8_t PLIB_DMA_CRCPolynomialLengthGet ( DMA_MODULE_ID index ) PLIB_DMA_CRCPolynomialLengthSet Function Selects the polynomial length. File plib_dma.h C void PLIB_DMA_CRCPolynomialLengthSet(DMA_MODULE_ID index, uint8_t polyLength); Returns None. Description This function Selects the polynomial length. Remarks This function implements an operation of the CRCPolynomialLength feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCPolynomialLength function in your application to automatically determine whether this feature is available. Preconditions None. Example uint8_t polyLength = 0x2; PLIB_DMA_CRCPolynomialLengthSet( DMA_ID_0, polyLength ); Parameters Parameters Description polyLength Polynomial length Function void PLIB_DMA_CRCPolynomialLengthSet ( DMA_MODULE_ID index, uint8_t polyLength ) PLIB_DMA_CRCTypeGet Function Gets the current DMA module CRC feature type. File plib_dma.h C DMA_CRC_TYPE PLIB_DMA_CRCTypeGet(DMA_MODULE_ID index); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 596 Returns • CRCType - One of the possible CRC checksums listed by DMA_CRC_TYPE. Description This function gets the DMA module CRC feature type. The CRC feature will compute either the IP header checksum or the Linear Shift Feedback Register (LFSR) checksum. Remarks This function implements an operation of the CRCType feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCType function in your application to automatically determine whether this feature is available. Preconditions None. Example DMA_CRC_TYPE CRCType; CRCType = PLIB_DMA_CRCTypeGet( DMA_ID_0 ); Function DMA_CRC_TYPE PLIB_DMA_CRCTypeGet ( DMA_MODULE_ID index ) PLIB_DMA_CRCTypeSet Function Selects the DMA module CRC feature type. File plib_dma.h C void PLIB_DMA_CRCTypeSet(DMA_MODULE_ID index, DMA_CRC_TYPE CRCType); Returns None. Description This function selects the DMA module CRC feature type. The CRC feature will compute either the IP header checksum or the Linear Shift Feedback Register (LFSR) checksum. Remarks This function implements an operation of the CRCType feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCType function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_CRCTypeSet(DMA_ID_0, DMA_CRC_IP_HEADER ); Parameters Parameters Description CRCType One of the possible CRC checksums listed by DMA_CRC_TYPE Function void PLIB_DMA_CRCTypeSet ( DMA_MODULE_ID index, DMA_CRC_TYPE CRCType ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 597 PLIB_DMA_CRCWriteByteOrderAlter Function The source data is written to the destination reordered as defined by the BYTO<1:0> bits. File plib_dma.h C void PLIB_DMA_CRCWriteByteOrderAlter(DMA_MODULE_ID index); Returns None. Description This function enables byte order alteration as specified by the BYTO<1:0> bits. The source data is written to the destination reordered as defined by the BYTO<1:0> bits. Remarks This function implements an operation of the CRCWriteByteOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCWriteByteOrder function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_CRCWriteByteOrderAlter ( DMA_ID_0 ); Function void PLIB_DMA_CRCWriteByteOrderAlter ( DMA_MODULE_ID index ) PLIB_DMA_CRCWriteByteOrderMaintain Function The source data is written to the destination unaltered. File plib_dma.h C void PLIB_DMA_CRCWriteByteOrderMaintain(DMA_MODULE_ID index); Returns None. Description This function disables byte order alteration. The source data is written to the destination unaltered. Remarks This function implements an operation of the CRCWriteByteOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCWriteByteOrder function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_CRCWriteByteOrderMaintain ( DMA_ID_0 ); Function void PLIB_DMA_CRCWriteByteOrderMaintain ( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 598 PLIB_DMA_CRCXOREnableGet Function Reads the CRC XOR register. File plib_dma.h C uint32_t PLIB_DMA_CRCXOREnableGet(DMA_MODULE_ID index); Returns • uint32_t - 32-bit CRC XOR enable mask data The CRC data (16-bit, 32-bit) is device-specific. Please refer to the specific device data sheet to determine availability. Description This function reads the CRC XOR register. Remarks This function implements an operation of the CRCXOREnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCXOREnable function in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t DMACRCXORdata; DMACRCXORdata = PLIB_DMA_CRCXOREnableGet ( DMA_ID_0 ); Function uint32_t PLIB_DMA_CRCXOREnableGet ( DMA_MODULE_ID index ) PLIB_DMA_CRCXOREnableSet Function Writes to the CRC XOR enable register as per the specified enable mask. File plib_dma.h C void PLIB_DMA_CRCXOREnableSet(DMA_MODULE_ID index, uint32_t DMACRCXOREnableMask); Returns None. Description This function writes to the CRC XOR enable register as per the specified enable mask. Each enabled bit will be taken as input to the shift register. Remarks This function implements an operation of the CRCXOREnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCXOREnable function in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t DMACRCXOREnableMask = 0x05EFFFFF; PLIB_DMA_CRCXOREnableSet ( DMA_ID_0, DMACRCXOREnableMask ); Function void PLIB_DMA_CRCXOREnableSet ( DMA_MODULE_ID index, Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 599 uint32_t DMACRCXOREnableMask ) j) Global Status Functions PLIB_DMA_CRCIsEnabled Function Gets the enable status of the CRC feature. File plib_dma.h C bool PLIB_DMA_CRCIsEnabled(DMA_MODULE_ID index); Returns • true - The CRC feature is enabled • false - The CRC feature is disabled Description This function gets the enable status of the CRC feature. Remarks This function implements an operation of the CRC feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRC function in your application to automatically determine whether this feature is available. Preconditions None. Example bool DMAcrcStatus; DMAcrcStatus = PLIB_DMA_CRCIsEnabled( DMA_ID_0 ); Function bool PLIB_DMA_CRCIsEnabled ( DMA_MODULE_ID index ) PLIB_DMA_IsBusy Function Gets the BUSY bit of the DMA controller. File plib_dma.h C bool PLIB_DMA_IsBusy(DMA_MODULE_ID index); Returns • true - DMA module is active • false - DMA module is disabled and is not actively transferring data Description This function gets the BUSY bit of the DMA controller. Remarks This function implements an operation of the Busy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsBusy function in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 600 Example bool dmaBusyStatus; dmaBusyStatus = PLIB_DMA_IsBusy( DMA_ID_0 ); Function bool PLIB_DMA_IsBusy ( DMA_MODULE_ID index ) PLIB_DMA_IsEnabled Function Returns the DMA module enable status. File plib_dma.h C bool PLIB_DMA_IsEnabled(DMA_MODULE_ID index); Returns • true - The DMA is enabled • false - The DMA is disabled Description This function returns the DMA module enable status. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsEnableControl function in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_DMA_IsEnabled( DMA_ID_0 ); Function bool PLIB_DMA_IsEnabled ( DMA_MODULE_ID index ) PLIB_DMA_LastBusAccessIsRead Function Returns true if the last DMA bus access was a read. File plib_dma.h C bool PLIB_DMA_LastBusAccessIsRead(DMA_MODULE_ID index); Returns • true - The last bus access was a read • false - The last bus access was not a read Description This function returns true if the last DMA bus access was a read. Remarks This function implements an operation of the LastBusAccess feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsLastBusAccess function in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 601 Example bool dmaLastBusAccessType; dmaLastBusAccessType = PLIB_DMA_LastBusAccessIsRead( DMA_ID_0 ); Function bool PLIB_DMA_LastBusAccessIsRead ( DMA_MODULE_ID index ) PLIB_DMA_LastBusAccessIsWrite Function Returns true if the last DMA bus access was a write. File plib_dma.h C bool PLIB_DMA_LastBusAccessIsWrite(DMA_MODULE_ID index); Returns • true - The last bus access was a write operation • false - The last bus access was not a write operation Description This function returns true if the last DMA bus access was a write operation. Remarks This function implements an operation of the LastBusAccess feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsLastBusAccess function in your application to automatically determine whether this feature is available. Preconditions None. Example bool dmaLastBusAccessType; dmaLastBusAccessType = PLIB_DMA_LastBusAccessIsWrite( DMA_ID_0 ); Function bool PLIB_DMA_LastBusAccessIsWrite ( DMA_MODULE_ID index ) PLIB_DMA_RecentAddressAccessed Function Returns the address of the most recent DMA access. File plib_dma.h C uint32_t PLIB_DMA_RecentAddressAccessed(DMA_MODULE_ID index); Returns • uint32_t - The most recent address accessed by the DMA Description This function returns the address of the most recent DMA access. Remarks This function implements an operation of the RecentAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsRecentAddress function in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 602 Example uint32_t dmaLastAddressAccessed; dmaLastAddressAccessed = PLIB_DMA_RecentAddressAccessed( DMA_ID_0 ); Function uint32_t PLIB_DMA_RecentAddressAccessed ( DMA_MODULE_ID index ) PLIB_DMA_SuspendIsEnabled Function Returns the DMA suspend status. File plib_dma.h C bool PLIB_DMA_SuspendIsEnabled(DMA_MODULE_ID index); Returns • true - The DMA transfers are suspended • false - The DMA operates normally Description This function returns the DMA suspend status. Remarks This function implements an operation of the Suspend feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsSuspend function in your application to automatically determine whether this feature is available. Preconditions None. Example bool dmaSuspendStatus; dmaSuspendStatus = PLIB_DMA_SuspendIsEnabled( DMA_ID_0 ); Function bool PLIB_DMA_SuspendIsEnabled ( DMA_MODULE_ID index ) k) Channel Status Functions PLIB_DMA_ChannelXAutoIsEnabled Function Returns the channel automatic enable status. File plib_dma.h C bool PLIB_DMA_ChannelXAutoIsEnabled(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • true - Channel automatic enable is on • false - Channel automatic enable is off Description This function returns the channel automatic enable status. Remarks This function implements an operation of the ChannelXAuto feature. This feature may not be available on all devices. Please refer to the specific Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 603 device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXAuto function in your application to determine whether this feature is available. Preconditions None. Example bool ChAutoEnableStatus; ChAutoEnableStatus = PLIB_DMA_ChannelXAutoIsEnabled(DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function bool PLIB_DMA_ChannelXAutoIsEnabled ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXBufferedDataIsWritten Function Returns the buffered data write status for the specified channel. File plib_dma.h C bool PLIB_DMA_ChannelXBufferedDataIsWritten(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • true - The content of the DMA buffer has not been written to the location specified in the destination/source address or in Null Write mode • false - The content of the DMA buffer has been written to the location specified in the destination/source address or in Null Write mode Description This function returns the buffered data write status for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example bool chBuffWriteStatus; chBuffWriteStatus = PLIB_DMA_ChannelXBufferedDataIsWritten( DMA_ID_0, DMA_CHANNEL_3 ); Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL Function bool PLIB_DMA_ChannelXBufferedDataIsWritten ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXBusyIsBusy Function Returns the busy status of the specified channel. File plib_dma.h Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 604 C bool PLIB_DMA_ChannelXBusyIsBusy(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • true - The channel is active or has been enabled • false - The channel is inactive or has been disabled Description This function returns the busy status of the specified channel. Remarks This function implements an operation of the ChannelXBusy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXBusy function in your application to automatically determine whether this feature is available. Preconditions None. Example bool chBusyStatus; chBusyStatus = PLIB_DMA_ChannelXBusyIsBusy ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function bool PLIB_DMA_ChannelXBusyIsBusy ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXChainIsEnabled Function Returns the chain status of the specified channel. File plib_dma.h C bool PLIB_DMA_ChannelXChainIsEnabled(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • true - The channel chain is on for this channel • false - The channel chain is off for this channel Description This function returns the chain status of the specified channel. Remarks This function implements an operation of the ChannelXChainEnbl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXChainEnbl function in your application to determine whether this feature is available. Preconditions None. Example bool ChchainStatus; ChchainStatus = PLIB_DMA_ChannelXChainIsEnabled( DMA_ID_0, DMA_CHANNEL_2 ); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 605 Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function bool PLIB_DMA_ChannelXChainIsEnabled ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXCollisionStatus Function Returns the status of the specified collision type for the specified channel. File plib_dma.h C bool PLIB_DMA_ChannelXCollisionStatus(DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_COLLISION collisonType); Returns • true - A collision specified by collisonType was detected • false - No collision of type collisonType was detected Description This function returns the status of the specified collision type for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example bool memWriteCollisionStatus; memWriteCollisionStatus = PLIB_DMA_ChannelXMemoryWriteCollisionStatus( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_COLLISION_MEMORY ); Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL collisonType Collision type listed by DMA_CHANNEL_COLLISION Function bool PLIB_DMA_ChannelXCollisionStatus ( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_COLLISION collisonType ) PLIB_DMA_ChannelXEventIsDetected Function Returns the event status on the specified channel. File plib_dma.h C bool PLIB_DMA_ChannelXEventIsDetected(DMA_MODULE_ID index, DMA_CHANNEL channel); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 606 Returns • true - An event was detected • false - No events were detected Description This function returns the event status on the specified channel. Remarks This function implements an operation of the ChannelXEvent feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_DMA_ExistsChannelXEvent function in your application to determine whether this feature is available. Preconditions None. Example bool channeleventStatus; channeleventStatus = PLIB_DMA_ChannelXEventIsDetected( DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function bool PLIB_DMA_ChannelXEventIsDetected ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXIsEnabled Function Return the enable status of the specified channel. File plib_dma.h C bool PLIB_DMA_ChannelXIsEnabled(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • true - The specified DMA channel is enabled • false - The specified DMA channel is disabled Description This function will return the enable status of the specified channel. Remarks This function implements an operation of the ChannelX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelX function in your application to automatically determine whether this feature is available. Preconditions None. Example bool chEnableStatus; chEnableStatus = PLIB_DMA_ChannelXIsEnabled ( DMA_ID_0, DMA_CHANNEL_2 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 607 Function bool PLIB_DMA_ChannelXIsEnabled ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXNullWriteModeIsEnabled Function Returns the enable status of the Null Write mode for the specified channel. File plib_dma.h C bool PLIB_DMA_ChannelXNullWriteModeIsEnabled(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns • true - Null write mode is enabled for this channel • false - Null write mode is disabled for this channel Description This function returns the enable status of the Null Write mode for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example bool chNullWriteStatus; chNullWriteStatus = PLIB_DMA_ChannelXNullWriteModeIsEnabled ( DMA_ID_0, DMA_CHANNEL_4 ); Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Function bool PLIB_DMA_ChannelXNullWriteModeIsEnabled ( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelXPingPongModeGet Function Returns the Ping-Pong mode status for the specified channel. File plib_dma.h C DMA_PING_PONG_MODE PLIB_DMA_ChannelXPingPongModeGet(DMA_MODULE_ID index, DMA_CHANNEL channel); Returns mode - One of the possible Ping-Pong modes Description This function returns the Ping-Pong mode status for the specified channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 608 Preconditions None. Example DMA_PING_PONG_MODE chPingPongStatus; chPingPongStatus = PLIB_DMA_ChannelXPingPongModeGet(DMA_ID_0, DMA_CHANNEL_3 ); if (DMA_PING_PONG_SECONDARY == chPingPongStatus) { \Application } Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL Function DMA_PING_PONG_MODE PLIB_DMA_ChannelXPingPongModeGet( DMA_MODULE_ID index, DMA_CHANNEL channel ) PLIB_DMA_ChannelBitsGet Function Returns the DMA channel bits. File plib_dma.h C uint8_t PLIB_DMA_ChannelBitsGet(DMA_MODULE_ID index); Returns • uint8_t - DMA channel bits Description This function returns the channel bits. Remarks This function implements an operation of the ChannelBits feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelBits function in your application to automatically determine whether this feature is available. Preconditions None. Example uint8_t dmaChBits; dmaChBits = PLIB_DMA_ChannelBitsGet( DMA_ID_0 ); Function uint8_t PLIB_DMA_ChannelBitsGet ( DMA_MODULE_ID index ) l) Feature Existence Functions PLIB_DMA_ExistsAbortTransfer Function Identifies whether the AbortTransfer feature exists on the DMA module. File plib_dma.h Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 609 C bool PLIB_DMA_ExistsAbortTransfer(DMA_MODULE_ID index); Returns • true - The AbortTransfer feature is supported on the device • false - The AbortTransfer feature is not supported on the device Description This function identifies whether the AbortTransfer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_AbortTransferSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsAbortTransfer( DMA_MODULE_ID index ) PLIB_DMA_ExistsBusy Function Identifies whether the Busy feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsBusy(DMA_MODULE_ID index); Returns • true - The Busy feature is supported on the device • false - The Busy feature is not supported on the device Description This function identifies whether the Busy feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_BusyActiveSet • PLIB_DMA_BusyActiveReset • PLIB_DMA_IsBusy Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsBusy( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 610 PLIB_DMA_ExistsChannelBits Function Identifies whether the ChannelBits feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelBits(DMA_MODULE_ID index); Returns • true - The ChannelBits feature is supported on the device • false - The ChannelBits feature is not supported on the device Description This function identifies whether the ChannelBits feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelBitsGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelBits( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelX Function Identifies whether the ChannelX feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelX(DMA_MODULE_ID index); Returns • true - The ChannelX feature is supported on the device • false - The ChannelX feature is not supported on the device Description This function identifies whether the ChannelX feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXEnable • PLIB_DMA_ChannelXIsEnabled • PLIB_DMA_ChannelXDisable Remarks None. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 611 Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelX( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXAbortIRQ Function Identifies whether the ChannelXAbortIRQ feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXAbortIRQ(DMA_MODULE_ID index); Returns • true - The ChannelXAbortIRQ feature is supported on the device • false - The ChannelXAbortIRQ feature is not supported on the device Description This function identifies whether the ChannelXAbortIRQ feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXAbortIRQSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXAbortIRQ( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXAuto Function Identifies whether the ChannelXAuto feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXAuto(DMA_MODULE_ID index); Returns • true - The ChannelXAuto feature is supported on the device • false - The ChannelXAuto feature is not supported on the device Description This function identifies whether the ChannelXAuto feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXAutoEnable • PLIB_DMA_ChannelXAutoDisable • PLIB_DMA_ChannelXAutoIsEnabled Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 612 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXAuto( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXBusy Function Identifies whether the ChannelXBusy feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXBusy(DMA_MODULE_ID index); Returns • true - The ChannelXBusy feature is supported on the device • false - The ChannelXBusy feature is not supported on the device Description This function identifies whether the ChannelXBusy feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXBusyActiveSet • PLIB_DMA_ChannelXBusyInActiveSet • PLIB_DMA_ChannelXBusyIsBusy Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXBusy( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXCellProgressPointer Function Identifies whether the ChannelXCellProgressPointer feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXCellProgressPointer(DMA_MODULE_ID index); Returns • true - The ChannelXCellProgressPointer feature is supported on the device • false - The ChannelXCellProgressPointer feature is not supported on the device Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 613 Description This function identifies whether the ChannelXCellProgressPointer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXCellProgressPointerGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXCellProgressPointer( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXCellSize Function Identifies whether the ChannelXCellSize feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXCellSize(DMA_MODULE_ID index); Returns • true - The ChannelXCellSize feature is supported on the device • false - The ChannelXCellSize feature is not supported on the device Description This function identifies whether the ChannelXCellSize feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXCellSizeGet • PLIB_DMA_ChannelXCellSizeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXCellSize( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXChain Function Identifies whether the ChannelXChain feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXChain(DMA_MODULE_ID index); Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 614 Returns • true - The ChannelXChain feature is supported on the device • false - The ChannelXChain feature is not supported on the device Description This function identifies whether the ChannelXChain feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXChainToLower • PLIB_DMA_ChannelXChainToHigher Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXChain( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXChainEnbl Function Identifies whether the ChannelXChainEnbl feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXChainEnbl(DMA_MODULE_ID index); Returns • true - The ChannelXChainEnbl feature is supported on the device • false - The ChannelXChainEnbl feature is not supported on the device Description This function identifies whether the ChannelXChainEnbl feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXChainEnable • PLIB_DMA_ChannelXChainDisable • PLIB_DMA_ChannelXChainIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXChainEnbl( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXDestinationPointer Function Identifies whether the ChannelXDestinationPointer feature exists on the DMA module. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 615 File plib_dma.h C bool PLIB_DMA_ExistsChannelXDestinationPointer(DMA_MODULE_ID index); Returns • true - The ChannelXDestinationPointer feature is supported on the device • false - The ChannelXDestinationPointer feature is not supported on the device Description This function identifies whether the ChannelXDestinationPointer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXDestinationPointerGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXDestinationPointer( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXDestinationSize Function Identifies whether the ChannelXDestinationSize feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXDestinationSize(DMA_MODULE_ID index); Returns • true - The ChannelXDestinationSize feature is supported on the device • false - The ChannelXDestinationSize feature is not supported on the device Description This function identifies whether the ChannelXDestinationSize feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXDestinationSizeGet • PLIB_DMA_ChannelXDestinationSizeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXDestinationSize( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 616 PLIB_DMA_ExistsChannelXDestinationStartAddress Function Identifies whether the ChannelXDestinationStartAddress feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXDestinationStartAddress(DMA_MODULE_ID index); Returns • true - The ChannelXDestinationStartAddress feature is supported on the device • false - The ChannelXDestinationStartAddress feature is not supported on the device Description This function identifies whether the ChannelXDestinationStartAddress feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXDestinationStartAddressGet • PLIB_DMA_ChannelXDestinationStartAddressSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXDestinationStartAddress( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXDisabled Function Identifies whether the ChannelXDisabled feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXDisabled(DMA_MODULE_ID index); Returns • true - The ChannelXDisabled feature is supported on the device • false - The ChannelXDisabled feature is not supported on the device Description This function identifies whether the ChannelXDisabled feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXDisabledEnablesEvents • PLIB_DMA_ChannelXDisabledDisablesEvents Remarks None. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 617 Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXDisabled( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXEvent Function Identifies whether the ChannelXEvent feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXEvent(DMA_MODULE_ID index); Returns • true - The ChannelXEvent feature is supported on the device • false - The ChannelXEvent feature is not supported on the device Description This function identifies whether the ChannelXEvent feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXEventIsDetected Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXEvent( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXINTSource Function Identifies whether the ChannelXINTSource feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXINTSource(DMA_MODULE_ID index); Returns • true - The ChannelXINTSource feature is supported on the device • false - The ChannelXINTSource feature is not supported on the device Description This function identifies whether the ChannelXINTSource feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXINTSourceEnable • PLIB_DMA_ChannelXINTSourceDisable • PLIB_DMA_ChannelXINTSourceIsEnabled Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 618 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXINTSource( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXINTSourceFlag Function Identifies whether the ChannelXINTSourceFlag feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXINTSourceFlag(DMA_MODULE_ID index); Returns • true - The ChannelXINTSourceFlag feature is supported on the device • false - The ChannelXINTSourceFlag feature is not supported on the device Description This function identifies whether the ChannelXINTSourceFlag feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXINTSourceFlagGet • PLIB_DMA_ChannelXINTSourceFlagSet • PLIB_DMA_ChannelXINTSourceFlagClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXINTSourceFlag( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXPatternData Function Identifies whether the ChannelXPatternData feature exists on the DMA module File plib_dma.h C bool PLIB_DMA_ExistsChannelXPatternData(DMA_MODULE_ID index); Returns • true - The ChannelXPatternData feature is supported on the device • false - The ChannelXPatternData feature is not supported on the device Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 619 Description This function identifies whether the ChannelXPatternData feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPatternDataGet • PLIB_DMA_ChannelXPatternDataSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXPatternData( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXPatternIgnore Function Identifies whether the ChannelXPatternIgnore feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXPatternIgnore(DMA_MODULE_ID index); Returns • true - The ChannelXPatternIgnore feature is supported on the device • false - The ChannelXPatternIgnore feature is not supported on the device Description This function identifies whether the ChannelXPatternIgnore feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPatternIgnoreSet • PLIB_DMA_ChannelXPatternIgnoreGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXPatternIgnore( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXPatternIgnoreByte Function Identifies whether the ChannelXPatternIgnoreByte feature exists on the DMA module. File plib_dma.h Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 620 C bool PLIB_DMA_ExistsChannelXPatternIgnoreByte(DMA_MODULE_ID index); Returns • true - The ChannelXPatternIgnoreByte feature is supported on the device • false - The ChannelXPatternIgnoreByte feature is not supported on the device Description This function identifies whether the ChannelXPatternIgnoreByte feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPatternIgnoreByteEnable • PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled • PLIB_DMA_ChannelXPatternIgnoreByteDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXPatternIgnoreByte( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXPatternLength Function Identifies whether the ChannelXPatternLength feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXPatternLength(DMA_MODULE_ID index); Returns • true - The ChannelXPatternLength feature is supported on the device • false - The ChannelXPatternLength feature is not supported on the device Description This function identifies whether the ChannelXPatternLength feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPatternLengthSet • PLIB_DMA_ChannelXPatternLengthGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXPatternLength( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 621 PLIB_DMA_ExistsChannelXPriority Function Identifies whether the ChannelXPriority feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXPriority(DMA_MODULE_ID index); Returns • true - The ChannelXPriority feature is supported on the device • false - The ChannelXPriority feature is not supported on the device Description This function identifies whether the ChannelXPriority feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPrioritySelect • PLIB_DMA_ChannelXPriorityGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXPriority( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXSourcePointer Function Identifies whether the ChannelXSourcePointer feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXSourcePointer(DMA_MODULE_ID index); Returns • true - The ChannelXSourcePointer feature is supported on the device • false - The ChannelXSourcePointer feature is not supported on the device Description This function identifies whether the ChannelXSourcePointer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXSourcePointerGet Remarks None. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 622 Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXSourcePointer( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXSourceSize Function Identifies whether the ChannelXSourceSize feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXSourceSize(DMA_MODULE_ID index); Returns • true - The ChannelXSourceSize feature is supported on the device • false - The ChannelXSourceSize feature is not supported on the device Description This function identifies whether the ChannelXSourceSize feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXSourceSizeGet • PLIB_DMA_ChannelXSourceSizeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXSourceSize( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXSourceStartAddress Function Identifies whether the ChannelXSourceStartAddress feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXSourceStartAddress(DMA_MODULE_ID index); Returns • true - The ChannelXSourceStartAddress feature is supported on the device • false - The ChannelXSourceStartAddress feature is not supported on the device Description This function identifies whether the ChannelXSourceStartAddress feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXSourceStartAddressGet • PLIB_DMA_ChannelXSourceStartAddressSet Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 623 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXSourceStartAddress( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXStartIRQ Function Identifies whether the ChannelXStartIRQ feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXStartIRQ(DMA_MODULE_ID index); Returns • true - The ChannelXStartIRQ feature is supported on the device • false - The ChannelXStartIRQ feature is not supported on the device Description This function identifies whether the ChannelXStartIRQ feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXStartIRQSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXStartIRQ( DMA_MODULE_ID index ) PLIB_DMA_ExistsChannelXTrigger Function Identifies whether the ChannelXTrigger feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsChannelXTrigger(DMA_MODULE_ID index); Returns • true - The ChannelXTrigger feature is supported on the device • false - The ChannelXTrigger feature is not supported on the device Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 624 Description This function identifies whether the ChannelXTrigger feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXTriggerEnable • PLIB_DMA_ChannelXTriggerIsEnabled • PLIB_DMA_ChannelXTriggerDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsChannelXTrigger( DMA_MODULE_ID index ) PLIB_DMA_ExistsCRC Function Identifies whether the CRC feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsCRC(DMA_MODULE_ID index); Returns • true - The CRC feature is supported on the device • false - The CRC feature is not supported on the device Description This function identifies whether the CRC feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCEnable • PLIB_DMA_CRCDisable • PLIB_DMA_CRCIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRC( DMA_MODULE_ID index ) PLIB_DMA_ExistsCRCAppendMode Function Identifies whether the CRCAppendMode feature exists on the DMA module. File plib_dma.h Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 625 C bool PLIB_DMA_ExistsCRCAppendMode(DMA_MODULE_ID index); Returns • true - The CRCAppendMode feature is supported on the device • false - The CRCAppendMode feature is not supported on the device Description This function identifies whether the CRCAppendMode feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCAppendModeEnable • PLIB_DMA_CRCAppendModeDisable • PLIB_DMA_CRCAppendModeIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRCAppendMode( DMA_MODULE_ID index ) PLIB_DMA_ExistsCRCBitOrder Function Identifies whether the CRCBitOrder feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsCRCBitOrder(DMA_MODULE_ID index); Returns • true - The CRCBitOrder feature is supported on the device • false - The CRCBitOrder feature is not supported on the device Description This function identifies whether the CRCBitOrder feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_CRCBitOrderSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRCBitOrder( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 626 PLIB_DMA_ExistsCRCByteOrder Function Identifies whether the CRCByteOrder feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsCRCByteOrder(DMA_MODULE_ID index); Returns • true - The CRCByteOrder feature is supported on the device • false - The CRCByteOrder feature is not supported on the device Description This function identifies whether the CRCByteOrder feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCByteOrderSelect • PLIB_DMA_CRCByteOrderGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRCByteOrder( DMA_MODULE_ID index ) PLIB_DMA_ExistsCRCChannel Function Identifies whether the CRCChannel feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsCRCChannel(DMA_MODULE_ID index); Returns • true - The CRCChannel feature is supported on the device • false - The CRCChannel feature is not supported on the device Description This function identifies whether the CRCChannel feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCChannelSelect • PLIB_DMA_CRCChannelGet Remarks None. Preconditions None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 627 Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRCChannel( DMA_MODULE_ID index ) PLIB_DMA_ExistsCRCData Function Identifies whether the CRCData feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsCRCData(DMA_MODULE_ID index); Returns • true - The CRCData feature is supported on the device • false - The CRCData feature is not supported on the device Description This function identifies whether the CRCData feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCDataRead • PLIB_DMA_CRCDataWrite Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRCData( DMA_MODULE_ID index ) PLIB_DMA_ExistsCRCPolynomialLength Function Identifies whether the CRCPolynomialLength feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsCRCPolynomialLength(DMA_MODULE_ID index); Returns • true - The CRCPolynomialLength feature is supported on the device • false - The CRCPolynomialLength feature is not supported on the device Description This function identifies whether the CRCPolynomialLength feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCPolynomialLengthSet • PLIB_DMA_CRCPolynomialLengthGet Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 628 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRCPolynomialLength( DMA_MODULE_ID index ) PLIB_DMA_ExistsCRCType Function Identifies whether the CRCType feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsCRCType(DMA_MODULE_ID index); Returns • true - The CRCType feature is supported on the device • false - The CRCType feature is not supported on the device Description This function identifies whether the CRCType feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCTypeGet • PLIB_DMA_CRCTypeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRCType( DMA_MODULE_ID index ) PLIB_DMA_ExistsCRCWriteByteOrder Function Identifies whether the CRCWriteByteOrder feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsCRCWriteByteOrder(DMA_MODULE_ID index); Returns • true - The CRCWriteByteOrder feature is supported on the device • false - The CRCWriteByteOrder feature is not supported on the device Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 629 Description This function identifies whether the CRCWriteByteOrder feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCWriteByteOrderAlter • PLIB_DMA_CRCWriteByteOrderMaintain Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRCWriteByteOrder( DMA_MODULE_ID index ) PLIB_DMA_ExistsCRCXOREnable Function Identifies whether the CRCXOREnable feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsCRCXOREnable(DMA_MODULE_ID index); Returns • true - The CRCXOREnable feature is supported on the device • false - The CRCXOREnable feature is not supported on the device Description This function identifies whether the CRCXOREnable feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCXOREnableSet • PLIB_DMA_CRCXOREnableGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsCRCXOREnable( DMA_MODULE_ID index ) PLIB_DMA_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the DMA module. File plib_dma.h Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 630 C bool PLIB_DMA_ExistsEnableControl(DMA_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_Enable • PLIB_DMA_Disable • PLIB_DMA_IsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsEnableControl( DMA_MODULE_ID index ) PLIB_DMA_ExistsLastBusAccess Function Identifies whether the LastBusAccess feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsLastBusAccess(DMA_MODULE_ID index); Returns • true - The LastBusAccess feature is supported on the device • false - The LastBusAccess feature is not supported on the device Description This function identifies whether the LastBusAccess feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_LastBusAccessIsRead • PLIB_DMA_LastBusAccessIsWrite Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsLastBusAccess( DMA_MODULE_ID index ) Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 631 PLIB_DMA_ExistsRecentAddress Function Identifies whether the RecentAddress feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsRecentAddress(DMA_MODULE_ID index); Returns • true - The RecentAddress feature is supported on the device • false - The RecentAddress feature is not supported on the device Description This function identifies whether the RecentAddress feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_RecentAddressAccessed Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsRecentAddress( DMA_MODULE_ID index ) PLIB_DMA_ExistsStartTransfer Function Identifies whether the StartTransfer feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsStartTransfer(DMA_MODULE_ID index); Returns • true - The StartTransfer feature is supported on the device • false - The StartTransfer feature is not supported on the device Description This function identifies whether the StartTransfer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_StartTransferSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 632 Function PLIB_DMA_ExistsStartTransfer( DMA_MODULE_ID index ) PLIB_DMA_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsStopInIdle(DMA_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_StopInIdleEnable • PLIB_DMA_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsStopInIdle( DMA_MODULE_ID index ) PLIB_DMA_ExistsSuspend Function Identifies whether the Suspend feature exists on the DMA module. File plib_dma.h C bool PLIB_DMA_ExistsSuspend(DMA_MODULE_ID index); Returns • true - The Suspend feature is supported on the device • false - The Suspend feature is not supported on the device Description This function identifies whether the Suspend feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_SuspendEnable • PLIB_DMA_SuspendDisable • PLIB_DMA_SuspendIsEnabled Remarks None. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 633 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DMA_ExistsSuspend( DMA_MODULE_ID index ) m) Data Types and Constants DMA_ADDRESS_OFFSET_TYPE Enumeration Lists the possible DMA address offsets. File help_plib_dma.h C typedef enum { DMA_ADDRESS_OFFSET_PRIMARY, DMA_ADDRESS_OFFSET_SECONDARY } DMA_ADDRESS_OFFSET_TYPE; Members Members Description DMA_ADDRESS_OFFSET_PRIMARY address offset-A DMA_ADDRESS_OFFSET_SECONDARY address offset-B Description DMA address offsets This enumeration lists all the possible DMA address offsets. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_CHANNEL Enumeration Lists the possible DMA channels available. File help_plib_dma.h C typedef enum { DMA_CHANNEL_0, DMA_CHANNEL_1, DMA_CHANNEL_2, DMA_CHANNEL_3, DMA_CHANNEL_4, DMA_CHANNEL_5, DMA_CHANNEL_6, DMA_CHANNEL_7 } DMA_CHANNEL; Members Members Description DMA_CHANNEL_0 DMA Channel 0 DMA_CHANNEL_1 DMA Channel 1 Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 634 DMA_CHANNEL_2 DMA Channel 2 DMA_CHANNEL_3 DMA Channel 3 DMA_CHANNEL_4 DMA Channel 4 DMA_CHANNEL_5 DMA Channel 5 DMA_CHANNEL_6 DMA Channel 6 DMA_CHANNEL_7 DMA Channel 7 Description DMA channel This enumeration lists all the possible DMA channels available. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_CHANNEL_ADDRESSING_MODE Enumeration Lists the possible channel addressing modes. File help_plib_dma.h C typedef enum { DMA_ADDRESSING_REGISTER_INDIRECT_WITH_POST_INCREMENT, DMA_ADDRESSING_REGISTER_INDIRECT_WITHOUT_POST_INCREMENT, DMA_ADDRESSING_PERIPHERAL_INDIRECT } DMA_CHANNEL_ADDRESSING_MODE; Members Members Description DMA_ADDRESSING_REGISTER_INDIRECT_WITH_POST_INCREMENT register indirect with post increment DMA_ADDRESSING_REGISTER_INDIRECT_WITHOUT_POST_INCREMENT register indirect without post increment DMA_ADDRESSING_PERIPHERAL_INDIRECT peripheral indirect addressing Description DMA channel addressing modes This enumeration lists all the possible channel addressing modes. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_CHANNEL_COLLISION Enumeration Lists the possible channel collision types. File help_plib_dma.h C typedef enum { DMA_CHANNEL_COLLISION_MEMORY, DMA_CHANNEL_COLLISION_PERIPHERAL, DMA_CHANNEL_COLLISION_TRANSFER_REQUEST } DMA_CHANNEL_COLLISION; Members Members Description DMA_CHANNEL_COLLISION_MEMORY Memory Write Collision DMA_CHANNEL_COLLISION_PERIPHERAL Peripheral Write collision DMA_CHANNEL_COLLISION_TRANSFER_REQUEST Transfer request collision Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 635 Description DMA channel collision types This enumeration lists all the possible channel collision types. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). DMA_CHANNEL_DATA_SIZE Enumeration Lists the possible data sizes for the DMA channel. File help_plib_dma.h C typedef enum { DMA_CHANNEL_DATA_8, DMA_CHANNEL_DATA_16 } DMA_CHANNEL_DATA_SIZE; Members Members Description DMA_CHANNEL_DATA_8 8 bit data size DMA_CHANNEL_DATA_16 16 bit data size Description DMA channel data size This enumeration lists all the possible data sizes for the DMA channels. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_CHANNEL_PRIORITY Enumeration Lists the possible channel priorities. File help_plib_dma.h C typedef enum { DMA_CHANNEL_PRIORITY_0, DMA_CHANNEL_PRIORITY_1, DMA_CHANNEL_PRIORITY_2, DMA_CHANNEL_PRIORITY_3, DMA_CHANNEL_ROUND_ROBIN, DMA_CHANNEL_FIXED_PRIORITY } DMA_CHANNEL_PRIORITY; Members Members Description DMA_CHANNEL_PRIORITY_0 priority 0 DMA_CHANNEL_PRIORITY_1 priority 1 DMA_CHANNEL_PRIORITY_2 priority 2 DMA_CHANNEL_PRIORITY_3 priority 3 DMA_CHANNEL_ROUND_ROBIN round-robin scheme DMA_CHANNEL_FIXED_PRIORITY fixed priority scheme Description DMA channel priority types This enumeration lists all the possible channel priorities. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 636 Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_CHANNEL_TRANSFER_DIRECTION Enumeration Lists the possible data transfer directions. File help_plib_dma.h C typedef enum { DMA_READ_FROM_MEMORY_WRITE_TO_PERIPHERAL, DMA_READ_FROM_PERIPHERAL_WRITE_TO_MEMORY, DMA_READ_FROM_MEMORY_WRITE_TO_MEMORY, DMA_READ_FROM_PERIPHERAL_WRITE_TO_PERIPHERAL } DMA_CHANNEL_TRANSFER_DIRECTION; Members Members Description DMA_READ_FROM_MEMORY_WRITE_TO_PERIPHERAL DMA transfer happens from the memory to peripheral DMA_READ_FROM_PERIPHERAL_WRITE_TO_MEMORY DMA transfer happens from the peripheral to memory DMA_READ_FROM_MEMORY_WRITE_TO_MEMORY DMA transfer happens from the memory to memory DMA_READ_FROM_PERIPHERAL_WRITE_TO_PERIPHERAL DMA transfer happens from the peripheral to peripheral Description DMA channel data transfer direction This enumeration lists all the possible data transfer directions. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_CHANNEL_TRIGGER_TYPE Enumeration Lists the possible DMA channel triggers. File help_plib_dma.h C typedef enum { DMA_CHANNEL_TRIGGER_TRANSFER_START, DMA_CHANNEL_TRIGGER_TRANSFER_ABORT, DMA_CHANNEL_TRIGGER_PATTERN_MATCH_ABORT } DMA_CHANNEL_TRIGGER_TYPE; Members Members Description DMA_CHANNEL_TRIGGER_TRANSFER_START Trigger for DMA transfer start DMA_CHANNEL_TRIGGER_TRANSFER_ABORT Trigger for DMA transfer abort DMA_CHANNEL_TRIGGER_PATTERN_MATCH_ABORT Trigger for DMA transfer abort via pattern match Description DMA trigger types This enumeration lists all the possible DMA channel triggers. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 637 DMA_CRC_BIT_ORDER Enumeration Lists the possible CRC calculation bit orders File help_plib_dma.h C typedef enum { DMA_CRC_BIT_ORDER_LSB, DMA_CRC_BIT_ORDER_MSB } DMA_CRC_BIT_ORDER; Members Members Description DMA_CRC_BIT_ORDER_LSB CRC is calculated least significant bit first DMA_CRC_BIT_ORDER_MSB CRC is calculated most significant bit first Description DMA CRC calculation bit order This enumeration lists all the possible CRC calculation bit orders Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_CRC_BYTE_ORDER Enumeration Lists the possible byte orders. File help_plib_dma.h C typedef enum { DMA_CRC_BYTEORDER_NO_SWAPPING, DMA_CRC_SWAP_BYTE_ON_WORD_BOUNDARY, DMA_CRC_SWAP_HALF_WORD_ON_WORD_BOUNDARY, DMA_CRC_SWAP_BYTE_ON_HALF_WORD_BOUNDARY } DMA_CRC_BYTE_ORDER; Members Members Description DMA_CRC_BYTEORDER_NO_SWAPPING No swapping, Source byte order DMA_CRC_SWAP_BYTE_ON_WORD_BOUNDARY Endian byte swap on word boundaries ( reverse source byte order ) DMA_CRC_SWAP_HALF_WORD_ON_WORD_BOUNDARY Swap half-words on word boundaries ( reverse source half-word order with source byte order per half-word ) DMA_CRC_SWAP_BYTE_ON_HALF_WORD_BOUNDARY Endian byte swap on half-word boundaries ( reverse source half-word order with reverse source byte order per half-word ) Description CRC Byte order type This enumeration lists all the possible byte orders handled by CRC module. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_CRC_TYPE Enumeration Lists the possible checksums. Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 638 File help_plib_dma.h C typedef enum { DMA_CRC_IP_HEADER, DMA_CRC_LFSR } DMA_CRC_TYPE; Members Members Description DMA_CRC_IP_HEADER CRC module will calculate IP header checksum DMA_CRC_LFSR CRC module will calculate Linear Feedback Shift Registers checksum Description CRC type This enumeration lists all the possible checksums handled by CRC module. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_DESTINATION_ADDRESSING_MODE Enumeration Lists the possible destination addressing modes. File help_plib_dma.h C typedef enum { DMA_ADDRESSING_DESTINATION_UNCHANGED, DMA_ADDRESSING_DESTINATION_INCREMENT_BASED_ON_SIZE, DMA_ADDRESSING_DESTINATION_DECREMENT_BASED_ON_SIZE, DMA_ADDRESSING_DESTINATION_PERIPHERAL_INDIRECT } DMA_DESTINATION_ADDRESSING_MODE; Members Members Description DMA_ADDRESSING_DESTINATION_UNCHANGED DMADST remains unchanged after a transfer completion DMA_ADDRESSING_DESTINATION_INCREMENT_BASED_ON_SIZE DMADST is incremented based on SIZE bit after a transfer completion DMA_ADDRESSING_DESTINATION_DECREMENT_BASED_ON_SIZE DMADST is decremented based on SIZE bit after a transfer completion DMA_ADDRESSING_DESTINATION_PERIPHERAL_INDIRECT DMADST is used in peripheral indirect addressing and remains unchanged Description DMA destination addressing modes This enumeration lists all the possible destination addressing modes. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_INT_TYPE Enumeration Lists the possible Interrupt types for a particular channel-X File help_plib_dma.h C typedef enum { DMA_INT_ADDRESS_ERROR, Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 639 DMA_INT_TRANSFER_ABORT, DMA_INT_CELL_TRANSFER_COMPLETE, DMA_INT_BLOCK_TRANSFER_COMPLETE, DMA_INT_DESTINATION_HALF_FULL, DMA_INT_DESTINATION_DONE, DMA_INT_SOURCE_HALF_EMPTY, DMA_INT_SOURCE_DONE, DMA_INT_COUNT_HALF_DONE, DMA_INT_CHANNEL_OVERRUN, DMA_INT_COMPLETE, DMA_INT_LOW_ADDRESS_LIMIT, DMA_INT_HIGH_ADDRESS_LIMIT } DMA_INT_TYPE; Members Members Description DMA_INT_ADDRESS_ERROR Channel address error interrupt DMA_INT_TRANSFER_ABORT channel transfer abort interrupt DMA_INT_CELL_TRANSFER_COMPLETE channel cell transfer complete DMA_INT_BLOCK_TRANSFER_COMPLETE Channel block transfer complete DMA_INT_DESTINATION_HALF_FULL Channel destination half full interrupt DMA_INT_DESTINATION_DONE Channel destination done interrupt DMA_INT_SOURCE_HALF_EMPTY Channel source half empty interrupt DMA_INT_SOURCE_DONE Channel source done interrupt DMA_INT_COUNT_HALF_DONE DMA count has reached its halfway DMA_INT_CHANNEL_OVERRUN channel overrun. channel is triggered while it is still completing the operation based on the previous trigger DMA_INT_COMPLETE DMA complete operation interrupt DMA_INT_LOW_ADDRESS_LIMIT DMA low address limit interrupt DMA_INT_HIGH_ADDRESS_LIMIT DMA high address limit interrupt Description DMA channel X interrupt types This enumeration lists all the possible interrupt types for a channel. Not to be confused with the DMA trigger/abort interrupt sources (supported only for few parts). Remarks Not to be confused with the DMA trigger/abort interrupt sources (supported only for few parts). This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_MODULE_ID Enumeration Possible instances of the DMA module. File help_plib_dma.h C typedef enum { DMA_ID_0 } DMA_MODULE_ID; Members Members Description DMA_ID_0 first instance of the DMA Description DMA module ID This data type defines the possible instances of the DMA module. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 640 DMA_PATTERN_LENGTH Enumeration Gives the DMA pattern length File help_plib_dma.h C typedef enum { DMA_PATTERN_MATCH_LENGTH_1BYTE, DMA_PATTERN_MATCH_LENGTH_2BYTES } DMA_PATTERN_LENGTH; Members Members Description DMA_PATTERN_MATCH_LENGTH_1BYTE The Length of matching pattern with CHPIGN<7:0> in DCHxCON<31:24> is 1 BYTE DMA_PATTERN_MATCH_LENGTH_2BYTES The Length of matching pattern with CHPIGN<7:0> in DCHxCON<31:24> is 2 BYTES Description DMA pattern length This enumeration gives the length of the pattern to be matched with CHPIGN<7:0> in DCHxCON<31:24. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_PING_PONG_MODE Enumeration Lists the possible ping-pong modes. File help_plib_dma.h C typedef enum { DMA_PING_PONG_PRIMARY, DMA_PING_PONG_SECONDARY } DMA_PING_PONG_MODE; Members Members Description DMA_PING_PONG_PRIMARY DMAxSTA is selected in the ping-pong mode DMA_PING_PONG_SECONDARY DMAxSTB is selected in the ping-pong mode Description DMA PING-PONG modes This enumeration lists all the possible ping-pong modes. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_SOURCE_ADDRESSING_MODE Enumeration Lists the possible source addressing modes. File help_plib_dma.h C typedef enum { DMA_ADDRESSING_SOURCE_UNCHANGED, DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE, Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 641 DMA_ADDRESSING_SOURCE_DECREMENT_BASED_ON_SIZE, DMA_ADDRESSING_SOURCE_PERIPHERAL_INDIRECT } DMA_SOURCE_ADDRESSING_MODE; Members Members Description DMA_ADDRESSING_SOURCE_UNCHANGED DMASRC remains unchanged after a transfer completion DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE DMASRC is incremented based on SIZE bit after a transfer completion DMA_ADDRESSING_SOURCE_DECREMENT_BASED_ON_SIZE DMASRC is decremented based on SIZE bit after a transfer completion DMA_ADDRESSING_SOURCE_PERIPHERAL_INDIRECT DMASRC is used in peripheral indirect addressing and remains unchanged Description DMA source addressing modes This enumeration lists all the possible source addressing modes. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_TRANSFER_MODE Enumeration Lists the possible DMA transfer/operating modes. File help_plib_dma.h C typedef enum { DMA_MODE_ONE_SHOT, DMA_MODE_REPEATED_ONE_SHOT, DMA_MODE_CONTINUOUS, DMA_MODE_REPEATED_CONTINUOUS, DMA_MODE_ONE_SHOT_PING_PONG_ENABLED, DMA_MODE_ONE_SHOT_PING_PONG_DISABLED, DMA_MODE_CONTINUOUS_PING_PONG_DISABLED, DMA_MODE_CONTINUOUS_PING_PONG_ENABLED } DMA_TRANSFER_MODE; Members Members Description DMA_MODE_ONE_SHOT one-shot transfer DMA_MODE_REPEATED_ONE_SHOT repeated one-shot transfer DMA_MODE_CONTINUOUS continuous transfer DMA_MODE_REPEATED_CONTINUOUS repeated continuous transfer DMA_MODE_ONE_SHOT_PING_PONG_ENABLED one-shot transfer with ping-pong buffers DMA_MODE_ONE_SHOT_PING_PONG_DISABLED one-shot transfer without the ping-pong buffers DMA_MODE_CONTINUOUS_PING_PONG_DISABLED continuous transfer without the ping-pong buffers DMA_MODE_CONTINUOUS_PING_PONG_ENABLED continuous transfer with ping-pong buffers Description DMA transfer/operating mode This enumeration lists the possible DMA transfer/operating modes. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). DMA_TRIGGER_SOURCE Enumeration Lists the possible DMA trigger sources. File help_plib_dma.h Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 642 C typedef enum { DMA_TRIGGER_TIMER_CORE , DMA_TRIGGER_SOFTWARE_0 , DMA_TRIGGER_SOFTWARE_1 , DMA_TRIGGER_EXTERNAL_0 , DMA_TRIGGER_EXTERNAL_1 , DMA_TRIGGER_EXTERNAL_2 , DMA_TRIGGER_EXTERNAL_3 , DMA_TRIGGER_EXTERNAL_4 , DMA_TRIGGER_TIMER_1 , DMA_TRIGGER_TIMER_2 , DMA_TRIGGER_TIMER_3 , DMA_TRIGGER_TIMER_4 , DMA_TRIGGER_TIMER_5 , DMA_TRIGGER_INPUT_CAPTURE_1 , DMA_TRIGGER_INPUT_CAPTURE_2 , DMA_TRIGGER_INPUT_CAPTURE_3 , DMA_TRIGGER_INPUT_CAPTURE_4 , DMA_TRIGGER_INPUT_CAPTURE_5 , DMA_TRIGGER_INPUT_CAPTURE_1_ERROR , DMA_TRIGGER_INPUT_CAPTURE_2_ERROR , DMA_TRIGGER_INPUT_CAPTURE_3_ERROR , DMA_TRIGGER_INPUT_CAPTURE_4_ERROR , DMA_TRIGGER_INPUT_CAPTURE_5_ERROR , DMA_TRIGGER_OUTPUT_COMPARE_1 , DMA_TRIGGER_OUTPUT_COMPARE_2 , DMA_TRIGGER_OUTPUT_COMPARE_3 , DMA_TRIGGER_OUTPUT_COMPARE_4 , DMA_TRIGGER_OUTPUT_COMPARE_5 , DMA_TRIGGER_SPI_1_ERROR , DMA_TRIGGER_SPI_1_RECEIVE , DMA_TRIGGER_SPI_1_TRANSMIT , DMA_TRIGGER_SPI_1A_ERROR , DMA_TRIGGER_SPI_1A_RECEIVE , DMA_TRIGGER_SPI_1A_TRANSMIT , DMA_TRIGGER_SPI_2_ERROR , DMA_TRIGGER_SPI_2_RECEIVE , DMA_TRIGGER_SPI_2_TRANSMIT , DMA_TRIGGER_SPI_2A_ERROR , DMA_TRIGGER_SPI_2A_RECEIVE , DMA_TRIGGER_SPI_2A_TRANSMIT , DMA_TRIGGER_SPI_3_ERROR , DMA_TRIGGER_SPI_3_RECEIVE , DMA_TRIGGER_SPI_3_TRANSMIT , DMA_TRIGGER_SPI_3A_ERROR , DMA_TRIGGER_SPI_3A_RECEIVE , DMA_TRIGGER_SPI_3A_TRANSMIT , DMA_TRIGGER_SPI_4_ERROR , DMA_TRIGGER_SPI_4_RECEIVE , DMA_TRIGGER_SPI_4_TRANSMIT , DMA_TRIGGER_I2C_1_ERROR , DMA_TRIGGER_I2C_1_SLAVE , DMA_TRIGGER_I2C_1_MASTER , DMA_TRIGGER_I2C_1A_ERROR , DMA_TRIGGER_I2C_1A_SLAVE , DMA_TRIGGER_I2C_1A_MASTER , DMA_TRIGGER_I2C_2_ERROR , DMA_TRIGGER_I2C_2_SLAVE , DMA_TRIGGER_I2C_2_MASTER , DMA_TRIGGER_I2C_2A_ERROR , DMA_TRIGGER_I2C_2A_SLAVE , DMA_TRIGGER_I2C_2A_MASTER , DMA_TRIGGER_I2C_3_ERROR , DMA_TRIGGER_I2C_3_SLAVE , DMA_TRIGGER_I2C_3_MASTER , DMA_TRIGGER_I2C_3A_ERROR , DMA_TRIGGER_I2C_3A_SLAVE , DMA_TRIGGER_I2C_3A_MASTER , DMA_TRIGGER_I2C_4_ERROR , DMA_TRIGGER_I2C_4_SLAVE , DMA_TRIGGER_I2C_4_MASTER , DMA_TRIGGER_I2C_5_ERROR , DMA_TRIGGER_I2C_5_SLAVE , Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 643 DMA_TRIGGER_I2C_5_MASTER , DMA_TRIGGER_USART_1_ERROR , DMA_TRIGGER_USART_1_RECEIVE , DMA_TRIGGER_USART_1_TRANSMIT , DMA_TRIGGER_USART_1A_ERROR , DMA_TRIGGER_USART_1A_RECEIVE , DMA_TRIGGER_USART_1A_TRANSMIT , DMA_TRIGGER_USART_1B_ERROR , DMA_TRIGGER_USART_1B_RECEIVE , DMA_TRIGGER_USART_1B_TRANSMIT , DMA_TRIGGER_USART_2_ERROR , DMA_TRIGGER_USART_2_RECEIVE , DMA_TRIGGER_USART_2_TRANSMIT , DMA_TRIGGER_USART_2A_ERROR , DMA_TRIGGER_USART_2A_RECEIVE , DMA_TRIGGER_USART_2A_TRANSMIT , DMA_TRIGGER_USART_2B_ERROR , DMA_TRIGGER_USART_2B_RECEIVE , DMA_TRIGGER_USART_2B_TRANSMIT , DMA_TRIGGER_USART_3_ERROR , DMA_TRIGGER_USART_3_RECEIVE , DMA_TRIGGER_USART_3_TRANSMIT , DMA_TRIGGER_USART_3A_ERROR , DMA_TRIGGER_USART_3A_RECEIVE , DMA_TRIGGER_USART_3A_TRANSMIT , DMA_TRIGGER_USART_3B_ERROR , DMA_TRIGGER_USART_3B_RECEIVE , DMA_TRIGGER_USART_3B_TRANSMIT , DMA_TRIGGER_USART_4_ERROR , DMA_TRIGGER_USART_4_RECEIVE , DMA_TRIGGER_USART_4_TRANSMIT , DMA_TRIGGER_USART_5_ERROR , DMA_TRIGGER_USART_5_RECEIVE , DMA_TRIGGER_USART_5_TRANSMIT , DMA_TRIGGER_USART_6_ERROR , DMA_TRIGGER_USART_6_RECEIVE , DMA_TRIGGER_USART_6_TRANSMIT , DMA_TRIGGER_CHANGE_NOTICE , DMA_TRIGGER_CHANGE_NOTICE_A , DMA_TRIGGER_CHANGE_NOTICE_B , DMA_TRIGGER_CHANGE_NOTICE_C , DMA_TRIGGER_CHANGE_NOTICE_D , DMA_TRIGGER_CHANGE_NOTICE_E , DMA_TRIGGER_CHANGE_NOTICE_F , DMA_TRIGGER_CHANGE_NOTICE_G , DMA_TRIGGER_DMA_0 , DMA_TRIGGER_DMA_1 , DMA_TRIGGER_DMA_2 , DMA_TRIGGER_DMA_3 , DMA_TRIGGER_DMA_4 , DMA_TRIGGER_DMA_5 , DMA_TRIGGER_DMA_6 , DMA_TRIGGER_DMA_7 , DMA_TRIGGER_COMPARATOR_1 , DMA_TRIGGER_COMPARATOR_2 , DMA_TRIGGER_COMPARATOR_3 , DMA_TRIGGER_ADC_1 , DMA_TRIGGER_PARALLEL_PORT , DMA_TRIGGER_CAN_1 , DMA_TRIGGER_CAN_2 , DMA_TRIGGER_CLOCK_MONITOR , DMA_TRIGGER_RTCC , DMA_TRIGGER_FLASH_CONTROL , DMA_TRIGGER_USB_1 , DMA_TRIGGER_ETH_1 , DMA_TRIGGER_PARALLEL_PORT_ERROR , DMA_TRIGGER_CTMU } DMA_TRIGGER_SOURCE; Members Members Description DMA_TRIGGER_TIMER_CORE Core timer DMA_TRIGGER_SOFTWARE_0 Software 0 Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 644 DMA_TRIGGER_SOFTWARE_1 Software 1 DMA_TRIGGER_EXTERNAL_0 External 0 DMA_TRIGGER_EXTERNAL_1 External 1 DMA_TRIGGER_EXTERNAL_2 External 2 DMA_TRIGGER_EXTERNAL_3 External 3 DMA_TRIGGER_EXTERNAL_4 External 4 DMA_TRIGGER_TIMER_1 Timer1 DMA_TRIGGER_TIMER_2 Timer2 DMA_TRIGGER_TIMER_3 Timer3 DMA_TRIGGER_TIMER_4 Timer4 DMA_TRIGGER_TIMER_5 Timer5 DMA_TRIGGER_INPUT_CAPTURE_1 Input Capture 1 DMA_TRIGGER_INPUT_CAPTURE_2 Input Capture 2 DMA_TRIGGER_INPUT_CAPTURE_3 Input Capture 3 DMA_TRIGGER_INPUT_CAPTURE_4 Input Capture 4 DMA_TRIGGER_INPUT_CAPTURE_5 Input Capture 5 DMA_TRIGGER_INPUT_CAPTURE_1_ERROR Input Capture 1 error DMA_TRIGGER_INPUT_CAPTURE_2_ERROR Input Capture 2 error DMA_TRIGGER_INPUT_CAPTURE_3_ERROR Input Capture 3 error DMA_TRIGGER_INPUT_CAPTURE_4_ERROR Input Capture 4 error DMA_TRIGGER_INPUT_CAPTURE_5_ERROR Input Capture 5 error DMA_TRIGGER_OUTPUT_COMPARE_1 Output Compare 1 DMA_TRIGGER_OUTPUT_COMPARE_2 Output Compare 2 DMA_TRIGGER_OUTPUT_COMPARE_3 Output Compare 3 DMA_TRIGGER_OUTPUT_COMPARE_4 Output Compare 4 DMA_TRIGGER_OUTPUT_COMPARE_5 Output Compare 5 DMA_TRIGGER_SPI_1_ERROR SPI1 error DMA_TRIGGER_SPI_1_RECEIVE SPI1 receive DMA_TRIGGER_SPI_1_TRANSMIT SPI1 transmit DMA_TRIGGER_SPI_1A_ERROR SPI1A error DMA_TRIGGER_SPI_1A_RECEIVE SPI1A receive DMA_TRIGGER_SPI_1A_TRANSMIT SPI1A transmit DMA_TRIGGER_SPI_2_ERROR SPI2 error DMA_TRIGGER_SPI_2_RECEIVE SPI2 receive DMA_TRIGGER_SPI_2_TRANSMIT SPI2 transmit DMA_TRIGGER_SPI_2A_ERROR SPI2A receive DMA_TRIGGER_SPI_2A_RECEIVE SPI2A receive DMA_TRIGGER_SPI_2A_TRANSMIT SPI2A transmit DMA_TRIGGER_SPI_3_ERROR SPI3 error DMA_TRIGGER_SPI_3_RECEIVE SPI3 receive DMA_TRIGGER_SPI_3_TRANSMIT SPI3 transmit DMA_TRIGGER_SPI_3A_ERROR SPI3A receive DMA_TRIGGER_SPI_3A_RECEIVE SPI3A receive DMA_TRIGGER_SPI_3A_TRANSMIT SPI3A receive DMA_TRIGGER_SPI_4_ERROR SPI4 error DMA_TRIGGER_SPI_4_RECEIVE SPI4 receive DMA_TRIGGER_SPI_4_TRANSMIT SPI4 transmit DMA_TRIGGER_I2C_1_ERROR I2C1 error DMA_TRIGGER_I2C_1_SLAVE I2C1 slave DMA_TRIGGER_I2C_1_MASTER I2C1 master DMA_TRIGGER_I2C_1A_ERROR I2C1A error DMA_TRIGGER_I2C_1A_SLAVE I2C1A slave DMA_TRIGGER_I2C_1A_MASTER I2C1A master DMA_TRIGGER_I2C_2_ERROR I2C2 error DMA_TRIGGER_I2C_2_SLAVE I2C2 slave Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 645 DMA_TRIGGER_I2C_2_MASTER I2C2 master DMA_TRIGGER_I2C_2A_ERROR I2C2A error DMA_TRIGGER_I2C_2A_SLAVE I2C2A slave DMA_TRIGGER_I2C_2A_MASTER I2C2A master DMA_TRIGGER_I2C_3_ERROR I2C3 error DMA_TRIGGER_I2C_3_SLAVE I2C3 slave DMA_TRIGGER_I2C_3_MASTER I2C3 master DMA_TRIGGER_I2C_3A_ERROR I2C3A error DMA_TRIGGER_I2C_3A_SLAVE I2C3A slave DMA_TRIGGER_I2C_3A_MASTER I2C3A master DMA_TRIGGER_I2C_4_ERROR I2C4 error DMA_TRIGGER_I2C_4_SLAVE I2C4 slave DMA_TRIGGER_I2C_4_MASTER I2C4 master DMA_TRIGGER_I2C_5_ERROR I2C5 error DMA_TRIGGER_I2C_5_SLAVE I2C5 slave DMA_TRIGGER_I2C_5_MASTER I2C5 master DMA_TRIGGER_USART_1_ERROR USART1 error DMA_TRIGGER_USART_1_RECEIVE USART1 receive DMA_TRIGGER_USART_1_TRANSMIT USART1 transmit DMA_TRIGGER_USART_1A_ERROR USART1A error DMA_TRIGGER_USART_1A_RECEIVE USART1A receive DMA_TRIGGER_USART_1A_TRANSMIT USART1A transmit DMA_TRIGGER_USART_1B_ERROR USART1B error DMA_TRIGGER_USART_1B_RECEIVE USART1B receive DMA_TRIGGER_USART_1B_TRANSMIT USART1B transmit DMA_TRIGGER_USART_2_ERROR USART2 error DMA_TRIGGER_USART_2_RECEIVE USART2 receive DMA_TRIGGER_USART_2_TRANSMIT USART2 transmit DMA_TRIGGER_USART_2A_ERROR USART2A error DMA_TRIGGER_USART_2A_RECEIVE USART2A receive DMA_TRIGGER_USART_2A_TRANSMIT USART2A transmit DMA_TRIGGER_USART_2B_ERROR USART2B error DMA_TRIGGER_USART_2B_RECEIVE USART2B receive DMA_TRIGGER_USART_2B_TRANSMIT USART2B transmit DMA_TRIGGER_USART_3_ERROR USART3 error DMA_TRIGGER_USART_3_RECEIVE USART3 receive DMA_TRIGGER_USART_3_TRANSMIT USART3 transmit DMA_TRIGGER_USART_3A_ERROR USART3A error DMA_TRIGGER_USART_3A_RECEIVE USART3A receive DMA_TRIGGER_USART_3A_TRANSMIT USART3A transmit DMA_TRIGGER_USART_3B_ERROR USART3B error DMA_TRIGGER_USART_3B_RECEIVE USART3B receive DMA_TRIGGER_USART_3B_TRANSMIT USART3B transmit DMA_TRIGGER_USART_4_ERROR USART4 error DMA_TRIGGER_USART_4_RECEIVE USART3B receive DMA_TRIGGER_USART_4_TRANSMIT USART4 transmit DMA_TRIGGER_USART_5_ERROR USART5 error DMA_TRIGGER_USART_5_RECEIVE USART5 receive DMA_TRIGGER_USART_5_TRANSMIT USART5 transmit DMA_TRIGGER_USART_6_ERROR USART6 error DMA_TRIGGER_USART_6_RECEIVE USART6 receive DMA_TRIGGER_USART_6_TRANSMIT USART6 transmit DMA_TRIGGER_CHANGE_NOTICE Change notice DMA_TRIGGER_CHANGE_NOTICE_A Change notice A DMA_TRIGGER_CHANGE_NOTICE_B Change notice B Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 646 DMA_TRIGGER_CHANGE_NOTICE_C Change notice C DMA_TRIGGER_CHANGE_NOTICE_D Change notice D DMA_TRIGGER_CHANGE_NOTICE_E Change notice E DMA_TRIGGER_CHANGE_NOTICE_F Change notice F DMA_TRIGGER_CHANGE_NOTICE_G Change notice G DMA_TRIGGER_DMA_0 DMA Channel 0 DMA_TRIGGER_DMA_1 DMA Channel 1 DMA_TRIGGER_DMA_2 DMA Channel 2 DMA_TRIGGER_DMA_3 DMA Channel 3 DMA_TRIGGER_DMA_4 DMA Channel 4 DMA_TRIGGER_DMA_5 DMA Channel 5 DMA_TRIGGER_DMA_6 DMA Channel 6 DMA_TRIGGER_DMA_7 DMA Channel 7 DMA_TRIGGER_COMPARATOR_1 Comparator 1 DMA_TRIGGER_COMPARATOR_2 DMA Channel 2 DMA_TRIGGER_COMPARATOR_3 DMA Channel 3 DMA_TRIGGER_ADC_1 ADC1 DMA_TRIGGER_PARALLEL_PORT Parallel port DMA_TRIGGER_CAN_1 CAN1 DMA_TRIGGER_CAN_2 CAN2 DMA_TRIGGER_CLOCK_MONITOR Clock monitor DMA_TRIGGER_RTCC RTCC DMA_TRIGGER_FLASH_CONTROL Flash control DMA_TRIGGER_USB_1 USB1 DMA_TRIGGER_ETH_1 ETH1 DMA_TRIGGER_PARALLEL_PORT_ERROR Parallel port error DMA_TRIGGER_CTMU CTMU Description DMA trigger sources This enumeration lists all the possible DMA trigger sources. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). DMA_CHANNEL_INT_SOURCE Enumeration Lists the Interrupt Source number for the available DMA channels. File help_plib_dma.h C typedef enum { DMA_CHANNEL_0_INT_SOURCE, DMA_CHANNEL_1_INT_SOURCE, DMA_CHANNEL_2_INT_SOURCE, DMA_CHANNEL_3_INT_SOURCE, DMA_CHANNEL_4_INT_SOURCE, DMA_CHANNEL_5_INT_SOURCE, DMA_CHANNEL_6_INT_SOURCE, DMA_CHANNEL_7_INT_SOURCE } DMA_CHANNEL_INT_SOURCE; Members Members Description DMA_CHANNEL_0_INT_SOURCE DMA Channel 0 Interrupt Source DMA_CHANNEL_1_INT_SOURCE DMA Channel 1 Interrupt Source DMA_CHANNEL_2_INT_SOURCE DMA Channel 2 Interrupt Source Peripheral Libraries Help DMA Peripheral Library Help Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 647 DMA_CHANNEL_3_INT_SOURCE DMA Channel 3 Interrupt Source DMA_CHANNEL_4_INT_SOURCE DMA Channel 4 Interrupt Source DMA_CHANNEL_5_INT_SOURCE DMA Channel 5 Interrupt Source DMA_CHANNEL_6_INT_SOURCE DMA Channel 6 Interrupt Source DMA_CHANNEL_7_INT_SOURCE DMA Channel 7 Interrupt Source Description DMA channel Interrupt source number This enumeration lists the Interrupt Source number for all of the available DMA channels. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Files Files Name Description plib_dma.h Defines the DMA Peripheral Library interface functions. help_plib_dma.h Defines the DMA Peripheral Library data types. Description This section lists the source and header files used by the library. plib_dma.h Defines the DMA Peripheral Library interface functions. Functions Name Description PLIB_DMA_AbortTransferSet Aborts transfer on the specified channel. PLIB_DMA_BusyActiveReset Resets the BUSY bit of the DMA controller. PLIB_DMA_BusyActiveSet Sets the BUSY bit of the DMA controller. PLIB_DMA_ChannelBitsGet Returns the DMA channel bits. PLIB_DMA_ChannelPriorityGet Gets the priority scheme of the DMA channels. PLIB_DMA_ChannelPrioritySelect Sets the priority scheme of the DMA channels. PLIB_DMA_ChannelXAbortIRQSet Sets the IRQ to abort the DMA transfer on the specified channel. PLIB_DMA_ChannelXAddressModeGet Gets the channel address mode. PLIB_DMA_ChannelXAddressModeSelect Sets the channel address mode. PLIB_DMA_ChannelXAutoDisable Channel is disabled after a block transfer is complete. PLIB_DMA_ChannelXAutoEnable Channel is continuously enabled. PLIB_DMA_ChannelXAutoIsEnabled Returns the channel automatic enable status. PLIB_DMA_ChannelXBufferedDataIsWritten Returns the buffered data write status for the specified channel. PLIB_DMA_ChannelXBusyActiveSet Sets the Busy bit to active. PLIB_DMA_ChannelXBusyInActiveSet Sets the Busy bit to inactive. PLIB_DMA_ChannelXBusyIsBusy Returns the busy status of the specified channel. PLIB_DMA_ChannelXCellProgressPointerGet Returns the number of bytes transferred since the last event. PLIB_DMA_ChannelXCellSizeGet Reads the cell size (in bytes) configured for the specified channel. PLIB_DMA_ChannelXCellSizeSet Writes the specified cell size into the register corresponding to the specified channel. PLIB_DMA_ChannelXChainDisable Disables the channel chaining for the specified DMA channel. PLIB_DMA_ChannelXChainEnable Channel chain feature is enabled. PLIB_DMA_ChannelXChainIsEnabled Returns the chain status of the specified channel. PLIB_DMA_ChannelXChainToHigher Chains the specified channel to a channel higher in natural priority. PLIB_DMA_ChannelXChainToLower Chains the specified channel to a channel lower in natural priority. PLIB_DMA_ChannelXCollisionStatus Returns the status of the specified collision type for the specified channel. Peripheral Libraries Help DMA Peripheral Library Help Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 648 PLIB_DMA_ChannelXDataSizeGet Returns the current data size for the specified channel. PLIB_DMA_ChannelXDataSizeSelect Selects the data size for the specified channel. PLIB_DMA_ChannelXDestinationAddressModeGet Gets the source address mode of the specified channel. PLIB_DMA_ChannelXDestinationAddressModeSelect Sets the source address mode of the specified channel. PLIB_DMA_ChannelXDestinationPointerGet Reads the current byte of the destination being pointed to for the specified channel. PLIB_DMA_ChannelXDestinationSizeGet Reads the destination size configured for the specified channel. PLIB_DMA_ChannelXDestinationSizeSet Writes the specified destination size into the register corresponding to the specified channel. PLIB_DMA_ChannelXDestinationStartAddressGet Reads the destination start address configured for the specified channel. PLIB_DMA_ChannelXDestinationStartAddressSet Writes the specified destination start address into the register corresponding to the specified channel. PLIB_DMA_ChannelXDisable Disable the specified channel. PLIB_DMA_ChannelXDisabledDisablesEvents Channel start/abort events will be ignored even if the channel is disabled. PLIB_DMA_ChannelXDisabledEnablesEvents Channel start/abort events will be registered even if the channel is disabled. PLIB_DMA_ChannelXEnable Enable the specified channel. PLIB_DMA_ChannelXEventIsDetected Returns the event status on the specified channel. PLIB_DMA_ChannelXINTSourceDisable Disables the specified interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceEnable Enables the specified interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagClear Clears the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagGet Returns the status of the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagSet Sets the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceIsEnabled Returns the enable status of the specified interrupt source for the specified channel. PLIB_DMA_ChannelXIsEnabled Return the enable status of the specified channel. PLIB_DMA_ChannelXNullWriteModeDisable Disables the Null Write mode. PLIB_DMA_ChannelXNullWriteModeEnable Enables the Null Write mode. PLIB_DMA_ChannelXNullWriteModeIsEnabled Returns the enable status of the Null Write mode for the specified channel. PLIB_DMA_ChannelXOperatingTransferModeGet Returns the current transfer/operating mode for the specified channel. PLIB_DMA_ChannelXOperatingTransferModeSelect Selects the transfer/operating mode for the specified channel. PLIB_DMA_ChannelXPatternDataGet Returns the pattern matching (for DMA abort) data programmed for the specified channel. PLIB_DMA_ChannelXPatternDataSet Writes the specified pattern matching data (for DMA abort) into the register corresponding to the specified channel. PLIB_DMA_ChannelXPatternIgnoreByteDisable Disables the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreByteEnable Enables the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled Returns the state of the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreGet Returns the pattern match ignore value. PLIB_DMA_ChannelXPatternIgnoreSet Sets the pattern match ignore value. PLIB_DMA_ChannelXPatternLengthGet Returns the pattern match length. PLIB_DMA_ChannelXPatternLengthSet Sets the pattern match length. PLIB_DMA_ChannelXPeripheralAddressGet Gets the peripheral address configured for the specified channel. PLIB_DMA_ChannelXPeripheralAddressSet Sets the peripheral address for the specified channel. PLIB_DMA_ChannelXPingPongModeGet Returns the Ping-Pong mode status for the specified channel. PLIB_DMA_ChannelXPriorityGet Gets the priority of the specified channel. PLIB_DMA_ChannelXPrioritySelect Sets the priority of the specified channel. PLIB_DMA_ChannelXReloadDisable Disables reloading of the address and count registers. PLIB_DMA_ChannelXReloadEnable Enables reloading of the address and count registers. PLIB_DMA_ChannelXReloadIsEnabled Returns the address and count registers reload enable status. PLIB_DMA_ChannelXSourceAddressModeGet Gets the source address mode of the specified channel. PLIB_DMA_ChannelXSourceAddressModeSelect Sets the source address mode of the specified channel. PLIB_DMA_ChannelXSourcePointerGet Reads the current byte of the source being pointed to for the specified channel. PLIB_DMA_ChannelXSourceSizeGet Reads the source size configured for the specified channel. Peripheral Libraries Help DMA Peripheral Library Help Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 649 PLIB_DMA_ChannelXSourceSizeSet Writes the specified source size into the register corresponding to the specified channel. PLIB_DMA_ChannelXSourceStartAddressGet Reads the source start address configured for the specified channel. PLIB_DMA_ChannelXSourceStartAddressSet Writes the specified source start address into the register corresponding to the specified channel. PLIB_DMA_ChannelXStartAddressOffsetGet Gets the primary/secondary start address (DPSRAM) offset. PLIB_DMA_ChannelXStartAddressOffsetSet Sets the primary/secondary start address (DPSRAM) offset to the value specified depending on the offset type specified for the specified channel. PLIB_DMA_ChannelXStartIRQSet Sets the IRQ to initiate the DMA transfer on the specified channel. PLIB_DMA_ChannelXTransferCountGet Gets the DMA data transfer count that is programmed for the specified channel. PLIB_DMA_ChannelXTransferCountSet Sets the DMA data transfer count for the specified channel. PLIB_DMA_ChannelXTransferDirectionGet Returns the data transfer direction of the specified channel. PLIB_DMA_ChannelXTransferDirectionSelect Selects the data transfer direction of the specified channel. PLIB_DMA_ChannelXTriggerDisable Disables the DMA transfer abort via a matching interrupt (specified by the IRQ). PLIB_DMA_ChannelXTriggerEnable Enables the specified DMA channel trigger. PLIB_DMA_ChannelXTriggerIsEnabled Returns the enable status of the specified DMA transfer/abort trigger. PLIB_DMA_ChannelXTriggerSourceNumberGet Gets the source number for the DMA channel interrupts. PLIB_DMA_CRCAppendModeDisable Disables the CRC append mode. PLIB_DMA_CRCAppendModeEnable Enables the CRC append mode. PLIB_DMA_CRCAppendModeIsEnabled Gets the enable status of the CRC append mode. PLIB_DMA_CRCBitOrderSelect Selects the bit order for checksum calculation. PLIB_DMA_CRCByteOrderGet Gets the current byte order selected by the DMA module CRC feature. PLIB_DMA_CRCByteOrderSelect Selects the byte order. PLIB_DMA_CRCChannelGet Returns the current DMA channel to which the CRC is assigned. PLIB_DMA_CRCChannelSelect Assigns the CRC to the specified DMA channel. PLIB_DMA_CRCDataRead Reads the contents of the DMA CRC data register. PLIB_DMA_CRCDataWrite Writes the contents of the DMA CRC data register with the specified data. PLIB_DMA_CRCDisable Disables the DMA module CRC feature. PLIB_DMA_CRCEnable Enables the DMA module CRC feature. PLIB_DMA_CRCIsEnabled Gets the enable status of the CRC feature. PLIB_DMA_CRCPolynomialLengthGet Gets the current polynomial length. PLIB_DMA_CRCPolynomialLengthSet Selects the polynomial length. PLIB_DMA_CRCTypeGet Gets the current DMA module CRC feature type. PLIB_DMA_CRCTypeSet Selects the DMA module CRC feature type. PLIB_DMA_CRCWriteByteOrderAlter The source data is written to the destination reordered as defined by the BYTO<1:0> bits. PLIB_DMA_CRCWriteByteOrderMaintain The source data is written to the destination unaltered. PLIB_DMA_CRCXOREnableGet Reads the CRC XOR register. PLIB_DMA_CRCXOREnableSet Writes to the CRC XOR enable register as per the specified enable mask. PLIB_DMA_Disable DMA module is disabled. PLIB_DMA_Enable DMA module is enabled. PLIB_DMA_ExistsAbortTransfer Identifies whether the AbortTransfer feature exists on the DMA module. PLIB_DMA_ExistsBusy Identifies whether the Busy feature exists on the DMA module. PLIB_DMA_ExistsChannelBits Identifies whether the ChannelBits feature exists on the DMA module. PLIB_DMA_ExistsChannelX Identifies whether the ChannelX feature exists on the DMA module. PLIB_DMA_ExistsChannelXAbortIRQ Identifies whether the ChannelXAbortIRQ feature exists on the DMA module. PLIB_DMA_ExistsChannelXAuto Identifies whether the ChannelXAuto feature exists on the DMA module. PLIB_DMA_ExistsChannelXBusy Identifies whether the ChannelXBusy feature exists on the DMA module. PLIB_DMA_ExistsChannelXCellProgressPointer Identifies whether the ChannelXCellProgressPointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXCellSize Identifies whether the ChannelXCellSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXChain Identifies whether the ChannelXChain feature exists on the DMA module. PLIB_DMA_ExistsChannelXChainEnbl Identifies whether the ChannelXChainEnbl feature exists on the DMA module. Peripheral Libraries Help DMA Peripheral Library Help Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 650 PLIB_DMA_ExistsChannelXDestinationPointer Identifies whether the ChannelXDestinationPointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationSize Identifies whether the ChannelXDestinationSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationStartAddress Identifies whether the ChannelXDestinationStartAddress feature exists on the DMA module. PLIB_DMA_ExistsChannelXDisabled Identifies whether the ChannelXDisabled feature exists on the DMA module. PLIB_DMA_ExistsChannelXEvent Identifies whether the ChannelXEvent feature exists on the DMA module. PLIB_DMA_ExistsChannelXINTSource Identifies whether the ChannelXINTSource feature exists on the DMA module. PLIB_DMA_ExistsChannelXINTSourceFlag Identifies whether the ChannelXINTSourceFlag feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternData Identifies whether the ChannelXPatternData feature exists on the DMA module PLIB_DMA_ExistsChannelXPatternIgnore Identifies whether the ChannelXPatternIgnore feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternIgnoreByte Identifies whether the ChannelXPatternIgnoreByte feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternLength Identifies whether the ChannelXPatternLength feature exists on the DMA module. PLIB_DMA_ExistsChannelXPriority Identifies whether the ChannelXPriority feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourcePointer Identifies whether the ChannelXSourcePointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourceSize Identifies whether the ChannelXSourceSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourceStartAddress Identifies whether the ChannelXSourceStartAddress feature exists on the DMA module. PLIB_DMA_ExistsChannelXStartIRQ Identifies whether the ChannelXStartIRQ feature exists on the DMA module. PLIB_DMA_ExistsChannelXTrigger Identifies whether the ChannelXTrigger feature exists on the DMA module. PLIB_DMA_ExistsCRC Identifies whether the CRC feature exists on the DMA module. PLIB_DMA_ExistsCRCAppendMode Identifies whether the CRCAppendMode feature exists on the DMA module. PLIB_DMA_ExistsCRCBitOrder Identifies whether the CRCBitOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCByteOrder Identifies whether the CRCByteOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCChannel Identifies whether the CRCChannel feature exists on the DMA module. PLIB_DMA_ExistsCRCData Identifies whether the CRCData feature exists on the DMA module. PLIB_DMA_ExistsCRCPolynomialLength Identifies whether the CRCPolynomialLength feature exists on the DMA module. PLIB_DMA_ExistsCRCType Identifies whether the CRCType feature exists on the DMA module. PLIB_DMA_ExistsCRCWriteByteOrder Identifies whether the CRCWriteByteOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCXOREnable Identifies whether the CRCXOREnable feature exists on the DMA module. PLIB_DMA_ExistsEnableControl Identifies whether the EnableControl feature exists on the DMA module. PLIB_DMA_ExistsLastBusAccess Identifies whether the LastBusAccess feature exists on the DMA module. PLIB_DMA_ExistsRecentAddress Identifies whether the RecentAddress feature exists on the DMA module. PLIB_DMA_ExistsStartTransfer Identifies whether the StartTransfer feature exists on the DMA module. PLIB_DMA_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the DMA module. PLIB_DMA_ExistsSuspend Identifies whether the Suspend feature exists on the DMA module. PLIB_DMA_IsBusy Gets the BUSY bit of the DMA controller. PLIB_DMA_IsEnabled Returns the DMA module enable status. PLIB_DMA_LastBusAccessIsRead Returns true if the last DMA bus access was a read. PLIB_DMA_LastBusAccessIsWrite Returns true if the last DMA bus access was a write. PLIB_DMA_RecentAddressAccessed Returns the address of the most recent DMA access. PLIB_DMA_StartTransferSet Initiates transfer on the specified channel. PLIB_DMA_StopInIdleDisable DMA transfers continue during Idle mode. PLIB_DMA_StopInIdleEnable DMA transfers are halted during Idle mode. PLIB_DMA_SuspendDisable DMA suspend is disabled and the DMA module operates normally. PLIB_DMA_SuspendEnable DMA transfers are suspended to allow uninterrupted access by the CPU to the data bus. PLIB_DMA_SuspendIsEnabled Returns the DMA suspend status. Peripheral Libraries Help DMA Peripheral Library Help Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 651 Description DMA Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Direct Memory Access (DMA) Peripheral Library for Microchip microcontrollers. The definitions in this file are for the DMA module. File Name plib_dma.h Company Microchip Technology Inc. help_plib_dma.h Defines the DMA Peripheral Library data types. Enumerations Name Description DMA_ADDRESS_OFFSET_TYPE Lists the possible DMA address offsets. DMA_CHANNEL Lists the possible DMA channels available. DMA_CHANNEL_ADDRESSING_MODE Lists the possible channel addressing modes. DMA_CHANNEL_COLLISION Lists the possible channel collision types. DMA_CHANNEL_DATA_SIZE Lists the possible data sizes for the DMA channel. DMA_CHANNEL_INT_SOURCE Lists the Interrupt Source number for the available DMA channels. DMA_CHANNEL_PRIORITY Lists the possible channel priorities. DMA_CHANNEL_TRANSFER_DIRECTION Lists the possible data transfer directions. DMA_CHANNEL_TRIGGER_TYPE Lists the possible DMA channel triggers. DMA_CRC_BIT_ORDER Lists the possible CRC calculation bit orders DMA_CRC_BYTE_ORDER Lists the possible byte orders. DMA_CRC_TYPE Lists the possible checksums. DMA_DESTINATION_ADDRESSING_MODE Lists the possible destination addressing modes. DMA_INT_TYPE Lists the possible Interrupt types for a particular channel-X DMA_MODULE_ID Possible instances of the DMA module. DMA_PATTERN_LENGTH Gives the DMA pattern length DMA_PING_PONG_MODE Lists the possible ping-pong modes. DMA_SOURCE_ADDRESSING_MODE Lists the possible source addressing modes. DMA_TRANSFER_MODE Lists the possible DMA transfer/operating modes. DMA_TRIGGER_SOURCE Lists the possible DMA trigger sources. Description DMA Peripheral Library data types. This header file contains data types and constants that make up the Interface to the direct memory access(DMA) peripheral library (PLIB) for Microchip microcontrollers. The definitions in this file are for DMA module. File Name help_plib_dma.h Company Microchip Technology Inc. Peripheral Libraries Help DMA Peripheral Library Help Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 652 Dual Data Rate (DDR) SDRAM Peripheral Library This topic describes the Dual Data Rate (DDR) SDRAM Peripheral Library. Introduction This library provides a low-level abstraction of the DDR SDRAM Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by abstracting differences from one microcontroller variant to another. Description The DDR SDRAM controller and associated physical interface (PHY) provide access to external SDRAM from the CPU and other targets within the device. The specific targets may vary between devices, but typically include graphics controller(s), DMA, and other peripherals. External DRAM expands the volatile memory available for the device, and is useful for operating systems, graphics controllers/accelerators, and other operations requiring large amounts of memory. The SDRAM and controller must be initialized before the SDRAM can be accessed. The initialization is specific to the timing constraints and addressing of the particular SDRAM in use, as well as the clocks to the controller and PHY. This library provides functions for initializing the controller, PHY, and external SDRAM. Using the Library This topic describes the basic architecture of the DDR SDRAM Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_ddr.h The interface to the DDR SDRAM Peripheral Library is defined in the plib_ddr.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the DDR SDRAM Peripheral Library must include peripheral.h. Library File: The DDR SDRAM Peripheral Library archive (.a) file is installed with MPLAB Harmony. Please refer to the Understanding MPLAB Harmony section for how the library interacts with the framework. Abstraction Model This library provides the low-level abstraction of the Dual Data Rate (DDR) SDRAM module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description The DDR SDRAM controller and PHY must be initialized prior to accessing SDRAM. The SDRAM itself must also be initialized. This library provides interface routines to perform these initializations. DDR SDRAM Peripheral Library Software Abstraction Block Diagram Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 653 Library Overview The library interface routines are divided into various subsections, each of the sub-sections addresses one of the blocks or the overall operation of the DDR SDRAM module. Library Interface Section Description General Configuration Functions The SDRAM controller must be configured for the system and device in use. General configuration options include DRAM type, operation mode and On-Die-Termination (ODT) settings. Target Arbitration Functions Arbitration parameters for each target can be programmed individually. The arbitration parameters determine the relative bandwidth assigned to each target. Adjusting target arbitration parameters can improve overall system performance by maximizing bandwidth utilization among targets. SDRAM Addressing Functions DDR SDRAM is addressed in terms of banks, rows and columns. The CPU address space is translated to SDRAM addresses by the controller. The addressing parameters are determined by the size and geometry of the SDRAM, and must be initialized in the controller to access the SDRAM correctly. SDRAM Timing Functions To operate correctly, timing delays must be inserted for various SDRAM operations. The timing delays are device-specific, and are specified in the SDRAM data sheet. These delays are used to initialize the controller for correct operation. SDRAM Initialization Functions The SDRAM must be initialized prior to use. Initialization consists of writing system-specific values to registers within the SDRAM itself, using the Host Command Interface. The registers and initialization sequence are standardized across SDRAM devices. PHY Initialization Functions Like the SDRAM controller, the PHY must be initialized prior to use. PHY parameters include ODT and drive-strength settings, DLL settings, and Self-Calibration-Logic (SCL) settings. Feature Existence Functions Interface routines that can be used to determine whether or not the feature is supported by the device. How the Library Works This section provides information on how the DDR SDRAM Peripheral Library works. Description General Configuration General configuration of the SDRAM controller includes the following: Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 654 • On-Die-Termination (ODT) settings for data reads and writes • Endianness • DDR type (DDR2 or DDR3) • Rate mode (full or half) Target Arbitration Initializing the arbitration parameters for each target is a two-step procedure. First, the minimum number of uninterrupted bursts (without interference from another target) is programmed, using the PLIB_DDR_MinLimit function. Then the number of bursts within a specific time-out period is set using the PLIB_DDR_ReqPeriod and PLIB_DDR_MinCommand functions. The relative time-outs and number of bursts between targets determine the total bandwidth allocation. For details, refer to the "DDR SDRAM" chapter in the specific device data sheet and Section 55. "DDR2 SDRAM Controller" (DS60001321) in the "PIC32 Family Reference Manual". SDRAM Addressing The address used by the CPU to access the SDRAM must be converted into a format understood by the SDRAM. The SDRAM uses bank, row, column and chip select bits to access data within the memory. The SDRAM addressing functions use shift and mask operations to translate the CPU address into bank, row, column and chip-select. There are four addressing functions, one each for bank, row, column and chip select. Each function takes mask and shift arguments. The mask parameter determines the number of bits that make up the address component, and the shift parameter determines where in the 32-bit CPU address the component is located. Refer to the DDR SDRAM Family Reference Manual for more details and examples. PHY Initialization The PHY controls the physical interface from the PIC32 to SDRAM. ODT is provided by the pads, and can be enabled or disabled using the PHY initialization functions. Setting ODT correctly for the platform can improve signal integrity by minimizing signal reflection. Enabling/disabling ODT and setting the impedance is done using the following functions: • PLIB_DDR_PHY_OdtEnable • PLIB_DDR_PHY_OdtDisable Similarly, the pad drive strength can be set using the PLIB_DDR_PHY_DriveStrengthSet function. Fine tuning of the ODT impedance and drive strength can be performed using the calibration functions PLIB_DDR_PHY_OdtCal and PLIB_DDR_PHY_DrvStrgthCal. The SDRAM PHY contains Self-Calibration-Logic (SCL) that is run automatically during initialization. Various SCL parameters can be set using the following functions: • PLIB_DDR_PHY_SCLEnable - enables SCL for a specific Chip Select • PLIB_DDR_PHY_ReadCASLatencySet - sets the read CAS latency during SCL • PLIB_DDR_PHY_WriteCASLatencySet - sets the write CAS latency during SCL • PLIB_DDR_PHY_OdtCSEnable - enables ODT on Chip Select during SCL • PLIB_DDR_PHY_SCLDelay - sets the SCL delay SDRAM Timing Several timing parameters must be initialized for the SDRAM interface to operate correctly. These include: • Refresh interval and delay • Read and write delays • Precharge delays • Addressing delays • Bank activate delays Timing parameters for specific SDRAMs are provided in the SDRAM data sheet. These are passed to the SDRAM timing initialization functions along with the controller clock period. The initialization functions then calculate the delays and set the controller timing registers to the correct values. Refer to Section 55. "DDR2 SDRAM Controller" (DS60001321)in the "PIC32 Family Reference Manual" for details. SDRAM Initialization The SDRAM is initialized by writing a series of commands to internal registers of the SDRAM itself. The register command interface is encoded on the control and address lines to the SDRAM. The SDRAM controller includes a series of registers that are initialized and transmitted to the SDRAM using the SDRAM initialization functions. The sequence is as follows: 1. Write the initialization words to the host command registers using the PLIB_DDR_CmdDataWrite function. 2. Set the number of commands with the PLIB_DDR_NumHostCmdsSet function. 3. Write the commands to the SDRAM using PLIB_DDR_CmdDataSend. 4. Wait for the SDRAM to acknowledge valid initialization using PLIB_DDR_CmdDataIsComplete. 5. Enable the SDRAM for normal operation with the PLIB_DDR_ControllerEnable function. The initialization command sequence is specified in the data sheet of the SDRAM device. An example initialization sequence is provided in Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 655 Section 55. "DDR2 SDRAM Controller" (DS60001321) of the "PIC32 Family Reference Manual". Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB X IDE. Library Interface a) General Configuration Functions Name Description PLIB_DDR_BigEndianSet Sets the DDR data endianness to big. PLIB_DDR_FullRateSet Sets the DDR controller to Full-rate mode. PLIB_DDR_HalfRateSet Sets the DDR controller to Half-rate mode. PLIB_DDR_LittleEndianSet Sets the DDR data endianness to little. PLIB_DDR_MaxPendingRefSet Initializes the DDR controller refresh configuration. PLIB_DDR_OdtReadDisable Selects which Chip Select to disable ODT for data reads. PLIB_DDR_OdtReadEnable Selects which Chip Select to enable ODT for data reads. PLIB_DDR_OdtWriteDisable Selects which Chip Select to disable ODT for data writes. PLIB_DDR_OdtWriteEnable Selects which Chip Select to enable ODT for data writes. PLIB_DDR_AutoPchrgDisable Prevents the DDR controller from issuing an auto-precharge command to close the bank at the end of every user command. PLIB_DDR_AutoPowerDownDisable Prevents the DDR controller from automatically entering Power-down mode. PLIB_DDR_AutoPchrgPowerDownDisable Prevents the DDR controller from automatically entering Precharge Power-down mode. PLIB_DDR_AutoSelfRefreshDisable Prevents the DDR controller from automatically entering Self-refresh mode. PLIB_DDR_AutoPchrgPowerDownEnable Enables the DDR controller to automatically enter Precharge Power-down mode. PLIB_DDR_AutoPowerDownEnable Enables the DDR controller to automatically enter Power-down mode. PLIB_DDR_AutoSelfRefreshEnable Enables the DDR controller to automatically enter Self-refresh mode. PLIB_DDR_AutoPchrgEnable Enables the DDR controller to issue an auto-precharge command to close the bank at the end of every user command. PLIB_DDR_TfawDelaySet Initializes the DDR controller with the four-bank activation window needed for the specific DDR in use. b) Target Arbitration Functions Name Description PLIB_DDR_MinCommand Sets the minimum number of bursts to be serviced for a DDR target within (REQPER * 4) number of clocks. PLIB_DDR_MinLimit Sets the minimum number of bursts for a DDR target. PLIB_DDR_ReqPeriod Sets the timeout for MINCMD number of bursts to be serviced for a DDR target. c) SDRAM Initialization Functions Name Description PLIB_DDR_CmdDataIsComplete Returns the value of the valid bit in the DDR2CMDISSUE register. This bit is cleared by hardware, when the SDRAM initialization data has been transmitted. PLIB_DDR_CmdDataSend Transmits the data in the command registers to the SDRAM. PLIB_DDR_CmdDataValid Indicates to the controller that the data in the command registers is valid. PLIB_DDR_ControllerEnable Enables the controller for normal operations after SDRAM is initialized. PLIB_DDR_MaxCmdBrstCntSet Sets the maximum number of commands that can be written to the controller in Burst mode. PLIB_DDR_NumHostCmdsSet Sets the number of commands to be transmitted to the SDRAM. PLIB_DDR_CmdDataWrite Writes an SDRAM command word to a command register in the controller. d) SDRAM Addressing Functions Name Description PLIB_DDR_BankAddressSet Initializes the DDR controller memory configuration registers for bank address. PLIB_DDR_ChipSelectAddressSet Initializes the DDR controller memory configuration registers for Chip Select address. PLIB_DDR_ColumnAddressSet Initializes the DDR controller memory configuration registers for the column address. PLIB_DDR_RowAddressSet Initializes the DDR controller memory configuration registers for row address. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 656 e) SDRAM Timing Functions Name Description PLIB_DDR_OdtReadParamSet Sets the ODT parameters for data reads. PLIB_DDR_OdtWriteParamSet Sets the ODT parameters for data writes. PLIB_DDR_DataDelaySet Initializes the DDR controller with the data delays needed for the specific DDR in use. PLIB_DDR_PowerDownDelaySet Initializes the DDR controller with the power down delays needed for the specific DDR in use. PLIB_DDR_SelfRefreshDelaySet Initializes the DDR controller with the self-refresh delays needed for the specific DDR in use. PLIB_DDR_PrechargAllBanksSet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_ReadWriteDelaySet Initializes the DDR controller with the read/write delays needed for the specific DDR in use. PLIB_DDR_RefreshTimingSet Initializes the DDR controller refresh configuration. PLIB_DDR_WriteWriteDelaySet Initializes the DDR controller with the read/write delays needed for the specific DDR in use. PLIB_DDR_PrechargeToRASDelaySet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_RASToCASDelaySet Initializes the DDR controller with the row/column address delays needed for the specific DDR in use. PLIB_DDR_RASToPrechargeDelaySet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_RASToRASBankDelaySet Initializes the DDR controller with the row/column address delays needed for the specific DDR in use. PLIB_DDR_RASToRASDelaySet Initializes the DDR controller with the row/column address delays needed for the specific DDR in use. PLIB_DDR_ReadToPrechargeDelaySet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_WriteToPrechargeDelaySet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_ReadReadDelaySet Initializes the DDR controller with the read/write delays needed for the specific DDR in use. PLIB_DDR_WriteReadDelaySet Initializes the DDR controller with the read/write delays needed for the specific DDR in use. f) PHY Initialization Functions Name Description PLIB_DDR_PHY_DDRTypeSet Sets the DRAM type for the PHY. PLIB_DDR_PHY_DllMasterDelayStartSet Sets the start value of the digital DLL master delay line. PLIB_DDR_PHY_DllRecalibDisable Disables periodic recalibration of the internal digital DLL. PLIB_DDR_PHY_DllRecalibEnable Enables periodic recalibration of the internal digital DLL, and sets the recalibration period. PLIB_DDR_PHY_DriveStrengthSet Disables On Die Termination. PLIB_DDR_PHY_DrvStrgthCal Calibrates the pad NFET and PFET output impedance. PLIB_DDR_PHY_ExternalDllEnable Enables the use of an external DLL. PLIB_DDR_PHY_ExtraClockDisable Does not enable the drive pad for an extra clock cycle after a write burst. PLIB_DDR_PHY_ExtraClockEnable Enables the drive pad for an extra clock cycle after a write burst. PLIB_DDR_PHY_InternalDllEnable Enables the use of the internal digital DLL. PLIB_DDR_PHY_OdtCal Calibrates the pull-up and pull-down ODT impedance. PLIB_DDR_PHY_OdtCSDisable Disables ODT on Chip Select while running SCL test. PLIB_DDR_PHY_OdtCSEnable Enables ODT on Chip Select while running SCL test. PLIB_DDR_PHY_OdtDisable Disables On Die Termination. PLIB_DDR_PHY_OdtEnable Enables On Die Termination and sets the value. PLIB_DDR_PHY_PadReceiveEnable Enables pad receivers on bidirectional I/O. PLIB_DDR_PHY_PreambleDlySet Sets the length of the preamble for data writes. PLIB_DDR_PHY_ReadCASLatencySet Sets the read CAS latency while running SCL test. PLIB_DDR_PHY_SCLDelay Disables ODT on Chip Select while running SCL test. PLIB_DDR_PHY_SCLEnable Enables SCL on the Chip Select 'cs'. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 657 PLIB_DDR_PHY_SCLTestBurstModeSet Sets the burst mode of the DRAM while running SCL test. PLIB_DDR_PHY_WriteCASLatencySet Sets the write CAS latency while running SCL test. PLIB_DDR_PHY_PadReceiveDisable Disables pad receivers on bidirectional I/O. PLIB_DDR_PHY_SCLCapClkDelaySet Sets capture clock delay during SCL. PLIB_DDR_PHY_SCLDDRClkDelaySet Sets DDR clock delay during SCL. PLIB_DDR_PHY_HalfRateSet Sets the PHY to half rate mode. PLIB_DDR_PHY_SCLStart Runs PHY Self Calibration. PLIB_DDR_PHY_SCLStatus Checks status of PHY Self Calibration. PLIB_DDR_PHY_AddCtlDriveStrengthSet Sets the drive strength for the PHY address and control pads. PLIB_DDR_PHY_DataDriveStrengthSet Sets the drive strength for the PHY data pads. PLIB_DDR_PHY_WriteCmdDelayDisable Disables write command delay. PLIB_DDR_PHY_WriteCmdDelayEnable Enables write command delay. The extra delay is needed for devices with even write latency (WL). g) Feature Existence Functions Name Description PLIB_DDR_ExistsAddressMapping Identifies whether the AddressMapping feature exists on the DDR module. PLIB_DDR_ExistsArbitrationControl Identifies whether the ArbitrationControl feature exists on the DDR module. PLIB_DDR_ExistsAutoPowerDown Identifies whether the AutoPowerDown feature exists on the DDR module. PLIB_DDR_ExistsAutoPrecharge Identifies whether the AutoPrecharge feature exists on the DDR module. PLIB_DDR_ExistsAutoSelfRefresh Identifies whether the AutoSelfRefresh feature exists on the DDR module. PLIB_DDR_ExistsDDRCommands Identifies whether the DDRCommands feature exists on the DDR module. PLIB_DDR_ExistsDDRControllerConfig Identifies whether the DDRControllerConfig feature exists on the DDR module. PLIB_DDR_ExistsODTConfig Identifies whether the ODTConfig feature exists on the DDR module. PLIB_DDR_ExistsPHY_DLLCalibration Identifies whether the PHY_DLLCalibration feature exists on the DDR module. PLIB_DDR_ExistsPHY_PadConfig Identifies whether the PHY_PadConfig feature exists on the DDR module. PLIB_DDR_ExistsPHY_SCLConfig Identifies whether the PHY_SCLConfig feature exists on the DDR module PLIB_DDR_ExistsRefreshConfig Identifies whether the RefreshConfig feature exists on the DDR module. PLIB_DDR_ExistsTimingDelays Identifies whether the TimingDelays feature exists on the DDR module h) Data Types and Constants Name Description DDR_CMD_IDLE_NOP DDR_PHY_DDR_TYPE Defines the DDR type. DDR_CMD_LOAD_MODE This is macro DDR_CMD_LOAD_MODE. DDR_PHY_DRIVE_STRENGTH Defines the PHY Pad drive strength value. DDR_CMD_PRECHARGE_ALL This is macro DDR_CMD_PRECHARGE_ALL. DDR_PHY_ODT Defines the ODT termination value. DDR_CMD_REFRESH This is macro DDR_CMD_REFRESH. DDR_PHY_PREAMBLE_DLY Defines the PHY preamble delay value. DDR_PHY_SCL_BURST_MODE Defines the burst mode for SCL. DDR_PHY_SCL_DELAY Defines the SCL delay. DDR_HOST_CMD_REG Defines the DDR host command register. DDR_MODULE_ID Enumeration: DDR_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. DDR_TARGET Defines the different targets to which the DDR controller is connected. Description This section describes the Application Programming Interface (API) functions of the DDR SDRAM Peripheral Library. Refer to each section for a detailed description. a) General Configuration Functions Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 658 PLIB_DDR_BigEndianSet Function Sets the DDR data endianness to big. File plib_ddr.h C void PLIB_DDR_BigEndianSet(DDR_MODULE_ID index); Returns None. Description This function sets the DDR data endianness to big. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_BigEndianSet(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_BigEndianSet( DDR_MODULE_ID index); PLIB_DDR_FullRateSet Function Sets the DDR controller to Full-rate mode. File plib_ddr.h C void PLIB_DDR_FullRateSet(DDR_MODULE_ID index); Returns None. Description This function sets the DDR controller to Full-rate mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_FullRateSet(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 659 Function void PLIB_DDR_FullRateSet( DDR_MODULE_ID index); PLIB_DDR_HalfRateSet Function Sets the DDR controller to Half-rate mode. File plib_ddr.h C void PLIB_DDR_HalfRateSet(DDR_MODULE_ID index); Returns None. Description This function sets the DDR controller to Half-rate mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_HalfRateSet(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_HalfRateSet( DDR_MODULE_ID index); PLIB_DDR_LittleEndianSet Function Sets the DDR data endianness to little. File plib_ddr.h C void PLIB_DDR_LittleEndianSet(DDR_MODULE_ID index); Returns None. Description This function sets the DDR data endianness to little. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_LittleEndianSet(DDR_ID_0); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 660 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_LittleEndianSet( DDR_MODULE_ID index); PLIB_DDR_MaxPendingRefSet Function Initializes the DDR controller refresh configuration. File plib_ddr.h C void PLIB_DDR_MaxPendingRefSet(DDR_MODULE_ID index, uint8_t maxRefs); Returns None. Description This function initializes the DDR controller refresh configuration and programs the number of refreshes that may be pending at one time. The following register field is programmed with this function: • MAXREFS<4:0> - DDRREFCFG<24:26> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define MAX_PEND_REF 7 PLIB_DDR_MaxPendingRefSet(DDR_ID_0, MAX_PEND_REF); Parameters Parameters Description index Identifier for the device instance to be configured maxRefs Maximum number of refreshes that may be pending at one time Function void PLIB_DDR_MaxPendingRefSet( DDR_MODULE_ID index, uint8_t maxRefs); PLIB_DDR_OdtReadDisable Function Selects which Chip Select to disable ODT for data reads. File plib_ddr.h C void PLIB_DDR_OdtReadDisable(DDR_MODULE_ID index, uint8_t odtCS); Returns None. Description This function selects which Chip Select to disable ODT for data reads. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 661 Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_OdtReadDisable(DDR_ID_0, 0); Parameters Parameters Description index Identifier for the device instance to be configured odtCS Chip select to program ODT control value Function void PLIB_DDR_OdtReadDisable( DDR_MODULE_ID index, uint8_t odtCS); PLIB_DDR_OdtReadEnable Function Selects which Chip Select to enable ODT for data reads. File plib_ddr.h C void PLIB_DDR_OdtReadEnable(DDR_MODULE_ID index, uint8_t odtCS); Returns None. Description This function selects which Chip Select to enable ODT for data reads. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_OdtReadEnable(DDR_ID_0, 0); Parameters Parameters Description index Identifier for the device instance to be configured odtCS Chip select to program ODT control value Function void PLIB_DDR_OdtReadEnable( DDR_MODULE_ID index, uint8_t odtCS); PLIB_DDR_OdtWriteDisable Function Selects which Chip Select to disable ODT for data writes. File plib_ddr.h C void PLIB_DDR_OdtWriteDisable(DDR_MODULE_ID index, uint8_t odtCS); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 662 Returns None. Description This function selects which Chip Select to disable ODT for data writes. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_OdtWriteDisable(DDR_ID_0, 0); Parameters Parameters Description index Identifier for the device instance to be configured odtCS Chip select to program ODT control value Function void PLIB_DDR_OdtWriteDisable( DDR_MODULE_ID index, uint8_t odtCS); PLIB_DDR_OdtWriteEnable Function Selects which Chip Select to enable ODT for data writes. File plib_ddr.h C void PLIB_DDR_OdtWriteEnable(DDR_MODULE_ID index, uint8_t odtCS); Returns None. Description This function selects which Chip Select to enable ODT for data writes. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_OdtWriteEnable(DDR_ID_0, 0); Parameters Parameters Description index Identifier for the device instance to be configured odtCS Chip select to program ODT control value Function void PLIB_DDR_OdtWriteEnable( DDR_MODULE_ID index, uint8_t odtCS); PLIB_DDR_AutoPchrgDisable Function Prevents the DDR controller from issuing an auto-precharge command to close the bank at the end of every user command. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 663 File plib_ddr.h C void PLIB_DDR_AutoPchrgDisable(DDR_MODULE_ID index); Returns None. Description This function prevents the DDR controller from issuing a auto-precharge command to close the bank at the end of every user command. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_AutoPchrgDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_AutoPchrgDisable( DDR_MODULE_ID index); PLIB_DDR_AutoPowerDownDisable Function Prevents the DDR controller from automatically entering Power-down mode. File plib_ddr.h C void PLIB_DDR_AutoPowerDownDisable(DDR_MODULE_ID index); Returns None. Description This function prevents the DDR controller from automatically entering Power-down mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_AutoPowerDownDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_AutoPowerDownDisable( DDR_MODULE_ID index); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 664 PLIB_DDR_AutoPchrgPowerDownDisable Function Prevents the DDR controller from automatically entering Precharge Power-down mode. File plib_ddr.h C void PLIB_DDR_AutoPchrgPowerDownDisable(DDR_MODULE_ID index); Returns None. Description This function prevents the DDR controller from automatically entering Precharge Power-down mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_AutoPchrgPowerDownDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_AutoPchrgPowerDownDisable( DDR_MODULE_ID index); PLIB_DDR_AutoSelfRefreshDisable Function Prevents the DDR controller from automatically entering Self-refresh mode. File plib_ddr.h C void PLIB_DDR_AutoSelfRefreshDisable(DDR_MODULE_ID index); Returns None. Description This function prevents the DDR controller from automatically entering Self-refresh mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_AutoSelfRefreshDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 665 Function void PLIB_DDR_AutoSelfRefreshDisable( DDR_MODULE_ID index); PLIB_DDR_AutoPchrgPowerDownEnable Function Enables the DDR controller to automatically enter Precharge Power-down mode. File plib_ddr.h C void PLIB_DDR_AutoPchrgPowerDownEnable(DDR_MODULE_ID index); Returns None. Description This function enables the DDR controller to automatically enter Precharge Power-down mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_AutoPchrgPowerDownEnable(DDR_ID_0); I Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_AutoPchrgPowerDownEnable( DDR_MODULE_ID index); PLIB_DDR_AutoPowerDownEnable Function Enables the DDR controller to automatically enter Power-down mode. File plib_ddr.h C void PLIB_DDR_AutoPowerDownEnable(DDR_MODULE_ID index); Returns None. Description This function enables the DDR controller to automatically enter Power-down mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_AutoPowerDownEnable(DDR_ID_0, pdd); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 666 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_AutoPowerDownEnable( DDR_MODULE_ID index); PLIB_DDR_AutoSelfRefreshEnable Function Enables the DDR controller to automatically enter Self-refresh mode. File plib_ddr.h C void PLIB_DDR_AutoSelfRefreshEnable(DDR_MODULE_ID index); Returns None. Description This function enables the DDR controller to automatically enter Self-refresh mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_AutoSelfRefreshEnable(DDR_ID_0, srd); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_AutoSelfRefreshEnable( DDR_MODULE_ID index); PLIB_DDR_AutoPchrgEnable Function Enables the DDR controller to issue an auto-precharge command to close the bank at the end of every user command. File plib_ddr.h C void PLIB_DDR_AutoPchrgEnable(DDR_MODULE_ID index); Returns None. Description This function enables the DDR controller to issue a auto-precharge command to close the bank at the end of every user command. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 667 Example PLIB_DDR_AutoPchrgEnable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_AutoPchrgEnable( DDR_MODULE_ID index); PLIB_DDR_TfawDelaySet Function Initializes the DDR controller with the four-bank activation window needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_TfawDelaySet(DDR_MODULE_ID index, uint32_t tFaw, uint32_t ctrlClkPer); Returns None. Description This function initializes the DDR controller with the four-bank activation window for the DDR in use. The following register field is programmed with this function: • FAWTDLY<5:0> - DDRDLYCFG3<21:16> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tFAW 35000 // psec PLIB_DDR_TfawDelaySet(DDR_ID_0, tFAW, CTRL_CLK_PERIOD); Parameters Parameters Description index Identifier for the device instance to be configured tFaw Four bank activation window (psec) ctrlClkPer DDR Controller clock period (psec) Function void PLIB_DDR_TfawDelaySet( DDR_MODULE_ID index, uint32_t tFaw, uint32_t ctrlClkPer); b) Target Arbitration Functions PLIB_DDR_MinCommand Function Sets the minimum number of bursts to be serviced for a DDR target within (REQPER * 4) number of clocks. File plib_ddr.h Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 668 C void PLIB_DDR_MinCommand(DDR_MODULE_ID index, uint8_t minCmd, DDR_TARGET target); Returns None. Description This function sets the minimum number of bursts to be serviced for a DDR target within (REQPER * 4) number of clocks. Used with PLIB_DDR_ReqPeriod to determine the total bandwidth allocated to a target. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions The target must be selected with PLIB_DDR_TargetSelect() prior to using this function. Example PLIB_DDR_MinCommand(DDR_ID_0, 83, DDR_TARGET_CPU); Parameters Parameters Description index Identifier for the device instance to be configured minCmd Number of bursts target Target for minCmd setting Function void PLIB_DDR_MinCommand( DDR_MODULE_ID index, uint8_t minCmd, DDR_TARGET target) PLIB_DDR_MinLimit Function Sets the minimum number of bursts for a DDR target. File plib_ddr.h C void PLIB_DDR_MinLimit(DDR_MODULE_ID index, uint8_t minLim, DDR_TARGET target); Returns None. Description This function sets the minimum number of bursts (two cycles per burst) that a target must have uninterrupted access to without interference from another target. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions The target must be selected with PLIB_DDR_TargetSelect prior to using this function. Example PLIB_DDR_MinLimit(DDR_ID_0, 1, DDR_TARGET_CPU); Parameters Parameters Description index Identifier for the device instance to be configured minLim Number of bursts target Target for minLim setting Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 669 Function void PLIB_DDR_MinLimit( DDR_MODULE_ID index, uint8_t minLim, DDR_TARGET target) PLIB_DDR_ReqPeriod Function Sets the timeout for MINCMD number of bursts to be serviced for a DDR target. File plib_ddr.h C void PLIB_DDR_ReqPeriod(DDR_MODULE_ID index, uint8_t reqPer, DDR_TARGET target); Returns None. Description This function sets the timeout for MINCMD number of bursts to be serviced for a DDR target. Used with PLIB_DDR_MinCommand to determine the total bandwidth allocated to a target. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions The target must be selected with PLIB_DDR_TargetSelect prior to using this function. Example PLIB_DDR_ReqPeriod(DDR_ID_0, 167, DDR_TARGET_CPU); Parameters Parameters Description index Identifier for the device instance to be configured reqPer Number of clocks (multiplied by 4) target Target for reqPer setting Function void PLIB_DDR_ReqPeriod( DDR_MODULE_ID index, uint8_t reqPer, DDR_TARGET target) c) SDRAM Initialization Functions PLIB_DDR_CmdDataIsComplete Function Returns the value of the valid bit in the DDR2CMDISSUE register. This bit is cleared by hardware, when the SDRAM initialization data has been transmitted. File plib_ddr.h C bool PLIB_DDR_CmdDataIsComplete(DDR_MODULE_ID index); Returns None. Description This function returns the value of the valid bit in the DDR2CMDISSUE register. This bit is cleared by hardware, when the SDRAM initialization data has been transmitted. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 670 Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example while (PLIB_DDR_CmdDataIsComplete(DDR_ID_0)); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_DDR_CmdDataIsComplete( DDR_MODULE_ID index); PLIB_DDR_CmdDataSend Function Transmits the data in the command registers to the SDRAM. File plib_ddr.h C void PLIB_DDR_CmdDataSend(DDR_MODULE_ID index); Returns None. Description This function transmits the data in the command registers to the SDRAM. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_CmdDataSend(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_CmdDataSend( DDR_MODULE_ID index); PLIB_DDR_CmdDataValid Function Indicates to the controller that the data in the command registers is valid. File plib_ddr.h C void PLIB_DDR_CmdDataValid(DDR_MODULE_ID index); Returns None. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 671 Description This function indicates to the controller that the data in the command registers is valid. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_CmdDataValid(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_CmdDataValid( DDR_MODULE_ID index); PLIB_DDR_ControllerEnable Function Enables the controller for normal operations after SDRAM is initialized. File plib_ddr.h C void PLIB_DDR_ControllerEnable(DDR_MODULE_ID index); Returns None. Description This function enables the controller for normal operations after SDRAM is initialized. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_ControllerEnable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_ControllerEnable( DDR_MODULE_ID index); PLIB_DDR_MaxCmdBrstCntSet Function Sets the maximum number of commands that can be written to the controller in Burst mode. File plib_ddr.h C void PLIB_DDR_MaxCmdBrstCntSet(DDR_MODULE_ID index, int8_t maxCmds); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 672 Returns None. Description This function sets the maximum number of commands that can be written to the controller in Burst mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_MaxCmdBrstCntSet(DDR_ID_0, 3); Parameters Parameters Description index Identifier for the device instance to be configured maxCmds Maximum number of commands that can be written to the controller in burst mode Function void PLIB_DDR_MaxCmdBrstCntSet( DDR_MODULE_ID index, int8_t maxCmds); PLIB_DDR_NumHostCmdsSet Function Sets the number of commands to be transmitted to the SDRAM. File plib_ddr.h C void PLIB_DDR_NumHostCmdsSet(DDR_MODULE_ID index, int8_t numCmds); Returns None. Description This function sets the number of commands to be transmitted to the SDRAM. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_NumHostCmdsSet(DDR_ID_0, 0x0B); Parameters Parameters Description index Identifier for the device instance to be configured numCmds Number of commands to be transmitted to the SDRAM Function void PLIB_DDR_NumHostCmdsSet( DDR_MODULE_ID index, int8_t numCmds); PLIB_DDR_CmdDataWrite Function Writes an SDRAM command word to a command register in the controller. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 673 File plib_ddr.h C void PLIB_DDR_CmdDataWrite(DDR_MODULE_ID index, DDR_HOST_CMD_REG cmdReg, uint32_t cmdData); Returns None. Description This function writes an SDRAM command word to a command register in the controller. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define DDR_CMD_IDLE_NOP 0x00FFFFFF PLIB_DDR_CmdDataWrite(DDR_ID_0, DDR_HOST_CMD_REG_100, DDR_CMD_IDLE_NOP); Parameters Parameters Description index Identifier for the device instance to be configured cmdData 32-bit command data word cmdReg Command register Function void PLIB_DDR_CmdDataWrite( DDR_MODULE_ID index, DDR_HOST_CMD_REG cmdReg, uint32_t cmdData); d) SDRAM Addressing Functions PLIB_DDR_BankAddressSet Function Initializes the DDR controller memory configuration registers for bank address. File plib_ddr.h C void PLIB_DDR_BankAddressSet(DDR_MODULE_ID index, uint32_t bnkShft, uint32_t bnkMsk); Returns None. Description This function initializes the DDR controller memory configuration registers for the bank address. The following register fields are programmed with this Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_BankAddressSet(DDR_ID_0, 9, 0x03); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 674 Parameters Parameters Description index Identifier for the device instance to be configured bnkShft Number of bits to shift the bank address bnkMsk Bank address bit mask Function void PLIB_DDR_BankAddressSet( DDR_MODULE_ID index, uint32_t bnkShft, uint32_t bnkMsk); • BNKADDR<4:0> - DDRMEMCFG0<12:8> • BNKADDRMSK<2:0> - DDRMEMCFG4<2:0> PLIB_DDR_ChipSelectAddressSet Function Initializes the DDR controller memory configuration registers for Chip Select address. File plib_ddr.h C void PLIB_DDR_ChipSelectAddressSet(DDR_MODULE_ID index, uint32_t csShft, uint32_t csMsk); Returns None. Description This function initializes the DDR controller memory configuration registers for the Chip Select address. The following register fields are programmed with this Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_ChipSelectAddressSet(DDR_ID_0, 18, 0); Parameters Parameters Description index Identifier for the device instance to be configured csShft Number of bits to shift the Chip Select address csMsk Chip select address bit mask Function void PLIB_DDR_ChipSelectAddressSet( DDR_MODULE_ID index, uint32_t csShft, uint32_t csMsk); • CSADDR<4:0> - DDRMEMCFG0<20:16> • CSADDRMSK<2:0> - DDRMEMCFG4<8:6> PLIB_DDR_ColumnAddressSet Function Initializes the DDR controller memory configuration registers for the column address. File plib_ddr.h C void PLIB_DDR_ColumnAddressSet(DDR_MODULE_ID index, uint32_t colShft, uint32_t colMskLo, uint32_t colMskHi); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 675 Returns None. Description This function initializes the DDR controller memory configuration registers for the column address. The following register fields are programmed with this Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_ColumnAddressSet(DDR_ID_0, 0, 0x1FF, 0); Parameters Parameters Description index Identifier for the device instance to be configured colShft Number of bits to shift the column address colMaskLo Column address bit mask low colMaskHi Column address bit mask high Function void PLIB_DDR_ColumnAddressSet( DDR_MODULE_ID index, uint32_t colShft, uint32_t colMskLo, uint32_t colMskHi); • CLHADDR<4:0> - DDRMEMCFG0<28:24> • CLADDRHMSK<12:0> - DDRMEMCFG2<12:0> • CLADDRLMSK<12:0> - DDRMEMCFG3<12:0> PLIB_DDR_RowAddressSet Function Initializes the DDR controller memory configuration registers for row address. File plib_ddr.h C void PLIB_DDR_RowAddressSet(DDR_MODULE_ID index, uint32_t rowShft, uint32_t rowMsk); Returns None. Description this function initializes the DDR controller memory configuration registers for the row address. The following register fields are programmed with this function: • RWADDR<4:0> - DDRMEMCFG0<4:0> • RWADDRMASK<12:0> - DDRMEMCFG1<12:0> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_RowAddressSet(DDR_ID_0, 12, 0x1FFF); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 676 Parameters Parameters Description index Identifier for the device instance to be configured rowShft Number of bits to shift the row address rowMask Row address bit mask Function void PLIB_DDR_RowAddressSet( DDR_MODULE_ID index, uint32_t rowShft, uint32_t rowMsk); e) SDRAM Timing Functions PLIB_DDR_OdtReadParamSet Function Sets the ODT parameters for data reads. File plib_ddr.h C void PLIB_DDR_OdtReadParamSet(DDR_MODULE_ID index, uint8_t rLen, uint8_t rDly); Returns None. Description This function sets the ODT parameters for data reads. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_OdtReadParamSet(DDR_ID_0, 2, 4); Parameters Parameters Description index Identifier for the device instance to be configured rLen The number of clocks the ODT is turned on for reads rDly The number of clocks after a read command before turning on ODT to the DDR Function void PLIB_DDR_OdtReadParamSet( DDR_MODULE_ID index, uint8_t rLen, uint8_t rDly); PLIB_DDR_OdtWriteParamSet Function Sets the ODT parameters for data writes. File plib_ddr.h C void PLIB_DDR_OdtWriteParamSet(DDR_MODULE_ID index, uint8_t wLen, uint8_t wDly); Returns None. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 677 Description This function sets the ODT parameters for data writes. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_OdtWriteParamSet(DDR_ID_0, 3, 1); Parameters Parameters Description index Identifier for the device instance to be configured wLen The number of clocks the ODT is turned on for writes wDly The number of clocks after a write command before turning on ODT to the DDR Function void PLIB_DDR_OdtWriteParamSet( DDR_MODULE_ID index, uint8_t wLen, uint8_t wDly); PLIB_DDR_DataDelaySet Function Initializes the DDR controller with the data delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_DataDelaySet(DDR_MODULE_ID index, uint8_t rLat, uint8_t wLat); Returns None. Description This function initializes the DDR controller with the data delays for the DDR in use. The following register fields are programmed with this function: • RBENDDLY<3:0> - DDRDLYCFG2<31:28> • NXTDATRQDLY<3:0> - DDRXFERCFG<3:0> • NXTDATAVDLY<4:0> - DDRXFERCFG<7:4>, DDRDLYCFG1<28> • RDATENDLY<3:0> - DDRXFERCFG<19:16> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_DataDelaySet(DDR_ID_0, 5, 4); Parameters Parameters Description index Identifier for the device instance to be configured rLat Read (CAS) latency in cycles (RL) wLat Write latency in cycles (WL) Function void PLIB_DDR_DataDelaySet( DDR_MODULE_ID index, uint8_t rLat, uint8_t wLat); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 678 PLIB_DDR_PowerDownDelaySet Function Initializes the DDR controller with the power down delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_PowerDownDelaySet(DDR_MODULE_ID index, uint32_t pwrDnDly, uint32_t tCKE, uint32_t tXP); Returns None. Description This function initializes the DDR controller with the power down delays for the DDR in use. The folPowerDownDelaySetlowing register fields are programmed with this function: • PWRDNDLY<7:0> - DDRPWRCFG<11:4> • PWRDNMINDLY<3:0> - DDR2DLYCFG1<19:16> • PWRDNEXDLY<5:0> - DDR2DLYCFG1<25:20> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define CLK_PERIOD 2500 // psec #define CTRL_CLK_PERIOD (CLK_PERIOD * 2) #define PWR_DN_DLY 8 #define tCKE 3 #define tXP 2 PLIB_DDR_PowerDownDelaySet(DDR_ID_0, PWR_DN_DLY, tCKE, tXP); Parameters Parameters Description index Identifier for the device instance to be configured pwrDnDly Power down delay (entry) in cycles tCKE Power down minimum delay in cycles (tCKE) tXP Power down exit delay in cycles (tXP) Function void PLIB_DDR_PowerDownDelaySet( DDR_MODULE_ID index, uint32_t pwrDnDly, uint32_t tCKE, uint32_t tXP); PLIB_DDR_SelfRefreshDelaySet Function Initializes the DDR controller with the self-refresh delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_SelfRefreshDelaySet(DDR_MODULE_ID index, uint32_t slfRefDly, uint32_t tCKE, uint32_t tDLLK); Returns None. Description This function initializes the DDR controller with the self-refresh delays for the specific DDR in use. The following register fields are programmed Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 679 with this function: • SLFREFDLY<9:0> - DDRPWRCFG<21:12> • SLFREFMINDLY<7:0> - DDRDLYCFG1<7:0> • SLFREFEXDLY<8:0> - DDRDLYCFG1<15:8>, DDR2DLYCFG1<30> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define SELF_REF_DLY 17 #define tCKE 3 PLIB_DDR_SelfRefreshDelaySet(DDR_ID_0, SELF_REF_DLY, tCKE, 85); Parameters Parameters Description index Identifier for the device instance to be configured slfRefDly Self refresh delay in number of clock cycles divided by 1024 (e.g., 1 = 1024 clocks, 2 = 2048 clocks, etc.) tCKE Power down minimum delay in cycles (tCKE) tDLLK DLL lock delay time in cycles (tDLLK) Function void PLIB_DDR_SelfRefreshDelaySet( DDR_MODULE_ID index, uint32_t slfRefDly, uint32_t tCKE, uint32_t tDLLK); PLIB_DDR_PrechargAllBanksSet Function Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_PrechargAllBanksSet(DDR_MODULE_ID index, uint32_t tRP, uint32_t ctrlClkPer); Returns None. Description This function initializes the DDR controller with the read/write precharge delays for the DDR in use. The following register fields are programmed with this function: • PCHRGALLDLY<3:0> - DDRDLYCFG2<3:0> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tRP 12500 // psec PLIB_DDR_PrechargAllBanksSet(DDR_ID_0, tRP, CTRL_CLK_PERIOD); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 680 tRP Precharge to active delay (psec) ctrlClkPer DDR Controller clock period (psec) Function void PLIB_DDR_PrechargAllBanksSet( DDR_MODULE_ID index, uint32_t tRP, uint32_t ctrlClkPer); PLIB_DDR_ReadWriteDelaySet Function Initializes the DDR controller with the read/write delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_ReadWriteDelaySet(DDR_MODULE_ID index, uint8_t bLen, uint8_t wLat, uint8_t rLat); Returns None. Description This function initializes the DDR controller with the read/write delays for the specific DDR in use. The following register fields are programmed with this function: • R2WDLY<3:0> - DDRDLYCFG0<27:24> • RMWDLY<3:0> - DDRDLYCFG0<31:28> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define BL 2 #define WL 4 #define RL 5 PLIB_DDR_ReadWriteDelaySet(DDR_ID_0 BL, WL, RL); Parameters Parameters Description index Identifier for the device instance to be configured bLen Burst length in cycles (BL) wLat Write latency in cycles (WL) rLat Read latency in cycles (RL) Function void PLIB_DDR_ReadWriteDelaySet( DDR_MODULE_ID index, uint8_t bLen, uint8_t wLat, uint8_t rLat); PLIB_DDR_RefreshTimingSet Function Initializes the DDR controller refresh configuration. File plib_ddr.h C void PLIB_DDR_RefreshTimingSet(DDR_MODULE_ID index, uint32_t tRFC, uint32_t tRFI, uint32_t ctrlClkPer); Returns None. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 681 Description This function initializes the DDR controller refresh configuration and programs the refresh interval and delay between refreshes. The following register fields are programmed with this function: • REFCNT<15:0> - DDRREFCFG<15:0> • REFDLY<5:0> - DDRREFCFG<23:16> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tRFC 75000 // psec #define tRFI 7800000 // psec PLIB_DDR_RefreshConfig(DDR_ID_0, tRFC, tRFI, CTRL_CLK_PERIOD); Parameters Parameters Description index Identifier for the device instance to be configured tRFC Refresh Cycle Time in clock cycles tRFI Refresh Interval in clock cycles ctrlClkPer DDR Controller clock period Function void PLIB_DDR_RefreshTimingSet( DDR_MODULE_ID index, uint32_t tRFC, uint32_t tRFI, uint32_t ctrlClkPer); PLIB_DDR_WriteWriteDelaySet Function Initializes the DDR controller with the read/write delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_WriteWriteDelaySet(DDR_MODULE_ID index, uint8_t bLen); Returns None. Description This function initializes the DDR controller with the read/write delays for the specific DDR in use. The following register fields are programmed with this function: • W2WDLY<3:0> - DDRDLYCFG0<19:16> • W2WCSDLY<3:0> - DDRDLYCFG0<23:20> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define BL 2 PLIB_DDR_WriteWriteDelaySet(DDR_ID_0, BL); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 682 Parameters Parameters Description index Identifier for the device instance to be configured bLen Burst length in cycles (BL) Function void PLIB_DDR_WriteWriteDelaySet( DDR_MODULE_ID index, uint8_t bLen); PLIB_DDR_PrechargeToRASDelaySet Function Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_PrechargeToRASDelaySet(DDR_MODULE_ID index, uint32_t tRP, uint32_t ctrlClkPer); Returns None. Description This function initializes the DDR controller with the read/write precharge delays for the DDR in use. The following register fields are programmed with this function: • PCHRG2RASDLY<3:0> - DDRDLYCFG2<24:27> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tRP 12500 // psec PLIB_DDR_PrechargeToRASDelaySet(DDR_ID_0, tRP, CTRL_CLK_PERIOD); Parameters Parameters Description index Identifier for the device instance to be configured tRP Precharge to active delay (psec) ctrlClkPer DDR Controller clock period Function void PLIB_DDR_PrechargeToRASDelaySet( DDR_MODULE_ID index, uint32_t tRP, uint32_t ctrlClkPer); PLIB_DDR_RASToCASDelaySet Function Initializes the DDR controller with the row/column address delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_RASToCASDelaySet(DDR_MODULE_ID index, uint32_t tRCD, uint32_t ctrlClkPer); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 683 Returns None. Description This function initializes the DDR controller with the row/column address delays for the DDR in use. The following register fields are programmed with this function: • RAS2CASDLY<3:0> - DDRDLYCFG2<23:20> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tRCD 12500 // psec PLIB_DDR_RASToCASDelaySet(DDR_ID_0, tRCD, CTRL_CLK_PERIOD); Parameters Parameters Description index Identifier for the device instance to be configured tRCD RAS to CAS delay (psec) ctrlClkPer DDR Controller clock period (psec) Function void PLIB_DDR_RASToCASDelaySet( DDR_MODULE_ID index, uint32_t tRCD, uint32_t ctrlClkPer); PLIB_DDR_RASToPrechargeDelaySet Function Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_RASToPrechargeDelaySet(DDR_MODULE_ID index, uint32_t tRAS, uint32_t ctrlClkPer); Returns None. Description This function initializes the DDR controller with the read/write precharge delays for the DDR in use. The following register fields are programmed with this function: • RAS2PCHRGDLY<4:0> - DDRDLYCFG3<4:0> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tRAS 45000 // psec PLIB_DDR_RASToPrechargeDelaySet(DDR_ID_0, tRAS, CTRL_CLK_PERIOD); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 684 Parameters Parameters Description index Identifier for the device instance to be configured tRAS Active to Precharge delay (psec) ctrlClkPer DDR Controller clock period (psec) Function void PLIB_DDR_RASToPrechargeDelaySet( DDR_MODULE_ID index, uint32_t tRAS, uint32_t ctrlClkPer); PLIB_DDR_RASToRASBankDelaySet Function Initializes the DDR controller with the row/column address delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_RASToRASBankDelaySet(DDR_MODULE_ID index, uint32_t tRC, uint32_t ctrlClkPer); Returns None. Description This function initializes the DDR controller with the row/column address delays for the DDR in use. The following register fields are programmed with this function: • RAS2RASSBNKDLY<5:0> - DDRDLYCFG3<13:8> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tRC 57500 // psec PLIB_DDR_RASToRASBankDelaySet(DDR_ID_0, tRC, CTRL_CLK_PERIOD); Parameters Parameters Description index Identifier for the device instance to be configured tRC Row cycle time (psec) ctrlClkPer DDR Controller clock period (psec) Function void PLIB_DDR_RASToRASBankDelaySet( DDR_MODULE_ID index, uint32_t tRC, uint32_t ctrlClkPer); PLIB_DDR_RASToRASDelaySet Function Initializes the DDR controller with the row/column address delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_RASToRASDelaySet(DDR_MODULE_ID index, uint32_t tRRD, uint32_t ctrlClkPer); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 685 Returns None. Description This function initializes the DDR controller with the row/column address delays for the DDR in use. The following register fields are programmed with this function: • RAS2RASDLY<3:0> - DDRDLYCFG2<19:16> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tRRD 7500 // psec PLIB_DDR_RASToRASDelaySet(DDR_ID_0, tRRD, CTRL_CLK_PERIOD); Parameters Parameters Description index Identifier for the device instance to be configured tRRD RAS to RAS delay (psec) ctrlClkPer DDR Controller clock period (psec) Function void PLIB_DDR_RASToRASDelaySet( DDR_MODULE_ID index, uint32_t tRRD, uint32_t ctrlClkPer); PLIB_DDR_ReadToPrechargeDelaySet Function Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_ReadToPrechargeDelaySet(DDR_MODULE_ID index, uint32_t tRTP, uint8_t bLen, uint32_t ctrlClkPer); Returns None. Description This function initializes the DDR controller with the read/write precharge delays for the DDR in use. The following register fields are programmed with this function: • R2PCHRGDLY<3:0> - DDRDLYCFG2<11:8> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tRTP 7500 // psec #define BL 2 PLIB_DDR_ReadToPrechargeDelaySet(DDR_ID_0, tRTP, BL, CTRL_CLK_PERIOD); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 686 Parameters Parameters Description index Identifier for the device instance to be configured tRTP Read to precharge delay (psec) bLen Burst length in cycles (BL) ctrlClkPer DDR Controller clock period (psec) Function void PLIB_DDR_ReadToPrechargeDelaySet( DDR_MODULE_ID index, uint32_t tRTP, uint8_t bLen, uint32_t ctrlClkPer); PLIB_DDR_WriteToPrechargeDelaySet Function Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_WriteToPrechargeDelaySet(DDR_MODULE_ID index, uint32_t tWR, uint8_t bLen, uint8_t wLat, uint32_t ctrlClkPer); Returns None. Description This function initializes the DDR controller with the read/write precharge delays for the DDR in use. The following register fields are programmed with this function: • W2PCHRGDLY<4:0> - DDRDLYCFG2<15:12>, DDRDLYCFG1<26> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define clock_period 2500 // psec #define CTRL_CLK_PERIOD (clock_period * 2) #define tRTP 7500 // psec #define BL 2 #define wLat 4 PLIB_DDR_WriteToPrechargeDelaySet(DDR_ID_0, tRTP, BL, wLat, CTRL_CLK_PERIOD); Parameters Parameters Description index Identifier for the device instance to be configured tWR Write recovery delay (psec) bLen Burst length in cycles (BL) wLat Write latency in cycles (WL) ctrlClkPer DDR Controller clock period (psec) Function void PLIB_DDR_WriteToPrechargeDelaySet( DDR_MODULE_ID index, uint32_t tWR, uint8_t bLen, uint8_t wLat, uint32_t ctrlClkPer); PLIB_DDR_ReadReadDelaySet Function Initializes the DDR controller with the read/write delays needed for the specific DDR in use. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 687 File plib_ddr.h C void PLIB_DDR_ReadReadDelaySet(DDR_MODULE_ID index, uint8_t bLen); Returns None. Description This function initializes the DDR controller with the read/write delays for the specific DDR in use. The following register fields are programmed with this function: • R2RDLY<3:0> - DDRDLYCFG0<11:8> • R2RCSDLY<3:0> - DDRDLYCFG0<15:12> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define BL 2 PLIB_DDR_ReadReadDelaySet(DDR_ID_0, BL); Parameters Parameters Description index Identifier for the device instance to be configured bLen Burst length in cycles (BL) Function void PLIB_DDR_ReadReadDelaySet( DDR_MODULE_ID index, uint8_t bLen); PLIB_DDR_WriteReadDelaySet Function Initializes the DDR controller with the read/write delays needed for the specific DDR in use. File plib_ddr.h C void PLIB_DDR_WriteReadDelaySet(DDR_MODULE_ID index, uint32_t tWTR, uint8_t bLen, uint8_t wLat, uint32_t ctrlClkPer); Returns None. Description This function initializes the DDR controller with the read/write delays for the specific DDR in use. The following register fields are programmed with this function: • W2RDLY<4:0> - DDRDLYCFG0<3:0>, DDRDLYCFG1<27> • W2RCSDLY<4:0> - DDRDLYCFG0<7:4>, DDRDLYCFG1<28> Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example #define CLK_PERIOD 2500 // psec Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 688 #define CTRL_CLK_PERIOD (CLK_PERIOD * 2) #define tWTR 7500 PLIB_DDR_WriteReadDelaySet(DDR_ID_0, tWTR, 2, 4, CTRL_CLK_PERIOD); Parameters Parameters Description index Identifier for the device instance to be configured tWTR Write to read latency (in psecs) bLen Burst length in cycles (BL) wLat Write latency in cycles (WL) ctrlClkPer Control clock period (psec) Function void PLIB_DDR_WriteReadDelaySet( DDR_MODULE_ID index, uint32_t tWTR, uint8_t bLen, uint8_t wLat, uint32_t ctrlClkPer); f) PHY Initialization Functions PLIB_DDR_PHY_DDRTypeSet Function Sets the DRAM type for the PHY. File plib_ddr.h C void PLIB_DDR_PHY_DDRTypeSet(DDR_MODULE_ID index, DDR_PHY_DDR_TYPE ddrType); Returns None. Description This function sets the DRAM type for the PHY. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_DDRTypeSet(DDR_ID_0, DDR_PHY_DDR_TYPE_DDR2); Parameters Parameters Description index Identifier for the device instance to be configured ddrType DDR type (DDR2 or DDR3) Function void PLIB_DDR_PHY_DDRTypeSet( DDR_MODULE_ID index, DDR_PHY_DDR_TYPE ddrType); PLIB_DDR_PHY_DllMasterDelayStartSet Function Sets the start value of the digital DLL master delay line. File plib_ddr.h Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 689 C void PLIB_DDR_PHY_DllMasterDelayStartSet(DDR_MODULE_ID index, uint8_t dlyStart); Returns None. Description This function sets the start value of the digital DLL master delay line. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_DllMasterDelayStartSet(DDR_ID_0, 3); Parameters Parameters Description index Identifier for the device instance to be configured dlyStart Function void PLIB_DDR_PHY_DllMasterDelayStartSet( DDR_MODULE_ID index, uint8_t dlyStart); PLIB_DDR_PHY_DllRecalibDisable Function Disables periodic recalibration of the internal digital DLL. File plib_ddr.h C void PLIB_DDR_PHY_DllRecalibDisable(DDR_MODULE_ID index); Returns None. Description this function disables periodic recalibration of the internal digital DLL. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_DllRecalibDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_DllRecalibDisable( DDR_MODULE_ID index); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 690 PLIB_DDR_PHY_DllRecalibEnable Function Enables periodic recalibration of the internal digital DLL, and sets the recalibration period. File plib_ddr.h C void PLIB_DDR_PHY_DllRecalibEnable(DDR_MODULE_ID index, uint32_t recalibCnt); Returns None. Description This function enables periodic recalibration of the internal digital DLL, and sets the recalibration period. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_DllRecalibEnable(DDR_ID_0, 100); Parameters Parameters Description index Identifier for the device instance to be configured recalibCnt Period of DLL recalibration in units of (PHY clock * 256) Function void PLIB_DDR_PHY_DllRecalibEnable( DDR_MODULE_ID index, uint32_t recalibCnt); PLIB_DDR_PHY_DriveStrengthSet Function Disables On Die Termination. File plib_ddr.h C void PLIB_DDR_PHY_DriveStrengthSet(DDR_MODULE_ID index, DDR_PHY_DRIVE_STRENGTH drvStr); Returns None. Description This function disables On Die Termination (ODT). Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_DriveStrengthSet(DDR_ID_0, DDR_PHY_DRIVE_STRENGTH_FULL); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 691 Parameters Parameters Description index Identifier for the device instance to be configured drvStr Drive strength Function void PLIB_DDR_PHY_DriveStrengthSet( DDR_MODULE_ID index, DDR_PHY_DRIVE_STRENGTH drvStr); PLIB_DDR_PHY_DrvStrgthCal Function Calibrates the pad NFET and PFET output impedance. File plib_ddr.h C void PLIB_DDR_PHY_DrvStrgthCal(DDR_MODULE_ID index, uint8_t nFet, uint8_t pFet); Returns None. Description This function calibrates the pad NFET and PFET output impedance. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_DrvStrgthCal(DDR_ID_0, 0xF, 0xF); Parameters Parameters Description index Identifier for the device instance to be configured nFet NFET impedance calibration value pFet PFET impedance calibration value Function void PLIB_DDR_PHY_DrvStrgthCal( DDR_MODULE_ID index, uint8_t nFet, uint8_t pFet); PLIB_DDR_PHY_ExternalDllEnable Function Enables the use of an external DLL. File plib_ddr.h C void PLIB_DDR_PHY_ExternalDllEnable(DDR_MODULE_ID index); Returns None. Description This function enables the use of an external DLL. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 692 Preconditions None. Example PLIB_DDR_PHY_ExternalDllEnable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_ExternalDllEnable( DDR_MODULE_ID index); PLIB_DDR_PHY_ExtraClockDisable Function Does not enable the drive pad for an extra clock cycle after a write burst. File plib_ddr.h C void PLIB_DDR_PHY_ExtraClockDisable(DDR_MODULE_ID index); Returns None. Description This function does not enable the drive pad for an extra clock cycle after a write burst. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_ExtraClockDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_ExtraClockDisable( DDR_MODULE_ID index); PLIB_DDR_PHY_ExtraClockEnable Function Enables the drive pad for an extra clock cycle after a write burst. File plib_ddr.h C void PLIB_DDR_PHY_ExtraClockEnable(DDR_MODULE_ID index); Returns None. Description This function enables the drive pad for an extra clock cycle after a write burst. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 693 Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_ExtraClockEnable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_ExtraClockEnable( DDR_MODULE_ID index); PLIB_DDR_PHY_InternalDllEnable Function Enables the use of the internal digital DLL. File plib_ddr.h C void PLIB_DDR_PHY_InternalDllEnable(DDR_MODULE_ID index); Returns None. Description This function enables the use of the internal digital DLL. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_InternalDllEnable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_InternalDllEnable( DDR_MODULE_ID index); PLIB_DDR_PHY_OdtCal Function Calibrates the pull-up and pull-down ODT impedance. File plib_ddr.h C void PLIB_DDR_PHY_OdtCal(DDR_MODULE_ID index, uint8_t puCal, uint8_t pdCal); Returns None. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 694 Description This function calibrates the pull-up and pull-down ODT impedance. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_OdtCal(DDR_ID_0, 2, 2); Parameters Parameters Description index Identifier for the device instance to be configured puCal Pull-up calibration value pdCal Pull-down calibration value Function void PLIB_DDR_PHY_OdtCal( DDR_MODULE_ID index, uint8_t puCal, uint8_t pdCal); PLIB_DDR_PHY_OdtCSDisable Function Disables ODT on Chip Select while running SCL test. File plib_ddr.h C void PLIB_DDR_PHY_OdtCSDisable(DDR_MODULE_ID index); Returns None. Description This function disables ODT on Chip Select while running SCL test. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_OdtCSDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_OdtCSDisable( DDR_MODULE_ID index); PLIB_DDR_PHY_OdtCSEnable Function Enables ODT on Chip Select while running SCL test. File plib_ddr.h Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 695 C void PLIB_DDR_PHY_OdtCSEnable(DDR_MODULE_ID index); Returns None. Description This function enables ODT on Chip Select while running SCL test. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_OdtCSEnable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_OdtCSEnable( DDR_MODULE_ID index); PLIB_DDR_PHY_OdtDisable Function Disables On Die Termination. File plib_ddr.h C void PLIB_DDR_PHY_OdtDisable(DDR_MODULE_ID index); Returns None. Description This function disables On Die Termination. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_OdtDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_OdtDisable( DDR_MODULE_ID index); PLIB_DDR_PHY_OdtEnable Function Enables On Die Termination and sets the value. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 696 File plib_ddr.h C void PLIB_DDR_PHY_OdtEnable(DDR_MODULE_ID index, DDR_PHY_ODT odtVal); Returns None. Description This function enables On Die Termination (ODT) and sets the value. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_OdtEnable(DDR_ID_0, DDR_PHY_ODT_75_OHM); Parameters Parameters Description index Identifier for the device instance to be configured odtVal The ODT value Function void PLIB_DDR_PHY_OdtEnable( DDR_MODULE_ID index, DDR_PHY_ODT odtVal); PLIB_DDR_PHY_PadReceiveEnable Function Enables pad receivers on bidirectional I/O. File plib_ddr.h C void PLIB_DDR_PHY_PadReceiveEnable(DDR_MODULE_ID index); Returns None. Description This function enables pad receivers on bidirectional I/O. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_PadReceiveEnable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_PadReceiveEnable( DDR_MODULE_ID index); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 697 PLIB_DDR_PHY_PreambleDlySet Function Sets the length of the preamble for data writes. File plib_ddr.h C void PLIB_DDR_PHY_PreambleDlySet(DDR_MODULE_ID index, DDR_PHY_PREAMBLE_DLY preDly); Returns None. Description This function sets the length of the preamble for data writes. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_PreambleDlySet(DDR_ID_0, DDR_PHY_PREAMBLE_DLY_1_0); Parameters Parameters Description index Identifier for the device instance to be configured preDly Preamble delay Function void PLIB_DDR_PHY_PreambleDlySet( DDR_MODULE_ID index, DDR_PHY_PREAMBLE_DLY preDly); PLIB_DDR_PHY_ReadCASLatencySet Function Sets the read CAS latency while running SCL test. File plib_ddr.h C void PLIB_DDR_PHY_ReadCASLatencySet(DDR_MODULE_ID index, uint8_t rLat); Returns None. Description This function sets the read CAS latency while running SCL test. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_ReadCASLatencySet(DDR_ID_0, 5); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 698 Parameters Parameters Description index Identifier for the device instance to be configured rLat Read CAS latency (RL) Function void PLIB_DDR_PHY_ReadCASLatencySet( DDR_MODULE_ID index, uint8_t rLat); PLIB_DDR_PHY_SCLDelay Function Disables ODT on Chip Select while running SCL test. File plib_ddr.h C void PLIB_DDR_PHY_SCLDelay(DDR_MODULE_ID index, DDR_PHY_SCL_DELAY sclDly); Returns None. Description This function disables ODT on Chip Select while running SCL test. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_SCLDelay(DDR_ID_0, DDR_PHY_SCL_DELAY_SINGLE); Parameters Parameters Description index Identifier for the device instance to be configured sclDly SCL delay Function void PLIB_DDR_PHY_SCLDelay( DDR_MODULE_ID index, DDR_PHY_SCL_DELAY sclDly); PLIB_DDR_PHY_SCLEnable Function Enables SCL on the Chip Select 'cs'. File plib_ddr.h C void PLIB_DDR_PHY_SCLEnable(DDR_MODULE_ID index, uint8_t cs); Returns None. Description This function enables SCL on the Chip Select 'cs'. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 699 Preconditions None. Example PLIB_DDR_PHY_SCLEnable(DDR_ID_0, 0); Parameters Parameters Description index Identifier for the device instance to be configured cs Chip select Function void PLIB_DDR_PHY_SCLEnable( DDR_MODULE_ID index, uint8_t cs); PLIB_DDR_PHY_SCLTestBurstModeSet Function Sets the burst mode of the DRAM while running SCL test. File plib_ddr.h C void PLIB_DDR_PHY_SCLTestBurstModeSet(DDR_MODULE_ID index, DDR_PHY_SCL_BURST_MODE brstMode); Returns None. Description This function sets the burst mode of the DRAM while running SCL test. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_SCLTestBurstModeSet(DDR_ID_0, DDR_PHY_SCL_BURST_MODE_8); Parameters Parameters Description index Identifier for the device instance to be configured brstMode Burst mode of the DRAM Function void PLIB_DDR_PHY_SCLTestBurstModeSet( DDR_MODULE_ID index, DDR_PHY_SCL_BURST_MODE brstMode); PLIB_DDR_PHY_WriteCASLatencySet Function Sets the write CAS latency while running SCL test. File plib_ddr.h C void PLIB_DDR_PHY_WriteCASLatencySet(DDR_MODULE_ID index, uint8_t wLat); Returns None. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 700 Description This function sets the write CAS latency while running SCL test. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_WriteCASLatencySet(DDR_ID_0, 4); Parameters Parameters Description index Identifier for the device instance to be configured wLat Write CAS latency (WL) Function void PLIB_DDR_PHY_WriteCASLatencySet( DDR_MODULE_ID index, uint8_t wLat); PLIB_DDR_PHY_PadReceiveDisable Function Disables pad receivers on bidirectional I/O. File plib_ddr.h C void PLIB_DDR_PHY_PadReceiveDisable(DDR_MODULE_ID index); Returns None. Description This function disables pad receivers on bidirectional I/O. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_PadReceiveDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_PadReceiveDisable( DDR_MODULE_ID index); PLIB_DDR_PHY_SCLCapClkDelaySet Function Sets capture clock delay during SCL. File plib_ddr.h Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 701 C void PLIB_DDR_PHY_SCLCapClkDelaySet(DDR_MODULE_ID index, uint8_t capDly); Returns None. Description This function sets capture clock delay during SCL. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_SCLCapClkDelaySet(DDR_ID_0, 4); Parameters Parameters Description index Identifier for the device instance to be configured capDly Capture Clock delay Function void PLIB_DDR_PHY_SCLCapClkDelaySet( DDR_MODULE_ID index, uint8_t capDly); PLIB_DDR_PHY_SCLDDRClkDelaySet Function Sets DDR clock delay during SCL. File plib_ddr.h C void PLIB_DDR_PHY_SCLDDRClkDelaySet(DDR_MODULE_ID index, uint8_t ddrDly); Returns None. Description This function sets DDR clock delay during SCL. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_SCLDDRClkDelaySet(DDR_ID_0, 4); Parameters Parameters Description index Identifier for the device instance to be configured ddrDly DDR Clock delay Function void PLIB_DDR_PHY_SCLDDRClkDelaySet( DDR_MODULE_ID index, uint8_t ddrDly); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 702 PLIB_DDR_PHY_HalfRateSet Function Sets the PHY to half rate mode. File plib_ddr.h C void PLIB_DDR_PHY_HalfRateSet(DDR_MODULE_ID index); Returns None. Description This function sets the PHY to half rate mode. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_HalfRateSet(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_HalfRateSet( DDR_MODULE_ID index); PLIB_DDR_PHY_SCLStart Function Runs PHY Self Calibration. File plib_ddr.h C void PLIB_DDR_PHY_SCLStart(DDR_MODULE_ID index); Returns None. Description This function runs PHY Self Calibration. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_SCLStart(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 703 Function void PLIB_DDR_PHY_SCLStart( DDR_MODULE_ID index); PLIB_DDR_PHY_SCLStatus Function Checks status of PHY Self Calibration. File plib_ddr.h C bool PLIB_DDR_PHY_SCLStatus(DDR_MODULE_ID index); Returns • true - The PHY SCL has passed • false - The PHY SCL has not passed Description This function checks status of PHY Self Calibration. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_SCLStatus(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_DDR_PHY_SCLStatus( DDR_MODULE_ID index); PLIB_DDR_PHY_AddCtlDriveStrengthSet Function Sets the drive strength for the PHY address and control pads. File plib_ddr.h C void PLIB_DDR_PHY_AddCtlDriveStrengthSet(DDR_MODULE_ID index, DDR_PHY_DRIVE_STRENGTH drvStr); Returns None. Description Sets the drive strength for the PHY address and control pads. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_AddCtlDriveStrengthSet(DDR_ID_0, DDR_PHY_DRIVE_STRENGTH_FULL); Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 704 Parameters Parameters Description index Identifier for the device instance to be configured drvStr Drive strength Function void PLIB_DDR_PHY_AddCtlDriveStrengthSet( DDR_MODULE_ID index, DDR_PHY_DRIVE_STRENGTH drvStr); PLIB_DDR_PHY_DataDriveStrengthSet Function Sets the drive strength for the PHY data pads. File plib_ddr.h C void PLIB_DDR_PHY_DataDriveStrengthSet(DDR_MODULE_ID index, DDR_PHY_DRIVE_STRENGTH drvStr); Returns None. Description Sets the drive strength for the PHY data pads. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_DataDriveStrengthSet(DDR_ID_0, DDR_PHY_DRIVE_STRENGTH_FULL); Parameters Parameters Description index Identifier for the device instance to be configured drvStr Drive strength Function void PLIB_DDR_PHY_DataDriveStrengthSet( DDR_MODULE_ID index, DDR_PHY_DRIVE_STRENGTH drvStr); PLIB_DDR_PHY_WriteCmdDelayDisable Function Disables write command delay. File plib_ddr.h C void PLIB_DDR_PHY_WriteCmdDelayDisable(DDR_MODULE_ID index); Returns None. Description Disables write command delay. Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 705 Preconditions None. Example PLIB_DDR_PHY_WriteCmdDelayDisable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_WriteCmdDelayDisable( DDR_MODULE_ID index); PLIB_DDR_PHY_WriteCmdDelayEnable Function Enables write command delay. The extra delay is needed for devices with even write latency (WL). File plib_ddr.h C void PLIB_DDR_PHY_WriteCmdDelayEnable(DDR_MODULE_ID index); Returns None. Description Enables write command delay. The extra delay is needed for devices with even write latency (WL). Remarks This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_DDR_PHY_WriteCmdDelayEnable(DDR_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_DDR_PHY_WriteCmdDelayEnable( DDR_MODULE_ID index); g) Feature Existence Functions PLIB_DDR_ExistsAddressMapping Function Identifies whether the AddressMapping feature exists on the DDR module. File plib_ddr.h C bool PLIB_DDR_ExistsAddressMapping(DDR_MODULE_ID index); Returns • true - The AddressMapping feature is supported on the device Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 706 • false - The AddressMapping feature is not supported on the device Description This function identifies whether the AddressMapping feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_RowAddressSet • PLIB_DDR_ColumnAddressSet • PLIB_DDR_BankAddressSet • PLIB_DDR_ChipSelectAddressSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsAddressMapping( DDR_MODULE_ID index ) PLIB_DDR_ExistsArbitrationControl Function Identifies whether the ArbitrationControl feature exists on the DDR module. File plib_ddr.h C bool PLIB_DDR_ExistsArbitrationControl(DDR_MODULE_ID index); Returns • true - The ArbitrationControl feature is supported on the device • false - The ArbitrationControl feature is not supported on the device Description This function identifies whether the ArbitrationControl feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_TargetSelect • PLIB_DDR_MinLimit • PLIB_DDR_ReqPeriod • PLIB_DDR_MinCommand Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsArbitrationControl( DDR_MODULE_ID index ) PLIB_DDR_ExistsAutoPowerDown Function Identifies whether the AutoPowerDown feature exists on the DDR module. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 707 File plib_ddr.h C bool PLIB_DDR_ExistsAutoPowerDown(DDR_MODULE_ID index); Returns • true - The AutoPowerDown feature is supported on the device • false - The AutoPowerDown feature is not supported on the device Description This function identifies whether the AutoPowerDown feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_AutoPowerDownEnable • PLIB_DDR_AutoPowerDownDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsAutoPowerDown( DDR_MODULE_ID index ) PLIB_DDR_ExistsAutoPrecharge Function Identifies whether the AutoPrecharge feature exists on the DDR module. File plib_ddr.h C bool PLIB_DDR_ExistsAutoPrecharge(DDR_MODULE_ID index); Returns • true - The AutoPrecharge feature is supported on the device • false - The AutoPrecharge feature is not supported on the device Description This function identifies whether the AutoPrecharge feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_AutoPchrgEnable • PLIB_DDR_AutoPchrgDisable • PLIB_DDR_AutoPchrgPowerDownEnable • PLIB_DDR_AutoPchrgPowerDownDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 708 Function PLIB_DDR_ExistsAutoPrecharge( DDR_MODULE_ID index ) PLIB_DDR_ExistsAutoSelfRefresh Function Identifies whether the AutoSelfRefresh feature exists on the DDR module. File plib_ddr.h C bool PLIB_DDR_ExistsAutoSelfRefresh(DDR_MODULE_ID index); Returns • true - The AutoSelfRefresh feature is supported on the device • false - The AutoSelfRefresh feature is not supported on the device Description This function identifies whether the AutoSelfRefresh feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_AutoSelfRefreshEnable • PLIB_DDR_AutoSelfRefreshDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsAutoSelfRefresh( DDR_MODULE_ID index ) PLIB_DDR_ExistsDDRCommands Function Identifies whether the DDRCommands feature exists on the DDR module. File plib_ddr.h C bool PLIB_DDR_ExistsDDRCommands(DDR_MODULE_ID index); Returns • true - The DDRCommands feature is supported on the device • false - The DDRCommands feature is not supported on the device Description This function identifies whether the DDRCommands feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_MaxCmdBrstCntSet • PLIB_DDR_NumHostCmdsSet • PLIB_DDR_CmdDataWrite • PLIB_DDR_CmdDataValid • PLIB_DDR_CmdDataSend • PLIB_DDR_CmdDataIsComplete • PLIB_DDR_ControllerEnable Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 709 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsDDRCommands( DDR_MODULE_ID index ) PLIB_DDR_ExistsDDRControllerConfig Function Identifies whether the DDRControllerConfig feature exists on the DDR module. File plib_ddr.h C bool PLIB_DDR_ExistsDDRControllerConfig(DDR_MODULE_ID index); Returns • true - The DDRControllerConfig feature is supported on the device • false - The DDRControllerConfig feature is not supported on the device Description This function identifies whether the DDRControllerConfig feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_BigEndianSet • PLIB_DDR_LittleEndianSet • PLIB_DDR_FullRateSet • PLIB_DDR_HalfRateSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsDDRControllerConfig( DDR_MODULE_ID index ) PLIB_DDR_ExistsODTConfig Function Identifies whether the ODTConfig feature exists on the DDR module. File plib_ddr.h C bool PLIB_DDR_ExistsODTConfig(DDR_MODULE_ID index); Returns • true - The ODTConfig feature is supported on the device Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 710 • false - The ODTConfig feature is not supported on the device Description This function identifies whether the ODTConfig feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_OdtReadEnable • PLIB_DDR_OdtReadDisable • PLIB_DDR_OdtWriteEnable • PLIB_DDR_OdtWriteDisable • PLIB_DDR_OdtWriteParamSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsODTConfig( DDR_MODULE_ID index ) PLIB_DDR_ExistsPHY_DLLCalibration Function Identifies whether the PHY_DLLCalibration feature exists on the DDR module. File plib_ddr.h C bool PLIB_DDR_ExistsPHY_DLLCalibration(DDR_MODULE_ID index); Returns • true - The PHY_DLLCalibration feature is supported on the device • false - The PHY_DLLCalibration feature is not supported on the device Description This function identifies whether the PHY_DLLCalibration feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_PHY_DllRecalibEnable • PLIB_DDR_PHY_DllRecalibDisable • PLIB_DDR_PHY_DllMasterDelayStartSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsPHY_DLLCalibration( DDR_MODULE_ID index ) PLIB_DDR_ExistsPHY_PadConfig Function Identifies whether the PHY_PadConfig feature exists on the DDR module. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 711 File plib_ddr.h C bool PLIB_DDR_ExistsPHY_PadConfig(DDR_MODULE_ID index); Returns • true - The PHY_PadConfig feature is supported on the device • false - The PHY_PadConfig feature is not supported on the device Description This function identifies whether the PHY_PadConfig feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_PHY_OdtEnable • PLIB_DDR_PHY_OdtDisable • PLIB_DDR_PHY_DriveStrengthSet • PLIB_DDR_PHY_OdtCal • PLIB_DDR_PHY_DrvStrgthCal • PLIB_DDR_PHY_ExtraClockEnable • PLIB_DDR_PHY_ExtraClockDisable • PLIB_DDR_PHY_InternalDllEnable • PLIB_DDR_PHY_ExternalDllEnable • PLIB_DDR_PHY_PadReceiveEnable • PLIB_DDR_PHY_PreambleDlySet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsPHY_PadConfig( DDR_MODULE_ID index ) PLIB_DDR_ExistsPHY_SCLConfig Function Identifies whether the PHY_SCLConfig feature exists on the DDR module File plib_ddr.h C bool PLIB_DDR_ExistsPHY_SCLConfig(DDR_MODULE_ID index); Returns • true - The PHY_SCLConfig feature is supported on the device • false - The PHY_SCLConfig feature is not supported on the device Description This function identifies whether the PHY_SCLConfig feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_PHY_SCLTestBurstModeSet • PLIB_DDR_PHY_DDRTypeSet • PLIB_DDR_PHY_ReadCASLatencySet • PLIB_DDR_PHY_WriteCASLatencySet • PLIB_DDR_PHY_OdtCSEnable Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 712 • PLIB_DDR_PHY_OdtCSDisable • PLIB_DDR_PHY_SCLDelay • PLIB_DDR_PHY_SCLEnable • PLIB_DDR_PHY_SCLDDRClkDelaySet • PLIB_DDR_PHY_SCLCapClkDelaySet • PLIB_DDR_PHY_SCLStart • PLIB_DDR_PHY_SCLStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsPHY_SCLConfig( DDR_MODULE_ID index ) PLIB_DDR_ExistsRefreshConfig Function Identifies whether the RefreshConfig feature exists on the DDR module. File plib_ddr.h C bool PLIB_DDR_ExistsRefreshConfig(DDR_MODULE_ID index); Returns • true - The RefreshConfig feature is supported on the device • false - The RefreshConfig feature is not supported on the device Description This function identifies whether the RefreshConfig feature is available on the DDR module. When this function returns true, this function is supported on the device: • PLIB_DDR_RefreshConfig Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsRefreshConfig( DDR_MODULE_ID index ) PLIB_DDR_ExistsTimingDelays Function Identifies whether the TimingDelays feature exists on the DDR module File plib_ddr.h Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 713 C bool PLIB_DDR_ExistsTimingDelays(DDR_MODULE_ID index); Returns • true - The TimingDelays feature is supported on the device • false - The TimingDelays feature is not supported on the device Description This function identifies whether the TimingDelays feature is available on the DDR module. When this function returns true, these functions are supported on the device: • PLIB_DDR_ReadWriteDelaySet • PLIB_DDR_SelfRefreshDelaySet • PLIB_DDR_PowerDownDelaySet • PLIB_DDR_PchrgDelaySet • PLIB_DDR_AddressDelaySet • PLIB_DDR_DataDelaySet • PLIB_DDR_TfawDelaySet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_DDR_ExistsTimingDelays( DDR_MODULE_ID index ) h) Data Types and Constants DDR_CMD_IDLE_NOP Macro File plib_ddr.h C #define DDR_CMD_IDLE_NOP 0x00FFFFFF Section Constants and Data Types DDR_PHY_DDR_TYPE Enumeration Defines the DDR type. File plib_ddr_help.h C typedef enum { DDR_PHY_DDR_TYPE_DDR2, DDR_PHY_DDR_TYPE_DDR3 } DDR_PHY_DDR_TYPE; Description DDR Type Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 714 This data type defines the DDR type. Remarks The actual definition of this enumeration is device-specific. DDR_CMD_LOAD_MODE Macro File plib_ddr.h C #define DDR_CMD_LOAD_MODE 0x00FFF001 Description This is macro DDR_CMD_LOAD_MODE. DDR_PHY_DRIVE_STRENGTH Enumeration Defines the PHY Pad drive strength value. File plib_ddr_help.h C typedef enum { DDR_PHY_DRIVE_STRENGTH_60, DDR_PHY_DRIVE_STRENGTH_FULL } DDR_PHY_DRIVE_STRENGTH; Description PHY Pad Drive Strength Value This data type defines the PHY Pad drive strength value. Remarks The actual definition of this enumeration is device-specific. DDR_CMD_PRECHARGE_ALL Macro File plib_ddr.h C #define DDR_CMD_PRECHARGE_ALL 0x00FFF401 Description This is macro DDR_CMD_PRECHARGE_ALL. DDR_PHY_ODT Enumeration Defines the ODT termination value. File plib_ddr_help.h C typedef enum { DDR_PHY_ODT_75_OHM, DDR_PHY_ODT_150_OHM } DDR_PHY_ODT; Description On-Die-Termination Value Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 715 This data type defines the ODT termination value. Remarks The actual definition of this enumeration is device-specific. DDR_CMD_REFRESH Macro File plib_ddr.h C #define DDR_CMD_REFRESH 0x00FFF801 Description This is macro DDR_CMD_REFRESH. DDR_PHY_PREAMBLE_DLY Enumeration Defines the PHY preamble delay value. File plib_ddr_help.h C typedef enum { DDR_PHY_PREAMBLE_DLY_2_0, DDR_PHY_PREAMBLE_DLY_1_5, DDR_PHY_PREAMBLE_DLY_1_0 } DDR_PHY_PREAMBLE_DLY; Description PHY Preamble Delay This data type defines the PHY preamble delay value. Remarks The actual definition of this enumeration is device-specific. DDR_PHY_SCL_BURST_MODE Enumeration Defines the burst mode for SCL. File plib_ddr_help.h C typedef enum { DDR_PHY_SCL_BURST_MODE_4, DDR_PHY_SCL_BURST_MODE_8 } DDR_PHY_SCL_BURST_MODE; Description PHY Preamble Delay This data type defines the burst mode for SCL. Remarks The actual definition of this enumeration is device-specific. DDR_PHY_SCL_DELAY Enumeration Defines the SCL delay. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 716 File plib_ddr_help.h C typedef enum { DDR_PHY_SCL_DELAY_SINGLE, DDR_PHY_SCL_DELAY_DOUBLE } DDR_PHY_SCL_DELAY; Description DDR Type This data type defines the SCL delay. Remarks The actual definition of this enumeration is device-specific. DDR_HOST_CMD_REG Enumeration Defines the DDR host command register. File plib_ddr_help.h C typedef enum { DDR_HOST_CMD_REG_100, DDR_HOST_CMD_REG_101, DDR_HOST_CMD_REG_102, DDR_HOST_CMD_REG_103, DDR_HOST_CMD_REG_104, DDR_HOST_CMD_REG_105, DDR_HOST_CMD_REG_106, DDR_HOST_CMD_REG_107, DDR_HOST_CMD_REG_108, DDR_HOST_CMD_REG_109, DDR_HOST_CMD_REG_110, DDR_HOST_CMD_REG_111, DDR_HOST_CMD_REG_112, DDR_HOST_CMD_REG_113, DDR_HOST_CMD_REG_114, DDR_HOST_CMD_REG_115, DDR_HOST_CMD_REG_200, DDR_HOST_CMD_REG_201, DDR_HOST_CMD_REG_202, DDR_HOST_CMD_REG_203, DDR_HOST_CMD_REG_204, DDR_HOST_CMD_REG_205, DDR_HOST_CMD_REG_206, DDR_HOST_CMD_REG_207, DDR_HOST_CMD_REG_208, DDR_HOST_CMD_REG_209, DDR_HOST_CMD_REG_210, DDR_HOST_CMD_REG_211, DDR_HOST_CMD_REG_212, DDR_HOST_CMD_REG_213, DDR_HOST_CMD_REG_214, DDR_HOST_CMD_REG_215 } DDR_HOST_CMD_REG; Description DDR Host Command Register this data type defines the DDR host command register. Remarks The actual definition of this enumeration is device-specific. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 717 DDR_MODULE_ID Enumeration File plib_ddr_help.h C typedef enum { DDR_ID_1, DDR_NUMBER_OF_MODULES } DDR_MODULE_ID; Members Members Description DDR_ID_1 DDR 1 DDR_NUMBER_OF_MODULES Total number of DDR modules available Description Enumeration: DDR_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. DDR_TARGET Enumeration Defines the different targets to which the DDR controller is connected. File plib_ddr_help.h C typedef enum { DDR_TARGET_CPU, DDR_TARGET_GC_IN, DDR_TARGET_GC_OUT, DDR_TARGET_GPU_IN, DDR_TARGET_GPU_OUT } DDR_TARGET; Description Targets This data type defines the different targets to which the DDR controller is connected. Remarks The actual definition of this enumeration is device-specific. Files Files Name Description plib_ddr.h Defines the DDR Peripheral Library Interface. Description This section lists the source and header files used by the library. plib_ddr.h Defines the DDR Peripheral Library Interface. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 718 Functions Name Description PLIB_DDR_AutoPchrgDisable Prevents the DDR controller from issuing an auto-precharge command to close the bank at the end of every user command. PLIB_DDR_AutoPchrgEnable Enables the DDR controller to issue an auto-precharge command to close the bank at the end of every user command. PLIB_DDR_AutoPchrgPowerDownDisable Prevents the DDR controller from automatically entering Precharge Power-down mode. PLIB_DDR_AutoPchrgPowerDownEnable Enables the DDR controller to automatically enter Precharge Power-down mode. PLIB_DDR_AutoPowerDownDisable Prevents the DDR controller from automatically entering Power-down mode. PLIB_DDR_AutoPowerDownEnable Enables the DDR controller to automatically enter Power-down mode. PLIB_DDR_AutoSelfRefreshDisable Prevents the DDR controller from automatically entering Self-refresh mode. PLIB_DDR_AutoSelfRefreshEnable Enables the DDR controller to automatically enter Self-refresh mode. PLIB_DDR_BankAddressSet Initializes the DDR controller memory configuration registers for bank address. PLIB_DDR_BigEndianSet Sets the DDR data endianness to big. PLIB_DDR_ChipSelectAddressSet Initializes the DDR controller memory configuration registers for Chip Select address. PLIB_DDR_CmdDataIsComplete Returns the value of the valid bit in the DDR2CMDISSUE register. This bit is cleared by hardware, when the SDRAM initialization data has been transmitted. PLIB_DDR_CmdDataSend Transmits the data in the command registers to the SDRAM. PLIB_DDR_CmdDataValid Indicates to the controller that the data in the command registers is valid. PLIB_DDR_CmdDataWrite Writes an SDRAM command word to a command register in the controller. PLIB_DDR_ColumnAddressSet Initializes the DDR controller memory configuration registers for the column address. PLIB_DDR_ControllerEnable Enables the controller for normal operations after SDRAM is initialized. PLIB_DDR_DataDelaySet Initializes the DDR controller with the data delays needed for the specific DDR in use. PLIB_DDR_ExistsAddressMapping Identifies whether the AddressMapping feature exists on the DDR module. PLIB_DDR_ExistsArbitrationControl Identifies whether the ArbitrationControl feature exists on the DDR module. PLIB_DDR_ExistsAutoPowerDown Identifies whether the AutoPowerDown feature exists on the DDR module. PLIB_DDR_ExistsAutoPrecharge Identifies whether the AutoPrecharge feature exists on the DDR module. PLIB_DDR_ExistsAutoSelfRefresh Identifies whether the AutoSelfRefresh feature exists on the DDR module. PLIB_DDR_ExistsDDRCommands Identifies whether the DDRCommands feature exists on the DDR module. PLIB_DDR_ExistsDDRControllerConfig Identifies whether the DDRControllerConfig feature exists on the DDR module. PLIB_DDR_ExistsODTConfig Identifies whether the ODTConfig feature exists on the DDR module. PLIB_DDR_ExistsPHY_DLLCalibration Identifies whether the PHY_DLLCalibration feature exists on the DDR module. PLIB_DDR_ExistsPHY_PadConfig Identifies whether the PHY_PadConfig feature exists on the DDR module. PLIB_DDR_ExistsPHY_SCLConfig Identifies whether the PHY_SCLConfig feature exists on the DDR module PLIB_DDR_ExistsRefreshConfig Identifies whether the RefreshConfig feature exists on the DDR module. PLIB_DDR_ExistsTimingDelays Identifies whether the TimingDelays feature exists on the DDR module PLIB_DDR_FullRateSet Sets the DDR controller to Full-rate mode. PLIB_DDR_HalfRateSet Sets the DDR controller to Half-rate mode. PLIB_DDR_LittleEndianSet Sets the DDR data endianness to little. PLIB_DDR_MaxCmdBrstCntSet Sets the maximum number of commands that can be written to the controller in Burst mode. PLIB_DDR_MaxPendingRefSet Initializes the DDR controller refresh configuration. PLIB_DDR_MinCommand Sets the minimum number of bursts to be serviced for a DDR target within (REQPER * 4) number of clocks. PLIB_DDR_MinLimit Sets the minimum number of bursts for a DDR target. PLIB_DDR_NumHostCmdsSet Sets the number of commands to be transmitted to the SDRAM. PLIB_DDR_OdtReadDisable Selects which Chip Select to disable ODT for data reads. PLIB_DDR_OdtReadEnable Selects which Chip Select to enable ODT for data reads. PLIB_DDR_OdtReadParamSet Sets the ODT parameters for data reads. PLIB_DDR_OdtWriteDisable Selects which Chip Select to disable ODT for data writes. PLIB_DDR_OdtWriteEnable Selects which Chip Select to enable ODT for data writes. PLIB_DDR_OdtWriteParamSet Sets the ODT parameters for data writes. PLIB_DDR_PHY_AddCtlDriveStrengthSet Sets the drive strength for the PHY address and control pads. PLIB_DDR_PHY_DataDriveStrengthSet Sets the drive strength for the PHY data pads. PLIB_DDR_PHY_DDRTypeSet Sets the DRAM type for the PHY. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 719 PLIB_DDR_PHY_DllMasterDelayStartSet Sets the start value of the digital DLL master delay line. PLIB_DDR_PHY_DllRecalibDisable Disables periodic recalibration of the internal digital DLL. PLIB_DDR_PHY_DllRecalibEnable Enables periodic recalibration of the internal digital DLL, and sets the recalibration period. PLIB_DDR_PHY_DriveStrengthSet Disables On Die Termination. PLIB_DDR_PHY_DrvStrgthCal Calibrates the pad NFET and PFET output impedance. PLIB_DDR_PHY_ExternalDllEnable Enables the use of an external DLL. PLIB_DDR_PHY_ExtraClockDisable Does not enable the drive pad for an extra clock cycle after a write burst. PLIB_DDR_PHY_ExtraClockEnable Enables the drive pad for an extra clock cycle after a write burst. PLIB_DDR_PHY_HalfRateSet Sets the PHY to half rate mode. PLIB_DDR_PHY_InternalDllEnable Enables the use of the internal digital DLL. PLIB_DDR_PHY_OdtCal Calibrates the pull-up and pull-down ODT impedance. PLIB_DDR_PHY_OdtCSDisable Disables ODT on Chip Select while running SCL test. PLIB_DDR_PHY_OdtCSEnable Enables ODT on Chip Select while running SCL test. PLIB_DDR_PHY_OdtDisable Disables On Die Termination. PLIB_DDR_PHY_OdtEnable Enables On Die Termination and sets the value. PLIB_DDR_PHY_PadReceiveDisable Disables pad receivers on bidirectional I/O. PLIB_DDR_PHY_PadReceiveEnable Enables pad receivers on bidirectional I/O. PLIB_DDR_PHY_PreambleDlySet Sets the length of the preamble for data writes. PLIB_DDR_PHY_ReadCASLatencySet Sets the read CAS latency while running SCL test. PLIB_DDR_PHY_SCLCapClkDelaySet Sets capture clock delay during SCL. PLIB_DDR_PHY_SCLDDRClkDelaySet Sets DDR clock delay during SCL. PLIB_DDR_PHY_SCLDelay Disables ODT on Chip Select while running SCL test. PLIB_DDR_PHY_SCLEnable Enables SCL on the Chip Select 'cs'. PLIB_DDR_PHY_SCLStart Runs PHY Self Calibration. PLIB_DDR_PHY_SCLStatus Checks status of PHY Self Calibration. PLIB_DDR_PHY_SCLTestBurstModeSet Sets the burst mode of the DRAM while running SCL test. PLIB_DDR_PHY_WriteCASLatencySet Sets the write CAS latency while running SCL test. PLIB_DDR_PHY_WriteCmdDelayDisable Disables write command delay. PLIB_DDR_PHY_WriteCmdDelayEnable Enables write command delay. The extra delay is needed for devices with even write latency (WL). PLIB_DDR_PowerDownDelaySet Initializes the DDR controller with the power down delays needed for the specific DDR in use. PLIB_DDR_PrechargAllBanksSet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_PrechargeToRASDelaySet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_RASToCASDelaySet Initializes the DDR controller with the row/column address delays needed for the specific DDR in use. PLIB_DDR_RASToPrechargeDelaySet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_RASToRASBankDelaySet Initializes the DDR controller with the row/column address delays needed for the specific DDR in use. PLIB_DDR_RASToRASDelaySet Initializes the DDR controller with the row/column address delays needed for the specific DDR in use. PLIB_DDR_ReadReadDelaySet Initializes the DDR controller with the read/write delays needed for the specific DDR in use. PLIB_DDR_ReadToPrechargeDelaySet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_ReadWriteDelaySet Initializes the DDR controller with the read/write delays needed for the specific DDR in use. PLIB_DDR_RefreshTimingSet Initializes the DDR controller refresh configuration. PLIB_DDR_ReqPeriod Sets the timeout for MINCMD number of bursts to be serviced for a DDR target. PLIB_DDR_RowAddressSet Initializes the DDR controller memory configuration registers for row address. PLIB_DDR_SelfRefreshDelaySet Initializes the DDR controller with the self-refresh delays needed for the specific DDR in use. PLIB_DDR_TfawDelaySet Initializes the DDR controller with the four-bank activation window needed for the specific DDR in use. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 720 PLIB_DDR_WriteReadDelaySet Initializes the DDR controller with the read/write delays needed for the specific DDR in use. PLIB_DDR_WriteToPrechargeDelaySet Initializes the DDR controller with the read/write precharge delays needed for the specific DDR in use. PLIB_DDR_WriteWriteDelaySet Initializes the DDR controller with the read/write delays needed for the specific DDR in use. Macros Name Description DDR_CMD_IDLE_NOP DDR_CMD_LOAD_MODE This is macro DDR_CMD_LOAD_MODE. DDR_CMD_PRECHARGE_ALL This is macro DDR_CMD_PRECHARGE_ALL. DDR_CMD_REFRESH This is macro DDR_CMD_REFRESH. Description Dual Data Rate (DDR) SDRAM Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the DDR Peripheral Library for Microchip microcontrollers. The definitions in this file are for the DDR module. File Name plib_ddr.h Company Microchip Technology Inc. Peripheral Libraries Help Dual Data Rate (DDR) SDRAM Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 721 EBI Peripheral Library This section describes the External Bus Interface (EBI) Peripheral Library. Introduction This library provides a low-level abstraction of the EBI Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The External Bus Interface (EBI) allows for external physical memory to be mapped into the kernels virtual memory map. The External Bus Interface (EBI) module provides a high-speed, convenient way to interface external parallel memory devices to the PIC32 family device. With the EBI module, it is possible to_connect_asynchronous SRAM and NOR Flash devices, as well as non-memory devices such as camera sensors. The module also supports Low-Cost Controllerless (LCC) Graphics devices. Using the Library This topic describes the basic architecture of the EBI Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_ebi.h The interface to the EBI Peripheral library is defined in the plib_ebi.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the EBI Peripheral library must include peripheral.h. Library File: The EBI Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the Peripheral interacts with the framework. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the EBI module. Library Interface Section Description Get Functions These functions can be used to return the status of a feature. Peripheral Libraries Help EBI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 722 Set Functions These functions can be used to configure features. Feature Existence Functions Lists the interface routines that describe whether or not the feature is supported by the device. How the Library Works Before using the EBI module, it must be enabled by the application developer(s). To work correctly, the device characteristics of the attached Memory/Flash must be set with the functions in this library. The Characteristics of the Memory/Flash will be found in the specific device data sheet. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. Configuring the Library The library is configured for the supported EBI module when the processor is chosen in the MPLAB X IDE. Library Interface a) Get Functions Name Description PLIB_EBI_AddressHoldTimeGet Returns the address hold time. PLIB_EBI_AddressSetupTimeGet Returns the setup hold time. PLIB_EBI_BaseAddressGet Returns the base address set for each Chip Select. PLIB_EBI_ControlEnableGet Returns the status of the EBI enable bit. PLIB_EBI_DataTurnAroundTimeGet Returns the data turn-around time set for the EBI bus. PLIB_EBI_FlashPowerDownModeGet Returns the set power-down state. PLIB_EBI_FlashResetPinGet Sets the control use of Flash Reset pin. PLIB_EBI_PageModeGet Returns the Paging mode settings. PLIB_EBI_PageReadCycleTimeGet Returns the cycle time for a page read. PLIB_EBI_ReadCycleTimeGet Returns the read time in the number of clock cycles. PLIB_EBI_ReadyModeGet Returns whether or not Ready mode was set. PLIB_EBI_StaticMemoryWidthRegisterGet Returns the set width of the data bus. PLIB_EBI_WritePulseWidthGet Returns the set hold time in clock cycles. PLIB_EBI_MemoryPageSizeGet Returns the Paging mode settings. PLIB_EBI_FlashTimingGet Returns the set Flash timing for external Flash. b) Set Functions Name Description PLIB_EBI_AddressPinEnableBitsSet Sets the address pins used for EBI. PLIB_EBI_BaseAddressSet Sets the base address for physical memory at each Chip Select pin. PLIB_EBI_ByteSelectPinSet Sets the data Byte Select High <15:8> and Low <7:0> enable pins for use. PLIB_EBI_ChipSelectEnableSet Sets the Chip Select pins for use with the EBI or GPIO. PLIB_EBI_DataEnableSet Sets the use of Data Byte Select Pins, High and Low, for control with EBI or GPIO. PLIB_EBI_FlashPowerDownModeSet Sets the pin state for Flash devices on Power-down and Reset. PLIB_EBI_FlashResetPinSet Sets the control use of the Flash Reset pin. PLIB_EBI_FlashTimingSet Sets the timing for hold in reset for external Flash. PLIB_EBI_MemoryCharacteristicsSet Sets the characteristics for memory or attached devices attached to the specified pin. PLIB_EBI_MemoryPagingSet Sets the size of the memory page if paging is used. PLIB_EBI_MemoryTimingConfigSet Sets the cycle time for page reading. PLIB_EBI_ReadyPin1ConfigSet Sets the control use of ReadyPin1 and inverts the status. PLIB_EBI_ReadyPin2ConfigSet Sets the control use of ReadyPin2 and inverts the status. PLIB_EBI_ReadyPin3ConfigSet Sets the control use of ReadyPin3 and inverts the status. PLIB_EBI_ReadyPinSensSet Sets the sensitivity of the Ready pin. PLIB_EBI_StaticMemoryWidthRegisterSet Sets the data width of static memory. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 723 PLIB_EBI_WriteOutputControlSet Sets the Write Enable and Output Enable control pins. PLIB_EBI_ControlEnableSet Sets the EBI bus ON/OFF enable bit. PLIB_EBI_ReadyModeSet Sets the use of Ready mode for each pin. c) Feature Existence Functions Name Description PLIB_EBI_ExistsAddressHoldTime Identifies whether the AddressHoldTime feature exists on the EBI module. PLIB_EBI_ExistsAddressPinEnableBits Identifies whether the AddressPinEnableBits feature exists on the EBI module. PLIB_EBI_ExistsAddressSetupTime Identifies whether the AddressSetupTime feature exists on the EBI module. PLIB_EBI_ExistsBaseAddress Identifies whether the Base_Address feature exists on the EBI module. PLIB_EBI_ExistsByteSelectPin Identifies whether the ByteSelectPin feature exists on the EBI module. PLIB_EBI_ExistsChipSelectEnable Identifies whether the ChipSelectEnable feature exists on the EBI module. PLIB_EBI_ExistsControlEnable Identifies whether the ControlEnable feature exists on the EBI module. PLIB_EBI_ExistsDataEnable Identifies whether the DataEnable feature exists on the EBI module. PLIB_EBI_ExistsDataTurnAroundTime Identifies whether the DataTurnAroundTime feature exists on the EBI module. PLIB_EBI_ExistsFlashPowerDownMode Identifies whether the FlashPowerDownMode feature exists on the EBI module. PLIB_EBI_ExistsFlashResetPin Identifies whether the FlashResetPin feature exists on the EBI module. PLIB_EBI_ExistsFlashTiming Identifies whether the FlashTiming feature exists on the EBI module. PLIB_EBI_ExistsMemoryCharacteristics Identifies whether the MemoryCharacteristics feature exists on the EBI module. PLIB_EBI_ExistsMemoryPaging Identifies whether the MemoryPaging feature exists on the EBI module. PLIB_EBI_ExistsMemoryTimingConfig Identifies whether the MemoryTimingConfig feature exists on the EBI module. PLIB_EBI_ExistsPageMode Identifies whether the PageMode feature exists on the EBI module. PLIB_EBI_ExistsPageReadTime Identifies whether the PageReadTime feature exists on the EBI module. PLIB_EBI_ExistsReadCycleTime Identifies whether the ReadCycleTime feature exists on the EBI module. PLIB_EBI_ExistsReadyMode Identifies whether the ReadyMode feature exists on the EBI module. PLIB_EBI_ExistsReadyPin1Config Identifies whether the ReadyPin1Config feature exists on the EBI module. PLIB_EBI_ExistsReadyPin2Config Identifies whether the ReadyPin2Config feature exists on the EBI module. PLIB_EBI_ExistsReadyPin3Config Identifies whether the ReadyPin3Config feature exists on the EBI module. PLIB_EBI_ExistsReadyPinSens Identifies whether the ReadyPinSens feature exists on the EBI module PLIB_EBI_ExistsStaticMemoryWidthRegister Identifies whether the StaticMemoryWidthRegister feature exists on the EBI module. PLIB_EBI_ExistsWriteOutputControl Identifies whether the WriteOutputControl feature exists on the EBI module. PLIB_EBI_ExistsWritePulseWidth Identifies whether the WritePulseWidth feature exists on the EBI module. d) Data Types and Constants Name Description EBI_ADDRESS_PORT Selects the EBI address port. EBI_CS_TIMING Selects the timing register set for Chip Select. EBI_MEMORY_SIZE Selects the memory size for Chip Select. EBI_MEMORY_TYPE Selects the memory type for Chip Select. EBI_MODULE_ID Identifies the supported EBI modules. EBI_PAGE_SIZE Selects the page size for the page mode device. EBI_STATIC_MEMORY_WIDTH Selects the static memory width for the register EBISMTx. Description This section describes the Application Programming Interface (API) functions of the EBI Peripheral Library. Refer to each section for a detailed description. a) Get Functions PLIB_EBI_AddressHoldTimeGet Function Returns the address hold time. File plib_ebi.h Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 724 C int PLIB_EBI_AddressHoldTimeGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns Returns an integer, which is the Address and Data Hold time in the number of clocks. Description This function returns the address and data hold time. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific Chip Select pin Function PLIB_EBI_AddressHoldTimeGet ( EBI_MODULE_ID index,int ChipSelectNumber) PLIB_EBI_AddressSetupTimeGet Function Returns the setup hold time. File plib_ebi.h C int PLIB_EBI_AddressSetupTimeGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns Returns an integer, which is the address setup time in the number of clocks. Description This function returns the setup hold time. A value of '0' is only valid in the case of SSRAM. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific Chip Select pin Function PLIB_EBI_AddressSetupTimeGet ( EBI_MODULE_ID index,int ChipSelectNumber) PLIB_EBI_BaseAddressGet Function Returns the base address set for each Chip Select. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 725 File plib_ebi.h C uint32_t PLIB_EBI_BaseAddressGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns Returns an unsigned integer that is the physical address of the attached device. Description This function returns the base address for each Chip Select pin. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies which Chip Select address pin address is being read Function PLIB_EBI_BaseAddressGet ( EBI_MODULE_ID index, int ChipSelectNumber) PLIB_EBI_ControlEnableGet Function Returns the status of the EBI enable bit. File plib_ebi.h C bool PLIB_EBI_ControlEnableGet(EBI_MODULE_ID index); Returns Boolean: • 1 = The EBI module is ON • 0 = The EBI module is OFF Description This function returns the status of the EBI enable bit. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ControlEnableGet ( EBI_MODULE_ID index) Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 726 PLIB_EBI_DataTurnAroundTimeGet Function Returns the data turn-around time set for the EBI bus. File plib_ebi.h C int PLIB_EBI_DataTurnAroundTimeGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns Returns an integer, which is the number of clock cycles that is set in the turn-around register. Description This function returns the data turn-around time set for the EBI Bus. Returns the clock cycles (0-7) for static memory between read-to-write, write-to-read, and read-to-read when Chip Select changes. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific Chip Select pin Function PLIB_EBI_DataTurnAroundTimeGet ( EBI_MODULE_ID index,int ChipSelectNumber) PLIB_EBI_FlashPowerDownModeGet Function Returns the set power-down state. File plib_ebi.h C bool PLIB_EBI_FlashPowerDownModeGet(EBI_MODULE_ID index); Returns A bool, depending on the setting of PLIB_EBI_FlashPowerDownModeSet. Description This function returns the set power-down state. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_FlashPowerDownModeGet ( EBI_MODULE_ID index) Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 727 PLIB_EBI_FlashResetPinGet Function Sets the control use of Flash Reset pin. File plib_ebi.h C bool PLIB_EBI_FlashResetPinGet(EBI_MODULE_ID index); Returns Returns a Boolean. Description This function set the control use of the Flash Reset pin. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_FlashResetPinGet ( EBI_MODULE_ID index) PLIB_EBI_PageModeGet Function Returns the Paging mode settings. File plib_ebi.h C bool PLIB_EBI_PageModeGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns • 1 = Page Mode is used • 0 = Page Mode is not used Description This function returns the state of the register PAGEMODE. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific Chip Select pin Function PLIB_EBI_PageModeGet ( EBI_MODULE_ID index,int ChipSelectNumber) Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 728 PLIB_EBI_PageReadCycleTimeGet Function Returns the cycle time for a page read. File plib_ebi.h C int PLIB_EBI_PageReadCycleTimeGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns Returns an integer, which is the number of clock cycles used to read a memory page. Description This function returns the cycle time for a page read. Read cycle time = TPRC + 1cycle. The value set and return are the same, the controller performs the read on the next clock, which is why there is a +1. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific Chip Select pin Function PLIB_EBI_PageReadCycleTimeGet ( EBI_MODULE_ID index,int ChipSelectNumber) PLIB_EBI_ReadCycleTimeGet Function Returns the read time in the number of clock cycles. File plib_ebi.h C int PLIB_EBI_ReadCycleTimeGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns Returns an integer, which is the read cycle time in system clocks. Description This function returns the read time in number of clock cycles. Read Cycle time = TRC +1 clock cycle. The controller will always take one extra clock (the next clock) for a Read Cycle. The return will be the time set by the user. Setting a Read Cycle time to a '0' will return a '0' when read, but the controller will add '1' to that value for the next available clock. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 729 ChipSelectNumber Identifies which Chip Select number to which the device is attached Function PLIB_EBI_ReadCycleTimeGet ( EBI_MODULE_ID index, int ChipSelectNumber) PLIB_EBI_ReadyModeGet Function Returns whether or not Ready mode was set. File plib_ebi.h C bool PLIB_EBI_ReadyModeGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns This function returns a bool. • 1 = Ready input is used • 0 = Ready input is not used Description This function returns the state of the register RDYMODE. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific Chip Select pin Function PLIB_EBI_ReadyModeGet ( EBI_MODULE_ID index, int ChipSelectNumber) PLIB_EBI_StaticMemoryWidthRegisterGet Function Returns the set width of the data bus. File plib_ebi.h C EBI_STATIC_MEMORY_WIDTH PLIB_EBI_StaticMemoryWidthRegisterGet(EBI_MODULE_ID index, int RegisterNumber); Returns An enum type, which is the bus mode in use. Description This function returns the set width of the data bus. Remarks None. Preconditions None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 730 Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_StaticMemoryWidthRegisterGet ( EBI_MODULE_ID index, int RegisterNumber) PLIB_EBI_WritePulseWidthGet Function Returns the set hold time in clock cycles. File plib_ebi.h C int PLIB_EBI_WritePulseWidthGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns Returns an integer, which is the number of clock cycles to which the write pulse width is set. Description This function returns the set hold time in clock cycles. Write Pulse with = TWP + 1 clock cycle. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific Chip Select pin Function PLIB_EBI_WritePulseWidthGet ( EBI_MODULE_ID index,int ChipSelectNumber) PLIB_EBI_MemoryPageSizeGet Function Returns the Paging mode settings. File plib_ebi.h C EBI_PAGE_SIZE PLIB_EBI_MemoryPageSizeGet(EBI_MODULE_ID index, int ChipSelectNumber); Returns Size of the memory page. Description This function returns the state of the register PAGESIZE. Remarks None. Preconditions None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 731 Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific Chip Select pin Function PLIB_EBI_MemoryPageSizeGet ( EBI_MODULE_ID index, int ChipSelectNumber) PLIB_EBI_FlashTimingGet Function Returns the set Flash timing for external Flash. File plib_ebi.h C int PLIB_EBI_FlashTimingGet(EBI_MODULE_ID index); Returns Returns an integer, which is the number of clock cycles. Description This function returns the set number of clock cycles to hold the external Flash memory in reset. Remarks None. Preconditions MemoryType must be set to Flash. Function PLIB_EBI_FlashTimingGet ( EBI_MODULE_ID index) b) Set Functions PLIB_EBI_AddressPinEnableBitsSet Function Sets the address pins used for EBI. File plib_ebi.h C void PLIB_EBI_AddressPinEnableBitsSet(EBI_MODULE_ID index, EBI_ADDRESS_PORT AddressPort); Returns None. Description This function sets the address pins used for EBI. Remarks None. Preconditions None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 732 Parameters Parameters Description index Identifier for the device instance AddressPort Identifies how many pins are used for addressing on the EBI bus Function PLIB_EBI_AddressPinEnableBitsSet ( EBI_MODULE_ID index, EBI_ADDRESS_PORT AddressPort) PLIB_EBI_BaseAddressSet Function Sets the base address for physical memory at each Chip Select pin. File plib_ebi.h C void PLIB_EBI_BaseAddressSet(EBI_MODULE_ID index, int ChipSelectNumber, uint32_t BaseAddress); Returns None. Description This function sets the base address for physical memory at each Chip Select pin. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies which Chip Select address pin is being assigned an address BaseAddress A physical address for memory Function PLIB_EBI_BaseAddressSet( EBI_MODULE_ID index, int ChipSelectNumber, uint32_t BaseAddress) PLIB_EBI_ByteSelectPinSet Function Sets the data Byte Select High <15:8> and Low <7:0> enable pins for use. File plib_ebi.h C void PLIB_EBI_ByteSelectPinSet(EBI_MODULE_ID index, bool ByteSelect0, bool ByteSelect1); Returns None. Description This function sets the data Byte Select High <15:8> and Low <7:0> enable pins for use. If the system uses Byte Select High/Low pins for the data, the pins must be enabled for use in the EBI controller. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 733 Remarks None. Preconditions The EBIDEN0 and EBIDEN1 registers must first be enabled, which is done using the function PLIB_EBI_DataEnableSet. Parameters Parameters Description index Identifier for the device instance ByteSelect0 Identifies the Lower Byte Select Pin for enabling ByteSelect1 Identifies the Upper Byte Select Pin for enabling Function PLIB_EBI_ByteSelectPinSet ( EBI_MODULE_ID index, bool ByteSelect0, bool ByteSelect1) PLIB_EBI_ChipSelectEnableSet Function Sets the Chip Select pins for use with the EBI or GPIO. File plib_ebi.h C void PLIB_EBI_ChipSelectEnableSet(EBI_MODULE_ID index, bool ChipSelect0, bool ChipSelect1, bool ChipSelect2, bool ChipSelect3); Returns None. Description This functions sets which Chip Select pins to use with the EBI or GPIO. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelect0 Identifies control of Chip Select 0 for enabling ChipSelect1 Identifies control of Chip Select 1 for enabling ChipSelect2 Identifies control of Chip Select 2 for enabling ChipSelect3 Identifies control of Chip Select 3 for enabling Function PLIB_EBI_ChipSelectEnableSet ( EBI_MODULE_ID index, bool ChipSelect0, bool ChipSelect1, bool ChipSelect2, bool ChipSelect3) PLIB_EBI_DataEnableSet Function Sets the use of Data Byte Select Pins, High and Low, for control with EBI or GPIO. File plib_ebi.h Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 734 C void PLIB_EBI_DataEnableSet(EBI_MODULE_ID index, bool DataUpperByte, bool DataLowerByte); Returns None. Description This function sets the use of the Data Byte Select Pins, High and Low, for control with EBI or GPIO. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance DataUpperByte Identifies control of Upper Data Byte for enabling DataLowerByte Identifies control of Lower Data Byte for enabling Function PLIB_EBI_DataEnableSet ( EBI_MODULE_ID index, bool DataUpperByte, bool DataLowerByte) PLIB_EBI_FlashPowerDownModeSet Function Sets the pin state for Flash devices on Power-down and Reset. File plib_ebi.h C void PLIB_EBI_FlashPowerDownModeSet(EBI_MODULE_ID index, bool FlashPowerDownMode); Returns None. Description This function sets the pin state for Flash devices upon a Power-down and Reset. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance FlashPowerDownMode A bool, which sets the power-down state for Flash memory Function PLIB_EBI_FlashPowerDownModeSet ( EBI_MODULE_ID index, bool FlashPowerDownMode) PLIB_EBI_FlashResetPinSet Function Sets the control use of the Flash Reset pin. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 735 File plib_ebi.h C void PLIB_EBI_FlashResetPinSet(EBI_MODULE_ID index, bool FlashResetPin); Returns None. Description This function sets the control use of the Flash Reset pin. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance FlashReadPin Flash Reset pin is used Function PLIB_EBI_FlashResetPinSet ( EBI_MODULE_ID index, bool FlashReadPin) PLIB_EBI_FlashTimingSet Function Sets the timing for hold in reset for external Flash. File plib_ebi.h C void PLIB_EBI_FlashTimingSet(EBI_MODULE_ID index, int FlashTiming); Returns None. Description This function sets the number of clock cycles to hold the external Flash memory in reset. Remarks None. Preconditions NOR Flash must be used with EBI instead of SRAM. Parameters Parameters Description index Identifier for the device instance FlashTiming An integer, which is the number of clock cycles Function PLIB_EBI_FlashTimingSet ( EBI_MODULE_ID index, int FlashTiming) Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 736 PLIB_EBI_MemoryCharacteristicsSet Function Sets the characteristics for memory or attached devices attached to the specified pin. File plib_ebi.h C void PLIB_EBI_MemoryCharacteristicsSet(EBI_MODULE_ID index, int ChipSelectNumber, EBI_MEMORY_TYPE MemoryType, EBI_MEMORY_SIZE MemorySize, EBI_CS_TIMING TimingReg); Returns None. Description This function sets the characteristics for memory or attached devices attached to the specified pin. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies which Chip Select pin is used MemoryType Identifies which memory is used MemorySize An enum type, which sets the size of the attached memory device TimingRegSet Identifies the timing register Function PLIB_EBI_MemoryCharacteristicsSet( EBI_MODULE_ID index, int ChipSelectNumber, EBI_MEMORY_TYPE MemoryType, EBI_MEMORY_SIZE MemorySize, EBI_CS_TIMING TimingReg) PLIB_EBI_MemoryPagingSet Function Sets the size of the memory page if paging is used. File plib_ebi.h C void PLIB_EBI_MemoryPagingSet(EBI_MODULE_ID index, int ChipSelectNumber, bool PageMode, EBI_PAGE_SIZE MemoryPageSize); Returns • 1 = Device supports Page mode • 0 = Device does not support Page mode Description This function sets the size of the memory page if paging is used. Remarks None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 737 Preconditions None. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Sets for that Chip Select pin <3:0> PageMode Enable or disable Page mode MemoryPageSize Size of memory pages Function PLIB_EBI_MemoryPagingSet ( EBI_MODULE_ID index, int ChipSelectNumber, bool PageMode, EBI_PAGE_SIZE MemoryPageSize) PLIB_EBI_MemoryTimingConfigSet Function Sets the cycle time for page reading. File plib_ebi.h C void PLIB_EBI_MemoryTimingConfigSet(EBI_MODULE_ID index, int CS_Timing_Reg, int PageReadTime, int DataTurnAroundTime, int WritePulseWidth, int AddressHoldTime, int AddressSetupTime, int ReadCycleTime); Returns None. Description This function sets the cycle time for page reading. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance CS_Timing_Reg Identifies which Chip Select Timing register to use EBISMT<0:2> PageReadTime The clock cycle needed for a Memory Page read DataTurnAroundTime Time between read-to-write, write-to-read, and read-to-read when Chip Select changes state. WritePulseWidth The clock cycles needed for a memory write AddressHoldTime The clock time needed for the address bus to hold AddressSetupTime The time needed for the address to settle ReadCycleTime _nt_ Function PLIB_EBI_MemoryTimingConfigSet( EBI_MODULE_ID index, int CS_Timing_Reg, int PageReadTime, int DataTurnAroundTime, int WritePulseWidth, int AddressHoldTime, int AddressSetupTime, int ReadCycleTime) Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 738 PLIB_EBI_ReadyPin1ConfigSet Function Sets the control use of ReadyPin1 and inverts the status. File plib_ebi.h C void PLIB_EBI_ReadyPin1ConfigSet(EBI_MODULE_ID index, bool ReadyPin1Enable, bool ReadyPin1Invert); Returns None. Description This function sets the control use of ReadyPin1, and then inverts the status. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ReadyPin1Invert Identifies the ON/OFF for invert ReadyPin1Enable Identifies if this pin is used by the control part Function PLIB_EBI_ReadyPin1ConfigSet ( EBI_MODULE_ID index, bool ReadyPin1Enable, bool ReadyPin1Invert) PLIB_EBI_ReadyPin2ConfigSet Function Sets the control use of ReadyPin2 and inverts the status. File plib_ebi.h C void PLIB_EBI_ReadyPin2ConfigSet(EBI_MODULE_ID index, bool ReadyPin2Enable, bool ReadyPin2Invert); Returns None. Description This function sets the control use of ReadyPin2 and inverts the status. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ReadyPin2Invert Identifies the ON/OFF for invert ReadyPin2Enable Identifies if this pin is used by the control part Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 739 Function PLIB_EBI_ReadyPin2ConfigSet ( EBI_MODULE_ID index, bool ReadyPin2Enable, bool ReadyPin2Invert) PLIB_EBI_ReadyPin3ConfigSet Function Sets the control use of ReadyPin3 and inverts the status. File plib_ebi.h C void PLIB_EBI_ReadyPin3ConfigSet(EBI_MODULE_ID index, bool ReadyPin3Enable, bool ReadyPin3Invert); Returns None. Description This function sets the control use of ReadyPin3, and then inverts the status. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance ReadyPin3Invert Identifies the ON/OFF for invert ReadyPin3Enable Identifies if this pin is used by the control part Function PLIB_EBI_ReadyPin3ConfigSet ( EBI_MODULE_ID index, bool ReadyPin3Enable, bool ReadyPin3Invert) PLIB_EBI_ReadyPinSensSet Function Sets the sensitivity of the Ready pin. File plib_ebi.h C void PLIB_EBI_ReadyPinSensSet(EBI_MODULE_ID index, bool SensitivityControl); Returns None. Description This function sets the sensitivity of the Ready pin. Remarks None. Preconditions None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 740 Parameters Parameters Description index Identifier for the device instance SensitivityControl Selection edge or level detection Function PLIB_EBI_ReadyPinSensSet ( EBI_MODULE_ID index, bool SensitivityControl) PLIB_EBI_StaticMemoryWidthRegisterSet Function Sets the data width of static memory. File plib_ebi.h C void PLIB_EBI_StaticMemoryWidthRegisterSet(EBI_MODULE_ID index, int RegisterNumber, EBI_STATIC_MEMORY_WIDTH StaticMemoryWidthRegister); Returns None. Description This function sets the data width of static memory. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance RegisterNumber The ID for the register being set StaticMemoryWidthRegister Identifies a bus width of either 8 bits or 16 bits Function PLIB_EBI_StaticMemoryWidthRegisterSet ( EBI_MODULE_ID index, int RegisterNumber, EBI_STATIC_MEMORY_WIDTH StaticMemoryWidthRegister) PLIB_EBI_WriteOutputControlSet Function Sets the Write Enable and Output Enable control pins. File plib_ebi.h C void PLIB_EBI_WriteOutputControlSet(EBI_MODULE_ID index, bool WriteEnable, bool OutputEnable); Returns None. Description This function sets the Write Enable and Output Enable control pins. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 741 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance WriteEnable Used for enabling Write Enable OutputEnable Used for enabling Output Enable Function PLIB_EBI_WriteOutputControlSet ( EBI_MODULE_ID index, bool WriteEnable, bool OutputEnable) PLIB_EBI_ControlEnableSet Function Sets the EBI bus ON/OFF enable bit. File plib_ebi.h C void PLIB_EBI_ControlEnableSet(EBI_MODULE_ID index, bool EnableBit); Returns None. Description This function sets the EBI bus ON/OFF enable bit. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance EnableBit Identifies the enable bit Function PLIB_EBI_ControlEnableSet ( EBI_MODULE_ID index, bool EnableBit) PLIB_EBI_ReadyModeSet Function Sets the use of Ready mode for each pin. File plib_ebi.h C void PLIB_EBI_ReadyModeSet(EBI_MODULE_ID index, bool ReadyPin0, bool ReadyPin1, bool ReadyPin2); Returns None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 742 Description This function sets the use of Ready mode for each pin. The attached device will either pull the ready pin high or low. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance; ReadyPin0, ReadyPin1, ReadyPin2 ReadyPin(x) Identifies the ready pin (1-3) Function PLIB_EBI_ReadyModeSet ( EBI_MODULE_ID index, bool ReadyPin0, bool ReadyPin1, bool ReadyPin2) c) Feature Existence Functions PLIB_EBI_ExistsAddressHoldTime Function Identifies whether the AddressHoldTime feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsAddressHoldTime(EBI_MODULE_ID index); Returns • true - The AddressHoldTime feature is supported on the device • false - The AddressHoldTime feature is not supported on the device Description This function identifies whether the AddressHoldTime feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_AddressHoldTimeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsAddressHoldTime( EBI_MODULE_ID index ) PLIB_EBI_ExistsAddressPinEnableBits Function Identifies whether the AddressPinEnableBits feature exists on the EBI module. File plib_ebi.h Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 743 C bool PLIB_EBI_ExistsAddressPinEnableBits(EBI_MODULE_ID index); Returns • true - The AddressPinEnableBits feature is supported on the device • false - The AddressPinEnableBits feature is not supported on the device Description This function identifies whether the AddressPinEnableBits feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_AddressPinEnableBitsSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsAddressPinEnableBits( EBI_MODULE_ID index ) PLIB_EBI_ExistsAddressSetupTime Function Identifies whether the AddressSetupTime feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsAddressSetupTime(EBI_MODULE_ID index); Returns • true - The AddressSetupTime feature is supported on the device • false - The AddressSetupTime feature is not supported on the device Description This function identifies whether the AddressSetupTime feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_AddressSetupTimeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsAddressSetupTime( EBI_MODULE_ID index ) PLIB_EBI_ExistsBaseAddress Function Identifies whether the Base_Address feature exists on the EBI module. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 744 File plib_ebi.h C bool PLIB_EBI_ExistsBaseAddress(EBI_MODULE_ID index); Returns • true - The Base_Address feature is supported on the device • false - The Base_Address feature is not supported on the device Description This function identifies whether the Base_Address feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_BaseAddressSet • PLIB_EBI_BaseAddressGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsBaseAddress( EBI_MODULE_ID index ) PLIB_EBI_ExistsByteSelectPin Function Identifies whether the ByteSelectPin feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsByteSelectPin(EBI_MODULE_ID index); Returns • true - The ByteSelectPin feature is supported on the device • false - The ByteSelectPin feature is not supported on the device Description This function identifies whether the ByteSelectPin feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_ByteSelectPinSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsByteSelectPin( EBI_MODULE_ID index ) Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 745 PLIB_EBI_ExistsChipSelectEnable Function Identifies whether the ChipSelectEnable feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsChipSelectEnable(EBI_MODULE_ID index); Returns • true - The ChipSelectEnable feature is supported on the device • false - The ChipSelectEnable feature is not supported on the device Description This function identifies whether the ChipSelectEnable feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_ChipSelectEnableSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsChipSelectEnable( EBI_MODULE_ID index ) PLIB_EBI_ExistsControlEnable Function Identifies whether the ControlEnable feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsControlEnable(EBI_MODULE_ID index); Returns • true - The ControlEnable feature is supported on the device • false - The ControlEnable feature is not supported on the device Description This function identifies whether the ControlEnable feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ControlEnableSet • PLIB_EBI_ControlEnableGet Remarks None. Preconditions None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 746 Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsControlEnable( EBI_MODULE_ID index ) PLIB_EBI_ExistsDataEnable Function Identifies whether the DataEnable feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsDataEnable(EBI_MODULE_ID index); Returns • true - The DataEnable feature is supported on the device • false - The DataEnable feature is not supported on the device Description This function identifies whether the DataEnable feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_DataEnableSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsDataEnable( EBI_MODULE_ID index ) PLIB_EBI_ExistsDataTurnAroundTime Function Identifies whether the DataTurnAroundTime feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsDataTurnAroundTime(EBI_MODULE_ID index); Returns • true - The DataTurnAroundTime feature is supported on the device • false - The DataTurnAroundTime feature is not supported on the device Description This function identifies whether the DataTurnAroundTime feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_DataTurnAroundTimeGet Remarks None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 747 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsDataTurnAroundTime( EBI_MODULE_ID index ) PLIB_EBI_ExistsFlashPowerDownMode Function Identifies whether the FlashPowerDownMode feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsFlashPowerDownMode(EBI_MODULE_ID index); Returns • true - The FlashPowerDownMode feature is supported on the device • false - The FlashPowerDownMode feature is not supported on the device Description This function identifies whether the FlashPowerDownMode feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_FlashPowerDownModeSet • PLIB_EBI_FlashPowerDownModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsFlashPowerDownMode( EBI_MODULE_ID index ) PLIB_EBI_ExistsFlashResetPin Function Identifies whether the FlashResetPin feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsFlashResetPin(EBI_MODULE_ID index); Returns • true - The FlashResetPin feature is supported on the device • false - The FlashResetPin feature is not supported on the device Description This function identifies whether the FlashResetPin feature is available on the EBI module. When this function returns true, these functions are supported on the device: Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 748 • PLIB_EBI_FlashResetPinSet • PLIB_EBI_FlashResetPinGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsFlashResetPin( EBI_MODULE_ID index ) PLIB_EBI_ExistsFlashTiming Function Identifies whether the FlashTiming feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsFlashTiming(EBI_MODULE_ID index); Returns • true - The FlashTiming feature is supported on the device • false - The FlashTiming feature is not supported on the device Description This function identifies whether the FlashTiming feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_FlashTimingSet • PLIB_EBI_FlashTimingGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsFlashTiming( EBI_MODULE_ID index ) PLIB_EBI_ExistsMemoryCharacteristics Function Identifies whether the MemoryCharacteristics feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsMemoryCharacteristics(EBI_MODULE_ID index); Returns • true - The MemoryCharacteristics feature is supported on the device Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 749 • false - The MemoryCharacteristics feature is not supported on the device Description This function identifies whether the MemoryCharacteristics feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_MemoryCharacteristicsSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsMemoryCharacteristics( EBI_MODULE_ID index ) PLIB_EBI_ExistsMemoryPaging Function Identifies whether the MemoryPaging feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsMemoryPaging(EBI_MODULE_ID index); Returns • true - The MemoryPaging feature is supported on the device • false - The MemoryPaging feature is not supported on the device Description This function identifies whether the MemoryPaging feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_MemoryPagingSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsMemoryPaging( EBI_MODULE_ID index ) PLIB_EBI_ExistsMemoryTimingConfig Function Identifies whether the MemoryTimingConfig feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsMemoryTimingConfig(EBI_MODULE_ID index); Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 750 Returns • true - The MemoryTimingConfig feature is supported on the device • false - The MemoryTimingConfig feature is not supported on the device Description This function identifies whether the MemoryTimingConfig feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_MemoryTimingConfigSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsMemoryTimingConfig( EBI_MODULE_ID index ) PLIB_EBI_ExistsPageMode Function Identifies whether the PageMode feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsPageMode(EBI_MODULE_ID index); Returns • true - The PageMode feature is supported on the device • false - The PageMode feature is not supported on the device Description This function identifies whether the PageMode feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_PageModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsPageMode( EBI_MODULE_ID index ) PLIB_EBI_ExistsPageReadTime Function Identifies whether the PageReadTime feature exists on the EBI module. File plib_ebi.h Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 751 C bool PLIB_EBI_ExistsPageReadTime(EBI_MODULE_ID index); Returns • true - The PageReadTime feature is supported on the device • false - The PageReadTime feature is not supported on the device Description This function identifies whether the PageReadTime feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_PageReadCycleTimeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsPageReadTime( EBI_MODULE_ID index ) PLIB_EBI_ExistsReadCycleTime Function Identifies whether the ReadCycleTime feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsReadCycleTime(EBI_MODULE_ID index); Returns • true - The ReadCycleTime feature is supported on the device • false - The ReadCycleTime feature is not supported on the device Description This function identifies whether the ReadCycleTime feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_ReadCycleTimeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsReadCycleTime( EBI_MODULE_ID index ) PLIB_EBI_ExistsReadyMode Function Identifies whether the ReadyMode feature exists on the EBI module. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 752 File plib_ebi.h C bool PLIB_EBI_ExistsReadyMode(EBI_MODULE_ID index); Returns • true - The ReadyMode feature is supported on the device • false - The ReadyMode feature is not supported on the device Description This function identifies whether the ReadyMode feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ReadyModeSet • PLIB_EBI_ReadyModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsReadyMode( EBI_MODULE_ID index ) PLIB_EBI_ExistsReadyPin1Config Function Identifies whether the ReadyPin1Config feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsReadyPin1Config(EBI_MODULE_ID index); Returns • true - The ReadyPin1Config feature is supported on the device • false - The ReadyPin1Config feature is not supported on the device Description This function identifies whether the ReadyPin1Config feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_ReadyPin1ConfigSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsReadyPin1Config( EBI_MODULE_ID index ) Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 753 PLIB_EBI_ExistsReadyPin2Config Function Identifies whether the ReadyPin2Config feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsReadyPin2Config(EBI_MODULE_ID index); Returns • true - The ReadyPin2Config feature is supported on the device • false - The ReadyPin2Config feature is not supported on the device Description This function identifies whether the ReadyPin2Config feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_ReadyPin2ConfigSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsReadyPin2Config( EBI_MODULE_ID index ) PLIB_EBI_ExistsReadyPin3Config Function Identifies whether the ReadyPin3Config feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsReadyPin3Config(EBI_MODULE_ID index); Returns • true - The ReadyPin3Config feature is supported on the device • false - The ReadyPin3Config feature is not supported on the device Description This function identifies whether the ReadyPin3Config feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_ReadyPin3ConfigSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 754 Function PLIB_EBI_ExistsReadyPin3Config( EBI_MODULE_ID index ) PLIB_EBI_ExistsReadyPinSens Function Identifies whether the ReadyPinSens feature exists on the EBI module File plib_ebi.h C bool PLIB_EBI_ExistsReadyPinSens(EBI_MODULE_ID index); Returns • true - The ReadyPinSens feature is supported on the device • false - The ReadyPinSens feature is not supported on the device Description This function identifies whether the ReadyPinSens feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_ReadyPinSensSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsReadyPinSens( EBI_MODULE_ID index ) PLIB_EBI_ExistsStaticMemoryWidthRegister Function Identifies whether the StaticMemoryWidthRegister feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsStaticMemoryWidthRegister(EBI_MODULE_ID index); Returns • true - The StaticMemoryWidthRegister feature is supported on the device • false - The StaticMemoryWidthRegister feature is not supported on the device Description This function identifies whether the StaticMemoryWidthRegister feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_StaticMemoryWidthRegisterSet • PLIB_EBI_StaticMemoryWidthRegisterGet Remarks None. Preconditions None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 755 Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsStaticMemoryWidthRegister( EBI_MODULE_ID index ) PLIB_EBI_ExistsWriteOutputControl Function Identifies whether the WriteOutputControl feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsWriteOutputControl(EBI_MODULE_ID index); Returns • true - The WriteOutputControl feature is supported on the device • false - The WriteOutputControl feature is not supported on the device Description This function identifies whether the WriteOutputControl feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_WriteOutputControlSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsWriteOutputControl( EBI_MODULE_ID index ) PLIB_EBI_ExistsWritePulseWidth Function Identifies whether the WritePulseWidth feature exists on the EBI module. File plib_ebi.h C bool PLIB_EBI_ExistsWritePulseWidth(EBI_MODULE_ID index); Returns • true - The WritePulseWidth feature is supported on the device • false - The WritePulseWidth feature is not supported on the device Description This function identifies whether the WritePulseWidth feature is available on the EBI module. When this function returns true, this function is supported on the device: • PLIB_EBI_WritePulseWidthGet Remarks None. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 756 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_EBI_ExistsWritePulseWidth( EBI_MODULE_ID index ) d) Data Types and Constants EBI_ADDRESS_PORT Enumeration Selects the EBI address port. File plib_ebi_help.h C typedef enum { EBI_EBIADDR_PIN0, EBI_EBIADDR_PIN1, EBI_EBIADDR_PIN2, EBI_EBIADDR_PIN3, EBI_EBIADDR_PIN4, EBI_EBIADDR_PIN5, EBI_EBIADDR_PIN6, EBI_EBIADDR_PIN7, EBI_EBIADDR_PIN8, EBI_EBIADDR_PIN9, EBI_EBIADDR_PIN10, EBI_EBIADDR_PIN11, EBI_EBIADDR_PIN12, EBI_EBIADDR_PIN13, EBI_EBIADDR_PIN14, EBI_EBIADDR_PIN15, EBI_EBIADDR_PIN16, EBI_EBIADDR_PIN17, EBI_EBIADDR_PIN18, EBI_EBIADDR_PIN19, EBI_EBIADDR_PIN20, EBI_EBIADDR_PIN21, EBI_EBIADDR_PIN22, EBI_EBIADDR_PIN23, EBI_ADDR_PRESET8, EBI_ADDR_PRESET12, EBI_ADDR_PRESET16, EBI_ADDR_PRESET_ALL } EBI_ADDRESS_PORT; Members Members Description EBI_EBIADDR_PIN0 PIN 0 EBI_EBIADDR_PIN1 PIN 1 EBI_EBIADDR_PIN2 PIN 2 EBI_EBIADDR_PIN3 PIN 3 EBI_EBIADDR_PIN4 PIN 4 EBI_EBIADDR_PIN5 PIN 5 EBI_EBIADDR_PIN6 PIN 6 EBI_EBIADDR_PIN7 PIN 7 EBI_EBIADDR_PIN8 PIN 8 EBI_EBIADDR_PIN9 PIN 9 Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 757 EBI_EBIADDR_PIN10 PIN 10 EBI_EBIADDR_PIN11 PIN 11 EBI_EBIADDR_PIN12 PIN 12 EBI_EBIADDR_PIN13 PIN 13 EBI_EBIADDR_PIN14 PIN 14 EBI_EBIADDR_PIN15 PIN 15 EBI_EBIADDR_PIN16 PIN 16 EBI_EBIADDR_PIN17 PIN 17 EBI_EBIADDR_PIN18 PIN 18 EBI_EBIADDR_PIN19 PIN 19 EBI_EBIADDR_PIN20 PIN 20 EBI_EBIADDR_PIN21 PIN 21 EBI_EBIADDR_PIN22 PIN 22 EBI_EBIADDR_PIN23 PIN 23 EBI_ADDR_PRESET8 Preset 8 EBI_ADDR_PRESET12 Preset 12 EBI_ADDR_PRESET16 Preset 16 EBI_ADDR_PRESET_ALL Preset All Description EBI Address Port This enumeration selects the EBI address port. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. EBI_CS_TIMING Enumeration Selects the timing register set for Chip Select. File plib_ebi_help.h C typedef enum { CS_TIMING_0, CS_TIMING_1, CS_TIMING_2 } EBI_CS_TIMING; Members Members Description CS_TIMING_0 Use EBISMT0 CS_TIMING_1 Use EBISMT1 CS_TIMING_2 Use EBISMT2 Description Timing Register for Chip Select This enumeration selects the timing register set for Chip Select Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. EBI_MEMORY_SIZE Enumeration Selects the memory size for Chip Select. File plib_ebi_help.h Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 758 C typedef enum { CSNOTUSED, MEMORY_SIZE_64KB, MEMORY_SIZE_128KB, MEMORY_SIZE_256KB, MEMORY_SIZE_512KB, MEMORY_SIZE_1MB, MEMORY_SIZE_2MB, MEMORY_SIZE_4MB, MEMORY_SIZE_8MB, MEMORY_SIZE_16MB } EBI_MEMORY_SIZE; Members Members Description CSNOTUSED Chip Select Not Used MEMORY_SIZE_64KB 64 KB (smaller memories alias within this range) MEMORY_SIZE_128KB 128 KB MEMORY_SIZE_256KB 256 KB MEMORY_SIZE_512KB 512 KB MEMORY_SIZE_1MB 1 MB MEMORY_SIZE_2MB 2 MB MEMORY_SIZE_4MB 4 MB MEMORY_SIZE_8MB 8 MB MEMORY_SIZE_16MB 16 MB Description Memory Size for Chip Select This enumeration selects memory size for Chip Select. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. EBI_MEMORY_TYPE Enumeration Selects the memory type for Chip Select. File plib_ebi_help.h C typedef enum { SRAM, NORFLASH } EBI_MEMORY_TYPE; Members Members Description SRAM SRAM NORFLASH NOR-Flash Description Memory Type for Chip Select This enumeration selects the memory type for Chip Select. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 759 EBI_MODULE_ID Enumeration Identifies the supported EBI modules. File plib_ebi_help.h C typedef enum { EBI_ID_0, EBI_NUMBER_OF_MODULES } EBI_MODULE_ID; Members Members Description EBI_ID_0 EBI Module 0 ID EBI_NUMBER_OF_MODULES Number of available WDT modules. Description EBI Module ID This enumeration identifies the available EBI modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. EBI_PAGE_SIZE Enumeration Selects the page size for the page mode device. File plib_ebi_help.h C typedef enum { PAGE_WORD4, PAGE_WORD8, PAGE_WORD16, PAGE_WORD32 } EBI_PAGE_SIZE; Members Members Description PAGE_WORD4 4-word page PAGE_WORD8 8-word page PAGE_WORD16 16-word page PAGE_WORD32 32-word page Description Page Size for page mode device This enumeration selects the page size for the page mode device. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. EBI_STATIC_MEMORY_WIDTH Enumeration Selects the static memory width for the register EBISMTx. File plib_ebi_help.h Peripheral Libraries Help EBI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 760 C typedef enum { MEMORY_WIDTH_8BIT, MEMORY_WIDTH_16BIT } EBI_STATIC_MEMORY_WIDTH; Members Members Description MEMORY_WIDTH_8BIT 8 bits MEMORY_WIDTH_16BIT 16 bits Description Memory Width This enumeration selects the static memory width for the register EBISMTx. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Files Files Name Description plib_ebi.h EBI Peripheral Library Interface Header. plib_ebi_help.h Description This section lists the source and header files used by the library. plib_ebi.h EBI Peripheral Library Interface Header. Functions Name Description PLIB_EBI_AddressHoldTimeGet Returns the address hold time. PLIB_EBI_AddressPinEnableBitsSet Sets the address pins used for EBI. PLIB_EBI_AddressSetupTimeGet Returns the setup hold time. PLIB_EBI_BaseAddressGet Returns the base address set for each Chip Select. PLIB_EBI_BaseAddressSet Sets the base address for physical memory at each Chip Select pin. PLIB_EBI_ByteSelectPinSet Sets the data Byte Select High <15:8> and Low <7:0> enable pins for use. PLIB_EBI_ChipSelectEnableSet Sets the Chip Select pins for use with the EBI or GPIO. PLIB_EBI_ControlEnableGet Returns the status of the EBI enable bit. PLIB_EBI_ControlEnableSet Sets the EBI bus ON/OFF enable bit. PLIB_EBI_DataEnableSet Sets the use of Data Byte Select Pins, High and Low, for control with EBI or GPIO. PLIB_EBI_DataTurnAroundTimeGet Returns the data turn-around time set for the EBI bus. PLIB_EBI_ExistsAddressHoldTime Identifies whether the AddressHoldTime feature exists on the EBI module. PLIB_EBI_ExistsAddressPinEnableBits Identifies whether the AddressPinEnableBits feature exists on the EBI module. PLIB_EBI_ExistsAddressSetupTime Identifies whether the AddressSetupTime feature exists on the EBI module. PLIB_EBI_ExistsBaseAddress Identifies whether the Base_Address feature exists on the EBI module. PLIB_EBI_ExistsByteSelectPin Identifies whether the ByteSelectPin feature exists on the EBI module. PLIB_EBI_ExistsChipSelectEnable Identifies whether the ChipSelectEnable feature exists on the EBI module. PLIB_EBI_ExistsControlEnable Identifies whether the ControlEnable feature exists on the EBI module. PLIB_EBI_ExistsDataEnable Identifies whether the DataEnable feature exists on the EBI module. PLIB_EBI_ExistsDataTurnAroundTime Identifies whether the DataTurnAroundTime feature exists on the EBI module. PLIB_EBI_ExistsFlashPowerDownMode Identifies whether the FlashPowerDownMode feature exists on the EBI module. PLIB_EBI_ExistsFlashResetPin Identifies whether the FlashResetPin feature exists on the EBI module. Peripheral Libraries Help EBI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 761 PLIB_EBI_ExistsFlashTiming Identifies whether the FlashTiming feature exists on the EBI module. PLIB_EBI_ExistsMemoryCharacteristics Identifies whether the MemoryCharacteristics feature exists on the EBI module. PLIB_EBI_ExistsMemoryPaging Identifies whether the MemoryPaging feature exists on the EBI module. PLIB_EBI_ExistsMemoryTimingConfig Identifies whether the MemoryTimingConfig feature exists on the EBI module. PLIB_EBI_ExistsPageMode Identifies whether the PageMode feature exists on the EBI module. PLIB_EBI_ExistsPageReadTime Identifies whether the PageReadTime feature exists on the EBI module. PLIB_EBI_ExistsReadCycleTime Identifies whether the ReadCycleTime feature exists on the EBI module. PLIB_EBI_ExistsReadyMode Identifies whether the ReadyMode feature exists on the EBI module. PLIB_EBI_ExistsReadyPin1Config Identifies whether the ReadyPin1Config feature exists on the EBI module. PLIB_EBI_ExistsReadyPin2Config Identifies whether the ReadyPin2Config feature exists on the EBI module. PLIB_EBI_ExistsReadyPin3Config Identifies whether the ReadyPin3Config feature exists on the EBI module. PLIB_EBI_ExistsReadyPinSens Identifies whether the ReadyPinSens feature exists on the EBI module PLIB_EBI_ExistsStaticMemoryWidthRegister Identifies whether the StaticMemoryWidthRegister feature exists on the EBI module. PLIB_EBI_ExistsWriteOutputControl Identifies whether the WriteOutputControl feature exists on the EBI module. PLIB_EBI_ExistsWritePulseWidth Identifies whether the WritePulseWidth feature exists on the EBI module. PLIB_EBI_FlashPowerDownModeGet Returns the set power-down state. PLIB_EBI_FlashPowerDownModeSet Sets the pin state for Flash devices on Power-down and Reset. PLIB_EBI_FlashResetPinGet Sets the control use of Flash Reset pin. PLIB_EBI_FlashResetPinSet Sets the control use of the Flash Reset pin. PLIB_EBI_FlashTimingGet Returns the set Flash timing for external Flash. PLIB_EBI_FlashTimingSet Sets the timing for hold in reset for external Flash. PLIB_EBI_MemoryCharacteristicsSet Sets the characteristics for memory or attached devices attached to the specified pin. PLIB_EBI_MemoryPageSizeGet Returns the Paging mode settings. PLIB_EBI_MemoryPagingSet Sets the size of the memory page if paging is used. PLIB_EBI_MemoryTimingConfigSet Sets the cycle time for page reading. PLIB_EBI_PageModeGet Returns the Paging mode settings. PLIB_EBI_PageReadCycleTimeGet Returns the cycle time for a page read. PLIB_EBI_ReadCycleTimeGet Returns the read time in the number of clock cycles. PLIB_EBI_ReadyModeGet Returns whether or not Ready mode was set. PLIB_EBI_ReadyModeSet Sets the use of Ready mode for each pin. PLIB_EBI_ReadyPin1ConfigSet Sets the control use of ReadyPin1 and inverts the status. PLIB_EBI_ReadyPin2ConfigSet Sets the control use of ReadyPin2 and inverts the status. PLIB_EBI_ReadyPin3ConfigSet Sets the control use of ReadyPin3 and inverts the status. PLIB_EBI_ReadyPinSensSet Sets the sensitivity of the Ready pin. PLIB_EBI_StaticMemoryWidthRegisterGet Returns the set width of the data bus. PLIB_EBI_StaticMemoryWidthRegisterSet Sets the data width of static memory. PLIB_EBI_WriteOutputControlSet Sets the Write Enable and Output Enable control pins. PLIB_EBI_WritePulseWidthGet Returns the set hold time in clock cycles. Description External Bus Interface (EBI) Peripheral Library Interface This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the EBI Peripheral Library. File Name plib_ebi.h Company Microchip Technology Inc. plib_ebi_help.h Enumerations Name Description EBI_ADDRESS_PORT Selects the EBI address port. EBI_CS_TIMING Selects the timing register set for Chip Select. Peripheral Libraries Help EBI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 762 EBI_MEMORY_SIZE Selects the memory size for Chip Select. EBI_MEMORY_TYPE Selects the memory type for Chip Select. EBI_MODULE_ID Identifies the supported EBI modules. EBI_PAGE_SIZE Selects the page size for the page mode device. EBI_STATIC_MEMORY_WIDTH Selects the static memory width for the register EBISMTx. Section Data Types & Constants Peripheral Libraries Help EBI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 763 Ethernet Peripheral Library This section describes the Ethernet Peripheral Library. Introduction The Ethernet Peripheral Library provides a low-level abstraction of the Ethernet module in the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without interacting directly with the module's registers, thereby hiding the differences in microcontroller variations. Description Ethernet is the most widely deployed network in offices and homes. Ethernet’s infrastructure, interoperability, and scalability serve to ease development and facilitate communications to the device. Once equipment is connected to an Ethernet network, it can be monitored or controlled through the internet with low latency – "real time" remote delivery. The Ethernet Controller is a bus master module that interfaces with an off-chip PHY to implement a complete Ethernet node in a system. Following are some of the key features of this module: • Supports 10/100 Mbps data transfer rates Peripheral Libraries Help Ethernet Peripheral Library Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 764 • Supports Full-Duplex and Half-Duplex operation • Supports Reduced Media Independent Interface (RMII) and Media Independent Interface (MII) PHY interface • Supports MII Management (MIIM) PHY Management interface • Supports both manual and automatic flow control • Supports Auto-MDIX and enabled PHYs • RAM descriptor based DMA operation for both receive and transmit path • Fully configurable interrupts • Configurable receive packet filtering: • CRC Check • 64-byte Pattern Match • Broadcast, Multicast and Unicast packets • Magic Packet™ • 64-bit Hash Table • Runt Packet • Supports Packet Payload Checksum calculation • Supports various hardware statistics counters Using the Library This topic describes the basic architecture of the Ethernet Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_eth.h The interface to the Ethernet Peripheral Library is defined in the plib_eth.h header file., which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Ethernet Peripheral Library should include peripheral.h. Library File: The Ethernet Peripheral Library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the Peripheral interacts with the framework. Hardware Abstraction Model This section describes how the low-level abstraction is modeled in the software and introduces the library interface. The interface provided is a superset of all the functionality of the available Ethernet on the device. Refer to the specific data sheet or family reference manual to determine the set of functions that are supported for each Ethernet module on your device. Description Hardware Model This library provides the low-level abstraction of the Ethernet module on Microchip family of microcontrollers with a convenient C language interface. Ethernet Controller Block Diagram Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 765 Note: For information on off-chip options to provide Ethernet functionality, refer to the specific device data sheet. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Ethernet module. Library Interface Section Description Initialization Functions Provides setup and configuration routines. Control Functions Provides control routines. Status Functions Provides status routines. Filtering Functions Provides filtering routines. Flow Control Functions Provides flow control routines. Interrupt Functions Provides interrupt routines. Statistics Functions Provides statistics routines. Feature Existence Functions These functions can be used to determine whether or not a particular feature exists on the device. Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 766 How the Library Works This section provides information on the operation of the Ethernet Peripheral Library. Description The Peripheral Library is an abstraction of hardware which can be used to control hardware and obtain status. It is intended to allow the programmer access to hardware registers without knowing the exact bit or register names which may vary on individual devices. For example, instead of turning on the Ethernet module using: ETHCON1bits.EON = 1; the programmer can turn on the Ethernet module using: PLIB_ETH_Enable(moduleId);. This allows the programmer to use the same command for any device containing an Ethernet module without having to learn the individual device register names. Basic Overview The Ethernet Controller provides the modules needed to implement a 10/100 Mbps Ethernet node using an external PHY chip. To off-load the CPU from moving packet data to and from the module, internal descriptor-based DMA engines are included in the controller. The Ethernet Controller consists of the following modules: • Media Access Control (MAC) block: Responsible for implementing the MAC functions of the Ethernet IEEE 802.3 Specification • Flow Control (FC) block, which provides: • Manual flow control • Automatic flow control • Transmission of PAUSE frames • Reception of PAUSE frame is handled within the MAC • RX Filter (RXF) block: This module performs filtering on every receive packet to determine whether each packet should be accepted or rejected and includes: • CRC Check • 64-byte Pattern Match • Broadcast, Multicast and Unicast packets • Magic Packet™ • 64-bit Hash Table • Runt Packet • TX DMA/TX BM Engine: The TX DMA and TX Buffer Management engines perform data transfers from the memory (using descriptor tables) to the MAC Transmit Interface • RX DMA/RX BM Engine: The RX DMA and RX Buffer Management engines transfer receive packets from the MAC to the memory (using descriptor tables) Basic Ethernet Controller Operation The Ethernet Controller is enabled using PLIB_ETH_Enable and is disabled using PLIB_ETH_Disable. The Ethernet Controller is disabled by default after any Reset. If the Ethernet Controller is disabled, all of the I/O pins used for the MII/RMII and MIIM interfaces operate as port pins and are under the control of the respective PORTx latch bit and TRISx bit. Disabling the controller resets the internal DMA state machines and all transmit and receive operations are aborted. The Special Function Registers (SFRs) are still accessible and their values are preserved. Clearing the ON bit while the Ethernet Controller is active will abort all pending operations and reset the peripheral as previously defined. Re-enabling the ON bit will restart the Ethernet Controller in its clean reset state while preserving the SFR values. Ethernet Controller Section Block Diagram Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 767 MAC Overview The MAC sub-layer is part of the functionality described in the OSI model for the Data Link Layer. It defines a medium-independent facility, built on the medium-dependent physical facility provided by the Physical Layer, and under the access-layer-independent LLC sub-layer or other MAC client. It is applicable to a general class of local area broadcast media suitable for use with the Carrier Sense Multiple Access with Collision Detection (CSMA/CD). The CSMA/CD MAC sub-layer provides services to the MAC client required for the transmission and reception of frames. The CSMA/CD MAC sub-layer makes a best effort to acquire the medium and transfer a serial stream of bits to the Physical Layer. Although certain errors are reported to the client, error recovery is not provided by the MAC. The following is a summary of the functional capabilities of the CSMA/CD MAC sub-layer as shown in the previous diagram. • For Frame Transmission: • Accepts data from the MAC client and constructs a frame • Presents a bit-serial data stream to the Physical Layer for transmission on the medium • In half-duplex mode, defers transmission of a bit-serial stream whenever the physical medium is busy • It can append proper Frame Check Sequence (FCS) value to outgoing frames and verifies full octet boundary alignment • Delays transmission of frame bit stream for specified inter-frame gap period • In half-duplex mode, halts transmission when collision is detected • In half-duplex mode, schedules retransmission after a collision until a specified retry limit is reached • In half-duplex mode, enforces collision to ensure propagation throughout network by sending jam message • Prepends preamble and Start Frame Delimiter and appends FCS to all frame Appends PAD field for frames whose data length is less than a minimum value • For Frame Reception: Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 768 • Receives a bit-serial data stream from the Physical Layer • Presents the received frames to the MAC client (broadcast, multicast, unicast frames, etc.) • Checks incoming frames for transmission errors by way of FCS and verifies octet boundary alignment • Removes preamble, Start Frame Delimiter and PAD field (if necessary) from received frames • Implements the MII Management block that provides control/status connection to the external MII PHY Note: Not all modes are available on all devices, please refer to the specific device data sheet to determine the set of modes supported for your device. In addition, refer to Section 35. "Ethernet Controller" (DS60001155) of the "PIC32 Family Reference Manual" or the Ethernet MAC Driver Library for more information. Ethernet Frame Overview Ethernet Frame Overview IEEE 802.3-compliant Ethernet frames (packets) are between 64 and 1518 bytes long (Preamble and Start -of-Frame Delimiter not included). Frames containing less than 64 bytes are known as "runt" frames, while frames containing more than 1518 bytes are known as "huge" frames. An Ethernet frame is made up of the following fields: • Start-of-Stream/Preamble • Start-of-Frame Delimiter (SFD) • Destination MAC address (DA) • Source MAC address (SA) • Type/Length field • Data Payload • Optional Padding field • Frame Check Sequence (FCS) • Traffic on the actual physical cable Please refer to the IEEE 802.3 Specification for detailed information about the Ethernet protocol. Ethernet Controller Operation Basic Ethernet Controller Operation The Ethernet Controller is enabled using PLIB_ETH_Enable and is disabled using PLIB_ETH_Disable. The Ethernet Controller is disabled by default after any Reset. If the Ethernet Controller is disabled, all of the I/O pins used for the MII/RMII and MIIM interfaces operate as port pins and are under the control of the respective PORT latch bit and TRIS bit. Disabling the controller resets the internal DMA state machines and all transmit and receive operations are aborted. The SFRs are still accessible and their values preserved. Clearing the ON bit while the Ethernet Controller is active will abort all pending operations and reset the peripheral as previously defined. Re-enabling the ON bit will restart the Ethernet Controller in its clean reset state while preserving the SFR values. Media Independent Interface (MII) This section describes the Media Independent Interface (MII). Description Media Independent Interface (MII) The Media Independent Interface (MII) is a standard interconnection between the MAC and the PHY for communicating TX and RX frame data. This MII has the following important characteristics: • Capable of supporting 10/100 Mbps rates for data transfer, and offers support for management functions • Provides independent four bit wide transmit and receive data paths • Uses TTL signal levels, compatible with common digital CMOS processes • Provides full-duplex operation In 10 Mbps mode, the MII runs at 2.5 MHz; in 100 Mbps mode it runs at 25 MHz. PHYs that provide MII are not required to support both data rates, and may support either one or both. Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 769 Reduced Media Independent Interface (RMII) This section describes the Reduced Media Independent Interface (RMII). Description Reduced Media Independent Interface (RMII) The management interface (MDIO/MDC) is assumed to be identical to that defined in MII. The RMII has the following characteristics: • Capable of supporting 10 Mbps and 100 Mbps data rates • Single clock reference for both MAC and the PHY (can be sourced from the MAC or from an external source) • Provides independent 2 bit wide transmit and receive data paths • Uses TTL signal levels, compatible with common digital CMOS processes • Provides full-duplex operation • The interface runs at 50 MHz Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 770 Flow Control Overview Flow Control Overview Ethernet flow control consists of the ability to send and receive PAUSE frames, which cause the receiving node to stop transmitting for a specific amount of time. On the transmit side, the Flow Control (FC) block handles the hardware handshaking between the MAC and the CPU when the transmit flow control is enabled. Flow control for the received packets is part of the MAC functionality. The PIC32 MAC supports both Symmetric PAUSE and Asymmetric PAUSE as described in Clause 28, Table 28B-2, and Clause 31 and Annex 31B of the IEEE 802.3 Specification. The FC block supports two modes of operation: manual and automatic. In addition, the mode of transmission (Full-Duplex or Half-Duplex) programmed into the MAC registers, is used by the FC block. Receive Filtering Overview Receive Filtering Overview The Receive Filter (RXF) block examines all incoming receive packets and accepts or rejects the packet, based on user-selectable filters. The following RX filters are supported: • CRC Error Acceptance Filter • Runt Error Acceptance Filter • CRC Check Rejection Filter • Runt Rejection Filter • Unicast Acceptance Filter • Not Me Unicast Acceptance Filter • Multicast Acceptance Filter • Broadcast Acceptance Filter • Hash Table Acceptance Filter • Magic Packet Acceptance Filter • Pattern Match Acceptance Filter with logical inversion Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 771 Ethernet DMA and Buffer Management Engine Ethernet DMA and Buffer Management Engines To reduce the overhead on the CPU to move the packet data between data memory and the Ethernet controller, internal receive (RX) and transmit (TX) DMA engines are integrated into the module. The DMA engines are responsible for transferring data from system memory to the MAC for transmit packets and for transferring data from the MAC to system memory for receive packets. The DMA engines each have access to the system memory by acting as two different bus masters, one bus master for transmit and one for receive. The DMA engines use separate Ethernet Descriptor Tables (EDTs) for TX and RX operations to determine where the TX/RX packet buffer resides in the system memory. Both transmit and receive descriptors, called Ethernet Descriptors (EDs), used by the DMA engines have a similar format, with only the status word formats being different. Refer to the "Ethernet" section in the family reference manual for more information. Sample Code This section provides information for initialization, transmit, and receive using code samples. Description Sample Code The basic functionality of the Ethernet Peripheral Library is grouped into these sections: • Initialization • Transmit • Receive For a properly functioning Ethernet port, development of a data queue and use of interrupts will be necessary. For this additional functionality, see the "Ethernet" section in the family reference manual or the Ethernet Driver Library for more information. Initialization Sequence The Ethernet Controller is enabled using PLIB_ETH_Enable and is disabled using PLIB_ETH_Disable. The Ethernet Controller is disabled by default after any Reset. After being Enabled, disabling the controller resets the internal DMA state machines and all transmit and receive operations are aborted. All registers remain accessible and their values are preserved. It is important to reset the PHY and MII Management registers to ensure the PHY is in a known initialized state. Before enabling the module for transmitting or receiving packets, there are several registers that must be initialized. To initialize the Ethernet Controller to receive and transmit, Microchip recommends the following sequence: 1. Begin with the module. • Disable the CPU Ethernet interrupt • Turn the Ethernet Controller off • Disable receive • Disable transmit • Wait until the Ethernet module is no longer busy • Disable all Ethernet Interrupts • Clear the Ethernet Interrupt Pending Flag(s) • Clear the transmit and receive start addresses 2. MAC initialize. • Reset the MAC • A configuration fuse (FETHIO) setting shows which pins will be used for connection to the PHY • A configuration fuse (FMIIEN) settings shows whether MII or RMII will be used 3. PHY Initialize is PHY dependent. Common procedures (which may vary by PHY vender) include the following: • Reset PHY (using Control Register 0) • Set the MII/RMII operation mode • Set the normal, swapped, or auto (preferred)MDIX • Check the PY capabilities (using Status Register 1) • Preferably the auto-negotiation should be selected if the PHY supports it. • Expose the supported capabilities (extended Register 4) • Start the negotiation (using Control Register 0) • wait for the negotiation to complete and get the link partner capabilities (extended Register 5) Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 772 • negotiation result (vendor-specific register) • If auto-negotiation is not supported (or not selected) • update the PHY Duplex and speed settings (use Control Register 0 or vender-specific register) 4. MAC Configuration • Enable MAC receive and pause both transmit and receive direction control frames. • Select the desired auto-padding, duplex, huge frame, and CRC capabilities. • Program back-to-back inter-packet gap and non-back-to-back interpacket gap. • Program collision window and maximum retransmissions. • Set Maximum frame length. • Optionally set the station MAC address(es) (or let them default to the factory value). 5. Continue Ethernet Controller initialization: • If planning to turn on flow control, update the Pause Timer Value • If using auto-flow control, set up the full/empty watermarks and enable it • Set the receive filters • Set receive buffer size - using packets that are too small impacts performance • Prepare the list/ring of transmit descriptors - refer to the device data sheet for more information • Prepare the list of receive descriptors populated with valid buffers for messages to be received - refer to the device data sheet for more information • Update the transmit buffer start address and the receive buffer start address • Enable the Ethernet Controller and wait until the module is ready • Enable Ethernet Receive. Receive Loop 1. Wait until the receive buffer count has been incremented. 2. Inspect the receive descriptor to see whether it is still owned by the Ethernet Module. 3. If the receive descriptor is still owned by the Ethernet module, nothing has been received. Loop to 1. 4. Otherwise, a message was received and software has control of the memory where it is stored. 5. Extract a message and do something with it. 6. Reinitialize buffer descriptor and return receive buffer to list and decrement the receive packet buffer count. 7. Loop. Transmit Loop 1. Software writes the packet data to packet data memory. A pointer to the packet data is inserted into the transmit buffer descriptor. 2. Update the necessary number of transmit descriptors, starting from the head of the list - setting the data buffer address (large packet fragmentation will impact performance). 3. Update the byte count for each descriptor with the number of bytes contained in each buffer. 4. Set the flag in each transmit descriptor that belongs to the packet to give the descriptor to the Ethernet module for transmission. 5. Enable the transmission. 6. Wait until the Ethernet module returns the transmit buffer descriptor ownership to software. 7. Insect the results of the transmission. 8. Loop. The packet transmit process is as follows: 1. Software writes the packet data to a packet buffer in data memory and programs a buffer descriptor entry to point to the packet data buffer. The buffer descriptor is used to define the Transmission Packet data buffer location and length, and its address is written to the Ethernet Controller. 2. Software then calls the TransmitRequestToSendEnable function, which starts the TX DMA and TXBM logic. 3. After the TX DMA engine reads the DATA_BUFFER_ADDRESS value, the engine will begin reading the packet data from the location read from the descriptor. 4. The TXBM indicates the start-of-frame to the MAC and transmits the entire frame data from the transmit buffer, until the end address is reached. The TXBM simply transmits from the start address until the specified number of bytes has been transmitted to the MAC transmit interface. 5. The MAC can retry a transmission due to an early collision. 6. The MAC can abort a transmission due to a late collision, excessive collisions or excessive defers. This condition is signaled by TXABORT bit (ETHIRQ<2>). 7. Once transmission has completed, the TX DMA engine stores the relevant bits of the TSV into the first descriptor entry of the packet. 8. After the packet has been transmitted, all the descriptors used for the transmission are released to the software via the EOWN bits being cleared. 9. If more valid TX descriptors are available (EOWN = 1), the DMA engine will go back to step 3 to begin the next packet’s transmission. Otherwise, if the next descriptor is still owned by hardware (EOWN = 0), transmission will halt and wait for the software to set the TXRTS bit again. Note that any collision that occurs within the CWINDOW bit (EMAC1CLRT<8:14>) boundary is an early collision and results in a Retry operation. A Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 773 collision that happens beyond the CWINDOW boundary will be treated as a late collision and will cause an abort. The CWINDOW bit in the EMAC1CLRT register is typically set to 64 bytes. An abort condition can also result from reaching the maximum collision count RETX bit (EMAC1CLRT<0:3>) for a packet trying to be sent. See the "Ethernet" section in the family reference manual or the Ethernet Driver Library for more information. Initialization #include "plib_eth.h" /******************************************************************************* */ void my_ETH_Initialize(ETH_MODULE_ID id) { //Disable System (CPU) Interrupt associated with Ethernet Peripheral // using the Interrupt Peripheral Library // Example: PLIB_INT_SourceDisable(PLIB_INT_SOURCE_ETH_1); //Disable Ethernet Peripheral in case it was previously enabled PLIB_ETH_Disable(ETH_MODULE_ID1); //Disable any Ethernet Controller interrupt generation: PLIB_ETH_InterruptSourceDisable(ETH_MODULE_ID1, ETH_ALL_INTERRUPT_SOURCES); PLIB_ETH_RxDisable(ETH_MODULE_ID1); PLIB_ETH_TxRTSDisable(ETH_MODULE_ID1); while (PLIB_ETH_EthernetIsBusy(ETH_MODULE_ID1)) {/*wait*/ } //Clear the System Interrupt Flag associated with Ethernet Peripheral // using the Interrupt Peripheral Library // Example: PLIB_INT_SourceFlagClear(PLIB_INT_SOURCE_ETH_1); ///////////////////////////////////////////////// //MAC Initialize PLIB_ETH_MIIResetEnable(ETH_MODULE_ID1); PLIB_ETH_MIIResetDisable(ETH_MODULE_ID1); //A configuration fuse (FETHIO) setting shows which digital pins need to be configured if (CONFIGURATION_FUSE_PRIMARY_ETH_PINS==1) { ConfigurePrimaryEthernetPinsAsDigital(); } else //(CONFIGURATION_FUSE_PRIMARY_ETH_PINS==0) { ConfigureAlternateEthernetPinsAsDigital(); } //A configuration fuse (FMIIEN) settings shows which digital pins need to be configured if (CONFIGURATION_FUSE_MII_STYLE==RMII) { PLIB_ETH_RMIIResetEnable(ETH_MODULE_ID1); PLIB_ETH_RMIIResetDisable(ETH_MODULE_ID1); PLIB_ETH_RMIISpeedSet(ETH_MODULE_ID1, ETH_RMII_100Mps); } PLIB_ETH_MIIResetEnable(ETH_MODULE_ID1); PLIB_ETH_MIIResetDisable(ETH_MODULE_ID1); PLIB_ETH_MIIMClockSet(ETH_MODULE_ID1, ETH_MII_SYSCLK_DIV_BY_10); ///////////////////////////////////////////////// //PHY Initialize is PHY dependent. // Common procedures (which may vary by PHY vender) include the following: // //Reset PHY (using Control Register 0) //Set the MII/RMII operation mode //Set the normal, swapped, or auto (preferred)MDIX //Check the PY capabilities (using Status Register 1) Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 774 //Preferably the auto-negotiation should be selected if the PHY supports it. //Expose the supported capabilities (extended Register 4) //Start the negotiation (using Control Register 0) //wait for the negotiation to complete and get the link partner capabilities (extended Register 5) //negotiation result (vendor-specific register) //If auto-negotiation is not supported (or not selected) //update the PHY Duplex and speed settings (use Control Register 0 or vender-specific register) ///////////////////////////////////////////////// //MAC Configuration PLIB_ETH_RxEnable(ETH_MODULE_ID1); PLIB_ETH_TxPauseEnable(ETH_MODULE_ID1); PLIB_ETH_RxPauseEnable(ETH_MODULE_ID1); //Select the desired auto-padding, duplex, huge frame, and CRC capabilities PLIB_ETH_AutoDetecPadSet(ETH_MODULE_ID1, ETH_AUTOPAD_BY_PKT_TYPE_ADD_CRC ); PLIB_ETH_FullDuplexEnable(ETH_MODULE_ID1); //or disable for half-duplex PLIB_ETH_CRCEnable(ETH_MODULE_ID1); //or disable if EMAC does not add CRC when no padding is necessary PLIB_ETH_HugeFrameDisable(ETH_MODULE_ID1); //or enable to receive huge frames //Program back-to-back inter-packet gap and non-back-to-back interpacket gap PLIB_ETH_BackToBackIPGpSet(ETH_MODULE_ID1, 0x15 /*backToBackGapValue*/); PLIB_ETH_NonBackToBackIPG1Set(ETH_MODULE_ID1, 0x0C /*nonBackToBackGap1Value*/); PLIB_ETH_NonBackToBackIPG2Set(ETH_MODULE_ID1, 0x12 /*nonBackToBackGap2Value*/); //Set Maximum frame length PLIB_ETH_MaxFrameLengthSet(ETH_MODULE_ID1, 1527 /*maxFrameLenValue*/); //Optionally set the station MAC address(es) (or let them default to the factory value) PLIB_ETH_StationAddressSet(ETH_MODULE_ID1, 1, 0x13 /*stationAddr1Value*/); ///////////////////////////////////////////////// //Continue Ethernet Controller Initialization //Set receive buffer size - using packets that are too small impacts performance PLIB_ETH_ReceiveBufferSizeSet(ETH_MODULE_ID1, 200 /*receiveBufSizeValue*/); //Prepare the list/ring of transmit descriptors - refer to the device data sheet for more information //Prepare the list of receive descriptors populated with valid buffers for messages to be received - refer //to the device data sheet for more information //Update the transmit buffer start address and the receive buffer start address PLIB_ETH_TxPacketDescAddrSet(ETH_MODULE_ID1, (uint8_t *)0xadd1add0/*txPktDescStartAddrValue*/); PLIB_ETH_RxPacketDescAddrSet(ETH_MODULE_ID1, (uint8_t *)0xadd3add2/*rxPktDescStartAddrValue*/); //If using auto flow control, set up the full/empty watermarks and enable it PLIB_ETH_PauseTimerSet(ETH_MODULE_ID1, 0x64 /*pauseTimerValue*/); PLIB_ETH_RxEmptyWmarkSet(ETH_MODULE_ID1, 0x3F/*emptyRxWatermarkValue*/); PLIB_ETH_RxFullWmarkSet(ETH_MODULE_ID1, 0x10 /*fullRxWatermarkValue*/); PLIB_ETH_AutoFlowControlEnable(ETH_MODULE_ID1); PLIB_ETH_ReceiveFilterEnable(ETH_MODULE_ID1, ETH_MULTICAST_FILT | // enable to accept multicast address packets ETH_BROADCAST_FILTER );// enable to accept all broadcast address packets PLIB_ETH_InterruptSourceDisable(ETH_MODULE_ID1, ETH_ALL_INTERRUPT_SOURCES); //Enable the Ethernet Controller and wait until the module is ready PLIB_ETH_Enable(ETH_MODULE_ID1); while (PLIB_ETH_EthernetIsBusy(ETH_MODULE_ID1)) { //Wait } PLIB_ETH_RxEnable(ETH_MODULE_ID1); return (EXIT_SUCCESS); } Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 775 Descriptor Table Example typedef volatile struct { union { //Common to both Receive and Transmit struct { unsigned: 7; unsigned EOWN: 1; //0=Software owns, 1=Ethernet Controller owns unsigned NPV: 1; //0=Next Desc follows this, 1=Next Desc pointed to by NEXT_ED unsigned: 7; unsigned bCount: 11; unsigned: 3; unsigned EOP: 1; unsigned SOP: 1; }; uint32_t w; }; // descriptor header //Common to both Receive and Transmit uint8_t* pEDBuff; // pointer to data buffer union { //This portion differs from Receive to Transmit uint64_t RX_STATUS; //Receive Status struct { unsigned RX_PKT_CHECKSUM: 16; unsigned: 8; unsigned RXF_RSV: 8; unsigned RSV: 32; }; uint64_t TX_STATUS; // Transmit Status struct //Transmit Struct { unsigned TSV_TRANSMIT_BYTE_COUNT: 16; unsigned TSV_TX_COLLISION_COUNT: 4; unsigned TSV_TX_CRC_ERROR: 1; unsigned TSV_TX_LENGTH_CHECK_ERROR: 1; unsigned TSV_TX_DONE: 1; unsigned TSV_TX_MULTICAST: 1; unsigned TSV_TX_BROADCAST: 1; unsigned TSV_TX_PACKET_DEFER: 1; unsigned TSV_TX_EXCESSIVE_DEFER: 1; unsigned TSV_TX_MAXIMUM_COLLISION: 1; unsigned TSV_TX_LATE_COLLISION: 1; unsigned TSV_TX_GIANT: 1; unsigned TSV_TX_UNDER_RUN: 1; unsigned TSV_TX_STATUS_VECTOR:1; unsigned TSV_TOTAL_BYTES_TX_ON_WIRE: 16; unsigned TSV_TX_CONTROL_FRAME: 1; unsigned TSV_TX_PAUSE_CONTROL_FRAME: 1; unsigned TSV_TX_BACKPRESSURE_APPLIED: 1; unsigned TSV_TX_VLAN_TAGGED_FRAME: 1; unsigned TSV_IGNORED: 4; unsigned TSV_USER_DEFINED: 8; }; }; // descriptor header //Common to both Receive and Transmit uint8_t* next_ed; // next descriptor (NPV==1); }__attribute__((__packed__)) eth_buffer_descriptor_t; // hardware RX descriptor (linked). For more information on this structure, refer to the "Ethernet" section in the family reference manual. Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 776 Transmit C Description #include "plib_eth.h" /*********************************************************************** // */ void my_ETH_Transmit(ETH_MODULE_ID id, eth_buffer_descriptor_t *pArrDcpt, uint8_t *pArrBuff, uint8_t nArrayItems, uint16_t *pArrSize) { //Input Parameters: // *pArrDcpt : pointer to an array that holds free descriptors // *pArrBuff: pointer to an array that holds buffers to be transmitted // *pArrSize: pointer to an array that holds the sizes of the buffers to be transmitted // nArrayItems: number of buffers to be transmitted // // Before attempting to transmit, the data must be placed into a packet // buffer (list) and the point(s) must be placed into transmit descriptor(s) // Refer to the DRV_ETH or the device family reference manual for more information extern void* VA_TO_PA(char* pBuff); // extern function that returns the physical // address of the input virtual address parameter uint16_t ix; // loop index eth_buffer_descriptor_t *pEDcpt; // current Ethernet descriptor eth_buffer_descriptor_t *tailDcpt; // last Ethernet descriptor uint8_t *pBuff; // current data buffer to be transmitted uint16_t *pSize; // current data buffer size pEDcpt=pArrDcpt; pBuff=pArrBuff; pSize=pArrSize; tailDcpt=0; for(ix=0; ix< nArrayItems; ix++, pEDcpt++, pBuff++, pSize++) { // pass the descriptor to hw, use linked descriptors, set proper size pEDcpt->pEDBuff = (uint8_t *)VA_TO_PA(pBuff); // set buffer pEDcpt->w=0; // clear all the fields pEDcpt->NPV=1; // set next pointer valid pEDcpt->EOWN=1; // set hw ownership pEDcpt->bCount = *pSize; // set proper size if(tailDcpt) { tailDcpt->next_ed = VA_TO_PA(&pEDcpt); } tailDcpt=pEDcpt; } // at this moment pEDcpt is an extra descriptor we use to end the descriptors list pEDcpt->w=0; // software ownership tailDcpt->next_ed= VA_TO_PA(&pEDcpt); pArrDcpt[0].SOP=1; // start of packet pArrDcpt[nArrayItems-1].EOP=1; // end of packet PLIB_ETH_TransmitPacketDescStartAddrSet(id, VA_TO_PA(pArrDcpt)); // set the transmit address PLIB_ETH_TransmitRequestToSendIsEnabled(id); // set the TXRTS // the ETHC will transmit the buffers we just programmed /* do something else in between */ while (PLIB_ETH_TxRTSIsEnabled(id)) { //Wait until transmit is not busy Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 777 } // check the ETHSTAT register to see the transfer result } Receive #include "plib_eth.h" /*********************************************************************** // */ void my_ETH_Receive(ETH_MODULE_ID id, eth_buffer_descriptor_t *pArrDcpt, uint8_t *pArrBuff, uint8_t nArrayItems, uint16_t rxBuffSize) { extern void* VA_TO_PA(char* pBuff); // extern function that returns the physical // address of the input virtual address parameter int ix;// index eth_buffer_descriptor_t *pEDcpt; // current Ethernet descriptor eth_buffer_descriptor_t *tailDcpt; // last Ethernet descriptor char* pBuff;// current data buffer to be transmitted pEDcpt=pArrDcpt; pBuff=pArrBuff; tailDcpt=0; //Prepare to receive PLIB_ETH_ReceiveBufferSizeSet(id, (rxBuffSize/16)); for(ix=0; ix< nArrayItems; ix++, pEDcpt++, pBuff++) {// pass the descriptor to hw, use linked descriptors, set proper size pEDcpt->pEDBuff=(unsigned char*)VA_TO_PA(pBuff);// set buffer pEDcpt->w=0;// clear all the fields pEDcpt->NPV= 1;// set next pointer valid pEDcpt->EOWN= 1;// set hw ownership if(tailDcpt) { tailDcpt->next_ed=VA_TO_PA(&pEDcpt); } tailDcpt=pEDcpt; } // at this moment pEDcpt is an extra descriptor we use to end the descriptors list pEDcpt->w=0;// software ownership tailDcpt->next_ed= VA_TO_PA(&pEDcpt); PLIB_ETH_RxPacketDescStartAddrSet(id, VA_TO_PA(pArrDcpt)); // set the address of the first RX descriptor PLIB_ETH_ReceiveEnable(id); // the Ethernet Controller will receive frames and place them in the receive buffers // we just programmed /* do something else in between */ while(PLIB_ETH_RxPacketCountGet(id)==0) { //Wait until something is received. // Packets are received as set by the receive filter } //Receive the packet //doSomethingWithReceivedPacket() // After the received packet has been processed, restore EOWN to 1 and PLIB_ETH_RxBufferCountDecrement(id); } Support for Legacy "Ethernet Controller Library" These routines (PLIB_ETH_Legacy*) provide MPLAB Harmony support for applications that use the "Ethernet Controller Library for Microchip Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 778 PIC32MX Microcontrollers" that is installed with XC32 compilers. Refer to the related compiled Help, hlpETH.chm, which is located in the ../Microchip/xc32//docs/pic32-lib-help folder of your XC32 compiler installation for legacy information. An additional argument, an index value from the ETH_MODULE_ID enumeration, has been added to allow these functions to work from within the context of this MPLAB Harmony Peripheral Library. Legacy Controller Library MPLAB Harmony EthClose EthDescriptorGetBuffer EthDescriptorsPoolAdd EthDescriptorsPoolCleanUp EthDescriptorsPoolRemove EthEventsClr EthEventsEnableClr EthEventsEnableGet EthEventsEnableSet EthEventsEnableWrite EthEventsGet EthInit EthMACGetAddress EthMACOpen EthMACSetAddress EthMACSetMaxFrame EthRxAcknowledgeBuffer EthRxAcknowledgePacket EthRxBuffersAppend EthRxFiltersClr EthRxFiltersHTSet EthRxFiltersPMClr EthRxFiltersPMSet EthRxFiltersSet EthRxFiltersWrite EthRxGetBuffer EthRxGetPacket EthRxSetBufferSize EthStatRxAlgnErrCnt EthStatRxFcsErrCnt EthStatRxOkCnt EthStatRxOvflCnt EthStatTxMColCnt EthStatTxOkCnt EthStatTxSColCnt EthTxAcknowledgeBuffer EthTxAcknowledgePacket EthTxGetBufferStatus EthTxGetPacketStatus EthTxSendBuffer EthTxSendPacket DRV_ETHMAC_LegacyClose DRV_ETHMAC_LegacyDescriptorGetBuffer DRV_ETHMAC_LegacyDescriptorsPoolAdd DRV_ETHMAC_LegacyDescriptorsPoolCleanUp DRV_ETHMAC_LegacyDescriptorsPoolRemove PLIB_ETH_EventsClr PLIB_ETH_EventsEnableClr PLIB_ETH_EventsEnableGet PLIB_ETH_EventsEnableSet PLIB_ETH_EventsEnableWrite PLIB_ETH_EventsGet DRV_ETHMAC_LegacyInit PLIB_ETH_MACGetAddress DRV_ETHMAC_LegacyMACOpen PLIB_ETH_MACSetAddress PLIB_ETH_MACSetMaxFrame DRV_ETHMAC_LegacyRxAcknowledgeBuffer DRV_ETHMAC_LegacyRxAcknowledgePacket DRV_ETHMAC_LegacyRxBuffersAppend PLIB_ETH_RxFiltersClr PLIB_ETH_RxFiltersHTSet PLIB_ETH_RxFiltersPMClr PLIB_ETH_RxFiltersPMSet PLIB_ETH_RxFiltersSet PLIB_ETH_RxFiltersWrite DRV_ETHMAC_LegacyRxGetBuffer DRV_ETHMAC_LegacyRxGetPacket PLIB_ETH_RxSetBufferSize PLIB_ETH_StatRxAlgnErrCnt PLIB_ETH_StatRxFcsErrCnt PLIB_ETH_StatRxOkCnt PLIB_ETH_StatRxOvflCnt PLIB_ETH_StatTxMColCnt PLIB_ETH_StatTxOkCnt PLIB_ETH_StatTxSColCnt DRV_ETHMAC_LegacyTxAcknowledgeBuffer DRV_ETHMAC_LegacyTxAcknowledgePacket DRV_ETHMAC_LegacyTxGetBufferStatus DRV_ETHMAC_LegacyTxGetPacketStatus DRV_ETHMAC_LegacyTxSendBuffer DRV_ETHMAC_LegacyTxSendPacket Peripheral Libraries Help Ethernet Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 779 Ethernet Peripheral Library Legacy Controller Library PLIB_ETH_EventsClr PLIB_ETH_EventsEnableClr PLIB_ETH_EventsEnableGet PLIB_ETH_EventsEnableSet PLIB_ETH_EventsEnableWrite PLIB_ETH_EventsGet PLIB_ETH_MACGetAddress PLIB_ETH_MACSetAddress PLIB_ETH_MACSetMaxFrame PLIB_ETH_RxFiltersClr PLIB_ETH_RxFiltersHTSet PLIB_ETH_RxFiltersPMClr PLIB_ETH_RxFiltersPMSet PLIB_ETH_RxFiltersSet PLIB_ETH_RxFiltersWrite PLIB_ETH_RxSetBufferSize PLIB_ETH_StatRxAlgnErrCnt PLIB_ETH_StatRxFcsErrCnt PLIB_ETH_StatRxOkCnt PLIB_ETH_StatRxOvflCnt PLIB_ETH_StatTxMColCnt PLIB_ETH_StatTxOkCnt PLIB_ETH_StatTxSColCnt EthEventsClr EthEventsEnableClr EthEventsEnableGet EthEventsEnableSet EthEventsEnableWrite EthEventsGet EthMACGetAddress EthMACSetAddress EthMACSetMaxFrame EthRxFiltersClr EthRxFiltersHTSet EthRxFiltersPMClr EthRxFiltersPMSet EthRxFiltersSet EthRxFiltersWrite EthRxSetBufferSize EthStatRxAlgnErrCnt EthStatRxFcsErrCnt EthStatRxOkCnt EthStatRxOvflCnt EthStatTxMColCnt EthStatTxOkCnt EthStatTxSColCnt Configuring the Library The library is configured for the supported Ethernet module when the processor is chosen in the MPLAB X IDE. Library Interface a) Initialization Functions Name Description PLIB_ETH_AutoDetectPadClear Clears the EMAC Auto-Pad option. PLIB_ETH_AutoDetectPadGet Gets the current EMAC Auto-Pad setting. PLIB_ETH_AutoDetectPadSet Sets the EMAC Auto-Pad option. PLIB_ETH_BackToBackIPGGet Gets the EMAC back-to-back interpacket gap. PLIB_ETH_BackToBackIPGSet Sets the EMAC back-to-back interpacket gap. PLIB_ETH_CollisionWindowGet Gets the EMAC collision window. PLIB_ETH_CollisionWindowSet Sets the EMAC collision window. PLIB_ETH_DelayedCRCDisable Disables EMAC delayed CRC. PLIB_ETH_DelayedCRCEnable Enables EMAC delayed CRC. PLIB_ETH_DelayedCRCIsEnabled Gets the EMAC delayed CRC enable status. PLIB_ETH_Disable Disables the Ethernet module. PLIB_ETH_Enable Enables the Ethernet module. PLIB_ETH_ExcessDeferDisable Disables EMAC excess defer. PLIB_ETH_ExcessDeferEnable Enables EMAC excess defer. PLIB_ETH_ExcessDeferIsEnabled Gets the EMAC excess defer enable status. PLIB_ETH_FrameLengthCheckDisable Disables the EMAC frame length check. PLIB_ETH_FrameLengthCheckEnable Enables the EMAC frame length check. PLIB_ETH_FrameLengthCheckIsEnabled Gets the EMAC frame length check status. PLIB_ETH_FullDuplexDisable Disables the EMAC full duplex operation. PLIB_ETH_FullDuplexEnable Enables the EMAC full duplex operation. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 780 PLIB_ETH_FullDuplexIsEnabled Gets the EMAC full duplex enable status. PLIB_ETH_HugeFrameDisable Disables the EMAC from receiving huge frames. PLIB_ETH_HugeFrameEnable Enables the EMAC to receive huge frames. PLIB_ETH_HugeFrameIsEnabled Gets the EMAC huge frame enable status. PLIB_ETH_IsEnabled Gets the Ethernet module enable status. PLIB_ETH_LongPreambleDisable Disables EMAC long preamble enforcement. PLIB_ETH_LongPreambleEnable Enables EMAC long preamble enforcement. PLIB_ETH_LongPreambleIsEnabled Gets the EMAC long preamble enforcement enable status. PLIB_ETH_LoopbackDisable Disables the EMAC loopback logic. PLIB_ETH_LoopbackEnable Enables the EMAC loopback logic. PLIB_ETH_LoopbackIsEnabled Gets the EMAC Loopback interface enable status. PLIB_ETH_MaxFrameLengthGet Gets the EMAC maximum frame length. PLIB_ETH_MaxFrameLengthSet Sets the EMAC maximum frame length. PLIB_ETH_MIIMClockGet Gets the current EMAC MIIM clock selection. PLIB_ETH_MIIMClockSet Sets the EMAC MIM clock selection. PLIB_ETH_MIIMNoPreDisable Disables EMAC No Preamble (allows preamble). PLIB_ETH_MIIMNoPreEnable Enables EMAC MIIM No Preamble (suppresses preamble). PLIB_ETH_MIIMNoPreIsEnabled Gets the EMAC MIIM No Preamble enable status. PLIB_ETH_NonBackToBackIPG1Get Gets the EMAC non-back-to-back interpacket gap register 1. PLIB_ETH_NonBackToBackIPG1Set Sets the EMAC non-back-to-back interpacket gap register 1. PLIB_ETH_NonBackToBackIPG2Get Gets the EMAC non-back-to-back interpacket gap register 2. PLIB_ETH_NonBackToBackIPG2Set Sets the EMAC non-back-to-back interpacket gap register 2. PLIB_ETH_PauseTimerGet Gets the Pause Timer value used for flow control. PLIB_ETH_PauseTimerSet Sets the Pause Timer value used for flow control. PLIB_ETH_ReceiveBufferSizeGet Gets the Ethernet module receive buffer size. PLIB_ETH_ReceiveBufferSizeSet Sets the Ethernet module receive buffer size. PLIB_ETH_ReceiveDisable Disables the EMAC from receiving frames. PLIB_ETH_ReceiveEnable Enables the EMAC to receive the frames. PLIB_ETH_ReceiveIsEnabled Gets the Ethernet EMAC receive enable status. PLIB_ETH_ReTxMaxGet Gets the EMAC maximum retransmissions. PLIB_ETH_ReTxMaxSet Sets the EMAC maximum retransmissions. PLIB_ETH_RMIISpeedGet Gets the current EMAC RMII speed. PLIB_ETH_RMIISpeedSet Sets EMAC RMII Speed. PLIB_ETH_StopInIdleDisable Ethernet module operation will continue when the device enters Idle mode. PLIB_ETH_StopInIdleEnable Ethernet module operation will stop when the device enters Idle mode. PLIB_ETH_StopInIdleIsEnabled Gets the Ethernet module Stop in Idle mode enable status. b) Control Functions Name Description PLIB_ETH_MCSRxResetDisable Disables the reset EMAC Control Sub-layer/Receive domain logic. PLIB_ETH_MCSRxResetEnable Enables the reset EMAC Control Sub-layer/Receive domain logic. PLIB_ETH_MCSRxResetIsEnabled Gets the EMAC Control Sub-layer/Receive domain logic reset status. PLIB_ETH_MCSTxResetDisable Disables the reset EMAC Control Sub-layer/Transmit domain logic. PLIB_ETH_MCSTxResetEnable Enables the reset of EMAC Control Sub-layer/Transmit domain logic. PLIB_ETH_MCSTxResetIsEnabled Gets the EMAC Control Sub-layer/Transmit domain logic reset status. PLIB_ETH_MIIMReadDataGet Gets EMAC MIIM management read data after a MII read cycle has completed. PLIB_ETH_MIIMReadStart Initiates an MII management read command. PLIB_ETH_MIIMResetDisable Disables EMAC Reset MII Management. PLIB_ETH_MIIMResetEnable Enables EMAC Reset Media Independent Interface (MII) Management. PLIB_ETH_MIIMResetIsEnabled Gets the EMAC Reset MII Management enable status. PLIB_ETH_MIIMScanIncrEnable Enables EMAC MIIM Scan Increment. PLIB_ETH_MIIMScanIncrDisable Disables the EMAC MIIM Scan Increment. PLIB_ETH_MIIMScanIncrIsEnabled Gets the EMAC MIIM scan increment enable status. PLIB_ETH_MIIMScanModeDisable Disables MIIM scan mode. PLIB_ETH_MIIMScanModeEnable Enables MIIM scan mode. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 781 PLIB_ETH_MIIMScanModeIsEnabled Gets the MII management scan enable status. PLIB_ETH_MIIMWriteDataSet Sets the EMAC MIIM write data before initiating an MII write cycle. PLIB_ETH_MIIMWriteStart Initiates an MII management write command. PLIB_ETH_MIIResetDisable Disables the EMAC Soft reset. PLIB_ETH_MIIResetEnable Enables the EMAC MIIM Soft reset. PLIB_ETH_MIIResetIsEnabled Gets EMAC MIIM Soft Reset enable status. PLIB_ETH_PHYAddressGet Gets the EMAC MIIM management PHY address. PLIB_ETH_PHYAddressSet Sets the EMAC MIIM PHY address. PLIB_ETH_RegisterAddressGet Gets the EMAC MIIM management register address. PLIB_ETH_RegisterAddressSet Sets EMAC MIIM register address. PLIB_ETH_RMIIResetDisable Disables EMAC Reset RMII. PLIB_ETH_RMIIResetEnable Enables EMAC Reset RMII. PLIB_ETH_RMIIResetIsEnabled Gets the EMAC Reset RMII enable status. PLIB_ETH_RxBufferCountDecrement Causes the Receive Descriptor Buffer Counter to decrement by 1. PLIB_ETH_RxDisable Disables the Ethernet module receive logic. PLIB_ETH_RxEnable Enables the Ethernet receive logic. PLIB_ETH_RxFuncResetDisable Disables the EMAC reset receive function logic. PLIB_ETH_RxFuncResetEnable Enables the EMAC reset receive function logic. PLIB_ETH_RxFuncResetIsEnabled Gets the EMAC reset receive function status. PLIB_ETH_RxIsEnabled Gets the Ethernet module receive enable status. PLIB_ETH_RxPacketDescAddrGet Gets the address of the next receive descriptor. PLIB_ETH_RxPacketDescAddrSet Sets the Ethernet module receive packet descriptor start address. PLIB_ETH_TestPauseDisable Disables EMAC test pause. PLIB_ETH_TestPauseEnable Enables EMAC test pause. PLIB_ETH_TestPauseIsEnabled Gets the EMAC test pause enable status. PLIB_ETH_TxFuncResetDisable Disables the EMAC Transmit function reset. PLIB_ETH_TxFuncResetEnable Enables the EMAC transmit function reset. PLIB_ETH_TxFuncResetIsEnabled Gets the EMAC Transmit function reset status. PLIB_ETH_TxPacketDescAddrGet Gets the address of the next descriptor to be transmitted. PLIB_ETH_TxPacketDescAddrSet Sets the Ethernet module transmit packet descriptor start address. PLIB_ETH_TxRTSDisable Aborts an Ethernet module transmission. PLIB_ETH_TxRTSEnable Enables the Ethernet transmit request to send. PLIB_ETH_TxRTSIsEnabled Gets the Ethernet module transmit request to send status. PLIB_ETH_CRCDisable Disables EMAC CRC. PLIB_ETH_CRCEnable Enables EMAC CRC. PLIB_ETH_CRCIsEnabled Gets the EMAC CRC enable status. c) Status Functions Name Description PLIB_ETH_DataNotValid Gets the MII management read data not valid status. PLIB_ETH_EthernetIsBusy Gets the status value of the Ethernet logic busy. PLIB_ETH_LinkHasFailed Gets the MII management link fail status. PLIB_ETH_MIIMIsBusy Gets the MII management busy status. PLIB_ETH_MIIMIsScanning Gets the MII Management scanning status. PLIB_ETH_ReceiveIsBusy Gets the Ethernet receive logic busy status. PLIB_ETH_TransmitIsBusy Gets the status value of the Ethernet transmit logic busy status d) Filtering Functions Name Description PLIB_ETH_HashTableGet Gets the value of the Hash table. PLIB_ETH_HashTableSet Sets the Ethernet module Hash table with the new value. PLIB_ETH_PassAllDisable Disables the EMAC PassAll. PLIB_ETH_PassAllEnable Enables the EMAC PassAll. PLIB_ETH_PassAllIsEnabled Gets the EMAC PassAll enable status. PLIB_ETH_PatternMatchChecksumGet Gets the value of the pattern match checksum register. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 782 PLIB_ETH_PatternMatchChecksumSet Sets the Ethernet module pattern match checksum register with the new value. PLIB_ETH_PatternMatchGet Gets the value of the selected pattern match mask register. PLIB_ETH_PatternMatchModeGet Gets the value of the selected pattern match mask register. PLIB_ETH_PatternMatchModeSet Sets the Ethernet module pattern match mode. PLIB_ETH_PatternMatchOffsetGet Gets the value of the patter match offset register. PLIB_ETH_PatternMatchOffsetSet Sets the Ethernet module patter match offset register with the new value. PLIB_ETH_PatternMatchSet Sets the Ethernet module pattern match mask register with the new value. PLIB_ETH_PurePreambleDisable Disables EMAC pure preamble enforcement. PLIB_ETH_PurePreambleEnable Enables EMAC pure preamble enforcement. PLIB_ETH_PurePreambleIsEnabled Gets EMAC pure preamble enforcement enable status. PLIB_ETH_ReceiveFilterDisable Disables the specified receive filter. PLIB_ETH_ReceiveFilterEnable Enables the specified receive filter. PLIB_ETH_ReceiveFilterIsEnable Disables the specified receive filter. PLIB_ETH_StationAddressGet Gets the selected EMAC station address. PLIB_ETH_StationAddressSet Sets the selected EMAC Station Address. e) Flow Control Functions Name Description PLIB_ETH_AutoFlowControlDisable Disables the Ethernet module Automatic Flow Control logic. PLIB_ETH_AutoFlowControlEnable Enables the Ethernet Automatic Flow Control logic. PLIB_ETH_AutoFlowControlIsEnabled Gets the Ethernet module Automatic Flow Control status. PLIB_ETH_BackPresNoBackoffDisable Disables EMAC backpressure/no back-off. PLIB_ETH_BackPresNoBackoffEnable Enables EMAC back pressure/no back-off. PLIB_ETH_BackPresNoBackoffIsEnabled Gets the EMAC backpressure/no back-off enable status. PLIB_ETH_ManualFlowControlDisable Disable Ethernet module Manual Flow Control logic. PLIB_ETH_ManualFlowControlEnable Enables the Ethernet Manual Flow Control logic. PLIB_ETH_ManualFlowControlIsEnabled Gets the Ethernet module Manual Flow Control enable status. PLIB_ETH_NoBackoffDisable Disables EMAC no back-offs. PLIB_ETH_NoBackoffEnable Enables EMAC no back-off. PLIB_ETH_NoBackoffIsEnabled Gets the EMAC no back-off enable status. PLIB_ETH_RxEmptyWmarkGet Gets the Ethernet module receive empty watermark. PLIB_ETH_RxEmptyWmarkSet Sets the Ethernet module receive empty water mark. PLIB_ETH_RxFullWmarkGet Gets the Ethernet module to receive a full watermark. PLIB_ETH_RxFullWmarkSet Sets the Ethernet module to receive a full watermark. PLIB_ETH_RxPauseDisable Disables the EMAC receive flow control. PLIB_ETH_RxPauseEnable Enables the EMAC receive flow control. PLIB_ETH_RxPauseIsEnabled Gets the EMAC receive flow pause enable status. PLIB_ETH_ShortcutQuantaDisable Disables EMAC shortcut pause quanta. PLIB_ETH_ShortcutQuantaEnable Enables EMAC shortcut pause quanta. PLIB_ETH_ShortcutQuantaIsEnabled Gets EMAC shortcut pause quanta enable status. PLIB_ETH_SimResetDisable Disables the EMAC simulation reset. PLIB_ETH_SimResetEnable Enables the EMAC simulation reset. PLIB_ETH_SimResetIsEnabled Gets the EMAC simulation reset status. PLIB_ETH_TestBackPressDisable Disables EMAC Test backpressure. PLIB_ETH_TestBackPressEnable Enables EMAC Test backpressure. PLIB_ETH_TestBackPressIsEnabled Gets the EMAC test backpressure enable status. PLIB_ETH_TxPauseDisable Disables the transmission of Pause frames. PLIB_ETH_TxPauseEnable Enables the transmission Pause frames. PLIB_ETH_TxPauseIsEnabled Gets the Ethernet module enable status. f) Interrupt Functions Name Description PLIB_ETH_InterruptClear Clears the Ethernet module interrupt source status as a group, using a mask. PLIB_ETH_InterruptSet Sets the Ethernet module interrupt source status as a group, using a mask. PLIB_ETH_InterruptsGet Gets the Ethernet module Interrupt Flag register as a group. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 783 PLIB_ETH_InterruptSourceDisable Clears the Ethernet module Interrupt Enable register as a group, using a mask. PLIB_ETH_InterruptSourceEnable Sets the Ethernet module Interrupt Enable register in a group, using a mask. PLIB_ETH_InterruptSourceIsEnabled Gets the Ethernet module Interrupt Enable register singularly or as a group. PLIB_ETH_InterruptSourcesGet Returns the entire interrupt enable register. PLIB_ETH_InterruptStatusGet Gets the Ethernet module Interrupt Flag register as a group, using a mask. g) Statistics Functions Name Description PLIB_ETH_AlignErrorCountClear Sets the count of Ethernet alignment errors to zero. PLIB_ETH_AlignErrorCountGet Gets the count of Ethernet alignment errors. PLIB_ETH_FCSErrorCountClear Sets the value of the Ethernet frame check sequence error to zero. PLIB_ETH_FCSErrorCountGet Gets the count of the frame check sequence error. PLIB_ETH_FramesRxdOkCountClear Sets the value of the Ethernet received frames 'OK' count to zero. PLIB_ETH_FramesRxdOkCountGet Gets the count of the frames frames received successfully. PLIB_ETH_FramesTxdOkCountClear Sets the count of Ethernet Control frames transmitted to zero. PLIB_ETH_FramesTxdOkCountGet Gets the count of Ethernet Control Frames transmitted successfully. PLIB_ETH_MultipleCollisionCountClear Sets the value of the Ethernet multiple collision frame count to zero. PLIB_ETH_MultipleCollisionCountGet Gets the count of the frames transmitted successfully after there was more than one collision. PLIB_ETH_RxOverflowCountClear Sets the value of the Ethernet receive overflow count to zero. PLIB_ETH_RxOverflowCountGet Gets the count of the dropped Ethernet receive frames. PLIB_ETH_RxPacketCountGet Gets the value of the receive packet buffer count. PLIB_ETH_SingleCollisionCountClear Sets the value of the Ethernet single collision frame count to zero. PLIB_ETH_SingleCollisionCountGet Gets the count of the frames transmitted successfully on a second attempt. h) Feature Existence Functions Name Description PLIB_ETH_ExistsAlignmentErrorCount Identifies whether the AlignmentErrorCount feature exists on the Ethernet module. PLIB_ETH_ExistsAutoFlowControl Identifies whether the AutoFlowControl feature exists on the Ethernet module. PLIB_ETH_ExistsCollisionCounts Identifies whether the CollisionCounts feature exists on the Ethernet module. PLIB_ETH_ExistsCollisionWindow Identifies whether the CollisionWindow feature exists on the Ethernet module. PLIB_ETH_ExistsEnable Identifies whether the Enable feature exists on the Ethernet module. PLIB_ETH_ExistsEthernetControllerStatus Identifies whether the EthernetControllerStatus feature exists on the Ethernet module. PLIB_ETH_ExistsFCSErrorCount Identifies whether the FCSErrorCount feature exists on the Ethernet module. PLIB_ETH_ExistsFramesTransmittedOK Identifies whether the FramesTransmittedOK feature exists on the Ethernet module. PLIB_ETH_ExistsFramexReceivedOK Identifies whether the FramexReceivedOK feature exists on the Ethernet module. PLIB_ETH_ExistsHashTable Identifies whether the HashTable feature exists on the Ethernet module. PLIB_ETH_ExistsInterPacketGaps Identifies whether the InterPacketGaps feature exists on the Ethernet module. PLIB_ETH_ExistsInterrupt Identifies whether the Interrupt feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Configuration Identifies whether the MAC_Configuration feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Resets Identifies whether the MAC_Resets feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Testing Identifies whether the MAC_Testing feature exists on the Ethernet module. PLIB_ETH_ExistsManualFlowControl Identifies whether the ManualFlowControl feature exists on the Ethernet module. PLIB_ETH_ExistsMaxFrameLength Identifies whether the MaxFrameLength feature exists on the Ethernet module. PLIB_ETH_ExistsMIIM_Config Identifies whether the MIIM_Config feature exists on the Ethernet module. PLIB_ETH_ExistsMIIM_Indicators Identifies whether the MIIM_Indicators feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMAddresses Identifies whether the MIIMAddresses feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMReadWrite Identifies whether the MIIMReadWrite feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMScanMode Identifies whether the MIIMScanMode feature exists on the Ethernet module. PLIB_ETH_ExistsMIIWriteReadData Identifies whether the MIIWriteReadData feature exists on the Ethernet module. PLIB_ETH_ExistsPatternMatch Identifies whether the PatternMatch feature exists on the Ethernet module. PLIB_ETH_ExistsPauseTimer Identifies whether the PauseTimer feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveBufferSize Identifies whether the ReceiveBufferSize feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveFilters Identifies whether the ReceiveFilters feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveOverflowCount Identifies whether the ReceiveOverflowCount feature exists on the Ethernet module. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 784 PLIB_ETH_ExistsReceiveWmarks Identifies whether the ReceiveWmarks feature exists on the Ethernet module. PLIB_ETH_ExistsRetransmissionMaximum Identifies whether the RetransmissionMaximum feature exists on the Ethernet module. PLIB_ETH_ExistsRMII_Support Identifies whether the RMII_Support feature exists on the Ethernet module. PLIB_ETH_ExistsRxBufferCountDecrement Identifies whether the RxBufferCountDecrement feature exists on the Ethernet module. PLIB_ETH_ExistsRxEnable Identifies whether the ReceiveEnable feature exists on the Ethernet module. PLIB_ETH_ExistsRxPacketDescriptorAddress Identifies whether the RxPacketDescriptorAddress feature exists on the Ethernet module. PLIB_ETH_ExistsStationAddress Identifies whether the StationAddress feature exists on the Ethernet module. PLIB_ETH_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the Ethernet module. PLIB_ETH_ExistsTransmitRTS Identifies whether the TransmitRTS feature exists on the Ethernet module. PLIB_ETH_ExistsTxPacketDescriptorAddress Identifies whether the TxPacketDescriptorAddress feature exists on the Ethernet module. i) Data Types and Constants Name Description ETH_AUTOPAD_OPTION Lists the possible automatic padding configurations. ETH_INTERRUPT_SOURCES Lists the possible values of ETH_INTERRUPT_SOURCES. ETH_MIIM_CLK Lists the possible speed selection for the Reduced Media Independent Interface (RMII). ETH_PATTERN_MATCH_MODE Lists the possible pattern match values. _ETH_PATTERN_MATCH_MODE_ Lists the possible pattern match values. ETH_RECEIVE_FILTER Lists the possible values of the receive filter. ETH_RMII_SPEED Lists the possible speed selection for the Reduced Media Independent Interface (RMII). Description This section describes the Application Programming Interface (API) functions of the Ethernet Peripheral Library. Refer to each section for a detailed description. a) Initialization Functions PLIB_ETH_AutoDetectPadClear Function Clears the EMAC Auto-Pad option. File plib_eth.h C void PLIB_ETH_AutoDetectPadClear(ETH_MODULE_ID index, ETH_AUTOPAD_OPTION option); Returns None. Description This function sets the EMAC Auto-Pad option. If any auto-pad option other than ETH_AUTOPAD_DISABLED_CHECK_CRC is selected, the CRC must be enabled by PLIB_ETH_CRCEnable. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_AutoDetectPadClear(MY_ETH_INSTANCE, PAD_OPTION); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 785 Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_AutoDetectPadClear(ETH_MODULE_ID index, ETH_AUTOPAD_OPTION option ); PLIB_ETH_AutoDetectPadGet Function Gets the current EMAC Auto-Pad setting. File plib_eth.h C ETH_AUTOPAD_OPTION PLIB_ETH_AutoDetectPadGet(ETH_MODULE_ID index); Returns ETH_AUTOPAD_OPTION. Description This function gets the current EMAC Auto-Pad setting. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example autoPadOption = PLIB_ETH_AutoDetectPadGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function ETH_AUTOPAD_OPTION PLIB_ETH_AutoDetectPadGet(ETH_MODULE_ID index); PLIB_ETH_AutoDetectPadSet Function Sets the EMAC Auto-Pad option. File plib_eth.h C void PLIB_ETH_AutoDetectPadSet(ETH_MODULE_ID index, ETH_AUTOPAD_OPTION option); Returns None. Description This function sets the EMAC Auto-Pad option. If any auto-pad option other than ETH_AUTOPAD_DISABLED_CHECK_CRC is selected, the CRC must be enabled by PLIB_ETH_CRCEnable. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 786 Example PLIB_ETH_AutoDetectPadSet(MY_ETH_INSTANCE, PAD_OPTION); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_AutoDetectPadSet(ETH_MODULE_ID index, ETH_AUTOPAD_OPTION option ); PLIB_ETH_BackToBackIPGGet Function Gets the EMAC back-to-back interpacket gap. File plib_eth.h C uint8_t PLIB_ETH_BackToBackIPGGet(ETH_MODULE_ID index); Returns • backToBackIPGValue - Back-to-back interpacket gap (7 bits) Description This function gets the EMAC back-to-back interpacket gap. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_BackToBackIPGGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_BackToBackIPGGet(ETH_MODULE_ID index) PLIB_ETH_BackToBackIPGSet Function Sets the EMAC back-to-back interpacket gap. File plib_eth.h C void PLIB_ETH_BackToBackIPGSet(ETH_MODULE_ID index, uint8_t backToBackIPGValue); Returns None. Description This function sets the EMAC back-to-back interpacket gap. Remarks In Full-Duplex mode, the register value should be the desired period in nibble times minus 3. In Full-Duplex, the recommended setting is 0x15. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 787 In Half-Duplex mode, the register value should be the desired period in nibble times minus 6. n Half-Duplex, the recommended setting is 0x12. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_BackToBackIPGSet(MY_ETH_INSTANCE, backToBackIPGValue); Parameters Parameters Description index Identifier for the device instance backToBackIPGValue Back-to-back interpacket gap Function void PLIB_ETH_BackToBackIPGSet(ETH_MODULE_ID index, uint8_t backToBackIPGValue) PLIB_ETH_CollisionWindowGet Function Gets the EMAC collision window. File plib_eth.h C uint8_t PLIB_ETH_CollisionWindowGet(ETH_MODULE_ID index); Returns • collisionWindowValue - A uint8_t (6-bit) value. Description This function gets the EMAC collision window. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_CollisionWindowGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_CollisionWindowGet(ETH_MODULE_ID index) PLIB_ETH_CollisionWindowSet Function Sets the EMAC collision window. File plib_eth.h C void PLIB_ETH_CollisionWindowSet(ETH_MODULE_ID index, uint8_t collisionWindowValue); Returns None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 788 Description This function sets the EMAC collision window. Remarks This is a programmable field representing the slot time or collision window during which collisions occur in properly configured networks. Since the collision window starts at the beginning of transmission, the preamble and SFD is included. Its default of 0x37 (55d) corresponds to the count of frame bytes at the end of the window. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_CollisionWindowSet(MY_ETH_INSTANCE, collisionWindowValue); Parameters Parameters Description index Identifier for the device instance collisionWindowValue Collision window Function void PLIB_ETH_CollisionWindowSet(ETH_MODULE_ID index, uint8_t collisionWindowValue) PLIB_ETH_DelayedCRCDisable Function Disables EMAC delayed CRC. File plib_eth.h C void PLIB_ETH_DelayedCRCDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC delayed CRC. No proprietary header exists. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_DelayedCRCDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_DelayedCRCDisable(ETH_MODULE_ID index) PLIB_ETH_DelayedCRCEnable Function Enables EMAC delayed CRC. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 789 File plib_eth.h C void PLIB_ETH_DelayedCRCEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC delayed CRC. A proprietary packet header exists. Four bytes of the packet header are ignored by the CRC function. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_DelayedCRCEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_DelayedCRCEnable(ETH_MODULE_ID index) PLIB_ETH_DelayedCRCIsEnabled Function Gets the EMAC delayed CRC enable status. File plib_eth.h C bool PLIB_ETH_DelayedCRCIsEnabled(ETH_MODULE_ID index); Returns • true - A proprietary header exists. Four bytes of packet header are ignored by the CRC function. • false - No proprietary header Description This function returns the EMAC delayed CRC enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_DelayedCRCIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_DelayedCRCIsEnabled(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 790 PLIB_ETH_Disable Function Disables the Ethernet module. File plib_eth.h C void PLIB_ETH_Disable(ETH_MODULE_ID index); Returns None. Description This function disables the Ethernet module. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_Disable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_Disable(ETH_MODULE_ID index) PLIB_ETH_Enable Function Enables the Ethernet module. File plib_eth.h C void PLIB_ETH_Enable(ETH_MODULE_ID index); Returns None. Description This function enables the Ethernet module. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_Enable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 791 Function void PLIB_ETH_Enable(ETH_MODULE_ID index) PLIB_ETH_ExcessDeferDisable Function Disables EMAC excess defer. File plib_eth.h C void PLIB_ETH_ExcessDeferDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC excess defer. The EMAC will abort when the excessive deferral limit is reached. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ExcessDeferDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_ExcessDeferDisable(ETH_MODULE_ID index) PLIB_ETH_ExcessDeferEnable Function Enables EMAC excess defer. File plib_eth.h C void PLIB_ETH_ExcessDeferEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC excess defer. The EMAC will defer to the carrier indefinitely. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ExcessDeferEnable(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 792 Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_ExcessDeferEnable(ETH_MODULE_ID index) PLIB_ETH_ExcessDeferIsEnabled Function Gets the EMAC excess defer enable status. File plib_eth.h C bool PLIB_ETH_ExcessDeferIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC will defer to carrier indefinitely as per the Standard • false - The EMAC will abort when the excessive deferral limit is reached Description This function gets the EMAC excess defer enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_ExcessDeferIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_ExcessDeferIsEnabled(ETH_MODULE_ID index) PLIB_ETH_FrameLengthCheckDisable Function Disables the EMAC frame length check. File plib_eth.h C void PLIB_ETH_FrameLengthCheckDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC frame length check. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 793 Preconditions None. Example PLIB_ETH_FrameLengthCheckDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_FrameLengthCheckDisable(ETH_MODULE_ID index) PLIB_ETH_FrameLengthCheckEnable Function Enables the EMAC frame length check. File plib_eth.h C void PLIB_ETH_FrameLengthCheckEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC frame length check. Both transmit and receive frame lengths are compared to the Length/Type field. If the Length/Type field represents a length, the check is performed. Mismatches are reported on the transmit/receive statistics vector. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_FrameLengthCheckEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_FrameLengthCheckEnable(ETH_MODULE_ID index) PLIB_ETH_FrameLengthCheckIsEnabled Function Gets the EMAC frame length check status. File plib_eth.h C bool PLIB_ETH_FrameLengthCheckIsEnabled(ETH_MODULE_ID index); Returns • true - Both transmit and receive frame lengths are compared to the Length/Type field. If the Length/Type field represents a length then the check is performed. Mismatches are reported on the transmit/receive statistics vector. • false - Length/Type field check is not performed Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 794 Description This function returns the EMAC frame length check status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_FrameLengthCheckIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_FrameLengthCheckIsEnabled(ETH_MODULE_ID index) PLIB_ETH_FullDuplexDisable Function Disables the EMAC full duplex operation. File plib_eth.h C void PLIB_ETH_FullDuplexDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC full-duplex operation, which results in the EMAC operating in half-duplex. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_FullDuplexDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_FullDuplexDisable(ETH_MODULE_ID index) PLIB_ETH_FullDuplexEnable Function Enables the EMAC full duplex operation. File plib_eth.h C void PLIB_ETH_FullDuplexEnable(ETH_MODULE_ID index); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 795 Returns None. Description This function enables the EMAC full duplex operation. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_FullDuplexEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_FullDuplexEnable(ETH_MODULE_ID index) PLIB_ETH_FullDuplexIsEnabled Function Gets the EMAC full duplex enable status. File plib_eth.h C bool PLIB_ETH_FullDuplexIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC operates in Full-Duplex mode • false - The EMAC operates in Half-Duplex mode Description This function returns the EMAC full duplex enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_FullDuplexIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_FullDuplexIsEnabled(ETH_MODULE_ID index) PLIB_ETH_HugeFrameDisable Function Disables the EMAC from receiving huge frames. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 796 File plib_eth.h C void PLIB_ETH_HugeFrameDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC from receiving huge frames. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_HugeFrameDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_HugeFrameDisable(ETH_MODULE_ID index) PLIB_ETH_HugeFrameEnable Function Enables the EMAC to receive huge frames. File plib_eth.h C void PLIB_ETH_HugeFrameEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC receiving the frames of any length. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_HugeFrameEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_HugeFrameEnable(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 797 PLIB_ETH_HugeFrameIsEnabled Function Gets the EMAC huge frame enable status. File plib_eth.h C bool PLIB_ETH_HugeFrameIsEnabled(ETH_MODULE_ID index); Returns • true - Frames of any length are transmitted and received • false - Huge frames are not allowed for receive or transmit Description This function returns the EMAC huge frame enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_HugeFrameIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_HugeFrameIsEnabled(ETH_MODULE_ID index) PLIB_ETH_IsEnabled Function Gets the Ethernet module enable status. File plib_eth.h C bool PLIB_ETH_IsEnabled(ETH_MODULE_ID index); Returns • true - Ethernet module is enabled • false - Ethernet module is disabled Description This function returns the Ethernet module enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_IsEnabled(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 798 Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_IsEnabled(ETH_MODULE_ID index) PLIB_ETH_LongPreambleDisable Function Disables EMAC long preamble enforcement. File plib_eth.h C void PLIB_ETH_LongPreambleDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC long preamble enforcement. The EMAC allows any length preamble. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_LongPreambleDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_LongPreambleDisable(ETH_MODULE_ID index) PLIB_ETH_LongPreambleEnable Function Enables EMAC long preamble enforcement. File plib_eth.h C void PLIB_ETH_LongPreambleEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC long preamble enforcement. The EMAC only allows receive packets which contain preamble fields less than 12 bytes in length. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 799 Example PLIB_ETH_LongPreambleEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_LongPreambleEnable(ETH_MODULE_ID index) PLIB_ETH_LongPreambleIsEnabled Function Gets the EMAC long preamble enforcement enable status. File plib_eth.h C bool PLIB_ETH_LongPreambleIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC only allows receive packets, which contain preamble fields less than 12 bytes in length • false - The EMAC allows any length preamble Description This function gets the EMAC long preamble enforcement enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_LongPreambleIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_LongPreambleIsEnabled(ETH_MODULE_ID index) PLIB_ETH_LoopbackDisable Function Disables the EMAC loopback logic. File plib_eth.h C void PLIB_ETH_LoopbackDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC loopback. EMAC resumes normal operation. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 800 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_LoopbackDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_LoopbackDisable(ETH_MODULE_ID index) PLIB_ETH_LoopbackEnable Function Enables the EMAC loopback logic. File plib_eth.h C void PLIB_ETH_LoopbackEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC loopback logic. The EMAC transmit interface is looped back to the EMAC receive interface. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_LoopbackEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_LoopbackEnable(ETH_MODULE_ID index) PLIB_ETH_LoopbackIsEnabled Function Gets the EMAC Loopback interface enable status. File plib_eth.h C bool PLIB_ETH_LoopbackIsEnabled(ETH_MODULE_ID index); Returns • true - EMAC transmit interface is looped back to the EMAC receive interface Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 801 • false - EMAC normal operation Description This function gets the EMAC Loopback interface enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_LoopbackIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_LoopbackIsEnabled(ETH_MODULE_ID index) PLIB_ETH_MaxFrameLengthGet Function Gets the EMAC maximum frame length. File plib_eth.h C uint16_t PLIB_ETH_MaxFrameLengthGet(ETH_MODULE_ID index); Returns • MaxFrameLength - Maximum frame length Description This function gets the EMAC maximum frame length. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_MaxFrameLengthGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_MaxFrameLengthGet(ETH_MODULE_ID index) PLIB_ETH_MaxFrameLengthSet Function Sets the EMAC maximum frame length. File plib_eth.h C void PLIB_ETH_MaxFrameLengthSet(ETH_MODULE_ID index, uint16_t MaxFrameLength); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 802 Returns None. Description This function sets the EMAC maximum frame length. Remarks This field resets to 0x05EE, which represents a maximum receive frame of 1518 bytes. An untagged maximum size Ethernet frame is 1518 bytes. A tagged frame adds four octets for a total of 1522 bytes. If a shorter/longer maximum length restriction is desired, program this 16-bit field. If a proprietary header is allowed, this field should be adjusted accordingly. For example, if 4-byte headers are prepended to frames, MACMAXF could be set to 1527 bytes. This would allow the maximum VLAN tagged frame plus the 4-byte header. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MaxFrameLengthSet(MY_ETH_INSTANCE, MaxFrameLength); Parameters Parameters Description index Identifier for the device instance MaxFrameLength Maximum frame length Function void PLIB_ETH_MaxFrameLengthSet(ETH_MODULE_ID index, uint16_t MaxFrameLength) PLIB_ETH_MIIMClockGet Function Gets the current EMAC MIIM clock selection. File plib_eth.h C ETH_MIIM_CLK PLIB_ETH_MIIMClockGet(ETH_MODULE_ID index); Returns • MIIMClock - Of type PLIB_ETH_MIIM_CLK Description This function returns the current EMAC MIIM clock selection. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example clkstat = PLIB_ETH_MIIMClockGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function ETH_MII_CLK PLIB_ETH_MIIMClockGet(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 803 PLIB_ETH_MIIMClockSet Function Sets the EMAC MIM clock selection. File plib_eth.h C void PLIB_ETH_MIIMClockSet(ETH_MODULE_ID index, ETH_MIIM_CLK MIIMClock); Returns None. Description This function sets the EMAC MIIM clock selection. Remarks This field is used by the clock divide logic in creating the MII Management Clock (MDC), which the IEEE 802.3 Specification defines to be no faster than 2.5 MHz. Some PHYs support clock rates up to 12.5 MHz. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIMClockSet(MY_ETH_INSTANCE, MIIMClock); Parameters Parameters Description index Identifier for the device instance MIIMClock of type ETH_MIIM_CLK - the system clock divisor for MII Function void PLIB_ETH_MIIMClockSet(ETH_MODULE_ID index, ETH_MIIM_CLK MIIMClock) PLIB_ETH_MIIMNoPreDisable Function Disables EMAC No Preamble (allows preamble). File plib_eth.h C void PLIB_ETH_MIIMNoPreDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC No preamble (allows preamble). Normal read/write cycles are performed. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIMNoPreDisable(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 804 Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIMNoPreDisable(ETH_MODULE_ID index) PLIB_ETH_MIIMNoPreEnable Function Enables EMAC MIIM No Preamble (suppresses preamble). File plib_eth.h C void PLIB_ETH_MIIMNoPreEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC MIIM No Preamble (suppresses preamble). The MII Management will perform read/write cycles without the 32-bit preamble field. Some PHYs support suppressed preamble. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIMNoPreEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIMNoPreEnable(ETH_MODULE_ID index) PLIB_ETH_MIIMNoPreIsEnabled Function Gets the EMAC MIIM No Preamble enable status. File plib_eth.h C bool PLIB_ETH_MIIMNoPreIsEnabled(ETH_MODULE_ID index); Returns • true - The MII Management will perform read/write cycles without the 32-bit preamble field. Some PHYs support suppressed preamble. • false - Normal read/write cycles are performed Description This function gets the EMAC MIIM No Preamble enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 805 Preconditions None. Example stat = PLIB_ETH_MIIMNoPreIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_MIIMNoPreIsEnabled(ETH_MODULE_ID index) PLIB_ETH_NonBackToBackIPG1Get Function Gets the EMAC non-back-to-back interpacket gap register 1. File plib_eth.h C uint8_t PLIB_ETH_NonBackToBackIPG1Get(ETH_MODULE_ID index); Returns • nonBackToBackIPGValue - Non-back-to-back interpacket gap (7 bits) Description This function gets the EMAC non-back-to-back interpacket gap register 1. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_NonBackToBackIPG1Get(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_NonBackToBackIPG1Get(ETH_MODULE_ID index) PLIB_ETH_NonBackToBackIPG1Set Function Sets the EMAC non-back-to-back interpacket gap register 1. File plib_eth.h C void PLIB_ETH_NonBackToBackIPG1Set(ETH_MODULE_ID index, uint8_t nonBackToBackIPGValue); Returns None. Description This function sets the EMAC non-back-to-back interpacket gap register 1. A value of 0x0C is recommended. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 806 Remarks This is a programmable field representing the optional carrierSense window referenced in the IEEE 802.3 Specification. If a carrier is detected during the timing of IPGR1, the MAC defers to the carrier. If, however, the carrier comes after IPGR1, the MAC continues timing IPGR2 and transmits, knowingly causing a collision, thereby ensuring fair access to the medium. Its range of values is 0x0 to IPGR2. Its recommended value is 0xC (12d). This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_NonBackToBackIPG1Set(MY_ETH_INSTANCE, nonBackToBackIPGValue); Parameters Parameters Description index Identifier for the device instance nonBackToBackIPGValue Non-back-to-back interpacket gap Function void PLIB_ETH_NonBackToBackIPG1Set(ETH_MODULE_ID index, uint8_t nonBackToBackIPGValue) PLIB_ETH_NonBackToBackIPG2Get Function Gets the EMAC non-back-to-back interpacket gap register 2. File plib_eth.h C uint8_t PLIB_ETH_NonBackToBackIPG2Get(ETH_MODULE_ID index); Returns • nonBackToBackIPGValue - Non-back-to-back interpacket gap (7 bits) Description This function gets the EMAC non-back-to-back interpacket gap register 2. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_NonBackToBackIPG2Get(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_NonBackToBackIPG2Get(ETH_MODULE_ID index) PLIB_ETH_NonBackToBackIPG2Set Function Sets the EMAC non-back-to-back interpacket gap register 2. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 807 C void PLIB_ETH_NonBackToBackIPG2Set(ETH_MODULE_ID index, uint8_t nonBackToBackIPGValue); Returns None. Description This function sets the EMAC non-back-to-back interpacket gap register 2. A value of 0x12 is recommended. Remarks This is a programmable field representing the non-back-to-back Inter-Packet-Gap. Its recommended value is 0x12 (18d), which represents the minimum IPG of 0.96 us (in 100 Mbps) or 9.6 us (in 10 Mbps). This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_NonBackToBackIPG2Set(MY_ETH_INSTANCE, nonBackToBackIPGValue); Parameters Parameters Description index Identifier for the device instance nonBackToBackIPGValue Non-back-to-back interpacket gap Function void PLIB_ETH_NonBackToBackIPG2Set(ETH_MODULE_ID index, uint8_t nonBackToBackIPGValue) PLIB_ETH_PauseTimerGet Function Gets the Pause Timer value used for flow control. File plib_eth.h C uint16_t PLIB_ETH_PauseTimerGet(ETH_MODULE_ID index); Returns • PauseTimerValue - Pause Timer Value Description This function gets the Pause Timer value used for flow control. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PauseTimerValue = PLIB_ETH_PauseTimerGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_PauseTimerGet(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 808 PLIB_ETH_PauseTimerSet Function Sets the Pause Timer value used for flow control. File plib_eth.h C void PLIB_ETH_PauseTimerSet(ETH_MODULE_ID index, uint16_t PauseTimerValue); Returns None. Description This function sets the Pause Timer value used for flow control. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions Write to the Pause Timer register before enabling the receiver. Call this function before calling PLIB_ETH_ReceiveEnable. Example PLIB_ETH_PauseTimerSet(MY_ETH_INSTANCE, PauseTimerValue); Parameters Parameters Description index Identifier for the device instance PauseTimerValue used for Flow Control Function void PLIB_ETH_PauseTimerSet(ETH_MODULE_ID index, uint16_t PauseTimerValue) PLIB_ETH_ReceiveBufferSizeGet Function Gets the Ethernet module receive buffer size. File plib_eth.h C uint8_t PLIB_ETH_ReceiveBufferSizeGet(ETH_MODULE_ID index); Returns ReceiveBufferSize - receive buffer size divided by 16 Description This function gets the Ethernet receive buffer size. The buffer size is set from 16 bytes up to 2032 bytes in increments of 16 bytes each. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example size = PLIB_ETH_ReceiveBufferSizeGet(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 809 Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_ReceiveBufferSizeGet(ETH_MODULE_ID index) PLIB_ETH_ReceiveBufferSizeSet Function Sets the Ethernet module receive buffer size. File plib_eth.h C void PLIB_ETH_ReceiveBufferSizeSet(ETH_MODULE_ID index, uint8_t ReceiveBufferSize); Returns None. Description This function sets the Ethernet receive buffer size. The buffer size is set from 16 bytes up to 2032 bytes in increments of 16 bytes each. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ReceiveBufferSizeSet(MY_ETH_INSTANCE, ReceiveBufferSize/16 ); Parameters Parameters Description index Identifier for the device instance ReceiveBufferSize In units of 16 bytes, must be a value of 0x01 to 0x7F, 0x00 is invalid Function void PLIB_ETH_ReceiveBufferSizeSet(ETH_MODULE_ID index, uint8_t ReceiveBufferSize) PLIB_ETH_ReceiveDisable Function Disables the EMAC from receiving frames. File plib_eth.h C void PLIB_ETH_ReceiveDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC from receiving frames. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 810 Preconditions None. Example PLIB_ETH_ReceiveDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_ReceiveDisable(ETH_MODULE_ID index) PLIB_ETH_ReceiveEnable Function Enables the EMAC to receive the frames. File plib_eth.h C void PLIB_ETH_ReceiveEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC to receive the frames. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ReceiveEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_ReceiveEnable(ETH_MODULE_ID index) PLIB_ETH_ReceiveIsEnabled Function Gets the Ethernet EMAC receive enable status. File plib_eth.h C bool PLIB_ETH_ReceiveIsEnabled(ETH_MODULE_ID index); Returns • true - Enable the EMAC to receive frames • false - Disable the EMAC to receive frames Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 811 Description This function gets the Ethernet EMAC receive enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_ReceiveIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_ReceiveIsEnabled(ETH_MODULE_ID index) PLIB_ETH_ReTxMaxGet Function Gets the EMAC maximum retransmissions. File plib_eth.h C uint8_t PLIB_ETH_ReTxMaxGet(ETH_MODULE_ID index); Returns • retransmitMax - Maximum number of retransmissions Description This function gets the EMAC maximum retransmissions. Remarks The maximum number of attempts is limited to 0x0F. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_ReTxMaxGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_ReTxMaxGet(ETH_MODULE_ID index) PLIB_ETH_ReTxMaxSet Function Sets the EMAC maximum retransmissions. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 812 C void PLIB_ETH_ReTxMaxSet(ETH_MODULE_ID index, uint16_t retransmitMax); Returns None. Description This function sets the EMAC maximum retransmissions. Remarks This is a programmable field specifying the number of retransmission attempts following a collision before aborting the packet due to excessive collisions. The IEEE 802.3 Specification standard specifies the maximum number of attempts (attemptLimit) to be 0xF (15d). Its default is 000. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ReTxMaxSet(retransmitMax); Parameters Parameters Description index Identifier for the device instance retransmitMax Maximum number of retransmissions Function void PLIB_ETH_ReTxMaxSet(ETH_MODULE_ID index, uint8_t retransmitMax) PLIB_ETH_RMIISpeedGet Function Gets the current EMAC RMII speed. File plib_eth.h C ETH_RMII_SPEED PLIB_ETH_RMIISpeedGet(ETH_MODULE_ID index); Returns • RMII_100Mbps - RMII running at 100 Mbps • RMII_10Mbps - RMII running at 10 Mbps Description This function gets the current EMAC RMII speed. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RMIISpeedGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function ETH_RMII_SPEED PLIB_ETH_RMIISpeedGet(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 813 PLIB_ETH_RMIISpeedSet Function Sets EMAC RMII Speed. File plib_eth.h C void PLIB_ETH_RMIISpeedSet(ETH_MODULE_ID index, ETH_RMII_SPEED RMIISpeed); Returns None. Description This function sets EMAC RMII speed. RMII speed can be either RMII_100Mbps or RMII_10Mbps. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RMIISpeedSet(MY_ETH_INSTANCE, ETH_RMII_SPEED RMIISpeed); Parameters Parameters Description index Identifier for the device instance RMIISpeed RMII_100Mbps or RMII_10Mbps of type ETH_RMII_SPEED Function void PLIB_ETH_RMIISpeedSet(ETH_MODULE_ID index, ETH_RMII_SPEED RMIISpeed) PLIB_ETH_StopInIdleDisable Function Ethernet module operation will continue when the device enters Idle mode. File plib_eth.h C void PLIB_ETH_StopInIdleDisable(ETH_MODULE_ID index); Returns None. Description This function directs the Ethernet module to continue operation when the device enters Idle mode. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_StopInIdleDisable(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 814 Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_StopInIdleDisable(ETH_MODULE_ID index) PLIB_ETH_StopInIdleEnable Function Ethernet module operation will stop when the device enters Idle mode. File plib_eth.h C void PLIB_ETH_StopInIdleEnable(ETH_MODULE_ID index); Returns None. Description This function directs the Ethernet module to stop operation when the device enters Idle mode. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_StopInIdleEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_StopInIdleEnable(ETH_MODULE_ID index) PLIB_ETH_StopInIdleIsEnabled Function Gets the Ethernet module Stop in Idle mode enable status. File plib_eth.h C bool PLIB_ETH_StopInIdleIsEnabled(ETH_MODULE_ID index); Returns • true - Ethernet module transfers stop during Idle mode • false - Ethernet module transfers continue to run during Idle mode Description This function returns the Ethernet module Stop in Idle mode enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 815 Preconditions None. Example stat = PLIB_ETH_StopInIdleIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_StopInIdleIsEnabled(ETH_MODULE_ID index) b) Control Functions PLIB_ETH_MCSRxResetDisable Function Disables the reset EMAC Control Sub-layer/Receive domain logic. File plib_eth.h C void PLIB_ETH_MCSRxResetDisable(ETH_MODULE_ID index); Returns None. Description This function disables the reset EMAC Control Sub-layer/Receive domain logic. The MCS/Receive domain logic is released from reset. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MCSRxResetDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MCSRxResetDisable(ETH_MODULE_ID index) PLIB_ETH_MCSRxResetEnable Function Enables the reset EMAC Control Sub-layer/Receive domain logic. File plib_eth.h C void PLIB_ETH_MCSRxResetEnable(ETH_MODULE_ID index); Returns None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 816 Description This function enables the reset EMAC Control Sub-layer/Receive domain logic. The MCS/Receive domain logic is held in reset. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MCSRxResetEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MCSRxResetEnable(ETH_MODULE_ID index) PLIB_ETH_MCSRxResetIsEnabled Function Gets the EMAC Control Sub-layer/Receive domain logic reset status. File plib_eth.h C bool PLIB_ETH_MCSRxResetIsEnabled(ETH_MODULE_ID index); Returns • true - EMAC Control Sub-layer/Receive domain logic is in reset • false - EMAC Control Sub-layer/Receive domain logic is not in reset Description This function gets the EMAC Control Sub-layer/Receive domain logic reset status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_MCSRxResetIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_MCSRxResetIsEnabled(ETH_MODULE_ID index) PLIB_ETH_MCSTxResetDisable Function Disables the reset EMAC Control Sub-layer/Transmit domain logic. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 817 C void PLIB_ETH_MCSTxResetDisable(ETH_MODULE_ID index); Returns None. Description This function disables the reset EMAC Control Sub-layer/Transmit domain logic. The MCS/Transmit domain logic is released from reset. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MCSTxResetDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MCSTxResetDisable(ETH_MODULE_ID index) PLIB_ETH_MCSTxResetEnable Function Enables the reset of EMAC Control Sub-layer/Transmit domain logic. File plib_eth.h C void PLIB_ETH_MCSTxResetEnable(ETH_MODULE_ID index); Returns None. Description This function resets the EMAC Control Sub-layer/Transmit domain logic. The MCS/Transmit domain logic is held in reset. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MCSTxResetEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MCSTxResetEnable(ETH_MODULE_ID index) PLIB_ETH_MCSTxResetIsEnabled Function Gets the EMAC Control Sub-layer/Transmit domain logic reset status. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 818 File plib_eth.h C bool PLIB_ETH_MCSTxResetIsEnabled(ETH_MODULE_ID index); Returns • true - EMAC Control Sub-layer/Transmit domain logic is held in reset • false - EMAC Control Sub-layer/Transmit domain logic is not in reset Description This function gets the EMAC Control Sub-layer/Transmit domain logic reset status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_MCSTxResetIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_MCSTxResetIsEnabled(ETH_MODULE_ID index) PLIB_ETH_MIIMReadDataGet Function Gets EMAC MIIM management read data after a MII read cycle has completed. File plib_eth.h C uint16_t PLIB_ETH_MIIMReadDataGet(ETH_MODULE_ID index); Returns • readData - MII read data Description This function gets EMAC MIIM management read data after a MII read cycle has completed. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example readData = PLIB_ETH_MIIMReadDataGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_MIIMReadDataGet(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 819 PLIB_ETH_MIIMReadStart Function Initiates an MII management read command. File plib_eth.h C void PLIB_ETH_MIIMReadStart(ETH_MODULE_ID index); Returns None. Description This function initiates an MII read command. The MII Management module will perform a single read cycle. To get data, use PLIB_ETH_MIIReadDataGet. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example while (PLIB_ETH_MIIMIsBusy(MY_ETH_INSTANCE)) { //Wait until MII Link is not busy } PLIB_ETH_MIIReadStart(MY_ETH_INSTANCE); while (PLIB_ETH_MIIReadIsDataNotValid(MY_ETH_INSTANCE)) { //Wait until read is complete } data = PLIB_ETH_MIIReadDataGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIMReadStart(ETH_MODULE_ID index) PLIB_ETH_MIIMResetDisable Function Disables EMAC Reset MII Management. File plib_eth.h C void PLIB_ETH_MIIMResetDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC Reset MII Management. EMAC will resume normal operation. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 820 Preconditions None. Example PLIB_ETH_MIIMResetDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIMResetDisable(ETH_MODULE_ID index) PLIB_ETH_MIIMResetEnable Function Enables EMAC Reset Media Independent Interface (MII) Management. File plib_eth.h C void PLIB_ETH_MIIMResetEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC Reset MII Management and holds the MII Management module in reset while enabled. Remarks MII Management held in Reset after This function is called. Disable ResetMIIanagement to return to normal operation. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIMResetEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIMResetEnable(ETH_MODULE_ID index) PLIB_ETH_MIIMResetIsEnabled Function Gets the EMAC Reset MII Management enable status. File plib_eth.h C bool PLIB_ETH_MIIMResetIsEnabled(ETH_MODULE_ID index); Returns • true - Reset the MII Management module • false - Normal operation Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 821 Description This function gets the EMAC Reset MII Management enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_MIIMResetIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_MIIMResetIsEnabled(ETH_MODULE_ID index) PLIB_ETH_MIIMScanIncrEnable Function Enables EMAC MIIM Scan Increment. File plib_eth.h C void PLIB_ETH_MIIMScanIncrEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC MIIM Scan Increment. The MII Management module will perform read cycles across a range of PHYs. The read cycles will start from address 1 through the value set in the PHY address register. Remarks The read cycles will start at PHY address 1 and continue through the value set for as the PHY address register. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIMScanIncrEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIMScanIncrEnable(ETH_MODULE_ID index) PLIB_ETH_MIIMScanIncrDisable Function Disables the EMAC MIIM Scan Increment. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 822 C void PLIB_ETH_MIIMScanIncrDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC MIIM Scan Increment. Allows continuous reads of the same PHY. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIMScanIncrDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIMScanIncrDisable(ETH_MODULE_ID index) PLIB_ETH_MIIMScanIncrIsEnabled Function Gets the EMAC MIIM scan increment enable status. File plib_eth.h C bool PLIB_ETH_MIIMScanIncrIsEnabled(ETH_MODULE_ID index); Returns • true - The MII Management module will perform read cycles across a range of PHYs. The read cycles will start from address 1 through the value set in the PHY address register. • false - Continuous reads of the same PHY Description This function gets the EMAC MIIM scan increment enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example ScanIncrement = PLIB_ETH_MIIMScanIncrIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_MIIMScanIncrIsEnabled(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 823 PLIB_ETH_MIIMScanModeDisable Function Disables MIIM scan mode. File plib_eth.h C void PLIB_ETH_MIIMScanModeDisable(ETH_MODULE_ID index); Returns None. Description This function disables MIIM scan mode. Scan is disabled for Normal operation. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIMScanModeDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIMScanModeDisable(ETH_MODULE_ID index) PLIB_ETH_MIIMScanModeEnable Function Enables MIIM scan mode. File plib_eth.h C void PLIB_ETH_MIIMScanModeEnable(ETH_MODULE_ID index); Returns None. Description This function enables MIIM scan mode. The MII Management module will perform read cycles continuously. (Useful for monitoring the Link Fail.) Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIMScanModeEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 824 Function void PLIB_ETH_MIIMScanModeEnable(ETH_MODULE_ID index) PLIB_ETH_MIIMScanModeIsEnabled Function Gets the MII management scan enable status. File plib_eth.h C bool PLIB_ETH_MIIMScanModeIsEnabled(ETH_MODULE_ID index); Returns • true - The MII Management module will perform read cycles continuously (for example, useful for monitoring the Link Fail) • false - Normal operation Description This function returns the MII management scan enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_MIIMScanModeIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_MIIMScanModeIsEnabled(ETH_MODULE_ID index) PLIB_ETH_MIIMWriteDataSet Function Sets the EMAC MIIM write data before initiating an MII write cycle. File plib_eth.h C void PLIB_ETH_MIIMWriteDataSet(ETH_MODULE_ID index, uint16_t writeData); Returns None. Description This function sets the EMAC MIIM write data before initiating write cycle. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions Prior to a call to this routine, the PHY and Register addresses should be set using PLIB_ETH_MIIPHYAddressSet and PLIB_ETH_MIIRegisterAddressSet. Example PLIB_ETH_MIIMWriteDataSet(MY_ETH_INSTANCE, WriteData); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 825 Parameters Parameters Description index Identifier for the device instance writeData MII write data Function void PLIB_ETH_MIIMWriteDataSet(ETH_MODULE_ID index, uint16_t writeData) PLIB_ETH_MIIMWriteStart Function Initiates an MII management write command. File plib_eth.h C void PLIB_ETH_MIIMWriteStart(ETH_MODULE_ID index); Returns None. Description This function initiates an MII management read command. The MII Management module will perform a write cycle. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions The PHY address and MII register address must be configured before a write using PLIB_ETH_MIIPHYAddressSet(MY_ETH_INSTANCE, phyAddr) and PLIB_ETH_MIIRegisterAddressSet(MY_ETH_INSTANCE, regAddr) Data to be written must be first loaded into the MII write register using PLIB_ETH_MIIMWriteDataSet(MY_ETH_INSTANCE, writeData) Example PLIB_ETH_MIIMWriteDataSet(MY_ETH_INSTANCE, dataToWrite); PLIB_ETH_MIIMWriteStart(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIMWriteStart(ETH_MODULE_ID index) PLIB_ETH_MIIResetDisable Function Disables the EMAC Soft reset. File plib_eth.h C void PLIB_ETH_MIIResetDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC MIIM Soft reset. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 826 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIResetDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIResetDisable(ETH_MODULE_ID index) PLIB_ETH_MIIResetEnable Function Enables the EMAC MIIM Soft reset. File plib_eth.h C void PLIB_ETH_MIIResetEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC MIIM soft reset. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MIIResetEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_MIIResetEnable(ETH_MODULE_ID index) PLIB_ETH_MIIResetIsEnabled Function Gets EMAC MIIM Soft Reset enable status. File plib_eth.h C bool PLIB_ETH_MIIResetIsEnabled(ETH_MODULE_ID index); Returns • true - MAC MII is in reset Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 827 • false - MAC MII is not in reset Description This function gets EMAC MIIM Soft reset enable status. By default this bit is set to '1'. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_MIIResetIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_MIIResetIsEnabled(ETH_MODULE_ID index) PLIB_ETH_PHYAddressGet Function Gets the EMAC MIIM management PHY address. File plib_eth.h C uint8_t PLIB_ETH_PHYAddressGet(ETH_MODULE_ID index); Returns • phyAddr - A 5-bit address of the PHY Description This function gets the EMAC MIIM management PHY address. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example phyAddr = PLIB_ETH_PHYAddressGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_PHYAddressGet(ETH_MODULE_ID index) PLIB_ETH_PHYAddressSet Function Sets the EMAC MIIM PHY address. File plib_eth.h C void PLIB_ETH_PHYAddressSet(ETH_MODULE_ID index, uint8_t phyAddr); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 828 Returns None. Description This function sets the EMAC MIIM PHY address. This field represents the 5-bit PHY Address field of Management cycles. Up to 31 PHYs can be addressed (0 is reserved). Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_PHYAddressSet(MY_ETH_INSTANCE, PhyAddr); Parameters Parameters Description index Identifier for the device instance phyAddr A 5-bit address of the PHY Function void PLIB_ETH_PHYAddressSet(ETH_MODULE_ID index, uint8_t phyAddr) PLIB_ETH_RegisterAddressGet Function Gets the EMAC MIIM management register address. File plib_eth.h C uint8_t PLIB_ETH_RegisterAddressGet(ETH_MODULE_ID index); Returns • regAddr - The (5-bit) address of the MII Registers Description This function gets the EMAC MIIM management register address. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example regAddr = PLIB_ETH_RegisterAddressGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_RegisterAddressGet(ETH_MODULE_ID index) PLIB_ETH_RegisterAddressSet Function Sets EMAC MIIM register address. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 829 File plib_eth.h C void PLIB_ETH_RegisterAddressSet(ETH_MODULE_ID index, uint8_t regAddr); Returns None. Description This function sets the EMAC MIIM register address. Up to 32 registers may be accessed. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RegisterAddressSet(MY_ETH_INSTANCE, regAddr); Parameters Parameters Description index Identifier for the device instance regAddr The (5-bit) address of the MII Registers. Function void PLIB_ETH_RegisterAddressSet(ETH_MODULE_ID index, uint8_t regAddr) PLIB_ETH_RMIIResetDisable Function Disables EMAC Reset RMII. File plib_eth.h C void PLIB_ETH_RMIIResetDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC Reset RMII for normal operation. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RMIIResetDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RMIIResetDisable(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 830 PLIB_ETH_RMIIResetEnable Function Enables EMAC Reset RMII. File plib_eth.h C void PLIB_ETH_RMIIResetEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC Reset RMII. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RMIIResetEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RMIIResetEnable(ETH_MODULE_ID index) PLIB_ETH_RMIIResetIsEnabled Function Gets the EMAC Reset RMII enable status. File plib_eth.h C bool PLIB_ETH_RMIIResetIsEnabled(ETH_MODULE_ID index); Returns • true - Reset the EMAC RMII module • false - Normal operation Description This function gets the EMAC Reset RMII enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_RMIIResetIsEnabled(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 831 Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_RMIIResetIsEnabled(ETH_MODULE_ID index) PLIB_ETH_RxBufferCountDecrement Function Causes the Receive Descriptor Buffer Counter to decrement by 1. File plib_eth.h C void PLIB_ETH_RxBufferCountDecrement(ETH_MODULE_ID index); Returns None. Description This function causes the Receive Descriptor Buffer Counter to decrement by 1. Remarks Hardware increments the receive buffer counter and software decrements it. If the receive buffer counter is incremented by the receive logic at the same time, the receive buffer counter will appear unchanged. Always reads as '0', so there is no get value routine. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RxBufferCountDecrement(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RxBufferCountDecrement(ETH_MODULE_ID index) PLIB_ETH_RxDisable Function Disables the Ethernet module receive logic. File plib_eth.h C void PLIB_ETH_RxDisable(ETH_MODULE_ID index); Returns None. Description This function disables the Ethernet receive logic. Remarks Disabling Ethernet receive is not recommended for making changes to any receive-related registers. After the receiver has been enabled, the Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 832 Ethernet module must be reinitialized to implement changes. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RxDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RxDisable(ETH_MODULE_ID index) PLIB_ETH_RxEnable Function Enables the Ethernet receive logic. File plib_eth.h C void PLIB_ETH_RxEnable(ETH_MODULE_ID index); Returns None. Description This function enables the Ethernet receive logic. Packets are received and stored in the receive buffer as controlled by the filter configuration. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions All receive registers must be configured before calling this function. Example PLIB_ETH_RxEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RxEnable(ETH_MODULE_ID index) PLIB_ETH_RxFuncResetDisable Function Disables the EMAC reset receive function logic. File plib_eth.h C void PLIB_ETH_RxFuncResetDisable(ETH_MODULE_ID index); Returns None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 833 Description This function disables the EMAC reset receive function logic. The reset receive function logic is released from reset. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RxFuncResetDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RxFuncResetDisable(ETH_MODULE_ID index) PLIB_ETH_RxFuncResetEnable Function Enables the EMAC reset receive function logic. File plib_eth.h C void PLIB_ETH_RxFuncResetEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC reset receive function logic. The receive function logic is held in reset. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RxFuncResetEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RxFuncResetEnable(ETH_MODULE_ID index) PLIB_ETH_RxFuncResetIsEnabled Function Gets the EMAC reset receive function status. File plib_eth.h C bool PLIB_ETH_RxFuncResetIsEnabled(ETH_MODULE_ID index); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 834 Returns • true - EMAC Receive function logic is held in reset • false - EMAC Receive function logic is not in reset Description This function gets the EMAC reset receive function status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_RxFuncResetIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_RxFuncResetIsEnabled(ETH_MODULE_ID index) PLIB_ETH_RxIsEnabled Function Gets the Ethernet module receive enable status. File plib_eth.h C bool PLIB_ETH_RxIsEnabled(ETH_MODULE_ID index); Returns • true - Ethernet module receive is enabled • false - Ethernet module receive is disabled Description This function returns the Ethernet module receive enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_ReceiveIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_RxIsEnabled(ETH_MODULE_ID index) PLIB_ETH_RxPacketDescAddrGet Function Gets the address of the next receive descriptor. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 835 File plib_eth.h C uint8_t * PLIB_ETH_RxPacketDescAddrGet(ETH_MODULE_ID index); Returns • ReceivePacketDescriptorAddress - receive packet descriptor address Description This function gets the address of the next receive descriptor to be used. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example RxPacketDescAddr = PLIB_ETH_RxPacketDescAddrGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t *PLIB_ETH_RxPacketDescAddrGet(ETH_MODULE_ID index) PLIB_ETH_RxPacketDescAddrSet Function Sets the Ethernet module receive packet descriptor start address. File plib_eth.h C void PLIB_ETH_RxPacketDescAddrSet(ETH_MODULE_ID index, uint8_t * rxPacketDescStartAddr); Returns None. Description This function sets the Ethernet receive packet descriptor start address. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions No transmit, receive, or DMA operations should be in progress when this function is called. Call this function before enabling transmit and receive. Example PLIB_ETH_RxPacketDescAddrSet(MY_ETH_INSTANCE, rxPacketDescStartAddr) Parameters Parameters Description index Identifier for the device instance rxPacketDescStartAddr This address must be 4-byte aligned. (The least significant 2 bits must be '00'.) Function void PLIB_ETH_RxPacketDescAddrSet(ETH_MODULE_ID index, uint8_t *rxPacketDescStartAddr) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 836 PLIB_ETH_TestPauseDisable Function Disables EMAC test pause. File plib_eth.h C void PLIB_ETH_TestPauseDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC Test Pause. The EMAC will resume normal operation. Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_TestPauseDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TestPauseDisable(ETH_MODULE_ID index) PLIB_ETH_TestPauseEnable Function Enables EMAC test pause. File plib_eth.h C void PLIB_ETH_TestPauseEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC test pause. The EMAC Control sub-layer will inhibit transmissions, just as if a Pause Receive Control frame with a non-zero pause time parameter was received. Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_TestPauseEnable(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 837 Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TestPauseEnable(ETH_MODULE_ID index) PLIB_ETH_TestPauseIsEnabled Function Gets the EMAC test pause enable status. File plib_eth.h C bool PLIB_ETH_TestPauseIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC Control sub-layer will inhibit transmissions, just as if a Pause Receive Control frame with a non-zero pause time parameter was received • false - Normal operation Description This function returns the EMAC test pause enable status. Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_TestPauseIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_TestPauseIsEnabled(ETH_MODULE_ID index) PLIB_ETH_TxFuncResetDisable Function Disables the EMAC Transmit function reset. File plib_eth.h C void PLIB_ETH_TxFuncResetDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC Transmit function reset. The EMAC transmit function is released from reset for normal operation. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 838 Preconditions None. Example PLIB_ETH_TxFuncResetDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TxFuncResetDisable(ETH_MODULE_ID index) PLIB_ETH_TxFuncResetEnable Function Enables the EMAC transmit function reset. File plib_eth.h C void PLIB_ETH_TxFuncResetEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC transmit function reset. The transmit function is held in reset. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_TxFuncResetEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TxFuncResetEnable(ETH_MODULE_ID index) PLIB_ETH_TxFuncResetIsEnabled Function Gets the EMAC Transmit function reset status. File plib_eth.h C bool PLIB_ETH_TxFuncResetIsEnabled(ETH_MODULE_ID index); Returns • true - EMAC transmit function logic is held in reset • false - EMAC transmit function logic is not in reset Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 839 Description This function gets the EMAC Transmit function reset status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_TxFuncResetIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_TxFuncResetIsEnabled(ETH_MODULE_ID index) PLIB_ETH_TxPacketDescAddrGet Function Gets the address of the next descriptor to be transmitted. File plib_eth.h C uint8_t * PLIB_ETH_TxPacketDescAddrGet(ETH_MODULE_ID index); Returns Transmit Packet Descriptor Start Address. Description This function gets the address of the next transmit descriptor. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example txPacketDescAddr = PLIB_ETH_TxPacketDescAddrGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t *PLIB_ETH_TxPacketDescAddrGet(ETH_MODULE_ID index) PLIB_ETH_TxPacketDescAddrSet Function Sets the Ethernet module transmit packet descriptor start address. File plib_eth.h C void PLIB_ETH_TxPacketDescAddrSet(ETH_MODULE_ID index, uint8_t * txPacketDescStartAddr); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 840 Returns None. Description This function sets the Ethernet transmit packet descriptor start address. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions No transmit, receive, or DMA operations should be in progress when this function is called. Call this function before enabling transmit and receive. Example PLIB_ETH_TxPacketDescAddrSet(MY_ETH_INSTANCE, txPacketDescStartAddr) Parameters Parameters Description index Identifier for the device instance txPacketDescStartAddr This address must be 4-byte aligned. (The least significant 2 bits must be '00'.) Function void PLIB_ETH_TxPacketDescAddrSet(ETH_MODULE_ID index, uint8_t *txPacketDescStartAddr) PLIB_ETH_TxRTSDisable Function Aborts an Ethernet module transmission. File plib_eth.h C void PLIB_ETH_TxRTSDisable(ETH_MODULE_ID index); Returns None. Description This function aborts an Ethernet module transmission and disables the transmitter after the current packet has completed. Remarks When disabled by software, transmission stops after the current packet has been completed. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_TxRTSDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TxRTSDisable(ETH_MODULE_ID index) PLIB_ETH_TxRTSEnable Function Enables the Ethernet transmit request to send. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 841 File plib_eth.h C void PLIB_ETH_TxRTSEnable(ETH_MODULE_ID index); Returns None. Description This function enables the Ethernet request to send. Transmit logic is activated and any packets defined in the Ethernet descriptor table are transmitted. Remarks This status is cleared by hardware when the transmission is complete. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions The TX descriptor list and TX DMA must be initialized using PLIB_ETH_TransmitPacketDescStartAddrSet. Example PLIB_ETH_TxRTSEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TxRTSEnable(ETH_MODULE_ID index) PLIB_ETH_TxRTSIsEnabled Function Gets the Ethernet module transmit request to send status. File plib_eth.h C bool PLIB_ETH_TxRTSIsEnabled(ETH_MODULE_ID index); Returns • true - Ethernet module transmit is active • false - Ethernet module transmission has stopped or has completed Description This function returns the Ethernet module transmit request to send status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_TransmitRTSIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 842 Function bool PLIB_ETH_TxRTSIsEnabled(ETH_MODULE_ID index) PLIB_ETH_CRCDisable Function Disables EMAC CRC. File plib_eth.h C void PLIB_ETH_CRCDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC CRC. Remarks The frames presented to the EMAC have a valid CRC This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_CRCDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_CRCDisable(ETH_MODULE_ID index) PLIB_ETH_CRCEnable Function Enables EMAC CRC. File plib_eth.h C void PLIB_ETH_CRCEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC CRC. The EMAC will append CRC whether padding is required or not. This must be enabled if auto-padding is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_CRCEnable(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 843 Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_CRCEnable(ETH_MODULE_ID index) PLIB_ETH_CRCIsEnabled Function Gets the EMAC CRC enable status. File plib_eth.h C bool PLIB_ETH_CRCIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC will append a CRC to every frame whether or not padding was required. Must be set if auto-padding is enabled. • false - The frames presented to the EMAC have a valid CRC Description This function returns the EMAC CRC enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_CRCIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_CRCIsEnabled(ETH_MODULE_ID index) c) Status Functions PLIB_ETH_DataNotValid Function Gets the MII management read data not valid status. File plib_eth.h C bool PLIB_ETH_DataNotValid(ETH_MODULE_ID index); Returns • true - The MII Management read cycle has not completed and the read data is not yet valid • false - The MII Management read cycle is complete and the read data is valid Description This function gets the MII management read data not valid status. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 844 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_DataNotValid(MY_ETH_INSTANCE); Also see the example for function: PLIB_ETH_MIIReadStart(). Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_DataNotValid(ETH_MODULE_ID index) PLIB_ETH_EthernetIsBusy Function Gets the status value of the Ethernet logic busy. File plib_eth.h C bool PLIB_ETH_EthernetIsBusy(ETH_MODULE_ID index); Returns • true - Ethernet logic has been turned ON or is completing a transaction • false - Ethernet logic is idle Description This function sets the value of the Ethernet logic busy. A request indicates that the module has just been turned ON or is completing a transaction after being turned OFF. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_EthernetIsBusy(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_EthernetIsBusy(ETH_MODULE_ID index) PLIB_ETH_LinkHasFailed Function Gets the MII management link fail status. File plib_eth.h C bool PLIB_ETH_LinkHasFailed(ETH_MODULE_ID index); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 845 Returns • true - The MII Management module link fail has occurred • false - The MII Management module link fail has not occurred Description This function returns the MII management link fail status. This value reflects the last read from the PHY status register. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_LinkHasFailed(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_LinkHasFailed(ETH_MODULE_ID index) PLIB_ETH_MIIMIsBusy Function Gets the MII management busy status. File plib_eth.h C bool PLIB_ETH_MIIMIsBusy(ETH_MODULE_ID index); Returns • true - The MII Management module is currently performing an MII Management read or write cycle • false - The MII Management is free Description This function returns the MII management busy status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_MIIMIsBusy(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_MIIMIsBusy(ETH_MODULE_ID index) PLIB_ETH_MIIMIsScanning Function Gets the MII Management scanning status. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 846 File plib_eth.h C bool PLIB_ETH_MIIMIsScanning(ETH_MODULE_ID index); Returns • true - The MII Management module scan operation (continuous MII Management Read cycles) is in progress • false - The MII Management scan operation is not in progress Description This function gets the MII Management scanning status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_MIIMIsScanning(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_MIIMIsScanning(ETH_MODULE_ID index) PLIB_ETH_ReceiveIsBusy Function Gets the Ethernet receive logic busy status. File plib_eth.h C bool PLIB_ETH_ReceiveIsBusy(ETH_MODULE_ID index); Returns • true - Receive logic is receiving data • false - Receive logic is idle Description This function gets the Ethernet receive logic busy status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_ReceiveIsBusy(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_ReceiveIsBusy(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 847 PLIB_ETH_TransmitIsBusy Function Gets the status value of the Ethernet transmit logic busy status File plib_eth.h C bool PLIB_ETH_TransmitIsBusy(ETH_MODULE_ID index); Returns • true - Transmit logic is sending data • false - Transmit logic is idle Description This function gets the value of the Ethernet transmit logic busy status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_TransmitIsBusy(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_TransmitIsBusy(ETH_MODULE_ID index) d) Filtering Functions PLIB_ETH_HashTableGet Function Gets the value of the Hash table. File plib_eth.h C uint32_t PLIB_ETH_HashTableGet(ETH_MODULE_ID index); Returns • hashTable - Hash table value (64-bits) Description This function gets the value of the Hash table. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_HashTableGet(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 848 Parameters Parameters Description index Identifier for the device instance Function uint64_t PLIB_ETH_HashTableGet(ETH_MODULE_ID index) PLIB_ETH_HashTableSet Function Sets the Ethernet module Hash table with the new value. File plib_eth.h C void PLIB_ETH_HashTableSet(ETH_MODULE_ID index, uint64_t hashTableValue); Returns None. Description This function sets the Hash table with the new value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions Call PLIB_ETH_HashTableFilterDisable to disable the Hash table filter before changing the hash table, or set the Hash Table prior to calling PLIB_ETH_ReceiveEnable. Example PLIB_ETH_HashTableSet(MY_ETH_INSTANCE, hashTableValue); Parameters Parameters Description index Identifier for the device instance hashTableValue hash table value (64-bits) Function void PLIB_ETH_HashTableSet(ETH_MODULE_ID index, uint64_t hashTableValue) PLIB_ETH_PassAllDisable Function Disables the EMAC PassAll. File plib_eth.h C void PLIB_ETH_PassAllDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC PassAll. Control frames are ignored. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 849 Preconditions None. Example PLIB_ETH_PassAllDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_PassAllDisable(ETH_MODULE_ID index) PLIB_ETH_PassAllEnable Function Enables the EMAC PassAll. File plib_eth.h C void PLIB_ETH_PassAllEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC PassAll, which enables both the normal and the control frames to be passed. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_PassAllEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_PassAllEnable(ETH_MODULE_ID index) PLIB_ETH_PassAllIsEnabled Function Gets the EMAC PassAll enable status. File plib_eth.h C bool PLIB_ETH_PassAllIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC will accept all frames regardless of type (normal vs. Control) • false - The received Control frames are ignored Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 850 Description This function gets the EMAC PassAll enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_PassAllIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_PassAllIsEnabled(ETH_MODULE_ID index) PLIB_ETH_PatternMatchChecksumGet Function Gets the value of the pattern match checksum register. File plib_eth.h C uint16_t PLIB_ETH_PatternMatchChecksumGet(ETH_MODULE_ID index); Returns The pattern match checksum. Description This function gets the value of the patter match checksum register. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_PatternMatchChecksumGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_PatternMatchChecksumGet(ETH_MODULE_ID index) PLIB_ETH_PatternMatchChecksumSet Function Sets the Ethernet module pattern match checksum register with the new value. File plib_eth.h C void PLIB_ETH_PatternMatchChecksumSet(ETH_MODULE_ID index, uint16_t PatternMatchChecksumValue); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 851 Returns None. Description This function sets the pattern match checksum register with the new value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions Call PLIB_ETH_PatternMatchModeSet(ETH_PATTERN_MATCH_DISABLED) to disable PatternMatch before changing the pattern match mask, or set the value before calling PLIB_ETH_ReceiveEnable. Example PLIB_ETH_PatternMatchChecksumSet(MY_ETH_INSTANCE, PatternMatchChecksumValue); Parameters Parameters Description index Identifier for the device instance to be configured PatternMatchChecksumValue Pattern match checksum value Function void PLIB_ETH_PatternMatchChecksumSet(ETH_MODULE_ID index, uint16_t PatternMatchChecksumValue) PLIB_ETH_PatternMatchGet Function Gets the value of the selected pattern match mask register. File plib_eth.h C uint64_t PLIB_ETH_PatternMatchGet(ETH_MODULE_ID index); Returns • patternMatchMaskValue - Pattern Match Mask Values Description This function gets the selected value of the patter match mask register. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_PatternMatchGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint64_t PLIB_ETH_PatternMatchGet(ETH_MODULE_ID index) PLIB_ETH_PatternMatchModeGet Function Gets the value of the selected pattern match mask register. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 852 File plib_eth.h C ETH_PATTERN_MATCH_MODE PLIB_ETH_PatternMatchModeGet(ETH_MODULE_ID index); Returns • modeSel - The method of pattern matching from ETH_PATTERN_MATCH_DISABLED Description This function gets the selected value of the patter match mask register. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_PatternMatchModeGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function ETH_PATTERN_MATCH_MODE PLIB_ETH_PatternMatchModeGet(ETH_MODULE_ID index) PLIB_ETH_PatternMatchModeSet Function Sets the Ethernet module pattern match mode. File plib_eth.h C void PLIB_ETH_PatternMatchModeSet(ETH_MODULE_ID index, ETH_PATTERN_MATCH_MODE modeSel); Returns None. Description This function sets the pattern match mode. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions Set the value before calling PLIB_ETH_ReceiveEnable(). Example PLIB_ETH_PatternMatchModeSet(MY_ETH_INSTANCE, ETH_PATTERN_MATCH_DISABLED); Parameters Parameters Description index Identifier for the device instance modeSel The method of pattern matching from ETH_PATTERN_MATCH_DISABLED Function void PLIB_ETH_PatternMatchModeSet(ETH_MODULE_ID index, ETH_PATTERN_MATCH_MODE modeSel) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 853 PLIB_ETH_PatternMatchOffsetGet Function Gets the value of the patter match offset register. File plib_eth.h C uint16_t PLIB_ETH_PatternMatchOffsetGet(ETH_MODULE_ID index); Returns • PatternMatchOffsetValue - Pattern match offset value Description This function gets the value of the patter match offset register. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example value = PLIB_ETH_PatternMatchOffsetGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_PatternMatchOffsetGet(ETH_MODULE_ID index) PLIB_ETH_PatternMatchOffsetSet Function Sets the Ethernet module patter match offset register with the new value. File plib_eth.h C void PLIB_ETH_PatternMatchOffsetSet(ETH_MODULE_ID index, uint16_t PatternMatchOffsetValue); Returns None. Description This function sets the pattern match offset register with the new value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions Call PLIB_ETH_PatternMatchModeSet(ETH_PATTERN_MATCH_DISABLED) to disable PatternMatch before changing the pattern match mask, or set the value before calling PLIB_ETH_ReceiveEnable. Example PLIB_ETH_PatternMatchOffsetSet(MY_ETH_INSTANCE, PatternMatchOffsetValue); Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 854 PatternMatchOffsetValue Pattern match offset value Function void PLIB_ETH_PatternMatchOffsetSet(ETH_MODULE_ID index, uint16_t PatternMatchOffsetValue) PLIB_ETH_PatternMatchSet Function Sets the Ethernet module pattern match mask register with the new value. File plib_eth.h C void PLIB_ETH_PatternMatchSet(ETH_MODULE_ID index, uint64_t patternMatchMaskValue); Returns None. Description This function sets the pattern match mask register with the new value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions Call PLIB_ETH_PatternMatchModeSet(index,ETH_PATTERN_MATCH_DISABLED) to disable PatternMatch before changing the pattern match mask, or set the value before calling PLIB_ETH_ReceiveEnable. Example PLIB_ETH_PatternMatchSet(MY_ETH_INSTANCE, patternMatchMaskValue); Parameters Parameters Description index Identifier for the device instance patternMatchMaskValue Pattern Match Mask Values (64-bits) Function void PLIB_ETH_PatternMatchSet(ETH_MODULE_ID index, uint64_t patternMatchMaskValue) PLIB_ETH_PurePreambleDisable Function Disables EMAC pure preamble enforcement. File plib_eth.h C void PLIB_ETH_PurePreambleDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC pure preamble enforcement. The EMAC does not perform any preamble checking. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 855 Example PLIB_ETH_PurePreambleDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_PurePreambleDisable(ETH_MODULE_ID index) PLIB_ETH_PurePreambleEnable Function Enables EMAC pure preamble enforcement. File plib_eth.h C void PLIB_ETH_PurePreambleEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC pure preamble enforcement. The EMAC will verify the contents of the preamble and discard packets with errors in the preamble. Remarks The EMAC will verify the content of the preamble to ensure it contains 0x55 and is error-free. A packet with errors in its preamble is discarded. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_PurePreambleEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_PurePreambleEnable(ETH_MODULE_ID index) PLIB_ETH_PurePreambleIsEnabled Function Gets EMAC pure preamble enforcement enable status. File plib_eth.h C bool PLIB_ETH_PurePreambleIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC will verify the content of the preamble to ensure it contains 0x55 and is error-free. A packet with errors in its preamble is discarded. • false - The EMAC does not perform any preamble checking Description This function gets the EMAC pure preamble enforcement enable status. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 856 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_PurePreambleIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_PurePreambleIsEnabled(ETH_MODULE_ID index) PLIB_ETH_ReceiveFilterDisable Function Disables the specified receive filter. File plib_eth.h C void PLIB_ETH_ReceiveFilterDisable(ETH_MODULE_ID index, ETH_RECEIVE_FILTER filter); Returns None. Description This function disables the specified receive filter. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ReceiveFilterDisable(index, ETH_CRC_OK_FILTER | ETH_RUNT_ENABLE_FILTER | ETH_UNICAST_FILTER ); Parameters Parameters Description index Identifier for the device instance filter The selection of receive filters to be disabled from the enumerated selection ETH_RECEIVE_FILTER Function void PLIB_ETH_ReceiveFilterDisable(ETH_MODULE_ID index, ETH_RECEIVE_FILTER filter) PLIB_ETH_ReceiveFilterEnable Function Enables the specified receive filter. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 857 C void PLIB_ETH_ReceiveFilterEnable(ETH_MODULE_ID index, ETH_RECEIVE_FILTER filter); Returns None. Description This function enables the specified receive filter. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ReceiveFilterEnable(index, ETH_CRC_OK_FILTER | ETH_RUNT_ENABLE_FILTER | ETH_UNICAST_FILTER ); Parameters Parameters Description index Identifier for the device instance filter The selection of receive filters to be enabled from the enumerated selection ETH_RECEIVE_FILTER Function void PLIB_ETH_ReceiveFilterEnable(ETH_MODULE_ID index, ETH_RECEIVE_FILTER filter) PLIB_ETH_ReceiveFilterIsEnable Function Disables the specified receive filter. File plib_eth.h C bool PLIB_ETH_ReceiveFilterIsEnable(ETH_MODULE_ID index, ETH_RECEIVE_FILTER filter); Returns • true - If at least one of the specified filters is enabled • false - If no specified filter is enabled Description This function disables the specified receive filter. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if (PLIB_ETH_ReceiveFilterIsEnable(index, ETH_UNICAST_FILTER)) { PLIB_ETH_ReceiveFilterDisable(MY_MODULE_ID, ETH_UNICAST_FILTER); } Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 858 Parameters Parameters Description index Identifier for the device instance filter The selection of receive filters to be disabled from the enumerated selection ETH_RECEIVE_FILTER Function bool PLIB_ETH_ReceiveFilterIsEnable(ETH_MODULE_ID index, ETH_RECEIVE_FILTER filter) PLIB_ETH_StationAddressGet Function Gets the selected EMAC station address. File plib_eth.h C uint8_t PLIB_ETH_StationAddressGet(ETH_MODULE_ID index, uint8_t which); Returns • stationAddress1 - Station address Description This function gets the selected EMAC station address. Remarks On a reset, this register is loaded with the factory preprogrammed station address. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stationAddr1 = PLIB_ETH_StationAddress1Get(MY_ETH_INSTANCE, which); Parameters Parameters Description index Identifier for the device instance which Select station address to change. Valid values are 1,2,3,4,5,6. Function uint8_t PLIB_ETH_StationAddressGet(ETH_MODULE_ID index, uint8_t which) PLIB_ETH_StationAddressSet Function Sets the selected EMAC Station Address. File plib_eth.h C void PLIB_ETH_StationAddressSet(ETH_MODULE_ID index, uint8_t which, uint8_t stationAddress); Returns None. Description This function sets the selected EMAC Station Address. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 859 Remarks On a reset, this register is loaded with the factory preprogrammed station address. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_StationAddressSet(MY_ETH_INSTANCE, which, stationAddress); Parameters Parameters Description index Identifier for the device instance which Select station address to change. Valid values are 1,2,3,4,5,6. stationAddress Station Address. Function void PLIB_ETH_StationAddressSet(ETH_MODULE_ID index, uint8_t which, uint8_t stationAddress) e) Flow Control Functions PLIB_ETH_AutoFlowControlDisable Function Disables the Ethernet module Automatic Flow Control logic. File plib_eth.h C void PLIB_ETH_AutoFlowControlDisable(ETH_MODULE_ID index); Returns None. Description This function disables the Ethernet Automatic Flow Control logic. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_AutoFlowControlDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_AutoFlowControlDisable(ETH_MODULE_ID index) PLIB_ETH_AutoFlowControlEnable Function Enables the Ethernet Automatic Flow Control logic. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 860 C void PLIB_ETH_AutoFlowControlEnable(ETH_MODULE_ID index); Returns None. Description This function enables Ethernet Automatic Flow Control logic. Remarks The full and empty watermarks are used to automatically enable and disable flow control, respectively. When the number of received buffers rises to the full watermark, flow control is automatically enabled. When the receive buffer count falls to the empty watermark, flow control is automatically disabled. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_AutoFlowControlEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_AutoFlowControlEnable(ETH_MODULE_ID index) PLIB_ETH_AutoFlowControlIsEnabled Function Gets the Ethernet module Automatic Flow Control status. File plib_eth.h C bool PLIB_ETH_AutoFlowControlIsEnabled(ETH_MODULE_ID index); Returns • true - Ethernet module Automatic Flow Control is enabled • false - Ethernet module Automatic Flow Control is disabled Description This function gets the Ethernet Automatic Flow Control enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_AutoFlowControlIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_AutoFlowControlIsEnabled(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 861 PLIB_ETH_BackPresNoBackoffDisable Function Disables EMAC backpressure/no back-off. File plib_eth.h C void PLIB_ETH_BackPresNoBackoffDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC backpressure/no back-off. The EMAC will back-off when there is backpressure and collisions occur. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_BackPresNoBackoffDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_BackPresNoBackoffDisable(ETH_MODULE_ID index) PLIB_ETH_BackPresNoBackoffEnable Function Enables EMAC back pressure/no back-off. File plib_eth.h C void PLIB_ETH_BackPresNoBackoffEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC backpressure/no back-off. The EMAC will not back-off when there is backpressure and collisions occur. Remarks The EMAC after incidentally causing a collision during backpressure will immediately retransmit without back-off reducing the chance of further collisions and ensuring transmit packets get sent. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_BackPresNoBackoffEnable(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 862 Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_BackPresNoBackoffEnable(ETH_MODULE_ID index) PLIB_ETH_BackPresNoBackoffIsEnabled Function Gets the EMAC backpressure/no back-off enable status. File plib_eth.h C bool PLIB_ETH_BackPresNoBackoffIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC after incidentally causing a collision during backpressure will immediately retransmit without back-off reducing the chance of further collisions and ensuring transmit packets get sent • false - The EMAC will not remove the back-off Description This function gets the EMAC backpressure/no back-off enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_BackPresNoBackoffIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_BackPresNoBackoffIsEnabled(ETH_MODULE_ID index) PLIB_ETH_ManualFlowControlDisable Function Disable Ethernet module Manual Flow Control logic. File plib_eth.h C void PLIB_ETH_ManualFlowControlDisable(ETH_MODULE_ID index); Returns None. Description This function disables the Ethernet Manual Flow Control logic and automatically sends a Pause frame with a 0x0000 Pause Timer value. This function affects both transmit and receive operations. Remarks Disabling Manual Flow Control will automatically send a Pause frame with a 0x0000 Pause Timer value to disable flow control. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 863 Preconditions None. Example PLIB_ETH_ManualFlowControlDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_ManualFlowControlDisable(ETH_MODULE_ID index) PLIB_ETH_ManualFlowControlEnable Function Enables the Ethernet Manual Flow Control logic. File plib_eth.h C void PLIB_ETH_ManualFlowControlEnable(ETH_MODULE_ID index); Returns None. Description This function enables the Ethernet Manual Flow Control logic. Enabling Manual Flow Control will send a Pause frame using the Pause Timer value. While enabled, a Pause frame is repeated every 128 x (Pause timer value)/2 transmit clock cycles. Affects both transmit and receive operations. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ManualFlowControlEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_ManualFlowControlEnable(ETH_MODULE_ID index) PLIB_ETH_ManualFlowControlIsEnabled Function Gets the Ethernet module Manual Flow Control enable status. File plib_eth.h C bool PLIB_ETH_ManualFlowControlIsEnabled(ETH_MODULE_ID index); Returns • true - Ethernet module Manual Flow Control is enabled • false - Ethernet module Manual Flow Control is disabled Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 864 Description This function returns the Ethernet module Manual Flow Control enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_ManualFlowControlIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_ManualFlowControlIsEnabled(ETH_MODULE_ID index) PLIB_ETH_NoBackoffDisable Function Disables EMAC no back-offs. File plib_eth.h C void PLIB_ETH_NoBackoffDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC no back-off. The EMAC will back-off when a collision occurs. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_NoBackoffDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_NoBackoffDisable(ETH_MODULE_ID index) PLIB_ETH_NoBackoffEnable Function Enables EMAC no back-off. File plib_eth.h C void PLIB_ETH_NoBackoffEnable(ETH_MODULE_ID index); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 865 Returns None. Description This function enables EMAC no back-off. The EMAC will not back-off when a collision occurs. Remarks Following a collision, the EMAC will immediately retransmit rather than using the Binary Exponential Back-off algorithm as specified in the Standard. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_NoBackoffEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_NoBackoffEnable(ETH_MODULE_ID index) PLIB_ETH_NoBackoffIsEnabled Function Gets the EMAC no back-off enable status. File plib_eth.h C bool PLIB_ETH_NoBackoffIsEnabled(ETH_MODULE_ID index); Returns • true - Following a collision, the EMAC will immediately retransmit • false - Following a collision, the EMAC will use the Binary Exponential Back-off algorithm Description This function gets the EMAC no back-off enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_NoBackoffIsEnabled(MY_ETsH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_NoBackoffIsEnabled(ETH_MODULE_ID index) PLIB_ETH_RxEmptyWmarkGet Function Gets the Ethernet module receive empty watermark. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 866 File plib_eth.h C uint8_t PLIB_ETH_RxEmptyWmarkGet(ETH_MODULE_ID index); Returns • receiveEmptyWmark - Empty watermark value Description This function gets the Ethernet receive empty watermark. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example watermarkValue = PLIB_ETH_RxEmptyWmarkGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_RxEmptyWmarkGet(ETH_MODULE_ID index) PLIB_ETH_RxEmptyWmarkSet Function Sets the Ethernet module receive empty water mark. File plib_eth.h C void PLIB_ETH_RxEmptyWmarkSet(ETH_MODULE_ID index, uint8_t watermarkValue); Returns None. Description This function sets the Ethernet receive empty water mark with a new value. The software controlled Receive Buffer Empty Wmark is compared against the receive buffer count to determine the empty watermark condition for the empty watermark interrupt and for disabling flow control if Auto Flow Control is enabled. The Full Wmark value should always be greater than the Empty Wmark value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RxEmptyWmarkSet(MY_ETH_INSTANCE, watermarkValue); Parameters Parameters Description index Identifier for the device instance watermarkValue Empty watermark value Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 867 Function void PLIB_ETH_RxEmptyWmarkSet(ETH_MODULE_ID index, uint8_t watermarkValue) PLIB_ETH_RxFullWmarkGet Function Gets the Ethernet module to receive a full watermark. File plib_eth.h C uint8_t PLIB_ETH_RxFullWmarkGet(ETH_MODULE_ID index); Returns • receiveFullWmark - Full watermark value Description This function gets the Ethernet to receive a full watermark. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example watermarkValue = PLIB_ETH_RxFullWmarkGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_RxFullWmarkGet(ETH_MODULE_ID index) PLIB_ETH_RxFullWmarkSet Function Sets the Ethernet module to receive a full watermark. File plib_eth.h C void PLIB_ETH_RxFullWmarkSet(ETH_MODULE_ID index, uint8_t watermarkValue); Returns None. Description This function sets the Ethernet to receive a full watermark with a new value. The software controlled RX Buffer Full Watermark (Wmark) Pointer is compared against the receive buffer count to determine the full watermark condition for the full watermark interrupt and for enabling flow control if Auto Flow Control is enabled. The Full Wmark value should always be greater than the Empty Wmark value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 868 Example PLIB_ETH_RxFullWmarkSet(MY_ETH_INSTANCE, watermarkValue); Parameters Parameters Description index Identifier for the device instance watermarkValue Full watermark value Function void PLIB_ETH_RxFullWmarkSet(ETH_MODULE_ID index, uint8_t watermarkValue) PLIB_ETH_RxPauseDisable Function Disables the EMAC receive flow control. File plib_eth.h C void PLIB_ETH_RxPauseDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC receive flow control. The received Pause Flow control frames are ignored. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RxPauseDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RxPauseDisable(ETH_MODULE_ID index) PLIB_ETH_RxPauseEnable Function Enables the EMAC receive flow control. File plib_eth.h C void PLIB_ETH_RxPauseEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC receive flow control. The EMAC will act upon the received Pause frames. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 869 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RxPauseEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RxPauseEnable(ETH_MODULE_ID index) PLIB_ETH_RxPauseIsEnabled Function Gets the EMAC receive flow pause enable status. File plib_eth.h C bool PLIB_ETH_RxPauseIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC acts upon received Pause Flow Control frames • false - Received Pause Flow Control frames are ignored Description This function gets the EMAC receive flow pause enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example status = PLIB_ETH_RxPauseIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_RxPauseIsEnabled(ETH_MODULE_ID index) PLIB_ETH_ShortcutQuantaDisable Function Disables EMAC shortcut pause quanta. File plib_eth.h C void PLIB_ETH_ShortcutQuantaDisable(ETH_MODULE_ID index); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 870 Returns None. Description This function disables EMAC shortcut pause quanta. The EMAC will resume normal operation. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ShortcutQuantaDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_ShortcutQuantaDisable(ETH_MODULE_ID index) PLIB_ETH_ShortcutQuantaEnable Function Enables EMAC shortcut pause quanta. File plib_eth.h C void PLIB_ETH_ShortcutQuantaEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC shortcut pause quanta. The EMAC reduces the effective pause quanta from 64 byte-times to 1 byte-time. Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_ShortcutQuantaEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_ShortcutQuantaEnable(ETH_MODULE_ID index) PLIB_ETH_ShortcutQuantaIsEnabled Function Gets EMAC shortcut pause quanta enable status. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 871 File plib_eth.h C bool PLIB_ETH_ShortcutQuantaIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC reduces the effective Pause Quanta from 64 byte-times to 1 byte-time • false - Normal operation Description This function returns EMAC shortcut pause quanta enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_ShortcutQuantaIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_ShortcutQuantaIsEnabled(ETH_MODULE_ID index) PLIB_ETH_SimResetDisable Function Disables the EMAC simulation reset. File plib_eth.h C void PLIB_ETH_SimResetDisable(ETH_MODULE_ID index); Returns None. Description This function disables the EMAC simulation reset. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_SimResetDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_SimResetDisable(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 872 PLIB_ETH_SimResetEnable Function Enables the EMAC simulation reset. File plib_eth.h C void PLIB_ETH_SimResetEnable(ETH_MODULE_ID index); Returns None. Description This function enables the EMAC simulation reset and resets the random number generator within the transmit (TX) function. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_SimResetEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_SimResetEnable(ETH_MODULE_ID index) PLIB_ETH_SimResetIsEnabled Function Gets the EMAC simulation reset status. File plib_eth.h C bool PLIB_ETH_SimResetIsEnabled(ETH_MODULE_ID index); Returns • true - Simulation Reset is enabled • false - Simulation Reset is disabled Description This function returns the EMAC simulation reset status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example stat = PLIB_ETH_SimResetIsEnabled(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 873 Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_SimResetIsEnabled(ETH_MODULE_ID index) PLIB_ETH_TestBackPressDisable Function Disables EMAC Test backpressure. File plib_eth.h C void PLIB_ETH_TestBackPressDisable(ETH_MODULE_ID index); Returns None. Description This function disables EMAC Test backpressure. The EMAC will resume normal operation. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_TestBackPressDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TestBackPressDisable(ETH_MODULE_ID index) PLIB_ETH_TestBackPressEnable Function Enables EMAC Test backpressure. File plib_eth.h C void PLIB_ETH_TestBackPressEnable(ETH_MODULE_ID index); Returns None. Description This function enables EMAC Test backpressure. The EMAC will assert backpressure on the link. Backpressure causes preamble to be transmitted, raising carrier sense. A transmit packet from the system will be sent during backpressure. Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 874 Preconditions None. Example PLIB_ETH_TestBackPressEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TestBackPressEnable(ETH_MODULE_ID index) PLIB_ETH_TestBackPressIsEnabled Function Gets the EMAC test backpressure enable status. File plib_eth.h C bool PLIB_ETH_TestBackPressIsEnabled(ETH_MODULE_ID index); Returns • true - The EMAC will assert backpressure on the link. Backpressure causes the preamble to be transmitted, raising the carrier sense. A transmit packet from the system will be sent during backpressure. • false - Normal operation Description This function gets the EMAC test backpressure enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_TestBackPressIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_TestBackPressIsEnabled(ETH_MODULE_ID index) PLIB_ETH_TxPauseDisable Function Disables the transmission of Pause frames. File plib_eth.h C void PLIB_ETH_TxPauseDisable(ETH_MODULE_ID index); Returns None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 875 Description This function disables the transmit Pause frames. The Pause frames are blocked from being transmitted. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_TxPauseDisable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TxPauseDisable(ETH_MODULE_ID index) PLIB_ETH_TxPauseEnable Function Enables the transmission Pause frames. File plib_eth.h C void PLIB_ETH_TxPauseEnable(ETH_MODULE_ID index); Returns None. Description This function enables the transmission Pause frames. The Pause frames are allowed for transmission. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_TxPauseEnable(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_TxPauseEnable(ETH_MODULE_ID index) PLIB_ETH_TxPauseIsEnabled Function Gets the Ethernet module enable status. File plib_eth.h C bool PLIB_ETH_TxPauseIsEnabled(ETH_MODULE_ID index); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 876 Returns • true - Pause Flow Control frames are allowed to be transmitted • false - Pause Flow Control frames are blocked Description This function gets the Ethernet module enable status. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example status = PLIB_ETH_TxPauseIsEnabled(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_ETH_TxPauseIsEnabled(ETH_MODULE_ID index) f) Interrupt Functions PLIB_ETH_InterruptClear Function Clears the Ethernet module interrupt source status as a group, using a mask. File plib_eth.h C void PLIB_ETH_InterruptClear(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask); Returns None. Description This function clears the Ethernet module interrupt source status using a mask. Logically 'OR' the masks together. Any masks not ORed with the others will be disabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // To clear several interrupts with one command, execute the following: PLIB_ETH_InterruptClear(MY_ETH_INSTANCE, ETH_EMPTY_WATERMARK_INTERRUPT | ETH_FULL_WATERMARK_INTERRUPT | ETH_RX_FIFO_OVERFLOW_ERROR_INTERRUPT ); Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 877 Function void PLIB_ETH_InterruptClear(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask) PLIB_ETH_InterruptSet Function Sets the Ethernet module interrupt source status as a group, using a mask. File plib_eth.h C void PLIB_ETH_InterruptSet(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask); Returns None. Description This function sets the Ethernet module interrupt source status using a mask. Logically 'OR' the masks together. Any masks not OR'd with the others will be disabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // To set several interrupt flags with one command, execute the following: PLIB_ETH_InterruptSet(MY_ETH_INSTANCE, ETH_EMPTY_WATERMARK_INTERRUPT | ETH_FULL_WATERMARK_INTERRUPT | ETH_RX_FIFO_OVERFLOW_ERROR_INTERRUPT ); Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together Function void PLIB_ETH_InterruptSet(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask) PLIB_ETH_InterruptsGet Function Gets the Ethernet module Interrupt Flag register as a group. File plib_eth.h C ETH_INTERRUPT_SOURCES PLIB_ETH_InterruptsGet(ETH_MODULE_ID index); Returns Interrupt bit map, as defined in ETH_INTERRUPT_SOURCES, showing which interrupts have fired. Description Gets the Ethernet module Interrupt Flag register as a group. Remarks none. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 878 Preconditions None. Example Parameters Parameters Description index Identifier for the device instance Function ETH_INTERRUPT_SOURCES PLIB_ETH_InterruptsGet(ETH_MODULE_ID index) PLIB_ETH_InterruptSourceDisable Function Clears the Ethernet module Interrupt Enable register as a group, using a mask. File plib_eth.h C void PLIB_ETH_InterruptSourceDisable(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask); Returns None. Description This function disables the Ethernet module interrupts by using a mask to select one or multiple interrupts to disable. Logically 'OR' elements of ETH_INTERRUPT_SOURCES together. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // To disable some interrupts with one command, execute the following: PLIB_ETH_InterruptSourceDisble(MY_ETH_INSTANCE, ETH_TRANSMIT_DONE_INTERRUPT | ETH_TRANSMIT_ABORT_INTERRUPT | ETH_RECEIVE_BUFFER_NOT_AVAILABLE_INTERRUPT | ETH_RECEIVE_FIFO_OVERFLOW_ERROR_INTERRUPT ); // Or to disable one interrupt with one command, execute the following: PLIB_ETH_InterruptSourceDisble(MY_ETH_INSTANCE, ETH_TRANSMIT_DONE_INTERRUPT); // Or to disable all interrupts with one command, execute the following: PLIB_ETH_InterruptSourceDisble(MY_ETH_INSTANCE, ETH_ALL_ETH_INTERRUPTS); Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together Function void PLIB_ETH_InterruptSourceDisable(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask) PLIB_ETH_InterruptSourceEnable Function Sets the Ethernet module Interrupt Enable register in a group, using a mask. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 879 File plib_eth.h C void PLIB_ETH_InterruptSourceEnable(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask); Returns None. Description This function enables the Ethernet module interrupts by using a mask to enable one or multiple interrupt enables. Logically 'OR' elements of ETH_INTERRUPT_SOURCES together. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // To enable some interrupts with one command, execute the following: PLIB_ETH_InterruptSourceEnable(MY_ETH_INSTANCE, ETH_TRANSMIT_DONE_INTERRUPT | ETH_TRANSMIT_ABORT_INTERRUPT | ETH_RECEIVE_BUFFER_NOT_AVAILABLE_INTERRUPT | ETH_RECEIVE_FIFO_OVERFLOW_ERROR_INTERRUPT); // Or to enable one interrupt with one command, execute the following: PLIB_ETH_InterruptSourceEnable(MY_ETH_INSTANCE, ETH_TRANSMIT_DONE_INTERRUPT); // Or to enable all interrupts with one command, execute the following: PLIB_ETH_InterruptSourceEnable(MY_ETH_INSTANCE, ETH_ALL_ETH_INTERRUPTS); Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together Function void PLIB_ETH_InterruptSourceEnable(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask) PLIB_ETH_InterruptSourceIsEnabled Function Gets the Ethernet module Interrupt Enable register singularly or as a group. File plib_eth.h C bool PLIB_ETH_InterruptSourceIsEnabled(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask); Returns • true - If any of the specified sources are enabled • false - If none of the specified sources are enabled Description This function returns a true if any of the specified interrupt sources are enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 880 Preconditions None. Example if ( PLIB_ETH_InterruptSourceIsEnabled(index, ETH_TRANSMIT_DONE_INTERRUPT)) { //If the interrupt is enabled, disable it... PLIB_ETH_InterruptSourceDisable(index, ETH_TRANSMIT_DONE_INTERRUPT); } Parameters Parameters Description index Identifier for the device instance mask The interrupt mask(s) to be checked Function bool PLIB_ETH_InterruptSourceIsEnabled(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask) PLIB_ETH_InterruptSourcesGet Function Returns the entire interrupt enable register. File plib_eth.h C ETH_INTERRUPT_SOURCES PLIB_ETH_InterruptSourcesGet(ETH_MODULE_ID index); Returns Bit map of interrupt sources, all ORed together, as defined by ETH_INTERRUPT_SOURCES. Description This function returns the entire interrupt enable register. Remarks None. Preconditions None. Example Parameters Parameters Description index Identifier for the device instance Function ETH_INTERRUPT_SOURCES PLIB_ETH_InterruptSourcesGet(ETH_MODULE_ID index) PLIB_ETH_InterruptStatusGet Function Gets the Ethernet module Interrupt Flag register as a group, using a mask. File plib_eth.h C bool PLIB_ETH_InterruptStatusGet(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask); Returns • true - If any of the specified source statuses are enabled Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 881 • false - If none of the specified source statuses are enabled Description This function gets the Ethernet module Interrupt Flag register using a mask. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if (PLIB_ETH_InterruptStatusGet(index, ETH_TRANSMIT_DONE_INTERRUPT)) { PLIB_ETH_InterruptClear(index, ETH_TRANSMIT_DONE_INTERRUPT); } Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together Function bool PLIB_ETH_InterruptStatusGet(ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask); g) Statistics Functions PLIB_ETH_AlignErrorCountClear Function Sets the count of Ethernet alignment errors to zero. File plib_eth.h C void PLIB_ETH_AlignErrorCountClear(ETH_MODULE_ID index); Returns None. Description This function sets the count of Ethernet alignment errors to zero. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_AlignErrorCountClear(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance value count of alignment errors Function void PLIB_ETH_AlignErrorCountClear(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 882 PLIB_ETH_AlignErrorCountGet Function Gets the count of Ethernet alignment errors. File plib_eth.h C uint16_t PLIB_ETH_AlignErrorCountGet(ETH_MODULE_ID index); Returns • value - Count of alignment errors Description This function gets the count of Ethernet alignment errors. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example count = PLIB_ETH_AlignErrorCountGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_AlignErrorCountGet(ETH_MODULE_ID index) PLIB_ETH_FCSErrorCountClear Function Sets the value of the Ethernet frame check sequence error to zero. File plib_eth.h C void PLIB_ETH_FCSErrorCountClear(ETH_MODULE_ID index); Returns None. Description This function sets the value of the Ethernet frame check sequence error to zero. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_FCSErrorCountClear(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 883 Parameters Parameters Description index Identifier for the device instance value Count of FCS Errors Function void PLIB_ETH_FCSErrorCountClear(ETH_MODULE_ID index) PLIB_ETH_FCSErrorCountGet Function Gets the count of the frame check sequence error. File plib_eth.h C uint16_t PLIB_ETH_FCSErrorCountGet(ETH_MODULE_ID index); Returns • value - Count of FCS Errors Description This function gets the count of the frame check sequence error. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example count = PLIB_ETH_FCSErrorCountGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_FCSErrorCountGet(ETH_MODULE_ID index) PLIB_ETH_FramesRxdOkCountClear Function Sets the value of the Ethernet received frames 'OK' count to zero. File plib_eth.h C void PLIB_ETH_FramesRxdOkCountClear(ETH_MODULE_ID index); Returns None. Description This function sets the value of the Ethernet frames 'OK' count to zero. Remarks Changing the value of this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 884 Preconditions None. Example PLIB_ETH_FramesRxdOkCountClear(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance value Count of frames received correctly Function void PLIB_ETH_FramesRxdOkCountClear(ETH_MODULE_ID index) PLIB_ETH_FramesRxdOkCountGet Function Gets the count of the frames frames received successfully. File plib_eth.h C uint16_t PLIB_ETH_FramesRxdOkCountGet(ETH_MODULE_ID index); Returns • value - Count of frames received correctly Description This function gets the count of the frames received successfully. Increment count for frames received successfully by the RX Filter. This count will not be incremented if there is a Frame Check Sequence (FCS) or Alignment error. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example count = PLIB_ETH_FramesRxdOkCountGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_FramesRxdOkCountGet(ETH_MODULE_ID index) PLIB_ETH_FramesTxdOkCountClear Function Sets the count of Ethernet Control frames transmitted to zero. File plib_eth.h C void PLIB_ETH_FramesTxdOkCountClear(ETH_MODULE_ID index); Returns None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 885 Description This function sets the count of Ethernet Control frames transmitted to zero. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_FramesTxdOkCountClear(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance value Count of control frames transmitted correctly Function void PLIB_ETH_FramesTxdOkCountClear(ETH_MODULE_ID index) PLIB_ETH_FramesTxdOkCountGet Function Gets the count of Ethernet Control Frames transmitted successfully. File plib_eth.h C uint16_t PLIB_ETH_FramesTxdOkCountGet(ETH_MODULE_ID index); Returns • count - count of control frames transmitted correctly Description This function gets the count of Ethernet Control Frames transmitted successfully. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example count = PLIB_ETH_FramesTxdOkCountGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_FramesTxdOkCountGet(ETH_MODULE_ID index) PLIB_ETH_MultipleCollisionCountClear Function Sets the value of the Ethernet multiple collision frame count to zero. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 886 C void PLIB_ETH_MultipleCollisionCountClear(ETH_MODULE_ID index); Returns None. Description This function sets the value of the Ethernet multiple collision frame count to zero. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_MultipleCollisionCountClear(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance value Count of multiple collision frames Function void PLIB_ETH_MultipleCollisionCountClear(ETH_MODULE_ID index) PLIB_ETH_MultipleCollisionCountGet Function Gets the count of the frames transmitted successfully after there was more than one collision. File plib_eth.h C uint16_t PLIB_ETH_MultipleCollisionCountGet(ETH_MODULE_ID index); Returns • count - Count of multiple collision frames Description This function gets the count of the frames transmitted successfully after there was more than one collision. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example count = PLIB_ETH_MultipleCollisionCountGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_MultipleCollisionCountGet(ETH_MODULE_ID index) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 887 PLIB_ETH_RxOverflowCountClear Function Sets the value of the Ethernet receive overflow count to zero. File plib_eth.h C void PLIB_ETH_RxOverflowCountClear(ETH_MODULE_ID index); Returns None. Description This function sets the value of the Ethernet receive overflow count to zero. Increment counter for frames accepted by the RX filter and subsequently dropped due to internal receive error. This event also sets the receive overflow interrupt flag. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_RxOverflowCountClear(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function void PLIB_ETH_RxOverflowCountClear(ETH_MODULE_ID index) PLIB_ETH_RxOverflowCountGet Function Gets the count of the dropped Ethernet receive frames. File plib_eth.h C uint16_t PLIB_ETH_RxOverflowCountGet(ETH_MODULE_ID index); Returns • count - uint16_t receiver overflow counts Description This function gets the count of the dropped Ethernet receive frames. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example count = PLIB_ETH_RxOverflowCountGet(MY_ETH_INSTANCE); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 888 Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_RxOverflowCountGet(ETH_MODULE_ID index) PLIB_ETH_RxPacketCountGet Function Gets the value of the receive packet buffer count. File plib_eth.h C uint8_t PLIB_ETH_RxPacketCountGet(ETH_MODULE_ID index); Returns • RxPacketCount - Number of received packets in memory Description This function gets the value of the receive packet buffer count. When a packet has been successfully received, this value is incremented by hardware. Software decrements the counter after a packet has been read. Call PLIB_ETH_ReceiveBufferCountDecrement(ETH_MODULE_ID index) to decrement. Remarks Receive Packet Buffer Counter cannot be decremented below 0x00 Cleared when the Ethernet module is reset. The Receive Packet Buffer Count is not set to '0' when the Ethernet module is turned OFF. This allows software to continue to utilize and decrement the count. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example count = PLIB_ETH_RxPacketCountGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_ETH_RxPacketCountGet(ETH_MODULE_ID index) PLIB_ETH_SingleCollisionCountClear Function Sets the value of the Ethernet single collision frame count to zero. File plib_eth.h C void PLIB_ETH_SingleCollisionCountClear(ETH_MODULE_ID index); Returns None. Description This function sets the value of the Ethernet single collision frame count to zero. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 889 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_ETH_SingleCollisionCountClear(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance value Count of single collision frames Function void PLIB_ETH_SingleCollisionCountClear(ETH_MODULE_ID index) PLIB_ETH_SingleCollisionCountGet Function Gets the count of the frames transmitted successfully on a second attempt. File plib_eth.h C uint16_t PLIB_ETH_SingleCollisionCountGet(ETH_MODULE_ID index); Returns • count - Count of frames transmitted successfully on second attempt Description This function gets the count of the frames transmitted successfully on a second attempt. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example count = PLIB_ETH_SingleCollisionCountGet(MY_ETH_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint16_t PLIB_ETH_SingleCollisionCountGet(ETH_MODULE_ID index) h) Feature Existence Functions PLIB_ETH_ExistsAlignmentErrorCount Function Identifies whether the AlignmentErrorCount feature exists on the Ethernet module. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 890 C bool PLIB_ETH_ExistsAlignmentErrorCount(ETH_MODULE_ID index); Returns • true - The AlignmentErrorCount feature is supported on the device • false - The AlignmentErrorCount feature is not supported on the device Description This function identifies whether the AlignmentErrorCount feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_AlignErrorCountClear • PLIB_ETH_AlignErrorCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsAlignmentErrorCount( ETH_MODULE_ID index ) PLIB_ETH_ExistsAutoFlowControl Function Identifies whether the AutoFlowControl feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsAutoFlowControl(ETH_MODULE_ID index); Returns • true - The AutoFlowControl feature is supported on the device • false - The AutoFlowControl feature is not supported on the device Description This function identifies whether the AutoFlowControl feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_AutoFlowControlEnable • PLIB_ETH_AutoFlowControlDisable • PLIB_ETH_AutoFlowControlIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsAutoFlowControl( ETH_MODULE_ID index ) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 891 PLIB_ETH_ExistsCollisionCounts Function Identifies whether the CollisionCounts feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsCollisionCounts(ETH_MODULE_ID index); Returns • true - The CollisionCounts feature is supported on the device • false - The CollisionCounts feature is not supported on the device Description This function identifies whether the CollisionCounts feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_SingleCollisionCountClear • PLIB_ETH_SingleCollisionCountGet • PLIB_ETH_MultipleCollisionCountClear • PLIB_ETH_MultipleCollisionCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsCollisionCounts( ETH_MODULE_ID index ) PLIB_ETH_ExistsCollisionWindow Function Identifies whether the CollisionWindow feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsCollisionWindow(ETH_MODULE_ID index); Returns • true - The CollisionWindow feature is supported on the device • false - The CollisionWindow feature is not supported on the device Description This function identifies whether the CollisionWindow feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_CollisionWindowGet • PLIB_ETH_CollisionWindowSet Remarks None. Preconditions None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 892 Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsCollisionWindow( ETH_MODULE_ID index ) PLIB_ETH_ExistsEnable Function Identifies whether the Enable feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsEnable(ETH_MODULE_ID index); Returns • true - The Enable feature is supported on the device • false - The Enable feature is not supported on the device Description This function identifies whether the Enable feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_Enable • PLIB_ETH_Disable • PLIB_ETH_IsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsEnable( ETH_MODULE_ID index ) PLIB_ETH_ExistsEthernetControllerStatus Function Identifies whether the EthernetControllerStatus feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsEthernetControllerStatus(ETH_MODULE_ID index); Returns • true - The EthernetControllerStatus feature is supported on the device • false - The EthernetControllerStatus feature is not supported on the device Description This function identifies whether the EthernetControllerStatus feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxPacketCountGet • PLIB_ETH_EthernetIsBus Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 893 • PLIB_ETH_TransmitIsBusy • PLIB_ETH_ReceiveIsBusy Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsEthernetControllerStatus( ETH_MODULE_ID index ) PLIB_ETH_ExistsFCSErrorCount Function Identifies whether the FCSErrorCount feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsFCSErrorCount(ETH_MODULE_ID index); Returns • true - The FCSErrorCount feature is supported on the device • false - The FCSErrorCount feature is not supported on the device Description This function identifies whether the FCSErrorCount feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_FCSErrorCountClear • PLIB_ETH_FCSErrorCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsFCSErrorCount( ETH_MODULE_ID index ) PLIB_ETH_ExistsFramesTransmittedOK Function Identifies whether the FramesTransmittedOK feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsFramesTransmittedOK(ETH_MODULE_ID index); Returns • true - The FramesTransmittedOK feature is supported on the device Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 894 • false - The FramesTransmittedOK feature is not supported on the device Description This function identifies whether the FramesTransmittedOK feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_FramesTxdOkCountClear • PLIB_ETH_FramesTxdOkCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsFramesTransmittedOK( ETH_MODULE_ID index ) PLIB_ETH_ExistsFramexReceivedOK Function Identifies whether the FramexReceivedOK feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsFramexReceivedOK(ETH_MODULE_ID index); Returns • true - The FramexReceivedOK feature is supported on the device • false - The FramexReceivedOK feature is not supported on the device Description This function identifies whether the FramexReceivedOK feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_FramesRxdOkCountClear • PLIB_ETH_FramesRxdOkCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsFramexReceivedOK( ETH_MODULE_ID index ) PLIB_ETH_ExistsHashTable Function Identifies whether the HashTable feature exists on the Ethernet module. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 895 C bool PLIB_ETH_ExistsHashTable(ETH_MODULE_ID index); Returns • true - The HashTable feature is supported on the device • false - The HashTable feature is not supported on the device Description This function identifies whether the HashTable feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_HashTableSet • PLIB_ETH_HashTableGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsHashTable( ETH_MODULE_ID index ) PLIB_ETH_ExistsInterPacketGaps Function Identifies whether the InterPacketGaps feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsInterPacketGaps(ETH_MODULE_ID index); Returns • true - The InterPacketGaps feature is supported on the device • false - The InterPacketGaps feature is not supported on the device Description This function identifies whether the InterPacketGaps feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_BackToBackIPGGet • PLIB_ETH_BackToBackIPGSet • PLIB_ETH_NonBackToBackIPG1Get • PLIB_ETH_NonBackToBackIPG1Set • PLIB_ETH_NonBackToBackIPG2Get • PLIB_ETH_NonBackToBackIPG2Set Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 896 Function PLIB_ETH_ExistsInterPacketGaps( ETH_MODULE_ID index ) PLIB_ETH_ExistsInterrupt Function Identifies whether the Interrupt feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsInterrupt(ETH_MODULE_ID index); Returns • true - The Interrupt feature is supported on the device • false - The Interrupt feature is not supported on the device Description This function identifies whether the Interrupt feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_InterruptSourceEnable • PLIB_ETH_InterruptSourceDisable • PLIB_ETH_InterruptSourceIsEnabled • PLIB_ETH_InterruptSet • PLIB_ETH_InterruptClear • PLIB_ETH_InterruptStatusGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsInterrupt( ETH_MODULE_ID index ) PLIB_ETH_ExistsMAC_Configuration Function Identifies whether the MAC_Configuration feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsMAC_Configuration(ETH_MODULE_ID index); Returns • true - The MAC_Configuration feature is supported on the device • false - The MAC_Configuration feature is not supported on the device Description This function identifies whether the MAC_Configuration feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_LoopbackEnable • PLIB_ETH_LoopbackDisable • PLIB_ETH_LoopbackIsEnabled Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 897 • PLIB_ETH_TxPauseEnable • PLIB_ETH_TxPauseDisable • PLIB_ETH_TxPauseIsEnabled • PLIB_ETH_RxPauseEnable • PLIB_ETH_RxPauseDisable • PLIB_ETH_RxPauseIsEnabled • PLIB_ETH_PassAllEnable • PLIB_ETH_PassAllDisable • PLIB_ETH_PassAllIsEnabled • PLIB_ETH_ReceiveEnable • PLIB_ETH_ReceiveDisable • PLIB_ETH_ReceiveIsEnabled • PLIB_ETH_ExcessDeferEnable • PLIB_ETH_ExcessDeferDisable • PLIB_ETH_ExcessDeferIsEnabled • PLIB_ETH_BackPresNoBackoffEnable • PLIB_ETH_BackPresNoBackoffDisable • PLIB_ETH_BackPresNoBackoffIsEnabled • PLIB_ETH_NoBackoffEnable • PLIB_ETH_NoBackoffDisable • PLIB_ETH_NoBackoffIsEnabled • PLIB_ETH_LongPreambleEnable • PLIB_ETH_LongPreambleDisable • PLIB_ETH_LongPreambleIsEnabled • PLIB_ETH_PurePreambleEnable • PLIB_ETH_PurePreambleDisable • PLIB_ETH_PurePreambleIsEnabled • PLIB_ETH_AutoDetectPadGet • PLIB_ETH_AutoDetectPadSet • PLIB_ETH_AutoDetectPadClear • PLIB_ETH_CRCEnable • PLIB_ETH_CRCDisable • PLIB_ETH_CRCIsEnabled • PLIB_ETH_DelayedCRCEnable • PLIB_ETH_DelayedCRCDisable • PLIB_ETH_DelayedCRCIsEnabled • PLIB_ETH_HugeFrameEnable • PLIB_ETH_HugeFrameDisable • PLIB_ETH_HugeFrameIsEnabled • PLIB_ETH_FrameLengthCheckEnable • PLIB_ETH_FrameLengthCheckDisable • PLIB_ETH_FrameLengthCheckIsEnabled • PLIB_ETH_FullDuplexEnable • PLIB_ETH_FullDuplexDisable • PLIB_ETH_FullDuplexIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMAC_Configuration( ETH_MODULE_ID index ) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 898 PLIB_ETH_ExistsMAC_Resets Function Identifies whether the MAC_Resets feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsMAC_Resets(ETH_MODULE_ID index); Returns • true - The MAC_Resets feature is supported on the device • false - The MAC_Resets feature is not supported on the device Description This function identifies whether the MAC_Resets feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIResetEnable • PLIB_ETH_MIIResetDisable • PLIB_ETH_MIIResetIsEnabled • PLIB_ETH_SimResetEnable • PLIB_ETH_SimResetDisable • PLIB_ETH_SimResetIsEnabled • PLIB_ETH_MCSRxResetEnable • PLIB_ETH_MCSRxResetDisable • PLIB_ETH_MCSRxResetIsEnabled • PLIB_ETH_RxFuncResetEnable • PLIB_ETH_RxFuncResetDisable • PLIB_ETH_RxFuncResetIsEnabled • PLIB_ETH_MCSTxResetEnable • PLIB_ETH_MCSTxResetDisable • PLIB_ETH_MCSTxResetIsEnabled • PLIB_ETH_TxFuncResetEnable • PLIB_ETH_TxFuncResetDisable • PLIB_ETH_TxFuncResetIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMAC_Resets( ETH_MODULE_ID index ) PLIB_ETH_ExistsMAC_Testing Function Identifies whether the MAC_Testing feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsMAC_Testing(ETH_MODULE_ID index); Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 899 Returns • true - The MAC_Testing feature is supported on the device • false - The MAC_Testing feature is not supported on the device Description This function identifies whether the MAC_Testing feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_TestBackPressEnable • PLIB_ETH_TestBackPressDisable • PLIB_ETH_TestBackPressIsEnabled • PLIB_ETH_TestPauseEnable • PLIB_ETH_TestPauseDisable • PLIB_ETH_TestPauseIsEnabled • PLIB_ETH_ShortcutQuantaEnable • PLIB_ETH_ShortcutQuantaDisable • PLIB_ETH_ShortcutQuantaIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMAC_Testing( ETH_MODULE_ID index ) PLIB_ETH_ExistsManualFlowControl Function Identifies whether the ManualFlowControl feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsManualFlowControl(ETH_MODULE_ID index); Returns • true - The ManualFlowControl feature is supported on the device • false - The ManualFlowControl feature is not supported on the device Description This function identifies whether the ManualFlowControl feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_ManualFlowControlEnable • PLIB_ETH_ManualFlowControlDisable • PLIB_ETH_ManualFlowControlIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 900 Function PLIB_ETH_ExistsManualFlowControl( ETH_MODULE_ID index ) PLIB_ETH_ExistsMaxFrameLength Function Identifies whether the MaxFrameLength feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsMaxFrameLength(ETH_MODULE_ID index); Returns • true - The MaxFrameLength feature is supported on the device • false - The MaxFrameLength feature is not supported on the device Description This function identifies whether the MaxFrameLength feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MaxFrameLengthGet • PLIB_ETH_MaxFrameLengthSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMaxFrameLength( ETH_MODULE_ID index ) PLIB_ETH_ExistsMIIM_Config Function Identifies whether the MIIM_Config feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsMIIM_Config(ETH_MODULE_ID index); Returns • true - The MIIM_Config feature is supported on the device • false - The MIIM_Config feature is not supported on the device Description This function identifies whether the MIIM_Config feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIMResetEnable • PLIB_ETH_MIIMResetDisable • PLIB_ETH_MIIMResetIsEnabled • PLIB_ETH_MIIMClockGet • PLIB_ETH_MIIMClockSet • PLIB_ETH_MIIMNoPreEnable • PLIB_ETH_MIIMNoPreDisable Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 901 • PLIB_ETH_MIIMNoPreIsEnabled • PLIB_ETH_MIIMScanIncrEnable • PLIB_ETH_MIIMScanIncrDisable • PLIB_ETH_MIIMScanIncrIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMIIM_Config( ETH_MODULE_ID index ) PLIB_ETH_ExistsMIIM_Indicators Function Identifies whether the MIIM_Indicators feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsMIIM_Indicators(ETH_MODULE_ID index); Returns • true - The MIIM_Indicators feature is supported on the device • false - The MIIM_Indicators feature is not supported on the device Description This function identifies whether the MIIM_Indicators feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_LinkHasFailed • PLIB_ETH_DataNotValid • PLIB_ETH_MIIMIsScanning • PLIB_ETH_MIIMIsBusy Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMIIM_Indicators( ETH_MODULE_ID index ) PLIB_ETH_ExistsMIIMAddresses Function Identifies whether the MIIMAddresses feature exists on the Ethernet module. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 902 C bool PLIB_ETH_ExistsMIIMAddresses(ETH_MODULE_ID index); Returns • true - The MIIMAddresses feature is supported on the device • false - The MIIMAddresses feature is not supported on the device Description This function identifies whether the MIIMAddresses feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_PHYAddressGet • PLIB_ETH_PHYAddressSet • PLIB_ETH_RegisterAddressGet • PLIB_ETH_RegisterAddressSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMIIMAddresses( ETH_MODULE_ID index ) PLIB_ETH_ExistsMIIMReadWrite Function Identifies whether the MIIMReadWrite feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsMIIMReadWrite(ETH_MODULE_ID index); Returns • true - The MIIMReadWrite feature is supported on the device • false - The MIIMReadWrite feature is not supported on the device Description This function identifies whether the MIIMReadWrite feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIMReadStart • PLIB_ETH_MIIMWriteStart Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMIIMReadWrite( ETH_MODULE_ID index ) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 903 PLIB_ETH_ExistsMIIMScanMode Function Identifies whether the MIIMScanMode feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsMIIMScanMode(ETH_MODULE_ID index); Returns • true - The MIIMScanMode feature is supported on the device • false - The MIIMScanMode feature is not supported on the device Description This function identifies whether the MIIMScanMode feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIMScanModeEnable • PLIB_ETH_MIIMScanModeDisable • PLIB_ETH_MIIMScanModeIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMIIMScanMode( ETH_MODULE_ID index ) PLIB_ETH_ExistsMIIWriteReadData Function Identifies whether the MIIWriteReadData feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsMIIWriteReadData(ETH_MODULE_ID index); Returns • true - The MIIWriteReadData feature is supported on the device • false - The MIIWriteReadData feature is not supported on the device Description This function identifies whether the MIIWriteReadData feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIMWriteDataSet • PLIB_ETH_MIIMReadDataGet Remarks None. Preconditions None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 904 Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsMIIWriteReadData( ETH_MODULE_ID index ) PLIB_ETH_ExistsPatternMatch Function Identifies whether the PatternMatch feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsPatternMatch(ETH_MODULE_ID index); Returns • true - The PatternMatch feature is supported on the device • false - The PatternMatch feature is not supported on the device Description This function identifies whether the PatternMatch feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_PatternMatchSet • PLIB_ETH_PatternMatchGet • PLIB_ETH_PatternMatchChecksumSet • PLIB_ETH_PatternMatchChecksumGet • PLIB_ETH_PatternMatchOffsetSet • PLIB_ETH_PatternMatchOffsetGet • PLIB_ETH_PatternMatchModeSet • PLIB_ETH_PatternMatchModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsPatternMatch( ETH_MODULE_ID index ) PLIB_ETH_ExistsPauseTimer Function Identifies whether the PauseTimer feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsPauseTimer(ETH_MODULE_ID index); Returns • true - The PauseTimer feature is supported on the device • false - The PauseTimer feature is not supported on the device Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 905 Description This function identifies whether the PauseTimer feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_PauseTimerSet • PLIB_ETH_PauseTimerGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsPauseTimer( ETH_MODULE_ID index ) PLIB_ETH_ExistsReceiveBufferSize Function Identifies whether the ReceiveBufferSize feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsReceiveBufferSize(ETH_MODULE_ID index); Returns • true - The ReceiveBufferSize feature is supported on the device • false - The ReceiveBufferSize feature is not supported on the device Description This function identifies whether the ReceiveBufferSize feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_ReceiveBufferSizeGet • PLIB_ETH_ReceiveBufferSizeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsReceiveBufferSize( ETH_MODULE_ID index ) PLIB_ETH_ExistsReceiveFilters Function Identifies whether the ReceiveFilters feature exists on the Ethernet module. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 906 C bool PLIB_ETH_ExistsReceiveFilters(ETH_MODULE_ID index); Returns • true - The ReceiveFilters feature is supported on the device • false - The ReceiveFilters feature is not supported on the device Description This function identifies whether the ReceiveFilters feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_ReceiveFilterEnable • PLIB_ETH_ReceiveFilterDisable • PLIB_ETH_ReceiveFilterIsEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsReceiveFilters( ETH_MODULE_ID index ) PLIB_ETH_ExistsReceiveOverflowCount Function Identifies whether the ReceiveOverflowCount feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsReceiveOverflowCount(ETH_MODULE_ID index); Returns • true - The ReceiveOverflowCount feature is supported on the device • false - The ReceiveOverflowCount feature is not supported on the device Description This function identifies whether the ReceiveOverflowCount feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxOverflowCountClear • PLIB_ETH_RxOverflowCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsReceiveOverflowCount( ETH_MODULE_ID index ) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 907 PLIB_ETH_ExistsReceiveWmarks Function Identifies whether the ReceiveWmarks feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsReceiveWmarks(ETH_MODULE_ID index); Returns • true - The ReceiveWmarks feature is supported on the device • false - The ReceiveWmarks feature is not supported on the device Description This function identifies whether the ReceiveWmarks feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxFullWmarkSet • PLIB_ETH_RxFullWmarkGet • PLIB_ETH_RxEmptyWmarkSet • PLIB_ETH_RxEmptyWmarkGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsReceiveWmarks( ETH_MODULE_ID index ) PLIB_ETH_ExistsRetransmissionMaximum Function Identifies whether the RetransmissionMaximum feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsRetransmissionMaximum(ETH_MODULE_ID index); Returns • true - The RetransmissionMaximum feature is supported on the device • false - The RetransmissionMaximum feature is not supported on the device Description This function identifies whether the RetransmissionMaximum feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_ReTxMaxGet • PLIB_ETH_ReTxMaxSet Remarks None. Preconditions None. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 908 Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsRetransmissionMaximum( ETH_MODULE_ID index ) PLIB_ETH_ExistsRMII_Support Function Identifies whether the RMII_Support feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsRMII_Support(ETH_MODULE_ID index); Returns • true - The RMII_Support feature is supported on the device • false - The RMII_Support feature is not supported on the device Description This function identifies whether the RMII_Support feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RMIIResetEnable • PLIB_ETH_RMIIResetDisable • PLIB_ETH_RMIIResetIsEnabled • PLIB_ETH_RMIISpeedGet • PLIB_ETH_RMIISpeedSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsRMII_Support( ETH_MODULE_ID index ) PLIB_ETH_ExistsRxBufferCountDecrement Function Identifies whether the RxBufferCountDecrement feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsRxBufferCountDecrement(ETH_MODULE_ID index); Returns • true - The RxBufferCountDecrement feature is supported on the device • false - The RxBufferCountDecrement feature is not supported on the device Description This function identifies whether the RxBufferCountDecrement feature is available on the Ethernet module. When this function returns true, this function is supported on the device: Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 909 • PLIB_ETH_RxBufferCountDecrement Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsRxBufferCountDecrement( ETH_MODULE_ID index ) PLIB_ETH_ExistsRxEnable Function Identifies whether the ReceiveEnable feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsRxEnable(ETH_MODULE_ID index); Returns • true - The ReceiveEnable feature is supported on the device • false - The ReceiveEnable feature is not supported on the device Description This function identifies whether the ReceiveEnable feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxEnable • PLIB_ETH_RxDisable • PLIB_ETH_RxIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsRxEnable( ETH_MODULE_ID index ) PLIB_ETH_ExistsRxPacketDescriptorAddress Function Identifies whether the RxPacketDescriptorAddress feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsRxPacketDescriptorAddress(ETH_MODULE_ID index); Returns • true - The RxPacketDescriptorAddress feature is supported on the device Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 910 • false - The RxPacketDescriptorAddress feature is not supported on the device Description This function identifies whether the RxPacketDescriptorAddress feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxPacketDescAddrSet • PLIB_ETH_RxPacketDescAddrGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsRxPacketDescriptorAddress( ETH_MODULE_ID index ) PLIB_ETH_ExistsStationAddress Function Identifies whether the StationAddress feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsStationAddress(ETH_MODULE_ID index); Returns • true - The StationAddress feature is supported on the device • false - The StationAddress feature is not supported on the device Description This function identifies whether the StationAddress feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_StationAddressGet • PLIB_ETH_StationAddressSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsStationAddress( ETH_MODULE_ID index ) PLIB_ETH_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the Ethernet module. File plib_eth.h Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 911 C bool PLIB_ETH_ExistsStopInIdle(ETH_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_StopInIdleEnable • PLIB_ETH_StopInIdleDisable • PLIB_ETH_StopInIdleIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsStopInIdle( ETH_MODULE_ID index ) PLIB_ETH_ExistsTransmitRTS Function Identifies whether the TransmitRTS feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsTransmitRTS(ETH_MODULE_ID index); Returns • true - The TransmitRTS feature is supported on the device • false - The TransmitRTS feature is not supported on the device Description This function identifies whether the TransmitRTS feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_TxRTSEnable • PLIB_ETH_TxRTSDisable • PLIB_ETH_TxRTSIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsTransmitRTS( ETH_MODULE_ID index ) Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 912 PLIB_ETH_ExistsTxPacketDescriptorAddress Function Identifies whether the TxPacketDescriptorAddress feature exists on the Ethernet module. File plib_eth.h C bool PLIB_ETH_ExistsTxPacketDescriptorAddress(ETH_MODULE_ID index); Returns • true - The TxPacketDescriptorAddress feature is supported on the device • false - The TxPacketDescriptorAddress feature is not supported on the device Description This function identifies whether the TxPacketDescriptorAddress feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_TxPacketDescAddrSet • PLIB_ETH_TxPacketDescAddrGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_ETH_ExistsTxPacketDescriptorAddress( ETH_MODULE_ID index ) i) Data Types and Constants ETH_AUTOPAD_OPTION Enumeration Lists the possible automatic padding configurations. File plib_eth.h C typedef enum { ETH_AUTOPAD_DISABLED_CHECK_CRC, ETH_AUTOPAD_TO_60BYTES_ADD_CRC, ETH_AUTOPAD_TO_64BYTES_ADD_CRC, ETH_AUTOPAD_BY_PKT_TYPE_ADD_CRC } ETH_AUTOPAD_OPTION; Description AutoDetectPad Selection This enumeration lists the possible automatic padding configurations. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). ETH_INTERRUPT_SOURCES Enumeration Lists the possible values of ETH_INTERRUPT_SOURCES. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 913 File plib_eth.h C typedef enum { ETH_TRANSMIT_BVCI_BUS_ERROR_INTERRUPT, ETH_RECEIVE_BVCI_BUS_ERROR_INTERRUPT, ETH_EMPTY_WATERMARK_INTERRUPT, ETH_FULL_WATERMARK_INTERRUPT, ETH_RECEIVE_DONE_INTERRUPT, ETH_PACKET_PENDING_INTERRUPT, ETH_RECEIVE_ACTIVITY_INTERRUPT, ETH_TRANSMIT_DONE_INTERRUPT, ETH_TRANSMIT_ABORT_INTERRUPT, ETH_RECEIVE_BUFFER_NOT_AVAILABLE_INTERRUPT, ETH_RECEIVE_FIFO_OVERFLOW_ERROR_INTERRUPT, ETH_ALL_INTERRUPT_SOURCES } ETH_INTERRUPT_SOURCES; Description ETH Module Interrupt Mask This enumeration lists the possible values of ETH_INTERRUPT_SOURCES. Remarks See also PLIB_ETH_EVENTS in plib_eth_lib.h. ETH_MIIM_CLK Enumeration Lists the possible speed selection for the Reduced Media Independent Interface (RMII). File plib_eth.h C typedef enum { ETH_MIIM_SYSCLK_DIV_BY_4, ETH_MIIM_SYSCLK_DIV_RSVD, ETH_MIIM_SYSCLK_DIV_BY_6, ETH_MIIM_SYSCLK_DIV_BY_8, ETH_MIIM_SYSCLK_DIV_BY_10, ETH_MIIM_SYSCLK_DIV_BY_14, ETH_MIIM_SYSCLK_DIV_BY_20, ETH_MIIM_SYSCLK_DIV_BY_28, ETH_MIIM_SYSCLK_DIV_BY_40 } ETH_MIIM_CLK; Description MII Clock Selection This enumeration lists the possible speed selection for RMII. The body contains only two states: RMII_10Mbps or RMII_100Mbps. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). ETH_PATTERN_MATCH_MODE Enumeration Lists the possible pattern match values. File plib_eth.h C typedef enum _ETH_PATTERN_MATCH_MODE_ { ETH_PATTERN_MATCH_DISABLED, ETH_PATTERN_MATCH_MODE_CHECKSUM_MATCH, ETH_PATTERN_MATCH_MODE_STATION_ADDR, Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 914 ETH_PATTERN_MATCH_MODE_UNICAST_ADDR, ETH_PATTERN_MATCH_MODE_BROADCAST_ADDR, ETH_PATTERN_MATCH_MODE_HASH_MATCH, ETH_PATTERN_MATCH_MODE_MAGIC_PACKET } ETH_PATTERN_MATCH_MODE; Members Members Description ETH_PATTERN_MATCH_DISABLED Pattern Match is disabled; pattern match is always unsuccessful ETH_PATTERN_MATCH_MODE_CHECKSUM_MATCH Pattern match if (NOTPM = 1 XOR Pattern Match Checksum matches) ETH_PATTERN_MATCH_MODE_STATION_ADDR Pattern match if (NOTPM = 1 XOR Pattern Match Checksum matches) AND (Destination Address = Station Address) ETH_PATTERN_MATCH_MODE_UNICAST_ADDR Pattern match if (NOTPM = 1 XOR Pattern Match Checksum matches) AND (Destination Address = Unicast Address) ETH_PATTERN_MATCH_MODE_BROADCAST_ADDR Pattern match if (NOTPM = 1 XOR Pattern Match Checksum matches) AND (Destination Address = Broadcast Address) ETH_PATTERN_MATCH_MODE_HASH_MATCH Pattern match if (NOTPM = 1 XOR Pattern Match Checksum matches) AND (Hash Table Filter match) ETH_PATTERN_MATCH_MODE_MAGIC_PACKET Pattern match if (NOTPM = 1 XOR Pattern Match Checksum matches) AND (Packet = Magic Packet) Description Pattern Match Modes This enumeration lists the pattern match mode values. Remarks In all pattern match enabled cases, it is the pattern match inversion XOR pattern match checksum AND . Some states were omitted from the enumeration since they were duplicates. This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). ETH_RECEIVE_FILTER Enumeration Lists the possible values of the receive filter. File plib_eth.h C typedef enum { ETH_HASH_FILTER, ETH_MAGIC_PACKET_FILTER, ETH_PATTERN_MATCH_INVERSION, ETH_CRC_ERROR_FILTER, ETH_CRC_OK_FILTER, ETH_RUNT_ERROR_FILTER, ETH_RUNT_ENABLE_FILTER, ETH_UNICAST_FILTER, ETH_NOT_ME_UNICAST_FILTER, ETH_MULTICAST_FILTER, ETH_BROADCAST_FILTER, ETH_ENABLE_ALL_FILTER } ETH_RECEIVE_FILTER; Members Members Description ETH_HASH_FILTER Enable: Hash Table Filtering. ETH_MAGIC_PACKET_FILTER Enable: Magic Packet Filtering. ETH_PATTERN_MATCH_INVERSION Enable: Pattern Match Checksum must not match to be accepted. ETH_CRC_ERROR_FILTER Enable: Received packet CRC must be invalid to be accepted. ETH_CRC_OK_FILTER Enable: Received packet CRC must be valid to be accepted. ETH_RUNT_ERROR_FILTER Enable: Received packet must be runt packet to be accepted. ETH_RUNT_ENABLE_FILTER Enable: Received packet must not be a runt packet to be accepted. Peripheral Libraries Help Ethernet Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 915 ETH_UNICAST_FILTER Enable: Unicast Packets whose destination address matches the station address are accepted. ETH_NOT_ME_UNICAST_FILTER Enable: Unicast Packets whose destination address do NOT match the station address are accepted. ETH_MULTICAST_FILTER Enable: Multicast Address Packets are accepted. ETH_BROADCAST_FILTER Enable: Broadcast Address Packets are accepted. ETH_ENABLE_ALL_FILTER Enable: All of the above packets are accepted. Description ETH Module Receive Filter Mask This enumeration lists the possible values of the receive filter. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). ETH_RMII_SPEED Enumeration Lists the possible speed selection for the Reduced Media Independent Interface (RMII). File plib_eth.h C typedef enum { ETH_RMII_10Mbps, ETH_RMII_100Mps } ETH_RMII_SPEED; Description RMII Speed Selection This enumeration lists the possible speed selection for RMII. The body contains only two states: RMII_10Mbps or RMII_100Mbps. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). Files Files Name Description plib_eth.h Defines the Ethernet Peripheral Library Interface. Description This section lists the source and header files used by the library. plib_eth.h Defines the Ethernet Peripheral Library Interface. Enumerations Name Description _ETH_PATTERN_MATCH_MODE_ Lists the possible pattern match values. ETH_AUTOPAD_OPTION Lists the possible automatic padding configurations. ETH_INTERRUPT_SOURCES Lists the possible values of ETH_INTERRUPT_SOURCES. ETH_MIIM_CLK Lists the possible speed selection for the Reduced Media Independent Interface (RMII). ETH_PATTERN_MATCH_MODE Lists the possible pattern match values. ETH_RECEIVE_FILTER Lists the possible values of the receive filter. ETH_RMII_SPEED Lists the possible speed selection for the Reduced Media Independent Interface (RMII). Peripheral Libraries Help Ethernet Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 916 Functions Name Description PLIB_ETH_AlignErrorCountClear Sets the count of Ethernet alignment errors to zero. PLIB_ETH_AlignErrorCountGet Gets the count of Ethernet alignment errors. PLIB_ETH_AutoDetectPadClear Clears the EMAC Auto-Pad option. PLIB_ETH_AutoDetectPadGet Gets the current EMAC Auto-Pad setting. PLIB_ETH_AutoDetectPadSet Sets the EMAC Auto-Pad option. PLIB_ETH_AutoFlowControlDisable Disables the Ethernet module Automatic Flow Control logic. PLIB_ETH_AutoFlowControlEnable Enables the Ethernet Automatic Flow Control logic. PLIB_ETH_AutoFlowControlIsEnabled Gets the Ethernet module Automatic Flow Control status. PLIB_ETH_BackPresNoBackoffDisable Disables EMAC backpressure/no back-off. PLIB_ETH_BackPresNoBackoffEnable Enables EMAC back pressure/no back-off. PLIB_ETH_BackPresNoBackoffIsEnabled Gets the EMAC backpressure/no back-off enable status. PLIB_ETH_BackToBackIPGGet Gets the EMAC back-to-back interpacket gap. PLIB_ETH_BackToBackIPGSet Sets the EMAC back-to-back interpacket gap. PLIB_ETH_CollisionWindowGet Gets the EMAC collision window. PLIB_ETH_CollisionWindowSet Sets the EMAC collision window. PLIB_ETH_CRCDisable Disables EMAC CRC. PLIB_ETH_CRCEnable Enables EMAC CRC. PLIB_ETH_CRCIsEnabled Gets the EMAC CRC enable status. PLIB_ETH_DataNotValid Gets the MII management read data not valid status. PLIB_ETH_DelayedCRCDisable Disables EMAC delayed CRC. PLIB_ETH_DelayedCRCEnable Enables EMAC delayed CRC. PLIB_ETH_DelayedCRCIsEnabled Gets the EMAC delayed CRC enable status. PLIB_ETH_Disable Disables the Ethernet module. PLIB_ETH_Enable Enables the Ethernet module. PLIB_ETH_EthernetIsBusy Gets the status value of the Ethernet logic busy. PLIB_ETH_ExcessDeferDisable Disables EMAC excess defer. PLIB_ETH_ExcessDeferEnable Enables EMAC excess defer. PLIB_ETH_ExcessDeferIsEnabled Gets the EMAC excess defer enable status. PLIB_ETH_ExistsAlignmentErrorCount Identifies whether the AlignmentErrorCount feature exists on the Ethernet module. PLIB_ETH_ExistsAutoFlowControl Identifies whether the AutoFlowControl feature exists on the Ethernet module. PLIB_ETH_ExistsCollisionCounts Identifies whether the CollisionCounts feature exists on the Ethernet module. PLIB_ETH_ExistsCollisionWindow Identifies whether the CollisionWindow feature exists on the Ethernet module. PLIB_ETH_ExistsEnable Identifies whether the Enable feature exists on the Ethernet module. PLIB_ETH_ExistsEthernetControllerStatus Identifies whether the EthernetControllerStatus feature exists on the Ethernet module. PLIB_ETH_ExistsFCSErrorCount Identifies whether the FCSErrorCount feature exists on the Ethernet module. PLIB_ETH_ExistsFramesTransmittedOK Identifies whether the FramesTransmittedOK feature exists on the Ethernet module. PLIB_ETH_ExistsFramexReceivedOK Identifies whether the FramexReceivedOK feature exists on the Ethernet module. PLIB_ETH_ExistsHashTable Identifies whether the HashTable feature exists on the Ethernet module. PLIB_ETH_ExistsInterPacketGaps Identifies whether the InterPacketGaps feature exists on the Ethernet module. PLIB_ETH_ExistsInterrupt Identifies whether the Interrupt feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Configuration Identifies whether the MAC_Configuration feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Resets Identifies whether the MAC_Resets feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Testing Identifies whether the MAC_Testing feature exists on the Ethernet module. PLIB_ETH_ExistsManualFlowControl Identifies whether the ManualFlowControl feature exists on the Ethernet module. PLIB_ETH_ExistsMaxFrameLength Identifies whether the MaxFrameLength feature exists on the Ethernet module. PLIB_ETH_ExistsMIIM_Config Identifies whether the MIIM_Config feature exists on the Ethernet module. PLIB_ETH_ExistsMIIM_Indicators Identifies whether the MIIM_Indicators feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMAddresses Identifies whether the MIIMAddresses feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMReadWrite Identifies whether the MIIMReadWrite feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMScanMode Identifies whether the MIIMScanMode feature exists on the Ethernet module. PLIB_ETH_ExistsMIIWriteReadData Identifies whether the MIIWriteReadData feature exists on the Ethernet module. Peripheral Libraries Help Ethernet Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 917 PLIB_ETH_ExistsPatternMatch Identifies whether the PatternMatch feature exists on the Ethernet module. PLIB_ETH_ExistsPauseTimer Identifies whether the PauseTimer feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveBufferSize Identifies whether the ReceiveBufferSize feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveFilters Identifies whether the ReceiveFilters feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveOverflowCount Identifies whether the ReceiveOverflowCount feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveWmarks Identifies whether the ReceiveWmarks feature exists on the Ethernet module. PLIB_ETH_ExistsRetransmissionMaximum Identifies whether the RetransmissionMaximum feature exists on the Ethernet module. PLIB_ETH_ExistsRMII_Support Identifies whether the RMII_Support feature exists on the Ethernet module. PLIB_ETH_ExistsRxBufferCountDecrement Identifies whether the RxBufferCountDecrement feature exists on the Ethernet module. PLIB_ETH_ExistsRxEnable Identifies whether the ReceiveEnable feature exists on the Ethernet module. PLIB_ETH_ExistsRxPacketDescriptorAddress Identifies whether the RxPacketDescriptorAddress feature exists on the Ethernet module. PLIB_ETH_ExistsStationAddress Identifies whether the StationAddress feature exists on the Ethernet module. PLIB_ETH_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the Ethernet module. PLIB_ETH_ExistsTransmitRTS Identifies whether the TransmitRTS feature exists on the Ethernet module. PLIB_ETH_ExistsTxPacketDescriptorAddress Identifies whether the TxPacketDescriptorAddress feature exists on the Ethernet module. PLIB_ETH_FCSErrorCountClear Sets the value of the Ethernet frame check sequence error to zero. PLIB_ETH_FCSErrorCountGet Gets the count of the frame check sequence error. PLIB_ETH_FrameLengthCheckDisable Disables the EMAC frame length check. PLIB_ETH_FrameLengthCheckEnable Enables the EMAC frame length check. PLIB_ETH_FrameLengthCheckIsEnabled Gets the EMAC frame length check status. PLIB_ETH_FramesRxdOkCountClear Sets the value of the Ethernet received frames 'OK' count to zero. PLIB_ETH_FramesRxdOkCountGet Gets the count of the frames frames received successfully. PLIB_ETH_FramesTxdOkCountClear Sets the count of Ethernet Control frames transmitted to zero. PLIB_ETH_FramesTxdOkCountGet Gets the count of Ethernet Control Frames transmitted successfully. PLIB_ETH_FullDuplexDisable Disables the EMAC full duplex operation. PLIB_ETH_FullDuplexEnable Enables the EMAC full duplex operation. PLIB_ETH_FullDuplexIsEnabled Gets the EMAC full duplex enable status. PLIB_ETH_HashTableGet Gets the value of the Hash table. PLIB_ETH_HashTableSet Sets the Ethernet module Hash table with the new value. PLIB_ETH_HugeFrameDisable Disables the EMAC from receiving huge frames. PLIB_ETH_HugeFrameEnable Enables the EMAC to receive huge frames. PLIB_ETH_HugeFrameIsEnabled Gets the EMAC huge frame enable status. PLIB_ETH_InterruptClear Clears the Ethernet module interrupt source status as a group, using a mask. PLIB_ETH_InterruptSet Sets the Ethernet module interrupt source status as a group, using a mask. PLIB_ETH_InterruptsGet Gets the Ethernet module Interrupt Flag register as a group. PLIB_ETH_InterruptSourceDisable Clears the Ethernet module Interrupt Enable register as a group, using a mask. PLIB_ETH_InterruptSourceEnable Sets the Ethernet module Interrupt Enable register in a group, using a mask. PLIB_ETH_InterruptSourceIsEnabled Gets the Ethernet module Interrupt Enable register singularly or as a group. PLIB_ETH_InterruptSourcesGet Returns the entire interrupt enable register. PLIB_ETH_InterruptStatusGet Gets the Ethernet module Interrupt Flag register as a group, using a mask. PLIB_ETH_IsEnabled Gets the Ethernet module enable status. PLIB_ETH_LinkHasFailed Gets the MII management link fail status. PLIB_ETH_LongPreambleDisable Disables EMAC long preamble enforcement. PLIB_ETH_LongPreambleEnable Enables EMAC long preamble enforcement. PLIB_ETH_LongPreambleIsEnabled Gets the EMAC long preamble enforcement enable status. PLIB_ETH_LoopbackDisable Disables the EMAC loopback logic. PLIB_ETH_LoopbackEnable Enables the EMAC loopback logic. PLIB_ETH_LoopbackIsEnabled Gets the EMAC Loopback interface enable status. PLIB_ETH_ManualFlowControlDisable Disable Ethernet module Manual Flow Control logic. PLIB_ETH_ManualFlowControlEnable Enables the Ethernet Manual Flow Control logic. PLIB_ETH_ManualFlowControlIsEnabled Gets the Ethernet module Manual Flow Control enable status. PLIB_ETH_MaxFrameLengthGet Gets the EMAC maximum frame length. Peripheral Libraries Help Ethernet Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 918 PLIB_ETH_MaxFrameLengthSet Sets the EMAC maximum frame length. PLIB_ETH_MCSRxResetDisable Disables the reset EMAC Control Sub-layer/Receive domain logic. PLIB_ETH_MCSRxResetEnable Enables the reset EMAC Control Sub-layer/Receive domain logic. PLIB_ETH_MCSRxResetIsEnabled Gets the EMAC Control Sub-layer/Receive domain logic reset status. PLIB_ETH_MCSTxResetDisable Disables the reset EMAC Control Sub-layer/Transmit domain logic. PLIB_ETH_MCSTxResetEnable Enables the reset of EMAC Control Sub-layer/Transmit domain logic. PLIB_ETH_MCSTxResetIsEnabled Gets the EMAC Control Sub-layer/Transmit domain logic reset status. PLIB_ETH_MIIMClockGet Gets the current EMAC MIIM clock selection. PLIB_ETH_MIIMClockSet Sets the EMAC MIM clock selection. PLIB_ETH_MIIMIsBusy Gets the MII management busy status. PLIB_ETH_MIIMIsScanning Gets the MII Management scanning status. PLIB_ETH_MIIMNoPreDisable Disables EMAC No Preamble (allows preamble). PLIB_ETH_MIIMNoPreEnable Enables EMAC MIIM No Preamble (suppresses preamble). PLIB_ETH_MIIMNoPreIsEnabled Gets the EMAC MIIM No Preamble enable status. PLIB_ETH_MIIMReadDataGet Gets EMAC MIIM management read data after a MII read cycle has completed. PLIB_ETH_MIIMReadStart Initiates an MII management read command. PLIB_ETH_MIIMResetDisable Disables EMAC Reset MII Management. PLIB_ETH_MIIMResetEnable Enables EMAC Reset Media Independent Interface (MII) Management. PLIB_ETH_MIIMResetIsEnabled Gets the EMAC Reset MII Management enable status. PLIB_ETH_MIIMScanIncrDisable Disables the EMAC MIIM Scan Increment. PLIB_ETH_MIIMScanIncrEnable Enables EMAC MIIM Scan Increment. PLIB_ETH_MIIMScanIncrIsEnabled Gets the EMAC MIIM scan increment enable status. PLIB_ETH_MIIMScanModeDisable Disables MIIM scan mode. PLIB_ETH_MIIMScanModeEnable Enables MIIM scan mode. PLIB_ETH_MIIMScanModeIsEnabled Gets the MII management scan enable status. PLIB_ETH_MIIMWriteDataSet Sets the EMAC MIIM write data before initiating an MII write cycle. PLIB_ETH_MIIMWriteStart Initiates an MII management write command. PLIB_ETH_MIIResetDisable Disables the EMAC Soft reset. PLIB_ETH_MIIResetEnable Enables the EMAC MIIM Soft reset. PLIB_ETH_MIIResetIsEnabled Gets EMAC MIIM Soft Reset enable status. PLIB_ETH_MultipleCollisionCountClear Sets the value of the Ethernet multiple collision frame count to zero. PLIB_ETH_MultipleCollisionCountGet Gets the count of the frames transmitted successfully after there was more than one collision. PLIB_ETH_NoBackoffDisable Disables EMAC no back-offs. PLIB_ETH_NoBackoffEnable Enables EMAC no back-off. PLIB_ETH_NoBackoffIsEnabled Gets the EMAC no back-off enable status. PLIB_ETH_NonBackToBackIPG1Get Gets the EMAC non-back-to-back interpacket gap register 1. PLIB_ETH_NonBackToBackIPG1Set Sets the EMAC non-back-to-back interpacket gap register 1. PLIB_ETH_NonBackToBackIPG2Get Gets the EMAC non-back-to-back interpacket gap register 2. PLIB_ETH_NonBackToBackIPG2Set Sets the EMAC non-back-to-back interpacket gap register 2. PLIB_ETH_PassAllDisable Disables the EMAC PassAll. PLIB_ETH_PassAllEnable Enables the EMAC PassAll. PLIB_ETH_PassAllIsEnabled Gets the EMAC PassAll enable status. PLIB_ETH_PatternMatchChecksumGet Gets the value of the pattern match checksum register. PLIB_ETH_PatternMatchChecksumSet Sets the Ethernet module pattern match checksum register with the new value. PLIB_ETH_PatternMatchGet Gets the value of the selected pattern match mask register. PLIB_ETH_PatternMatchModeGet Gets the value of the selected pattern match mask register. PLIB_ETH_PatternMatchModeSet Sets the Ethernet module pattern match mode. PLIB_ETH_PatternMatchOffsetGet Gets the value of the patter match offset register. PLIB_ETH_PatternMatchOffsetSet Sets the Ethernet module patter match offset register with the new value. PLIB_ETH_PatternMatchSet Sets the Ethernet module pattern match mask register with the new value. PLIB_ETH_PauseTimerGet Gets the Pause Timer value used for flow control. PLIB_ETH_PauseTimerSet Sets the Pause Timer value used for flow control. PLIB_ETH_PHYAddressGet Gets the EMAC MIIM management PHY address. PLIB_ETH_PHYAddressSet Sets the EMAC MIIM PHY address. Peripheral Libraries Help Ethernet Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 919 PLIB_ETH_PurePreambleDisable Disables EMAC pure preamble enforcement. PLIB_ETH_PurePreambleEnable Enables EMAC pure preamble enforcement. PLIB_ETH_PurePreambleIsEnabled Gets EMAC pure preamble enforcement enable status. PLIB_ETH_ReceiveBufferSizeGet Gets the Ethernet module receive buffer size. PLIB_ETH_ReceiveBufferSizeSet Sets the Ethernet module receive buffer size. PLIB_ETH_ReceiveDisable Disables the EMAC from receiving frames. PLIB_ETH_ReceiveEnable Enables the EMAC to receive the frames. PLIB_ETH_ReceiveFilterDisable Disables the specified receive filter. PLIB_ETH_ReceiveFilterEnable Enables the specified receive filter. PLIB_ETH_ReceiveFilterIsEnable Disables the specified receive filter. PLIB_ETH_ReceiveIsBusy Gets the Ethernet receive logic busy status. PLIB_ETH_ReceiveIsEnabled Gets the Ethernet EMAC receive enable status. PLIB_ETH_RegisterAddressGet Gets the EMAC MIIM management register address. PLIB_ETH_RegisterAddressSet Sets EMAC MIIM register address. PLIB_ETH_ReTxMaxGet Gets the EMAC maximum retransmissions. PLIB_ETH_ReTxMaxSet Sets the EMAC maximum retransmissions. PLIB_ETH_RMIIResetDisable Disables EMAC Reset RMII. PLIB_ETH_RMIIResetEnable Enables EMAC Reset RMII. PLIB_ETH_RMIIResetIsEnabled Gets the EMAC Reset RMII enable status. PLIB_ETH_RMIISpeedGet Gets the current EMAC RMII speed. PLIB_ETH_RMIISpeedSet Sets EMAC RMII Speed. PLIB_ETH_RxBufferCountDecrement Causes the Receive Descriptor Buffer Counter to decrement by 1. PLIB_ETH_RxDisable Disables the Ethernet module receive logic. PLIB_ETH_RxEmptyWmarkGet Gets the Ethernet module receive empty watermark. PLIB_ETH_RxEmptyWmarkSet Sets the Ethernet module receive empty water mark. PLIB_ETH_RxEnable Enables the Ethernet receive logic. PLIB_ETH_RxFullWmarkGet Gets the Ethernet module to receive a full watermark. PLIB_ETH_RxFullWmarkSet Sets the Ethernet module to receive a full watermark. PLIB_ETH_RxFuncResetDisable Disables the EMAC reset receive function logic. PLIB_ETH_RxFuncResetEnable Enables the EMAC reset receive function logic. PLIB_ETH_RxFuncResetIsEnabled Gets the EMAC reset receive function status. PLIB_ETH_RxIsEnabled Gets the Ethernet module receive enable status. PLIB_ETH_RxOverflowCountClear Sets the value of the Ethernet receive overflow count to zero. PLIB_ETH_RxOverflowCountGet Gets the count of the dropped Ethernet receive frames. PLIB_ETH_RxPacketCountGet Gets the value of the receive packet buffer count. PLIB_ETH_RxPacketDescAddrGet Gets the address of the next receive descriptor. PLIB_ETH_RxPacketDescAddrSet Sets the Ethernet module receive packet descriptor start address. PLIB_ETH_RxPauseDisable Disables the EMAC receive flow control. PLIB_ETH_RxPauseEnable Enables the EMAC receive flow control. PLIB_ETH_RxPauseIsEnabled Gets the EMAC receive flow pause enable status. PLIB_ETH_ShortcutQuantaDisable Disables EMAC shortcut pause quanta. PLIB_ETH_ShortcutQuantaEnable Enables EMAC shortcut pause quanta. PLIB_ETH_ShortcutQuantaIsEnabled Gets EMAC shortcut pause quanta enable status. PLIB_ETH_SimResetDisable Disables the EMAC simulation reset. PLIB_ETH_SimResetEnable Enables the EMAC simulation reset. PLIB_ETH_SimResetIsEnabled Gets the EMAC simulation reset status. PLIB_ETH_SingleCollisionCountClear Sets the value of the Ethernet single collision frame count to zero. PLIB_ETH_SingleCollisionCountGet Gets the count of the frames transmitted successfully on a second attempt. PLIB_ETH_StationAddressGet Gets the selected EMAC station address. PLIB_ETH_StationAddressSet Sets the selected EMAC Station Address. PLIB_ETH_StopInIdleDisable Ethernet module operation will continue when the device enters Idle mode. PLIB_ETH_StopInIdleEnable Ethernet module operation will stop when the device enters Idle mode. PLIB_ETH_StopInIdleIsEnabled Gets the Ethernet module Stop in Idle mode enable status. PLIB_ETH_TestBackPressDisable Disables EMAC Test backpressure. PLIB_ETH_TestBackPressEnable Enables EMAC Test backpressure. Peripheral Libraries Help Ethernet Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 920 PLIB_ETH_TestBackPressIsEnabled Gets the EMAC test backpressure enable status. PLIB_ETH_TestPauseDisable Disables EMAC test pause. PLIB_ETH_TestPauseEnable Enables EMAC test pause. PLIB_ETH_TestPauseIsEnabled Gets the EMAC test pause enable status. PLIB_ETH_TransmitIsBusy Gets the status value of the Ethernet transmit logic busy status PLIB_ETH_TxFuncResetDisable Disables the EMAC Transmit function reset. PLIB_ETH_TxFuncResetEnable Enables the EMAC transmit function reset. PLIB_ETH_TxFuncResetIsEnabled Gets the EMAC Transmit function reset status. PLIB_ETH_TxPacketDescAddrGet Gets the address of the next descriptor to be transmitted. PLIB_ETH_TxPacketDescAddrSet Sets the Ethernet module transmit packet descriptor start address. PLIB_ETH_TxPauseDisable Disables the transmission of Pause frames. PLIB_ETH_TxPauseEnable Enables the transmission Pause frames. PLIB_ETH_TxPauseIsEnabled Gets the Ethernet module enable status. PLIB_ETH_TxRTSDisable Aborts an Ethernet module transmission. PLIB_ETH_TxRTSEnable Enables the Ethernet transmit request to send. PLIB_ETH_TxRTSIsEnabled Gets the Ethernet module transmit request to send status. Description Ethernet Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Ethernet Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Ethernet module. File Name plib_eth.h Company Microchip Technology Inc. Peripheral Libraries Help Ethernet Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 921 GLCD Controller Peripheral Library This section describes the GLCD Controller (GLCD Controller) Peripheral Library. Introduction This library provides a low-level abstraction of the GLCD Controller Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by abstracting differences from one microcontroller variant to another. Description The primary function of the Graphics LCD (GLCD) controller is to directly interface with display glasses and to control pixels on a screen. The GLCD controller transfers display data from a memory device and formats it for a display device. It also provides accelerated on-the-fly rendering of vertical and horizontal lines, rectangles, and copying of a rectangular area between different locations on the screen. After initialization, the GLCD controller will perform rendering through DMA, thereby off-loading the CPU. The GLCD controller can support three rendering layers. Each layer supports the configurable stride and alpha blending feature. Each layer supports different input pixel formats such as RGBA8888, ARGB8888, RGB888, RGB565, RGBA5551, YUYV, RGB232, LUT8 and grayscale. These layers can be combined together into a single layer with a configurable output format. The output format can be RGB888, RGB666, RGB323, YUYV, Serial 3-beat (RGB), Serial 4-beat (RGBA), Two-phase 12-bit mode, and BT656. For the LUT8 input format, the Look-up Table (LUT) resides within the device and is configurable. The device supports a programmable cursor and the cursor data can be set in the device memory. The polarity of signals HSYNC, VSYNC, DE, and PCLK is configurable. Using the Library This topic describes the basic architecture of the GLCD Controller Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_glcd.h The interface to the GLCD Controller Peripheral Library is defined in the plib_glcd.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the GLCD Controller Peripheral Library must include peripheral.h. Library File: The GLCD Controller Peripheral Library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the GLCD Controller module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description The GLCD Peripheral Library software is depicted by the following block diagram: GLCD Controller Software Abstraction Block Diagram Peripheral Libraries Help GLCD Controller Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 922 Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Deadman Timer module. Library Interface Section Description General Configuration Functions Functions that enable/disable the GLCD and set the RGB Sequential mode. Display Signal Polarity and Timing Management Functions Functions that handles polarity and timing of display signals such as VSYNC, HSYNC, DE, and PCLK. Background Management Functions Functions that handle setting the background color. Layer Management Functions that manage layer configuration and overlay. Hardware Cursor Control and Management Functions Functions that handle cursor data settings and cursor drawing position control. Palette and Gamma Correction Control Functions Functions that control hardware color palette/gamma table data settings. Interrupt Control Functions Functions that control device interrupt settings. Miscellaneous Control Functions Functions that control miscellaneous GLCD features. Feature Existence Functions Functions that determine existence of certain features. How the Library Works This section provides information on how the GLCD Controller Peripheral Library works. General Configuration Provides general configuration information. Description General configuration of the GLCD Controller includes enabling and disabling the GLCD module globally. Enable/Disable GLCD Enabling and disabling the GLCD are the basic routines that may be called during initialization and exit routines of the application. Example: // Enable the GLCD controller PLIB_GLCD_Enable ( GLCD_ID_0 ); // Disable the GLCD PLIB_GLCD_Disable ( GLCD_ID_0 ); // Check the enable status of the GLCD controller. Peripheral Libraries Help GLCD Controller Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 923 if(PLIB_GLCD_IsEnabled( GLCD_ID_0 )) { // application code } GLCD RGB Sequential Mode Set The GLCD RGB Sequential mode controls the GLCD output pins. The function used to set the RGB sequential mode is PLIB_GLCD_RGBSequentialModeSet. This basic function may be called during initialization and exit routines of the application. Display Signal Polarity and Timing Management Provides information on display signal polarity. Description A GLCD controller peripheral is connected the display using the following pins: HSYNC, VSYNC, GCLK, GEN and GD<23:0>. The HSYNC, VSYNC, GCLK and GEN polarity can be set using the PLIB_GLCD_SignalPolaritySet function. The signal polarity can be either positive or negative based on the display requirements. The GLCD source clock and pixel clock frequency can be controlled using the PLIB_GLCD_FormattingClockDivideEnable and PLIB_GLCD_ClockDividerSet functions. The timing of the signals, HSYNC, VSYNC, and GEN, is based on the display requirements and can be programmed to suit different display resolutions. The functions used to modify the HSYNC, VSYNC and GEN timing parameters are PLIB_GLCD_ResolutionXYSet, PLIB_GLCD_BlankingXYSet PLIB_GLCD_FrontPorchXYSet, and PLIB_GLCD_BackPorchXYSet. Display Background Management Provides information on display background management. Description The GLCD Controller supports three layers and a background layer. A background layer is a basic layer that can be filled with one color of format RGBA8888 using the PLIB_GLCD_BackgroundColorSet function. The other layers will be applied on top of the background layer with a requested blending mode. Peripheral Libraries Help GLCD Controller Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 924 Layer Management Provides information on layer management. Description The GLCD Controller supports three drawing layers. Each layer can be enabled or disabled using the PLIB_GLCD_LayerEnable or PLIB_GLCD_LayerDisable functions, respectively. Each layer’s start location, start (x, y), can be set using the PLIB_GLCD_LayerStartXYSet function and the size, size(x, y), can be set using the PLIB_GLCD_LayerSizeXYSet function. Layer resolution and stride can be set using the PLIB_GLCD_LayerResXYSet and PLIB_GLCD_LayerStrideSet functions, respectively. A bi-linear filter can be applied to each layer using the PLIB_GLCD_LayerBilinearFilterEnable function. Each layer supports different color formats and the color format can be set using the PLIB_GLCD_LayerColorModeSet function. Each Layer can have a different global alpha value, which can be set using the PLIB_GLCD_LayerGlobalAlphaSet function. Each Layer alpha can be premultiplied by global alpha using the PLIB_GLCD_LayerPreMultiplyImageAlphaEnable function; otherwise, the PLIB_GLCD_LayerPreMultiplyImageAlphaDisable function is used. To force global alpha value as the layer alpha the PLIB_GLCD_LayerForceWithGlobalAlphaEnable function is called; otherwise, the PLIB_GLCD_LayerForceWithGlobalAlphaDisble function is called. The next layer is overlayed on a previous layer. Two layers can be blended based on source and destination layer blending functions. The source and destination blending functions can be set using the PLIB_GLCD_LayerSrcBlendFuncSet and PLIB_GLCD_LayerDestBlendFuncSet functions, respectively. The layer overlay and blending is not restricted by the layer color format. Two layers with a different color format can be blended together. Peripheral Libraries Help GLCD Controller Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 925 With the exception of the background layer, the other three layers have no memory space allocated on its own into GLCD device. The application must allocate GLCD accessible memory into the controller RAM and pass the address of the allocated memory to the GLCD. The address of the allocated memory for the layer can be set into the GLCD using the PLIB_GLCD_LayerBaseAddressSet function. Hardware Cursor Control and Management Provides information on hardware cursor control and management. Description The GLCD Controller supports a fully programmable 32 x 32 16-color hardware cursor. The cursor can be enabled or disabled using the PLIB_GLCD_CursorEnable or PLIB_GLCD_CursorDisbale functions, respectively. The position of the cursor is set using the PLIB_GLCD_CursorXYSet function. Each pixel value of the cursor bitmap is represented by 4 bits. The first 32-bit word contains 8 pixels of the cursor bitmap data starting from pixel position (0, 7) to pixel (0, 0). The remainder of the cursor bitmap data continues similarly to the first 32-bit word. The complete cursor bitmap data is represented by 128 x 32 bit words. This cursor data is set using the PLIB_GLCD_CursorDataSet function. The 4-bit value representing the pixel in the cursor bitmap data is used as the index of the cursor Color Look-up Table (CLUT). The cursor CLUT is set using the PLIB_GLCD_CursorLUTSet function. The color format of the cursor CLUT is XRGB, where 'X' = unimplemented. The size of cursor CLUT is 16 colors. Palette and Gamma Correction Control Provides information on palette/gamma correction control. Description For a layer with a source format set to 8-bit color palette look-up table (LUT8), the global CLUT can be set in the GLCD using the PLIB_GLCD_GlobalColorLUTSet function. The format of each color in the CLUT is XRGB8888, where 'X' = unimplemented. The size of the CLUT is 256 colors. The same global CLUT is used to map RGB values to new RGB values for the purpose of gamma correction. The PLIB_GLCD_PaletteGammaRampEnable or PLIB_GLCD_PaletteGammaRampDisable function can be used to enable or disable the Palette/Gamma correction feature. Interrupt Control Provides information interrupt control Description The GLCD Controller can trigger an interrupt on HSYNC and VSYNC. To enable or disable interrupt on HSYNC the PLIB_GLCD_HSyncInterruptEnable or PLIB_GLCD_HSyncInterruptDisable functions is used, respectively. To enable or disable interrupt on VSYNC the PLIB_GLCD_VSyncInterruptEnable or PLIB_GLCD_VSyncInterruptDisable function is used, respectively. The interrupt trigger can be set to either level or edge triggered using the PLIB_GLCD_IRQTriggerControlSet function. Miscellaneous Control Provides information on miscellaneous control features. Peripheral Libraries Help GLCD Controller Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 926 Description The other GLCD feature controls that were not covered in the previous sections are: dithering, VSYNC for single cycle per line, force output blank, and YUV output. The dithering feature can be enabled or disabled using the PLIB_GLCD_DitheringEnable or PLIB_GLCD_DitheringDisable functions, respectively. VSYNC for single cycle per line is enabled or disabled using the PLIB_GLCD_SingleCyclePerLineVsyncEnable or PLIB_GLCD_SingleCyclePerLineVsyncDisable functions, respectively. The forcing of GLCD output to blank is enabled or disabled using the PLIB_GLCD_ForceOutputBlankEnable or PLIB_GLCD_ForceOutputBlankDisable functions, respectively. If the GLCD RGB Sequential mode is set to YUYU or BT656 format, the function, PLIB_GLCD_YUVOutputEnable, must be called; otherwise, the PLIB_GLCD_YUVOutputDisable function must be called. The GLCD Peripheral Library also provides access to various GLCD status flags. To verify if the last row is currently displayed, the function, PLIB_GLCD_IsLastRowm is called. To determine the signal level of DE, HSYNC and VSYNC, the functions, PLIB_GLCD_DESignalLevelGet, PLIB_GLCD_HSyncSignalLevelGet, and PLIB_GLCD_VSyncSignalLevelGet are called, respectively. To know whether GLCD is in active vertical blanking state the PLIB_GLCD_IsVerticalBlankingActive function is called. Configuring the Library The library is configured for the supported GLCD Controller module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Configuration Functions Name Description PLIB_GLCD_Disable Disables the Graphics LCD Controller. PLIB_GLCD_Enable Enables the Graphics LCD Controller. PLIB_GLCD_RGBSequentialModeSet Sets the RGB output sequential mode. b) Display Signal Polarity and Timing Management Functions Name Description PLIB_GLCD_SignalPolarityGet Gets the polarity of the pixel clock, DE, HSync and VSync pin of the Graphics LCD Controller. PLIB_GLCD_SignalPolaritySet Sets the polarity of the pixel clock, DE, HSync and VSync pin of the Graphics LCD Controller. PLIB_GLCD_BackPorchXGet Gets X Axis Back Porch. PLIB_GLCD_BackPorchXYSet Sets the back porch on the x and y axis for the Graphics LCD Controller. PLIB_GLCD_BackPorchYGet Gets Y Axis Back Porch. PLIB_GLCD_BlankingXYSet Sets the blanking period on the x and y axis of the Graphics LCD Controller. PLIB_GLCD_FormattingClockDivideDisable Disbale the Clock Formatting feature. PLIB_GLCD_FormattingClockDivideEnable Enable the Clock Formatting feature. PLIB_GLCD_FormattingClockDivideIsEnabled Verify whether Clock Formatting feature is enabled. PLIB_GLCD_FrontPorchXGet Gets X Axis Front Porch. PLIB_GLCD_FrontPorchXYSet Sets the front porch on the x and y axis for the Graphics LCD Controller. PLIB_GLCD_FrontPorchYGet Gets Y Axis Front Porch. PLIB_GLCD_LinesPrefetchGet Gets value of lines to be prefetched. PLIB_GLCD_ResolutionXGet Gets X Axis Resolution. PLIB_GLCD_ResolutionYGet Gets Y Axis Resolution. PLIB_GLCD_BlankingXGet Gets the X Axis Blanking Period. PLIB_GLCD_BlankingYGet Gets the Y Axis Blanking Period. PLIB_GLCD_LinesPrefetchSet Sets the clock controls of the Graphics LCD Controller. PLIB_GLCD_ClockDividerSet Sets clock controls of the Graphics LCD Controller. PLIB_GLCD_ClockDividerGet Gets Clock Divider value. PLIB_GLCD_ResolutionXYSet Sets the display resolution for the Graphics LCD Controller. c) Background Management Functions Name Description PLIB_GLCD_BackgroundColorGet Gets the value of the Background Color. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 927 PLIB_GLCD_BackgroundColorSet Sets the background color. d) Layer Management Functions Name Description PLIB_GLCD_LayerBaseAddressGet Gets the Layer Base Address. PLIB_GLCD_LayerBaseAddressSet Sets the base address of layer surface of the Graphics LCD Controller. PLIB_GLCD_LayerBilinearFilterDisable Disables the layer Bilinear filter of the Graphics LCD Controller. PLIB_GLCD_LayerBilinearFilterEnable Enables the layer Bilinear filter of the Graphics LCD Controller. PLIB_GLCD_LayerBilinearFilterIsEnabled Verify whether Layer Bilinear Filter is enabled. PLIB_GLCD_LayerColorModeGet Gets the Layer Color Mode. PLIB_GLCD_LayerColorModeSet Sets the layer color mode of the Graphics LCD Controller. PLIB_GLCD_LayerDestBlendFuncGet Gets the Layer Destination Blend Function. PLIB_GLCD_LayerDestBlendFuncSet Sets the layer destination blend function of the Graphics LCD Controller. PLIB_GLCD_LayerDisable Disables the layer of the Graphics LCD Controller. PLIB_GLCD_LayerEnable Enables the layer of the Graphics LCD Controller. PLIB_GLCD_LayerForceWithGlobalAlphaDisable Disables the Layer Force Global Alpha feature. PLIB_GLCD_LayerForceWithGlobalAlphaEnable Enable the Layer Force Global Alpha feature. PLIB_GLCD_LayerForceWithGlobalAlphaIsEnabled Verify whether Layer Force with Global Alpha Feature is enabled. PLIB_GLCD_LayerGlobalAlphaGet Gets the Layer Global Alpha value. PLIB_GLCD_LayerGlobalAlphaSet Sets the layer global alpha of the Graphics LCD Controller. PLIB_GLCD_LayerIsEnabled Verify whether Layer is enabled. PLIB_GLCD_LayerPreMultiplyImageAlphaDisable Disable Layer Pre-Multiply Image Alpha Feature. PLIB_GLCD_LayerPreMultiplyImageAlphaEnable Enable Layer Pre-Multiply Image Alpha Feature. PLIB_GLCD_LayerPreMultiplyImageAlphaIsEnabled Verify whether the Layer Pre-Multiply Image Alpha Feature is enabled. PLIB_GLCD_LayerResXGet Gets the Layer X Axis Resolution. PLIB_GLCD_LayerResXYSet Sets the layer resolution in pixels. PLIB_GLCD_LayerResYGet Gets the Layer Y Axis Resolution. PLIB_GLCD_LayerSizeXGet Gets the Layer X Axis Size. PLIB_GLCD_LayerSizeXYSet Sets the layer size x and size y of the Graphics LCD Controller. PLIB_GLCD_LayerSizeYGet Gets the Layer Y Axis Size. PLIB_GLCD_LayerSrcBlendFuncGet Gets the Layer Source Blend Function. PLIB_GLCD_LayerSrcBlendFuncSet Sets the layer source blend function of the Graphics LCD Controller. PLIB_GLCD_LayerStartXGet Gets the Layer X Axis Start Position. PLIB_GLCD_LayerStartXYSet Sets the layer start x and start y of the Graphics LCD Controller. PLIB_GLCD_LayerStartYGet Gets the Layer Y Axis Start Position. PLIB_GLCD_LayerStrideGet Gets the Layer Stride value. PLIB_GLCD_LayerStrideSet Sets the layer surface stride of the Graphics LCD Controller. e) Hardware Cursor Control and Management Functions Name Description PLIB_GLCD_CursorDataGet Gets the Cursor Data at given Index. PLIB_GLCD_CursorDataSet Sets the cursor image data. PLIB_GLCD_CursorDisable Disables the cursor of the Graphics LCD Controller. PLIB_GLCD_CursorEnable Enables the cursor of the Graphics LCD Controller. PLIB_GLCD_CursorIsEnabled Verifies whether the cursor is enabled. PLIB_GLCD_CursorLUTGet Gets the color from Cursor LUT at given Index. PLIB_GLCD_CursorLUTSet Sets the cursor color look-up table (LUT) in XRGB8888 format. PLIB_GLCD_CursorXGet Gets the cursor X Axis Position. PLIB_GLCD_CursorXYSet Sets the x and y coordinates of the Graphics LCD Controller cursor. PLIB_GLCD_CursorYGet Gets the Cursor Y Axis Position. f) Palette and Gamma Correction Control Functions Name Description PLIB_GLCD_GlobalColorLUTGet Gets the Color from Global Color LUT at given Index. PLIB_GLCD_GlobalColorLUTSet Set Global Color LUT. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 928 PLIB_GLCD_PaletteGammaRampDisable Disables the palette / gamma ramp of the Graphics LCD Controller. PLIB_GLCD_PaletteGammaRampEnable Enables the palette / gamma ramp of the Graphics LCD Controller. PLIB_GLCD_PaletteGammaRampIsEnabled Verify whether Palette / Gamma Ramp feature is enabled. g) Interrupt Control Functions Name Description PLIB_GLCD_HSyncInterruptDisable Disables interrupts at Hsync. PLIB_GLCD_HSyncInterruptEnable Enables interrupts at Hsync. PLIB_GLCD_HSyncInterruptIsEnabled Verify whether HSYNC Interrupt is enabled. PLIB_GLCD_HSyncSignalLevelGet Gets the Hsync signal level. PLIB_GLCD_IRQTriggerControlGet Gets the IRQ Trigger Control value. PLIB_GLCD_IRQTriggerControlSet Sets the IRQ trigger control. PLIB_GLCD_VSyncInterruptDisable Disables interrupts at Vsync. PLIB_GLCD_VSyncInterruptEnable Enables interrupts at Vsync. PLIB_GLCD_VSyncInterruptIsEnabled Verify whether VSYNC Interrupt is enabled. PLIB_GLCD_VSyncSignalLevelGet Gets the Vsync signal level. h) Miscellaneous Control Functions Name Description PLIB_GLCD_DitheringDisable Disables the Dithering feature of the Graphics LCD Controller. PLIB_GLCD_DitheringEnable Enables the Dithering feature of the Graphics LCD Controller. PLIB_GLCD_ForceOutputBlankDisable Disable Force Output Blank feature. PLIB_GLCD_ForceOutputBlankEnable Enable Force Output Blank feature. PLIB_GLCD_SingleCyclePerLineVsyncDisable Clears VSYNC on single cycle per line. PLIB_GLCD_SingleCyclePerLineVsyncEnable Sets VSYNC on single cycle per line. PLIB_GLCD_SingleCyclePerLineVsyncIsEnabled Verify whether VSYNC on Single Cycle Per Line feature is enabled. PLIB_GLCD_YUVOutputDisable Disables the output of the Graphics LCD Controller in YUV format. PLIB_GLCD_YUVOutputEnable Enables the output of the Graphics LCD Controller in YUV format. PLIB_GLCD_DESignalLevelGet Gets the display enable signal level. PLIB_GLCD_DitheringIsEnabled Verifies whether Dithering is enabled. PLIB_GLCD_ForceOutputBlankIsEnabled Verify whether the Force Output Blank feature is enabled. PLIB_GLCD_IsEnabled Verifies whether the Graphics LCD Controller is Enabled. PLIB_GLCD_IsLastRow Gets the status indicating whether a last row is currently displayed by the Graphics Display Controller. PLIB_GLCD_IsVerticalBlankingActive Get the active status. PLIB_GLCD_RGBSequentialModeGet Get the RGB Sequential Mode already set. PLIB_GLCD_YUVOutputIsEnabled Verify whether the YUV Output feature is enabled. i) Feature Existence Functions Name Description PLIB_GLCD_ExistsBackgroundColor Verify whether the Background Color Feature is supported. PLIB_GLCD_ExistsBackPorchXY Verify whether Back Porch Feature is supported. PLIB_GLCD_ExistsBlankingXY Verify whether Blanking Period Feature is supported. PLIB_GLCD_ExistsClockDivider Verify whether the Clock Divider feature is supported. PLIB_GLCD_ExistsCursor Verifies whether the cursor feature exists. PLIB_GLCD_ExistsCursorData PLIB_GLCD_ExistsCursorLUT Verify whether Cursor LUT feature is supported. PLIB_GLCD_ExistsCursorXY Verify whether Cursor XY Position feature is supported. PLIB_GLCD_ExistsDESignalLevel Verify whether DE Signal Level feature is supported. PLIB_GLCD_ExistsDithering Verifies whether the Dithering feature exists. PLIB_GLCD_ExistsEnable Identifies whether the GLCD Enable feature exists on the GLCD module. PLIB_GLCD_ExistsForceOutputBlank Verify whether Force Output Blank feature is supported. PLIB_GLCD_ExistsFormattingClockDivide Verify whether Clock Formatting feature is available. PLIB_GLCD_ExistsFrontPorchXY Verify whether Front Porch Feature is supported. PLIB_GLCD_ExistsGlobalColorLUT Verify whether Global Color LUT feature is supported. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 929 PLIB_GLCD_ExistsHSyncInterruptEnable Verify whether the HSYNC Interrupt Enable feature is supported. PLIB_GLCD_ExistsHSyncSignalLevel Verify whether HSYNC Signal Level feature is supported. PLIB_GLCD_ExistsIRQTriggerControl Verify whether the IRQ Trigger Control feature is supported. PLIB_GLCD_ExistsIsLastRow Verify whether Is Last Row Feature is supported. PLIB_GLCD_ExistsIsVerticalBlankingActive Verify whether Is Vertical Blanking Active feature is supported. PLIB_GLCD_ExistsLayerBaseAddress Verify whether the Layer Base Address feature is supported. PLIB_GLCD_ExistsLayerBilinearFilterEnable Enable Layer Bilinear Filter Feature. PLIB_GLCD_ExistsLayerColorMode Verify whether Layer Color Mode is supported. PLIB_GLCD_ExistsLayerDestBlendFunc Verify whether Layer Destination Blend Function Feature is supported. PLIB_GLCD_ExistsLayerEnable Verify whether Layer Enable Feature is supported. PLIB_GLCD_ExistsLayerForceWithGlobalAlpha Verify whether Layer Force with Global Alpha Feature is supported. PLIB_GLCD_ExistsLayerGlobalAlpha Verify whether Layer Global Alpha Feature is supported. PLIB_GLCD_ExistsLayerPreMultiplyImageAlpha Verify whether Layer Pre-Multiply Image Alpha Feature is supported. PLIB_GLCD_ExistsLayerResXY PLIB_GLCD_ExistsLayerSizeXY Verify whether Layer X Axis and Y Axis Size feature is supported. PLIB_GLCD_ExistsLayerSrcBlendFunc Verify whether Layer Source Blend Function Feature is supported. PLIB_GLCD_ExistsLayerStartXY Verify whether Layer Start XY Position feature is supported. PLIB_GLCD_ExistsLayerStride Verify whether the Layer Stride Feature is supported. PLIB_GLCD_ExistsLinesPrefetch Verify whether Lines Prefetch Set Feature supported. PLIB_GLCD_ExistsPaletteGammaRamp Verifies whether the palette / gamma ramp feature is supported. PLIB_GLCD_ExistsResolutionXY Verify whether YUV Output feature is supported. PLIB_GLCD_ExistsRGBSequentialMode Verify whether RGB Sequential Mode feature is supported. PLIB_GLCD_ExistsSignalPolarity Verifies whether the Signal Polarity Selection feature exists. PLIB_GLCD_ExistsSingleCyclePerLineVsync Verifies whether VSYNC on Single cycle Per Line Feature exists. PLIB_GLCD_ExistsVSyncInterruptEnable Verify whether VSYNC Interrupt Enable feature is supported. PLIB_GLCD_ExistsVSyncSignalLevel Verify whether VSYNC Signal Level feature is supported. PLIB_GLCD_ExistsYUVOutput Verify whether YUV output feature is supported. j) Data Types and Constants Name Description GLCD_IRQ_TRIGGER_CONTROL Possible values of GLCD Interrupt Trigger Mode. GLCD_LAYER_COLOR_MODE Possible values of GLCD color Mode. GLCD_LAYER_DEST_BLEND_FUNC Possible values of GLCD Layer Destination Blend Functions. GLCD_LAYER_ID Possible values of GLCD Layer Ids GLCD_LAYER_SRC_BLEND_FUNC Possible values of GLCD Layer Source Blend Functions. GLCD_MODULE_ID Possible instances of the GLCD module GLCD_RGB_MODE GLCD RGB Sequential Mode GLCD_SIGNAL_POLARITY Polarity values of different output signals. Description This section describes the Application Programming Interface (API) functions of the GLCD Controller Peripheral Library. Refer to each section for a detailed description. a) General Configuration Functions PLIB_GLCD_Disable Function Disables the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_Disable(GLCD_MODULE_ID index); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 930 Returns None. Description This function disables the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_Disable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_Disable( GLCD_MODULE_ID index ) PLIB_GLCD_Enable Function Enables the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_Enable(GLCD_MODULE_ID index); Returns None. Description This function enables the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_Enable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_Enable( GLCD_MODULE_ID index ) PLIB_GLCD_RGBSequentialModeSet Function Sets the RGB output sequential mode. File plib_glcd.h Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 931 C void PLIB_GLCD_RGBSequentialModeSet(GLCD_MODULE_ID index, GLCD_RGB_MODE mode); Returns None. Description This function sets the RGB output sequential mode. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_RGBSequentialModeSet( GLCD_MODULE_ID_0, GLCD_RGB_MODE_PARALLEL ); Parameters Parameters Description index Identifier of the device instance. mode RGB sequential mode defined by GLCD_RGB_MODE. Function void PLIB_GLCD_RGBSequentialModeSet( GLCD_MODULE_ID index, GLCD_RGB_MODE mode ) b) Display Signal Polarity and Timing Management Functions PLIB_GLCD_SignalPolarityGet Function Gets the polarity of the pixel clock, DE, HSync and VSync pin of the Graphics LCD Controller. File plib_glcd.h C GLCD_SIGNAL_POLARITY PLIB_GLCD_SignalPolarityGet(GLCD_MODULE_ID index); Returns None. Description This function gets the polarity of the pixel clock, DE, HSync and VSync pin of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t signalPolarity = GLCD_POLARITY_POSITIVE; signalPolarity = PLIB_GLCD_VSyncPolarityGet( GLCD_MODULE_ID_0 ); if( signalPolarity & GLCD_DE_POLARITY_NEGATIVE ) { // DE Polarity Negative } Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 932 Parameters Parameters Description index Identifier of the device instance. Function GLCD_SIGNAL_POLARITY PLIB_GLCD_SignalPolarityGet( GLCD_MODULE_ID index ) PLIB_GLCD_SignalPolaritySet Function Sets the polarity of the pixel clock, DE, HSync and VSync pin of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_SignalPolaritySet(GLCD_MODULE_ID index, GLCD_SIGNAL_POLARITY polarity); Returns None. Description This function sets the polarity of the pixel clock, DE, HSync and VSync pin of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_SignalPolaritySet( GLCD_MODULE_ID_0, GLCD_POLARITY_POSITIVE | GLCD_DE_POLARITY_NEGATIVE ); Parameters Parameters Description index Identifier of the device instance. polarity Enum variable specifying polarity. Function void PLIB_GLCD_SignalPolaritySet( GLCD_MODULE_ID index, GLCD_SIGNAL_POLARITY polarity ) PLIB_GLCD_BackPorchXGet Function Gets X Axis Back Porch. File plib_glcd.h C uint32_t PLIB_GLCD_BackPorchXGet(GLCD_MODULE_ID index); Returns • value of X Axis Back Porch. Description This function gets X Axis Back Porch. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 933 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t backPorchX; backPorchX = PLIB_GLCD_BackPorchXGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_BackPorchXGet( GLCD_MODULE_ID index ) PLIB_GLCD_BackPorchXYSet Function Sets the back porch on the x and y axis for the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_BackPorchXYSet(GLCD_MODULE_ID index, uint32_t backPorchX, uint32_t backPorchY); Returns None. Description This function sets the back porch on the x and y axis for the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // set back porch as: on x axis: 40 and on y axis: 20 PLIB_GLCD_BackPorchXYSet( GLCD_MODULE_ID_0, 40, 20 ); Parameters Parameters Description index Identifier of the device instance. backPorchX Back porch pulse width on x axis. backPorchY Back porch pulse width on y axis. Function void PLIB_GLCD_BackPorchXYSet( GLCD_MODULE_ID index, uint32_t backPorchX uint32_t backPorchY ) PLIB_GLCD_BackPorchYGet Function Gets Y Axis Back Porch. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 934 File plib_glcd.h C uint32_t PLIB_GLCD_BackPorchYGet(GLCD_MODULE_ID index); Returns • value of Y Axis Back Porch. Description This function gets Y Axis Back Porch. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t backPorchY; backPorchY = PLIB_GLCD_BackPorchYGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_BackPorchYGet( GLCD_MODULE_ID index ) PLIB_GLCD_BlankingXYSet Function Sets the blanking period on the x and y axis of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_BlankingXYSet(GLCD_MODULE_ID index, uint32_t blankingX, uint32_t blankingY); Returns None. Description This function sets the blanking period on the x and y axis of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // Set blanking period: on x axis: 10 and on y axis: 10 PLIB_GLCD_BlankingXY_Set( GLCD_MODULE_ID_0, 10, 10 ); Parameters Parameters Description index Identifier of the device instance. blankingX Blanking period on x axis. blankingY Blanking period on y axis. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 935 Function void PLIB_GLCD_BlankingXYSet( GLCD_MODULE_ID index, uint32_t blankingX uint32_t blankingY ) PLIB_GLCD_FormattingClockDivideDisable Function Disbale the Clock Formatting feature. File plib_glcd.h C void PLIB_GLCD_FormattingClockDivideDisable(GLCD_MODULE_ID index); Returns None. Description This function disbales the Clock Formatting feature. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_FormattingClockDivideDisable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_FormattingClockDivideDisable( GLCD_MODULE_ID index ) PLIB_GLCD_FormattingClockDivideEnable Function Enable the Clock Formatting feature. File plib_glcd.h C void PLIB_GLCD_FormattingClockDivideEnable(GLCD_MODULE_ID index); Returns None. Description This function Enables the Clock Formatting feature. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_FormattingClockDivideEnable( GLCD_MODULE_ID_0 ); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 936 Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_FormattingClockDivideEnable( GLCD_MODULE_ID index ) PLIB_GLCD_FormattingClockDivideIsEnabled Function Verify whether Clock Formatting feature is enabled. File plib_glcd.h C bool PLIB_GLCD_FormattingClockDivideIsEnabled(GLCD_MODULE_ID index); Returns • true - The Clock Formatting feature is enabled. • false - The Clock Formatting feature is disabled. Description This function verifies if the Clock Formatting feature is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_FormattingClockDivideIsEnabled( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_FormattingClockDivideDisable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_FormattingClockDivideIsEnabled( GLCD_MODULE_ID index ) PLIB_GLCD_FrontPorchXGet Function Gets X Axis Front Porch. File plib_glcd.h C uint32_t PLIB_GLCD_FrontPorchXGet(GLCD_MODULE_ID index); Returns • value of X Axis Front Porch. Description This Function gets X Axis Front Porch. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 937 Preconditions None. Example uint32_t porchX; porchX = PLIB_GLCD_FrontPorchXGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_FrontPorchXGet( GLCD_MODULE_ID index ) PLIB_GLCD_FrontPorchXYSet Function Sets the front porch on the x and y axis for the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_FrontPorchXYSet(GLCD_MODULE_ID index, uint32_t frontPorchX, uint32_t frontPorchY); Returns None. Description This function sets the front porch on the x and y axis for the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // set front porch as: on x axis: 40 and on y axis: 20 PLIB_GLCD_FrontPorchXYSet( GLCD_MODULE_ID_0, 40, 20 ); Parameters Parameters Description index Identifier of the device instance. frontPorchX Front porch pulse width on x axis. frontPorchY Front porch pulse width on y axis. Function void PLIB_GLCD_FrontPorchXYSet( GLCD_MODULE_ID index, uint32_t frontPorchX, uint32_t frontPorchY ) PLIB_GLCD_FrontPorchYGet Function Gets Y Axis Front Porch. File plib_glcd.h Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 938 C uint32_t PLIB_GLCD_FrontPorchYGet(GLCD_MODULE_ID index); Returns • value of y axis front porch. Description This function gets Y Axis Front Porch. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t porchY; porchY = PLIB_GLCD_FrontPorchYGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_FrontPorchYGet( GLCD_MODULE_ID index ) PLIB_GLCD_LinesPrefetchGet Function Gets value of lines to be prefetched. File plib_glcd.h C uint32_t PLIB_GLCD_LinesPrefetchGet(GLCD_MODULE_ID index); Returns • value of lines to be prefetched. Description This function gets the value of lines to be prefetched. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t linesPrefetch; linesPrefetch = PLIB_GLCD_LinesPrefetchGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_LinesPrefetchGet( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 939 PLIB_GLCD_ResolutionXGet Function Gets X Axis Resolution. File plib_glcd.h C uint32_t PLIB_GLCD_ResolutionXGet(GLCD_MODULE_ID index); Returns • value of x axis resolution. Description This function gets the X Axis resolution. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t resolutionX; resolutionX = PLIB_GLCD_ResolutionXGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_ResolutionXGet( GLCD_MODULE_ID index ) PLIB_GLCD_ResolutionYGet Function Gets Y Axis Resolution. File plib_glcd.h C uint32_t PLIB_GLCD_ResolutionYGet(GLCD_MODULE_ID index); Returns • Value of Y Axis Resolution. Description This function gets the Y Axis Resolution. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t resolutionY; resolutionY = PLIB_GLCD_ResolutionYGet( GLCD_MODULE_ID_0 ); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 940 Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_ResolutionYGet( GLCD_MODULE_ID index ) PLIB_GLCD_BlankingXGet Function Gets the X Axis Blanking Period. File plib_glcd.h C uint32_t PLIB_GLCD_BlankingXGet(GLCD_MODULE_ID index); Returns • value of X Axis Blanking Period. Description This function gets the X Axis Blanking Period. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t blankingX; blankingX = PLIB_GLCD_BlankingXGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_BlankingXGet( GLCD_MODULE_ID index ) PLIB_GLCD_BlankingYGet Function Gets the Y Axis Blanking Period. File plib_glcd.h C uint32_t PLIB_GLCD_BlankingYGet(GLCD_MODULE_ID index); Returns • value of Y Axis Blanking Period. Description This function gets the Y Axis Blanking Period. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 941 Preconditions None. Example uint32_t blankingY; blankingY = PLIB_GLCD_BlankingYGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_BlankingYGet( GLCD_MODULE_ID index ) PLIB_GLCD_LinesPrefetchSet Function Sets the clock controls of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LinesPrefetchSet(GLCD_MODULE_ID index, uint32_t linesPrefetch); Returns None. Description This function sets the clock controls of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LinesPrefetchSet( GLCD_MODULE_ID_0, MY_LINES_PREFETCH_VALUE ); Parameters Parameters Description index Identifier of the device instance linesPrefetch clock lines prefetch Function void PLIB_GLCD_LinesPrefetchSet( GLCD_MODULE_ID index, uint32_t linesPrefetch ) PLIB_GLCD_ClockDividerSet Function Sets clock controls of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_ClockDividerSet(GLCD_MODULE_ID index, uint32_t clockDivider); Returns None. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 942 Description This function sets clock controls of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_ClockDividerSet( GLCD_MODULE_ID_0, MY_CLOCK_DIVIDER_VALUE ); Parameters Parameters Description index Identifier of the device instance. clockDivider Factor dividing the GLCD clock. Function void PLIB_GLCD_ClockDividerSet( GLCD_MODULE_ID index, uint32_t clockDivider ) PLIB_GLCD_ClockDividerGet Function Gets Clock Divider value. File plib_glcd.h C uint32_t PLIB_GLCD_ClockDividerGet(GLCD_MODULE_ID index); Returns • value of clock divider. Description This function gets the Clock Divider value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t dividerValue; dividerValue = PLIB_GLCD_ClockDividerGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_ClockDividerGet( GLCD_MODULE_ID index ) PLIB_GLCD_ResolutionXYSet Function Sets the display resolution for the Graphics LCD Controller. File plib_glcd.h Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 943 C void PLIB_GLCD_ResolutionXYSet(GLCD_MODULE_ID index, uint32_t resolutionX, uint32_t resolutionY); Returns None. Description This function sets the display resolution for the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // set display resolution as: width: 640 pixels and height: 480 pixels PLIB_GLCD_ResolutionXYSet( GLCD_MODULE_ID_0, 640, 480 ); Parameters Parameters Description index Identifier of the device instance. resolutionX Display resolution on x axis in terms of number of pixels. resolutionY Display resolution on y axis in terms of number of pixels. Function void PLIB_GLCD_ResolutionXYSet( GLCD_MODULE_ID index, uint32_t resolutionX, uint32_t resolutionY ) c) Background Management Functions PLIB_GLCD_BackgroundColorGet Function Gets the value of the Background Color. File plib_glcd.h C uint32_t PLIB_GLCD_BackgroundColorGet(GLCD_MODULE_ID index); Returns • value of the Background Color. Description This function gets the value of the Background Color. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t backgroundColor; backgroundColor = PLIB_GLCD_BackgroundColorGet( GLCD_MODULE_ID_0 ); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 944 Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_BackgroundColorGet( GLCD_MODULE_ID index ); PLIB_GLCD_BackgroundColorSet Function Sets the background color. File plib_glcd.h C void PLIB_GLCD_BackgroundColorSet(GLCD_MODULE_ID index, uint32_t bgColor); Returns None. Description This function sets the background color of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_BGColorSet( GLCD_MODULE_ID_0, 0x000000FF ); Parameters Parameters Description index Identifier of the device instance. bgColor Background color. Function void ExistsBackgroundColor( GLCD_MODULE_ID index ) d) Layer Management Functions PLIB_GLCD_LayerBaseAddressGet Function Gets the Layer Base Address. File plib_glcd.h C uint32_t PLIB_GLCD_LayerBaseAddressGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • Layer base address value. Description This function sets the Layer Base Address. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 945 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t layerBaseAddress; layerBaseAddress = PLIB_GLCD_LayerBaseAddressGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function uint32_t PLIB_GLCD_LayerBaseAddressGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerBaseAddressSet Function Sets the base address of layer surface of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerBaseAddressSet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t baseAddress); Returns None. Description This function sets the layer base address of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // Set layer 0 surface base address as 0x20000000 PLIB_GLCD_LayerBaseAddressSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, 0x20000000 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. baseAddress baseAddress of layer surface. Function void PLIB_GLCD_LayerBaseAddressSet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t baseAddress ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 946 PLIB_GLCD_LayerBilinearFilterDisable Function Disables the layer Bilinear filter of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerBilinearFilterDisable(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns None. Description This function disables the layer Bilinear filter of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LayerBilinearFilterDisable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function void PLIB_GLCD_LayerBilinearFilterDisable ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerBilinearFilterEnable Function Enables the layer Bilinear filter of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerBilinearFilterEnable(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns None. Description This function enables the layer Bilinear filter of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LayerBilinearFilterEnable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 947 Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function void PLIB_GLCD_LayerBilinearFilterEnable ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerBilinearFilterIsEnabled Function Verify whether Layer Bilinear Filter is enabled. File plib_glcd.h C bool PLIB_GLCD_LayerBilinearFilterIsEnabled(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • true - The Layer Bilinear feature is enabled. • false - The Layer Bilinear feature is disabled. Description This function verifies whether Layer Bilinear Filter is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_LayerBilinearFilterIsEnabled( GLCD_MODULE_ID_0, GLCD_LAYER_0 ) ) { PLIB_GLCD_LayerBilinearFilterDisable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); } Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function bool PLIB_GLCD_LayerBilinearFilterIsEnabled ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerColorModeGet Function Gets the Layer Color Mode. File plib_glcd.h C GLCD_LAYER_COLOR_MODE PLIB_GLCD_LayerColorModeGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 948 Returns • GLCD_LAYER_COLOR_MODE_LUT8 - Layer Color Mode set to LUT8 • GLCD_LAYER_COLOR_MODE_RGBA5551 - Layer Color Mode set to RGBA5551 • GLCD_LAYER_COLOR_MODE_RGBA8888 - Layer Color Mode set to RGBA8888 • GLCD_LAYER_COLOR_MODE_RGB332 - Layer Color Mode set to RGB 332 • GLCD_LAYER_COLOR_MODE_RGB565 - Layer Color Mode set to RGB565 • GLCD_LAYER_COLOR_MODE_ARGB8888 - Layer Color Mode set to ARGB8888 • GLCD_LAYER_COLOR_MODE_L8 - Layer Color Mode set to L8 • GLCD_LAYER_COLOR_MODE_L1 - Layer Color Mode set to L1 • GLCD_LAYER_COLOR_MODE_L4 - Layer Color Mode set to L4 • GLCD_LAYER_COLOR_MODE_YUYV - Layer Color Mode set to YUYV • GLCD_LAYER_COLOR_MODE_RGB888 - Layer Color Mode set to RGB888 Description This function gets the Layer Color Mode Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t colorMode; colorMode = PLIB_GLCD_LayerColorModeGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function GLCD_LAYER_COLOR_MODE PLIB_GLCD_LayerColorModeGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ); PLIB_GLCD_LayerColorModeSet Function Sets the layer color mode of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerColorModeSet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, GLCD_LAYER_COLOR_MODE colorMode); Returns None. Description This function sets the layer color mode of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 949 Example // Set layer color mode to RGB232 PLIB_GLCD_LayerColorModeSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, GLCD_LAYER_COLOR_MODE_RGB232 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. colorMode Color mode defined by GLCD_LAYER_COLOR_MODE. Function void PLIB_GLCD_LayerColorModeSet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, GLCD_LAYER_COLOR_MODE colorMode ) PLIB_GLCD_LayerDestBlendFuncGet Function Gets the Layer Destination Blend Function. File plib_glcd.h C GLCD_LAYER_DEST_BLEND_FUNC PLIB_GLCD_LayerDestBlendFuncGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • GLCD_LAYER_DEST_BLEND_BLACK - Destination Blend function set to Black = 0. • GLCD_LAYER_DEST_BLEND_WHITE - Destination Blend function set to White = 255. • GLCD_LAYER_DEST_BLEND_ALPHA_SRC - Destination Blend function set to Source Alpha. • GLCD_LAYER_DEST_BLEND_ALPHA_GBL - Destination Blend function set to Global Alpha. • GLCD_LAYER_DEST_BLEND_ALPHA_SRCGBL - Destination Blend function set to ( Source * Global Alpha ) • GLCD_LAYER_DEST_BLEND_INV_SRC - Destination Blend function set to ( 1 - Source Alpha ) • GLCD_LAYER_DEST_BLEND_INV_GBL - Destination Blend function set to ( 1 - Global Alpha ) • GLCD_LAYER_DEST_BLEND_INV_SRCGBL - Destination Blend function set to ( 1 - ( Source Alpha * Global Alpha )). • GLCD_LAYER_DEST_BLEND_ALPHA_DST - Destination Blend function set to Destination Alpha. • GLCD_LAYER_DEST_BLEND_INV_DST - Destination Blend function set to ( 1 - Destination Alpha ) Description This function gets the Layer Destination Blend Function. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t destBlendFunc; destBlendFunc = PLIB_GLCD_LayerDestBlendFuncGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function GLCD_LAYER_DEST_BLEND_FUNC PLIB_GLCD_LayerDestBlendFuncGet( GLCD_MODULE_ID index, Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 950 GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerDestBlendFuncSet Function Sets the layer destination blend function of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerDestBlendFuncSet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, GLCD_LAYER_DEST_BLEND_FUNC blendFunc); Returns None. Description This function sets the layer destination blend function of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LayerDestBlendFuncSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, GLCD_BLEND_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. blendFunc Blend function defined by GLCD_LAYER_BLEND_FUNCTION. Function void PLIB_GLCD_LayerDestBlendFuncSet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, GLCD_LAYER_DEST_BLEND_FUNC blendFunc ) PLIB_GLCD_LayerDisable Function Disables the layer of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerDisable(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns None. Description This function disables the layer of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 951 Example PLIB_GLCD_LayerDisable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function void PLIB_GLCD_LayerDisable( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerEnable Function Enables the layer of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerEnable(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns None. Description This function enables the layer of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LayerEnable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function void PLIB_GLCD_LayerEnable( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerForceWithGlobalAlphaDisable Function Disables the Layer Force Global Alpha feature. File plib_glcd.h C void PLIB_GLCD_LayerForceWithGlobalAlphaDisable(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns None. Description This function disables the Layer Force Global Alpha feature. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 952 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LayerForceWithGlobalAlphaDisable ( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function void PLIB_GLCD_LayerForceWithGlobalAlphaDisable ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerForceWithGlobalAlphaEnable Function Enable the Layer Force Global Alpha feature. File plib_glcd.h C void PLIB_GLCD_LayerForceWithGlobalAlphaEnable(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns None. Description This function enables the Layer Force Global Alpha feature. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LayerForceWithGlobalAlphaEnable ( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function void PLIB_GLCD_LayerForceWithGlobalAlphaEnable ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerForceWithGlobalAlphaIsEnabled Function Verify whether Layer Force with Global Alpha Feature is enabled. File plib_glcd.h Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 953 C bool PLIB_GLCD_LayerForceWithGlobalAlphaIsEnabled(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • true - The Layer Force Global Alpha feature is enabled. • false - The Layer Force Global Alpha feature is disabled. Description This function verifies whether Layer Force with Global Alpha Feature is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_LayerForceWithGlobalAlphaIsEnabled( GLCD_MODULE_ID_0, GLCD_LAYER_0 ) ) { PLIB_GLCD_LayerForceWithGlobalAlphaDisable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); } Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function bool PLIB_GLCD_LayerForceWithGlobalAlphaIsEnabled ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerGlobalAlphaGet Function Gets the Layer Global Alpha value. File plib_glcd.h C uint8_t PLIB_GLCD_LayerGlobalAlphaGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • Layer Alpha value Description This function gets the Layer Global Alpha value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint8_t layerAlpha; layerAlpha = PLIB_GLCD_LayerGlobalAlphaGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 954 Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function uint8_t PLIB_GLCD_LayerGlobalAlphaGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerGlobalAlphaSet Function Sets the layer global alpha of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerGlobalAlphaSet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint8_t value); Returns None. Description This function sets the layer global alpha of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // set global alpha value of layer 0 to 255 PLIB_GLCD_Layer_GlobalAlpha_Set( GLCD_MODULE_ID_0, GLCD_LAYER_0, 255 ) Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. value Global alpha value. Function void PLIB_GLCD_LayerGlobalAlphaSet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint8_t value ) PLIB_GLCD_LayerIsEnabled Function Verify whether Layer is enabled. File plib_glcd.h C bool PLIB_GLCD_LayerIsEnabled(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • true - The given Layer is enabled. • false - The given Layer is disabled. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 955 Description This function verifies whether a given Layer is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_LayerIsEnabled( GLCD_MODULE_ID_0, GLCD_LAYER_0 ) ) { PLIB_GLCD_LayerDisable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_LayerIsEnabled ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerPreMultiplyImageAlphaDisable Function Disable Layer Pre-Multiply Image Alpha Feature. File plib_glcd.h C void PLIB_GLCD_LayerPreMultiplyImageAlphaDisable(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns None. Description This function disables Layer Pre-Multiply Image Alpha Feature. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LayerPreMultiplyImageAlphaDisable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function void PLIB_GLCD_LayerPreMultiplyImageAlphaDisable ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerPreMultiplyImageAlphaEnable Function Enable Layer Pre-Multiply Image Alpha Feature. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 956 File plib_glcd.h C void PLIB_GLCD_LayerPreMultiplyImageAlphaEnable(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns None. Description This function enables the Layer Pre-Multiply Image Alpha Feature. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LayerPreMultiplyImageAlphaEnable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function void PLIB_GLCD_LayerPreMultiplyImageAlphaEnable ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerPreMultiplyImageAlphaIsEnabled Function Verify whether the Layer Pre-Multiply Image Alpha Feature is enabled. File plib_glcd.h C bool PLIB_GLCD_LayerPreMultiplyImageAlphaIsEnabled(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • true - The Layer Pre-Multiply Image Alpha feature is enabled • false - The Layer Pre-Multiply Image Alpha feature is disabled. Description This function verifies whether the Layer Pre-Multiply Image Alpha Feature is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_LayerPreMultiplyImageAlphaIsEnabled( GLCD_MODULE_ID_0, GLCD_LAYER_0 ) ) { PLIB_GLCD_LayerPreMultiplyImageAlphaDisable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); } Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 957 Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function bool PLIB_GLCD_LayerPreMultiplyImageAlphaIsEnabled ( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerResXGet Function Gets the Layer X Axis Resolution. File plib_glcd.h C uint32_t PLIB_GLCD_LayerResXGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • value of layer x axis resolution. Description This function gets the Layer X Axis Resolution. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t resolutionX; resolutionX = PLIB_GLCD_LayerResXGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function uint32_t PLIB_GLCD_LayerResXGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerResXYSet Function Sets the layer resolution in pixels. File plib_glcd.h C void PLIB_GLCD_LayerResXYSet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t resolutionX, uint32_t resolutionY); Returns None. Description This function sets the layer resolution in pixels. The resolution is defined as the number of pixels on the x axis and the number of pixels on the y Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 958 axis. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // Layer resolution set to x = 320 pixels and y = 240 pixels PLIB_GLCD_Layer_ResXY_Set( GLCD_MODULE_ID_0, GLCD_LAYER_0, 320, 240); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. resolutionX resolution on x axis in terms of pixels. resolutionY resolution on y axis in terms of pixels. Function void PLIB_GLCD_LayerResXYSet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t resolutionX, uint32_t resolutionY ) PLIB_GLCD_LayerResYGet Function Gets the Layer Y Axis Resolution. File plib_glcd.h C uint32_t PLIB_GLCD_LayerResYGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • value of layer y axis resolution. Description This function gets the Layer Y Axis Resolution. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t resolutionY; resolutionY = PLIB_GLCD_LayerResYGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function uint32_t PLIB_GLCD_LayerResYGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 959 PLIB_GLCD_LayerSizeXGet Function Gets the Layer X Axis Size. File plib_glcd.h C uint32_t PLIB_GLCD_LayerSizeXGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • Layer Size X value. Description This function gets the Layer X Axis Size. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t sizeX; startX = PLIB_GLCD_LayerSizeXGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function uint32_t PLIB_GLCD_LayerSizeXGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerSizeXYSet Function Sets the layer size x and size y of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerSizeXYSet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t sizeX, uint32_t sizeY); Returns None. Description This function sets the layer start x and start y of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // set layer size to (640, 480) PLIB_GLCD_LayerSizeXYSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, 640, 480); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 960 Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. sizeX Layer size on x axis in terms of pixels. sizeY Layer size on y axis in terms of pixels. Function void PLIB_GLCD_LayerSizeXYSet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t sizeX, uint32_t sizeY ) PLIB_GLCD_LayerSizeYGet Function Gets the Layer Y Axis Size. File plib_glcd.h C uint32_t PLIB_GLCD_LayerSizeYGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • Layer Size Y value. Description This function gets the Layer Y Axis Size. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t sizeY; sizeY = PLIB_GLCD_LayerSizeYGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function uint32_t PLIB_GLCD_LayerSizeYGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerSrcBlendFuncGet Function Gets the Layer Source Blend Function. File plib_glcd.h C GLCD_LAYER_SRC_BLEND_FUNC PLIB_GLCD_LayerSrcBlendFuncGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 961 Returns • GLCD_LAYER_SRC_BLEND_BLACK - Source Blend Function set to Black = 0. • GLCD_LAYER_SRC_BLEND_WHITE - Source Blend Function set to White = 255. • GLCD_LAYER_SRC_BLEND_ALPHA_SRC - Source Blend Function set to Source Alpha. • GLCD_LAYER_SRC_BLEND_ALPHA_GBL - Source Blend Function set to Global Alpha. • GLCD_LAYER_SRC_BLEND_ALPHA_SRCGBL - Source Blend Function set to ( Source Alpha * Global Alpha ). • GLCD_LAYER_SRC_BLEND_INV_SRC - Source Blend Function set to ( 1 - Source Alpha ). • GLCD_LAYER_SRC_BLEND_INV_GBL - Source Blend Function set to ( 1 - Global Alpha ). • GLCD_LAYER_SRC_BLEND_INV_SRCGBL - Source Blend Function set to ( 1 - ( Source Alpha * Global Alpha ) ) • GLCD_LAYER_SRC_BLEND_ALPHA_DST - Source Blend Function set to Destination Alpha • GLCD_LAYER_SRC_BLEND_INV_DST - Source Blend Function set to ( 1 - Destination Alpha ) Description This function gets the Layer Source Blend Function. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t srcBlendFunc; srcBlendFunc = PLIB_GLCD_LayerSrcBlendFuncGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function GLCD_LAYER_SRC_BLEND_FUNC PLIB_GLCD_LayerSrcBlendFuncGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerSrcBlendFuncSet Function Sets the layer source blend function of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerSrcBlendFuncSet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, GLCD_LAYER_SRC_BLEND_FUNC blendFunc); Returns None. Description This function sets the layer source blend function of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_LayerSrcBlendFuncSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 962 GLCD_BLEND_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. blendFunc Blend function defined by GLCD_LAYER_BLEND_FUNCTION. Function void PLIB_GLCD_LayerSrcBlendFuncSet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, GLCD_LAYER_SRC_BLEND_FUNC blendFunc ) PLIB_GLCD_LayerStartXGet Function Gets the Layer X Axis Start Position. File plib_glcd.h C uint32_t PLIB_GLCD_LayerStartXGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • Layer Start X value. Description This function gets the Layer X Axis Start Position. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t startX; startX = PLIB_GLCD_LayerStartXGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function uint32_t PLIB_GLCD_LayerStartXGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ); PLIB_GLCD_LayerStartXYSet Function Sets the layer start x and start y of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerStartXYSet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t startX, uint32_t startY); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 963 Returns None. Description This function sets the layer start x and start y of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None Example // set layer start to (20, 20) PLIB_GLCD_LayerStartXYSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, 20, 20); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. startX Layer start on x axis in terms of pixels. startY Layer start on y axis in terms of pixels. Function void PLIB_GLCD_LayerStartXYSet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t startX, uint32_t startY ) PLIB_GLCD_LayerStartYGet Function Gets the Layer Y Axis Start Position. File plib_glcd.h C uint32_t PLIB_GLCD_LayerStartYGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • Layer Start Y value. Description This function gets the Layer Y Axis Start Position. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t startY; startY = PLIB_GLCD_LayerStartYGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 964 layerId Identifier of the Graphics rendering layer. Function uint32_t PLIB_GLCD_LayerStartYGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ); PLIB_GLCD_LayerStrideGet Function Gets the Layer Stride value. File plib_glcd.h C uint32_t PLIB_GLCD_LayerStrideGet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId); Returns • value of the stride. Description This function gets the Layer Stride value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t layerStride; layerStride = PLIB_GLCD_LayerStrideGet( GLCD_MODULE_ID_0 GLCD_LAYER_0 ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. Function uint32_t PLIB_GLCD_LayerStrideGet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId ) PLIB_GLCD_LayerStrideSet Function Sets the layer surface stride of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_LayerStrideSet(GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t stride); Returns None. Description This function sets the layer surface stride of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 965 Preconditions None. Example uint32_t imageStride = IMAGE_WIDTH * IMAGE_BYTES_PER_PIXEL; // To make stride 4 byte aligned imageStride += ( imageStride % 4 ); PLIB_GLCD_LayerStrideSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, imageStride ); Parameters Parameters Description index Identifier of the device instance. layerId Identifier of the Graphics rendering layer. stride line width in bytes including padding. Function void PLIB_GLCD_LayerStrideSet( GLCD_MODULE_ID index, GLCD_LAYER_ID layerId, uint32_t stride ) e) Hardware Cursor Control and Management Functions PLIB_GLCD_CursorDataGet Function Gets the Cursor Data at given Index. File plib_glcd.h C uint32_t PLIB_GLCD_CursorDataGet(GLCD_MODULE_ID index, uint32_t dataIndex); Returns • value of the 8 pixels of the cursor at given index. Description This function gets the Cursor Data at given Index. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t cursorData; cursorData = PLIB_GLCD_CursorDataGet( GLCD_MODULE_ID_0, MY_CURSOR_DATA_INDEX ); Parameters Parameters Description index Identifier of the device instance. dataIndex Index of the Cursor data. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 966 Function uint32_t PLIB_GLCD_CursorDataGet( GLCD_MODULE_ID index, uint32_t dataIndex ) PLIB_GLCD_CursorDataSet Function Sets the cursor image data. File plib_glcd.h C void PLIB_GLCD_CursorDataSet(GLCD_MODULE_ID index, uint32_t * cursorData); Returns None. Description This function sets the cursor image data. The image data format is 4-bit black, white and 50 percent gray color. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t *cursorData = cursorDataAddress; // Set cursor data in the format: 4-bit CLUT Index PLIB_GLCD_CursorDataSet( GLCD_MODULE_ID_0, cursorData ); Parameters Parameters Description index Identifier of the device instance. cursorData pointer to cursor data in the format 4-bit CLUT Index. Function void PLIB_GLCD_CursorDataSet( GLCD_MODULE_ID index, uint32_t * cursorData ) PLIB_GLCD_CursorDisable Function Disables the cursor of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_CursorDisable(GLCD_MODULE_ID index); Returns None. Description This function disables the cursor of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 967 Example if ( PLIB_GLCD_ExistsCursor( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_CursorDisable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_CursorDisable( GLCD_MODULE_ID index ) PLIB_GLCD_CursorEnable Function Enables the cursor of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_CursorEnable(GLCD_MODULE_ID index); Returns None. Description This function enables the cursor of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_ExistsCursor( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_CursorEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_CursorEnable( GLCD_MODULE_ID index ) PLIB_GLCD_CursorIsEnabled Function Verifies whether the cursor is enabled. File plib_glcd.h C bool PLIB_GLCD_CursorIsEnabled(GLCD_MODULE_ID index); Returns • true - Cursor is enabled. • false - Cursor is disabled. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 968 Description This function verifies whether the cursor is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_CursorIsEnabled( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_CursorDisable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_CursorIsEnabled ( GLCD_MODULE_ID index ) PLIB_GLCD_CursorLUTGet Function Gets the color from Cursor LUT at given Index. File plib_glcd.h C uint32_t PLIB_GLCD_CursorLUTGet(GLCD_MODULE_ID index, uint32_t lutIndex); Returns • value of color from color LUT at given index. Description This function gets the color from Cursor LUT at given Index. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t cursorLUTColor; cursorLUTColor = PLIB_GLCD_CursorLUTGet( GLCD_MODULE_ID_0, MY_CURSOR_CLUT_INDEX ); Parameters Parameters Description index Identifier of the device instance. lutIndex Cursor Color LUT index. Function uint32_t PLIB_GLCD_CursorLUTGet( GLCD_MODULE_ID index, uint32_t lutIndex ) PLIB_GLCD_CursorLUTSet Function Sets the cursor color look-up table (LUT) in XRGB8888 format. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 969 File plib_glcd.h C void PLIB_GLCD_CursorLUTSet(GLCD_MODULE_ID index, uint32_t * cursorLUT); Returns None. Description This function sets the cursor color LUT of the Graphics LCD Controller in XRGB8888 format. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t * cursorLUTColors = cursorLUTAddress; PLIB_GLCD_CursorLUTSet( GLCD_MODULE_ID_0, cursorLUTColors ); Parameters Parameters Description index Identifier of the device instance. cursorLUT Pointer to the cursor color LUT in XRGB8888 format. Function void PLIB_GLCD_CursorLUTSet( GLCD_MODULE_ID index, uint32_t * cursorLUT ) PLIB_GLCD_CursorXGet Function Gets the cursor X Axis Position. File plib_glcd.h C uint32_t PLIB_GLCD_CursorXGet(GLCD_MODULE_ID index); Returns • Cursor X Axis Position. Description This function gets the cursor X Axis Position. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t cursorX; cursorX = PLIB_GLCD_CursorXGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 970 Function uint32_t PLIB_GLCD_CursorXGet( GLCD_MODULE_ID index ) PLIB_GLCD_CursorXYSet Function Sets the x and y coordinates of the Graphics LCD Controller cursor. File plib_glcd.h C void PLIB_GLCD_CursorXYSet(GLCD_MODULE_ID index, uint32_t cursorX, uint32_t cursorY); Returns None. Description This function sets the x and y coordinates of the Graphics Display Controller cursor. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // update cursor position at x:20 pixels and y:20 pixels PLIB_GLCD_CursorXYSet( GLCD_MODULE_ID_0, 20, 20 ); Parameters Parameters Description index Identifier of the device instance. cursorX cursor coordinate on x axis in terms of pixels. cursorY cursor coordinate on y axis in terms of pixels. Function void PLIB_GLCD_CursorXYSet( GLCD_MODULE_ID index, uint32_t cursorX, uint32_t cursorY ) PLIB_GLCD_CursorYGet Function Gets the Cursor Y Axis Position. File plib_glcd.h C uint32_t PLIB_GLCD_CursorYGet(GLCD_MODULE_ID index); Returns • Cursor Y Axis Position. Description This function gets the Cursor Y Axis Position. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 971 Preconditions None. Example uint32_t cursorY; cursorY = PLIB_GLCD_CursorYGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function uint32_t PLIB_GLCD_CursorYGet( GLCD_MODULE_ID index ) f) Palette and Gamma Correction Control Functions PLIB_GLCD_GlobalColorLUTGet Function Gets the Color from Global Color LUT at given Index. File plib_glcd.h C uint32_t PLIB_GLCD_GlobalColorLUTGet(GLCD_MODULE_ID index, uint32_t lutIndex); Returns • value of Color from the Color Lookup Table. Description This function gets the Color from Global Color LUT at given Index. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t lutColor; lutColor = PLIB_GLCD_GlobalColorLUTGet( GLCD_MODULE_ID_0, MY_LUT_COLOR_INDEX ); Parameters Parameters Description index Identifier of the device instance. lutIndex Color Lookup table index. Function uint32_t PLIB_GLCD_GlobalColorLUTGet( GLCD_MODULE_ID index, uint32_t lutIndex ) PLIB_GLCD_GlobalColorLUTSet Function Set Global Color LUT. File plib_glcd.h Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 972 C void PLIB_GLCD_GlobalColorLUTSet(GLCD_MODULE_ID index, uint32_t * globalLUT); Returns None. Description This function sets the Global Color LUT. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t globalColorLUT[256] = { // Initial values }; PLIB_GLCD_GlobalColorLUTSet( GLCD_MODULE_ID_0, globalColorLUT ); Parameters Parameters Description index Identifier of the device instance. globalLUT pointer of the Global Color Lookup table data array. Function void PLIB_GLCD_GlobalColorLUTSet( GLCD_MODULE_ID index, uint32_t *globalLUT ) PLIB_GLCD_PaletteGammaRampDisable Function Disables the palette / gamma ramp of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_PaletteGammaRampDisable(GLCD_MODULE_ID index); Returns None. Description This function disables the palette / gamma ramp of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_PaletteGammaRampDisable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_PaletteGammaRampDisable( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 973 PLIB_GLCD_PaletteGammaRampEnable Function Enables the palette / gamma ramp of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_PaletteGammaRampEnable(GLCD_MODULE_ID index); Returns None. Description This function enables the palette / gamma ramp of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_PaletteGammaRampEnable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_PaletteGammaRampEnable( GLCD_MODULE_ID index ) PLIB_GLCD_PaletteGammaRampIsEnabled Function Verify whether Palette / Gamma Ramp feature is enabled. File plib_glcd.h C bool PLIB_GLCD_PaletteGammaRampIsEnabled(GLCD_MODULE_ID index); Returns • true - The palette / gamma ramp feature is enabled. • false - The palette / gamma ramp feature is disabled. Description This function verifies whether Palette / Gamma Ramp feature is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_PaletteGammaRampIsEnabled( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_PaletteGammaRampDisable( GLCD_MODULE_ID_0 ); } Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 974 Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_PaletteGammaRampIsEnabled( GLCD_MODULE_ID index ) g) Interrupt Control Functions PLIB_GLCD_HSyncInterruptDisable Function Disables interrupts at Hsync. File plib_glcd.h C void PLIB_GLCD_HSyncInterruptDisable(GLCD_MODULE_ID index); Returns None. Description This function disables interrupts at Hsync. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_HsyncInterruptDisable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_HSyncInterruptDisable( GLCD_MODULE_ID index ) PLIB_GLCD_HSyncInterruptEnable Function Enables interrupts at Hsync. File plib_glcd.h C void PLIB_GLCD_HSyncInterruptEnable(GLCD_MODULE_ID index); Returns None. Description This function enables interrupts at Hsync. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 975 Preconditions None. Example PLIB_GLCD_HSyncInterruptEnable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_HSyncInterruptEnable( GLCD_MODULE_ID index ) PLIB_GLCD_HSyncInterruptIsEnabled Function Verify whether HSYNC Interrupt is enabled. File plib_glcd.h C bool PLIB_GLCD_HSyncInterruptIsEnabled(GLCD_MODULE_ID index); Returns • true - The HSYNC Interrupt feature is enabled. • false - The HSYNC Interrupt feature is disabled. Description This function verifies whether HSYNC Interrupt is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_HSyncInterruptIsEnabled( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_HSyncInterruptDisable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_HSyncInterruptIsEnabled( GLCD_MODULE_ID index ) PLIB_GLCD_HSyncSignalLevelGet Function Gets the Hsync signal level. File plib_glcd.h C bool PLIB_GLCD_HSyncSignalLevelGet(GLCD_MODULE_ID index); Returns • true - The Hsync signal level is high. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 976 • false - The Hsync signal level is low. Description This function returns the Hsync signal level. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if(!PLIB_GLCD_HSyncSignalLevelGet( GLCD_MODULE_ID_0 )); { //Hsync signal level is low return; } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_HSyncSignalLevelGet( GLCD_MODULE_ID index ) PLIB_GLCD_IRQTriggerControlGet Function Gets the IRQ Trigger Control value. File plib_glcd.h C GLCD_IRQ_TRIGGER_CONTROL PLIB_GLCD_IRQTriggerControlGet(GLCD_MODULE_ID index); Returns • GLCD_IRQ_TRIGGER_LEVEL - IRQ is Level Triggered. • GLCD_IRQ_TRIGGER_EDGE - IRQ is edge Triggered. Description This function gets the IRQ Trigger Control value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t irqTrigger; irqTrigger = PLIB_GLCD_IRQTriggerControlGet( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function GLCD_IRQ_TRIGGER_CONTROL PLIB_GLCD_IRQTriggerControlGet( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 977 PLIB_GLCD_IRQTriggerControlSet Function Sets the IRQ trigger control. File plib_glcd.h C void PLIB_GLCD_IRQTriggerControlSet(GLCD_MODULE_ID index, GLCD_IRQ_TRIGGER_CONTROL irqControl); Returns None. Description This function sets the IRQ trigger control. IRQ trigger detection is defined at the edge or level of the trigger pulse. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example // Set trigger detection at edge PLIB_GLCD_IRQTriggerControlSet( GLCD_MODULE_ID_0, GLCD_IRQ_TRIGGER_EDGE ); Parameters Parameters Description index Identifier of the device instance. control Trigger control defined by GLCD_IRQ_TRIGGER_CONTROL. Function void PLIB_GLCD_IRQTriggerControlSet( GLCD_MODULE_ID index, GLCD_IRQ_TRIGGER_CONTROL irqControl) PLIB_GLCD_VSyncInterruptDisable Function Disables interrupts at Vsync. File plib_glcd.h C void PLIB_GLCD_VSyncInterruptDisable(GLCD_MODULE_ID index); Returns None. Description This function disables interrupts at Vsync. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_VsyncInterruptDisable( GLCD_MODULE_ID_0 ); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 978 Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_VSyncInterruptDisable( GLCD_MODULE_ID index ) PLIB_GLCD_VSyncInterruptEnable Function Enables interrupts at Vsync. File plib_glcd.h C void PLIB_GLCD_VSyncInterruptEnable(GLCD_MODULE_ID index); Returns None. Description This function enables interrupts at Vsync. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None Example PLIB_GLCD_VSyncInterruptEnable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_VSyncInterruptEnable( GLCD_MODULE_ID index ) PLIB_GLCD_VSyncInterruptIsEnabled Function Verify whether VSYNC Interrupt is enabled. File plib_glcd.h C bool PLIB_GLCD_VSyncInterruptIsEnabled(GLCD_MODULE_ID index); Returns • true - The VSYNC Interrupt feature is enabled. • false - The VSYNC Interrupt feature is disabled. Description This function verifies whether the VSYNC Interrupt is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 979 Preconditions None. Example if ( PLIB_GLCD_VSyncInterruptIsEnabled( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_VSyncInterruptDisable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_VSyncInterruptIsEnabled( GLCD_MODULE_ID index ) PLIB_GLCD_VSyncSignalLevelGet Function Gets the Vsync signal level. File plib_glcd.h C bool PLIB_GLCD_VSyncSignalLevelGet(GLCD_MODULE_ID index); Returns • true - The Vsync signal level is high. • false - The Vsync signal level is low. Description This function returns the Vsync signal level. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if(!PLIB_GLCD_VSyncSignalLevelGet( GLCD_MODULE_ID_0 )); { //Vsync signal level is low return; } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_VSyncSignalLevelGet( GLCD_MODULE_ID index ) h) Miscellaneous Control Functions PLIB_GLCD_DitheringDisable Function Disables the Dithering feature of the Graphics LCD Controller. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 980 File plib_glcd.h C void PLIB_GLCD_DitheringDisable(GLCD_MODULE_ID index); Returns None. Description This function disables the Dithering feature of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_DitheringDisable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_DitheringDisable( GLCD_MODULE_ID index ) PLIB_GLCD_DitheringEnable Function Enables the Dithering feature of the Graphics LCD Controller. File plib_glcd.h C void PLIB_GLCD_DitheringEnable(GLCD_MODULE_ID index); Returns None. Description This function enables the Dithering feature of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_DitheringEnable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_DitheringEnable( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 981 PLIB_GLCD_ForceOutputBlankDisable Function Disable Force Output Blank feature. File plib_glcd.h C void PLIB_GLCD_ForceOutputBlankDisable(GLCD_MODULE_ID index); Returns None. Description This function disables the Force Output Blank feature. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_ForceOutputBlankDisable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_ForceOutputBlankDisable( GLCD_MODULE_ID index ) PLIB_GLCD_ForceOutputBlankEnable Function Enable Force Output Blank feature. File plib_glcd.h C void PLIB_GLCD_ForceOutputBlankEnable(GLCD_MODULE_ID index); Returns None. Description This function enables the Force Output Blank feature. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_ForceOutputBlankEnable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 982 Function void PLIB_GLCD_ForceOutputBlankEnable( GLCD_MODULE_ID index ) PLIB_GLCD_SingleCyclePerLineVsyncDisable Function Clears VSYNC on single cycle per line. File plib_glcd.h C void PLIB_GLCD_SingleCyclePerLineVsyncDisable(GLCD_MODULE_ID index); Returns None. Description This function clears VSYNC on single cycle per line. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_SingleCyclePerLineVsyncClear( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_SingleCyclePerLineVsyncClear( GLCD_MODULE_ID index ) PLIB_GLCD_SingleCyclePerLineVsyncEnable Function Sets VSYNC on single cycle per line. File plib_glcd.h C void PLIB_GLCD_SingleCyclePerLineVsyncEnable(GLCD_MODULE_ID index); Returns None. Description This function sets VSYNC on single cycle per line. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_SingleCyclePerLineVsyncEnable( GLCD_MODULE_ID_0 ); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 983 Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_SingleCyclePerLineVsyncSet( GLCD_MODULE_ID index ) PLIB_GLCD_SingleCyclePerLineVsyncIsEnabled Function Verify whether VSYNC on Single Cycle Per Line feature is enabled. File plib_glcd.h C bool PLIB_GLCD_SingleCyclePerLineVsyncIsEnabled(GLCD_MODULE_ID index); Returns • true - VSYNC on Single Cycle Per Line is enabled. • false - VSYNC on Single Cycle Per Line is disabled. Description This function verifies whether VSYNC on Single Cycle Per Line feature is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if(PLIB_GLCD_SingleCyclePerLineVsyncIsEnabled(GLCD_MODULE_ID_0)) { PLIB_GLCD_SingleCyclePerLineVsyncDisable(GLCD_MODULE_ID_0); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_SingleCyclePerLineVsyncIsEnabled( GLCD_MODULE_ID index ) PLIB_GLCD_YUVOutputDisable Function Disables the output of the Graphics LCD Controller in YUV format. File plib_glcd.h C void PLIB_GLCD_YUVOutputDisable(GLCD_MODULE_ID index); Returns None. Description This function Disables the output of the Graphics LCD Controller in YUV format. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 984 Preconditions None. Example PLIB_GLCD_YUVOutputDisable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_YUVOutputDisable( GLCD_MODULE_ID index ) PLIB_GLCD_YUVOutputEnable Function Enables the output of the Graphics LCD Controller in YUV format. File plib_glcd.h C void PLIB_GLCD_YUVOutputEnable(GLCD_MODULE_ID index); Returns None. Description This function enables the output of the Graphics LCD Controller in YUV format. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example PLIB_GLCD_YUVOutputEnable( GLCD_MODULE_ID_0 ); Parameters Parameters Description index Identifier of the device instance. Function void PLIB_GLCD_YUVOutputEnable( GLCD_MODULE_ID index ) PLIB_GLCD_DESignalLevelGet Function Gets the display enable signal level. File plib_glcd.h C bool PLIB_GLCD_DESignalLevelGet(GLCD_MODULE_ID index); Returns • true - The DE signal level high. • false - The DE signal level low. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 985 Description This function returns the display enable (DE) signal of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if(!PLIB_GLCD_DESignalLevelGet( GLCD_MODULE_ID_0 )); { //DE signal low return; } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_DESignalLevelGet( GLCD_MODULE_ID index ) PLIB_GLCD_DitheringIsEnabled Function Verifies whether Dithering is enabled. File plib_glcd.h C bool PLIB_GLCD_DitheringIsEnabled(GLCD_MODULE_ID index); Returns • true - The Dithering feature is enabled. • false - The Dithering feature is disabled. Description This function verifies whether Dithering is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if(PLIB_GLCD_DitheringIsEnabled(GLCD_MODULE_ID_0 )) { PLIB_GLCD_DitheringDisable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_DitheringIsEnabled( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 986 PLIB_GLCD_ForceOutputBlankIsEnabled Function Verify whether the Force Output Blank feature is enabled. File plib_glcd.h C bool PLIB_GLCD_ForceOutputBlankIsEnabled(GLCD_MODULE_ID index); Returns • true - The Force Output Blank feature is enabled. • false - The Force Output Blank feature is disabled. Description This function verifies whether the Force Output Blank feature is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_ForceOutputBlankIsEnabled( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_ForceOutputBlankDisable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ForceOutputBlankIsEnabled( GLCD_MODULE_ID index ) PLIB_GLCD_IsEnabled Function Verifies whether the Graphics LCD Controller is Enabled. File plib_glcd.h C bool PLIB_GLCD_IsEnabled(GLCD_MODULE_ID index); Returns • true - Graphics LCD Controller is Enabled • false - Graphics LCD Controller is Disabled Description This function verifies whether the Graphics LCD Controller is Enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_IsEnabled( GLCD_MODULE_ID_0 ) ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 987 { PLIB_GLCD_Disable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_IsEnabled ( GLCD_MODULE_ID index ) PLIB_GLCD_IsLastRow Function Gets the status indicating whether a last row is currently displayed by the Graphics Display Controller. File plib_glcd.h C bool PLIB_GLCD_IsLastRow(GLCD_MODULE_ID index); Returns • true - The last row is currently displayed. • false - The last row is not currently displayed. Description This function returns the status indicating whether a last row is currently displayed by the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if(!PLIB_GLCD_IsLastRow( GLCD_MODULE_ID_0 )); { // The last row is not currently displayed return; } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_IsLastRow( GLCD_MODULE_ID index ) PLIB_GLCD_IsVerticalBlankingActive Function Get the active status. File plib_glcd.h C bool PLIB_GLCD_IsVerticalBlankingActive(GLCD_MODULE_ID index); Returns • true - The Vertical Blanking is active. • false - The Vertical Blanking is inactive. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 988 Description This function returns the active status of the Graphics LCD Controller. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_IsVerticalBlankingActive( GLCD_MODULE_ID_0 ) ) { //GLCD Vertical Blanking active return; } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_IsVerticalBlankingActive( GLCD_MODULE_ID index ) PLIB_GLCD_RGBSequentialModeGet Function Get the RGB Sequential Mode already set. File plib_glcd.h C GLCD_RGB_MODE PLIB_GLCD_RGBSequentialModeGet(GLCD_MODULE_ID index); Returns • GLCD_RGB_MODE_PARALLEL_RGB565 - Parallel RGB 565 Mode • GLCD_RGB_MODE_PARALLEL_RGB888 - Parallel RGB 888 Mode • GLCD_RGB_MODE_SERIAL_RGB_3 - Byte Serial RGB 3 Mode • GLCD_RGB_MODE_SERIAL_RGBA_4 - Byte Serial RGB 4 Mode • GLCD_RGB_MODE_SERIAL_12BIT - Byte Two-Phase 12-bit Mode • GLCD_RGB_MODE_YUYV_16BIT - YUYV 16 bit Mode • GLCD_RGB_MODE_BT_656 - BT 656 Mode Description This function gets the RGB Sequential Mode already set. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example uint32_t rgbMode; rgbMode = PLIB_GLCD_RGBSequentialModeGet( GLCD_MODULE_ID_0 ); if( rgbMode == GLCD_RGB_MODE_PARALLEL_RGB565 ) { // RGB Mode set to RGB 565 format } Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 989 Parameters Parameters Description index Identifier of the device instance. Function GLCD_RGB_MODE PLIB_GLCD_RGBSequentialModeGet( GLCD_MODULE_ID index ) PLIB_GLCD_YUVOutputIsEnabled Function Verify whether the YUV Output feature is enabled. File plib_glcd.h C bool PLIB_GLCD_YUVOutputIsEnabled(GLCD_MODULE_ID index); Returns • true - The YUV output feature is enabled. • false - The YUV output feature is disabled. Description This function verifies whether the YUV Output feature is enabled. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_YUVOutputIsEnabled( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_YUVOutputDisable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_YUVOutputIsEnabled( GLCD_MODULE_ID index ) i) Feature Existence Functions PLIB_GLCD_ExistsBackgroundColor Function Verify whether the Background Color Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsBackgroundColor(GLCD_MODULE_ID index); Returns • true - The Background Color feature is supported. • false - The Background Color feature is not supported. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 990 Description This function verifies whether the Background Color Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsBackgroundColor( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_BackgroundColorSet( GLCD_MODULE_ID_0, MY_BACKGROUND_COLOR_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsBackgroundColor( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsBackPorchXY Function Verify whether Back Porch Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsBackPorchXY(GLCD_MODULE_ID index); Returns • true - The Back Porch feature is supported. • false - The Back Porch feature is not supported. Description This function verifies whether Back Porch Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsBackPorchXY( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_BackPorchXYSet( GLCD_MODULE_ID_0, MY_BACK_PORCH_X_VALUE, MY_BACK_PORCH_Y_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsBackPorchXY( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 991 PLIB_GLCD_ExistsBlankingXY Function Verify whether Blanking Period Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsBlankingXY(GLCD_MODULE_ID index); Returns • true - The Blanking feature is supported. • false - The Blanking feature is not supported. Description This function verifies whether Blanking Period Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsBlankingXY( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_BlankingXYSet( GLCD_MODULE_ID_0, MY_BLANKING_PERIOD_X_VALUE, MY_BLANKING_PERIOD_Y_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsBlankingXY( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsClockDivider Function Verify whether the Clock Divider feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsClockDivider(GLCD_MODULE_ID index); Returns • true - The Clock divide feature is supported. • false - The Clock divide feature is not supported. Description This function verifies whether the Clock Divider feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 992 Example if( PLIB_GLCD_ExistsClockDivider( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_ClockDividerSet( GLCD_MODULE_ID_0, MY_CLOCK_DIVIDER_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsClockDivider( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsCursor Function Verifies whether the cursor feature exists. File plib_glcd.h C bool PLIB_GLCD_ExistsCursor(GLCD_MODULE_ID index); Returns • true - Cursor feature exists. • false - Cursor feature does not exits. Description This function verifies whether the cursor feature exists. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_ExistsCursor( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_CursorEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsCursor( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsCursorData Function File plib_glcd.h C bool PLIB_GLCD_ExistsCursorData(GLCD_MODULE_ID index); Returns • true - The Cursor Data feature is supported. • false - The Cursor Data feature is not supported. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 993 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsCursorData( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_CursorDataSet( GLCD_MODULE_ID_0, MY_CURSOR_DATA_POINTER_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsCursorData( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsCursorLUT Function Verify whether Cursor LUT feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsCursorLUT(GLCD_MODULE_ID index); Returns • true - The Cursor LUT feature is supported. • false - The Cursor LUT feature is not supported. Description This function verifies whether Cursor LUT feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsCursorLUT( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_CursorLUTSet( GLCD_MODULE_ID_0, MY_CURSOR_LUT_DATA_POINTER_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsCursorLUT( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsCursorXY Function Verify whether Cursor XY Position feature is supported. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 994 File plib_glcd.h C bool PLIB_GLCD_ExistsCursorXY(GLCD_MODULE_ID index); Returns • true - The Cursor Position feature is supported. • false - The Cursor Position feature is not supported. Description This function verifies whether Cursor XY Position feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsCursorXY( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_CursorXYSet( GLCD_MODULE_ID_0, MY_CURSOR_POSITION_X_VALUE, MY_CURSOR_POSITION_Y_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsCursorXY( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsDESignalLevel Function Verify whether DE Signal Level feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsDESignalLevel(GLCD_MODULE_ID index); Returns • true - The DE Signal Level feature is supported. • false - The DE Signal Level feature is not supported. Description This function verifies whether DE Signal Level feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsDESignalLevel( GLCD_MODULE_ID_0 ) ) { if( PLIB_GLCD_DESignalLevelGet( GLCD_MODULE_ID_0 ) ) { Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 995 // DE Signal Level High } } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsDESignalLevel( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsDithering Function Verifies whether the Dithering feature exists. File plib_glcd.h C bool PLIB_GLCD_ExistsDithering(GLCD_MODULE_ID index); Returns • true - The Dithering feature is supported on the device • false - The Dithering feature is not supported on the device Description This function verifies whether the Dithering feature exists. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_ExistsDithering( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_DitheringEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsDithering( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsEnable Function Identifies whether the GLCD Enable feature exists on the GLCD module. File plib_glcd.h C bool PLIB_GLCD_ExistsEnable(GLCD_MODULE_ID index); Returns • true - The GLCD Enable feature is supported on the device • false - The GLCD Enable feature is not supported on the device Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 996 Description This function identifies whether the GLCD Enable feature is available on the GLCD module. When this function returns true, these functions are supported on the device: • PLIB_GLCD_Enable • PLIB_GLCD_Disable Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_ExistsEnable( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_Enable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier for the device instance Function bool PLIB_GLCD_ExistsEnable ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsForceOutputBlank Function Verify whether Force Output Blank feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsForceOutputBlank(GLCD_MODULE_ID index); Returns • true - The force output blank feature supported • false - The force output blank feature not supported Description This function verifies whether Force Output Blank feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsForceOutputBlank( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_ForceOutputBlankEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsForceOutputBlank( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 997 PLIB_GLCD_ExistsFormattingClockDivide Function Verify whether Clock Formatting feature is available. File plib_glcd.h C bool PLIB_GLCD_ExistsFormattingClockDivide(GLCD_MODULE_ID index); Returns • true - The Clock formatting feature is supported. • false - The Clock formatting feature is not supported. Description This function verifies whether Clock formatting feature is available. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsFormattingClockDivide( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_FormattingClockDivideEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsFormattingClockDivide( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsFrontPorchXY Function Verify whether Front Porch Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsFrontPorchXY(GLCD_MODULE_ID index); Returns • true - The Front Porch feature is supported. • false - The Front Porch feature is not supported. Description This funtion verifies whether Front Porch Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsFrontPorchXY( GLCD_MODULE_ID_0 ) ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 998 { PLIB_GLCD_FrontPorchXYSet( GLCD_MODULE_ID_0, MY_FRONT_PORCH_X_VALUE, MY_FRONT_PORCH_Y_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsFrontPorchXY( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsGlobalColorLUT Function Verify whether Global Color LUT feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsGlobalColorLUT(GLCD_MODULE_ID index); Returns • true - The Global Color LUT feature is supported. • false - The Global Color LUT feature is not supported. Description This function verifies whether Global Color LUT feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsGlobalColorLUT( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_GlobalColorLUTSet( GLCD_MODULE_ID_0, MY_GLOBAL_LUT_POINTER_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsGlobalColorLUT( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsHSyncInterruptEnable Function Verify whether the HSYNC Interrupt Enable feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsHSyncInterruptEnable(GLCD_MODULE_ID index); Returns • true - The HSYNC Interrupt Enable feature is supported. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 999 • false - The HSYNC Interrupt Enable feature is not supported. Description This function verifies whether the HSYNC Interrupt Enable feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsHSyncInterruptEnable( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_HSyncInterruptEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsHSyncInterruptEnable( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsHSyncSignalLevel Function Verify whether HSYNC Signal Level feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsHSyncSignalLevel(GLCD_MODULE_ID index); Returns • true - The HSYNC Signal Level feature is supported. • false - The HSYNC Signal Level feature is not supported. Description This function verifies whether the HSYNC Signal Level feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsHSyncSignalLevel( GLCD_MODULE_ID_0 ) ) { if( PLIB_GLCD_HSyncSignalLevelGet( GLCD_MODULE_ID_0 ) ) { // HSYNC Signal Level High } } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsHSyncSignalLevel( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1000 PLIB_GLCD_ExistsIRQTriggerControl Function Verify whether the IRQ Trigger Control feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsIRQTriggerControl(GLCD_MODULE_ID index); Returns • true - The IRQ Trigger Control feature is supported. • false - The IRQ Trigger Control feature is not supported. Description This function verifies whether the IRQ Trigger Control feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsIRQTriggerControl( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_IRQTriggerControlSet( GLCD_MODULE_ID_0, MY_IRQ_TRIGGER_CONTROL ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsIRQTriggerControl( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsIsLastRow Function Verify whether Is Last Row Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsIsLastRow(GLCD_MODULE_ID index); Returns • true - The Is Last Row feature is supported. • false - The Is Last Row feature is not supported. Description This function verifies whether Is Last Row Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1001 Example if( PLIB_GLCD_ExistsIsLastRow( GLCD_MODULE_ID_0 ) ) { if( PLIB_GLCD_IsLastRow( GLCD_MODULE_ID_0 ) ) { // Last row currently displayed } } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsIsLastRow( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsIsVerticalBlankingActive Function Verify whether Is Vertical Blanking Active feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsIsVerticalBlankingActive(GLCD_MODULE_ID index); Returns • true - The Is Vertical Blanking feature is supported. • false - The Is Vertical Blanking feature is not supported. Description This function verifies whether Is Vertical Blanking Active feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsIsVerticalBlankingActive( GLCD_MODULE_ID_0 ) ) { if( PLIB_GLCD_IsVerticalBlankingActive( GLCD_MODULE_ID_0 ) ) { // Vertical Blanking Active } } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsIsVerticalBlankingActive( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerBaseAddress Function Verify whether the Layer Base Address feature is supported. File plib_glcd.h Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1002 C bool PLIB_GLCD_ExistsLayerBaseAddress(GLCD_MODULE_ID index); Returns • true - The Layer Base Address feature is supported. • false - The Layer Base Address feature is not supported. Description This function verifies whether the Layer Base Address feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerBaseAddress( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerBaseAddressSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, MY_LAYER_BASE_ADDRESS_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerBaseAddress ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerBilinearFilterEnable Function Enable Layer Bilinear Filter Feature. File plib_glcd.h C bool PLIB_GLCD_ExistsLayerBilinearFilterEnable(GLCD_MODULE_ID index); Returns • true - The Layer Bilinear Filter feature is supported. • false - The Layer Bilinear Filter feature is not supported. Description This function enables the Layer Bilinear Filter Feature. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerBilinearFilterEnable( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerBilinearFilterEnable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); } Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1003 Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerBilinearFilterEnable ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerColorMode Function Verify whether Layer Color Mode is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsLayerColorMode(GLCD_MODULE_ID index); Returns • true - The Layer Color Mode feature is supported. • false - The Layer Color Mode feature is not supported. Description This function verifies whether Layer Color Mode is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerColorMode( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerColorModeSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, MY_LAYER_COLOR_MODE_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerColorMode ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerDestBlendFunc Function Verify whether Layer Destination Blend Function Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsLayerDestBlendFunc(GLCD_MODULE_ID index); Returns • true - The Layer Destination Blend Function feature is supported. • false - The Layer Destination Blend Function feature is not supported. Description This function verifies whether Layer Destination Blend Function Feature is supported. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1004 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerDestBlendFunc( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerDestBlendFuncSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, MY_LAYER_DEST_BLEND_FUNC_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerDestBlendFunc ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerEnable Function Verify whether Layer Enable Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsLayerEnable(GLCD_MODULE_ID index); Returns • true - The Layer Enable feature is supported. • false - The Layer Enable feature is not supported. Description This function verifies whether Layer enable Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerEnable( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerEnable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerEnable ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerForceWithGlobalAlpha Function Verify whether Layer Force with Global Alpha Feature is supported. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1005 File plib_glcd.h C bool PLIB_GLCD_ExistsLayerForceWithGlobalAlpha(GLCD_MODULE_ID index); Returns • true - The Layer Force Global Alpha feature is supported. • false - The Layer Force Global Alpha feature is not supported. Description This function verifies whether Layer Force with Global Alpha Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerForceWithGlobalAlpha( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerForceWithGlobalAlphaEnable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerForceWithGlobalAlpha ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerGlobalAlpha Function Verify whether Layer Global Alpha Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsLayerGlobalAlpha(GLCD_MODULE_ID index); Returns • true - The Layer Global Alpha feature is supported. • false - The Layer Global Alpha feature is not supported. Description This function verifies whether Layer Global Alpha Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerGlobalAlpha( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerGlobalAlphaSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, MY_LAYER_GLOBAL_ALPHA_VALUE ); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1006 } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerGlobalAlpha( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerPreMultiplyImageAlpha Function Verify whether Layer Pre-Multiply Image Alpha Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsLayerPreMultiplyImageAlpha(GLCD_MODULE_ID index); Returns • true - The Layer Pre-Multiply Image Alpha feature is supported. • false - The Layer Pre-Multiply Image Alpha feature is not supported. Description This function verifies whether Layer Pre-Multiply Image Alpha Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerPreMultiplyImageAlpha( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerPreMultiplyImageAlphaEnable( GLCD_MODULE_ID_0, GLCD_LAYER_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerPreMultiplyImageAlpha ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerResXY Function File plib_glcd.h C bool PLIB_GLCD_ExistsLayerResXY(GLCD_MODULE_ID index); Returns • true - The Layer Resolution feature is supported. • false - The Layer Resolution feature is not supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1007 Preconditions None. Example if( PLIB_GLCD_ExistsLayerResXY( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerResXYSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, MY_LAYER_RES_X_VALUE, MY_LAYER_RES_Y_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerResXY( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerSizeXY Function Verify whether Layer X Axis and Y Axis Size feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsLayerSizeXY(GLCD_MODULE_ID index); Returns • true - The Layer Size feature is supported. • false - The Layer Size feature is not supported. Description This function verifies whether Layer X Axis and Y Axis Size feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerSizeXY( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerSizeXYSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, MY_LAYER_SIZE_X_VALUE, MY_LAYER_SIZE_Y_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerSizeXY ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerSrcBlendFunc Function Verify whether Layer Source Blend Function Feature is supported. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1008 File plib_glcd.h C bool PLIB_GLCD_ExistsLayerSrcBlendFunc(GLCD_MODULE_ID index); Returns • true - The Layer Source Blend Function feature is supported. • false - The Layer Source Blend Function feature is not supported. Description This function verifies whether Layer Source Blend Function Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerSrcBlendFunc( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerSrcBlendFuncSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, MY_LAYER_SRC_BLEND_FUNC_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerSrcBlendFunc ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerStartXY Function Verify whether Layer Start XY Position feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsLayerStartXY(GLCD_MODULE_ID index); Returns • true - The Layer Start feature is supported. • false - The Layer Start feature is not supported. Description This function verifies whether Layer Start XY Position feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerStartXY( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerStartXYSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1009 MY_LAYER_START_X_VALUE, MY_LAYER_START_Y_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerStartXY ( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLayerStride Function Verify whether the Layer Stride Feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsLayerStride(GLCD_MODULE_ID index); Returns • true - The Layer Stride feature is supported. • false - The Layer Stride feature is not supported. Description This function verifies whether the Layer Stride Feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLayerStride( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LayerStrideSet( GLCD_MODULE_ID_0, GLCD_LAYER_0, MY_LAYER_STRIDE_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLayerStride( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsLinesPrefetch Function Verify whether Lines Prefetch Set Feature supported. File plib_glcd.h C bool PLIB_GLCD_ExistsLinesPrefetch(GLCD_MODULE_ID index); Returns • true - The Lines Prefetch feature is supported. • false - The Lines Prefetch feature is not supported. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1010 Description This function verifies whether Lines Prefetch Set Feature supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsLinesPrefetch( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_LinesPrefetchSet( GLCD_MODULE_ID_0, MY_LINES_PREFETCH_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsLinesPrefetch( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsPaletteGammaRamp Function Verifies whether the palette / gamma ramp feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsPaletteGammaRamp(GLCD_MODULE_ID index); Returns • true - The palette / gamma ramp enable feature supported. • false - The palette / gamma ramp enable feature not supported. Description This function verifies whether the palette / gamma ramp feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsPaletteGammaRamp( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_PaletteGammaRampEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsPaletteGammaRamp( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1011 PLIB_GLCD_ExistsResolutionXY Function Verify whether YUV Output feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsResolutionXY(GLCD_MODULE_ID index); Returns • true - The Resolution feature is supported. • false - The Resolution feature is not supported. Description This function verifies whether YUV Output feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsResolutionXY( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_ResolutionXYSet( GLCD_MODULE_ID_0, MY_RESOLUTION_X_VALUE, MY_RESOLUTION_Y_VALUE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsYUVOutput( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsRGBSequentialMode Function Verify whether RGB Sequential Mode feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsRGBSequentialMode(GLCD_MODULE_ID index); Returns • true - The RGB Sequential Mode feature is supported. • false - The RGB Sequential Mode feature is not supported. Description This function verifies whether RGB Sequential Mode feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1012 Example if( PLIB_GLCD_ExistsRGBSequentialMode( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_RGBSequentialModeSet( GLCD_MODULE_ID_0, GLCD_RGB_MODE_PARALLEL ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsRGBSequentialMode( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsSignalPolarity Function Verifies whether the Signal Polarity Selection feature exists. File plib_glcd.h C bool PLIB_GLCD_ExistsSignalPolarity(GLCD_MODULE_ID index); Returns • true - Feature exists • false - Feature does not exist Description This function verifies whether the Signal Polarity Selection feature exists. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if ( PLIB_GLCD_ExistsSignalPolarity( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_SignalPolaritySet( GLCD_MODULE_ID_0, GLCD_POLARITY_POSITIVE | GLCD_DE_POLARITY_NEGATIVE ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsSignalPolarity( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsSingleCyclePerLineVsync Function Verifies whether VSYNC on Single cycle Per Line Feature exists. File plib_glcd.h C bool PLIB_GLCD_ExistsSingleCyclePerLineVsync(GLCD_MODULE_ID index); Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1013 Returns • true - The feature: VSYNC on Single Cycle Per Line is supported on the device. • false - The feature: VSYNC on Single Cycle Per Line is not supported on the device. Description This function verifies whether VSYNC on Single cycle Per Line Feature exists. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if(PLIB_GLCD_ExistsSingleCyclePerLineVsync( GLCD_MODULE_ID_0)) { PLIB_GLCD_SingleCyclePerLineVsyncEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsSingleCycleVsync( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsVSyncInterruptEnable Function Verify whether VSYNC Interrupt Enable feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsVSyncInterruptEnable(GLCD_MODULE_ID index); Returns • true - The VSYNC Interrupt Enable feature is supported. • false - The VSYNC Interrupt Enable feature is not supported. Description This function verifies whether VSYNC Interrupt Enable feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsVSyncInterruptEnable( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_VSyncInterruptEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsVSyncInterruptEnable( GLCD_MODULE_ID index ) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1014 PLIB_GLCD_ExistsVSyncSignalLevel Function Verify whether VSYNC Signal Level feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsVSyncSignalLevel(GLCD_MODULE_ID index); Returns • true - The VSYNC Signal Level feature is supported. • false - The VSYNC Signal Level feature is not supported. Description This function verifies whether VSYNC Signal Level feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Example if( PLIB_GLCD_ExistsVSyncSignalLevel( GLCD_MODULE_ID_0 ) ) { if( PLIB_GLCD_VSyncSignalLevelGet( GLCD_MODULE_ID_0 ) ) { // VSYNC Signal Level High } } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsVSyncSignalLevel( GLCD_MODULE_ID index ) PLIB_GLCD_ExistsYUVOutput Function Verify whether YUV output feature is supported. File plib_glcd.h C bool PLIB_GLCD_ExistsYUVOutput(GLCD_MODULE_ID index); Returns • true - The YUV output feature is supported. • false - The YUV output feature is not supported. Description This function verifies whether YUV output feature is supported. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Preconditions None. Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1015 Example if( PLIB_GLCD_ExistsYUVOutput( GLCD_MODULE_ID_0 ) ) { PLIB_GLCD_YUVOutputEnable( GLCD_MODULE_ID_0 ); } Parameters Parameters Description index Identifier of the device instance. Function bool PLIB_GLCD_ExistsYUVOutput( GLCD_MODULE_ID index ) j) Data Types and Constants GLCD_IRQ_TRIGGER_CONTROL Enumeration Possible values of GLCD Interrupt Trigger Mode. File plib_glcd_help.h C typedef enum { GLCD_IRQ_TRIGGER_LEVEL = 0x00000000, GLCD_IRQ_TRIGGER_EDGE = 0x80000000 } GLCD_IRQ_TRIGGER_CONTROL; Members Members Description GLCD_IRQ_TRIGGER_LEVEL = 0x00000000 Interrupt Level Triggered GLCD_IRQ_TRIGGER_EDGE = 0x80000000 Interrupt Edge Triggered Description GLCD Interrupt Trigger Mode This data type defines the possible values of GLCD Interrupt Trigger modes. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). GLCD_LAYER_COLOR_MODE Enumeration Possible values of GLCD color Mode. File plib_glcd_help.h C typedef enum { GLCD_LAYER_COLOR_MODE_LUT8 = 0x0, GLCD_LAYER_COLOR_MODE_RGBA5551 = 0x1, GLCD_LAYER_COLOR_MODE_RGBA8888 = 0x2, GLCD_LAYER_COLOR_MODE_RGB332 = 0x4, GLCD_LAYER_COLOR_MODE_RGB565 = 0x5, GLCD_LAYER_COLOR_MODE_ARGB8888 = 0x6, GLCD_LAYER_COLOR_MODE_L8 = 0x7, GLCD_LAYER_COLOR_MODE_L1 = 0x8, GLCD_LAYER_COLOR_MODE_L4 = 0x9, GLCD_LAYER_COLOR_MODE_YUYV = 0xA, GLCD_LAYER_COLOR_MODE_RGB888 = 0xB } GLCD_LAYER_COLOR_MODE; Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1016 Members Members Description GLCD_LAYER_COLOR_MODE_LUT8 = 0x0 GLCD Layer color mode LUT 8 GLCD_LAYER_COLOR_MODE_RGBA5551 = 0x1 GLCD Layer color mode RGBA 5551 GLCD_LAYER_COLOR_MODE_RGBA8888 = 0x2 GLCD Layer color mode RGBA 8888 GLCD_LAYER_COLOR_MODE_RGB332 = 0x4 GLCD Layer color mode RGB 332 GLCD_LAYER_COLOR_MODE_RGB565 = 0x5 GLCD Layer color mode RGB 565 GLCD_LAYER_COLOR_MODE_ARGB8888 = 0x6 GLCD Layer color mode ARGB 8888 GLCD_LAYER_COLOR_MODE_L8 = 0x7 GLCD Layer color mode L8 GLCD_LAYER_COLOR_MODE_L1 = 0x8 GLCD Layer color mode L1 GLCD_LAYER_COLOR_MODE_L4 = 0x9 GLCD Layer color mode L4 GLCD_LAYER_COLOR_MODE_YUYV = 0xA GLCD Layer color mode YUYV GLCD_LAYER_COLOR_MODE_RGB888 = 0xB GLCD Layer color mode RGB888 Description GLCD Layer color Mode This data type defines the possible values of GLCD Layer color modes. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). GLCD_LAYER_DEST_BLEND_FUNC Enumeration Possible values of GLCD Layer Destination Blend Functions. File plib_glcd_help.h C typedef enum { GLCD_LAYER_DEST_BLEND_BLACK = 0x0000, GLCD_LAYER_DEST_BLEND_WHITE = 0x1000, GLCD_LAYER_DEST_BLEND_ALPHA_SRC = 0x2000, GLCD_LAYER_DEST_BLEND_ALPHA_GBL = 0x3000, GLCD_LAYER_DEST_BLEND_ALPHA_SRCGBL = 0x4000, GLCD_LAYER_DEST_BLEND_INV_SRC = 0x5000, GLCD_LAYER_DEST_BLEND_INV_GBL = 0x6000, GLCD_LAYER_DEST_BLEND_INV_SRCGBL = 0x7000, GLCD_LAYER_DEST_BLEND_ALPHA_DST = 0xA000, GLCD_LAYER_DEST_BLEND_INV_DST = 0xD000 } GLCD_LAYER_DEST_BLEND_FUNC; Members Members Description GLCD_LAYER_DEST_BLEND_BLACK = 0x0000 Layer Destination Blend Function: Black, Destination Alpha = 0 GLCD_LAYER_DEST_BLEND_WHITE = 0x1000 Layer Destination Blend Function: White, Destination Alpha = 255 GLCD_LAYER_DEST_BLEND_ALPHA_SRC = 0x2000 Layer Destination Blend Function: Source Alpha GLCD_LAYER_DEST_BLEND_ALPHA_GBL = 0x3000 Layer Destination Blend Function: Global Alpha GLCD_LAYER_DEST_BLEND_ALPHA_SRCGBL = 0x4000 Layer Destination Blend Function: (Source Alpha * Global Alpha) GLCD_LAYER_DEST_BLEND_INV_SRC = 0x5000 Layer Destination Blend Function: (1 - Source Alpha) GLCD_LAYER_DEST_BLEND_INV_GBL = 0x6000 Layer Destination Blend Function: (1 - Global Alpha) GLCD_LAYER_DEST_BLEND_INV_SRCGBL = 0x7000 Layer Destination Blend Function: (1 - (Source Alpha * Global Alpha)) Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1017 GLCD_LAYER_DEST_BLEND_ALPHA_DST = 0xA000 Layer Destination Blend Function: Destination Alpha GLCD_LAYER_DEST_BLEND_INV_DST = 0xD000 Layer Destination Blend Function: (1 - Destination Alpha) Description GLCD Layer Destination Blend Function This data type defines the possible values of GLCD Layer Destination Blend Functions. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). GLCD_LAYER_ID Enumeration Possible values of GLCD Layer Ids File plib_glcd_help.h C typedef enum { GLCD_LAYER_ID_0 = 0x0, GLCD_LAYER_ID_1 = 0x1, GLCD_LAYER_ID_2 = 0x2, GLCD_LAYER_ID_MAX = 0x3 } GLCD_LAYER_ID; Members Members Description GLCD_LAYER_ID_0 = 0x0 GLCD Layer 0 Id GLCD_LAYER_ID_1 = 0x1 GLCD Layer 1 Id GLCD_LAYER_ID_2 = 0x2 GLCD Layer 2 Id GLCD_LAYER_ID_MAX = 0x3 Maximum number of Layers supported by GLCD Description GLCD Layer Ids This data type defines the possible values of GLCD Layer Ids. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). GLCD_LAYER_SRC_BLEND_FUNC Enumeration Possible values of GLCD Layer Source Blend Functions. File plib_glcd_help.h C typedef enum { GLCD_LAYER_SRC_BLEND_BLACK = 0x0000, GLCD_LAYER_SRC_BLEND_WHITE = 0x0100, GLCD_LAYER_SRC_BLEND_ALPHA_SRC = 0x0200, GLCD_LAYER_SRC_BLEND_ALPHA_GBL = 0x0300, GLCD_LAYER_SRC_BLEND_ALPHA_SRCGBL = 0x0400, GLCD_LAYER_SRC_BLEND_INV_SRC = 0x0500, GLCD_LAYER_SRC_BLEND_INV_GBL = 0x0600, GLCD_LAYER_SRC_BLEND_INV_SRCGBL = 0x0700, GLCD_LAYER_SRC_BLEND_ALPHA_DST = 0x0A00, GLCD_LAYER_SRC_BLEND_INV_DST = 0x0D00 } GLCD_LAYER_SRC_BLEND_FUNC; Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1018 Members Members Description GLCD_LAYER_SRC_BLEND_BLACK = 0x0000 Layer Source Blend Function: Black, Source Alpha = 0 GLCD_LAYER_SRC_BLEND_WHITE = 0x0100 Layer Source Blend Function: White, Source Alpha = 255 GLCD_LAYER_SRC_BLEND_ALPHA_SRC = 0x0200 Layer Source Blend Function: Source Alpha GLCD_LAYER_SRC_BLEND_ALPHA_GBL = 0x0300 Layer Source Blend Function: Global Alpha GLCD_LAYER_SRC_BLEND_ALPHA_SRCGBL = 0x0400 Layer Source Blend Function: (Source Alpha * Global Alpha) GLCD_LAYER_SRC_BLEND_INV_SRC = 0x0500 Layer Source Blend Function: (1 - Source Alpha) GLCD_LAYER_SRC_BLEND_INV_GBL = 0x0600 Layer Source Blend Function: (1 - Global Alpha) GLCD_LAYER_SRC_BLEND_INV_SRCGBL = 0x0700 Layer Source Blend Function: (1 - (Source Alpha * Global Alpha)) GLCD_LAYER_SRC_BLEND_ALPHA_DST = 0x0A00 Layer Source Blend Function: Destination Alpha GLCD_LAYER_SRC_BLEND_INV_DST = 0x0D00 Layer Source Blend Function: (1 - Destination Alpha) Description GLCD Layer Source Blend Function This data type defines the possible values of GLCD Layer Source Blend Functions. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). GLCD_MODULE_ID Enumeration Possible instances of the GLCD module File plib_glcd_help.h C typedef enum { GLCD_ID_0 = 0, GLCD_NUMBER_OF_MODULES } GLCD_MODULE_ID; Members Members Description GLCD_ID_0 = 0 first instance of the GLCD GLCD_NUMBER_OF_MODULES number of GLCD modules Description GLCD module ID This data type defines the possible instances of the GLCD module. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). GLCD_RGB_MODE Enumeration GLCD RGB Sequential Mode File plib_glcd_help.h Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1019 C typedef enum { GLCD_RGB_MODE_PARALLEL_RGB565 = 0x00000000, GLCD_RGB_MODE_PARALLEL_RGB888 = 0x00000001, GLCD_RGB_MODE_SERIAL_RGB_3 = 0x00000002, GLCD_RGB_MODE_SERIAL_RGBA_4 = 0x00000003, GLCD_RGB_MODE_SERIAL_12BIT = 0x00000004, GLCD_RGB_MODE_YUYV_16BIT = 0x00000005, GLCD_RGB_MODE_BT_656 = 0x00000006 } GLCD_RGB_MODE; Members Members Description GLCD_RGB_MODE_PARALLEL_RGB565 = 0x00000000 Parallel RGB 565 Mode GLCD_RGB_MODE_PARALLEL_RGB888 = 0x00000001 Parallel RGB 888 Mode GLCD_RGB_MODE_SERIAL_RGB_3 = 0x00000002 Byte Serial RGB 3 Mode GLCD_RGB_MODE_SERIAL_RGBA_4 = 0x00000003 Byte Serial RGB 4 Mode GLCD_RGB_MODE_SERIAL_12BIT = 0x00000004 Byte Two-Phase 12-bit Mode GLCD_RGB_MODE_YUYV_16BIT = 0x00000005 YUYV 16 bit Mode GLCD_RGB_MODE_BT_656 = 0x00000006 BT 656 Mode Description GLCD RGB Sequential Mode This data type defines the possible RGB Sequential Mode of GLCD. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). GLCD_SIGNAL_POLARITY Enumeration Polarity values of different output signals. File plib_glcd_help.h C typedef enum { GLCD_POLARITY_POSITIVE = 0x00000000, GLCD_PIXEL_CLOCK_POLARITY_NEGATIVE = 0x00400000, GLCD_DE_POLARITY_NEGATIVE = 0x04000000, GLCD_HSYNC_POLARITY_NEGATIVE = 0x08000000, GLCD_VSYNC_POLARITY_NEGATIVE = 0x10000000 } GLCD_SIGNAL_POLARITY; Members Members Description GLCD_POLARITY_POSITIVE = 0x00000000 Positive polarity of PCLK, DE, HSYNC and VSYNC pins GLCD_PIXEL_CLOCK_POLARITY_NEGATIVE = 0x00400000 Negative Pixel Clock Pin Polarity GLCD_DE_POLARITY_NEGATIVE = 0x04000000 Negative DE Pin Polarity GLCD_HSYNC_POLARITY_NEGATIVE = 0x08000000 Negative HSYNC Pin Polarity GLCD_VSYNC_POLARITY_NEGATIVE = 0x10000000 Negative VSYNC Pin Polarity Description GLCD Output Signal Polarity Peripheral Libraries Help GLCD Controller Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1020 This data type defines the polarity values of different output signals. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). Files Files Name Description plib_glcd.h Defines the Graphics LCD Controller (GLCD) Peripheral Library Interface. Description This section lists the source and header files used by the library. plib_glcd.h Defines the Graphics LCD Controller (GLCD) Peripheral Library Interface. Functions Name Description PLIB_GLCD_BackgroundColorGet Gets the value of the Background Color. PLIB_GLCD_BackgroundColorSet Sets the background color. PLIB_GLCD_BackPorchXGet Gets X Axis Back Porch. PLIB_GLCD_BackPorchXYSet Sets the back porch on the x and y axis for the Graphics LCD Controller. PLIB_GLCD_BackPorchYGet Gets Y Axis Back Porch. PLIB_GLCD_BlankingXGet Gets the X Axis Blanking Period. PLIB_GLCD_BlankingXYSet Sets the blanking period on the x and y axis of the Graphics LCD Controller. PLIB_GLCD_BlankingYGet Gets the Y Axis Blanking Period. PLIB_GLCD_ClockDividerGet Gets Clock Divider value. PLIB_GLCD_ClockDividerSet Sets clock controls of the Graphics LCD Controller. PLIB_GLCD_CursorDataGet Gets the Cursor Data at given Index. PLIB_GLCD_CursorDataSet Sets the cursor image data. PLIB_GLCD_CursorDisable Disables the cursor of the Graphics LCD Controller. PLIB_GLCD_CursorEnable Enables the cursor of the Graphics LCD Controller. PLIB_GLCD_CursorIsEnabled Verifies whether the cursor is enabled. PLIB_GLCD_CursorLUTGet Gets the color from Cursor LUT at given Index. PLIB_GLCD_CursorLUTSet Sets the cursor color look-up table (LUT) in XRGB8888 format. PLIB_GLCD_CursorXGet Gets the cursor X Axis Position. PLIB_GLCD_CursorXYSet Sets the x and y coordinates of the Graphics LCD Controller cursor. PLIB_GLCD_CursorYGet Gets the Cursor Y Axis Position. PLIB_GLCD_DESignalLevelGet Gets the display enable signal level. PLIB_GLCD_Disable Disables the Graphics LCD Controller. PLIB_GLCD_DitheringDisable Disables the Dithering feature of the Graphics LCD Controller. PLIB_GLCD_DitheringEnable Enables the Dithering feature of the Graphics LCD Controller. PLIB_GLCD_DitheringIsEnabled Verifies whether Dithering is enabled. PLIB_GLCD_Enable Enables the Graphics LCD Controller. PLIB_GLCD_ExistsBackgroundColor Verify whether the Background Color Feature is supported. PLIB_GLCD_ExistsBackPorchXY Verify whether Back Porch Feature is supported. PLIB_GLCD_ExistsBlankingXY Verify whether Blanking Period Feature is supported. PLIB_GLCD_ExistsClockDivider Verify whether the Clock Divider feature is supported. PLIB_GLCD_ExistsCursor Verifies whether the cursor feature exists. PLIB_GLCD_ExistsCursorData PLIB_GLCD_ExistsCursorLUT Verify whether Cursor LUT feature is supported. PLIB_GLCD_ExistsCursorXY Verify whether Cursor XY Position feature is supported. PLIB_GLCD_ExistsDESignalLevel Verify whether DE Signal Level feature is supported. PLIB_GLCD_ExistsDithering Verifies whether the Dithering feature exists. Peripheral Libraries Help GLCD Controller Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1021 PLIB_GLCD_ExistsEnable Identifies whether the GLCD Enable feature exists on the GLCD module. PLIB_GLCD_ExistsForceOutputBlank Verify whether Force Output Blank feature is supported. PLIB_GLCD_ExistsFormattingClockDivide Verify whether Clock Formatting feature is available. PLIB_GLCD_ExistsFrontPorchXY Verify whether Front Porch Feature is supported. PLIB_GLCD_ExistsGlobalColorLUT Verify whether Global Color LUT feature is supported. PLIB_GLCD_ExistsHSyncInterruptEnable Verify whether the HSYNC Interrupt Enable feature is supported. PLIB_GLCD_ExistsHSyncSignalLevel Verify whether HSYNC Signal Level feature is supported. PLIB_GLCD_ExistsIRQTriggerControl Verify whether the IRQ Trigger Control feature is supported. PLIB_GLCD_ExistsIsLastRow Verify whether Is Last Row Feature is supported. PLIB_GLCD_ExistsIsVerticalBlankingActive Verify whether Is Vertical Blanking Active feature is supported. PLIB_GLCD_ExistsLayerBaseAddress Verify whether the Layer Base Address feature is supported. PLIB_GLCD_ExistsLayerBilinearFilterEnable Enable Layer Bilinear Filter Feature. PLIB_GLCD_ExistsLayerColorMode Verify whether Layer Color Mode is supported. PLIB_GLCD_ExistsLayerDestBlendFunc Verify whether Layer Destination Blend Function Feature is supported. PLIB_GLCD_ExistsLayerEnable Verify whether Layer Enable Feature is supported. PLIB_GLCD_ExistsLayerForceWithGlobalAlpha Verify whether Layer Force with Global Alpha Feature is supported. PLIB_GLCD_ExistsLayerGlobalAlpha Verify whether Layer Global Alpha Feature is supported. PLIB_GLCD_ExistsLayerPreMultiplyImageAlpha Verify whether Layer Pre-Multiply Image Alpha Feature is supported. PLIB_GLCD_ExistsLayerResXY PLIB_GLCD_ExistsLayerSizeXY Verify whether Layer X Axis and Y Axis Size feature is supported. PLIB_GLCD_ExistsLayerSrcBlendFunc Verify whether Layer Source Blend Function Feature is supported. PLIB_GLCD_ExistsLayerStartXY Verify whether Layer Start XY Position feature is supported. PLIB_GLCD_ExistsLayerStride Verify whether the Layer Stride Feature is supported. PLIB_GLCD_ExistsLinesPrefetch Verify whether Lines Prefetch Set Feature supported. PLIB_GLCD_ExistsPaletteGammaRamp Verifies whether the palette / gamma ramp feature is supported. PLIB_GLCD_ExistsResolutionXY Verify whether YUV Output feature is supported. PLIB_GLCD_ExistsRGBSequentialMode Verify whether RGB Sequential Mode feature is supported. PLIB_GLCD_ExistsSignalPolarity Verifies whether the Signal Polarity Selection feature exists. PLIB_GLCD_ExistsSingleCyclePerLineVsync Verifies whether VSYNC on Single cycle Per Line Feature exists. PLIB_GLCD_ExistsVSyncInterruptEnable Verify whether VSYNC Interrupt Enable feature is supported. PLIB_GLCD_ExistsVSyncSignalLevel Verify whether VSYNC Signal Level feature is supported. PLIB_GLCD_ExistsYUVOutput Verify whether YUV output feature is supported. PLIB_GLCD_ForceOutputBlankDisable Disable Force Output Blank feature. PLIB_GLCD_ForceOutputBlankEnable Enable Force Output Blank feature. PLIB_GLCD_ForceOutputBlankIsEnabled Verify whether the Force Output Blank feature is enabled. PLIB_GLCD_FormattingClockDivideDisable Disbale the Clock Formatting feature. PLIB_GLCD_FormattingClockDivideEnable Enable the Clock Formatting feature. PLIB_GLCD_FormattingClockDivideIsEnabled Verify whether Clock Formatting feature is enabled. PLIB_GLCD_FrontPorchXGet Gets X Axis Front Porch. PLIB_GLCD_FrontPorchXYSet Sets the front porch on the x and y axis for the Graphics LCD Controller. PLIB_GLCD_FrontPorchYGet Gets Y Axis Front Porch. PLIB_GLCD_GlobalColorLUTGet Gets the Color from Global Color LUT at given Index. PLIB_GLCD_GlobalColorLUTSet Set Global Color LUT. PLIB_GLCD_HSyncInterruptDisable Disables interrupts at Hsync. PLIB_GLCD_HSyncInterruptEnable Enables interrupts at Hsync. PLIB_GLCD_HSyncInterruptIsEnabled Verify whether HSYNC Interrupt is enabled. PLIB_GLCD_HSyncSignalLevelGet Gets the Hsync signal level. PLIB_GLCD_IRQTriggerControlGet Gets the IRQ Trigger Control value. PLIB_GLCD_IRQTriggerControlSet Sets the IRQ trigger control. PLIB_GLCD_IsEnabled Verifies whether the Graphics LCD Controller is Enabled. PLIB_GLCD_IsLastRow Gets the status indicating whether a last row is currently displayed by the Graphics Display Controller. PLIB_GLCD_IsVerticalBlankingActive Get the active status. PLIB_GLCD_LayerBaseAddressGet Gets the Layer Base Address. PLIB_GLCD_LayerBaseAddressSet Sets the base address of layer surface of the Graphics LCD Controller. Peripheral Libraries Help GLCD Controller Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1022 PLIB_GLCD_LayerBilinearFilterDisable Disables the layer Bilinear filter of the Graphics LCD Controller. PLIB_GLCD_LayerBilinearFilterEnable Enables the layer Bilinear filter of the Graphics LCD Controller. PLIB_GLCD_LayerBilinearFilterIsEnabled Verify whether Layer Bilinear Filter is enabled. PLIB_GLCD_LayerColorModeGet Gets the Layer Color Mode. PLIB_GLCD_LayerColorModeSet Sets the layer color mode of the Graphics LCD Controller. PLIB_GLCD_LayerDestBlendFuncGet Gets the Layer Destination Blend Function. PLIB_GLCD_LayerDestBlendFuncSet Sets the layer destination blend function of the Graphics LCD Controller. PLIB_GLCD_LayerDisable Disables the layer of the Graphics LCD Controller. PLIB_GLCD_LayerEnable Enables the layer of the Graphics LCD Controller. PLIB_GLCD_LayerForceWithGlobalAlphaDisable Disables the Layer Force Global Alpha feature. PLIB_GLCD_LayerForceWithGlobalAlphaEnable Enable the Layer Force Global Alpha feature. PLIB_GLCD_LayerForceWithGlobalAlphaIsEnabled Verify whether Layer Force with Global Alpha Feature is enabled. PLIB_GLCD_LayerGlobalAlphaGet Gets the Layer Global Alpha value. PLIB_GLCD_LayerGlobalAlphaSet Sets the layer global alpha of the Graphics LCD Controller. PLIB_GLCD_LayerIsEnabled Verify whether Layer is enabled. PLIB_GLCD_LayerPreMultiplyImageAlphaDisable Disable Layer Pre-Multiply Image Alpha Feature. PLIB_GLCD_LayerPreMultiplyImageAlphaEnable Enable Layer Pre-Multiply Image Alpha Feature. PLIB_GLCD_LayerPreMultiplyImageAlphaIsEnabled Verify whether the Layer Pre-Multiply Image Alpha Feature is enabled. PLIB_GLCD_LayerResXGet Gets the Layer X Axis Resolution. PLIB_GLCD_LayerResXYSet Sets the layer resolution in pixels. PLIB_GLCD_LayerResYGet Gets the Layer Y Axis Resolution. PLIB_GLCD_LayerSizeXGet Gets the Layer X Axis Size. PLIB_GLCD_LayerSizeXYSet Sets the layer size x and size y of the Graphics LCD Controller. PLIB_GLCD_LayerSizeYGet Gets the Layer Y Axis Size. PLIB_GLCD_LayerSrcBlendFuncGet Gets the Layer Source Blend Function. PLIB_GLCD_LayerSrcBlendFuncSet Sets the layer source blend function of the Graphics LCD Controller. PLIB_GLCD_LayerStartXGet Gets the Layer X Axis Start Position. PLIB_GLCD_LayerStartXYSet Sets the layer start x and start y of the Graphics LCD Controller. PLIB_GLCD_LayerStartYGet Gets the Layer Y Axis Start Position. PLIB_GLCD_LayerStrideGet Gets the Layer Stride value. PLIB_GLCD_LayerStrideSet Sets the layer surface stride of the Graphics LCD Controller. PLIB_GLCD_LinesPrefetchGet Gets value of lines to be prefetched. PLIB_GLCD_LinesPrefetchSet Sets the clock controls of the Graphics LCD Controller. PLIB_GLCD_PaletteGammaRampDisable Disables the palette / gamma ramp of the Graphics LCD Controller. PLIB_GLCD_PaletteGammaRampEnable Enables the palette / gamma ramp of the Graphics LCD Controller. PLIB_GLCD_PaletteGammaRampIsEnabled Verify whether Palette / Gamma Ramp feature is enabled. PLIB_GLCD_ResolutionXGet Gets X Axis Resolution. PLIB_GLCD_ResolutionXYSet Sets the display resolution for the Graphics LCD Controller. PLIB_GLCD_ResolutionYGet Gets Y Axis Resolution. PLIB_GLCD_RGBSequentialModeGet Get the RGB Sequential Mode already set. PLIB_GLCD_RGBSequentialModeSet Sets the RGB output sequential mode. PLIB_GLCD_SignalPolarityGet Gets the polarity of the pixel clock, DE, HSync and VSync pin of the Graphics LCD Controller. PLIB_GLCD_SignalPolaritySet Sets the polarity of the pixel clock, DE, HSync and VSync pin of the Graphics LCD Controller. PLIB_GLCD_SingleCyclePerLineVsyncDisable Clears VSYNC on single cycle per line. PLIB_GLCD_SingleCyclePerLineVsyncEnable Sets VSYNC on single cycle per line. PLIB_GLCD_SingleCyclePerLineVsyncIsEnabled Verify whether VSYNC on Single Cycle Per Line feature is enabled. PLIB_GLCD_VSyncInterruptDisable Disables interrupts at Vsync. PLIB_GLCD_VSyncInterruptEnable Enables interrupts at Vsync. PLIB_GLCD_VSyncInterruptIsEnabled Verify whether VSYNC Interrupt is enabled. PLIB_GLCD_VSyncSignalLevelGet Gets the Vsync signal level. PLIB_GLCD_YUVOutputDisable Disables the output of the Graphics LCD Controller in YUV format. PLIB_GLCD_YUVOutputEnable Enables the output of the Graphics LCD Controller in YUV format. PLIB_GLCD_YUVOutputIsEnabled Verify whether the YUV Output feature is enabled. Peripheral Libraries Help GLCD Controller Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1023 Description Graphics LCD Controller (GLCD) Peripheral Library Interface Header. This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Graphics LCD Controller Peripheral Library for Microchip micro-controllers. The definitions in this file are only for the directly addressable memory mapped Graphics LCD Controller module. File Name plib_glcd.h Company Microchip Technology Inc. Peripheral Libraries Help GLCD Controller Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1024 I2C Peripheral Library This section describes the Inter-Integrated Circuit (I2C) Peripheral Library. Introduction This library provides a low-level abstraction of the Inter-Integrated Circuit (I2C) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description The I2C module is a serial interface useful for communicating with other peripheral or microcontroller devices. These peripheral devices may be serial EEPROMs, display drivers, analog-to-digital converters, etc. Please refer to the I2C-Bus Specification (v2.1), available from Philips Semiconductor (see the following Note) for complete details on the operation and requirements for the I2C bus. Note: Trademarks and Intellectual Property are property of their respective owners. Customers are responsible for obtaining appropriate licensing or rights before using this software. Refer to the MPLAB Harmony Software License Agreement for complete licensing information. A copy of this agreement is available in the /doc folder of your MPLAB Harmony installation. Using the Library This topic describes the basic architecture of the I2C Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_i2c.h The interface to the I2C library is defined in the plib_i2c.h header file, which is included by the peripheral library header file,peripheral.h. Any C language source (.c) file that uses the I2C library must include peripheral.h. Peripheral Module IDs Peripheral libraries are indexed to allow a single library to control any number of instances of a peripheral in a single microcontroller. To support this, the first parameter to each operation in a peripheral library is the module instance ID. The module instance ID is defined by an enumeration that is defined in the processor-specific header files (included by the library's interface header). For the I2C Peripheral Library, the module instance IDs are defined by the I2C_MODULE_ID enumeration. Not all microcontrollers will have all instances of the module listed in this enumeration. Please refer to the specific device data sheet for more information. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1025 Hardware Abstraction Model This library provides a low-level abstraction of the Inter-Integrated Circuit (I2C) module on Microchip PIC microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model Description The I2C Peripheral Library provides interface routines to interact with the blocks shown in the following diagram. Hardware Abstraction Model Diagram The TX Buffer and RX Buffer are 1-byte (8-bit) buffers for data transmitted (TX) or received (RX) by the Serial Interface to the I2C bus over the SDA line synchronized with the SCL line by the Clock Control logic. The desired baud rate frequency can be programmed in the Clock Control logic (within I2C bus specifications of 0-100 kHz for Low-to-Fast I2C mode and up to 3.4 MHz for High-Speed I2C mode) by setting the Baud Rate value. However, the nature of the I2C bus allows slower targets to stretch the clock to slower rates as required, in real time. The I2C bus is a transfer-based multi-master bus, allowing multiple masters to initiate transfers at any time the bus is not currently busy. The Master Arbiter logic monitors transfers and determines if arbitration has been lost. There is no loss of data for the winning master. However, the losing master must retry the entire transfer again later, when the bus is idle. Slave devices are identified by either 7- or-10 bit addresses. The I2C module can act as either a bus master that can initiate transfers or as a slave, responding to transfers initiated by other masters on the bus. The Slave Address Detect logic monitors transfers initiated by other masters to recognize when other masters have addressed this module when it is acting as a slave. The Slave Address is programmed into the I2C module by the software along with an (optional) address Mask, specifying bits in the address that can be ignored. This ability to "mask off" certain bits in the address allows the I2C module to identify multiple addresses and respond as if it were more than one slave device. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the I2C module. Library Interface Section Description General Initialization Functions Provides configuration routines for: • Slave Mode Clock Stretching • General Call and Other Reserved Address Support • System Management Bus (SMBus) support • High Frequency Support • Stop-in-Idle Control • Module Enable/Disable Control Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1026 General Status Functions Provides status routines for I2C bus conditions. Baud Rate Generator Control Functions Provides configuration and access routines for baud rate control. Slave Address Control Functions Provides configuration, access, and status routines for control of the slave address to which the I2C module will respond when operating in Slave mode. Slave Mask Control Functions Provides configuration and access routines for control of the "ignore" bit mask for slave addressing. The "ignore" mask determines which bits in the incoming transfer's address are ignored, allowing the module to respond to multiple I2C addresses when operating in slave mode. Note: This feature is not available on all devices. Refer to the specific device data sheet determine whether slave address masking is supported for your device. Slave Control Functions Provides status and control routines for operating in slave mode (either as a receiver or as a transmitter). Master Control Functions Provides routines for control of the module when operating in master mode (either as a receiver or as a transmitter). Note: The necessary status routines are either part of the general, transmitter, or receiver groups depending on their purpose. Transmitter Control Functions Provides control, status, and data transfer routines for transmitting data (either as a master or a slave). Receiver Control Functions Provides control, status, and data transfer routines for receiving data (either as a master or a slave). Feature Existence Functions Determine whether particular features exist on a device. How the Library Works Provides information on how the library works. Description Before enabling the I2C module the caller must initialize basic configuration, clock frequency, and Slave address recognition features (see Initializing the I2C). After the module has been enabled, it can begin monitoring the bus as a slave device waiting to be addressed by an external master (see Operating as a Slave Receiver). A slave device only transfers data on the bus when it has been addressed by a master (see Operating as a Slave Transmitter). If the module is used to start a transfer, it is operating as a master. A master addresses a slave and controls the transfer of data by providing the clock (see Operating as a Master Transmitter and Operating as a Master Receiver). Some operations in the I2C library initiate actions on the I2C bus that require time to complete. Also, some events occur asynchronously on the bus. In each of these cases, the module causes either a "master", "slave", or "error" interrupt. Interrupt State Machine describes the different states that can cause an interrupt and show what causes the transition from one state to another. Handling Errors describes the various errors that can occur and how to deal with them. Data transfers on the I2C bus must follow specific formats defined by the I2C bus protocol. (Refer to Forming Transfers for details) Note: The I2C peripheral library does not directly respond to interrupts. The client software (usually a driver, middleware_layer, or application) should implement the Interrupt Service Routine (ISR) and call the I2C library's interface routines from that ISR to manage the state of the I2C module. Usage Model The following diagram illustrates the library usage model for the I2C Peripheral Library. Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1027 Initializing the I2C To initialize the I2C module, perform the following sequence: 1. Select the desired general configuration options using General Initialization Functions (see the Library Interface section) to select the desired operation of the following features: • Slave Clock Stretching • General Call Address Recognition • System Management Bus (SMBus) Support • High Frequency Operation • Reserved Address Protection • Stop-in-Idle Operation 2. Program the Baud Rate Generator to set the desired baud rate using the PLIB_I2C_BaudRateSet function. 3. If operating in slave mode, set the desired slave address using the PLIB_I2C_SlaveAddress7BitSet function (for 7-bit mode operation) or PLIB_I2C_SlaveAddress10BitSet function (for 10-bit mode operation). 4. If running in an interrupt-driven environment, clear any pending interrupts and enable the appropriate (master, slave, and error) I2C interrupts. Note: Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for more information. 5. Enable the module for operation using the PLIB_I2C_Enable function. Example #define MY_I2C_ID I2C_ID_1 uint32_t actualClock; // Configure General I2C Options PLIB_I2C_SlaveClockStretchingEnable(MY_I2C_ID); PLIB_I2C_GeneralCallEnable(MY_I2C_ID); PLIB_I2C_SMBDisable(MY_I2C_ID); PLIB_I2C_HighFrequencyDisable(MY_I2C_ID); PLIB_I2C_ReservedAddressProtectEnable(MY_I2C_ID); PLIB_I2C_StopInIdleEnable(MY_I2C_ID); // Set Desired baud rate PLIB_I2C_BaudRateSet ( MY_I2C_ID, MY_PERIPHEAL_CLOCK_FREQ, MY_I2C_BAUD_RATE); // Set the appropriate slave address (slave only) PLIB_I2C_SlaveAddress7BitSet(MY_I2C_ID, MY_SLAVE_ADDRESS); // Optional: Clear and enable interrupts before enabling the I2C module. // Enable the module PLIB_I2C_Enable(MY_I2C_ID); Note: Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section referenced by that chapter for more information. Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1028 The previous example uses the following constants: Symbol Description I2C_ID_1 Defined as the selected I2C module value from the I2C Module enumeration. Example: #define MY_I2C_ID I2C_ID_1 MY_I2C_PERIPHERAL_CLOCK Defined as the peripheral clock frequency (in Hz) of the I2C module. Example: #define MY_I2C_PERIPHERAL_CLOCK 80000000 MY_I2C_BAUD_RATE Defined as desired I2C baud rate. Example: #define MY_I2C_BAUD_RATE 100000 MY_SLAVE_ADDRESS Defined as the desired 7-bit I2C slave address. Example: #define 0x1A // Slave address 0011010 in binary Note: If '0' is passed as the mask value, the I2C module will only respond to single slave address passed in the second parameter. Operating as a Slave Receiver Before enabling the module, the module's "local" slave address and mask should be programmed using the PLIB_I2C_SlaveAddress7BitSet function or the PLIB_I2C_SlaveAddress10BitSet function, depending on the desired address width. If slave address masking is supported on the chosen processor the "don't care bits" mask can be set using the PLIB_I2C_SlaveMask7BitSet function or the PLIB_I2C_SlaveMask10BitSet function, also depending on the desired address width. Once the I2C module has been enabled, it will begin waiting for an I2C master to address it. When the programmed local slave address is recognized (ignoring any bits in the programmed mask value, if supported), the module will ACK the address and notify software that it has received an address byte. If the R/W bit of the address is 0, the module enters receive mode automatically. As additional bytes are received, the module will automatically ACK them if the previous byte has been read from the RX buffer before the new byte has been completely received and notify software of the newly available byte. Both address and data bytes received must be read from the RX buffer by software. Preconditions 1. The module must have had its basic options and clock frequency initialized and have been enabled (see Initializing the I2C). 2. An external master must have started a transfer. 3. The address of the transfer must have matched with the address (ignoring any bits in the mask) programmed into the module by software. Process Software must follow this sequence: 1. Ensure that a byte has been received either by polling the PLIB_I2C_ReceivedByteIsAvailable function or by waiting for a slave interrupt (at which time, this function should still be checked). 2. Identify if the byte is a data byte or an address byte using the PLIB_I2C_SlaveAddressIsDetected function. 3. If the byte is an address byte, software must identify if it is starting a read or write operation using the PLIB_I2C_SlaveReadIsRequested function. 4. Software must read the byte from the RX buffer using the PLIB_I2C_ReceivedByteGet function, even if it was an address byte. 5. If clock stretching was enabled during initialization, software must call the PLIB_I2C_SlaveClockRelease function to release the SCL line. Example #define MY_I2C_ID I2C_ID_1 uint8_t data; if ( PLIB_I2C_ReceivedByteIsAvailable(MY_I2C_ID) ) { // Check to see if the byte is data or an address if (PLIB_I2C_SlaveAddressWasDetected(MY_I2C_ID)) { if ( PLIB_I2C_SlaveReadWasRequested(MY_I2C_ID) ) { // Beginning a slave receive sequence } else { // Beginning a slave transmit sequence } } else { // Data Byte Received } // Read the data or address from the RX buffer data = PLIB_I2C_ReceivedByteGet(MY_I2C_ID); Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1029 // Free the SCL line (only if clock stretching was enabled) PLIB_I2C_SlaveClockRelease(MY_I2C_ID); } The previous example uses the following constants and variables: Symbol Description MY_I2C_ID Defined as the selected I2C module value from the I2C_MODULE_ID enumeration. Example: #define MY_I2C_ID I2C_ID_1 data This is the variable used to hold the byte received. Operating as a Slave Transmitter Once an external master has addressed the I2C module (see Operating as a Slave Receiver) with the read-write bit set (as determined by calling the PLIB_I2C_SlaveReadIsRequested function), software can begin transmitting data to the master. Preconditions 1. The module must have had its basic options and clock frequency initialized and have been enabled(see Initializing the I2C) 2. An external master must have started a transfer. 3. The address of the transfer must have matched with the address slave programmed into the I2C module (see Managing Slave Addresses). 4. A slave read must have been requested (as previously described). Note: When the address has been received and matched the programmed local slave address, a slave interrupt will occur if it has been enabled. Transmitting a Byte When operating as a slave transmitter on the I2C bus, the software must use the following sequence to transmit data bytes. 1. Ensure that the TX buffer is currently ready to_accept_a byte to be transmitted using the PLIB_I2C_TransmitterIsReady function. 2. Write the byte to be transmitted to the TX buffer using the PLIB_I2C_TransmitterByteSend function. 3. If clock stretching was enabled (using the PLIB_I2C_SlaveClockStretchingEnable function) and the previous byte was ACKed, the PLIB_I2C_SlaveClockRelease function must be called to release the SCL line (it is safe to call this even if the previous byte was NAKed.) Example #define MY_I2C_ID I2C_ID_1 uint8_t data; // Assign the desired byte value into the "data" variable if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { // Write the byte to the TX buffer PLIB_I2C_TransmitterByteSend(MY_I2C_ID, data); // Free the SCL line (only if clock stretching was enabled) PLIB_I2C_SlaveClockRelease(MY_I2C_ID); } Checking Acknowledgement After a byte has been transmitted, the module latches the ACK/NAK response from the master so that software may use the following sequence to verify it and causes another slave interrupt (if it has been enabled). 1. Ensure that the byte has been completely transmitted using the PLIB_I2C_TransmitterByteHasCompleted function (and/or by responding to the slave interrupt). 2. Determine if the byte was ACKed or NAKed using the PLIB_I2C_TransmitterByteWasAcknowledged function. Example #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterByteHasCompleted(MY_I2C_ID)) { if (PLIB_I2C_TransmitterByteWasAcknowledged(MY_I2C_ID)) { // Transmission successful } else { // Transmission was not successful } } Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1030 The previous examples use the following constants and variables: Symbol Description MY_I2C_ID Defined as the selected I2C module value from the I2C_MODULE_ID enumeration. Example: #define MY_I2C_ID I2C_ID_1 data This is the buffer containing byte of data to transmit. Operating as a Master Transmitter Whenever the I2C module initiates a transfer on the bus, it is acting as master. A transfer can be initiated any time the bus is idle. If two masters attempt to initiate transfers at nearly the same time, one of them will lose arbitration at some point during the transfer and must retry the transfer later when the bus becomes idle. The winner of arbitration can continue, without any data loss. An I2C bus transfer always begins with a Start condition, followed by one or two properly formatted bytes containing the 7-bit or 10-bit target slave address (address of the slave device that is the target of the transfer). The direction of the remainder of transfers (after the address has been sent) is indicated by bit 0 of the address (0 = write/transmitting, 1 = read/receiving, from the point of view of the master). After that, any amount of data may be transferred and a repeated Start condition (followed by another properly formatted address) can occur to change the direction of the transfer or even the target slave device. See Forming Transfers for details of the possible transfer formats. When the master is finished, an I2C bus transfer always ends with a Stop condition. These steps are summarized as follows: Summary of Steps 1. Send a Start condition. 2. Send a 7-bit or 10-bit address (one or two bytes with a write transfer indication in bit 0). 3. Send data bytes. 4. Send a Stop condition. Each of these steps making up a transfer will take some time to complete. The completion of each step will cause an I2C master interrupt. The software must always keep track of which state it was in, check the I2C status, and respond to the interrupt by performing the next appropriate step. Notes: 1. Arbitration loss can occur after each step has completed. Software should check for arbitration loss by calling the PLIB_I2C_ArbitrationLossHasOccurred function. If arbitration loss occurs, it must be cleared by calling the PLIB_I2C_ArbitrationLossClear function. 2. After any step completes, but before sending the Stop condition (see step 4), the master may send a repeated Start condition and start over at step 2 to change slave targets and/or transfer direction. Sending a Start Condition To start a master transfer, the software must do the following: Preconditions The module must have had its basic options and clock frequency initialized and have been enabled (see Initializing the I2C). Process 1. Verify that the bus is idle using the PLIB_I2C_BusIsIdle function. 2. Send the start signal using the PLIB_I2C_MasterStart function. 3. Check for arbitration loss after the start condition has completed using the PLIB_I2C_ArbitrationLossHasOccurred function. Example: Sending a Start Condition #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_BusIsIdle(MY_I2C_ID)) { PLIB_I2C_MasterStart(MY_I2C_ID); } The Start condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Start condition has been initiated. Even if the bus is verified to be idle before sending the start condition, a bus collision can still occur while the Start condition is being transmitted. To verify that arbitration has not been lost during transmission of the Start condition, the software should check the PLIB_I2C_ArbitrationLossHasOccurred function after the Start condition has completed. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Abort transfer, retry later PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } Sending a 7-bit Address Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1031 To send a 7-bit address, the software must do the following: Preconditions The Start condition must have been sent and completed as previously described. Process 1. Write the address byte to the TX buffer using the PLIB_I2C_TransmitterByteSend function. The address byte that is supplied as the parameter to PLIB_I2C_TransmitterByteSend should also include the R/W bit. Note: A master interrupt will occur once the address byte has been transmitted and ACKed or NAKed by the targeted slave device. (If the slave device does not answer, an implicit NAK will occur.) 2. Once the address byte has been ACKed or NAKed by the slave target, software must verify the result and respond appropriately. The Acknowledgement and Arbitration process is described in a subsequent section, just before the description of how to send a Stop condition.) Example: Sending a 7-bit Address #define MY_I2C_ID I2C_ID_1 #define SLAVE_TARGET_ADDRESS 0x22 uint8_t slaveAddress = 0; // Format the 7-bit address byte with the write indication in bit 0 slaveAddress = SLAVE_TARGET_ADDRESS; // Send the address byte if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, slaveAddress); } Note: Bits 7-1 contain the 7-bit target slave address. Bit 0 indicates read or write direction for the remainder of the transfer. Sending a 10-bit Target Slave Address To send a 10-bit address, the software must do the following: Preconditions The Start condition must have been sent and completed as previously described. Process 1. Format the two address bytes correctly with the 10-bit address and the read/write bit appropriately set (for a read transfer) or cleared (for a write transfer). 2. Ensure that the TX buffer is currently ready to_accept_a byte to be transmitted using the PLIB_I2C_TransmitterIsReady function. 3. Write the first address byte to the TX buffer using the PLIB_I2C_TransmitterByteSend function. Note: After the first byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or you can poll the PLIB_I2C_TransmitterByteHasCompleted function). 4. Ensure that the first address byte was ACKed by the slave target (to do this, follow the Acknowledgement process described in a following section. 5. Write the second address byte to the TX buffer using the PLIB_I2C_TransmitterIsReady function and the PLIB_I2C_TransmitterByteSend function. Note: After the second byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or you can poll the PLIB_I2C_TransmitterByteHasCompleted function). 6. Ensure that the second address byte was ACKed by the slave target (to do this, follow the process in the Acknowledgement and Arbitration, which is described later in this section). Example: Formatting the 10-bit Address in Two Bytes /* first byte of 10-bit address which is inclusive of R/W bit */ #define SLAVE_TARGET_10BIT_ADDRESS_BYTE1 0xF6 /* second byte of 10-bit address */ #define SLAVE_TARGET_10BIT_ADDRESS_BYTE2 0x22 uint8_t slaveAddressByte1 = 0; uint8_t slaveAddressByte2 = 0; /* include the R/W in bit 0 of the first byte */ slaveAddressByte1 = SLAVE_TARGET_10BIT_ADDRESS_BYTE1; slaveAddressByte2 = SLAVE_TARGET_10BIT_ADDRESS_BYTE2; Example: Sending the First Byte of a 10-bit Address Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1032 #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, slaveAddressByte1); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Example: Sending the Second Byte of a 10-bit Address #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, slaveAddressByte2); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Sending a Data Byte The following sequence can be used to send a data byte and repeated to send an arbitrary number of data bytes. Preconditions • The Start condition must have been sent and completed as previously described • The target slave address has been fully transmitted (with the write indication in bit 0) and ACKed by the targeted slave device Process 1. Ensure that the TX buffer is currently ready to_accept_a byte to be transmitted using the PLIB_I2C_TransmitterIsReady Function. 2. Write the byte to be transmitted to the TX buffer using the PLIB_I2C_TransmitterByteSend Function. Note: After the byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or poll the PLIB_I2C_TransmitterByteHasCompleted function). 3. Check for arbitration loss or an ACK or NAK from the slave as described in the next section, Acknowledgement and Arbitration. Example #define MY_I2C_ID I2C_ID_1 uint8_t data; // Assign the data value into the "data" variable if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, data); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Acknowledgement and Arbitration After sending a data or address byte (as previously described), the master transmitter must check to see if arbitration was lost and if the byte was ACKed or NAKed. If the byte was ACKed, the slave receiver is ready to receive more bytes. If the byte was NAKed, the slave receiver cannot_accept_any more bytes at this time. Preconditions • The start condition must have been sent and completed as previously described • A byte (address or data) must have been transmitted, using one of the previous processes Process 1. Ensure that the byte has been completely transmitted using the PLIB_I2C_TransmitterByteHasCompleted function (and/or by waiting for the master interrupt) 2. Determine if arbitration loss has occurred using the PLIB_I2C_ArbitrationLossHasOccurred function. 3. Determine if the byte was ACKed or NAKed using the PLIB_I2C_TransmitterByteWasAcknowledged function. Example #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterByteHasCompleted(MY_I2C_ID)) { if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Handle arbitration loss PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } else Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1033 { if (PLIB_I2C_TransmitterByteWasAcknowledged(MY_I2C_ID)) { // Transmission successful } else { // Transmission was not successful } } } To handle arbitration loss, the master transmitter must stop the transfer process and retry the entire transfer again at a later time when the bus is not busy. Sending a Repeated Start Condition If the master wants to change slave targets or transfer directions, it can send a repeated Start condition followed by a new address at any time after the previous target slave address has been acknowledged (and before the Stop condition has been sent). Preconditions • The Start condition must have been sent and completed as previously described • A target slave address must have been transmitted and ACKed • Zero or more data bytes may also have been sent and ACKed Process Send the repeated Start condition using the PLIB_I2C_MasterStartRepeat function. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStartRepeat(MY_I2C_ID); The Start condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Start condition has been initiated. The repeated Start must be followed by another target slave address (either 7-bit or 10-bit, as appropriate). Sending a Stop Condition When the master transmitter has finished sending data, it must end the transfer with a stop condition. Preconditions • The Start condition must have been sent and completed as previously described • A target slave address must have been transmitted and ACKed • Zero or more data bytes may also have been sent and ACKed Note: At least one address byte must be transmitted between the Start and Stop conditions. Following a Start condition immediately with a Stop condition is a protocol error and can cause some slave devices to lock up and stop responding to the bus. Process Send a stop condition using the PLIB_I2C_MasterStop function. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStop(MY_I2C_ID); The Stop condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Stop condition has been initiated. After a Stop condition, the bus should be idle unless a master immediately starts a new transfer. Strictly speaking, a bus collision can still occur while the Stop condition is being transmitted. Although the transfer is already completed when the Stop condition has been sent, software does not have to abort the transfer; however, it should still check for and clear the arbitration loss condition if it occurs. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } The previous examples use the following constants and variables: Symbol Description MY_I2C_ID Defined as the selected I2C module value from the I2C Module enumeration. Example: #define MY_I2C_ID I2C_ID_1 Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1034 data This is the buffer containing byte of data to transmit. slaveTargetAddress7Bit This variable is used to demonstrate how to properly format and access a 7-bit target slave address SLAVE_TARGET_7BIT_ADDRESS This constant is used as a placeholder for the actual 7-bit target slave address that must be defined by the client code. slaveAddress10Bit This variable is used to demonstrate how to properly format and access a 10-bit slave address. SLAVE_TARGET_10BIT_ADDRESS This constant is used as a placeholder for the actual 10-bit slave address that must be defined by the client code. Operating as a Master Receiver Any time the I2C module initiates a transfer on the bus, it is acting as a master. A transfer can be initiated any time the bus is idle. If two masters attempt to initiate transfers at nearly the same time, one of them will lose arbitration and must retry the transfer later when the bus becomes idle. The winner of arbitration can continue, without any data loss. An I2C bus transfer always begins with a Start condition, followed by a 7-bit or 10-bit (1-byte or 2-byte) target slave address. Therefore, every master transfer starts off transmitting at least one byte. The direction of transfer of subsequent bytes (after the first byte has been sent) is indicated by bit 0 of the first address byte (0 = write/transmitting, 1 = read/receiving, from the point of view of the master). If 10-bit addressing is used or additional data (such as an internal address) is to be transmitted after the first address byte, the first address byte must indicate a write transfer. To change the direction after transmitting more than just a single address byte, a repeated Start condition (followed by another single address byte) must be sent (see Forming Transfers for details of the possible transfer formats). When the master is finished, an I2C bus transfer always ends with a Stop condition. This results in two basic formats for receiving data as a master, summarized as follows: Summary of Steps: Read Only 1. Send a Start condition. 2. Send a 7-bit address with a read transfer indication in bit 0. 3. Receive data bytes. 4. Send a Stop condition. Summary of Steps: Combined Read-Write 1. Send a Start condition. 2. Send a 7-bit address (or the first byte of a 10-bit address) with a write transfer indication in bit 0. 3. Send the second byte of a 10-bit address (and/or any additional data to be transmitted). 4. Send a repeated Start condition. 5. Resend the first byte of the 10-bit address (or a 7-bit address) with a read indication in bit 0. 6. Receive data bytes. 7. Send a Stop condition. Each of these steps making up a transfer will take some time to complete. The completion of each step will cause an I2C master interrupt. The software must always keep track of which state it was in and respond to the interrupt by performing the next appropriate step. Sending a Start Condition To start a master transfer, the software must do the following: Preconditions The module must have had its basic options and clock frequency initialized and have been enabled (see Initializing the I2C). Process 1. Verify that the bus is idle using the PLIB_I2C_BusIsIdle function. 2. Send the start signal using the PLIB_I2C_MasterStart function. Example #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_BusIsIdle(MY_I2C_ID)) { PLIB_I2C_MasterStart(MY_I2C_ID); } The Start condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Start condition has been initiated. Even if the bus is verified to be idle before sending the Start condition, a bus collision can still occur while the Start condition is being transmitted. To verify that arbitration has not been lost during transmission of the Start condition, the software should check the PLIB_I2C_ArbitrationLossHasOccurred function after the Start condition has completed. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Abort transfer, retry later PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1035 } Sending a 7-bit Address To send a 7-bit address (or the first byte of a 10-bit address), the software must do the following: Preconditions The Start condition must have been sent and completed as previously described. Process 1. Ensure that the TX buffer is currently ready to_accept_a byte to be transmitted using the PLIB_I2C_TransmitterIsReady function. 2. Format the address byte correctly with the 7-bit address and the read/write bit appropriately set (for a read transfer) or cleared (for a write transfer). 3. Write the address byte to the TX buffer using the PLIB_I2C_TransmitterByteSend function. Note: A master interrupt will occur once the address byte has been transmitted and ACKed or NAKed by the targeted slave device (or if arbitration was lost). If the slave device does not answer, an implicit NAK will occur. 4. Once the address byte has been ACKed or NAKed by the slave target (or if arbitration was lost), software must verify the result and respond appropriately. The Acknowledgement and Arbitration process is described in a subsequent section, just before the description of how to send a Stop condition.) Example: Sending a 7-bit Address #define MY_I2C_ID I2C_ID_1 #define SLAVE_TARGET_ADDRESS 0x22 uint8_t slaveAddress = 0; // Format the 7-bit address byte with the read indication in bit 0 slaveAddress = (SLAVE_TARGET_ADDRESS | 0x01); // Send the address byte if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, slaveAddress); } Note: Bits 7-1 contain the 7-bit target slave address. Bit 0 indicates read or write direction for the remainder of the transfer. Sending a 10-bit Target Slave Address To send a 10-bit address, the software must do the following: Preconditions The Start condition must have been sent and completed as previously described. Process 1. Format the two address bytes correctly with the 10-bit address and the read/write bit cleared, indicating a write transfer. 2. Ensure that the TX buffer is currently ready to_accept_a byte to be transmitted using the PLIB_I2C_TransmitterIsReady function. 3. Write the first address byte to the TX buffer using the PLIB_I2C_TransmitterByteSend function. Note: After the first byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or poll the PLIB_I2C_TransmitterByteHasCompleted function). 4. Ensure that the first address byte was ACKed by the slave target and check for arbitration loss. To do this, use the Acknowledgement and Arbitration process, which described in the next section. 5. Write the second address byte to the TX buffer using the PLIB_I2C_TransmitterIsReady function and the PLIB_I2C_TransmitterByteSend function. Note: After the second byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or you can poll the PLIB_I2C_TransmitterByteHasCompleted function). 6. Ensure that the second address byte was ACKed by the slave target and that arbitration was not lost. To do this, use the Acknowledgement and Arbitration process, which described in the next section. Example: Formatting the 10-bit Address in Two Bytes #define MY_I2C_ID I2C_ID_1 /* first byte of 10-bit address which is inclusive of R/W bit */ #define SLAVE_TARGET_10BIT_ADDRESS_BYTE1 0xF6 /* second byte of 10-bit address */ #define SLAVE_TARGET_10BIT_ADDRESS_BYTE2 0x22 uint8_t slaveAddressByte1 = 0; Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1036 uint8_t slaveAddressByte2 = 0; /* including the R/W bit in byte-1 of 10-bit address */ slaveAddressByte1 = (SLAVE_TARGET_10BIT_ADDRESS_BYTE1 | 0x01); /* the second byte is included as is */ slaveAddressByte2 = SLAVE_TARGET_10BIT_ADDRESS_BYTE2; Example: Sending the First Byte of a 10-bit Address #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, slaveAddressByte1); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Example: Sending the Second Byte of a 10-bit Address #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, slaveAddressByte2); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Acknowledgement and Arbitration After sending a data or address byte (as previously described), the master transmitter must check to see if arbitration was lost and if the byte was ACKed or NAKed. If the byte was ACKed, the slave receiver is ready to receive more bytes. If the byte was NAKed, the slave receiver cannot_accept_any more bytes at this time. Preconditions • The Start condition must have been sent and completed as previously described • A byte (address or data) must have been transmitted, using one of the previous processes Process 1. Ensure that the byte has been completely transmitted using the PLIB_I2C_TransmitterByteHasCompleted function (and/or by waiting for the master interrupt). 2. Determine if arbitration loss has occurred using the PLIB_I2C_ArbitrationLossHasOccurred function. 3. Determine if the byte was ACKed or NAKed using the PLIB_I2C_TransmitterByteWasAcknowledged function. #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterByteHasCompleted(MY_I2C_ID)) { if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Handle arbitration loss PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } else { if (PLIB_I2C_TransmitterByteWasAcknowledged(MY_I2C_ID)) { // Transmission successful } else { // Transmission was not successful } } } To handle arbitration loss, the master must stop the transfer process and retry the entire transfer again at a later time when the bus is not busy. Sending a Repeated Start Condition If the master wants to change slave targets or transfer directions, it must send a repeated Start condition followed by a new address at any time after the previous target slave address has been acknowledged (and before the Stop condition has been sent). Preconditions • The Start condition must have been sent and completed as previously described • A target slave address must have been transmitted and ACKed. • Zero or more data bytes may also have been sent or received and ACKed as appropriate. Process Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1037 Send the repeated Start condition using the PLIB_I2C_MasterStartRepeat function. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStartRepeat(MY_I2C_ID); The repeated Start condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Start condition has been initiated. It must then be followed by another target slave address (either 7-bit or 10-bit, as appropriate). Strictly speaking, a bus collision can still occur while the repeated start condition is being transmitted. To verify that arbitration has not been lost during transmission of the repeated Start condition, the software should check the PLIB_I2C_ArbitrationLossHasOccurred function after the repeated Start condition has completed. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Abort transfer, retry later PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } Receiving a Data Byte The following sequence can be used to receive a data byte and repeated to receive an arbitrary number of data bytes. Preconditions • The Start condition must have been sent and completed as previously described • The target slave address must have been fully transmitted (with the read indication in bit 0) and ACKed by the targeted slave device Process 1. Start the I2C module cycling the clock line to receive one byte by calling the PLIB_I2C_MasterReceiverClock1Byte function. The I2C module will generate a master interrupt once the eighth clock cycle has completed, but before the ninth cycle has started. 2. Ensure that a byte was received and is available in the RX buffer using the PLIB_I2C_ReceivedByteIsAvailable function. 3. If a byte is available, get it from the RX buffer using the PLIB_I2C_ReceivedByteGet function. 4. ACK or NAK the byte (as determined by software) using the PLIB_I2C_ReceivedByteAcknowledge function. The master receiver indicates to the slave transmitter that it wants to terminate the transfer by NAKing the last byte. All other bytes should be ACKed after reception. 5. Ensure that the ACK/NAK signal has completed using the PLIB_I2C_ReceiverByteAcknowledgeHasCompleted function or by waiting for the master interrupt. Note: Arbitration loss cannot occur during a master reception (only during transmission). Example: Enabling the Receiver #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterReceiverClock1Byte(MY_I2C_ID); Wait for reception to complete before attempting to get the byte from the receiver. Example: Reading a Byte from the RX Buffer #define MY_I2C_ID I2C_ID_1 #define MY_MAX_COUNT 10 uint8_t data; int count; if ( PLIB_I2C_ReceivedByteIsAvailable(MY_I2C_ID) ) { data = PLIB_I2C_ReceivedByteGet(MY_I2C_ID); count++; // Determine if the data should be ACKed or NAKed if (count < MY_MAX_COUNT) { PLIB_I2C_ReceivedByteAcknowledge(MY_I2C_ID, true); } else { PLIB_I2C_ReceivedByteAcknowledge(MY_I2C_ID, false); } } Wait for the ACK/NAK to complete by waiting for the next master interrupt. Example: Verifying ACK/NAK Signal is Complete #define MY_I2C_ID I2C_ID_1 Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1038 if (PLIB_I2C_ReceiverByteAcknowledgeHasCompleted(MY_I2C_ID)) { // Byte reception sequence complete } Sending a Stop Condition When the master transmitter has finished sending data, it must end the transfer with a Stop condition. Preconditions • The Start condition must have been sent and completed as previously described • A target slave address must have been transmitted and ACKed. • Zero or more data bytes may also have been sent or received and ACKed as appropriate Note: At least one address byte must be transmitted between the Start and Stop conditions. Following a Start condition immediately with a Stop condition is a protocol error and can cause some slave devices to lock up and stop responding to the bus. Process Send a Stop condition using the PLIB_I2C_MasterStop function. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStop(MY_I2C_ID); The Stop condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Stop condition has been initiated. After a Stop condition, the bus should be idle unless a master immediately starts a new transfer. Strictly speaking, a bus collision can still occur while the stop condition is being transmitted. Although the transfer is already completed when the Stop condition has been sent, software does not have to abort the transfer; however, it should still check for and clear the arbitration loss condition if it occurs. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } The previous example uses the following constants and variables: Symbol Description MY_I2C_ID Defined as the selected I2C module value from the I2C Module enumeration. Example: #define MY_I2C_ID I2C_ID_1 data This is the buffer to hold byte of data received. slaveTargetAddress7Bit This variable is used to demonstrate how to properly format and access a 7-bit target slave address SLAVE_TARGET_7BIT_ADDRESS This constant is used as a place holder for the actual 7-bit target slave address that must be defined by the client code. slaveAddress10Bit This variable is used to demonstrate how to properly format and access a 10-bit target slave address SLAVE_TARGET_10BIT_ADDRESS This constant is used as a place holder for the actual 10-bit target slave address that must be defined by the client code. Interrupt State Machine The I2C state machine can be used in either a polled or an interrupt-driven manner. However, even when polled, software must check the state of the master, slave, and error interrupt flags to identify when a state transition occurs. The I2C module can cause three different interrupts: • Slave Interrupt - A byte was sent or received in Slave mode • Master Interrupt - A bus action has completed in Master mode • Error Interrupt - An error has occurred in any mode (see Handling Errors) Note: Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for more information. The I2C module will not start generating interrupts (setting the I2C interrupt flags, even if interrupts are disabled) until it is properly configured and enabled. After that, interrupts are generated as described in the following section. Software has to respond appropriately once the interrupt has Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1039 occurred (the flag has been set) to allow the state machine to advance to the next state. These actions are described following the state machine diagram to which they refer. Notes: 1. These state machine diagrams show the normal operations. Error and exception cases are explained in the Handling Errors section and are not shown in the diagrams. 2. The transition labels sometimes represent hardware interrupts (or the setting of an interrupt flag) and sometimes represent software actions. Refer to the transition tables to understand the transitions. 3. The Wait state is shared between all state machines (i.e., while in the Wait state, the I2C module can start a new master-mode transfer or be addressed by an external master). 4. The Start state is shared between both read and write master transfer state machines (i.e., when starting a new transfer, software can choose start either a read or a write transfer). Slave Mode State Machine Slave Mode State Transitions In Slave mode, state transitions occur under hardware control automatically or in response to an interrupt. Software must respond appropriately to ensure that the module continues to operate correctly. Transition From State To State Software Actions Enable Initialize Wait Enable the module, using the PLIB_I2C_Enable function Slave Interrupt, 7-bit Address Match, Write Wait Receive mode Software should call the PLIB_I2C_ReceivedByteIsAvailable function to verify that a byte has been received and the PLIB_I2C_SlaveAddressWasDetected function to verify that a 7-bit address (or the first byte of a 10-bit address) has been received. Then, software must get the address byte from the receiver buffer (the byte is automatically ACKed), using the PLIB_I2C_ReceivedByteGet function. Software must also release the clock by calling PLIB_I2C_SlaveClockRelease function to allow reception of the next byte. Note: This transition occurs on a write transfer with either a 7-bit or 10-bit address (for the first of two address bytes). Slave Interrupt, Byte Received Receive mode Receive mode Software should call the PLIB_I2C_ReceivedByteIsAvailable function to verify that a byte has been received and, if one has, get the byte from the receiver buffer by calling PLIB_I2C_ReceivedByteGet function. Then, software must release the clock by calling PLIB_I2C_SlaveClockRelease function to allow reception of the next byte. Slave Interrupt, 10-bit Address Match Receive mode Receive mode Software should call the PLIB_I2C_ReceivedByteIsAvailable function to verify that a byte has been received and (if 10-bit addressing is being used) call the PLIB_I2C_SlaveAddress10BitWasDetected function to verify that the second byte of the 10-bit address matched the low-order 8-bits of the local-slave 10-bit address. Next, software must get the address byte received from the receiver buffer (the byte is automatically ACKed), using the PLIB_I2C_ReceivedByteGet function. Note: This transition occurs on write transfer when using 10-bit (2-byte) addressing when the second address byte is received. End Receive Receive mode Wait None. Software is not aware of this transition. A receive transfer can end with a stop condition, a repeated start, or if the second-half of a 10-bit slave address does not match the programmed local slave address (and possibly the optional mask). Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1040 Slave Interrupt, 7-bit Address Match, Read Wait Transmit mode Software should call the PLIB_I2C_ReceivedByteIsAvailable function to verify that a byte has been received and the PLIB_I2C_SlaveAddressWasDetected function to verify that an address has been received. Then, software must get the address byte from the receiver buffer (the byte is automatically ACKed), using the PLIB_I2C_ReceivedByteGet function. Notes: 1. This transition occurs on a read transfer with a 7-bit (1-byte) address or after a repeated-start with a 10-bit slave address. 2. The second byte of a 10-bit address is not sent after a repeated-start condition, only the first byte. The 10-bit slave device must remember if it was addressed at the beginning of this transfer. 3. After handling the address byte received, software should call the PLIB_I2C_TransmitterIsReady function to make sure that the transmitter buffer is able to_accept_a byte and, if it is, call the PLIB_I2C_TransmitterByteSend function to send the requested byte. Slave Interrupt, Byte Completed Transmit mode Transmit mode Software must call the PLIB_I2C_TransmitterByteWasAcknowledged function to check to see if the byte was ACKed or NAKed. If the byte was ACKed, software must send the next byte by calling the PLIB_I2C_TransmitterIsReady function to make sure that the transmitter buffer is able to_accept_a byte and, if it is, call the PLIB_I2C_TransmitterByteSend function to send the next byte. NAK Transmit mode Wait Software must call the PLIB_I2C_TransmitterByteWasAcknowledged function to check to see if the byte was ACKed or NAKed. The master will NAK the last byte it wants to receive. At that point, the transfer is effectively over and software must not attempt to send any more bytes. The module automatically transitions back to the Wait state when the Stop condition occurs, but software does not receive an interrupt at that point. Master Mode Write Transfer State Machine Master-Mode Write-Transfer State Transitions Transition From State To State Software Actions Begin Master Transfer Wait Start This state transition occurs when software initiates transmission of the start condition. Software should call the PLIB_I2C_BusIsIdle function to verify that the bus is not currently in use by another master. Then it must call the PLIB_I2C_MasterStart function (or PLIB_I2C_MasterStartRepeat function) to send the start (or repeated start) condition. Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1041 Master Interrupt, Start Completed Start 7-Bit Address, Write After the start condition has completed, software should check for a possible collision by calling the PLIB_I2C_ArbitrationLossHasOccurred function. Then, it must send an appropriately formatted 7-bit address byte (or the first byte of the 10-bit address) to the I2C bus to address a slave target. To do this, it should first call the PLIB_I2C_TransmitterIsReadyfunction to verify that the transmitter buffer is ready to_accept_a byte and then call the PLIB_I2C_TransmitterByteSend function to send the byte. Master Interrupt, Byte Completed 7-bit Address, Write Transmit When the master interrupt occurs (or the PLIB_I2C_TransmitterByteHasCompleted function returns true) to indicate that the last byte sent has completed, software must check to ensure that the slave device ACKed the byte by calling the PLIB_I2C_TransmitterByteWasAcknowledged function. Software should also call the PLIB_I2C_ArbitrationLossHasOccurred function to determine if a collision occurred. If all is well, software may then send another byte to the slave using the PLIB_I2C_TransmitterIsReady function and the PLIB_I2C_TransmitterByteSend function. If 10-bit addressing is being used for this transfer, the start condition and first byte of the 10-bit address must be followed by the second byte of the 10-bit address. Multiple slaves may respond to the first byte of the 10-bit address. It requires the second byte to uniquely identify the 10-bit slave. However, this is sent using the same process as if it were a data byte. Master Interrupt, Byte Completed Transmit Transmit Software must call the PLIB_I2C_TransmitterByteWasAcknowledged function check to ensure that the slave device ACKed the byte and the PLIB_I2C_ArbitrationLossHasOccurred function to determine if a collision occurred. If all is well, software may call the PLIB_I2C_TransmitterIsReady function and PLIB_I2C_TransmitterByteSendfunction to send another byte to the slave and remain in the Transmit state. If not, software should abort the transfer by sending a Stop condition and transition to the Stop, repeated Start state. Master Interrupt, Byte Completed 7-bit Address, Write Stop, repeated Start If the slave NAKed any byte sent or if software wants to end or restart the transfer (perhaps to change direction) it can do so by sending a stop condition (using the PLIB_I2C_MasterStop function) or repeated Start condition (using the PLIB_I2C_MasterStartRepeat function). Master Interrupt, Byte Completed Transmit Stop, repeated Start Software must call the PLIB_I2C_TransmitterByteWasAcknowledged function check to check to see if the slave ACKed or NAKed the byte. If the slave NAKed the byte or if software wants to end or restart the transfer (perhaps to change direction) it can do so by sending a Stop condition (using the PLIB_I2C_MasterStop function) or repeated Start condition (using the PLIB_I2C_MasterStartRepeat function). Restart Stop, repeated Start Start Immediately after initiating the repeated Start condition, software transitions back to the Start state where it must decide what sort of transfer it will start next. Note: Read transfers will transition to the Start state in the Master Mode Read Transfer state machine. Master Interrupt, Stop Completed Stop, repeated Start Wait When the master interrupt occurs, indicating that the Stop condition has completed, software transitions back to the Wait state (which is actually part of the Slave Mode state machine). Master-Mode Read-Transfer State Machine Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1042 Master Mode Read Transfer State Transitions In Master mode, transitions are initiated under software control and interrupts occur (the master interrupt flag is set, even when interrupts are disabled) when the action initiated has completed. If at any point, an address or data byte is NAKed by the slave or an error occurs, usually the safest thing for the master to do is to end the transfer with a Stop condition and release the bus. Transition From State To State Software Actions Begin Master Transfer Wait Start This state transition occurs when software initiates transmission of the start condition. Software should call the PLIB_I2C_BusIsIdle function to verify that the bus is not currently in use by another master. Then it must call the PLIB_I2C_MasterStart function (or PLIB_I2C_MasterStartRepeat function) to send the start (or repeated Start) condition. Master Interrupt, Start Completed Start 7-Bit Address, Read After the start condition has completed, software should check for a possible collision by calling the PLIB_I2C_ArbitrationLossHasOccurred function. Then, it must send an appropriately formatted 7-bit address byte (or the first byte of the 10-bit address) to the I2C bus to address a slave target. To do this, it should first call the PLIB_I2C_TransmitterIsReady function to verify that the transmitter buffer is ready to_accept_a byte and then call the PLIB_I2C_TransmitterByteSend function to send the byte. Note: If using 10-bit addressing, this is a repeated transmission of the first byte of the 10-bit address since all 10-bit transfers must start off as write transfers (so both address bytes can be sent) then be restarted to become read transfers. Master Interrupt, Byte Completed 7-Bit Address, Read Receive Software must initiate the "Clock1Byte" operation (using the PLIB_I2C_MasterReceiverClock1Byte function) so that the I2C module will cycle the SCL line eight times causing the slave to send the requested byte of data. Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1043 Master Interrupt, Byte Available Receive ACK NAK When a byte has been received (which software can verify using the PLIB_I2C_ReceivedByteIsAvailable function), software must get the received byte from the RX buffer (using the PLIB_I2C_ReceivedByteGet function) and initiate transmission of the ACK/NAK bit (using the PLIB_I2C_ReceivedByteAcknowledge function). If it intends to receive another byte, software must ACK the byte just received. If it does not intend to receive another byte, software must NAK the byte just received. Master Interrupt, ACK Completed ACK, NAK Receive Software can verify that the ACK signal has completed using the PLIB_I2C_ReceiverByteAcknowledgeHasCompleted function. If software ACKed the previously received byte, it must initiate the "Clock1Byte" operation (using the PLIB_I2C_MasterReceiverClock1Byte function) so that the I2C module will cycle the SCL line eight times so that the slave can send the requested byte. Otherwise, software must have NAKed the previous byte to end the transfer. Master Interrupt, NAK Completed ACK, NAK Stop, Restart Software can verify that the NAK signal has completed using the PLIB_I2C_ReceiverByteAcknowledgeHasCompleted function. If software intends to continue the transfer without allowing the bus to go idle, it must initiate a repeated-start (using the PLIB_I2C_MasterStartRepeat function) and transition immediately to the Start state. If software intends to end the transfer and allow the bus to go idle, it must initiate a Stop condition using the PLIB_I2C_MasterStop function. Restart Stop, repeated Start Start Immediately after initiating the repeated Start condition, software automatically transitions back to the "Start" state where it must decide if it will restart with a read or write transfer. Note: Write transfers will transition to the Start state in the Master Mode Write Transfer state machine. Master Interrupt, Stop Completed Stop, repeated Start Wait When the master interrupt occurs, indicating that the Stop condition has completed, software transitions back to the waiting state (which is actually part of the Slave Mode state machine). Managing Slave Addresses An I2C address identifies which slave device is being targeted by a master device on a transfer-by-transfer basis. I2C addresses can be either 7-bits or 10-bits, as shown in the following sections, 7-Bit Slave Addresses and 10-Bit Slave Addresses. Addresses that are 7-bits long are sent in a single byte where bit 0 identifies the direction of the remaining data in the transfer. Addresses that are 10-bits long are sent in two bytes using a reserved range in the 7-bit address space (addresses 0x78 through 0x7C) to encode the two high-order bits (bits A9 and A8) in the first byte. The second byte encodes the eight low-order bites (A7 through A0). These formats are in the following two sections. 7-Bit Slave Addresses When using 7-bit slave addressing, the address byte is the first byte sent by any I2C master device immediately following a "Start" condition. The 7-bit address is shifted left by 1 bit to fill bits 7-to-1 in the address byte. Bit 0 in the 7-bit address byte indicates the transfer direction, as follows. Bits Usage A6:A0 Bits 7 through 1 of the address byte contain the 7-bit slave address. R/W Bit 0 of the address byte is the read/write bit (0 = Read, 1 = Write). See Operating as a Master Transmitter and Operating as a Master Receiver for examples. 10-Bit Slave Addresses When using 10-bit slave addresses, the first address byte must be sent immediately following a start or repeated Start condition. The second byte must immediately follow the first byte when performing a write transfer. Read transfers must begin as write transfers so that both bytes may be sent. Immediately after sending the second address byte, the master will issue a repeated Start condition and resend the first address byte only (with the read/write bit cleared, indicating a read transfer. The second byte is not retransmitted. Since the transfer has been restarted, all listening 10-bit slave devices know that they will not be address again until the transfer has been ended with a Stop condition. However, devices that respond to 7-bit addresses might respond, so the first byte of the 10-bit address must be repeated to prevent that. The format of the 10-bit address is shown as follows. Bits Usage 11110 Bits 7 through 3 of the first byte are constants. This guarantees that the first byte of the 10-bit address will fall within the reserved range of the 7-bit addresses. A9:A8 Bits 2 through 1 of the first byte are the two high-order bits of the 10-bit address. Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1044 R/W Bit 0 of the first byte is the Read/Write bit (0 = Read, 1 = Write). A7:A0 The second byte contains the 8 low-order bits of the 10-bit address. See Operating as a Master Transmitter and Operating as a Master Receiver for examples. Operating in Slave Mode In Slave mode, the "slave address" refers to the address (and optional mask) programmed into the I2C module to determine to which address or addresses the module will respond when addressed by an external master. The "raw" (unformatted) address is passed to or returned from the Managing Slave Addresses routines (without being formatted as previously shown). Likewise, the mask passed to or returned from the Slave Mask Control Functions (see the Library Interface section) is unformatted. Operating in Master Mode In Master mode, the "slave address" refers to the address transmitted on the I2C bus to identify the slave target of the transfer. In these cases, the slave address must be correctly formatted (as previously shown) and sent on the bus one byte at a time. Forming Transfers Forming Transfers Transfers are formed by chaining the basic "building blocks" shown in the following transfer format legend. The following are all valid I2C transfer formats: • This format allows a master to transmit n bytes of data to an I2C slave supporting a 7-bit address. • This format allows a master to receive n+1 bytes of data from a "streaming" slave. Such a slave has no internal addressing capability. That is, it has no internal registers or addresses. It can only "stream" data to a master that reads from it. • This format allows a master to write n bytes of data to a slave, followed immediately by reading n+1 bytes of data from a slave by sending a repeated Start condition after the first transfer. This format is useful for specifying an internal address to a device, and then reading data from that address. A repeated Start condition can also be used to chain transfers together without letting the bus go idle and potentially losing arbitration. • The following format allows a master to send n bytes of data to a target supporting a 10-bit address. Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1045 • This format is used to receive n+1 bytes of data from a slave supporting a 10-bit address. The repeated Start condition must be used because the second byte of the 10-bit address must be sent after the first byte of the 10-bit address. Then, the direction of the transfer must be switched to a "read". To do this, after the repeated Start, the master repeats the first byte of the 10-bit address with a "read" indication in the low-order bit and 10-bit slave devices must "remember" if they were being addressed once the transfer has started. • This format allows a master to send n bytes of data to a slave device supporting a 10-bit address and immediately read n+1 bytes of data from the same device using the repeated Start and resending the first byte of the 10-bit address technique as shown in the previous format. This format is useful when the master needs to read data from a specific address within a device and it needs to send that address before performing the read. • This format allows a master to chain writes to multiple slaves supporting 10-bit addresses. • This format allows a master to chain multiple writes to different slaves. Note that only the first write can be to a slave supporting a 7-bit address. The second (and any subsequent) writes must be to slaves with 10-bit addresses once any 10-bit device has been addressed. • This format can be used by a "hardware" master that does not have a programmable address. This allows the hardware master to broadcast to all slaves on the bus using the "General Call" address, followed by the master's address. (The master address is generally the same as the device's slave address if it can also act as a slave device.) This format is not normally used by a microcontroller acting as a master. However, it may be received by a microcontroller if such a hardware master exists on the bus. Handling Errors There are three basic types of errors that can occur during various I2C operations: • Transmitter Overflow • Receiver Overflow • Arbitration Loss Handling Transmitter Overflow Errors A transmitter overflow error occurs when the software attempts to write to the TX buffer (by calling the PLIB_I2C_TransmitterByteSend function) while the transmitter is busy. When this occurs, the write is not allowed and the transmitter overflow status bit is set. This can be identified by calling the PLIB_I2C_TransmitterOverflowHasOccurred function. Additional attempts to write to the TX buffer will not be allowed until the transmitter overflow error is cleared by calling the PLIB_I2C_TransmitterOverflowClear function. This sort of error should be either avoided by checking the PLIB_I2C_TransmitterIsReady function before attempting to send a byte or by checking for the error after attempting to send a byte. Interrupts: The transmitter overflow error does not trigger an interrupt. Peripheral Libraries Help I2C Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1046 Handling Receiver Overflow Errors A receiver overflow error occurs when an incoming byte has been completely received and is ready to be transferred to the RX buffer, but software has not yet gotten the previous byte from the RX buffer. When this happens the receiver overflow status bit is set and the incoming byte will be lost. This can happen when software does not respond quickly enough to a slave or master interrupt when receiving data. Software should check for this error before calling the PLIB_I2C_ReceivedByteGet function to get a byte from the RX buffer to determine if any data has been lost. This error can be identified by calling the PLIB_I2C_ReceiverOverflowHasOccurred function. This error must be cleared by calling the PLIB_I2C_ReceiverOverflowClear function or no additional data will be received. Interrupts: The receiver overflow error does not trigger an interrupt (although the incoming data byte does, even though it is lost.) Handling Arbitration Loss Errors Strictly speaking, arbitration loss is not an error. Rather it is a normal part of bus operation in a multi-master environment. Arbitration loss occurs when more than one master attempts to transmit on the bus at the same (or nearly the same) time. When this happens, at some point one of the masters will attempt to transmit a binary one ('1') when the other attempts to transmit a binary zero ('0'). At that point, the master transmitting the zero will win the transmission, because the zero transmission will dominate on the bus. The master detecting that the bus signals a zero when it attempted to transmit a one will lose arbitration and must immediately stop transmitting on the bus (which happens automatically). Arbitration loss can be detected during any of the following actions: • Transmission of a Start condition • Transmission of a repeated Start condition • Transmission of an address or data byte • Transmission of an acknowledge bit • Transmission of a Stop condition Arbitration loss can be identified by calling the PLIB_I2C_ArbitrationLossHasOccurred function. The arbitration loss condition can be cleared by calling the PLIB_I2C_ArbitrationLossClear function. Once arbitration loss occurs, the losing master must wait until the bus is once again idle (at which time a master interrupt will occur if arbitration loss has occurred) and retransmit the transfer from the beginning. Interrupts: The I2C module will trigger an error interrupt when arbitration loss occurs. Other Features Other Features Note: The following features are not available on all devices. Please refer to the specific device data sheet to determine which features are supported by your device. General Call Address Support The I2C General Call address (reserved address 0) allows a master to address all slave devices on the bus. During slave operation the module can be made to respond to or ignore the general call address using the PLIB_I2C_GeneralCallEnable function or the PLIB_I2C_GeneralCallDisable function. When a slave address byte is received, software can identify if it was the general call address using the PLIB_I2C_SlaveAddressIsGeneralCall function (or by checking the value of the address byte received). Note: The general call address is always 7-bits. SMBus Support The I2C module can support communication on a System Management Bus (SMBus) by calling the PLIB_I2C_SMBEnable function to adjust the electrical characteristics of the SMBus. Operation During Sleep Mode When the device enters Sleep mode, all clock sources supplied to the I2C modules are shut down. If the device enters Sleep mode in the middle of an I2C master transmission or reception operation, the operation is aborted. If the device enters Sleep mode when the module is operating in slave mode, the external master's clock will continue run the slave state machine. If a slave address match occurs, an interrupt will be provided to wake up the device. Note: Indeterminate results can occur if an error occurs during Sleep mode. Operation During Idle Mode When the device enters Idle mode, the system clock sources remain functional and the CPU stops code execution. I2C operation during Idle mode can be controlled using the PLIB_I2C_StopInIdleEnable function or the PLIB_I2C_StopInIdleDisable function. By default, the I2C module continues to operate in Idle mode and provide full functionality. Operation with DMA Software activity must occur between the transfer of each byte, making DMA inappropriate for use with the I2C module. Peripheral Libraries Help I2C Peripheral Library Configuring the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1047 Configuring the Library This library is appropriate for microcontrollers with a dedicated I2C module (not an SSP or MSSP module). The library is configured for the supported I2C module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Initialization Functions Name Description PLIB_I2C_Disable Disables the specified I2C module. PLIB_I2C_Enable Enables the specified I2C module. PLIB_I2C_GeneralCallDisable Disables the I2C module from recognizing the general call address. PLIB_I2C_GeneralCallEnable Enables the I2C module to recognize the general call address. PLIB_I2C_HighFrequencyDisable Disables the I2C module from using high frequency (400 kHz or 1 MHz) signaling. PLIB_I2C_HighFrequencyEnable Enables the I2C module to use high frequency (400 kHz or 1 MHz) signaling. PLIB_I2C_IPMIDisable Disables the I2C module's support for the IPMI specification PLIB_I2C_IPMIEnable Enables the I2C module to support the Intelligent Platform Management Interface (IPMI) specification (see Remarks). PLIB_I2C_ReservedAddressProtectDisable Disables the I2C module from protecting reserved addresses, allowing it to respond to them. PLIB_I2C_ReservedAddressProtectEnable Enables the I2C module to protect (not respond to) reserved addresses. PLIB_I2C_SlaveClockStretchingDisable Disables the I2C module from stretching the slave clock. PLIB_I2C_SlaveClockStretchingEnable Enables the I2C module to stretch the slave clock. PLIB_I2C_SMBDisable Disable the I2C module support for SMBus electrical signaling levels. PLIB_I2C_SMBEnable Enables the I2C module to support System Management Bus (SMBus) electrical signaling levels. PLIB_I2C_StopInIdleDisable Disables the Stop-in-Idle feature. PLIB_I2C_StopInIdleEnable Enables the I2C module to stop when the processor enters Idle mode b) General Status Functions Name Description PLIB_I2C_ArbitrationLossClear Clears the arbitration loss status flag PLIB_I2C_ArbitrationLossHasOccurred Identifies if bus arbitration has been lost. PLIB_I2C_BusIsIdle Determines whether the I2C bus is idle or busy. PLIB_I2C_StartClear Clears the start status flag PLIB_I2C_StartWasDetected Identifies when a Start condition has been detected. PLIB_I2C_StopClear Clears the stop status flag PLIB_I2C_StopWasDetected Identifies when a Stop condition has been detected c) Baud Rate Generator Control Functions Name Description PLIB_I2C_BaudRateGet Calculates the I2C module's current SCL clock frequency. PLIB_I2C_BaudRateSet Sets the desired baud rate. d) Slave Address Control Functions Name Description PLIB_I2C_SlaveAddress10BitGet Identifies the current 10-bit Slave mode address. PLIB_I2C_SlaveAddress10BitSet Selects 10-bit Slave mode addressing and sets the address value. PLIB_I2C_SlaveAddress10BitWasDetected Detects reception of the second byte of a 10-bit slave address. PLIB_I2C_SlaveAddress7BitGet Identifies the current 7-bit Slave mode address. PLIB_I2C_SlaveAddress7BitSet Selects 7-bit Slave mode addressing and sets the slave address value. PLIB_I2C_SlaveAddressHoldDisable Disables Address holding. PLIB_I2C_SlaveAddressHoldEnable Enables address holding. PLIB_I2C_SlaveAddressIsDetected Detects if the most recent byte received is a data or an address byte. PLIB_I2C_SlaveAddressIsGeneralCall Identifies if the current slave address received is the general call address. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1048 PLIB_I2C_SlaveAddressModeIs10Bits Identifies if the current slave address mode is 7-bits or 10-bits. PLIB_I2C_SlaveDataIsDetected Detects if the most recent byte received is a data or an address byte. PLIB_I2C_SlaveReadIsRequested Detects if the request from the master was a read or write. e) Slave Mask Control Functions Name Description PLIB_I2C_SlaveMask10BitGet Identifies the current 10-bit Slave mode address mask. PLIB_I2C_SlaveMask10BitSet Sets the 10-bit mask for Slave mode addressing. PLIB_I2C_SlaveMask7BitGet Identifies the current 7-bit Slave mode address mask. PLIB_I2C_SlaveMask7BitSet Sets the 7-bit mask for Slave mode addressing . f) Slave Control Functions Name Description PLIB_I2C_AcksequenceIsInProgress Checks whether the acknowledge sequence is in progress or it is completed. PLIB_I2C_DataLineHoldTimeSet Sets the data line hold time. PLIB_I2C_SlaveBufferOverwriteDisable Disables buffer overwrite. PLIB_I2C_SlaveBufferOverwriteEnable Enables buffer overwrite. PLIB_I2C_SlaveBusCollisionDetectDisable Disables bus collision detect interrupts. PLIB_I2C_SlaveBusCollisionDetectEnable Enables slave bus collision interrupts. PLIB_I2C_SlaveClockHold Holds the SCL clock line low after receiving a byte. PLIB_I2C_SlaveClockRelease Releases a previously held SCL clock line. PLIB_I2C_SlaveDataHoldDisable Disables data holding. PLIB_I2C_SlaveDataHoldEnable Enables data holding. PLIB_I2C_SlaveInterruptOnStartDisable Disables the feature of generating interrupt on start condition. PLIB_I2C_SlaveInterruptOnStartEnable Enables the feature of generating interrupt on start condition. PLIB_I2C_SlaveInterruptOnStopDisable Disables the feature of generating interrupt on stop condition. PLIB_I2C_SlaveInterruptOnStopEnable Enables the feature of generating interrupt on stop condition. g) Master Control Functions Name Description PLIB_I2C_MasterReceiverClock1Byte Drives the bus clock to receive 1 byte of data from a slave device. PLIB_I2C_MasterStart Sends an I2C Start condition on the I2C bus in Master mode. PLIB_I2C_MasterStartRepeat Sends a repeated Start condition during an ongoing transfer in Master mode. PLIB_I2C_MasterStop Sends an I2C Stop condition to terminate a transfer in Master mode. h) Transmitter Control Functions Name Description PLIB_I2C_TransmitterByteHasCompleted Detects whether the module has finished transmitting the most recent byte. PLIB_I2C_TransmitterByteSend Sends a byte of data on the I2C bus. PLIB_I2C_TransmitterByteWasAcknowledged Determines whether the most recently sent byte was acknowledged. PLIB_I2C_TransmitterIsBusy Identifies if the transmitter of the specified I2C module is currently busy (unable to accept more data). PLIB_I2C_TransmitterIsReady Detects if the transmitter is ready to accept data to transmit. PLIB_I2C_TransmitterOverflowClear Clears the transmitter overflow status flag. PLIB_I2C_TransmitterOverflowHasOccurred Identifies if a transmitter overflow error has occurred. i) Receiver Control Functions Name Description PLIB_I2C_ReceivedByteAcknowledge Allows a receiver to acknowledge a that a byte of data has been received. PLIB_I2C_ReceivedByteGet Gets a byte of data received from the I2C bus interface. PLIB_I2C_ReceivedByteIsAvailable Detects whether the receiver has data available. PLIB_I2C_ReceiverByteAcknowledgeHasCompleted Determines if the previous acknowledge has completed. PLIB_I2C_ReceiverOverflowClear Clears the receiver overflow status flag. PLIB_I2C_ReceiverOverflowHasOccurred Identifies if a receiver overflow error has occurred. PLIB_I2C_MasterReceiverReadyToAcknowledge Checks whether the hardware is ready to acknowledge. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1049 j) Feature Existence Functions Name Description PLIB_I2C_ExistsAcksequenceProgress Identifies whether the AcksequenceIsInProgress feature exists on the I2C module. PLIB_I2C_ExistsArbitrationLoss Identifies whether the ArbitrationLoss feature exists on the I2C module. PLIB_I2C_ExistsBaudRate Identifies whether the BaudRate feature exists on the I2C module. PLIB_I2C_ExistsBusIsIdle Identifies whether the BusIdle feature exists on the I2C module. PLIB_I2C_ExistsClockStretching Identifies whether the ClockStretching feature exists on the I2C module. PLIB_I2C_ExistsDataLineHoldTime Identifies whether the DataLineHoldTime feature exists on the I2C module. PLIB_I2C_ExistsGeneralCall Identifies whether the GeneralCall feature exists on the I2C module. PLIB_I2C_ExistsGeneralCallAddressDetect Identifies whether the GeneralCallAddressDetect feature exists on the I2C module. PLIB_I2C_ExistsHighFrequency Identifies whether the HighFrequency feature exists on the I2C module. PLIB_I2C_ExistsIPMI Identifies whether the IPMI feature exists on the I2C module. PLIB_I2C_ExistsMasterReceiverClock1Byte Identifies whether the MasterReceiverClock1Byte feature exists on the I2C module. PLIB_I2C_ExistsMasterStart Identifies whether the MasterStart feature exists on the I2C module. PLIB_I2C_ExistsMasterStartRepeat Identifies whether the MasterStartRepeat feature exists on the I2C module. PLIB_I2C_ExistsMasterStop Identifies whether the MasterStop feature exists on the I2C module. PLIB_I2C_ExistsModuleEnable Identifies whether the ModuleEnable feature exists on the I2C module. PLIB_I2C_ExistsReceivedByteAcknowledge Identifies whether the ReceivedByteAcknowledge feature exists on the I2C module. PLIB_I2C_ExistsReceivedByteAvailable Identifies whether the ReceivedByteAvailable feature exists on the I2C module PLIB_I2C_ExistsReceivedByteGet Identifies whether the ReceivedByteGet feature exists on the I2C module PLIB_I2C_ExistsReceiverOverflow Identifies whether the ReceiverOverflow feature exists on the I2C module. PLIB_I2C_ExistsReservedAddressProtect Identifies whether the ReservedAddressProtect feature exists on the I2C module. PLIB_I2C_ExistsSlaveAddress10Bit Identifies whether the SlaveAddress10Bit feature exists on the I2C module. PLIB_I2C_ExistsSlaveAddress7Bit Identifies whether the SlaveAddress7Bit feature exists on the I2C module. PLIB_I2C_ExistsSlaveAddressDetect Identifies whether the SlaveAddressDetect feature exists on the I2C module. PLIB_I2C_ExistsSlaveAddressHoldEnable Identifies whether the SlaveAddressHoldEnable feature exists on the I2C module. PLIB_I2C_ExistsSlaveBufferOverwrite Identifies whether the SlaveBufferOverwrite feature exists on the I2C module. PLIB_I2C_ExistsSlaveBusCollisionDetect Identifies whether the SlaveBusCollisionDetect feature exists on the I2C module. PLIB_I2C_ExistsSlaveClockHold Identifies whether the SlaveClockHold feature exists on the I2C module. PLIB_I2C_ExistsSlaveDataDetect Identifies whether the SlaveDataDetect feature exists on the I2C module. PLIB_I2C_ExistsSlaveInterruptOnStart Identifies whether the SlaveInterruptOnStart feature exists on the I2C module. PLIB_I2C_ExistsSlaveInterruptOnStop Identifies whether the SlaveInterruptOnStop feature exists on the I2C module. PLIB_I2C_ExistsSlaveMask Identifies whether the SlaveMask feature exists on the I2C module. PLIB_I2C_ExistsSlaveReadRequest Identifies whether the SlaveReadRequest feature exists on the I2C module. PLIB_I2C_ExistsSMBus Identifies whether the SMBus feature exists on the I2C module. PLIB_I2C_ExistsStartDetect Identifies whether the StartDetect feature exists on the I2C module. PLIB_I2C_ExistsStopDetect Identifies whether the StopDetect feature exists on the I2C module. PLIB_I2C_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the I2C module. PLIB_I2C_ExistsTransmitterByteAcknowledge Identifies whether the TransmitterByteAcknowledge feature exists on the I2C module. PLIB_I2C_ExistsTransmitterByteComplete Identifies whether the TransmitterByteComplete feature exists on the I2C module. PLIB_I2C_ExistsTransmitterByteSend Identifies whether the TransmitterByteSend feature exists on the I2C module. PLIB_I2C_ExistsTransmitterIsBusy Identifies whether the TransmitterBusy feature exists on the I2C module. PLIB_I2C_ExistsTransmitterOverflow Identifies whether the TransmitterOverflow feature exists on the I2C module. PLIB_I2C_ExistsSlaveDataHoldEnable Identifies whether the SlaveDataHoldEnable feature exists on the I2C module. k) Data Types and Constants Name Description I2C_MODULE_ID This is type I2C_MODULE_ID. Description This section describes the Application Programming Interface (API) functions of the I2C Peripheral Library. Refer to each section for a detailed description. a) General Initialization Functions Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1050 PLIB_I2C_Disable Function Disables the specified I2C module. File plib_i2c.h C void PLIB_I2C_Disable(I2C_MODULE_ID index); Returns None. Description This function disables the specified I2C module. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsModuleEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_Disable( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_Disable( I2C_MODULE_ID index ) PLIB_I2C_Enable Function Enables the specified I2C module. File plib_i2c.h C void PLIB_I2C_Enable(I2C_MODULE_ID index); Returns None. Description This function enables the specified I2C module. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsModuleEnable in your application to determine whether this feature is available. Preconditions The module should be appropriately configured before being enabled. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1051 Example #define MY_I2C_ID I2C_ID_1 #define MY_CLOCK_FREQUENCY 80000000 #define MY_BAUD_RATE 10000 #define MY_SLAVE_ADDRESS 0x23 PLIB_I2C_SlaveClockStretchingEnable ( MY_I2C_ID ); PLIB_I2C_SMBDisable ( MY_I2C_ID ); PLIB_I2C_HighFrequencyDisable ( MY_I2C_ID ); PLIB_I2C_ReservedAddressProtectEnable ( MY_I2C_ID ); PLIB_I2C_StopInIdleDisable ( MY_I2C_ID ); PLIB_I2C_BaudRateSet ( MY_I2C_ID, MY_CLOCK_FREQUENCY, MY_BAUD_RATE ); PLIB_I2C_SlaveAddress7BitSet( MY_I2C_ID, MY_SLAVE_ADDRESS ); PLIB_I2C_Enable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_Enable( I2C_MODULE_ID index ) PLIB_I2C_GeneralCallDisable Function Disables the I2C module from recognizing the general call address. File plib_i2c.h C void PLIB_I2C_GeneralCallDisable(I2C_MODULE_ID index); Returns None. Description This function disables the I2C module from recognizing the general call address when operating as a slave receiver. Remarks The General-call feature can be re-enabled by calling the PLIB_I2C_GeneralCallEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsGeneralCall in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_GeneralCallDisable(MY_I2C_ID); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_GeneralCallDisable ( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1052 PLIB_I2C_GeneralCallEnable Function Enables the I2C module to recognize the general call address. File plib_i2c.h C void PLIB_I2C_GeneralCallEnable(I2C_MODULE_ID index); Returns None. Description This function enables the I2C module to recognize the general call address when operating as a slave receiver. Remarks The General-call feature can be disabled by calling the PLIB_I2C_GeneralCallDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsGeneralCall in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_GeneralCallEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_GeneralCallEnable ( I2C_MODULE_ID index ) PLIB_I2C_HighFrequencyDisable Function Disables the I2C module from using high frequency (400 kHz or 1 MHz) signaling. File plib_i2c.h C void PLIB_I2C_HighFrequencyDisable(I2C_MODULE_ID index); Returns None. Description This function disables the I2C module from using high-frequency signaling, preventing it from using the 400 kHz and 1 MHz signaling rates. Remarks The high-frequency feature can be re-enabled by calling the PLIB_I2C_HighFrequencyEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsHighFrequency in your application to determine whether this feature is available. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1053 Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_HighFrequencyDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_HighFrequencyDisable ( I2C_MODULE_ID index ) PLIB_I2C_HighFrequencyEnable Function Enables the I2C module to use high frequency (400 kHz or 1 MHz) signaling. File plib_i2c.h C void PLIB_I2C_HighFrequencyEnable(I2C_MODULE_ID index); Returns None. Description This function enables the I2C module to use high-frequency signaling, allowing it to use the 400 kHz and 1 MHz signaling rates. Remarks The high-speed feature can be disabled by calling the PLIB_I2C_HighSpeedEnable function. This feature must be enabled if frequencies higher than 100 kHz programmed using the PLIB_I2C_BaudRateSet function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsHighFrequency in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_HighFrequencyEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_HighFrequencyEnable ( I2C_MODULE_ID index ) PLIB_I2C_IPMIDisable Function Disables the I2C module's support for the IPMI specification File plib_i2c.h Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1054 C void PLIB_I2C_IPMIDisable(I2C_MODULE_ID index); Returns None. Description This function disables the I2C module's support for the IPMI specification. Remarks Please refer to the IPMI specification for details of the Intelligent Platform Management Interface. The IPMI specification is the property of Intel Corporation, Hewlett-Packard Company, NEC Corporation, and Dell Inc. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsIPMI in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_IPMIDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_IPMIDisable ( I2C_MODULE_ID index ) PLIB_I2C_IPMIEnable Function Enables the I2C module to support the Intelligent Platform Management Interface (IPMI) specification (see Remarks). File plib_i2c.h C void PLIB_I2C_IPMIEnable(I2C_MODULE_ID index); Returns None. Description This function enables the I2C module to support the IPMI specification. Remarks Please refer to the IPMI specification for details of the Intelligent Platform Management Interface. The IPMI specification is the property of Intel Corporation, Hewlett-Packard Company, NEC Corporation, and Dell Inc. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsIPMI in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1055 PLIB_I2C_IPMIEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_IPMIEnable ( I2C_MODULE_ID index ) PLIB_I2C_ReservedAddressProtectDisable Function Disables the I2C module from protecting reserved addresses, allowing it to respond to them. File plib_i2c.h C void PLIB_I2C_ReservedAddressProtectDisable(I2C_MODULE_ID index); Returns None. Description This function disables the I2C module from protecting reserved addresses, allowing it to respond to them when they match the module's slave address and mask. Remarks The reserved-address-protect feature can be re-enabled by calling the PLIB_I2C_ReservedAddressProtectEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReservedAddressProtect in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_ReservedAddressProtectDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_ReservedAddressProtectDisable ( I2C_MODULE_ID index ) PLIB_I2C_ReservedAddressProtectEnable Function Enables the I2C module to protect (not respond to) reserved addresses. File plib_i2c.h C void PLIB_I2C_ReservedAddressProtectEnable(I2C_MODULE_ID index); Returns None. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1056 Description This function enables the I2C module to protect reserved addresses by not responding to them, even if they match the module's slave address and mask. Remarks The reserved-address-protect feature can be disabled by calling the PLIB_I2C_ReservedAddressProtectDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReservedAddressProtect in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_ReservedAddressProtectEnable(MY_I2C_ID); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_ReservedAddressProtectEnable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveClockStretchingDisable Function Disables the I2C module from stretching the slave clock. File plib_i2c.h C void PLIB_I2C_SlaveClockStretchingDisable(I2C_MODULE_ID index); Returns None. Description This function disables the I2C module from stretching the slave clock to allow time for software to respond to bytes received from the master. Remarks The clock stretching feature can be re-enabled by calling the PLIB_I2C_SlaveClockStretchingEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsClockStretching in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveClockStretchingDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1057 Function void PLIB_I2C_SlaveClockStretchingDisable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveClockStretchingEnable Function Enables the I2C module to stretch the slave clock. File plib_i2c.h C void PLIB_I2C_SlaveClockStretchingEnable(I2C_MODULE_ID index); Returns None. Description This function enables the I2C module to stretch the slave clock to allow time for software to respond to bytes received from the master. Remarks The clock stretching feature can be disabled by calling the PLIB_I2C_SlaveClockStretchingDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsClockStretching in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveClockStretchingEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveClockStretchingEnable ( I2C_MODULE_ID index ) PLIB_I2C_SMBDisable Function Disable the I2C module support for SMBus electrical signaling levels. File plib_i2c.h C void PLIB_I2C_SMBDisable(I2C_MODULE_ID index); Returns None. Description This function disables the I2C module support for SMBus electrical signaling levels. Remarks The SMB feature can be re-enabled by calling the PLIB_I2C_SMBEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1058 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSMBus in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SMBDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SMBDisable ( I2C_MODULE_ID index ) PLIB_I2C_SMBEnable Function Enables the I2C module to support System Management Bus (SMBus) electrical signaling levels. File plib_i2c.h C void PLIB_I2C_SMBEnable(I2C_MODULE_ID index); Returns None. Description This function enables the I2C module to support SMBus electrical signaling levels. Remarks The SMB feature can be disabled by calling the PLIB_I2C_SMBDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSMBus in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SMBEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SMBEnable ( I2C_MODULE_ID index ) PLIB_I2C_StopInIdleDisable Function Disables the Stop-in-Idle feature. File plib_i2c.h Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1059 C void PLIB_I2C_StopInIdleDisable(I2C_MODULE_ID index); Returns None. Description This function disables the Stop-in-Idle feature, preventing the I2C module from stopping when the processor enters Idle mode. Remarks The Stop-in-Idle feature can be re-enabled by calling the PLIB_I2C_StopInIdleEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_StopInIdleDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_StopInIdleDisable ( I2C_MODULE_ID index ) PLIB_I2C_StopInIdleEnable Function Enables the I2C module to stop when the processor enters Idle mode File plib_i2c.h C void PLIB_I2C_StopInIdleEnable(I2C_MODULE_ID index); Returns None. Description This function enables the I2C module to stop when the processor enters Idle mode. Remarks The Stop-in-Idle feature can be disabled by calling the PLIB_I2C_StopInIdleDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_StopInIdleEnable ( MY_I2C_ID ); Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1060 Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_StopInIdleEnable ( I2C_MODULE_ID index ) b) General Status Functions PLIB_I2C_ArbitrationLossClear Function Clears the arbitration loss status flag File plib_i2c.h C void PLIB_I2C_ArbitrationLossClear(I2C_MODULE_ID index); Returns None. Description This function clears the arbitration loss status flag. Remarks This flag is set by hardware when bus arbitration loss occurs. Its status can be tested using the PLIB_I2C_ArbitrationLossHasOccurred function. This flag should be cleared by software after the arbitration loss has been handled. To handle the error, the entire transmission (from the Start condition to the Stop or restart condition) must be retried later when the bus becomes idle. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsArbitrationLoss in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_ArbitrationLossHasOccurred ( MY_I2C_ID ) ) { // Handle bus collision PLIB_I2C_ArbitrationLossClear ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_ArbitrationLossClear ( I2C_MODULE_ID index ) PLIB_I2C_ArbitrationLossHasOccurred Function Identifies if bus arbitration has been lost. File plib_i2c.h Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1061 C bool PLIB_I2C_ArbitrationLossHasOccurred(I2C_MODULE_ID index); Returns • true - If software if a bus collision occurred, resulting in loss of bus arbitration • false - If no bus collision occurred Description This function identifies if bus arbitration has been lost. Remarks The arbitration status should be checked after any Master mode transmission or if an error interrupt occurs. If a bus collision occurs, the entire transmission (from the Start condition to the Stop or restart condition) must be retried later when the bus becomes idle. This flag should be cleared by software using the PLIB_I2C_ArbitrationLossClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsArbitrationLoss in your application to determine whether this feature is available. Preconditions Bus collisions can occur during any master-mode transmission including: • Sending a Start condition • Sending a repeated Start condition • Sending an address or data byte • sending an ACK/NAK bit • Sending a Stop condition Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_ArbitrationLossHasOccurred ( MY_I2C_ID ) ) { // Handle bus collision PLIB_I2C_ArbitrationLossClear( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_ArbitrationLossHasOccurred ( I2C_MODULE_ID index ) PLIB_I2C_BusIsIdle Function Determines whether the I2C bus is idle or busy. File plib_i2c.h C bool PLIB_I2C_BusIsIdle(I2C_MODULE_ID index); Returns • true - The bus is currently idle. It is safe to start a master transfer. • false - The bus is currently busy. Do not start a master transfer. Description This function checks to see if the I2C bus is currently idle or if there is some activity currently taking place. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1062 Remarks When this function returns true it does not guarantee that a bus arbitration loss cannot occur. Two or more masters can start a transfer within the minimum start signal hold time. (Refer to the I2C specification for a definition of the minimum Start condition hold time.) The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsBusIsIdle in your application to determine whether this feature is available. Preconditions The module must be configured appropriately and enabled. Example #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_BusIsIdle ( MY_I2C_ID )) { PLIB_I2C_MasterStart ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_BusIsIdle ( I2C_MODULE_ID index ) PLIB_I2C_StartClear Function Clears the start status flag File plib_i2c.h C void PLIB_I2C_StartClear(I2C_MODULE_ID index); Returns None. Description This function clears the start status flag. Remarks This flag is cleared automatically by the hardware when a Stop condition is detected, but it can also be cleared by software. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStartDetect in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_StartWasDetected( MY_I2C_ID ) ) { // Handle Start condition PLIB_I2C_StartClear(MY_I2C_ID); } Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1063 Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_StartClear ( I2C_MODULE_ID index ) PLIB_I2C_StartWasDetected Function Identifies when a Start condition has been detected. File plib_i2c.h C bool PLIB_I2C_StartWasDetected(I2C_MODULE_ID index); Returns • true - A Start Condition has been detected • false - No Start condition has been detected since the last time a Stop condition was detected (or the module was initialized) Description This function identifies when a Start condition has been detected. Remarks This flag is cleared automatically by the hardware when a stop condition is detected, but it can also be cleared by software using PLIB_I2C_StartClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStartDetect in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_StartWasDetected ( MY_I2C_ID ) ) { // Handle Start condition } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_StartWasDetected ( I2C_MODULE_ID index ) PLIB_I2C_StopClear Function Clears the stop status flag File plib_i2c.h C void PLIB_I2C_StopClear(I2C_MODULE_ID index); Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1064 Returns None. Description This function clears the stop status flag. Remarks This flag is cleared automatically by the hardware when a Start condition is detected, but it can also be cleared by software. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStopDetect in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_StopWasDetected ( MY_I2C_ID ) ) { // Handle stop condition PLIB_I2C_StopClear ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_StopClear ( I2C_MODULE_ID index ) PLIB_I2C_StopWasDetected Function Identifies when a Stop condition has been detected File plib_i2c.h C bool PLIB_I2C_StopWasDetected(I2C_MODULE_ID index); Returns • true - A Stop condition has been detected • false - No Stop condition has been detected since the last time a Start condition was detected (or the module was initialized) Description This function identifies when a Stop condition has been detected. Remarks This flag is cleared automatically by the hardware when a Start condition is detected, but it can also be cleared by software using the PLIB_I2C_StopClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStopDetect in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1065 Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_StopWasDetected ( MY_I2C_ID ) ) { // Handle stop condition } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_StopWasDetected ( I2C_MODULE_ID index ) c) Baud Rate Generator Control Functions PLIB_I2C_BaudRateGet Function Calculates the I2C module's current SCL clock frequency. File plib_i2c.h C I2C_BAUD_RATE PLIB_I2C_BaudRateGet(I2C_MODULE_ID index, uint32_t clockFrequencyHz); Returns SCL frequency currently used Description This function calculates the I2C module's current SCL clock frequency. Remarks The actual frequency provided may be slightly different than the frequency requested due to truncation errors. The actual frequency observed on the SCL line may be lower due to clock stretching. The MY_CLOCK_FREQUENCY macro in the example is used as placeholder for the actual clock frequency. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsBaudRate in your application to determine whether this feature is available. Preconditions The returned value may not be valid if PLIB_I2C_BaudRateSet has not been previously called to set the SCL clock frequency. Example #define MY_I2C_ID I2C_ID_1 #define MY_CLOCK_FREQ_INPUT 80000000 uint32_t myBaudRate; myBaudRate = PLIB_I2C_BaudRateGet ( MY_I2C_ID, MY_CLOCK_FREQ_INPUT ); Parameters Parameters Description index Identifies the desired I2C module clockFrequencyHz Clock Frequency (Hz) provided for the I2C module Function I2C_BAUD_RATE PLIB_I2C_BaudRateGet ( I2C_MODULE_ID index, uint32_t clockFrequencyHz ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1066 PLIB_I2C_BaudRateSet Function Sets the desired baud rate. File plib_i2c.h C void PLIB_I2C_BaudRateSet(I2C_MODULE_ID index, uint32_t clockFrequencyHz, I2C_BAUD_RATE baudRate); Returns None. Description This function sets the desired baud rate so that the I2C module will operate at the desired clock frequency (on the SCL line of the bus.) Remarks IMPORTANT: The I2C module's high-frequency mode must be enabled for frequencies higher than 100 kHz using the PLIB_I2C_HighFrequencyEnable function. Otherwise, the high-frequency mode must be disabled using the PLIB_I2C_HighFrequencyDisable function. The actual frequency selected may be slightly different than the frequency requested due to truncation errors. Use the PLIB_I2C_BaudRateGet function to obtain the actual baud rate value that has been programmed. The actual frequency observed on the SCL line may be lower due to clock stretching. If the system clock is changed during an active receive operation, a receiver error or data loss may result. To avoid this issue, verify that no receptions are in progress before changing the system clock. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsBaudRate in your application to determine whether this feature is available. Preconditions The source clock, being sent to the I2C module (internal to the microcontroller) must be operating at the frequency passed. Example #define MY_I2C_ID I2C_ID_1 #define MY_CLOCK_FREQUENCY_INPUT 80000000 PLIB_I2C_HighFrequencyDisable ( MY_I2C_ID ); PLIB_I2C_BaudRateSet ( MY_I2C_ID, MY_CLOCK_FREQUENCY_INPUT, 40000 ); Parameters Parameters Description index Identifies the desired I2C module clockFrequencyHz Clock Frequency (Hz) baudRate The desired baud rate value. This should be an appropriate value for the frequency and microcontroller in use. Function void PLIB_I2C_BaudRateSet ( I2C_MODULE_ID index, uint32_t clockFrequencyHz, I2C_BAUD_RATE baudRate ) d) Slave Address Control Functions PLIB_I2C_SlaveAddress10BitGet Function Identifies the current 10-bit Slave mode address. File plib_i2c.h Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1067 C uint16_t PLIB_I2C_SlaveAddress10BitGet(I2C_MODULE_ID index); Returns The 10-bit slave address to which the module is currently set to respond. Description This function identifies the 10-bit slave address to which the module will currently respond. Remarks The 16-bit address will be right-aligned in the 16-bit return value. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress10Bit in your application to determine whether this feature is available. Preconditions The address provided may not be valid if it has not been previously set. Example #define MY_I2C_ID I2C_ID_1 uint16_t slaveAddress; if (PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slaveAddress = PLIB_I2C_SlaveAddress10BitGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function uint16_t PLIB_I2C_SlaveAddress10BitGet ( I2C_MODULE_ID index ) PLIB_I2C_SlaveAddress10BitSet Function Selects 10-bit Slave mode addressing and sets the address value. File plib_i2c.h C void PLIB_I2C_SlaveAddress10BitSet(I2C_MODULE_ID index, uint16_t address); Returns None. Description This function selects 10-bit Slave mode addressing sets the slave address to which the module will respond when operating in Slave mode. Remarks I2C modules on some microcontroller families may also support an address mask (to allow the module to respond to multiple addresses. When using these microcontrollers, the PLIB_I2C_SlaveAddress10BitSetMasked may be used to support the mask feature. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_SLAVE_ADDRESS_10_BIT macro in the example is used as a placeholder for the actual desired slave address. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress10Bit in your application to determine whether this feature is available. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1068 Preconditions None Example #define MY_I2C_ID I2C_ID_1 #define MY_SLAVE_ADDR_10_BIT 0x23 PLIB_I2C_SlaveAddress10BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_10_BIT ); Parameters Parameters Description index Identifies the desired I2C module address The 10-bit slave address to which the module will respond (The address should be right-aligned in the 16-bit parameter, without any read/write bit in the 0 position) Function void PLIB_I2C_SlaveAddress10BitSet ( I2C_MODULE_ID index, uint16_t address ) PLIB_I2C_SlaveAddress10BitWasDetected Function Detects reception of the second byte of a 10-bit slave address. File plib_i2c.h C bool PLIB_I2C_SlaveAddress10BitWasDetected(I2C_MODULE_ID index); Returns • true - If the second byte of the local 10-bit address has been received • false - If the second byte of the local 10-bit address has not been received Description This function detects if the second byte of a 10-bit slave address (containing the low-order 8 bits) matching the local address has been received. Remarks This function should only be used by slave receivers. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddressDetect in your application to determine whether this feature is available. Preconditions The module must have been configured for 10-bit addressing in Slave mode, enabled, and the first byte of the 10-bit local slave address must have already been received and matched. Example #define MY_I2C_ID I2C_ID_1 uint8_t i2cReadData; if ( PLIB_I2C_SlaveAddress10BitWasDetected ( MY_I2C_ID ) ) { i2cReadData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_SlaveAddress10BitWasDetected ( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1069 PLIB_I2C_SlaveAddress7BitGet Function Identifies the current 7-bit Slave mode address. File plib_i2c.h C uint8_t PLIB_I2C_SlaveAddress7BitGet(I2C_MODULE_ID index); Returns The 7-bit slave address to which the module is currently set to respond. Description This function identifies the 7-bit slave address to which the module will currently respond. Remarks The 7-bit address will be right-aligned in the 8-bit return value. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress7Bit in your application to determine whether this feature is available. Preconditions The address provided may not be valid if it has not been previously set. Example #define MY_I2C_ID I2C_ID_1 uint8_t slave_address7bit; if (!PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slave_address7bit = PLIB_I2C_SlaveAddress7BitGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function uint8_t PLIB_I2C_SlaveAddress7BitGet ( I2C_MODULE_ID index ) PLIB_I2C_SlaveAddress7BitSet Function Selects 7-bit Slave mode addressing and sets the slave address value. File plib_i2c.h C void PLIB_I2C_SlaveAddress7BitSet(I2C_MODULE_ID index, uint8_t address); Returns None. Description This function selects 7-bit Slave mode addressing sets the address to which the module will respond when operating in Slave mode. Remarks I2C modules on some microcontroller families may also support an address mask (to allow the module to respond to multiple addresses. When using these microcontrollers, the PLIB_I2C_SlaveAddress7BitSetMasked may be used to support the mask feature. Refer to the specific device Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1070 data sheet to determine whether this feature is supported for your device. The MY_SLAVE_ADDRESS_7_BIT macro in the example is used as a placeholder for the actual desired slave address. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress7Bit in your application to determine whether this feature is available. Preconditions None Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveAddress7BitSet ( MY_I2C_ID, MY_SLAVE_ADDRESS_7_BIT ); Parameters Parameters Description index Identifies the desired I2C module address The 7-bit slave address to which the module will respond (The address should be right-aligned in the 8-bit parameter, without any read/write bit in the 0 position) Function void PLIB_I2C_SlaveAddress7BitSet ( I2C_MODULE_ID index, uint8_t address ) PLIB_I2C_SlaveAddressHoldDisable Function Disables Address holding. File plib_i2c.h C void PLIB_I2C_SlaveAddressHoldDisable(I2C_MODULE_ID index); Returns None. Description This function disables address holding. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveAddressHoldEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveAddressHoldDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveAddressHoldDisable ( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1071 PLIB_I2C_SlaveAddressHoldEnable Function Enables address holding. File plib_i2c.h C void PLIB_I2C_SlaveAddressHoldEnable(I2C_MODULE_ID index); Returns None. Description This function enables address holding. If address byte is received, following the 8th falling edge of clock for a clock line will be held low. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveAddressHoldEnable in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveAddressHoldEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveAddressHoldEnable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveAddressIsDetected Function Detects if the most recent byte received is a data or an address byte. File plib_i2c.h C bool PLIB_I2C_SlaveAddressIsDetected(I2C_MODULE_ID index); Returns • true - If the byte received is an address byte • false - If the byte received is a data byte Description This function identifies if the most recent byte received was a data byte or an address byte. Remarks This function should only be used by slave receivers. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveReadRequest in your application to determine whether this feature is available. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1072 Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started. Example #define MY_I2C_ID I2C_ID_1 uint8_t getData; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { if ( PLIB_I2C_SlaveAddressIsDetected ( MY_I2C_ID ) ) { if ( PLIB_I2C_SlaveReadIsRequested ( MY_I2C_ID ) ) { // Begin slave transmit mode } else { // Begin slave receive mode } } // Read the data and release the bus getData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); PLIB_I2C_SlaveClockRelease ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_SlaveAddressIsDetected ( I2C_MODULE_ID index ) PLIB_I2C_SlaveAddressIsGeneralCall Function Identifies if the current slave address received is the general call address. File plib_i2c.h C bool PLIB_I2C_SlaveAddressIsGeneralCall(I2C_MODULE_ID index); Returns • true - If the slave address received is the general call address • false - if the slave address received is not the general call address Description This function identifies if the current slave address received is the general call address. Remarks This bit is set when the general call address has been received. This bit is automatically cleared by hardware when a Stop condition occurs and cannot be cleared by software. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsGeneralCallAddressDetect in your application to determine whether this feature is available. Preconditions A slave address must have been received. Example #define MY_I2C_ID I2C_ID_1 Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1073 uint8_t slaveAddress7Bit; if ( !PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { if ( PLIB_I2C_SlaveAddressIsGeneralCall( MY_I2C_ID ) ) { // Handle general call address } slaveAddress7Bit = PLIB_I2C_SlaveAddress7BitGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_SlaveAddressIsGeneralCall ( I2C_MODULE_ID index ) PLIB_I2C_SlaveAddressModeIs10Bits Function Identifies if the current slave address mode is 7-bits or 10-bits. File plib_i2c.h C bool PLIB_I2C_SlaveAddressModeIs10Bits(I2C_MODULE_ID index); Returns • true - If the current slave addressing mode is 10-bits • false - if the current slave addressing mode is 7-bits Description This function identifies if the current slave addressing mode is 7-bits or 10-bits. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress10Bit in your application to determine whether this feature is available. Preconditions The mode provided may not be valid if the address mode has not been previously set. Example uint8_t slave_address7Bit; uint16_t slave_address10Bit; if ( PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slave_address10Bit = PLIB_I2C_SlaveAddress10BitGet ( MY_I2C_ID ); } else { slave_address7Bit = PLIB_I2C_SlaveAddress7BitGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_SlaveAddressModeIs10Bits ( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1074 PLIB_I2C_SlaveDataIsDetected Function Detects if the most recent byte received is a data or an address byte. File plib_i2c.h C bool PLIB_I2C_SlaveDataIsDetected(I2C_MODULE_ID index); Returns • true - If the byte received is a data byte • false - If the byte received is an address byte Description This function identifies if the most recent byte received was a data byte or an address byte. Remarks This function should only be used by slave receivers. This function returns the opposite of the PLIB_I2C_SlaveAddressIsDetected function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveDataDetect in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started. Example #define MY_I2C_ID I2C_ID_1 uint8_t dataReceived; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { if ( PLIB_I2C_SlaveDataIsDetected( MY_I2C_ID ) ) { // Read the data and release the bus dataReceived = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); PLIB_I2C_SlaveClockRelease ( MY_I2C_ID ); } } Parameters Parameters Description index Identifies the desired I2C module. Function bool PLIB_I2C_SlaveDataIsDetected ( I2C_MODULE_ID index ) PLIB_I2C_SlaveReadIsRequested Function Detects if the request from the master was a read or write. File plib_i2c.h C bool PLIB_I2C_SlaveReadIsRequested(I2C_MODULE_ID index); Returns • true - If an external master is requesting data (slave read/transmit) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1075 • false - If an external master is sending data (slave write/receive) Description This function identifies if a slave read (transmit) or a slave write (receive) was requested by the master that addressed the module. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveReadRequest in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started. Example #define MY_I2C_ID I2C_ID_1 uint8_t slaveTxData; uint8_t slaveRxData; if ( PLIB_I2C_SlaveReadIsRequested ( MY_I2C_ID ) ) { if ( PLIB_I2C_TransmitterIsReady ( MY_I2C_ID ) ) { PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, slaveTxData ); } } else { slaveRxData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_SlaveReadIsRequested ( I2C_MODULE_ID index ) e) Slave Mask Control Functions PLIB_I2C_SlaveMask10BitGet Function Identifies the current 10-bit Slave mode address mask. File plib_i2c.h C uint16_t PLIB_I2C_SlaveMask10BitGet(I2C_MODULE_ID index); Returns The 10-bit slave address mask that the module is currently using to determine to which addresses the module will respond. Description This function identifies the 10-bit slave address mask that is currently being used to determine which slave addresses the module will respond. Remarks The 10-bit address mask will be Right-aligned in the 16-bit return value. This function is not supported on microcontrollers with I2C modules that do not support the slave address mask feature. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1076 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveMask in your application to determine whether this feature is available. Preconditions The address mask provided may not be valid if it has not been previously been set. Example #define MY_I2C_ID I2C_ID_1 uint16_t slave_address; uint16_t slave_addressMask; if ( PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slave_address = PLIB_I2C_SlaveAddress10BitGet ( MY_I2C_ID ); slave_addressMask = PLIB_I2C_SlaveMask10BitGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function uint16_t PLIB_I2C_SlaveMask10BitGet ( I2C_MODULE_ID index ) PLIB_I2C_SlaveMask10BitSet Function Sets the 10-bit mask for Slave mode addressing. File plib_i2c.h C void PLIB_I2C_SlaveMask10BitSet(I2C_MODULE_ID index, uint16_t mask); Returns None. Description This function sets the 10-bit mask for Slave mode addressing. The address mask (if supported) is used, along with the slave address to identify to which addresses the module will respond when operating in Slave mode. It acts as an "ignore" mask, allowing the module to ignore bits within the slave address and thus respond to multiple slave addresses on microcontrollers with I2C modules that support the mask feature. Remarks I2C modules on some microcontroller families may not support the mask feature, in which case the PLIB_I2C_SlaveMask10BitSet function will not be supported. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_SLAVE_ADDRESS_10_BIT and MY_SLAVE_ADDRESS_MASK_10_BIT macros in the example code are used as placeholders for the actual desired slave address and mask that must be filled in by the caller. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveMask in your application to determine whether this feature is available. Preconditions None Example #define MY_I2C_ID I2C_ID_1 #define MY_SLAVE_ADDR_10_BIT 0x23 #define MY_SLAVE_ADDR_MASK_10_BIT 0x12 PLIB_I2C_SlaveAddress10BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_10_BIT ); PLIB_I2C_SlaveMask10BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_MASK_10_BIT ); Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1077 Parameters Parameters Description index Identifies the desired I2C module mask This parameter identifies bits in the address that are "don't care" bits. These bits will be ignored when attempting to match the address, effectively allowing the module to recognize multiple slave addresses. (To match an address exactly, this value must be zero (0).) (This value must also be right aligned in the 16-bit parameter.) Function void PLIB_I2C_SlaveMask10BitSet ( I2C_MODULE_ID index, uint16_t mask ) PLIB_I2C_SlaveMask7BitGet Function Identifies the current 7-bit Slave mode address mask. File plib_i2c.h C uint8_t PLIB_I2C_SlaveMask7BitGet(I2C_MODULE_ID index); Returns The 7-bit Slave mode address mask that the module is currently using to determine to which addresses the module will respond. Description This function identifies the 7-bit Slave mode address mask that is currently being used to determine which slave addresses the module will respond. Remarks The 7-bit address mask will be right-aligned in the 8-bit return value. This function is not supported on microcontrollers with I2C modules that do not support the slave address mask feature. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveMask in your application to determine whether this feature is available. Preconditions The address mask provided may not be valid if it has not been previously been set. Example #define MY_I2C_ID I2C_ID_1 uint8_t slaveAddr; uint8_t slaveAddressMsk; if ( !PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slaveAddr = PLIB_I2C_SlaveAddress7BitGet ( MY_I2C_ID ); slaveAddressMsk = PLIB_I2C_SlaveMask7BitGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function uint8_t PLIB_I2C_SlaveMask7BitGet ( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1078 PLIB_I2C_SlaveMask7BitSet Function Sets the 7-bit mask for Slave mode addressing . File plib_i2c.h C void PLIB_I2C_SlaveMask7BitSet(I2C_MODULE_ID index, uint8_t mask); Returns None. Description This function sets the 7-bit mask for Slave mode addressing. The address mask (if supported) is used, along with the slave address to identify to which addresses the module will respond when operating in Slave mode. It acts as an "ignore" mask, allowing the module to ignore bits within the slave address and will respond to multiple slave addresses on microcontrollers with I2C modules that support the mask feature. Remarks I2C modules on some microcontroller families may not support the mask feature, in which case the PLIB_I2C_SlaveMask7BitSet function will not be supported. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_SLAVE_ADDRESS_7_BIT and MY_SLAVE_ADDRESS_MASK_7_BIT macros in the example code are used as placeholders for the actual desired slave address and mask that must be filled in by the caller. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveMask in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 #define MY_SLAVE_ADDR_7_BIT 0x23 #define MY_SLAVE_ADDR_MASK_7_BIT 0x12 PLIB_I2C_SlaveAddress7BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_7_BIT ); PLIB_I2C_SlaveMask7BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_MASK_7_BIT ); Parameters Parameters Description index Identifies the desired I2C module mask This parameter identifies bits in the address that are "don't care" bits. These bits will be ignored when attempting to match the address, effectively allowing the module to recognize multiple slave addresses. (To match an address exactly, this parameter must be zero (0).) Function void PLIB_I2C_SlaveMask7BitSet ( I2C_MODULE_ID index, uint8_t mask ) f) Slave Control Functions PLIB_I2C_AcksequenceIsInProgress Function Checks whether the acknowledge sequence is in progress or it is completed. File plib_i2c.h C bool PLIB_I2C_AcksequenceIsInProgress(I2C_MODULE_ID index); Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1079 Returns • true - Acknowledge sequence is in progress. • false - Acknowledge sequence is not started or completed. Description This function checks whether the acknowledge sequence is in progress or it is completed. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsAcksequenceProgress in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_AcksequenceIsInProgress ( MY_I2C_ID ) ) { //Transmission completed } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_AcksequenceIsInProgress ( I2C_MODULE_ID index ) PLIB_I2C_DataLineHoldTimeSet Function Sets the data line hold time. File plib_i2c.h C void PLIB_I2C_DataLineHoldTimeSet(I2C_MODULE_ID index, I2C_SDA_MIN_HOLD_TIME sdaHoldTimeNs); Returns None. Description This function sets the data line hold time. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsDataLineHoldTime in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_PLIB_I2C_DataLineHoldTimeSet ( MY_I2C_ID, I2C_SDA_MIN_HOLD_TIME_300NS ); Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1080 Parameters Parameters Description index Identifies the desired I2C module. sdaHoldTimeNs SDA hold time in nanoseconds. Function void PLIB_I2C_DataLineHoldTimeSet ( I2C_MODULE_ID index, I2C_SDA_MIN_HOLD_TIME sdaHoldTimeNs ) PLIB_I2C_SlaveBufferOverwriteDisable Function Disables buffer overwrite. File plib_i2c.h C void PLIB_I2C_SlaveBufferOverwriteDisable(I2C_MODULE_ID index); Returns None. Description This function disables buffer overwrite. If the buffer overwrite is disabled, on data receive, when the previous data is not read, the buffer will not be overwritten. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveBufferOverwrite in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveBufferOverwriteDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveBufferOverwriteDisable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveBufferOverwriteEnable Function Enables buffer overwrite. File plib_i2c.h C void PLIB_I2C_SlaveBufferOverwriteEnable(I2C_MODULE_ID index); Returns None. Description This function enables buffer overwrite. If the buffer overwrite is enabled, on data receive, even if the previous data is not read, the buffer will be Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1081 filled with new data and acknowledge will be generated. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveBufferOverwrite in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveBufferOverwriteEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveBufferOverwriteEnable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveBusCollisionDetectDisable Function Disables bus collision detect interrupts. File plib_i2c.h C void PLIB_I2C_SlaveBusCollisionDetectDisable(I2C_MODULE_ID index); Returns None. Description This function disables bus collision detect interrupts. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveBusCollisionDetect in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveBusCollisionDetectDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_SlaveBusCollisionDetectDisable ( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1082 PLIB_I2C_SlaveBusCollisionDetectEnable Function Enables slave bus collision interrupts. File plib_i2c.h C void PLIB_I2C_SlaveBusCollisionDetectEnable(I2C_MODULE_ID index); Returns None. Description This function enables bus collision interrupts. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveBusCollisionDetect in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveAddressHoldEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveBusCollisionDetectEnable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveClockHold Function Holds the SCL clock line low after receiving a byte. File plib_i2c.h C void PLIB_I2C_SlaveClockHold(I2C_MODULE_ID index); Returns None. Description This function allows an I2C slave to stretch the SCL clock line, holding it low to throttle data transfer from a master transmitter. Remarks This function will cause the SCL line to be forced low, after the current byte has been fully received. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveClockHold in your application to determine whether this feature is available. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1083 Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started by an external master. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveClockHold ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveClockHold ( I2C_MODULE_ID index ) PLIB_I2C_SlaveClockRelease Function Releases a previously held SCL clock line. File plib_i2c.h C void PLIB_I2C_SlaveClockRelease(I2C_MODULE_ID index); Returns None. Description This function allows a slave receiver to release a previously held SCL clock line, allowing it to go high and allowing data transfer to continue. Remarks Calling this function when the clock has not been held will not cause any problems. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveClockHold in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started by an external master, and the SCL clock line should have been previously held (forced low) by the I2C module. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveClockRelease ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveClockRelease ( I2C_MODULE_ID index ) PLIB_I2C_SlaveDataHoldDisable Function Disables data holding. File plib_i2c.h Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1084 C void PLIB_I2C_SlaveDataHoldDisable(I2C_MODULE_ID index); Returns None. Description This function disables data holding. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveDataHoldEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveDataHoldDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveDataHoldDisable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveDataHoldEnable Function Enables data holding. File plib_i2c.h C void PLIB_I2C_SlaveDataHoldEnable(I2C_MODULE_ID index); Returns None. Description This function enables data holding. If a data byte is received, following the 8th falling edge of clock for a clock line will be held low. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveDataHoldEnable in your application to determine whether this feature is available. This API is supported only for the slave mode of I2C. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveDataHoldEnable ( MY_I2C_ID ); Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1085 Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveDataHoldEnable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveInterruptOnStartDisable Function Disables the feature of generating interrupt on start condition. File plib_i2c.h C void PLIB_I2C_SlaveInterruptOnStartDisable(I2C_MODULE_ID index); Returns None. Description This function disables the feature of generating interrupt on start condition. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveInterruptOnStart in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveInterruptOnStartDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveInterruptOnStartDisable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveInterruptOnStartEnable Function Enables the feature of generating interrupt on start condition. File plib_i2c.h C void PLIB_I2C_SlaveInterruptOnStartEnable(I2C_MODULE_ID index); Returns None. Description This function enables the feature of generating interrupt on start condition. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1086 Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveInterruptOnStart in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveInterruptOnStartEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveInterruptOnStartEnable ( I2C_MODULE_ID index ) PLIB_I2C_SlaveInterruptOnStopDisable Function Disables the feature of generating interrupt on stop condition. File plib_i2c.h C void PLIB_I2C_SlaveInterruptOnStopDisable(I2C_MODULE_ID index); Returns None. Description This function disables the feature of generating interrupt on stop condition. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveInterruptOnStop in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveInterruptOnStopDisable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveInterruptOnStopDisable ( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1087 PLIB_I2C_SlaveInterruptOnStopEnable Function Enables the feature of generating interrupt on stop condition. File plib_i2c.h C void PLIB_I2C_SlaveInterruptOnStopEnable(I2C_MODULE_ID index); Returns None. Description This function enables the feature of generating interrupt on stop condition. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveInterruptOnStop in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveInterruptOnStopEnable ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_SlaveInterruptOnStopEnable ( I2C_MODULE_ID index ) g) Master Control Functions PLIB_I2C_MasterReceiverClock1Byte Function Drives the bus clock to receive 1 byte of data from a slave device. File plib_i2c.h C void PLIB_I2C_MasterReceiverClock1Byte(I2C_MODULE_ID index); Returns None. Description This function drives the bus clock to receive 1 byte of data from a slave device. Remarks The module stops driving the bus clock after the reception of a single byte of data and this function must be called again to receive another byte. After the module has finished receiving a data byte (determined by responding to an I2C master interrupt and/or by checking the Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1088 PLIB_I2C_ReceivedByteIsAvailable function), software should check the PLIB_I2C_ReceiverOverflowHasOccurred function to ensure that no data was lost because the receiver buffer was full when the byte was completely received and ready to be placed into the receiver buffer. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsMasterReceiverClock1Byte in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and the module must be the intended receiver of the next byte of data. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterReceiverClock1Byte ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_MasterReceiverClock1Byte ( I2C_MODULE_ID index ) PLIB_I2C_MasterStart Function Sends an I2C Start condition on the I2C bus in Master mode. File plib_i2c.h C void PLIB_I2C_MasterStart(I2C_MODULE_ID index); Returns None. Description This function sends the start signal (a falling edge on SDA while SCL is high) to start a transfer on the I2C bus when acting in Master mode. Remarks Only an I2C master can start a transfer on the bus. The bus is considered to be busy after a Start condition. After the Start condition has completed (detected by responding to the I2C master interrupt), software should check for arbitration loss by calling the PLIB_I2C_ArbitrationLossHasOccurred function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsMasterStart in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled and the I2C bus must currently be idle. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_BusIsIdle ( MY_I2C_ID ) ) { PLIB_I2C_MasterStart ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1089 Function void PLIB_I2C_MasterStart ( I2C_MODULE_ID index ) PLIB_I2C_MasterStartRepeat Function Sends a repeated Start condition during an ongoing transfer in Master mode. File plib_i2c.h C void PLIB_I2C_MasterStartRepeat(I2C_MODULE_ID index); Returns None. Description This function supports sending a repeated Start condition to change slave targets or transfer direction to support certain I2C transfer formats in Master mode. Remarks Only an I2C master that has already started a transfer can send a repeated Start condition. After the repeated-start condition has completed (detected by responding to the I2C master interrupt), software should check for arbitration loss by the PLIB_I2C_ArbitrationLossHasOccurred function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsMasterStartRepeat in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStartRepeat ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_MasterStartRepeat ( I2C_MODULE_ID index ) PLIB_I2C_MasterStop Function Sends an I2C Stop condition to terminate a transfer in Master mode. File plib_i2c.h C void PLIB_I2C_MasterStop(I2C_MODULE_ID index); Returns None. Description This function sends the stop signal (a rising edge on SDA while SCL is high) on the I2C bus, to end a transfer on the I2C bus when in Master mode. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1090 Remarks Only an I2C master that has already started a transfer can send a Stop condition. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsMasterStop in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately, enabled, and a previously started transfer must be completed. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStop ( MY_I2C_ID ); Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_MasterStop ( I2C_MODULE_ID index ) h) Transmitter Control Functions PLIB_I2C_TransmitterByteHasCompleted Function Detects whether the module has finished transmitting the most recent byte. File plib_i2c.h C bool PLIB_I2C_TransmitterByteHasCompleted(I2C_MODULE_ID index); Returns • true - If the transmitter has completed sending the data byte • false - If the transmitter is still busy sending the data byte Description This function determines if the transmitter has finished sending the most recently sent byte on the I2C bus. Remarks This function should be used by both master and slave transmitters. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterByteComplete in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and a data or address byte must have been sent. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_TransmitterByteHasCompleted ( MY_I2C_ID ) ) { //Transmission completed } Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1091 Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_TransmitterByteHasCompleted ( I2C_MODULE_ID index ) PLIB_I2C_TransmitterByteSend Function Sends a byte of data on the I2C bus. File plib_i2c.h C void PLIB_I2C_TransmitterByteSend(I2C_MODULE_ID index, uint8_t data); Returns None. Description This function allows the caller to send a byte of data on the I2C bus. Remarks This function should be used by both master and slave transmitters. The caller must either first call the PLIB_I2C_TransmitterIsReady function before calling this function to ensure that the transmitter is ready to receive a new byte to transmit or call the PLIB_I2C_TransmitterOverflowHasOccurred function immediately after calling this function to ensure that a transmitter write collision did not occur. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterByteSend in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and the I2C module's transmitter must be ready to accept a byte of data to send. Example #define MY_I2C_ID I2C_ID_1 uint8_t transmitData; //set 'transmitData' variable if ( PLIB_I2C_TransmitterIsReady ( MY_I2C_ID ) ) { PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, transmitData ); } Parameters Parameters Description index Identifies the desired I2C module data Data byte to send on the I2C bus Function void PLIB_I2C_TransmitterByteSend ( I2C_MODULE_ID index, uint8_t data ) PLIB_I2C_TransmitterByteWasAcknowledged Function Determines whether the most recently sent byte was acknowledged. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1092 File plib_i2c.h C bool PLIB_I2C_TransmitterByteWasAcknowledged(I2C_MODULE_ID index); Returns • true - If the receiver ACKed the byte • false - If the receiver NAKed the byte Description This function allows a transmitter to determine if the byte just sent was positively acknowledged (ACKed) or negatively acknowledged (NAKed) by the receiver. Remarks This function can be used by both master or slave transmitters. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterByteAcknowledge in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, a byte of data must have been sent on the I2C bus, and the transmission must have completed. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_TransmitterByteHasCompleted ( MY_I2C_ID ) ) { if ( PLIB_I2C_TransmitterByteWasAcknowledged ( MY_I2C_ID ) ) { // transmission successful } } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_TransmitterByteWasAcknowledged ( I2C_MODULE_ID index ) PLIB_I2C_TransmitterIsBusy Function Identifies if the transmitter of the specified I2C module is currently busy (unable to accept more data). File plib_i2c.h C bool PLIB_I2C_TransmitterIsBusy(I2C_MODULE_ID index); Returns • true - The transmitter is busy (unable to accept new data) • false - The transmitter is ready (able to accept new data) Description This function identifies if the transmitter of the specified I2C module is currently busy (unable to accept more data). Remarks This function returns the inverse of the PLIB_I2C_TransmitterIsReady function. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1093 This flag is cleared automatically by the hardware when the transmitter is ready. It cannot be cleared by software. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterIsBusy in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 uint8_t transData; //set 'transData' variable if ( !PLIB_I2C_TransmitterIsBusy( MY_I2C_ID ) ) { PLIB_I2C_TransmitterByteSend( MY_I2C_ID, transData ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_TransmitterIsBusy ( I2C_MODULE_ID index ) PLIB_I2C_TransmitterIsReady Function Detects if the transmitter is ready to accept data to transmit. File plib_i2c.h C bool PLIB_I2C_TransmitterIsReady(I2C_MODULE_ID index); Returns • true - If the transmitter is ready to accept more data • false - If the transmitter is not ready to accept more data Description This function determines if the transmitter is ready to accept more data to be transmitted on the I2C bus. Remarks This function should be used by both master and slave transmitters. This function returns the inverse of the PLIB_I2C_TransmitterIsBusy function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterIsBusy in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately, enabled, and a transfer must have been previously started. Example #define MY_I2C_ID I2C_ID_1 uint8_t sendData; //set 'sendData' variable if ( PLIB_I2C_TransmitterIsReady ( MY_I2C_ID ) ) { Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1094 PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, sendData ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_TransmitterIsReady ( I2C_MODULE_ID index ) PLIB_I2C_TransmitterOverflowClear Function Clears the transmitter overflow status flag. File plib_i2c.h C void PLIB_I2C_TransmitterOverflowClear(I2C_MODULE_ID index); Returns None. Description This function clears the transmitter overflow status flag. Remarks This flag is set by hardware when an overflow error occurs. Its status can be tested using the PLIB_I2C_TransmitterOverflowHasOccurred function. This flag must be cleared be cleared by software after the overflow error has been handled. To handle the error, software must retry the write later after the PLIB_I2C_TransmitterByteSend function returns TRUE. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterOverflow in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 uint8_t my_data; //set 'my_data' variable PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, my_data ); if ( PLIB_I2C_TransmitterOverflowHasOccurred ( MY_I2C_ID ) ) { // Handle overflow error PLIB_I2C_TransmitterOverflowClear ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_TransmitterOverflowClear ( I2C_MODULE_ID index ) PLIB_I2C_TransmitterOverflowHasOccurred Function Identifies if a transmitter overflow error has occurred. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1095 File plib_i2c.h C bool PLIB_I2C_TransmitterOverflowHasOccurred(I2C_MODULE_ID index); Returns • true - If software attempted to write a byte to the transmitter buffer while the transmitter was busy and unable to accept a new byte (i.e., the write will not occur) • false - If no transmitter overflow occurred when software attempted to write a byte to the transmitter buffer (i.e., the write occurred successfully) Description This function identifies if a transmitter overflow error has occurred. Remarks This flag must be cleared be cleared by software using the PLIB_I2C_TransmitterOverflowClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterOverflow in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 uint8_t txData; //set 'txData' variable PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, txData ); if ( PLIB_I2C_TransmitterOverflowHasOccurred ( MY_I2C_ID ) ) { // Handle overflow error PLIB_I2C_TransmitterOverflowClear ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_TransmitterOverflowHasOccurred ( I2C_MODULE_ID index ) i) Receiver Control Functions PLIB_I2C_ReceivedByteAcknowledge Function Allows a receiver to acknowledge a that a byte of data has been received. File plib_i2c.h C void PLIB_I2C_ReceivedByteAcknowledge(I2C_MODULE_ID index, bool ack); Returns None. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1096 Description This function allows a receiver to positively acknowledge (ACK) or negatively acknowledge (NAK) a byte of data that has been received from the I2C bus. Remarks This function can only be used by master receivers. Slave receivers automatically ACK or NAK bytes. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceivedByteAcknowledge in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and a byte of data must have been received from the I2C bus. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { if ( PLIB_I2C_MasterReceiverReadyToAcknowledge ( MY_I2C_ID ) ) { PLIB_I2C_ReceivedByteAcknowledge ( MY_I2C_ID, true ); data = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } } Parameters Parameters Description index Identifies the desired I2C module ack Determines how the byte should be acknowledged: • If true, positively acknowledges (ACK) the byte of data received • If false, negatively acknowledges (NAK) the byte of data received Function void PLIB_I2C_ReceivedByteAcknowledge ( I2C_MODULE_ID index, bool ack ) PLIB_I2C_ReceivedByteGet Function Gets a byte of data received from the I2C bus interface. File plib_i2c.h C uint8_t PLIB_I2C_ReceivedByteGet(I2C_MODULE_ID index); Returns A byte of data received from the I2C bus. Description This function allows the caller to read a byte of data received from the I2C bus. Remarks This function should be used by both master and slave receivers. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceivedByteGet in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and a byte of data must have Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1097 been received from the I2C bus. Example #define MY_I2C_ID I2C_ID_1 uint8_t receivedData; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { PLIB_I2C_ReceivedByteAcknowledge ( MY_I2C_ID, true ); receivedData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function uint8_t PLIB_I2C_ReceivedByteGet ( I2C_MODULE_ID index ) PLIB_I2C_ReceivedByteIsAvailable Function Detects whether the receiver has data available. File plib_i2c.h C bool PLIB_I2C_ReceivedByteIsAvailable(I2C_MODULE_ID index); Returns • true - If the receiver has data available • false - If the receiver does not have data available Description This function determines if the receiver has data available to be read by software. Remarks This function should be used by both master and slave receivers. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceivedByteAvailable in your application to determine whether this feature is available. Preconditions The I2C module must have been configured appropriately and enabled, and a transfer must have been previously started. Example #define MY_I2C_ID I2C_ID_1 uint8_t readData; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { readData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_ReceivedByteIsAvailable ( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1098 PLIB_I2C_ReceiverByteAcknowledgeHasCompleted Function Determines if the previous acknowledge has completed. File plib_i2c.h C bool PLIB_I2C_ReceiverByteAcknowledgeHasCompleted(I2C_MODULE_ID index); Returns • true - If the acknowledgment has completed • false - If the acknowledgment has not completed Description This function allows the receiver to determine if the acknowledgment signal has completed. Remarks This function can only be used by master receivers. Slave receivers automatically ACK or NAK bytes. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceivedByteAcknowledge in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, a byte of data must have been received on the I2C bus, and the acknowledgment must have been started (by calling the PLIB_I2C_ReceivedByteAcknowledge function). Example PLIB_I2C_ReceivedByteAcknowledge ( MY_I2C_ID, true ); if ( PLIB_I2C_ReceiverByteAcknowledgeHasCompleted ( MY_I2C_ID ) ) { // acknowledgment completed } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_ReceiverByteAcknowledgeHasCompleted ( I2C_MODULE_ID index ) PLIB_I2C_ReceiverOverflowClear Function Clears the receiver overflow status flag. File plib_i2c.h C void PLIB_I2C_ReceiverOverflowClear(I2C_MODULE_ID index); Returns None. Description This function clears the receiver overflow status flag. Remarks This flag is set by hardware when an overflow error occurs. Its status can be tested using the PLIB_I2C_ReceiverOverflowHasOccurred function. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1099 This flag should be cleared be cleared by software after the overflow error has been handled by reading the byte in the receiver buffer. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceiverOverflow in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_ReceiverOverflowHasOccurred ( MY_I2C_ID ) ) { // Handle overflow error PLIB_I2C_ReceiverOverflowClear ( MY_I2C_ID ); } Parameters Parameters Description index Identifies the desired I2C module Function void PLIB_I2C_ReceiverOverflowClear ( I2C_MODULE_ID index ) PLIB_I2C_ReceiverOverflowHasOccurred Function Identifies if a receiver overflow error has occurred. File plib_i2c.h C bool PLIB_I2C_ReceiverOverflowHasOccurred(I2C_MODULE_ID index); Returns • true - If a byte was received while the receiver buffer still held a previously received byte (The new byte will be lost) • false - If no receiver overflow occurred when a byte has been received Description This function identifies if a receiver overflow error has occurred. Remarks This flag should be cleared be cleared by software using the PLIB_I2C_ReceiverOverflowClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceiverOverflow in your application to determine whether this feature is available. Preconditions None. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_ReceiverOverflowHasOccurred ( MY_I2C_ID ) ) { // Handle overflow error PLIB_I2C_ReceiverOverflowClear ( MY_I2C_ID ); } Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1100 Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_ReceiverOverflowHasOccurred ( I2C_MODULE_ID index ) PLIB_I2C_MasterReceiverReadyToAcknowledge Function Checks whether the hardware is ready to acknowledge. File plib_i2c.h C bool PLIB_I2C_MasterReceiverReadyToAcknowledge(I2C_MODULE_ID index); Returns • true - If the hardware status is ready to acknowledge • false - If the hardware is not ready to acknowledge Description This function checks for preconditions before acknowledging a slave. Remarks This function can only be used by master receivers. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceivedByteAcknowledge in your application to determine whether this feature is available. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started and a byte of data must have been received from the I2C bus. Example #define MY_I2C_ID I2C_ID_1 uint8_t data; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { if ( PLIB_I2C_MasterReceiverReadyToAcknowledge ( MY_I2C_ID ) ) { PLIB_I2C_ReceivedByteAcknowledge ( MY_I2C_ID, true ); data = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } } Parameters Parameters Description index Identifies the desired I2C module Function bool PLIB_I2C_MasterReceiverReadyToAcknowledge ( I2C_MODULE_ID index ) j) Feature Existence Functions PLIB_I2C_ExistsAcksequenceProgress Function Identifies whether the AcksequenceIsInProgress feature exists on the I2C module. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1101 File plib_i2c.h C bool PLIB_I2C_ExistsAcksequenceProgress(I2C_MODULE_ID index); Returns • true - If the AcksequenceIsInProgress feature is supported on the device • false - If the AcksequenceIsInProgress feature is not supported on the device Description This function identifies whether the AcksequenceIsInProgress feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_AcksequenceIsInProgress Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsAcksequenceProgress( I2C_MODULE_ID index ) PLIB_I2C_ExistsArbitrationLoss Function Identifies whether the ArbitrationLoss feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsArbitrationLoss(I2C_MODULE_ID index); Returns • true - If the ArbitrationLoss feature is supported on the device • false - If the ArbitrationLoss feature is not supported on the device Description This function identifies whether the ArbitrationLoss feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ArbitrationLossHasOccurred • PLIB_I2C_ArbitrationLossClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsArbitrationLoss( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1102 PLIB_I2C_ExistsBaudRate Function Identifies whether the BaudRate feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsBaudRate(I2C_MODULE_ID index); Returns • true - If the BaudRate feature is supported on the device • false - If the BaudRate feature is not supported on the device Description This function identifies whether the BaudRate feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_BaudRateSet • PLIB_I2C_BaudRateGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsBaudRate( I2C_MODULE_ID index ) PLIB_I2C_ExistsBusIsIdle Function Identifies whether the BusIdle feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsBusIsIdle(I2C_MODULE_ID index); Returns • true - If the BusIdle feature is supported on the device • false - If the BusIdle feature is not supported on the device Description This function identifies whether the BusIdle feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_BusIsIdle Remarks None. Preconditions None. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1103 Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsBusIsIdle( I2C_MODULE_ID index ) PLIB_I2C_ExistsClockStretching Function Identifies whether the ClockStretching feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsClockStretching(I2C_MODULE_ID index); Returns • true - If the ClockStretching feature is supported on the device • false - If the ClockStretching feature is not supported on the device Description This function identifies whether the ClockStretching feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveClockStretchingEnable • PLIB_I2C_SlaveClockStretchingDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsClockStretching( I2C_MODULE_ID index ) PLIB_I2C_ExistsDataLineHoldTime Function Identifies whether the DataLineHoldTime feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsDataLineHoldTime(I2C_MODULE_ID index); Returns • true - If the DataLineHoldTime feature is supported on the device • false - If the DataLineHoldTime feature is not supported on the device Description This function identifies whether the DataLineHoldTime feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_DataLineHoldTimeSet Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1104 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsDataLineHoldTime( I2C_MODULE_ID index ) PLIB_I2C_ExistsGeneralCall Function Identifies whether the GeneralCall feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsGeneralCall(I2C_MODULE_ID index); Returns • true - If the GeneralCall feature is supported on the device • false - If the GeneralCall feature is not supported on the device Description This function identifies whether the GeneralCall feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_GeneralCallEnable • PLIB_I2C_GeneralCallDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsGeneralCall( I2C_MODULE_ID index ) PLIB_I2C_ExistsGeneralCallAddressDetect Function Identifies whether the GeneralCallAddressDetect feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsGeneralCallAddressDetect(I2C_MODULE_ID index); Returns • true - If the GeneralCallAddressDetect feature is supported on the device • false - If the GeneralCallAddressDetect feature is not supported on the device Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1105 Description This function identifies whether the GeneralCallAddressDetect feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_SlaveAddressIsGeneralCall Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsGeneralCallAddressDetect( I2C_MODULE_ID index ) PLIB_I2C_ExistsHighFrequency Function Identifies whether the HighFrequency feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsHighFrequency(I2C_MODULE_ID index); Returns • true - If the HighFrequency feature is supported on the device • false - If the HighFrequency feature is not supported on the device Description This function identifies whether the HighFrequency feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_HighFrequencyEnable • PLIB_I2C_HighFrequencyDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsHighFrequency( I2C_MODULE_ID index ) PLIB_I2C_ExistsIPMI Function Identifies whether the IPMI feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsIPMI(I2C_MODULE_ID index); Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1106 Returns • true - If the IPMI feature is supported on the device • false - If the IPMI feature is not supported on the device Description This function identifies whether the IPMI feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_IPMIEnable • PLIB_I2C_IPMIDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsIPMI( I2C_MODULE_ID index ) PLIB_I2C_ExistsMasterReceiverClock1Byte Function Identifies whether the MasterReceiverClock1Byte feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsMasterReceiverClock1Byte(I2C_MODULE_ID index); Returns • true - If the MasterReceiverClock1Byte feature is supported on the device • false - If the MasterReceiverClock1Byte feature is not supported on the device Description This function identifies whether the MasterReceiverClock1Byte feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_MasterReceiverClock1Byte Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsMasterReceiverClock1Byte( I2C_MODULE_ID index ) PLIB_I2C_ExistsMasterStart Function Identifies whether the MasterStart feature exists on the I2C module. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1107 File plib_i2c.h C bool PLIB_I2C_ExistsMasterStart(I2C_MODULE_ID index); Returns • true - If the MasterStart feature is supported on the device • false - If the MasterStart feature is not supported on the device Description This function identifies whether the MasterStart feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_MasterStart Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsMasterStart( I2C_MODULE_ID index ) PLIB_I2C_ExistsMasterStartRepeat Function Identifies whether the MasterStartRepeat feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsMasterStartRepeat(I2C_MODULE_ID index); Returns • true - If the MasterStartRepeat feature is supported on the device • false - If the MasterStartRepeat feature is not supported on the device Description This function identifies whether the MasterStartRepeat feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_MasterStartRepeat Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsMasterStartRepeat( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1108 PLIB_I2C_ExistsMasterStop Function Identifies whether the MasterStop feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsMasterStop(I2C_MODULE_ID index); Returns • true - If the MasterStop feature is supported on the device • false - If the MasterStop feature is not supported on the device Description This function identifies whether the MasterStop feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_MasterStop Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsMasterStop( I2C_MODULE_ID index ) PLIB_I2C_ExistsModuleEnable Function Identifies whether the ModuleEnable feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsModuleEnable(I2C_MODULE_ID index); Returns • true - If the ModuleEnable feature is supported on the device • false - If the ModuleEnable feature is not supported on the device Description This function identifies whether the ModuleEnable feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_Enable • PLIB_I2C_Disable Remarks None. Preconditions None. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1109 Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsModuleEnable( I2C_MODULE_ID index ) PLIB_I2C_ExistsReceivedByteAcknowledge Function Identifies whether the ReceivedByteAcknowledge feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsReceivedByteAcknowledge(I2C_MODULE_ID index); Returns • true - If the ReceivedByteAcknowledge feature is supported on the device • false - If the ReceivedByteAcknowledge feature is not supported on the device Description This function identifies whether the ReceivedByteAcknowledge feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ReceivedByteAcknowledge • PLIB_I2C_ReceiverByteAcknowledgeHasCompleted • PLIB_I2C_MasterReceiverReadyToAcknowledge Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsReceivedByteAcknowledge( I2C_MODULE_ID index ) PLIB_I2C_ExistsReceivedByteAvailable Function Identifies whether the ReceivedByteAvailable feature exists on the I2C module File plib_i2c.h C bool PLIB_I2C_ExistsReceivedByteAvailable(I2C_MODULE_ID index); Returns • true - If the ReceivedByteAvailable feature is supported on the device • false - If the ReceivedByteAvailable feature is not supported on the device Description This function identifies whether the ReceivedByteAvailable feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_ReceivedByteIsAvailable Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1110 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsReceivedByteAvailable( I2C_MODULE_ID index ) PLIB_I2C_ExistsReceivedByteGet Function Identifies whether the ReceivedByteGet feature exists on the I2C module File plib_i2c.h C bool PLIB_I2C_ExistsReceivedByteGet(I2C_MODULE_ID index); Returns • true - If the ReceivedByteGet feature is supported on the device • false - If the ReceivedByteGet feature is not supported on the device Description This function identifies whether the ReceivedByteGet feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_ReceivedByteGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsReceivedByteGet( I2C_MODULE_ID index ) PLIB_I2C_ExistsReceiverOverflow Function Identifies whether the ReceiverOverflow feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsReceiverOverflow(I2C_MODULE_ID index); Returns • true - If the ReceiverOverflow feature is supported on the device • false - If the ReceiverOverflow feature is not supported on the device Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1111 Description This function identifies whether the ReceiverOverflow feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ReceiverOverflowHasOccurred • PLIB_I2C_ReceiverOverflowClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsReceiverOverflow( I2C_MODULE_ID index ) PLIB_I2C_ExistsReservedAddressProtect Function Identifies whether the ReservedAddressProtect feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsReservedAddressProtect(I2C_MODULE_ID index); Returns • true - If the ReservedAddressProtect feature is supported on the device • false - If the ReservedAddressProtect feature is not supported on the device Description This function identifies whether the ReservedAddressProtect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ReservedAddressProtectEnable • PLIB_I2C_ReservedAddressProtectDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsReservedAddressProtect( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveAddress10Bit Function Identifies whether the SlaveAddress10Bit feature exists on the I2C module. File plib_i2c.h Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1112 C bool PLIB_I2C_ExistsSlaveAddress10Bit(I2C_MODULE_ID index); Returns • true - If the SlaveAddress10Bit feature is supported on the device • false - If the SlaveAddress10Bit feature is not supported on the device Description This function identifies whether the SlaveAddress10Bit feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveAddress10BitSet • PLIB_I2C_SlaveAddress10BitGet • PLIB_I2C_SlaveAddressModeIs10Bits Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveAddress10Bit( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveAddress7Bit Function Identifies whether the SlaveAddress7Bit feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveAddress7Bit(I2C_MODULE_ID index); Returns • true - If the SlaveAddress7Bit feature is supported on the device • false - If the SlaveAddress7Bit feature is not supported on the device Description This function identifies whether the SlaveAddress7Bit feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveAddress7BitSet • PLIB_I2C_SlaveAddress7BitGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveAddress7Bit( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1113 PLIB_I2C_ExistsSlaveAddressDetect Function Identifies whether the SlaveAddressDetect feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveAddressDetect(I2C_MODULE_ID index); Returns • true - If the SlaveAddressDetect feature is supported on the device • false - If the SlaveAddressDetect feature is not supported on the device Description This function identifies whether the SlaveAddressDetect feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_SlaveAddress10BitWasDetected Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveAddressDetect( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveAddressHoldEnable Function Identifies whether the SlaveAddressHoldEnable feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveAddressHoldEnable(I2C_MODULE_ID index); Returns • true - If the SlaveAddressHoldEnable feature is supported on the device • false - If the SlaveAddressHoldEnable feature is not supported on the device Description This function identifies whether the SlaveAddressHoldEnable feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveAddressHoldEnable • PLIB_I2C_SlaveAddressHoldDisable Remarks None. Preconditions None. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1114 Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveAddressHoldEnable( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveBufferOverwrite Function Identifies whether the SlaveBufferOverwrite feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveBufferOverwrite(I2C_MODULE_ID index); Returns • true - If the SlaveBufferOverwrite feature is supported on the device • false - If the SlaveBufferOverwrite feature is not supported on the device Description This function identifies whether the SlaveBufferOverwrite feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveBufferOverwriteEnable • PLIB_I2C_SlaveBufferOverwriteDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveBufferOverwrite( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveBusCollisionDetect Function Identifies whether the SlaveBusCollisionDetect feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveBusCollisionDetect(I2C_MODULE_ID index); Returns • true - If the SlaveBusCollisionDetect feature is supported on the device • false - If the SlaveBusCollisionDetect feature is not supported on the device Description This function identifies whether the SlaveBusCollisionDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveBusCollisionDetectEnable • PLIB_I2C_SlaveBusCollisionDetectDisable Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1115 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveBusCollisionDetect( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveClockHold Function Identifies whether the SlaveClockHold feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveClockHold(I2C_MODULE_ID index); Returns • true - If the SlaveClockHold feature is supported on the device • false - If the SlaveClockHold feature is not supported on the device Description This function identifies whether the SlaveClockHold feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveClockHold • PLIB_I2C_SlaveClockRelease Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveClockHold( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveDataDetect Function Identifies whether the SlaveDataDetect feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveDataDetect(I2C_MODULE_ID index); Returns • true - If the SlaveDataDetect feature is supported on the device • false - If the SlaveDataDetect feature is not supported on the device Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1116 Description This function identifies whether the SlaveDataDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveDataIsDetected • PLIB_I2C_SlaveAddressIsDetected Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveDataDetect( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveInterruptOnStart Function Identifies whether the SlaveInterruptOnStart feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveInterruptOnStart(I2C_MODULE_ID index); Returns • true - If the SlaveInterruptOnStart feature is supported on the device • false - If the SlaveInterruptOnStart feature is not supported on the device Description This function identifies whether the SlaveInterruptOnStart feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveInterruptOnStartEnable • PLIB_I2C_SlaveInterruptOnStartDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveInterruptOnStart( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveInterruptOnStop Function Identifies whether the SlaveInterruptOnStop feature exists on the I2C module. File plib_i2c.h Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1117 C bool PLIB_I2C_ExistsSlaveInterruptOnStop(I2C_MODULE_ID index); Returns • true - If the SlaveInterruptOnStop feature is supported on the device • false - If the SlaveInterruptOnStop feature is not supported on the device Description This function identifies whether the SlaveInterruptOnStop feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveInterruptOnStopEnable • PLIB_I2C_SlaveInterruptOnStopDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveInterruptOnStop( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveMask Function Identifies whether the SlaveMask feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveMask(I2C_MODULE_ID index); Returns • true - If the SlaveMask feature is supported on the device • false - If the SlaveMask feature is not supported on the device Description This function identifies whether the SlaveMask feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveMask7BitSet • PLIB_I2C_SlaveMask7BitGet • PLIB_I2C_SlaveMask10BitSet • PLIB_I2C_SlaveMask10BitGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveMask( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1118 PLIB_I2C_ExistsSlaveReadRequest Function Identifies whether the SlaveReadRequest feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveReadRequest(I2C_MODULE_ID index); Returns • true - If the SlaveReadRequest feature is supported on the device • false - If the SlaveReadRequest feature is not supported on the device Description This function identifies whether the SlaveReadRequest feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_SlaveReadIsRequested Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveReadRequest( I2C_MODULE_ID index ) PLIB_I2C_ExistsSMBus Function Identifies whether the SMBus feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSMBus(I2C_MODULE_ID index); Returns • true - If the SMBus feature is supported on the device • false - If the SMBus feature is not supported on the device Description This function identifies whether the SMBus feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SMBEnable • PLIB_I2C_SMBDisable Remarks None. Preconditions None. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1119 Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSMBus( I2C_MODULE_ID index ) PLIB_I2C_ExistsStartDetect Function Identifies whether the StartDetect feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsStartDetect(I2C_MODULE_ID index); Returns • true - If the StartDetect feature is supported on the device • false - If the StartDetect feature is not supported on the device Description This function identifies whether the StartDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_StartWasDetected • PLIB_I2C_StartClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsStartDetect( I2C_MODULE_ID index ) PLIB_I2C_ExistsStopDetect Function Identifies whether the StopDetect feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsStopDetect(I2C_MODULE_ID index); Returns • true - If the StopDetect feature is supported on the device • false - If the StopDetect feature is not supported on the device Description This function identifies whether the StopDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_StopWasDetected • PLIB_I2C_StopClear Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1120 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsStopDetect( I2C_MODULE_ID index ) PLIB_I2C_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsStopInIdle(I2C_MODULE_ID index); Returns • true - If the StopInIdle feature is supported on the device • false - If the StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_StopInIdleEnable • PLIB_I2C_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsStopInIdle( I2C_MODULE_ID index ) PLIB_I2C_ExistsTransmitterByteAcknowledge Function Identifies whether the TransmitterByteAcknowledge feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsTransmitterByteAcknowledge(I2C_MODULE_ID index); Returns • true - If the TransmitterByteAcknowledge feature is supported on the device • false - If the TransmitterByteAcknowledge feature is not supported on the device Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1121 Description This function identifies whether the TransmitterByteAcknowledge feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_TransmitterByteWasAcknowledged Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsTransmitterByteAcknowledge( I2C_MODULE_ID index ) PLIB_I2C_ExistsTransmitterByteComplete Function Identifies whether the TransmitterByteComplete feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsTransmitterByteComplete(I2C_MODULE_ID index); Returns • true - If the TransmitterByteComplete feature is supported on the device • false - If the TransmitterByteComplete feature is not supported on the device Description This function identifies whether the TransmitterByteComplete feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_TransmitterByteHasCompleted Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsTransmitterByteComplete( I2C_MODULE_ID index ) PLIB_I2C_ExistsTransmitterByteSend Function Identifies whether the TransmitterByteSend feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsTransmitterByteSend(I2C_MODULE_ID index); Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1122 Returns • true - If the TransmitterByteSend feature is supported on the device • false - If the TransmitterByteSend feature is not supported on the device Description This function identifies whether the TransmitterByteSend feature is available on the I2C module. When this function returns true, this function is supported on the device: • PLIB_I2C_TransmitterByteSend Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsTransmitterByteSend( I2C_MODULE_ID index ) PLIB_I2C_ExistsTransmitterIsBusy Function Identifies whether the TransmitterBusy feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsTransmitterIsBusy(I2C_MODULE_ID index); Returns • true - If the TransmitterBusy feature is supported on the device • false - If the TransmitterBusy feature is not supported on the device Description This function identifies whether the TransmitterBusy feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_TransmitterIsBusy • PLIB_I2C_TransmitterIsReady Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsTransmitterIsBusy( I2C_MODULE_ID index ) PLIB_I2C_ExistsTransmitterOverflow Function Identifies whether the TransmitterOverflow feature exists on the I2C module. Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1123 File plib_i2c.h C bool PLIB_I2C_ExistsTransmitterOverflow(I2C_MODULE_ID index); Returns • true - If the TransmitterOverflow feature is supported on the device • false - If the TransmitterOverflow feature is not supported on the device Description This function identifies whether the TransmitterOverflow feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_TransmitterOverflowHasOccurred • PLIB_I2C_TransmitterOverflowClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsTransmitterOverflow( I2C_MODULE_ID index ) PLIB_I2C_ExistsSlaveDataHoldEnable Function Identifies whether the SlaveDataHoldEnable feature exists on the I2C module. File plib_i2c.h C bool PLIB_I2C_ExistsSlaveDataHoldEnable(I2C_MODULE_ID index); Returns • true - If the SlaveDataHoldEnable feature is supported on the device • false - If the SlaveDataHoldEnable feature is not supported on the device Description This function identifies whether the SlaveDataHoldEnable feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveDataHoldEnable • PLIB_I2C_SlaveDataHoldDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_I2C_ExistsSlaveDataHoldEnable( I2C_MODULE_ID index ) Peripheral Libraries Help I2C Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1124 k) Data Types and Constants I2C_MODULE_ID Enumeration File plib_i2c_help.h C typedef enum { I2C_ID_1, I2C_ID_2, I2C_ID_3, I2C_ID_4, I2C_ID_5, I2C_NUMBER_OF_MODULES } I2C_MODULE_ID; Members Members Description I2C_ID_1 I2C Module 1 ID I2C_ID_2 I2C Module 2 ID I2C_ID_3 I2C Module 3 ID I2C_ID_4 I2C Module 4 ID I2C_ID_5 I2C Module 5 ID I2C_NUMBER_OF_MODULES Number of available I2C modules. Description This is type I2C_MODULE_ID. Files Files Name Description plib_i2c.h This file contains the interface definition for the I2C Peripheral Library. plib_i2c_help.h Identifies the supported I2C modules. Description This section lists the source and header files used by the library. plib_i2c.h This file contains the interface definition for the I2C Peripheral Library. Functions Name Description PLIB_I2C_AcksequenceIsInProgress Checks whether the acknowledge sequence is in progress or it is completed. PLIB_I2C_ArbitrationLossClear Clears the arbitration loss status flag PLIB_I2C_ArbitrationLossHasOccurred Identifies if bus arbitration has been lost. PLIB_I2C_BaudRateGet Calculates the I2C module's current SCL clock frequency. PLIB_I2C_BaudRateSet Sets the desired baud rate. PLIB_I2C_BusIsIdle Determines whether the I2C bus is idle or busy. PLIB_I2C_DataLineHoldTimeSet Sets the data line hold time. PLIB_I2C_Disable Disables the specified I2C module. PLIB_I2C_Enable Enables the specified I2C module. PLIB_I2C_ExistsAcksequenceProgress Identifies whether the AcksequenceIsInProgress feature exists on the I2C module. Peripheral Libraries Help I2C Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1125 PLIB_I2C_ExistsArbitrationLoss Identifies whether the ArbitrationLoss feature exists on the I2C module. PLIB_I2C_ExistsBaudRate Identifies whether the BaudRate feature exists on the I2C module. PLIB_I2C_ExistsBusIsIdle Identifies whether the BusIdle feature exists on the I2C module. PLIB_I2C_ExistsClockStretching Identifies whether the ClockStretching feature exists on the I2C module. PLIB_I2C_ExistsDataLineHoldTime Identifies whether the DataLineHoldTime feature exists on the I2C module. PLIB_I2C_ExistsGeneralCall Identifies whether the GeneralCall feature exists on the I2C module. PLIB_I2C_ExistsGeneralCallAddressDetect Identifies whether the GeneralCallAddressDetect feature exists on the I2C module. PLIB_I2C_ExistsHighFrequency Identifies whether the HighFrequency feature exists on the I2C module. PLIB_I2C_ExistsIPMI Identifies whether the IPMI feature exists on the I2C module. PLIB_I2C_ExistsMasterReceiverClock1Byte Identifies whether the MasterReceiverClock1Byte feature exists on the I2C module. PLIB_I2C_ExistsMasterStart Identifies whether the MasterStart feature exists on the I2C module. PLIB_I2C_ExistsMasterStartRepeat Identifies whether the MasterStartRepeat feature exists on the I2C module. PLIB_I2C_ExistsMasterStop Identifies whether the MasterStop feature exists on the I2C module. PLIB_I2C_ExistsModuleEnable Identifies whether the ModuleEnable feature exists on the I2C module. PLIB_I2C_ExistsReceivedByteAcknowledge Identifies whether the ReceivedByteAcknowledge feature exists on the I2C module. PLIB_I2C_ExistsReceivedByteAvailable Identifies whether the ReceivedByteAvailable feature exists on the I2C module PLIB_I2C_ExistsReceivedByteGet Identifies whether the ReceivedByteGet feature exists on the I2C module PLIB_I2C_ExistsReceiverOverflow Identifies whether the ReceiverOverflow feature exists on the I2C module. PLIB_I2C_ExistsReservedAddressProtect Identifies whether the ReservedAddressProtect feature exists on the I2C module. PLIB_I2C_ExistsSlaveAddress10Bit Identifies whether the SlaveAddress10Bit feature exists on the I2C module. PLIB_I2C_ExistsSlaveAddress7Bit Identifies whether the SlaveAddress7Bit feature exists on the I2C module. PLIB_I2C_ExistsSlaveAddressDetect Identifies whether the SlaveAddressDetect feature exists on the I2C module. PLIB_I2C_ExistsSlaveAddressHoldEnable Identifies whether the SlaveAddressHoldEnable feature exists on the I2C module. PLIB_I2C_ExistsSlaveBufferOverwrite Identifies whether the SlaveBufferOverwrite feature exists on the I2C module. PLIB_I2C_ExistsSlaveBusCollisionDetect Identifies whether the SlaveBusCollisionDetect feature exists on the I2C module. PLIB_I2C_ExistsSlaveClockHold Identifies whether the SlaveClockHold feature exists on the I2C module. PLIB_I2C_ExistsSlaveDataDetect Identifies whether the SlaveDataDetect feature exists on the I2C module. PLIB_I2C_ExistsSlaveDataHoldEnable Identifies whether the SlaveDataHoldEnable feature exists on the I2C module. PLIB_I2C_ExistsSlaveInterruptOnStart Identifies whether the SlaveInterruptOnStart feature exists on the I2C module. PLIB_I2C_ExistsSlaveInterruptOnStop Identifies whether the SlaveInterruptOnStop feature exists on the I2C module. PLIB_I2C_ExistsSlaveMask Identifies whether the SlaveMask feature exists on the I2C module. PLIB_I2C_ExistsSlaveReadRequest Identifies whether the SlaveReadRequest feature exists on the I2C module. PLIB_I2C_ExistsSMBus Identifies whether the SMBus feature exists on the I2C module. PLIB_I2C_ExistsStartDetect Identifies whether the StartDetect feature exists on the I2C module. PLIB_I2C_ExistsStopDetect Identifies whether the StopDetect feature exists on the I2C module. PLIB_I2C_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the I2C module. PLIB_I2C_ExistsTransmitterByteAcknowledge Identifies whether the TransmitterByteAcknowledge feature exists on the I2C module. PLIB_I2C_ExistsTransmitterByteComplete Identifies whether the TransmitterByteComplete feature exists on the I2C module. PLIB_I2C_ExistsTransmitterByteSend Identifies whether the TransmitterByteSend feature exists on the I2C module. PLIB_I2C_ExistsTransmitterIsBusy Identifies whether the TransmitterBusy feature exists on the I2C module. PLIB_I2C_ExistsTransmitterOverflow Identifies whether the TransmitterOverflow feature exists on the I2C module. PLIB_I2C_GeneralCallDisable Disables the I2C module from recognizing the general call address. PLIB_I2C_GeneralCallEnable Enables the I2C module to recognize the general call address. PLIB_I2C_HighFrequencyDisable Disables the I2C module from using high frequency (400 kHz or 1 MHz) signaling. PLIB_I2C_HighFrequencyEnable Enables the I2C module to use high frequency (400 kHz or 1 MHz) signaling. PLIB_I2C_IPMIDisable Disables the I2C module's support for the IPMI specification Peripheral Libraries Help I2C Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1126 PLIB_I2C_IPMIEnable Enables the I2C module to support the Intelligent Platform Management Interface (IPMI) specification (see Remarks). PLIB_I2C_MasterReceiverClock1Byte Drives the bus clock to receive 1 byte of data from a slave device. PLIB_I2C_MasterReceiverReadyToAcknowledge Checks whether the hardware is ready to acknowledge. PLIB_I2C_MasterStart Sends an I2C Start condition on the I2C bus in Master mode. PLIB_I2C_MasterStartRepeat Sends a repeated Start condition during an ongoing transfer in Master mode. PLIB_I2C_MasterStop Sends an I2C Stop condition to terminate a transfer in Master mode. PLIB_I2C_ReceivedByteAcknowledge Allows a receiver to acknowledge a that a byte of data has been received. PLIB_I2C_ReceivedByteGet Gets a byte of data received from the I2C bus interface. PLIB_I2C_ReceivedByteIsAvailable Detects whether the receiver has data available. PLIB_I2C_ReceiverByteAcknowledgeHasCompleted Determines if the previous acknowledge has completed. PLIB_I2C_ReceiverOverflowClear Clears the receiver overflow status flag. PLIB_I2C_ReceiverOverflowHasOccurred Identifies if a receiver overflow error has occurred. PLIB_I2C_ReservedAddressProtectDisable Disables the I2C module from protecting reserved addresses, allowing it to respond to them. PLIB_I2C_ReservedAddressProtectEnable Enables the I2C module to protect (not respond to) reserved addresses. PLIB_I2C_SlaveAddress10BitGet Identifies the current 10-bit Slave mode address. PLIB_I2C_SlaveAddress10BitSet Selects 10-bit Slave mode addressing and sets the address value. PLIB_I2C_SlaveAddress10BitWasDetected Detects reception of the second byte of a 10-bit slave address. PLIB_I2C_SlaveAddress7BitGet Identifies the current 7-bit Slave mode address. PLIB_I2C_SlaveAddress7BitSet Selects 7-bit Slave mode addressing and sets the slave address value. PLIB_I2C_SlaveAddressHoldDisable Disables Address holding. PLIB_I2C_SlaveAddressHoldEnable Enables address holding. PLIB_I2C_SlaveAddressIsDetected Detects if the most recent byte received is a data or an address byte. PLIB_I2C_SlaveAddressIsGeneralCall Identifies if the current slave address received is the general call address. PLIB_I2C_SlaveAddressModeIs10Bits Identifies if the current slave address mode is 7-bits or 10-bits. PLIB_I2C_SlaveBufferOverwriteDisable Disables buffer overwrite. PLIB_I2C_SlaveBufferOverwriteEnable Enables buffer overwrite. PLIB_I2C_SlaveBusCollisionDetectDisable Disables bus collision detect interrupts. PLIB_I2C_SlaveBusCollisionDetectEnable Enables slave bus collision interrupts. PLIB_I2C_SlaveClockHold Holds the SCL clock line low after receiving a byte. PLIB_I2C_SlaveClockRelease Releases a previously held SCL clock line. PLIB_I2C_SlaveClockStretchingDisable Disables the I2C module from stretching the slave clock. PLIB_I2C_SlaveClockStretchingEnable Enables the I2C module to stretch the slave clock. PLIB_I2C_SlaveDataHoldDisable Disables data holding. PLIB_I2C_SlaveDataHoldEnable Enables data holding. PLIB_I2C_SlaveDataIsDetected Detects if the most recent byte received is a data or an address byte. PLIB_I2C_SlaveInterruptOnStartDisable Disables the feature of generating interrupt on start condition. PLIB_I2C_SlaveInterruptOnStartEnable Enables the feature of generating interrupt on start condition. PLIB_I2C_SlaveInterruptOnStopDisable Disables the feature of generating interrupt on stop condition. PLIB_I2C_SlaveInterruptOnStopEnable Enables the feature of generating interrupt on stop condition. PLIB_I2C_SlaveMask10BitGet Identifies the current 10-bit Slave mode address mask. PLIB_I2C_SlaveMask10BitSet Sets the 10-bit mask for Slave mode addressing. PLIB_I2C_SlaveMask7BitGet Identifies the current 7-bit Slave mode address mask. PLIB_I2C_SlaveMask7BitSet Sets the 7-bit mask for Slave mode addressing . PLIB_I2C_SlaveReadIsRequested Detects if the request from the master was a read or write. PLIB_I2C_SMBDisable Disable the I2C module support for SMBus electrical signaling levels. PLIB_I2C_SMBEnable Enables the I2C module to support System Management Bus (SMBus) electrical signaling levels. PLIB_I2C_StartClear Clears the start status flag PLIB_I2C_StartWasDetected Identifies when a Start condition has been detected. PLIB_I2C_StopClear Clears the stop status flag PLIB_I2C_StopInIdleDisable Disables the Stop-in-Idle feature. PLIB_I2C_StopInIdleEnable Enables the I2C module to stop when the processor enters Idle mode PLIB_I2C_StopWasDetected Identifies when a Stop condition has been detected PLIB_I2C_TransmitterByteHasCompleted Detects whether the module has finished transmitting the most recent byte. Peripheral Libraries Help I2C Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1127 PLIB_I2C_TransmitterByteSend Sends a byte of data on the I2C bus. PLIB_I2C_TransmitterByteWasAcknowledged Determines whether the most recently sent byte was acknowledged. PLIB_I2C_TransmitterIsBusy Identifies if the transmitter of the specified I2C module is currently busy (unable to accept more data). PLIB_I2C_TransmitterIsReady Detects if the transmitter is ready to accept data to transmit. PLIB_I2C_TransmitterOverflowClear Clears the transmitter overflow status flag. PLIB_I2C_TransmitterOverflowHasOccurred Identifies if a transmitter overflow error has occurred. Description I2C Peripheral Library Interface Header This library provides a low-level abstraction of the Inter-Integrated Circuit (I2C) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences between one microcontroller variant and another. File Name plib_i2c.h Company Microchip Technology Inc. plib_i2c_help.h Identifies the supported I2C modules. Enumerations Name Description I2C_MODULE_ID This is type I2C_MODULE_ID. Description I2C Module ID This enumeration identifies the available I2C modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers specified in the data sheet. Peripheral Libraries Help I2C Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1128 Input Capture Peripheral Library This section describes the Input Capture Peripheral Library. Introduction This library provides a low-level abstraction of the Input Capture (IC) Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The Input Capture (IC) module is used to capture a timer value on the occurrence of an event on an input pin. The IC module plays a major role in applications requiring frequency measurement. Figure 1: Input Capture Module Figure 1 shows the functionality of an Input Capture module. An input signal is provided to the input of this module. The input may be prescaled. An edge detection block detects if the input is undergoing a rising or falling transition. Control logic undertakes the capture of the timer value depending upon the operating mode selected. Some devices have Input Capture modules with dedicated timers that can be used to synchronize multiple IC modules together or cascade 16-bit timers to obtain a 32-bit timer. The timer may be triggered by an external, asynchronous input to start counting as well. The IC module has multiple modes of operation which can be used for different applications. Operating modes include the following: • Timer value capture at falling edge of input signal • Timer value capture at rising edge of input signal • Timer value capture at both edges of input signal • Timer value capture on a specified edge of the input signal and every edge thereafter • Timer value capture on every fourth or sixteenth rising edge of the input signal • Interrupt-only mode in which Input Capture module acts as a source of external interrupt. This mode is functional only in device Sleep and Idle modes. The IC module also incorporates a First In First Out (FIFO) buffer, which temporarily holds the captured value until it is read by the user application. The IC module is capable of generating interrupts when a set number of captures have taken place. Using the Library This topic describes the basic architecture of the Input Capture Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_ic.h Peripheral Libraries Help Input Capture Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1129 The interface to the Input Capture Peripheral library is defined in the plib_ic.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Input Capture Peripheral library must include peripheral.h. Library File: The IC Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the Peripheral interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the Input Capture (IC) module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all of the functionality of the available IC module on the device. Refer to the "Input Capture" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine the set of functions that are supported for each IC module on your device. Description The IC Peripheral Library is used to simplify low-level access to the IC module without having the need to directly interact with the module registers. The names of the functions are generic and lead to easier access to the IC module on different device variants. Input Capture module Software Abstraction Block Diagram The IC module can be described from a software standpoint as having functions to configure the module itself and select an intended mode of operation. Separate functions exist to select the timer whose value is captured by the IC module. When an external input event occurs, the IC module captures the timer value and stores it in a First In First Out (FIFO) buffer. The captured value can be read from the FIFO buffer by performing an input buffer read by calling the respective function. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Input Capture module. Library Interface Section Description General Setup Functions Provides setup, configuration, and status interface routines for the overall operation of the Input Capture module. Timer Functions Provides timer interface routines. Input Capture Buffer Functions Provides buffer interface routines. Operation Modes Functions Provides operation mode routines. Power-Saving Modes Functions Provides Power-Saving Modes routines. Feature Existence Functions Determine whether particular features exist on a device. Peripheral Libraries Help Input Capture Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1130 How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. All of the interface functions in this library are classified according to: • General setup functions: These functions deal with general setup of the IC module • Timer functions: These routines are used to select the timer, input for the timer, and configure synchronous or triggered operation for the timer • Operation Modes routine: The PLIB_IC_ModeSelect function is used to select an operation mode of IC module • Input capture buffer routines: These routines deal with reading the capture value stored in the IC buffer and performing status checks on the IC buffer • Power-Saving modes: • In Sleep mode, the IC module can function only as an external interrupt source. A rising edge input wakes the device from sleep. An interrupt will be generated if it is enabled for that module. • In Idle mode, the IC module can be configured to either stop its operation or continue its operation • Exists functions: These functions determine whether or not a particular feature is present on a device Subsequent sections provide examples that depict the use of interface routines to perform general tasks such as IC module setup and reading captured values. Input Capture Module Setup This section shows the steps required to initialize and configure the IC module. The IC module is configured such that a capture event occurs at the first falling edge of the input signal, and then at every subsequent edge of the input signal. Example: /* This example shows how to initialize and configure IC module */ /* Disable IC module */ PLIB_IC_Disable(MY_IC_ID); /* Disable any peripherals multiplexed with Input Capture pin */ /* Configure I/O pin as input pin. Refer PORTS Peripheral Library */ /* Stop in Idle mode is disabled for IC module. IC mode functions even in Idle mode */ PLIB_IC_StopInIdleDisable(MY_IC_ID); /* Every Edge Capture mode of operation is selected for IC module */ PLIB_IC_ModeSelect(MY_IC_ID, IC_INPUT_CAPTURE_EVERY_EDGE_MODE); /* Timer2 is selected as a clock source for the IC module */ PLIB_IC_TimerSelect(MY_IC_ID, IC_TIMER_TMR2); /* 32-bit timer is selected*/ PLIB_IC_BufferSizeSelect(MY_IC_ID, IC_BUFFER_SIZE_32BIT); /* IC module is enabled */ PLIB_IC_Enable(MY_IC_ID); Reading a Capture Value This section shows how to read a capture value from the input capture buffer. Example: /* This example shows how to read a Capture value */ uint32_t bufferVal; /* Reading a value from an empty Capture Buffer leads to indeterminate data*/ /* Read value from a non-empty buffer */ if(!PLIB_IC_BufferIsEmpty(MY_IC_ID)) { /* Read the buffer value */ bufferVal = PLIB_IC_Buffer32BitGet(MY_IC_ID); } /* Buffer Overflow condition */ while(PLIB_IC_BufferOverflowHasOccurred) Peripheral Libraries Help Input Capture Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1131 { /*Read buffer values until buffer is empty and overflow condition ceases*/ bufferVal = PLIB_IC_Buffer32BitGet(MY_IC_ID); } Configuring the Library The library is configured for the supported Input Capture module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Setup Functions Name Description PLIB_IC_Disable Disables the IC module. PLIB_IC_Enable Enables the IC module. PLIB_IC_EventsPerInterruptSelect Selects the number of capture events before an interrupt is issued. PLIB_IC_FirstCaptureEdgeSelect Captures the timer count value at the first selected edge of input signal. b) Timer Functions Name Description PLIB_IC_TimerSelect Selects the clock source for the IC module. PLIB_IC_AlternateClockDisable Selects Timer2 and Timer3, instead of the alternate clock source. PLIB_IC_AlternateClockEnable Selects the alternate clock source. PLIB_IC_AlternateTimerSelect Selects an alternate timer as a clock source for the IC module. PLIB_IC_ExistsAlternateTimerSelect Identifies whether the AlternateTimerSelect feature exists on the IC module. c) Input Capture Buffer Functions Name Description PLIB_IC_Buffer16BitGet Obtains the 16-bit input capture buffer value. PLIB_IC_Buffer32BitGet Obtains the 32-bit input capture buffer value. PLIB_IC_BufferIsEmpty Checks whether the input capture buffer is empty. PLIB_IC_BufferOverflowHasOccurred Checks whether an input capture buffer overflow has occurred. PLIB_IC_BufferSizeSelect Sets the input capture buffer size. d) Operation Modes Functions Name Description PLIB_IC_ModeSelect Selects the input capture mode for IC module. e) Power-Saving Modes Functions Name Description PLIB_IC_StopInIdleDisable Continues module operation when the device enters Idle mode PLIB_IC_StopInIdleEnable Discontinues IC module operation when the device enters Idle mode. f) Feature Existence Functions Name Description PLIB_IC_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the IC module. PLIB_IC_ExistsBufferIsEmptyStatus Identifies whether the BufferIsEmptyStatus feature exists on the IC module PLIB_IC_ExistsBufferOverflowStatus Identifies whether the BufferOverflowStatus feature exists on the IC module. PLIB_IC_ExistsBufferSize Identifies whether the BufferSize feature exists on the IC module. PLIB_IC_ExistsBufferValue Identifies whether the BufferValue feature exists on the IC module. PLIB_IC_ExistsCaptureMode Identifies whether the CaptureMode feature exists on the IC module. PLIB_IC_ExistsEdgeCapture Identifies whether the EdgeCapture feature exists on the IC module. PLIB_IC_ExistsEnable Identifies whether the EnableControl feature exists on the IC module PLIB_IC_ExistsEventsPerInterruptSelect Identifies whether the EventsPerInterruptSelect feature exists on the IC module. PLIB_IC_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the IC module. Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1132 PLIB_IC_ExistsTimerSelect Identifies whether the TimerSelect feature exists on the IC module. g) Data Types and Constants Name Description IC_BUFFER_SIZE Selects the IC Buffer size. IC_EDGE_TYPES Lists the options to select a rising or falling edge for input capture. IC_EVENTS_PER_INTERRUPT Lists the number of input capture events for an interrupt to occur. IC_INPUT_CAPTURE_MODES Lists all of the input capture modes for the IC module. IC_MODULE_ID IC_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on a Microchip microcontroller. Refer to the specific device data sheet to determine the correct number of modules defined for the device. IC_TIMERS Lists the different 16-bit timers for the IC module. IC_ALT_TIMERS Lists the different 16-bit alternate timers for the IC module. Description This section describes the Application Programming Interface (API) functions of the Input Capture Peripheral Library. Refer to each section for a detailed description. a) General Setup Functions PLIB_IC_Disable Function Disables the IC module. File plib_ic.h C void PLIB_IC_Disable(IC_MODULE_ID index); Returns None. Description This function disables the IC module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_IC_ID IC_ID_1 PLIB_IC_Disable(MY_IC_ID); Parameters Parameters Description index Identifies the IC module Function void PLIB_IC_Disable( IC_MODULE_ID index ) Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1133 PLIB_IC_Enable Function Enables the IC module. File plib_ic.h C void PLIB_IC_Enable(IC_MODULE_ID index); Returns None. Description This function enables the IC module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsEnable in your application to determine whether this feature is available. Preconditions The module should be appropriately configured before being enabled. Example #define MY_IC_ID IC_ID_1 //Do all the other configurations before enabling. PLIB_IC_Enable(MY_IC_ID); Parameters Parameters Description index Identifies the desired IC module Function void PLIB_IC_Enable( IC_MODULE_ID index ) PLIB_IC_EventsPerInterruptSelect Function Selects the number of capture events before an interrupt is issued. File plib_ic.h C void PLIB_IC_EventsPerInterruptSelect(IC_MODULE_ID index, IC_EVENTS_PER_INTERRUPT event); Returns None. Description The IC module can be configured to generate interrupts depending upon the occurrence of a certain number of capture events. The number of capture events before an interrupt is generated is set by this function. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsEventsPerInterruptSelect in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1134 Example #define MY_IC_ID IC_ID_1 // IC module is configured to generate interrupt on every capture event PLIB_IC_EventsPerInterruptSelect(MY_IC_ID, IC_INTERRUPT_ON_EVERY_CAPTURE_EVENT ); Parameters Parameters Description index Identifies the desired IC module event Identifies the interrupt control mode Function void PLIB_IC_EventsPerInterruptSelect( IC_MODULE_ID index,IC_EVENTS_PER_INTERRUPT event) PLIB_IC_FirstCaptureEdgeSelect Function Captures the timer count value at the first selected edge of input signal. File plib_ic.h C void PLIB_IC_FirstCaptureEdgeSelect(IC_MODULE_ID index, IC_EDGE_TYPES edgeType); Returns None. Description This function captures the timer count value at the first selected edge of the input signal. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsEdgeCapture in your application to determine whether this feature is available. Preconditions This setting applies only when the Every Edge Capture mode is set. The capture mode is set by the PLIB_IC_ModeSelect function. Example #define MY_IC_ID IC_ID_1 PLIB_IC_FirstCaptureEdgeSelect(MY_IC_ID,IC_EDGE_FALLING); Parameters Parameters Description index Identifies the desired IC module edgeType Identifies the edge type (i.e., whether rising or falling edge) Function void PLIB_IC_FirstCaptureEdgeSelect( IC_MODULE_ID index, IC_EDGE_TYPES edgeType ) b) Timer Functions PLIB_IC_TimerSelect Function Selects the clock source for the IC module. File plib_ic.h Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1135 C void PLIB_IC_TimerSelect(IC_MODULE_ID index, IC_TIMERS tmr); Returns None. Description This function selects the 16-bit timer source for the IC module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsTimerSelect in your application to determine whether this feature is available. Preconditions The 16-bit time base needs to be set. Example #define MY_IC_ID IC_ID_1 // 16-bit Timer-2 is selected PLIB_IC_TimerSelect(MY_IC_ID, IC_TIMER_TMR2); Parameters Parameters Description index Identifies the desired IC module tmr Identifies the 16-bit timer Function void PLIB_IC_TimerSelect( IC_MODULE_ID index, IC_TIMERS tmr ) PLIB_IC_AlternateClockDisable Function Selects Timer2 and Timer3, instead of the alternate clock source. File plib_ic.h C void PLIB_IC_AlternateClockDisable(IC_MODULE_ID index); Returns None. Description Selects Timer2 and Timer3, instead of the alternate clock source. Remarks The feature is not supported on all devices. Please refer to the specific device data sheet to determine availability. A system unlock must be performed before this function can be executed. This function applies to all input capture modules, regardless of the IC_MODULE_ID passed in the call. Preconditions A system unlock PLIB_DEVCON_SystemUnlock must be performed before this function can be executed. Example // Call system service to unlock oscillator #define MY_IC_ID IC_ID_1 PLIB_IC_AlternateClockDisable( MY_IC_ID ); Parameters Parameters Description index Identifies the desired IC module Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1136 Function void PLIB_IC_AlternateClockDisable( IC_MODULE_ID index) PLIB_IC_AlternateClockEnable Function Selects the alternate clock source. File plib_ic.h C void PLIB_IC_AlternateClockEnable(IC_MODULE_ID index); Returns None. Description Selects the alternate clock source instead of Timer2/3. Remarks The feature is not supported on all devices. Please refer to the specific device data sheet to determine availability. A system unlock must be performed before this function can be executed. This function applies to all input capture modules, regardless of the IC_MODULE_ID passed in the call. Preconditions A system unlock PLIB_DEVCON_SystemUnlock must be performed before this function can be executed. Example // Call system service to unlock oscillator #define MY_IC_ID IC_ID_1 PLIB_IC_AlternateClockEnable( MY_IC_ID ); Parameters Parameters Description index Identifies the desired IC module Function void PLIB_IC_AlternateClockEnable( IC_MODULE_ID index) PLIB_IC_AlternateTimerSelect Function Selects an alternate timer as a clock source for the IC module. File plib_ic.h C bool PLIB_IC_AlternateTimerSelect(IC_MODULE_ID index, IC_ALT_TIMERS tmr); Returns Boolean • true - Alternate timer selected successfully. • false - Alternate timer selection failure, select appropriate alternate timer for the IC module index. Description This function selects an alternate timer as a clock source for the IC module. IC_ID_1,IC_ID_2,IC_ID_3 : Can use Timer4 or Timer5 as alternate timers. IC_ID_4,IC_ID_5,IC_ID_6 : Can use Timer2 or Timer3 as alternate timers. IC_ID_7,IC_ID_8,IC_ID_9 : Can use Timer6 or Timer7 as alternate timers. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1137 PLIB_IC_ExistsAlternateTimerSelect in your application to determine whether this feature is available. Preconditions The 16-bit time base needs to be set. PLIB_IC_AlternateClockEnable API should be called for the IC module to enable the alternate clock selection. Example #define MY_IC_ID IC_ID_1 bool result; //Enabling alternate timer selection // Call system service to unlock oscillator PLIB_IC_AlternateClockEnable( MY_IC_ID ); // 16-bit Timer4 is selected as the clock source for IC module 1 result = PLIB_IC_AlternateTimerSelect(MY_IC_ID, IC_ALT_TIMER_TMR4); if(false == result) { //Selected alternate timer does not available for the desired IC module. //Select appropriate alternate timer. } Parameters Parameters Description index Identifies the desired IC module tmr Identifies the alternate timer Function bool PLIB_IC_AlternateTimerSelect( IC_MODULE_ID index, IC_ALT_TIMERS tmr ) PLIB_IC_ExistsAlternateTimerSelect Function Identifies whether the AlternateTimerSelect feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsAlternateTimerSelect(IC_MODULE_ID index); Returns • true - If the AlternateTimerSelect feature is supported on the device • false - If the AlternateTimerSelect feature is not supported on the device Description This function identifies whether the AlternateTimerSelect feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_AlternateTimerSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_IC_ExistsAlternateTimerSelect( IC_MODULE_ID index ) Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1138 c) Input Capture Buffer Functions PLIB_IC_Buffer16BitGet Function Obtains the 16-bit input capture buffer value. File plib_ic.h C uint16_t PLIB_IC_Buffer16BitGet(IC_MODULE_ID index); Returns None. Description This function reads the 16-bit value of the IC buffer to obtain the captured timer value. This function is used when the buffer size is set to 16-bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferValue in your application to determine whether this feature is available. Preconditions The buffer size should be set to 16 bits (i.e., PLIB_IC_BufferSizeSet(MY_IC_ID, IC_BUFFER_SIZE_16BIT). Example #define MY_IC_ID IC_ID_1 uint16_t bufferVal; // Read input capture buffer value and store it in 'bufferVal' bufferVal = PLIB_IC_Buffer16BitGet(MY_IC_ID); Parameters Parameters Description index Identifies the desired IC module Function uint16_t PLIB_IC_Buffer16BitGet( IC_MODULE_ID index ) PLIB_IC_Buffer32BitGet Function Obtains the 32-bit input capture buffer value. File plib_ic.h C uint32_t PLIB_IC_Buffer32BitGet(IC_MODULE_ID index); Returns None. Description This function reads the 32-bit value of the IC buffer to obtain the captured timer value. This function is used when the buffer size is set to 32 bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferValue in your application to determine whether this feature is available. Preconditions The buffer size should be set to 32 bits (i.e., PLIB_IC_BufferSizeSet(MY_IC_ID, IC_BUFFER_SIZE_32BIT). Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1139 Example #define MY_IC_ID IC_ID_1 uint32_t bufferVal; // Read input capture buffer value and store it in 'bufferVal' bufferVal = PLIB_IC_Buffer32BitGet(MY_IC_ID); Parameters Parameters Description index Identifies the desired IC module Function uint32_t PLIB_IC_Buffer32BitGet( IC_MODULE_ID index ) PLIB_IC_BufferIsEmpty Function Checks whether the input capture buffer is empty. File plib_ic.h C bool PLIB_IC_BufferIsEmpty(IC_MODULE_ID index); Returns Boolean • true - The input capture buffer is empty • false - The input capture buffer is not empty Description This function returns 'true' if the input capture buffer is empty and 'false' if the buffer is not empty. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferIsEmptyStatus in your application to determine whether this feature is available. Preconditions None. Example #define MY_IC_ID IC_ID_1 if(!PLIB_IC_BufferIsEmpty(MY_IC_ID)) { // Do some operation }; Parameters Parameters Description index Identifies the desired IC module Function bool PLIB_IC_BufferIsEmpty( IC_MODULE_ID index) PLIB_IC_BufferOverflowHasOccurred Function Checks whether an input capture buffer overflow has occurred. File plib_ic.h C bool PLIB_IC_BufferOverflowHasOccurred(IC_MODULE_ID index); Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1140 Returns Boolean • true - An overflow of the input capture buffer has occurred • false - An overflow of the input capture buffer has not occurred Description This function returns 'true' if an input capture buffer has overflowed and 'false' if the buffer has not overflowed. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferOverflowStatus in your application to determine whether this feature is available. Preconditions This function only applies when not in Edge Detect mode. Example #define MY_IC_ID IC_ID_1 if(!PLIB_IC_BufferOverflowHasOccurred(MY_IC_ID)) { // Do some operation }; Parameters Parameters Description index Identifies the desired IC module Function bool PLIB_IC_BufferOverflowHasOccurred( IC_MODULE_ID index) PLIB_IC_BufferSizeSelect Function Sets the input capture buffer size. File plib_ic.h C void PLIB_IC_BufferSizeSelect(IC_MODULE_ID index, IC_BUFFER_SIZE bufSize); Returns None. Description This function sets the input capture buffer size for IC module. The buffer size can be set to 16 bits or 32 bits. The buffer size should be consistent with the timer selected. A 32-bit timer requires a 32-bit buffer and a 16-bit timer requires a 16-bit buffer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferSize in your application to determine whether this feature is available. Preconditions The buffer size should be consistent with the timer selected. Example #define MY_IC_ID IC_ID_1 // 32-bit timer resource is selected PLIB_IC_BufferSizeSelect(MY_IC_ID, IC_BUFFER_SIZE_32BIT); Parameters Parameters Description index Identifies the desired IC module Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1141 bufSize Sets the buffer size to 16 bits or 32 bits Function void PLIB_IC_BufferSizeSelect( IC_MODULE_ID index, IC_BUFFER_SIZE bufSize) d) Operation Modes Functions PLIB_IC_ModeSelect Function Selects the input capture mode for IC module. File plib_ic.h C void PLIB_IC_ModeSelect(IC_MODULE_ID index, IC_INPUT_CAPTURE_MODES modeSel); Returns None. Description This function selects the input capture mode for the IC module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsCaptureMode in your application to determine whether this feature is available. Preconditions None. Example #define MY_IC_ID IC_ID_1 // Every Edge Mode is selected PLIB_IC_ModeSelect(MY_IC_ID, IC_INPUT_CAPTURE_EVERY_EDGE_MODE); Parameters Parameters Description index Identifies the desired IC module modeSel Identifies the timer type required Function void PLIB_IC_ModeSelect( IC_MODULE_ID index, IC_INPUT_CAPTURE_MODES modeSel ) e) Power-Saving Modes Functions PLIB_IC_StopInIdleDisable Function Continues module operation when the device enters Idle mode File plib_ic.h C void PLIB_IC_StopInIdleDisable(IC_MODULE_ID index); Returns None. Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1142 Description The function continues operation of the IC module when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_IC_ID IC_ID_1 PLIB_IC_StopInIdleDisable(MY_IC_ID); Parameters Parameters Description index Identifies the desired IC module Function void PLIB_IC_StopInIdleDisable( IC_MODULE_ID index ) PLIB_IC_StopInIdleEnable Function Discontinues IC module operation when the device enters Idle mode. File plib_ic.h C void PLIB_IC_StopInIdleEnable(IC_MODULE_ID index); Returns None. Description This function discontinues IC module operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_IC_ID IC_ID_1 PLIB_IC_StopInIdleEnable(MY_IC_ID); Parameters Parameters Description index Identifies the desired IC module Function void PLIB_IC_StopInIdleEnable( IC_MODULE_ID index ) f) Feature Existence Functions Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1143 PLIB_IC_ExistsAlternateClock Function Identifies whether the AlternateClock feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsAlternateClock(IC_MODULE_ID index); Returns • true - The AlternateClock feature is supported on the device • false - The AlternateClock feature is not supported on the device Description This function identifies whether the AlternateClock feature is available on the IC module. When this function returns true, these functions are supported on the device: • PLIB_IC_AlternateClockEnable • PLIB_IC_AlternateClockDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsAlternateClock( IC_MODULE_ID index ) PLIB_IC_ExistsBufferIsEmptyStatus Function Identifies whether the BufferIsEmptyStatus feature exists on the IC module File plib_ic.h C bool PLIB_IC_ExistsBufferIsEmptyStatus(IC_MODULE_ID index); Returns • true - The BufferIsEmptyStatus feature is supported on the device • false - The BufferIsEmptyStatus feature is not supported on the device Description This function identifies whether the BufferIsEmptyStatus feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_BufferIsEmpty Remarks None. Preconditions None. Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1144 Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsBufferIsEmptyStatus( IC_MODULE_ID index ) PLIB_IC_ExistsBufferOverflowStatus Function Identifies whether the BufferOverflowStatus feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsBufferOverflowStatus(IC_MODULE_ID index); Returns • true - The BufferOverflowStatus feature is supported on the device • false - The BufferOverflowStatus feature is not supported on the device Description This function identifies whether the BufferOverflowStatus feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_BufferOverflowHasOccurred Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsBufferOverflowStatus( IC_MODULE_ID index ) PLIB_IC_ExistsBufferSize Function Identifies whether the BufferSize feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsBufferSize(IC_MODULE_ID index); Returns • true - The BufferSize feature is supported on the device • false - The BufferSize feature is not supported on the device Description This function identifies whether the BufferSize feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_BufferSizeSelect Remarks None. Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1145 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsBufferSize( IC_MODULE_ID index ) PLIB_IC_ExistsBufferValue Function Identifies whether the BufferValue feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsBufferValue(IC_MODULE_ID index); Returns • true - The BufferValue feature is supported on the device • false - The BufferValue feature is not supported on the device Description This function identifies whether the BufferValue feature is available on the IC module. When this function returns true, these functions are supported on the device: • PLIB_IC_Buffer32BitGet • PLIB_IC_Buffer16BitGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsBufferValue( IC_MODULE_ID index ) PLIB_IC_ExistsCaptureMode Function Identifies whether the CaptureMode feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsCaptureMode(IC_MODULE_ID index); Returns • true - The CaptureMode feature is supported on the device • false - The CaptureMode feature is not supported on the device Description This function identifies whether the CaptureMode feature is available on the IC module. When this function returns true, this function is supported on the device: Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1146 • PLIB_IC_ModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsCaptureMode( IC_MODULE_ID index ) PLIB_IC_ExistsEdgeCapture Function Identifies whether the EdgeCapture feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsEdgeCapture(IC_MODULE_ID index); Returns • true - The EdgeCapture feature is supported on the device • false - The EdgeCapture feature is not supported on the device Description This function identifies whether the EdgeCapture feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_FirstCaptureEdgeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsEdgeCapture( IC_MODULE_ID index ) PLIB_IC_ExistsEnable Function Identifies whether the EnableControl feature exists on the IC module File plib_ic.h C bool PLIB_IC_ExistsEnable(IC_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1147 Description This function identifies whether the EnableControl feature is available on the IC module. When this function returns true, these functions are supported on the device: • PLIB_IC_Enable • PLIB_IC_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsEnable( IC_MODULE_ID index ) PLIB_IC_ExistsEventsPerInterruptSelect Function Identifies whether the EventsPerInterruptSelect feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsEventsPerInterruptSelect(IC_MODULE_ID index); Returns • true - The EventsPerInterruptSelect feature is supported on the device • false - The EventsPerInterruptSelect feature is not supported on the device Description This function identifies whether the EventsPerInterruptSelect feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_EventsPerInterruptSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsEventsPerInterruptSelect( IC_MODULE_ID index ) PLIB_IC_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsStopInIdle(IC_MODULE_ID index); Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1148 Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the IC module. When this function returns true, these functions are supported on the device: • PLIB_IC_StopInIdleEnable • PLIB_IC_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsStopInIdle( IC_MODULE_ID index ) PLIB_IC_ExistsTimerSelect Function Identifies whether the TimerSelect feature exists on the IC module. File plib_ic.h C bool PLIB_IC_ExistsTimerSelect(IC_MODULE_ID index); Returns • true - The TimerSelect feature is supported on the device • false - The TimerSelect feature is not supported on the device Description This function identifies whether the TimerSelect feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_TimerSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_IC_ExistsTimerSelect( IC_MODULE_ID index ) g) Data Types and Constants Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1149 IC_BUFFER_SIZE Enumeration Selects the IC Buffer size. File plib_ic_help.h C typedef enum { IC_BUFFER_SIZE_32BIT, IC_BUFFER_SIZE_16BIT } IC_BUFFER_SIZE; Members Members Description IC_BUFFER_SIZE_32BIT 32-bit timer source select IC_BUFFER_SIZE_16BIT 16-bit timer source select Description IC Buffer Size The IC buffer can be set to 16 bits or 32 bits. The buffer size is set by the PLIB_IC_BufferSizeSelect function. IC_EDGE_TYPES Enumeration Lists the options to select a rising or falling edge for input capture. File plib_ic_help.h C typedef enum { IC_EDGE_FALLING, IC_EDGE_RISING } IC_EDGE_TYPES; Members Members Description IC_EDGE_FALLING Select Falling Edge IC_EDGE_RISING Select Rising Edge Description IC Edge Types Select This enumeration lists the options to select a rising edge input capture or a falling edge input capture. The selection is made by the PLIB_IC_FirstCaptureEdgeSelect function. IC_EVENTS_PER_INTERRUPT Enumeration Lists the number of input capture events for an interrupt to occur. File plib_ic_help.h C typedef enum { IC_INTERRUPT_ON_EVERY_4TH_CAPTURE_EVENT, IC_INTERRUPT_ON_EVERY_3RD_CAPTURE_EVENT, IC_INTERRUPT_ON_EVERY_2ND_CAPTURE_EVENT, IC_INTERRUPT_ON_EVERY_CAPTURE_EVENT } IC_EVENTS_PER_INTERRUPT; Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1150 Members Members Description IC_INTERRUPT_ON_EVERY_4TH_CAPTURE_EVENT Interrupt on every 4th capture event IC_INTERRUPT_ON_EVERY_3RD_CAPTURE_EVENT Interrupt on every 3rd capture event IC_INTERRUPT_ON_EVERY_2ND_CAPTURE_EVENT Interrupt on every 2nd capture event IC_INTERRUPT_ON_EVERY_CAPTURE_EVENT Interrupt on every capture event Description IC Capture Events Per Interrupt Select This enumeration lists the number of events that should occur before an interrupt is generated. An interrupt can occur on every capture event, and every second, third, or fourth capture event. IC_INPUT_CAPTURE_MODES Enumeration Lists all of the input capture modes for the IC module. File plib_ic_help.h C typedef enum { IC_INPUT_CAPTURE_INTERRUPT_MODE, IC_INPUT_CAPTURE_EVERY_EDGE_MODE, IC_INPUT_CAPTURE_EVERY_16TH_EDGE_MODE, IC_INPUT_CAPTURE_EVERY_4TH_EDGE_MODE, IC_INPUT_CAPTURE_RISING_EDGE_MODE, IC_INPUT_CAPTURE_FALLING_EDGE_MODE, IC_INPUT_CAPTURE_EDGE_DETECT_MODE, IC_INPUT_CAPTURE_DISABLE_MODE } IC_INPUT_CAPTURE_MODES; Members Members Description IC_INPUT_CAPTURE_INTERRUPT_MODE Interrupt only mode: Rising edge on input triggers an interrupt. This mode is used only when device is in Sleep/Idle mode IC_INPUT_CAPTURE_EVERY_EDGE_MODE Every Edge Capture mode: The first edge of the input signal is specified via PLIB_IC_RisingEdgeCaptureSet() or PLIB_IC_FallingEdgeCaptureSet() routines. Subsequently, timer count value is captured on every rising and falling of the input signal IC_INPUT_CAPTURE_EVERY_16TH_EDGE_MODE Prescaled Capture mode: Timer count value is captured every 16th rising edge of input signal IC_INPUT_CAPTURE_EVERY_4TH_EDGE_MODE Prescaled Capture mode: Timer count value is captured every 4th rising edge of input signal IC_INPUT_CAPTURE_RISING_EDGE_MODE Rising Edge mode: Timer count value is captured on every rising edge of input signal IC_INPUT_CAPTURE_FALLING_EDGE_MODE Falling Edge mode: Timer count value is captured on every falling edge of input signal IC_INPUT_CAPTURE_EDGE_DETECT_MODE Edge Detect mode: Timer count value is captured on every rising and falling of the input signal Interrupt control bits are ignored and an interrupt event is generated for every capture. Overflow status is not updated. IC_INPUT_CAPTURE_DISABLE_MODE Capture module is disabled.Input signal is ignored and no capture events or interrupts are generated Description IC Input Capture Mode Select This enumeration lists all of the input capture modes for IC module. The capture mode is set via the PLIB_IC_ModeSelect function. IC_MODULE_ID Enumeration File plib_ic_help.h C typedef enum { Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1151 IC_ID_1, IC_ID_2, IC_ID_3, IC_ID_4, IC_ID_5, IC_ID_6, IC_ID_7, IC_ID_8, IC_ID_9, IC_NUMBER_OF_MODULES } IC_MODULE_ID; Members Members Description IC_NUMBER_OF_MODULES The total number of modules available. Description IC_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on a Microchip microcontroller. Refer to the specific device data sheet to determine the correct number of modules defined for the device. IC_TIMERS Enumeration Lists the different 16-bit timers for the IC module. File plib_ic_help.h C typedef enum { IC_TIMER_TMR3, IC_TIMER_TMR2 } IC_TIMERS; Members Members Description IC_TIMER_TMR3 Timer3 select IC_TIMER_TMR2 Timer2 select Description IC 16-bit Timer Select This enumeration lists the different 16-bit timers for the IC time base when the IC module is configured with a 16-bit timer resource. IC_ALT_TIMERS Enumeration Lists the different 16-bit alternate timers for the IC module. File plib_ic_help.h C typedef enum { IC_ALT_TIMER_TMR3, IC_ALT_TIMER_TMR2, IC_ALT_TIMER_TMR5, IC_ALT_TIMER_TMR4, IC_ALT_TIMER_TMR7, IC_ALT_TIMER_TMR6 } IC_ALT_TIMERS; Members Members Description IC_ALT_TIMER_TMR3 Select Timer3 as the alternate clock source for IC module Peripheral Libraries Help Input Capture Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1152 IC_ALT_TIMER_TMR2 Select Timer2 as the alternate clock source for IC module IC_ALT_TIMER_TMR5 Select Timer5 as the alternate clock source for IC module IC_ALT_TIMER_TMR4 Select Timer4 as the alternate clock source for IC module IC_ALT_TIMER_TMR7 Select Timer7 as the alternate clock source for IC module IC_ALT_TIMER_TMR6 Select Timer6 as the alternate clock source for IC module Description IC 16-bit alternate Timer Select This enumeration lists the different 16-bit timers for the IC time base when the IC module is configured with a 16-bit alternate timer resource. Files Files Name Description plib_ic.h This file contains the interface definition for the Input Capture (IC) peripheral library. plib_ic_help.h This is file plib_ic_help.h. Description This section lists the source and header files used by the library. plib_ic.h This file contains the interface definition for the Input Capture (IC) peripheral library. Functions Name Description PLIB_IC_AlternateClockDisable Selects Timer2 and Timer3, instead of the alternate clock source. PLIB_IC_AlternateClockEnable Selects the alternate clock source. PLIB_IC_AlternateTimerSelect Selects an alternate timer as a clock source for the IC module. PLIB_IC_Buffer16BitGet Obtains the 16-bit input capture buffer value. PLIB_IC_Buffer32BitGet Obtains the 32-bit input capture buffer value. PLIB_IC_BufferIsEmpty Checks whether the input capture buffer is empty. PLIB_IC_BufferOverflowHasOccurred Checks whether an input capture buffer overflow has occurred. PLIB_IC_BufferSizeSelect Sets the input capture buffer size. PLIB_IC_Disable Disables the IC module. PLIB_IC_Enable Enables the IC module. PLIB_IC_EventsPerInterruptSelect Selects the number of capture events before an interrupt is issued. PLIB_IC_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the IC module. PLIB_IC_ExistsAlternateTimerSelect Identifies whether the AlternateTimerSelect feature exists on the IC module. PLIB_IC_ExistsBufferIsEmptyStatus Identifies whether the BufferIsEmptyStatus feature exists on the IC module PLIB_IC_ExistsBufferOverflowStatus Identifies whether the BufferOverflowStatus feature exists on the IC module. PLIB_IC_ExistsBufferSize Identifies whether the BufferSize feature exists on the IC module. PLIB_IC_ExistsBufferValue Identifies whether the BufferValue feature exists on the IC module. PLIB_IC_ExistsCaptureMode Identifies whether the CaptureMode feature exists on the IC module. PLIB_IC_ExistsEdgeCapture Identifies whether the EdgeCapture feature exists on the IC module. PLIB_IC_ExistsEnable Identifies whether the EnableControl feature exists on the IC module PLIB_IC_ExistsEventsPerInterruptSelect Identifies whether the EventsPerInterruptSelect feature exists on the IC module. PLIB_IC_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the IC module. PLIB_IC_ExistsTimerSelect Identifies whether the TimerSelect feature exists on the IC module. PLIB_IC_FirstCaptureEdgeSelect Captures the timer count value at the first selected edge of input signal. PLIB_IC_ModeSelect Selects the input capture mode for IC module. PLIB_IC_StopInIdleDisable Continues module operation when the device enters Idle mode PLIB_IC_StopInIdleEnable Discontinues IC module operation when the device enters Idle mode. PLIB_IC_TimerSelect Selects the clock source for the IC module. Peripheral Libraries Help Input Capture Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1153 Description IC Module Peripheral Library Interface Header This library provides a low-level abstraction of the Input Capture (IC) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences between one microcontroller variant and another. File Name plib_ic.h Company Microchip Technology Inc. plib_ic_help.h Enumerations Name Description IC_ALT_TIMERS Lists the different 16-bit alternate timers for the IC module. IC_BUFFER_SIZE Selects the IC Buffer size. IC_EDGE_TYPES Lists the options to select a rising or falling edge for input capture. IC_EVENTS_PER_INTERRUPT Lists the number of input capture events for an interrupt to occur. IC_INPUT_CAPTURE_MODES Lists all of the input capture modes for the IC module. IC_MODULE_ID IC_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on a Microchip microcontroller. Refer to the specific device data sheet to determine the correct number of modules defined for the device. IC_TIMERS Lists the different 16-bit timers for the IC module. Description This is file plib_ic_help.h. Peripheral Libraries Help Input Capture Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1154 Interrupt Peripheral Library This section describes the Interrupt Peripheral Library. Introduction This library provides a low-level abstraction of the Interrupt Controller module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description The Interrupt Controller is a key component of a microcontroller. The Interrupt Controller reduces the numerous peripheral interrupt request signals to a single interrupt request signal to the microcontroller core. The key features present on an Interrupt Controller are: • Interrupt source configuration: Provides the ability to enable, disable, and prioritize a source that may interrupt the core • Interrupt status flags: Identify the source of an interrupt request or exception, usually generated by a peripheral The interrupt will be sent to the core, only if the source is enabled to generate an interrupt and interrupts have been enabled (if supported). Sources will be prioritized so that the highest priority interrupt will be sent to the core if multiple sources cause interrupts at the same time. Many interrupt controllers also include, other optional features: • Global enable configuration: Controls the generation of any interrupt to the core from the Interrupt Controller • Choice of edge transition: Controls the edge transition (high-to-low or low-to-high) on which the interrupts are generated • Priority configuration: Associates a programmable priority with the interrupt source Interrupts can be handled inside the core in the following ways: • Vectored: Each interrupt has an associated interrupt handler routine • Non-vectored: All interrupts have a single (shared) interrupt handler routine. The software determines the interrupt source based on the interrupt status-flags register. • Combination of vectored and non-vectored: Interrupts combined in groups. Each group has a single common interrupt vector or handler, but there are multiple groups (i.e., multiple vectors). Within a specific vector group, software determines which one in the group sources caused the interrupt. A microcontroller can support one, or more than one of these modes. Note: Please refer to the specific device data sheet to determine availability of these features for your device. Using the Library This topic describes the basic architecture of the Interrupt Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_int.h The interface to the Interrupt Peripheral Library is defined in the plib_int.h header file, which is included in the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Interrupt Peripheral Library must include peripheral.h. Library File: The Interrupt Peripheral Library (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the peripheral interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the Interrupt Controller module on Microchip microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model Peripheral Libraries Help Interrupt Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1155 The Interrupt Controller receives requests from multiple Interrupt Sources. The Interrupt Controller Configuration controls the overall operation of the interrupt controller. Not all microcontrollers support all the following features listed: • Interrupt nesting configuration • Edge selection of the external interrupts • Vector mode selection • Priority level configuration • Current CPU interrupt and priority status information Source Enable Configuration enables or disables a particular source. On some microcontrollers other CPU exceptions or traps can also be controlled. Source Status Flags give the status of the interrupt request from a specific interrupt source. Other optional features include the Vector Priority Configuration, which is available on some micro controllers and the Proximity Timer. Priority configuration allows a priority level to be associated with each interrupt vector. The proximity timer creates a temporal window in which a group of interrupts of the same, or lower, priority will be held off. This provides an opportunity to queue these interrupt requests and process them using tail-chaining of multiple IRQs and allows higher priority interrupts to pass through during the hold-off window. Traps and Exceptions Some of the things that can interrupt the normal flow of instruction execution of the CPU core are not actual interrupt sources. These are things such as a division-by-zero error or attempting to address unimplemented memory. These errors are either internal to the CPU core itself or are so catastrophic that they are non-maskable and are trapped separately. This library refers to them in general as "traps" and there are interface elements provided to allow software to handle them. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Interrupt module. Library Interface Section Description General Configuration Functions Provides setup, configuration, and status interface routines for the overall operation of the Interrupt Controller module. Interrupt Source Control Functions Provides setup and status routines for: • Setting up the source enable configuration • Setting up the vector priority configuration • Querying a source's interrupt status flag Other Status and Control Functions Provides setup and status routines for: • Global interrupt enable status • Vector number and priority of the current ISR • Proximity timer • Trap handling Feature Existence Functions Determine whether certain features are available. How the Library Works This section provides information on initialization and interrupt source setup and handling. Description Initialization The steps that are required to initialize the Interrupt Controller module vary for different microcontrollers. Note: Refer to the specific device data sheet for the correct initialization sequence for your device. Peripheral Libraries Help Interrupt Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1156 Interrupt Source Setup An interrupt Source needs to be enabled in order for it to be able to generate a interrupt to the core. Use the function PLIB_INT_SourceEnable to enable the interrupt source. INT_SOURCE is a list of the possible interrupt sources On some microcontrollers, each interrupt vector can be associated with a priority. Use the function PLIB_INT_VectorPrioritySet to set the interrupt vector priority. INT_VECTOR is a list of the possible interrupt vectors and INT_PRIORITY_LEVEL is the list of possible priority levels. On some microcontrollers, each interrupt vector can be associated with a sub-priority. Use the function PLIB_INT_VectorSubPrioritySet to set the interrupt source sub-priority. INT_SUBPRIORITY_LEVEL is a list of possible sub-priority levels. On most microcontrollers, it will be necessary to enable interrupt generation to the core by calling the PLIB_INT_Enable function. Interrupt Handling The status of the interrupt indicates whether or not the interrupt request was generated by the source. The status of the trap source can be obtained using the function PLIB_INT_TrapSourceFlagGet and the status of the interrupt source can be obtained using the function PLIB_INT_SourceFlagGet. The interrupt status flags can be used to indicate the interrupt status even if the interrupt is not enabled for the source. When the interrupt is not enabled for the source, no interrupt is generated to the core even though the interrupt controller still recognizes that the source requested an interrupt. INT_TRAP_SOURCE is a list of possible trap events, and INT_SOURCE is a list of possible interrupt sources. Before the Interrupt Service Routine (ISR) ends, the status of the interrupt needs to be cleared to avoid entering the ISR repeatedly for the same interrupt event. A trap source status can be cleared using the function PLIB_INT_TrapSourceFlagClear, and an interrupt source status can be cleared using the function PLIB_INT_SourceFlagClear. INT_TRAP_SOURCE is a list of possible trap events, and INT_SOURCE is a list of possible interrupt sources. Configuring the Library The library is configured for the supported Interrupt module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Configuration Functions Name Description PLIB_INT_Disable Disables the generation of interrupts to the CPU. PLIB_INT_Enable Enables the generation of interrupts to the CPU. PLIB_INT_ExternalFallingEdgeSelect Selects the falling edge as the edge polarity of the external interrupt. PLIB_INT_ExternalRisingEdgeSelect Selects the rising edge as the edge polarity of the external interrupt. PLIB_INT_IsEnabled Identifies if interrupts are currently enabled or disabled at the top level. PLIB_INT_MultiVectorSelect Configures the Interrupt Controller for Multiple Vector mode. PLIB_INT_PriorityGet Returns the priority level of the latest interrupt presented to the CPU. PLIB_INT_ProximityTimerDisable Disables the interrupt temporal-proximity timer. PLIB_INT_ProximityTimerEnable Enables the interrupt temporal-proximity timer and selects the priority levels that start the timer. PLIB_INT_SingleVectorSelect Configures the Interrupt Controller for Single Vector mode. PLIB_INT_SingleVectorShadowSetDisable Disables the Shadow Register Set in Single Vector mode. PLIB_INT_SingleVectorShadowSetEnable Enables the Shadow Register Set in Single Vector mode. PLIB_INT_SetState Restores the status of CPU interrupts based on the value passed into the function. PLIB_INT_ShadowRegisterAssign Assigns a shadow register set for an interrupt priority level. PLIB_INT_VariableVectorOffsetSet Sets the offset specific to an interrupt source number. PLIB_INT_SoftwareNMITrigger Triggers software NMI. b) Interrupt Source Control Functions Name Description PLIB_INT_SourceDisable Disables the interrupt source PLIB_INT_SourceEnable Enables the interrupt source. PLIB_INT_SourceFlagClear Clears the status of the interrupt flag for the selected source. PLIB_INT_SourceFlagGet Returns the status of the interrupt flag for the selected source. PLIB_INT_SourceFlagSet Sets the status of the interrupt flag for the selected source. PLIB_INT_SourceIsEnabled Gets the enable state of the interrupt source. PLIB_INT_VectorPriorityGet Gets the priority of the interrupt vector. PLIB_INT_VectorPrioritySet Sets the priority of the interrupt vector. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1157 PLIB_INT_VectorSubPriorityGet Gets the sub-priority of the interrupt vector. PLIB_INT_VectorSubPrioritySet Sets the sub-priority of the interrupt vector. c) Other Status and Control Functions Name Description PLIB_INT_CPUCurrentPriorityLevelGet Gets the interrupt priority level at which the CPU is currently operating. PLIB_INT_ProximityTimerGet Returns the value used by the temporal proximity timer as a reload value when the temporal proximity timer is triggered by an interrupt event. PLIB_INT_ProximityTimerSet Sets the temporal proximity timer reload value. This value is used to reload the proximity timer after it has been triggered by an interrupt event. PLIB_INT_VectorGet Returns the interrupt vector that is presented to the CPU. PLIB_INT_GetStateAndDisable Disables the generation of interrupts to the CPU. PLIB_INT_ShadowRegisterGet Gets the shadow register set assigned for an interrupt priority level. PLIB_INT_VariableVectorOffsetGet Gets the offset specific to an interrupt source number. d) Feature Existence Functions Name Description PLIB_INT_ExistsCPUCurrentPriorityLevel Identifies whether the CPUCurrentPriorityLevel feature exists on the Interrupts module. PLIB_INT_ExistsEnableControl Identifies whether the EnableControl feature exists on the Interrupt module. PLIB_INT_ExistsExternalINTEdgeSelect Identifies whether the ExternalINTEdgeSelect feature exists on the Interrupts module. PLIB_INT_ExistsINTCPUPriority Identifies whether the INTCPUPriority feature exists on the Interrupt module. PLIB_INT_ExistsINTCPUVector Identifies whether the INTCPUVector feature exists on the Interrupt module. PLIB_INT_ExistsProximityTimerControl Identifies whether the ProximityTimerControl feature exists on the Interrupts module. PLIB_INT_ExistsProximityTimerEnable Identifies whether the ProximityTimerEnable feature exists on the Interrupts module. PLIB_INT_ExistsSingleVectorShadowSet Identifies whether the SingleVectorShadowSet feature exists on the Interrupt module. PLIB_INT_ExistsSourceControl Identifies whether the SourceControl feature exists on the Interrupt module. PLIB_INT_ExistsSourceFlag Identifies whether the SourceFlag feature exists on the Interrupt module. PLIB_INT_ExistsVectorPriority Identifies whether the VectorPriority feature exists on the Interrupt module. PLIB_INT_ExistsVectorSelect Identifies whether the VectorSelect feature exists on the Interrupt module. PLIB_INT_ExistsShadowRegisterAssign Identifies whether the ShadowRegisterAssign feature exists on the Interrupts module. PLIB_INT_ExistsVariableOffset Identifies whether the VariableOffset feature exists on the Interrupt module. PLIB_INT_ExistsSoftwareNMI Identifies whether the SoftwareNMI feature exists on the Interrupt module. e) Data Types and Constants Name Description INT_EXTERNAL_SOURCES Lists the possible external sources that can cause an interrupt to occur. INT_PRIORITY_LEVEL Lists the possible interrupt priority levels. INT_SOURCE Lists the possible sources that can cause an interrupt to occur. INT_SUBPRIORITY_LEVEL Lists the possible interrupt sub priority levels. INT_VECTOR Lists the possible interrupt vectors. INT_STATE_GLOBAL Data type defining the global interrupt state. INT_SHADOW_REGISTER Lists the possible shadow register sets. INT_VECTOR_SPACING Lists the possible interrupt vector spacing. Description This section describes the Application Programming Interface (API) functions of the Interrupt Peripheral Library. Refer to each section for a detailed description. a) General Configuration Functions PLIB_INT_Disable Function Disables the generation of interrupts to the CPU. File plib_int.h Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1158 C void PLIB_INT_Disable(INT_MODULE_ID index); Returns None. Description This function disables the generation of interrupts to the CPU. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsEnableControl function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_Disable( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Function void PLIB_INT_Disable ( INT_MODULE_ID index ) PLIB_INT_Enable Function Enables the generation of interrupts to the CPU. File plib_int.h C void PLIB_INT_Enable(INT_MODULE_ID index); Returns None. Description This function enables the generation of interrupts to the CPU. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsEnableControl function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_Enable( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1159 Function void PLIB_INT_Enable ( INT_MODULE_ID index ) PLIB_INT_ExternalFallingEdgeSelect Function Selects the falling edge as the edge polarity of the external interrupt. File plib_int.h C void PLIB_INT_ExternalFallingEdgeSelect(INT_MODULE_ID index, INT_EXTERNAL_SOURCES source); Returns None. Description This function selects the falling edge as the edge polarity of the external interrupt. Remarks This function implements an operation of the ExternalINTEdgeSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsExternalINTEdgeSelect function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_ExternalFallingEdgeSelect( INT_ID_0, (INT_EXTERNAL_INT_SOURCE0 | INT_EXTERNAL_INT_SOURCE1) ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). source One or more of the values from INT_EXTERNAL_SOURCES. Values can be combined using a bitwise "OR" operation. Function void PLIB_INT_ExternalFallingEdgeSelect ( INT_MODULE_ID index, INT_EXTERNAL_SOURCES source ) PLIB_INT_ExternalRisingEdgeSelect Function Selects the rising edge as the edge polarity of the external interrupt. File plib_int.h C void PLIB_INT_ExternalRisingEdgeSelect(INT_MODULE_ID index, INT_EXTERNAL_SOURCES source); Returns None. Description This function selects the rising edge as the edge polarity of the external interrupt. Remarks This function implements an operation of the ExternalINTEdgeSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsExternalINTEdgeSelect function in your application to determine whether this feature is available. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1160 Preconditions None. Example PLIB_INT_ExternalRisingEdgeSelect( INT_ID_0, ( INT_EXTERNAL_INT_SOURCE0 | INT_EXTERNAL_INT_SOURCE1 ) ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). source One or more of the values from INT_EXTERNAL_SOURCES. Values can be combined using a bitwise "OR" operation. Function void PLIB_INT_ExternalRisingEdgeSelect ( INT_MODULE_ID index, INT_EXTERNAL_SOURCES source ) PLIB_INT_IsEnabled Function Identifies if interrupts are currently enabled or disabled at the top level. File plib_int.h C bool PLIB_INT_IsEnabled(INT_MODULE_ID index); Returns • true - If the interrupts are currently enabled • false - If the interrupts are currently disabled Description This function identifies if interrupts are enabled or disabled at the top level. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsEnableControl function in your application to determine whether this feature is available. Preconditions None. Example status = PLIB_INT_IsEnabled( INT_ID_0 ); Function bool PLIB_INT_IsEnabled ( INT_MODULE_ID index ) PLIB_INT_MultiVectorSelect Function Configures the Interrupt Controller for Multiple Vector mode. File plib_int.h C void PLIB_INT_MultiVectorSelect(INT_MODULE_ID index); Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1161 Returns None. Description This function configures the Interrupt Controller for Multiple Vector mode. Interrupt requests will serviced at the calculated vector addresses. The CPU vectors to the unique address for each vector number. Remarks While the user can, during run-time, reconfigure the interrupt controller from Single Vector mode to Multiple Vector mode, such action is strongly discouraged, as it may result in undefined behavior. This function implements an operation of the VectorSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsVectorSelect function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_MultiVectorSelect( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Function void PLIB_INT_MultiVectorSelect( INT_MODULE_ID index ) PLIB_INT_PriorityGet Function Returns the priority level of the latest interrupt presented to the CPU. File plib_int.h C INT_PRIORITY_LEVEL PLIB_INT_PriorityGet(INT_MODULE_ID index); Returns One of the possible values from INT_PRIORITY_LEVEL. Description This function returns the priority level of the latest interrupt presented to the CPU. Remarks This value should only be used when the interrupt controller is configured for single vector mode using the function PLIB_INT_SingleVectorSelect. This function implements an operation of the INTCPUPriority feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsINTCPUPriority function in your application to determine whether this feature is available. Preconditions None. Example INT_PRIORITY_LEVEL level = PLIB_INT_RequestedPriorityLevelGet( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1162 Function INT_PRIORITY_LEVEL PLIB_INT_PriorityGet ( INT_MODULE_ID index ) PLIB_INT_ProximityTimerDisable Function Disables the interrupt temporal-proximity timer. File plib_int.h C void PLIB_INT_ProximityTimerDisable(INT_MODULE_ID index); Returns None. Description This function disables the interrupt temporal-proximity timer. Remarks This function implements an operation of the ProximityTimerEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsProximityTimerEnable function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_ProximityTimerDisable(INT_PRIORITY_LEVEL3); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Function void PLIB_INT_ProximityTimerDisable( INT_MODULE_ID index ) PLIB_INT_ProximityTimerEnable Function Enables the interrupt temporal-proximity timer and selects the priority levels that start the timer. File plib_int.h C void PLIB_INT_ProximityTimerEnable(INT_MODULE_ID index, INT_PRIORITY_LEVEL priority); Returns None. Description This function enables the interrupt temporal-proximity timer and selects the priority levels that start the timer. One of the possible values from PLIB_INT_PRIORITY_LEVEL can be selected. Interrupts of that priority and lower start the temporal proximity timer. Remarks This function implements an operation of the ProximityTimerEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsProximityTimerEnable function in your application to determine whether this feature is available. Choosing INT_PRIORITY_0 disables the proximity timer (exactly the same as if PLIB_INT_ProximityTimerDisable had been called. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1163 Preconditions None. Example //Interrupts of group priority 3 or lower start the temporal proximity timer PLIB_INT_ProximityTimerEnable( INT_ID_0, INT_PRIORITY_LEVEL3 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). priority One of possible values from INT_PRIORITY_LEVEL. Function void PLIB_INT_ProximityTimerEnable ( INT_MODULE_ID index, INT_PRIORITY_LEVEL priority ) PLIB_INT_SingleVectorSelect Function Configures the Interrupt Controller for Single Vector mode. File plib_int.h C void PLIB_INT_SingleVectorSelect(INT_MODULE_ID index); Returns None. Description The function configures the Interrupt Controller for Single Vector mode. All interrupt requests will serviced at one vector address. The CPU vectors to the same address for all interrupt sources. Remarks While the user can, during run-time, reconfigure the Interrupt Controller from Single Vector mode to Multiple Vector mode, such action is strongly discouraged, as it may result in undefined behavior. This function implements an operation of the VectorSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsVectorSelect function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_SingleVectorSelect( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Function void PLIB_INT_SingleVectorSelect ( INT_MODULE_ID index ) PLIB_INT_SingleVectorShadowSetDisable Function Disables the Shadow Register Set in Single Vector mode. File plib_int.h Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1164 C void PLIB_INT_SingleVectorShadowSetDisable(INT_MODULE_ID index); Returns None. Description This function disables usage of the "shadow" set of processor registers when operating in Single Vector mode. Remarks This function implements an operation of the SingleVectorShadowSet feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsSingleVectorShadowSet function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_SingleVectorShadowSetEnable( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Function void PLIB_INT_SingleVectorShadowSetDisable ( INT_MODULE_ID index ) PLIB_INT_SingleVectorShadowSetEnable Function Enables the Shadow Register Set in Single Vector mode. File plib_int.h C void PLIB_INT_SingleVectorShadowSetEnable(INT_MODULE_ID index); Returns None. Description This function enables usage of the "shadow" set of processor registers when operating in Single Vector mode. Remarks This function implements an operation of the SingleVectorShadowSet feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsSingleVectorShadowSet function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_SingleVectorShadowSetEnable( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1165 Function void PLIB_INT_SingleVectorShadowSetEnable ( INT_MODULE_ID index ) PLIB_INT_SetState Function Restores the status of CPU interrupts based on the value passed into the function. File plib_int.h C void PLIB_INT_SetState(INT_MODULE_ID index, INT_STATE_GLOBAL interrupt_state); Returns None. Description This function will use the value passed in, to set the state of global interrupts. Remarks This function should be paired with the use of PLIB_INT_GetStateAndDisable. The value returned from PLIB_INT_GetStateAndDisable should be passed into this function. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsEnableControl function in your application to determine whether this feature is available. Preconditions None. Example INT_STATE_GLOBAL interrupt_value; interrupt_value = PLIB_INT_GetStateAndDisable( INT_ID_0 ); PLIB_INT_SetState(INT_ID_0, interrupt_value); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). interrupt_state value returned from previous call to PLIB_INT_GetStateAndDisable. Function void PLIB_INT_SetState ( INT_MODULE_ID index, INT_STATE_GLOBAL interrupt_state ) PLIB_INT_ShadowRegisterAssign Function Assigns a shadow register set for an interrupt priority level. File plib_int.h C void PLIB_INT_ShadowRegisterAssign(INT_MODULE_ID index, INT_PRIORITY_LEVEL priority, INT_SHADOW_REGISTER shadowRegister); Returns None. Description The function assigns a shadow register set for an interrupt priority level. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1166 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsShadowRegisterAssign function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_ShadowRegisterAssign( INT_ID_0, INT_PRIORITY_LEVEL5, INT_SHADOW_REGISTER_5 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all devices that have only one Interrupt module). priority Interrupt priority level for the shadow register set that is to be assigned. shadowRegister Shadow register set number. Function void PLIB_INT_ShadowRegisterAssign ( INT_MODULE_ID index, INT_PRIORITY_LEVEL priority, INT_SHADOW_REGISTER shadowRegister ) PLIB_INT_VariableVectorOffsetSet Function Sets the offset specific to an interrupt source number. File plib_int.h C void PLIB_INT_VariableVectorOffsetSet(INT_MODULE_ID index, INT_VECTOR vector, uint32_t offset); Returns None. Description The function sets the offset specific to an interrupt source number. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsVariableOffset function in your application to determine whether this feature is available. Preconditions None. Example //Set 200 bytes offset PLIB_INT_VariableVectorOffsetSet ( INT_ID_0, INT_VECTOR_USB1, 200 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). vector Interrupt source, one of the possible value from INT_VECTOR enum. offset Offset in number of bytes. Function void PLIB_INT_VariableVectorOffsetSet ( INT_MODULE_ID index, INT_VECTOR source, uint32_t offset ) Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1167 PLIB_INT_SoftwareNMITrigger Function Triggers software NMI. File plib_int.h C void PLIB_INT_SoftwareNMITrigger(INT_MODULE_ID index); Returns None. Description This function triggers the software NMI. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_INT_ExistsSoftwareNMI in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_SoftwareNMITrigger( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Function void PLIB_INT_SoftwareNMITrigger( INT_MODULE_ID index ) b) Interrupt Source Control Functions PLIB_INT_SourceDisable Function Disables the interrupt source File plib_int.h C void PLIB_INT_SourceDisable(INT_MODULE_ID index, INT_SOURCE source); Returns None. Description This function disables the given interrupt source. Remarks This function implements an operation of the SourceControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsSourceControl function in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1168 Example PLIB_INT_SourceDisable(INT_ID_0,INT_SOURCE_TIMER_1); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). source One of the possible values from INT_SOURCE. Function void PLIB_INT_SourceDisable ( INT_MODULE_ID index, INT_SOURCE source ) PLIB_INT_SourceEnable Function Enables the interrupt source. File plib_int.h C void PLIB_INT_SourceEnable(INT_MODULE_ID index, INT_SOURCE source); Returns None. Description This function enables the interrupt source. The interrupt flag is set when the interrupt request is sampled. The pending interrupt request will not cause further processing if the interrupt is not enabled using this function or if interrupts are not enabled (on processors that support the PLIB_INT_Enable feature). Remarks This function implements an operation of the SourceControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsSourceControl function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_SourceEnable(INT_ID_0,INT_SOURCE_TIMER_1); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). source One of the possible values from INT_SOURCE. Function void PLIB_INT_SourceEnable ( INT_MODULE_ID index, INT_SOURCE source ) PLIB_INT_SourceFlagClear Function Clears the status of the interrupt flag for the selected source. File plib_int.h C void PLIB_INT_SourceFlagClear(INT_MODULE_ID index, INT_SOURCE source); Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1169 Returns None. Description This function clears the status of the interrupt flag for the selected source. The flag is set when the interrupt request is identified. The pending interrupt request will not cause further processing if the interrupt is not enabled using the function PLIB_INT_InterruptSourceEnable or if interrupts are not enabled (on processors that support the PLIB_INT_Enable feature). Remarks This function implements an operation of the SourceFlag feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsSourceFlag function in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_INT_SourceFlagGet(INT_ID_0,INT_SOURCE_TIMER_1)) { PLIB_INT_SourceFlagClear(INT_ID_0,INT_SOURCE_TIMER_1); } Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). source One of the possible values from INT_SOURCE. Function void PLIB_INT_SourceFlagClear ( INT_MODULE_ID index, INT_SOURCE source ) PLIB_INT_SourceFlagGet Function Returns the status of the interrupt flag for the selected source. File plib_int.h C bool PLIB_INT_SourceFlagGet(INT_MODULE_ID index, INT_SOURCE source); Returns • true - If the interrupt request is recognized for the source • false - If the interrupt request is not recognized for the source Description This function returns the status of the interrupt flag for the selected source. The flag is set when the interrupt request is recognized. The pending interrupt request will not cause further processing if the interrupt is not enabled using the function PLIB_INT_InterruptSourceEnable or if interrupts are not enabled (on processors that support the PLIB_INT_Enable feature). Remarks This function implements an operation of the SourceFlag feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsSourceFlag function in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_INT_SourceFlagGet(INT_ID_0, INT_SOURCE_TIMER_1)) { PLIB_INT_SourceFlagClear(INT_ID_0, INT_SOURCE_TIMER_1); Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1170 } Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). source One of the possible values from INT_SOURCE. Function bool PLIB_INT_SourceFlagGet ( INT_MODULE_ID index, INT_SOURCE source ) PLIB_INT_SourceFlagSet Function Sets the status of the interrupt flag for the selected source. File plib_int.h C void PLIB_INT_SourceFlagSet(INT_MODULE_ID index, INT_SOURCE source); Returns None. Description This function sets the status of the interrupt flag for the selected source. This function will not be used during normal operation of the system. It is used to generate test interrupts for debug and testing purposes. Remarks This function implements an operation of the SourceFlag feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsSourceFlag function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_SourceFlagSet(INT_ID_0,INT_SOURCE_TIMER_1); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). source One of the possible values from INT_SOURCE. Function void PLIB_INT_SourceFlagSet ( INT_MODULE_ID index, INT_SOURCE source ) PLIB_INT_SourceIsEnabled Function Gets the enable state of the interrupt source. File plib_int.h C bool PLIB_INT_SourceIsEnabled(INT_MODULE_ID index, INT_SOURCE source); Returns • true - If the interrupt source is enabled • false - If the interrupt source is disabled Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1171 Description This function gets the enable state of the interrupt source. Remarks This function implements an operation of the SourceControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsSourceControl function in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_INT_SourceIsEnabled(INT_ID_0,INT_SOURCE_TIMER_1) != true) { PLIB_INT_SourceEnable(INT_ID_0,INT_SOURCE_TIMER_1); } Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). source One of the possible values from INT_SOURCE. Function bool PLIB_INT_SourceIsEnabled ( INT_MODULE_ID index, INT_SOURCE source ) PLIB_INT_VectorPriorityGet Function Gets the priority of the interrupt vector. File plib_int.h C INT_PRIORITY_LEVEL PLIB_INT_VectorPriorityGet(INT_MODULE_ID index, INT_VECTOR vector); Returns • priority - One of the possible values from INT_PRIORITY_LEVEL Description Gets the priority of the interrupt vector. The priority is one of the possible values from INT_PRIORITY_LEVEL Remarks This function implements an operation of the VectorPriority feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsVectorPriority function in your application to determine whether this feature is available. Preconditions None. Example INT_PRIORITY_LEVEL level; level = PLIB_INT_VectorPriorityGet(INT_ID_0, INT_VECTOR_T1); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). vector One of the possible values from INT_VECTOR Function PLIB_INT_PRIORITY_LEVEL INT_VectorPriorityGet ( INT_MODULE_ID index, INT_VECTOR vector ) Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1172 PLIB_INT_VectorPrioritySet Function Sets the priority of the interrupt vector. File plib_int.h C void PLIB_INT_VectorPrioritySet(INT_MODULE_ID index, INT_VECTOR vector, INT_PRIORITY_LEVEL priority); Returns None. Description Sets the priority of the interrupt vector. The priority is one of the possible values from INT_PRIORITY_LEVEL. Remarks This function implements an operation of the VectorPriority feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsVectorPriority function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_VectorPrioritySet(INT_ID_0, INT_VECTOR_T1, INT_PRIORITY_LEVEL4); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). vector One of the possible values from INT_VECTOR priority One of the possible values from INT_PRIORITY_LEVEL Function void PLIB_INT_VectorPrioritySet( INT_MODULE_ID index, INT_VECTOR vector, INT_PRIORITY_LEVEL priority ) PLIB_INT_VectorSubPriorityGet Function Gets the sub-priority of the interrupt vector. File plib_int.h C INT_SUBPRIORITY_LEVEL PLIB_INT_VectorSubPriorityGet(INT_MODULE_ID index, INT_VECTOR vector); Returns • priority - One of the possible values from INT_SUBPRIORITY_LEVEL Description This function gets the sub-priority of the interrupt vector. The priority is one of the possible values from INT_SUBPRIORITY_LEVEL. Remarks This function implements an operation of the VectorPriority feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsVectorPriority function in your application to determine whether this feature is available. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1173 Preconditions None. Example INT_SUBPRIORITY_LEVEL level; level = PLIB_INT_VectorSubPriorityGet(INT_ID_0, INT_VECTOR_T1); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). vector One of the possible values from INT_VECTOR Function INT_SUBPRIORITY_LEVEL PLIB_INT_VectorSubPriorityGet (INT_MODULE_ID index, INT_VECTOR vector ) PLIB_INT_VectorSubPrioritySet Function Sets the sub-priority of the interrupt vector. File plib_int.h C void PLIB_INT_VectorSubPrioritySet(INT_MODULE_ID index, INT_VECTOR vector, INT_SUBPRIORITY_LEVEL subPriority); Returns None. Description This function sets the sub priority of the interrupt vector. The sub-priority is one of the possible values from INT_SUBPRIORITY_LEVEL. Remarks This function implements an operation of the VectorPriority feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsVectorPriority function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_VectorSubPrioritySet(INT_ID_0, INT_VECTOR_T1, INT_SUBPRIORITY_LEVEL1); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). vector One of the possible values from INT_VECTOR subPriority One of the possible values from INT_SUBPRIORITY_LEVEL Function void PLIB_INT_VectorSubPrioritySet ( INT_MODULE_ID index, INT_VECTOR vector, INT_SUBPRIORITY_LEVEL subPriority ) c) Other Status and Control Functions Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1174 PLIB_INT_CPUCurrentPriorityLevelGet Function Gets the interrupt priority level at which the CPU is currently operating. File plib_int.h C INT_PRIORITY_LEVEL PLIB_INT_CPUCurrentPriorityLevelGet(INT_MODULE_ID index); Returns • priority - The current interrupt priority of the CPU. Range (0 - 15) Description This function gets the interrupt priority level at which the CPU is currently operating. Remarks User interrupts are disabled when the CPU priority is more than 7. This function implements an operation of the CPUCurrentPriorityLevel feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsCPUCurrentPriorityLevel function in your application to determine whether this feature is available. Preconditions None. Example INT_PRIORITY_LEVEL currentCPUPriority; currentCPUPriority = PLIB_INT_CPUCurrentPriorityLevelGet( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Function INT_PRIORITY_LEVEL PLIB_INT_CPUCurrentPriorityLevelGet ( INT_MODULE_ID index ) PLIB_INT_ProximityTimerGet Function Returns the value used by the temporal proximity timer as a reload value when the temporal proximity timer is triggered by an interrupt event. File plib_int.h C uint32_t PLIB_INT_ProximityTimerGet(INT_MODULE_ID index); Returns Timer reload value. Description This function returns the value used by the temporal proximity timer as a reload value when the temporal proximity timer is triggered by an interrupt event. Remarks This function implements an operation of the ProximityTimerControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsProximityTimerControl function in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1175 Example uint32_t timer; timer = PLIB_INT_ProximityTimerGet( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Function uint32_t PLIB_INT_ProximityTimerGet ( INT_MODULE_ID index ) PLIB_INT_ProximityTimerSet Function Sets the temporal proximity timer reload value. This value is used to reload the proximity timer after it has been triggered by an interrupt event. File plib_int.h C void PLIB_INT_ProximityTimerSet(INT_MODULE_ID index, uint32_t timerreloadvalue); Returns None. Description This function sets the temporal proximity timer reload value. This value is used to reload the proximity timer after it has been triggered by an interrupt event. Remarks This function implements an operation of the ProximityTimerControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsProximityTimerControl function in your application to determine whether this feature is available. Preconditions None. Example PLIB_INT_ProximityTimerSet(INT_ID_0, 0x12345678); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). timerReloadValue Timer reload value. Function void PLIB_INT_ProximityTimerSet ( INT_MODULE_ID index, uint32_t timerReloadValue ) PLIB_INT_VectorGet Function Returns the interrupt vector that is presented to the CPU. File plib_int.h C INT_VECTOR PLIB_INT_VectorGet(INT_MODULE_ID index); Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1176 Returns One of the possible values from INT_VECTOR. Description This function returns the interrupt vector that is presented to the CPU. Remarks This value should only be used when the interrupt controller is configured for single vector mode using the function PLIB_INT_MultiVectorDisable. This function implements an operation of the INTCPUVector feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsINTCPUVector function in your application to determine whether this feature is available. Preconditions None. Example INT_VECTOR level = PLIB_INT_VectorGet( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Function INT_VECTOR PLIB_INT_VectorGet ( INT_MODULE_ID index ) PLIB_INT_GetStateAndDisable Function Disables the generation of interrupts to the CPU. File plib_int.h C INT_STATE_GLOBAL PLIB_INT_GetStateAndDisable(INT_MODULE_ID index); Returns Value of CP0 Status register before interrupts were disabled globally. Description This function disables the generation of interrupts to the CPU. Remarks This function should be paired with the use of PLIB_INT_SetState. The value returned from this function should be passed into PLIB_INT_SetState. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsEnableControl function in your application to determine whether this feature is available. Preconditions None. Example INT_STATE_GLOBAL interrupt_value; interrupt_value = PLIB_INT_GetStateAndDisable( INT_ID_0 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1177 Function INT_STATE_GLOBAL PLIB_INT_GetStateAndDisable ( INT_MODULE_ID index ) PLIB_INT_ShadowRegisterGet Function Gets the shadow register set assigned for an interrupt priority level. File plib_int.h C INT_SHADOW_REGISTER PLIB_INT_ShadowRegisterGet(INT_MODULE_ID index, INT_PRIORITY_LEVEL priority); Returns None. Description The function gets the shadow register set assigned for an interrupt priority level. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsShadowRegisterAssign function in your application to determine whether this feature is available. Preconditions None. Example INT_SHADOW_REGISTER shadowReg; shadowReg = PLIB_INT_ShadowRegisterGet( INT_ID_0, INT_PRIORITY_LEVEL5 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module ). priority Interrupt priority level for the shadow register set that is to be assigned. Function INT_SHADOW_REGISTER PLIB_INT_ShadowRegisterGet ( INT_MODULE_ID index, INT_PRIORITY_LEVEL priority ) PLIB_INT_VariableVectorOffsetGet Function Gets the offset specific to an interrupt source number. File plib_int.h C uint32_t PLIB_INT_VariableVectorOffsetGet(INT_MODULE_ID index, INT_VECTOR vector); Returns Offset value. Description The function gets the offset specific to an interrupt source number. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_INT_ExistsVariableOffset function in your application to determine whether this feature is available. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1178 Preconditions None. Example uint32_t offset; offset = PLIB_INT_VariableVectorOffsetGet ( INT_ID_0, INT_VECTOR_USB1 ); Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all of the devices that have only one Interrupt module). vector Interrupt source, one of the possible value from INT_VECTOR enum. Function uint32_t PLIB_INT_VariableVectorOffsetGet ( INT_MODULE_ID index, INT_VECTOR vector ) d) Feature Existence Functions PLIB_INT_ExistsCPUCurrentPriorityLevel Function Identifies whether the CPUCurrentPriorityLevel feature exists on the Interrupts module. File plib_int.h C bool PLIB_INT_ExistsCPUCurrentPriorityLevel(INT_MODULE_ID index); Returns • true - The CPUCurrentPriorityLevel feature is supported on the device • false - The CPUCurrentPriorityLevel feature is not supported on the device Description This function identifies whether the CPUCurrentPriorityLevel feature is available on the Interrupt module. When this function returns true, this function is supported on the device: • PLIB_INT_CPUCurrentPriorityLevelGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsCPUCurrentPriorityLevel( INT_MODULE_ID index ) PLIB_INT_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the Interrupt module. File plib_int.h Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1179 C bool PLIB_INT_ExistsEnableControl(INT_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_Enable • PLIB_INT_Disable • PLIB_INT_IsEnabled • PLIB_INT_SetState • PLIB_INT_GetStateAndDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsEnableControl( INT_MODULE_ID index ) PLIB_INT_ExistsExternalINTEdgeSelect Function Identifies whether the ExternalINTEdgeSelect feature exists on the Interrupts module. File plib_int.h C bool PLIB_INT_ExistsExternalINTEdgeSelect(INT_MODULE_ID index); Returns • true - The ExternalINTEdgeSelect feature is supported on the device • false - The ExternalINTEdgeSelect feature is not supported on the device Description This function identifies whether the ExternalINTEdgeSelect feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_ExternalRisingEdgeSelect • PLIB_INT_ExternalFallingEdgeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1180 Function PLIB_INT_ExistsExternalINTEdgeSelect( INT_MODULE_ID index ) PLIB_INT_ExistsINTCPUPriority Function Identifies whether the INTCPUPriority feature exists on the Interrupt module. File plib_int.h C bool PLIB_INT_ExistsINTCPUPriority(INT_MODULE_ID index); Returns • true - The INTCPUPriority feature is supported on the device • false - The INTCPUPriority feature is not supported on the device Description This function identifies whether the INTCPUPriority feature is available on the Interrupt module. When this function returns true, this function is supported on the device: • PLIB_INT_PriorityGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsINTCPUPriority( INT_MODULE_ID index ) PLIB_INT_ExistsINTCPUVector Function Identifies whether the INTCPUVector feature exists on the Interrupt module. File plib_int.h C bool PLIB_INT_ExistsINTCPUVector(INT_MODULE_ID index); Returns • true - The INTCPUVector feature is supported on the device • false - The INTCPUVector feature is not supported on the device Description This function identifies whether the INTCPUVector feature is available on the Interrupt module. When this function returns true, this function is supported on the device: • PLIB_INT_VectorGet Remarks None. Preconditions None. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1181 Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsINTCPUVector( INT_MODULE_ID index ) PLIB_INT_ExistsProximityTimerControl Function Identifies whether the ProximityTimerControl feature exists on the Interrupts module. File plib_int.h C bool PLIB_INT_ExistsProximityTimerControl(INT_MODULE_ID index); Returns • true - The ProximityTimerControl feature is supported on the device • false - The ProximityTimerControl feature is not supported on the device Description This function identifies whether the ProximityTimerControl feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_ProximityTimerSet • PLIB_INT_ProximityTimerGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsProximityTimerControl( INT_MODULE_ID index ) PLIB_INT_ExistsProximityTimerEnable Function Identifies whether the ProximityTimerEnable feature exists on the Interrupts module. File plib_int.h C bool PLIB_INT_ExistsProximityTimerEnable(INT_MODULE_ID index); Returns • true - The ProximityTimerEnable feature is supported on the device • false - The ProximityTimerEnable feature is not supported on the device Description This function identifies whether the ProximityTimerEnable feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_ProximityTimerEnable • PLIB_INT_ProximityTimerDisable Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1182 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsProximityTimerEnable( INT_MODULE_ID index ) PLIB_INT_ExistsSingleVectorShadowSet Function Identifies whether the SingleVectorShadowSet feature exists on the Interrupt module. File plib_int.h C bool PLIB_INT_ExistsSingleVectorShadowSet(INT_MODULE_ID index); Returns • true - The SingleVectorShadowSet feature is supported on the device • false - The SingleVectorShadowSet feature is not supported on the device Description This function identifies whether the SingleVectorShadowSet feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_SingleVectorShadowSetDisable • PLIB_INT_SingleVectorShadowSetEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsSingleVectorShadowSet( INT_MODULE_ID index ) PLIB_INT_ExistsSourceControl Function Identifies whether the SourceControl feature exists on the Interrupt module. File plib_int.h C bool PLIB_INT_ExistsSourceControl(INT_MODULE_ID index); Returns • true - The SourceControl feature is supported on the device • false - The SourceControl feature is not supported on the device Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1183 Description This function identifies whether the SourceControl feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_SourceEnable • PLIB_INT_SourceDisable • PLIB_INT_SourceIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsSourceControl( INT_MODULE_ID index ) PLIB_INT_ExistsSourceFlag Function Identifies whether the SourceFlag feature exists on the Interrupt module. File plib_int.h C bool PLIB_INT_ExistsSourceFlag(INT_MODULE_ID index); Returns • true - The SourceFlag feature is supported on the device • false - The SourceFlag feature is not supported on the device Description This function identifies whether the SourceFlag feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_SourceFlagGet • PLIB_INT_SourceFlagSet • PLIB_INT_SourceFlagClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsSourceFlag( INT_MODULE_ID index ) PLIB_INT_ExistsVectorPriority Function Identifies whether the VectorPriority feature exists on the Interrupt module. File plib_int.h Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1184 C bool PLIB_INT_ExistsVectorPriority(INT_MODULE_ID index); Returns • true - The VectorPriority feature is supported on the device • false - The VectorPriority feature is not supported on the device Description This function identifies whether the VectorPriority feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_VectorPrioritySet • PLIB_INT_VectorPriorityGet • PLIB_INT_VectorSubPrioritySet • PLIB_INT_VectorSubPriorityGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsVectorPriority( INT_MODULE_ID index ) PLIB_INT_ExistsVectorSelect Function Identifies whether the VectorSelect feature exists on the Interrupt module. File plib_int.h C bool PLIB_INT_ExistsVectorSelect(INT_MODULE_ID index); Returns • true - The VectorSelect feature is supported on the device • false - The VectorSelect feature is not supported on the device Description This function identifies whether the VectorSelect feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_MultiVectorSelect • PLIB_INT_SingleVectorSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsVectorSelect( INT_MODULE_ID index ) Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1185 PLIB_INT_ExistsShadowRegisterAssign Function Identifies whether the ShadowRegisterAssign feature exists on the Interrupts module. File plib_int.h C bool PLIB_INT_ExistsShadowRegisterAssign(INT_MODULE_ID index); Returns • true - The ShadowRegisterAssign feature is supported on the device • false - The ShadowRegisterAssign feature is not supported on the device Description This function identifies whether the ShadowRegisterAssign feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_ShadowRegisterAssign • PLIB_INT_ShadowRegisterGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsShadowRegisterAssign( INT_MODULE_ID index ) PLIB_INT_ExistsVariableOffset Function Identifies whether the VariableOffset feature exists on the Interrupt module. File plib_int.h C bool PLIB_INT_ExistsVariableOffset(INT_MODULE_ID index); Returns • true - The VariableOffset feature is supported on the device • false - The VariableOffset feature is not supported on the device Description This function identifies whether the VariableOffset feature is available on the Interrupt module. When this function returns true, these functions are supported on the device: • PLIB_INT_VariableOffsetSet • PLIB_INT_VariableOffsetGet Remarks None. Preconditions None. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1186 Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsVariableOffset( INT_MODULE_ID index ) PLIB_INT_ExistsSoftwareNMI Function Identifies whether the SoftwareNMI feature exists on the Interrupt module. File plib_int.h C bool PLIB_INT_ExistsSoftwareNMI(INT_MODULE_ID index); Returns • true - The SoftwareNMI feature is supported on the device • false - The SoftwareNMI feature is not supported on the device Description This function identifies whether the SoftwareNMI feature is available on the Interrupt module. When this function returns true, this function is supported on the device: • PLIB_INT_SoftwareNMITrigger Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_INT_ExistsSoftwareNMI( INT_MODULE_ID index ) e) Data Types and Constants INT_EXTERNAL_SOURCES Enumeration Lists the possible external sources that can cause an interrupt to occur. File plib_int_help.h C typedef enum { INT_EXTERNAL_INT_SOURCE0, INT_EXTERNAL_INT_SOURCE1, INT_EXTERNAL_INT_SOURCE2, INT_EXTERNAL_INT_SOURCE3, INT_EXTERNAL_INT_SOURCE4 } INT_EXTERNAL_SOURCES; Members Members Description INT_EXTERNAL_INT_SOURCE0 External Interrupt Source 0 Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1187 INT_EXTERNAL_INT_SOURCE1 External Interrupt Source 1 INT_EXTERNAL_INT_SOURCE2 External Interrupt Source 2 INT_EXTERNAL_INT_SOURCE3 External Interrupt Source 3 INT_EXTERNAL_INT_SOURCE4 External Interrupt Source 4 Description External Interrupt Sources This enumeration lists the possible external sources that can cause an interrupt to occur. Remarks This enumeration is processor-specific and is defined in the processor-specific header files (see processor.h). INT_PRIORITY_LEVEL Enumeration Lists the possible interrupt priority levels. File plib_int_help.h C typedef enum { INT_PRIORITY_LEVEL0, INT_PRIORITY_LEVEL1, INT_PRIORITY_LEVEL2, INT_PRIORITY_LEVEL3, INT_PRIORITY_LEVEL4, INT_PRIORITY_LEVEL5, INT_PRIORITY_LEVEL6, INT_PRIORITY_LEVEL7 } INT_PRIORITY_LEVEL; Members Members Description INT_PRIORITY_LEVEL0 Disabled INT_PRIORITY_LEVEL1 Priority 1 INT_PRIORITY_LEVEL2 Priority 2 INT_PRIORITY_LEVEL3 Priority 3 INT_PRIORITY_LEVEL4 Priority 4 INT_PRIORITY_LEVEL5 Priority 5 INT_PRIORITY_LEVEL6 Priority 6 INT_PRIORITY_LEVEL7 Priority 7 Description Priority Level This enumeration lists the possible interrupt priority levels that can be selected for each source. Remarks This enumeration is processor-specific and is defined in the processor-specific header files (see processor.h). INT_SOURCE Enumeration Lists the possible sources that can cause an interrupt to occur. File plib_int_help.h C typedef enum { INT_SOURCE_SOFTWARE_0, INT_SOURCE_SOFTWARE_1, INT_SOURCE_EXTERNAL_0, INT_SOURCE_EXTERNAL_1, Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1188 INT_SOURCE_EXTERNAL_2 , INT_SOURCE_EXTERNAL_3 , INT_SOURCE_EXTERNAL_4 , INT_SOURCE_TIMER_CORE , INT_SOURCE_TIMER_1 , INT_SOURCE_TIMER_2 , INT_SOURCE_TIMER_3 , INT_SOURCE_TIMER_4 , INT_SOURCE_TIMER_5 , INT_SOURCE_INPUT_CAPTURE_1 , INT_SOURCE_INPUT_CAPTURE_1_ERROR , INT_SOURCE_INPUT_CAPTURE_2 , INT_SOURCE_INPUT_CAPTURE_2_ERROR , INT_SOURCE_INPUT_CAPTURE_3 , INT_SOURCE_INPUT_CAPTURE_3_ERROR , INT_SOURCE_INPUT_CAPTURE_4 , INT_SOURCE_INPUT_CAPTURE_4_ERROR , INT_SOURCE_INPUT_CAPTURE_5 , INT_SOURCE_INPUT_CAPTURE_5_ERROR , INT_SOURCE_OUTPUT_COMPARE_1 , INT_SOURCE_OUTPUT_COMPARE_2 , INT_SOURCE_OUTPUT_COMPARE_3 , INT_SOURCE_OUTPUT_COMPARE_4 , INT_SOURCE_OUTPUT_COMPARE_5 , INT_SOURCE_SPI_1_ERROR , INT_SOURCE_SPI_1_RECEIVE , INT_SOURCE_SPI_1_TRANSMIT , INT_SOURCE_SPI_2_ERROR , INT_SOURCE_SPI_2_RECEIVE , INT_SOURCE_SPI_2_TRANSMIT , INT_SOURCE_SPI_3_ERROR , INT_SOURCE_SPI_3_RECEIVE , INT_SOURCE_SPI_3_TRANSMIT , INT_SOURCE_SPI_4_ERROR , INT_SOURCE_SPI_4_RECEIVE , INT_SOURCE_SPI_4_TRANSMIT , INT_SOURCE_USART_1_ERROR , INT_SOURCE_USART_1_RECEIVE , INT_SOURCE_USART_1_TRANSMIT , INT_SOURCE_USART_2_ERROR , INT_SOURCE_USART_2_RECEIVE , INT_SOURCE_USART_2_TRANSMIT , INT_SOURCE_USART_3_ERROR , INT_SOURCE_USART_3_RECEIVE , INT_SOURCE_USART_3_TRANSMIT , INT_SOURCE_USART_4_ERROR , INT_SOURCE_USART_4_RECEIVE , INT_SOURCE_USART_4_TRANSMIT , INT_SOURCE_USART_5_ERROR , INT_SOURCE_USART_5_RECEIVE , INT_SOURCE_USART_5_TRANSMIT , INT_SOURCE_USART_6_ERROR , INT_SOURCE_USART_6_RECEIVE , INT_SOURCE_USART_6_TRANSMIT , INT_SOURCE_I2C_1_ERROR , INT_SOURCE_I2C_1_SLAVE , INT_SOURCE_I2C_1_MASTER , INT_SOURCE_I2C_2_ERROR , INT_SOURCE_I2C_2_SLAVE , INT_SOURCE_I2C_2_MASTER , INT_SOURCE_I2C_3_ERROR , INT_SOURCE_I2C_3_SLAVE , INT_SOURCE_I2C_3_MASTER , INT_SOURCE_I2C_4_ERROR , INT_SOURCE_I2C_4_SLAVE , INT_SOURCE_I2C_4_MASTER , INT_SOURCE_I2C_5_ERROR , INT_SOURCE_I2C_5_SLAVE , INT_SOURCE_I2C_5_MASTER , INT_SOURCE_CHANGE_NOTICE , INT_SOURCE_CHANGE_NOTICE_A , INT_SOURCE_CHANGE_NOTICE_B , INT_SOURCE_CHANGE_NOTICE_C , INT_SOURCE_CHANGE_NOTICE_D , INT_SOURCE_CHANGE_NOTICE_E , Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1189 INT_SOURCE_CHANGE_NOTICE_F , INT_SOURCE_CHANGE_NOTICE_G , INT_SOURCE_CHANGE_NOTICE_H , INT_SOURCE_CHANGE_NOTICE_J , INT_SOURCE_CHANGE_NOTICE_K , INT_SOURCE_ADC_1 , INT_SOURCE_ADC_1_DC1 , INT_SOURCE_ADC_1_DC2 , INT_SOURCE_ADC_1_DC3 , INT_SOURCE_ADC_1_DC4 , INT_SOURCE_ADC_1_DC5 , INT_SOURCE_ADC_1_DC6 , INT_SOURCE_ADC_1_DF1 , INT_SOURCE_ADC_1_DF2 , INT_SOURCE_ADC_1_DF3 , INT_SOURCE_ADC_1_DF4 , INT_SOURCE_ADC_1_DF5 , INT_SOURCE_ADC_1_DF6 , INT_SOURCE_ADC_1_DATA0 , INT_SOURCE_ADC_1_DATA1 , INT_SOURCE_ADC_1_DATA2 , INT_SOURCE_ADC_1_DATA3 , INT_SOURCE_ADC_1_DATA4 , INT_SOURCE_ADC_1_DATA5 , INT_SOURCE_ADC_1_DATA6 , INT_SOURCE_ADC_1_DATA7 , INT_SOURCE_ADC_1_DATA8 , INT_SOURCE_ADC_1_DATA9 , INT_SOURCE_ADC_1_DATA10 , INT_SOURCE_ADC_1_DATA11 , INT_SOURCE_ADC_1_DATA12 , INT_SOURCE_ADC_1_DATA13 , INT_SOURCE_ADC_1_DATA14 , INT_SOURCE_ADC_1_DATA15 , INT_SOURCE_ADC_1_DATA16 , INT_SOURCE_ADC_1_DATA17 , INT_SOURCE_ADC_1_DATA18 , INT_SOURCE_ADC_1_DATA19 , INT_SOURCE_ADC_1_DATA20 , INT_SOURCE_ADC_1_DATA21 , INT_SOURCE_ADC_1_DATA22 , INT_SOURCE_ADC_1_DATA23 , INT_SOURCE_ADC_1_DATA24 , INT_SOURCE_ADC_1_DATA25 , INT_SOURCE_ADC_1_DATA26 , INT_SOURCE_ADC_1_DATA27 , INT_SOURCE_ADC_1_DATA28 , INT_SOURCE_ADC_1_DATA29 , INT_SOURCE_ADC_1_DATA30 , INT_SOURCE_ADC_1_DATA31 , INT_SOURCE_ADC_1_DATA32 , INT_SOURCE_ADC_1_DATA33 , INT_SOURCE_ADC_1_DATA34 , INT_SOURCE_ADC_1_DATA35 , INT_SOURCE_ADC_1_DATA36 , INT_SOURCE_ADC_1_DATA37 , INT_SOURCE_ADC_1_DATA38 , INT_SOURCE_ADC_1_DATA39 , INT_SOURCE_ADC_1_DATA40 , INT_SOURCE_ADC_1_DATA41 , INT_SOURCE_ADC_1_DATA42 , INT_SOURCE_ADC_1_DATA43 , INT_SOURCE_ADC_1_DATA44 , INT_SOURCE_ADC_END_OF_SCAN , INT_SOURCE_ADC_ANALOG_CIRCUIT_READY , INT_SOURCE_ADC_UPDATE_READY , INT_SOURCE_ADC_GROUP , INT_SOURCE_ADC_0_EARLY , INT_SOURCE_ADC_1_EARLY , INT_SOURCE_ADC_2_EARLY , INT_SOURCE_ADC_3_EARLY , INT_SOURCE_ADC_4_EARLY , INT_SOURCE_ADC_7_EARLY , INT_SOURCE_ADC_0_WARM , INT_SOURCE_ADC_1_WARM , Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1190 INT_SOURCE_ADC_2_WARM, INT_SOURCE_ADC_3_WARM, INT_SOURCE_ADC_4_WARM, INT_SOURCE_ADC_7_WARM, INT_SOURCE_PARALLEL_PORT, INT_SOURCE_PARALLEL_PORT_ERROR, INT_SOURCE_COMPARATOR_1, INT_SOURCE_COMPARATOR_2, INT_SOURCE_CLOCK_MONITOR, INT_SOURCE_RTCC, INT_SOURCE_DMA_0, INT_SOURCE_DMA_1, INT_SOURCE_DMA_2, INT_SOURCE_DMA_3, INT_SOURCE_DMA_4, INT_SOURCE_DMA_5, INT_SOURCE_DMA_6, INT_SOURCE_DMA_7, INT_SOURCE_FLASH_CONTROL, INT_SOURCE_USB_1, INT_SOURCE_CAN_1, INT_SOURCE_CAN_2, INT_SOURCE_ETH_1, INT_SOURCE_ADC_FAULT, INT_SOURCE_CRYPTO, INT_SOURCE_SPI_5_RECEIVE, INT_SOURCE_SPI_5_TRANSMIT, INT_SOURCE_SPI_6_ERROR, INT_SOURCE_SPI_6_RECEIVE, INT_SOURCE_SPI_6_TRANSMIT } INT_SOURCE; Members Members Description INT_SOURCE_SOFTWARE_0 Software interrupt 0 INT_SOURCE_SOFTWARE_1 Software interrupt 1 INT_SOURCE_EXTERNAL_0 External interrupt 0 INT_SOURCE_EXTERNAL_1 External interrupt 1 INT_SOURCE_EXTERNAL_2 External interrupt 2 INT_SOURCE_EXTERNAL_3 External interrupt 3 INT_SOURCE_EXTERNAL_4 External interrupt 4 INT_SOURCE_TIMER_CORE Core timer interrupt INT_SOURCE_TIMER_1 Timer 1 interrupt INT_SOURCE_TIMER_2 Timer 2 interrupt INT_SOURCE_TIMER_3 Timer 3 interrupt INT_SOURCE_TIMER_4 Timer 4 interrupt INT_SOURCE_TIMER_5 Timer 5 interrupt INT_SOURCE_INPUT_CAPTURE_1 Input Capture 1 interrupt INT_SOURCE_INPUT_CAPTURE_1_ERROR Input Capture 1 Error interrupt INT_SOURCE_INPUT_CAPTURE_2 Input Capture 2 interrupt INT_SOURCE_INPUT_CAPTURE_2_ERROR Input Capture 2 Error interrupt INT_SOURCE_INPUT_CAPTURE_3 Input Capture 3 interrupt INT_SOURCE_INPUT_CAPTURE_3_ERROR Input Capture 3 Error interrupt INT_SOURCE_INPUT_CAPTURE_4 Input Capture 4 interrupt INT_SOURCE_INPUT_CAPTURE_4_ERROR Input Capture 4 Error interrupt INT_SOURCE_INPUT_CAPTURE_5 Input Capture 5 interrupt INT_SOURCE_INPUT_CAPTURE_5_ERROR Input Capture 5 Error interrupt INT_SOURCE_OUTPUT_COMPARE_1 Output Compare 1 interrupt INT_SOURCE_OUTPUT_COMPARE_2 Output Compare 2 interrupt INT_SOURCE_OUTPUT_COMPARE_3 Output Compare 3 interrupt INT_SOURCE_OUTPUT_COMPARE_4 Output Compare 4 interrupt INT_SOURCE_OUTPUT_COMPARE_5 Output Compare 5 interrupt INT_SOURCE_SPI_1_ERROR SPI1 Error interrupt Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1191 INT_SOURCE_SPI_1_RECEIVE SPI1 Receive Done interrupt INT_SOURCE_SPI_1_TRANSMIT SPI1 Transmit Done interrupt INT_SOURCE_SPI_2_ERROR SPI2 Error interrupt INT_SOURCE_SPI_2_RECEIVE SPI2 Receive Done interrupt INT_SOURCE_SPI_2_TRANSMIT SPI2 Transmit Done interrupt INT_SOURCE_SPI_3_ERROR SPI3 Error interrupt INT_SOURCE_SPI_3_RECEIVE SPI3 Receive Done interrupt INT_SOURCE_SPI_3_TRANSMIT SPI3 Transmit Done interrupt INT_SOURCE_SPI_4_ERROR SPI4 Error interrupt INT_SOURCE_SPI_4_RECEIVE SPI4 Receive Done interrupt INT_SOURCE_SPI_4_TRANSMIT SPI4 Transmit Done interrupt INT_SOURCE_USART_1_ERROR UART1 Error interrupt INT_SOURCE_USART_1_RECEIVE UART1 Receive interrupt INT_SOURCE_USART_1_TRANSMIT UART1 Transmit interrupt INT_SOURCE_USART_2_ERROR UART2 Error interrupt INT_SOURCE_USART_2_RECEIVE UART2 Receive interrupt INT_SOURCE_USART_2_TRANSMIT UART2 Transmit interrupt INT_SOURCE_USART_3_ERROR UART3 Error interrupt INT_SOURCE_USART_3_RECEIVE UART3 Receive interrupt INT_SOURCE_USART_3_TRANSMIT UART3 Transmit interrupt INT_SOURCE_USART_4_ERROR UART4 Error interrupt INT_SOURCE_USART_4_RECEIVE UART4 Receive interrupt INT_SOURCE_USART_4_TRANSMIT UART4 Transmit interrupt INT_SOURCE_USART_5_ERROR UART5 Error interrupt INT_SOURCE_USART_5_RECEIVE UART5 Receive interrupt INT_SOURCE_USART_5_TRANSMIT UART5 Transmit interrupt INT_SOURCE_USART_6_ERROR UART6 Error interrupt INT_SOURCE_USART_6_RECEIVE UART6 Receive interrupt INT_SOURCE_USART_6_TRANSMIT UART6 Transmit interrupt INT_SOURCE_I2C_1_ERROR I2C1 Bus Error Event interrupt INT_SOURCE_I2C_1_SLAVE I2C1 Slave Event interrupt INT_SOURCE_I2C_1_MASTER I2C1 Master Event interrupt INT_SOURCE_I2C_2_ERROR I2C2 Bus Error Event interrupt INT_SOURCE_I2C_2_SLAVE I2C2 Slave Event interrupt INT_SOURCE_I2C_2_MASTER I2C2 Master Event interrupt INT_SOURCE_I2C_3_ERROR I2C3 Bus Error Event interrupt INT_SOURCE_I2C_3_SLAVE I2C3 Slave Event interrupt INT_SOURCE_I2C_3_MASTER I2C3 Master Event interrupt INT_SOURCE_I2C_4_ERROR I2C4 Bus Error Event interrupt INT_SOURCE_I2C_4_SLAVE I2C4 Slave Event interrupt INT_SOURCE_I2C_4_MASTER I2C4 Master Event interrupt INT_SOURCE_I2C_5_ERROR I2C5 Bus Error Event interrupt INT_SOURCE_I2C_5_SLAVE I2C5 Slave Event interrupt INT_SOURCE_I2C_5_MASTER I2C5 Master Event interrupt INT_SOURCE_CHANGE_NOTICE Input Change Notice interrupt INT_SOURCE_CHANGE_NOTICE_A Input Change Notice Channel A interrupt INT_SOURCE_CHANGE_NOTICE_B Input Change Notice Channel B interrupt INT_SOURCE_CHANGE_NOTICE_C Input Change Notice Channel C interrupt INT_SOURCE_CHANGE_NOTICE_D Input Change Notice Channel D interrupt INT_SOURCE_CHANGE_NOTICE_E Input Change Notice Channel E interrupt INT_SOURCE_CHANGE_NOTICE_F Input Change Notice Channel F interrupt INT_SOURCE_CHANGE_NOTICE_G Input Change Notice Channel G interrupt INT_SOURCE_CHANGE_NOTICE_H Input Change Notice Channel H interrupt INT_SOURCE_CHANGE_NOTICE_J Input Change Notice Channel J interrupt INT_SOURCE_CHANGE_NOTICE_K Input Change Notice Channel K interrupt Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1192 INT_SOURCE_ADC_1 Analog-to-Digital Converter 1 interrupt INT_SOURCE_ADC_1_DC1 ADC Digital Comparator 1 INT_SOURCE_ADC_1_DC2 ADC Digital Comparator 2 INT_SOURCE_ADC_1_DC3 ADC Digital Comparator 3 INT_SOURCE_ADC_1_DC4 ADC Digital Comparator 4 INT_SOURCE_ADC_1_DC5 ADC Digital Comparator 5 INT_SOURCE_ADC_1_DC6 ADC Digital Comparator 6 INT_SOURCE_ADC_1_DF1 ADC Digital Filter 1 INT_SOURCE_ADC_1_DF2 ADC Digital Filter 2 INT_SOURCE_ADC_1_DF3 ADC Digital Filter 3 INT_SOURCE_ADC_1_DF4 ADC Digital Filter 4 INT_SOURCE_ADC_1_DF5 ADC Digital Filter 5 INT_SOURCE_ADC_1_DF6 ADC Digital Filter 6 INT_SOURCE_ADC_1_DATA0 ADC Data 0 INT_SOURCE_ADC_1_DATA1 ADC Data 1 INT_SOURCE_ADC_1_DATA2 ADC Data 2 INT_SOURCE_ADC_1_DATA3 ADC Data 3 INT_SOURCE_ADC_1_DATA4 ADC Data 4 INT_SOURCE_ADC_1_DATA5 ADC Data 5 INT_SOURCE_ADC_1_DATA6 ADC Data 6 INT_SOURCE_ADC_1_DATA7 ADC Data 7 INT_SOURCE_ADC_1_DATA8 ADC Data 8 INT_SOURCE_ADC_1_DATA9 ADC Data 9 INT_SOURCE_ADC_1_DATA10 ADC Data 10 INT_SOURCE_ADC_1_DATA11 ADC Data 11 INT_SOURCE_ADC_1_DATA12 ADC Data 12 INT_SOURCE_ADC_1_DATA13 ADC Data 13 INT_SOURCE_ADC_1_DATA14 ADC Data 14 INT_SOURCE_ADC_1_DATA15 ADC Data 15 INT_SOURCE_ADC_1_DATA16 ADC Data 16 INT_SOURCE_ADC_1_DATA17 ADC Data 17 INT_SOURCE_ADC_1_DATA18 ADC Data 18 INT_SOURCE_ADC_1_DATA19 ADC Data 19 INT_SOURCE_ADC_1_DATA20 ADC Data 20 INT_SOURCE_ADC_1_DATA21 ADC Data 21 INT_SOURCE_ADC_1_DATA22 ADC Data 22 INT_SOURCE_ADC_1_DATA23 ADC Data 23 INT_SOURCE_ADC_1_DATA24 ADC Data 24 INT_SOURCE_ADC_1_DATA25 ADC Data 25 INT_SOURCE_ADC_1_DATA26 ADC Data 26 INT_SOURCE_ADC_1_DATA27 ADC Data 27 INT_SOURCE_ADC_1_DATA28 ADC Data 28 INT_SOURCE_ADC_1_DATA29 ADC Data 29 INT_SOURCE_ADC_1_DATA30 ADC Data 30 INT_SOURCE_ADC_1_DATA31 ADC Data 31 INT_SOURCE_ADC_1_DATA32 ADC Data 32 INT_SOURCE_ADC_1_DATA33 ADC Data 33 INT_SOURCE_ADC_1_DATA34 ADC Data 34 INT_SOURCE_ADC_1_DATA35 ADC Data 35 INT_SOURCE_ADC_1_DATA36 ADC Data 36 INT_SOURCE_ADC_1_DATA37 ADC Data 37 INT_SOURCE_ADC_1_DATA38 ADC Data 38 INT_SOURCE_ADC_1_DATA39 ADC Data 39 INT_SOURCE_ADC_1_DATA40 ADC Data 40 INT_SOURCE_ADC_1_DATA41 ADC Data 41 Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1193 INT_SOURCE_ADC_1_DATA42 ADC Data 42 INT_SOURCE_ADC_1_DATA43 ADC Data 43 INT_SOURCE_ADC_1_DATA44 ADC Data 44 INT_SOURCE_ADC_END_OF_SCAN ADC End of Scan INT_SOURCE_ADC_ANALOG_CIRCUIT_READY ADC Analog Circuit Ready INT_SOURCE_ADC_UPDATE_READY ADC Update Ready INT_SOURCE_ADC_GROUP ADC Group INT_SOURCE_ADC_0_EARLY ADC0 Early Interrupt INT_SOURCE_ADC_1_EARLY ADC1 Early Interrupt INT_SOURCE_ADC_2_EARLY ADC2 Early Interrupt INT_SOURCE_ADC_3_EARLY ADC3 Early Interrupt INT_SOURCE_ADC_4_EARLY ADC4 Early Interrupt INT_SOURCE_ADC_7_EARLY ADC7 Early Interrupt INT_SOURCE_ADC_0_WARM ADC0 Warm Interrupt INT_SOURCE_ADC_1_WARM ADC1 Warm Interrupt INT_SOURCE_ADC_2_WARM ADC2 Warm Interrupt INT_SOURCE_ADC_3_WARM ADC3 Warm Interrupt INT_SOURCE_ADC_4_WARM ADC4 Warm Interrupt INT_SOURCE_ADC_7_WARM ADC7 Warm Interrupt INT_SOURCE_PARALLEL_PORT Parallel Master Port interrupt INT_SOURCE_PARALLEL_PORT_ERROR Parallel Master Port Error interrupt INT_SOURCE_COMPARATOR_1 Comparator 1 interrupt INT_SOURCE_COMPARATOR_2 Comparator 2 interrupt INT_SOURCE_CLOCK_MONITOR Fail-Safe Clock Monitor interrupt INT_SOURCE_RTCC Real-Time Clock and Calender interrupt INT_SOURCE_DMA_0 Direct Memory Access Channel 0 interrupt INT_SOURCE_DMA_1 Direct Memory Access Channel 1 interrupt INT_SOURCE_DMA_2 Direct Memory Access Channel 2 interrupt INT_SOURCE_DMA_3 Direct Memory Access Channel 3 interrupt INT_SOURCE_DMA_4 Direct Memory Access Channel 4 interrupt INT_SOURCE_DMA_5 Direct Memory Access Channel 5 interrupt INT_SOURCE_DMA_6 Direct Memory Access Channel 6 interrupt INT_SOURCE_DMA_7 Direct Memory Access Channel 7 interrupt INT_SOURCE_FLASH_CONTROL Flash Control Event interrupt INT_SOURCE_USB_1 Universal Serial Bus 1 interrupt INT_SOURCE_CAN_1 Controller Area Network 1 interrupt INT_SOURCE_CAN_2 Controller Area Network 2 interrupt INT_SOURCE_ETH_1 Ethernet interrupt INT_SOURCE_ADC_FAULT ADC Fault interrupt INT_SOURCE_CRYPTO Crypto interrupt INT_SOURCE_SPI_5_RECEIVE SPI 5 Receive Done interrupt INT_SOURCE_SPI_5_TRANSMIT SPI 5 Transmit Done interrupt INT_SOURCE_SPI_6_ERROR SPI 6 Error interrupt INT_SOURCE_SPI_6_RECEIVE SPI 6 Receive Done interrupt INT_SOURCE_SPI_6_TRANSMIT SPI 6 Transmit Done interrupt Description Interrupt Source This enumeration lists the possible sources that can cause an interrupt to occur. Remarks This enumeration is processor-specific and is defined in the processor-specific header files (see processor.h). INT_SUBPRIORITY_LEVEL Enumeration Lists the possible interrupt sub priority levels. Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1194 File plib_int_help.h C typedef enum { INT_SUBPRIORITY_LEVEL0, INT_SUBPRIORITY_LEVEL1, INT_SUBPRIORITY_LEVEL2, INT_SUBPRIORITY_LEVEL3 } INT_SUBPRIORITY_LEVEL; Members Members Description INT_SUBPRIORITY_LEVEL0 Sub Priority 0 INT_SUBPRIORITY_LEVEL1 Sub Priority 1 INT_SUBPRIORITY_LEVEL2 Sub Priority 2 INT_SUBPRIORITY_LEVEL3 Sub Priority 3 Description Sub Priority Level This enumeration lists the possible interrupt sub priority levels that can be selected for each source. Remarks This enumeration (INT_SUBPRIORITY_LEVEL) is processor-specific and is defined in the processor-specific header files (see processor.h). INT_VECTOR Enumeration Lists the possible interrupt vectors. File plib_int_help.h C typedef enum { INT_VECTOR_CT, INT_VECTOR_CS0, INT_VECTOR_CS1, INT_VECTOR_INT0, INT_VECTOR_T1, INT_VECTOR_IC1, INT_VECTOR_OC1, INT_VECTOR_INT1, INT_VECTOR_T2, INT_VECTOR_IC2, INT_VECTOR_OC2, INT_VECTOR_INT2, INT_VECTOR_T3, INT_VECTOR_IC3, INT_VECTOR_OC3, INT_VECTOR_INT3, INT_VECTOR_T4, INT_VECTOR_IC4, INT_VECTOR_OC4, INT_VECTOR_INT4, INT_VECTOR_T5, INT_VECTOR_IC5, INT_VECTOR_OC5, INT_VECTOR_SPI1, INT_VECTOR_UART1, INT_VECTOR_SPI3, INT_VECTOR_I2C3, INT_VECTOR_I2C1, INT_VECTOR_CN, INT_VECTOR_AD1, INT_VECTOR_PMP, INT_VECTOR_CMP1, INT_VECTOR_CMP2, Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1195 INT_VECTOR_UART3 , INT_VECTOR_SPI2 , INT_VECTOR_I2C4 , INT_VECTOR_UART2 , INT_VECTOR_SPI4 , INT_VECTOR_I2C5 , INT_VECTOR_I2C2 , INT_VECTOR_FSCM , INT_VECTOR_RTCC , INT_VECTOR_DMA0 , INT_VECTOR_DMA1 , INT_VECTOR_DMA2 , INT_VECTOR_DMA3 , INT_VECTOR_DMA4 , INT_VECTOR_DMA5 , INT_VECTOR_DMA6 , INT_VECTOR_DMA7 , INT_VECTOR_FCE , INT_VECTOR_USB , INT_VECTOR_CAN1 , INT_VECTOR_CAN2 , INT_VECTOR_ETH , INT_VECTOR_UART4 , INT_VECTOR_UART6 , INT_VECTOR_UART5 , INT_VECTOR_ADC1 , INT_VECTOR_ADC1_DC1 , INT_VECTOR_ADC1_DC2 , INT_VECTOR_ADC1_DC3 , INT_VECTOR_ADC1_DC4 , INT_VECTOR_ADC1_DC5 , INT_VECTOR_ADC1_DC6 , INT_VECTOR_ADC1_DF1 , INT_VECTOR_ADC1_DF2 , INT_VECTOR_ADC1_DF3 , INT_VECTOR_ADC1_DF4 , INT_VECTOR_ADC1_DF5 , INT_VECTOR_ADC1_DF6 , INT_VECTOR_ADC1_DATA0 , INT_VECTOR_ADC1_DATA1 , INT_VECTOR_ADC1_DATA2 , INT_VECTOR_ADC1_DATA3 , INT_VECTOR_ADC1_DATA4 , INT_VECTOR_ADC1_DATA5 , INT_VECTOR_ADC1_DATA6 , INT_VECTOR_ADC1_DATA7 , INT_VECTOR_ADC1_DATA8 , INT_VECTOR_ADC1_DATA9 , INT_VECTOR_ADC1_DATA10 , INT_VECTOR_ADC1_DATA11 , INT_VECTOR_ADC1_DATA12 , INT_VECTOR_ADC1_DATA13 , INT_VECTOR_ADC1_DATA14 , INT_VECTOR_ADC1_DATA15 , INT_VECTOR_ADC1_DATA16 , INT_VECTOR_ADC1_DATA17 , INT_VECTOR_ADC1_DATA18 , INT_VECTOR_ADC1_DATA19 , INT_VECTOR_ADC1_DATA20 , INT_VECTOR_ADC1_DATA21 , INT_VECTOR_ADC1_DATA22 , INT_VECTOR_ADC1_DATA23 , INT_VECTOR_ADC1_DATA24 , INT_VECTOR_ADC1_DATA25 , INT_VECTOR_ADC1_DATA26 , INT_VECTOR_ADC1_DATA27 , INT_VECTOR_ADC1_DATA28 , INT_VECTOR_ADC1_DATA29 , INT_VECTOR_ADC1_DATA30 , INT_VECTOR_ADC1_DATA31 , INT_VECTOR_ADC1_DATA32 , INT_VECTOR_ADC1_DATA33 , INT_VECTOR_ADC1_DATA34 , INT_VECTOR_ADC1_DATA35 , INT_VECTOR_ADC1_DATA36 , Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1196 INT_VECTOR_ADC1_DATA37, INT_VECTOR_ADC1_DATA38, INT_VECTOR_ADC1_DATA39, INT_VECTOR_ADC1_DATA40, INT_VECTOR_ADC1_DATA41, INT_VECTOR_ADC1_DATA42, INT_VECTOR_ADC1_DATA43, INT_VECTOR_ADC1_DATA44, INT_VECTOR_ADC_END_OF_SCAN, INT_VECTOR_ADC_ANALOG_CIRCUIT_READY, INT_VECTOR_ADC_UPDATE_READY, INT_VECTOR_ADC_GROUP, INT_VECTOR_ADC_0_EARLY, INT_VECTOR_ADC_1_EARLY, INT_VECTOR_ADC_2_EARLY, INT_VECTOR_ADC_3_EARLY, INT_VECTOR_ADC_4_EARLY, INT_VECTOR_ADC_7_EARLY, INT_VECTOR_ADC_0_WARM, INT_VECTOR_ADC_1_WARM, INT_VECTOR_ADC_2_WARM, INT_VECTOR_ADC_3_WARM, INT_VECTOR_ADC_4_WARM, INT_VECTOR_ADC_7_WARM, INT_VECTOR_ADC_FAULT, INT_VECTOR_CRYPTO, INT_VECTOR_I2C2_BUS, INT_VECTOR_I2C2_SLAVE, INT_VECTOR_I2C2_MASTER, INT_VECTOR_SPI5_FAULT, INT_VECTOR_SPI5_RX, INT_VECTOR_SPI5_TX, INT_VECTOR_SPI6_FAULT, INT_VECTOR_SPI6_RX, INT_VECTOR_SPI6_TX, INT_VECTOR_CHANGE_NOTICE_A, INT_VECTOR_CHANGE_NOTICE_B, INT_VECTOR_CHANGE_NOTICE_C, INT_VECTOR_CHANGE_NOTICE_D, INT_VECTOR_CHANGE_NOTICE_E, INT_VECTOR_CHANGE_NOTICE_F, INT_VECTOR_CHANGE_NOTICE_G, INT_VECTOR_CHANGE_NOTICE_H, INT_VECTOR_CHANGE_NOTICE_J, INT_VECTOR_CHANGE_NOTICE_K } INT_VECTOR; Members Members Description INT_VECTOR_CT Core Timer Interrupt INT_VECTOR_CS0 Core Software Interrupt 0 INT_VECTOR_CS1 Core Software Interrupt 1 INT_VECTOR_INT0 External Interrupt 0 INT_VECTOR_T1 Timer 1 Interrupt INT_VECTOR_IC1 Input Capture 1 Interrupt INT_VECTOR_OC1 Output Compare 1 Interrupt INT_VECTOR_INT1 External Interrupt 1 INT_VECTOR_T2 Timer 2 Interrupt INT_VECTOR_IC2 Input Capture 2 Interrupt INT_VECTOR_OC2 Output Compare 2 Interrupt INT_VECTOR_INT2 External Interrupt 2 INT_VECTOR_T3 Timer 3 Interrupt INT_VECTOR_IC3 Input Capture 3 Interrupt INT_VECTOR_OC3 Output Compare 3 Interrupt INT_VECTOR_INT3 External Interrupt 3 INT_VECTOR_T4 Timer 4 Interrupt INT_VECTOR_IC4 Input Capture 4 Interrupt Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1197 INT_VECTOR_OC4 Output Compare 4 Interrupt INT_VECTOR_INT4 External Interrupt 4 INT_VECTOR_T5 Timer 5 Interrupt INT_VECTOR_IC5 Input Capture 5 Interrupt INT_VECTOR_OC5 Output Compare 5 Interrupt INT_VECTOR_SPI1 SPI 1 Interrupt INT_VECTOR_UART1 UART 1 Interrupt INT_VECTOR_SPI3 SPI 3 Interrupt INT_VECTOR_I2C3 I2C 3 Interrupt INT_VECTOR_I2C1 I2C 1 Interrupt INT_VECTOR_CN Change Notification Interrupt INT_VECTOR_AD1 ADC Interrupt INT_VECTOR_PMP PMP Interrupt INT_VECTOR_CMP1 Comparator 1 Interrupt INT_VECTOR_CMP2 Comparator 2 Interrupt INT_VECTOR_UART3 UART 3 Interrupt INT_VECTOR_SPI2 SPI 2 Interrupt INT_VECTOR_I2C4 I2C 4 Interrupt INT_VECTOR_UART2 UART 2 Interrupt INT_VECTOR_SPI4 SPI 4 Interrupt INT_VECTOR_I2C5 I2C 5 Interrupt INT_VECTOR_I2C2 I2C 2 Interrupt INT_VECTOR_FSCM Fail Safe Clock Monitor Interrupt INT_VECTOR_RTCC RTCC Interrupt INT_VECTOR_DMA0 DMA 0 Interrupt INT_VECTOR_DMA1 DMA 1 Interrupt INT_VECTOR_DMA2 DMA 2 Interrupt INT_VECTOR_DMA3 DMA 3 Interrupt INT_VECTOR_DMA4 DMA 4 Interrupt INT_VECTOR_DMA5 DMA 5 Interrupt INT_VECTOR_DMA6 DMA 6 Interrupt INT_VECTOR_DMA7 DMA 7 Interrupt INT_VECTOR_FCE Flash Control Event Interrupt INT_VECTOR_USB USB Interrupt INT_VECTOR_CAN1 CAN 1 Interrupt INT_VECTOR_CAN2 CAN 2 Interrupt INT_VECTOR_ETH Ethernet Interrupt INT_VECTOR_UART4 UART 4 Interrupt INT_VECTOR_UART6 UART 6 Interrupt INT_VECTOR_UART5 UART 5 Interrupt INT_VECTOR_ADC1 Analog-to-Digital Converter 1 interrupt INT_VECTOR_ADC1_DC1 ADC Digital Comparator 1 INT_VECTOR_ADC1_DC2 ADC Digital Comparator 2 INT_VECTOR_ADC1_DC3 ADC Digital Comparator 3 INT_VECTOR_ADC1_DC4 ADC Digital Comparator 4 INT_VECTOR_ADC1_DC5 ADC Digital Comparator 5 INT_VECTOR_ADC1_DC6 ADC Digital Comparator 6 INT_VECTOR_ADC1_DF1 ADC Digital Filter 1 INT_VECTOR_ADC1_DF2 ADC Digital Filter 2 INT_VECTOR_ADC1_DF3 ADC Digital Filter 3 INT_VECTOR_ADC1_DF4 ADC Digital Filter 4 INT_VECTOR_ADC1_DF5 ADC Digital Filter 5 INT_VECTOR_ADC1_DF6 ADC Digital Filter 6 INT_VECTOR_ADC1_DATA0 ADC Data 0 INT_VECTOR_ADC1_DATA1 ADC Data 1 Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1198 INT_VECTOR_ADC1_DATA2 ADC Data 2 INT_VECTOR_ADC1_DATA3 ADC Data 3 INT_VECTOR_ADC1_DATA4 ADC Data 4 INT_VECTOR_ADC1_DATA5 ADC Data 5 INT_VECTOR_ADC1_DATA6 ADC Data 6 INT_VECTOR_ADC1_DATA7 ADC Data 7 INT_VECTOR_ADC1_DATA8 ADC Data 8 INT_VECTOR_ADC1_DATA9 ADC Data 9 INT_VECTOR_ADC1_DATA10 ADC Data 10 INT_VECTOR_ADC1_DATA11 ADC Data 11 INT_VECTOR_ADC1_DATA12 ADC Data 12 INT_VECTOR_ADC1_DATA13 ADC Data 13 INT_VECTOR_ADC1_DATA14 ADC Data 14 INT_VECTOR_ADC1_DATA15 ADC Data 15 INT_VECTOR_ADC1_DATA16 ADC Data 16 INT_VECTOR_ADC1_DATA17 ADC Data 17 INT_VECTOR_ADC1_DATA18 ADC Data 18 INT_VECTOR_ADC1_DATA19 ADC Data 19 INT_VECTOR_ADC1_DATA20 ADC Data 20 INT_VECTOR_ADC1_DATA21 ADC Data 21 INT_VECTOR_ADC1_DATA22 ADC Data 22 INT_VECTOR_ADC1_DATA23 ADC Data 23 INT_VECTOR_ADC1_DATA24 ADC Data 24 INT_VECTOR_ADC1_DATA25 ADC Data 25 INT_VECTOR_ADC1_DATA26 ADC Data 26 INT_VECTOR_ADC1_DATA27 ADC Data 27 INT_VECTOR_ADC1_DATA28 ADC Data 28 INT_VECTOR_ADC1_DATA29 ADC Data 29 INT_VECTOR_ADC1_DATA30 ADC Data 30 INT_VECTOR_ADC1_DATA31 ADC Data 31 INT_VECTOR_ADC1_DATA32 ADC Data 32 INT_VECTOR_ADC1_DATA33 ADC Data 33 INT_VECTOR_ADC1_DATA34 ADC Data 34 INT_VECTOR_ADC1_DATA35 ADC Data 35 INT_VECTOR_ADC1_DATA36 ADC Data 36 INT_VECTOR_ADC1_DATA37 ADC Data 37 INT_VECTOR_ADC1_DATA38 ADC Data 38 INT_VECTOR_ADC1_DATA39 ADC Data 39 INT_VECTOR_ADC1_DATA40 ADC Data 40 INT_VECTOR_ADC1_DATA41 ADC Data 41 INT_VECTOR_ADC1_DATA42 ADC Data 42 INT_VECTOR_ADC1_DATA43 ADC Data 43 INT_VECTOR_ADC1_DATA44 ADC Data 44 INT_VECTOR_ADC_END_OF_SCAN ADC End of Scan INT_VECTOR_ADC_ANALOG_CIRCUIT_READY ADC Analog Circuit Ready INT_VECTOR_ADC_UPDATE_READY ADC Update Ready INT_VECTOR_ADC_GROUP ADC Group INT_VECTOR_ADC_0_EARLY ADC0 Early Interrupt INT_VECTOR_ADC_1_EARLY ADC1 Early Interrupt INT_VECTOR_ADC_2_EARLY ADC2 Early Interrupt INT_VECTOR_ADC_3_EARLY ADC3 Early Interrupt INT_VECTOR_ADC_4_EARLY ADC4 Early Interrupt INT_VECTOR_ADC_7_EARLY ADC7 Early Interrupt INT_VECTOR_ADC_0_WARM ADC0 Warm Interrupt INT_VECTOR_ADC_1_WARM ADC1 Warm Interrupt Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1199 INT_VECTOR_ADC_2_WARM ADC2 Warm Interrupt INT_VECTOR_ADC_3_WARM ADC3 Warm Interrupt INT_VECTOR_ADC_4_WARM ADC4 Warm Interrupt INT_VECTOR_ADC_7_WARM ADC7 Warm Interrupt INT_VECTOR_ADC_FAULT ADC Fault interrupt INT_VECTOR_CRYPTO Crypto interrupt INT_VECTOR_I2C2_BUS I2C 2 Bus Interrupt INT_VECTOR_I2C2_SLAVE I2C 2 Bus Interrupt INT_VECTOR_I2C2_MASTER I2C 2 Bus Interrupt INT_VECTOR_SPI5_FAULT SPI 5 Error interrupt INT_VECTOR_SPI5_RX SPI 5 Receive Done interrupt INT_VECTOR_SPI5_TX SPI 5 Transmit Done interrupt INT_VECTOR_SPI6_FAULT SPI 6 Error interrupt INT_VECTOR_SPI6_RX SPI 6 Receive Done interrupt INT_VECTOR_SPI6_TX SPI 6 Transmit Done interrupt INT_VECTOR_CHANGE_NOTICE_A Input Change Notice Channel A interrupt INT_VECTOR_CHANGE_NOTICE_B Input Change Notice Channel B interrupt INT_VECTOR_CHANGE_NOTICE_C Input Change Notice Channel C interrupt INT_VECTOR_CHANGE_NOTICE_D Input Change Notice Channel D interrupt INT_VECTOR_CHANGE_NOTICE_E Input Change Notice Channel E interrupt INT_VECTOR_CHANGE_NOTICE_F Input Change Notice Channel F interrupt INT_VECTOR_CHANGE_NOTICE_G Input Change Notice Channel G interrupt INT_VECTOR_CHANGE_NOTICE_H Input Change Notice Channel H interrupt INT_VECTOR_CHANGE_NOTICE_J Input Change Notice Channel J interrupt INT_VECTOR_CHANGE_NOTICE_K Input Change Notice Channel K interrupt Description Interrupt Vectors This enumeration lists the possible interrupt vectors. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). INT_STATE_GLOBAL Type Data type defining the global interrupt state. File plib_int.h C typedef uint32_t INT_STATE_GLOBAL; Description INT global state type definition This data type is used for interrupt enable and disable functions. Remarks None. INT_SHADOW_REGISTER Enumeration Lists the possible shadow register sets. File plib_int_help.h Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1200 C typedef enum { INT_SHADOW_REGISTER_0, INT_SHADOW_REGISTER_1, INT_SHADOW_REGISTER_2, INT_SHADOW_REGISTER_3, INT_SHADOW_REGISTER_4, INT_SHADOW_REGISTER_5, INT_SHADOW_REGISTER_6, INT_SHADOW_REGISTER_7 } INT_SHADOW_REGISTER; Members Members Description INT_SHADOW_REGISTER_0 Shadow register set 0 INT_SHADOW_REGISTER_1 Shadow register set 1 INT_SHADOW_REGISTER_2 Shadow register set 2 INT_SHADOW_REGISTER_3 Shadow register set 3 INT_SHADOW_REGISTER_4 Shadow register set 4 INT_SHADOW_REGISTER_5 Shadow register set 5 INT_SHADOW_REGISTER_6 Shadow register set 6 INT_SHADOW_REGISTER_7 Shadow register set 7 Description Shadow Register Sets This enumeration lists the possible shadow register sets. Remarks This feature may not be available on all the devices. Refer to the specific device header files for availability. INT_VECTOR_SPACING Enumeration Lists the possible interrupt vector spacing. File plib_int_help.h C typedef enum { INT_VECTOR_SPACING_0, INT_VECTOR_SPACING_8, INT_VECTOR_SPACING_16, INT_VECTOR_SPACING_32, INT_VECTOR_SPACING_64, INT_VECTOR_SPACING_128, INT_VECTOR_SPACING_256, INT_VECTOR_SPACING_512 } INT_VECTOR_SPACING; Members Members Description INT_VECTOR_SPACING_0 0 Byte Vector Spacing INT_VECTOR_SPACING_8 8 Byte Vector Spacing INT_VECTOR_SPACING_16 16 Byte Vector Spacing INT_VECTOR_SPACING_32 32 Byte Vector Spacing INT_VECTOR_SPACING_64 64 Byte Vector Spacing INT_VECTOR_SPACING_128 128 Byte Vector Spacing INT_VECTOR_SPACING_256 256 Byte Vector Spacing INT_VECTOR_SPACING_512 512 Byte Vector Spacing Description Interrupt Vector Spacing Peripheral Libraries Help Interrupt Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1201 This enumeration lists the possible interrupt vector spacing, which can be provided between two interrupt vectors. Remarks This feature may not be available in all the devices. Refer to the specific device header files for availability. Files Files Name Description plib_int.h Defines the Interrupt Peripheral Library interface plib_int_help.h Description This section lists the source and header files used by the library. plib_int.h Defines the Interrupt Peripheral Library interface Functions Name Description PLIB_INT_CPUCurrentPriorityLevelGet Gets the interrupt priority level at which the CPU is currently operating. PLIB_INT_Disable Disables the generation of interrupts to the CPU. PLIB_INT_Enable Enables the generation of interrupts to the CPU. PLIB_INT_ExistsCPUCurrentPriorityLevel Identifies whether the CPUCurrentPriorityLevel feature exists on the Interrupts module. PLIB_INT_ExistsEnableControl Identifies whether the EnableControl feature exists on the Interrupt module. PLIB_INT_ExistsExternalINTEdgeSelect Identifies whether the ExternalINTEdgeSelect feature exists on the Interrupts module. PLIB_INT_ExistsINTCPUPriority Identifies whether the INTCPUPriority feature exists on the Interrupt module. PLIB_INT_ExistsINTCPUVector Identifies whether the INTCPUVector feature exists on the Interrupt module. PLIB_INT_ExistsProximityTimerControl Identifies whether the ProximityTimerControl feature exists on the Interrupts module. PLIB_INT_ExistsProximityTimerEnable Identifies whether the ProximityTimerEnable feature exists on the Interrupts module. PLIB_INT_ExistsShadowRegisterAssign Identifies whether the ShadowRegisterAssign feature exists on the Interrupts module. PLIB_INT_ExistsSingleVectorShadowSet Identifies whether the SingleVectorShadowSet feature exists on the Interrupt module. PLIB_INT_ExistsSoftwareNMI Identifies whether the SoftwareNMI feature exists on the Interrupt module. PLIB_INT_ExistsSourceControl Identifies whether the SourceControl feature exists on the Interrupt module. PLIB_INT_ExistsSourceFlag Identifies whether the SourceFlag feature exists on the Interrupt module. PLIB_INT_ExistsVariableOffset Identifies whether the VariableOffset feature exists on the Interrupt module. PLIB_INT_ExistsVectorPriority Identifies whether the VectorPriority feature exists on the Interrupt module. PLIB_INT_ExistsVectorSelect Identifies whether the VectorSelect feature exists on the Interrupt module. PLIB_INT_ExternalFallingEdgeSelect Selects the falling edge as the edge polarity of the external interrupt. PLIB_INT_ExternalRisingEdgeSelect Selects the rising edge as the edge polarity of the external interrupt. PLIB_INT_GetStateAndDisable Disables the generation of interrupts to the CPU. PLIB_INT_IsEnabled Identifies if interrupts are currently enabled or disabled at the top level. PLIB_INT_MultiVectorSelect Configures the Interrupt Controller for Multiple Vector mode. PLIB_INT_PriorityGet Returns the priority level of the latest interrupt presented to the CPU. PLIB_INT_ProximityTimerDisable Disables the interrupt temporal-proximity timer. PLIB_INT_ProximityTimerEnable Enables the interrupt temporal-proximity timer and selects the priority levels that start the timer. PLIB_INT_ProximityTimerGet Returns the value used by the temporal proximity timer as a reload value when the temporal proximity timer is triggered by an interrupt event. PLIB_INT_ProximityTimerSet Sets the temporal proximity timer reload value. This value is used to reload the proximity timer after it has been triggered by an interrupt event. PLIB_INT_SetState Restores the status of CPU interrupts based on the value passed into the function. PLIB_INT_ShadowRegisterAssign Assigns a shadow register set for an interrupt priority level. PLIB_INT_ShadowRegisterGet Gets the shadow register set assigned for an interrupt priority level. PLIB_INT_SingleVectorSelect Configures the Interrupt Controller for Single Vector mode. PLIB_INT_SingleVectorShadowSetDisable Disables the Shadow Register Set in Single Vector mode. Peripheral Libraries Help Interrupt Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1202 PLIB_INT_SingleVectorShadowSetEnable Enables the Shadow Register Set in Single Vector mode. PLIB_INT_SoftwareNMITrigger Triggers software NMI. PLIB_INT_SourceDisable Disables the interrupt source PLIB_INT_SourceEnable Enables the interrupt source. PLIB_INT_SourceFlagClear Clears the status of the interrupt flag for the selected source. PLIB_INT_SourceFlagGet Returns the status of the interrupt flag for the selected source. PLIB_INT_SourceFlagSet Sets the status of the interrupt flag for the selected source. PLIB_INT_SourceIsEnabled Gets the enable state of the interrupt source. PLIB_INT_VariableVectorOffsetGet Gets the offset specific to an interrupt source number. PLIB_INT_VariableVectorOffsetSet Sets the offset specific to an interrupt source number. PLIB_INT_VectorGet Returns the interrupt vector that is presented to the CPU. PLIB_INT_VectorPriorityGet Gets the priority of the interrupt vector. PLIB_INT_VectorPrioritySet Sets the priority of the interrupt vector. PLIB_INT_VectorSubPriorityGet Gets the sub-priority of the interrupt vector. PLIB_INT_VectorSubPrioritySet Sets the sub-priority of the interrupt vector. Types Name Description INT_STATE_GLOBAL Data type defining the global interrupt state. Description Interrupt Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Interrupt Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Interrupt Controller module. File Name plib_int.h Company Microchip Technology Inc. plib_int_help.h Enumerations Name Description INT_EXTERNAL_SOURCES Lists the possible external sources that can cause an interrupt to occur. INT_PRIORITY_LEVEL Lists the possible interrupt priority levels. INT_SHADOW_REGISTER Lists the possible shadow register sets. INT_SOURCE Lists the possible sources that can cause an interrupt to occur. INT_SUBPRIORITY_LEVEL Lists the possible interrupt sub priority levels. INT_VECTOR Lists the possible interrupt vectors. INT_VECTOR_SPACING Lists the possible interrupt vector spacing. Section Interrupt Controller Definitions - Processor-Specific Enumerations *************************************************************************** *************************************************************************** This section defines Interrupt Controller enumerations that are processor-specific. Peripheral Libraries Help Interrupt Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1203 NVM Peripheral Library This section describes the Non-volatile Memory (NVM) Peripheral Library. Introduction This library provides a low-level abstraction of the Non-Volatile Memory (NVM)component (Flash and EEPROM) on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description Flash Program Memory The Flash program memory is readable, writeable and erasable during normal operation over the entire operating voltage range. A read from program memory is executed at one byte/word at a time depending on the width of the data bus. A write to the program memory is executed in either blocks of specific sizes or a single word depending on the type of processor used. An erase is performed in blocks. A bulk erase may be performed from user code depending on the type of processor supporting the operation. Writing or erasing program memory will cease instruction fetches until the operation is complete thus restricting memory access and therefore preventing code execution. This is controlled by an internal programming timer. There are three processor dependant methods for Flash program memory modification. • Run-Time Self Programming (RTSP) • In-Circuit Serial Programming (ICSP) • EJTAG programming Note: This topic covers the RTSP techniques. EEPROM Memory The EEPROM memory is the data storage memory. On device power-up, power is disconnected from the EEPROM and the EEPROM will be in its lowest power mode. When it is enabled, power is applied to the EEPROM, but it will be ready for the access only after a power-up delay. Once ready for access, all read and write operations are executed using the Data EEPROM registers. Write/Read/Erase operations are possible in words. A bulk erase may be performed to erase the full EEPROM. Using the Library This topic describes the basic architecture of the NVM Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_nvm.h The interface to the NVM library is defined in the plib_nvm.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the NVM library must include peripheral.h. Library File: The NVM peripheral library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the NVM module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Abstraction Model The NVM Peripheral Library provides interface routines to interact with the blocks shown in the diagram. NVM Software Abstraction Block Diagram Peripheral Libraries Help NVM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1204 The Flash Status and Control logic ensures that the Flash memory is configured appropriately for modification. It also provides the status of the different operations in progress as well as errors, if any. It also decides if the operation is for Flash program memory or the special device Configuration registers. The Flash Read/Write block ensures that the user data is written to/read from the program memory holding latches. It provides a_layer of abstraction over the sequence of processor specific instructions which are required to access this data. Depending on the processor type, either block or Word programming options are available. The EEPROM Status and Control logic ensures that the EEPROM is configured appropriately for access and also provides the status of the different operations in progress, as well as errors, if any. The EEPROM Read/Write block ensures that the user data is written to/read from the data EEPROM. All of the EEPROM operations are word programmable with the exception of the bulk erase, which erases the entire EEPROM. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the NVM module Library Interface Section Description Flash Memory Configuration and Status Functions Provides Flash memory setup, configuration, and status control interface routines. Flash Memory Functions Provides Flash memory interface routines. Other Flash Memory Functions Provides additional functions for Boot page and Flash memory. EEPROM Configuration and Status Functions Provides EEPROM setup, configuration, and status control interface routines. EEPROM Operation Functions Provides interface routines for EEPROM operations. Feature Existence Functions Determine whether or not certain features are available. How the Library Works The usage model for this library is explained in the following sections. Description Each of the blocks in the diagram correspond to the library interface section. Usage Model Peripheral Libraries Help NVM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1205 State Machine This topic describes the NVM Write and Read state machine. Description The following state machine is for the NVM Read and Write during the normal operation. This state machine is provided to give a general idea of the usage model of the peripheral library. Refer to the usage model for more detailed steps for the scenario that is being used. NVM Write and Read State Machine Peripheral Libraries Help NVM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1206 State Associated Function Setup and Initialization Refer to mode of NVM for detailed instructions of setup. Select Type of memory Once the NVM has been appropriately set up and initialized, the state machine waits for the application to select the type of memory to be accessed, either Memory region (Flash/EEPROM) or the corresponding configuration registers. Configure and enable write/read Configures the registers and enables the write/read operation. Select Address The application provides the write/read address from which to access memory. Send Data/Read Data When the application is polling it can fill data/read data into the internal holding registers and initiate write via PLIB_NVM_FlashWriteStart(NVM_ID_0) or PLIB_NVM_EEPROMWriteStart(NVM_ID_0). Read Error/Write Status The error/write status is available to the application through the PLIB_NVM_FlashWriteCycleHasCompleted(NVM_ID_0) or PLIB_NVM_EEPROMOperationHasCompleted(NVM_ID_0) functions and other status/error APIs. Note: Refer to the mode used for the NVM for the setup and initialization steps. Peripheral Libraries Help NVM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1207 Flash Operations This topic describes Flash operations. Description Note: Flash program memory operations vary across microcontrollers. Please refer to the "Flash Controller" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine which features are supported by the device in use. Flash Read Operation Setup Do the following set up Flash read operation: 1. Provide the Flash program memory from which the data memory has to be read via the API PLIB_NVM_FlashRead function. This address is then updated in the respective address registers or the Table Pointers depending on the device. 2. Ensure the alignment of the address as specified by the specific device data sheet. 3. The size of the data read depends upon the microcontroller in use. For details, please refer to the specific device data sheet. Example: Flash Program Memory Read // Determine the address from which to read #define MY_FLASH_BASE_ADDRESS 0xA0007862 // Or any address in Flash to read uint32_t address = MY_FLASH_BASE_ADDRESS; // The Data Available at the memory location size_t DataToBeRead; // where, MY_NVM_INSTANCE - is a specific instance of the hardware peripheral. // where, address - The address in the memory from which to read. DataToBeRead = PLIB_NVM_FlashRead(NVM_ID_0, address); EEPROM Operations This topic describes EEPROM operations. Description Note: EEPROM operations vary across microcontrollers. Please refer to the "Data EEPROM" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine which features are supported by the device in use. Before accessing the EEPROM at full speed, it is necessary to program configuration values into the Data EEPROM controller after enabling it. Refer to "EEPROM Configuration Write Operation Setup" in Flash Operations for more information. EEPROM Read Operation Setup Prior to reading the Data EEPROM, the Data EEPROM must be enabled and ready. There can be no ongoing command when a new command is issued to the Data EEPROM. Do the following to execute a Data EEPROM read operation: 1. Load the Data EEPROM address to be read. The address must be on a 32-bit boundary and the last two bits must be ‘00’. 2. Select the read operation command. 3. Enable for read access. 4. Start the read operation. 5. Wait until the read cycle is complete. 6. Read the data from the intermediate register. Example: EEPROM Read if (PLIB_NVM_EEPROMIsReady( NVM_ID_0 )) { // There should be no ongoing operation. if (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )) { // Set address on 32-bit boundary, last two bits must be '00' uint32_t ADDR = 0x0100; // Load Data EEPROM read command PLIB_NVM_EEPROMOperationSelect( NVM_ID_0 , EEPROM_WORD_READ_OPERATION); // Load address and check if it is valid if(true ==PLIB_NVM_EEPROMAddress( NVM_ID_0 , ADDR )) { Peripheral Libraries Help NVM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1208 // Enable access for read PLIB_NVM_EEPROMReadEnable( NVM_ID_0 ); // Start the read operation PLIB_NVM_EEPROMReadStart( NVM_MODULE_ID index ); // Wait until read is complete while (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )); // Read the data *ee_data = PLIB_NVM_EEPROMRead( NVM_ID_0 ); } } } EEPROM Write Operation Setup Prior to writing to the Data EEPROM, the Data EEPROM must be enabled and ready. There can be no ongoing command when a new command is issued to the Data EEPROM. Do the following to execute a Data EEPROM write operation: 1. Load the Data EEPROM address where data has to be stored. The address must be on a 32-bit boundary so that the last two bits must be ‘00’. 2. Select the write operation command. 3. Enable for write access. 4. Write data into the intermediate register. 5. Execute the Data EEPROM unlock sequence. 6. Start the write operation. 7. Wait until the write cycle is complete. Example: EEPROM Write if (PLIB_NVM_EEPROMIsReady( NVM_ID_0 )) { // There should be no ongoing operation. if (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )) { // Set address on 32-bit boundary, last two bits must be '00' uint32_t ADDR = 0x0100; //Keys to unlock EEPROM uint32_t key1 = 0xEDB7; uint32_t key2 = 0x1248; // Load Data EEPROM write command PLIB_NVM_EEPROMOperationSelect( NVM_ID_0 , EEPROM_WORD_WRITE_OPERATION); // Load address and check if it is valid if(true ==PLIB_NVM_EEPROMAddress( NVM_ID_0 , ADDR )) { // Enable access to write PLIB_NVM_EEPROMWriteEnable( NVM_ID_0 ); // Load data to intermediate register PLIB_NVM_EEPROMDataToWrite ( NVM_ID_0 , ee_data ) ; // Unlock the EEPROM PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key1); PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key2); // Start the write operation PLIB_NVM_EEPROMWriteStart( NVM_MODULE_ID index ); // Wait until write is complete while (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )); } } } EEPROM Forced Word Erase Operation Setup Under normal conditions, there is no need to attempt a Forced Word Erase. The Data EEPROM has internal logic which automatically manages all read, erase, and write command sequences. If a verification error occurs during a write to the Data EEPROM, the user can attempt a Forced Word Erase operation to recover the Data EEPROM word storage location. The Word Erase operation is similar to the write operation. Example: EEPROM Word Erase if (PLIB_NVM_EEPROMIsReady( NVM_ID_0 )) { // There should be no ongoing operation. if (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )) Peripheral Libraries Help NVM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1209 { // Set address on 32-bit boundary, last two bits must be '00' uint32_t ADDR = 0x0100; //Keys to unlock EEPROM uint32_t key1 = 0xEDB7; uint32_t key2 = 0x1248; // Load Data EEPROM forced word erase command PLIB_NVM_EEPROMOperationSelect( NVM_ID_0 , EEPROM_FORCED_WORD_ERASE_OPERATION); // Load address and check if it is valid if(true ==PLIB_NVM_EEPROMAddress( NVM_ID_0 , ADDR )) { // Enable access to write PLIB_NVM_EEPROMWriteEnable( NVM_ID_0 ); // Unlock the EEPROM PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key1); PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key2); // Start the write operation PLIB_NVM_EEPROMEraseStart( NVM_MODULE_ID index ); // Wait until write is complete while (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )); } } EEPROM Bulk Erase Operation Setup Prior to erasing the entire Data EEPROM, the Data EEPROM must be enabled and ready. There can be no ongoing command when a new command is issued to the Data EEPROM. The Bulk Erase operation is similar to the write operation except the EEPROM operation is selected for Bulk erase and the data or address does not need to be loaded. Example: EEPROM Bulk Erase if (PLIB_NVM_EEPROMIsReady( NVM_ID_0 )) { // There should be no ongoing operation. if (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )) { //Keys to unlock EEPROM uint32_t key1 = 0xEDB7; uint32_t key2 = 0x1248; // Load Data EEPROM forced word erase command PLIB_NVM_EEPROMOperationSelect( NVM_ID_0 , EEPROM_ERASE_ALL_OPERATION); // Enable access to write PLIB_NVM_EEPROMWriteEnable( NVM_ID_0 ); // Unlock the EEPROM PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key1); PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key2); // Start the write operation PLIB_NVM_EEPROMEraseStart( NVM_MODULE_ID index ); // Wait until write is complete while (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )); } } EEPROM Configuration Write Operation Setup Before accessing the EEPROM at full speed, it is necessary to program configuration values into the Data EEPROM controller after enabling it. This is done through the Configuration Write operation. The configuration values to be written to the Data EEPROM Controller are stored in the DEVEE1 through DEVEE8 registers. Eight consecutive word write cycles should be performed with the EEPROM Configuration Write mode operation selected. Miscellaneous Functions This topic describes miscellaneous features. Description Note: Features vary across microcontrollers. Please refer to the "Flash Controller" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine which features are supported by the device in use. This section will detail out a few niche and processor-specific APIs provided by this library. Peripheral Libraries Help NVM Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1210 Stop in Idle Mode The PLIB_NVM_EEPROMStopInIdleEnable and PLIB_NVM_EEPROMStopInIdleDisable functions cater to this functionality. These functions ensure that EEPROM operations are discontinued or continued in Idle mode. Low Voltage Detection The PLIB_NVM_LowVoltageIsDetected and PLIB_NVM_LowVoltageEventIsActive functions support low-voltage error detection and triggering of a Flash memory low-voltage event. Long Write/Erase Cycle Detection The PLIB_NVM_EEPROMNextWriteCycleIsLong function allows the application to know whether the next EEPROM Write/Erase cycle is long. Configuring the Library The library is configured for the supported NVM module when the processor is chosen in the MPLAB X IDE. Building the Library This section list the files that are available in the src folder of the NVM driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. Library Interface a) Flash Memory Configuration and Status Functions Name Description PLIB_NVM_LowVoltageEventIsActive Provides low voltage detection status. PLIB_NVM_LowVoltageIsDetected Provides low voltage error detection status. PLIB_NVM_MemoryModifyEnable Allows write cycles to Flash memory. PLIB_NVM_MemoryModifyInhibit Inhibits write cycles to Flash memory. PLIB_NVM_MemoryOperationSelect Selects the operation to be performed on Flash memory. b) Flash Memory Operation Functions Name Description PLIB_NVM_DataBlockSourceAddress Takes the address parameter in the argument and loads the base address from which data has to be copied into Flash memory. PLIB_NVM_FlashAddressToModify Modifies the Flash memory address. PLIB_NVM_FlashEraseStart Performs erase operation on the selected Flash memory area. PLIB_NVM_FlashProvideData Provides the data to be written into Flash memory. PLIB_NVM_FlashProvideQuadData Provides the quad data to be written into Flash memory. PLIB_NVM_FlashRead Read the specified address of Flash memory. PLIB_NVM_FlashWriteKeySequence Copies the mandatory KEY sequence into the respective registers. PLIB_NVM_FlashWriteStart Performs a write operation on the Flash memory row selected. PLIB_NVM_FlashWriteCycleHasCompleted Provides the status of the Flash write cycle. PLIB_NVM_WriteOperationHasTerminated Provides the status of the Flash write operation or sequence. c) Other Flash Memory Functions Name Description PLIB_NVM_FlashSwapLockSelect Selects the kind of Flash swap lock required. PLIB_NVM_FlashSwapLockStatusGet Get the status of Swap lock bits. PLIB_NVM_FlashWriteProtectMemoryAreaRange Sets the address below which physical memory will be write protected. PLIB_NVM_BootPageWriteProtectionDisable Write protection for selected boot page is disabled. PLIB_NVM_BootPageWriteProtectionEnable Locks the selected boot page. PLIB_NVM_IsBootMemoryLocked Provides lock status of boot page write-protect bits. PLIB_NVM_IsBootPageWriteProtected Provides write protection status for boot memory page. PLIB_NVM_IsProgramFlashMemoryLocked Provides lock status of Program Flash Write-Protect register. PLIB_NVM_LockBootMemory Locks the boot write-protect bits. PLIB_NVM_LockProgramFlashMemory Lock the Program Flash write-protect register. PLIB_NVM_ProgramFlashBank1LowerRegion Maps Flash Bank 1 to the lower mapped region. PLIB_NVM_ProgramFlashBank2LowerRegion Maps the bank 2 to lower mapped region. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1211 PLIB_NVM_ProgramFlashBank2IsLowerRegion Gives the status of Program Flash Bank mapping. PLIB_NVM_BootFlashBank1LowerRegion Maps Boot Flash Bank 1 to lower mapped region. PLIB_NVM_BootFlashBank2IsLowerRegion Gives the status of Boot Flash Bank mapping. PLIB_NVM_BootFlashBank2LowerRegion Maps Boot Flash Bank 2 to the lower mapped region. d) EEPROM Configuration and Status Functions Name Description PLIB_NVM_EEPROMEnable Enables the EEPROM memory. PLIB_NVM_EEPROMDisable Disables the EEPROM memory. PLIB_NVM_EEPROMIsReady Provides the availability status of the EEPROM. PLIB_NVM_EEPROMStopInIdleEnable Discontinues EEPROM operation when device enters Idle mode. PLIB_NVM_EEPROMStopInIdleDisable Continues EEPROM operation when device enters Idle mode. PLIB_NVM_EEPROMStopInIdleIsEnabled Returns Stop in Idle mode status of the EEPROM operation. PLIB_NVM_EEPROMOperationSelect Selects the operation to be performed on the EEPROM. PLIB_NVM_EEPROMWriteEnable Allows write or erase operation to the EEPROM. PLIB_NVM_EEPROMReadEnable Allows read operation to the EEPROM. PLIB_NVM_EEPROMWriteIsEnabled Returns EEPROM Write permission status. PLIB_NVM_EEPROMReadIsEnabled Returns EEPROM read permission status. PLIB_NVM_EEPROMNextWriteCycleIsLong Informs whether the next write or erase cycle of the EEPROM is long. PLIB_NVM_EEPROMErrorGet Returns the EEPROM operation error. PLIB_NVM_EEPROMErrorClear Clears the EEPROM operation error. e) EEPROM Operation Functions Name Description PLIB_NVM_EEPROMAddress EEPROM address where operation has to be performed. PLIB_NVM_EEPROMDataToWrite Accepts the data to be written into the EEPROM. PLIB_NVM_EEPROMKeySequenceWrite Write mandatory KEY sequence to unlock the EEPROM write or erase protection. PLIB_NVM_EEPROMEraseStart Initiates EEPROM erase cycle. PLIB_NVM_EEPROMWriteStart Initiates a EEPROM write cycle. PLIB_NVM_EEPROMReadStart Initiates a EEPROM read cycle. PLIB_NVM_EEPROMOperationHasCompleted Provides the status of the EEPROM write or erase or read cycle. PLIB_NVM_EEPROMRead Read the EEPROM data. PLIB_NVM_EEPROMOperationAbort Aborts the current EEPROM operation. f) Feature Existence Functions Name Description PLIB_NVM_ExistsAddressModifyControl Identifies whether the AddressModifyControl feature exists on the NVM module. PLIB_NVM_ExistsBootPageWriteProtect Identifies whether the BootPageWriteProtect feature exists on the NVM module. PLIB_NVM_ExistsFlashBankRegionSelect Identifies whether the FlashBankRegionSelect feature exists on the NVM module. PLIB_NVM_ExistsFlashWPMemoryRangeProvide Identifies whether the FlashWPMemoryRangeProvide feature exists on the NVM module. PLIB_NVM_ExistsKeySequence Identifies whether the KeySequence feature exists on the NVM module. PLIB_NVM_ExistsLockBootSelect Identifies whether the LockBootSelect feature exists on the NVM module. PLIB_NVM_ExistsLockPFMSelect Identifies whether the LockPFMSelect feature exists on the NVM module. PLIB_NVM_ExistsLowVoltageError Identifies whether the LowVoltageError feature exists on the NVM module. PLIB_NVM_ExistsLowVoltageStatus Identifies whether the LowVoltageStatus feature exists on the NVM module. PLIB_NVM_ExistsMemoryModificationControl Identifies whether the MemoryModificationControl feature exists on the NVM module. PLIB_NVM_ExistsOperationMode Identifies whether the OperationMode feature exists on the NVM module. PLIB_NVM_ExistsProvideData Identifies whether the ProvideData feature exists on the NVM module. PLIB_NVM_ExistsProvideQuadData Identifies whether the ProvideQuadData feature exists on the NVM module. PLIB_NVM_ExistsSourceAddress Identifies whether the SourceAddress feature exists on the NVM module. PLIB_NVM_ExistsWriteErrorStatus Identifies whether the WriteErrorStatus feature exists on the NVM module. PLIB_NVM_ExistsWriteOperation Identifies whether the WriteOperation feature exists on the NVM module. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1212 PLIB_NVM_ExistsBootFlashBankRegion Identifies whether the BootFlashBankRegion feature exists on the NVM module. PLIB_NVM_ExistsSwapLockControl Identifies whether the SwapLockControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMAddressControl Identifies whether the EEPROMAddressControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMDataControl Identifies whether the EEPROMDataControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMEnableControl Identifies whether the EEPROMEnableControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMEnableOperationControl Identifies whether the EEPROMEnableOperationControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMErrorStatus Identifies whether the EEPROMErrorStatus feature exists on the NVM module. PLIB_NVM_ExistsEEPROMKeySequence Identifies whether the EEPROMKeySequence feature exists on the NVM module. PLIB_NVM_ExistsEEPROMLongWriteStatus Identifies whether the EEPROMLongWriteStatus feature exists on the NVM module. PLIB_NVM_ExistsEEPROMOperationAbortControl Identifies whether the EEPROMOperationAbortControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMOperationModeControl Identifies whether the EEPROMOperationModeControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMStartOperationControl Identifies whether the EEPROMStartOperationControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMStopInIdleControl Identifies whether the EEPROMStopInIdleControl feature exists on the NVM module. g) Data Types and Constants Name Description NVM_BOOT_MEMORY_AREA Lists the different possible boot memory region. NVM_BOOT_MEMORY_PAGE Lists the different NVM boot memory pages. NVM_OPERATION_MODE Lists the different Flash operation modes. NVM_MODULE_ID Possible instances of the NVM module. NVM_FLASH_SWAP_LOCK_TYPE Lists the possible type of Flash swap lock. EEPROM_ERROR Lists the different EEPROM operation errors. EEPROM_OPERATION_MODE Lists the different EEPROM operation modes. Description This section describes the Application Programming Interface (API) functions of the NVM Peripheral Library. Refer to each section for a detailed description. a) Flash Memory Configuration and Status Functions PLIB_NVM_LowVoltageEventIsActive Function Provides low voltage detection status. File plib_nvm.h C bool PLIB_NVM_LowVoltageEventIsActive(NVM_MODULE_ID index); Returns • 1 - Low Voltage Event is active • 0 - Low Voltage Event is not active Description This function provides detection of low voltage event, if any. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1213 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Preconditions None. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_LowVoltageEventIsActive( NVM_MODULE_ID index) PLIB_NVM_LowVoltageIsDetected Function Provides low voltage error detection status. File plib_nvm.h C bool PLIB_NVM_LowVoltageIsDetected(NVM_MODULE_ID index); Returns • 1 - Low Voltage detection and possible data corruption • 0 - Voltage Level Acceptable for programming Description This function provides detection of low voltage error status. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Preconditions None. Example bool status; status = PLIB_NVM_LowVoltageIsDetected(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_LowVoltageIsDetected( NVM_MODULE_ID index) PLIB_NVM_MemoryModifyEnable Function Allows write cycles to Flash memory. File plib_nvm.h Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1214 C void PLIB_NVM_MemoryModifyEnable(NVM_MODULE_ID index); Returns None. Description This function allows changing the write control (WR) bit and disables writing into the SWAP and NVMOP bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsMemoryModificationControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_MemoryModifyEnable(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_MemoryModifyEnable( NVM_MODULE_ID index) PLIB_NVM_MemoryModifyInhibit Function Inhibits write cycles to Flash memory. File plib_nvm.h C void PLIB_NVM_MemoryModifyInhibit(NVM_MODULE_ID index); Returns None. Description This function disables the writing in the write control (WR) bit and enables writing into the SWAP and NVMOP bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsMemoryModificationControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_MemoryModifyInhibit(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_MemoryModifyInhibit( NVM_MODULE_ID index) Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1215 PLIB_NVM_MemoryOperationSelect Function Selects the operation to be performed on Flash memory. File plib_nvm.h C void PLIB_NVM_MemoryOperationSelect(NVM_MODULE_ID index, NVM_OPERATION_MODE operationmode); Returns None. Description This function selects the operation to be performed on Flash memory. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsOperationMode in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_MemoryOperationSelect(MY_NVM_INSTANCE, NVM_MEMORY_ROW_PROGRAM_OPERATION); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_MemoryOperationSelect( NVM_MODULE_ID index, NVM_OPERATION_TYPE_SELECT operationmode) b) Flash Memory Operation Functions PLIB_NVM_DataBlockSourceAddress Function Takes the address parameter in the argument and loads the base address from which data has to be copied into Flash memory. File plib_nvm.h C void PLIB_NVM_DataBlockSourceAddress(NVM_MODULE_ID index, uint32_t address); Returns None. Description This function takes the address parameter in the argument and loads the base address from which data has to be copied into Flash memory. This is to copy a row of data directly into Flash in one iteration without handling any intermediate holding registers. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsSourceAddress in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1216 Example uint32_t address = MY_RAM_BASE_ADDRESS; PLIB_NVM_DataBlockSourceAddress(MY_NVM_INSTANCE, address); Parameters Parameters Description index Identifier for the device instance to be configured address The starting address in the user data memory from which data will be written Function void PLIB_NVM_DataBlockSourceAddress( NVM_MODULE_ID index, uint32_t address) PLIB_NVM_FlashAddressToModify Function Modifies the Flash memory address. File plib_nvm.h C void PLIB_NVM_FlashAddressToModify(NVM_MODULE_ID index, uint32_t address); Returns None. Description This function takes the address parameter in the argument and loads the address that will be modified by the actual write operation. The write or erase operation following this will write or erase the user data into or from the Flash program memory. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsAddressModifyControl in your application to determine whether this feature is available. Preconditions None. Example uint32_t address = MY_FLASH_BASE_ADDRESS; PLIB_NVM_FlashAddressToModify(MY_NVM_INSTANCE, address); Parameters Parameters Description index Identifier for the device instance to be configured address The starting address in the memory from which data will be written. This address should be a physical address. Function void PLIB_NVM_FlashAddressToModify( NVM_MODULE_ID index, uint32_t address) PLIB_NVM_FlashEraseStart Function Performs erase operation on the selected Flash memory area. File plib_nvm.h C void PLIB_NVM_FlashEraseStart(NVM_MODULE_ID index); Returns None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1217 Description This function Performs erase operation on the selected Flash memory region. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteOperation in your application to determine whether this feature is available. Preconditions • The Address of the page to be erased must be provided using PLIB_NVM_FlashAddressToModify • Erase Operation should be selected using PLIB_NVM_MemoryOperationSelect • The module should be configured to access Flash memory using PLIB_NVM_MemoryModifyEnable • The unlock key sequence should be provided using PLIB_NVM_FlashWriteKeySequence Example PLIB_NVM_FlashEraseStart(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_FlashEraseStart( NVM_MODULE_ID index) PLIB_NVM_FlashProvideData Function Provides the data to be written into Flash memory. File plib_nvm.h C void PLIB_NVM_FlashProvideData(NVM_MODULE_ID index, uint32_t data); Returns None. Description This function provides the user data to intermediate registers before being written into Flash memory. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsProvideData in your application to determine whether this feature is available. Preconditions None. Example uint32_t DataToWrite; PLIB_NVM_FlashProvideData(MY_NVM_INSTANCE, DataToWrite); Parameters Parameters Description index Identifier for the device instance to be configured data Data to be written Function void PLIB_NVM_FlashProvideData( NVM_MODULE_ID index, uint32_t data) Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1218 PLIB_NVM_FlashProvideQuadData Function Provides the quad data to be written into Flash memory. File plib_nvm.h C void PLIB_NVM_FlashProvideQuadData(NVM_MODULE_ID index, uint32_t * data); Returns None. Description This function provides the user quad data to intermediate registers before being written into Flash memory. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsProvideQuadData in your application to determine whether this feature is available. Preconditions None. Example uint32_t DataToWrite[4]; PLIB_NVM_FlashProvideQuadData(MY_NVM_INSTANCE, &DataToWrite); Parameters Parameters Description index Identifier for the device instance to be configured data Address pointing to the data to be written. Function void PLIB_NVM_FlashProvideQuadData( NVM_MODULE_ID index, uint32_t *data); PLIB_NVM_FlashRead Function Read the specified address of Flash memory. File plib_nvm.h C uint32_t PLIB_NVM_FlashRead(NVM_MODULE_ID index, uint32_t address); Returns Data value read at the memory address. Description This function takes the address parameter in the argument and loads the read address to the appropriate register. The read operation provides data from the given address. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteOperation in your application to determine whether this feature is available. Preconditions None. Example uint32_t DataToBeRead; Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1219 DataToBeRead = PLIB_NVM_FlashRead(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured address The address in the memory from which to read Function uint32_t PLIB_NVM_FlashRead( NVM_MODULE_ID index, uint32_t address) PLIB_NVM_FlashWriteKeySequence Function Copies the mandatory KEY sequence into the respective registers. File plib_nvm.h C void PLIB_NVM_FlashWriteKeySequence(NVM_MODULE_ID index, uint32_t keysequence); Returns None. Description This function copies the mandatory KEY sequence into the respective registers. Remarks Without the KEY sequence write or erase operation will not be executed. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsKeySequence in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_FlashWriteKeySequence(MY_NVM_INSTANCE, keysequence); Parameters Parameters Description index Identifier for the device instance to be configured keysequence Mandatory KEY sequence depending on the controller type Function void PLIB_NVM_FlashWriteKeySequence( NVM_MODULE_ID index, uint32_t keysequence) PLIB_NVM_FlashWriteStart Function Performs a write operation on the Flash memory row selected. File plib_nvm.h C void PLIB_NVM_FlashWriteStart(NVM_MODULE_ID index); Returns None. Description This function performs a write operation on the Flash memory row selected. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1220 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteOperation in your application to determine whether this feature is available. Preconditions • The Address of the page to be written must be provided using PLIB_NVM_FlashAddressToModify • Erase Operation should be selected using PLIB_NVM_MemoryOperationSelect • The module should be configured to access Flash memory using PLIB_NVM_MemoryModifyEnable • The unlock key sequence should be provided using PLIB_NVM_FlashWriteKeySequence Example PLIB_NVM_FlashWriteStart(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_FlashWriteStart( NVM_MODULE_ID index) PLIB_NVM_FlashWriteCycleHasCompleted Function Provides the status of the Flash write cycle. File plib_nvm.h C bool PLIB_NVM_FlashWriteCycleHasCompleted(NVM_MODULE_ID index); Returns • 0 - Write or erase cycle is incomplete • 1 - Write or erase cycle has completed Description This function provides the status of the Flash write cycle that was initiated by a write or erase operation. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteOperation in your application to determine whether this feature is available. Preconditions None. Example bool status; status = PLIB_NVM_FlashWriteCycleHasCompleted(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_FlashWriteCycleHasCompleted( NVM_MODULE_ID index) PLIB_NVM_WriteOperationHasTerminated Function Provides the status of the Flash write operation or sequence. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1221 File plib_nvm.h C bool PLIB_NVM_WriteOperationHasTerminated(NVM_MODULE_ID index); Returns • 1 - Write operation prematurely terminated • 0 - Write operation completed Description This function provides the status of the Flash write operation or sequence that was initiated by a write or erase operation. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteErrorStatus in your application to determine whether this feature is available. Preconditions None. Example bool status; status = PLIB_NVM_WriteOperationHasTerminated(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_WriteOperationHasTerminated( NVM_MODULE_ID index) c) Other Flash Memory Functions PLIB_NVM_FlashSwapLockSelect Function Selects the kind of Flash swap lock required. File plib_nvm.h C void PLIB_NVM_FlashSwapLockSelect(NVM_MODULE_ID index, NVM_FLASH_SWAP_LOCK_TYPE lockType); Returns None. Description This function allows user to select which swap bits will be writable. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsSwapLockControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_FlashSwapLockSelect(MY_NVM_INSTANCE, NVM_FLASH_SWAP_UNLOCKED); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1222 Parameters Parameters Description index Identifier for the device instance to be configured lockType One of the value from NVM_FLASH_SWAP_LOCK_TYPE enum to identify which swap bit will be locked Function void PLIB_NVM_FlashSwapLockSelect ( NVM_MODULE_ID index, NVM_FLASH_SWAP_LOCK_TYPE lockType ) PLIB_NVM_FlashSwapLockStatusGet Function Get the status of Swap lock bits. File plib_nvm.h C NVM_FLASH_SWAP_LOCK_TYPE PLIB_NVM_FlashSwapLockStatusGet(NVM_MODULE_ID index); Returns • NVM_FLASH_SWAP_LOCK_TYPE - The lock status of Flash swap bits. Description This function allows user to get the status of swap lock bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsSwapLockControl in your application to determine whether this feature is available. Preconditions None. Example NVM_FLASH_SWAP_LOCK_TYPE lockStatus; lockStatus = PLIB_NVM_FlashSwapLockStatusGet(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured. Function NVM_FLASH_SWAP_LOCK_TYPE PLIB_NVM_FlashSwapLockStatusGet ( NVM_MODULE_ID index ) PLIB_NVM_FlashWriteProtectMemoryAreaRange Function Sets the address below which physical memory will be write protected. File plib_nvm.h C void PLIB_NVM_FlashWriteProtectMemoryAreaRange(NVM_MODULE_ID index, uint32_t address); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1223 Returns None. Description This function sets the address below which physical memory will be protected. Physical memory below address 0x1Dxxxxxx is write protected, where 'xxxxxx' is specified by "address" parameter. When "address" has a value of '0', write protection is disabled for the entire program Flash. If the specified address falls within the page, the entire page and all pages below the current page will be protected. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsFlashWPMemoryRangeProvide in your application to determine whether this feature is available. Preconditions The unlock key sequence should be provided using PLIB_NVM_FlashWriteKeySequence. Example PLIB_NVM_FlashWriteProtectMemoryAreaRange(MY_NVM_INSTANCE, WRITE_PROTECT_PAGE_ADDRESS); Parameters Parameters Description index Identifier for the device instance to be configured address Flash program write-protect (Page) address Function void PLIB_NVM_FlashWriteProtectMemoryAreaRange( NVM_MODULE_ID index, uint32_t address); PLIB_NVM_BootPageWriteProtectionDisable Function Write protection for selected boot page is disabled. File plib_nvm.h C void PLIB_NVM_BootPageWriteProtectionDisable(NVM_MODULE_ID index, NVM_BOOT_MEMORY_PAGE bootPage); Returns None. Description This function disables Write protection for selected boot page. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsBootPageWriteProtect in your application to determine whether this feature is available. Preconditions Unlock key sequence should be provided using API PLIB_NVM_FlashWriteKeySequence. Example PLIB_NVM_BootPageWriteProtectionDisable(MY_NVM_INSTANCE, LOWER_BOOT_ALIAS_PAGE4); Parameters Parameters Description index Identifier for the device instance to be configured bootPage Selects the boot page for which write protection has to be disabled Function void PLIB_NVM_BootPageWriteProtectionDisable( NVM_MODULE_ID index, NVM_BOOT_MEMORY_PAGE bootPage); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1224 PLIB_NVM_BootPageWriteProtectionEnable Function Locks the selected boot page. File plib_nvm.h C void PLIB_NVM_BootPageWriteProtectionEnable(NVM_MODULE_ID index, NVM_BOOT_MEMORY_PAGE bootPage); Returns None. Description This function locks the selected boot page. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsBootPageWriteProtect in your application to determine whether this feature is available. Preconditions Unlock key sequence should be provided using API PLIB_NVM_FlashWriteKeySequence. Example PLIB_NVM_BootPageWriteProtectionEnable(MY_NVM_INSTANCE, LOWER_BOOT_ALIAS_PAGE4); Parameters Parameters Description index Identifier for the device instance to be configured bootPage Selects the boot page which has to be locked Function void PLIB_NVM_BootPageWriteProtectionEnable( NVM_MODULE_ID index, NVM_BOOT_MEMORY_PAGE bootPage); PLIB_NVM_IsBootMemoryLocked Function Provides lock status of boot page write-protect bits. File plib_nvm.h C bool PLIB_NVM_IsBootMemoryLocked(NVM_MODULE_ID index, NVM_BOOT_MEMORY_AREA memoryArea); Returns • 1 - Selected boot alias write-protect bits are locked • 0 - Selected boot alias write-protect bits are not locked Description This function provides lock status of boot page write-protect bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLockBootSelect in your application to determine whether this feature is available. Preconditions None. Example bool status; status = PLIB_NVM_IsBootMemoryLocked(MY_NVM_INSTANCE, LOWER_BOOT_ALIAS_AREA); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1225 Parameters Parameters Description index Identifier for the device instance to be configured memoryArea Selects between the Lower or Upper Boot Alias area Function bool PLIB_NVM_IsBootMemoryLocked( NVM_MODULE_ID index, NVM_BOOT_MEMORY_AREA memoryArea); PLIB_NVM_IsBootPageWriteProtected Function Provides write protection status for boot memory page. File plib_nvm.h C bool PLIB_NVM_IsBootPageWriteProtected(NVM_MODULE_ID index, NVM_BOOT_MEMORY_PAGE bootPage); Returns • 1 - Selected boot region is write protected • 0 - Selected boot region is not write protected Description This function provides write protection status for selected boot memory page. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsBootPageWriteProtect in your application to determine whether this feature is available. Preconditions None. Example bool status; status = PLIB_NVM_IsBootPageWriteProtected(MY_NVM_INSTANCE, LOWER_BOOT_ALIAS_PAGE4); Parameters Parameters Description index Identifier for the device instance to be configured bootPage Selects the boot page region Function bool PLIB_NVM_IsBootPageWriteProtected( NVM_MODULE_ID index, NVM_BOOT_MEMORY_PAGE bootPage); PLIB_NVM_IsProgramFlashMemoryLocked Function Provides lock status of Program Flash Write-Protect register. File plib_nvm.h C bool PLIB_NVM_IsProgramFlashMemoryLocked(NVM_MODULE_ID index); Returns • 1 - Program Flash write-protect register is locked • 0 - Program Flash write-protect register is not locked Description This function provides lock status of Program Flash Write-Protect (NVMPWP) register. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1226 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLockPFMSelect in your application to determine whether this feature is available. Preconditions None. Example bool status; status = PLIB_NVM_IsProgramFlashMemoryLocked(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_IsProgramFlashMemoryLocked( NVM_MODULE_ID index); PLIB_NVM_LockBootMemory Function Locks the boot write-protect bits. File plib_nvm.h C void PLIB_NVM_LockBootMemory(NVM_MODULE_ID index, NVM_BOOT_MEMORY_AREA memoryArea); Returns None. Description This function locks the given (lower or upper alias) boot write-protect bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLockBootSelect in your application to determine whether this feature is available. Preconditions The unlock key sequence should be provided using PLIB_NVM_FlashWriteKeySequence. Example PLIB_NVM_LockBootMemory(MY_NVM_INSTANCE, LOWER_BOOT_ALIAS_AREA); Parameters Parameters Description index Identifier for the device instance to be configured memoryArea Selects between Lower or Upper Boot Alias area Function void PLIB_NVM_LockBootMemory( NVM_MODULE_ID index, NVM_BOOT_MEMORY_AREA memoryArea); PLIB_NVM_LockProgramFlashMemory Function Lock the Program Flash write-protect register. File plib_nvm.h C void PLIB_NVM_LockProgramFlashMemory(NVM_MODULE_ID index); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1227 Returns None. Description This function locks the Program Flash Write-Protect register (NVMPWP). Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLockPFMSelect in your application to determine whether this feature is available. Preconditions Unlock key sequence should be provided using API PLIB_NVM_FlashWriteKeySequence. Example PLIB_NVM_LockProgramFlashMemory(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_LockProgramFlashMemory( NVM_MODULE_ID index); PLIB_NVM_ProgramFlashBank1LowerRegion Function Maps Flash Bank 1 to the lower mapped region. File plib_nvm.h C void PLIB_NVM_ProgramFlashBank1LowerRegion(NVM_MODULE_ID index); Returns None. Description This function maps Program Flash Bank 1 to the lower mapped region and programs Flash Bank 2 to the upper mapped region. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsFlashBankRegionSelect in your application to determine whether this feature is available. Preconditions The WREN bit in the NVMCON register should be set to '0' using PLIB_NVM_MemoryModifyInhibit before swapping the memory regions. Example PLIB_NVM_ProgramFlashBank1LowerRegion(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_ProgramFlashBank1LowerRegion( NVM_MODULE_ID index); PLIB_NVM_ProgramFlashBank2LowerRegion Function Maps the bank 2 to lower mapped region. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1228 File plib_nvm.h C void PLIB_NVM_ProgramFlashBank2LowerRegion(NVM_MODULE_ID index); Returns None. Description This function maps Program Flash Bank 2 to the lower mapped region and Program Flash Bank 1 to the upper mapped region. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsFlashBankRegionSelect in your application to determine whether this feature is available. Preconditions The WREN bit in the NVMCON register should be set to '0' using PLIB_NVM_MemoryModifyInhibit before swapping the memory regions. Example PLIB_NVM_ProgramFlashBank2LowerRegion(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_ProgramFlashBank2LowerRegion( NVM_MODULE_ID index); PLIB_NVM_ProgramFlashBank2IsLowerRegion Function Gives the status of Program Flash Bank mapping. File plib_nvm.h C bool PLIB_NVM_ProgramFlashBank2IsLowerRegion(NVM_MODULE_ID index); Returns • 1 - Program Flash Bank 2 is mapped to the lower mapped region and Program Flash Bank 1 is mapped to the upper mapped region • 0 - Program Flash Bank 1 is mapped to the lower mapped region and Program Flash Bank 2 is mapped to the upper mapped region Description This function tells which Program Flash Bank is mapped to which region. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsFlashBankRegionSelect in your application to determine whether this feature is available. Preconditions None. Example if(!PLIB_NVM_ProgramFlashBank2IsLowerRegion(MY_NVM_INSTANCE)) PLIB_NVM_ProgramFlashBank2LowerRegion(NVM_MODULE_ID index); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1229 Function bool PLIB_NVM_ProgramFlashBank2IsLowerRegion( NVM_MODULE_ID index); PLIB_NVM_BootFlashBank1LowerRegion Function Maps Boot Flash Bank 1 to lower mapped region. File plib_nvm.h C void PLIB_NVM_BootFlashBank1LowerRegion(NVM_MODULE_ID index); Returns None. Description This function maps Boot Flash Bank 1 to the lower mapped region and Boot Flash Bank 2 to the upper mapped region. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsBootFlashBankRegion in your application to determine whether this feature is available. Preconditions The WREN bit in the NVMCON register should be set to '0' using PLIB_NVM_MemoryModifyInhibit before swapping the memory regions. Example PLIB_NVM_BootFlashBank1LowerRegion(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_BootFlashBank1LowerRegion( NVM_MODULE_ID index); PLIB_NVM_BootFlashBank2IsLowerRegion Function Gives the status of Boot Flash Bank mapping. File plib_nvm.h C bool PLIB_NVM_BootFlashBank2IsLowerRegion(NVM_MODULE_ID index); Returns • 1 - Boot Flash Bank 2 is mapped to the lower mapped region and Boot Flash Bank 1 is mapped to the upper mapped region • 0 - Boot Flash Bank 1 is mapped to the lower mapped region and Boot Flash Bank 2 is mapped to the upper mapped region Description This function tells which Boot Flash Bank is mapped to which region. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsBootFlashBankRegion in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1230 Example if(!PLIB_NVM_BootFlashBank2IsLowerRegion(MY_NVM_INSTANCE)) PLIB_NVM_BootFlashBank2LowerRegion(NVM_MODULE_ID index); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_BootFlashBank2IsLowerRegion( NVM_MODULE_ID index); PLIB_NVM_BootFlashBank2LowerRegion Function Maps Boot Flash Bank 2 to the lower mapped region. File plib_nvm.h C void PLIB_NVM_BootFlashBank2LowerRegion(NVM_MODULE_ID index); Returns None. Description This function maps Boot Flash Bank 2 to the lower mapped region and Boot Flash Bank 1 to the upper mapped region. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsBootFlashBankRegion in your application to determine whether this feature is available. Preconditions The WREN bit in the NVMCON register should be set to '0' using PLIB_NVM_MemoryModifyInhibit before swapping the memory regions. Example PLIB_NVM_BootFlashBank2LowerRegion(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_BootFlashBank2LowerRegion( NVM_MODULE_ID index); d) EEPROM Configuration and Status Functions PLIB_NVM_EEPROMEnable Function Enables the EEPROM memory. File plib_nvm.h C void PLIB_NVM_EEPROMEnable(NVM_MODULE_ID index); Returns None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1231 Description This function enables the EEPROM memory for access. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMEnableControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_EEPROMEnable(MY_NVM_INSTANCE); if(PLIB_NVM_EEPROMIsReady(MY_NVM_INSTANCE)) { //Perform operation } Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMEnable( NVM_MODULE_ID index ) PLIB_NVM_EEPROMDisable Function Disables the EEPROM memory. File plib_nvm.h C void PLIB_NVM_EEPROMDisable(NVM_MODULE_ID index); Returns None. Description This function disables EEPROM memory access. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMEnableControl in your application to determine whether this feature is available. Preconditions This API will have no affect if there is any ongoing EEPROM operation. Example if(PLIB_NVM_EEPROMOperationHasCompleted) { PLIB_NVM_EEPROMDisable(MY_NVM_INSTANCE); } Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMDisable( NVM_MODULE_ID index ) Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1232 PLIB_NVM_EEPROMIsReady Function Provides the availability status of the EEPROM. File plib_nvm.h C bool PLIB_NVM_EEPROMIsReady(NVM_MODULE_ID index); Returns • true - EEPROM is ready to use • false - EEPROM is not yet ready to use Description This function provides the ready status of the EEPROM which was initiated by PLIB_NVM_EEPROMEnable. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMEnableControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_EEPROMEnable(MY_NVM_INSTANCE); if(PLIB_NVM_EEPROMIsReady(MY_NVM_INSTANCE)) { //Perform operation } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_EEPROMIsReady( NVM_MODULE_ID index ) PLIB_NVM_EEPROMStopInIdleEnable Function Discontinues EEPROM operation when device enters Idle mode. File plib_nvm.h C void PLIB_NVM_EEPROMStopInIdleEnable(NVM_MODULE_ID index); Returns None. Description This function discontinues EEPROM operation when device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMStopInIdleControl in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1233 Example PLIB_NVM_EEPROMStopInIdleEnable(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMStopInIdleEnable( NVM_MODULE_ID index ) PLIB_NVM_EEPROMStopInIdleDisable Function Continues EEPROM operation when device enters Idle mode. File plib_nvm.h C void PLIB_NVM_EEPROMStopInIdleDisable(NVM_MODULE_ID index); Returns None. Description This function continues EEPROM operation when device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMStopInIdleControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_EEPROMStopInIdleDisable(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMStopInIdleDisable( NVM_MODULE_ID index ) PLIB_NVM_EEPROMStopInIdleIsEnabled Function Returns Stop in Idle mode status of the EEPROM operation. File plib_nvm.h C bool PLIB_NVM_EEPROMStopInIdleIsEnabled(NVM_MODULE_ID index); Returns • true - EEPROM discontinues operation when the device enters Idle mode • false - EEPROM continues operation when the device enters Idle mode Description This function returns whether the EEPROM continues or discontinues operation when the device enters Idle mode. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1234 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMStopInIdleControl in your application to determine whether this feature is available. Preconditions None. Example bool sidl_status; sidl_status = PLIB_NVM_EEPROMStopInIdleIsEnabled(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_EEPROMStopInIdleIsEnabled( NVM_MODULE_ID index ) PLIB_NVM_EEPROMOperationSelect Function Selects the operation to be performed on the EEPROM. File plib_nvm.h C void PLIB_NVM_EEPROMOperationSelect(NVM_MODULE_ID index, EEPROM_OPERATION_MODE mode); Returns None. Description This function selects the operation to be performed on the EEPROM from the set of operations available from the enum EEPROM_OPERATION_MODE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMOperationModeControl in your application to determine whether this feature is available. Preconditions This API will have no affect if there is any ongoing EEPROM operation. Example PLIB_NVM_EEPROMOperationSelect(MY_NVM_INSTANCE, EEPROM_WORD_READ_OPERATION); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMOperationSelect( NVM_MODULE_ID index , EEPROM_OPERATION_MODE mode) PLIB_NVM_EEPROMWriteEnable Function Allows write or erase operation to the EEPROM. File plib_nvm.h C void PLIB_NVM_EEPROMWriteEnable(NVM_MODULE_ID index); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1235 Returns None. Description This function enables write or erase operations on the EEPROM and inhibits read. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMEnableOperationControl in your application to determine whether this feature is available. Preconditions This API will have no affect if there is any ongoing EEPROM operation. Example PLIB_NVM_EEPROMWriteEnable(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMWriteEnable( NVM_MODULE_ID index ) PLIB_NVM_EEPROMReadEnable Function Allows read operation to the EEPROM. File plib_nvm.h C void PLIB_NVM_EEPROMReadEnable(NVM_MODULE_ID index); Returns None. Description This function enables read operations on the EEPROM and inhibits write or erase. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMEnableOperationControl in your application to determine whether this feature is available. Preconditions This API will have no affect if there is any ongoing EEPROM operation. Example PLIB_NVM_EEPROMReadEnable(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMReadEnable( NVM_MODULE_ID index ) PLIB_NVM_EEPROMWriteIsEnabled Function Returns EEPROM Write permission status. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1236 File plib_nvm.h C bool PLIB_NVM_EEPROMWriteIsEnabled(NVM_MODULE_ID index); Returns • true - EEPROM write or erase is enabled • false - EEPROM write or erase is not enabled Description This function returns whether or not the EEPROM write or erase. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMEnableOperationControl in your application to determine whether this feature is available. Preconditions This API will have no affect if there is any ongoing EEPROM operation. Example if(PLIB_NVM_EEPROMWriteIsEnabled(MY_NVM_INSTANCE)) { //perform write or erase } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_EEPROMWriteIsEnabled( NVM_MODULE_ID index ) PLIB_NVM_EEPROMReadIsEnabled Function Returns EEPROM read permission status. File plib_nvm.h C bool PLIB_NVM_EEPROMReadIsEnabled(NVM_MODULE_ID index); Returns • true - EEPROM read is enabled. • false - EEPROM read is not enabled. Description This function returns whether or not the EEPROM read is enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMEnableOperationControl in your application to determine whether this feature is available. Preconditions This API will have no affect if there is any ongoing EEPROM operation. Example if(PLIB_NVM_EEPROMReadIsEnabled(MY_NVM_INSTANCE)) { //perform read } Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1237 Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_EEPROMReadIsEnabled( NVM_MODULE_ID index ) PLIB_NVM_EEPROMNextWriteCycleIsLong Function Informs whether the next write or erase cycle of the EEPROM is long. File plib_nvm.h C bool PLIB_NVM_EEPROMNextWriteCycleIsLong(NVM_MODULE_ID index); Returns false - Next write/Erase cycle will not take more time to complete. true - Next write/Erase cycle will take more time to complete. Description This function informs whether the next write or erase cycle of the EEPROM is long (i.e., the next write or erase to the EEPROM address (passed by PLIB_NVM_EEPROMAddress) will require more time (~20 ms) than usual). Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMLongWriteStatus in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_NVM_EEPROMNextWriteCycleIsLong( MY_NVM_INSTANCE )) { //stays here for ~20ms, better skip to other task for this time. } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_EEPROMNextWriteCycleIsLong( NVM_MODULE_ID index ) PLIB_NVM_EEPROMErrorGet Function Returns the EEPROM operation error. File plib_nvm.h C EEPROM_ERROR PLIB_NVM_EEPROMErrorGet(NVM_MODULE_ID index); Returns EEPROM_ERROR. Description This function returns the EEPROM operation error. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1238 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMErrorStatus in your application to determine whether this feature is available. Preconditions None. Example EEPROM_ERROR error; error = PLIB_NVM_EEPROMErrorGet(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function EEPROM_ERROR PLIB_NVM_EEPROMErrorGet( NVM_MODULE_ID index ) PLIB_NVM_EEPROMErrorClear Function Clears the EEPROM operation error. File plib_nvm.h C void PLIB_NVM_EEPROMErrorClear(NVM_MODULE_ID index); Returns None. Description This function clears the EEPROM operation error. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMErrorStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_EEPROMErrorClear(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMErrorClear( NVM_MODULE_ID index ) e) EEPROM Operation Functions PLIB_NVM_EEPROMAddress Function EEPROM address where operation has to be performed. File plib_nvm.h Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1239 C bool PLIB_NVM_EEPROMAddress(NVM_MODULE_ID index, uint32_t address); Returns • true - EEPROM address is valid • false - EEPROM address is invalid, please check if it is in the EEPROM address boundary and last two bits are '00' Description This function accepts the EEPROM address upon which to operate. Lower two bits of the address must always be '00'; otherwise, an error will occur when operation is started on EEPROM. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMAddressControl in your application to determine whether this feature is available. Preconditions This API will have no affect if there is any ongoing EEPROM operation. Example uint32_t address = MY_EEPROM_ADDRESS; // Load address and check if it is valid if(true ==PLIB_NVM_EEPROMAddress( NVM_ID_0 , address )) { //Perform operation } Parameters Parameters Description index Identifier for the device instance to be configured address The address of the EEPROM from or to which data will be read or written. This address should be a physical address. Function bool PLIB_NVM_EEPROMAddress( NVM_MODULE_ID index, uint32_t address) PLIB_NVM_EEPROMDataToWrite Function Accepts the data to be written into the EEPROM. File plib_nvm.h C void PLIB_NVM_EEPROMDataToWrite(NVM_MODULE_ID index, uint32_t data); Returns None. Description This function accepts data to be written into the EEPROM. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMDataControl in your application to determine whether this feature is available. Preconditions This API will have no affect if there is any ongoing EEPROM operation. Example PLIB_NVM_EEPROMDataToWrite(MY_NVM_INSTANCE, DATA); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1240 Parameters Parameters Description index Identifier for the device instance to be configured data Data to be written Function void PLIB_NVM_EEPROMDataToWrite ( NVM_MODULE_ID index , uint32_t data ) PLIB_NVM_EEPROMKeySequenceWrite Function Write mandatory KEY sequence to unlock the EEPROM write or erase protection. File plib_nvm.h C void PLIB_NVM_EEPROMKeySequenceWrite(NVM_MODULE_ID index, uint32_t keysequence); Returns None. Description Without the KEY sequence write or erase operation will not be executed. Writing the KEY 0xEDB7 followed by writing the another KEY 0x1248 will unlock the EEPROM control register for write or erase operations. Writing any other value will lock the EEPROM control register. The unlock sequence is not necessary for a read operation. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMKeySequence in your application to determine whether this feature is available. Preconditions Interrupts should be disabled when writing the unlock sequence to the EEKEY register to prevent a disruption of the unlock sequence. Example //EEPROM is locked. uint32_t key1 = 0xEDB7; uint32_t key2 = 0x1248; PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key1); PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key2); //EEPROM is now unlocked. Parameters Parameters Description index Identifier for the device instance to be configured keysequence Mandatory KEY sequence depending on the controller type Function void PLIB_NVM_EEPROMKeySequenceWrite ( NVM_MODULE_ID index , uint32_t keysequence ) PLIB_NVM_EEPROMEraseStart Function Initiates EEPROM erase cycle. File plib_nvm.h C void PLIB_NVM_EEPROMEraseStart(NVM_MODULE_ID index); Returns None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1241 Description This function initiates the EEPROM erase cycle. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMStartOperationControl in your application to determine whether this feature is available. Preconditions PLIB_NVM_EEPROMWriteEnable should be called. Example // Enable write or erase operation PLIB_NVM_EEPROMWriteEnable( NVM_ID_0 ); // unlock PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key1); PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key2); // Start the erase operation PLIB_NVM_EEPROMEraseStart( NVM_MODULE_ID index ); // Wait until erase is complete while (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMEraseStart( NVM_MODULE_ID index) PLIB_NVM_EEPROMWriteStart Function Initiates a EEPROM write cycle. File plib_nvm.h C void PLIB_NVM_EEPROMWriteStart(NVM_MODULE_ID index); Returns None. Description This function initiates the EEPROM write cycle. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMStartOperationControl in your application to determine whether this feature is available. Preconditions EEPROM write should be enabled through PLIB_NVM_EEPROMWriteEnable. Example // Enable write operation PLIB_NVM_EEPROMWriteEnable( NVM_ID_0 ); // Provide data PLIB_NVM_EEPROMDataToWrite ( NVM_ID_0 , ee_data ) ; // unlock PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key1); PLIB_NVM_EEPROMKeySequenceWrite(MY_NVM_INSTANCE, key2); // Start the write operation PLIB_NVM_EEPROMWriteStart( NVM_MODULE_ID index ); // Wait until write is complete while (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1242 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMWriteStart( NVM_MODULE_ID index) PLIB_NVM_EEPROMReadStart Function Initiates a EEPROM read cycle. File plib_nvm.h C void PLIB_NVM_EEPROMReadStart(NVM_MODULE_ID index); Returns None. Description This function initiates the EEPROM read cycle. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMStartOperationControl in your application to determine whether this feature is available. Preconditions EEPROM read should be enabled through PLIB_NVM_EEPROMReadEnable. Example // Enable read operation PLIB_NVM_EEPROMReadEnable( NVM_ID_0 ); // Start the read cycle PLIB_NVM_EEPROMReadStart( NVM_MODULE_ID index ); // Wait until read is complete while (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )); // Read the data ee_data = PLIB_NVM_EEPROMRead( NVM_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMReadStart( NVM_MODULE_ID index) PLIB_NVM_EEPROMOperationHasCompleted Function Provides the status of the EEPROM write or erase or read cycle. File plib_nvm.h C bool PLIB_NVM_EEPROMOperationHasCompleted(NVM_MODULE_ID index); Returns • true - Write or erase cycle has completed • false - Write or erase cycle has not completed Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1243 Description This function provides the status of the EEPROM write or erase or read operation status. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMStartOperationControl in your application to determine whether this feature is available. Preconditions None. Example // Start the erase operation PLIB_NVM_EEPROMEraseStart( NVM_MODULE_ID index ); // Wait until erase is complete while (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_NVM_EEPROMOperationHasCompleted( NVM_MODULE_ID index ) PLIB_NVM_EEPROMRead Function Read the EEPROM data. File plib_nvm.h C uint32_t PLIB_NVM_EEPROMRead(NVM_MODULE_ID index); Returns 32-bit EEPROM data. Description This function returns the EERPOM data that is been fetched by performing the EEPROM read operation sequence. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMDataControl in your application to determine whether this feature is available. Preconditions This API will have no affect if there is any ongoing EEPROM operation, or may return junk data. Example uint32_t EEPROM_Data; // Start the read operation PLIB_NVM_EEPROMReadStart( NVM_MODULE_ID index ); // Wait until read is complete while (PLIB_NVM_EEPROMOperationHasCompleted( NVM_ID_0 )); // Now read the data EEPROM_Data = PLIB_NVM_EEPROMRead( NVM_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_NVM_EEPROMRead( NVM_MODULE_ID index) Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1244 PLIB_NVM_EEPROMOperationAbort Function Aborts the current EEPROM operation. File plib_nvm.h C void PLIB_NVM_EEPROMOperationAbort(NVM_MODULE_ID index); Returns None. Description This function aborts the on-going write or erase operation as soon as possible. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsEEPROMOperationAbortControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_NVM_EEPROMOperationAbort(MY_NVM_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_NVM_EEPROMOperationAbort( NVM_MODULE_ID index ) f) Feature Existence Functions PLIB_NVM_ExistsAddressModifyControl Function Identifies whether the AddressModifyControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsAddressModifyControl(NVM_MODULE_ID index); Returns • true - The AddressModifyControl feature is supported on the device • false - The AddressModifyControl feature is not supported on the device Description This function identifies whether the AddressModifyControl feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_FlashAddressToModify Remarks None. Preconditions None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1245 Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsAddressModifyControl( NVM_MODULE_ID index ) PLIB_NVM_ExistsBootPageWriteProtect Function Identifies whether the BootPageWriteProtect feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsBootPageWriteProtect(NVM_MODULE_ID index); Returns • true - The BootPageWriteProtect feature is supported on the device • false - The BootPageWriteProtect feature is not supported on the device Description This function identifies whether the BootPageWriteProtect feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_BootPageWriteProtectionEnable • PLIB_NVM_BootPageWriteProtectionDisable • PLIB_NVM_IsBootPageWriteProtected Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsBootPageWriteProtect( NVM_MODULE_ID index ) PLIB_NVM_ExistsFlashBankRegionSelect Function Identifies whether the FlashBankRegionSelect feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsFlashBankRegionSelect(NVM_MODULE_ID index); Returns • true - The FlashBankRegionSelect feature is supported on the device • false - The FlashBankRegionSelect feature is not supported on the device Description This function identifies whether the FlashBankRegionSelect feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_ProgramFlashBank1LowerRegion • PLIB_NVM_ProgramFlashBank2LowerRegion Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1246 • PLIB_NVM_ProgramFlashBank2IsLowerRegion Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsFlashBankRegionSelect( NVM_MODULE_ID index ) PLIB_NVM_ExistsFlashWPMemoryRangeProvide Function Identifies whether the FlashWPMemoryRangeProvide feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsFlashWPMemoryRangeProvide(NVM_MODULE_ID index); Returns • true - The FlashWPMemoryRangeProvide feature is supported on the device • false - The FlashWPMemoryRangeProvide feature is not supported on the device Description This function identifies whether the FlashWPMemoryRangeProvide feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_FlashWriteProtectMemoryAreaRange Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsFlashWPMemoryRangeProvide( NVM_MODULE_ID index ) PLIB_NVM_ExistsKeySequence Function Identifies whether the KeySequence feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsKeySequence(NVM_MODULE_ID index); Returns • true - The KeySequence feature is supported on the device • false - The KeySequence feature is not supported on the device Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1247 Description This function identifies whether the KeySequence feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_FlashWriteKeySequence Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsKeySequence( NVM_MODULE_ID index ) PLIB_NVM_ExistsLockBootSelect Function Identifies whether the LockBootSelect feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsLockBootSelect(NVM_MODULE_ID index); Returns • true - The LockBootSelect feature is supported on the device • false - The LockBootSelect feature is not supported on the device Description This function identifies whether the LockBootSelect feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_LockBootMemory • PLIB_NVM_IsBootMemoryLocked Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsLockBootSelect( NVM_MODULE_ID index ) PLIB_NVM_ExistsLockPFMSelect Function Identifies whether the LockPFMSelect feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsLockPFMSelect(NVM_MODULE_ID index); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1248 Returns • true - The LockPFMSelect feature is supported on the device • false - The LockPFMSelect feature is not supported on the device Description This function identifies whether the LockPFMSelect feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_LockProgramFlashMemory • PLIB_NVM_IsProgramFlashMemoryLocked Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsLockPFMSelect( NVM_MODULE_ID index ) PLIB_NVM_ExistsLowVoltageError Function Identifies whether the LowVoltageError feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsLowVoltageError(NVM_MODULE_ID index); Returns • true - The LowVoltageStatus feature is supported on the device • false - The LowVoltageStatus feature is not supported on the device Description This function identifies whether the LowVoltageStatus feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_LowVoltageIsDetected Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsLowVoltageError( NVM_MODULE_ID index ) PLIB_NVM_ExistsLowVoltageStatus Function Identifies whether the LowVoltageStatus feature exists on the NVM module. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1249 File plib_nvm.h C bool PLIB_NVM_ExistsLowVoltageStatus(NVM_MODULE_ID index); Returns • true - The LowVoltageStatus feature is supported on the device • false - The LowVoltageStatus feature is not supported on the device Description This function identifies whether the LowVoltageStatus feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_LowVoltageEventIsActive Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsLowVoltageStatus( NVM_MODULE_ID index ) PLIB_NVM_ExistsMemoryModificationControl Function Identifies whether the MemoryModificationControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsMemoryModificationControl(NVM_MODULE_ID index); Returns • true - The MemoryModificationControl feature is supported on the device • false - The MemoryModificationControl feature is not supported on the device Description This function identifies whether the MemoryModificationControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_MemoryModifyEnable • PLIB_NVM_MemoryModifyInhibit Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsMemoryModificationControl( NVM_MODULE_ID index ) Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1250 PLIB_NVM_ExistsOperationMode Function Identifies whether the OperationMode feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsOperationMode(NVM_MODULE_ID index); Returns • true - The OperationMode feature is supported on the device • false - The OperationMode feature is not supported on the device Description This function identifies whether the OperationMode feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_MemoryOperationSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsOperationMode( NVM_MODULE_ID index ) PLIB_NVM_ExistsProvideData Function Identifies whether the ProvideData feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsProvideData(NVM_MODULE_ID index); Returns • true - The ProvideData feature is supported on the device • false - The ProvideData feature is not supported on the device Description This function identifies whether the ProvideData feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_FlashProvideData Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1251 Function PLIB_NVM_ExistsProvideData( NVM_MODULE_ID index ) PLIB_NVM_ExistsProvideQuadData Function Identifies whether the ProvideQuadData feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsProvideQuadData(NVM_MODULE_ID index); Returns • true - The ProvideQuadData feature is supported on the device • false - The ProvideQuadData feature is not supported on the device Description This function identifies whether the ProvideQuadData feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_FlashProvideQuadData Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsProvideQuadData( NVM_MODULE_ID index ) PLIB_NVM_ExistsSourceAddress Function Identifies whether the SourceAddress feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsSourceAddress(NVM_MODULE_ID index); Returns • true - The SourceAddress feature is supported on the device • false - The SourceAddress feature is not supported on the device Description This function identifies whether the SourceAddress feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_DataBlockSourceAddress Remarks None. Preconditions None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1252 Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsSourceAddress( NVM_MODULE_ID index ) PLIB_NVM_ExistsWriteErrorStatus Function Identifies whether the WriteErrorStatus feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsWriteErrorStatus(NVM_MODULE_ID index); Returns • true - The WriteErrorStatus feature is supported on the device • false - The WriteErrorStatus feature is not supported on the device Description This function identifies whether the WriteErrorStatus feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_WriteOperationHasTerminated Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsWriteErrorStatus( NVM_MODULE_ID index ) PLIB_NVM_ExistsWriteOperation Function Identifies whether the WriteOperation feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsWriteOperation(NVM_MODULE_ID index); Returns • true - The WriteOperation feature is supported on the device • false - The WriteOperation feature is not supported on the device Description This function identifies whether the WriteOperation feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_FlashRead • PLIB_NVM_FlashWriteStart • PLIB_NVM_FlashEraseStart • PLIB_NVM_FlashWriteCycleHasCompleted Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1253 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsWriteOperation( NVM_MODULE_ID index ) PLIB_NVM_ExistsBootFlashBankRegion Function Identifies whether the BootFlashBankRegion feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsBootFlashBankRegion(NVM_MODULE_ID index); Returns • true - The BootFlashBankRegion feature is supported on the device • false - The BootFlashBankRegion feature is not supported on the device Description This function identifies whether the BootFlashBankRegion feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_BootFlashBank1LowerRegion • PLIB_NVM_BootFlashBank2LowerRegion • PLIB_NVM_BootFlashBank2IsLowerRegion Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsBootFlashBankRegion( NVM_MODULE_ID index ) PLIB_NVM_ExistsSwapLockControl Function Identifies whether the SwapLockControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsSwapLockControl(NVM_MODULE_ID index); Returns • true - The SwapLockControl feature is supported on the device • false - The SwapLockControl feature is not supported on the device Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1254 Description This function identifies whether the SwapLockControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_FlashSwapLockSelect • PLIB_NVM_FlashSwapLockStatusGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsSwapLockControl( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMAddressControl Function Identifies whether the EEPROMAddressControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMAddressControl(NVM_MODULE_ID index); Returns • true - The EEPROMAddressControl feature is supported on the device • false - The EEPROMAddressControl feature is not supported on the device Description This function identifies whether the EEPROMAddressControl feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_EEPROMAddress Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMAddressControl( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMDataControl Function Identifies whether the EEPROMDataControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMDataControl(NVM_MODULE_ID index); Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1255 Returns • true - The EEPROMDataControl feature is supported on the device • false - The EEPROMDataControl feature is not supported on the device Description This function identifies whether the EEPROMDataControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_EEPROMDataToWrite • PLIB_NVM_EEPROMRead Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMDataControl( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMEnableControl Function Identifies whether the EEPROMEnableControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMEnableControl(NVM_MODULE_ID index); Returns • true - The EEPROMEnableControl feature is supported on the device • false - The EEPROMEnableControl feature is not supported on the device Description This function identifies whether the EEPROMEnableControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_EEPROMEnable • PLIB_NVM_EEPROMDisable • PLIB_NVM_EEPROMIsReady Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMEnableControl( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMEnableOperationControl Function Identifies whether the EEPROMEnableOperationControl feature exists on the NVM module. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1256 File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMEnableOperationControl(NVM_MODULE_ID index); Returns • true - The EEPROMEnableOperationControl feature is supported on the device • false - The EEPROMEnableOperationControl feature is not supported on the device Description This function identifies whether the EEPROMEnableOperationControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_EEPROMWriteEnable • PLIB_NVM_EEPROMWriteIsEnabled • PLIB_NVM_EEPROMReadEnable • PLIB_NVM_EEPROMReadIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMEnableOperationControl( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMErrorStatus Function Identifies whether the EEPROMErrorStatus feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMErrorStatus(NVM_MODULE_ID index); Returns • true - The EEPROMErrorStatus feature is supported on the device • false - The EEPROMErrorStatus feature is not supported on the device Description This function identifies whether the EEPROMErrorStatus feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_EEPROMErrorGet • PLIB_NVM_EEPROMErrorClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1257 Function PLIB_NVM_ExistsEEPROMErrorStatus( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMKeySequence Function Identifies whether the EEPROMKeySequence feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMKeySequence(NVM_MODULE_ID index); Returns • true - The EEPROMKeySequence feature is supported on the device • false - The EEPROMKeySequence feature is not supported on the device Description This function identifies whether the EEPROMKeySequence feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_EEPROMKeySequenceWrite Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMKeySequence( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMLongWriteStatus Function Identifies whether the EEPROMLongWriteStatus feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMLongWriteStatus(NVM_MODULE_ID index); Returns • true - The EEPROMLongWriteStatus feature is supported on the device • false - The EEPROMLongWriteStatus feature is not supported on the device Description This function identifies whether the EEPROMLongWriteStatus feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_EEPROMNextWriteCycleIsLong Remarks None. Preconditions None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1258 Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMLongWriteStatus( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMOperationAbortControl Function Identifies whether the EEPROMOperationAbortControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMOperationAbortControl(NVM_MODULE_ID index); Returns • true - The EEPROMOperationAbortControl feature is supported on the device • false - The EEPROMOperationAbortControl feature is not supported on the device Description This function identifies whether the EEPROMOperationAbortControl feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_EEPROMOperationAbort Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMOperationAbortControl( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMOperationModeControl Function Identifies whether the EEPROMOperationModeControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMOperationModeControl(NVM_MODULE_ID index); Returns • true - The EEPROMOperationModeControl feature is supported on the device • false - The EEPROMOperationModeControl feature is not supported on the device Description This function identifies whether the EEPROMOperationModeControl feature is available on the NVM module. When this function returns true, this function is supported on the device: • PLIB_NVM_EEPROMOperationSelect Remarks None. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1259 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMOperationModeControl( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMStartOperationControl Function Identifies whether the EEPROMStartOperationControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMStartOperationControl(NVM_MODULE_ID index); Returns • true - The EEPROMStartOperationControl feature is supported on the device • false - The EEPROMStartOperationControl feature is not supported on the device Description This function identifies whether the EEPROMStartOperationControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_EEPROMReadStart • PLIB_NVM_EEPROMWriteStart • PLIB_NVM_EEPROMEraseStart • PLIB_NVM_EEPROMOperationHasCompleted Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMStartOperationControl( NVM_MODULE_ID index ) PLIB_NVM_ExistsEEPROMStopInIdleControl Function Identifies whether the EEPROMStopInIdleControl feature exists on the NVM module. File plib_nvm.h C bool PLIB_NVM_ExistsEEPROMStopInIdleControl(NVM_MODULE_ID index); Returns • true - The EEPROMStopInIdleControl feature is supported on the device • false - The EEPROMStopInIdleControl feature is not supported on the device Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1260 Description This function identifies whether the EEPROMStopInIdleControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_EEPROMStopInIdleEnable • PLIB_NVM_EEPROMStopInIdleDisable • PLIB_NVM_EEPROMStopInIdleIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_NVM_ExistsEEPROMStopInIdleControl( NVM_MODULE_ID index ) g) Data Types and Constants NVM_BOOT_MEMORY_AREA Enumeration Lists the different possible boot memory region. File plib_nvm_help.h C typedef enum { LOWER_BOOT_ALIAS_AREA, UPPER_BOOT_ALIAS_AREA, LOWER_BOOT_MEMORY_AREA_NOT_SUPPORTED } NVM_BOOT_MEMORY_AREA; Members Members Description LOWER_BOOT_ALIAS_AREA Lower boot alias region UPPER_BOOT_ALIAS_AREA Upper boot alias region LOWER_BOOT_MEMORY_AREA_NOT_SUPPORTED Lower boot alias region is not supported Description NVM Boot Memory Area This enumeration lists the different possible boot memory region. Remarks This enumeration is processor specific and is defined in the processor-specific header files. NVM_BOOT_MEMORY_PAGE Enumeration Lists the different NVM boot memory pages. File plib_nvm_help.h C typedef enum { LOWER_BOOT_ALIAS_PAGE4, Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1261 LOWER_BOOT_ALIAS_PAGE3, LOWER_BOOT_ALIAS_PAGE2, LOWER_BOOT_ALIAS_PAGE1, LOWER_BOOT_ALIAS_PAGE0, UPPER_BOOT_ALIAS_PAGE4, UPPER_BOOT_ALIAS_PAGE3, UPPER_BOOT_ALIAS_PAGE2, UPPER_BOOT_ALIAS_PAGE1, UPPER_BOOT_ALIAS_PAGE0, LOWER_BOOT_MEMORY_PAGE_NOT_SUPPORTED } NVM_BOOT_MEMORY_PAGE; Members Members Description LOWER_BOOT_ALIAS_PAGE4 Lower boot alias page 4 LOWER_BOOT_ALIAS_PAGE3 Lower boot alias page 3 LOWER_BOOT_ALIAS_PAGE2 Lower boot alias page 2 LOWER_BOOT_ALIAS_PAGE1 Lower boot alias page 1 LOWER_BOOT_ALIAS_PAGE0 Lower boot alias page 0 UPPER_BOOT_ALIAS_PAGE4 Upper boot alias page 4 UPPER_BOOT_ALIAS_PAGE3 Upper boot alias page 3 UPPER_BOOT_ALIAS_PAGE2 Upper boot alias page 2 UPPER_BOOT_ALIAS_PAGE1 Upper boot alias page 1 UPPER_BOOT_ALIAS_PAGE0 Upper boot alias page 0 LOWER_BOOT_MEMORY_PAGE_NOT_SUPPORTED Lower boot memory page not supported Description NVM Boot Memory Page This enumeration lists the different NVM boot memory page details. Remarks This enumeration is processor specific and is defined in the processor-specific header files. NVM_OPERATION_MODE Enumeration Lists the different Flash operation modes. File plib_nvm_help.h C typedef enum { WORD_PROGRAM_OPERATION, ROW_PROGRAM_OPERATION, PAGE_ERASE_OPERATION, FLASH_ERASE_OPERATION, UPPER_FLASH_REGION_ERASE_OPERATION, LOWER_FLASH_REGION_ERASE_OPERATION, QUAD_WORD_PROGRAM_OPERATION, NO_OPERATION } NVM_OPERATION_MODE; Members Members Description WORD_PROGRAM_OPERATION Word Program Operation ROW_PROGRAM_OPERATION Row Program Operation PAGE_ERASE_OPERATION Page Erase Operation FLASH_ERASE_OPERATION Flash Erase Operation UPPER_FLASH_REGION_ERASE_OPERATION Upper Flash Region Erase Operation LOWER_FLASH_REGION_ERASE_OPERATION Lower Flash Region Erase Operation QUAD_WORD_PROGRAM_OPERATION Quad Word Program Operation NO_OPERATION No Operation Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1262 Description NVM Operation Mode This enumeration lists the different Flash operation modes. Remarks This enumeration is processor specific and is defined in the processor-specific header files. NVM_MODULE_ID Enumeration Possible instances of the NVM module. File plib_nvm_help.h C typedef enum { NVM_ID_0, NVM_NUMBER_OF_MODULES } NVM_MODULE_ID; Members Members Description NVM_ID_0 NVM Module 0 ID NVM_NUMBER_OF_MODULES Number of available NVM modules. Description NVM Module ID This data type defines the possible instances of the NVM module. Remarks This enumeration is processor specific and is defined in the processor-specific header files. NVM_FLASH_SWAP_LOCK_TYPE Enumeration Lists the possible type of Flash swap lock. File plib_nvm_help.h C typedef enum { NVM_FLASH_SWAP_UNLOCKED = 0x0, NVM_FLASH_SWAP_LOCKED = 0x1, NVM_FLASH_SWAP_LOCKED_UNTIL_RESET = 0x3 } NVM_FLASH_SWAP_LOCK_TYPE; Members Members Description NVM_FLASH_SWAP_UNLOCKED = 0x0 Program Flash Bank and Boot Flash Bank region swapping is Not locked NVM_FLASH_SWAP_LOCKED = 0x1 Program Flash Bank and Boot Flash Bank region swapping is locked NVM_FLASH_SWAP_LOCKED_UNTIL_RESET = 0x3 Program Flash Bank and Boot Flash Bank region swapping is locked until device is reset Description NVM Flash Swap Lock This enumeration lists the possible type of Flash swap lock. Remarks This feature may not be available on all the devices. Refer to the specific device header files for availability. Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1263 EEPROM_ERROR Enumeration Lists the different EEPROM operation errors. File plib_nvm_help.h C typedef enum { NO_ERROR, VERIFY_ERROR, INVALID_OPERATION, BOR_ERROR } EEPROM_ERROR; Members Members Description NO_ERROR No error has occurred VERIFY_ERROR Error occurred during verification INVALID_OPERATION Operation selected and executed are not the same BOR_ERROR BOR has suspended EEPROM operation Description EEPROM operation error This enumeration lists the different EEPROM operation errors. Remarks This enumeration is processor specific and is defined in the processor-specific header files. EEPROM_OPERATION_MODE Enumeration Lists the different EEPROM operation modes. File plib_nvm_help.h C typedef enum { EEPROM_WORD_READ_OPERATION, EEPROM_WORD_WRITE_OPERATION, EEPROM_FORCED_WORD_ERASE_OPERATION, EEPROM_ERASE_ALL_OPERATION, EEPROM_CONFIG_WRITE_OPERATION } EEPROM_OPERATION_MODE; Members Members Description EEPROM_WORD_READ_OPERATION Word read operation EEPROM_WORD_WRITE_OPERATION Word write operation EEPROM_FORCED_WORD_ERASE_OPERATION Page erase operation. Under normal conditions, there is no need to attempt a Forced Word Erase. The Data EEPROM has internal logic which automatically manages all read/erase/write command sequences. Software execution of the Forced Word Erase operation should be used in response to write verification error, VERIFY_ERROR EEPROM_ERASE_ALL_OPERATION Bulk erase operation. Unlike the read command, the bulk erase command cannot be aborted by software. During an erase cycle, any software attempt to write to the EECON register will be ignored EEPROM_CONFIG_WRITE_OPERATION Write to configuration registers operation. Before accessing the EEPROM at full speed, it is necessary to program configuration values into the Data EEPROM controller after enabling it. This is done through the Configuration Write operation Description EEPROM Operation Mode Peripheral Libraries Help NVM Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1264 This enumeration lists the different EEPROM operation modes. Remarks This enumeration is processor specific and is defined in the processor- specific header files. Files Files Name Description plib_nvm.h NVM PLIB Interface Header for NVM common definitions. plib_nvm_help.h Defines the NVM Peripheral Library data types. Description This section lists the source and header files used by the library. plib_nvm.h NVM PLIB Interface Header for NVM common definitions. Functions Name Description PLIB_NVM_BootFlashBank1LowerRegion Maps Boot Flash Bank 1 to lower mapped region. PLIB_NVM_BootFlashBank2IsLowerRegion Gives the status of Boot Flash Bank mapping. PLIB_NVM_BootFlashBank2LowerRegion Maps Boot Flash Bank 2 to the lower mapped region. PLIB_NVM_BootPageWriteProtectionDisable Write protection for selected boot page is disabled. PLIB_NVM_BootPageWriteProtectionEnable Locks the selected boot page. PLIB_NVM_DataBlockSourceAddress Takes the address parameter in the argument and loads the base address from which data has to be copied into Flash memory. PLIB_NVM_EEPROMAddress EEPROM address where operation has to be performed. PLIB_NVM_EEPROMDataToWrite Accepts the data to be written into the EEPROM. PLIB_NVM_EEPROMDisable Disables the EEPROM memory. PLIB_NVM_EEPROMEnable Enables the EEPROM memory. PLIB_NVM_EEPROMEraseStart Initiates EEPROM erase cycle. PLIB_NVM_EEPROMErrorClear Clears the EEPROM operation error. PLIB_NVM_EEPROMErrorGet Returns the EEPROM operation error. PLIB_NVM_EEPROMIsReady Provides the availability status of the EEPROM. PLIB_NVM_EEPROMKeySequenceWrite Write mandatory KEY sequence to unlock the EEPROM write or erase protection. PLIB_NVM_EEPROMNextWriteCycleIsLong Informs whether the next write or erase cycle of the EEPROM is long. PLIB_NVM_EEPROMOperationAbort Aborts the current EEPROM operation. PLIB_NVM_EEPROMOperationHasCompleted Provides the status of the EEPROM write or erase or read cycle. PLIB_NVM_EEPROMOperationSelect Selects the operation to be performed on the EEPROM. PLIB_NVM_EEPROMRead Read the EEPROM data. PLIB_NVM_EEPROMReadEnable Allows read operation to the EEPROM. PLIB_NVM_EEPROMReadIsEnabled Returns EEPROM read permission status. PLIB_NVM_EEPROMReadStart Initiates a EEPROM read cycle. PLIB_NVM_EEPROMStopInIdleDisable Continues EEPROM operation when device enters Idle mode. PLIB_NVM_EEPROMStopInIdleEnable Discontinues EEPROM operation when device enters Idle mode. PLIB_NVM_EEPROMStopInIdleIsEnabled Returns Stop in Idle mode status of the EEPROM operation. PLIB_NVM_EEPROMWriteEnable Allows write or erase operation to the EEPROM. PLIB_NVM_EEPROMWriteIsEnabled Returns EEPROM Write permission status. PLIB_NVM_EEPROMWriteStart Initiates a EEPROM write cycle. PLIB_NVM_ExistsAddressModifyControl Identifies whether the AddressModifyControl feature exists on the NVM module. PLIB_NVM_ExistsBootFlashBankRegion Identifies whether the BootFlashBankRegion feature exists on the NVM module. Peripheral Libraries Help NVM Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1265 PLIB_NVM_ExistsBootPageWriteProtect Identifies whether the BootPageWriteProtect feature exists on the NVM module. PLIB_NVM_ExistsEEPROMAddressControl Identifies whether the EEPROMAddressControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMDataControl Identifies whether the EEPROMDataControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMEnableControl Identifies whether the EEPROMEnableControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMEnableOperationControl Identifies whether the EEPROMEnableOperationControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMErrorStatus Identifies whether the EEPROMErrorStatus feature exists on the NVM module. PLIB_NVM_ExistsEEPROMKeySequence Identifies whether the EEPROMKeySequence feature exists on the NVM module. PLIB_NVM_ExistsEEPROMLongWriteStatus Identifies whether the EEPROMLongWriteStatus feature exists on the NVM module. PLIB_NVM_ExistsEEPROMOperationAbortControl Identifies whether the EEPROMOperationAbortControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMOperationModeControl Identifies whether the EEPROMOperationModeControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMStartOperationControl Identifies whether the EEPROMStartOperationControl feature exists on the NVM module. PLIB_NVM_ExistsEEPROMStopInIdleControl Identifies whether the EEPROMStopInIdleControl feature exists on the NVM module. PLIB_NVM_ExistsFlashBankRegionSelect Identifies whether the FlashBankRegionSelect feature exists on the NVM module. PLIB_NVM_ExistsFlashWPMemoryRangeProvide Identifies whether the FlashWPMemoryRangeProvide feature exists on the NVM module. PLIB_NVM_ExistsKeySequence Identifies whether the KeySequence feature exists on the NVM module. PLIB_NVM_ExistsLockBootSelect Identifies whether the LockBootSelect feature exists on the NVM module. PLIB_NVM_ExistsLockPFMSelect Identifies whether the LockPFMSelect feature exists on the NVM module. PLIB_NVM_ExistsLowVoltageError Identifies whether the LowVoltageError feature exists on the NVM module. PLIB_NVM_ExistsLowVoltageStatus Identifies whether the LowVoltageStatus feature exists on the NVM module. PLIB_NVM_ExistsMemoryModificationControl Identifies whether the MemoryModificationControl feature exists on the NVM module. PLIB_NVM_ExistsOperationMode Identifies whether the OperationMode feature exists on the NVM module. PLIB_NVM_ExistsProvideData Identifies whether the ProvideData feature exists on the NVM module. PLIB_NVM_ExistsProvideQuadData Identifies whether the ProvideQuadData feature exists on the NVM module. PLIB_NVM_ExistsSourceAddress Identifies whether the SourceAddress feature exists on the NVM module. PLIB_NVM_ExistsSwapLockControl Identifies whether the SwapLockControl feature exists on the NVM module. PLIB_NVM_ExistsWriteErrorStatus Identifies whether the WriteErrorStatus feature exists on the NVM module. PLIB_NVM_ExistsWriteOperation Identifies whether the WriteOperation feature exists on the NVM module. PLIB_NVM_FlashAddressToModify Modifies the Flash memory address. PLIB_NVM_FlashEraseStart Performs erase operation on the selected Flash memory area. PLIB_NVM_FlashProvideData Provides the data to be written into Flash memory. PLIB_NVM_FlashProvideQuadData Provides the quad data to be written into Flash memory. PLIB_NVM_FlashRead Read the specified address of Flash memory. PLIB_NVM_FlashSwapLockSelect Selects the kind of Flash swap lock required. PLIB_NVM_FlashSwapLockStatusGet Get the status of Swap lock bits. PLIB_NVM_FlashWriteCycleHasCompleted Provides the status of the Flash write cycle. PLIB_NVM_FlashWriteKeySequence Copies the mandatory KEY sequence into the respective registers. PLIB_NVM_FlashWriteProtectMemoryAreaRange Sets the address below which physical memory will be write protected. PLIB_NVM_FlashWriteStart Performs a write operation on the Flash memory row selected. PLIB_NVM_IsBootMemoryLocked Provides lock status of boot page write-protect bits. PLIB_NVM_IsBootPageWriteProtected Provides write protection status for boot memory page. PLIB_NVM_IsProgramFlashMemoryLocked Provides lock status of Program Flash Write-Protect register. PLIB_NVM_LockBootMemory Locks the boot write-protect bits. PLIB_NVM_LockProgramFlashMemory Lock the Program Flash write-protect register. PLIB_NVM_LowVoltageEventIsActive Provides low voltage detection status. Peripheral Libraries Help NVM Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1266 PLIB_NVM_LowVoltageIsDetected Provides low voltage error detection status. PLIB_NVM_MemoryModifyEnable Allows write cycles to Flash memory. PLIB_NVM_MemoryModifyInhibit Inhibits write cycles to Flash memory. PLIB_NVM_MemoryOperationSelect Selects the operation to be performed on Flash memory. PLIB_NVM_ProgramFlashBank1LowerRegion Maps Flash Bank 1 to the lower mapped region. PLIB_NVM_ProgramFlashBank2IsLowerRegion Gives the status of Program Flash Bank mapping. PLIB_NVM_ProgramFlashBank2LowerRegion Maps the bank 2 to lower mapped region. PLIB_NVM_WriteOperationHasTerminated Provides the status of the Flash write operation or sequence. Description Non-Volatile Memory (NVM) Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the NVM PLIB for all families of Microchip microcontrollers..The definitions in this file are common to NVM peripheral. File Name plib_nvm.h Company Microchip Technology Inc. plib_nvm_help.h Defines the NVM Peripheral Library data types. Enumerations Name Description EEPROM_ERROR Lists the different EEPROM operation errors. EEPROM_OPERATION_MODE Lists the different EEPROM operation modes. NVM_BOOT_MEMORY_AREA Lists the different possible boot memory region. NVM_BOOT_MEMORY_PAGE Lists the different NVM boot memory pages. NVM_FLASH_SWAP_LOCK_TYPE Lists the possible type of Flash swap lock. NVM_MODULE_ID Possible instances of the NVM module. NVM_OPERATION_MODE Lists the different Flash operation modes. Description NVM Peripheral Library Constants Header This header file contains the definitions of the data types and constants that make up the interface to the NVM Peripheral Library for Microchip microcontrollers. The definitions in this file are for NVM module. File Name plib_nvm_help.h Company Microchip Technology Inc. Peripheral Libraries Help NVM Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1267 Output Compare Peripheral Library This section describes the Output Compare Peripheral Library. Introduction This library provides a low-level abstraction of the Output Compare Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The Output Compare module is primarily used to generate a single pulse or a series of pulses in response to selected time base events. Output Compare module operation essentially requires a timer and one or two compare values. Users have an option to select either a 32-bit timer or a 16-bit timer. The timer can be programmed to count at a desired frequency and count up to a desired period value. Details regarding timer operation and setup can be found in the Timer Peripheral Library. The Output Compare module compares the value of the timer with the compare values depending on the selected operating mode. When a compare match occurs between a timer value and compare values, the Output Compare module outputs a change of state on its output pins in accordance with the chosen Output Compare compare mode logic. Either a single pulse or a sequence of pulses may be generated. Some of the key operating modes of the OC module are: • Single Compare Set High/Low modes: In these compare modes, a compare match between the timer and the buffer (primary compare value) sets the output High/Low. The output remains at the same state after compare match event unless the module is disabled or the mode is changed. • Single Compare Toggle mode: Output toggles state at every compare match event between the timer and the buffer (primary compare value) • Dual compare Single/Continuous Pulse modes: These modes require two compare values. Leading edge of output pulse is generated during compare match of the incrementing timer and the buffer (primary compare value). Trailing edge of output pulse results when a compare match occurs between the incrementing timer and the pulse width value (secondary compare value). The output may be a single pulse or a sequence of pulses. • Pulse-Width Modulation (PWM) modes: In this mode, output goes high when a compare match occurs between timer and the pulse width value (duty cycle). The output is reset back to its initial state when the timer resets after attaining its maximum count. The Output Compare module also provides programmable interrupt generation on a compare match event. In PWM mode, hardware-based Fault detection and automatic output disable features are provided. Figure 1 shows a block diagram of the Output Compare module. A compare match between the timer value and the compare values generates a pulse at the output. Figure 1: Output Compare Module Block Diagram Figure 2 shows a block diagram of the Output Compare module with dedicated timers, present on some devices. It facilitates the use of multiple Output Compare modules operating synchronously or the use of an asynchronous trigger to generate a pulse. Figure 2: Output Compare Module Block Diagram with Dedicated Timers Peripheral Libraries Help Output Compare Peripheral Library Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1268 Using the Library This topic describes the basic architecture of the Output Compare Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_oc.h The interface to the Output Compare Peripheral library is defined in the plib_oc.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Output Compare Peripheral Library must include peripheral.h. Library File: The Output Compare Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the Peripheral interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the Output Compare module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all the functionality of the available Output Compare modules on the device. Refer to the "Output Compare" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine the set of functions that are supported for each Output Compare module on your device. Description The Output Compare Peripheral Library is used to simplify low-level access to the Output Compare module without having the need to directly interact the module's registers. The function names are generic and lead to easier access to the Output Compare module on different devices. Output Compare module Software Abstraction Block Diagram Peripheral Libraries Help Output Compare Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1269 The Output Compare module can be described from a software standpoint as having functions to configure the module itself, to select the timer, set the buffer and pulse width values, and select the mode of operation. The desired nature of the output pulse is thus obtained. A 16-bit or a 32-bit timer can be selected for the output compare time base. In some devices, the Output Compare module can be synchronized to an external input source. The Output Compare module can also operate asynchronously, based on a trigger by an input source. The Output Compare module entails the use of some functions dealing with Timer set up. These details can be found in Timer Peripheral Library. Functions have been provided to set buffer values and pulse-width values. Pulse-width values are used only in Dual compare and PWM modes. In PWM mode, the buffer value provides the initial duty cycle for the first time period, while all later time cycles employ the 'pulse-width' value as the duty cycle value. Compare modes: • Single Compare Level Mode: Sets the output of Output Compare module at either 'High' or 'Low' at a compare match event • Single Compare Toggle Mode: Toggles the output of OC module at each compare match event. This mode will produce continuous pulses. • Dual Compare Mode: Output Compare module output is driven 'High' on compare match with buffer value and driven 'Low' on a compare match with the pulse-width value. The output can be either a single pulse or a continuous stream of pulses. • PWM Mode: In Edge-aligned PWM mode, the Output Compare module output is driven 'High' whenever the timer resets, and is driven 'Low' on a compare match with the pulse-width value. Faults may or may not be enabled. In Center-aligned PWM mode, the Output Compare module output is driven 'High' on a compare match with the buffer value and driven 'Low' on a compare match with the pulse-width value. Note: In PWM mode, it is vital that the user selects the mode of operation before selecting a Fault input. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Output Compare module. Library Interface Section Description General Setup Functions Provides setup, configuration and status control interface routines. Compare Mode Functions Provides Compare mode interface routines. Timer Functions Provides Timer interface routines. Power-Saving Modes Functions Provides Power-Saving modes interface routines. Faults Functions Provides Faults interface routines. Feature Existence Functions Provides interface routines that determine whether or not certain features are available. Peripheral Libraries Help Output Compare Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1270 How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. All of the interface functions in this library are classified according to: • General Setup: These routines deal with general setup of Output Compare module • Compare/PWM Mode: These routines facilitate the selection of a Compare/PWM mode and setting up the compare values • Timer: These functions deal with configuring the timer, selection of the clock source, and setting up a synchronous or asynchronous mode of operation for the OC module • Power-Saving Modes: • Sleep Mode: The Output Compare module output is driven to the same state as it was in prior to the device entering Sleep mode. In PWM Fault mode, Fault detection is active. A Fault forces output of the OC module to tri-state or to a fixed predetermined state. • Idle Mode: The Output Compare module can be configured to suspend its operations or continue its operations. If the Output Compare module suspends its operations, it has the same behavior as it does in Sleep mode. • Faults: These functions are used to select Fault inputs and identify occurrences of Faults when the Output Compare module functions in PWM mode • Exists: These functions notify whether or not a particular feature is present on a device The following sections provide examples that depict the use of interface functions to perform general tasks such as initialization and set up of the Output Compare module and setting up the Output Compare module in different compare modes. Single Compare Set High Mode The Single Compare Set High mode sets the output of the Output Compare module 'High' at a compare match event. This section illustrates the steps required to configure the Output Compare module in Single Compare Set High mode. Example: /* This example illustrates setting up Output Compare Module in Single Compare Set High mode */ /* Configure Timer2 in 16-bit mode. Refer to Timer Peripheral Library for the API */ /* Disable OC module */ PLIB_OC_Disable(MY_OC_ID); /* Select Timer2 as time base */ PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); /* Set period of time base. Refer to Timer Peripheral Library for the API */ /* Select compare mode */ PLIB_OC_ModeSelect(MY_OC_ID, OC_SET_HIGH_SINGLE_PULSE_MODE); /* Set buffer size to 16-bits */ PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_16BIT); /* Set buffer value */ PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); /* Configure interrupts associated with Output Compare module. Refer to Timer Peripheral Library for the API */ /* Enable Timer2. Refer to Timer Peripheral Library for the API */ /* Enable the Output Compare module */ PLIB_OC_Enable(MY_OC_ID); Single Compare Toggle Mode The Single Compare Toggle mode toggles the output of the Output Compare module at each compare match event. This section illustrates the steps required to configure the Output Compare module in Single Compare Toggle mode. Example: /* This example illustrates setting up Output Compare Module in Single Compare Toggle mode */ Peripheral Libraries Help Output Compare Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1271 /* Configure Timer2 in 16-bit mode. Refer to Timer Peripheral Library for the API */ /* Disable OC module */ PLIB_OC_Disable(MY_OC_ID); /* Select Timer2 as time base */ PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); /* Set period of time base. Refer to Timer Peripheral Library for the API */ /* Select compare mode */ PLIB_OC_ModeSelect(MY_OC_ID, OC_TOGGLE_CONTINOUS_PULSE_MODE); /* Set buffer size to 16-bits */ PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_16BIT); /* Set Buffer Value */ PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); /* Configure interrupts associated with Output Compare module. Refer to Interrupts Peripheral Library for the API */ /* Enable Timer2. Refer to Timer Peripheral Library for the API */ /* Enable Output Compare module */ PLIB_OC_Enable(MY_OC_ID); Dual Compare Continuous Mode In this mode, the Output Compare module output is driven 'High' on a compare match with the buffer value and driven 'Low' on a compare match with the pulse-width value. A continuous stream of pulses is generated. This section illustrates the steps required to configure the Output Compare module in Dual Compare Continuous Pulse mode. Example: /* This example illustrates setting up Output Compare Module in Dual Compare Continuous Pulse mode */ /* Configure Timer2 in 16-bit mode. Refer to Timer Peripheral Library for the API */ /* Disable OC module */ PLIB_OC_Disable(MY_OC_ID); /* Select Timer2 as time base */ PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); /* Set period of time base. Refer to Timer Peripheral Library for the API */ /* Select compare mode */ PLIB_OC_ModeSelect(MY_OC_ID, OC_DUAL_COMPARE_CONTINUOUS_PULSE_MODE); /* Set buffer size to 16-bits */ PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_16BIT); /* Set buffer(primary compare) value */ PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); /*Set pulse width(secondary compare) value */ PLIB_OC_PulseWidth16BitSet(MY_OC_ID, 0x0FFF); /* Configure interrupts associated with Output Compare module. Refer to Interrupts Peripheral Library for the API */ /* Enable Timer2. Refer to Timer Peripheral Library for the API */ /* Enable the Output Compare module */ PLIB_OC_Enable(MY_OC_ID); Peripheral Libraries Help Output Compare Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1272 PWM Mode with Enabled Faults This section illustrates the steps required to configure the Output Compare module in PWM mode. Note: In PWM mode, it is vital that the user selects the mode of operation before selecting a Fault input. Example: This section illustrates the steps required to configure the Output Compare module in PWM mode with Fault protection. This mode can be selected using PLIB_OC_ModeSelect or PLIB_OC_FaultInputSelect. /* Configure Timer2 in 16-bit mode. Refer to Timer Peripheral Library for the API */ /* Disable OC module */ PLIB_OC_Disable(MY_OC_ID); /* Select Timer2 as time base */ PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); /* Set period of time base. Refer to Timer Peripheral Library for the API */ /* Select compare mode. PWM with fault protection mode is selected , fault selection is preset in the hardware*/ PLIB_OC_ModeSelect(MY_OC_ID, OC_COMPARE_PWM_MODE_WITH_FAULT_PROTECTION ); /*or use PLIB_OC_FaultInputSelect(MY_OC_ID, OC_FAULT_PRESET) to achieve the same*/ /* Set buffer size to 16-bits. Refer to Timer Peripheral Library for the API */ PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_16BIT); /* Set buffer (initial duty cycle) Value */ PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); /*Set pulse width (Duty cycle) value */ PLIB_OC_PulseWidth16BitSet(MY_OC_ID, 0x0FFF); /* Configure interrupts associated with Output Compare module. Refer to Interrupts Peripheral Library for the API */ /* Enable Timer2. Refer to Timer Peripheral Library for the API */ /* Enable OC module */ PLIB_OC_Enable(MY_OC_ID); /* Check for PWM Fault */ while(!PLIB_OC_FaultHasOccurred(MY_OC_ID)) { /* If no PWM fault, continue normal operation*/ } Configuring the Library The library is configured for the supported Output Compare module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Setup Functions Name Description PLIB_OC_Disable Disable the Output Compare module. PLIB_OC_Enable Enables the Output Compare module. PLIB_OC_IsEnabled Checks whether the Output Compare module is enabled or not. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1273 b) Compare Mode Functions Name Description PLIB_OC_ModeSelect Selects the compare mode for the Output Compare module. PLIB_OC_Buffer16BitSet Sets a 16-bit primary compare value for compare operations. PLIB_OC_Buffer32BitSet Sets a 32-bit primary compare value for compare operations. PLIB_OC_BufferSizeSelect Sets the buffer size and pulse width to 16-bits or 32-bits. PLIB_OC_PulseWidth16BitSet Sets a 16-bit pulse width for Output Compare module output. PLIB_OC_PulseWidth32BitSet Sets a 32-bit pulse width for Output Compare module output. c) Timer Functions Name Description PLIB_OC_TimerSelect Selects a clock source for the Output Compare module. PLIB_OC_AlternateClockDisable Selects Timer 2/3, instead of the alternate clock source. PLIB_OC_AlternateClockEnable Selects the alternate clock source. PLIB_OC_AlternateTimerSelect Selects an alternate timer as a clock source for the Output Compare module. d) Power-Saving Modes Functions Name Description PLIB_OC_StopInIdleDisable Output Compare module continues operating when the device enters Idle mode. PLIB_OC_StopInIdleEnable Discontinues Output Compare module operation when the device enters Idle mode. e) Faults Functions Name Description PLIB_OC_FaultHasOccurred Checks if a PWM fault has occurred. PLIB_OC_FaultInputSelect Enables/Disables the Fault input for the Output Compare PWM mode. f) Feature Existence Functions Name Description PLIB_OC_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the Output Compare module. PLIB_OC_ExistsBufferSize Identifies whether the BufferSize feature exists on the Output Compare module. PLIB_OC_ExistsBufferValue Identifies whether the BufferValue feature exists on the Output Compare module. PLIB_OC_ExistsCompareModeSelect Identifies whether the CompareModeSelect feature exists on the Output Compare module. PLIB_OC_ExistsEnableControl Identifies whether the EnableControl feature exists on the Output Compare module. PLIB_OC_ExistsFaultInput Identifies whether the FaultInput feature exists on the Output Compare module. PLIB_OC_ExistsFaultStatus Identifies whether the FaultStatus feature exists on the Output Compare module. PLIB_OC_ExistsPulseWidth Identifies whether the PulseWidth feature exists on the Output Compare module. PLIB_OC_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the Output Compare module. PLIB_OC_ExistsTimerSelect Identifies whether the TimerSelect feature exists on the Output Compare module. PLIB_OC_ExistsAlternateTimerSelect Identifies whether the AlternateTimerSelect feature exists on the Output Compare module. g) Data Types and Constants Name Description OC_16BIT_TIMERS Lists different 16 bit time bases for Output Compare module. OC_BUFFER_SIZE Lists different buffer sizes for compare value. OC_COMPARE_MODES Lists the different compare modes for the Output Compare module. OC_FAULTS Lists different fault sources for Output Compare module OC_MODULE_ID OC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to determine the correct number of modules defined for the desired microcontroller. OC_ALT_TIMERS Lists the different 16-bit alternate timers for the Output Compare module. Description This section describes the Application Programming Interface (API) functions of the Output Compare Peripheral Library. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1274 Refer to each section for a detailed description. a) General Setup Functions PLIB_OC_Disable Function Disable the Output Compare module. File plib_oc.h C void PLIB_OC_Disable(OC_MODULE_ID index); Returns None. Description This function disables the Output Compare module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_OC_ID OC_ID_1 PLIB_OC_Disable(MY_OC_ID); Parameters Parameters Description index Identifies the Output Compare module Function void PLIB_OC_Disable( OC_MODULE_ID index ) PLIB_OC_Enable Function Enables the Output Compare module. File plib_oc.h C void PLIB_OC_Enable(OC_MODULE_ID index); Returns None. Description This function enables the Output Compare module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsEnableControl in your application to determine whether this feature is available. Preconditions The module should be appropriately configured before being enabled. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1275 Example #define MY_OC_ID OC_ID_1 //Do all the other configurations before enabling. PLIB_OC_Enable(MY_OC_ID); Parameters Parameters Description index Identifies the desired Output Compare module Function void PLIB_OC_Enable( OC_MODULE_ID index ) PLIB_OC_IsEnabled Function Checks whether the Output Compare module is enabled or not. File plib_oc.h C bool PLIB_OC_IsEnabled(OC_MODULE_ID index); Returns Boolean • true - The Output Compare module is enabled • false - The Output Compare module is not enabled Description The function returns the enable status of the Output Compare module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example #define MY_OC_ID OC_ID_1 if(PLIB_OC_IsEnabled(MY_OC_ID)) { //Take respective actions } else { //Take respective actions } Parameters Parameters Description index Identifies the desired Output Compare module Function bool PLIB_OC_IsEnabled( OC_MODULE_ID index ) b) Compare Mode Functions Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1276 PLIB_OC_ModeSelect Function Selects the compare mode for the Output Compare module. File plib_oc.h C void PLIB_OC_ModeSelect(OC_MODULE_ID index, OC_COMPARE_MODES cmpMode); Returns None. Description This function selects the compare mode for the Output Compare module. Remarks If PLIB_OC_FaultInputSelect is called after PLIB_OC_ModeSelect, the mode selected by the PLIB_OC_ModeSelect function will be overwritten as the PLIB_OC_FaultInputSelect function selects the PWM mode with or without Fault protection. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsCompareModeSelect in your application to determine whether this feature is available. Preconditions The Output Compare module must be turned off before a new mode is selected. The Output Compare module is turned off through the PLIB_OC_ModeSelect(MY_OC_ID,OC_COMPARE_TURN_OFF_MODE) function. Refer to the enumeration description for information on different modes and preconditions. Example #define MY_OC_ID OC_ID_1 // Dual compare continuous pulse mode is selected PLIB_OC_ModeSelect(MY_OC_ID, OC_DUAL_COMPARE_CONTINUOUS_PULSE_MODE ); Parameters Parameters Description index Identifies the desired Output Compare module cmpMode Identifies the compare mode for Output Compare module Function void PLIB_OC_ModeSelect( OC_MODULE_ID index, OC_COMPARE_MODES cmpMode ) PLIB_OC_Buffer16BitSet Function Sets a 16-bit primary compare value for compare operations. File plib_oc.h C void PLIB_OC_Buffer16BitSet(OC_MODULE_ID index, uint16_t val16Bit); Returns None. Description This function sets a 16-bit primary compare value for compare operations in all modes except PWM modes. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsBufferValue in your application to determine whether this feature is available. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1277 Preconditions The PWM mode of operation should not be selected. The buffer size should be set to 16-bits by the PLIB_OC_BufferSizeSelect function. Example #define MY_OC_ID OC_ID_1 PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); Parameters Parameters Description index Identifies the desired Output Compare module val16Bit Sets a 16-bit primary compare value Function void PLIB_OC_Buffer16BitSet( OC_MODULE_ID index, uint16_t val16Bit) PLIB_OC_Buffer32BitSet Function Sets a 32-bit primary compare value for compare operations. File plib_oc.h C void PLIB_OC_Buffer32BitSet(OC_MODULE_ID index, uint32_t val32Bit); Returns None. Description This function sets a 32-bit primary compare value for compare operations in all modes except PWM modes. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsBufferValue in your application to determine whether this feature is available. Preconditions The PWM mode of operation should not be selected. The buffer size should be set to 32-bits by the PLIB_OC_BufferSizeSelect function. Example #define MY_OC_ID OC_ID_1 PLIB_OC_Buffer32BitSet(MY_OC_ID, 0x000000FF); Parameters Parameters Description index Identifies the desired Output Compare module val32Bit Sets a 32-bit primary compare value Function void PLIB_OC_Buffer32BitSet( OC_MODULE_ID index, uint32_t val32Bit) PLIB_OC_BufferSizeSelect Function Sets the buffer size and pulse width to 16-bits or 32-bits. File plib_oc.h C void PLIB_OC_BufferSizeSelect(OC_MODULE_ID index, OC_BUFFER_SIZE size); Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1278 Returns None. Description This function sets the size of the buffer and pulse width to 16-bits or 32-bits. The choice is made based on whether a 16-bit timer or a 32-bit timer is selected. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsBufferSize in your application to determine whether this feature is available. Preconditions None. Example #define MY_OC_ID OC_ID_1 // Buffer size and pulse width size are set to 32-bits PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_32BIT); Parameters Parameters Description index Identifies the desired Output Compare module size Identifies the size of compare value Function void PLIB_OC_BufferSizeSelect( OC_MODULE_ID index, OC_BUFFER_SIZE size ) PLIB_OC_PulseWidth16BitSet Function Sets a 16-bit pulse width for Output Compare module output. File plib_oc.h C void PLIB_OC_PulseWidth16BitSet(OC_MODULE_ID index, uint16_t pulseWidth); Returns None. Description This function sets a 16-bit pulse width for the Output Compare module in dual compare modes. A dual compare mode can be selected using the PLIB_OC_ModeSelect function. Secondary compare match event (pulse width) decides the trailing (falling) edge of the Output Compare module output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsPulseWidth in your application to determine whether this feature is available. Preconditions Dual compare operation should be selected. The buffer size should be set to 16-bits by the PLIB_OC_BufferSizeSelect function. Example #define MY_OC_ID OC_ID_1 PLIB_OC_PulseWidth16BitSet(MY_OC_ID, 0x0FFF); Parameters Parameters Description index Identifies the desired Output Compare module pulseWidth Pulse width value Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1279 Function void PLIB_OC_PulseWidth16BitSet( OC_MODULE_ID index,uint16_t pulseWidth) PLIB_OC_PulseWidth32BitSet Function Sets a 32-bit pulse width for Output Compare module output. File plib_oc.h C void PLIB_OC_PulseWidth32BitSet(OC_MODULE_ID index, uint32_t pulseWidth); Returns None. Description This function sets a 32-bit pulse width for Output Compare module in dual compare modes. A dual compare mode can be selected using PLIB_OC_ModeSelect function. Secondary compare match event (pulse width) decides the trailing (falling) edge of the Output Compare module output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsPulseWidth in your application to determine whether this feature is available. Preconditions Dual compare operation should be selected. The buffer size should be set to 32-bits by the PLIB_OC_BufferSizeSelect function. Example #define MY_OC_ID OC_ID_1 PLIB_OC_PulseWidth32BitSet(MY_OC_ID, 0x00000FFF); Parameters Parameters Description index Identifies the desired Output Compare module pulseWidth Pulse width value Function void PLIB_OC_PulseWidth32BitSet( OC_MODULE_ID index,uint32_t pulseWidth) c) Timer Functions PLIB_OC_TimerSelect Function Selects a clock source for the Output Compare module. File plib_oc.h C void PLIB_OC_TimerSelect(OC_MODULE_ID index, OC_16BIT_TIMERS tmr); Returns None. Description This function selects a clock source for the Output Compare module if the 16-bit time base is set. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1280 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsTimerSelect in your application to determine whether this feature is available. Preconditions The 16-bit time base needs to be set. Example #define MY_OC_ID OC_ID_1 // 16-bit Timer2 is selected PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); Parameters Parameters Description index Identifies the desired Output Compare module tmr Identifies the timer Function void PLIB_OC_TimerSelect( OC_MODULE_ID index, OC_16BIT_TIMERS tmr ) PLIB_OC_AlternateClockDisable Function Selects Timer 2/3, instead of the alternate clock source. File plib_oc.h C void PLIB_OC_AlternateClockDisable(OC_MODULE_ID index); Returns None. Description This function selects Timer2/Timer3, instead of the alternate clock source. Remarks The feature is not supported on all devices. Please refer to the specific device data sheet to determine availability. A system unlock must be performed before this function can be executed. This function applies to all input capture modules, regardless of the OC_MODULE_ID passed in the call. Preconditions A system unlock PLIB_DEVCON_SystemUnlock must be performed before this function can be executed. Example // Call system service to unlock oscillator #define MY_OC_ID OC_ID_1 PLIB_OC_AlternateClockDisable( MY_OC_ID ); Parameters Parameters Description index Identifies the desired Output Compare module Function void PLIB_OC_AlternateClockDisable( OC_MODULE_ID index) PLIB_OC_AlternateClockEnable Function Selects the alternate clock source. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1281 File plib_oc.h C void PLIB_OC_AlternateClockEnable(OC_MODULE_ID index); Returns None. Description This function selects the alternate clock source instead of Timer2/Timer3. Remarks The feature is not supported on all devices. Please refer to the specific device data sheet to determine availability. A system unlock must be performed before this function can be executed. This function applies to all input capture modules, regardless of the OC_MODULE_ID passed in the call. Preconditions A system unlock PLIB_DEVCON_SystemUnlock must be performed before this function can be executed. Example // Call system service to unlock oscillator #define MY_OC_ID OC_ID_1 PLIB_OC_AlternateClockEnable( MY_OC_ID ); Parameters Parameters Description index Identifies the desired Output Compare module Function void PLIB_OC_AlternateClockEnable( OC_MODULE_ID index) PLIB_OC_AlternateTimerSelect Function Selects an alternate timer as a clock source for the Output Compare module. File plib_oc.h C bool PLIB_OC_AlternateTimerSelect(OC_MODULE_ID index, OC_ALT_TIMERS tmr); Returns • true - Alternate timer selected successfully • false - Alternate timer selection failure, select an appropriate alternate timer for the Output Compare module index Description This function selects an alternate timer as a clock source for the Output Compare module. • OC_ID_1,OC_ID_2,OC_ID_3: Can use Timer4 or Timer5 as alternate timers • OC_ID_4,OC_ID_5,OC_ID_6: Can use Timer2 or Timer3 as alternate timers • OC_ID_7,OC_ID_8,OC_ID_9: Can use Timer6 or Timer7 as alternate timers Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsAlternateTimerSelect in your application to determine whether this feature is available. Preconditions The 16-bit time base needs to be set. The PLIB_OC_AlternateClockEnable function should be called for the Output Compare module to enable the alternate clock selection. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1282 Example #define MY_OC_ID OC_ID_1 bool result; //Enabling alternate timer selection PLIB_OC_AlternateClockEnable( MY_OC_ID ); // 16-bit Timer4 is selected as the clock source for Output Compare module 1 result = PLIB_OC_AlternateTimerSelect(MY_OC_ID, OC_ALT_TIMER_TMR4); if(false == result) { // Selected alternate timer does not available for the desired Output // Compare module. // Select the appropriate alternate timer. } Parameters Parameters Description index Identifies the desired Output Compare module tmr Identifies the alternate timer Function bool PLIB_OC_AlternateTimerSelect( OC_MODULE_ID index, OC_ALT_TIMERS tmr ) d) Power-Saving Modes Functions PLIB_OC_StopInIdleDisable Function Output Compare module continues operating when the device enters Idle mode. File plib_oc.h C void PLIB_OC_StopInIdleDisable(OC_MODULE_ID index); Returns None. Description The function continues Output Compare module operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_OC_ID OC_ID_1 PLIB_OC_StopInIdleDisable(MY_OC_ID); Parameters Parameters Description index Identifies the desired Output Compare module Function void PLIB_OC_StopInIdleDisable( OC_MODULE_ID index ) Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1283 PLIB_OC_StopInIdleEnable Function Discontinues Output Compare module operation when the device enters Idle mode. File plib_oc.h C void PLIB_OC_StopInIdleEnable(OC_MODULE_ID index); Returns None. Description This function discontinues Output Compare module operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_OC_ID OC_ID_1 PLIB_OC_StopInIdleEnable(MY_OC_ID); Parameters Parameters Description index Identifies the desired Output Compare module Function void PLIB_OC_StopInIdleEnable( OC_MODULE_ID index ) e) Faults Functions PLIB_OC_FaultHasOccurred Function Checks if a PWM fault has occurred. File plib_oc.h C bool PLIB_OC_FaultHasOccurred(OC_MODULE_ID index); Returns • true - PWM Fault has occurred • false - No PWM fault has occurred Description This function returns 'true' if a PWM Fault has occurred and 'false' if no Fault condition exists. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsFaultStatus in your application to determine whether this feature is available. Preconditions This function should be used only in Edge or Center-Aligned PWM mode set by the PLIB_OC_ModeSelect() function. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1284 Example #define MY_OC_ID OC_ID_1 if(!PLIB_OC_FaultHasOccurred(MY_OC_ID)) { // Do some operation }; Parameters Parameters Description index Identifies the desired Output Compare module Function bool PLIB_OC_FaultHasOccurred( OC_MODULE_ID index) PLIB_OC_FaultInputSelect Function Enables/Disables the Fault input for the Output Compare PWM mode. File plib_oc.h C void PLIB_OC_FaultInputSelect(OC_MODULE_ID index, OC_FAULTS flt); Returns None. Description This function enables/disables the Fault input for the Output Compare PWM mode. If some other mode was selected using PLIB_OC_ModeSelect, the mode selected by PLIB_OC_ModeSelect will be overwritten as PLIB_OC_FaultInputSelect selects PWM mode with/without Fault protection. Fault input is valid if the fault pin is enabled in the hardware. If a logic '0' is detected on the OCFA/OCFB pin, the selected PWM output pin(s) are placed in the tri-state. The user may elect to provide a pull-down or pull-up resistor on the PWM pin to provide for a desired state if a Fault condition occurs. The shutdown of the PWM output is immediate and is not tied to the device clock source. Fault occurrence can be detected by calling the function PLIB_OC_FaultHasOccurred. The Output Compare module will be disabled until the following conditions are met: • The external Fault condition has been removed • The PWM mode is re-enabled Remarks This function selects the PWM mode of the Output Compare module with Fault protection or without Fault protection. These modes can be selected using PLIB_OC_ModeSelect also. If any other Output Compare mode is selected prior to this function, that mode will be overwritten as this feature is available for PWM mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsFaultInput in your application to determine whether this feature is available. Preconditions Fault pin: OCFA for OC_ID_1 to OC_ID_4 , OCFB for OC_ID_5 in MX devices. OCFA for OC_ID_1 to OC_ID_3 and OC_ID_7 to OC_ID_9 , OCFB for OC_ID_4 to OC_ID_6 in MZ devices. should be enabled in the hardware if enabling the fault input, that is if selecting the OC_FAULT_PRESET. Example #define MY_OC_ID OC_ID_1 // Fault pin is enabled in the hardware // This function selects PWM with fault protection mode for MY_OC_ID instance. PLIB_OC_FaultInputSelect(MY_OC_ID, OC_FAULT_PRESET); // Output Compare fault input is now enabled for Output Compare Module Parameters Parameters Description index Identifies the desired Output Compare module flt Identifies the Output Compare module Fault input Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1285 Function void PLIB_OC_FaultInputSelect( OC_MODULE_ID index, OC_FAULTS flt) f) Feature Existence Functions PLIB_OC_ExistsAlternateClock Function Identifies whether the AlternateClock feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsAlternateClock(OC_MODULE_ID index); Returns • true - The AlternateClock feature is supported on the device • false - The AlternateClock feature is not supported on the device Description This function identifies whether the AlternateClock feature is available on the Output Compare module. When this function returns true, these functions are supported on the device: • PLIB_OC_AlternateClockEnable • PLIB_OC_AlternateClockDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OC_ExistsAlternateClock( OC_MODULE_ID index ) PLIB_OC_ExistsBufferSize Function Identifies whether the BufferSize feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsBufferSize(OC_MODULE_ID index); Returns • true - If the BufferSize feature is supported on the device • false - If the BufferSize feature is not supported on the device Description This function identifies whether the BufferSize feature is available on the Output Compare module. When this function returns true, this function is supported on the device: • PLIB_OC_BufferSizeSelect Remarks None. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1286 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsBufferSize( OC_MODULE_ID index ) PLIB_OC_ExistsBufferValue Function Identifies whether the BufferValue feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsBufferValue(OC_MODULE_ID index); Returns • true - If the BufferValue feature is supported on the device • false - If the BufferValue feature is not supported on the device Description This function identifies whether the BufferValue feature is available on the Output Compare module. When this function returns true, these functions are supported on the device: • PLIB_OC_Buffer32BitSet • PLIB_OC_Buffer16BitSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsBufferValue( OC_MODULE_ID index ) PLIB_OC_ExistsCompareModeSelect Function Identifies whether the CompareModeSelect feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsCompareModeSelect(OC_MODULE_ID index); Returns • true - If the CompareModeSelect feature is supported on the device • false - If the CompareModeSelect feature is not supported on the device Description This function identifies whether the CompareModeSelect feature is available on the Output Compare module. When this function returns true, this function is supported on the device: Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1287 • PLIB_OC_ModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsCompareModeSelect( OC_MODULE_ID index ) PLIB_OC_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsEnableControl(OC_MODULE_ID index); Returns • true - If the EnableControl feature is supported on the device • false - If the EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the Output Compare module. When this function returns true, these functions are supported on the device: • PLIB_OC_Enable • PLIB_OC_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsEnableControl( OC_MODULE_ID index ) PLIB_OC_ExistsFaultInput Function Identifies whether the FaultInput feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsFaultInput(OC_MODULE_ID index); Returns • true - If the FaultInput feature is supported on the device • false - If the FaultInput feature is not supported on the device Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1288 Description This function identifies whether the FaultInput feature is available on the Output Compare module. When this function returns true, this function is supported on the device: • PLIB_OC_FaultInputSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsFaultInput( OC_MODULE_ID index ) PLIB_OC_ExistsFaultStatus Function Identifies whether the FaultStatus feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsFaultStatus(OC_MODULE_ID index); Returns • true - If the FaultStatus feature is supported on the device • false - If the FaultStatus feature is not supported on the device Description This function identifies whether the FaultStatus feature is available on the Output Compare module. When this function returns true, this function is supported on the device: • PLIB_OC_FaultHasOccurred Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsFaultStatus( OC_MODULE_ID index ) PLIB_OC_ExistsPulseWidth Function Identifies whether the PulseWidth feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsPulseWidth(OC_MODULE_ID index); Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1289 Returns • true - If the PulseWidth feature is supported on the device • false - If the PulseWidth feature is not supported on the device Description This function identifies whether the PulseWidth feature is available on the Output Compare module. When this function returns true, these functions are supported on the device: • PLIB_OC_PulseWidth32BitSet • PLIB_OC_PulseWidth16BitSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsPulseWidth( OC_MODULE_ID index ) PLIB_OC_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsStopInIdle(OC_MODULE_ID index); Returns • true - If the StopInIdle feature is supported on the device • false - If the StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the Output Compare module. When this function returns true, these functions are supported on the device: • PLIB_OC_StopInIdleEnable • PLIB_OC_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsStopInIdle( OC_MODULE_ID index ) PLIB_OC_ExistsTimerSelect Function Identifies whether the TimerSelect feature exists on the Output Compare module. Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1290 File plib_oc.h C bool PLIB_OC_ExistsTimerSelect(OC_MODULE_ID index); Returns • true - If the TimerSelect feature is supported on the device • false - If the TimerSelect feature is not supported on the device Description This function identifies whether the TimerSelect feature is available on the Output Compare module. When this function returns true, this function is supported on the device: • PLIB_OC_TimerSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsTimerSelect( OC_MODULE_ID index ) PLIB_OC_ExistsAlternateTimerSelect Function Identifies whether the AlternateTimerSelect feature exists on the Output Compare module. File plib_oc.h C bool PLIB_OC_ExistsAlternateTimerSelect(OC_MODULE_ID index); Returns • true - If the AlternateTimerSelect feature is supported on the device • false - If the AlternateTimerSelect feature is not supported on the device Description This function identifies whether the AlternateTimerSelect feature is available on the Output Compare module. When this function returns true, this function is supported on the device: • PLIB_OC_AlternateTimerSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function bool PLIB_OC_ExistsAlternateTimerSelect( OC_MODULE_ID index ) Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1291 g) Data Types and Constants OC_16BIT_TIMERS Enumeration Lists different 16 bit time bases for Output Compare module. File plib_oc_help.h C typedef enum { OC_TIMER_16BIT_TMR2, OC_TIMER_16BIT_TMR3 } OC_16BIT_TIMERS; Members Members Description OC_TIMER_16BIT_TMR2 Clock source of Timer2 is the clock source of Output Compare module OC_TIMER_16BIT_TMR3 Clock source of Timer3 is the clock source of Output Compare module Description Output Compare 16-bit Timer Select This enumeration lists different 16 bit time bases for Output Compare module. The time base is set by the PLIB_OC_TimerSelect function. OC_BUFFER_SIZE Enumeration Lists different buffer sizes for compare value. File plib_oc_help.h C typedef enum { OC_BUFFER_SIZE_16BIT, OC_BUFFER_SIZE_32BIT } OC_BUFFER_SIZE; Members Members Description OC_BUFFER_SIZE_16BIT Buffer size is 16-bits. Duty cycle and compare values will have 16-bit values. OC_BUFFER_SIZE_32BIT Buffer size is 32-bits. Duty cycle and compare values will have 32-bit values. Description Output Compare Buffer Size This enumeration lists different buffer sizes for compare value and duty cycle value. OC_COMPARE_MODES Enumeration Lists the different compare modes for the Output Compare module. File plib_oc_help.h C typedef enum { OC_COMPARE_PWM_MODE_WITH_FAULT_PROTECTION, OC_COMPARE_PWM_MODE_WITHOUT_FAULT_PROTECTION, OC_COMPARE_PWM_EDGE_ALIGNED_MODE, OC_DUAL_COMPARE_CONTINUOUS_PULSE_MODE, OC_DUAL_COMPARE_SINGLE_PULSE_MODE, Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1292 OC_TOGGLE_CONTINUOUS_PULSE_MODE, OC_SET_LOW_SINGLE_PULSE_MODE, OC_SET_HIGH_SINGLE_PULSE_MODE, OC_COMPARE_TURN_OFF_MODE } OC_COMPARE_MODES; Members Members Description OC_COMPARE_PWM_MODE_WITH_FAULT_PROTECTION Output Compare module output is PWM signal and is fault protected if fault protection pin is enabled. Fault protection is valid if the fault pin is enabled in the hardware. Fault pin: OCFA for OC_ID_1 to OC_ID_4 , OCFB for OC_ID_5 in MX devices. OCFA for OC_ID_1 to OC_ID_3 and OC_ID_7 to OC_ID_9 , OCFB for OC_ID_4 to OC_ID_6 in PIC32MZ devices. If a logic ‘0’ is detected on the OCFA/OCFB pin, the selected PWM output pin(s) are placed in the tri-state. The user may elect to provide a pull-down or pull-up resistor on the PWM pin to provide for a desired state if a Fault condition occurs. The shutdown of the PWM output is immediate and is not tied to the device clock source. Fault occurrence can be detected by calling the function PLIB_OC_FaultHasOccurred. The Output Compare will be disabled until the following conditions are met: 1. The external Fault condition has been removed 2. The PWM mode is re-enabled OC_COMPARE_PWM_MODE_WITHOUT_FAULT_PROTECTION Output Compare module output is PWM signal and is not fault protected OC_COMPARE_PWM_EDGE_ALIGNED_MODE This element is obsolete and it will be removed from next release OC_DUAL_COMPARE_CONTINUOUS_PULSE_MODE Dual Compare, Continuous Pulse mode: Output Compare module output is driven high on compare match with primary compare value and driven low on compare match with secondary compare value. A continuous stream of pulses is generated unless the compare mode is changed or the module is disabled. If the secondary compare value is greater than time base period value, secondary compare match does not occur. As a consequence, Output Compare module output stays high. OC_DUAL_COMPARE_SINGLE_PULSE_MODE Dual Compare, Single Pulse mode: Output Compare module output is driven high on compare match with primary compare value and driven low on compare match with secondary compare value. If the secondary compare value is greater than time base period value, secondary compare match does not occur. As a consequence, Output Compare module output stays high until a mode change is made or module is disabled OC_TOGGLE_CONTINUOUS_PULSE_MODE Single Compare Toggle mode: Output Compare module output is initialized to Low. Output Compare module output toggles at every compare match event with primary compare value with a single peripheral bus clock cycle delay. This scheme generates a square wave with 50% duty cycle. An interrupt is generated each time the output toggles. OC_SET_LOW_SINGLE_PULSE_MODE Single Compare Set Low mode: A compare match event with primary compare value will set the output of Output Compare module 'Low' with a single peripheral bus clock cycle delay. Output stays Low unless Output Compare module is disabled or a new compare mode is chosen. An interrupt is generated at compare match event. Output Compare module output is initially forced High. OC_SET_HIGH_SINGLE_PULSE_MODE Single Compare Set High mode: A compare match event with primary compare value will set the output of Output Compare module 'High' with a single peripheral bus clock cycle delay. Output stays High unless Output Compare module is disabled or a new compare mode is chosen. An interrupt is generated at compare match event. Output Compare module output is initially forced Low. OC_COMPARE_TURN_OFF_MODE Turn OFF mode: Output Compare module is disabled but still draws current. This mode is used to temporarily turn OFF the Output Compare module before a new compare mode is selected Description Output Compare Compare Modes This enumeration lists different compare modes for Output Compare module. The compare mode is set by the PLIB_OC_ModeSelect function. OC_FAULTS Enumeration Lists different fault sources for Output Compare module File plib_oc_help.h Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1293 C typedef enum { OC_FAULT_PRESET, OC_FAULT_DISABLE } OC_FAULTS; Members Members Description OC_FAULT_PRESET Enable Fault protection. PWM operation with fault protection. OC_FAULT_DISABLE Disable Fault protection. PWM operation without faults. Description Output Compare Fault Select This enumeration lists different fault sources for Output Compare module. The fault source is selected by the PLIB_OC_FaultInputSelect function. OC_MODULE_ID Enumeration File plib_oc_help.h C typedef enum { OC_ID_1, OC_ID_2, OC_ID_3, OC_ID_4, OC_ID_5, OC_ID_6, OC_ID_7, OC_ID_8, OC_ID_9, OC_NUMBER_OF_MODULES } OC_MODULE_ID; Members Members Description OC_NUMBER_OF_MODULES The total number of modules available. Description OC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to determine the correct number of modules defined for the desired microcontroller. OC_ALT_TIMERS Enumeration Lists the different 16-bit alternate timers for the Output Compare module. File plib_oc_help.h C typedef enum { OC_ALT_TIMER_TMR2, OC_ALT_TIMER_TMR3, OC_ALT_TIMER_TMR4, OC_ALT_TIMER_TMR5, OC_ALT_TIMER_TMR6, OC_ALT_TIMER_TMR7 } OC_ALT_TIMERS; Peripheral Libraries Help Output Compare Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1294 Members Members Description OC_ALT_TIMER_TMR2 Select Timer2 as the alternate clock source for Output Compare module OC_ALT_TIMER_TMR3 Select Timer3 as the alternate clock source for Output Compare module OC_ALT_TIMER_TMR4 Select Timer4 as the alternate clock source for Output Compare module OC_ALT_TIMER_TMR5 Select Timer5 as the alternate clock source for Output Compare module OC_ALT_TIMER_TMR6 Select Timer6 as the alternate clock source for Output Compare module OC_ALT_TIMER_TMR7 Select Timer7 as the alternate clock source for Output Compare module Description Output Compare 16-bit alternate Timer Select This enumeration lists the different 16-bit timers for the Output Compare time base when the Output Compare module is configured with a 16-bit alternate timer resource. Files Files Name Description plib_oc.h This file contains the interface definition for the Output Compare Peripheral Library. plib_oc_help.h This is file plib_oc_help.h. Description This section lists the source and header files used by the library. plib_oc.h This file contains the interface definition for the Output Compare Peripheral Library. Functions Name Description PLIB_OC_AlternateClockDisable Selects Timer 2/3, instead of the alternate clock source. PLIB_OC_AlternateClockEnable Selects the alternate clock source. PLIB_OC_AlternateTimerSelect Selects an alternate timer as a clock source for the Output Compare module. PLIB_OC_Buffer16BitSet Sets a 16-bit primary compare value for compare operations. PLIB_OC_Buffer32BitSet Sets a 32-bit primary compare value for compare operations. PLIB_OC_BufferSizeSelect Sets the buffer size and pulse width to 16-bits or 32-bits. PLIB_OC_Disable Disable the Output Compare module. PLIB_OC_Enable Enables the Output Compare module. PLIB_OC_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the Output Compare module. PLIB_OC_ExistsAlternateTimerSelect Identifies whether the AlternateTimerSelect feature exists on the Output Compare module. PLIB_OC_ExistsBufferSize Identifies whether the BufferSize feature exists on the Output Compare module. PLIB_OC_ExistsBufferValue Identifies whether the BufferValue feature exists on the Output Compare module. PLIB_OC_ExistsCompareModeSelect Identifies whether the CompareModeSelect feature exists on the Output Compare module. PLIB_OC_ExistsEnableControl Identifies whether the EnableControl feature exists on the Output Compare module. PLIB_OC_ExistsFaultInput Identifies whether the FaultInput feature exists on the Output Compare module. PLIB_OC_ExistsFaultStatus Identifies whether the FaultStatus feature exists on the Output Compare module. PLIB_OC_ExistsPulseWidth Identifies whether the PulseWidth feature exists on the Output Compare module. PLIB_OC_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the Output Compare module. PLIB_OC_ExistsTimerSelect Identifies whether the TimerSelect feature exists on the Output Compare module. PLIB_OC_FaultHasOccurred Checks if a PWM fault has occurred. PLIB_OC_FaultInputSelect Enables/Disables the Fault input for the Output Compare PWM mode. PLIB_OC_IsEnabled Checks whether the Output Compare module is enabled or not. PLIB_OC_ModeSelect Selects the compare mode for the Output Compare module. PLIB_OC_PulseWidth16BitSet Sets a 16-bit pulse width for Output Compare module output. PLIB_OC_PulseWidth32BitSet Sets a 32-bit pulse width for Output Compare module output. Peripheral Libraries Help Output Compare Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1295 PLIB_OC_StopInIdleDisable Output Compare module continues operating when the device enters Idle mode. PLIB_OC_StopInIdleEnable Discontinues Output Compare module operation when the device enters Idle mode. PLIB_OC_TimerSelect Selects a clock source for the Output Compare module. Description Output Compare Module Peripheral Library Interface Header This library provides a low-level abstraction of the Output Compare module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences between one microcontroller variant and another. File Name plib_oc.h Company Microchip Technology Inc. plib_oc_help.h Enumerations Name Description OC_16BIT_TIMERS Lists different 16 bit time bases for Output Compare module. OC_ALT_TIMERS Lists the different 16-bit alternate timers for the Output Compare module. OC_BUFFER_SIZE Lists different buffer sizes for compare value. OC_COMPARE_MODES Lists the different compare modes for the Output Compare module. OC_FAULTS Lists different fault sources for Output Compare module OC_MODULE_ID OC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to determine the correct number of modules defined for the desired microcontroller. Description This is file plib_oc_help.h. Peripheral Libraries Help Output Compare Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1296 Oscillator Peripheral Library This section describes the Oscillator Peripheral Library. Introduction This library provides a low-level abstraction of the Oscillator module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The Oscillator is the heart of the microcontroller and provides the clock on which the core and the peripherals run. For all of the oscillators present on a Microchip microcontroller, two kinds of configurations exist: • Through Configuration bits • At execution time The first is through 'Configuration bits', which is a one-time configuration done during the programming of the device. These one-time configurations are programmed in the code memory. The other is 'Execution time' configuration, which deals with features that are allowed to be changed during run-time. This peripheral library provides functions which deal only with the 'execution time' configurable features of the Oscillator module. Certain Oscillator module features can only be selected through 'Configuration bits'. However, most of the features can be altered during run-time by using the functions provided in this library. Using the Library This topic describes the basic architecture of the Oscillator Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_osc.h The interface to the Oscillator Peripheral Library is defined in the plib_osc.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Oscillator Peripheral Library must include peripheral.h. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the Oscillator module on Microchip microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model The Oscillator hardware model is shown in the following figure. The blocks represented in dashed lines may not be present in all microcontrollers. Refer to the "Oscillator" chapter in the specific device data sheet to determine availability. Peripheral Libraries Help Oscillator Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1297 To understand the Oscillator module and how each feature is mapped in this library, it is important to understand the following terminology. Clock Source A clock source is hardware that generates oscillations, which may be internal or external. Divisor and Multiplier/PLL These are hardware modules that can scale the clock. The rate at which the scaling is done may be fixed or configurable. Clock Outputs Clock outputs means output lines from the Oscillator module, which may route to different modules of the device or to the CPU (i.e., the system clock). The following diagram provides a simplified explanation and the relationship between the previously mentioned terms. In most cases, there are multiple clock source options available for each of the clock outputs. However, not all the clock sources are available for all the output clocks. Scaling is an optional feature in most of the cases. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Output Compare module. Library Interface Section Description General Setup Functions Provides General Configurations • Operation on a WAIT instruction • System clock source selection Primary Oscillator Setup Functions Provides Configuration Routines for the Primary Oscillator: • Primary Oscillator Sleep Enable Peripheral Libraries Help Oscillator Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1298 Secondary Oscillator Setup Functions Provides Configuration Routines for the Secondary Oscillator: • Secondary Oscillator Enable/Disable • Secondary Oscillator Ready Indicator Auxiliary Oscillator Setup Functions Provides Configuration Routines for the Auxiliary Oscillator Configuration: • Reference Clock Source for Auxiliary Clock • Auxiliary Oscillator Mode Selection Reference Oscillator Setup Functions Provides Configuration Routines for the Reference Oscillator Configuration: • Reference Oscillator Output Enable/Disable • Select Reference Oscillator Output Divider • Reference Oscillator Clock Source Selection • Configure Reference Oscillator in Sleep Mode Fast RC (FRC) Oscillator Setup Functions Provides Configuration Routines for FRC Oscillator: • FRC Oscillator clock divider selection • FRC Oscillator tuning Oscillator Switch Setup Functions Provides Configuration Routines for Oscillator Switch and New Oscillator Selection: • Initiate an oscillator switch • Select the new oscillator • Get the current oscillator selection bits Doze Setup Functions Provides Configuration Routines for Doze mode Configuration • Enable/Disable Doze mode • Select DOZE (CPU Peripheral Clock Ratio) bits USB and Display Clock Setup Functions Provides Configuration Routines for USB and Display Clock Configuration: • Select FRC as USB Clock • Select Graphics Controller Clock • Display Module Clock Divider Selection PLL Setup Functions Provides Configuration Routines for PLL (Including USB and Auxiliary PLL) • PLL Multiplier • PLL Output Divider • 96 MHz PLL Enable for USB/Graphics Clock • Auxiliary PLL Input Divider • Auxiliary PLL Output Divider • Auxiliary PLL Multiplier • Auxiliary PLL Enable/Disable • PLL and USB PLL Lock Status Peripheral Clock Setup Functions Provides Configuration Routines for the Peripheral Clock • Set Peripheral Block Clock Divisor Clock Fail Monitoring Functions Provides Routines for Clock Fail Monitoring • Clock Fail Detect Status Feature Existence Functions Provides interface routines that determine whether certain features are available. How the Library Works The library can be used to control the Oscillator module. The usage model is explained in this section. Description The following diagram shows the major components of the usage model: Oscillator Selection and Switching Note: The device Configuration options change with the microcontroller family. Refer to the "Oscillator" chapter in the specific device data sheet for possible device configurations. Peripheral Libraries Help Oscillator Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1299 On devices that allow it, the oscillator selection can be overridden at run-time using the Oscillator Peripheral Library, as shown in the following code example: //Do the configuration bit settings OSC_SYS_TYPE currOsc; OSC_SYS_TYPE newOsc=OSC_PRIMARY; //get the current oscillator currOsc = PLIB_OSC_CurrentSysClockGet(OSC_ID_0); //check if the current oscillator is same as new oscillator if(currOsc != newOsc) { // Unlock the Oscillator Registers PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); //set the new oscillator request to Fast RC oscillator PLIB_OSC_SysClockSelect ( OSC_ID_0, newOsc ); } Example: Oscillator Selection Change During Run-time In the event the clock switch did not complete, the clock switch logic can be reset by calling the following API: bool oscSwitch_st; oscSwitch_st = PLIB_OSC_ClockSwitchingIsComplete(OSC_ID_0); if(!oscSwitch_st) { // Unlock the Oscillator Registers PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); PLIB_OSC_ClockSwitchingAbort(OSC_ID_0); } Example: Oscillator Switch Abort This will abandon the clock switch process, stop and reset the oscillator start-up timer (if applicable), and stop the PLL (if applicable). The clock switch process can be aborted at any time. A clock switch that is already in progress can also be aborted by performing a second clock switch. Clock Sources This section explains the available clock sources and their setup. The following clock sources are available in Microchip microcontrollers: • Primary Oscillator (Posc) • Secondary Oscillator (Sosc) • Internal Fast RC (FRC) Oscillator • Internal Low-Power RC (LPRC) Oscillator Primary Oscillator (Posc) The Primary Oscillator has several operating modes (refer to the "Oscillator" chapter in the specific device data sheet for exact operating modes). The selection of the operating mode is done using the device Configuration registers during device programming. During run-time this can be changed using the oscillator switch option. However, changing the operating mode from High Gain (HC) to External Clock (EC) or External Resonator(XT) is not possible. If a PLL is available, the PLL input divider can only be programmed during device programming. However, the PLL output divider and the PLL multiplier can be changed during run-time using the PLL functions described in the PLL section. Secondary Oscillator (Sosc) The optional Secondary Oscillator is designed specifically for low-power operation with an external crystal. The Secondary Oscillator is enabled in hardware by the device Configuration bits. Once it is enabled in hardware, it can be switched on during software run-time. bool oscSecondary_st; oscSecondary_st = PLIB_OSC_SecondaryIsEnabled(OSC_ID_0); if(oscSecondary_st) { // Unlock the Oscillator Registers PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); PLIB_OSC_SecondaryDisable(OSC_ID_0); } Peripheral Libraries Help Oscillator Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1300 Internal Fast RC (FRC) Oscillator The FRC Oscillator is a fast user-trimmable internal RC oscillator with a user-selectable input divider, PLL multiplier, and output divider. See the "Oscillator" chapter in the specific device data sheet for more information on the FRC oscillator. Once the FRC oscillator is selected using the device Configuration registers or an oscillator switch is initiated selecting the FRC as a new oscillator, the FRC Oscillator PLL divider can be changed during run-time. OSC_FRC_DIV FRCDivisor; //Get the current divider value for FRC FRCDivisor = PLIB_OSC_FRCDivisorGet(OSC_ID_0); if(FRCDivisor != OSC_FRC_DIV_4) { // Unlock the Oscillator Registers PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); PLIB_OSC_FRCDivisorSelect ( OSC_ID_0, OSC_FRC_DIV_4 ); } Internal Low-Power RC (LPRC) Oscillator The LPRC Oscillator is separate from the FRC Oscillator. It oscillates at a nominal frequency of 31.25 kHz (this value is device-dependent). The LPRC Oscillator can act as the clock source for the Power-up Timer (PWRT), Watchdog Timer (WDT), Fail-Safe Clock Monitor (FSCM), and PLL reference circuits. It can also be used to provide a low-frequency clock source option for the device in those applications where power consumption is critical and timing accuracy is not required. The LPRC remains enabled after power on in the following conditions: • Fail-safe clock monitoring is enabled • Watchdog Timer is enabled • LPRC is selected as the system clock PLL Configuration OSC_SYSPLL_OUT_DIV PLLOutDiv; OSC_SYSPLL_MULTIPLIER pll_multiply; // Unlock the Oscillator Registers PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); pll_multiply = PLIB_OSC_SysPLLMultiplierGet(OSC_ID_0); if(pll_multiply != 15) { PLIB_OSC_SysPLLMultiplierSelect(OSC_ID_0, 15); } PLLOutDiv = PLIB_OSC_SysPLLOutputDivisorGet(OSC_ID_0); if(PLLOutDiv != OSC_SYSPLL_OUT_DIV_8) { PLIB_OSC_SysPLLOutputDivisorSelect(OSC_ID_0, OSC_SYSPLL_OUT_DIV_8); } Fail-Safe Clock Monitor Fail-Safe Clock Monitor (FSCM) The Fail-Safe Clock Monitor (FSCM) is designed to allow continued device operation if the current oscillator fails. It is intended for use with the Primary Oscillator (Posc) and automatically switches to the FRC oscillator if a Posc failure is detected. The switch to the FRC oscillator allows continued device operation and the ability to retry the Posc or to execute the appropriate for a clock failure. The FSCM can be enabled in the device configuration during the programming of the device. During run-time, the clock failure status can be obtained as follows: bool clockFail; //Returns true if clock failure is detected. clockFail = PLIB_OSC_ClockHasFailed(OSC_ID_0); Internal FRC Oscillator Tuning Tuning the Oscillator Peripheral Libraries Help Oscillator Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1301 Oscillator tuning will help compensate for temperature effects on the FRC frequency over a wide range of temperatures. The tuning step size is an approximation, the application is supposed to try different values to achieve the best result. In some of the devices there are different tuning modes available. Direct Number Method FRC tuning is based on the number specified by the PLIB_OSC_FRCTuningSelect function. PLIB_OSC_FRCTuningModeSet(OSC_ID_0, OSC_TUNING_USING_NUMBER); PLIB_OSC_FRCTuningSelect(OSC_ID_0, 0x11); Sequential Dithering To get the sequential dithering working, the client needs to set eight sequencer values. Value 0 is set using the PLIB_OSC_FRCTuningSelect function. The other seven values (values 1 through 7) are set using the PLIB_OSC_FRCTuningSequenceValueSet function. // Unlock the Oscillator Registers PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); PLIB_OSC_FRCTuningModeSet(OSC_ID_0, OSC_TUNING_SEQ_DITHER); PLIB_OSC_FRCTuningSelect(OSC_ID_0, 0x11); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_1, OSC_FRC_TUNE_MINUS_2_25_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_2, OSC_FRC_TUNE_MINUS_1_5_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_3, OSC_FRC_TUNE_MINUS_0_375_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_4, OSC_FRC_TUNE_PLUS_0_43_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_5, OSC_FRC_TUNE_PLUS_1_29_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_6, OSC_FRC_TUNE_PLUS_2_54_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_7, OSC_FRC_TUNE_MINUS_3_PERCENT); //Configure PWM (period, pulse width and turn on the module) Pseudo-Random Number Select the tuning mode. Then, configure the PWM module and set the period and pulse width. The Oscillator system generates a 4-bit number based on a pseudo-random number generation algorithm. It then uses this value to tune the FRC oscillator. The module will generate different frequencies corresponding to the generated pseudo-random numbers every eighth PWM cycle. PLIB_OSC_FRCTuningModeSet(OSC_ID_0, OSC_TUNING_PSEUDO_RANDOM); //15 bit Linear Feedback shift register value PLIB_OSC_LinearFeedbackShiftRegSet(OSC_ID_0, 0x7FFF); //Configure PWM (period, pulse width and turn on the module) Configuring the Library The library is configured for the supported Oscillator module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Setup Functions Name Description PLIB_OSC_OnWaitActionGet Gets the configured operation to be performed when a WAIT instruction is executed. PLIB_OSC_OnWaitActionSet Selects the operation to be performed when a WAIT instruction is executed. PLIB_OSC_SlewDisable Disables the selected type of slewing. PLIB_OSC_SlewDivisorStepGet Get the slew divisor maximum step. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1302 PLIB_OSC_SlewDivisorStepSelect Selects division steps used while slewing. PLIB_OSC_SlewEnable Enables the selected type of slewing. PLIB_OSC_SlewIsEnabled Returns 'true' if the reference oscillator is disabled in Idle mode. PLIB_OSC_SleepToStartupClockGet Returns the clock used for the duration when the device wakes from sleep and the clock ready. PLIB_OSC_SleepToStartupClockSelect Selects the clock duration for when the device wakes from sleep and the clock is ready. PLIB_OSC_DreamModeDisable Disables the dream mode. PLIB_OSC_DreamModeEnable Enables the dream mode. PLIB_OSC_DreamModeStatus gets the status of the dream mode. b) Primary Oscillator Setup Functions Name Description PLIB_OSC_ClockIsReady Get the ready status of clock. PLIB_OSC_ClockSlewingIsActive Returns the status of clock slewing. PLIB_OSC_SystemClockDivisorGet Get the system clock divisor value. PLIB_OSC_SystemClockDivisorSelect Selects system clock divisor. c) Secondary Oscillator Setup Functions Name Description PLIB_OSC_SecondaryDisable Disables the Secondary Oscillator. PLIB_OSC_SecondaryEnable Enables the Secondary Oscillator. PLIB_OSC_SecondaryIsEnabled Returns 'true' if the Secondary Oscillator is enabled. PLIB_OSC_SecondaryIsReady Returns 'true' if the Secondary Oscillator is ready. d) Reference Oscillator Setup Functions Name Description PLIB_OSC_ReferenceOscBaseClockSelect Sets the base clock for the reference oscillator. PLIB_OSC_ReferenceOscDisable Disables the reference oscillator output. PLIB_OSC_ReferenceOscDivisorValueSet Selects the reference oscillator divisor value. PLIB_OSC_ReferenceOscEnable Enables the reference oscillator. PLIB_OSC_ReferenceOscIsEnabled Gets the enable status of the reference oscillator output. PLIB_OSC_ReferenceOscSourceChangeIsActive Returns 'true' if a reference oscillator source change request is active. PLIB_OSC_ReferenceOscStopInIdleDisable Enables the reference oscillator in Idle mode. PLIB_OSC_ReferenceOscStopInIdleEnable Configures the reference oscillator to stop operating in Idle mode. PLIB_OSC_ReferenceOscStopInIdleIsEnabled Returns 'true' if the reference oscillator is disabled in Idle mode. PLIB_OSC_ReferenceOscStopInSleepDisable Enables the reference oscillator in Sleep mode. PLIB_OSC_ReferenceOscStopInSleepEnable Configures the reference oscillator to stop operating in Sleep mode. PLIB_OSC_ReferenceOscStopInSleepIsEnabled Returns 'true' if the reference oscillator is disabled in Sleep mode. PLIB_OSC_ReferenceOscSwitchIsComplete Returns 'true' if the reference oscillator base clock switching is complete. PLIB_OSC_ReferenceOscTrimSet Sets the reference oscillator divisor trim value. PLIB_OSC_ReferenceOutputDisable Disables the reference oscillator output. PLIB_OSC_ReferenceOutputEnable Enables the reference oscillator output. PLIB_OSC_ReferenceOutputIsEnabled Returns 'true' if the reference oscillator output is enabled. e) Fast RC Oscillator Setup Functions Name Description PLIB_OSC_FRCDivisorGet Gets the FRC clock divisor. PLIB_OSC_FRCDivisorSelect Sets the FRC clock divisor to the specified value. PLIB_OSC_FRCTuningSelect Sets the FRC tuning value. f) Oscillator Switch Setup Functions Name Description PLIB_OSC_ClockSwitchingAbort Aborts an oscillator switch. PLIB_OSC_ClockSwitchingIsComplete Gets the oscillator switch progress status. PLIB_OSC_CurrentSysClockGet Gets the current oscillator selected. PLIB_OSC_SysClockSelect Selects the new oscillator. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1303 g) USB and Display Clock Setup Functions Name Description PLIB_OSC_UsbClockSourceGet Gets the USB module clock source. PLIB_OSC_UsbClockSourceSelect Sets the USB module clock source. h) PLL Setup Functions Name Description PLIB_OSC_PLLClockIsLocked Gets the lock status for the clock and PLL selections. PLIB_OSC_PLLClockLock Locks the clock and PLL selections. PLIB_OSC_PLLClockUnlock Unlocks the clock and PLL selections. PLIB_OSC_PLLIsLocked Returns 'true' if the selected PLL module is locked. PLIB_OSC_SysPLLFrequencyRangeGet Gets the frequency range for the PLL module. PLIB_OSC_SysPLLFrequencyRangeSet Sets the frequency range for the PLL module. PLIB_OSC_SysPLLInputClockSourceGet Gets the input clock source for the PLL module. PLIB_OSC_SysPLLInputClockSourceSet Sets the input clock source for the PLL module. PLIB_OSC_SysPLLInputDivisorGet Gets the input divisor for the PLL. PLIB_OSC_SysPLLMultiplierGet Gets the PLL multiplier. PLIB_OSC_SysPLLMultiplierSelect Sets the PLL multiplier to the specified value. PLIB_OSC_SysPLLOutputDivisorGet Gets the output divisor for the PLL. PLIB_OSC_SysPLLOutputDivisorSet Sets the output divider for the PLL to the specified value. PLIB_OSC_SysPLLInputDivisorSet Sets the input divider for the PLL to the specified value. PLIB_OSC_BTPLLClockOutDisable Disables the Bluetooth PLL Clock Output. PLIB_OSC_BTPLLClockOutEnable Enables the Bluetooth PLL clock Ouput. PLIB_OSC_BTPLLClockOutStatus gets the status of the Bluetooth PLL clock Output. PLIB_OSC_BTPLLFrequencyRangeGet Gets the frequency range for the Bluetooth PLL module. PLIB_OSC_BTPLLFrequencyRangeSet Sets the frequency range for the Bluetooth PLL module. PLIB_OSC_BTPLLInputClockSourceGet Gets the input clock source for the Bluetooth PLL module. PLIB_OSC_BTPLLInputClockSourceSet Sets the input clock source for the Bluetooth PLL module. PLIB_OSC_BTPLLInputDivisorGet Gets the input divisor for the Bluetooth PLL. PLIB_OSC_BTPLLInputDivisorSet Sets the input divider for the Bluetooth PLL to the specified value. PLIB_OSC_BTPLLMultiplierGet Gets the Bluetooth PLL multiplier. PLIB_OSC_BTPLLMultiplierSelect Sets the Bluetooth PLL multiplier to the specified value. PLIB_OSC_BTPLLOutputDivisorGet Gets the output divisor for the PLL. PLIB_OSC_BTPLLOutputDivisorSet Sets the output divider for the Bluetooth PLL to the specified value. PLIB_OSC_ForceSPLLLockDisable Disables the Force PLL Lock feature for specified PLL. PLIB_OSC_ForceSPLLLockEnable Enables the Force PLL Lock feature for specified PLL. PLIB_OSC_ForceSPLLLockStatus gets the status of the force PLL Lock bit of the specified PLL. PLIB_OSC_PLLBypassDisable Disables the PLL Bypass. PLIB_OSC_PLLBypassEnable Enables the PLL Bypass. PLIB_OSC_PLLBypassStatus gets the status of the PLL Bypass. PLIB_OSC_UPLLFrequencyRangeGet Gets the frequency range for the USB PLL module. PLIB_OSC_UPLLFrequencyRangeSet Sets the frequency range for the USB PLL module. PLIB_OSC_UPLLInputDivisorGet Gets the input divisor for the USB PLL. PLIB_OSC_UPLLInputDivisorSet Sets the input divider for the USB PLL to the specified value. PLIB_OSC_UPLLMultiplierGet Gets the USB PLL multiplier. PLIB_OSC_UPLLMultiplierSelect Sets the USB PLL multiplier to the specified value. PLIB_OSC_UPLLOutputDivisorGet Gets the output divisor for the PLL. PLIB_OSC_UPLLOutputDivisorSet Sets the output divider for the USB PLL to the specified value. PLIB_OSC_ResetPLLAssert Asserts the PLL reset for selected PLL. PLIB_OSC_ResetPLLDeassert Deasserts the PLL reset for selected PLL. PLIB_OSC_ResetPLLStatus gets the status of the PLL reset bit for the specified PLL. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1304 i) Peripheral Clock Setup Functions Name Description PLIB_OSC_PBClockDivisorGet Gets the peripheral bus clock divisor. PLIB_OSC_PBClockDivisorIsReady Checks whether the peripheral bus clock divisor is ready to be written. PLIB_OSC_PBClockDivisorSet Sets the peripheral bus clock divisor to the specified value. PLIB_OSC_PBOutputClockDisable Disables the peripheral bus output clock. PLIB_OSC_PBOutputClockEnable Enables the peripheral bus output clock PLIB_OSC_PBOutputClockIsEnabled Checks whether or not the peripheral bus clock output is enabled. j) Clock Functions Name Description PLIB_OSC_ClockHasFailed Returns 'true' if the clock fails. PLIB_OSC_ClockStart Starts the specified clock source. PLIB_OSC_ClockStop Stops the specified clock source. PLIB_OSC_ClockStopStatus returns the status of clock stop bit for the specified clock source. k) Feature Existence Functions Name Description PLIB_OSC_ExistsClockFail Identifies whether the ClockFail feature exists on the Oscillator module. PLIB_OSC_ExistsFRCDivisor Identifies whether the FRCDivisor feature exists on the Oscillator module. PLIB_OSC_ExistsFRCTuning Identifies whether the FRCTuning feature exists on the Oscillator module. PLIB_OSC_ExistsOnWaitAction Identifies whether the OnWaitAction feature exists on the Oscillator module. PLIB_OSC_ExistsOscCurrentGet Identifies whether the OscCurrentGet feature exists on the Oscillator module. PLIB_OSC_ExistsOscSelect Identifies whether the OscSelect feature exists on the Oscillator module. PLIB_OSC_ExistsOscSwitchInit Identifies whether the OscSwitchInit feature exists on the Oscillator module. PLIB_OSC_ExistsPBClockDivisor Identifies whether the PBClockDivisor feature exists on the Oscillator module. PLIB_OSC_ExistsPBClockOutputEnable Identifies whether the PBClockOutputEnable feature exists on the Oscillator module. PLIB_OSC_ExistsPBClockReady Identifies whether the PBClockReady feature exists on the Oscillator module. PLIB_OSC_ExistsPLLClockLock Identifies whether the PLLClockLock feature exists on the Oscillator module. PLIB_OSC_ExistsPLLLockStatus Identifies whether the PLLLockStatus feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscBaseClock Identifies whether the ReferenceOscBaseClock feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscChange Identifies whether the ReferenceOscChange feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscChangeActive Identifies whether the ReferenceOscChangeActive feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscDivisor Identifies whether the ReferenceOscDivisor feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscEnable Identifies whether the ReferenceOscEnable feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscStopInIdleEnable Identifies whether the ReferenceOscStopInIdleEnable feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscStopInSleep Identifies whether the ReferenceOscStopInSleep feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscTrim Identifies whether the ReferenceOscTrim feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOutputEnable Identifies whether the ReferenceOutputEnable feature exists on the Oscillator module. PLIB_OSC_ExistsSecondaryEnable Identifies whether the SecondaryEnable feature exists on the Oscillator module. PLIB_OSC_ExistsSecondaryReady Identifies whether the SecondaryReady feature exists on the Oscillator module. PLIB_OSC_ExistsSysPLLFrequencyRange Identifies whether the PLLFrequencyRange feature exists on the Oscillator module. PLIB_OSC_ExistsSysPLLInputClockSource Identifies whether the PLLInputClockSource feature exists on the Oscillator module. PLIB_OSC_ExistsSysPLLInputDivisor Identifies whether the PLLInputDivisor feature exists on the Oscillator module. PLIB_OSC_ExistsSysPLLMultiplier Identifies whether the PLLMultiplier feature exists on the Oscillator module. PLIB_OSC_ExistsSysPLLOutputDivisor Identifies whether the PLLOutputDivisor feature exists on the Oscillator module. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1305 PLIB_OSC_ExistsUsbClockSource Identifies whether the UsbClockSource feature exists on the Oscillator module. PLIB_OSC_ExistsClockReadyStatus Identifies whether the ClockReadyStatus feature exists on the Oscillator module. PLIB_OSC_ExistsClockSlewingStatus Identifies whether the ClockSlewingStatus feature exists on the Oscillator module. PLIB_OSC_ExistsSleepToStartupClock Identifies whether the SleepToStartupClock feature exists on the Oscillator module. PLIB_OSC_ExistsSlewDivisorStepControl Identifies whether the SlewDivisorStepControl feature exists on the Oscillator module. PLIB_OSC_ExistsSlewEnableControl Identifies whether the SlewEnableControl feature exists on the Oscillator module. PLIB_OSC_ExistsSystemClockDivisorControl Identifies whether the SystemClockDivisorControl feature exists on the Oscillator module. PLIB_OSC_ExistsBTPLLClockOut Identifies whether the BTPLLClockOut feature exists on the OSC module PLIB_OSC_ExistsBTPLLFrequencyRange Identifies whether the BTPLLFrequencyRange feature exists on the OSC module PLIB_OSC_ExistsBTPLLInputClockSource Identifies whether the BTPLLInputClockSource feature exists on the OSC module PLIB_OSC_ExistsBTPLLInputDivisor Identifies whether the BTPLLInputDivisor feature exists on the OSC module PLIB_OSC_ExistsBTPLLMultiplier Identifies whether the BTPLLMultiplier feature exists on the OSC module PLIB_OSC_ExistsBTPLLOutputDivisor Identifies whether the BTPLLOutputDivisor feature exists on the OSC module PLIB_OSC_ExistsClockDiagStatus Identifies whether the ClockDiagStatus feature exists on the OSC module PLIB_OSC_ExistsDreamModeControl Identifies whether the DreamModeControl feature exists on the OSC module PLIB_OSC_ExistsForceLock Identifies whether the ForceLock feature exists on the OSC module PLIB_OSC_ExistsPLLBypass Identifies whether the SPLLBypass feature exists on the OSC module PLIB_OSC_ExistsResetPLL Identifies whether the ResetPLL feature exists on the OSC module PLIB_OSC_ExistsUPLLFrequencyRange Identifies whether the UPLLFrequencyRange feature exists on the OSC module PLIB_OSC_ExistsUPLLInputDivisor Identifies whether the UPLLInputDivisor feature exists on the OSC module PLIB_OSC_ExistsUPLLMultiplier Identifies whether the UPLLMultiplier feature exists on the OSC module PLIB_OSC_ExistsUPLLOutputDivisor Identifies whether the UPLLOutputDivisor feature exists on the OSC module l) Data Types and Constants Name Description OSC_PB_CLOCK_DIV_TYPE Type of the oscillator PB Clock divisor value. OSC_REF_DIVISOR_TYPE Reference oscillator divisor type. OSC_REFERENCE_MAX_DIV Defines the reference clock output divisor maximum value. OSC_SYSPLL_MULTIPLIER_TYPE Type of the oscillator system PLL multiplier value. OSC_FRC_DIV Lists the possible Fast RC (FRC) Oscillator divider values. OSC_MODULE_ID Possible instances of the OSC module. OSC_OPERATION_ON_WAIT Lists the possible base clock values for the reference oscillator. OSC_PERIPHERAL_BUS Lists the possible Peripheral buses. OSC_PLL_SELECT Lists the PLLs in the Oscillator module. OSC_REFERENCE Lists the possible reference oscillator. OSC_SYS_TYPE Lists the possible oscillator type values. OSC_SYSPLL_FREQ_RANGE Lists the possible PLL frequency range. OSC_SYSPLL_IN_CLK_SOURCE Lists the possible input clock source for PLL module. OSC_SYSPLL_OUT_DIV Lists the possible PLL output divider values. OSC_USBCLOCK_SOURCE Lists the possible USB clock sources. OSC_CLOCK_ID Lists the clock sources for which ready status can be checked. OSC_CLOCK_SLEW_TYPE Lists the possible type of clock slewing. OSC_SLEEP_TO_STARTUP_CLK_TYPE Lists the possible clock sources for sleep to start-up period. Description This section describes the Application Programming Interface (API) functions of the Oscillator Peripheral Library. Refer to each section for a detailed description. a) General Setup Functions Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1306 PLIB_OSC_OnWaitActionGet Function Gets the configured operation to be performed when a WAIT instruction is executed. File plib_osc.h C OSC_OPERATION_ON_WAIT PLIB_OSC_OnWaitActionGet(OSC_MODULE_ID index); Returns On a WAIT action, one of the possible values of OSC_OPERATION_ON_WAIT. Description This function gets the configured operation that is to be performed when a WAIT instruction is executed. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOnWaitAction in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_OSC_OnWaitActionGet(OSC_ID_0) == OSC_ON_WAIT_SLEEP) { //Do some action } Parameters Parameters Description index Identifies the desired oscillator module Function OSC_OPERATION_ON_WAIT PLIB_OSC_OnWaitActionGet ( OSC_MODULE_ID index ) PLIB_OSC_OnWaitActionSet Function Selects the operation to be performed when a WAIT instruction is executed. File plib_osc.h C void PLIB_OSC_OnWaitActionSet(OSC_MODULE_ID index, OSC_OPERATION_ON_WAIT onWait); Returns None. Description This function selects the operation to be performed when a WAIT instruction is executed. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOnWaitAction in your application to determine whether this feature is available. If this function is not called, the device will enter Idle mode on execution of a WAIT instruction. Preconditions None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1307 Example PLIB_OSC_OnWaitActionSet(OSC_ID_0, OSC_ON_WAIT_SLEEP); Parameters Parameters Description index Identifies the desired oscillator module onWait Operation to be performed when a WAIT instruction is executed. One of the possible values of OSC_OPERATION_ON_WAIT. Function void PLIB_OSC_OnWaitActionSet ( OSC_MODULE_ID index, OSC_OPERATION_ON_WAIT onWait ) PLIB_OSC_SlewDisable Function Disables the selected type of slewing. File plib_osc.h C void PLIB_OSC_SlewDisable(OSC_MODULE_ID index, OSC_CLOCK_SLEW_TYPE slewType); Returns None. Description This function disables slewing to an upward or downward frequency based on the selection. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSlewEnableControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SlewDisable(OSC_ID_0, OSC_CLOCK_SLEW_DOWNWARD); Parameters Parameters Description index Identifies the desired oscillator module slewType One of the possible value from OSC_CLOCK_SLEW_TYPE Function void PLIB_OSC_SlewDisable ( OSC_MODULE_ID index, OSC_CLOCK_SLEW_TYPE slewType ) PLIB_OSC_SlewDivisorStepGet Function Get the slew divisor maximum step. File plib_osc.h C uint32_t PLIB_OSC_SlewDivisorStepGet(OSC_MODULE_ID index); Returns • slewSteps - Number of steps in which slewing is occurring Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1308 Description This function returns the number of division steps used when slewing during a frequency change. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSlewDivisorStepControl in your application to determine whether this feature is available. Preconditions None. Example uint32_t slewSteps; slewSteps = PLIB_OSC_SlewDivisorStepGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function uint32_t PLIB_OSC_SlewDivisorStepGet ( OSC_MODULE_ID index ) PLIB_OSC_SlewDivisorStepSelect Function Selects division steps used while slewing. File plib_osc.h C void PLIB_OSC_SlewDivisorStepSelect(OSC_MODULE_ID index, uint32_t slewSteps); Returns None. Description This API selects number of division steps to be used when slewing during a frequency change. If the number of steps chosen is 0, no divisor will be used while slewing. If the number of steps chosen is 1, slewing will start with divide by 2, and then no divisor. Similarly, if the number of steps chosen is 2, slewing will start with divisor 4. Then,after a few seconds the divisor will be 2, and then after a few more seconds no divisor will be used and so on. Therefore, the largest step would be equal to 2^(number of steps), and then the step size will reduce by half every few seconds. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSlewDivisorStepControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SlewDivisorStepSelect(OSC_ID_0, OSC_SLEW_DIVISOR_STEP_MAX_32); Parameters Parameters Description index Identifies the desired oscillator module slewSteps Number of steps in which slewing is desired Function void PLIB_OSC_SlewDivisorStepSelect Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1309 ( OSC_MODULE_ID index, uint32_t slewSteps ) PLIB_OSC_SlewEnable Function Enables the selected type of slewing. File plib_osc.h C void PLIB_OSC_SlewEnable(OSC_MODULE_ID index, OSC_CLOCK_SLEW_TYPE slewType); Returns None. Description This function enables slewing to an upward or downward frequency based on the selection. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSlewEnableControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SlewEnable(OSC_ID_0, OSC_CLOCK_SLEW_DOWNWARD); Parameters Parameters Description index Identifies the desired oscillator module slewType One of the possible value from OSC_CLOCK_SLEW_TYPE Function void PLIB_OSC_SlewEnable ( OSC_MODULE_ID index, OSC_CLOCK_SLEW_TYPE slewType ) PLIB_OSC_SlewIsEnabled Function Returns 'true' if the reference oscillator is disabled in Idle mode. File plib_osc.h C bool PLIB_OSC_SlewIsEnabled(OSC_MODULE_ID index, OSC_CLOCK_SLEW_TYPE slewType); Returns • true - The selected type of Slewing is enabled • false - The selected type of Slewing is disabled Description This function returns 'true' if the reference oscillator is disabled in Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSlewEnableControl in your application to determine whether this feature is available. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1310 Preconditions None. Example bool slewStatus; slewStatus = PLIB_OSC_SlewIsEnabled(OSC_ID_0, OSC_CLOCK_SLEW_DOWNWARD); Parameters Parameters Description index Identifies the desired oscillator module slewType One of the possible value from OSC_CLOCK_SLEW_TYPE. Function bool PLIB_OSC_SlewIsEnabled ( OSC_MODULE_ID index, OSC_CLOCK_SLEW_TYPE slewType ) PLIB_OSC_SleepToStartupClockGet Function Returns the clock used for the duration when the device wakes from sleep and the clock ready. File plib_osc.h C OSC_SLEEP_TO_STARTUP_CLK_TYPE PLIB_OSC_SleepToStartupClockGet(OSC_MODULE_ID index); Returns • startupOsc - One of the possible values from OSC_SLEEP_TO_STARTUP_CLK_TYPE Description When a device enters Sleep mode, the source of the system clock usually stops and takes some time after waking up to start running at full speed. This function is to return the clock set for that duration in which the actual clock source is starting up. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSleepToStartupClock in your application to determine whether this feature is available. Preconditions None. Example OSC_SLEEP_TO_STARTUP_CLK_TYPE startupClk; startupClk = PLIB_OSC_SleepToStartupClockGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_SLEEP_TO_STARTUP_CLK_TYPE PLIB_OSC_SleepToStartupClockGet ( OSC_MODULE_ID index ) PLIB_OSC_SleepToStartupClockSelect Function Selects the clock duration for when the device wakes from sleep and the clock is ready. File plib_osc.h Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1311 C void PLIB_OSC_SleepToStartupClockSelect(OSC_MODULE_ID index, OSC_SLEEP_TO_STARTUP_CLK_TYPE startupOsc); Returns None. Description When a device enters Sleep mode, the source of the system clock usually stops and takes some time after waking up to start running at full speed. This function allows the user to select a clock for that duration in which the actual clock source is starting up. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSleepToStartupClock in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SleepToStartupClockSelect(OSC_ID_0, OSC_SLEEP_TO_STARTUP_CLK_FRC); Parameters Parameters Description index Identifies the desired oscillator module startupOsc One of the possible values from OSC_SLEEP_TO_STARTUP_CLK_TYPE Function void PLIB_OSC_SleepToStartupClockSelect ( OSC_MODULE_ID index, OSC_SLEEP_TO_STARTUP_CLK_TYPE startupOsc ) PLIB_OSC_DreamModeDisable Function Disables the dream mode. File plib_osc.h C void PLIB_OSC_DreamModeDisable(OSC_MODULE_ID index); Returns None. Description This function is used to disable the dream mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsDreamModeControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_DreamModeDisable(OSC_ID_0); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1312 Parameters Parameters Description index Identifies the desired oscillator module Function void PLIB_OSC_DreamModeDisable ( OSC_MODULE_ID index) PLIB_OSC_DreamModeEnable Function Enables the dream mode. File plib_osc.h C void PLIB_OSC_DreamModeEnable(OSC_MODULE_ID index); Returns None. Description This function is used to enable the dream mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsDreamModeControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_DreamModeEnable(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function void PLIB_OSC_DreamModeEnable ( OSC_MODULE_ID index) PLIB_OSC_DreamModeStatus Function gets the status of the dream mode. File plib_osc.h C bool PLIB_OSC_DreamModeStatus(OSC_MODULE_ID index); Returns Status of dream mode bit. Description This function is used to get the status of the dream mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsDreamModeControl in your application to determine whether this feature is available. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1313 Preconditions None. Example bool drmMode = PLIB_OSC_DreamModeStatus(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function bool PLIB_OSC_DreamModeStatus ( OSC_MODULE_ID index) b) Primary Oscillator Setup Functions PLIB_OSC_ClockIsReady Function Get the ready status of clock. File plib_osc.h C bool PLIB_OSC_ClockIsReady(OSC_MODULE_ID index, OSC_CLOCK_ID clk); Returns • true - Indicates that the selected clock is running and is stable • false - Indicates that the selected clock is either turned off or is still warming up Description This function returns the ready status of selected clock. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsClockReadyStatus in your application to determine whether this feature is available. Preconditions None. Example bool clkReady; clkReady = PLIB_OSC_ClockIsReady(OSC_ID_0, OSC_CLOCK_FAST_RC); Parameters Parameters Description index Identifies the desired oscillator module. clk One of the values of OSC_CLOCK_ID. Function bool PLIB_OSC_ClockIsReady ( OSC_MODULE_ID index, OSC_CLOCK_ID clk) PLIB_OSC_ClockSlewingIsActive Function Returns the status of clock slewing. File plib_osc.h Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1314 C bool PLIB_OSC_ClockSlewingIsActive(OSC_MODULE_ID index); Returns • true - The clock frequency is being actively slewed to the new frequency. • false - The clock switch has reached its final value Description This function returns the current status of clock switching slewing. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsClockSlewingStatus in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_OSC_ClockSlewingIsActive(OSC_ID_0)) { //wait for clock switch to complete } Parameters Parameters Description index Identifies the desired oscillator module. Function bool PLIB_OSC_ClockSlewingIsActive ( OSC_MODULE_ID index ) PLIB_OSC_SystemClockDivisorGet Function Get the system clock divisor value. File plib_osc.h C uint32_t PLIB_OSC_SystemClockDivisorGet(OSC_MODULE_ID index); Returns • systemClkDivisor - The value by which system clock is divided. Description This function returns the divisor set for system clock. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSystemClockDivisorControl in your application to determine whether this feature is available. Preconditions None. Example uint32_t systemClkDivisor; systemClkDivisor = PLIB_OSC_SystemClockDivisorGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1315 Function uint32_t PLIB_OSC_SystemClockDivisorGet ( OSC_MODULE_ID index ) PLIB_OSC_SystemClockDivisorSelect Function Selects system clock divisor. File plib_osc.h C void PLIB_OSC_SystemClockDivisorSelect(OSC_MODULE_ID index, uint32_t systemClkDivisor); Returns None. Description This function selects the system clock divisor. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSystemClockDivisorControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SystemClockDivisorSelect(OSC_ID_0, OSC_SYSTEM_CLOCK_DIVIDED_BY_10); Parameters Parameters Description index Identifies the desired oscillator module systemClkDivisor The value by which the system clock is to be divided Function void PLIB_OSC_SystemClockDivisorSelect ( OSC_MODULE_ID index, uint32_t systemClkDivisor ) c) Secondary Oscillator Setup Functions PLIB_OSC_SecondaryDisable Function Disables the Secondary Oscillator. File plib_osc.h C void PLIB_OSC_SecondaryDisable(OSC_MODULE_ID index); Returns None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1316 Description This function disables the Secondary Oscillator. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSecondaryEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SecondaryDisable(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function void PLIB_OSC_SecondaryDisable ( OSC_MODULE_ID index ); PLIB_OSC_SecondaryEnable Function Enables the Secondary Oscillator. File plib_osc.h C void PLIB_OSC_SecondaryEnable(OSC_MODULE_ID index); Returns None. Description This function enables the Secondary Oscillator. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSecondaryEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SecondaryEnable(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function void PLIB_OSC_SecondaryEnable ( OSC_MODULE_ID index ) PLIB_OSC_SecondaryIsEnabled Function Returns 'true' if the Secondary Oscillator is enabled. File plib_osc.h Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1317 C bool PLIB_OSC_SecondaryIsEnabled(OSC_MODULE_ID index); Returns • true - The Secondary Oscillator is enabled • false - The Secondary Oscillator is disabled Description This function returns 'true' if the Secondary Oscillator is enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSecondaryEnable in your application to determine whether this feature is available. Preconditions None. Example bool secOscEnable; secOscEnable = PLIB_OSC_SecondaryIsEnabled(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function bool PLIB_OSC_SecondaryIsEnabled ( OSC_MODULE_ID index ); PLIB_OSC_SecondaryIsReady Function Returns 'true' if the Secondary Oscillator is ready. File plib_osc.h C bool PLIB_OSC_SecondaryIsReady(OSC_MODULE_ID index); Returns • true - Indicates that the Secondary Oscillator is running and is stable • false - Indicates that the Secondary Oscillator is either turned off or is still warming up Description This function returns the ready status of the Secondary Oscillator. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSecondaryReady in your application to determine whether this feature is available. Preconditions None. Example bool secOscReady; secOscReady = PLIB_OSC_SecondaryIsReady(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1318 Function bool PLIB_OSC_SecondaryIsReady ( OSC_MODULE_ID index ) d) Reference Oscillator Setup Functions PLIB_OSC_ReferenceOscBaseClockSelect Function Sets the base clock for the reference oscillator. File plib_osc.h C void PLIB_OSC_ReferenceOscBaseClockSelect(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc, OSC_REF_BASECLOCK refOscBaseClock); Returns None. Description This function sets the base clock for the reference oscillator. There are multiple clock sources by which the user can configure the module to output to the pin. Users can check the accuracy of the clock by probing the pin. Use the PLIB_OSC_ReferenceOscDivisorValueSet function to divide the clock if it is a very high value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscBaseClock in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ReferenceOscBaseClockSelect(OSC_ID_0, OSC_REFERENCE_1, OSC_REF_BASECLOCK_PBCLK); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator refOscBaseClk One of the possible values of OSC_REF_BASECLOCK Function void PLIB_OSC_ReferenceOscBaseClockSelect ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc, OSC_REF_BASECLOCK refOscBaseClock ) PLIB_OSC_ReferenceOscDisable Function Disables the reference oscillator output. File plib_osc.h C void PLIB_OSC_ReferenceOscDisable(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns None. Description This function disables output from the reference oscillator. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1319 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ReferenceOscDisable(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function void PLIB_OSC_ReferenceOscDisable ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscDivisorValueSet Function Selects the reference oscillator divisor value. File plib_osc.h C void PLIB_OSC_ReferenceOscDivisorValueSet(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc, OSC_REF_DIVISOR_TYPE refOscDivValue); Returns None. Description This function selects the reference oscillator divisor value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscDivisor in your application to determine whether this feature is available. The value entered may not be the actual divisor. Please refer to the specific device data sheet to determine the actual divisor corresponding to the value entered. Preconditions None. Example // Select the clock source. PLIB_OSC_ReferenceOscBaseClockSelect(OSC_ID_0, OSC_REFERENCE_1, OSC_REF_BASECLOCK_PBCLK); PLIB_OSC_ReferenceOscDivisorValueSet(OSC_ID_0, OSC_REFERENCE_1, 128); PLIB_OSC_ReferenceOscEnable(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator refOscDivValue Value for Reference Oscillator Divisor (RODIV) field. If it is '0', the divider is not used. Function void PLIB_OSC_ReferenceOscDivisorValueSet ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc, OSC_REF_DIVISOR_TYPE refOscDivValue ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1320 PLIB_OSC_ReferenceOscEnable Function Enables the reference oscillator. File plib_osc.h C void PLIB_OSC_ReferenceOscEnable(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns None. Description This function enables the reference oscillator. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscEnable in your application to determine whether this feature is available. If the device has a reference clock output enable control, calling this function may not give the reference clock output. Use the PLIB_OSC_ReferenceOutputEnable function to enable the output. Preconditions None. Example PLIB_OSC_ReferenceOscEnable(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function void PLIB_OSC_ReferenceOscEnable ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscIsEnabled Function Gets the enable status of the reference oscillator output. File plib_osc.h C bool PLIB_OSC_ReferenceOscIsEnabled(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns • true - The reference oscillator is enabled • false - The reference oscillator is disabled Description This function gets the enable status of the reference oscillator output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscEnable in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1321 Example if(PLIB_OSC_ReferenceOscIsEnabled(OSC_ID_0, OSC_REFERENCE_1)) { //Do some action } Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function bool PLIB_OSC_ReferenceOscIsEnabled ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscSourceChangeIsActive Function Returns 'true' if a reference oscillator source change request is active. File plib_osc.h C bool PLIB_OSC_ReferenceOscSourceChangeIsActive(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns • true - The reference oscillator change request is active • false - The reference oscillator change request is not active Description This function returns 'true' if the reference oscillator source change is in progress. The software is not allowed to give a new source change request. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscChangeActive in your application to determine whether this feature is available. Preconditions None. Example if (!PLIB_OSC_ReferenceOscSourceChangeIsActive(OSC_ID_0, OSC_REFERENCE_1)) { //Allowed to change the reference clock source } Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function bool PLIB_OSC_ReferenceOscSourceChangeIsActive ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscStopInIdleDisable Function Enables the reference oscillator in Idle mode. File plib_osc.h Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1322 C void PLIB_OSC_ReferenceOscStopInIdleDisable(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns None. Description This function enables the reference oscillator in Idle mode. The reference oscillator continues to run in Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInIdleEnable in your application to determine whether this feature is available. The default state of the device is the reference oscillator is enabled in Idle mode. Preconditions None. Example PLIB_OSC_ReferenceOsctopInSleepDisable(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function void PLIB_OSC_ReferenceOscStopInIdleDisable ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscStopInIdleEnable Function Configures the reference oscillator to stop operating in Idle mode. File plib_osc.h C void PLIB_OSC_ReferenceOscStopInIdleEnable(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns None. Description This function configures the reference oscillator to stop operating in Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInIdleEnable in your application to determine whether this feature is available. The default state of the device is reference oscillator enabled in Idle mode. Therefore, calling this function is necessary only if the PLIB_OSC_ReferenceOscStopInIdleDisable function was previously called, and the software wants to enable oscillator operation in Sleep mode. Preconditions None. Example PLIB_OSC_ReferenceOscStopInIdleEnable(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1323 Function void PLIB_OSC_ReferenceOscStopInIdleEnable ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscStopInIdleIsEnabled Function Returns 'true' if the reference oscillator is disabled in Idle mode. File plib_osc.h C bool PLIB_OSC_ReferenceOscStopInIdleIsEnabled(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns • true - The reference oscillator is disabled in Idle mode • false - The reference oscillator is enabled in Idle mode Description This function returns 'true' if the reference oscillator is disabled in Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInIdleEnable in your application to determine whether this feature is available. Preconditions None. Example bool refOscIdle; refOscIdle = PLIB_OSC_ReferenceOscStopInIdleIsEnabled(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function bool PLIB_OSC_ReferenceOscStopInIdleIsEnabled ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscStopInSleepDisable Function Enables the reference oscillator in Sleep mode. File plib_osc.h C void PLIB_OSC_ReferenceOscStopInSleepDisable(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns None. Description This function enables the reference oscillator in Sleep mode. The reference oscillator continues to run in Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInSleep in your application to determine whether this feature is available. The reference clock output will be stopped in Sleep mode if the base clock selected is 'System Clock' or 'Peripheral Clock' regardless of this function. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1324 The default state of the device is for the reference oscillator to be enabled in Sleep mode. Therefore, calling this function is necessary only if the PLIB_OSC_ReferenceOscStopInSleepEnable function was previously called, and the software wants to enable oscillator operation in Sleep mode. Preconditions None. Example PLIB_OSC_ReferenceOsctopInSleepDisable(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function void PLIB_OSC_ReferenceOscStopInSleepDisable ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscStopInSleepEnable Function Configures the reference oscillator to stop operating in Sleep mode. File plib_osc.h C void PLIB_OSC_ReferenceOscStopInSleepEnable(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns None. Description This function configures the reference oscillator to stop operating in Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInSleep in your application to determine whether this feature is available. The default state of the device is for the reference oscillator to be enabled in Sleep mode. Preconditions None. Example PLIB_OSC_ReferenceOscStopInSleepEnable(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function void PLIB_OSC_ReferenceOscStopInSleepEnable ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscStopInSleepIsEnabled Function Returns 'true' if the reference oscillator is disabled in Sleep mode. File plib_osc.h C bool PLIB_OSC_ReferenceOscStopInSleepIsEnabled(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1325 Returns • true - The reference oscillator is disabled in Sleep mode • false - The reference oscillator is enabled in Sleep mode Description This function returns 'true' if the reference oscillator is disabled in Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInSleep in your application to determine whether this feature is available. Preconditions None. Example bool refOscSleep; refOscSleep = PLIB_OSC_ReferenceOscStopInSleepIsEnabled(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function bool PLIB_OSC_ReferenceOscStopInSleepIsEnabled ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscSwitchIsComplete Function Returns 'true' if the reference oscillator base clock switching is complete. File plib_osc.h C bool PLIB_OSC_ReferenceOscSwitchIsComplete(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns • true - The reference clock base clock switching is complete • false - The reference clock base clock switching is not complete; switching is not started Description This function returns 'true' if the reference oscillator base clock switching is complete. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscChange in your application to determine whether this feature is available. Preconditions None. Example bool refOscIdle; refOscIdle = PLIB_OSC_ReferenceOscSwitchIsComplete(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1326 Function bool PLIB_OSC_ReferenceOscSwitchIsComplete ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOscTrimSet Function Sets the reference oscillator divisor trim value. File plib_osc.h C void PLIB_OSC_ReferenceOscTrimSet(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc, OSC_REF_TRIM_TYPE trimValue); Returns None. Description This function selects the reference oscillator divisor trim value. The value selected divided by OSC_REF_TRIM_MAX_VALUE will be added to the oscillator divisor value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscTrim in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ReferenceOscTrimSet(OSC_ID_0, OSC_REFERENCE_1, 50); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator trimValue Reference oscillator trim value Function void PLIB_OSC_ReferenceOscTrimSet ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc, OSC_REF_TRIM_TYPE trimValue ) PLIB_OSC_ReferenceOutputDisable Function Disables the reference oscillator output. File plib_osc.h C void PLIB_OSC_ReferenceOutputDisable(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns None. Description This function disables the reference oscillator output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOutputEnable in your application to determine whether this feature is available. The default state of the device is reference oscillator output disabled. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1327 Preconditions None. Example PLIB_OSC_ReferenceOutputDisable(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function void PLIB_OSC_ReferenceOutputDisable ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOutputEnable Function Enables the reference oscillator output. File plib_osc.h C void PLIB_OSC_ReferenceOutputEnable(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Returns None. Description This function enables the reference oscillator output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOutputEnable in your application to determine whether this feature is available. The default state of the device is reference oscillator output disabled. Preconditions None. Example PLIB_OSC_ReferenceOutputEnable(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function void PLIB_OSC_ReferenceOutputEnable ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) PLIB_OSC_ReferenceOutputIsEnabled Function Returns 'true' if the reference oscillator output is enabled. File plib_osc.h C bool PLIB_OSC_ReferenceOutputIsEnabled(OSC_MODULE_ID index, OSC_REFERENCE referenceOsc); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1328 Returns • true - The reference oscillator output is enabled • false - The reference oscillator output is disabled Description This function returns 'true' if the reference oscillator output is enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOutputEnable in your application to determine whether this feature is available. Preconditions None. Example bool refOscIdle; refOscIdle = PLIB_OSC_ReferenceOutputIsEnabled(OSC_ID_0, OSC_REFERENCE_1); Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Function bool PLIB_OSC_ReferenceOutputIsEnabled ( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ) e) Fast RC Oscillator Setup Functions PLIB_OSC_FRCDivisorGet Function Gets the FRC clock divisor. File plib_osc.h C uint16_t PLIB_OSC_FRCDivisorGet(OSC_MODULE_ID index); Returns The FRC divisor value. Description This function gets the FRC clock divisor. The value returned will be direct number and not enum equivalent. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsFRCDivisor in your application to determine whether this feature is available. Preconditions None. Example uint16_t divisorFRC; divisorFRC = PLIB_OSC_FRCDivisorGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1329 Function uint16_t PLIB_OSC_FRCDivisorGet( OSC_MODULE_ID index ) PLIB_OSC_FRCDivisorSelect Function Sets the FRC clock divisor to the specified value. File plib_osc.h C void PLIB_OSC_FRCDivisorSelect(OSC_MODULE_ID index, OSC_FRC_DIV divisorFRC); Returns None. Description This function sets the FRC clock divisor to the specified value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsFRCDivisor in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_FRCDivisorSelect ( OSC_ID_0, OSC_FRC_DIV_4 ); Parameters Parameters Description index Identifies the desired oscillator module divisorFRC One of the possible values from OSC_FRC_DIV Function void PLIB_OSC_FRCDivisorSelect ( OSC_MODULE_ID index, OSC_FRC_DIV divisorFRC ) PLIB_OSC_FRCTuningSelect Function Sets the FRC tuning value. File plib_osc.h C void PLIB_OSC_FRCTuningSelect(OSC_MODULE_ID index, OSC_FRC_TUNE_TYPE tuningValue); Returns None. Description This function tunes the FRC oscillator to the value specified. The application is supposed to try different values and find the best one. If the device has different tuning modes, this function will be used differently. See the example provided for the PLIB_OSC_FRCTuningSequenceValueSet function for details. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsFRCTuning in your application to determine whether this feature is available. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1330 Preconditions None. Example PLIB_OSC_FRCTuningSelect(OSC_ID_0, 0x05); Parameters Parameters Description index Identifies the desired oscillator module tuningValue Tuning value. One of the possible values from OSC_FRC_TUNE_TYPE. Function void PLIB_OSC_FRCTuningSelect ( OSC_MODULE_ID index, OSC_FRC_TUNE_TYPE tuningValue ) f) Oscillator Switch Setup Functions PLIB_OSC_ClockSwitchingAbort Function Aborts an oscillator switch. File plib_osc.h C void PLIB_OSC_ClockSwitchingAbort(OSC_MODULE_ID index); Returns None. Description This function aborts the oscillator switch to the selection specified by the new oscillator selection bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOscSwitchInit in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ClockSwitchingAbort(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function void PLIB_OSC_ClockSwitchingAbort ( OSC_MODULE_ID index ) PLIB_OSC_ClockSwitchingIsComplete Function Gets the oscillator switch progress status. File plib_osc.h C bool PLIB_OSC_ClockSwitchingIsComplete(OSC_MODULE_ID index); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1331 Returns • true - The oscillator switch is complete • false - The oscillator switch is in progress Description This function gets the status of the oscillator switch progress. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOscSwitchInit in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SysClockSelect(OSC_ID_0, OSC_PRIMARY); while(!PLIB_OSC_ClockSwitchingIsComplete(OSC_ID_0)); Parameters Parameters Description index Identifies the desired oscillator module Function bool PLIB_OSC_ClockSwitchingIsComplete( OSC_MODULE_ID index ); PLIB_OSC_CurrentSysClockGet Function Gets the current oscillator selected. File plib_osc.h C OSC_SYS_TYPE PLIB_OSC_CurrentSysClockGet(OSC_MODULE_ID index); Returns One of the possible values from OSC_SYS_TYPE. Description This function gets the current oscillator. If the application has not changed the oscillator selection, this will be same as the oscillator selected through the Configuration bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOscCurrentGet in your application to determine whether this feature is available. Preconditions None. Example OSC_SYS_TYPE oscCurrent; oscCurrent = PLIB_OSC_CurrentSysClockGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_SYS_TYPE PLIB_OSC_CurrentSysClockGet ( OSC_MODULE_ID index ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1332 PLIB_OSC_SysClockSelect Function Selects the new oscillator. File plib_osc.h C void PLIB_OSC_SysClockSelect(OSC_MODULE_ID index, OSC_SYS_TYPE newOsc); Returns None. Description This function selects the new oscillator. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOscSelect in your application to determine whether this feature is available. This function adds the necessary delay (NOP instructions) after switching the oscillator. Therefore, the user need not add any delay as specified in the device data sheet. Preconditions None. Example PLIB_OSC_SysClockSelect(OSC_ID_0, OSC_PRIMARY); Parameters Parameters Description index Identifies the desired oscillator module newOsc One of the possible values from OSC_SYS_TYPE Function void PLIB_OSC_SysClockSelect ( OSC_MODULE_ID index, OSC_SYS_TYPE newOsc ) g) USB and Display Clock Setup Functions PLIB_OSC_UsbClockSourceGet Function Gets the USB module clock source. File plib_osc.h C OSC_USBCLOCK_SOURCE PLIB_OSC_UsbClockSourceGet(OSC_MODULE_ID index); Returns USB module clock source. One of the possible values from OSC_USBCLOCK_SOURCE. Description This function gets the USB module clock source. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUsbClockSource in your application to determine whether this feature is available. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1333 Preconditions None. Example if (SYS_OSC_USBCLK_FRC == PLIB_OSC_UsbClockSourceGet(OSC_ID_0)) { //Do some action } Parameters Parameters Description index Identifies the desired oscillator module Function OSC_USBCLOCK_SOURCE PLIB_OSC_UsbClockSourceGet ( OSC_MODULE_ID index ) PLIB_OSC_UsbClockSourceSelect Function Sets the USB module clock source. File plib_osc.h C void PLIB_OSC_UsbClockSourceSelect(OSC_MODULE_ID index, OSC_USBCLOCK_SOURCE usbClock); Returns None. Description This function sets the USB module clock source. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUsbClockSource in your application to determine whether this feature is available. Before placing the USB module in Suspend mode, use this function to enable the FRC clock. Preconditions None. Example PLIB_OSC_UsbClockSourceSelect(OSC_ID_0, SYS_OSC_USBCLK_FRC); Parameters Parameters Description index Identifies the desired oscillator module usbClock Select the USB module clock source. One of the possible values from OSC_USBCLOCK_SOURCE. Function void PLIB_OSC_UsbClockSourceSelect ( OSC_MODULE_ID index, OSC_USBCLOCK_SOURCE usbClock ) h) PLL Setup Functions PLIB_OSC_PLLClockIsLocked Function Gets the lock status for the clock and PLL selections. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1334 File plib_osc.h C bool PLIB_OSC_PLLClockIsLocked(OSC_MODULE_ID index); Returns • true - The clock and PLL selections are locked • false - The clock and PLL selections are not locked Description This function gets the lock status for the clock and PLL selections. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPLLClockLock in your application to determine whether this feature is available. If the PLL does not stabilize properly during start-up, this function may not reflect the actual status of PLL lock, nor does it detect when the PLL loses lock during normal operation. Preconditions None. Example bool clockPLL_st; clockPLL_st = PLIB_OSC_PLLClockIsLocked(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function bool PLIB_OSC_PLLClockIsLocked ( OSC_MODULE_ID index ) PLIB_OSC_PLLClockLock Function Locks the clock and PLL selections. File plib_osc.h C void PLIB_OSC_PLLClockLock(OSC_MODULE_ID index); Returns None. Description This function locks the clock and PLL selections. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPLLClockLock in your application to determine whether this feature is available. The data given by this function is only valid if clock switching and monitoring are enabled. Otherwise Clock and PLL selections are never locked and may be modified. Preconditions The Fail-Safe Clock Monitor (FSCM) should be enabled. Example PLIB_OSC_PLLClockLock(OSC_ID_0); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1335 Parameters Parameters Description index Identifies the desired oscillator module Function void PLIB_OSC_PLLClockLock ( OSC_MODULE_ID index ) PLIB_OSC_PLLClockUnlock Function Unlocks the clock and PLL selections. File plib_osc.h C void PLIB_OSC_PLLClockUnlock(OSC_MODULE_ID index); Returns None. Description This function unlocks the clock and PLL selection so that the clock and PLL may be modified. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPLLClockLock in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_PLLClockUnlock(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function void PLIB_OSC_PLLClockUnlock ( OSC_MODULE_ID index ) PLIB_OSC_PLLIsLocked Function Returns 'true' if the selected PLL module is locked. File plib_osc.h C bool PLIB_OSC_PLLIsLocked(OSC_MODULE_ID index, OSC_PLL_SELECT pllselect); Returns • true - The PLL module is in lock or the PLL module start-up timer is satisfied • false - The PLL module is out of lock, the PLL start-up timer is running, or the PLL module is disabled Description This function returns the lock status of the selected PLL module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPLLLockStatus in your application to determine whether this feature is available. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1336 If the PLL does not stabilize properly during start-up, this function may not reflect the actual status of PLL lock, nor does it detect when the PLL loses lock during normal operation. Preconditions None. Example bool lockPLL_status; lockPLL_status = PLIB_OSC_PLLIsLocked(OSC_ID_0, OSC_PLL_SYSTEM); Parameters Parameters Description index Identifies the desired oscillator module pllselect Selects the PLL module Function bool PLIB_OSC_PLLIsLocked ( OSC_MODULE_ID index, OSC_PLL_SELECT pllselect ) PLIB_OSC_SysPLLFrequencyRangeGet Function Gets the frequency range for the PLL module. File plib_osc.h C OSC_SYSPLL_FREQ_RANGE PLIB_OSC_SysPLLFrequencyRangeGet(OSC_MODULE_ID index); Returns • PLLFrequencyRange - One of the possible values from OSC_SYSPLL_FREQ_RANGE Description This function returns the frequency range set for the PLL module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLFrequencyRange in your application to determine whether this feature is available. Preconditions None. Example OSC_SYSPLL_FREQ_RANGE PLLFrequencyRange; PLLFrequencyRange = PLIB_OSC_SysPLLFrequencyRangeGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_SYSPLL_FREQ_RANGE PLIB_OSC_SysPLLFrequencyRangeGet ( OSC_MODULE_ID index ) PLIB_OSC_SysPLLFrequencyRangeSet Function Sets the frequency range for the PLL module. File plib_osc.h C void PLIB_OSC_SysPLLFrequencyRangeSet(OSC_MODULE_ID index, OSC_SYSPLL_FREQ_RANGE PLLFrequencyRange); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1337 Returns None. Description This function sets the frequency range for the PLL module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLFrequencyRange in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SysPLLFrequencyRangeSet(OSC_ID_0, OSC_SYSPLL_FREQ_RANGE_5M_TO_10M); Parameters Parameters Description index Identifies the desired oscillator module PLLFrequencyRange One of the possible values from OSC_SYSPLL_FREQ_RANGE Function void PLIB_OSC_SysPLLFrequencyRangeSet ( OSC_MODULE_ID index, OSC_SYSPLL_FREQ_RANGE PLLFrequencyRange ) PLIB_OSC_SysPLLInputClockSourceGet Function Gets the input clock source for the PLL module. File plib_osc.h C OSC_SYSPLL_IN_CLK_SOURCE PLIB_OSC_SysPLLInputClockSourceGet(OSC_MODULE_ID index); Returns • PLLInClockSource - One of the possible values from OSC_SYSPLL_IN_CLK_SOURCE Description This function returns the input clock source for the PLL module Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLInputClockSource in your application to determine whether this feature is available. Preconditions None. Example OSC_SYSPLL_IN_CLK_SOURCE PLLInClockSource; PLLInClockSource = PLIB_OSC_SysPLLInputClockSourceGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_SYSPLL_IN_CLK_SOURCE PLIB_OSC_SysPLLInputClockSourceGet ( OSC_MODULE_ID index ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1338 PLIB_OSC_SysPLLInputClockSourceSet Function Sets the input clock source for the PLL module. File plib_osc.h C void PLIB_OSC_SysPLLInputClockSourceSet(OSC_MODULE_ID index, OSC_SYSPLL_IN_CLK_SOURCE PLLInClockSource); Returns None. Description This function sets the input clock source for the PLL module Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLInputClockSource in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SysPLLInputClockSourceSet(OSC_ID_0, OSC_SYSPLL_IN_CLK_SOURCE_FRC); Parameters Parameters Description index Identifies the desired oscillator module PLLInClockSource One of the possible values from OSC_SYSPLL_IN_CLK_SOURCE Function void PLIB_OSC_SysPLLInputClockSourceSet ( OSC_MODULE_ID index, OSC_SYSPLL_IN_CLK_SOURCE PLLInClockSource ) PLIB_OSC_SysPLLInputDivisorGet Function Gets the input divisor for the PLL. File plib_osc.h C uint16_t PLIB_OSC_SysPLLInputDivisorGet(OSC_MODULE_ID index); Returns The System PLL input divisor as a number. Description This function returns the input divisor for the PLL. Remarks The direct register value itself is returned instead of the register value equivalent. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLInputDivisor in your application to determine whether this feature is available. Preconditions None. Example uint16_t pllInDiv; Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1339 PLLInDiv = PLIB_OSC_SysPLLInputDivisorGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function uint16_t PLIB_OSC_SysPLLInputDivisorGet ( OSC_MODULE_ID index ) PLIB_OSC_SysPLLMultiplierGet Function Gets the PLL multiplier. File plib_osc.h C OSC_SYSPLL_MULTIPLIER_TYPE PLIB_OSC_SysPLLMultiplierGet(OSC_MODULE_ID index); Returns One of the possible values of PB clock divisor of type OSC_SYSPLL_MULTIPLIER_TYPE. Description This function returns the PLL multiplier. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLMultiplier in your application to determine whether this feature is available. The actual multiplier value will be returned, and NOT the 'PLLMULT' field value. Refer to the specific device data sheet for information. Preconditions None. Example OSC_SYSPLL_MULTIPLIER_TYPE pll_multiply; pll_multiply = PLIB_OSC_SysPLLMultiplierGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_SYSPLL_MULTIPLIER_TYPE PLIB_OSC_SysPLLMultiplierGet ( OSC_MODULE_ID index ) PLIB_OSC_SysPLLMultiplierSelect Function Sets the PLL multiplier to the specified value. File plib_osc.h C void PLIB_OSC_SysPLLMultiplierSelect(OSC_MODULE_ID index, OSC_SYSPLL_MULTIPLIER_TYPE pll_multiplier); Returns None. Description This function sets the PLL multiplier to the specified value. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1340 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLMultiplier in your application to determine whether this feature is available. Use the PLL Multiplier value directly for the parameter 'pll_multiplier', and NOT the value of the 'PLLMULT' field. Use of the PLL Multiplier value is not supported by the selected device, and therefore, library behavior is undefined. Refer to the specific device data sheet for information. Preconditions None. Example PLIB_OSC_SysPLLMultiplierSelect (OSC_ID_0, 0x08); Parameters Parameters Description index Identifies the desired oscillator module pll_multiplier One of the possible values of PB clock divisor of type OSC_PLL_MUL_TYPE Function void PLIB_OSC_SysPLLMultiplierSelect ( OSC_MODULE_ID index, OSC_SYSPLL_MULTIPLIER_TYPE pll_multiplier ) PLIB_OSC_SysPLLOutputDivisorGet Function Gets the output divisor for the PLL. File plib_osc.h C uint16_t PLIB_OSC_SysPLLOutputDivisorGet(OSC_MODULE_ID index); Returns System PLL output divisor value. Description This function returns the output divisor for the System PLL. The value is the actual divisor and not the enum value corresponding to it. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLOutputDivisor in your application to determine whether this feature is available. Preconditions None. Example uint16_t pllOutDiv; pllOutDiv = PLIB_OSC_SysPLLOutputDivisorGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function uint16_t PLIB_OSC_SysPLLOutputDivisorGet ( OSC_MODULE_ID index ) PLIB_OSC_SysPLLOutputDivisorSet Function Sets the output divider for the PLL to the specified value. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1341 File plib_osc.h C void PLIB_OSC_SysPLLOutputDivisorSet(OSC_MODULE_ID index, OSC_SYSPLL_OUT_DIV PLLOutDiv); Returns None. Description This function sets the output divider for the PLL to the specified value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLOutputDivisor in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SysPLLOutputDivisorSelect(OSC_ID_0, OSC_SYSPLL_OUT_DIV_1); Parameters Parameters Description index Identifies the desired oscillator module PLLOutDiv One of the possible values from OSC_SYSPLL_OUT_DIV Function void PLIB_OSC_SysPLLOutputDivisorSet ( OSC_MODULE_ID index, OSC_SYSPLL_OUT_DIV PLLOutDiv ) PLIB_OSC_SysPLLInputDivisorSet Function Sets the input divider for the PLL to the specified value. File plib_osc.h C void PLIB_OSC_SysPLLInputDivisorSet(OSC_MODULE_ID index, uint16_t PLLInDiv); Returns None. Description This function sets the input divider for the PLL to the specified value. Remarks Pass the direct divisor instead of the register value equivalent. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLInputDivisor in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_SysPLLInputDivisorSet( OSC_ID_0, 3 ); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1342 Parameters Parameters Description index Identifies the desired oscillator module PLLInDiv System PLL input divisor value Function void PLIB_OSC_SysPLLInputDivisorSet ( OSC_MODULE_ID index, uint16_t PLLInDiv ) PLIB_OSC_BTPLLClockOutDisable Function Disables the Bluetooth PLL Clock Output. File plib_osc.h C void PLIB_OSC_BTPLLClockOutDisable(OSC_MODULE_ID index); Returns None. Description This function is used to disable the Bluetooth PLL clock output to SoC pin. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLClockOut in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_BTPLLClockOutDisable(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function void PLIB_OSC_BTPLLClockOutDisable ( OSC_MODULE_ID index) PLIB_OSC_BTPLLClockOutEnable Function Enables the Bluetooth PLL clock Ouput. File plib_osc.h C void PLIB_OSC_BTPLLClockOutEnable(OSC_MODULE_ID index); Returns None. Description This function is used to enable the Bluetooth PLL clock Output to the SoC pin. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1343 PLIB_OSC_ExistsBTPLLClockOut in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_BTPLLClockOutEnable(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function void PLIB_OSC_BTPLLClockOutEnable ( OSC_MODULE_ID index) PLIB_OSC_BTPLLClockOutStatus Function gets the status of the Bluetooth PLL clock Output. File plib_osc.h C bool PLIB_OSC_BTPLLClockOutStatus(OSC_MODULE_ID index); Returns Status of Bluetooth PLL clock output. Description This function is used to get the status of the Bluetooth PLL clock Output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLClockOut in your application to determine whether this feature is available. Preconditions None. Example bool btpllClkOut = PLIB_OSC_BTPLLClockOutStatus(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function bool PLIB_OSC_BTPLLClockOutStatus ( OSC_MODULE_ID index) PLIB_OSC_BTPLLFrequencyRangeGet Function Gets the frequency range for the Bluetooth PLL module. File plib_osc.h C OSC_BTPLL_FREQ_RANGE PLIB_OSC_BTPLLFrequencyRangeGet(OSC_MODULE_ID index); Returns • PLLFrequencyRange - One of the possible values from OSC_BTPLL_FREQ_RANGE Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1344 Description This function returns the frequency range set for the Bluetooth PLL module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLFrequencyRange in your application to determine whether this feature is available. Preconditions None. Example OSC_BTPLL_FREQ_RANGE PLLFrequencyRange; PLLFrequencyRange = PLIB_OSC_BTPLLFrequencyRangeGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_BTPLL_FREQ_RANGE PLIB_OSC_BTPLLFrequencyRangeGet ( OSC_MODULE_ID index ) PLIB_OSC_BTPLLFrequencyRangeSet Function Sets the frequency range for the Bluetooth PLL module. File plib_osc.h C void PLIB_OSC_BTPLLFrequencyRangeSet(OSC_MODULE_ID index, OSC_BTPLL_FREQ_RANGE PLLFrequencyRange); Returns None. Description This function sets the frequency range for the Bluetooth PLL module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLFrequencyRange in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_BTPLLFrequencyRangeSet(OSC_ID_0, OSC_BTPLL_FREQ_RANGE_5M_TO_10M); Parameters Parameters Description index Identifies the desired oscillator module PLLFrequencyRange One of the possible values from OSC_BTPLL_FREQ_RANGE Function void PLIB_OSC_BTPLLFrequencyRangeSet ( OSC_MODULE_ID index, OSC_BTPLL_FREQ_RANGE PLLFrequencyRange ) PLIB_OSC_BTPLLInputClockSourceGet Function Gets the input clock source for the Bluetooth PLL module. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1345 File plib_osc.h C OSC_SYSPLL_IN_CLK_SOURCE PLIB_OSC_BTPLLInputClockSourceGet(OSC_MODULE_ID index); Returns • PLLInClockSource - One of the possible values from OSC_BTPLL_IN_CLK_SOURCE Description This function returns the input clock source for the Bluetooth PLL module Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLInputClockSource in your application to determine whether this feature is available. Preconditions None. Example OSC_BTPLL_IN_CLK_SOURCE PLLInClockSource; PLLInClockSource = PLIB_OSC_BTPLLInputClockSourceGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_BTPLL_IN_CLK_SOURCE PLIB_OSC_BTPLLInputClockSourceGet ( OSC_MODULE_ID index ) PLIB_OSC_BTPLLInputClockSourceSet Function Sets the input clock source for the Bluetooth PLL module. File plib_osc.h C void PLIB_OSC_BTPLLInputClockSourceSet(OSC_MODULE_ID index, OSC_BTPLL_IN_CLK_SOURCE PLLInClockSource); Returns None. Description This function sets the input clock source for the Bluetooth PLL module Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLInputClockSource in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_BTPLLInputClockSourceSet(OSC_ID_0, OSC_BTPLL_IN_CLK_SOURCE_FRC); Parameters Parameters Description index Identifies the desired oscillator module PLLInClockSource One of the possible values from OSC_BTPLL_IN_CLK_SOURCE Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1346 Function void PLIB_OSC_BTPLLInputClockSourceSet ( OSC_MODULE_ID index, OSC_BTPLL_IN_CLK_SOURCE PLLInClockSource ) PLIB_OSC_BTPLLInputDivisorGet Function Gets the input divisor for the Bluetooth PLL. File plib_osc.h C uint16_t PLIB_OSC_BTPLLInputDivisorGet(OSC_MODULE_ID index); Returns The Bluetooth PLL input divisor as a number. Description This function returns the input divisor for the Bluetooth PLL. Remarks The direct register value itself is returned instead of the register value equivalent. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLInputDivisor in your application to determine whether this feature is available. Preconditions None. Example uint16_t pllInDiv; PLLInDiv = PLIB_OSC_BTPLLInputDivisorGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function uint16_t PLIB_OSC_BTPLLInputDivisorGet ( OSC_MODULE_ID index ) PLIB_OSC_BTPLLInputDivisorSet Function Sets the input divider for the Bluetooth PLL to the specified value. File plib_osc.h C void PLIB_OSC_BTPLLInputDivisorSet(OSC_MODULE_ID index, uint16_t PLLInDiv); Returns None. Description This function sets the input divider for the Bluetooth PLL to the specified value. Remarks Pass the direct divisor instead of the register value equivalent. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLInputDivisor in your application to determine whether this feature is available. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1347 Preconditions None. Example PLIB_OSC_BTPLLInputDivisorSet( OSC_ID_0, 3 ); Parameters Parameters Description index Identifies the desired oscillator module PLLInDiv USB PLL input divisor value Function void PLIB_OSC_BTPLLInputDivisorSet ( OSC_MODULE_ID index, uint16_t PLLInDiv ) PLIB_OSC_BTPLLMultiplierGet Function Gets the Bluetooth PLL multiplier. File plib_osc.h C OSC_SYSPLL_MULTIPLIER_TYPE PLIB_OSC_BTPLLMultiplierGet(OSC_MODULE_ID index); Returns One of the possible values of Bluetooth Multiplier of type OSC_SYSPLL_MULTIPLIER_TYPE. Description This function returns the Bluetooth PLL multiplier. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLMultiplier in your application to determine whether this feature is available. The actual multiplier value will be returned, and NOT the 'BTPLLMULT' field value. Refer to the specific device data sheet for information. Preconditions None. Example OSC_SYSPLL_MULTIPLIER_TYPE pll_multiply; pll_multiply = PLIB_OSC_BTPLLMultiplierGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_SYSPLL_MULTIPLIER_TYPE PLIB_OSC_BTPLLMultiplierGet ( OSC_MODULE_ID index ) PLIB_OSC_BTPLLMultiplierSelect Function Sets the Bluetooth PLL multiplier to the specified value. File plib_osc.h C void PLIB_OSC_BTPLLMultiplierSelect(OSC_MODULE_ID index, OSC_SYSPLL_MULTIPLIER_TYPE pll_multiplier); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1348 Returns None. Description This function sets the Bluetooth PLL multiplier to the specified value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLMultiplier in your application to determine whether this feature is available. Use the USB PLL Multiplier value directly for the parameter 'pll_multiplier', and NOT the value of the 'BTPLLMULT' field. Use of the PLL Multiplier value is not supported by the selected device, and therefore, library behavior is undefined. Refer to the specific device data sheet for information. Preconditions None. Example PLIB_OSC_BTPLLMultiplierSelect (OSC_ID_0, 0x08); Parameters Parameters Description index Identifies the desired oscillator module pll_multiplier One of the possible values between 0 and 255 Function void PLIB_OSC_BTPLLMultiplierSelect ( OSC_MODULE_ID index, OSC_SYSPLL_MULTIPLIER_TYPE pll_multiplier ) PLIB_OSC_BTPLLOutputDivisorGet Function Gets the output divisor for the PLL. File plib_osc.h C uint16_t PLIB_OSC_BTPLLOutputDivisorGet(OSC_MODULE_ID index); Returns Bluetooth PLL output divisor value. Description This function returns the output divisor for the Bluetooth PLL. The value is the actual divisor and not the enum value corresponding to it. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLOutputDivisor in your application to determine whether this feature is available. Preconditions None. Example uint16_t pllOutDiv; pllOutDiv = PLIB_OSC_BTPLLOutputDivisorGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function uint16_t PLIB_OSC_BTPLLOutputDivisorGet ( OSC_MODULE_ID index ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1349 PLIB_OSC_BTPLLOutputDivisorSet Function Sets the output divider for the Bluetooth PLL to the specified value. File plib_osc.h C void PLIB_OSC_BTPLLOutputDivisorSet(OSC_MODULE_ID index, OSC_BTPLL_OUT_DIV PLLOutDiv); Returns None. Description This function sets the output divider for the Bluetooth PLL to the specified value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsBTPLLOutputDivisor in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_BTPLLOutputDivisorSelect(OSC_ID_0, OSC_BTPLL_OUT_DIV_1); Parameters Parameters Description index Identifies the desired oscillator module PLLOutDiv One of the possible values from OSC_BTPLL_OUT_DIV Function void PLIB_OSC_BTPLLOutputDivisorSet ( OSC_MODULE_ID index, OSC_BTPLL_OUT_DIV PLLOutDiv ) PLIB_OSC_ForceSPLLLockDisable Function Disables the Force PLL Lock feature for specified PLL. File plib_osc.h C void PLIB_OSC_ForceSPLLLockDisable(OSC_MODULE_ID index, OSC_PLL_SELECT pllSel); Returns None. Description This function is used to disable the Force PLL Lock feature for the specified PLL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsForceLock in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ForceSPLLLockDisable(OSC_ID_0, OSC_PLL_USB); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1350 Parameters Parameters Description index Identifies the desired oscillator module pllSel PLL for which force locked to be disabled Function void PLIB_OSC_ForceSPLLLockDisable ( OSC_MODULE_ID index, OSC_PLL_SELECT pllSel) PLIB_OSC_ForceSPLLLockEnable Function Enables the Force PLL Lock feature for specified PLL. File plib_osc.h C void PLIB_OSC_ForceSPLLLockEnable(OSC_MODULE_ID index, OSC_PLL_SELECT pllSel); Returns None. Description This function is used to enable the Force PLL Lock feature for the specified PLL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsForceLock in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ForceSPLLLockEnable(OSC_ID_0, OSC_PLL_USB); Parameters Parameters Description index Identifies the desired oscillator module pllSel PLL to be force locked Function void PLIB_OSC_ForceSPLLLockEnable ( OSC_MODULE_ID index, OSC_PLL_SELECT pllSel) PLIB_OSC_ForceSPLLLockStatus Function gets the status of the force PLL Lock bit of the specified PLL. File plib_osc.h C bool PLIB_OSC_ForceSPLLLockStatus(OSC_MODULE_ID index, OSC_PLL_SELECT pllSel); Returns Status of Force PLL Lock Status for the specified PLL. Description This function is used to get the status of the force PLL Lock bit of the specified PLL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1351 PLIB_OSC_ExistsForceLock in your application to determine whether this feature is available. Preconditions None. Example bool spllFLock = PLIB_OSC_ForceSPLLLockStatus(OSC_ID_0, OSC_PLL_USB); Parameters Parameters Description index Identifies the desired oscillator module pllSel PLL for which force lock status to be read. Function bool PLIB_OSC_ForceSPLLLockStatus ( OSC_MODULE_ID index, OSC_PLL_SELECT pllSel) PLIB_OSC_PLLBypassDisable Function Disables the PLL Bypass. File plib_osc.h C void PLIB_OSC_PLLBypassDisable(OSC_MODULE_ID index, OSC_PLL_SELECT pllSel); Returns None. Description This function is used to disable the PLL Bypass for a specified PLL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSPLLBypass in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_PLLBypassDisable(OSC_ID_0, OSC_PLL_USB); Parameters Parameters Description index Identifies the desired oscillator module pllSel PLL for which bypass has to be disabled Function void PLIB_OSC_SPLLBypassDisable ( OSC_MODULE_ID index, OSC_PLL_SELECT pllSel ) PLIB_OSC_PLLBypassEnable Function Enables the PLL Bypass. File plib_osc.h C void PLIB_OSC_PLLBypassEnable(OSC_MODULE_ID index, OSC_PLL_SELECT pllSel); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1352 Returns None. Description This function is used to enable the PLL Bypass for a specified PLL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPLLBypass in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_PLLBypassEnable(OSC_ID_0, OSC_PLL_USB); Parameters Parameters Description index Identifies the desired oscillator module pllSel PLL for which bypass has to be enabled Function void PLIB_OSC_PLLBypassEnable ( OSC_MODULE_ID index, OSC_PLL_SELECT pllSel ) PLIB_OSC_PLLBypassStatus Function gets the status of the PLL Bypass. File plib_osc.h C bool PLIB_OSC_PLLBypassStatus(OSC_MODULE_ID index, OSC_PLL_SELECT pllSel); Returns Status of SPLL Bypass bit. Description This function is used to get the status of the PLL Bypass bit for a specified PLL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSPLLBypass in your application to determine whether this feature is available. Preconditions None. Example bool spllBypass = PLIB_OSC_SPLLBypassStatus(OSC_ID_0. OSC_PLL_USB); Parameters Parameters Description index Identifies the desired oscillator module pllSel PLL whose Bypass status has to be read Function bool PLIB_OSC_SPLLBypassStatus ( OSC_MODULE_ID index, OSC_PLL_SELECT pllSel ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1353 PLIB_OSC_UPLLFrequencyRangeGet Function Gets the frequency range for the USB PLL module. File plib_osc.h C OSC_UPLL_FREQ_RANGE PLIB_OSC_UPLLFrequencyRangeGet(OSC_MODULE_ID index); Returns • PLLFrequencyRange - One of the possible values from OSC_UPLL_FREQ_RANGE Description This function returns the frequency range set for the USB PLL module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUPLLFrequencyRange in your application to determine whether this feature is available. Preconditions None. Example OSC_UPLL_FREQ_RANGE PLLFrequencyRange; PLLFrequencyRange = PLIB_OSC_UPLLFrequencyRangeGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_UPLL_FREQ_RANGE PLIB_OSC_UPLLFrequencyRangeGet ( OSC_MODULE_ID index ) PLIB_OSC_UPLLFrequencyRangeSet Function Sets the frequency range for the USB PLL module. File plib_osc.h C void PLIB_OSC_UPLLFrequencyRangeSet(OSC_MODULE_ID index, OSC_UPLL_FREQ_RANGE PLLFrequencyRange); Returns None. Description This function sets the frequency range for the USB PLL module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUPLLFrequencyRange in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_UPLLFrequencyRangeSet(OSC_ID_0, OSC_UPLL_FREQ_RANGE_5M_TO_10M); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1354 Parameters Parameters Description index Identifies the desired oscillator module PLLFrequencyRange One of the possible values from OSC_UPLL_FREQ_RANGE Function void PLIB_OSC_UPLLFrequencyRangeSet ( OSC_MODULE_ID index, OSC_UPLL_FREQ_RANGE PLLFrequencyRange ) PLIB_OSC_UPLLInputDivisorGet Function Gets the input divisor for the USB PLL. File plib_osc.h C uint16_t PLIB_OSC_UPLLInputDivisorGet(OSC_MODULE_ID index); Returns The USB PLL input divisor as a number. Description This function returns the input divisor for the USB PLL. Remarks The direct register value itself is returned instead of the register value equivalent. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUPLLInputDivisor in your application to determine whether this feature is available. Preconditions None. Example uint16_t pllInDiv; PLLInDiv = PLIB_OSC_UPLLInputDivisorGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function uint16_t PLIB_OSC_UPLLInputDivisorGet ( OSC_MODULE_ID index ) PLIB_OSC_UPLLInputDivisorSet Function Sets the input divider for the USB PLL to the specified value. File plib_osc.h C void PLIB_OSC_UPLLInputDivisorSet(OSC_MODULE_ID index, uint16_t PLLInDiv); Returns None. Description This function sets the input divider for the USB PLL to the specified value. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1355 Remarks Pass the direct divisor instead of the register value equivalent. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUPLLInputDivisor in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_UPLLInputDivisorSet( OSC_ID_0, 3 ); Parameters Parameters Description index Identifies the desired oscillator module PLLInDiv USB PLL input divisor value Function void PLIB_OSC_UPLLInputDivisorSet ( OSC_MODULE_ID index, uint16_t PLLInDiv ) PLIB_OSC_UPLLMultiplierGet Function Gets the USB PLL multiplier. File plib_osc.h C OSC_SYSPLL_MULTIPLIER_TYPE PLIB_OSC_UPLLMultiplierGet(OSC_MODULE_ID index); Returns One of the possible values of USB Multiplier of type OSC_SYSPLL_MULTIPLIER_TYPE. Description This function returns the USB PLL multiplier. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUPLLMultiplier in your application to determine whether this feature is available. The actual multiplier value will be returned, and NOT the 'UPLLMULT' field value. Refer to the specific device data sheet for information. Preconditions None. Example OSC_SYSPLL_MULTIPLIER_TYPE pll_multiply; pll_multiply = PLIB_OSC_UPLLMultiplierGet(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function OSC_SYSPLL_MULTIPLIER_TYPE PLIB_OSC_UPLLMultiplierGet ( OSC_MODULE_ID index ) PLIB_OSC_UPLLMultiplierSelect Function Sets the USB PLL multiplier to the specified value. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1356 File plib_osc.h C void PLIB_OSC_UPLLMultiplierSelect(OSC_MODULE_ID index, OSC_SYSPLL_MULTIPLIER_TYPE pll_multiplier); Returns None. Description This function sets the USB PLL multiplier to the specified value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUPLLMultiplier in your application to determine whether this feature is available. Use the USB PLL Multiplier value directly for the parameter 'pll_multiplier', and NOT the value of the 'UPLLMULT' field. Use of the PLL Multiplier value is not supported by the selected device, and therefore, library behavior is undefined. Refer to the specific device data sheet for information. Preconditions None. Example PLIB_OSC_UPLLMultiplierSelect (OSC_ID_0, 0x08); Parameters Parameters Description index Identifies the desired oscillator module pll_multiplier One of the possible values between 0 and 255 Function void PLIB_OSC_UPLLMultiplierSelect ( OSC_MODULE_ID index, OSC_SYSPLL_MULTIPLIER_TYPE pll_multiplier ) PLIB_OSC_UPLLOutputDivisorGet Function Gets the output divisor for the PLL. File plib_osc.h C uint16_t PLIB_OSC_UPLLOutputDivisorGet(OSC_MODULE_ID index); Returns USB PLL output divisor value. Description This function returns the output divisor for the USB PLL. The value is the actual divisor and not the enum value corresponding to it. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUPLLOutputDivisor in your application to determine whether this feature is available. Preconditions None. Example uint16_t pllOutDiv; pllOutDiv = PLIB_OSC_UPLLOutputDivisorGet(OSC_ID_0); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1357 Parameters Parameters Description index Identifies the desired oscillator module Function uint16_t PLIB_OSC_UPLLOutputDivisorGet ( OSC_MODULE_ID index ) PLIB_OSC_UPLLOutputDivisorSet Function Sets the output divider for the USB PLL to the specified value. File plib_osc.h C void PLIB_OSC_UPLLOutputDivisorSet(OSC_MODULE_ID index, OSC_UPLL_OUT_DIV PLLOutDiv); Returns None. Description This function sets the output divider for the USB PLL to the specified value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUPLLOutputDivisor in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_UPLLOutputDivisorSelect(OSC_ID_0, OSC_UPLL_OUT_DIV_1); Parameters Parameters Description index Identifies the desired oscillator module PLLOutDiv One of the possible values from OSC_UPLL_OUT_DIV Function void PLIB_OSC_UPLLOutputDivisorSet ( OSC_MODULE_ID index, OSC_UPLL_OUT_DIV PLLOutDiv ) PLIB_OSC_ResetPLLAssert Function Asserts the PLL reset for selected PLL. File plib_osc.h C void PLIB_OSC_ResetPLLAssert(OSC_MODULE_ID index, OSC_PLL_SELECT pllSel); Returns None. Description This function is used to assert the PLL reset for the selected PLL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1358 PLIB_OSC_ExistsResetPLL in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ResetPLLAssert(OSC_ID_0, OSC_PLL_USB); Parameters Parameters Description index Identifies the desired oscillator module pllSel PLL for which reset to be asserted Function void PLIB_OSC_ResetPLLAssert ( OSC_MODULE_ID index, OSC_PLL_SELECT pllSel) PLIB_OSC_ResetPLLDeassert Function Deasserts the PLL reset for selected PLL. File plib_osc.h C void PLIB_OSC_ResetPLLDeassert(OSC_MODULE_ID index, OSC_PLL_SELECT pllSel); Returns None. Description This function is used to deassert the PLL reset for the selected PLL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsResetPLL in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ResetPLLDeassert(OSC_ID_0, OSC_PLL_USB); Parameters Parameters Description index Identifies the desired oscillator module pllSel PLL for which reset to be deasserted Function void PLIB_OSC_ResetPLLDeassert ( OSC_MODULE_ID index, OSC_PLL_SELECT pllSel) PLIB_OSC_ResetPLLStatus Function gets the status of the PLL reset bit for the specified PLL. File plib_osc.h C bool PLIB_OSC_ResetPLLStatus(OSC_MODULE_ID index, OSC_PLL_SELECT pllSel); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1359 Returns Status of PLL reset bit for the specified PLL. Description This function is used to get the status of the PLL reset bit for the specified PLL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsResetPLL in your application to determine whether this feature is available. Preconditions None. Example bool upllReset = PLIB_OSC_ResetPLLStatus(OSC_ID_0, OSC_PLL_USB); Parameters Parameters Description index Identifies the desired oscillator module pllSel PLL whose reset status to be checked Function bool PLIB_OSC_ResetPLLStatus ( OSC_MODULE_ID index, OSC_PLL_SELECT pllSel) i) Peripheral Clock Setup Functions PLIB_OSC_PBClockDivisorGet Function Gets the peripheral bus clock divisor. File plib_osc.h C OSC_PB_CLOCK_DIV_TYPE PLIB_OSC_PBClockDivisorGet(OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber); Returns One of the possible values of PB clock divisor of type OSC_PB_CLOCK_DIV_TYPE. Description This function returns the peripheral bus clock divisor. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockDivisor in your application to determine whether this feature is available. Actual Divisor value will be returned, NOT the 'PBDIV' field value. Refer the data sheet of the device for the detail. Preconditions None. Example OSC_PB_CLOCK_DIV_TYPE peripheralBusClkDiv; peripheralBusClkDiv = PLIB_OSC_PBClockDivisorGet(OSC_ID_0, OSC_PERIPHERAL_BUS_1); Parameters Parameters Description index Identifies the desired oscillator module Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1360 peripheralBusNumber Identifies the desired peripheral bus Function OSC_PB_CLOCK_DIV_TYPE PLIB_OSC_PBClockDivisorGet ( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ) PLIB_OSC_PBClockDivisorIsReady Function Checks whether the peripheral bus clock divisor is ready to be written. File plib_osc.h C bool PLIB_OSC_PBClockDivisorIsReady(OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber); Returns • true - The peripheral bus clock divisor can be written • false - The peripheral bus clock divisor cannot be written Description This function checks whether the peripheral bus clock divisor is ready to be written. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockReady in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_OSC_PBClockDivisorIsReady(OSC_ID_0, OSC_PERIPHERAL_BUS_1)) { PLIB_OSC_PBClockDivisorSet (OSC_ID_0, OSC_PERIPHERAL_BUS_1, 0x01); } Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus Function bool PLIB_OSC_PBClockDivisorIsReady( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ) PLIB_OSC_PBClockDivisorSet Function Sets the peripheral bus clock divisor to the specified value. File plib_osc.h C void PLIB_OSC_PBClockDivisorSet(OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber, OSC_PB_CLOCK_DIV_TYPE peripheralBusClkDiv); Returns None. Description This function sets the peripheral bus clock divisor to the specified value. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1361 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockDivisor in your application to determine whether this feature is available. Use PB Divider value directly for the parameter 'peripheralBusClkDiv', and NOT the value of the 'PBDIV' field. Use of the PB Divider value is not supported by the selected device, and therefore, library behavior is undefined. Refer the the specific device data sheet for information. Preconditions Peripheral bus clock divisor should be ready to be written. Example PLIB_OSC_PBClockDivisorSet (OSC_ID_0, OSC_PERIPHERAL_BUS_1, 0x01); Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus peripheralBusClkDiv One of the possible values of PB clock divisor of type OSC_PB_CLOCK_DIV_TYPE Function void PLIB_OSC_PBClockDivisorSet( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber, OSC_PB_CLOCK_DIV_TYPE peripheralBusClkDiv ) PLIB_OSC_PBOutputClockDisable Function Disables the peripheral bus output clock. File plib_osc.h C void PLIB_OSC_PBOutputClockDisable(OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber); Returns None Description This function disables the peripheral bus output clock. Remarks The clock for peripheral bus 1 cannot be turned off. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockOutputEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_PBOutputClockDisable (OSC_ID_0, OSC_PERIPHERAL_BUS_2); Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus Function void PLIB_OSC_PBOutputClockDisable( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1362 PLIB_OSC_PBOutputClockEnable Function Enables the peripheral bus output clock File plib_osc.h C void PLIB_OSC_PBOutputClockEnable(OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber); Returns None Description This function enables the peripheral bus output clock Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockOutputEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_PBOutputClockEnable (OSC_ID_0, OSC_PERIPHERAL_BUS_2); Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus Function void PLIB_OSC_PBOutputClockEnable( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ) PLIB_OSC_PBOutputClockIsEnabled Function Checks whether or not the peripheral bus clock output is enabled. File plib_osc.h C bool PLIB_OSC_PBOutputClockIsEnabled(OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber); Returns • true - The peripheral bus clock output is enabled • false - The peripheral bus clock output is disabled Description This function checks whether or not the peripheral bus clock output is enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockOutputEnable in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_OSC_PBOutputClockIsEnabled(OSC_ID_0, OSC_PERIPHERAL_BUS_2)) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1363 { PLIB_OSC_PBOutputClockDisable(OSC_ID_0, OSC_PERIPHERAL_BUS_2); } Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus Function bool PLIB_OSC_PBOutputClockIsEnabled( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ) j) Clock Functions PLIB_OSC_ClockHasFailed Function Returns 'true' if the clock fails. File plib_osc.h C bool PLIB_OSC_ClockHasFailed(OSC_MODULE_ID index); Returns • true - The FSCM detected a clock failure • false - The no clock failure has been detected Description This function returns 'true' if the clock fails. Monitors the Fail-Safe Clock Monitor (FSCM). Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsClockFail in your application to determine whether this feature is available. Preconditions None. Example bool clockStatus; clockStatus = PLIB_OSC_ClockHasFailed(OSC_ID_0); Parameters Parameters Description index Identifies the desired oscillator module Function bool PLIB_OSC_ClockHasFailed ( OSC_MODULE_ID index ); PLIB_OSC_ClockStart Function Starts the specified clock source. File plib_osc.h C void PLIB_OSC_ClockStart(OSC_MODULE_ID index, OSC_CLOCK_DIAG clk); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1364 Returns None. Description This function is used to start a specified clock source if it has already been stopped. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsClockDiagStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ClockStart(OSC_ID_0, OSC_CLOCK_POSC_STOP); Parameters Parameters Description index Identifies the desired oscillator module clk Clock to be started Function void PLIB_OSC_ClockStart ( OSC_MODULE_ID index, OSC_CLOCK_DIAG clk) PLIB_OSC_ClockStop Function Stops the specified clock source. File plib_osc.h C void PLIB_OSC_ClockStop(OSC_MODULE_ID index, OSC_CLOCK_DIAG clk); Returns None. Description This function is used to stop a specified clock source. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsClockDiagStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_OSC_ClockStop(OSC_ID_0, OSC_CLOCK_POSC_STOP); Parameters Parameters Description index Identifies the desired oscillator module clk Clock to be stopped Function void PLIB_OSC_ClockStop ( OSC_MODULE_ID index, OSC_CLOCK_DIAG clk) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1365 PLIB_OSC_ClockStopStatus Function returns the status of clock stop bit for the specified clock source. File plib_osc.h C bool PLIB_OSC_ClockStopStatus(OSC_MODULE_ID index, OSC_CLOCK_DIAG clk); Returns Status of the clock stop bit for a specified clock source. Description This function is used to get the status of clock stop bit for the specified clock source. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsClockDiagStatus in your application to determine whether this feature is available. Preconditions None. Example bool PoscStat = PLIB_OSC_ClockStart(OSC_ID_0, OSC_CLOCK_POSC_STOP); Parameters Parameters Description index Identifies the desired oscillator module clk Clock source whose status to be checked Function bool PLIB_OSC_ClockStopStatus ( OSC_MODULE_ID index, OSC_CLOCK_DIAG clk) k) Feature Existence Functions PLIB_OSC_ExistsClockFail Function Identifies whether the ClockFail feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsClockFail(OSC_MODULE_ID index); Returns • true - If the ClockFail feature is supported on the device • false - If the ClockFail feature is not supported on the device Description This function identifies whether the ClockFail feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ClockHasFailed Remarks None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1366 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsClockFail( OSC_MODULE_ID index ) PLIB_OSC_ExistsFRCDivisor Function Identifies whether the FRCDivisor feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsFRCDivisor(OSC_MODULE_ID index); Returns • true - If the FRCDivisor feature is supported on the device • false - If the FRCDivisor feature is not supported on the device Description This function identifies whether the FRCDivisor feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_FRCDivisorSelect • PLIB_OSC_FRCDivisorGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsFRCDivisor( OSC_MODULE_ID index ) PLIB_OSC_ExistsFRCTuning Function Identifies whether the FRCTuning feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsFRCTuning(OSC_MODULE_ID index); Returns • true - If the FRCTuning feature is supported on the device • false - If the FRCTuning feature is not supported on the device Description This function identifies whether the FRCTuning feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1367 • PLIB_OSC_FRCTuningSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsFRCTuning( OSC_MODULE_ID index ) PLIB_OSC_ExistsOnWaitAction Function Identifies whether the OnWaitAction feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsOnWaitAction(OSC_MODULE_ID index); Returns • true - If the OnWaitAction feature is supported on the device • false - If the OnWaitAction feature is not supported on the device Description This function identifies whether the OnWaitAction feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_OnWaitActionSet • PLIB_OSC_OnWaitActionGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsOnWaitAction( OSC_MODULE_ID index ) PLIB_OSC_ExistsOscCurrentGet Function Identifies whether the OscCurrentGet feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsOscCurrentGet(OSC_MODULE_ID index); Returns • true - If the OscCurrentGet feature is supported on the device • false - If the OscCurrentGet feature is not supported on the device Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1368 Description This function identifies whether the OscCurrentGet feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_CurrentSysClockGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsOscCurrentGet( OSC_MODULE_ID index ) PLIB_OSC_ExistsOscSelect Function Identifies whether the OscSelect feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsOscSelect(OSC_MODULE_ID index); Returns • true - If the OscSelect feature is supported on the device • false - If the OscSelect feature is not supported on the device Description This function identifies whether the OscSelect feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysClockSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsOscSelect( OSC_MODULE_ID index ) PLIB_OSC_ExistsOscSwitchInit Function Identifies whether the OscSwitchInit feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsOscSwitchInit(OSC_MODULE_ID index); Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1369 Returns • true - If the OscSwitchInit feature is supported on the device • false - If the OscSwitchInit feature is not supported on the device Description This function identifies whether the OscSwitchInit feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ClockSwitchingAbort • PLIB_OSC_ClockSwitchingIsComplete Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsOscSwitchInit( OSC_MODULE_ID index ) PLIB_OSC_ExistsPBClockDivisor Function Identifies whether the PBClockDivisor feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsPBClockDivisor(OSC_MODULE_ID index); Returns • true - If the PBClockDivisor feature is supported on the device • false - If the PBClockDivisor feature is not supported on the device Description This function identifies whether the PBClockDivisor feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PBClockDivisorGet • PLIB_OSC_PBClockDivisorSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsPBClockDivisor( OSC_MODULE_ID index ) PLIB_OSC_ExistsPBClockOutputEnable Function Identifies whether the PBClockOutputEnable feature exists on the Oscillator module. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1370 File plib_osc.h C bool PLIB_OSC_ExistsPBClockOutputEnable(OSC_MODULE_ID index); Returns • true - If the PBClockOutputEnable feature is supported on the device • false - If the PBClockOutputEnable feature is not supported on the device Description This function identifies whether the PBClockOutputEnable feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PBOutputClockEnable • PLIB_OSC_PBOutputClockDisable • PLIB_OSC_PBOutputClockIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsPBClockOutputEnable( OSC_MODULE_ID index ) PLIB_OSC_ExistsPBClockReady Function Identifies whether the PBClockReady feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsPBClockReady(OSC_MODULE_ID index); Returns • true - If the PBClockReady feature is supported on the device • false - If the PBClockReady feature is not supported on the device Description This function identifies whether the PBClockReady feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PBClockDivisorIsReady Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsPBClockReady( OSC_MODULE_ID index ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1371 PLIB_OSC_ExistsPLLClockLock Function Identifies whether the PLLClockLock feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsPLLClockLock(OSC_MODULE_ID index); Returns • true - If the PLLClockLock feature is supported on the device • false - If the PLLClockLock feature is not supported on the device Description This function identifies whether the PLLClockLock feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PLLClockLock • PLIB_OSC_PLLClockUnlock • PLIB_OSC_PLLClockIsLocked Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsPLLClockLock( OSC_MODULE_ID index ) PLIB_OSC_ExistsPLLLockStatus Function Identifies whether the PLLLockStatus feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsPLLLockStatus(OSC_MODULE_ID index); Returns • true - If the PLLLockStatus feature is supported on the device • false - If the PLLLockStatus feature is not supported on the device Description This function identifies whether the PLLLockStatus feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PLLIsLocked Remarks None. Preconditions None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1372 Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsPLLLockStatus( OSC_MODULE_ID index ) PLIB_OSC_ExistsReferenceOscBaseClock Function Identifies whether the ReferenceOscBaseClock feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsReferenceOscBaseClock(OSC_MODULE_ID index); Returns • true - If the ReferenceOscBaseClock feature is supported on the device • false - If the ReferenceOscBaseClock feature is not supported on the device Description This function identifies whether the ReferenceOscBaseClock feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscBaseClockSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsReferenceOscBaseClock( OSC_MODULE_ID index ) PLIB_OSC_ExistsReferenceOscChange Function Identifies whether the ReferenceOscChange feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsReferenceOscChange(OSC_MODULE_ID index); Returns • true - If the ReferenceOscChange feature is supported on the device • false - If the ReferenceOscChange feature is not supported on the device Description This function identifies whether the ReferenceOscChange feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscSwitchIsComplete Remarks None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1373 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsReferenceOscChange( OSC_MODULE_ID index ) PLIB_OSC_ExistsReferenceOscChangeActive Function Identifies whether the ReferenceOscChangeActive feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsReferenceOscChangeActive(OSC_MODULE_ID index); Returns • true - If the ReferenceOscChangeActive feature is supported on the device • false - If the ReferenceOscChangeActive feature is not supported on the device Description This function identifies whether the ReferenceOscChangeActive feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscSourceChangeIsActive Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsReferenceOscChangeActive( OSC_MODULE_ID index ) PLIB_OSC_ExistsReferenceOscDivisor Function Identifies whether the ReferenceOscDivisor feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsReferenceOscDivisor(OSC_MODULE_ID index); Returns • true - If the ReferenceOscDivisor feature is supported on the device • false - If the ReferenceOscDivisor feature is not supported on the device Description This function identifies whether the ReferenceOscDivisor feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscDivisorValueSet Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1374 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsReferenceOscDivisor( OSC_MODULE_ID index ) PLIB_OSC_ExistsReferenceOscEnable Function Identifies whether the ReferenceOscEnable feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsReferenceOscEnable(OSC_MODULE_ID index); Returns • true - If the ReferenceOscEnable feature is supported on the device • false - If the ReferenceOscEnable feature is not supported on the device Description This function identifies whether the ReferenceOscEnable feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscEnable • PLIB_OSC_ReferenceOscDisable • PLIB_OSC_ReferenceOscIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsReferenceOscEnable( OSC_MODULE_ID index ) PLIB_OSC_ExistsReferenceOscStopInIdleEnable Function Identifies whether the ReferenceOscStopInIdleEnable feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsReferenceOscStopInIdleEnable(OSC_MODULE_ID index); Returns • true - If the ReferenceOscStopInIdleEnable feature is supported on the device • false - If the ReferenceOscStopInIdleEnable feature is not supported on the device Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1375 Description This function identifies whether the ReferenceOscStopInIdleEnable feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscStopInIdleEnable • PLIB_OSC_ReferenceOscStopInIdleDisable • PLIB_OSC_ReferenceOscStopInIdleIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsReferenceOscStopInIdleEnable( OSC_MODULE_ID index ) PLIB_OSC_ExistsReferenceOscStopInSleep Function Identifies whether the ReferenceOscStopInSleep feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsReferenceOscStopInSleep(OSC_MODULE_ID index); Returns • true - If the ReferenceOscStopInSleep feature is supported on the device • false - If the ReferenceOscStopInSleep feature is not supported on the device Description This function identifies whether the ReferenceOscStopInSleep feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscStopInSleepEnable • PLIB_OSC_ReferenceOscStopInSleepDisable • PLIB_OSC_ReferenceOscStopInSleepIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsReferenceOscStopInSleep( OSC_MODULE_ID index ) PLIB_OSC_ExistsReferenceOscTrim Function Identifies whether the ReferenceOscTrim feature exists on the Oscillator module. File plib_osc.h Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1376 C bool PLIB_OSC_ExistsReferenceOscTrim(OSC_MODULE_ID index); Returns • true - If the ReferenceOscTrim feature is supported on the device • false - If the ReferenceOscTrim feature is not supported on the device Description This function identifies whether the ReferenceOscTrim feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscTrimSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsReferenceOscTrim( OSC_MODULE_ID index ) PLIB_OSC_ExistsReferenceOutputEnable Function Identifies whether the ReferenceOutputEnable feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsReferenceOutputEnable(OSC_MODULE_ID index); Returns • true - If the ReferenceOutputEnable feature is supported on the device • false - If the ReferenceOutputEnable feature is not supported on the device Description This function identifies whether the ReferenceOutputEnable feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOutputEnable • PLIB_OSC_ReferenceOutputDisable • PLIB_OSC_ReferenceOutputIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsReferenceOutputEnable( OSC_MODULE_ID index ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1377 PLIB_OSC_ExistsSecondaryEnable Function Identifies whether the SecondaryEnable feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSecondaryEnable(OSC_MODULE_ID index); Returns • true - If the SecondaryEnable feature is supported on the device • false - If the SecondaryEnable feature is not supported on the device Description This function identifies whether the SecondaryEnable feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SecondaryEnable • PLIB_OSC_SecondaryDisable • PLIB_OSC_SecondaryIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSecondaryEnable( OSC_MODULE_ID index ) PLIB_OSC_ExistsSecondaryReady Function Identifies whether the SecondaryReady feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSecondaryReady(OSC_MODULE_ID index); Returns • true - If the SecondaryReady feature is supported on the device • false - If the SecondaryReady feature is not supported on the device Description This function identifies whether the SecondaryReady feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SecondaryIsReady Remarks None. Preconditions None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1378 Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSecondaryReady( OSC_MODULE_ID index ) PLIB_OSC_ExistsSysPLLFrequencyRange Function Identifies whether the PLLFrequencyRange feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSysPLLFrequencyRange(OSC_MODULE_ID index); Returns • true - If the PLLFrequencyRange feature is supported on the device • false - If the PLLFrequencyRange feature is not supported on the device Description This function identifies whether the PLLFrequencyRange feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLFrequencyRangeSet • PLIB_OSC_SysPLLFrequencyRangeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSysPLLFrequencyRange( OSC_MODULE_ID index ) PLIB_OSC_ExistsSysPLLInputClockSource Function Identifies whether the PLLInputClockSource feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSysPLLInputClockSource(OSC_MODULE_ID index); Returns • true - If the PLLInputClockSource feature is supported on the device • false - If the PLLInputClockSource feature is not supported on the device Description This function identifies whether the PLLInputClockSource feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLInputClockSourceSet • PLIB_OSC_SysPLLInputClockSourceGet Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1379 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSysPLLInputClockSource( OSC_MODULE_ID index ) PLIB_OSC_ExistsSysPLLInputDivisor Function Identifies whether the PLLInputDivisor feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSysPLLInputDivisor(OSC_MODULE_ID index); Returns • true - If the PLLInputDivisor feature is supported on the device • false - If the PLLInputDivisor feature is not supported on the device Description This function identifies whether the PLLInputDivisor feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLInputDivisorSet • PLIB_OSC_SysPLLInputDivisorGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSysPLLInputDivisor( OSC_MODULE_ID index ) PLIB_OSC_ExistsSysPLLMultiplier Function Identifies whether the PLLMultiplier feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSysPLLMultiplier(OSC_MODULE_ID index); Returns • true - If the PLLMultiplier feature is supported on the device • false - If the PLLMultiplier feature is not supported on the device Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1380 Description This function identifies whether the PLLMultiplier feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLMultiplierSelect • PLIB_OSC_SysPLLMultiplierGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSysPLLMultiplier( OSC_MODULE_ID index ) PLIB_OSC_ExistsSysPLLOutputDivisor Function Identifies whether the PLLOutputDivisor feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSysPLLOutputDivisor(OSC_MODULE_ID index); Returns • true - If the PLLOutputDivisor feature is supported on the device • false - If the PLLOutputDivisor feature is not supported on the device Description This function identifies whether the PLLOutputDivisor feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLOutputDivisorSet • PLIB_OSC_SysPLLOutputDivisorGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSysPLLOutputDivisor( OSC_MODULE_ID index ) PLIB_OSC_ExistsUsbClockSource Function Identifies whether the UsbClockSource feature exists on the Oscillator module. File plib_osc.h Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1381 C bool PLIB_OSC_ExistsUsbClockSource(OSC_MODULE_ID index); Returns • true - If the UsbClockSource feature is supported on the device • false - If the UsbClockSource feature is not supported on the device Description This function identifies whether the UsbClockSource feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_UsbClockSourceSelect • PLIB_OSC_UsbClockSourceGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsUsbClockSource( OSC_MODULE_ID index ) PLIB_OSC_ExistsClockReadyStatus Function Identifies whether the ClockReadyStatus feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsClockReadyStatus(OSC_MODULE_ID index); Returns • true - The ClockReadyStatus feature is supported on the device • false - The ClockReadyStatus feature is not supported on the device Description This function identifies whether the ClockReadyStatus feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ClockIsReady Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsClockReadyStatus( OSC_MODULE_ID index ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1382 PLIB_OSC_ExistsClockSlewingStatus Function Identifies whether the ClockSlewingStatus feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsClockSlewingStatus(OSC_MODULE_ID index); Returns • true - The ClockSlewingStatus feature is supported on the device • false - The ClockSlewingStatus feature is not supported on the device Description This function identifies whether the ClockSlewingStatus feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ClockSlewingIsActive Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsClockSlewingStatus( OSC_MODULE_ID index ) PLIB_OSC_ExistsSleepToStartupClock Function Identifies whether the SleepToStartupClock feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSleepToStartupClock(OSC_MODULE_ID index); Returns • true - The SleepToStartupClock feature is supported on the device • false - The SleepToStartupClock feature is not supported on the device Description This function identifies whether the SleepToStartupClock feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SleepToStartupClockSelect • PLIB_OSC_SleepToStartupClockGet Remarks None. Preconditions None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1383 Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSleepToStartupClock( OSC_MODULE_ID index ) PLIB_OSC_ExistsSlewDivisorStepControl Function Identifies whether the SlewDivisorStepControl feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSlewDivisorStepControl(OSC_MODULE_ID index); Returns • true - The SlewDivisorStepControl feature is supported on the device • false - The SlewDivisorStepControl feature is not supported on the device Description This function identifies whether the SlewDivisorStepControl feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SlewDivisorStepSelect • PLIB_OSC_SlewDivisorStepGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSlewDivisorStepControl( OSC_MODULE_ID index ) PLIB_OSC_ExistsSlewEnableControl Function Identifies whether the SlewEnableControl feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSlewEnableControl(OSC_MODULE_ID index); Returns • true - The SlewEnableControl feature is supported on the device • false - The SlewEnableControl feature is not supported on the device Description This function identifies whether the SlewEnableControl feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SlewEnable • PLIB_OSC_SlewDisable • PLIB_OSC_SlewIsEnabled Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1384 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSlewEnableControl( OSC_MODULE_ID index ) PLIB_OSC_ExistsSystemClockDivisorControl Function Identifies whether the SystemClockDivisorControl feature exists on the Oscillator module. File plib_osc.h C bool PLIB_OSC_ExistsSystemClockDivisorControl(OSC_MODULE_ID index); Returns • true - The SystemClockDivisorControl feature is supported on the device • false - The SystemClockDivisorControl feature is not supported on the device Description This function identifies whether the SystemClockDivisorControl feature is available on the Oscillator module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SystemClockDivisorSelect • PLIB_OSC_SystemClockDivisorGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsSystemClockDivisorControl( OSC_MODULE_ID index ) PLIB_OSC_ExistsBTPLLClockOut Function Identifies whether the BTPLLClockOut feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsBTPLLClockOut(OSC_MODULE_ID index); Returns • true - The BTPLLClockOut feature is supported on the device • false - The BTPLLClockOut feature is not supported on the device Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1385 Description This function identifies whether the BTPLLClockOut feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_BTPLLClockOutEnable • PLIB_OSC_BTPLLClockOutDisable • PLIB_OSC_BTPLLClockOutStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsBTPLLClockOut( OSC_MODULE_ID index ) PLIB_OSC_ExistsBTPLLFrequencyRange Function Identifies whether the BTPLLFrequencyRange feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsBTPLLFrequencyRange(OSC_MODULE_ID index); Returns • true - The BTPLLFrequencyRange feature is supported on the device • false - The BTPLLFrequencyRange feature is not supported on the device Description This function identifies whether the BTPLLFrequencyRange feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_BTPLLFrequencyRangeSet • PLIB_OSC_BTPLLFrequencyRangeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsBTPLLFrequencyRange( OSC_MODULE_ID index ) PLIB_OSC_ExistsBTPLLInputClockSource Function Identifies whether the BTPLLInputClockSource feature exists on the OSC module File plib_osc.h Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1386 C bool PLIB_OSC_ExistsBTPLLInputClockSource(OSC_MODULE_ID index); Returns • true - The BTPLLInputClockSource feature is supported on the device • false - The BTPLLInputClockSource feature is not supported on the device Description This function identifies whether the BTPLLInputClockSource feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_BTPLLInputClockSourceSet • PLIB_OSC_BTPLLInputClockSourceGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsBTPLLInputClockSource( OSC_MODULE_ID index ) PLIB_OSC_ExistsBTPLLInputDivisor Function Identifies whether the BTPLLInputDivisor feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsBTPLLInputDivisor(OSC_MODULE_ID index); Returns • true - The BTPLLInputDivisor feature is supported on the device • false - The BTPLLInputDivisor feature is not supported on the device Description This function identifies whether the BTPLLInputDivisor feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_BTPLLInputDivisorSet • PLIB_OSC_BTPLLInputDivisorGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsBTPLLInputDivisor( OSC_MODULE_ID index ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1387 PLIB_OSC_ExistsBTPLLMultiplier Function Identifies whether the BTPLLMultiplier feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsBTPLLMultiplier(OSC_MODULE_ID index); Returns • true - The BTPLLMultiplier feature is supported on the device • false - The BTPLLMultiplier feature is not supported on the device Description This function identifies whether the BTPLLMultiplier feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_BTPLLMultiplierSelect • PLIB_OSC_BTPLLMultiplierGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsBTPLLMultiplier( OSC_MODULE_ID index ) PLIB_OSC_ExistsBTPLLOutputDivisor Function Identifies whether the BTPLLOutputDivisor feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsBTPLLOutputDivisor(OSC_MODULE_ID index); Returns • true - The BTPLLOutputDivisor feature is supported on the device • false - The BTPLLOutputDivisor feature is not supported on the device Description This function identifies whether the BTPLLOutputDivisor feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_BTPLLOutputDivisorSet • PLIB_OSC_BTPLLOutputDivisorGet Remarks None. Preconditions None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1388 Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsBTPLLOutputDivisor( OSC_MODULE_ID index ) PLIB_OSC_ExistsClockDiagStatus Function Identifies whether the ClockDiagStatus feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsClockDiagStatus(OSC_MODULE_ID index); Returns • true - The ClockDiagStatus feature is supported on the device • false - The ClockDiagStatus feature is not supported on the device Description This function identifies whether the ClockDiagStatus feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ClockStop • PLIB_OSC_ClockStart • PLIB_OSC_ClockStopStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsClockDiagStatus( OSC_MODULE_ID index ) PLIB_OSC_ExistsDreamModeControl Function Identifies whether the DreamModeControl feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsDreamModeControl(OSC_MODULE_ID index); Returns • true - The DreamModeControl feature is supported on the device • false - The DreamModeControl feature is not supported on the device Description This function identifies whether the DreamModeControl feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_DreamModeEnable • PLIB_OSC_DreamModeDisable Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1389 • PLIB_OSC_DreamModeStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsDreamModeControl( OSC_MODULE_ID index ) PLIB_OSC_ExistsForceLock Function Identifies whether the ForceLock feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsForceLock(OSC_MODULE_ID index); Returns • true - The ForceLock feature is supported on the device • false - The ForceLock feature is not supported on the device Description This function identifies whether the ForceLock feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ForceSPLLLockEnable • PLIB_OSC_ForceSPLLLockDisable • PLIB_OSC_ForceSPLLLockStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsForceLock( OSC_MODULE_ID index ) PLIB_OSC_ExistsPLLBypass Function Identifies whether the SPLLBypass feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsPLLBypass(OSC_MODULE_ID index); Returns • true - The PLLBypass feature is supported on the device Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1390 • false - The PLLBypass feature is not supported on the device Description This function identifies whether the PLLBypass feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PLLBypassEnable • PLIB_OSC_PLLBypassDisable • PLIB_OSC_PLLBypassStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsPLLBypass( OSC_MODULE_ID index ) PLIB_OSC_ExistsResetPLL Function Identifies whether the ResetPLL feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsResetPLL(OSC_MODULE_ID index); Returns • true - The ResetPLL feature is supported on the device • false - The ResetPLL feature is not supported on the device Description This function identifies whether the ResetPLL feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ResetPLLAssert • PLIB_OSC_ResetPLLDeassert • PLIB_OSC_ResetPLLStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsResetPLL( OSC_MODULE_ID index ) PLIB_OSC_ExistsUPLLFrequencyRange Function Identifies whether the UPLLFrequencyRange feature exists on the OSC module Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1391 File plib_osc.h C bool PLIB_OSC_ExistsUPLLFrequencyRange(OSC_MODULE_ID index); Returns • true - The UPLLFrequencyRange feature is supported on the device • false - The UPLLFrequencyRange feature is not supported on the device Description This function identifies whether the UPLLFrequencyRange feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_UPLLFrequencyRangeSet • PLIB_OSC_UPLLFrequencyRangeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsUPLLFrequencyRange( OSC_MODULE_ID index ) PLIB_OSC_ExistsUPLLInputDivisor Function Identifies whether the UPLLInputDivisor feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsUPLLInputDivisor(OSC_MODULE_ID index); Returns • true - The UPLLInputDivisor feature is supported on the device • false - The UPLLInputDivisor feature is not supported on the device Description This function identifies whether the UPLLInputDivisor feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_UPLLInputDivisorSet • PLIB_OSC_UPLLInputDivisorGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsUPLLInputDivisor( OSC_MODULE_ID index ) Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1392 PLIB_OSC_ExistsUPLLMultiplier Function Identifies whether the UPLLMultiplier feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsUPLLMultiplier(OSC_MODULE_ID index); Returns • true - The UPLLMultiplier feature is supported on the device • false - The UPLLMultiplier feature is not supported on the device Description This function identifies whether the UPLLMultiplier feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_UPLLMultiplierSelect • PLIB_OSC_UPLLMultiplierGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsUPLLMultiplier( OSC_MODULE_ID index ) PLIB_OSC_ExistsUPLLOutputDivisor Function Identifies whether the UPLLOutputDivisor feature exists on the OSC module File plib_osc.h C bool PLIB_OSC_ExistsUPLLOutputDivisor(OSC_MODULE_ID index); Returns • true - The UPLLOutputDivisor feature is supported on the device • false - The UPLLOutputDivisor feature is not supported on the device Description This function identifies whether the UPLLOutputDivisor feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_UPLLOutputDivisorSet • PLIB_OSC_UPLLOutputDivisorGet Remarks None. Preconditions None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1393 Parameters Parameters Description index Identifier for the device instance Function PLIB_OSC_ExistsUPLLOutputDivisor( OSC_MODULE_ID index ) l) Data Types and Constants OSC_PB_CLOCK_DIV_TYPE Macro Type of the oscillator PB Clock divisor value. File plib_osc_help.h C #define OSC_PB_CLOCK_DIV_TYPE SFR_TYPE Description Oscillator Peripheral Bus Clock Divisor Value Type This macro defines the type of the oscillator PB Clock divisor value. Remarks None. OSC_REF_DIVISOR_TYPE Macro Reference oscillator divisor type. File plib_osc_help.h C #define OSC_REF_DIVISOR_TYPE SFR_TYPE Description Reference oscillator divisor type This macro defines the reference oscillator divisor type. Please refer to the specific device data sheet to determine the possible values of this type. Remarks None. OSC_REFERENCE_MAX_DIV Macro Defines the reference clock output divisor maximum value. File plib_osc_help.h C #define OSC_REFERENCE_MAX_DIV 65534 Description Reference clock output divisor maximum This macro defines the reference clock output divisor maximum value. Remarks None. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1394 OSC_SYSPLL_MULTIPLIER_TYPE Macro Type of the oscillator system PLL multiplier value. File plib_osc_help.h C #define OSC_SYSPLL_MULTIPLIER_TYPE SFR_TYPE Description Oscillator System PLL Multiplier Value Type This macro defines the type of the oscillator system PLL multiplier value. Remarks None. OSC_FRC_DIV Enumeration Lists the possible Fast RC (FRC) Oscillator divider values. File plib_osc_help.h C typedef enum { OSC_FRC_DIV_1, OSC_FRC_DIV_2, OSC_FRC_DIV_4, OSC_FRC_DIV_8, OSC_FRC_DIV_16, OSC_FRC_DIV_32, OSC_FRC_DIV_64, OSC_FRC_DIV_256 } OSC_FRC_DIV; Members Members Description OSC_FRC_DIV_1 Fast RC Oscillator output Divide by 1 OSC_FRC_DIV_2 Fast RC Oscillator output Divide by 2 OSC_FRC_DIV_4 Fast RC Oscillator output Divide by 4 OSC_FRC_DIV_8 Fast RC Oscillator output Divide by 8 OSC_FRC_DIV_16 Fast RC Oscillator output Divide by 16 OSC_FRC_DIV_32 Fast RC Oscillator output Divide by 32 OSC_FRC_DIV_64 Fast RC Oscillator output Divide by 64 OSC_FRC_DIV_256 Fast RC Oscillator output Divide by 256 Description FRC divider. This enumeration lists the possible FRC Oscillator divider values. Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_MODULE_ID Enumeration Possible instances of the OSC module. File plib_osc_help.h Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1395 C typedef enum { OSC_ID_0 } OSC_MODULE_ID; Members Members Description OSC_ID_0 first instance of the OSC Description OSC module ID This data type defines the possible instances of the Oscillator module. Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_OPERATION_ON_WAIT Enumeration Lists the possible base clock values for the reference oscillator. File plib_osc_help.h C typedef enum { OSC_REF_BASECLOCK_SYSCLK, OSC_REF_BASECLOCK_PBCLK, OSC_REF_BASECLOCK_PRIMARY, OSC_REF_BASECLOCK_FRC, OSC_REF_BASECLOCK_LPRC, OSC_REF_BASECLOCK_SOSC, OSC_REF_BASECLOCK_USBCLK, OSC_REF_BASECLOCK_SYSPLLOUT, OSC_ON_WAIT_IDLE, OSC_ON_WAIT_SLEEP } OSC_OPERATION_ON_WAIT; Members Members Description OSC_REF_BASECLOCK_SYSCLK The base clock for reference clock is System Clock OSC_REF_BASECLOCK_PBCLK The base clock for reference clock is Peripheral Clock OSC_REF_BASECLOCK_PRIMARY The base clock for reference clock is Primary Oscillator OSC_REF_BASECLOCK_FRC The base clock for reference clock is FRC Oscillator OSC_REF_BASECLOCK_LPRC The base clock for reference clock is internal Low-Power RC OSC_REF_BASECLOCK_SOSC The base clock for reference clock is Secondary Oscillator OSC_REF_BASECLOCK_USBCLK The base clock for reference clock is USB Clock OSC_REF_BASECLOCK_SYSPLLOUT The base clock for reference clock is System PLL output OSC_ON_WAIT_IDLE Idle on Wait Instruction OSC_ON_WAIT_SLEEP Idle on Sleep Instruction Description Base clock for reference oscillator. This enumeration lists the possible base clock values for the reference oscillator. Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_PERIPHERAL_BUS Enumeration Lists the possible Peripheral buses. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1396 File plib_osc_help.h C typedef enum { OSC_PERIPHERAL_BUS_1, OSC_PERIPHERAL_BUS_2, OSC_PERIPHERAL_BUS_3, OSC_PERIPHERAL_BUS_4, OSC_PERIPHERAL_BUS_5, OSC_PERIPHERAL_BUS_6, OSC_PERIPHERAL_BUS_7, OSC_PERIPHERAL_BUS_8 } OSC_PERIPHERAL_BUS; Members Members Description OSC_PERIPHERAL_BUS_1 Peripheral bus 1 OSC_PERIPHERAL_BUS_2 Peripheral bus 2 OSC_PERIPHERAL_BUS_3 Peripheral bus 3 OSC_PERIPHERAL_BUS_4 Peripheral bus 4 OSC_PERIPHERAL_BUS_5 Peripheral bus 5 OSC_PERIPHERAL_BUS_6 Peripheral bus 6 OSC_PERIPHERAL_BUS_7 Peripheral bus 7 OSC_PERIPHERAL_BUS_8 Peripheral bus 8 Description Peripheral Buses This enumeration lists the possible peripheral buses available in the device Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_PLL_SELECT Enumeration Lists the PLLs in the Oscillator module. File plib_osc_help.h C typedef enum { OSC_PLL_SYSTEM, OSC_PLL_USB } OSC_PLL_SELECT; Members Members Description OSC_PLL_SYSTEM Select system PLL OSC_PLL_USB Select USB PLL Description Oscillator PLL selection. This enumeration lists the available PLLs in the Oscillator module. Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_REFERENCE Enumeration Lists the possible reference oscillator. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1397 File plib_osc_help.h C typedef enum { OSC_REFERENCE_1, OSC_REFERENCE_2, OSC_REFERENCE_3, OSC_REFERENCE_4 } OSC_REFERENCE; Members Members Description OSC_REFERENCE_1 Reference Oscillator 1 OSC_REFERENCE_2 Reference Oscillator 2 OSC_REFERENCE_3 Reference Oscillator 3 OSC_REFERENCE_4 Reference Oscillator 4 Description Reference Oscillators This enumeration lists the possible reference oscillator instances available in the device. Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_SYS_TYPE Enumeration Lists the possible oscillator type values. File plib_osc_help.h C typedef enum { OSC_FRC, OSC_FRC_WITH_PLL, OSC_PRIMARY, OSC_PRIMARY_WITH_PLL, OSC_SECONDARY, OSC_LPRC, OSC_FRC_DIV_BY_16, OSC_FRC_BY_FRCDIV } OSC_SYS_TYPE; Members Members Description OSC_FRC Fast RC Oscillator. This includes the 8 MHz oscillator OSC_FRC_WITH_PLL Fast RC Oscillator with PLL OSC_PRIMARY Primary Oscillator OSC_PRIMARY_WITH_PLL Fast RC Oscillator with PLL and PostScaler. Includes the 8MHz oscillator OSC_SECONDARY Secondary Oscillator OSC_LPRC Low Power RC Oscillator OSC_FRC_DIV_BY_16 Low-Power Fast RC Oscillator with PostScaler OSC_FRC_BY_FRCDIV Fast RC Oscillator divided by FRCDIV bits Description Oscillator type. This enumeration lists the possible oscillator type values. Remarks This enumeration is processor specific and is defined in the processor-specific header files. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1398 OSC_SYSPLL_FREQ_RANGE Enumeration Lists the possible PLL frequency range. File plib_osc_help.h C typedef enum { OSC_SYSPLL_FREQ_RANGE_BYPASS, OSC_SYSPLL_FREQ_RANGE_5M_TO_10M, OSC_SYSPLL_FREQ_RANGE_8M_TO_16M, OSC_SYSPLL_FREQ_RANGE_13M_TO_26M, OSC_SYSPLL_FREQ_RANGE_21M_TO_42M, OSC_SYSPLL_FREQ_RANGE_34M_TO_68M } OSC_SYSPLL_FREQ_RANGE; Members Members Description OSC_SYSPLL_FREQ_RANGE_BYPASS PLL freq range bypass OSC_SYSPLL_FREQ_RANGE_5M_TO_10M PLL frequency range is 5 MHz to 10 MHz OSC_SYSPLL_FREQ_RANGE_8M_TO_16M PLL frequency range is 8 MHz to 16 MHz OSC_SYSPLL_FREQ_RANGE_13M_TO_26M PLL frequency range is 13 MHz to 26 MHz OSC_SYSPLL_FREQ_RANGE_21M_TO_42M PLL frequency range is 21 MHz to 42 MHz OSC_SYSPLL_FREQ_RANGE_34M_TO_68M PLL frequency range is 34 MHz to 68 MHz Description System PLL Frequency Range This enumeration lists the possible frequency range for PLL module available in the device. Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_SYSPLL_IN_CLK_SOURCE Enumeration Lists the possible input clock source for PLL module. File plib_osc_help.h C typedef enum { OSC_SYSPLL_IN_CLK_SOURCE_FRC, OSC_SYSPLL_IN_CLK_SOURCE_PRIMARY } OSC_SYSPLL_IN_CLK_SOURCE; Members Members Description OSC_SYSPLL_IN_CLK_SOURCE_FRC FRC is input clock source for PLL module OSC_SYSPLL_IN_CLK_SOURCE_PRIMARY Primary clock is the input clock source for PLL module Description System PLL Input Clock Source This enumeration lists the possible input clock source for PLL module available in the device. Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_SYSPLL_OUT_DIV Enumeration Lists the possible PLL output divider values. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1399 File plib_osc_help.h C typedef enum { OSC_SYSPLL_OUT_DIV_1, OSC_SYSPLL_OUT_DIV_2, OSC_SYSPLL_OUT_DIV_4, OSC_SYSPLL_OUT_DIV_8, OSC_SYSPLL_OUT_DIV_16, OSC_SYSPLL_OUT_DIV_32, OSC_SYSPLL_OUT_DIV_64, OSC_SYSPLL_OUT_DIV_256 } OSC_SYSPLL_OUT_DIV; Members Members Description OSC_SYSPLL_OUT_DIV_1 Divide by 1 OSC_SYSPLL_OUT_DIV_2 Divide by 2 OSC_SYSPLL_OUT_DIV_4 Divide by 4 OSC_SYSPLL_OUT_DIV_8 Divide by 8 OSC_SYSPLL_OUT_DIV_16 Divide by 16 OSC_SYSPLL_OUT_DIV_32 Divide by 32 OSC_SYSPLL_OUT_DIV_64 Divide by 64 OSC_SYSPLL_OUT_DIV_256 Divide by 256 Description PLL Output divider. This enumeration lists the possible PLL output divider values. Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_USBCLOCK_SOURCE Enumeration Lists the possible USB clock sources. File plib_osc_help.h C typedef enum { SYS_OSC_USBCLK_PRIMARY, SYS_OSC_USBCLK_FRC } OSC_USBCLOCK_SOURCE; Members Members Description SYS_OSC_USBCLK_PRIMARY USB clock source is primary oscillator SYS_OSC_USBCLK_FRC USB clock source isFRC oscillator Description USB clock sources. This enumeration lists the the possible USB clock sources. Remarks This enumeration is processor specific and is defined in the processor-specific header files. OSC_CLOCK_ID Enumeration Lists the clock sources for which ready status can be checked. Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1400 File plib_osc_help.h C typedef enum { OSC_CLOCK_FAST_RC, OSC_CLOCK_PRIMARY_OSC, OSC_CLOCK_SECONDARY_OSC, OSC_CLOCK_LOW_POWER_RC, OSC_CLOCK_SYSTEM_PLL } OSC_CLOCK_ID; Members Members Description OSC_CLOCK_FAST_RC Fast RC Oscillator OSC_CLOCK_PRIMARY_OSC Primary Oscillator OSC_CLOCK_SECONDARY_OSC Secondary Oscillator OSC_CLOCK_LOW_POWER_RC Low Power RC Oscillator OSC_CLOCK_SYSTEM_PLL System PLL Description OSC Clock ID This enumeration lists all the possible clock sources for which the ready status can be checked. Remarks This feature may not be available in all the devices. Refer to the specific device header files for availability. OSC_CLOCK_SLEW_TYPE Enumeration Lists the possible type of clock slewing. File plib_osc_help.h C typedef enum { OSC_CLOCK_SLEW_DOWNWARD, OSC_CLOCK_SLEW_UPWARD } OSC_CLOCK_SLEW_TYPE; Members Members Description OSC_CLOCK_SLEW_DOWNWARD Slewing to a lower clock frequency OSC_CLOCK_SLEW_UPWARD Slewing to a higher clock frequency Description OSC Clock Slew Rate This enumeration lists the possible type of clock slewing. Remarks This feature may not be available in all the devices. Refer to the specific device header files for availability. OSC_SLEEP_TO_STARTUP_CLK_TYPE Enumeration Lists the possible clock sources for sleep to start-up period. File plib_osc_help.h C typedef enum { Peripheral Libraries Help Oscillator Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1401 OSC_SLEEP_TO_STARTUP_CLK_FRC, OSC_SLEEP_TO_STARTUP_NO_ADDITIONAL_CLK } OSC_SLEEP_TO_STARTUP_CLK_TYPE; Members Members Description OSC_SLEEP_TO_STARTUP_CLK_FRC FRC will be used after wakeup from sleep until selected clock is ready OSC_SLEEP_TO_STARTUP_NO_ADDITIONAL_CLK No additional clock will be used after wakeup from sleep, selected clock will be used directly once it is ready Description Sleep to Speed Startup Clock This enumeration lists the possible clock sources that can be used from the time when the device wakes from sleep until the actual clock source is ready to be used. Remarks This feature may not be available in all the devices. Check device specific header files for availability. Files Files Name Description plib_osc.h Defines the Oscillator (OSC) Peripheral Library interface. plib_osc_help.h Defines the Oscillator Peripheral Library data types. Description This section lists the source and header files used by the library. plib_osc.h Defines the Oscillator (OSC) Peripheral Library interface. Functions Name Description PLIB_OSC_BTPLLClockOutDisable Disables the Bluetooth PLL Clock Output. PLIB_OSC_BTPLLClockOutEnable Enables the Bluetooth PLL clock Ouput. PLIB_OSC_BTPLLClockOutStatus gets the status of the Bluetooth PLL clock Output. PLIB_OSC_BTPLLFrequencyRangeGet Gets the frequency range for the Bluetooth PLL module. PLIB_OSC_BTPLLFrequencyRangeSet Sets the frequency range for the Bluetooth PLL module. PLIB_OSC_BTPLLInputClockSourceGet Gets the input clock source for the Bluetooth PLL module. PLIB_OSC_BTPLLInputClockSourceSet Sets the input clock source for the Bluetooth PLL module. PLIB_OSC_BTPLLInputDivisorGet Gets the input divisor for the Bluetooth PLL. PLIB_OSC_BTPLLInputDivisorSet Sets the input divider for the Bluetooth PLL to the specified value. PLIB_OSC_BTPLLMultiplierGet Gets the Bluetooth PLL multiplier. PLIB_OSC_BTPLLMultiplierSelect Sets the Bluetooth PLL multiplier to the specified value. PLIB_OSC_BTPLLOutputDivisorGet Gets the output divisor for the PLL. PLIB_OSC_BTPLLOutputDivisorSet Sets the output divider for the Bluetooth PLL to the specified value. PLIB_OSC_ClockHasFailed Returns 'true' if the clock fails. PLIB_OSC_ClockIsReady Get the ready status of clock. PLIB_OSC_ClockSlewingIsActive Returns the status of clock slewing. PLIB_OSC_ClockStart Starts the specified clock source. PLIB_OSC_ClockStop Stops the specified clock source. PLIB_OSC_ClockStopStatus returns the status of clock stop bit for the specified clock source. PLIB_OSC_ClockSwitchingAbort Aborts an oscillator switch. PLIB_OSC_ClockSwitchingIsComplete Gets the oscillator switch progress status. PLIB_OSC_CurrentSysClockGet Gets the current oscillator selected. PLIB_OSC_DreamModeDisable Disables the dream mode. Peripheral Libraries Help Oscillator Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1402 PLIB_OSC_DreamModeEnable Enables the dream mode. PLIB_OSC_DreamModeStatus gets the status of the dream mode. PLIB_OSC_ExistsBTPLLClockOut Identifies whether the BTPLLClockOut feature exists on the OSC module PLIB_OSC_ExistsBTPLLFrequencyRange Identifies whether the BTPLLFrequencyRange feature exists on the OSC module PLIB_OSC_ExistsBTPLLInputClockSource Identifies whether the BTPLLInputClockSource feature exists on the OSC module PLIB_OSC_ExistsBTPLLInputDivisor Identifies whether the BTPLLInputDivisor feature exists on the OSC module PLIB_OSC_ExistsBTPLLMultiplier Identifies whether the BTPLLMultiplier feature exists on the OSC module PLIB_OSC_ExistsBTPLLOutputDivisor Identifies whether the BTPLLOutputDivisor feature exists on the OSC module PLIB_OSC_ExistsClockDiagStatus Identifies whether the ClockDiagStatus feature exists on the OSC module PLIB_OSC_ExistsClockFail Identifies whether the ClockFail feature exists on the Oscillator module. PLIB_OSC_ExistsClockReadyStatus Identifies whether the ClockReadyStatus feature exists on the Oscillator module. PLIB_OSC_ExistsClockSlewingStatus Identifies whether the ClockSlewingStatus feature exists on the Oscillator module. PLIB_OSC_ExistsDreamModeControl Identifies whether the DreamModeControl feature exists on the OSC module PLIB_OSC_ExistsForceLock Identifies whether the ForceLock feature exists on the OSC module PLIB_OSC_ExistsFRCDivisor Identifies whether the FRCDivisor feature exists on the Oscillator module. PLIB_OSC_ExistsFRCTuning Identifies whether the FRCTuning feature exists on the Oscillator module. PLIB_OSC_ExistsOnWaitAction Identifies whether the OnWaitAction feature exists on the Oscillator module. PLIB_OSC_ExistsOscCurrentGet Identifies whether the OscCurrentGet feature exists on the Oscillator module. PLIB_OSC_ExistsOscSelect Identifies whether the OscSelect feature exists on the Oscillator module. PLIB_OSC_ExistsOscSwitchInit Identifies whether the OscSwitchInit feature exists on the Oscillator module. PLIB_OSC_ExistsPBClockDivisor Identifies whether the PBClockDivisor feature exists on the Oscillator module. PLIB_OSC_ExistsPBClockOutputEnable Identifies whether the PBClockOutputEnable feature exists on the Oscillator module. PLIB_OSC_ExistsPBClockReady Identifies whether the PBClockReady feature exists on the Oscillator module. PLIB_OSC_ExistsPLLBypass Identifies whether the SPLLBypass feature exists on the OSC module PLIB_OSC_ExistsPLLClockLock Identifies whether the PLLClockLock feature exists on the Oscillator module. PLIB_OSC_ExistsPLLLockStatus Identifies whether the PLLLockStatus feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscBaseClock Identifies whether the ReferenceOscBaseClock feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscChange Identifies whether the ReferenceOscChange feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscChangeActive Identifies whether the ReferenceOscChangeActive feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscDivisor Identifies whether the ReferenceOscDivisor feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscEnable Identifies whether the ReferenceOscEnable feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscStopInIdleEnable Identifies whether the ReferenceOscStopInIdleEnable feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscStopInSleep Identifies whether the ReferenceOscStopInSleep feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOscTrim Identifies whether the ReferenceOscTrim feature exists on the Oscillator module. PLIB_OSC_ExistsReferenceOutputEnable Identifies whether the ReferenceOutputEnable feature exists on the Oscillator module. PLIB_OSC_ExistsResetPLL Identifies whether the ResetPLL feature exists on the OSC module PLIB_OSC_ExistsSecondaryEnable Identifies whether the SecondaryEnable feature exists on the Oscillator module. PLIB_OSC_ExistsSecondaryReady Identifies whether the SecondaryReady feature exists on the Oscillator module. PLIB_OSC_ExistsSleepToStartupClock Identifies whether the SleepToStartupClock feature exists on the Oscillator module. PLIB_OSC_ExistsSlewDivisorStepControl Identifies whether the SlewDivisorStepControl feature exists on the Oscillator module. PLIB_OSC_ExistsSlewEnableControl Identifies whether the SlewEnableControl feature exists on the Oscillator module. PLIB_OSC_ExistsSysPLLFrequencyRange Identifies whether the PLLFrequencyRange feature exists on the Oscillator module. Peripheral Libraries Help Oscillator Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1403 PLIB_OSC_ExistsSysPLLInputClockSource Identifies whether the PLLInputClockSource feature exists on the Oscillator module. PLIB_OSC_ExistsSysPLLInputDivisor Identifies whether the PLLInputDivisor feature exists on the Oscillator module. PLIB_OSC_ExistsSysPLLMultiplier Identifies whether the PLLMultiplier feature exists on the Oscillator module. PLIB_OSC_ExistsSysPLLOutputDivisor Identifies whether the PLLOutputDivisor feature exists on the Oscillator module. PLIB_OSC_ExistsSystemClockDivisorControl Identifies whether the SystemClockDivisorControl feature exists on the Oscillator module. PLIB_OSC_ExistsUPLLFrequencyRange Identifies whether the UPLLFrequencyRange feature exists on the OSC module PLIB_OSC_ExistsUPLLInputDivisor Identifies whether the UPLLInputDivisor feature exists on the OSC module PLIB_OSC_ExistsUPLLMultiplier Identifies whether the UPLLMultiplier feature exists on the OSC module PLIB_OSC_ExistsUPLLOutputDivisor Identifies whether the UPLLOutputDivisor feature exists on the OSC module PLIB_OSC_ExistsUsbClockSource Identifies whether the UsbClockSource feature exists on the Oscillator module. PLIB_OSC_ForceSPLLLockDisable Disables the Force PLL Lock feature for specified PLL. PLIB_OSC_ForceSPLLLockEnable Enables the Force PLL Lock feature for specified PLL. PLIB_OSC_ForceSPLLLockStatus gets the status of the force PLL Lock bit of the specified PLL. PLIB_OSC_FRCDivisorGet Gets the FRC clock divisor. PLIB_OSC_FRCDivisorSelect Sets the FRC clock divisor to the specified value. PLIB_OSC_FRCTuningSelect Sets the FRC tuning value. PLIB_OSC_OnWaitActionGet Gets the configured operation to be performed when a WAIT instruction is executed. PLIB_OSC_OnWaitActionSet Selects the operation to be performed when a WAIT instruction is executed. PLIB_OSC_PBClockDivisorGet Gets the peripheral bus clock divisor. PLIB_OSC_PBClockDivisorIsReady Checks whether the peripheral bus clock divisor is ready to be written. PLIB_OSC_PBClockDivisorSet Sets the peripheral bus clock divisor to the specified value. PLIB_OSC_PBOutputClockDisable Disables the peripheral bus output clock. PLIB_OSC_PBOutputClockEnable Enables the peripheral bus output clock PLIB_OSC_PBOutputClockIsEnabled Checks whether or not the peripheral bus clock output is enabled. PLIB_OSC_PLLBypassDisable Disables the PLL Bypass. PLIB_OSC_PLLBypassEnable Enables the PLL Bypass. PLIB_OSC_PLLBypassStatus gets the status of the PLL Bypass. PLIB_OSC_PLLClockIsLocked Gets the lock status for the clock and PLL selections. PLIB_OSC_PLLClockLock Locks the clock and PLL selections. PLIB_OSC_PLLClockUnlock Unlocks the clock and PLL selections. PLIB_OSC_PLLIsLocked Returns 'true' if the selected PLL module is locked. PLIB_OSC_ReferenceOscBaseClockSelect Sets the base clock for the reference oscillator. PLIB_OSC_ReferenceOscDisable Disables the reference oscillator output. PLIB_OSC_ReferenceOscDivisorValueSet Selects the reference oscillator divisor value. PLIB_OSC_ReferenceOscEnable Enables the reference oscillator. PLIB_OSC_ReferenceOscIsEnabled Gets the enable status of the reference oscillator output. PLIB_OSC_ReferenceOscSourceChangeIsActive Returns 'true' if a reference oscillator source change request is active. PLIB_OSC_ReferenceOscStopInIdleDisable Enables the reference oscillator in Idle mode. PLIB_OSC_ReferenceOscStopInIdleEnable Configures the reference oscillator to stop operating in Idle mode. PLIB_OSC_ReferenceOscStopInIdleIsEnabled Returns 'true' if the reference oscillator is disabled in Idle mode. PLIB_OSC_ReferenceOscStopInSleepDisable Enables the reference oscillator in Sleep mode. PLIB_OSC_ReferenceOscStopInSleepEnable Configures the reference oscillator to stop operating in Sleep mode. PLIB_OSC_ReferenceOscStopInSleepIsEnabled Returns 'true' if the reference oscillator is disabled in Sleep mode. PLIB_OSC_ReferenceOscSwitchIsComplete Returns 'true' if the reference oscillator base clock switching is complete. PLIB_OSC_ReferenceOscTrimSet Sets the reference oscillator divisor trim value. PLIB_OSC_ReferenceOutputDisable Disables the reference oscillator output. PLIB_OSC_ReferenceOutputEnable Enables the reference oscillator output. PLIB_OSC_ReferenceOutputIsEnabled Returns 'true' if the reference oscillator output is enabled. PLIB_OSC_ResetPLLAssert Asserts the PLL reset for selected PLL. PLIB_OSC_ResetPLLDeassert Deasserts the PLL reset for selected PLL. PLIB_OSC_ResetPLLStatus gets the status of the PLL reset bit for the specified PLL. PLIB_OSC_SecondaryDisable Disables the Secondary Oscillator. PLIB_OSC_SecondaryEnable Enables the Secondary Oscillator. Peripheral Libraries Help Oscillator Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1404 PLIB_OSC_SecondaryIsEnabled Returns 'true' if the Secondary Oscillator is enabled. PLIB_OSC_SecondaryIsReady Returns 'true' if the Secondary Oscillator is ready. PLIB_OSC_SleepToStartupClockGet Returns the clock used for the duration when the device wakes from sleep and the clock ready. PLIB_OSC_SleepToStartupClockSelect Selects the clock duration for when the device wakes from sleep and the clock is ready. PLIB_OSC_SlewDisable Disables the selected type of slewing. PLIB_OSC_SlewDivisorStepGet Get the slew divisor maximum step. PLIB_OSC_SlewDivisorStepSelect Selects division steps used while slewing. PLIB_OSC_SlewEnable Enables the selected type of slewing. PLIB_OSC_SlewIsEnabled Returns 'true' if the reference oscillator is disabled in Idle mode. PLIB_OSC_SysClockSelect Selects the new oscillator. PLIB_OSC_SysPLLFrequencyRangeGet Gets the frequency range for the PLL module. PLIB_OSC_SysPLLFrequencyRangeSet Sets the frequency range for the PLL module. PLIB_OSC_SysPLLInputClockSourceGet Gets the input clock source for the PLL module. PLIB_OSC_SysPLLInputClockSourceSet Sets the input clock source for the PLL module. PLIB_OSC_SysPLLInputDivisorGet Gets the input divisor for the PLL. PLIB_OSC_SysPLLInputDivisorSet Sets the input divider for the PLL to the specified value. PLIB_OSC_SysPLLMultiplierGet Gets the PLL multiplier. PLIB_OSC_SysPLLMultiplierSelect Sets the PLL multiplier to the specified value. PLIB_OSC_SysPLLOutputDivisorGet Gets the output divisor for the PLL. PLIB_OSC_SysPLLOutputDivisorSet Sets the output divider for the PLL to the specified value. PLIB_OSC_SystemClockDivisorGet Get the system clock divisor value. PLIB_OSC_SystemClockDivisorSelect Selects system clock divisor. PLIB_OSC_UPLLFrequencyRangeGet Gets the frequency range for the USB PLL module. PLIB_OSC_UPLLFrequencyRangeSet Sets the frequency range for the USB PLL module. PLIB_OSC_UPLLInputDivisorGet Gets the input divisor for the USB PLL. PLIB_OSC_UPLLInputDivisorSet Sets the input divider for the USB PLL to the specified value. PLIB_OSC_UPLLMultiplierGet Gets the USB PLL multiplier. PLIB_OSC_UPLLMultiplierSelect Sets the USB PLL multiplier to the specified value. PLIB_OSC_UPLLOutputDivisorGet Gets the output divisor for the PLL. PLIB_OSC_UPLLOutputDivisorSet Sets the output divider for the USB PLL to the specified value. PLIB_OSC_UsbClockSourceGet Gets the USB module clock source. PLIB_OSC_UsbClockSourceSelect Sets the USB module clock source. Description Oscillator Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Oscillator (OSC) Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Oscillator module. File Name plib_osc.h Company Microchip Technology Inc. plib_osc_help.h Defines the Oscillator Peripheral Library data types. Enumerations Name Description OSC_CLOCK_ID Lists the clock sources for which ready status can be checked. OSC_CLOCK_SLEW_TYPE Lists the possible type of clock slewing. OSC_FRC_DIV Lists the possible Fast RC (FRC) Oscillator divider values. OSC_MODULE_ID Possible instances of the OSC module. OSC_OPERATION_ON_WAIT Lists the possible base clock values for the reference oscillator. Peripheral Libraries Help Oscillator Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1405 OSC_PERIPHERAL_BUS Lists the possible Peripheral buses. OSC_PLL_SELECT Lists the PLLs in the Oscillator module. OSC_REFERENCE Lists the possible reference oscillator. OSC_SLEEP_TO_STARTUP_CLK_TYPE Lists the possible clock sources for sleep to start-up period. OSC_SYS_TYPE Lists the possible oscillator type values. OSC_SYSPLL_FREQ_RANGE Lists the possible PLL frequency range. OSC_SYSPLL_IN_CLK_SOURCE Lists the possible input clock source for PLL module. OSC_SYSPLL_OUT_DIV Lists the possible PLL output divider values. OSC_USBCLOCK_SOURCE Lists the possible USB clock sources. Macros Name Description OSC_PB_CLOCK_DIV_TYPE Type of the oscillator PB Clock divisor value. OSC_REF_DIVISOR_TYPE Reference oscillator divisor type. OSC_REFERENCE_MAX_DIV Defines the reference clock output divisor maximum value. OSC_SYSPLL_MULTIPLIER_TYPE Type of the oscillator system PLL multiplier value. Description Oscillator Peripheral Library Interface Header This header file contains the definitions of the data types and constants that make up the interface to the Oscillator Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Oscillator module. File Name plib_osc_help.h Company Microchip Technology Inc. Peripheral Libraries Help Oscillator Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1406 PMP Peripheral Library This section describes the Parallel Master Port (PMP) Peripheral Library. Introduction This library provides a low-level abstraction of the Parallel Master Port (PMP) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The following diagram shows a block diagram of the PMP module and how it interacts with other peripherals. Using the Library This topic describes the basic architecture of the PMP Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_pmp.h The interface to the PMP Peripheral library is defined in the plib_pmp.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the PMP Peripheral Library must include peripheral.h. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the Parallel Master Port (PMP) module on Microchip's microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The PMP module provides interface routines to interact with external peripherals such as LCD, EEPROM, Flash memory, etc., as shown in the following diagram. The diagram shows the PMP module acting as a master. The PMP module can be easily configured to act as a slave. The address and data lines can be multiplexed to suit the application. The address and data buffers are up to 2-byte (16-bit) buffers for data transmitted or received by the parallel interface to the PMP bus over the data and address lines synchronized with control logic including the read and write strobe. PMP Hardware Abstraction Model Diagram Peripheral Libraries Help PMP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1407 The desired timing wait states to suit different peripheral timings can also be programmed using the PMP module. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the PMP module Library Interface Section Description General Initialization Functions Provides configuration for: • Interrupt mode • Address Incrementing mode • Stop-in-Idle operation • Operating mode • Multiplexing mode • Chip Select mode Wait States Initialization Functions Provides configuration routines to tune the wait states of the PMP module. Data Read and Write Functions Provides functions for receiving the data from another module when operating in Master or Slave mode. Also provides routines for transmitting data from the module when operating in Master or Slave mode. Address Handling Provides functions to set the PMP module to point to the desired addresses. Port Configuration Provides functions for configuring the PMP pins either for PMP purpose or general purpose. Polarity Configuration Provides routines for configuring the PMP pins polarity either as active-high or active-low. Error Status/Control Functions Provides functions and status for error handling (either as a master or a slave). General Status Functions Provides status of the PMP module. Note: The enhanced feature APIs are not available on all devices. Please refer to the specific device data sheet to determine the availability of these enhanced features. How the Library Works Provides information on how the library works. Description Before enabling the PMP module, the caller must initialize basic parameters such as wait states timings, and interrupt mode features (see the Initialization section). After the module has been enabled, it can begin monitoring the bus as a slave device waiting to be addressed by an external master (see the Operating as a Slave section). A slave device only transfers data on the bus when it has been addressed by a master. If the module is used to start a transfer, it is operating as a master. A master addresses a slave and controls the transfer of data by providing the clock (see the Operating as a Master section). Some operations in the PMP peripheral library initiate actions on the PMP bus that require time to complete. Also, some events occur asynchronously on the bus. In each of these cases, the module causes either a "master", "slave", or "error" interrupt. The State Machine section describes the different states that can cause an interrupt and show what causes the transition from one state to another. The Handling Errors section describes the various errors that can occur and how to deal with them. Usage Model The following diagram shows the high level organization of the PMP Peripheral Library usage model. The items in the diagram correspond to the groupings in the Library Interface section. Peripheral Libraries Help PMP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1408 PMP Library Usage Model Initialization This section describes the general initialization of the PMP module. Description The important configurations to look for are as follows. Operating Mode Depending on the device, the PMP module can function in Master modes 1 or 2, buffered/enhanced slave mode or the legacy slave mode. To set the PMP module in the appropriate mode, use PLIB_PMP_OperationModeSelect. Multiplexing Mode Depending on the application requirement or hardware arrangement, the data lines can be used to multiplex the addressing information. Various multiplexing modes supported are listed by PMP_MUX_MODE. Use PLIB_PMP_MultiplexModeSelect to select the appropriate multiplexing mode. Chip Select Mode As needed, the Chip Select lines can be made to function as Chip Select or as address lines. Use PLIB_PMP_ChipSelectFunctionSelect to select the required functionality of Chip Select lines. Interrupt Mode PMP generates interrupts based on the option selected for the interrupt mode. Interrupts can be enabled, disabled, generated at the end of a read or write cycle, or when other events occur. Use the PLIB_PMP_InterruptModeSelect to select these options. Address Increment Mode After every read/write cycle, the PMP module can be configured to automatically increment or decrement the address it is accessing. Use PLIB_PMP_AddressIncrementModeSelect to select this option. To initialize the PMP module, perform the following sequence: 1. Select the desired initialization options using the General Initialization Functions (see the Library Interface section) to select the desired operation of the following features: • Operating mode • Multiplexing mode • Chip Select mode • Interrupt mode • Address Incrementing mode • Stop-in-Idle operation 2. Program the wait states of the PMP module. Refer to Wait States Initialization Functions in the Library Interface section for an example. 3. If operating in Master mode, set the desired address (8-bit in this case, the size may vary depending on the application) using PLIB_PMP_AddressSet. 4. If running in an interrupt-driven environment, clear any pending interrupts and enable the appropriate (master, slave, and error) PMP interrupts. Peripheral Libraries Help PMP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1409 Note: Refer to the "Interrupt Controller" chapter in the specific device data sheet for details. 5. Enable the module for operation using PLIB_PMP_Enable. Example // Configure General PMP Options // Select the PMP operation mode PLIB_PMP_OperationModeSelect( PMP_ID_0, PMP_MASTER_READ_WRITE_STROBES_INDEPENDENT ); // Set the multiplexing to none. Address and data lines are not multiplexed. PLIB_PMP_MultiplexModeSelect( PMP_ID_0, PMP_MUX_NONE ); // Select the function of chip-select lines PLIB_PMP_ChipSelectFunctionSelect( PMP_ID_0, PMCS1_PMCS2_AS_ADDRESS_LINES ); // Select the interrupt mode PLIB_PMP_InterruptModeSelect( PMP_ID_0, PMP_INTERRUPT_NONE ); // disable the auto increment/decrement of address after each read/write PLIB_PMP_AddressIncrementModeSelect( PMP_ID_0, PMP_ADDRESS_INCREMENT_DECREMENT_DISABLE ); // Enable stop in Idle mode. PLIB_PMP_StopInIdleEnable( PMP_ID_0 ); // Set Desired Wait State Values // Set the data wait states PLIB_PMP_WaitStatesDataSetUpSelect( PMP_ID_0, PMP_DATA_WAIT_FOUR ); // Set the strobe wait states PLIB_PMP_WaitStatesStrobeSelect( PMP_ID_0, PMP_STROBE_WAIT_1 ); // Set the data hold wait states. PLIB_PMP_WaitStatesDataHoldSelect( PMP_ID_0, PMP_DATA_HOLD_1 ); // Set the appropriate address (MASTER only) PLIB_PMP_AddressSet ( PMP_ID_0, 0x12 ); // Optional: Clear and enable interrupts before enabling the PMP module. // Enable the module PLIB_PMP_Enable( PMP_ID_0 ); Note: Refer to the "Interrupt Controller" chapter in the specific device data sheet for details on how to clear and enable the PMP module interrupts. Wait States Initialization This section describes set up and initialization of the wait states for the PMP module. Description In Master mode, the user can control the duration of the read, write and address cycles by configuring the module Wait states. One Wait state period is equivalent to one peripheral bus clock cycles. The following figure shows an example of a Master Read operation using Wait states. Wait States Wait states can be added to the beginning, middle and end of any read or write cycle using the corresponding bits in the PMP Configuration. The wait states differ depending on which PMP mode you are in, but setting the wait states is the same per mode and device, as shown in the following example. Initializing Wait States The following sequence can be used to set up the wait states for the PMP Master mode. Peripheral Libraries Help PMP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1410 Preconditions: None. Process: 1. Set the data hold time using PLIB_PMP_WaitStatesDataHoldSelect. 2. Set the strobe wait time using PLIB_PMP_WaitStatesStrobeSelect. 3. Set the data wait time using PLIB_PMP_WaitStatesDataSetUpSelect. Example // Set the data wait states PLIB_PMP_WaitStatesDataSetUpSelect( PMP_ID_0, PMP_DATA_WAIT_ONE ); // Set the strobe wait states PLIB_PMP_WaitStatesStrobeSelect( PMP_ID_0, PMP_STROBE_WAIT_1 ); // Set the data hold wait states. PLIB_PMP_WaitStatesDataHoldSelect( PMP_ID_0, PMP_DATA_HOLD_1 ); Operating as a Master This section describes how to set up the PMP module to operate as a master. Description The PMP module, while acting as a master, waits for its input or output buffers to be read or written. Once the buffers have been manipulated, the appropriate action takes place. A PMP bus transfer always begins with reading or writing to the appropriate PMP input/output buffers. A read from a PMP input buffer performs a PMP read. A write to a PMP output buffer performs a PMP write. The address pins associated with the transfer will have the value that is inside the address register of the PMP module. These steps are summarized as follows. Summary of Steps • Set up the proper PMP address • Send or read data bytes Each of these steps making up a transfer will take some time to complete. By monitoring the busy bit of the PMP module, the user application can determine whether the transfer is complete. The completion of each step can cause a PMP interrupt. Sending a Data Byte The following sequence can be used to send a data byte and repeated to send an arbitrary number of data bytes. Preconditions: • The address of the destination must be configured in the PMP module • The proper control signals are configured for PMP operation • The PMP module is configured for the desired Master mode • The PMP module is enabled Process: 1. Ensure that the PMP module is not busy by using PLIB_PMP_PortIsBusy. 2. Write the output data buffer using PLIB_PMP_MasterSend. Example: uint8_t data = 'a'; // Set the destination address to be written PLIB_PMP_AddressSet(PMP_ID_0, 0x1234 ); // Check to see if the PMP is busy, and then send the byte if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { // Send the data PLIB_PMP_MasterSend( PMP_ID_0, data ); } Receiving a Data byte The following sequence can be used to send a data byte and repeated to send an arbitrary number of data bytes. Preconditions: • The address of the destination must be configured in the PMP module • The proper control signal are configured for PMP operation Process: 1. Ensure that the PMP module is not busy by using PLIB_PMP_PortIsBusy. 2. Write the output data buffer using PLIB_PMP_MasterReceive. Example: Peripheral Libraries Help PMP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1411 uint8_t data; // Set the source address PLIB_PMP_AddressSet(PMP_ID_0, 0x1234 ); // Check to see the PMP is not busy, and then read the data if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { // receive the data data = PLIB_PMP_MasterReceive( PMP_ID_0 ); } Operating as a Slave This section describes how to set up the PMP module to operate as a slave. Description The PMP module while acting as a slave, waits for read or write strobes to occur. Once the buffers have been manipulated, the appropriate action takes place. Summary of Steps • Check to see if data is available to be read • Prepare output buffer for slave read Each of these steps making up a transfer will take some time to complete. By monitoring the busy bit of the PMP module, the user application can determine whether the transfer is complete. The completion of each step can cause a PMP interrupt. Reading Available Data The following sequence can be used to receive a data byte and repeated to receive an arbitrary number of data bytes. Preconditions: • The address of the destination must be set in the PMP module • The proper control signals are initialized for PMP operation Process: 1. Check to see if data is available using PLIB_PMP_InputBufferXIsFull. 2. Read the available data using PLIB_PMP_InputBufferXByteReceive. Example: uint8_t data; // Check to see if data is available, and then receive the byte if(PLIB_PMP_InputBufferXIsFull( PMP_ID_0, 1)) { // Receive the data from buffer one. data = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 1 ); } Preparing Output Buffer for Slave Write The following sequence can be used to send a data byte and repeated to send an arbitrary number of data bytes. Preconditions: The proper control signals are initialized for PMP operation. Process: 1. Ensure that the output buffer to be written is empty by using PLIB_PMP_OutputBufferXIsEmpty. 2. Write the output data buffer using PLIB_PMP_OutputBufferXByteSend. Example: uint8_t data; // Check to see if output buffer is available, and then send the byte if(PLIB_PMP_OutputBufferXIsEmpty( PMP_ID_0, 1)) { // Fill the output buffer-1 with the data to be sent PLIB_PMP_OutputBufferXByteSend( PMP_ID_0, 1, value); } State Machine The PMP state machine can be used in either a polled or an interrupt-driven manner. However, in both cases, software must check the state of the master, slave, and error interrupt flags to identify when a state transition occurs. Peripheral Libraries Help PMP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1412 Description The PMP module has one basic interrupt that is triggered when data has been written or read. In Buffered Slave mode, this interrupt can be set to wait until an 'X' amount of buffers are written or read. This interrupt must be cleared in software, but can also be used in DMA transactions to trigger the next DMA transfer. The PMP module will not start generating interrupts (setting the PMP interrupt flags, even if interrupts are disabled) until it is properly configured and enabled. After that, interrupts are generated as described in subsequent sections. Software has to respond appropriately once the interrupt has occurred (the flag has been set) to allow the state machine to advance to the next state. These actions are described in the following sections for the state machine diagram to which they refer. Slave Mode State Machine Slave-Mode State Transitions In Slave mode, state transitions occur under hardware control automatically or in response to an interrupt. Software must respond appropriately to ensure that the PMP module continues to operate correctly. Basically, if a read/write strobe occurs, the appropriate read/write occurs, which in turn sets the interrupt. Peripheral Libraries Help PMP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1413 Master Mode State Machine Master-Mode State Transitions In Master mode, state transitions occur under hardware control automatically or in response to an interrupt. Software must respond appropriately to ensure that the PMP module continues to operate correctly. Basically, if an input or output register is manipulated, the appropriate read/write happens, which in turn sets the interrupt. The PMP module can also be configured to have read/write strobes indicating whether a read/write has completed. Handling Errors There are two basic types of errors that can occur during various slave PMP operations: • Input Buffer Overrun • Output Buffer Underflow This section provides information on handling these types of errors. Description Handling Input Buffer Overrun Errors An input buffer overflow error occurs when the software is not reading or clearing the input buffers fast enough for the master PMP device attached to it. When this occurs, the master write is not allowed and the "input buffer overflow" status bit is set. This can be identified by calling PLIB_PMP_InputOverflowHasOccurred. Additional attempts to write to the input buffer will not be allowed until the overflow error is cleared by calling PLIB_PMP_InputOverflowClear. This type of error should be either avoided by having proper communication techniques with the PMP Master device or checked using PLIB_PMP_InputBuffersAreFull, which informs the controller that no buffers have data in them (overflow) . Interrupts: The input buffer overflow error does not trigger an interrupt. Handling Output Buffer Underflow Errors An output buffer underflow error occurs when the software is not writing to the output buffers fast enough for the master PMP device attached to it. When this occurs, the master read is not allowed and the "output buffer underflow" status bit is set. This can be identified by calling PLIB_PMP_OutputUnderflowHasOccurred. Additional attempts to read from the output buffer will not be allowed until the overflow error is cleared by calling PLIB_PMP_OutputUnderflowClear. This sort of error should be either avoided by having proper communication techniques with the PMP Master device, or checked using PLIB_PMP_OutputBuffersAreEmpty, which informs the controller that buffers have data in them (underflow) . Interrupts: The input buffer overflow error does not trigger an interrupt. Peripheral Libraries Help PMP Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1414 Other Features This section provides information on additional features that may be available. These features are not available on all devices. Please refer to the "Parallel Master Port (PMP)" chapter in the specific device data sheet to determine which features are supported by your device. Description Operation During Sleep Mode When the device enters Sleep mode, the system clock is disabled. The consequences of Sleep mode depend on which mode the PMP module is configured in at the time that Sleep mode is invoked. Master If the device enters Sleep mode while the PMP module is operating in Master mode, PMP operation will be suspended in its current state until clock execution resumes. As this may cause unexpected control pin timings, users should avoid invoking Sleep mode when continuous use of the module is needed. Slave While the PMP module is inactive, but enabled for any Slave mode operation, any read or write operations occurring at that time will be able to complete without the use of the microcontroller clock. Once the operation is completed, the module will issue an interrupt. This interrupt may be used to wake the device from Sleep or Idle modes, depending on the configuration and capabilities of the device. Refer to the specific device data sheet or the related peripheral section in the reference manual to determine the capabilities of your device. Operation During Idle Mode When the device enters Idle mode, the system clock sources remain functional and the CPU stops code execution. PMP operation during Idle mode can be controlled using the PLIB_PMP_StopInIdleEnable or the PLIB_PMP_StopInIdleDisable. By default, the PMP module continues to operate in Idle mode and provide full functionality. Configuring the Library The library is configured for the supported PMP module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Initialization Functions Name Description PLIB_PMP_AddressIncrementModeGet Gets the increment mode being used with the address of the PMP module. PLIB_PMP_AddressIncrementModeSelect Configures the increment mode being used with the address of the PMP module. PLIB_PMP_AddressLatchStrobeDisable Disables the specific address latch strobe. PLIB_PMP_AddressLatchStrobeEnable Enables the specific address latch strobe. PLIB_PMP_ChipSelectFunctionSelect Defines the functionality of the pins intended to be used as Chip Select. PLIB_PMP_ChipSelectXDisable Configures the Chip Select. PLIB_PMP_ChipSelectXEnable Configures the Chip Select. PLIB_PMP_ChipSelectXIsActive Gets the current status of the specified Chip Select. PLIB_PMP_DataSizeSelect Enables data transfer size for the PMP module. PLIB_PMP_Disable Disables the specific PMP module. PLIB_PMP_Enable Enables the specific PMP module. PLIB_PMP_InputBufferTypeSelect Selects the input buffer based on the input passed. PLIB_PMP_InterruptModeGet Gets the current configured interrupt mode being used with the PMP module. PLIB_PMP_InterruptModeSelect Configures the interrupt request mode being used with the PMP module. PLIB_PMP_MultiplexModeGet Gets the current multiplexing mode configured between the address and data of the PMP module. PLIB_PMP_MultiplexModeSelect Configures the multiplexing between the address and data of the PMP module. PLIB_PMP_OperationModeGet Gets the current operation mode of the PMP module. PLIB_PMP_OperationModeSelect Configures the operation mode of the PMP module. PLIB_PMP_StopInIdleDisable Enables the PMP module to continue operation in Idle mode. PLIB_PMP_StopInIdleEnable Discontinues PMP module operation when the device enters Idle mode. PLIB_PMP_DualModeReadAddressGet Gets the current read address of the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1415 PLIB_PMP_DualModeReadAddressSet Sets the address to be written in Dual mode. PLIB_PMP_DualModeWriteAddressGet Gets the current write address of the PMP module. PLIB_PMP_DualModeWriteAddressSet Sets the address to be written in Dual mode. PLIB_PMP_DualModeMasterReceive Receives the data in the Master Dual mode. PLIB_PMP_DualBufferEnable Enables PMP dual Read/Write buffer. PLIB_PMP_DualBufferDisable Disables the specific PMP module. PLIB_PMP_DualModeMasterSend Sends the specified data in Dual Master mode. b) Enhanced General Initialization Functions Name Description PLIB_PMP_ReadChipSelectXDisable Configures the Read Chip Select. PLIB_PMP_ReadChipSelectXEnable Configures the Read Chip Select. PLIB_PMP_WriteChipSelectXDisable Configures the Write Chip Select. PLIB_PMP_WriteChipSelectXEnable Configures the Write Chip Select. c) General Status Functions Name Description PLIB_PMP_IsEnabled Checks whether or not the PMP module is enabled. PLIB_PMP_DualBufferIsEnabled Checks whether or not the PMP module is enabled. PLIB_PMP_PortIsBusy Identifies if the (Master mode) PMP port is busy. PLIB_PMP_InputOverflowHasOccurred Identifies if there was a receiver overflow error. PLIB_PMP_OutputUnderflowHasOccurred Identifies if there was an output buffer sent out with no data. d) Error Status/Control Functions Name Description PLIB_PMP_InputOverflowClear Clears a PMP Overflow error. PLIB_PMP_OutputUnderflowClear Clears a PMP output underflow error. e) Data Read and Write Functions Name Description PLIB_PMP_InputBuffersAreFull Gets the state of the input buffers. PLIB_PMP_InputBufferXByteReceive Data to be received in Byte mode. PLIB_PMP_InputBufferXIsFull Gets the state of the identified input buffer. PLIB_PMP_IsDataReceived Checks and returns if the data has been received in the specified buffer in Slave mode. PLIB_PMP_IsDataTransmitted Checks and returns if the data has been transmitted from the specified buffer in Slave mode. PLIB_PMP_MasterReceive Receives the data in Master mode. PLIB_PMP_MasterSend Sends the specified data in Master mode. PLIB_PMP_OutputBuffersAreEmpty Gets the state of the output buffers. PLIB_PMP_OutputBufferXByteSend Data to be transmitted in Byte mode. PLIB_PMP_OutputBufferXIsEmpty Gets the state of the input buffer. PLIB_PMP_SlaveReceive Receives the data in Slave mode. PLIB_PMP_SlaveSend Sends the specified data in Slave mode. PLIB_PMP_ReadCycleIsStarted Checks whether or not the read cycle on PMP bus is enabled. PLIB_PMP_ReadCycleStart Starts a read cycle on the PMP bus. f) Wait States Initialization Functions Name Description PLIB_PMP_WaitStatesDataHoldSelect Configures the data hold states (after data transfer) needed to be used with the PMP module. PLIB_PMP_WaitStatesDataSetUpSelect Configures the data wait states (before the data transfer) needed to be used with the PMP module. PLIB_PMP_WaitStatesStrobeSelect Configures the strobe wait states (during the data transfer) needed to be used with the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1416 g) Address Handling Functions Name Description PLIB_PMP_AddressGet Gets the current address of the PMP module. PLIB_PMP_AddressLinesA0A1Get Gets the value of the address lines PMA0 and PMA1. PLIB_PMP_AddressLinesA0A1Set Sets the address lines PMA0 and PMA1 with the value specified. PLIB_PMP_AddressSet Sets the current address of the PMP module to the specified address. h) Port Configuration Functions Name Description PLIB_PMP_AddressPortDisable Disables the port lines specified as PMP address lines. PLIB_PMP_AddressPortEnable Enables the port lines specified as PMP address lines. PLIB_PMP_ReadWriteStrobePortDisable Disables the PMP module read strobe port. PLIB_PMP_ReadWriteStrobePortEnable Enables the PMP module read strobe port. PLIB_PMP_WriteEnableStrobePortDisable Disables the PMP module write strobe port. PLIB_PMP_WriteEnableStrobePortEnable Enables the PMP module write strobe port. i) Polarity Configuration Functions Name Description PLIB_PMP_AddressLatchPolaritySelect Sets the address latch strobe polarity. PLIB_PMP_ChipSelectXPolaritySelect Sets the specified Chip Select polarity. PLIB_PMP_ReadWriteStrobePolaritySelect Sets the polarity of the read strobe. PLIB_PMP_WriteEnableStrobePolaritySelect Sets the polarity of the write enable strobe. j) Feature Existence Functions Name Description PLIB_PMP_ExistsAddressControl Identifies whether the AddressControl feature exists on the PMP module. PLIB_PMP_ExistsAddressLatchPolarity Identifies whether the AddressLatchPolarity feature exists on the PMP module. PLIB_PMP_ExistsAddressLatchStrobePortControl Identifies whether the AddressLatchStrobePortControl feature exists on the PMP module. PLIB_PMP_ExistsAddressPortPinControl Identifies whether the AddressPortPinControl feature exists on the PMP module. PLIB_PMP_ExistsBufferOverFlow Identifies whether the BufferOverFlow feature exists on the PMP module. PLIB_PMP_ExistsBufferRead Identifies whether the BufferRead feature exists on the PMP module. PLIB_PMP_ExistsBufferType Identifies whether the BufferType feature exists on the PMP module. PLIB_PMP_ExistsBufferUnderFlow Identifies whether the BufferUnderFlow feature exists on the PMP module. PLIB_PMP_ExistsBufferWrite Identifies whether the BufferWrite feature exists on the PMP module. PLIB_PMP_ExistsBusyStatus Identifies whether the BusyStatus feature exists on the PMP module. PLIB_PMP_ExistsChipSelectEnable Identifies whether the ChipSelectEnable feature exists on the PMP module. PLIB_PMP_ExistsChipSelectoperation Identifies whether the ChipSelectoperation feature exists on the PMP module. PLIB_PMP_ExistsChipXPolarity Identifies whether the ChipXPolarity feature exists on the PMP module. PLIB_PMP_ExistsCSXActiveStatus Identifies whether the CSXActiveStatus feature exists on the PMP module. PLIB_PMP_ExistsDataHoldWaitStates Identifies whether the DataHoldWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataSetUpWaitStates Identifies whether the DataSetUpWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataStrobeWaitStates Identifies whether the DataStrobeWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataTransferSize Identifies whether the DataTransferSize feature exists on the PMP module. PLIB_PMP_ExistsEnableControl Identifies whether the EnableControl feature exists on the PMP module. PLIB_PMP_ExistsIncrementMode Identifies whether the IncrementMode feature exists on the PMP module. PLIB_PMP_ExistsInputBufferFull Identifies whether the InputBufferFull feature exists on the PMP module. PLIB_PMP_ExistsInputBufferXStatus Identifies whether the InputBufferXStatus feature exists on the PMP module. PLIB_PMP_ExistsInterruptMode Identifies whether the InterruptMode feature exists on the PMP module. PLIB_PMP_ExistsMasterRXTX Identifies whether the MasterRXTX feature exists on the PMP module. PLIB_PMP_ExistsMUXModeSelect Identifies whether the MUXModeSelect feature exists on the PMP module. PLIB_PMP_ExistsOperationMode Identifies whether the OperationMode feature exists on the PMP module. PLIB_PMP_ExistsOutPutBufferEmpty Identifies whether the OutPutBufferEmpty feature exists on the PMP module. PLIB_PMP_ExistsOutputBufferXStatus Identifies whether the OutputBufferXStatus feature exists on the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1417 PLIB_PMP_ExistsReadWritePolarity Identifies whether the ReadWritePolarity feature exists on the PMP module. PLIB_PMP_ExistsReadWriteStrobePortControl Identifies whether the ReadWriteStrobePortControl feature exists on the PMP module. PLIB_PMP_ExistsSlaveRX Identifies whether the SlaveRX feature exists on the PMP module. PLIB_PMP_ExistsSlaveTX Identifies whether the SlaveTX feature exists on the PMP module. PLIB_PMP_ExistsStopInIdleControl Identifies whether the StopInIdleControl feature exists on the PMP module. PLIB_PMP_ExistsWriteEnablePolarity Identifies whether the WriteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsWriteEnablePortControl Identifies whether the WriteEnablePortControl feature exists on the PMP module. PLIB_PMP_ExistsDualBufferControl Identifies whether the DualBufferControl feature exists on the PMP module. PLIB_PMP_ExistsDualModeMasterRXTX Identifies whether the DualModeMasterRXTX feature exists on the PMP module. PLIB_PMP_ExistsDualModeReadAddressControl Identifies whether the DualModeReadAddressControl feature exists on the PMP module. PLIB_PMP_ExistsDualModeWriteAddressControl Identifies whether the DualModeWriteAddressControl feature exists on the PMP module. PLIB_PMP_ExistsReadChipSelectEnable Identifies whether the ReadChipSelectEnable feature exists on the PMP module. PLIB_PMP_ExistsWriteChipSelectEnable Identifies whether the WriteChipSelectEnable feature exists on the PMP module. PLIB_PMP_ExistsStartReadControl Identifies whether the StartReadControl feature exists on the PMP module. k) Data Types and Constants Name Description PMP_ACK_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_ADDRESS_HOLD_LATCH_WAIT_STATES PMP hold after address latch strobe wait states configuration. PMP_ADDRESS_LATCH Address Latch Strobe configuration. PMP_ADDRESS_LATCH_WAIT_STATES PMP address latch strobe wait states configuration. PMP_ADDRESS_PORT Defines the different address lines that are available for configuration. PMP_ALTERNATE_MASTER_WAIT_STATES PMP alternate master wait states. PMP_CHIP_SELECT PMP Chip Select data type. PMP_CHIPSELECT_FUNCTION Defines different functions available for the Chip Select lines multiplexed with address lines. PMP_DATA_HOLD_STATES PMP Data Hold after strobe wait state. PMP_DATA_LENGTH Possible data lengths handled by the PMP module. PMP_DATA_SIZE PMP data size. PMP_DATA_WAIT_STATES PMP data setup time configuration. PMP_INCREMENT_MODE PMP address incrementing configuration. PMP_INPUT_BUFFER_TYPE PMP Input Buffers type. PMP_INTERRUPT_MODE PMP interrupt request mode data type. PMP_MASTER_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_MODULE_ID Possible instances of the PMP module. PMP_MUX_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_OPERATION_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_PMBE_PORT Defines the available Byte Enable ports. PMP_POLARITY_LEVEL Possible polarity levels for the PMP pins. PMP_STROBE_WAIT_STATES PMP strobe signal wait time configuration. Description This section describes the Application Programming Interface (API) functions of the PMP Peripheral Library. Refer to each section for a detailed description. a) General Initialization Functions PLIB_PMP_AddressIncrementModeGet Function Gets the increment mode being used with the address of the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1418 File plib_pmp.h C PMP_INCREMENT_MODE PLIB_PMP_AddressIncrementModeGet(PMP_MODULE_ID index); Returns PMP_INCREMENT_MODE - One of the possible values from PMP_INCREMENT_MODE Description This function gets the pins used by the PMP module. Refer to the enumeration PMP_INCREMENT_MODE for the possible settings. Remarks This function implements an operation of the IncrementMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsIncrementMode in your application to to automatically determine whether this feature is available. Preconditions None. Example PMP_INCREMENT_MODE curAddressIncMode; curAddressIncMode = PLIB_PMP_AddressIncrementModeGet( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function PMP_INCREMENT_MODE PLIB_PMP_AddressIncrementModeGet ( PMP_MODULE_ID index ) PLIB_PMP_AddressIncrementModeSelect Function Configures the increment mode being used with the address of the PMP module. File plib_pmp.h C void PLIB_PMP_AddressIncrementModeSelect(PMP_MODULE_ID index, PMP_INCREMENT_MODE incrementMode); Returns None. Description This function configures the pins used by the PMP module. Refer to the enumeration PMP_INCREMENT_MODE for the possible settings. Remarks This function implements an operation of the IncrementMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsIncrementMode in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_AddressIncrementModeSelect( PMP_ID_0, PMP_ADDRESS_INCREMENT_DECREMENT_DISABLE ); Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1419 Parameters Parameters Description index Identifier for the device instance to be addressed incrementMode One of the possible values from PMP_INCREMENT_MODE Function void PLIB_PMP_AddressIncrementModeSelect( PMP_MODULE_ID index, PMP_INCREMENT_MODE incrementMode ) PLIB_PMP_AddressLatchStrobeDisable Function Disables the specific address latch strobe. File plib_pmp.h C void PLIB_PMP_AddressLatchStrobeDisable(PMP_MODULE_ID index, PMP_ADDRESS_LATCH latch); Returns None. Description This function disables the PMP module with a specific address latch strobe depending on which strobes are not needed. Remarks This function implements an operation of the AddressLatchStrobePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressLatchStrobePortControl in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_AddressLatchStrobeDisable( PMP_ID_0, PMP_ADDRESS_LATCH_UPPER ); PLIB_PMP_AddressLatchStrobeDisable( PMP_ID_0, PMP_ADDRESS_LATCH_HIGH ); PLIB_PMP_AddressLatchStrobeDisable( PMP_ID_0, PMP_ADDRESS_LATCH_LOW ); Parameters Parameters Description index Identifier for the device instance to be addressed latch Identifier for the latch to be disabled Function void PLIB_PMP_AddressLatchStrobeDisable ( PMP_MODULE_ID index, PMP_ADDRESS_LATCH latch ) PLIB_PMP_AddressLatchStrobeEnable Function Enables the specific address latch strobe. File plib_pmp.h C void PLIB_PMP_AddressLatchStrobeEnable(PMP_MODULE_ID index, PMP_ADDRESS_LATCH latch); Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1420 Returns None. Description This function enables the PMP module with a specific address latch strobe depending on which strobes are needed. Remarks This function implements an operation of the AddressLatchStrobePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressLatchStrobePortControl in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_AddressLatchStrobeEnable( PMP_ID_0, PMP_ADDRESS_LATCH_UPPER ); PLIB_PMP_AddressLatchStrobeEnable( PMP_ID_0, PMP_ADDRESS_LATCH_HIGH ); PLIB_PMP_AddressLatchStrobeEnable( PMP_ID_0, PMP_ADDRESS_LATCH_LOW ); Parameters Parameters Description index Identifier for the device instance to be addressed latch Identifier for the latch to be enabled Function void PLIB_PMP_AddressLatchStrobeEnable ( PMP_MODULE_ID index, PMP_ADDRESS_LATCH latch ) PLIB_PMP_ChipSelectFunctionSelect Function Defines the functionality of the pins intended to be used as Chip Select. File plib_pmp.h C void PLIB_PMP_ChipSelectFunctionSelect(PMP_MODULE_ID index, PMP_CHIPSELECT_FUNCTION chipselfunct); Returns None. Description This function selects the PMCS1/PMCS2 as either Chip Select or as address lines depending on the way these bits are programmed. Remarks This function implements an operation of the ChipSelectoperation feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipSelectoperation in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_ChipSelectFunctionSelect( PMP_ID_0, PMCS1_PMCS2_AS_ADDRESS_LINES ); Parameters Parameters Description index Identifier for the device instance to be addressed chipselfunct One of the possible values from PMP_CHIPSELECT_FUNCTION Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1421 Function void PLIB_PMP_ChipSelectFunctionSelect( PMP_MODULE_ID index, PMP_CHIPSELECT_FUNCTION chipselfunct ) PLIB_PMP_ChipSelectXDisable Function Configures the Chip Select. File plib_pmp.h C void PLIB_PMP_ChipSelectXDisable(PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect); Returns None. Description This function configures the Chip Select(s) being used by the PMP module. The specified Chip Select pin functions as the address pin. Remarks This function implements an operation of the ChipSelectEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipSelectEnable in your application to to automatically determine whether this feature is available. Preconditions None. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_ChipSelectXDisable( PMP_ID_0, chipSelect ); Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for which Chip Select to configure Function void PLIB_PMP_ChipSelectXDisable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ) PLIB_PMP_ChipSelectXEnable Function Configures the Chip Select. File plib_pmp.h C void PLIB_PMP_ChipSelectXEnable(PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect); Returns None. Description This function configures the Chip Select(s) being used by the PMP module. The specified Chip Select pin functions as chipSelect. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1422 Remarks This function implements an operation of the ChipSelectEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipSelectEnable in your application to to automatically determine whether this feature is available. Preconditions None. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_ChipSelectXEnable( PMP_ID_0, chipSelect ); Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for which Chip Select to configure Function void PLIB_PMP_ChipSelectXEnable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ) PLIB_PMP_ChipSelectXIsActive Function Gets the current status of the specified Chip Select. File plib_pmp.h C bool PLIB_PMP_ChipSelectXIsActive(PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect); Returns • true - Chip Select is active • false - Chip Select is not active Description This function returns the current status of the specified Chip Select. Remarks This function implements an operation of the CSXActiveStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsCSXActiveStatus in your application to to automatically determine whether this feature is available. Preconditions None. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; if(PLIB_PMP_ChipSelectXIsActive( PMP_ID_0, chipSelect )) { //Do something useful } Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for the Chip Select to be checked Function bool PLIB_PMP_ChipSelectXIsActive ( PMP_MODULE_ID index, Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1423 PMP_CHIP_SELECT chipSelect ) PLIB_PMP_DataSizeSelect Function Enables data transfer size for the PMP module. File plib_pmp.h C void PLIB_PMP_DataSizeSelect(PMP_MODULE_ID index, PMP_DATA_SIZE size); Returns None. Description This function enables 4-bit, 8-bit, or 16-bit data transfer for the PMP module. Remarks This function implements an operation of the DataTransferSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDataTransferSize in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_DataSizeSelect( PMP_ID_0, PMP_DATA_SIZE_8_BITS ); Parameters Parameters Description index Identifier for the device instance to be addressed size Identifier for the data size to be used Function void PLIB_PMP_DataSizeSelect ( PMP_MODULE_ID index, PMP_DATA_SIZE size ) PLIB_PMP_Disable Function Disables the specific PMP module. File plib_pmp.h C void PLIB_PMP_Disable(PMP_MODULE_ID index); Returns None. Description This function disables the specific PMP module. Remarks The default state after any reset for a PMP module is the disable state. If the PMP is disabled, all the related pins are in control of the general purpose I/O logic. Disabling the PMP module resets the buffers to empty states. Any data characters in the buffers are lost. All error and status bits are also reset. Disabling the PMP while the PMP is active, will abort all pending transmissions and receptions. Re-enabling the PMP will restart the module in the same configuration. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1424 When disabled, the PMP power consumption is minimal. This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsEnableControl in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_Disable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_Disable ( PMP_MODULE_ID index ) PLIB_PMP_Enable Function Enables the specific PMP module. File plib_pmp.h C void PLIB_PMP_Enable(PMP_MODULE_ID index); Returns None. Description This function enables the specific PMP module. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsEnableControl in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_Enable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_Enable ( PMP_MODULE_ID index ) PLIB_PMP_InputBufferTypeSelect Function Selects the input buffer based on the input passed. File plib_pmp.h Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1425 C void PLIB_PMP_InputBufferTypeSelect(PMP_MODULE_ID index, PMP_INPUT_BUFFER_TYPE inputBuffer); Returns None. Description This function selects the input buffer based on the input passed. Either TTL or Schmitt Trigger input buffers are selected. Remarks This function implements an operation of the BufferType feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferType in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_InputBufferTypeSelect( PMP_ID_0, PMP_INPUT_BUFFER_TTL ); Parameters Parameters Description index Identifier for the device instance to be addressed inputBuffer One of the possible input buffer types Function void PLIB_PMP_InputBufferTypeSelect ( PMP_MODULE_ID index, PMP_INPUT_BUFFER_TYPE inputBuffer ) PLIB_PMP_InterruptModeGet Function Gets the current configured interrupt mode being used with the PMP module. File plib_pmp.h C PMP_INTERRUPT_MODE PLIB_PMP_InterruptModeGet(PMP_MODULE_ID index); Returns One of the possible values from PMP_INTERRUPT_MODE. Description This function gets the current configured interrupt mode being used with the PMP module. Remarks This function implements an operation of the InterruptMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInterruptMode in your application to to automatically determine whether this feature is available. Preconditions None. Example PMP_INTERRUPT_MODE currentIntMode; currentIntMode = PLIB_PMP_InterruptModeGet ( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1426 Function PMP_INTERRUPT_MODE PLIB_PMP_InterruptModeGet ( PMP_MODULE_ID index ) PLIB_PMP_InterruptModeSelect Function Configures the interrupt request mode being used with the PMP module. File plib_pmp.h C void PLIB_PMP_InterruptModeSelect(PMP_MODULE_ID index, PMP_INTERRUPT_MODE interruptMode); Returns None. Description This function configures the pins used by the PMP module. Refer to the enumeration PMP_INTERRUPT_MODE for the possible settings. Remarks This function implements an operation of the InterruptMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInterruptMode in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_InterruptModeSelect( PMP_ID_0, PMP_INTERRUPT_NONE ); Parameters Parameters Description index Identifier for the device instance to be addressed interruptMode One of the possible values from PMP_INTERRUPT_MODE Function void PLIB_PMP_InterruptModeSelect( PMP_MODULE_ID index, PMP_INTERRUPT_MODE interruptMode ) PLIB_PMP_MultiplexModeGet Function Gets the current multiplexing mode configured between the address and data of the PMP module. File plib_pmp.h C PMP_MUX_MODE PLIB_PMP_MultiplexModeGet(PMP_MODULE_ID index); Returns index - Identifier for the device instance to be addressed PMP_MUX_MODE - One of the possible values from PMP_MUX_MODE Description This function gets the current multiplexing mode configured between the address and data of the PMP module. Remarks This function implements an operation of the MUXModeSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsMUXModeSelect in your application to to automatically determine whether this feature is available. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1427 Preconditions None. Example PMP_MUX_MODE currentMuxMode; currentMuxMode = PLIB_PMP_MultiplexModeGet( PMP_ID_0 ); Function PMP_MUX_MODE PLIB_PMP_MultiplexModeGet( PMP_MODULE_ID index ) PLIB_PMP_MultiplexModeSelect Function Configures the multiplexing between the address and data of the PMP module. File plib_pmp.h C void PLIB_PMP_MultiplexModeSelect(PMP_MODULE_ID index, PMP_MUX_MODE multiplexMode); Returns None. Description This function configures the pins used by the PMP module. Refer to the enumeration PMP_MUX_MODE for the possible settings. Remarks This function implements an operation of the MUXModeSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsMUXModeSelect in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_MultiplexModeSelect( PMP_ID_0, PMP_MUX_NONE ); Parameters Parameters Description index Identifier for the device instance to be addressed multiplexMode One of the possible values from the PMP_MUX_MODE Function void PLIB_PMP_MultiplexModeSelect( PMP_MODULE_ID index, PMP_MUX_MODE multiplexMode ) PLIB_PMP_OperationModeGet Function Gets the current operation mode of the PMP module. File plib_pmp.h C PMP_OPERATION_MODE PLIB_PMP_OperationModeGet(PMP_MODULE_ID index); Returns PMP_OPERATION_MODE - One of the possible values from PMP_OPERATION_MODE Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1428 Description This function gets the current operation mode of the PMP module. Remarks This function implements an operation of the OperationMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOperationMode in your application to to automatically determine whether this feature is available. Preconditions None. Example PMP_OPERATION_MODE curOpMode; curOpMode = PLIB_PMP_OperationModeGet( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function PMP_OPERATION_MODE PLIB_PMP_OperationModeGet ( PMP_MODULE_ID index ) PLIB_PMP_OperationModeSelect Function Configures the operation mode of the PMP module. File plib_pmp.h C void PLIB_PMP_OperationModeSelect(PMP_MODULE_ID index, PMP_OPERATION_MODE operationMode); Returns None. Description This function configures operation mode of the PMP module. Refer to the enumeration PMP_OPERATION_MODE for the possible settings. Remarks This function implements an operation of the OperationMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOperationMode in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_OperationModeSelect( PMP_ID_0, PMP_MASTER_READ_WRITE_STROBES_MULTIPLEXED ); Parameters Parameters Description index Identifier for the device instance to be addressed operationMode One of the possible values from PMP_OPERATION_MODE Function void PLIB_PMP_OperationModeSelect( PMP_MODULE_ID index, PMP_OPERATION_MODE operationMode ) Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1429 PLIB_PMP_StopInIdleDisable Function Enables the PMP module to continue operation in Idle mode. File plib_pmp.h C void PLIB_PMP_StopInIdleDisable(PMP_MODULE_ID index); Returns None. Description This function disables the stop in idle flag. The PMP module continues operation in Idle mode. Remarks By default, the PMP module will continue operation in Idle mode. This function implements an operation of the StopInIdleControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsStopInIdleControl in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_StopInIdleDisable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_StopInIdleDisable ( PMP_MODULE_ID index ) PLIB_PMP_StopInIdleEnable Function Discontinues PMP module operation when the device enters Idle mode. File plib_pmp.h C void PLIB_PMP_StopInIdleEnable(PMP_MODULE_ID index); Returns None. Description This function enables the PMP module to discontinue operation when the device enters Idle mode. Remarks This function implements an operation of the StopInIdleControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsStopInIdleControl in your application to to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1430 Example PLIB_PMP_StopInIdleEnable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_StopInIdleEnable ( PMP_MODULE_ID index ) PLIB_PMP_DualModeReadAddressGet Function Gets the current read address of the PMP module. File plib_pmp.h C uint32_t PLIB_PMP_DualModeReadAddressGet(PMP_MODULE_ID index); Returns • readAddress - Device address from where PMP read will occur Description This function gets the current read address of the PMP module. Remarks This function implements an operation of the DualModeReadAddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDualModeReadAddressControl in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as a master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example uint32_t readAddress; readAddress = PLIB_PMP_DualModeReadAddressGet( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function uint32_t PLIB_PMP_DualModeReadAddressGet ( PMP_MODULE_ID index ) PLIB_PMP_DualModeReadAddressSet Function Sets the address to be written in Dual mode. File plib_pmp.h C void PLIB_PMP_DualModeReadAddressSet(PMP_MODULE_ID index, uint32_t readAddress); Returns None. Description This function sets the address to be written to the specified value in Dual mode. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1431 Remarks This function implements an operation of the DualModeReadAddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDualModeReadAddressControl in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as a master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example uint8_t no_of_addressLines = 8; PLIB_PMP_DualModeReadAddressSet( PMP_ID_0, 0xff ); Parameters Parameters Description index Identifier for the device instance to be addressed readAddress Device address from where PMP read will happen Function void PLIB_PMP_DualModeReadAddressSet ( PMP_MODULE_ID index, uint32_t readAddress ) PLIB_PMP_DualModeWriteAddressGet Function Gets the current write address of the PMP module. File plib_pmp.h C uint32_t PLIB_PMP_DualModeWriteAddressGet(PMP_MODULE_ID index); Returns • writeAddress - Device Write address to be set Description This function gets the current write address of the PMP module. Remarks This function implements an operation of the DualModeWriteAddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDualModeWriteAddressControl in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as a master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example uint32_t address; address = PLIB_PMP_DualModeWriteAddressGet( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function uint32_t PLIB_PMP_DualModeWriteAddressGet ( PMP_MODULE_ID index ) PLIB_PMP_DualModeWriteAddressSet Function Sets the address to be written in Dual mode. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1432 File plib_pmp.h C void PLIB_PMP_DualModeWriteAddressSet(PMP_MODULE_ID index, uint32_t writeAddress); Returns None. Description This function sets the address to be written to the specified value in Dual mode. Remarks This function implements an operation of the DualModeWriteAddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDualModeWriteAddressControl in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example uint8_t no_of_addressLines = 8; PLIB_PMP_DualModeWriteAddressSet( PMP_ID_0, 0xff ); Parameters Parameters Description index Identifier for the device instance to be addressed writeAddress Device write address to be set Function void PLIB_PMP_DualModeWriteAddressSet ( PMP_MODULE_ID index, uint32_t writeAddress ) PLIB_PMP_DualModeMasterReceive Function Receives the data in the Master Dual mode. File plib_pmp.h C uint16_t PLIB_PMP_DualModeMasterReceive(PMP_MODULE_ID index); Returns • uint16_t - Data received Description This function receives the data in Dual mode. The flow of data is from the slave to the master. Remarks This function to be used only when the PMP is acting as master. This function implements an operation of the DualModeMasterRXTX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDualModeMasterRXTX in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as a master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example uint16_t data; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { data = PLIB_PMP_DualModeMasterReceive( PMP_ID_0 ); Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1433 } Parameters Parameters Description index Identifier for the device instance to be addressed. Function uint16_t PLIB_PMP_DualModeMasterReceive ( PMP_MODULE_ID index ) PLIB_PMP_DualBufferEnable Function Enables PMP dual Read/Write buffer. File plib_pmp.h C void PLIB_PMP_DualBufferEnable(PMP_MODULE_ID index); Returns None. Description This function enables dual Read/Write buffers for PMP module. Once enabled, PMP uses separate registers for read and write. • Registers used for Reads: PMRADDR and PMRDIN • Registers used for Writes: PMRWADDR and PMDOUT Remarks This feature is only valid in Master mode. This function implements an operation of the DualBufferControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDualBufferControl in your application to automatically determine whether this feature is available. Preconditions The PMP module is configured as a master. Example PLIB_PMP_DualBufferEnable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_DualBufferEnable ( PMP_MODULE_ID index ) PLIB_PMP_DualBufferDisable Function Disables the specific PMP module. File plib_pmp.h C void PLIB_PMP_DualBufferDisable(PMP_MODULE_ID index); Returns None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1434 Description This function disables the specific PMP module. Remarks This feature is only valid in Master mode. This function implements an operation of the DualBufferControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDualBufferControl in your application to automatically determine whether this feature is available. Preconditions The PMP module is configured as a master. Example PLIB_PMP_DualBufferDisable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_DualBufferDisable ( PMP_MODULE_ID index ) PLIB_PMP_DualModeMasterSend Function Sends the specified data in Dual Master mode. File plib_pmp.h C void PLIB_PMP_DualModeMasterSend(PMP_MODULE_ID index, uint16_t data); Returns None. Description This function sends the specified data in dual mode. The data flow is from master to slave. Remarks This function to be used only when the PMP is acting as master. This function implements an operation of the DualModeMasterRXTX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDualModeMasterRXTX in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as a master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example uint16_t data = 'a'; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { PLIB_PMP_DualModeMasterSend( PMP_ID_0, data ); } Parameters Parameters Description index Identifier for the device instance to be addressed data Data to be transmitted Function void PLIB_PMP_DualModeMasterSend ( PMP_MODULE_ID index, Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1435 uint16_t data ) b) Enhanced General Initialization Functions PLIB_PMP_ReadChipSelectXDisable Function Configures the Read Chip Select. File plib_pmp.h C void PLIB_PMP_ReadChipSelectXDisable(PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect); Returns None. Description This function configures the Read Chip Select(s) being used by the PMP module. The specified Chip Select pin functions as the address pin. Remarks This function implements an operation of the ReadChipSelectEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsReadChipSelectEnable in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_ReadChipSelectXDisable( PMP_ID_0, chipSelect ); Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for which Chip Select to configure Function void PLIB_PMP_ReadChipSelectXDisable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ) PLIB_PMP_ReadChipSelectXEnable Function Configures the Read Chip Select. File plib_pmp.h C void PLIB_PMP_ReadChipSelectXEnable(PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect); Returns None. Description This function configures the Read Chip Select(s) being used by the PMP module. The specified Chip Select pin functions as chipSelect. Remarks This function implements an operation of the ReadChipSelectEnable feature. This feature may not be available on all devices. Please refer to the Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1436 specific device data sheet to determine availability or use PLIB_PMP_ExistsReadChipSelectEnable in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_ReadChipSelectXEnable( PMP_ID_0, chipSelect ); Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for which Chip Select to configure Function void PLIB_PMP_ReadChipSelectXEnable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ) PLIB_PMP_WriteChipSelectXDisable Function Configures the Write Chip Select. File plib_pmp.h C void PLIB_PMP_WriteChipSelectXDisable(PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect); Returns None. Description This function configures the Write Chip Select(s) being used by the PMP module. The specified Chip Select pin functions as the address pin. Remarks This function implements an operation of the WriteChipSelectEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWriteChipSelectEnable in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_WriteChipSelectXDisable( PMP_ID_0, chipSelect ); Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for which Chip Select to configure Function void PLIB_PMP_WriteChipSelectXDisable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ) PLIB_PMP_WriteChipSelectXEnable Function Configures the Write Chip Select. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1437 File plib_pmp.h C void PLIB_PMP_WriteChipSelectXEnable(PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect); Returns None. Description This function configures the Write Chip Select(s) being used by the PMP module. The specified Chip Select pin functions as chipSelect. Remarks This function implements an operation of the WriteChipSelectEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWriteChipSelectEnable in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as master. PMP Dual mode should be enabled using the API PLIB_PMP_DualBufferEnable. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_WriteChipSelectXEnable( PMP_ID_0, chipSelect ); Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for which Chip Select to configure Function void PLIB_PMP_WriteChipSelectXEnable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ) c) General Status Functions PLIB_PMP_IsEnabled Function Checks whether or not the PMP module is enabled. File plib_pmp.h C bool PLIB_PMP_IsEnabled(PMP_MODULE_ID index); Returns • true - If the PMP module is enabled • false - if the PMP module is disabled Description This function checks whether or not the PMP module is enabled. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsEnableControl in your application to to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1438 Example bool pmpStatus; pmpStatus = PLIB_PMP_IsEnabled( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function bool PLIB_PMP_IsEnabled ( PMP_MODULE_ID index ) PLIB_PMP_DualBufferIsEnabled Function Checks whether or not the PMP module is enabled. File plib_pmp.h C bool PLIB_PMP_DualBufferIsEnabled(PMP_MODULE_ID index); Returns • true - If the PMP module is enabled • false - if the PMP module is disabled Description This function checks whether or not the PMP module is enabled. Remarks This feature is only valid in Master mode. This function implements an operation of the DualBufferControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDualBufferControl in your application to automatically determine whether this feature is available. Preconditions None. Example bool pmpStatus; pmpStatus = PLIB_PMP_DualBufferIsEnabled( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function bool PLIB_PMP_DualBufferIsEnabled ( PMP_MODULE_ID index ) PLIB_PMP_PortIsBusy Function Identifies if the (Master mode) PMP port is busy. File plib_pmp.h C bool PLIB_PMP_PortIsBusy(PMP_MODULE_ID index); Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1439 Returns • true - If the port is busy • false - If the port is not busy Description This function identifies if the PMP port is busy (in Master mode). Remarks Works only in Master mode. This function implements an operation of the BusyStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBusyStatus in your application to to automatically determine whether this feature is available. Preconditions None. Example bool status; status = PLIB_PMP_PortIsBusy( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function bool PLIB_PMP_PortIsBusy ( PMP_MODULE_ID index ) PLIB_PMP_InputOverflowHasOccurred Function Identifies if there was a receiver overflow error. File plib_pmp.h C bool PLIB_PMP_InputOverflowHasOccurred(PMP_MODULE_ID index); Returns • true - If the input buffer has overflowed • false - If the input buffer has not overflowed Description This function identifies if there was a receiver overflow error. Remarks This function implements an operation of the BufferOverFlow feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferOverFlow in your application to to automatically determine whether this feature is available. Preconditions None. Example if(PLIB_PMP_InputOverflowHasOccurred( PMP_ID_0 )) { PLIB_PMP_InputOverflowClear( PMP_ID_0 ); } Parameters Parameters Description index Identifier for the device instance to be addressed Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1440 Function bool PLIB_PMP_InputOverflowHasOccurred ( PMP_MODULE_ID index ) PLIB_PMP_OutputUnderflowHasOccurred Function Identifies if there was an output buffer sent out with no data. File plib_pmp.h C bool PLIB_PMP_OutputUnderflowHasOccurred(PMP_MODULE_ID index); Returns • true - If the input buffer was empty when data was sent • false - If the output buffer was not empty when data was sent Description This function identifies if there was a output buffer was sent out with no data. Remarks This function implements an operation of the BufferUnderFlow feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferUnderFlow in your application to to automatically determine whether this feature is available. Preconditions None. Example if(PLIB_PMP_OutputUnderflowHasOccurred( PMP_ID_0 )) { PLIB_PMP_OutputUnderflowClear( PMP_ID_0 ); } Parameters Parameters Description index Identifier for the device instance to be addressed Function bool PLIB_PMP_OutputUnderflowHasOccurred ( PMP_MODULE_ID index ) d) Error Status/Control Functions PLIB_PMP_InputOverflowClear Function Clears a PMP Overflow error. File plib_pmp.h C void PLIB_PMP_InputOverflowClear(PMP_MODULE_ID index); Returns None. Description This function clears an overflow error. Clearing the error resets the receive buffer. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1441 Remarks This function implements an operation of the BufferOverFlow feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferOverFlow in your application to to automatically determine whether this feature is available. Preconditions None. Example if(PLIB_PMP_InputOverflowHasOccurred( PMP_ID_0 )) { PLIB_PMP_InputOverflowClear( PMP_ID_0 ); } Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_InputOverflowClear ( PMP_MODULE_ID index ) PLIB_PMP_OutputUnderflowClear Function Clears a PMP output underflow error. File plib_pmp.h C void PLIB_PMP_OutputUnderflowClear(PMP_MODULE_ID index); Returns None. Description This function clears a PMP output underflow error. Remarks This function implements an operation of the BufferUnderFlow feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferUnderFlow in your application to to automatically determine whether this feature is available. Preconditions None. Example if(PLIB_PMP_OutputUnderflowHasOccurred( PMP_ID_0 )) { PLIB_PMP_OutputUnderflowClear( PMP_ID_0 ); } Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_OutputUnderflowClear ( PMP_MODULE_ID index ) e) Data Read and Write Functions Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1442 PLIB_PMP_InputBuffersAreFull Function Gets the state of the input buffers. File plib_pmp.h C bool PLIB_PMP_InputBuffersAreFull(PMP_MODULE_ID index); Returns • true - If all input buffers are full • false - If all input buffers are not full Description This function gets the state of the input buffers. Remarks This function implements an operation of the InputBufferFull feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInputBufferFull in your application to to automatically determine whether this feature is available. Preconditions None. Example uint8_t value; if(PLIB_PMP_InputBuffersAreFull( PMP_ID_0 )) { value = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 1 ); } Parameters Parameters Description index Identifier for the device instance to be addressed Function bool PLIB_PMP_InputBuffersAreFull ( PMP_MODULE_ID index ) PLIB_PMP_InputBufferXByteReceive Function Data to be received in Byte mode. File plib_pmp.h C uint8_t PLIB_PMP_InputBufferXByteReceive(PMP_MODULE_ID index, uint8_t buffer); Returns • data - Data to be received Description This function specifies the data to be received in Byte mode from the desired PMP module. Remarks This function implements an operation of the BufferRead feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferRead in your application to to automatically determine whether this feature is available. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1443 Preconditions None. Example uint8_t mydata; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { // get data from buffer-1 mydata = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 1 ); } Parameters Parameters Description index Identifier for the device instance to be addressed buffer One of the possible buffers (valid values are 0 to 3) Function uint8_t PLIB_PMP_InputBufferXByteReceive ( PMP_MODULE_ID index, uint8_t buffer ) PLIB_PMP_InputBufferXIsFull Function Gets the state of the identified input buffer. File plib_pmp.h C bool PLIB_PMP_InputBufferXIsFull(PMP_MODULE_ID index, uint8_t buffer); Returns • true - If all input buffers are full • false - If all input buffers are not full Description This function gets the state of the identified input buffer. Remarks This function implements an operation of the InputBufferXStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInputBufferXStatus in your application to to automatically determine whether this feature is available. Preconditions None. Example uint8_t value; // Check the status of buffer-2 if(PLIB_PMP_InputBufferXIsFull( PMP_ID_0, 2 )) { // get data from buffer 2 value = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 2 ); } Parameters Parameters Description index Identifier for the device instance to be addressed buffer The input buffer number (valid values are 0 to 3) Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1444 Function bool PLIB_PMP_InputBufferXIsFull ( PMP_MODULE_ID index, uint8_t buffer ) PLIB_PMP_IsDataReceived Function Checks and returns if the data has been received in the specified buffer in Slave mode. File plib_pmp.h C bool PLIB_PMP_IsDataReceived(PMP_MODULE_ID index, uint8_t buffer); Returns • true - Data has been received in the specified buffer • false - Data has not been received in the specified buffer Description This function checks and returns if the data has been received in the specified buffer in Slave mode. Remarks This function implements an operation of the InputBufferXStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInputBufferXStatus in your application to to automatically determine whether this feature is available. Preconditions The PMP module should be configured for Slave mode operation. Example int8_t data; // Check if data is received on buffer-2 if(PLIB_PMP_IsDataReceived( PMP_ID_0, 2 )) { // get data from buffer-2 data = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 2 ); } Parameters Parameters Description index Identifier for the device instance to be addressed buffer One of the possible input buffers (valid values are 0 to 3) Function bool PLIB_PMP_IsDataReceived ( PMP_MODULE_ID index, uint8_t buffer ) PLIB_PMP_IsDataTransmitted Function Checks and returns if the data has been transmitted from the specified buffer in Slave mode. File plib_pmp.h C bool PLIB_PMP_IsDataTransmitted(PMP_MODULE_ID index, uint8_t buffer); Returns • true - If data has been transmitted from the specified buffer Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1445 • false - If data has not been transmitted from the specified buffer Description This function checks and returns if data has been transmitted from the specified buffer. Remarks This function implements an operation of the OutputBufferXStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOutputBufferXStatus in your application to to automatically determine whether this feature is available. Preconditions The PMP module should be configured for Slave mode operation. Example uint8_t data; if(PLIB_PMP_IsDataTransmitted( PMP_ID_0, 2 )) { PLIB_PMP_OutputBufferXByteSend( PMP_ID_0, 2, data ); } Parameters Parameters Description index Identifier for the device instance to be addressed buffer One of the possible output buffers (valid range is 0 to 3) Function bool PLIB_PMP_IsDataTransmitted ( PMP_MODULE_ID index, uint8_t buffer ) PLIB_PMP_MasterReceive Function Receives the data in Master mode. File plib_pmp.h C uint16_t PLIB_PMP_MasterReceive(PMP_MODULE_ID index); Returns uint16_t - Data received Description This function receives the data. The flow of data is from the slave to the master. Remarks This function to be used only when the PMP is acting as master. This function implements an operation of the MasterRXTX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsMasterRXTX in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as a master. Example uint16_t data; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { data = PLIB_PMP_MasterReceive( PMP_ID_0 ); } Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1446 Parameters Parameters Description index Identifier for the device instance to be addressed. Function uint16_t PLIB_PMP_MasterReceive ( PMP_MODULE_ID index ) PLIB_PMP_MasterSend Function Sends the specified data in Master mode. File plib_pmp.h C void PLIB_PMP_MasterSend(PMP_MODULE_ID index, uint16_t data); Returns None. Description This function sends the specified data. The data flow is from master to slave. Remarks This function to be used only when the PMP is acting as master. This function implements an operation of the MasterRXTX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsMasterRXTX in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured for Master mode. Example uint16_t data = 'a'; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { PLIB_PMP_MasterSend( PMP_ID_0, data ); } Parameters Parameters Description index Identifier for the device instance to be addressed data Data to be transmitted Function void PLIB_PMP_MasterSend ( PMP_MODULE_ID index, uint16_t data ) PLIB_PMP_OutputBuffersAreEmpty Function Gets the state of the output buffers. File plib_pmp.h C bool PLIB_PMP_OutputBuffersAreEmpty(PMP_MODULE_ID index); Returns • true - If all output buffers are empty • false - If all output buffers are not empty Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1447 Description This function returns the state of the output buffers. Remarks This function implements an operation of the OutPutBufferEmpty feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOutPutBufferEmpty in your application to to automatically determine whether this feature is available. Preconditions None. Example uint8_t value=0xEF; if(PLIB_PMP_OutputBuffersAreEmpty( PMP_ID_0 )) { PLIB_PMP_OutputBufferXByteSend( PMP_ID_0, 1, value); } Parameters Parameters Description index Identifier for the device instance to be addressed Function bool PLIB_PMP_OutputBuffersAreEmpty ( PMP_MODULE_ID index ) PLIB_PMP_OutputBufferXByteSend Function Data to be transmitted in Byte mode. File plib_pmp.h C void PLIB_PMP_OutputBufferXByteSend(PMP_MODULE_ID index, uint8_t buffer, uint8_t data); Returns None. Description This function specifies the data to be transmitted in Byte mode for the desired PMP module. Remarks This function implements an operation of the BufferWrite feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferWrite in your application to to automatically determine whether this feature is available. Preconditions None. Example uint8_t data = 'a'; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { PLIB_PMP_OutputBufferXByteSend( PMP_ID_0, 1, data ); } Parameters Parameters Description index Identifier for the device instance to be addressed Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1448 buffer One of the possible output buffers (valid range is 0 to 3) data Data to be transmitted Function void PLIB_PMP_OutputBufferXByteSend ( PMP_MODULE_ID index, uint8_t buffer, uint8_t data ) PLIB_PMP_OutputBufferXIsEmpty Function Gets the state of the input buffer. File plib_pmp.h C bool PLIB_PMP_OutputBufferXIsEmpty(PMP_MODULE_ID index, uint8_t buffer); Returns • true - If the identified output buffer is empty • false - If the identified output buffer is not empty Description This function returns the state of the input buffer. Remarks This function implements an operation of the OutputBufferXStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOutputBufferXStatus in your application to to automatically determine whether this feature is available. Preconditions None. Example uint8_t value = 0xEF; if(PLIB_PMP_OutputBufferXIsEmpty( PMP_ID_0, 1 ) ) { PLIB_PMP_OutputBufferXByteSend( PMP_ID_0,1, value); } Parameters Parameters Description index Identifier for the device instance to be addressed buffer Output buffer number (valid range is 0 to 3) Function bool PLIB_PMP_OutputBufferXIsEmpty ( PMP_MODULE_ID index, uint8_t buffer ) PLIB_PMP_SlaveReceive Function Receives the data in Slave mode. File plib_pmp.h C uint16_t PLIB_PMP_SlaveReceive(PMP_MODULE_ID index); Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1449 Returns • uint16_t - Data received Description This function receives the data. The flow of data is from the master to the slave. Remarks This function to be used only when the PMP is acting as slave. This function implements an operation of the SlaveRX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsSlaveRX in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured as a slave. Example uint16_t data; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { data = PLIB_PMP_SlaveReceive( PMP_ID_0 ); } Parameters Parameters Description index Identifier for the device instance to be addressed. Function uint16_t PLIB_PMP_SlaveReceive ( PMP_MODULE_ID index ) PLIB_PMP_SlaveSend Function Sends the specified data in Slave mode. File plib_pmp.h C void PLIB_PMP_SlaveSend(PMP_MODULE_ID index, uint16_t data); Returns None. Description This function sends the specified data. The flow of data is from the slave to the master. Remarks This function to be used only when the PMP is acting as slave. This function implements an operation of the SlaveTX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsSlaveTX in your application to to automatically determine whether this feature is available. Preconditions The PMP module is configured for Slave mode. Example uint16_t data = 'a'; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { PLIB_PMP_SlaveSend( PMP_ID_0, data ); } Parameters Parameters Description index Identifier for the device instance to be addressed Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1450 data Data to be transmitted Function void PLIB_PMP_SlaveSend ( PMP_MODULE_ID index, uint16_t data ) PLIB_PMP_ReadCycleIsStarted Function Checks whether or not the read cycle on PMP bus is enabled. File plib_pmp.h C bool PLIB_PMP_ReadCycleIsStarted(PMP_MODULE_ID index); Returns • true - If the PMP Read cycle is enabled • false - if the PMP Read cycle is not enabled Description This function checks whether or not the read cycle on PMP bus is enabled. Remarks This function implements an operation of the StartReadControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsStartReadControl in your application to automatically determine whether this feature is available. Preconditions None. Example bool pmpReadStartStatus; pmpReadStartStatus = PLIB_PMP_ReadCycleIsStarted( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function bool PLIB_PMP_ReadCycleIsStarted ( PMP_MODULE_ID index ) PLIB_PMP_ReadCycleStart Function Starts a read cycle on the PMP bus. File plib_pmp.h C void PLIB_PMP_ReadCycleStart(PMP_MODULE_ID index); Returns None. Description This function stars a read cycle on the bus for the selected PMP module. This bit is cleared by hardware at the end of the read cycle Remarks This function implements an operation of the StartReadControl feature. This feature may not be available on all devices. Please refer to the Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1451 specific device data sheet to determine availability or use PLIB_PMP_ExistsStartReadControl in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_ReadCycleStart( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_ReadCycleStart( PMP_MODULE_ID index ) f) Wait States Initialization Functions PLIB_PMP_WaitStatesDataHoldSelect Function Configures the data hold states (after data transfer) needed to be used with the PMP module. File plib_pmp.h C void PLIB_PMP_WaitStatesDataHoldSelect(PMP_MODULE_ID index, PMP_DATA_HOLD_STATES dataHoldState); Returns None. Description This function configures the number of peripheral bus clock cycles needed for wait states. Refer to the enumeration PMP_DATA_HOLD_STATES for the possible settings. Remarks This function implements an operation of the DataHoldWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDataHoldWaitStates in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_WaitStatesDataHoldSelect( PMP_ID_0, PMP_DATA_HOLD_2 ); Parameters Parameters Description index Identifier for the device instance to be addressed dataHoldState One of the possible values from PMP_DATA_HOLD_STATES Function void PLIB_PMP_WaitStatesDataHoldSelect( PMP_MODULE_ID index, PMP_DATA_HOLD_STATES dataHoldState ) PLIB_PMP_WaitStatesDataSetUpSelect Function Configures the data wait states (before the data transfer) needed to be used with the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1452 File plib_pmp.h C void PLIB_PMP_WaitStatesDataSetUpSelect(PMP_MODULE_ID index, PMP_DATA_WAIT_STATES dataWaitState); Returns None. Description This function configures the number of peripheral bus clock cycles needed for wait states. Refer to the enumeration PMP_DATA_WAIT_STATES for the possible settings. Remarks This function implements an operation of the DataSetUpWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDataSetUpWaitStates in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_WaitStatesDataSetUpSelect( PMP_ID_0, PMP_DATA_WAIT_TWO ); Parameters Parameters Description index Identifier for the device instance to be addressed dataWaitState One of the possible values from PMP_DATA_WAIT_STATES Function void PLIB_PMP_WaitStatesDataSetUpSelect( PMP_MODULE_ID index, PMP_DATA_WAIT_STATES dataWaitState ) PLIB_PMP_WaitStatesStrobeSelect Function Configures the strobe wait states (during the data transfer) needed to be used with the PMP module. File plib_pmp.h C void PLIB_PMP_WaitStatesStrobeSelect(PMP_MODULE_ID index, PMP_STROBE_WAIT_STATES strobeWaitState); Returns None. Description This function configures the number of peripheral bus clock cycles needed for wait states. Refer to the enumeration PMP_STROBE_WAIT_STATES for the possible settings. Remarks This function implements an operation of the DataStrobeWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDataStrobeWaitStates in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_WaitStatesStrobeSelect( PMP_ID_0, PMP_STROBE_WAIT_2 ); Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1453 Parameters Parameters Description index Identifier for the device instance to be addressed strobeWaitState One of the possible values from PMP_STROBE_WAIT_STATES Function void PLIB_PMP_WaitStatesStrobeSelect( PMP_MODULE_ID index, PMP_STROBE_WAIT_STATES strobeWaitState ) g) Address Handling Functions PLIB_PMP_AddressGet Function Gets the current address of the PMP module. File plib_pmp.h C uint32_t PLIB_PMP_AddressGet(PMP_MODULE_ID index); Returns • address - Device address to be set Description This function gets the current address of the PMP module. Remarks This function implements an operation of the AddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressControl in your application to to automatically determine whether this feature is available. Preconditions None. Example uint32_t address; address = PLIB_PMP_AddressGet( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function uint32_t PLIB_PMP_AddressGet ( PMP_MODULE_ID index ) PLIB_PMP_AddressLinesA0A1Get Function Gets the value of the address lines PMA0 and PMA1. File plib_pmp.h C uint8_t PLIB_PMP_AddressLinesA0A1Get(PMP_MODULE_ID index); Returns uint8_t - The two-bit address Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1454 Description This function gets the value of the address lines PMA0 and PMA1. This function is used in the addressable parallel slave port mode. Remarks This function implements an operation of the AddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressControl in your application to to automatically determine whether this feature is available. Preconditions None. Example uint8_t bufferAddress; bufferAddress = PLIB_PMP_AddressLinesA0A1Get( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function uint8_t PLIB_PMP_AddressLinesA0A1Get ( PMP_MODULE_ID index ) PLIB_PMP_AddressLinesA0A1Set Function Sets the address lines PMA0 and PMA1 with the value specified. File plib_pmp.h C void PLIB_PMP_AddressLinesA0A1Set(PMP_MODULE_ID index, uint8_t address); Returns None. Description This function sets the address lines PMA0 and PMA1 with the value specified. This function is used in the addressable parallel slave port mode. Remarks This function implements an operation of the AddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressControl in your application to to automatically determine whether this feature is available. Preconditions None. Example uint8_t bufferAddress = 0x2; PLIB_PMP_AddressLinesA0A1Set( PMP_ID_0, bufferAddress ); Parameters Parameters Description index Identifier for the device instance to be addressed address The two-bit address Function void PLIB_PMP_AddressLinesA0A1Set ( PMP_MODULE_ID index, uint8_t address ) Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1455 PLIB_PMP_AddressSet Function Sets the current address of the PMP module to the specified address. File plib_pmp.h C void PLIB_PMP_AddressSet(PMP_MODULE_ID index, uint32_t address); Returns None. Description This function sets the current address of the PMP module to the specified value. Remarks This function implements an operation of the AddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressControl in your application to to automatically determine whether this feature is available. Preconditions None. Example uint8_t no_of_addressLines = 8; PLIB_PMP_AddressSet( PMP_ID_0, 0xff ); Parameters Parameters Description index Identifier for the device instance to be addressed address Device address to be set Function void PLIB_PMP_AddressSet ( PMP_MODULE_ID index, uint32_t address ) h) Port Configuration Functions PLIB_PMP_AddressPortDisable Function Disables the port lines specified as PMP address lines. File plib_pmp.h C void PLIB_PMP_AddressPortDisable(PMP_MODULE_ID index, PMP_ADDRESS_PORT portfunctions); Returns None. Description This function disables the port lines specified as PMP address lines. They function as normal I/O lines. Remarks This function implements an operation of the AddressPortPinControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressPortPinControl in your application to to automatically determine whether this feature is available. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1456 Preconditions None. Example //Example-1 PMP_ADDRESS_PORT portfunctions = PMP_PMA2_TO_PMA13_PORTS; PLIB_PMP_AddressPortDisable( PMP_ID_0, PMP_PMA2_TO_PMA13_PORTS ); //Example-2 PLIB_PMP_AddressPortDisable( PMP_ID_0, ( PMP_PMA14_PORT | PMP_PMA15_PORT ) ); Parameters Parameters Description index Identifier for the device instance to be addressed portfunctions One of the possible values from PMP_ADDRESS_PORT Function void PLIB_PMP_AddressPortDisable ( PMP_MODULE_ID index, PMP_ADDRESS_PORT portfunctions ) PLIB_PMP_AddressPortEnable Function Enables the port lines specified as PMP address lines. File plib_pmp.h C void PLIB_PMP_AddressPortEnable(PMP_MODULE_ID index, PMP_ADDRESS_PORT portfunctions); Returns None. Description This function enables the port lines specified as PMP address lines. Remarks This function implements an operation of the AddressPortPinControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressPortPinControl in your application to to automatically determine whether this feature is available. Preconditions None. Example //Example-1 PMP_ADDRESS_PORT portfunctions = PMP_PMA2_TO_PMA13_PORTS; PLIB_PMP_AddressPortEnable( PMP_ID_0, PMP_PMA2_TO_PMA13_PORTS ); //Example-2 PLIB_PMP_AddressPortEnable( PMP_ID_0, ( PMP_PMA14_PORT | PMP_PMA15_PORT ) ); Parameters Parameters Description index Identifier for the device instance to be addressed portfunctions One of the possible values from PMP_ADDRESS_PORT Function void PLIB_PMP_AddressPortEnable ( PMP_MODULE_ID index, Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1457 PMP_ADDRESS_PORT portfunctions ) PLIB_PMP_ReadWriteStrobePortDisable Function Disables the PMP module read strobe port. File plib_pmp.h C void PLIB_PMP_ReadWriteStrobePortDisable(PMP_MODULE_ID index); Returns None. Description This function disables the read strobe port of the PMP module. Remarks This function implements an operation of the ReadWriteStrobePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsReadWriteStrobePortControl in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_ReadWriteStrobePortDisable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_ReadWriteStrobePortDisable ( PMP_MODULE_ID index ) PLIB_PMP_ReadWriteStrobePortEnable Function Enables the PMP module read strobe port. File plib_pmp.h C void PLIB_PMP_ReadWriteStrobePortEnable(PMP_MODULE_ID index); Returns None. Description This function enables the read strobe port of the PMP module. Remarks This function implements an operation of the ReadWriteStrobePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsReadWriteStrobePortControl in your application to to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1458 Example PLIB_PMP_ReadWriteStrobePortEnable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_ReadWriteStrobePortEnable ( PMP_MODULE_ID index ) PLIB_PMP_WriteEnableStrobePortDisable Function Disables the PMP module write strobe port. File plib_pmp.h C void PLIB_PMP_WriteEnableStrobePortDisable(PMP_MODULE_ID index); Returns None. Description This function disables the write strobe port of the PMP module. Remarks This function implements an operation of the WriteEnablePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWriteEnablePortControl in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_WriteEnableStrobePortDisable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_WriteEnableStrobePortDisable ( PMP_MODULE_ID index ) PLIB_PMP_WriteEnableStrobePortEnable Function Enables the PMP module write strobe port. File plib_pmp.h C void PLIB_PMP_WriteEnableStrobePortEnable(PMP_MODULE_ID index); Returns None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1459 Description This function enables the write strobe port of the PMP module. Remarks This function implements an operation of the WriteEnablePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWriteEnablePortControl in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_WriteEnableStrobePortEnable( PMP_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be addressed Function void PLIB_PMP_WriteEnableStrobePortEnable ( PMP_MODULE_ID index ) i) Polarity Configuration Functions PLIB_PMP_AddressLatchPolaritySelect Function Sets the address latch strobe polarity. File plib_pmp.h C void PLIB_PMP_AddressLatchPolaritySelect(PMP_MODULE_ID index, PMP_POLARITY_LEVEL polarity); Returns None. Description This function sets the address latch polarity to the level specified. Remarks This function implements an operation of the AddressLatchPolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressLatchPolarity in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_AddressLatchPolaritySelect( PMP_ID_0, PMP_POLARITY_ACTIVE_HIGH ); Parameters Parameters Description index Identifier for the device instance to be addressed polarity Possible polarity levels Function void PLIB_PMP_AddressLatchPolaritySelect( PMP_MODULE_ID index, PMP_POLARITY_LEVEL polarity ) Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1460 PLIB_PMP_ChipSelectXPolaritySelect Function Sets the specified Chip Select polarity. File plib_pmp.h C void PLIB_PMP_ChipSelectXPolaritySelect(PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_POLARITY_LEVEL polarity); Returns None. Description This function sets the specified Chip Select polarity to the level specified. Remarks This function implements an operation of the ChipXPolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXPolarity in your application to to automatically determine whether this feature is available. Preconditions None. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_ChipSelectXPolaritySelect( PMP_ID_0, chipSelect, PMP_POLARITY_ACTIVE_HIGH ); Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for Chip Select polarity Possible polarity levels Function void PLIB_PMP_ChipSelectXPolaritySelect ( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_POLARITY_LEVEL polarity ) PLIB_PMP_ReadWriteStrobePolaritySelect Function Sets the polarity of the read strobe. File plib_pmp.h C void PLIB_PMP_ReadWriteStrobePolaritySelect(PMP_MODULE_ID index, PMP_POLARITY_LEVEL polarity); Returns None. Description This function sets polarity of the read strobe to the level specified. Remarks This function implements an operation of the ReadWritePolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsReadWritePolarity in your application to to automatically determine Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1461 whether this feature is available. Preconditions None. Example PLIB_PMP_ReadWriteStrobePolaritySelect( PMP_ID_0, PMP_POLARITY_ACTIVE_HIGH ); Parameters Parameters Description index Identifier for the device instance to be addressed polarity Possible polarity levels Function void PLIB_PMP_ReadWriteStrobePolaritySelect ( PMP_MODULE_ID index, PMP_POLARITY_LEVEL polarity ) PLIB_PMP_WriteEnableStrobePolaritySelect Function Sets the polarity of the write enable strobe. File plib_pmp.h C void PLIB_PMP_WriteEnableStrobePolaritySelect(PMP_MODULE_ID index, PMP_POLARITY_LEVEL polarity); Returns None. Description This function sets the polarity of the write enable strobe to the level specified. Remarks This function implements an operation of the WriteEnablePolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWriteEnablePolarity in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PMP_WriteEnableStrobePolaritySelect( PMP_ID_0, PMP_POLARITY_ACTIVE_HIGH ); Parameters Parameters Description index Identifier for the device instance to be addressed polarity Possible polarity levels Function void PLIB_PMP_WriteEnableStrobePolaritySelect ( PMP_MODULE_ID index, PMP_POLARITY_LEVEL polarity ) j) Feature Existence Functions PLIB_PMP_ExistsAddressControl Function Identifies whether the AddressControl feature exists on the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1462 File plib_pmp.h C bool PLIB_PMP_ExistsAddressControl(PMP_MODULE_ID index); Returns • true - The AddressControl feature is supported on the device • false - The AddressControl feature is not supported on the device Description This function identifies whether the AddressControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_AddressSet • PLIB_PMP_AddressGet • PLIB_PMP_AddressLinesA0A1Set • PLIB_PMP_AddressLinesA0A1Get Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsAddressControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsAddressLatchPolarity Function Identifies whether the AddressLatchPolarity feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsAddressLatchPolarity(PMP_MODULE_ID index); Returns • true - The AddressLatchPolarity feature is supported on the device • false - The AddressLatchPolarity feature is not supported on the device Description This function identifies whether the AddressLatchPolarity feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_AddressLatchPolaritySelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1463 Function PLIB_PMP_ExistsAddressLatchPolarity( PMP_MODULE_ID index ) PLIB_PMP_ExistsAddressLatchStrobePortControl Function Identifies whether the AddressLatchStrobePortControl feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsAddressLatchStrobePortControl(PMP_MODULE_ID index); Returns • true - The AddressLatchStrobePortControl feature is supported on the device • false - The AddressLatchStrobePortControl feature is not supported on the device Description This function identifies whether the AddressLatchStrobePortControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_AddressLatchStrobeEnable • PLIB_PMP_AddressLatchStrobeDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsAddressLatchStrobePortControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsAddressPortPinControl Function Identifies whether the AddressPortPinControl feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsAddressPortPinControl(PMP_MODULE_ID index); Returns • true - The AddressPortPinControl feature is supported on the device • false - The AddressPortPinControl feature is not supported on the device Description This function identifies whether the AddressPortPinControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_AddressPortEnable • PLIB_PMP_AddressPortDisable Remarks None. Preconditions None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1464 Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsAddressPortPinControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsBufferOverFlow Function Identifies whether the BufferOverFlow feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsBufferOverFlow(PMP_MODULE_ID index); Returns • true - The BufferOverFlow feature is supported on the device • false - The BufferOverFlow feature is not supported on the device Description This function identifies whether the BufferOverFlow feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_InputOverflowHasOccurred • PLIB_PMP_InputOverflowClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsBufferOverFlow( PMP_MODULE_ID index ) PLIB_PMP_ExistsBufferRead Function Identifies whether the BufferRead feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsBufferRead(PMP_MODULE_ID index); Returns • true - The BufferRead feature is supported on the device • false - The BufferRead feature is not supported on the device Description This function identifies whether the BufferRead feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_InputBufferXByteReceive Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1465 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsBufferRead( PMP_MODULE_ID index ) PLIB_PMP_ExistsBufferType Function Identifies whether the BufferType feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsBufferType(PMP_MODULE_ID index); Returns • true - The BufferType feature is supported on the device • false - The BufferType feature is not supported on the device Description This function identifies whether the BufferType feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_InputBufferTypeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsBufferType( PMP_MODULE_ID index ) PLIB_PMP_ExistsBufferUnderFlow Function Identifies whether the BufferUnderFlow feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsBufferUnderFlow(PMP_MODULE_ID index); Returns • true - The BufferUnderFlow feature is supported on the device • false - The BufferUnderFlow feature is not supported on the device Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1466 Description This function identifies whether the BufferUnderFlow feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_OutputUnderflowHasOccurred • PLIB_PMP_OutputUnderflowClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsBufferUnderFlow( PMP_MODULE_ID index ) PLIB_PMP_ExistsBufferWrite Function Identifies whether the BufferWrite feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsBufferWrite(PMP_MODULE_ID index); Returns • true - The BufferWrite feature is supported on the device • false - The BufferWrite feature is not supported on the device Description This function identifies whether the BufferWrite feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_OutputBufferXByteSend Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsBufferWrite( PMP_MODULE_ID index ) PLIB_PMP_ExistsBusyStatus Function Identifies whether the BusyStatus feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsBusyStatus(PMP_MODULE_ID index); Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1467 Returns • true - The BusyStatus feature is supported on the device • false - The BusyStatus feature is not supported on the device Description This function identifies whether the BusyStatus feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_PortIsBusy Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsBusyStatus( PMP_MODULE_ID index ) PLIB_PMP_ExistsChipSelectEnable Function Identifies whether the ChipSelectEnable feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsChipSelectEnable(PMP_MODULE_ID index); Returns • true - The ChipSelectEnable feature is supported on the device • false - The ChipSelectEnable feature is not supported on the device Description This function identifies whether the ChipSelectEnable feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_ChipSelectXEnable • PLIB_PMP_ChipSelectXDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsChipSelectEnable( PMP_MODULE_ID index ) PLIB_PMP_ExistsChipSelectoperation Function Identifies whether the ChipSelectoperation feature exists on the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1468 File plib_pmp.h C bool PLIB_PMP_ExistsChipSelectoperation(PMP_MODULE_ID index); Returns • true - The ChipSelectoperation feature is supported on the device • false - The ChipSelectoperation feature is not supported on the device Description This function identifies whether the ChipSelectoperation feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_ChipSelectFunctionSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsChipSelectoperation( PMP_MODULE_ID index ) PLIB_PMP_ExistsChipXPolarity Function Identifies whether the ChipXPolarity feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsChipXPolarity(PMP_MODULE_ID index); Returns • true - The ChipXPolarity feature is supported on the device • false - The ChipXPolarity feature is not supported on the device Description This function identifies whether the ChipXPolarity feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_ChipSelectXPolaritySelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsChipXPolarity( PMP_MODULE_ID index ) Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1469 PLIB_PMP_ExistsCSXActiveStatus Function Identifies whether the CSXActiveStatus feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsCSXActiveStatus(PMP_MODULE_ID index); Returns • true - The CSXActiveStatus feature is supported on the device • false - The CSXActiveStatus feature is not supported on the device Description This function identifies whether the CSXActiveStatus feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_ChipSelectXIsActive Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsCSXActiveStatus( PMP_MODULE_ID index ) PLIB_PMP_ExistsDataHoldWaitStates Function Identifies whether the DataHoldWaitStates feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsDataHoldWaitStates(PMP_MODULE_ID index); Returns • true - The DataHoldWaitStates feature is supported on the device • false - The DataHoldWaitStates feature is not supported on the device Description This function identifies whether the DataHoldWaitStates feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_WaitStatesDataHoldSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1470 Function PLIB_PMP_ExistsDataHoldWaitStates( PMP_MODULE_ID index ) PLIB_PMP_ExistsDataSetUpWaitStates Function Identifies whether the DataSetUpWaitStates feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsDataSetUpWaitStates(PMP_MODULE_ID index); Returns • true - The DataSetUpWaitStates feature is supported on the device • false - The DataSetUpWaitStates feature is not supported on the device Description This function identifies whether the DataSetUpWaitStates feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_WaitStatesDataSetUpSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsDataSetUpWaitStates( PMP_MODULE_ID index ) PLIB_PMP_ExistsDataStrobeWaitStates Function Identifies whether the DataStrobeWaitStates feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsDataStrobeWaitStates(PMP_MODULE_ID index); Returns • true - The DataStrobeWaitStates feature is supported on the device • false - The DataStrobeWaitStates feature is not supported on the device Description This function identifies whether the DataStrobeWaitStates feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_WaitStatesStrobeSelect Remarks None. Preconditions None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1471 Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsDataStrobeWaitStates( PMP_MODULE_ID index ) PLIB_PMP_ExistsDataTransferSize Function Identifies whether the DataTransferSize feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsDataTransferSize(PMP_MODULE_ID index); Returns • true - The DataTransferSize feature is supported on the device • false - The DataTransferSize feature is not supported on the device Description This function identifies whether the DataTransferSize feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_DataSizeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsDataTransferSize( PMP_MODULE_ID index ) PLIB_PMP_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsEnableControl(PMP_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_Disable • PLIB_PMP_Enable • PLIB_PMP_IsEnabled Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1472 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsEnableControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsIncrementMode Function Identifies whether the IncrementMode feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsIncrementMode(PMP_MODULE_ID index); Returns • true - The IncrementMode feature is supported on the device • false - The IncrementMode feature is not supported on the device Description This function identifies whether the IncrementMode feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_AddressIncrementModeSelect • PLIB_PMP_AddressIncrementModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsIncrementMode( PMP_MODULE_ID index ) PLIB_PMP_ExistsInputBufferFull Function Identifies whether the InputBufferFull feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsInputBufferFull(PMP_MODULE_ID index); Returns • true - The InputBufferFull feature is supported on the device • false - The InputBufferFull feature is not supported on the device Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1473 Description This function identifies whether the InputBufferFull feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_InputBuffersAreFull Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsInputBufferFull( PMP_MODULE_ID index ) PLIB_PMP_ExistsInputBufferXStatus Function Identifies whether the InputBufferXStatus feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsInputBufferXStatus(PMP_MODULE_ID index); Returns • true - The InputBufferXStatus feature is supported on the device • false - The InputBufferXStatus feature is not supported on the device Description This function identifies whether the InputBufferXStatus feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_InputBufferXIsFull • PLIB_PMP_IsDataReceived Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsInputBufferXStatus( PMP_MODULE_ID index ) PLIB_PMP_ExistsInterruptMode Function Identifies whether the InterruptMode feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsInterruptMode(PMP_MODULE_ID index); Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1474 Returns • true - The InterruptMode feature is supported on the device • false - The InterruptMode feature is not supported on the device Description This function identifies whether the InterruptMode feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_InterruptModeSelect • PLIB_PMP_InterruptModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsInterruptMode( PMP_MODULE_ID index ) PLIB_PMP_ExistsMasterRXTX Function Identifies whether the MasterRXTX feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsMasterRXTX(PMP_MODULE_ID index); Returns • true - The MasterRXTX feature is supported on the device • false - The MasterRXTX feature is not supported on the device Description This function identifies whether the MasterRXTX feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_MasterSend • PLIB_PMP_MasterReceive Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsMasterRXTX( PMP_MODULE_ID index ) PLIB_PMP_ExistsMUXModeSelect Function Identifies whether the MUXModeSelect feature exists on the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1475 File plib_pmp.h C bool PLIB_PMP_ExistsMUXModeSelect(PMP_MODULE_ID index); Returns • true - The MUXModeSelect feature is supported on the device • false - The MUXModeSelect feature is not supported on the device Description This function identifies whether the MUXModeSelect feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_MultiplexModeSelect • PLIB_PMP_MultiplexModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsMUXModeSelect( PMP_MODULE_ID index ) PLIB_PMP_ExistsOperationMode Function Identifies whether the OperationMode feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsOperationMode(PMP_MODULE_ID index); Returns • true - The OperationMode feature is supported on the device • false - The OperationMode feature is not supported on the device Description This function identifies whether the OperationMode feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_OperationModeSelect • PLIB_PMP_OperationModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsOperationMode( PMP_MODULE_ID index ) Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1476 PLIB_PMP_ExistsOutPutBufferEmpty Function Identifies whether the OutPutBufferEmpty feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsOutPutBufferEmpty(PMP_MODULE_ID index); Returns • true - The OutPutBufferEmpty feature is supported on the device • false - The OutPutBufferEmpty feature is not supported on the device Description This function identifies whether the OutPutBufferEmpty feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_OutputBuffersAreEmpty Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsOutPutBufferEmpty( PMP_MODULE_ID index ) PLIB_PMP_ExistsOutputBufferXStatus Function Identifies whether the OutputBufferXStatus feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsOutputBufferXStatus(PMP_MODULE_ID index); Returns • true - The OutputBufferXStatus feature is supported on the device • false - The OutputBufferXStatus feature is not supported on the device Description This function identifies whether the OutputBufferXStatus feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_OutputBufferXIsEmpty • PLIB_PMP_IsDataTransmitted Remarks None. Preconditions None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1477 Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsOutputBufferXStatus( PMP_MODULE_ID index ) PLIB_PMP_ExistsReadWritePolarity Function Identifies whether the ReadWritePolarity feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsReadWritePolarity(PMP_MODULE_ID index); Returns • true - The ReadWritePolarity feature is supported on the device • false - The ReadWritePolarity feature is not supported on the device Description This function identifies whether the ReadWritePolarity feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_ReadWriteStrobePolaritySelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsReadWritePolarity( PMP_MODULE_ID index ) PLIB_PMP_ExistsReadWriteStrobePortControl Function Identifies whether the ReadWriteStrobePortControl feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsReadWriteStrobePortControl(PMP_MODULE_ID index); Returns • true - The ReadWriteStrobePortControl feature is supported on the device • false - The ReadWriteStrobePortControl feature is not supported on the device Description This function identifies whether the ReadWriteStrobePortControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_ReadWriteStrobePortEnable • PLIB_PMP_ReadWriteStrobePortDisable Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1478 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsReadWriteStrobePortControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsSlaveRX Function Identifies whether the SlaveRX feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsSlaveRX(PMP_MODULE_ID index); Returns • true - The SlaveRX feature is supported on the device • false - The SlaveRX feature is not supported on the device Description This function identifies whether the SlaveRX feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_SlaveReceive Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsSlaveRX( PMP_MODULE_ID index ) PLIB_PMP_ExistsSlaveTX Function Identifies whether the SlaveTX feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsSlaveTX(PMP_MODULE_ID index); Returns • true - The SlaveTX feature is supported on the device • false - The SlaveTX feature is not supported on the device Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1479 Description This function identifies whether the SlaveTX feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_SlaveSend Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsSlaveTX( PMP_MODULE_ID index ) PLIB_PMP_ExistsStopInIdleControl Function Identifies whether the StopInIdleControl feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsStopInIdleControl(PMP_MODULE_ID index); Returns • true - The StopInIdleControl feature is supported on the device • false - The StopInIdleControl feature is not supported on the device Description This function identifies whether the StopInIdleControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_StopInIdleEnable • PLIB_PMP_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsStopInIdleControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsWriteEnablePolarity Function Identifies whether the WriteEnablePolarity feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsWriteEnablePolarity(PMP_MODULE_ID index); Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1480 Returns • true - The WriteEnablePolarity feature is supported on the device • false - The WriteEnablePolarity feature is not supported on the device Description This function identifies whether the WriteEnablePolarity feature is available on the PMP module. When this function returns true, this function is supported on the device: • PLIB_PMP_WriteEnableStrobePolaritySelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsWriteEnablePolarity( PMP_MODULE_ID index ) PLIB_PMP_ExistsWriteEnablePortControl Function Identifies whether the WriteEnablePortControl feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsWriteEnablePortControl(PMP_MODULE_ID index); Returns • true - The WriteEnablePortControl feature is supported on the device • false - The WriteEnablePortControl feature is not supported on the device Description This function identifies whether the WriteEnablePortControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_WriteEnableStrobePortEnable • PLIB_PMP_WriteEnableStrobePortDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsWriteEnablePortControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsDualBufferControl Function Identifies whether the DualBufferControl feature exists on the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1481 File plib_pmp.h C bool PLIB_PMP_ExistsDualBufferControl(PMP_MODULE_ID index); Returns • true - The DualBufferControl feature is supported on the device • false - The DualBufferControl feature is not supported on the device Description This function identifies whether the DualBufferControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_DualBufferDisable • PLIB_PMP_DualBufferEnable • PLIB_PMP_DualBufferIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsDualBufferControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsDualModeMasterRXTX Function Identifies whether the DualModeMasterRXTX feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsDualModeMasterRXTX(PMP_MODULE_ID index); Returns • true - The DualModeMasterRXTX feature is supported on the device • false - The DualModeMasterRXTX feature is not supported on the device Description This function identifies whether the DualModeMasterRXTX feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_DualModeMasterSend • PLIB_PMP_DualModeMasterReceive Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1482 Function PLIB_PMP_ExistsDualModeMasterRXTX( PMP_MODULE_ID index ) PLIB_PMP_ExistsDualModeReadAddressControl Function Identifies whether the DualModeReadAddressControl feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsDualModeReadAddressControl(PMP_MODULE_ID index); Returns • true - The DualModeReadAddressControl feature is supported on the device • false - The DualModeReadAddressControl feature is not supported on the device Description This function identifies whether the DualModeReadAddressControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_DualModeReadAddressSet • PLIB_PMP_DualModeReadAddressGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsDualModeReadAddressControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsDualModeWriteAddressControl Function Identifies whether the DualModeWriteAddressControl feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsDualModeWriteAddressControl(PMP_MODULE_ID index); Returns • true - The DualModeWriteAddressControl feature is supported on the device • false - The DualModeWriteAddressControl feature is not supported on the device Description This function identifies whether the DualModeWriteAddressControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_DualModeWriteAddressSet • PLIB_PMP_DualModeWriteAddressGet Remarks None. Preconditions None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1483 Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsDualModeWriteAddressControl( PMP_MODULE_ID index ) PLIB_PMP_ExistsReadChipSelectEnable Function Identifies whether the ReadChipSelectEnable feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsReadChipSelectEnable(PMP_MODULE_ID index); Returns • true - The ReadChipSelectEnable feature is supported on the device • false - The ReadChipSelectEnable feature is not supported on the device Description This function identifies whether the ReadChipSelectEnable feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_ReadChipSelectXEnable • PLIB_PMP_ReadChipSelectXDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsReadChipSelectEnable( PMP_MODULE_ID index ) PLIB_PMP_ExistsWriteChipSelectEnable Function Identifies whether the WriteChipSelectEnable feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsWriteChipSelectEnable(PMP_MODULE_ID index); Returns • true - The WriteChipSelectEnable feature is supported on the device • false - The WriteChipSelectEnable feature is not supported on the device Description This function identifies whether the WriteChipSelectEnable feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_WriteChipSelectXEnable • PLIB_PMP_WriteChipSelectXDisable Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1484 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsWriteChipSelectEnable( PMP_MODULE_ID index ) PLIB_PMP_ExistsStartReadControl Function Identifies whether the StartReadControl feature exists on the PMP module. File plib_pmp.h C bool PLIB_PMP_ExistsStartReadControl(PMP_MODULE_ID index); Returns • true - The StartReadControl feature is supported on the device • false - The StartReadControl feature is not supported on the device Description This function identifies whether the StartReadControl feature is available on the PMP module. When this function returns true, these functions are supported on the device: • PLIB_PMP_ReadCycleStart • PLIB_PMP_ReadCycleIsStarted Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PMP_ExistsStartReadControl( PMP_MODULE_ID index ) k) Data Types and Constants PMP_ACK_MODE Enumeration Defines the different mode configurations in which the PMP can be enabled. File plib_pmp_help.h C typedef enum { PMP_USE_ACK_WITH_TIMEOUT, PMP_USE_ACK, Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1485 PMP_ACK_DISABLED } PMP_ACK_MODE; Members Members Description PMP_USE_ACK_WITH_TIMEOUT Acknowledge used with a timeout PMP_USE_ACK Acknowledge is used PMP_ACK_DISABLED Acknowledge is not used Description PMP Acknowledge Modes This data type defines the different configurations by which the PMP can be enabled. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_ADDRESS_HOLD_LATCH_WAIT_STATES Enumeration PMP hold after address latch strobe wait states configuration. File plib_pmp_help.h C typedef enum { PMP_ADDRESS_HOLD_ONE_AND_ONE_QUARTER, PMP_ADDRESS_HOLD_ONE_QUARTER } PMP_ADDRESS_HOLD_LATCH_WAIT_STATES; Members Members Description PMP_ADDRESS_HOLD_ONE_AND_ONE_QUARTER Data Wait of 1 1/4 Peripheral Bus Clock Cycles PMP_ADDRESS_HOLD_ONE_QUARTER Data Wait of 1/4 Peripheral Bus Clock Cycles Description PMP Address Latch Strobe Wait States This data type defines the different configurations by which the PMP holds after address latch strobe wait states can be configured. Refer to the specific device data sheet for the exact clock cycle timing. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_ADDRESS_LATCH Enumeration Address Latch Strobe configuration. File plib_pmp_help.h C typedef enum { PMP_ADDRESS_LATCH_UPPER, PMP_ADDRESS_LATCH_HIGH, PMP_ADDRESS_LATCH_LOW } PMP_ADDRESS_LATCH; Members Members Description PMP_ADDRESS_LATCH_UPPER Address latch upper PMP_ADDRESS_LATCH_HIGH Address latch high PMP_ADDRESS_LATCH_LOW Address latch low Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1486 Description PMP Address Latch This data type defines the different configurations by which the PMP address latch strobes can be configured. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_ADDRESS_LATCH_WAIT_STATES Enumeration PMP address latch strobe wait states configuration. File plib_pmp_help.h C typedef enum { PMP_ADDRESS_WAIT_THREE_AND_HALF, PMP_ADDRESS_WAIT_TWO_AND_HALF, PMP_ADDRESS_WAIT_ONE_AND_HALF, PMP_ADDRESS_WAIT_HALF } PMP_ADDRESS_LATCH_WAIT_STATES; Members Members Description PMP_ADDRESS_WAIT_THREE_AND_HALF Data Wait of 3 1/2 Peripheral Bus Clock Cycles PMP_ADDRESS_WAIT_TWO_AND_HALF Data Wait of 2 1/2 Peripheral Bus Clock Cycles PMP_ADDRESS_WAIT_ONE_AND_HALF Data Wait of 1 1/2 Peripheral Bus Clock Cycles PMP_ADDRESS_WAIT_HALF Data Wait of 1/2 Peripheral Bus Clock Cycles Description PMP Address Latch Strobe Wait States This data type defines the different configurations by which the PMP address latch strobe wait states can be configured. Refer to the specific device data sheet for the exact clock cycle timing. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_ADDRESS_PORT Enumeration Defines the different address lines that are available for configuration. File plib_pmp_help.h C typedef enum { PMP_PMA0_PORT, PMP_PMA1_PORT, PMP_PMA2_TO_PMA13_PORTS, PMP_PMA2_PORT, PMP_PMA3_PORT, PMP_PMA4_PORT, PMP_PMA5_PORT, PMP_PMA6_PORT, PMP_PMA7_PORT, PMP_PMA8_PORT, PMP_PMA9_PORT, PMP_PMA10_PORT, PMP_PMA11_PORT, PMP_PMA12_PORT, PMP_PMA13_PORT, PMP_PMA14_PORT, PMP_PMA15_PORT, PMP_PMA16_TO_PMA22_PORTS, Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1487 PMP_PMA2_TO_PMA10_PORTS } PMP_ADDRESS_PORT; Members Members Description PMP_PMA0_PORT Address line 0 port (make as general purpose I/O or PMP address line) PMP_PMA1_PORT Address line 1 port (make as general purpose I/O or PMP address line) PMP_PMA2_TO_PMA13_PORTS Address line 2 to 13 ports (make as general purpose I/O or PMP address lines) PMP_PMA2_PORT Address line 2 port (make as general purpose I/O or PMP address line) PMP_PMA3_PORT Address line 3 port (make as general purpose I/O or PMP address line) PMP_PMA4_PORT Address line 4 port (make as general purpose I/O or PMP address line) PMP_PMA5_PORT Address line 5 port (make as general purpose I/O or PMP address line) PMP_PMA6_PORT Address line 6 port (make as general purpose I/O or PMP address line) PMP_PMA7_PORT Address line 7 port (make as general purpose I/O or PMP address line) PMP_PMA8_PORT Address line 8 port (make as general purpose I/O or PMP address line) PMP_PMA9_PORT Address line 9 port (make as general purpose I/O or PMP address line) PMP_PMA10_PORT Address line 10 port (make as general purpose I/O or PMP address line) PMP_PMA11_PORT Address line 11 port (make as general purpose I/O or PMP address line) PMP_PMA12_PORT Address line 12 port (make as general purpose I/O or PMP address line) PMP_PMA13_PORT Address line 13 port (make as general purpose I/O or PMP address line) PMP_PMA14_PORT Address line 14 port (make as general purpose I/O or PMP address line) PMP_PMA15_PORT Address line 15 port (make as general purpose I/O or PMP address line) PMP_PMA16_TO_PMA22_PORTS Address line 16 to 22 ports (make as general purpose I/O or PMP address lines) PMP_PMA2_TO_PMA10_PORTS Address line 2 to 10 ports (make as general purpose I/O or PMP address lines) Description PMP Address Port Pins This data type defines the different address that can be configured by the PMP module. The user application can make each pin as a general purpose I/O or part of PMP functionality. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). These enumerator values can be passed in a bitwise ORed fashion to select multiple ports at a time. PMP_ALTERNATE_MASTER_WAIT_STATES Enumeration PMP alternate master wait states. File plib_pmp_help.h C typedef enum { PMP_ALTERNATE_MASTER_WAIT_10, PMP_ALTERNATE_MASTER_WAIT_9, PMP_ALTERNATE_MASTER_WAIT_8, PMP_ALTERNATE_MASTER_WAIT_7, PMP_ALTERNATE_MASTER_WAIT_6, PMP_ALTERNATE_MASTER_WAIT_5, PMP_ALTERNATE_MASTER_WAIT_4, PMP_ALTERNATE_MASTER_WAIT_3 } PMP_ALTERNATE_MASTER_WAIT_STATES; Members Members Description PMP_ALTERNATE_MASTER_WAIT_10 Wait of 10 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_9 Wait of 9 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_8 Wait of 8 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_7 Wait of 7 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_6 Wait of 6 Alternate Master Cycles Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1488 PMP_ALTERNATE_MASTER_WAIT_5 Wait of 5 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_4 Wait of 4 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_3 Wait of 3 Alternate Master Cycles Description PMP Alternate Master Wait States This data type defines the different configurations by which the PMP alternate master wait states can be configured. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_CHIP_SELECT Enumeration PMP Chip Select data type. File plib_pmp_help.h C typedef enum { PMP_CHIP_SELECT_ONE, PMP_CHIP_SELECT_TWO } PMP_CHIP_SELECT; Members Members Description PMP_CHIP_SELECT_ONE Chip Select One PMP_CHIP_SELECT_TWO Chip Select Two Description PMP Chip Select This data type defines the different Chip Select lines of the PMP module. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_CHIPSELECT_FUNCTION Enumeration Defines different functions available for the Chip Select lines multiplexed with address lines. File plib_pmp_help.h C typedef enum { PMCS1_AS_CHIP_SELECT, PMCS1_AS_ADDRESS_LINE, PMCS1_PMCS2_AS_ADDRESS_LINES, PMCS1_AS_ADDRESS_LINE_PMCS2_AS_CHIP_SELECT, PMCS1_AND_PMCS2_AS_CHIP_SELECT } PMP_CHIPSELECT_FUNCTION; Members Members Description PMCS1_AS_CHIP_SELECT CS1 used as Chip Select PMCS1_AS_ADDRESS_LINE CS1 used as address line PMCS1_PMCS2_AS_ADDRESS_LINES CS1 and CS2 used as address lines PMCS1_AS_ADDRESS_LINE_PMCS2_AS_CHIP_SELECT CS1 used as address line and CS2 as Chip Select PMCS1_AND_PMCS2_AS_CHIP_SELECT Both CS1 and CS2 used as Chip Selects Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1489 Description PMP Chip Select pin functions This data type defines different functions of Chip Select pins. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_DATA_HOLD_STATES Enumeration PMP Data Hold after strobe wait state. File plib_pmp_help.h C typedef enum { PMP_DATA_HOLD_FOUR, PMP_DATA_HOLD_THREE, PMP_DATA_HOLD_TWO, PMP_DATA_HOLD_ONE } PMP_DATA_HOLD_STATES; Members Members Description PMP_DATA_HOLD_FOUR Data Hold of 4 Peripheral Bus Clock Cycles PMP_DATA_HOLD_THREE Data Hold of 3 Peripheral Bus Clock Cycles PMP_DATA_HOLD_TWO Data Hold of 2 Peripheral Bus Clock Cycles PMP_DATA_HOLD_ONE Data Hold of 1 Peripheral Bus Clock Cycles Description PMP Data Hold after strobe wait state This data type defines the different data Hold after strobe wait states. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_DATA_LENGTH Enumeration Possible data lengths handled by the PMP module. File plib_pmp_help.h C typedef enum { PMP_DATA_8_BITS, PMP_DATA_16_BITS, PMP_DATA_32_BITS } PMP_DATA_LENGTH; Members Members Description PMP_DATA_8_BITS 8-bit data length PMP_DATA_16_BITS 16-bit data length PMP_DATA_32_BITS 32-bit data length Description PMP data length This data type defines the possible data lengths handled by the PMP module. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1490 Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_DATA_SIZE Enumeration PMP data size. File plib_pmp_help.h C typedef enum { PMP_DATA_SIZE_8_BITS = 0x0, PMP_DATA_SIZE_16_BITS = 0x1 } PMP_DATA_SIZE; Members Members Description PMP_DATA_SIZE_8_BITS = 0x0 Data length of 8-bits PMP_DATA_SIZE_16_BITS = 0x1 Data length of 16-bits Description PMP DATA Size This data type defines the different configurations for the data lengths handled by the PMP module. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_DATA_WAIT_STATES Enumeration PMP data setup time configuration. File plib_pmp_help.h C typedef enum { PMP_DATA_WAIT_FOUR, PMP_DATA_WAIT_THREE, PMP_DATA_WAIT_TWO, PMP_DATA_WAIT_ONE } PMP_DATA_WAIT_STATES; Members Members Description PMP_DATA_WAIT_FOUR Data Wait of 4 Peripheral Bus Clock Cycles PMP_DATA_WAIT_THREE Data Wait of 3 Peripheral Bus Clock Cycles PMP_DATA_WAIT_TWO Data Wait of 2 Peripheral Bus Clock Cycles PMP_DATA_WAIT_ONE Data Wait of 1 Peripheral Bus Clock Cycles Description PMP Data setup to read/write/address phase wait state configuration This data type defines the different wait state configurations for setup to read/write/address phase. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_INCREMENT_MODE Enumeration PMP address incrementing configuration. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1491 File plib_pmp_help.h C typedef enum { PMP_BUFFERS_AUTO_INCREMENT, PMP_ADDRESS_AUTO_DECREMENT, PMP_ADDRESS_AUTO_INCREMENT, PMP_ADDRESS_INCREMENT_DECREMENT_DISABLE } PMP_INCREMENT_MODE; Members Members Description PMP_BUFFERS_AUTO_INCREMENT Read and write buffers auto-increment PMP_ADDRESS_AUTO_DECREMENT Decrement PMP Address by one every read/write cycle PMP_ADDRESS_AUTO_INCREMENT Increment PMP Address by one every read/write cycle PMP_ADDRESS_INCREMENT_DECREMENT_DISABLE PMP Address does not change Description PMP Increment Modes This data type defines the different configurations by which the PMP address incrementing can be configured. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_INPUT_BUFFER_TYPE Enumeration PMP Input Buffers type. File plib_pmp_help.h C typedef enum { PMP_INPUT_BUFFER_TTL, PMP_INPUT_BUFFER_SCHMITT } PMP_INPUT_BUFFER_TYPE; Members Members Description PMP_INPUT_BUFFER_TTL TTL input buffer PMP_INPUT_BUFFER_SCHMITT Schmitt trigger input buffer Description PMP Input Buffers type This data type defines the input buffer types. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_INTERRUPT_MODE Enumeration PMP interrupt request mode data type. File plib_pmp_help.h C typedef enum { PMP_INTERRUPT_BUFFER_3_IS_ACCESSED, PMP_INTERRUPT_EVERY_RW_CYCLE, Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1492 PMP_INTERRUPT_NONE } PMP_INTERRUPT_MODE; Members Members Description PMP_INTERRUPT_BUFFER_3_IS_ACCESSED Interrupt generated when Read/Write Buffer 3 is read/written PMP_INTERRUPT_EVERY_RW_CYCLE Interrupt Occurs Every Read/Write Cycle PMP_INTERRUPT_NONE No interrupt generated Description PMP Interrupt Mode This data type defines the different configurations by which the PMP can be configured for interrupt requests. Remarks None. PMP_MASTER_MODE Enumeration Defines the different mode configurations in which the PMP can be enabled. File plib_pmp_help.h C typedef enum { PMP_ALTERNATE_MASTER_DIRECT, PMP_ALTERNATE_MASTER, PMP_CPU_MASTER } PMP_MASTER_MODE; Members Members Description PMP_ALTERNATE_MASTER_DIRECT Alternate Master has PMP control with Direct I/O access PMP_ALTERNATE_MASTER Alternate Master has PMP control PMP_CPU_MASTER CPU has PMP control Description PMP Master Modes This data type defines the different configurations by which the PMP can be enabled. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_MODULE_ID Enumeration Possible instances of the PMP module. File plib_pmp_help.h C typedef enum { PMP_ID_0 } PMP_MODULE_ID; Members Members Description PMP_ID_0 first instance of the PMP Description PMP module ID Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1493 This data type defines the possible instances of the PMP module. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_MUX_MODE Enumeration Defines the different mode configurations in which the PMP can be enabled. File plib_pmp_help.h C typedef enum { PMP_MUX_ADDRESS_PHASES_3, PMP_MUX_ADDRESS_PHASES_2, PMP_MUX_ADDRESS_PHASES_1, PMP_MUX_LINES_16_ADDRESS_16_DATA, PMP_MUX_LINES_16_ADDRESS_8_DATA, PMP_MUX_LINES_8_ADDRESS_8_DATA, PMP_MUX_NONE } PMP_MUX_MODE; Members Members Description PMP_MUX_ADDRESS_PHASES_3 Lower address bits are multiplexed with data bits using 3 address phase PMP_MUX_ADDRESS_PHASES_2 Lower address bits are multiplexed with data bits using 2 address phases PMP_MUX_ADDRESS_PHASES_1 Lower address bits are multiplexed with data bits using 1 address phase PMP_MUX_LINES_16_ADDRESS_16_DATA 16 address lines are multiplexed on 16 data lines PMP_MUX_LINES_16_ADDRESS_8_DATA 16 address lines multiplexed on 8 data lines PMP_MUX_LINES_8_ADDRESS_8_DATA 8 bits of address is multiplexed on 8 data lines PMP_MUX_NONE No multiplexing of address and data lines Description PMP Multiplex Modes This data type defines the different configurations by which the PMP can be enabled. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_OPERATION_MODE Enumeration Defines the different mode configurations in which the PMP can be enabled. File plib_pmp_help.h C typedef enum { PMP_MASTER_READ_WRITE_STROBES_MULTIPLEXED, PMP_MASTER_READ_WRITE_STROBES_INDEPENDENT, PMP_BUFFERED_SLAVE, PMP_ENHANCED_SLAVE, PMP_LEGACY_SLAVE } PMP_OPERATION_MODE; Members Members Description PMP_MASTER_READ_WRITE_STROBES_MULTIPLEXED Master mode 1, the read and the write strobes share a single line. The enable strobe is used to decode the info sent on read/write strobe line PMP_MASTER_READ_WRITE_STROBES_INDEPENDENT Master mode 2, the read and write strobes are on independent lines PMP_BUFFERED_SLAVE Buffered Slave mode PMP_ENHANCED_SLAVE Enhanced Slave mode Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1494 PMP_LEGACY_SLAVE Legacy Parallel Slave mode Description PMP Operation Modes This data type defines the different configurations by which the PMP can be enabled. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_PMBE_PORT Enumeration Defines the available Byte Enable ports. File plib_pmp_help.h C typedef enum { PMBE_0, PMBE_1 } PMP_PMBE_PORT; Members Members Description PMBE_0 Byte Enable Port-0 PMBE_1 Byte Enable Port-1 Description PMP Byte Enable port. This data type defines the available Byte Enable ports. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PMP_POLARITY_LEVEL Enumeration Possible polarity levels for the PMP pins. File plib_pmp_help.h C typedef enum { PMP_POLARITY_ACTIVE_HIGH, PMP_POLARITY_ACTIVE_LOW } PMP_POLARITY_LEVEL; Members Members Description PMP_POLARITY_ACTIVE_HIGH Active high polarity PMP_POLARITY_ACTIVE_LOW Active low polarity Description PMP Pins Polarity This data type defines the possible polarity levels for the PMP pins. Remarks None. Peripheral Libraries Help PMP Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1495 PMP_STROBE_WAIT_STATES Enumeration PMP strobe signal wait time configuration. File plib_pmp_help.h C typedef enum { PMP_STROBE_WAIT_FIFTEEN, PMP_STROBE_WAIT_FOURTEEN, PMP_STROBE_WAIT_THIRTEEN, PMP_STROBE_WAIT_TWELVE, PMP_STROBE_WAIT_ELEVEN, PMP_STROBE_WAIT_TEN, PMP_STROBE_WAIT_NINE, PMP_STROBE_WAIT_EIGHT, PMP_STROBE_WAIT_SEVEN, PMP_STROBE_WAIT_SIX, PMP_STROBE_WAIT_FIVE, PMP_STROBE_WAIT_FOUR, PMP_STROBE_WAIT_THREE, PMP_STROBE_WAIT_TWO, PMP_STROBE_WAIT_ONE, PMP_STROBE_WAIT_NONE } PMP_STROBE_WAIT_STATES; Members Members Description PMP_STROBE_WAIT_FIFTEEN Strobe Wait of 15 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_FOURTEEN Strobe Wait of 14 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_THIRTEEN Strobe Wait of 13 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_TWELVE Strobe Wait of 12 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_ELEVEN Strobe Wait of 11 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_TEN Strobe Wait of 10 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_NINE Strobe Wait of 9 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_EIGHT Strobe Wait of 8 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_SEVEN Strobe Wait of 7 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_SIX Strobe Wait of 6 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_FIVE Strobe Wait of 5 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_FOUR Strobe Wait of 4 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_THREE Strobe Wait of 3 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_TWO Strobe Wait of 2 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_ONE Strobe Wait of 1 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_NONE No wait states Description PMP Read to Byte enable strobe configuration This data type defines the different configurations by which the PMP strobe wait signal time can be configured. Remarks This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). Files Files Name Description plib_pmp.h Parallel Master Port (PMP) Peripheral Library Interface Header. plib_pmp_help.h Parallel Master Port (PMP) Peripheral Library Help Header. Peripheral Libraries Help PMP Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1496 Description This section lists the source and header files used by the library. plib_pmp.h Parallel Master Port (PMP) Peripheral Library Interface Header. Functions Name Description PLIB_PMP_AddressGet Gets the current address of the PMP module. PLIB_PMP_AddressIncrementModeGet Gets the increment mode being used with the address of the PMP module. PLIB_PMP_AddressIncrementModeSelect Configures the increment mode being used with the address of the PMP module. PLIB_PMP_AddressLatchPolaritySelect Sets the address latch strobe polarity. PLIB_PMP_AddressLatchStrobeDisable Disables the specific address latch strobe. PLIB_PMP_AddressLatchStrobeEnable Enables the specific address latch strobe. PLIB_PMP_AddressLinesA0A1Get Gets the value of the address lines PMA0 and PMA1. PLIB_PMP_AddressLinesA0A1Set Sets the address lines PMA0 and PMA1 with the value specified. PLIB_PMP_AddressPortDisable Disables the port lines specified as PMP address lines. PLIB_PMP_AddressPortEnable Enables the port lines specified as PMP address lines. PLIB_PMP_AddressSet Sets the current address of the PMP module to the specified address. PLIB_PMP_ChipSelectFunctionSelect Defines the functionality of the pins intended to be used as Chip Select. PLIB_PMP_ChipSelectXDisable Configures the Chip Select. PLIB_PMP_ChipSelectXEnable Configures the Chip Select. PLIB_PMP_ChipSelectXIsActive Gets the current status of the specified Chip Select. PLIB_PMP_ChipSelectXPolaritySelect Sets the specified Chip Select polarity. PLIB_PMP_DataSizeSelect Enables data transfer size for the PMP module. PLIB_PMP_Disable Disables the specific PMP module. PLIB_PMP_DualBufferDisable Disables the specific PMP module. PLIB_PMP_DualBufferEnable Enables PMP dual Read/Write buffer. PLIB_PMP_DualBufferIsEnabled Checks whether or not the PMP module is enabled. PLIB_PMP_DualModeMasterReceive Receives the data in the Master Dual mode. PLIB_PMP_DualModeMasterSend Sends the specified data in Dual Master mode. PLIB_PMP_DualModeReadAddressGet Gets the current read address of the PMP module. PLIB_PMP_DualModeReadAddressSet Sets the address to be written in Dual mode. PLIB_PMP_DualModeWriteAddressGet Gets the current write address of the PMP module. PLIB_PMP_DualModeWriteAddressSet Sets the address to be written in Dual mode. PLIB_PMP_Enable Enables the specific PMP module. PLIB_PMP_ExistsAddressControl Identifies whether the AddressControl feature exists on the PMP module. PLIB_PMP_ExistsAddressLatchPolarity Identifies whether the AddressLatchPolarity feature exists on the PMP module. PLIB_PMP_ExistsAddressLatchStrobePortControl Identifies whether the AddressLatchStrobePortControl feature exists on the PMP module. PLIB_PMP_ExistsAddressPortPinControl Identifies whether the AddressPortPinControl feature exists on the PMP module. PLIB_PMP_ExistsBufferOverFlow Identifies whether the BufferOverFlow feature exists on the PMP module. PLIB_PMP_ExistsBufferRead Identifies whether the BufferRead feature exists on the PMP module. PLIB_PMP_ExistsBufferType Identifies whether the BufferType feature exists on the PMP module. PLIB_PMP_ExistsBufferUnderFlow Identifies whether the BufferUnderFlow feature exists on the PMP module. PLIB_PMP_ExistsBufferWrite Identifies whether the BufferWrite feature exists on the PMP module. PLIB_PMP_ExistsBusyStatus Identifies whether the BusyStatus feature exists on the PMP module. PLIB_PMP_ExistsChipSelectEnable Identifies whether the ChipSelectEnable feature exists on the PMP module. PLIB_PMP_ExistsChipSelectoperation Identifies whether the ChipSelectoperation feature exists on the PMP module. PLIB_PMP_ExistsChipXPolarity Identifies whether the ChipXPolarity feature exists on the PMP module. PLIB_PMP_ExistsCSXActiveStatus Identifies whether the CSXActiveStatus feature exists on the PMP module. PLIB_PMP_ExistsDataHoldWaitStates Identifies whether the DataHoldWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataSetUpWaitStates Identifies whether the DataSetUpWaitStates feature exists on the PMP module. Peripheral Libraries Help PMP Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1497 PLIB_PMP_ExistsDataStrobeWaitStates Identifies whether the DataStrobeWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataTransferSize Identifies whether the DataTransferSize feature exists on the PMP module. PLIB_PMP_ExistsDualBufferControl Identifies whether the DualBufferControl feature exists on the PMP module. PLIB_PMP_ExistsDualModeMasterRXTX Identifies whether the DualModeMasterRXTX feature exists on the PMP module. PLIB_PMP_ExistsDualModeReadAddressControl Identifies whether the DualModeReadAddressControl feature exists on the PMP module. PLIB_PMP_ExistsDualModeWriteAddressControl Identifies whether the DualModeWriteAddressControl feature exists on the PMP module. PLIB_PMP_ExistsEnableControl Identifies whether the EnableControl feature exists on the PMP module. PLIB_PMP_ExistsIncrementMode Identifies whether the IncrementMode feature exists on the PMP module. PLIB_PMP_ExistsInputBufferFull Identifies whether the InputBufferFull feature exists on the PMP module. PLIB_PMP_ExistsInputBufferXStatus Identifies whether the InputBufferXStatus feature exists on the PMP module. PLIB_PMP_ExistsInterruptMode Identifies whether the InterruptMode feature exists on the PMP module. PLIB_PMP_ExistsMasterRXTX Identifies whether the MasterRXTX feature exists on the PMP module. PLIB_PMP_ExistsMUXModeSelect Identifies whether the MUXModeSelect feature exists on the PMP module. PLIB_PMP_ExistsOperationMode Identifies whether the OperationMode feature exists on the PMP module. PLIB_PMP_ExistsOutPutBufferEmpty Identifies whether the OutPutBufferEmpty feature exists on the PMP module. PLIB_PMP_ExistsOutputBufferXStatus Identifies whether the OutputBufferXStatus feature exists on the PMP module. PLIB_PMP_ExistsReadChipSelectEnable Identifies whether the ReadChipSelectEnable feature exists on the PMP module. PLIB_PMP_ExistsReadWritePolarity Identifies whether the ReadWritePolarity feature exists on the PMP module. PLIB_PMP_ExistsReadWriteStrobePortControl Identifies whether the ReadWriteStrobePortControl feature exists on the PMP module. PLIB_PMP_ExistsSlaveRX Identifies whether the SlaveRX feature exists on the PMP module. PLIB_PMP_ExistsSlaveTX Identifies whether the SlaveTX feature exists on the PMP module. PLIB_PMP_ExistsStartReadControl Identifies whether the StartReadControl feature exists on the PMP module. PLIB_PMP_ExistsStopInIdleControl Identifies whether the StopInIdleControl feature exists on the PMP module. PLIB_PMP_ExistsWriteChipSelectEnable Identifies whether the WriteChipSelectEnable feature exists on the PMP module. PLIB_PMP_ExistsWriteEnablePolarity Identifies whether the WriteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsWriteEnablePortControl Identifies whether the WriteEnablePortControl feature exists on the PMP module. PLIB_PMP_InputBuffersAreFull Gets the state of the input buffers. PLIB_PMP_InputBufferTypeSelect Selects the input buffer based on the input passed. PLIB_PMP_InputBufferXByteReceive Data to be received in Byte mode. PLIB_PMP_InputBufferXIsFull Gets the state of the identified input buffer. PLIB_PMP_InputOverflowClear Clears a PMP Overflow error. PLIB_PMP_InputOverflowHasOccurred Identifies if there was a receiver overflow error. PLIB_PMP_InterruptModeGet Gets the current configured interrupt mode being used with the PMP module. PLIB_PMP_InterruptModeSelect Configures the interrupt request mode being used with the PMP module. PLIB_PMP_IsDataReceived Checks and returns if the data has been received in the specified buffer in Slave mode. PLIB_PMP_IsDataTransmitted Checks and returns if the data has been transmitted from the specified buffer in Slave mode. PLIB_PMP_IsEnabled Checks whether or not the PMP module is enabled. PLIB_PMP_MasterReceive Receives the data in Master mode. PLIB_PMP_MasterSend Sends the specified data in Master mode. PLIB_PMP_MultiplexModeGet Gets the current multiplexing mode configured between the address and data of the PMP module. PLIB_PMP_MultiplexModeSelect Configures the multiplexing between the address and data of the PMP module. PLIB_PMP_OperationModeGet Gets the current operation mode of the PMP module. PLIB_PMP_OperationModeSelect Configures the operation mode of the PMP module. PLIB_PMP_OutputBuffersAreEmpty Gets the state of the output buffers. PLIB_PMP_OutputBufferXByteSend Data to be transmitted in Byte mode. PLIB_PMP_OutputBufferXIsEmpty Gets the state of the input buffer. PLIB_PMP_OutputUnderflowClear Clears a PMP output underflow error. Peripheral Libraries Help PMP Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1498 PLIB_PMP_OutputUnderflowHasOccurred Identifies if there was an output buffer sent out with no data. PLIB_PMP_PortIsBusy Identifies if the (Master mode) PMP port is busy. PLIB_PMP_ReadChipSelectXDisable Configures the Read Chip Select. PLIB_PMP_ReadChipSelectXEnable Configures the Read Chip Select. PLIB_PMP_ReadCycleIsStarted Checks whether or not the read cycle on PMP bus is enabled. PLIB_PMP_ReadCycleStart Starts a read cycle on the PMP bus. PLIB_PMP_ReadWriteStrobePolaritySelect Sets the polarity of the read strobe. PLIB_PMP_ReadWriteStrobePortDisable Disables the PMP module read strobe port. PLIB_PMP_ReadWriteStrobePortEnable Enables the PMP module read strobe port. PLIB_PMP_SlaveReceive Receives the data in Slave mode. PLIB_PMP_SlaveSend Sends the specified data in Slave mode. PLIB_PMP_StopInIdleDisable Enables the PMP module to continue operation in Idle mode. PLIB_PMP_StopInIdleEnable Discontinues PMP module operation when the device enters Idle mode. PLIB_PMP_WaitStatesDataHoldSelect Configures the data hold states (after data transfer) needed to be used with the PMP module. PLIB_PMP_WaitStatesDataSetUpSelect Configures the data wait states (before the data transfer) needed to be used with the PMP module. PLIB_PMP_WaitStatesStrobeSelect Configures the strobe wait states (during the data transfer) needed to be used with the PMP module. PLIB_PMP_WriteChipSelectXDisable Configures the Write Chip Select. PLIB_PMP_WriteChipSelectXEnable Configures the Write Chip Select. PLIB_PMP_WriteEnableStrobePolaritySelect Sets the polarity of the write enable strobe. PLIB_PMP_WriteEnableStrobePortDisable Disables the PMP module write strobe port. PLIB_PMP_WriteEnableStrobePortEnable Enables the PMP module write strobe port. Description This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the PMP Peripheral Library. File Name plib_pmp.h Company Microchip Technology Inc. plib_pmp_help.h Parallel Master Port (PMP) Peripheral Library Help Header. Enumerations Name Description PMP_ACK_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_ADDRESS_HOLD_LATCH_WAIT_STATES PMP hold after address latch strobe wait states configuration. PMP_ADDRESS_LATCH Address Latch Strobe configuration. PMP_ADDRESS_LATCH_WAIT_STATES PMP address latch strobe wait states configuration. PMP_ADDRESS_PORT Defines the different address lines that are available for configuration. PMP_ALTERNATE_MASTER_WAIT_STATES PMP alternate master wait states. PMP_CHIP_SELECT PMP Chip Select data type. PMP_CHIPSELECT_FUNCTION Defines different functions available for the Chip Select lines multiplexed with address lines. PMP_DATA_HOLD_STATES PMP Data Hold after strobe wait state. PMP_DATA_LENGTH Possible data lengths handled by the PMP module. PMP_DATA_SIZE PMP data size. PMP_DATA_WAIT_STATES PMP data setup time configuration. PMP_INCREMENT_MODE PMP address incrementing configuration. PMP_INPUT_BUFFER_TYPE PMP Input Buffers type. PMP_INTERRUPT_MODE PMP interrupt request mode data type. Peripheral Libraries Help PMP Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1499 PMP_MASTER_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_MODULE_ID Possible instances of the PMP module. PMP_MUX_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_OPERATION_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_PMBE_PORT Defines the available Byte Enable ports. PMP_POLARITY_LEVEL Possible polarity levels for the PMP pins. PMP_STROBE_WAIT_STATES PMP strobe signal wait time configuration. Description PMP/EPMP Peripheral Library Help Header This header file contains the data types and constants that make up the interface to the PMP Peripheral Library. File Name plib_pmp_help.h Company Microchip Technology Inc. Peripheral Libraries Help PMP Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1500 Prefetch Cache Peripheral Library This section describes the Prefetch Cache Peripheral Library. Introduction This library provides a low-level abstraction of the Prefetch Cache module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The Prefetch Cache module increases system performance for most applications by: • Predictive prefetching of instructions ahead of the current program counter, hiding the access time of the Flash memory • Instruction and data caching The program Flash memory (PFM) contains a Prefetch module and a number of cache lines, each containing four words. Some of the cache lines may be allocated to data or peripherals. Each cache line has an associated tag. The tag contains the address of the data in the cache line, and a number of status bits. The number of cache lines and number and type of status bits may vary between devices. Refer to your specific device data sheet for details. Using the Library This topic describes the basic architecture of the Prefetch Cache Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_pcache.h The interface to the Prefetch Cache Peripheral Library is defined in the plib_pcache.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Prefetch Cache Peripheral Library must include peripheral.h. Library File: The Prefetch Cache Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the Prefetch Cache module on Microchip family microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model The Prefetch Cache module is a performance enhancing module included in some microcontrollers. When running at high clock rates, wait states must be inserted into program Flash memory (PFM) read transactions to meet the access time of the PFM. Wait states can be hidden to the core Peripheral Libraries Help Prefetch Cache Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1501 by prefetching and storing instructions in a temporary holding area that the CPU can access quickly. There are two main functions that the Prefetch Cache module performs: Caching instructions when they are accessed, and prefetching instructions from the PFM before they are needed. The cache holds a subset of the cacheable memory in temporary holding spaces known as cache lines. Each cache line has a tag describing what it is currently holding, and the address where it is mapped. Normally, the cache lines just hold a copy of what is currently in memory to make data available to the CPU without wait states. CPU-requested data may or may not be in the cache. A cache-miss occurs if the CPU requests cacheable data that is not in the cache. In this case, a read is performed to the PFM at the correct address, the data is supplied to the cache and to the CPU. A cache-hit occurs if the cache contains the data that the CPU requests. In the case of a cache-hit, data is supplied to the CPU without wait states. The second main function of the Prefetch Cache module is to prefetch CPU instructions. The module calculates the address of the next cache line and performs a read of the PFM to get the next cache line. This line is placed into a prefetch cache buffer in anticipation of executing straight-line code. Cache Control This library provides a set of functions to control the behavior of the overall Cache Module. Those functions include: • Setting or reading the number of clock wait cycles • Setting or reading the number of cache lines allocated to data • Controlling which cache lines are invalidated on a PFM write cycle Cache Line Operations This library provides a set of functions to read, write and control the behavior of individual Cache Lines. Operations on individual Cache Lines are performed using a two-step process: 1. Select the individual cache line with PLIB_PCACHE_CacheLineSelect. 2. Perform the required cache line operation using any of the routines in the Cache Line Operations section. The operations available are: • Set the cache line to data or instruction type • Mark the cache line as valid or invalid • Lock or unlock the cache line • Read or write the Flash type (boot or program) associated with the cache line • Read or write the address associated with the cache line • Read or write the mask field to force a match between the cache line and multiple physical addresses • Read or write any individual word in the cache line data array Once the operation is performed, the cache line remains selected until PLIB_PCACHE_CacheLineDeselect is performed. Only one cache line can be selected at a time. Cache Status The cache maintains a count of hits and misses for profiling purposes. The cache hit counter increments each time the processor issues an instruction fetch or load that hits the prefetch cache from a cacheable region. Similarly, the cache miss counter increments each time the processor issues an instruction fetch or load that misses the prefetch cache from a cacheable region. Accesses to non-cacheable regions do not affect the counters. These values can be read or written using the Cache Status routines. The cache uses a Least Recently Used (LRU) algorithm to replace cache lines on a miss. The specific algorithm may vary between devices. In some devices, the state of the LRU algorithm encoding bits can be read with PLIB_PCACHE_LeastRecentlyUsedStateRead. Prefetch Control Predictive prefetch is controlled by the Prefetch Control routines. Devices with no L1 CPU cache can prefetch from cacheable or non-cacheable regions or both. Devices with L1 CPU cache can prefetch from any address, CPU instructions or CPU instructions and data. Predictive prefetch Peripheral Libraries Help Prefetch Cache Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1502 can be disabled for either type of device. Prefetch Status The Prefetch Cache module maintains a count of prefetch aborts for profiling purposes. The prefetch abort counter is incremented each time a prefetch is aborted due to a non-sequential instruction fetch, load or store. This value can be read or written using the Prefetch Status routines. Flash ECC On some devices, the Flash ECC module has the ability to detect single and double bit errors on PFM reads. When a single bit error is detected, the error is corrected and the Single Error Correction (SEC) counter is decremented. When the SEC counter reaches zero, an interrupt is generated to the CPU. The user has the ability to enable or disable the SEC interrupt. It is disabled by default. The user may set the SEC counter value at any time. The maximum counter value may be device-specific and is defined for each processor by the PLIB_PCACHE_MAX_SEC_COUNT constant. When a double bit error is detected, the device will set the DED status to true and generate a bus exception to the initiator. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Prefetch Cache module. Library Interface Section Description Cache Control Functions Provides Cache Control interface routines. Cache Line Functions Provides Cache Line interface routines. Cache Status Functions Provides Cache Status interface routines. Prefetch Control Functions Provides Prefetch Control interface routines. Prefetch Status Functions Provides Prefetch Status interface routines. Flash ECC Functions Provides Flash ECC interface routines. Feature Existence Functions Provides interface routines that determine whether or not certain features are available. How the Library Works Provides information on how the library works. Description This library can be used to optimize the performance of the processor while executing out of cacheable program Flash memory. This is done by implementing the following: • Instruction caching • Data caching • Cache line control • Predictive prefetching • ECC detection Arrays The cache consists of two arrays: tag and data. The data array contains a number of lines of program instructions or data words. The word size is the same as the processor data width. The tag array contains a number of corresponding fields, each containing: • Mask – address mask value • Tag – tag address to match against • Valid – indicates whether the data in the cache line is valid or not • Lock – indicates the line is locked to hold its contents • Type – instruction, data or peripheral Note: Not all Tag fields are available on all devices. The number of cache lines may vary between devices. Refer to the specific device data sheet for details. Example Cache Line Peripheral Libraries Help Prefetch Cache Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1503 Operations This library allows the programmer to perform various operations on the cache tag and data arrays: • Enable/Disable • Set the Wait state • Read, write, lock, invalidate Note: Not all operations are available on all devices. Refer to the specific device data sheet for details. Cache Control Operations Cache Wait States When operating at high clock rates, the Prefetch Cache module must insert wait states into Program Flash Memory (PFM) read operations to meet PFM access time requirements. One Wait state is equivalent to one clock cycle delay. At reset, the Prefetch Cache Module is set to the maximum number of wait states for the device. The PFM read time can be optimized for the device by selecting the minimum number of wait states for the clock rate used. The number of wait states for a given clock frequency may vary between devices. Note: Refer to the specific device data sheet for details on how to calculate the optimum number of wait states for your device. Example: Setting the Number of PFM wait states based on the System Clock This example assumes one wait state for every 20 MHz of system clock. if (sysclk < 20000000) { PLIB_PCACHE_WaitStateSet(0); } else if (sysclk < 40000000) { PLIB_PCACHE_WaitStateSet(1); } ... Data Caching Some Prefetch Cache modules allow the user to allocate cache lines to data. This is to provide improved CPU access to constant data stored in PFM. By default, data caching is disabled. The Prefetch Cache Peripheral Library allows the user to set the number of cache lines allocated to data. The number of lines available may vary among devices. The available settings are provided by the device-dependent PLIB_PCACHE_DATA_ENABLE enumeration. Example: Allocating two Cache Lines to Data PLIB_PCACHE_DataCacheEnableSet(PLIB_PCACHE_DATA_2LINE); Cache Line Invalidating on PFM Write It is not possible to execute out of cache while programming the PFM. The PFM controller stalls the cache during the programming sequence. Therefore, user code that initiates a programming sequence should not be located in a cacheable address region. During program operation, the Prefetch Cache is flushed by invalidating some or all of the cache lines. To invalidate all of the cache lines on a PFM write operation, the function PLIB_PCACHE_InvalidateOnPFMProgramAll should be called prior to the PFM write. This will invalidate and unlock every cache line during the write operation. The cache tags and masks are also cleared for all lines. If PLIB_PCACHE_InvalidateOnPFMProgramUnlocked is called before the PFM write, only lines that are not locked will be forced invalid. By default, only unlocked cache lines are invalidated during a PFM write. Cache Line Operations Performing a cache line operation is a two-step process. Before calling a Cache Line operation function, the cache line must be selected and write-enabled. Once selected and write-enabled, any number of cache line operations may be performed on the selected line until the line is cleared or a different line is selected and write-enabled. Cache lines are selected and write-enabled using PLIB_PCACHE_CacheLineSelect. Cache lines are write-disabled using PLIB_PCACHE_CacheLineDeselect. The following example shows operations on two different cache lines. The code comments describe each operation. Example: Cache Line Operations uint32_t cacheLine[4] = {0x01234567, 0x12345678, 0x23456789, 0x34567890}; //Select Cache Line 4 PLIB_PCACHE_CacheLineSelect(4); //Invalidate Cache Line 4 Peripheral Libraries Help Prefetch Cache Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1504 PLIB_PCACHE_CacheLineInvalid(); //Select Cache Line 6 PLIB_PCACHE_CacheLineSelect(6); //Set Cache Line 6 to Data Type PLIB_PCACHE_CacheLineData(); //Write Data to Cache Line 6 for (i=0; i). Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1519 Description This function returns the current state of the cache tag mask for the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Remarks This function implements an operation of the CacheLineMask feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineMask in your application to to automatically determine whether this feature is available. Preconditions None. Example uint32_t mask; mask = PLIB_PCACHE_CacheLineMaskGet(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function uint32_t PLIB_PCACHE_CacheLineMaskGet( PCACHE_MODULE_ID index ) PLIB_PCACHE_CacheLineMaskSet Function Sets the cache tag mask to force a match on set bits on the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. File plib_pcache.h C void PLIB_PCACHE_CacheLineMaskSet(PCACHE_MODULE_ID index, uint32_t mask); Returns None. Description This function sets the cache tag mask to force a match on set bits on the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Remarks This function implements an operation of the CacheLineMask feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineMask in your application to to automatically determine whether this feature is available. Preconditions None. Example uint32_t mask = 0x0C0; PLIB_PCACHE_CacheLineMaskSet(PCACHE_ID_0, mask); Parameters Parameters Description index Identifier for the device instance to be configured mask Address mask (bits set to '1' will force a match; valid bits: <15:5>) Function void PLIB_PCACHE_CacheLineMaskSet( PCACHE_MODULE_ID index, uint32_t mask ) PLIB_PCACHE_CacheLineSelect Function Enables write access to the cache line specified by cache_line. Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1520 File plib_pcache.h C void PLIB_PCACHE_CacheLineSelect(PCACHE_MODULE_ID index, uint32_t cache_line); Returns None. Description This function enables write access to the cache line specified by cache_line. Remarks At reset, all cache lines are read-only. This function implements an operation of the CacheLineSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineSelect in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_CacheLineSelect(PCACHE_ID_0, 0); Parameters Parameters Description index Identifier for the device instance to be configured cache_line Specifies the cache line to enable write access Function void PLIB_PCACHE_CacheLineSelect( PCACHE_MODULE_ID index, uint32_t cache_line ) PLIB_PCACHE_CacheLineUnlock Function Unlocks cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. File plib_pcache.h C void PLIB_PCACHE_CacheLineUnlock(PCACHE_MODULE_ID index); Returns None. Description This function unlocks the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Remarks This function implements an operation of the CacheLineLock feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineLock in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_CacheLineUnlock(PCACHE_ID_0); Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1521 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_PCACHE_CacheLineUnlock( PCACHE_MODULE_ID index ) PLIB_PCACHE_CacheLineValid Function Validates cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. File plib_pcache.h C void PLIB_PCACHE_CacheLineValid(PCACHE_MODULE_ID index); Returns None. Description This function validates the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Remarks This function implements an operation of the CacheLineValid feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineValid in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_CacheLineValid(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_PCACHE_CacheLineValid( PCACHE_MODULE_ID index ) PLIB_PCACHE_WordRead Function Reads the word specified by word from cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. File plib_pcache.h C uint32_t PLIB_PCACHE_WordRead(PCACHE_MODULE_ID index, uint32_t word); Returns A 32-bit unsigned word from the cache data array. Description This function reads the word specified by word from the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Remarks This function implements an operation of the Word feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsWord in your application to to automatically determine whether this feature is available. Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1522 Preconditions None. Example uint32_t word; word = PLIB_PCACHE_WordRead(PCACHE_ID_0, 0); Parameters Parameters Description index Identifier for the device instance to be read word Location of the word in the data array to be read Function uint32_t PLIB_PCACHE_WordRead( PCACHE_MODULE_ID index, uint32_t word ) PLIB_PCACHE_WordWrite Function Writes the word (specified by word parameter) with data (specified by data parameter) to cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. File plib_pcache.h C void PLIB_PCACHE_WordWrite(PCACHE_MODULE_ID index, uint32_t word, uint32_t data); Returns None. Description This function writes the word (specified by word parameter) with data (specified by data parameter) to the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Remarks This function implements an operation of the Word feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsWord in your application to to automatically determine whether this feature is available. Preconditions None. Example uint32_t word = 0; uint32_t data = 0xDEADBEEF; PLIB_PCACHE_WordWrite(PCACHE_ID_0, word, data); Parameters Parameters Description index Identifier for the device instance to be written. word Location of the word in the data array to be written data 32-bit unsigned word to write to cache data array Function void PLIB_PCACHE_WordWrite( PCACHE_MODULE_ID index, uint32_t word, uint32_t data ) c) Cache Status Functions Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1523 PLIB_PCACHE_CacheHitRead Function Reads the number of cache hits. File plib_pcache.h C uint32_t PLIB_PCACHE_CacheHitRead(PCACHE_MODULE_ID index); Returns The number of cache hits. Description This function reads and returns the number of cache hits. Remarks This function implements an operation of the CacheHit feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheHit in your application to to automatically determine whether this feature is available. Preconditions None. Example uint32_t cache_hits; cache_hits = PLIB_PCACHE_CacheHitRead(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function uint32_t PLIB_PCACHE_CacheHitRead( PCACHE_MODULE_ID index ) PLIB_PCACHE_CacheHitWrite Function Sets the number of cache hits. File plib_pcache.h C void PLIB_PCACHE_CacheHitWrite(PCACHE_MODULE_ID index, uint32_t data); Returns None. Description This function sets the number of cache hits. Remarks This function implements an operation of the CacheHit feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheHit in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_CacheHitWrite(PCACHE_ID_0, 0xF00); Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1524 Parameters Parameters Description index Identifier for the device instance to be written data Number of cache hits to write Function void PLIB_PCACHE_CacheHitWrite( PCACHE_MODULE_ID index, uint32_t data ) PLIB_PCACHE_CacheMissRead Function Reads the number of cache misses. File plib_pcache.h C uint32_t PLIB_PCACHE_CacheMissRead(PCACHE_MODULE_ID index); Returns The number of cache misses. Description This function reads and returns the number of cache misses. Remarks This function implements an operation of the CacheMiss feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheMiss in your application to to automatically determine whether this feature is available. Preconditions None. Example uint32_t cache_misses; cache_misses = PLIB_PCACHE_CacheMissRead(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be read. Function uint32_t PLIB_PCACHE_CacheMissRead( PCACHE_MODULE_ID index ) PLIB_PCACHE_CacheMissWrite Function Sets the number of cache misses. File plib_pcache.h C void PLIB_PCACHE_CacheMissWrite(PCACHE_MODULE_ID index, uint32_t data); Returns None. Description This function sets the number of cache misses. Remarks This function implements an operation of the CacheMiss feature. This feature may not be available on all devices. Please refer to the specific Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1525 device data sheet to determine availability or use PLIB_RTCC_ExistsCacheMiss in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_CacheMissWrite(PCACHE_ID_0, 0xF00); Parameters Parameters Description index Identifier for the device instance to be written data Number of cache misses to write Function void PLIB_PCACHE_CacheMissWrite( PCACHE_MODULE_ID index, uint32_t data ) PLIB_PCACHE_LeastRecentlyUsedStateRead Function Reads the state of the cache Least Recently Used (LRU) encoding bits. File plib_pcache.h C uint32_t PLIB_PCACHE_LeastRecentlyUsedStateRead(PCACHE_MODULE_ID index); Returns The state of the LRU encoding bits represented as a 25-bit unsigned integer. Description This function reads the state of the cache LRU encoding bits. Remarks This function implements an operation of the LeastRecentlyUsedState feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsLeastRecentlyUsedState in your application to to automatically determine whether this feature is available. Preconditions None. Example uint32_t lru_state; lru_state = PLIB_PCACHE_LeastRecentlyUsedStateRead(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be read. Function uint32_t PLIB_PCACHE_LeastRecentlyUsedStateRead( PCACHE_MODULE_ID index ) d) Prefetch Control Functions PLIB_PCACHE_PrefetchEnableGet Function Gets the predictive Prefetch state for the Prefetch Cache module. File plib_pcache.h Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1526 C PLIB_PCACHE_PREFETCH_ENABLE PLIB_PCACHE_PrefetchEnableGet(PCACHE_MODULE_ID index); Returns PLIB_PCACHE_PREFETCH_ENABLE Description This function gets the predictive Prefetch state for the Prefetch Cache module. Remarks At reset, the Prefetch Cache module is disabled and this function will return PLIB_PCACHE_DISABLE. This function implements an operation of the PrefetchEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsPrefetchEnable in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_PREFETCH_ENABLE region; region = PLIB_PCACHE_PrefetchEnableGet(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function PLIB_PCACHE_PREFETCH_ENABLE PLIB_PCACHE_PrefetchEnableGet( PCACHE_MODULE_ID index ) PLIB_PCACHE_PrefetchEnableSet Function Sets the predictive Prefetch state for the Prefetch Cache module. File plib_pcache.h C void PLIB_PCACHE_PrefetchEnableSet(PCACHE_MODULE_ID index, PLIB_PCACHE_PREFETCH_ENABLE region); Returns None. Description This function sets the predictive Prefetch state for the Prefetch Cache module. Remarks At reset, the Prefetch Cache module is disabled. This function implements an operation of the PrefetchEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsPrefetchEnable in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_PrefetchEnableSet(PCACHE_ID_0, PLIB_PCACHE_PREFETCH_ENABLE_ALL); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1527 region PLIB_PCACHE_PREFETCH_ENABLE Function void PLIB_PCACHE_PrefetchEnableSet( PCACHE_MODULE_ID index, PLIB_PCACHE_PREFETCH_ENABLE region ) e) Prefetch Status Functions PLIB_PCACHE_PrefetchAbortRead Function Reads the number of prefetch aborts. File plib_pcache.h C uint32_t PLIB_PCACHE_PrefetchAbortRead(PCACHE_MODULE_ID index); Returns The number of prefetch aborts. Description This function reads and returns the number of prefetch aborts. Remarks This function implements an operation of the PrefetchAbort feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsPrefetchAbort in your application to to automatically determine whether this feature is available. Preconditions None. Example uint32_t pfabt; pfabt = PLIB_PCACHE_PrefetchAbortRead(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function uint32_t PLIB_PCACHE_PrefetchAbortRead( PCACHE_MODULE_ID index ) PLIB_PCACHE_PrefetchAbortWrite Function Sets the number of prefetch aborts. File plib_pcache.h C void PLIB_PCACHE_PrefetchAbortWrite(PCACHE_MODULE_ID index, uint32_t data); Returns None. Description This function Sets the number of prefetch aborts. Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1528 Remarks This function implements an operation of the PrefetchAbort feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsPrefetchAbort in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_PrefetchAbortWrite(PCACHE_ID_0, 0xF00); Parameters Parameters Description index Identifier for the device instance to be written data Number of prefetch aborts Function void PLIB_PCACHE_PrefetchAbortWrite( PCACHE_MODULE_ID index, uint32_t data ) f) Flash ECC Functions PLIB_PCACHE_FlashDEDStatusClear Function Clears a bus exception caused by a double-bit error. File plib_pcache.h C void PLIB_PCACHE_FlashDEDStatusClear(PCACHE_MODULE_ID index); Returns None. Description This function clears a bus exception caused by a double-bit error. Remarks The DED status is set by hardware. This function implements an operation of the FlashDEDStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashDEDStatus in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_FlashDEDStatusClear(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be cleared Function void PLIB_PCACHE_FlashDEDStatusClear( PCACHE_MODULE_ID index ) PLIB_PCACHE_FlashDEDStatusGet Function Determines if a bus exception was caused by a double-bit error. Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1529 File plib_pcache.h C bool PLIB_PCACHE_FlashDEDStatusGet(PCACHE_MODULE_ID index); Returns • true - A double-bit error was detected • false - A double-bit error was not detected Description This function determines if a bus exception was caused by a double-bit error. Remarks The Double-bit Error Detected (DED) status is set by hardware. This function implements an operation of the FlashDEDStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashDEDStatus in your application to to automatically determine whether this feature is available. Preconditions None. Example bool dedStatus; dedStatus = PLIB_PCACHE_FlashDEDStatusGet(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Function bool PLIB_PCACHE_FlashDEDStatusGet( PCACHE_MODULE_ID index ) PLIB_PCACHE_FlashSECCountGet Function Returns the current value of the Flash SEC counter. File plib_pcache.h C uint8_t PLIB_PCACHE_FlashSECCountGet(PCACHE_MODULE_ID index); Returns • count - Number of SEC events to occur before the SEC status is set to true Description This function returns the current value of the Flash SEC counter. Remarks This function implements an operation of the FlashSECCount feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECCount in your application to to automatically determine whether this feature is available. Preconditions None. Example uint8_t count; count = PLIB_PCACHE_FlashSECCountGet(PCACHE_ID_0); Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1530 Parameters Parameters Description index Identifier for the device instance to be read Function uint8_t PLIB_PCACHE_FlashSECCountGet( PCACHE_MODULE_ID index ) PLIB_PCACHE_FlashSECCountSet Function Sets the number of single-bit error corrections that must occur before the SEC status is set to true. File plib_pcache.h C void PLIB_PCACHE_FlashSECCountSet(PCACHE_MODULE_ID index, uint8_t count); Returns None. Description This function sets the number of single-bit error corrections that must occur before the SEC status is set to true. Remarks This function implements an operation of the FlashSECCount feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECCount in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_FlashSECCountSet(PCACHE_ID_0, 255); Parameters Parameters Description index Identifier for the device instance to be configured count Number of SEC events to occur before SEC status is set to true Function void PLIB_PCACHE_FlashSECCountSet( PCACHE_MODULE_ID index, uint8_t count ) PLIB_PCACHE_FlashSECIntDisable Function Disables an interrupt on SEC. File plib_pcache.h C void PLIB_PCACHE_FlashSECIntDisable(PCACHE_MODULE_ID index); Returns None. Description This function disables an interrupt on SEC. Remarks At reset the SEC interrupt is disabled. Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1531 This function implements an operation of the FlashSECInt feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECInt in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_FlashSECIntDisable(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be disabled Function void PLIB_PCACHE_FlashSECIntDisable( PCACHE_MODULE_ID index ) PLIB_PCACHE_FlashSECIntEnable Function Enables an interrupt on SEC. File plib_pcache.h C void PLIB_PCACHE_FlashSECIntEnable(PCACHE_MODULE_ID index); Returns None Description This function enables an interrupt on SEC. Remarks At reset the SEC interrupt is disabled. This function implements an operation of the FlashSECInt feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECInt in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_FlashSECIntEnable(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be enabled Function void PLIB_PCACHE_FlashSECIntEnable( PCACHE_MODULE_ID index ) PLIB_PCACHE_FlashSECStatusClear Function Sets the single-bit error corrected status to false. File plib_pcache.h C void PLIB_PCACHE_FlashSECStatusClear(PCACHE_MODULE_ID index); Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1532 Returns None. Description This function sets the single-bit error corrected status to false. Remarks The SEC status must be cleared in response to a Prefetch Cache SEC interrupt. This function implements an operation of the FlashSECStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECStatus in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_FlashSECStatusClear(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be cleared Function void PLIB_PCACHE_FlashSECStatusClear( PCACHE_MODULE_ID index ) PLIB_PCACHE_FlashSECStatusGet Function Determines if a SEC event triggered a Prefetch Cache interrupt. File plib_pcache.h C bool PLIB_PCACHE_FlashSECStatusGet(PCACHE_MODULE_ID index); Returns • true - A single-bit error was corrected • false - A double-bit error was not corrected Description This function determines if a SEC event triggered a Prefetch Cache interrupt. Remarks The SEC bit is set when a single-bit error is corrected and the SEC counter is zero. If the Flash SEC interrupt is enabled, an error event is reported to the CPU by a Prefetch Cache interrupt event. This function implements an operation of the FlashSECStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECStatus in your application to to automatically determine whether this feature is available. Preconditions None. Example bool secStatus; secStatus = PLIB_PCACHE_FlashSECStatusGet(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be read Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1533 Function bool PLIB_PCACHE_FlashSECStatusGet( PCACHE_MODULE_ID index ) PLIB_PCACHE_FlashSECStatusSet Function Sets the single-bit error corrected status to true. File plib_pcache.h C void PLIB_PCACHE_FlashSECStatusSet(PCACHE_MODULE_ID index); Returns None. Description This function sets the single-bit error corrected status to true. Remarks This function is provided for code testing and debug purposes. Setting the SEC status while the SEC count is zero and the SEC interrupt is enabled will trigger a Prefetch Cache interrupt to the CPU. This function implements an operation of the FlashSECStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECStatus in your application to to automatically determine whether this feature is available. Preconditions None. Example PLIB_PCACHE_FlashSECStatusSet(PCACHE_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_PCACHE_FlashSECStatusSet( PCACHE_MODULE_ID index ) g) Feature Existence Functions PLIB_PCACHE_ExistsCacheHit Function Identifies that the CacheHit feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsCacheHit(PCACHE_MODULE_ID index); Returns • true - The CacheHit feature is supported on the device • false - The CacheHit feature is not supported on the device Description This interface identifies that the CacheHit feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheHitRead Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1534 • PLIB_PCACHE_CacheHitWrite Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsCacheHit( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsCacheLine Function Identifies that the CacheLineSelect feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsCacheLine(PCACHE_MODULE_ID index); Returns • true - The CacheLineSelect feature is supported on the device • false - The CacheLineSelect feature is not supported on the device Description This interface identifies that the CacheLineSelect feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineSelect • PLIB_PCACHE_CacheLineDeselect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsCacheLine( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsCacheLineAddr Function Identifies that the CacheLineAddr feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsCacheLineAddr(PCACHE_MODULE_ID index); Returns • true - The CacheLineAddr feature is supported on the device • false - The CacheLineAddr feature is not supported on the device Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1535 Description This interface identifies that the CacheLineAddr feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineAddrSet • PLIB_PCACHE_CacheLineAddrGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsCacheLineAddr( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsCacheLineFlashType Function Identifies that the CacheLineFlashType feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsCacheLineFlashType(PCACHE_MODULE_ID index); Returns • true - The CacheLineFlashType feature is supported on the device • false - The CacheLineFlashType feature is not supported on the device Description This interface identifies that the CacheLineFlashType feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineFlashTypeBoot • PLIB_PCACHE_CacheLineFlashTypeInst • PLIB_PCACHE_CacheLineFlashTypeIsInst Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsCacheLineFlashType( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsCacheLineLock Function Identifies that the CacheLineLock feature exists on the Prefetch Cache module. File plib_pcache.h Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1536 C bool PLIB_PCACHE_ExistsCacheLineLock(PCACHE_MODULE_ID index); Returns • true - The CacheLineLock feature is supported on the device • false - The CacheLineLock feature is not supported on the device Description This interface identifies that the CacheLineLock feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineLock • PLIB_PCACHE_CacheLineUnlock • PLIB_PCACHE_CacheLineIsLocked Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsCacheLineLock( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsCacheLineMask Function Identifies that the CacheLineMask feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsCacheLineMask(PCACHE_MODULE_ID index); Returns • true - The CacheLineMask feature is supported on the device • false - The CacheLineMask feature is not supported on the device Description This interface identifies that the CacheLineMask feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineMaskSet • PLIB_PCACHE_CacheLineMaskGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsCacheLineMask( PCACHE_MODULE_ID index ) Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1537 PLIB_PCACHE_ExistsCacheLineType Function Identifies that the CacheLineType feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsCacheLineType(PCACHE_MODULE_ID index); Returns • true - The CacheLineType feature is supported on the device • false - The CacheLineType feature is not supported on the device Description This interface identifies that the CacheLineType feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineData • PLIB_PCACHE_CacheLineInst • PLIB_PCACHE_CacheLineIsInst Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsCacheLineType( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsCacheLineValid Function Identifies that the CacheLineValid feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsCacheLineValid(PCACHE_MODULE_ID index); Returns • true - The CacheLineValid feature is supported on the device • false - The CacheLineValid feature is not supported on the device Description This interface identifies that the CacheLineValid feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineValid • PLIB_PCACHE_CacheLineInvalid • PLIB_PCACHE_CacheLineIsValid Remarks None. Preconditions None. Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1538 Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsCacheLineValid( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsCacheMiss Function Identifies that the CacheMiss feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsCacheMiss(PCACHE_MODULE_ID index); Returns • true - The CacheMiss feature is supported on the device • false - The CacheMiss feature is not supported on the device Description This interface identifies that the CacheMiss feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheMissRead • PLIB_PCACHE_CacheMissWrite Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsCacheMiss( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsDataCacheEnable Function Identifies that the DataCacheEnable feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsDataCacheEnable(PCACHE_MODULE_ID index); Returns • true - The DataCacheEnable feature is supported on the device • false - The DataCacheEnable feature is not supported on the device Description This interface identifies that the DataCacheEnable feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_DataCacheEnableSet • PLIB_PCACHE_DataCacheEnableGet Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1539 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsDataCacheEnable( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsFlashDEDStatus Function Identifies that the FlashDEDStatus feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsFlashDEDStatus(PCACHE_MODULE_ID index); Returns • true - The FlashDEDStatus feature is supported on the device • false - The FlashDEDStatus feature is not supported on the device Description This interface identifies that the FlashDEDStatus feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_FlashDEDStatusGet • PLIB_PCACHE_FlashDEDStatusClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsFlashDEDStatus( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsFlashSECCount Function Identifies that the FlashSECCount feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsFlashSECCount(PCACHE_MODULE_ID index); Returns • true - The FlashSECCount feature is supported on the device • false - The FlashSECCount feature is not supported on the device Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1540 Description This interface identifies that the FlashSECCount feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_FlashSECCountSet • PLIB_PCACHE_FlashSECCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsFlashSECCount( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsFlashSECInt Function Identifies that the FlashSECInt feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsFlashSECInt(PCACHE_MODULE_ID index); Returns • true - The FlashSECInt feature is supported on the device • false - The FlashSECInt feature is not supported on the device Description This interface identifies that the FlashSECInt feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_FlashSECIntEnable • PLIB_PCACHE_FlashSECIntDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsFlashSECInt( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsFlashSECStatus Function Identifies that the FlashSECStatus feature exists on the Prefetch Cache module. File plib_pcache.h Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1541 C bool PLIB_PCACHE_ExistsFlashSECStatus(PCACHE_MODULE_ID index); Returns • true - The FlashSECStatus feature is supported on the device • false - The FlashSECStatus feature is not supported on the device Description This interface identifies that the FlashSECStatus feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_FlashSECStatusGet • PLIB_PCACHE_FlashSECStatusSet • PLIB_PCACHE_FlashSECStatusClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsFlashSECStatus( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsInvalidateOnPFMProgram Function Identifies that the InvalidateOnPFMProgram feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsInvalidateOnPFMProgram(PCACHE_MODULE_ID index); Returns • true - The InvalidateOnPFMProgram feature is supported on the device • false - The InvalidateOnPFMProgram feature is not supported on the device Description This interface identifies that the InvalidateOnPFMProgram feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_InvalidateOnPFMProgramAll • PLIB_PCACHE_InvalidateOnPFMProgramUnlocked Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsInvalidateOnPFMProgram( PCACHE_MODULE_ID index ) Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1542 PLIB_PCACHE_ExistsLeastRecentlyUsedState Function Identifies that the LeastRecentlyUsedState feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsLeastRecentlyUsedState(PCACHE_MODULE_ID index); Returns • true - The LeastRecentlyUsedState feature is supported on the device • false - The LeastRecentlyUsedState feature is not supported on the device Description This interface identifies that the LeastRecentlyUsedState feature is available on the Prefetch Cache module. When this interface returns true, this function is supported on the device: • PLIB_PCACHE_LeastRecentlyUsedStateRead Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsLeastRecentlyUsedState( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsPrefetchAbort Function Identifies that the PrefetchAbort feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsPrefetchAbort(PCACHE_MODULE_ID index); Returns • true - The PrefetchAbort feature is supported on the device • false - The PrefetchAbort feature is not supported on the device Description This interface identifies that the PrefetchAbort feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_PrefetchAbortRead • PLIB_PCACHE_PrefetchAbortWrite Remarks None. Preconditions None. Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1543 Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsPrefetchAbort( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsPrefetchEnable Function Identifies that the PrefetchEnable feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsPrefetchEnable(PCACHE_MODULE_ID index); Returns • true - The PrefetchEnable feature is supported on the device • false - The PrefetchEnable feature is not supported on the device Description This interface identifies that the PrefetchEnable feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_PrefetchEnableSet • PLIB_PCACHE_PrefetchEnableGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsPrefetchEnable( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsWaitState Function Identifies that the WaitState feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsWaitState(PCACHE_MODULE_ID index); Returns • true - The WaitState feature is supported on the device • false - The WaitState feature is not supported on the device Description This interface identifies that the WaitState feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_WaitStateSet • PLIB_PCACHE_WaitStateGet Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1544 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsWaitState( PCACHE_MODULE_ID index ) PLIB_PCACHE_ExistsWord Function Identifies that the Word feature exists on the Prefetch Cache module. File plib_pcache.h C bool PLIB_PCACHE_ExistsWord(PCACHE_MODULE_ID index); Returns • true - The Word feature is supported on the device • false - The Word feature is not supported on the device Description This interface identifies that the Word feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_WordRead • PLIB_PCACHE_WordWrite Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PCACHE_ExistsWord( PCACHE_MODULE_ID index ) h) Data Types and Constants PLIB_PCACHE_MAX_SEC_COUNT Macro Defines the maximum value for single bit error counter. File help_plib_pcache.h C #define PLIB_PCACHE_MAX_SEC_COUNT 255 Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1545 Description Maximum Value for Single Bit Error Counter This definition specifies the maximum value for single bit error counter. Remarks The actual maximum value of the SEC counter is processor specific and is defined in the processor-specific header files (see processor.h). PLIB_PCACHE_NUM_LINES Macro Defines the number of available Prefetch Cache Lines. File help_plib_pcache.h C #define PLIB_PCACHE_NUM_LINES Description Number of Cache Lines This definition specifies the number of Prefetch Cache Lines available. Remarks The actual number of cache lines is processor specific and is defined in the processor-specific header files (see processor.h). PLIB_PCACHE_NUM_WORDS_PER_LINE Macro Defines the number of Words per Prefetch Cache Line. File help_plib_pcache.h C #define PLIB_PCACHE_NUM_WORDS_PER_LINE Description Number of Words per Cache Line This definition specifies the number of Words per Prefetch Cache Line. Remarks The actual number of words per cache line is processor specific and is defined in the processor-specific header files (see processor.h). PCACHE_MODULE_ID Enumeration Lists the possible Module IDs for the Prefetch Cache. File help_plib_pcache.h C typedef enum { PCACHE_ID_1, PCACHE_NUMBER_OF_MODULES } PCACHE_MODULE_ID; Description Module ID This enumeration lists the possible Module IDs for the Prefetch Cache. Remarks Refer to the data sheet to get the correct number of modules defined for the desired device. Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1546 PLIB_PCACHE_DATA_ENABLE Enumeration Lists the possible predictive prefetch states for the Prefetch Cache. File help_plib_pcache.h C typedef enum { PLIB_PCACHE_DATA_DISABLE, PLIB_PCACHE_DATA_1LINE, PLIB_PCACHE_DATA_2LINE, PLIB_PCACHE_DATA_4LINE } PLIB_PCACHE_DATA_ENABLE; Members Members Description PLIB_PCACHE_DATA_DISABLE Disable data caching PLIB_PCACHE_DATA_1LINE Enable data caching with a size of 1 Line PLIB_PCACHE_DATA_2LINE Enable data caching with a size of 2 Lines PLIB_PCACHE_DATA_4LINE Enable data caching with a size of 4 Lines Description Data Cache Enable This enumeration lists the possible predictive prefetch states for the Prefetch Cache. Remarks Not all settings are available for all devices. See the device-specific data sheet for details. This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). PLIB_PCACHE_PREFETCH_ENABLE Enumeration Lists the possible predictive prefetch states for the Prefetch Cache. File help_plib_pcache.h C typedef enum { PLIB_PCACHE_PREFETCH_DISABLE, PLIB_PCACHE_PREFETCH_ENABLE_CACHED_REGIONS, PLIB_PCACHE_PREFETCH_ENABLE_CPU_INST, PLIB_PCACHE_PREFETCH_ENABLE_NONCACHED_REGIONS, PLIB_PCACHE_PREFETCH_ENABLE_CPU_INST_DATA, PLIB_PCACHE_PREFETCH_ENABLE_ALL } PLIB_PCACHE_PREFETCH_ENABLE; Members Members Description PLIB_PCACHE_PREFETCH_DISABLE Disable predictive prefetch enable PLIB_PCACHE_PREFETCH_ENABLE_CACHED_REGIONS Enable predictive prefetch cache for cacheable regions only PLIB_PCACHE_PREFETCH_ENABLE_CPU_INST Enable predictive prefetch cache for cacheable regions only PLIB_PCACHE_PREFETCH_ENABLE_NONCACHED_REGIONS Enable predictive prefetch cache for non-cacheable regions only PLIB_PCACHE_PREFETCH_ENABLE_CPU_INST_DATA Enable predictive prefetch cache for non-cacheable regions only PLIB_PCACHE_PREFETCH_ENABLE_ALL Enable predictive prefetch cache for cacheable and non-cacheable regions Description Predictive Prefetch Cache Enable Bits This enumeration lists the possible predictive prefetch states for the Prefetch Cache. Peripheral Libraries Help Prefetch Cache Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1547 Remarks Not all settings are available for all devices. See the device-specific data sheet for details. This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). Files Files Name Description plib_pcache.h Defines the Prefetch Cache Peripheral Library Interface help_plib_pcache.h This file is used for documentation purposes Description This section lists the source and header files used by the library. plib_pcache.h Defines the Prefetch Cache Peripheral Library Interface Functions Name Description PLIB_PCACHE_CacheHitRead Reads the number of cache hits. PLIB_PCACHE_CacheHitWrite Sets the number of cache hits. PLIB_PCACHE_CacheLineAddrGet Gets the TAG address in the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineAddrSet Sets the TAG address in the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineData Sets cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect to data type. PLIB_PCACHE_CacheLineDeselect Disables write access to the cache line specified by cache_line. PLIB_PCACHE_CacheLineFlashTypeBoot Set the cache line tag for the line previously write-enabled by PLIB_PCACHE_CacheLineSelect as residing in Boot Flash. PLIB_PCACHE_CacheLineFlashTypeInst Set the cache line tag for the line previously write-enabled by PLIB_PCACHE_CacheLineSelect as residing in Instruction Flash. PLIB_PCACHE_CacheLineFlashTypeIsInst Returns true if the cache line tag for the line previously write-enabled by PLIB_PCACHE_CacheLineSelect shows the line is residing in Instruction Flash. PLIB_PCACHE_CacheLineInst Sets cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect to instruction type. PLIB_PCACHE_CacheLineInvalid Invalidates cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineIsInst Returns true if cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect is set to instruction type. PLIB_PCACHE_CacheLineIsLocked Returns true if cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect is locked. PLIB_PCACHE_CacheLineIsValid Returns true if cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect is valid. PLIB_PCACHE_CacheLineLock Locks cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineMaskGet Returns the current state of the cache tag mask for the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineMaskSet Sets the cache tag mask to force a match on set bits on the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineSelect Enables write access to the cache line specified by cache_line. PLIB_PCACHE_CacheLineUnlock Unlocks cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineValid Validates cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheMissRead Reads the number of cache misses. PLIB_PCACHE_CacheMissWrite Sets the number of cache misses. Peripheral Libraries Help Prefetch Cache Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1548 PLIB_PCACHE_DataCacheEnableGet Gets the data cache enable bits. PLIB_PCACHE_DataCacheEnableSet Sets the data cache enable bits. PLIB_PCACHE_ExistsCacheHit Identifies that the CacheHit feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLine Identifies that the CacheLineSelect feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineAddr Identifies that the CacheLineAddr feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineFlashType Identifies that the CacheLineFlashType feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineLock Identifies that the CacheLineLock feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineMask Identifies that the CacheLineMask feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineType Identifies that the CacheLineType feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineValid Identifies that the CacheLineValid feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheMiss Identifies that the CacheMiss feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsDataCacheEnable Identifies that the DataCacheEnable feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsFlashDEDStatus Identifies that the FlashDEDStatus feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsFlashSECCount Identifies that the FlashSECCount feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsFlashSECInt Identifies that the FlashSECInt feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsFlashSECStatus Identifies that the FlashSECStatus feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsInvalidateOnPFMProgram Identifies that the InvalidateOnPFMProgram feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsLeastRecentlyUsedState Identifies that the LeastRecentlyUsedState feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsPrefetchAbort Identifies that the PrefetchAbort feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsPrefetchEnable Identifies that the PrefetchEnable feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsWaitState Identifies that the WaitState feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsWord Identifies that the Word feature exists on the Prefetch Cache module. PLIB_PCACHE_FlashDEDStatusClear Clears a bus exception caused by a double-bit error. PLIB_PCACHE_FlashDEDStatusGet Determines if a bus exception was caused by a double-bit error. PLIB_PCACHE_FlashSECCountGet Returns the current value of the Flash SEC counter. PLIB_PCACHE_FlashSECCountSet Sets the number of single-bit error corrections that must occur before the SEC status is set to true. PLIB_PCACHE_FlashSECIntDisable Disables an interrupt on SEC. PLIB_PCACHE_FlashSECIntEnable Enables an interrupt on SEC. PLIB_PCACHE_FlashSECStatusClear Sets the single-bit error corrected status to false. PLIB_PCACHE_FlashSECStatusGet Determines if a SEC event triggered a Prefetch Cache interrupt. PLIB_PCACHE_FlashSECStatusSet Sets the single-bit error corrected status to true. PLIB_PCACHE_InvalidateOnPFMProgramAll Sets Prefetch Cache to invalidate all data and instruction lines on a PFM program cycle. PLIB_PCACHE_InvalidateOnPFMProgramUnlocked Sets Prefetch Cache to invalidate all unlocked data and instruction lines on a PFM program cycle. PLIB_PCACHE_LeastRecentlyUsedStateRead Reads the state of the cache Least Recently Used (LRU) encoding bits. PLIB_PCACHE_PrefetchAbortRead Reads the number of prefetch aborts. PLIB_PCACHE_PrefetchAbortWrite Sets the number of prefetch aborts. PLIB_PCACHE_PrefetchEnableGet Gets the predictive Prefetch state for the Prefetch Cache module. PLIB_PCACHE_PrefetchEnableSet Sets the predictive Prefetch state for the Prefetch Cache module. PLIB_PCACHE_WaitStateGet Gets the Prefetch Cache access time. PLIB_PCACHE_WaitStateSet Sets the Prefetch Cache access time. PLIB_PCACHE_WordRead Reads the word specified by word from cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Peripheral Libraries Help Prefetch Cache Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1549 PLIB_PCACHE_WordWrite Writes the word (specified by word parameter) with data (specified by data parameter) to cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Description Prefetch Cache Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Prefetch Cache Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Prefetch Cache module. File Name plib_pcache.h Company Microchip Technology Inc. help_plib_pcache.h Enumerations Name Description PCACHE_MODULE_ID Lists the possible Module IDs for the Prefetch Cache. PLIB_PCACHE_DATA_ENABLE Lists the possible predictive prefetch states for the Prefetch Cache. PLIB_PCACHE_PREFETCH_ENABLE Lists the possible predictive prefetch states for the Prefetch Cache. Macros Name Description PLIB_PCACHE_MAX_SEC_COUNT Defines the maximum value for single bit error counter. PLIB_PCACHE_NUM_LINES Defines the number of available Prefetch Cache Lines. PLIB_PCACHE_NUM_WORDS_PER_LINE Defines the number of Words per Prefetch Cache Line. Description This file is used for documentation purposes Peripheral Libraries Help Prefetch Cache Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1550 Ports Peripheral Library This section describes the Ports Peripheral Library. Introduction This library provides a low-level abstraction of the I/O Ports module on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The general purpose I/O pins can be considered the simplest of peripherals. These I/O pins allow the microcontroller to monitor and control other devices. To add flexibility and functionality to a device, some pins are multiplexed with alternate function(s). These functions depend on which peripheral features are on the device. In general, when a peripheral is functioning, that pin may not be used as a general purpose I/O pin. A major challenge in general purpose devices is providing the largest possible set of peripheral features while minimizing the conflict of features on I/O pins. The Peripheral Pin Select (PPS) feature simplifies this challenge by enabling the user’s peripheral set selection and their placement on a wide range of I/O pins. By increasing the pin out options available on a particular device, users can better tailor the microcontroller to their entire application. The PPS feature operates over a fixed subset of digital I/O pins. Users may independently map the input and/or output of any one of many digital peripherals to any one of these I/O pins. PPS is performed in software and generally does not require the device to be reprogrammed. Hardware safeguards are included that prevent accidental or spurious changes to the peripheral mapping once it has been established. Note: Peripheral Pin Select is not available on all devices. Please refer to the specific device data sheet to determine availability of this feature. Following are some of the key features of the I/O Ports module: • Individual output pin/port open-drain control • Individual input pin/port pull-up/down control • Monitor select inputs and generate interrupt on mismatch condition (Change Notification) • Operation during Sleep and Idle modes • Port line analog/digital selection • Port slew rate control • PPS peripheral function remapping Using the Library This topic describes the basic architecture of the Ports Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_ports.h The interface to the Ports Peripheral Library is defined in the plib_ports.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Ports Peripheral Library must include peripheral.h. Library File: The Ports Peripheral Library is part of the processor-specific peripheral library installed with the compiler. This library is automatically available (in the default search path) for any project built using the Microchip compilers. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This topic provides detailed information for general purpose I/O and pin mapping. Description General Purpose I/O All port pins have three controls directly associated with their operation as digital I/O. The data direction control determines whether the pin is an input or an output. All port pins are defined as inputs after a Reset. Writes to a port are latched and, if programmed as an output, driven by a buffer to the pin. The value of pin can be read directly from an input buffer, (after it has been synchronized to the clock), regardless of whether the pin direction has been selected as input or output. Additionally, the value being driven by the latch before the output buffer, can also be read. Peripheral Libraries Help Ports Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1551 Internal pull-up resistors are available on selected port pins to eliminate the need to use external pull-up resistors. These pull-ups can be controlled by this library. The open-drain feature allows the generation of outputs higher than VDD on any desired digital-only pins by using external pull-up resistors. Note: For detailed specifications on the maximum allowed open-drain voltage, refer to the "Electrical Characteristics" chapter in the specific device data sheet. The input change notification feature of the I/O ports allows the microcontrollers to generate interrupt requests to the processor in response to a change of state on selected input pins. This feature is capable of detecting input change of states even in Sleep mode, when the clocks are disabled. The alternate pin function selections are used to steer specific peripheral input and output functions between different pins. The output slew rate of some port pins are programmable to select either the standard transition rate or a reduced transition rate of 'x' times the standard to minimize EMI. Peripheral Pin Select In addition to general purpose IO control, this library also provides a low-level abstraction of the PPS module on Microchip microcontrollers with a convenient C language interface. Available Pins The number of available pins is dependent on the particular device and its pin count. Pins that support the PPS feature include the designation 'RPn' or 'RPIn' in their full pin designation, where 'RP' designates a remappable peripheral and 'n' is the remappable pin number. RP is used to designate pins that support both remappable input and output functions, while RPI indicates pins that only support remappable input functions. Available Peripherals The peripherals managed by PPS are all digital-only peripherals. These include general serial communications (UART and SPI), general purpose timer clock inputs, timer-related peripherals (Input Capture and Output Compare), comparator digital output, interrupt-on-change inputs, etc. In comparison, some digital-only peripheral modules are never included in the peripheral pin select feature. This is because the peripheral’s function requires special I/O circuitry on a specific port and cannot be easily connected to multiple pins. These modules include I2C, among others. A similar requirement excludes all modules with analog inputs, such as the Analog-to-Digital Converter (ADC). If multiple peripherals are enabled on the same pin(s), there is an internal priority that decides which function is mapped to the pin. When a remappable peripheral is active on a given I/O pin, it takes priority over all other digital I/O and digital communication peripherals associated with the pin. Priority is given regardless of the type of peripheral that is mapped. Remappable peripherals never take priority over any analog functions associated with the pin. In other words, If an analog function is enabled on the pin, the PPS input will be disabled. Input Mapping The inputs of the peripheral pin select options are mapped on the basis of the peripheral. Peripheral Libraries Help Ports Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1552 Output Mapping In contrast to inputs, the outputs of the peripheral pin select options are mapped on the basis of the pin. In this case, a control associated with a particular pin dictates the peripheral output to be mapped. Mapping Limitations The control schema of the peripheral select pins is not limited to a small range of fixed peripheral configurations. There are no mutual-exclusion or hardware-enforced lockouts between any of the peripheral mapping SFRs. Literally any combination of peripheral mappings across any or all of the RPn pins is possible. This includes both many-to-one and one-to-many mappings of peripheral inputs and outputs to pins. While such mappings may be technically possible from a configuration point of view, they may not be supportable from an electrical point of view and may cause damage to the part. Notes: 1. For detailed specifications on the mapping limitations, refer to the "I/O Ports" chapter in the specific device data sheet. 2. Regrading pin priorities, the priority of the pins are assigned from left to right, left being the highest priority and the right most being the least priority. Peripheral Libraries Help Ports Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1553 Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Ports module. Library Interface Section Description Port Functions Port access read/write/toggle/clear interfaces with 8-/16-/32-bit widths based on the selected device. Port Pin Functions Port bit/pin read/write/toggle/clear interfaces. Change Notification Functions Port change notification. Peripheral Pin Select Functions Interface routines for mapping the digital input/output to a specific the PPS remappable input/output pin. Feature Existence Functions Determine whether certain features exist. How the Library Works How the Library Works The following topics discuss the processes involved while using a Ports module: • Ports Control • Ports Function Remap • Ports Change Notification • Special Considerations Ports Control Port Functions Usage: • Port Read - Ports can be read at byte/word level using PLIB_PORTS_Read, and at the bit/pin level using PLIB_PORTS_PinGet • Port Write - Ports can be written to at byte/word level using PLIB_PORTS_Write and at the bit/pin level using PLIB_PORTS_PinWrite. The function PLIB_PORTS_PinSet can be used to set a specific bit/pin of a port. A mask-based PORTx write can be accomplished using the function PLIB_PORTS_Set with the appropriate mask as a parameter along with the value. • Port Clear - Ports can be cleared at byte/word level using PLIB_PORTS_Clear with appropriate mask as a parameter and at the bit/pin level using PLIB_PORTS_PinClear • Port Direction - The ports read direction can be set at byte/word level using PLIB_PORTS_DirectionInputSet and at the bit/pin level using PLIB_PORTS_PinDirectionInputSet. Similarly, the ports write direction can be set at the byte/word level using PLIB_PORTS_DirectionOutputSet and at the bit/pin level using PLIB_PORTS_PinDirectionOutputSet. The direction information can be read using PLIB_PORTS_DirectionGet. • Port Toggle - Ports can be toggled at the byte/word level using PLIB_PORTS_Toggle with the appropriate mask as a parameter and at the bit/pin level using PLIB_PORTS_PinToggle • Port Open Drain - Ports can be enabled for open-drain functionality at the byte/word level using the interface PLIB_PORTS_OpenDrainEnable and at the bit/pin level using PLIB_PORTS_PinOpenDrainEnable. Similarly, the ports can be disabled for open-drain functionality at the byte/word level using PLIB_PORTS_OpenDrainDisable and at the bit/pin level using PLIB_PORTS_PinOpenDrainDisable. Example: // PORT Direction setting for output PLIB_PORTS_DirectionOutputSet(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0xFFFF); // Writing a value into a PORT PLIB_PORTS_Write(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_TYPE)0x1234); // PORT Direction setting for input PLIB_PORTS_DirectionInputSet(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0xFFFF); // Reading back the previously written value PORTS_DATA_TYPE readData = PLIB_PORTS_Read(MY_PORTS_INSTANCE, MY_CHANNEL); // Clearing the PORT PLIB_PORTS_Clear(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); // Writing the value based on the mask, only 0x34 gets written to the PORT PLIB_PORTS_Set(MY_PORTS_INSTANCE, MY_CHANNEL, 0x1234, (PORTS_DATA_MASK)0x00FF); // Toggling a PORT PLIB_PORTS_Toggle(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); Peripheral Libraries Help Ports Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1554 Ports Function Remap Using the PPS Feature: 1. Ensure that any fixed digital peripherals on the pins to be used are disabled. 2. Ensure that pins with analog functionality are set to Digital mode. 3. Enable writing to the Input/Output control register using PLIB_DEVCON_SystemUnlock and PLIB_DEVCON_DeviceRegistersUnlock. 4. Remap the input and/or output pins using the internal PPS module. This can be achieved with the functions PLIB_PORTS_RemapInput and PLIB_PORTS_RemapOutput with the respective parameters defined in the processor specific headers. 5. Lock the Input/Output control register using PLIB_DEVCON_SystemUnlock and PLIB_DEVCON_DeviceRegistersUnlock. 6. Configure and enable newly mapped PPS peripherals. Example: // System Unlock PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); // Unlock PPS registers PLIB_DEVCON_DeviceRegistersUnlock(DEVCON_ID_0, DEVCON_PPS_REGISTERS); // Remapping input function 'Input Capture 1' to the Remappable pin 'RPD2' PLIB_PORTS_RemapInput(PORTS_ID_0, INPUT_FUNC_IC1, INPUT_PIN_RPD2 ); // Remapping output function 'UART3 Transmit' to the Remappable pin 'RPA14' PLIB_PORTS_RemapOutput(PORTS_ID_0, OUTPUT_FUNC_U3TX, OUTPUT_PIN_RPA14); // Lock PPS registers PLIB_DEVCON_DeviceRegistersLock(DEVCON_ID_0, DEVCON_PPS_REGISTERS); Note: For more information, refer to the "I/O Ports" chapter in the specific device data sheet or the family reference manual section specified in that chapter. Ports Change Notification Change Notification Feature Usage 1. Ensure that the change notify pin is configured as a digital input by setting the associated bit in the direction register using the PLIB_PORTS_PinDirectionInputSet or PLIB_PORTS_DirectionInputSet functions. 2. Select the desired change notification pin using PLIB_PORTS_PinChangeNoticeEnable. 3. Turn on the weak pull-up devices (if desired) for the selected change notification pins using PLIB_PORTS_ChangeNoticePullUpEnable (weak pull-ups can be disabled using PLIB_PORTS_ChangeNoticePullUpDisable). 4. Clear the selected change notification interrupt flag. 5. Select the desired interrupt priority for change notification pin. 6. Enable change notification interrupts. 7. Change notification can be disabled after the successful usage using PLIB_PORTS_PinChangeNoticeDisable. Certain microcontrollers support the global control over the change notification feature using the following functions: PLIB_PORTS_ChangeNoticeEnable and PLIB_PORTS_ChangeNoticeDisable. If there are any requirements to control the pull-downs, the following two functions could be used: PLIB_PORTS_ChangeNoticePullDownPerPortEnable and PLIB_PORTS_ChangeNoticePullDownPerPortDisable. Change Notification Operation in Sleep and Idle Modes The change notification feature continues to operate during Sleep or Idle mode. Its operation can be enabled or disabled using PLIB_PORTS_ChangeNoticeInIdleEnable or PLIB_PORTS_ChangeNoticeInIdleDisable. If one of the enabled change notification pins changes states, the respective status bit will be set, which can be monitored using PLIB_PORTS_ChangeNoticePerPortHasOccurred. Example: // Enabling the global change notification PLIB_PORTS_ChangeNoticeEnable(MY_PORTS_INSTANCE); // Enabling weak pull-ups for the change notification PIN 10 PLIB_PORTS_ChangeNoticePullUpEnable(MY_PORTS_INSTANCE, PORTS_CHANGE_NOTICE_PIN_10); // Enabling change notification on PIN 10 PLIB_PORTS_PinChangeNoticeEnable(MY_PORTS_INSTANCE, PORTS_CHANGE_NOTICE_PIN_10); Note: For more information, refer to the "I/O Ports" chapter in the specific device data sheet or the related family reference manual section specified in that chapter. Peripheral Libraries Help Ports Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1555 Special Considerations Considerations on Ports Usage When reading a port register, all pins configured as analog input channels will read as cleared. Pins configured as digital inputs will not operate correctly with analog peripherals. Analog levels on any pin that is defined as a digital input may cause the input buffer of analog peripherals to consume current that exceeds the device specifications. Pull-ups and pull-downs on change notification pins should always be disabled when the port pin is configured as a digital output. One instruction cycle is required between a port direction change or port write operation and a read operation of the same port. Typically, this instruction would be a NOP. Considerations for PPS The ability to control PPS options introduces several considerations into application design that could be overlooked. This is particularly true for several common peripherals that are available only as remappable peripherals. The main consideration is that the peripheral pin selects are not available on default pins in the device’s default (i.e., Reset) state, all PPS inputs are tied to VSS and all PPS outputs are disconnected. This condition requires the user to initialize the device with the proper peripheral configuration before any other application code is executed. For application safety, however, it is best to lock the configuration after writing to the PPS control. The assignment of a peripheral signal to a particular pin does not automatically perform any other configuration of the pin’s I/O circuitry. In theory, this means adding a pin-selectable output to a pin may mean inadvertently driving an existing peripheral input when the output is driven. Users must be familiar with the behavior of other fixed peripherals that share a remappable pin and know when to enable or disable them. To be safe, fixed digital peripherals that share the same pin should be disabled when not in use. In addition, configuring a remappable pin for a specific peripheral does not automatically turn on that feature. The peripheral must be specifically configured for operation and enabled, as if it were tied to a fixed pin. Where this occurs in the application code (immediately following a device Reset and peripheral configuration or inside the main application routine) depends on the peripheral and its use in the application. A final consideration is that PPS functions neither override analog inputs, nor reconfigure pins with analog functions for digital I/O. If a pin is configured as an analog input on a device Reset, it must be explicitly reconfigured as a digital I/O when used with PPS. Note: For more information, refer to the "I/O Ports" chapter in the specific device data sheet or the family reference manual section specified in that chapter. Configuring the Library The library is configured for the supported Ports module when the supported processor is chosen in the MPLAB X IDE. Library Interface a) Port Pin Functions Name Description PLIB_PORTS_PinClear Clears the selected digital pin/latch. PLIB_PORTS_PinDirectionInputSet Makes the selected pin direction input PLIB_PORTS_PinDirectionOutputSet Makes the selected pin direction output PLIB_PORTS_PinGet Reads/Gets data from the selected digital pin. PLIB_PORTS_PinModeSelect Enables the selected pin as analog or digital. PLIB_PORTS_PinSet Sets the selected digital pin/latch. PLIB_PORTS_PinToggle Toggles the selected digital pin/latch. PLIB_PORTS_PinWrite Writes the selected digital pin/latch. PLIB_PORTS_PinModePerPortSelect Enables the selected port pin as analog or digital. PLIB_PORTS_PinGetLatched Reads/Gets data from the selected latch. PLIB_PORTS_PinChangeNoticeEdgeHasOccurred Check Change Notice edge status. PLIB_PORTS_PinChangeNoticeEdgeIsEnabled Check if Change Notice edge is enabled or not. PLIB_PORTS_PinSlewRateGet Gets the slew rate for selected port pin. PLIB_PORTS_PinOpenDrainDisable Disables the open drain functionality for the selected pin. PLIB_PORTS_PinOpenDrainEnable Enables the open drain functionality for the selected pin. b) Port Functions Name Description PLIB_PORTS_Clear Clears the selected digital port/latch bits. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1556 PLIB_PORTS_DirectionGet Reads the direction of the selected digital port. PLIB_PORTS_DirectionInputSet Makes the selected pins direction input. PLIB_PORTS_DirectionOutputSet Makes the selected pins direction output. PLIB_PORTS_Read Reads the selected digital port. PLIB_PORTS_Set Sets the selected bits of the port. PLIB_PORTS_Toggle Toggles the selected digital port/latch. PLIB_PORTS_Write Writes the selected digital port/latch. PLIB_PORTS_OpenDrainDisable Disables the open drain functionality for the selected port. PLIB_PORTS_OpenDrainEnable Enables the open drain functionality for the selected port pins. PLIB_PORTS_ReadLatched Reads and returns data from the selected Latch. PLIB_PORTS_ChannelModeSelect Enables the selected channel pins as analog or digital. PLIB_PORTS_ChannelSlewRateSelect Selects the slew rate for selected channel pins. c) Peripheral Pin Select Functions Name Description PLIB_PORTS_RemapInput Input function remapping. PLIB_PORTS_RemapOutput Output function remapping. d) Change Notification Functions Name Description PLIB_PORTS_ChangeNoticeDisable Global Change Notice disable. PLIB_PORTS_ChangeNoticeEnable Global Change Notice enable. PLIB_PORTS_ChangeNoticeInIdleDisable CPU Idle halts the Change Notice operation. PLIB_PORTS_ChangeNoticeInIdleEnable CPU Idle mode does not affect Change Notice operation. PLIB_PORTS_ChangeNoticeInIdlePerPortDisable Change Notification halts in Idle mode for selected channel. PLIB_PORTS_ChangeNoticeInIdlePerPortEnable Allows CN to be working in Idle mode for selected channel. PLIB_PORTS_ChangeNoticePerPortHasOccured This is function PLIB_PORTS_ChangeNoticePerPortHasOccured. PLIB_PORTS_ChangeNoticePerPortTurnOff Disables the change notification for selected port. PLIB_PORTS_ChangeNoticePerPortTurnOn Enables the change notification for selected port. PLIB_PORTS_ChangeNoticePullDownPerPortDisable Disables the pull-down for selected Change Notice pins. PLIB_PORTS_ChangeNoticePullDownPerPortEnable Enables the pull-down for selected Change Notice pins. PLIB_PORTS_ChangeNoticePullUpDisable Disable pull-up on input change. PLIB_PORTS_ChangeNoticePullUpEnable Enable pull-up on input change. PLIB_PORTS_ChangeNoticePullUpPerPortDisable Disables weak pull-up for the selected pin. PLIB_PORTS_ChangeNoticePullUpPerPortEnable Enables the pull-up for selected Change Notice pins. PLIB_PORTS_PinChangeNoticeDisable Port pin Change Notice disable. PLIB_PORTS_PinChangeNoticeEnable Port pin Change Notice interrupt enable. PLIB_PORTS_PinChangeNoticePerPortDisable Disables CN interrupt for the selected pin. PLIB_PORTS_PinChangeNoticePerPortEnable Enables CN interrupt for the selected pin. PLIB_PORTS_ChangeNoticePerPortHasOccurred checks the status of change on the pin PLIB_PORTS_ChannelChangeNoticeDisable Disables CN interrupt for the selected pins of a channel. PLIB_PORTS_ChannelChangeNoticeEnable Enables CN interrupt for the selected pins of a channel. PLIB_PORTS_ChannelChangeNoticePullDownDisable Disables Change Notice pull-down for the selected channel pins. PLIB_PORTS_ChannelChangeNoticePullDownEnable Enables Change Notice pull-down for the selected channel pins. PLIB_PORTS_ChannelChangeNoticePullUpDisable Disables Change Notice pull-up for the selected channel pins. PLIB_PORTS_ChannelChangeNoticePullUpEnable Enables Change Notice pull-up for the selected channel pins. PLIB_PORTS_ChannelChangeNoticeEdgeDisable Disables selected type of edge for selected CN pins. PLIB_PORTS_ChannelChangeNoticeEdgeEnable Enables selected type of edge for selected CN pins. PLIB_PORTS_ChannelChangeNoticeMethodGet Gets the Change Notice style for the selected port channel. PLIB_PORTS_ChannelChangeNoticeMethodSelect Selects the Change Notice style for selected port channel. PLIB_PORTS_AnPinsModeSelect Enables the selected AN pins as analog or digital. PLIB_PORTS_CnPinsDisable Disables CN interrupt for the selected pins of a channel. PLIB_PORTS_CnPinsEnable Enables CN interrupt for the selected pins of a channel. PLIB_PORTS_CnPinsPullUpDisable Disables Change Notice pull-up for the selected channel pins. PLIB_PORTS_CnPinsPullUpEnable Enables Change Notice pull-up for the selected channel pins. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1557 e) Feature Existence Functions Name Description PLIB_PORTS_ExistsChangeNotice Identifies whether the ChangeNotice feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticeInIdle Identifies whether the ChangeNoticeInIdle feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePerPortInIdle Identifies whether the ChangeNoticeInIdlePerPort feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePerPortStatus Identifies whether the ChangeNoticePerPortStatus feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePerPortTurnOn Identifies whether the ChangeNoticePerPortTurnOn feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePullDownPerPort Identifies whether the ChangeNoticePullDownPerPort feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePullUp Identifies whether the ChangeNoticePullup feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePullUpPerPort Identifies whether the ChangeNoticePullUpPerPort feature exists on the Ports module. PLIB_PORTS_ExistsPinChangeNotice Identifies whether the PinChangeNotice feature exists on the Ports module. PLIB_PORTS_ExistsPinChangeNoticePerPort Identifies whether the PinChangeNoticePerPort feature exists on the Ports module. PLIB_PORTS_ExistsPinMode Identifies whether the PinMode feature exists on the Ports module. PLIB_PORTS_ExistsPinModePerPort Identifies whether the PinModePerPort feature exists on the Ports module. PLIB_PORTS_ExistsPortsDirection Identifies whether the PortsDirection feature exists on the Ports module. PLIB_PORTS_ExistsPortsOpenDrain Identifies whether the PortsOpenDrain feature exists on the Ports module. PLIB_PORTS_ExistsPortsRead Identifies whether the PortsRead feature exists on the Ports module. PLIB_PORTS_ExistsPortsWrite Identifies whether the PortsWrite feature exists on the Ports module. PLIB_PORTS_ExistsRemapInput Identifies whether the RemapInput feature exists on the Ports module. PLIB_PORTS_ExistsRemapOutput Identifies whether the RemapOutput feature exists on the Ports module. PLIB_PORTS_ExistsLatchRead Identifies whether the LatchRead feature exists on the Ports module. PLIB_PORTS_ExistsAnPinsMode Identifies whether the AnPinsMode feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticeEdgeControl Identifies whether the ChangeNoticeEdgeControl feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticeEdgeStatus Identifies whether the ChangeNoticeEdgeStatus feature exists on the Ports module. PLIB_PORTS_ExistsChannelChangeNoticeMethod Identifies whether the ChannelChangeNoticeMethod feature exists on the Ports module. PLIB_PORTS_ExistsSlewRateControl Identifies whether the SlewRateControl feature exists on the Ports module. f) Data Types and Constants Name Description PORTS_ANALOG_PIN Data type defining the different analog input pins. PORTS_BIT_POS Lists the constants that hold different PORTS bit positions. PORTS_CHANGE_NOTICE_PIN Data type defining the different Change Notification (CN) pins enumerations. PORTS_CHANNEL Identifies the available Ports channels. PORTS_DATA_MASK Data type defining the Ports data mask PORTS_DATA_TYPE Data type defining the Ports data type. PORTS_MODULE_ID Identifies the available Ports modules. PORTS_PIN_MODE Identifies the available pin modes. PORTS_REMAP_FUNCTION Data type defining the different remap function enumerations. PORTS_REMAP_INPUT_FUNCTION Data type defining the different remap input function enumerations. PORTS_REMAP_INPUT_PIN Data type defining the different Ports I/O input pins enumerations. PORTS_REMAP_OUTPUT_FUNCTION Data type defining the different remap output function enumerations. PORTS_REMAP_OUTPUT_PIN Data type defining the different Ports I/O output pins enumerations. PORTS_REMAP_PIN Data type defining the different remappable input/output enumerations. PORTS_AN_PIN Data type defining the different analog input pins. PORTS_CN_PIN Data type defining the different Change Notification (CN) pins enumerations. PORTS_CHANGE_NOTICE_EDGE Data type defining the different edge type for change notification. PORTS_CHANGE_NOTICE_METHOD Data type defining the different method of ports pin change notification. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1558 PORTS_PIN_SLEW_RATE Data type defining the different slew rates for port pins. Description This section describes the Application Programming Interface (API) functions of the Ports Peripheral Library. Refer to each section for a detailed description. a) Port Pin Functions PLIB_PORTS_PinClear Function Clears the selected digital pin/latch. File plib_ports.h C void PLIB_PORTS_PinClear(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function clears the selected digital pin/latch. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Preconditions None. Example // Clears port pin RC4 PLIB_PORTS_PinClear(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Function void PLIB_PORTS_PinClear( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_PinDirectionInputSet Function Makes the selected pin direction input File plib_ports.h C void PLIB_PORTS_PinDirectionInputSet(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function makes the selected pin direction as input Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1559 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Preconditions None. Example // make pin RC4 as input PLIB_PORTS_PinDirectionInputSet(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS direction that has to be made input Function void PLIB_PORTS_PinDirectionInputSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_PinDirectionOutputSet Function Makes the selected pin direction output File plib_ports.h C void PLIB_PORTS_PinDirectionOutputSet(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function makes the selected pin direction as output Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Preconditions None. Example // make pin RC4 as output PLIB_PORTS_PinDirectionOutputSet(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS direction that has to be made output Function void PLIB_PORTS_PinDirectionOutputSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1560 PLIB_PORTS_PinGet Function Reads/Gets data from the selected digital pin. File plib_ports.h C bool PLIB_PORTS_PinGet(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns Port pin read data. Description This function reads/gets data from the selected digital PORT i/o pin. This function should be used to read the live data at the pin. Remarks For reading the Latched data, PLIB_PORTS_PinGetLatched function should be used. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsRead in your application to determine whether this feature is available. Preconditions None. Example // read port pin RC4 bool bitStatus = PLIB_PORTS_PinGet(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Function bool PLIB_PORTS_PinGet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_PinModeSelect Function Enables the selected pin as analog or digital. File plib_ports.h C void PLIB_PORTS_PinModeSelect(PORTS_MODULE_ID index, PORTS_ANALOG_PIN pin, PORTS_PIN_MODE mode); Returns None. Description This function enables the selected pin as analog or digital. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1561 Example // Make AN0 pin as Analog PLIB_PORTS_PinModeSelect(PORTS_ID_0, PORTS_ANALOG_PIN_0, PORTS_PIN_MODE_ANALOG); Parameters Parameters Description index Identifier for the device instance to be configured pin Possible values of PORTS_ANALOG_PIN mode Possible values of PORTS_PIN_MODE Function void PLIB_PORTS_PinModeSelect( PORTS_MODULE_ID index, PORTS_ANALOG_PIN pin, PORTS_PIN_MODE mode ); PLIB_PORTS_PinSet Function Sets the selected digital pin/latch. File plib_ports.h C void PLIB_PORTS_PinSet(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function sets the selected digital pin/latch. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Preconditions None. Example // Sets port pin RC4 PLIB_PORTS_PinSet(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Function void PLIB_PORTS_PinSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_PinToggle Function Toggles the selected digital pin/latch. File plib_ports.h Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1562 C void PLIB_PORTS_PinToggle(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function toggles the selected digital pin/latch. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Preconditions None. Example // Toggles port pin RC4 PLIB_PORTS_PinToggle(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Function void PLIB_PORTS_PinToggle( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_PinWrite Function Writes the selected digital pin/latch. File plib_ports.h C void PLIB_PORTS_PinWrite(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos, bool value); Returns None. Description This function writes to the selected digital pin/latch. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Preconditions None. Example // write 'one' in port RC4 PLIB_PORTS_PinWrite(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4, 1); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1563 channel Identifier for the Ports channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS value Value to be written to the specific pin/latch true sets the bit, false - clears the bit Function void PLIB_PORTS_PinWrite( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos, bool value ) PLIB_PORTS_PinModePerPortSelect Function Enables the selected port pin as analog or digital. File plib_ports.h C void PLIB_PORTS_PinModePerPortSelect(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos, PORTS_PIN_MODE mode); Returns None. Description This function enables the selected port pin as analog or digital. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_PinModeSelect function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinModePerPort in your application to determine whether this feature is available. Preconditions None. Example // Make RC5 pin Analog PLIB_PORTS_PinModePerPortSelect(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_5, PORTS_PIN_MODE_ANALOG); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Function void PLIB_PORTS_PinModePerPortSelect( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos, PORTS_PIN_MODE mode ); PLIB_PORTS_PinGetLatched Function Reads/Gets data from the selected latch. File plib_ports.h Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1564 C bool PLIB_PORTS_PinGetLatched(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns Latch read data. Description This function reads/gets data from the selected PORTx Data Latch, not from the port I/O pins. Remarks For reading the Live data from the i/o pin, PLIB_PORTS_PinGet function should be used. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsLatchRead in your application to determine whether this feature is available. Preconditions None. Example // read latch RC4 bool bitStatus = PLIB_PORTS_PinGetLatched(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Function bool PLIB_PORTS_PinGetLatched( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_PinChangeNoticeEdgeHasOccurred Function Check Change Notice edge status. File plib_ports.h C bool PLIB_PORTS_PinChangeNoticeEdgeHasOccurred(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns • true - Change Notice edge transition has occurred • false - Change Notice edge transition has not occurred Description This function checks whether or no a Change Notice edge transition has occurred on the selected port pin. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeEdgeStatus in your application to determine whether this feature is available. Preconditions None. Example // Check if Change Notice edge transition has occurred for pin RC1. if (PLIB_PORTS_PinChangeNoticeEdgeHasOccurred(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_1)) { Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1565 // do something } Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos One of the possible values of PORTS_BIT_POS Function bool PLIB_PORTS_PinChangeNoticeEdgeHasOccurred ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); PLIB_PORTS_PinChangeNoticeEdgeIsEnabled Function Check if Change Notice edge is enabled or not. File plib_ports.h C bool PLIB_PORTS_PinChangeNoticeEdgeIsEnabled(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos, PORTS_CHANGE_NOTICE_EDGE cnEdgeType); Returns • true - Selected type of Change Notice Edge is enabled. • false - Selected type of Change Notice Edge is not enabled. Description This function checks if selected type of Change Notice edge is enabled on a particular port pin or not. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeEdgeControl in your application to determine whether this feature is available. Preconditions None. Example // Check if Change Notice at rising edge is enabled or not for pin RC1. if (PLIB_PORTS_PinChangeNoticeEdgeIsEnabled(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_1, PORTS_CHANGE_NOTICE_EDGE_RISING)) { // do something } Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos One of the possible values of PORTS_BIT_POS. cnEdgeType Type of the edge which has to be checked. Function bool PLIB_PORTS_PinChangeNoticeEdgeIsEnabled ( PORTS_MODULE_ID index, Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1566 PORTS_CHANNEL channel, PORTS_BIT_POS bitPos, PORTS_CHANGE_NOTICE_EDGE cnEdgeType ); PLIB_PORTS_PinSlewRateGet Function Gets the slew rate for selected port pin. File plib_ports.h C PORTS_PIN_SLEW_RATE PLIB_PORTS_PinSlewRateGet(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns One of the possible values of PORTS_PIN_SLEW_RATE. Description This function gets the slew rate of selected port pin. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsSlewRateControl in your application to determine whether this feature is available. Preconditions None. Example PORTS_PIN_SLEW_RATE slewRate; // Get the slew rate of pin RC1 slewRate = PLIB_PORTS_PinSlewRateGet(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_1); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos One of the possible values of PORTS_BIT_POS. Function PORTS_PIN_SLEW_RATE PLIB_PORTS_PinSlewRateGet ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); PLIB_PORTS_PinOpenDrainDisable Function Disables the open drain functionality for the selected pin. File plib_ports.h C void PLIB_PORTS_PinOpenDrainDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1567 Returns None. Description This function disables the open drain functionality for the selected pin. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsOpenDrain in your application to determine whether this feature is available. Preconditions None. Example // Disable open drain for pin RC4 PLIB_PORTS_PinOpenDrainDisable(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. bitPos One of the possible values of PORTS_BIT_POS. Function void PLIB_PORTS_PinOpenDrainDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_PinOpenDrainEnable Function Enables the open drain functionality for the selected pin. File plib_ports.h C void PLIB_PORTS_PinOpenDrainEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function enables the open drain functionality for the selected pin. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsOpenDrain in your application to determine whether this feature is available. Preconditions None. Example // Enable open drain for pin RC4 PLIB_PORTS_PinOpenDrainEnable(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1568 Function void PLIB_PORTS_PinOpenDrainEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) b) Port Functions PLIB_PORTS_Clear Function Clears the selected digital port/latch bits. File plib_ports.h C void PLIB_PORTS_Clear(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK clearMask); Returns None. Description This function clears the selected digital port/latch bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Preconditions None. Example // Clears the three least significant Port C bits PLIB_PORTS_Clear(PORTS_ID_0, PORT_CHANNEL_C, 0x0007); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. clearMask Identifies the bits to be cleared Function void PLIB_PORTS_Clear( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK clearMask ) PLIB_PORTS_DirectionGet Function Reads the direction of the selected digital port. File plib_ports.h C PORTS_DATA_MASK PLIB_PORTS_DirectionGet(PORTS_MODULE_ID index, PORTS_CHANNEL channel); Returns Direction of the selected port of type PORTS_DATA_MASK Description This function reads the direction of the selected digital port. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1569 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Preconditions None. Example // Reads the direction of Port C pins PORTS_DATA_MASK readDir = PLIB_PORTS_DirectionGet(PORTS_ID_0, PORT_CHANNEL_C); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. Function PORTS_DATA_MASK PLIB_PORTS_DirectionGet( PORTS_MODULE_ID index, PORTS_CHANNEL channel ) PLIB_PORTS_DirectionInputSet Function Makes the selected pins direction input. File plib_ports.h C void PLIB_PORTS_DirectionInputSet(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function makes the selected pins direction input. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Preconditions None. Example // Make RC0, RC1 and RC2 pins as Input PLIB_PORTS_DirectionInputSet(PORTS_ID_0, PORT_CHANNEL_C, 0x0007); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. mask Identifies the pins direction that has to be made input Function void PLIB_PORTS_DirectionInputSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ) PLIB_PORTS_DirectionOutputSet Function Makes the selected pins direction output. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1570 File plib_ports.h C void PLIB_PORTS_DirectionOutputSet(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function makes the selected pins direction output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Preconditions None. Example // Make RC0, RC1 and RC2 pins as Output PLIB_PORTS_DirectionOutputSet(PORTS_ID_0, PORT_CHANNEL_C, 0x0007); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. mask Identifies the pins direction that has to be made output Function void PLIB_PORTS_DirectionOutputSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ) PLIB_PORTS_Read Function Reads the selected digital port. File plib_ports.h C PORTS_DATA_TYPE PLIB_PORTS_Read(PORTS_MODULE_ID index, PORTS_CHANNEL channel); Returns data on a port with width PORTS_DATA_TYPE Description This function reads from the selected digital port. Remarks For reading the Latched data, PLIB_PORTS_ReadLatched function should be used. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsRead in your application to determine whether this feature is available. Preconditions None. Example // Read PORT C PORTS_DATA_TYPE readData = PLIB_PORTS_Read(PORTS_ID_0, PORT_CHANNEL_C); Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1571 Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. Function PORTS_DATA_TYPE PLIB_PORTS_Read( PORTS_MODULE_ID index, PORTS_CHANNEL channel ) PLIB_PORTS_Set Function Sets the selected bits of the port. File plib_ports.h C void PLIB_PORTS_Set(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_TYPE value, PORTS_DATA_MASK mask); Returns None. Description This function performs an 'AND' operation on the value and mask parameters, and then sets the bits in the port channel that were set by the result of the 'AND' operation. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Preconditions None. Example // MY_VALUE - 0x1234 PORTS_DATA_MASK myMask = (PORTS_DATA_MASK)0x00FF; // Set the PORT C bit positions 2,4 and 5 (0x0034 = b0000 0000 0011 0100) PLIB_PORTS_Set(MY_PORTS_INSTANCE, PORT_CHANNEL_C, MY_VALUE, myMask); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. value Consists of information about which port bit has to be set and which not mask Identifies the bits which could be intended for setting Function void PLIB_PORTS_Set( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_TYPE value, PORTS_DATA_MASK mask ) PLIB_PORTS_Toggle Function Toggles the selected digital port/latch. File plib_ports.h Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1572 C void PLIB_PORTS_Toggle(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK toggleMask); Returns None. Description This function toggles the selected digital port/latch. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Preconditions None. Example // Toggles the three least significant Port C bits PLIB_PORTS_Toggle(PORTS_ID_0, PORT_CHANNEL_C, 0x0007); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. toggleMask Identifies the bits to be toggled Function void PLIB_PORTS_Toggle( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK toggleMask ) PLIB_PORTS_Write Function Writes the selected digital port/latch. File plib_ports.h C void PLIB_PORTS_Write(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_TYPE value); Returns None. Description This function writes to the selected digital port/latch. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Preconditions None. Example // Write 0x12 into PORT C PLIB_PORTS_Write(PORTS_ID_0, PORT_CHANNEL_C, 0x12); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1573 channel Identifier for the Ports channel A, B, C, etc. value Value to be written into a port of width PORTS_DATA_TYPE Function void PLIB_PORTS_Write( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_TYPE value ) PLIB_PORTS_OpenDrainDisable Function Disables the open drain functionality for the selected port. File plib_ports.h C void PLIB_PORTS_OpenDrainDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function disables the open drain functionality for the selected port. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsOpenDrain in your application to determine whether this feature is available. Preconditions None. Example // Disable Open Drain for RC0, RC1 and RC2 pins PLIB_PORTS_OpenDrainDisable(PORTS_ID_0, PORT_CHANNEL_C, 0x0007); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. mask Identifies the pins for the open drain to be disabled Function void PLIB_PORTS_OpenDrainDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ) PLIB_PORTS_OpenDrainEnable Function Enables the open drain functionality for the selected port pins. File plib_ports.h C void PLIB_PORTS_OpenDrainEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function enables the open drain functionality for the selected port pins. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1574 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsOpenDrain in your application to determine whether this feature is available. Preconditions None. Example // Enable Open Drain for RC0, RC1 and RC2 pins PLIB_PORTS_OpenDrainEnable(PORTS_ID_0, PORT_CHANNEL_C, 0x0007); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. mask Identifies the pins for the open drain to be enabled Function void PLIB_PORTS_OpenDrainEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ) PLIB_PORTS_ReadLatched Function Reads and returns data from the selected Latch. File plib_ports.h C PORTS_DATA_TYPE PLIB_PORTS_ReadLatched(PORTS_MODULE_ID index, PORTS_CHANNEL channel); Returns Latch read data. Description This function reads and returns the data from the selected Latch. Remarks For reading the Live data, PLIB_PORTS_Read function should be used. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsLatchRead in your application to determine whether this feature is available. Preconditions None. Example // Read latch C PORTS_DATA_TYPE bitStatus = PLIB_PORTS_ReadLatched(PORTS_ID_0, PORT_CHANNEL_C); Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the Ports channel A, B, C, etc. Function PORTS_DATA_TYPE PLIB_PORTS_ReadLatched ( PORTS_MODULE_ID index, PORTS_CHANNEL channel ) Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1575 PLIB_PORTS_ChannelModeSelect Function Enables the selected channel pins as analog or digital. File plib_ports.h C void PLIB_PORTS_ChannelModeSelect(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK modeMask, PORTS_PIN_MODE mode); Returns None. Description This function enables the selected channel pins as analog or digital. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_AnPinsModeSelect function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinModePerPort in your application to determine whether this feature is available. Preconditions None. Example // Make pins RC5, RC8 and RC13 Analog PLIB_PORTS_ChannelModeSelect(PORTS_ID_0, PORT_CHANNEL_C, 0x2120, PORTS_PIN_MODE_ANALOG); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel modeMask Identifies the pins whose mode has to be modified. Modes of the pins whose corresponding bit is '1' get modified, mode of the other pins remains the same. mode Possible values of PORTS_PIN_MODE (Analog or Digital) Function void PLIB_PORTS_ChannelModeSelect ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK modeMask, PORTS_PIN_MODE mode ); PLIB_PORTS_ChannelSlewRateSelect Function Selects the slew rate for selected channel pins. File plib_ports.h C void PLIB_PORTS_ChannelSlewRateSelect(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK channelMask, PORTS_PIN_SLEW_RATE slewRate); Returns None. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1576 Description This function selects the slew rate for selected channel pins. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsSlewRateControl in your application to determine whether this feature is available. Preconditions None. Example // Make slew rate of pins RC5, RC8 and RC13 slowest PLIB_PORTS_ChannelSlewRateSelect(PORTS_ID_0, PORT_CHANNEL_C, 0x2120, PORTS_PIN_SLEW_RATE_SLOWEST); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel channelMask Identifies the pins for which slew rate has to be modified. Slew rate of the pins which corresponding bit is "1" get modified, slew rate of the other pins remains the same. slewRate One of the possible values of PORTS_PIN_SLEW_RATE. Function void PLIB_PORTS_ChannelSlewRateSelect ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK channelMask, PORTS_PIN_SLEW_RATE slewRate ); c) Peripheral Pin Select Functions PLIB_PORTS_RemapInput Function Input function remapping. File plib_ports.h C void PLIB_PORTS_RemapInput(PORTS_MODULE_ID index, PORTS_REMAP_INPUT_FUNCTION inputFunction, PORTS_REMAP_INPUT_PIN remapInputPin); Returns None. Description This function controls the Input function remapping. It allows user to map any of the input functionality on any of the remappable input pin. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsRemapInputOutput in your application to determine whether this feature is available. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1577 Preconditions IOLOCK bit of configuration register should be clear to allow any remapping. PLIB_DEVCON_DeviceRegistersUnlock function can be used for that purpose. Refer DEVCON PLIB (or System Service) and the specific device data sheet to find more information. Example // System Unlock PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); // Unlock PPS registers PLIB_DEVCON_DeviceRegistersUnlock(DEVCON_ID_0, DEVCON_PPS_REGISTERS); // Remapping input function 'Input Capture 1' to the Remappable pin 'RPD2' PLIB_PORTS_RemapInput(PORTS_ID_0, INPUT_FUNC_IC1, INPUT_PIN_RPD2 ); Parameters Parameters Description index Identifier for the device instance to be configured inputFunction One of the possible values of PORTS_REMAP_INPUT_FUNCTION remapInputPin One of the possible values of PORTS_REMAP_INPUT_PIN Function void PLIB_PORTS_RemapInput( PORTS_MODULE_ID index, PORTS_REMAP_INPUT_FUNCTION inputFunction, PORTS_REMAP_INPUT_PIN remapInputPin ); PLIB_PORTS_RemapOutput Function Output function remapping. File plib_ports.h C void PLIB_PORTS_RemapOutput(PORTS_MODULE_ID index, PORTS_REMAP_OUTPUT_FUNCTION outputFunction, PORTS_REMAP_OUTPUT_PIN remapOutputPin); Returns None. Description This function controls the Output function remapping. it allows user to map any of the output functionality on any of the remappable output pin. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsRemapInputOutput in your application to determine whether this feature is available. Preconditions IOLOCK bit of configuration register should be clear to allow any remapping. PLIB_DEVCON_DeviceRegistersUnlock function can be used for that purpose. Refer DEVCON PLIB (or System Service) and the specific device data sheet to find more information. Example // System Unlock PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); // Unlock PPS registers PLIB_DEVCON_DeviceRegistersUnlock(DEVCON_ID_0, DEVCON_PPS_REGISTERS); // Remapping output function 'UART3 Transmit' to the Remappable pin 'RPA14' PLIB_PORTS_RemapOutput(PORTS_ID_0, OUTPUT_FUNC_U3TX, OUTPUT_PIN_RPA14); Parameters Parameters Description index Identifier for the device instance to be configured outputFunction One of the possible values of PORTS_REMAP_OUTPUT_FUNCTION remapOutputPin One of the possible values of PORTS_REMAP_OUTPUT_PIN Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1578 Function void PLIB_PORTS_RemapOutput( PORTS_MODULE_ID index, PORTS_REMAP_OUTPUT_FUNCTION outputFunction, PORTS_REMAP_OUTPUT_PIN remapOutputPin ); d) Change Notification Functions PLIB_PORTS_ChangeNoticeDisable Function Global Change Notice disable. File plib_ports.h C void PLIB_PORTS_ChangeNoticeDisable(PORTS_MODULE_ID index); Returns None. Description This function disables the global Change Notice feature. Remarks This function is only available in devices without PPS. For PPS devices, use the PLIB_PORTS_ChangeNoticePerPortTurnOff function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNotice in your application to determine whether this feature is available. Preconditions None. Example // Disable Change Notification PLIB_PORTS_ChangeNoticeDisable(PORTS_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_PORTS_ChangeNoticeDisable( PORTS_MODULE_ID index ) PLIB_PORTS_ChangeNoticeEnable Function Global Change Notice enable. File plib_ports.h C void PLIB_PORTS_ChangeNoticeEnable(PORTS_MODULE_ID index); Returns None. Description This function enables the global Change Notice feature. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1579 Remarks This function is only available in devices without PPS. For PPS devices, use the PLIB_PORTS_ChangeNoticePerPortTurnOn function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNotice in your application to determine whether this feature is available. Preconditions None. Example // Enable Change Notification PLIB_PORTS_ChangeNoticeEnable(PORTS_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_PORTS_ChangeNoticeEnable( PORTS_MODULE_ID index ) PLIB_PORTS_ChangeNoticeInIdleDisable Function CPU Idle halts the Change Notice operation. File plib_ports.h C void PLIB_PORTS_ChangeNoticeInIdleDisable(PORTS_MODULE_ID index); Returns None. Description This function halts the Change Notice operation when the CPU enters Idle mode. Remarks This function is only available in devices without PPS. For PPS devices, use the PLIB_PORTS_ChangeNoticeInIdlePerPortDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeInIdle in your application to determine whether this feature is available. Preconditions None. Example // Halts the Change notification operation when CPU enters Idle mode PLIB_PORTS_ChangeNoticeInIdleDisable(PORTS_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_PORTS_ChangeNoticeInIdleDisable( PORTS_MODULE_ID index ) PLIB_PORTS_ChangeNoticeInIdleEnable Function CPU Idle mode does not affect Change Notice operation. File plib_ports.h Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1580 C void PLIB_PORTS_ChangeNoticeInIdleEnable(PORTS_MODULE_ID index); Returns None. Description This function makes sure that Change Notice feature continues working in Idle mode. Remarks This function is only available in devices without PPS. For PPS devices, use the PLIB_PORTS_ChangeNoticeInIdlePerPortEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeInIdle in your application to determine whether this feature is available. Preconditions None. Example // Change notification feature will be working even when CPU goes to // Idle mode PLIB_PORTS_ChangeNoticeInIdleEnable(PORTS_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_PORTS_ChangeNoticeInIdleEnable( PORTS_MODULE_ID index ) PLIB_PORTS_ChangeNoticeInIdlePerPortDisable Function Change Notification halts in Idle mode for selected channel. File plib_ports.h C void PLIB_PORTS_ChangeNoticeInIdlePerPortDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel); Returns None. Description This function makes sure that change notification feature halts in Idle mode for the selected channel. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_ChangeNoticeInIdleDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePerPortInIdle in your application to determine whether this feature is available. Preconditions None. Example // Change notification halts in Idle mode for Port C PLIB_PORTS_ChangeNoticeInIdlePerPortDisable(PORTS_ID_0, PORT_CHANNEL_C); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1581 Function void PLIB_PORTS_ChangeNoticeInIdlePerPortDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); PLIB_PORTS_ChangeNoticeInIdlePerPortEnable Function Allows CN to be working in Idle mode for selected channel. File plib_ports.h C void PLIB_PORTS_ChangeNoticeInIdlePerPortEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel); Returns None. Description This function makes sure that change notification feature keeps working in Idle mode for the selected channel. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_ChangeNoticeInIdleEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePerPortInIdle in your application to determine whether this feature is available. Preconditions None. Example // Change notification continues working in Idle mode for Port C PLIB_PORTS_ChangeNoticeInIdlePerPortEnable(PORTS_ID_0, PORT_CHANNEL_C); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel Function void PLIB_PORTS_ChangeNoticeInIdlePerPortEnable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); PLIB_PORTS_ChangeNoticePerPortHasOccured Function File plib_ports.h C bool PLIB_PORTS_ChangeNoticePerPortHasOccured(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Description This is function PLIB_PORTS_ChangeNoticePerPortHasOccured. PLIB_PORTS_ChangeNoticePerPortTurnOff Function Disables the change notification for selected port. File plib_ports.h Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1582 C void PLIB_PORTS_ChangeNoticePerPortTurnOff(PORTS_MODULE_ID index, PORTS_CHANNEL channel); Returns None. Description This function disables the change notification for selected port. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_ChangeNoticeDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePerPortTurnOn in your application to determine whether this feature is available. Preconditions None. Example // Disable Change notification for Port C PLIB_PORTS_ChangeNoticePerPortTurnOff(PORTS_ID_0, PORT_CHANNEL_C); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel Function void PLIB_PORTS_ChangeNoticePerPortTurnOff( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); PLIB_PORTS_ChangeNoticePerPortTurnOn Function Enables the change notification for selected port. File plib_ports.h C void PLIB_PORTS_ChangeNoticePerPortTurnOn(PORTS_MODULE_ID index, PORTS_CHANNEL channel); Returns None. Description This function enables the change notification for selected port. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_ChangeNoticeEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePerPortTurnOn in your application to determine whether this feature is available. Preconditions None. Example // Enable Change notification for Port C PLIB_PORTS_ChangeNoticePerPortTurnOn(PORTS_ID_0, PORT_CHANNEL_C); Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1583 Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel Function void PLIB_PORTS_ChangeNoticePerPortTurnOn ( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); PLIB_PORTS_ChangeNoticePullDownPerPortDisable Function Disables the pull-down for selected Change Notice pins. File plib_ports.h C void PLIB_PORTS_ChangeNoticePullDownPerPortDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function disables the pull-down for selected Change Notice pins. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullDownPerPort in your application to determine whether this feature is available. Preconditions None. Example // Disable pull-down for RC5 pin PLIB_PORTS_ChangeNoticePullDownPerPortDisable(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_5); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins Function void PLIB_PORTS_ChangeNoticePullDownPerPortDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_ChangeNoticePullDownPerPortEnable Function Enables the pull-down for selected Change Notice pins. File plib_ports.h C void PLIB_PORTS_ChangeNoticePullDownPerPortEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1584 Returns None. Description This function enables the pull-down for selected Change Notice pins. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullDownPerPort in your application to determine whether this feature is available. Preconditions None. Example // Enable pull-down for RC5 pin PLIB_PORTS_ChangeNoticePullDownPerPortEnable(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_5); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins Function void PLIB_PORTS_ChangeNoticePullDownPerPortEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_ChangeNoticePullUpDisable Function Disable pull-up on input change. File plib_ports.h C void PLIB_PORTS_ChangeNoticePullUpDisable(PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum); Returns None. Description This function disables pull-up on selected input change notification pin. Remarks This function is only available in devices without PPS. For PPS devices, use the PLIB_PORTS_ChangeNoticePullUpPerPortDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUp in your application to determine whether this feature is available. Preconditions None. Example // Disable pull-up on pin CN13 PLIB_PORTS_ChangeNoticePullUpDisable(PORTS_ID_0, CN13); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1585 pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Function void PLIB_PORTS_ChangeNoticePullUpDisable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ) PLIB_PORTS_ChangeNoticePullUpEnable Function Enable pull-up on input change. File plib_ports.h C void PLIB_PORTS_ChangeNoticePullUpEnable(PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum); Returns None. Description This function enables pull-up on selected input change notification pin Remarks This function is only available in devices without PPS. For PPS devices, use the PLIB_PORTS_ChangeNoticePullUpPerPortEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUp in your application to determine whether this feature is available. Preconditions None. Example // Enable pull-up on pin CN13 PLIB_PORTS_ChangeNoticePullUpEnable(PORTS_ID_0, CN13); Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Function void PLIB_PORTS_ChangeNoticePullUpEnable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ) PLIB_PORTS_ChangeNoticePullUpPerPortDisable Function Disables weak pull-up for the selected pin. File plib_ports.h C void PLIB_PORTS_ChangeNoticePullUpPerPortDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function disables weak pull-up for the selected port pin. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1586 Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_ChangeNoticePullUpDisable function. Pull-ups on change notification pins should always be disabled when the port pin is configured as a digital output. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUpPerPort in your application to determine whether this feature is available. Preconditions None. Example // Disable pull-up for RC5 pin PLIB_PORTS_ChangeNoticePullUpPerPortDisable(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_5); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins Function void PLIB_PORTS_ChangeNoticePullUpPerPortDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); PLIB_PORTS_ChangeNoticePullUpPerPortEnable Function Enables the pull-up for selected Change Notice pins. File plib_ports.h C void PLIB_PORTS_ChangeNoticePullUpPerPortEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function enables the pull-up for selected Change Notice pins. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_ChangeNoticePullUpEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUpPerPort in your application to determine whether this feature is available. Preconditions None. Example // Enable pull-up for RC5 pin PLIB_PORTS_ChangeNoticePullUpPerPortEnable(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_5); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1587 Function void PLIB_PORTS_ChangeNoticePullUpPerPortEnable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_PinChangeNoticeDisable Function Port pin Change Notice disable. File plib_ports.h C void PLIB_PORTS_PinChangeNoticeDisable(PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum); Returns None. Description This function disables the port pin Change Notice feature. Remarks This function is only available in devices without PPS. For PPS devices, use the PLIB_PORTS_PinChangeNoticePerPortDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinChangeNotice in your application to determine whether this feature is available. Preconditions None. Example // Disable Change Notice interrupt for pin CN13 PLIB_PORTS_PinChangeNoticeDisable(PORTS_ID_0, CN13); Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Function void PLIB_PORTS_PinChangeNoticeDisable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ) PLIB_PORTS_PinChangeNoticeEnable Function Port pin Change Notice interrupt enable. File plib_ports.h C void PLIB_PORTS_PinChangeNoticeEnable(PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum); Returns None. Description This function enables the port pin Change Notice feature. Remarks This function is only available in devices without PPS. For PPS devices, use the PLIB_PORTS_PinChangeNoticePerPortEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1588 PLIB_PORTS_ExistsPinChangeNotice in your application to determine whether this feature is available. Preconditions None. Example // Enable Change Notice interrupt for pin CN13 PLIB_PORTS_PinChangeNoticeEnable(PORTS_ID_0, CN13); Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Function void PLIB_PORTS_PinChangeNoticeEnable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ) PLIB_PORTS_PinChangeNoticePerPortDisable Function Disables CN interrupt for the selected pin. File plib_ports.h C void PLIB_PORTS_PinChangeNoticePerPortDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function disables Change Notice interrupt for the selected port pin. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_PinChangeNoticeDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeIntPerPort in your application to determine whether this feature is available. Preconditions None. Example // Disable CN interrupt for RC5 pin PLIB_PORTS_PinChangeNoticePerPortDisable(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_5); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins Function void PLIB_PORTS_PinChangeNoticePerPortDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_PinChangeNoticePerPortEnable Function Enables CN interrupt for the selected pin. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1589 File plib_ports.h C void PLIB_PORTS_PinChangeNoticePerPortEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function enables Change Notice interrupt for the selected port pin. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_PinChangeNoticeEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeIntPerPort in your application to determine whether this feature is available. Preconditions None. Example // Enable CN interrupt for RC5 pin PLIB_PORTS_PinChangeNoticePerPortEnable(PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_5); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins Function void PLIB_PORTS_PinChangeNoticePerPortEnable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ) PLIB_PORTS_ChangeNoticePerPortHasOccurred Function checks the status of change on the pin File plib_ports.h C bool PLIB_PORTS_ChangeNoticePerPortHasOccurred(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos); Returns None. Description This function checks if the change has occurred on the given pin or not. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePerPortStatus in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1590 Example if(PLIB_PORTS_ChangeNoticePerPortHasOccurred( PORTS_ID_0, PORT_CHANNEL_C, PORTS_BIT_POS_4 ) == True) { //do something } Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins Function bool PLIB_PORTS_ChangeNoticePerPortHasOccurred ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); PLIB_PORTS_ChannelChangeNoticeDisable Function Disables CN interrupt for the selected pins of a channel. File plib_ports.h C void PLIB_PORTS_ChannelChangeNoticeDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function Disables Change Notice interrupt for the selected port pins of a channel. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_CnPinsDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeIntPerPort in your application to determine whether this feature is available. Preconditions None. Example // Disable CN interrupt for RC5, RC8 and RC13 pins PLIB_PORTS_ChannelChangeNoticeDisable(PORTS_ID_0, PORT_CHANNEL_C, 0x2120); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel mask Identifies the pins for which change notification is to be disabled Function void PLIB_PORTS_ChannelChangeNoticeDisable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1591 PLIB_PORTS_ChannelChangeNoticeEnable Function Enables CN interrupt for the selected pins of a channel. File plib_ports.h C void PLIB_PORTS_ChannelChangeNoticeEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function enables Change Notice interrupt for the selected port pins of a channel. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_CnPinsEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeIntPerPort in your application to determine whether this feature is available. Preconditions None. Example // Enable CN interrupt for RC5, RC8 and RC13 pins PLIB_PORTS_ChannelChangeNoticeEnable(PORTS_ID_0, PORT_CHANNEL_C, 0x2120); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel mask Identifies the pins for which change notification is to be enabled Function void PLIB_PORTS_ChannelChangeNoticeEnable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); PLIB_PORTS_ChannelChangeNoticePullDownDisable Function Disables Change Notice pull-down for the selected channel pins. File plib_ports.h C void PLIB_PORTS_ChannelChangeNoticePullDownDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function Disables the Change Notice pull-down for the selected channel pins. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1592 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullDownPerPort in your application to determine whether this feature is available. Preconditions None. Example // Disable pull-down for RC5, RC8 and RC13 pins PLIB_PORTS_ChannelChangeNoticePullDownDisable(PORTS_ID_0, PORT_CHANNEL_C, 0x2120); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel mask Identifies the pins for the pull-down to be disabled Function void PLIB_PORTS_ChannelChangeNoticePullDownDisable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); PLIB_PORTS_ChannelChangeNoticePullDownEnable Function Enables Change Notice pull-down for the selected channel pins. File plib_ports.h C void PLIB_PORTS_ChannelChangeNoticePullDownEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function enables the Change Notice pull-down for the selected channel pins. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullDownPerPort in your application to determine whether this feature is available. Preconditions None. Example // Enable pull-down for RC5, RC8 and RC13 pins PLIB_PORTS_ChannelChangeNoticePullDownEnable(PORTS_ID_0, PORT_CHANNEL_C, 0x2120); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel mask Identifies the pins for the pull-down to be enabled Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1593 Function void PLIB_PORTS_ChannelChangeNoticePullDownEnable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); PLIB_PORTS_ChannelChangeNoticePullUpDisable Function Disables Change Notice pull-up for the selected channel pins. File plib_ports.h C void PLIB_PORTS_ChannelChangeNoticePullUpDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function Disables the Change Notice pull-up for the selected channel pins. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_CnPinsPullUpDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUpPerPort in your application to determine whether this feature is available. Preconditions None. Example // Disable pull-up for RC5, RC8 and RC13 pins PLIB_PORTS_ChannelChangeNoticePullUpDisable(PORTS_ID_0, PORT_CHANNEL_C, 0x2120); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel mask Identifies the pins of the pull-up to be disabled Function void PLIB_PORTS_ChannelChangeNoticePullUpDisable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); PLIB_PORTS_ChannelChangeNoticePullUpEnable Function Enables Change Notice pull-up for the selected channel pins. File plib_ports.h Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1594 C void PLIB_PORTS_ChannelChangeNoticePullUpEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask); Returns None. Description This function enables the Change Notice pull-up for the selected channel pins. Remarks This function is only available in devices with PPS. For Non-PPS devices, use the PLIB_PORTS_CnPinsPullUpEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUpPerPort in your application to determine whether this feature is available. Preconditions None. Example // Enable pull-up for RC5, RC8 and RC13 pins PLIB_PORTS_ChannelChangeNoticePullUpEnable(PORTS_ID_0, PORT_CHANNEL_C, 0x2120); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel mask Identifies the pins of the pull-up to be enabled Function void PLIB_PORTS_ChannelChangeNoticePullUpEnable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); PLIB_PORTS_ChannelChangeNoticeEdgeDisable Function Disables selected type of edge for selected CN pins. File plib_ports.h C void PLIB_PORTS_ChannelChangeNoticeEdgeDisable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK edgeRisingMask, PORTS_DATA_MASK edgeFallingMask); Returns None. Description This function Disables selected type of edge (falling or rising) for selected CN pins of a port channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeEdgeControl in your application to determine whether this feature is available. Preconditions Change Notice method should be selected as "PORTS_CHANGE_NOTICE_METHOD_EDGE_DETECT" using PLIB_PORTS_ChannelChangeNoticeMethodSelect before using this function. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1595 Example // Disable Change Notice at rising edge for RC1 pin and at falling edge for // RC1 & RC5 pins. PLIB_PORTS_ChannelChangeNoticeEdgeDisable(PORTS_ID_0, PORT_CHANNEL_C, 0x0002, 0x0022); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel edgeRisingMask Identifies the pins for which Change Notice has to be enabled for rising edge. Change notice interrupt at rising edge is enabled for the pins which corresponding bit is '1', for the other pins it remains the same. edgeFallingMask Identifies the pins for which Change Notice has to be enabled for falling edge. Change notice interrupt at falling edge is enabled for the pins which corresponding bit is '1', for the other pins it remains the same. Function void PLIB_PORTS_ChannelChangeNoticeEdgeDisable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK edgeRisingMask, PORTS_DATA_MASK edgeFallingMask ); PLIB_PORTS_ChannelChangeNoticeEdgeEnable Function Enables selected type of edge for selected CN pins. File plib_ports.h C void PLIB_PORTS_ChannelChangeNoticeEdgeEnable(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK edgeRisingMask, PORTS_DATA_MASK edgeFallingMask); Returns None. Description This function Enables selected type of edge (falling or rising) for selected CN pins of a port channel. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeEdgeControl in your application to determine whether this feature is available. Preconditions Change Notice method should be selected as "PORTS_CHANGE_NOTICE_METHOD_EDGE_DETECT" using PLIB_PORTS_ChannelChangeNoticeMethodSelect before using this function. Example // Enable Change Notice at rising edge for RC1 pin and at falling edge for // RC1 & RC5 pins. PLIB_PORTS_ChannelChangeNoticeEdgeEnable(PORTS_ID_0, PORT_CHANNEL_C, 0x0002, 0x0022); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1596 edgeRisingMask Identifies the pins for which Change Notice has to be enabled for rising edge. Change Notice interrupt at rising edge is enabled for the pins which corresponding bit is '1', for the other pins it remains the same. edgeFallingMask Identifies the pins for which Change Notice has to be enabled for falling edge. Change Notice interrupt at falling edge is enabled for the pins which corresponding bit is '1', for the other pins it remains the same. Function void PLIB_PORTS_ChannelChangeNoticeEdgeEnable ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK edgeRisingMask, PORTS_DATA_MASK edgeFallingMask ); PLIB_PORTS_ChannelChangeNoticeMethodGet Function Gets the Change Notice style for the selected port channel. File plib_ports.h C PORTS_CHANGE_NOTICE_METHOD PLIB_PORTS_ChannelChangeNoticeMethodGet(PORTS_MODULE_ID index, PORTS_CHANNEL channel); Returns One of the possible values of PORTS_CHANGE_NOTICE_METHOD. Description This function gets the Change Notice style (or method) for the selected port channel. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChannelChangeNoticeMethod in your application to determine whether this feature is available. Preconditions None. Example PORTS_CHANGE_NOTICE_METHOD changeNoticeMethod; changeNoticeMethod = PLIB_PORTS_ChannelChangeNoticeMethodGet(PORTS_ID_0, PORT_CHANNEL_C); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel Function PORTS_CHANGE_NOTICE_METHOD PLIB_PORTS_ChannelChangeNoticeMethodGet ( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); PLIB_PORTS_ChannelChangeNoticeMethodSelect Function Selects the Change Notice style for selected port channel. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1597 File plib_ports.h C void PLIB_PORTS_ChannelChangeNoticeMethodSelect(PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_CHANGE_NOTICE_METHOD changeNoticeMethod); Returns None. Description This function selects the Change Notice style (or method) for selected port channel. It allows user to select whether the Change Notice detection will happen based on edge transition or level transition on all the CN pins of a particular channel. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChannelChangeNoticeMethod in your application to determine whether this feature is available. Preconditions None. Example PLIB_PORTS_ChannelChangeNoticeMethodSelect(PORTS_ID_0, PORT_CHANNEL_C, PORTS_CHANGE_NOTICE_METHOD_EDGE_DETECT); Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel changeNoticeMethod One of the possible values of PORTS_CHANGE_NOTICE_METHOD. Function void PLIB_PORTS_ChannelChangeNoticeMethodSelect ( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_CHANGE_NOTICE_METHOD changeNoticeMethod ); PLIB_PORTS_AnPinsModeSelect Function Enables the selected AN pins as analog or digital. File plib_ports.h C void PLIB_PORTS_AnPinsModeSelect(PORTS_MODULE_ID index, PORTS_AN_PIN anPins, PORTS_PIN_MODE mode); Returns None. Description This function enables the selected AN pins as analog or digital. Remarks This function is only available in devices without PPS feature. For PPS devices, use the PLIB_PORTS_ChannelModeSelect function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsAnPinsMode in your application to determine whether this feature is available. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1598 Preconditions None. Example // Make pins AN5, AN8 and AN13 Analog PLIB_PORTS_AnPinsModeSelect(PORTS_ID_0, PORTS_AN_PIN_5 | PORTS_AN_PIN_8 | PORTS_AN_PIN_13, PORTS_PIN_MODE_ANALOG); Parameters Parameters Description index Identifier for the device instance to be configured anPins AN pins whose mode is to be changed. Multiple AN pins can be ORed. mode Possible values of PORTS_PIN_MODE (Analog or Digital) Function void PLIB_PORTS_AnPinsModeSelect ( PORTS_MODULE_ID index, PORTS_AN_PIN anPins, PORTS_PIN_MODE mode ); PLIB_PORTS_CnPinsDisable Function Disables CN interrupt for the selected pins of a channel. File plib_ports.h C void PLIB_PORTS_CnPinsDisable(PORTS_MODULE_ID index, PORTS_CN_PIN cnPins); Returns None. Description This function Disables Change Notice interrupt for the selected port pins of a channel. Remarks This function is only available in devices without PPS feature. For PPS devices, use the PLIB_PORTS_ChannelChangeNoticeDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinChangeNotice in your application to determine whether this feature is available. Preconditions None. Example // Disable CN interrupt for CN5, CN8 and CN13 pins PLIB_PORTS_CnPinsDisable(PORTS_ID_0, CHANGE_NOTICE_PIN_5 | CHANGE_NOTICE_PIN_8 | CHANGE_NOTICE_PIN_13); Parameters Parameters Description index Identifier for the device instance to be configured cnPins CN pins to be disabled. Multiple CN pins can be ORed. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1599 Function void PLIB_PORTS_CnPinsDisable ( PORTS_MODULE_ID index, PORTS_CN_PIN cnPins ); PLIB_PORTS_CnPinsEnable Function Enables CN interrupt for the selected pins of a channel. File plib_ports.h C void PLIB_PORTS_CnPinsEnable(PORTS_MODULE_ID index, PORTS_CN_PIN cnPins); Returns None. Description This function enables Change Notice interrupt for the selected port pins of a channel. Remarks This function is only available in devices without PPS feature. For PPS devices, use the PLIB_PORTS_ChannelChangeNoticeEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinChangeNotice in your application to determine whether this feature is available. Preconditions None. Example // Enable CN interrupt for CN5, CN8 and CN13 pins PLIB_PORTS_CnPinsEnable(PORTS_ID_0, CHANGE_NOTICE_PIN_5 | CHANGE_NOTICE_PIN_8 | CHANGE_NOTICE_PIN_13); Parameters Parameters Description index Identifier for the device instance to be configured cnPins CN pins to be enabled. Multiple CN pins can be ORed. Function void PLIB_PORTS_CnPinsEnable ( PORTS_MODULE_ID index, PORTS_CN_PIN cnPins ); PLIB_PORTS_CnPinsPullUpDisable Function Disables Change Notice pull-up for the selected channel pins. File plib_ports.h C void PLIB_PORTS_CnPinsPullUpDisable(PORTS_MODULE_ID index, PORTS_CN_PIN cnPins); Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1600 Returns None. Description This function Disables the Change Notice pull-up for the selected channel pins. Remarks This function is only available in devices without PPS feature. For PPS devices, use the PLIB_PORTS_ChannelChangeNoticePullUpDisable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUp in your application to determine whether this feature is available. Preconditions None. Example // Disable pull-up for CN5, CN8 and CN13 pins PLIB_PORTS_CnPinsPullUpDisable(PORTS_ID_0, CHANGE_NOTICE_PIN_5 | CHANGE_NOTICE_PIN_8 | CHANGE_NOTICE_PIN_13); Parameters Parameters Description index Identifier for the device instance to be configured cnPins CN pins whose pull-up is to be disabled. Multiple CN pins can be ORed. Function void PLIB_PORTS_CnPinsPullUpDisable ( PORTS_MODULE_ID index, PORTS_CN_PIN cnPins ); PLIB_PORTS_CnPinsPullUpEnable Function Enables Change Notice pull-up for the selected channel pins. File plib_ports.h C void PLIB_PORTS_CnPinsPullUpEnable(PORTS_MODULE_ID index, PORTS_CN_PIN cnPins); Returns None. Description This function enables the Change Notice pull-up for the selected channel pins. Remarks This function is only available in devices without PPS feature. For PPS devices, use the PLIB_PORTS_ChannelChangeNoticePullUpEnable function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUp in your application to determine whether this feature is available. Preconditions None. Example // Enable pull-up for CN5, CN8 and CN13 pins Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1601 PLIB_PORTS_CnPinsPullUpEnable(PORTS_ID_0, CHANGE_NOTICE_PIN_5 | CHANGE_NOTICE_PIN_8 | CHANGE_NOTICE_PIN_13); Parameters Parameters Description index Identifier for the device instance to be configured cnPins CN pins whose pull-up is to be enabled. Multiple CN pins can be ORed. Function void PLIB_PORTS_CnPinsPullUpEnable ( PORTS_MODULE_ID index, PORTS_CN_PIN cnPins ); e) Feature Existence Functions PLIB_PORTS_ExistsChangeNotice Function Identifies whether the ChangeNotice feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChangeNotice(PORTS_MODULE_ID index); Returns • true - The ChangeNotice feature is supported on the device • false - The ChangeNotice feature is not supported on the device Description This function identifies whether the ChangeNotice feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticeEnable • PLIB_PORTS_ChangeNoticeDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNotice( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsChangeNoticeInIdle Function Identifies whether the ChangeNoticeInIdle feature exists on the Ports module. File plib_ports.h Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1602 C bool PLIB_PORTS_ExistsChangeNoticeInIdle(PORTS_MODULE_ID index); Returns • true - The ChangeNoticeInIdle feature is supported on the device • false - The ChangeNoticeInIdle feature is not supported on the device Description This function identifies whether the ChangeNoticeInIdle feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticeInIdleEnable • PLIB_PORTS_ChangeNoticeInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNoticeInIdle( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsChangeNoticePerPortInIdle Function Identifies whether the ChangeNoticeInIdlePerPort feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChangeNoticePerPortInIdle(PORTS_MODULE_ID index); Returns • true - The ChangeNoticeInIdlePerPort feature is supported on the device • false - The ChangeNoticeInIdlePerPort feature is not supported on the device Description This function identifies whether the ChangeNoticeInIdlePerPort feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticeInIdlePerPortEnable • PLIB_PORTS_ChangeNoticeInIdlePerPortDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNoticePerPortInIdle( PORTS_MODULE_ID index ) Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1603 PLIB_PORTS_ExistsChangeNoticePerPortStatus Function Identifies whether the ChangeNoticePerPortStatus feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChangeNoticePerPortStatus(PORTS_MODULE_ID index); Returns • true - The ChangeNoticePerPortStatus feature is supported on the device • false - The ChangeNoticePerPortStatus feature is not supported on the device Description This function identifies whether the ChangeNoticePerPortStatus feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePerPortHasOccured • PLIB_PORTS_ChangeNoticePerPortHasOccurred Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNoticePerPortStatus( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsChangeNoticePerPortTurnOn Function Identifies whether the ChangeNoticePerPortTurnOn feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChangeNoticePerPortTurnOn(PORTS_MODULE_ID index); Returns • true - The ChangeNoticePerPortTurnOn feature is supported on the device • false - The ChangeNoticePerPortTurnOn feature is not supported on the device Description This function identifies whether the ChangeNoticePerPortTurnOn feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePerPortTurnOn • PLIB_PORTS_ChangeNoticePerPortTurnOff Remarks None. Preconditions None. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1604 Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNoticePerPortTurnOn( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsChangeNoticePullDownPerPort Function Identifies whether the ChangeNoticePullDownPerPort feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChangeNoticePullDownPerPort(PORTS_MODULE_ID index); Returns • true - The ChangeNoticePullDownPerPort feature is supported on the device • false - The ChangeNoticePullDownPerPort feature is not supported on the device Description This function identifies whether the ChangeNoticePullDownPerPort feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePullDownPerPortEnable • PLIB_PORTS_ChangeNoticePullDownPerPortDisable • PLIB_PORTS_ChannelChangeNoticePullDownEnable • PLIB_PORTS_ChannelChangeNoticePullDownDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNoticePullDownPerPort( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsChangeNoticePullUp Function Identifies whether the ChangeNoticePullup feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChangeNoticePullUp(PORTS_MODULE_ID index); Returns • true - The ChangeNoticePullup feature is supported on the device • false - The ChangeNoticePullup feature is not supported on the device Description This function identifies whether the ChangeNoticePullup feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePullUpEnable Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1605 • PLIB_PORTS_ChangeNoticePullUpDisable • PLIB_PORTS_CnPinsPullUpEnable • PLIB_PORTS_CnPinsPullUpDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNoticePullUp( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsChangeNoticePullUpPerPort Function Identifies whether the ChangeNoticePullUpPerPort feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChangeNoticePullUpPerPort(PORTS_MODULE_ID index); Returns • true - The ChangeNoticePullUpPerPort feature is supported on the device • false - The ChangeNoticePullUpPerPort feature is not supported on the device Description This function identifies whether the ChangeNoticePullUpPerPort feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePullUpPerPortEnable • PLIB_PORTS_ChangeNoticePullUpPerPortDisable • PLIB_PORTS_ChannelChangeNoticePullUpEnable • PLIB_PORTS_ChannelChangeNoticePullUpDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNoticePullUpPerPort( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsPinChangeNotice Function Identifies whether the PinChangeNotice feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsPinChangeNotice(PORTS_MODULE_ID index); Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1606 Returns • true - The PinChangeNotice feature is supported on the device • false - The PinChangeNotice feature is not supported on the device Description This function identifies whether the PinChangeNotice feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinChangeNoticeEnable • PLIB_PORTS_PinChangeNoticeDisable • PLIB_PORTS_CnPinsEnable • PLIB_PORTS_CnPinsDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsPinChangeNotice( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsPinChangeNoticePerPort Function Identifies whether the PinChangeNoticePerPort feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsPinChangeNoticePerPort(PORTS_MODULE_ID index); Returns • true - The PinChangeNoticePerPort feature is supported on the device • false - The PinChangeNoticePerPort feature is not supported on the device Description This function identifies whether the PinChangeNoticePerPort feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinChangeNoticePerPortEnable • PLIB_PORTS_PinChangeNoticePerPortDisable • PLIB_PORTS_ChannelChangeNoticeEnable • PLIB_PORTS_ChannelChangeNoticeDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsPinChangeNoticePerPort( PORTS_MODULE_ID index ) Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1607 PLIB_PORTS_ExistsPinMode Function Identifies whether the PinMode feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsPinMode(PORTS_MODULE_ID index); Returns • true - The PinMode feature is supported on the device • false - The PinMode feature is not supported on the device Description This function identifies whether the PinMode (Analog Pin or Digital Pin) feature is available on the Ports module. When this function returns true, this function is supported on the device: • PLIB_PORTS_PinModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsPinMode( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsPinModePerPort Function Identifies whether the PinModePerPort feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsPinModePerPort(PORTS_MODULE_ID index); Returns • true - The PinModePerPort feature is supported on the device • false - The PinModePerPort feature is not supported on the device Description This function identifies whether the PinModePerPort (Analog Pin or Digital Pin) feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinModePerPortSelect • PLIB_PORTS_ChannelModeSelect Remarks None. Preconditions None. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1608 Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsPinModePerPort( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsPortsDirection Function Identifies whether the PortsDirection feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsPortsDirection(PORTS_MODULE_ID index); Returns • true - The PortsDirection feature is supported on the device • false - The PortsDirection feature is not supported on the device Description This function identifies whether the PortsDirection feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinDirectionInputSet • PLIB_PORTS_PinDirectionOutputSet • PLIB_PORTS_DirectionInputSet • PLIB_PORTS_DirectionOutputSet • PLIB_PORTS_DirectionGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsPortsDirection( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsPortsOpenDrain Function Identifies whether the PortsOpenDrain feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsPortsOpenDrain(PORTS_MODULE_ID index); Returns • true - The PortsOpenDrain feature is supported on the device • false - The PortsOpenDrain feature is not supported on the device Description This function identifies whether the PortsOpenDrain feature is available on the Ports module. When this function returns true, these functions are supported on the device: Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1609 • PLIB_PORTS_PinOpenDrainEnable • PLIB_PORTS_PinOpenDrainDisable • PLIB_PORTS_OpenDrainEnable • PLIB_PORTS_OpenDrainDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsPortsOpenDrain( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsPortsRead Function Identifies whether the PortsRead feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsPortsRead(PORTS_MODULE_ID index); Returns • true - The PortsRead feature is supported on the device • false - The PortsRead feature is not supported on the device Description This function identifies whether the PortsRead feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinGet • PLIB_PORTS_Read Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsPortsRead( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsPortsWrite Function Identifies whether the PortsWrite feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsPortsWrite(PORTS_MODULE_ID index); Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1610 Returns • true - The PortsWrite feature is supported on the device • false - The PortsWrite feature is not supported on the device Description This function identifies whether the PortsWrite feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinWrite • PLIB_PORTS_PinSet • PLIB_PORTS_PinClear • PLIB_PORTS_PinToggle • PLIB_PORTS_Write • PLIB_PORTS_Set • PLIB_PORTS_Toggle • PLIB_PORTS_Clear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsPortsWrite( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsRemapInput Function Identifies whether the RemapInput feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsRemapInput(PORTS_MODULE_ID index); Returns • true - The RemapInput feature is supported on the device • false - The RemapInput feature is not supported on the device Description This function identifies whether the RemapInput feature is available on the Ports module. When this function returns true, this function is supported on the device: • PLIB_PORTS_RemapInput Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsRemapInput( PORTS_MODULE_ID index ) Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1611 PLIB_PORTS_ExistsRemapOutput Function Identifies whether the RemapOutput feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsRemapOutput(PORTS_MODULE_ID index); Returns • true - The RemapOutput feature is supported on the device • false - The RemapOutput feature is not supported on the device Description This function identifies whether the RemapOutput feature is available on the Ports module. When this function returns true, this function is supported on the device: • PLIB_PORTS_RemapOutput Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsRemapOutput( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsLatchRead Function Identifies whether the LatchRead feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsLatchRead(PORTS_MODULE_ID index); Returns • true - The LatchRead feature is supported on the device • false - The LatchRead feature is not supported on the device Description This function identifies whether the LatchRead feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinGetLatched • PLIB_PORTS_ReadLatched Remarks None. Preconditions None. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1612 Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsLatchRead( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsAnPinsMode Function Identifies whether the AnPinsMode feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsAnPinsMode(PORTS_MODULE_ID index); Returns • true - The AnPinsMode feature is supported on the device • false - The AnPinsMode feature is not supported on the device Description This function identifies whether the AnPinsMode feature is available on the Ports module. When this function returns true, this function is supported on the device: • PLIB_PORTS_AnPinsModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsAnPinsMode( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsChangeNoticeEdgeControl Function Identifies whether the ChangeNoticeEdgeControl feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChangeNoticeEdgeControl(PORTS_MODULE_ID index); Returns • true - The ChangeNoticeEdgeControl feature is supported on the device • false - The ChangeNoticeEdgeControl feature is not supported on the device Description This function identifies whether the ChangeNoticeEdgeControl feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChannelChangeNoticeEdgeEnable • PLIB_PORTS_ChannelChangeNoticeEdgeDisable • PLIB_PORTS_PinChangeNoticeEdgeIsEnabled Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1613 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNoticeEdgeControl( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsChangeNoticeEdgeStatus Function Identifies whether the ChangeNoticeEdgeStatus feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChangeNoticeEdgeStatus(PORTS_MODULE_ID index); Returns • true - The ChangeNoticeEdgeStatus feature is supported on the device • false - The ChangeNoticeEdgeStatus feature is not supported on the device Description This function identifies whether the ChangeNoticeEdgeStatus feature is available on the Ports module. When this function returns true, this function is supported on the device: • PLIB_PORTS_PinChangeNoticeEdgeHasOccurred Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChangeNoticeEdgeStatus( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsChannelChangeNoticeMethod Function Identifies whether the ChannelChangeNoticeMethod feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsChannelChangeNoticeMethod(PORTS_MODULE_ID index); Returns • true - The ChannelChangeNoticeMethod feature is supported on the device • false - The ChannelChangeNoticeMethod feature is not supported on the device Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1614 Description This function identifies whether the ChannelChangeNoticeMethod feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChannelChangeNoticeMethodSelect • PLIB_PORTS_ChannelChangeNoticeMethodGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsChannelChangeNoticeMethod( PORTS_MODULE_ID index ) PLIB_PORTS_ExistsSlewRateControl Function Identifies whether the SlewRateControl feature exists on the Ports module. File plib_ports.h C bool PLIB_PORTS_ExistsSlewRateControl(PORTS_MODULE_ID index); Returns • true - The SlewRateControl feature is supported on the device • false - The SlewRateControl feature is not supported on the device Description This function identifies whether the SlewRateControl feature is available on the Ports module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChannelSlewRateSelect • PLIB_PORTS_PinSlewRateGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_PORTS_ExistsSlewRateControl( PORTS_MODULE_ID index ) f) Data Types and Constants PORTS_ANALOG_PIN Enumeration Data type defining the different analog input pins. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1615 File help_plib_ports.h C typedef enum { PORTS_ANALOG_PIN_0 , PORTS_ANALOG_PIN_1 , PORTS_ANALOG_PIN_2 , PORTS_ANALOG_PIN_3 , PORTS_ANALOG_PIN_4 , PORTS_ANALOG_PIN_5 , PORTS_ANALOG_PIN_6 , PORTS_ANALOG_PIN_7 , PORTS_ANALOG_PIN_8 , PORTS_ANALOG_PIN_9 , PORTS_ANALOG_PIN_10 , PORTS_ANALOG_PIN_11 , PORTS_ANALOG_PIN_12 , PORTS_ANALOG_PIN_13 , PORTS_ANALOG_PIN_14 , PORTS_ANALOG_PIN_15 , PORTS_ANALOG_PIN_16 , PORTS_ANALOG_PIN_17 , PORTS_ANALOG_PIN_18 , PORTS_ANALOG_PIN_19 , PORTS_ANALOG_PIN_20 , PORTS_ANALOG_PIN_21 , PORTS_ANALOG_PIN_22 , PORTS_ANALOG_PIN_23 , PORTS_ANALOG_PIN_24 , PORTS_ANALOG_PIN_25 , PORTS_ANALOG_PIN_26 , PORTS_ANALOG_PIN_27 , PORTS_ANALOG_PIN_28 , PORTS_ANALOG_PIN_29 , PORTS_ANALOG_PIN_30 , PORTS_ANALOG_PIN_31 , PORTS_ANALOG_PIN_32 , PORTS_ANALOG_PIN_33 , PORTS_ANALOG_PIN_34 , PORTS_ANALOG_PIN_35 , PORTS_ANALOG_PIN_36 , PORTS_ANALOG_PIN_37 , PORTS_ANALOG_PIN_38 , PORTS_ANALOG_PIN_39 , PORTS_ANALOG_PIN_40 , PORTS_ANALOG_PIN_41 , PORTS_ANALOG_PIN_42 , PORTS_ANALOG_PIN_43 , PORTS_ANALOG_PIN_44 , PORTS_ANALOG_PIN_45 , PORTS_ANALOG_PIN_46 , PORTS_ANALOG_PIN_47 , PORTS_ANALOG_PIN_48 , PORTS_ANALOG_PIN_49 } PORTS_ANALOG_PIN; Members Members Description PORTS_ANALOG_PIN_0 Analog Input Pin 0 PORTS_ANALOG_PIN_1 Analog Input Pin 1 PORTS_ANALOG_PIN_2 Analog Input Pin 2 PORTS_ANALOG_PIN_3 Analog Input Pin 3 PORTS_ANALOG_PIN_4 Analog Input Pin 4 PORTS_ANALOG_PIN_5 Analog Input Pin 5 PORTS_ANALOG_PIN_6 Analog Input Pin 6 PORTS_ANALOG_PIN_7 Analog Input Pin 7 PORTS_ANALOG_PIN_8 Analog Input Pin 8 Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1616 PORTS_ANALOG_PIN_9 Analog Input Pin 9 PORTS_ANALOG_PIN_10 Analog Input Pin 10 PORTS_ANALOG_PIN_11 Analog Input Pin 11 PORTS_ANALOG_PIN_12 Analog Input Pin 12 PORTS_ANALOG_PIN_13 Analog Input Pin 13 PORTS_ANALOG_PIN_14 Analog Input Pin 14 PORTS_ANALOG_PIN_15 Analog Input Pin 15 PORTS_ANALOG_PIN_16 Analog Input Pin 16 PORTS_ANALOG_PIN_17 Analog Input Pin 17 PORTS_ANALOG_PIN_18 Analog Input Pin 18 PORTS_ANALOG_PIN_19 Analog Input Pin 19 PORTS_ANALOG_PIN_20 Analog Input Pin 20 PORTS_ANALOG_PIN_21 Analog Input Pin 21 PORTS_ANALOG_PIN_22 Analog Input Pin 22 PORTS_ANALOG_PIN_23 Analog Input Pin 23 PORTS_ANALOG_PIN_24 Analog Input Pin 24 PORTS_ANALOG_PIN_25 Analog Input Pin 25 PORTS_ANALOG_PIN_26 Analog Input Pin 26 PORTS_ANALOG_PIN_27 Analog Input Pin 27 PORTS_ANALOG_PIN_28 Analog Input Pin 28 PORTS_ANALOG_PIN_29 Analog Input Pin 29 PORTS_ANALOG_PIN_30 Analog Input Pin 30 PORTS_ANALOG_PIN_31 Analog Input Pin 31 PORTS_ANALOG_PIN_32 Analog Input Pin 32 PORTS_ANALOG_PIN_33 Analog Input Pin 33 PORTS_ANALOG_PIN_34 Analog Input Pin 34 PORTS_ANALOG_PIN_35 Analog Input Pin 35 PORTS_ANALOG_PIN_36 Analog Input Pin 36 PORTS_ANALOG_PIN_37 Analog Input Pin 37 PORTS_ANALOG_PIN_38 Analog Input Pin 38 PORTS_ANALOG_PIN_39 Analog Input Pin 39 PORTS_ANALOG_PIN_40 Analog Input Pin 40 PORTS_ANALOG_PIN_41 Analog Input Pin 41 PORTS_ANALOG_PIN_42 Analog Input Pin 42 PORTS_ANALOG_PIN_43 Analog Input Pin 43 PORTS_ANALOG_PIN_44 Analog Input Pin 44 PORTS_ANALOG_PIN_45 Analog Input Pin 45 PORTS_ANALOG_PIN_46 Analog Input Pin 46 PORTS_ANALOG_PIN_47 Analog Input Pin 47 PORTS_ANALOG_PIN_48 Analog Input Pin 48 PORTS_ANALOG_PIN_49 Analog Input Pin 49 Description PORTS Analog input pins This data type defines the different analog input pins. Remarks Values of these AN Pin enums are different from the other similar enumerators by name PORTS_AN_PIN. These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_BIT_POS Enumeration Lists the constants that hold different PORTS bit positions. File help_plib_ports.h Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1617 C typedef enum { PORTS_BIT_POS_0, PORTS_BIT_POS_1, PORTS_BIT_POS_2, PORTS_BIT_POS_3, PORTS_BIT_POS_4, PORTS_BIT_POS_5, PORTS_BIT_POS_6, PORTS_BIT_POS_7, PORTS_BIT_POS_8, PORTS_BIT_POS_9, PORTS_BIT_POS_10, PORTS_BIT_POS_11, PORTS_BIT_POS_12, PORTS_BIT_POS_13, PORTS_BIT_POS_14, PORTS_BIT_POS_15 } PORTS_BIT_POS; Members Members Description PORTS_BIT_POS_0 PORT bit position 0 PORTS_BIT_POS_1 PORT bit position 1 PORTS_BIT_POS_2 PORT bit position 2 PORTS_BIT_POS_3 PORT bit position 3 PORTS_BIT_POS_4 PORT bit position 4 PORTS_BIT_POS_5 PORT bit position 5 PORTS_BIT_POS_6 PORT bit position 6 PORTS_BIT_POS_7 PORT bit position 7 PORTS_BIT_POS_8 PORT bit position 8 PORTS_BIT_POS_9 PORT bit position 9 PORTS_BIT_POS_10 PORT bit position 10 PORTS_BIT_POS_11 PORT bit position 11 PORTS_BIT_POS_12 PORT bit position 12 PORTS_BIT_POS_13 PORT bit position 13 PORTS_BIT_POS_14 PORT bit position 14 PORTS_BIT_POS_15 PORT bit position 15 Description PORTS bit positions Lists the constants that hold different PORTS bit positions. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_CHANGE_NOTICE_PIN Enumeration Data type defining the different Change Notification (CN) pins enumerations. File help_plib_ports.h C typedef enum { CN0, CN1, CN2, CN3, CN4, CN5, CN6, CN7, Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1618 CN8, CN9, CN10, CN11, CN12, CN13, CN14, CN15, CN16, CN17, CN18, CN19, CN20, CN21 } PORTS_CHANGE_NOTICE_PIN; Members Members Description CN0 Change Notification Pin 0 CN1 Change Notification Pin 1 CN2 Change Notification Pin 2 CN3 Change Notification Pin 3 CN4 Change Notification Pin 4 CN5 Change Notification Pin 5 CN6 Change Notification Pin 6 CN7 Change Notification Pin 7 CN8 Change Notification Pin 8 CN9 Change Notification Pin 9 CN10 Change Notification Pin 10 CN11 Change Notification Pin 11 CN12 Change Notification Pin 12 CN13 Change Notification Pin 13 CN14 Change Notification Pin 14 CN15 Change Notification Pin 15 CN16 Change Notification Pin 16 CN17 Change Notification Pin 17 CN18 Change Notification Pin 18 CN19 Change Notification Pin 19 CN20 Change Notification Pin 20 CN21 Change Notification Pin 21 Description Change Notification Pins enumeration This data type defines the different CN pins enumerations. Remarks Values of these CN Pin enums are different from the other similar enumerators by name PORTS_CN_PIN. These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_CHANNEL Enumeration Identifies the available Ports channels. File help_plib_ports.h C typedef enum { PORT_CHANNEL_A, PORT_CHANNEL_B, PORT_CHANNEL_C, PORT_CHANNEL_D, Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1619 PORT_CHANNEL_E, PORT_CHANNEL_F, PORT_CHANNEL_G, PORT_CHANNEL_H, PORT_CHANNEL_J, PORT_CHANNEL_K } PORTS_CHANNEL; Members Members Description PORT_CHANNEL_A Port A PORT_CHANNEL_B Port B PORT_CHANNEL_C Port C PORT_CHANNEL_D Port D PORT_CHANNEL_E Port E PORT_CHANNEL_F Port F PORT_CHANNEL_G Port G PORT_CHANNEL_H Port H PORT_CHANNEL_J Port J PORT_CHANNEL_K Port K Description PORT Channel ID This enumeration identifies the available Ports channels. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules are available on all devices. Refer to the specific device data sheet to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. PORTS_DATA_MASK Type Data type defining the Ports data mask File plib_ports.h C typedef uint16_t PORTS_DATA_MASK; Description Ports data mask definition This data type defines the Ports data mask Remarks None. PORTS_DATA_TYPE Type Data type defining the Ports data type. File plib_ports.h C typedef uint32_t PORTS_DATA_TYPE; Description Ports data type definition This data type defines the Ports data type. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1620 Remarks None. PORTS_MODULE_ID Enumeration Identifies the available Ports modules. File help_plib_ports.h C typedef enum { PORTS_ID_0, PORT_NUMBER_OF_MODULES } PORTS_MODULE_ID; Members Members Description PORT_NUMBER_OF_MODULES Max number of Instances Description PORT Module ID This enumeration identifies the available Ports modules. Remarks Not all modules are available on all devices. Refer to the specific device data sheet to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. PORTS_PIN_MODE Enumeration Identifies the available pin modes. File help_plib_ports.h C typedef enum { PORTS_PIN_MODE_ANALOG, PORTS_PIN_MODE_DIGITAL } PORTS_PIN_MODE; Members Members Description PORTS_PIN_MODE_ANALOG Port Pin is in Analog Mode PORTS_PIN_MODE_DIGITAL Port pin is in Digital Mode Description PORTs Pin Mode This enumeration identifies the available pin modes. Remarks Not all modules are available on all devices. Refer to the specific device data sheet to determine which modules are supported. PORTS_REMAP_FUNCTION Enumeration Data type defining the different remap function enumerations. File help_plib_ports.h Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1621 C typedef enum { PORTS_REMAP_FUNCTION_EXT_INT1 , PORTS_REMAP_FUNCTION_EXT_INT2 , PORTS_REMAP_FUNCTION_EXT_INT3 , PORTS_REMAP_FUNCTION_EXT_INT4 , PORTS_REMAP_FUNCTION_IC1 , PORTS_REMAP_FUNCTION_IC2 , PORTS_REMAP_FUNCTION_IC3 , PORTS_REMAP_FUNCTION_IC4 , PORTS_REMAP_FUNCTION_IC5 , PORTS_REMAP_FUNCTION_IC6 , PORTS_REMAP_FUNCTION_IC7 , PORTS_REMAP_FUNCTION_IC8 , PORTS_REMAP_FUNCTION_IC9 , PORTS_REMAP_FUNCTION_OC_FAULTA , PORTS_REMAP_FUNCTION_OC_FAULTB , PORTS_REMAP_FUNCTION_SPI1_CLOCK , PORTS_REMAP_FUNCTION_SPI1_DATA , PORTS_REMAP_FUNCTION_SPI1_SLAVE_SEL , PORTS_REMAP_FUNCTION_SPI2_CLOCK , PORTS_REMAP_FUNCTION_SPI2_DATA , PORTS_REMAP_FUNCTION_SPI2_SLAVE_SEL , PORTS_REMAP_FUNCTION_SPI3_CLOCK , PORTS_REMAP_FUNCTION_SPI3_DATA , PORTS_REMAP_FUNCTION_SPI3_SLAVE_SEL , PORTS_REMAP_FUNCTION_TMR2_EXT_CLOCK , PORTS_REMAP_FUNCTION_TMR3_EXT_CLOCK , PORTS_REMAP_FUNCTION_TMR4_EXT_CLOCK , PORTS_REMAP_FUNCTION_TMR5_EXT_CLOCK , PORTS_REMAP_FUNCTION_USART1_CTS , PORTS_REMAP_FUNCTION_USART1_RX , PORTS_REMAP_FUNCTION_USART2_CTS , PORTS_REMAP_FUNCTION_USART2_RX , PORTS_REMAP_FUNCTION_USART3_CTS , PORTS_REMAP_FUNCTION_USART3_RX , PORTS_REMAP_FUNCTION_USART4_CTS , PORTS_REMAP_FUNCTION_USART4_RX , PORTS_REMAP_FUNCTION_REFCLKI , PORTS_REMAP_FUNCTION_NULL , PORTS_REMAP_FUNCTION_C1OUT , PORTS_REMAP_FUNCTION_C2OUT , PORTS_REMAP_FUNCTION_U1TX , PORTS_REMAP_FUNCTION_U1RTS , PORTS_REMAP_FUNCTION_U2TX , PORTS_REMAP_FUNCTION_U2RTS , PORTS_REMAP_FUNCTION_SDO1 , PORTS_REMAP_FUNCTION_SCK1OUT , PORTS_REMAP_FUNCTION_SS1OUT , PORTS_REMAP_FUNCTION_SDO2 , PORTS_REMAP_FUNCTION_SCK2OUT , PORTS_REMAP_FUNCTION_SS2OUT , PORTS_REMAP_FUNCTION_OC1 , PORTS_REMAP_FUNCTION_OC2 , PORTS_REMAP_FUNCTION_OC3 , PORTS_REMAP_FUNCTION_OC4 , PORTS_REMAP_FUNCTION_OC5 , PORTS_REMAP_FUNCTION_OC6 , PORTS_REMAP_FUNCTION_OC7 , PORTS_REMAP_FUNCTION_OC8 , PORTS_REMAP_FUNCTION_U3TX , PORTS_REMAP_FUNCTION_U3RTS , PORTS_REMAP_FUNCTION_U4TX , PORTS_REMAP_FUNCTION_U4RTS , PORTS_REMAP_FUNCTION_SDO3 , PORTS_REMAP_FUNCTION_SCK3OUT , PORTS_REMAP_FUNCTION_SS3OUT , PORTS_REMAP_FUNCTION_OC9 , PORTS_REMAP_FUNCTION_C3OUT , PORTS_REMAP_FUNCTION_REFCLKO } PORTS_REMAP_FUNCTION; Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1622 Members Members Description PORTS_REMAP_FUNCTION_EXT_INT1 Input Function Name - External Interrupt 1 PORTS_REMAP_FUNCTION_EXT_INT2 Input Function Name - External Interrupt 2 PORTS_REMAP_FUNCTION_EXT_INT3 Input Function Name - External Interrupt 3 PORTS_REMAP_FUNCTION_EXT_INT4 Input Function Name - External Interrupt 4 PORTS_REMAP_FUNCTION_IC1 Input Function Name - Input Capture 1 PORTS_REMAP_FUNCTION_IC2 Input Function Name - Input Capture 2 PORTS_REMAP_FUNCTION_IC3 Input Function Name - Input Capture 3 PORTS_REMAP_FUNCTION_IC4 Input Function Name - Input Capture 4 PORTS_REMAP_FUNCTION_IC5 Input Function Name - Input Capture 5 PORTS_REMAP_FUNCTION_IC6 Input Function Name - Input Capture 6 PORTS_REMAP_FUNCTION_IC7 Input Function Name - Input Capture 7 PORTS_REMAP_FUNCTION_IC8 Input Function Name - Input Capture 8 PORTS_REMAP_FUNCTION_IC9 Input Function Name - Input Capture 9 PORTS_REMAP_FUNCTION_OC_FAULTA Input Function Name - Output Compare Fault A PORTS_REMAP_FUNCTION_OC_FAULTB Input Function Name - Output Compare Fault B PORTS_REMAP_FUNCTION_SPI1_CLOCK Input Function Name - SPI1 Clock PORTS_REMAP_FUNCTION_SPI1_DATA Input Function Name - SPI1 Data PORTS_REMAP_FUNCTION_SPI1_SLAVE_SEL Input Function Name - SPI1 Slave Select PORTS_REMAP_FUNCTION_SPI2_CLOCK Input Function Name - SPI2 Clock PORTS_REMAP_FUNCTION_SPI2_DATA Input Function Name - SPI2 Data PORTS_REMAP_FUNCTION_SPI2_SLAVE_SEL Input Function Name - SPI2 Slave Select PORTS_REMAP_FUNCTION_SPI3_CLOCK Input Function Name - SPI3 Clock PORTS_REMAP_FUNCTION_SPI3_DATA Input Function Name - SPI3 Data PORTS_REMAP_FUNCTION_SPI3_SLAVE_SEL Input Function Name - SPI3 Slave Select PORTS_REMAP_FUNCTION_TMR2_EXT_CLOCK Input Function Name - Timer2 External CLock PORTS_REMAP_FUNCTION_TMR3_EXT_CLOCK Input Function Name - Timer3 External Clock PORTS_REMAP_FUNCTION_TMR4_EXT_CLOCK Input Function Name - Timer4 External Clock PORTS_REMAP_FUNCTION_TMR5_EXT_CLOCK Input Function Name - Timer5 External Clock PORTS_REMAP_FUNCTION_USART1_CTS Input Function Name - USART1 Clear To Send PORTS_REMAP_FUNCTION_USART1_RX Input Function Name - USART1 Receive PORTS_REMAP_FUNCTION_USART2_CTS Input Function Name - USART2 Clear To Send PORTS_REMAP_FUNCTION_USART2_RX Input Function Name - USART2 Receive PORTS_REMAP_FUNCTION_USART3_CTS Input Function Name - USART3 Clear To Send PORTS_REMAP_FUNCTION_USART3_RX Input Function Name - USART3 Receive PORTS_REMAP_FUNCTION_USART4_CTS Input Function Name - USART4 Clear To Send PORTS_REMAP_FUNCTION_USART4_RX Input Function Name - USART4 Receive PORTS_REMAP_FUNCTION_REFCLKI Input Function Name - Reference Clock Input PORTS_REMAP_FUNCTION_NULL Output Function Name - Null PORTS_REMAP_FUNCTION_C1OUT Output Function Name - Comparator 1 Output PORTS_REMAP_FUNCTION_C2OUT Output Function Name - Comparator 2 Output PORTS_REMAP_FUNCTION_U1TX Output Function Name - UART1 Transmit PORTS_REMAP_FUNCTION_U1RTS Output Function Name - UART1 Request To Send PORTS_REMAP_FUNCTION_U2TX Output Function Name - UART2 Transmit PORTS_REMAP_FUNCTION_U2RTS Output Function Name - UART2 Request To Send PORTS_REMAP_FUNCTION_SDO1 Output Function Name - SPI1 Data Output PORTS_REMAP_FUNCTION_SCK1OUT Output Function Name - SPI1 Clock Output PORTS_REMAP_FUNCTION_SS1OUT Output Function Name - SPI1 Slave Select Output PORTS_REMAP_FUNCTION_SDO2 Output Function Name - SPI2 Data Output PORTS_REMAP_FUNCTION_SCK2OUT Output Function Name - SPI2 Clock Output PORTS_REMAP_FUNCTION_SS2OUT Output Function Name - SPI2 Slave Select Output PORTS_REMAP_FUNCTION_OC1 Output Function Name - Output Compare 1 PORTS_REMAP_FUNCTION_OC2 Output Function Name - Output Compare 2 Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1623 PORTS_REMAP_FUNCTION_OC3 Output Function Name - Output Compare 3 PORTS_REMAP_FUNCTION_OC4 Output Function Name - Output Compare 4 PORTS_REMAP_FUNCTION_OC5 Output Function Name - Output Compare 5 PORTS_REMAP_FUNCTION_OC6 Output Function Name - Output Compare 6 PORTS_REMAP_FUNCTION_OC7 Output Function Name - Output Compare 7 PORTS_REMAP_FUNCTION_OC8 Output Function Name - Output Compare 8 PORTS_REMAP_FUNCTION_U3TX Output Function Name - UART3 Transmit PORTS_REMAP_FUNCTION_U3RTS Output Function Name - UART3 Request To Send PORTS_REMAP_FUNCTION_U4TX Output Function Name - UART4 Transmit PORTS_REMAP_FUNCTION_U4RTS Output Function Name - UART4 Request To Send PORTS_REMAP_FUNCTION_SDO3 Output Function Name - SPI3 Data Output PORTS_REMAP_FUNCTION_SCK3OUT Output Function Name - SPI3 Clock Output PORTS_REMAP_FUNCTION_SS3OUT Output Function Name - SPI3 Slave Select Output PORTS_REMAP_FUNCTION_OC9 Output Function Name - Output Compare 9 PORTS_REMAP_FUNCTION_C3OUT Output Function Name - Comparator 3 Output PORTS_REMAP_FUNCTION_REFCLKO Output Function Name - Reference Clock Output Description Remap Function Enumeration This data type defines the different remap function enumerations. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_REMAP_INPUT_FUNCTION Enumeration Data type defining the different remap input function enumerations. File help_plib_ports.h C typedef enum { INPUT_FUNC_INT1, INPUT_FUNC_INT2, INPUT_FUNC_INT3, INPUT_FUNC_INT4, INPUT_FUNC_T2CK, INPUT_FUNC_T3CK, INPUT_FUNC_T4CK, INPUT_FUNC_T5CK, INPUT_FUNC_T6CK, INPUT_FUNC_T7CK, INPUT_FUNC_T8CK, INPUT_FUNC_T9CK, INPUT_FUNC_IC1, INPUT_FUNC_IC2, INPUT_FUNC_IC3, INPUT_FUNC_IC4, INPUT_FUNC_IC5, INPUT_FUNC_IC6, INPUT_FUNC_IC7, INPUT_FUNC_IC8, INPUT_FUNC_IC9, INPUT_FUNC_OCFA, INPUT_FUNC_OCFB, INPUT_FUNC_U1RX, INPUT_FUNC_U1CTS, INPUT_FUNC_U2RX, INPUT_FUNC_U2CTS, INPUT_FUNC_U3RX, INPUT_FUNC_U3CTS, INPUT_FUNC_U4RX, INPUT_FUNC_U4CTS, INPUT_FUNC_U5RX, Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1624 INPUT_FUNC_U5CTS, INPUT_FUNC_U6RX, INPUT_FUNC_U6CTS, INPUT_FUNC_SDI1, INPUT_FUNC_SS1, INPUT_FUNC_SDI2, INPUT_FUNC_SS2, INPUT_FUNC_SDI3, INPUT_FUNC_SS3, INPUT_FUNC_SDI4, INPUT_FUNC_SS4, INPUT_FUNC_SDI5, INPUT_FUNC_SS5, INPUT_FUNC_SDI6, INPUT_FUNC_SS6, INPUT_FUNC_C1RX, INPUT_FUNC_C2RX, INPUT_FUNC_REFCLKI1, INPUT_FUNC_REFCLKI3, INPUT_FUNC_REFCLKI4, REMAP_NOT_SUPPORTED } PORTS_REMAP_INPUT_FUNCTION; Description Remap Input Function Enumeration This data type defines the different remap input function enumerations. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_REMAP_INPUT_PIN Enumeration Data type defining the different Ports I/O input pins enumerations. File help_plib_ports.h C typedef enum { INPUT_PIN_RPD2, INPUT_PIN_RPG8, INPUT_PIN_RPF4, INPUT_PIN_RPD10, INPUT_PIN_RPF1, INPUT_PIN_RPB9, INPUT_PIN_RPB10, INPUT_PIN_RPC14, INPUT_PIN_RPB5, INPUT_PIN_RPC1, INPUT_PIN_RPD14, INPUT_PIN_RPG1, INPUT_PIN_RPA14, INPUT_PIN_RPD6, INPUT_PIN_RPD3, INPUT_PIN_RPG7, INPUT_PIN_RPF5, INPUT_PIN_RPD11, INPUT_PIN_RPF0, INPUT_PIN_RPB1, INPUT_PIN_RPE5, INPUT_PIN_RPC13, INPUT_PIN_RPB3, INPUT_PIN_RPC4, INPUT_PIN_RPD15, INPUT_PIN_RPG0, INPUT_PIN_RPA15, INPUT_PIN_RPD7, INPUT_PIN_RPD9, INPUT_PIN_RPG6, INPUT_PIN_RPB8, INPUT_PIN_RPB15, Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1625 INPUT_PIN_RPD4, INPUT_PIN_RPB0, INPUT_PIN_RPE3, INPUT_PIN_RPB7, INPUT_PIN_RPF12, INPUT_PIN_RPD12, INPUT_PIN_RPF8, INPUT_PIN_RPC3, INPUT_PIN_RPE9, INPUT_PIN_RPD1, INPUT_PIN_RPG9, INPUT_PIN_RPB14, INPUT_PIN_RPD0, INPUT_PIN_RPB6, INPUT_PIN_RPD5, INPUT_PIN_RPB2, INPUT_PIN_RPF3, INPUT_PIN_RPF13, INPUT_PIN_NC, INPUT_PIN_RPF2, INPUT_PIN_RPC2, INPUT_PIN_RPE8, INPUT_PIN_RPF7, INPUT_PIN_RPD8, INPUT_PIN_RPA0, INPUT_PIN_RPB4, INPUT_PIN_RPC7, INPUT_PIN_RPC0, INPUT_PIN_RPC5, INPUT_PIN_RPA1, INPUT_PIN_RPB11, INPUT_PIN_RPA8, INPUT_PIN_RPC8, INPUT_PIN_RPA9, INPUT_PIN_RPA2, INPUT_PIN_RPA4, INPUT_PIN_RPB13, INPUT_PIN_RPC6, INPUT_PIN_RPA3, INPUT_PIN_RPC9, PIN_REMAP_NOT_SUPPORTED } PORTS_REMAP_INPUT_PIN; Description PORTS IO Input Pins enumeration This data type defines the different Ports I/O input pins enumerations. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_REMAP_OUTPUT_FUNCTION Enumeration Data type defining the different remap output function enumerations. File help_plib_ports.h C typedef enum { OUTPUT_FUNC_U3TX, OUTPUT_FUNC_U4RTS, OUTPUT_FUNC_SDO1, OUTPUT_FUNC_SDO2, OUTPUT_FUNC_SDO3, OUTPUT_FUNC_SDO5, OUTPUT_FUNC_SS6, OUTPUT_FUNC_OC3, OUTPUT_FUNC_OC6, OUTPUT_FUNC_REFCLKO4, OUTPUT_FUNC_C2OUT, OUTPUT_FUNC_C1TX, Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1626 OUTPUT_FUNC_U1TX, OUTPUT_FUNC_U2RTS, OUTPUT_FUNC_U5TX, OUTPUT_FUNC_U6RTS, OUTPUT_FUNC_SDO4, OUTPUT_FUNC_OC4, OUTPUT_FUNC_OC7, OUTPUT_FUNC_REFCLKO1, OUTPUT_FUNC_U3RTS, OUTPUT_FUNC_U4TX, OUTPUT_FUNC_U6TX, OUTPUT_FUNC_SS1, OUTPUT_FUNC_SS3, OUTPUT_FUNC_SS4, OUTPUT_FUNC_SS5, OUTPUT_FUNC_SDO6, OUTPUT_FUNC_OC5, OUTPUT_FUNC_OC8, OUTPUT_FUNC_C1OUT, OUTPUT_FUNC_REFCLKO3, OUTPUT_FUNC_U1RTS, OUTPUT_FUNC_U2TX, OUTPUT_FUNC_U5RTS, OUTPUT_FUNC_SS2, OUTPUT_FUNC_OC2, OUTPUT_FUNC_OC1, OUTPUT_FUNC_OC9, OUTPUT_FUNC_C2TX, OUTPUT_FUNC_C3OUT, OUTPUT_FUNC_REFCLKO, OUTPUT_FUNC_NO_CONNECT } PORTS_REMAP_OUTPUT_FUNCTION; Description Remap Output Function Enumeration This data type defines the different remap output function enumerations. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_REMAP_OUTPUT_PIN Enumeration Data type defining the different Ports I/O output pins enumerations. File help_plib_ports.h C typedef enum { OUTPUT_PIN_RPA0, OUTPUT_PIN_RPA1, OUTPUT_PIN_RPA2, OUTPUT_PIN_RPA3, OUTPUT_PIN_RPA4, OUTPUT_PIN_RPA8, OUTPUT_PIN_RPA9, OUTPUT_PIN_RPA14, OUTPUT_PIN_RPA15, OUTPUT_PIN_RPB0, OUTPUT_PIN_RPB1, OUTPUT_PIN_RPB2, OUTPUT_PIN_RPB3, OUTPUT_PIN_RPB4, OUTPUT_PIN_RPB5, OUTPUT_PIN_RPB6, OUTPUT_PIN_RPB7, OUTPUT_PIN_RPB8, OUTPUT_PIN_RPB9, OUTPUT_PIN_RPB10, OUTPUT_PIN_RPB11, OUTPUT_PIN_RPB13, Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1627 OUTPUT_PIN_RPB14, OUTPUT_PIN_RPB15, OUTPUT_PIN_RPC0, OUTPUT_PIN_RPC1, OUTPUT_PIN_RPC2, OUTPUT_PIN_RPC3, OUTPUT_PIN_RPC4, OUTPUT_PIN_RPC5, OUTPUT_PIN_RPC6, OUTPUT_PIN_RPC7, OUTPUT_PIN_RPC8, OUTPUT_PIN_RPC9, OUTPUT_PIN_RPC13, OUTPUT_PIN_RPC14, OUTPUT_PIN_RPD0, OUTPUT_PIN_RPD1, OUTPUT_PIN_RPD2, OUTPUT_PIN_RPD3, OUTPUT_PIN_RPD4, OUTPUT_PIN_RPD5, OUTPUT_PIN_RPD6, OUTPUT_PIN_RPD7, OUTPUT_PIN_RPD8, OUTPUT_PIN_RPD9, OUTPUT_PIN_RPD10, OUTPUT_PIN_RPD11, OUTPUT_PIN_RPD12, OUTPUT_PIN_RPD14, OUTPUT_PIN_RPD15, OUTPUT_PIN_RPE3, OUTPUT_PIN_RPE5, OUTPUT_PIN_RPE8, OUTPUT_PIN_RPE9, OUTPUT_PIN_RPF0, OUTPUT_PIN_RPF1, OUTPUT_PIN_RPF2, OUTPUT_PIN_RPF3, OUTPUT_PIN_RPF4, OUTPUT_PIN_RPF5, OUTPUT_PIN_RPF6, OUTPUT_PIN_RPF7, OUTPUT_PIN_RPF8, OUTPUT_PIN_RPF12, OUTPUT_PIN_RPF13, OUTPUT_PIN_RPG0, OUTPUT_PIN_RPG1, OUTPUT_PIN_RPG6, OUTPUT_PIN_RPG7, OUTPUT_PIN_RPG8, OUTPUT_PIN_RPG9, REMAP_NOT_SUPPORTED } PORTS_REMAP_OUTPUT_PIN; Description PORTS IO Output Pins enumeration This data type defines the different Ports I/O output pins enumerations. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_REMAP_PIN Enumeration Data type defining the different remappable input/output enumerations. File help_plib_ports.h C typedef enum { PORTS_REMAP_PIN_RPI0, PORTS_REMAP_PIN_RPI1, Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1628 PORTS_REMAP_PIN_RPI2 , PORTS_REMAP_PIN_RPI3 , PORTS_REMAP_PIN_RPI4 , PORTS_REMAP_PIN_RPI5 , PORTS_REMAP_PIN_RPI6 , PORTS_REMAP_PIN_RPI7 , PORTS_REMAP_PIN_RPI8 , PORTS_REMAP_PIN_RPI9 , PORTS_REMAP_PIN_RPI10 , PORTS_REMAP_PIN_RPI11 , PORTS_REMAP_PIN_RPI12 , PORTS_REMAP_PIN_RPI13 , PORTS_REMAP_PIN_RPI14 , PORTS_REMAP_PIN_RPI15 , PORTS_REMAP_PIN_RPI16 , PORTS_REMAP_PIN_RPI17 , PORTS_REMAP_PIN_RPI18 , PORTS_REMAP_PIN_RPI19 , PORTS_REMAP_PIN_RPI20 , PORTS_REMAP_PIN_RPI21 , PORTS_REMAP_PIN_RPI22 , PORTS_REMAP_PIN_RPI23 , PORTS_REMAP_PIN_RPI24 , PORTS_REMAP_PIN_RPI25 , PORTS_REMAP_PIN_RPI26 , PORTS_REMAP_PIN_RPI27 , PORTS_REMAP_PIN_RPI28 , PORTS_REMAP_PIN_RPI29 , PORTS_REMAP_PIN_RPI30 , PORTS_REMAP_PIN_RPI31 , PORTS_REMAP_PIN_RPI32 , PORTS_REMAP_PIN_RPI33 , PORTS_REMAP_PIN_RPI34 , PORTS_REMAP_PIN_RPI35 , PORTS_REMAP_PIN_RPI36 , PORTS_REMAP_PIN_RPI37 , PORTS_REMAP_PIN_RPI38 , PORTS_REMAP_PIN_RPI39 , PORTS_REMAP_PIN_RPI40 , PORTS_REMAP_PIN_RPI41 , PORTS_REMAP_PIN_RPI42 , PORTS_REMAP_PIN_RPI43 , PORTS_REMAP_PIN_RPI44 , PORTS_REMAP_PIN_RPI45 , PORTS_REMAP_PIN_RP0 , PORTS_REMAP_PIN_RP1 , PORTS_REMAP_PIN_RP2 , PORTS_REMAP_PIN_RP3 , PORTS_REMAP_PIN_RP4 , PORTS_REMAP_PIN_RP5 , PORTS_REMAP_PIN_RP6 , PORTS_REMAP_PIN_RP7 , PORTS_REMAP_PIN_RP8 , PORTS_REMAP_PIN_RP9 , PORTS_REMAP_PIN_RP10 , PORTS_REMAP_PIN_RP11 , PORTS_REMAP_PIN_RP12 , PORTS_REMAP_PIN_RP13 , PORTS_REMAP_PIN_RP14 , PORTS_REMAP_PIN_RP15 , PORTS_REMAP_PIN_RP16 , PORTS_REMAP_PIN_RP17 , PORTS_REMAP_PIN_RP18 , PORTS_REMAP_PIN_RP19 , PORTS_REMAP_PIN_RP20 , PORTS_REMAP_PIN_RP21 , PORTS_REMAP_PIN_RP22 , PORTS_REMAP_PIN_RP23 , PORTS_REMAP_PIN_RP24 , PORTS_REMAP_PIN_RP25 , PORTS_REMAP_PIN_RP26 , PORTS_REMAP_PIN_RP27 , PORTS_REMAP_PIN_RP28 , PORTS_REMAP_PIN_RP29 , PORTS_REMAP_PIN_RP30 , Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1629 PORTS_REMAP_PIN_RP31 , PORTS_REMAP_PIN_RPA0 , PORTS_REMAP_PIN_RPB3 , PORTS_REMAP_PIN_RPB4 , PORTS_REMAP_PIN_RPB15 , PORTS_REMAP_PIN_RPB7 , PORTS_REMAP_PIN_RPC7 , PORTS_REMAP_PIN_RPC0 , PORTS_REMAP_PIN_RPC5 , PORTS_REMAP_PIN_RPA1 , PORTS_REMAP_PIN_RPB5 , PORTS_REMAP_PIN_RPB1 , PORTS_REMAP_PIN_RPB11 , PORTS_REMAP_PIN_RPB8 , PORTS_REMAP_PIN_RPA8 , PORTS_REMAP_PIN_RPC8 , PORTS_REMAP_PIN_RPA9 , PORTS_REMAP_PIN_RPA2 , PORTS_REMAP_PIN_RPB6 , PORTS_REMAP_PIN_RPA4 , PORTS_REMAP_PIN_RPB13 , PORTS_REMAP_PIN_RPB2 , PORTS_REMAP_PIN_RPC6 , PORTS_REMAP_PIN_RPC1 , PORTS_REMAP_PIN_RPC3 , PORTS_REMAP_PIN_RPA3 , PORTS_REMAP_PIN_RPB14 , PORTS_REMAP_PIN_RPB0 , PORTS_REMAP_PIN_RPB10 , PORTS_REMAP_PIN_RPB9 , PORTS_REMAP_PIN_RPC9 , PORTS_REMAP_PIN_RPC2 , PORTS_REMAP_PIN_RPC4 } PORTS_REMAP_PIN; Members Members Description PORTS_REMAP_PIN_RPI0 Remappable input RPI0 PORTS_REMAP_PIN_RPI1 Remappable input RPI1 PORTS_REMAP_PIN_RPI2 Remappable input RPI2 PORTS_REMAP_PIN_RPI3 Remappable input RPI3 PORTS_REMAP_PIN_RPI4 Remappable input RPI4 PORTS_REMAP_PIN_RPI5 Remappable input RPI5 PORTS_REMAP_PIN_RPI6 Remappable input RPI6 PORTS_REMAP_PIN_RPI7 Remappable input RPI7 PORTS_REMAP_PIN_RPI8 Remappable input RPI8 PORTS_REMAP_PIN_RPI9 Remappable input RPI9 PORTS_REMAP_PIN_RPI10 Remappable input RPI10 PORTS_REMAP_PIN_RPI11 Remappable input RPI11 PORTS_REMAP_PIN_RPI12 Remappable input RPI12 PORTS_REMAP_PIN_RPI13 Remappable input RPI13 PORTS_REMAP_PIN_RPI14 Remappable input RPI14 PORTS_REMAP_PIN_RPI15 Remappable input RPI15 PORTS_REMAP_PIN_RPI16 Remappable input RPI16 PORTS_REMAP_PIN_RPI17 Remappable input RPI17 PORTS_REMAP_PIN_RPI18 Remappable input RPI18 PORTS_REMAP_PIN_RPI19 Remappable input RPI19 PORTS_REMAP_PIN_RPI20 Remappable input RPI20 PORTS_REMAP_PIN_RPI21 Remappable input RPI21 PORTS_REMAP_PIN_RPI22 Remappable input RPI22 PORTS_REMAP_PIN_RPI23 Remappable input RPI23 PORTS_REMAP_PIN_RPI24 Remappable input RPI24 PORTS_REMAP_PIN_RPI25 Remappable input RPI25 PORTS_REMAP_PIN_RPI26 Remappable input RPI26 Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1630 PORTS_REMAP_PIN_RPI27 Remappable input RPI27 PORTS_REMAP_PIN_RPI28 Remappable input RPI28 PORTS_REMAP_PIN_RPI29 Remappable input RPI29 PORTS_REMAP_PIN_RPI30 Remappable input RPI30 PORTS_REMAP_PIN_RPI31 Remappable input RPI31 PORTS_REMAP_PIN_RPI32 Remappable input RPI32 PORTS_REMAP_PIN_RPI33 Remappable input RPI33 PORTS_REMAP_PIN_RPI34 Remappable input RPI34 PORTS_REMAP_PIN_RPI35 Remappable input RPI35 PORTS_REMAP_PIN_RPI36 Remappable input RPI36 PORTS_REMAP_PIN_RPI37 Remappable input RPI37 PORTS_REMAP_PIN_RPI38 Remappable input RPI38 PORTS_REMAP_PIN_RPI39 Remappable input RPI39 PORTS_REMAP_PIN_RPI40 Remappable input RPI40 PORTS_REMAP_PIN_RPI41 Remappable input RPI41 PORTS_REMAP_PIN_RPI42 Remappable input RPI42 PORTS_REMAP_PIN_RPI43 Remappable input RPI43 PORTS_REMAP_PIN_RPI44 Remappable input RPI44 PORTS_REMAP_PIN_RPI45 Remappable input RPI45 PORTS_REMAP_PIN_RP0 Remappable output RP0 PORTS_REMAP_PIN_RP1 Remappable output RP1 PORTS_REMAP_PIN_RP2 Remappable output RP2 PORTS_REMAP_PIN_RP3 Remappable output RP3 PORTS_REMAP_PIN_RP4 Remappable output RP4 PORTS_REMAP_PIN_RP5 Remappable output RP5 PORTS_REMAP_PIN_RP6 Remappable output RP6 PORTS_REMAP_PIN_RP7 Remappable output RP7 PORTS_REMAP_PIN_RP8 Remappable output RP8 PORTS_REMAP_PIN_RP9 Remappable output RP9 PORTS_REMAP_PIN_RP10 Remappable output RP10 PORTS_REMAP_PIN_RP11 Remappable output RP11 PORTS_REMAP_PIN_RP12 Remappable output RP12 PORTS_REMAP_PIN_RP13 Remappable output RP13 PORTS_REMAP_PIN_RP14 Remappable output RP14 PORTS_REMAP_PIN_RP15 Remappable output RP15 PORTS_REMAP_PIN_RP16 Remappable output RP16 PORTS_REMAP_PIN_RP17 Remappable output RP17 PORTS_REMAP_PIN_RP18 Remappable output RP18 PORTS_REMAP_PIN_RP19 Remappable output RP19 PORTS_REMAP_PIN_RP20 Remappable output RP20 PORTS_REMAP_PIN_RP21 Remappable output RP21 PORTS_REMAP_PIN_RP22 Remappable output RP22 PORTS_REMAP_PIN_RP23 Remappable output RP23 PORTS_REMAP_PIN_RP24 Remappable output RP24 PORTS_REMAP_PIN_RP25 Remappable output RP25 PORTS_REMAP_PIN_RP26 Remappable output RP26 PORTS_REMAP_PIN_RP27 Remappable output RP27 PORTS_REMAP_PIN_RP28 Remappable output RP28 PORTS_REMAP_PIN_RP29 Remappable output RP29 PORTS_REMAP_PIN_RP30 Remappable output RP30 PORTS_REMAP_PIN_RP31 Remappable output RP31 PORTS_REMAP_PIN_RPA0 Remappable output RPA0 PORTS_REMAP_PIN_RPB3 Remappable output RPB3 PORTS_REMAP_PIN_RPB4 Remappable output RPB4 PORTS_REMAP_PIN_RPB15 Remappable output RPB15 Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1631 PORTS_REMAP_PIN_RPB7 Remappable output RPB7 PORTS_REMAP_PIN_RPC7 Remappable output RPC7 PORTS_REMAP_PIN_RPC0 Remappable output RPC0 PORTS_REMAP_PIN_RPC5 Remappable output RPC5 PORTS_REMAP_PIN_RPA1 Remappable output RPA1 PORTS_REMAP_PIN_RPB5 Remappable output RPB5 PORTS_REMAP_PIN_RPB1 Remappable output RPB1 PORTS_REMAP_PIN_RPB11 Remappable output RPB11 PORTS_REMAP_PIN_RPB8 Remappable output RPB8 PORTS_REMAP_PIN_RPA8 Remappable output RPA8 PORTS_REMAP_PIN_RPC8 Remappable output RPC8 PORTS_REMAP_PIN_RPA9 Remappable output RPA9 PORTS_REMAP_PIN_RPA2 Remappable output RPA2 PORTS_REMAP_PIN_RPB6 Remappable output RPB6 PORTS_REMAP_PIN_RPA4 Remappable output RPA4 PORTS_REMAP_PIN_RPB13 Remappable output RPB13 PORTS_REMAP_PIN_RPB2 Remappable output RPB2 PORTS_REMAP_PIN_RPC6 Remappable output RPC6 PORTS_REMAP_PIN_RPC1 Remappable output RPC1 PORTS_REMAP_PIN_RPC3 Remappable output RPC3 PORTS_REMAP_PIN_RPA3 Remappable output RPA3 PORTS_REMAP_PIN_RPB14 Remappable output RPB14 PORTS_REMAP_PIN_RPB0 Remappable output RPB0 PORTS_REMAP_PIN_RPB10 Remappable output RPB10 PORTS_REMAP_PIN_RPB9 Remappable output RPB9 PORTS_REMAP_PIN_RPC9 Remappable output RPC9 PORTS_REMAP_PIN_RPC2 Remappable output RPC2 PORTS_REMAP_PIN_RPC4 Remappable output RPC4 Description Remappable Input/Output Enumeration This data type defines the different remappable input/output enumerations. Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. PORTS_AN_PIN Enumeration Data type defining the different analog input pins. File help_plib_ports.h C typedef enum { PORTS_AN_PIN_0, PORTS_AN_PIN_1, PORTS_AN_PIN_2, PORTS_AN_PIN_3, PORTS_AN_PIN_4, PORTS_AN_PIN_5, PORTS_AN_PIN_6, PORTS_AN_PIN_7, PORTS_AN_PIN_8, PORTS_AN_PIN_9, PORTS_AN_PIN_10, PORTS_AN_PIN_11, PORTS_AN_PIN_12, PORTS_AN_PIN_13, PORTS_AN_PIN_14, PORTS_AN_PIN_15, Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1632 PORTS_AN_PIN_ALL } PORTS_AN_PIN; Members Members Description PORTS_AN_PIN_0 AN Pin 0 PORTS_AN_PIN_1 AN Pin 1 PORTS_AN_PIN_2 AN Pin 2 PORTS_AN_PIN_3 AN Pin 3 PORTS_AN_PIN_4 AN Pin 4 PORTS_AN_PIN_5 AN Pin 5 PORTS_AN_PIN_6 AN Pin 6 PORTS_AN_PIN_7 AN Pin 7 PORTS_AN_PIN_8 AN Pin 8 PORTS_AN_PIN_9 AN Pin 9 PORTS_AN_PIN_10 AN Pin 10 PORTS_AN_PIN_11 AN Pin 11 PORTS_AN_PIN_12 AN Pin 12 PORTS_AN_PIN_13 AN Pin 13 PORTS_AN_PIN_14 AN Pin 14 PORTS_AN_PIN_15 AN Pin 15 PORTS_AN_PIN_ALL All the AN Pins Description Analog input pins This data type defines the different analog input pins. Remarks Values of these AN Pin enums are different from the other similar enumerators by name PORTS_ANALOG_PIN. These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_CN_PIN Enumeration Data type defining the different Change Notification (CN) pins enumerations. File help_plib_ports.h C typedef enum { CHANGE_NOTICE_PIN_0, CHANGE_NOTICE_PIN_1, CHANGE_NOTICE_PIN_2, CHANGE_NOTICE_PIN_3, CHANGE_NOTICE_PIN_4, CHANGE_NOTICE_PIN_5, CHANGE_NOTICE_PIN_6, CHANGE_NOTICE_PIN_7, CHANGE_NOTICE_PIN_8, CHANGE_NOTICE_PIN_9, CHANGE_NOTICE_PIN_10, CHANGE_NOTICE_PIN_11, CHANGE_NOTICE_PIN_12, CHANGE_NOTICE_PIN_13, CHANGE_NOTICE_PIN_14, CHANGE_NOTICE_PIN_15, CHANGE_NOTICE_PIN_16, CHANGE_NOTICE_PIN_17, CHANGE_NOTICE_PIN_18, CHANGE_NOTICE_PIN_19, CHANGE_NOTICE_PIN_20, CHANGE_NOTICE_PIN_21, CHANGE_NOTICE_PIN_ALL } PORTS_CN_PIN; Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1633 Members Members Description CHANGE_NOTICE_PIN_0 Change Notice Pin 0 CHANGE_NOTICE_PIN_1 Change Notice Pin 1 CHANGE_NOTICE_PIN_2 Change Notice Pin 2 CHANGE_NOTICE_PIN_3 Change Notice Pin 3 CHANGE_NOTICE_PIN_4 Change Notice Pin 4 CHANGE_NOTICE_PIN_5 Change Notice Pin 5 CHANGE_NOTICE_PIN_6 Change Notice Pin 6 CHANGE_NOTICE_PIN_7 Change Notice Pin 7 CHANGE_NOTICE_PIN_8 Change Notice Pin 8 CHANGE_NOTICE_PIN_9 Change Notice Pin 9 CHANGE_NOTICE_PIN_10 Change Notice Pin 10 CHANGE_NOTICE_PIN_11 Change Notice Pin 11 CHANGE_NOTICE_PIN_12 Change Notice Pin 12 CHANGE_NOTICE_PIN_13 Change Notice Pin 13 CHANGE_NOTICE_PIN_14 Change Notice Pin 14 CHANGE_NOTICE_PIN_15 Change Notice Pin 15 CHANGE_NOTICE_PIN_16 Change Notice Pin 16 CHANGE_NOTICE_PIN_17 Change Notice Pin 17 CHANGE_NOTICE_PIN_18 Change Notice Pin 18 CHANGE_NOTICE_PIN_19 Change Notice Pin 19 CHANGE_NOTICE_PIN_20 Change Notice Pin 20 CHANGE_NOTICE_PIN_21 Change Notice Pin 21 CHANGE_NOTICE_PIN_ALL All the Change Notice Pins Description Change Notice Pins enumeration This data type defines the different CN pins enumerations. Remarks Values of these CN Pin enums are different from the other similar enumerators by name PORTS_CHANGE_NOTICE_PIN. These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_CHANGE_NOTICE_EDGE Enumeration Data type defining the different edge type for change notification. File help_plib_ports.h C typedef enum { PORTS_CHANGE_NOTICE_EDGE_RISING = 0, PORTS_CHANGE_NOTICE_EDGE_FALLING = 1 } PORTS_CHANGE_NOTICE_EDGE; Members Members Description PORTS_CHANGE_NOTICE_EDGE_RISING = 0 Change Notification on rising edge PORTS_CHANGE_NOTICE_EDGE_FALLING = 1 Change Notification on falling edge Description PORTS Change Notice Edge Type This data type defines the different edge type for change notification. Peripheral Libraries Help Ports Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1634 Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_CHANGE_NOTICE_METHOD Enumeration Data type defining the different method of ports pin change notification. File help_plib_ports.h C typedef enum { PORTS_CHANGE_NOTICE_METHOD_SAMPLED = 0, PORTS_CHANGE_NOTICE_METHOD_EDGE_DETECT = 1 } PORTS_CHANGE_NOTICE_METHOD; Members Members Description PORTS_CHANGE_NOTICE_METHOD_SAMPLED = 0 Change notification happens when there is level transition PORTS_CHANGE_NOTICE_METHOD_EDGE_DETECT = 1 Change notification happens when there is edge transition Description PORTS Pin Change Notice Method This data type defines the different method of ports pin change notification. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. PORTS_PIN_SLEW_RATE Enumeration Data type defining the different slew rates for port pins. File help_plib_ports.h C typedef enum { PORTS_PIN_SLEW_RATE_FASTEST = 0x00, PORTS_PIN_SLEW_RATE_FAST = 0x01, PORTS_PIN_SLEW_RATE_SLOW = 0x02, PORTS_PIN_SLEW_RATE_SLOWEST = 0x03 } PORTS_PIN_SLEW_RATE; Members Members Description PORTS_PIN_SLEW_RATE_FASTEST = 0x00 Slew rate fastest PORTS_PIN_SLEW_RATE_FAST = 0x01 Slew rate fast PORTS_PIN_SLEW_RATE_SLOW = 0x02 Slew rate slow PORTS_PIN_SLEW_RATE_SLOWEST = 0x03 Slew rate slowest Description PORTS Pin Slew Rate This data type defines the different slew rates for port pins. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. Peripheral Libraries Help Ports Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1635 Files Files Name Description plib_ports.h Ports Peripheral Library Interface header for Ports function definitions. help_plib_ports.h This is file help_plib_ports.h. Description This section lists the source and header files used by the library. plib_ports.h Ports Peripheral Library Interface header for Ports function definitions. Functions Name Description PLIB_PORTS_AnPinsModeSelect Enables the selected AN pins as analog or digital. PLIB_PORTS_ChangeNoticeDisable Global Change Notice disable. PLIB_PORTS_ChangeNoticeEnable Global Change Notice enable. PLIB_PORTS_ChangeNoticeInIdleDisable CPU Idle halts the Change Notice operation. PLIB_PORTS_ChangeNoticeInIdleEnable CPU Idle mode does not affect Change Notice operation. PLIB_PORTS_ChangeNoticeInIdlePerPortDisable Change Notification halts in Idle mode for selected channel. PLIB_PORTS_ChangeNoticeInIdlePerPortEnable Allows CN to be working in Idle mode for selected channel. PLIB_PORTS_ChangeNoticePerPortHasOccured This is function PLIB_PORTS_ChangeNoticePerPortHasOccured. PLIB_PORTS_ChangeNoticePerPortHasOccurred checks the status of change on the pin PLIB_PORTS_ChangeNoticePerPortTurnOff Disables the change notification for selected port. PLIB_PORTS_ChangeNoticePerPortTurnOn Enables the change notification for selected port. PLIB_PORTS_ChangeNoticePullDownPerPortDisable Disables the pull-down for selected Change Notice pins. PLIB_PORTS_ChangeNoticePullDownPerPortEnable Enables the pull-down for selected Change Notice pins. PLIB_PORTS_ChangeNoticePullUpDisable Disable pull-up on input change. PLIB_PORTS_ChangeNoticePullUpEnable Enable pull-up on input change. PLIB_PORTS_ChangeNoticePullUpPerPortDisable Disables weak pull-up for the selected pin. PLIB_PORTS_ChangeNoticePullUpPerPortEnable Enables the pull-up for selected Change Notice pins. PLIB_PORTS_ChannelChangeNoticeDisable Disables CN interrupt for the selected pins of a channel. PLIB_PORTS_ChannelChangeNoticeEdgeDisable Disables selected type of edge for selected CN pins. PLIB_PORTS_ChannelChangeNoticeEdgeEnable Enables selected type of edge for selected CN pins. PLIB_PORTS_ChannelChangeNoticeEnable Enables CN interrupt for the selected pins of a channel. PLIB_PORTS_ChannelChangeNoticeMethodGet Gets the Change Notice style for the selected port channel. PLIB_PORTS_ChannelChangeNoticeMethodSelect Selects the Change Notice style for selected port channel. PLIB_PORTS_ChannelChangeNoticePullDownDisable Disables Change Notice pull-down for the selected channel pins. PLIB_PORTS_ChannelChangeNoticePullDownEnable Enables Change Notice pull-down for the selected channel pins. PLIB_PORTS_ChannelChangeNoticePullUpDisable Disables Change Notice pull-up for the selected channel pins. PLIB_PORTS_ChannelChangeNoticePullUpEnable Enables Change Notice pull-up for the selected channel pins. PLIB_PORTS_ChannelModeSelect Enables the selected channel pins as analog or digital. PLIB_PORTS_ChannelSlewRateSelect Selects the slew rate for selected channel pins. PLIB_PORTS_Clear Clears the selected digital port/latch bits. PLIB_PORTS_CnPinsDisable Disables CN interrupt for the selected pins of a channel. PLIB_PORTS_CnPinsEnable Enables CN interrupt for the selected pins of a channel. PLIB_PORTS_CnPinsPullUpDisable Disables Change Notice pull-up for the selected channel pins. PLIB_PORTS_CnPinsPullUpEnable Enables Change Notice pull-up for the selected channel pins. PLIB_PORTS_DirectionGet Reads the direction of the selected digital port. PLIB_PORTS_DirectionInputSet Makes the selected pins direction input. PLIB_PORTS_DirectionOutputSet Makes the selected pins direction output. PLIB_PORTS_ExistsAnPinsMode Identifies whether the AnPinsMode feature exists on the Ports module. Peripheral Libraries Help Ports Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1636 PLIB_PORTS_ExistsChangeNotice Identifies whether the ChangeNotice feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticeEdgeControl Identifies whether the ChangeNoticeEdgeControl feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticeEdgeStatus Identifies whether the ChangeNoticeEdgeStatus feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticeInIdle Identifies whether the ChangeNoticeInIdle feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePerPortInIdle Identifies whether the ChangeNoticeInIdlePerPort feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePerPortStatus Identifies whether the ChangeNoticePerPortStatus feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePerPortTurnOn Identifies whether the ChangeNoticePerPortTurnOn feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePullDownPerPort Identifies whether the ChangeNoticePullDownPerPort feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePullUp Identifies whether the ChangeNoticePullup feature exists on the Ports module. PLIB_PORTS_ExistsChangeNoticePullUpPerPort Identifies whether the ChangeNoticePullUpPerPort feature exists on the Ports module. PLIB_PORTS_ExistsChannelChangeNoticeMethod Identifies whether the ChannelChangeNoticeMethod feature exists on the Ports module. PLIB_PORTS_ExistsLatchRead Identifies whether the LatchRead feature exists on the Ports module. PLIB_PORTS_ExistsPinChangeNotice Identifies whether the PinChangeNotice feature exists on the Ports module. PLIB_PORTS_ExistsPinChangeNoticePerPort Identifies whether the PinChangeNoticePerPort feature exists on the Ports module. PLIB_PORTS_ExistsPinMode Identifies whether the PinMode feature exists on the Ports module. PLIB_PORTS_ExistsPinModePerPort Identifies whether the PinModePerPort feature exists on the Ports module. PLIB_PORTS_ExistsPortsDirection Identifies whether the PortsDirection feature exists on the Ports module. PLIB_PORTS_ExistsPortsOpenDrain Identifies whether the PortsOpenDrain feature exists on the Ports module. PLIB_PORTS_ExistsPortsRead Identifies whether the PortsRead feature exists on the Ports module. PLIB_PORTS_ExistsPortsWrite Identifies whether the PortsWrite feature exists on the Ports module. PLIB_PORTS_ExistsRemapInput Identifies whether the RemapInput feature exists on the Ports module. PLIB_PORTS_ExistsRemapOutput Identifies whether the RemapOutput feature exists on the Ports module. PLIB_PORTS_ExistsSlewRateControl Identifies whether the SlewRateControl feature exists on the Ports module. PLIB_PORTS_OpenDrainDisable Disables the open drain functionality for the selected port. PLIB_PORTS_OpenDrainEnable Enables the open drain functionality for the selected port pins. PLIB_PORTS_PinChangeNoticeDisable Port pin Change Notice disable. PLIB_PORTS_PinChangeNoticeEdgeHasOccurred Check Change Notice edge status. PLIB_PORTS_PinChangeNoticeEdgeIsEnabled Check if Change Notice edge is enabled or not. PLIB_PORTS_PinChangeNoticeEnable Port pin Change Notice interrupt enable. PLIB_PORTS_PinChangeNoticePerPortDisable Disables CN interrupt for the selected pin. PLIB_PORTS_PinChangeNoticePerPortEnable Enables CN interrupt for the selected pin. PLIB_PORTS_PinClear Clears the selected digital pin/latch. PLIB_PORTS_PinDirectionInputSet Makes the selected pin direction input PLIB_PORTS_PinDirectionOutputSet Makes the selected pin direction output PLIB_PORTS_PinGet Reads/Gets data from the selected digital pin. PLIB_PORTS_PinGetLatched Reads/Gets data from the selected latch. PLIB_PORTS_PinModePerPortSelect Enables the selected port pin as analog or digital. PLIB_PORTS_PinModeSelect Enables the selected pin as analog or digital. PLIB_PORTS_PinOpenDrainDisable Disables the open drain functionality for the selected pin. PLIB_PORTS_PinOpenDrainEnable Enables the open drain functionality for the selected pin. PLIB_PORTS_PinSet Sets the selected digital pin/latch. PLIB_PORTS_PinSlewRateGet Gets the slew rate for selected port pin. PLIB_PORTS_PinToggle Toggles the selected digital pin/latch. PLIB_PORTS_PinWrite Writes the selected digital pin/latch. PLIB_PORTS_Read Reads the selected digital port. PLIB_PORTS_ReadLatched Reads and returns data from the selected Latch. PLIB_PORTS_RemapInput Input function remapping. Peripheral Libraries Help Ports Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1637 PLIB_PORTS_RemapOutput Output function remapping. PLIB_PORTS_Set Sets the selected bits of the port. PLIB_PORTS_Toggle Toggles the selected digital port/latch. PLIB_PORTS_Write Writes the selected digital port/latch. Types Name Description PORTS_DATA_MASK Data type defining the Ports data mask PORTS_DATA_TYPE Data type defining the Ports data type. Description Ports Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Ports Peripheral Library for all families of Microchip microcontrollers. The definitions in this file are common to the Ports peripheral. File Name plib_ports.h Company Microchip Technology Inc. help_plib_ports.h Enumerations Name Description PORTS_AN_PIN Data type defining the different analog input pins. PORTS_ANALOG_PIN Data type defining the different analog input pins. PORTS_BIT_POS Lists the constants that hold different PORTS bit positions. PORTS_CHANGE_NOTICE_EDGE Data type defining the different edge type for change notification. PORTS_CHANGE_NOTICE_METHOD Data type defining the different method of ports pin change notification. PORTS_CHANGE_NOTICE_PIN Data type defining the different Change Notification (CN) pins enumerations. PORTS_CHANNEL Identifies the available Ports channels. PORTS_CN_PIN Data type defining the different Change Notification (CN) pins enumerations. PORTS_MODULE_ID Identifies the available Ports modules. PORTS_PIN_MODE Identifies the available pin modes. PORTS_PIN_SLEW_RATE Data type defining the different slew rates for port pins. PORTS_REMAP_FUNCTION Data type defining the different remap function enumerations. PORTS_REMAP_INPUT_FUNCTION Data type defining the different remap input function enumerations. PORTS_REMAP_INPUT_PIN Data type defining the different Ports I/O input pins enumerations. PORTS_REMAP_OUTPUT_FUNCTION Data type defining the different remap output function enumerations. PORTS_REMAP_OUTPUT_PIN Data type defining the different Ports I/O output pins enumerations. PORTS_REMAP_PIN Data type defining the different remappable input/output enumerations. Description This is file help_plib_ports.h. Peripheral Libraries Help Ports Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1638 Power Peripheral Library This section describes the Power Peripheral Library. Introduction This library provides a low-level abstraction of the Power Controller modules on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The Power Controller is a key component of a microcontroller. Power control features allow the user to obtain the balance of power consumption and performance that is best suited to their application. The features provided in this library discuss specific software commands that are used dynamically to place the device in low-power (i.e., power-saving) modes, which disable power and clocking of selected features. When implementing a system to achieve the lowest possible power consumption while maintain the needed performance, the oscillator configuration and clocking of all peripherals must also be considered. Oscillator configuration and peripheral clocking are addressed in the Oscillator Peripheral Library. In addition, each peripheral may have its own low-power mode settings that are controlled by the library of that peripheral. The user is advised to refer to the libraries of the peripherals used for their particular application. Key features present on a power controller include (a microcontroller can support one or more of these power features): • Power Source Configuration: Provides the ability to enable and disable a source that may regulate the power consumption in the device • Power Status Flags: Indicate the status of the particular power feature in the device Note: Not all devices support all of the features discussed in this section. Please refer to specific device data sheet to determine the supported features for your device. Using the Library This topic describes the basic architecture of the Power Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_power.h The interface to the Power Peripheral Library is defined in the plib_power.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Power Peripheral Library must include peripheral.h. Peripheral Module IDs Peripheral libraries are indexed to allow a single library to control any number of instances of a peripheral in a single microcontroller. To support this, the first parameter to each operation in a peripheral library is the module instance ID. The module instance ID is defined by an enumeration that is defined in the processor-specific header files (included by the library's interface header). Not all microcontrollers will have all instances of the module listed in this enumeration. Please refer to the specific data sheet to determine availability. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the Power Controller module on Microchip microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Block Diagram Peripheral Libraries Help Power Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1639 This section discusses the various power-saving features implemented in hardware. Combinations of these methods can be used to selectively tailor an application’s power consumption, while still maintaining critical or timing-sensitive application features. Note: Not all devices support all of the features discussed in this section. Please refer to specific device data sheet to determine the supported features for your device. Instruction-based Power-Saving Modes In addition to full-power operation, otherwise known as Run mode, PIC microcontrollers also provide other instruction-based power-saving modes. By powering down to different modes, different functional areas of the microcontroller allow progressive reductions of operating and idle power consumption. In addition, these modes can be tailored for more power reduction, but at a trade-off of some operating features. • Idle Mode: In Idle mode, the CPU is halted, but the System Clock (SYSCLK) source is still enabled. This allows peripherals to continue to operate when the CPU is halted. Peripherals can be individually configured to halt when entering Idle mode by setting their respective SIDL bit. Latency when exiting Idle mode is very low due to the CPU oscillator source remaining active. • Sleep Mode: The CPU, SYSCLK source and any peripherals that operate on the system clock source are disabled • Deep Sleep Mode: The CPU SYSCLK source, and all the peripherals, with the exception of the Real-Time Clock and Calendar (RTCC) and the Deep Sleep Watchdog Timer (DSWDT), are disabled. This is the lowest power mode for the device. The power to RAM and Flash is also disabled. Deep Sleep mode represents the lowest power mode available without removing power from the application. The instruction-based power-saving modes are exited as a result of several different hardware triggers. When the device exits one of these three operating modes, it is said to ‘wake-up'. Hardware-based Power-Saving Mode VBAT mode is a hardware-based power-saving mode that maintains only the most critical operations when a power loss occurs on VDD. The mode does this by powering the systems from a back-up power source connected to the VBAT pin. In this mode, the RTCC can run even when there is no power on VDD. VBAT mode is entered whenever power is removed from VDD. An on-chip power switch detects the power loss from VDD and connects the VBAT pin to the low-voltage regulator. Entering VBAT mode requires that a power source, distinct from the main VDD power source, be available on the VBAT pin and that VDD be completely removed from the VDD pin(s). Removing VDD can be either unintentional, as in a power failure, or as part of a deliberate power reduction strategy. Peripheral Libraries Help Power Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1640 Note: Not all devices support all of the features discussed in this section. Please refer to specific device data sheet to determine the supported features for your device. Selective Peripheral Power Control Sleep and Idle modes allow users to substantially reduce power consumption by slowing or stopping the CPU clock. Even so, peripheral modules may still remain clocked, and thus, consume some amount of power. There may be cases where the application needs what these modes do not provide: the ability to allocate limited power resources to the CPU while eliminating power consumption from the peripherals. PIC microcontrollers address this requirement by allowing peripheral modules to be selectively enabled or disabled, reducing or eliminating their power consumption. In addition to the selective peripheral power control implemented as part of this library, devices will also include power saving features that are implemented in their specific libraries. These features include the ability to stop (shutdown) automatically when entering idle mode. On some peripherals the ability to continue operation in Sleep mode is available. Always review the libraries for the peripherals used by your application for specific and unique features that will help minimize power consumption. Disabling Peripheral Modules Most of the peripheral modules in the PIC microcontroller family architecture can be selectively disabled, reducing or essentially eliminating their power consumption during all operating modes. All peripheral modules (except for I/O ports) also have a Control bit that can disable their functionality. These bits, known as the Peripheral Module Disable (PMD) bits, are generically named: 'xxMD'. These bits are located in the PMDx Special Function Registers (SFRs). In contrast to the module enable bits, the xxMD bit must be set to a '1' to disable the module. While the PMD and module enable bits both disable a peripheral’s functionality, the PMD bit completely shuts down the peripheral, effectively powering down all circuits and removing all clock sources. This has the additional effect of making any of the module’s control and buffer registers, mapped in the SFR space, unavailable for operations. In other words, when the PMD bit is used to disable a module, the peripheral ceases to exist until the PMD bit is cleared. The PMD bit is most useful in highly power-sensitive applications, where even tiny savings in power consumption can determine the ability of an application to function. In these cases, the bits can be set before the main body of the application to remove those peripherals that will not be needed. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Power Controller module. Library Interface Section Description Initialization Functions This section provides a set of functions for configuring the Power-Saving features and enabling or disabling the particular power feature. Status Functions This section provides a function to read the status of a particular power feature. HLVD Functions This section provides High/Low-Voltage Detect functions. Deep Sleep Functions This section provides Deep Sleep mode functions. Feature Existence Functions This section provides functions that can be used to determine available features. Note: The interface provided is a superset of all power functionality available on the device. Refer to the "Power-Saving Features" chapter in the specific device data sheet for availability. How the Library Works Provides information on how the library works. Description Usage of this library is partitioned into two major sections. Initialization The steps that are required to initialize the Power Controller module vary for different microcontrollers. Refer to the specific device data sheet to determine the correct initialization sequence. The following information provides a general overview. Power Source Setup • A module can be disabled for the microcontroller to be able to save power. Use the function PLIB_POWER_ModuleDisable to disable the particular module. POWER_MODULE_DISABLE provides a list of possible modules sources. • On most microcontrollers, the voltage regulator can be controlled during Sleep mode. It can be enabled (turned on) using PLIB_POWER_VoltageRegulatorEnable and disabled (turned off) using PLIB_POWER_VoltageRegulatorDisable. Peripheral Libraries Help Power Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1641 • On some microcontrollers, Deep Sleep mode is enabled using PLIB_POWER_DeepSleepModeEnable. The Deep Sleep mode is disabled using PLIB_POWER_DeepSleepModeDisable. Power Status Status of the particular power feature indicates the previous status of that feature. This feature can be used to determine whether the device was in Sleep or Idle mode before waking up. It also allows software to clear the previous status of the device. Configuring the Library The library is configured for the supported Power Controller modules when the processor is chosen in the MPLAB X IDE. Library Interface a) Initialization Functions Name Description PLIB_POWER_DeepSleepModeDisable Disables Deep Sleep mode. PLIB_POWER_DeepSleepModeEnable Enables Deep Sleep mode. PLIB_POWER_PeripheralModuleDisable Disable the power supply for the module selected in the source. PLIB_POWER_PeripheralModuleEnable Enable the power supply for the module selected in the source. PLIB_POWER_PeripheralModuleIsEnabled Checks to see whether or not the selected peripheral is enabled. PLIB_POWER_VoltageRegulatorDisable Disables the voltage regulator during Sleep mode. PLIB_POWER_VoltageRegulatorEnable Enable the voltage regulator during Sleep mode. PLIB_POWER_DeepSleepGPRsRetentionDisable Disables the General Purpose Registers retention. PLIB_POWER_DeepSleepGPRsRetentionEnable Enables the General Purpose Registers retention. PLIB_POWER_DeepSleepModeIsEnabled Returns the enable/disable status of Deep Sleep mode. PLIB_POWER_DeepSleepModuleDisable Disables the module in Deep Sleep mode. PLIB_POWER_DeepSleepModuleEnable Enables the module in Deep Sleep mode. PLIB_POWER_DeepSleepPortPinsStateRelease Releases I/O pins upon wake-up from Deep Sleep mode. PLIB_POWER_DeepSleepPortPinsStateRetain Enables the I/O pins to retain their previous states upon wake-up from Deep Sleep mode. PLIB_POWER_DeepSleepWakeupEventDisable Disables wake-up from Deep Sleep mode by the selected event. PLIB_POWER_DeepSleepWakeupEventEnable Enables wake-up from the Deep Sleep mode by the selected event. b) Status Functions Name Description PLIB_POWER_ClearIdleStatus Clears the Idle mode status of the device. PLIB_POWER_ClearSleepStatus Clear the Sleep mode status bit of the device. PLIB_POWER_DeviceWasInIdleMode Returns the Idle mode status of the device. PLIB_POWER_DeviceWasInSleepMode Returns the Sleep mode status of the device. PLIB_POWER_HighVoltageOnVDD1V8HasOccurred Returns the DDR2 High Voltage Detection status of the device. PLIB_POWER_VoltageRegulatorIsEnabled Provides the status of the voltage regulator during Sleep mode. PLIB_POWER_DeepSleepStatusClear Clears the Deep Sleep mode status bit of the device. PLIB_POWER_DeepSleepEventStatusClear Clear any events that occurred during Deep Sleep mode. PLIB_POWER_DeepSleepEventStatusGet Returns the events that occurred during Deep Sleep mode. PLIB_POWER_DeepSleepModeHasOccurred Returns the Deep Sleep mode status of the device. c) HLVD Functions Name Description PLIB_POWER_HLVDBandGapVoltageIsStable Returns the status of Band Gap voltage. PLIB_POWER_HLVDDisable Disables High/Low-Voltage Detection on VDD. PLIB_POWER_HLVDEnable Enables High/Low-Voltage Detection (HLVD) on VDD. PLIB_POWER_HLVDIsEnabled Returns the enable/disable status of High/Low-Voltage Detection on VDD. PLIB_POWER_HLVDLimitSelect Selects the HLVD limit. PLIB_POWER_HLVDModeSelect Selects the Voltage Detection mode. PLIB_POWER_HLVDStatusGet Returns the HLVD event status. PLIB_POWER_HLVDStopInIdleDisable Continues HLVD operation when the device enters Idle mode. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1642 PLIB_POWER_HLVDStopInIdleEnable Discontinues HLVD operation when the device enters Idle mode. PLIB_POWER_HLVDStopInIdleIsEnabled Returns the Stop in Idle mode status of the HLVD operation. d) Deep Sleep Functions Name Description PLIB_POWER_DeepSleepGPRRead Reads 32-bit data from the Deep Sleep General Purpose Register. PLIB_POWER_DeepSleepGPRWrite Writes 32-bit data into the Deep Sleep General Purpose Register. e) Feature Existence Functions Name Description PLIB_POWER_ExistsDeepSleepMode Identifies whether the DeepSleepModeControl feature exists on the Power module. PLIB_POWER_ExistsIdleStatus Identifies whether the IdleStatus feature exists on the Power module. PLIB_POWER_ExistsPeripheralModuleControl Identifies whether the PeripheralModuleControl feature exists on the Power module. PLIB_POWER_ExistsSleepStatus Identifies whether the SleepStatus feature exists on the Power module. PLIB_POWER_ExistsVoltageRegulatorControl Identifies whether the VoltageRegulatorControl feature exists on the Power module. PLIB_POWER_ExistsDeepSleepEventStatus Identifies whether the DeepSleepEventStatus feature exists on the Power module. PLIB_POWER_ExistsDeepSleepGPROperation Identifies whether the DeepSleepGPROperation feature exists on the Power module. PLIB_POWER_ExistsDeepSleepGPRsRetentionControl Identifies whether the DeepSleepGPRsRetentionControl feature exists on the Power module. PLIB_POWER_ExistsDeepSleepModuleControl Identifies whether the DeepSleepModuleControl feature exists on the Power module. PLIB_POWER_ExistsDeepSleepPortPinsStateControl Identifies whether the DeepSleepPortPinsStateControl feature exists on the Power module. PLIB_POWER_ExistsHighVoltageOnVDD1V8 Identifies whether the HighVoltageOnVDD1V8 feature exists on the Power module. PLIB_POWER_ExistsDeepSleepModeOccurrence Identifies whether the DeepSleepModeOccurrence feature exists on the Power module. PLIB_POWER_ExistsDeepSleepWakeupEventControl Identifies whether the DeepSleepWakeupEventControl feature exists on the Power module. PLIB_POWER_ExistsHLVDBandGapVoltageStability Identifies whether the HLVDBandGapVoltageStability feature exists on the Power module. PLIB_POWER_ExistsHLVDEnableControl Identifies whether the HLVDEnableControl feature exists on the Power module. PLIB_POWER_ExistsHLVDLimitSelection Identifies whether the HLVDLimitSelection feature exists on the Power module. PLIB_POWER_ExistsHLVDModeControl Identifies whether the HLVDModeControl feature exists on the Power module. PLIB_POWER_ExistsHLVDStatus Identifies whether the HLVDStatus feature exists on the Power module. PLIB_POWER_ExistsHLVDStopInIdleControl Identifies whether the HLVDStopInIdleControl feature exists on the Power module. f) Data Types and Constants Name Description DEEP_SLEEP_EVENT Lists the events that occurred during Deep Sleep mode. DEEP_SLEEP_GPR Lists the Deep Sleep General Purpose Registers (GPRs). DEEP_SLEEP_MODULE Lists the modules that can be enabled/disabled during Deep Sleep mode. DEEP_SLEEP_WAKE_UP_EVENT Lists the events that can be used to wake the device from Deep Sleep mode. POWER_MODULE List of the modules whose power can be controlled. POWER_MODULE_ID Identifies the supported Power modules. HLVD_LIMIT Lists the voltage limits for the HLVD module. HLVD_MODE Lists the modes for the High/Low Voltage Detection (HLVD) module. Description This section describes the Application Programming Interface (API) functions of the Power Peripheral Library. Refer to each section for a detailed description. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1643 a) Initialization Functions PLIB_POWER_DeepSleepModeDisable Function Disables Deep Sleep mode. File plib_power.h C void PLIB_POWER_DeepSleepModeDisable(POWER_MODULE_ID index); Returns None. Description This function disables Deep Sleep mode. Deep Sleep mode is intended to provide the lowest levels of power consumption available without requiring the use of external switches to completely remove all power from the device. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepMode in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_DeepSleepModeDisable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_DeepSleepModeDisable ( POWER_MODULE_ID index) PLIB_POWER_DeepSleepModeEnable Function Enables Deep Sleep mode. File plib_power.h C void PLIB_POWER_DeepSleepModeEnable(POWER_MODULE_ID index); Returns None. Description This function enables Deep Sleep mode. Deep Sleep mode is intended to provide the lowest levels of power consumption available without requiring the use of external switches to completely remove all power from the device. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepMode in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1644 Example PLIB_POWER_DeepSleepModeEnable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_DeepSleepModeEnable ( POWER_MODULE_ID index) PLIB_POWER_PeripheralModuleDisable Function Disable the power supply for the module selected in the source. File plib_power.h C void PLIB_POWER_PeripheralModuleDisable(POWER_MODULE_ID index, POWER_MODULE source); Returns None. Description This function completely shuts down the selected peripheral, effectively powering down all circuits and removing all clock sources. This has the additional affect of making any of the module’s control and buffer registers, which are mapped in the SFR space, unavailable for operations. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsPeripheralModuleControl in your application to determine whether this feature is available. Disabling a peripheral module while it’s ON bit is set, may result in undefined behavior. The ON bit for the associated peripheral module must be cleared prior to disable a module via this API. Preconditions The PMDLOCK bit of the Configuration register should be cleared using the function PLIB_DEVCON_DeviceRegistersUnlock (this function allows changes in the PMD registers). Refer to the Device Control (DEVCON) Peripheral Library Help (or System Service) and the specific device data sheet for more information. Example // System Unlock PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); // Unlock PMD registers PLIB_DEVCON_DeviceRegistersUnlock(DEVCON_ID_0, DEVCON_PMD_REGISTERS); // Disable ADC module PLIB_POWER_PeripheralModuleDisable (POWER_ID_0, POWER_MODULE_ADC); Parameters Parameters Description index Identifier for the device instance to be configured source Select the module to be disabled from POWER_MODULE enum Function void PLIB_POWER_PeripheralModuleDisable ( POWER_MODULE_ID index, POWER_MODULE source ) PLIB_POWER_PeripheralModuleEnable Function Enable the power supply for the module selected in the source. File plib_power.h Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1645 C void PLIB_POWER_PeripheralModuleEnable(POWER_MODULE_ID index, POWER_MODULE source); Returns None. Description This function enables the power supply for the selected module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsPeripheralModuleControl in your application to determine whether this feature is available. Preconditions The PMDLOCK bit of the Configuration register should be cleared using the function PLIB_DEVCON_DeviceRegistersUnlock (this function allows changes in the PMD registers). Refer to the Device Control (DEVCON) Peripheral Library Help (or System Service) and the specific device data sheet for more information. Example // System Unlock PLIB_DEVCON_SystemUnlock(DEVCON_ID_0); // Unlock PMD registers PLIB_DEVCON_DeviceRegistersUnlock(DEVCON_ID_0, DEVCON_PMD_REGISTERS); // Enable ADC module PLIB_POWER_PeripheralModuleEnable (POWER_ID_0, POWER_MODULE_ADC); Parameters Parameters Description index Identifier for the device instance to be configured source Select the module to be enabled from POWER_MODULE enum Function void PLIB_POWER_PeripheralModuleEnable ( POWER_MODULE_ID index, POWER_MODULE source ) PLIB_POWER_PeripheralModuleIsEnabled Function Checks to see whether or not the selected peripheral is enabled. File plib_power.h C bool PLIB_POWER_PeripheralModuleIsEnabled(POWER_MODULE_ID index, POWER_MODULE source); Returns • true - Power of the selected peripheral is enabled • false - Power of the selected peripheral is disabled Description This function checks to see whether or not the selected peripheral is enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsPeripheralModuleControl in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_POWER_PeripheralModuleIsEnabled ( POWER_MODULE_0, POWER_MODULE_ADC )) { Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1646 } Parameters Parameters Description index Identifier for the device instance to be configured source Select the module to be enabled from the POWER_MODULE enum Function bool PLIB_POWER_PeripheralModuleIsEnabled ( POWER_MODULE_ID index, POWER_MODULE source ) PLIB_POWER_VoltageRegulatorDisable Function Disables the voltage regulator during Sleep mode. File plib_power.h C void PLIB_POWER_VoltageRegulatorDisable(POWER_MODULE_ID index); Returns None. Description This function disables the voltage regulator during Sleep mode for the selected device. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsVoltageRegulatorControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_VoltageRegulatorDisable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_VoltageRegulatorDisable ( POWER_MODULE_ID index) PLIB_POWER_VoltageRegulatorEnable Function Enable the voltage regulator during Sleep mode. File plib_power.h C void PLIB_POWER_VoltageRegulatorEnable(POWER_MODULE_ID index); Returns None. Description This function enables the voltage regulator during Sleep mode for the selected device. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsVoltageRegulatorControl in your application to determine whether this feature is available. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1647 Preconditions None. Example PLIB_POWER_VoltageRegulatorEnable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_VoltageRegulatorEnable ( POWER_MODULE_ID index) PLIB_POWER_DeepSleepGPRsRetentionDisable Function Disables the General Purpose Registers retention. File plib_power.h C void PLIB_POWER_DeepSleepGPRsRetentionDisable(POWER_MODULE_ID index); Returns None. Description This function disables the Deep Sleep General Purpose Registers to retain their values when the device enters Deep Sleep/VBAT mode, which means the power to DEEP_SLEEP_GPR_1 to DEEP_SLEEP_GPR_32 will be dismissed. Power to DEEP_SLEEP_GPR_0 will be retained by default. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepGPRsRetentionControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_DeepSleepGPRsRetentionDisable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_DeepSleepGPRsRetentionDisable ( POWER_MODULE_ID index) PLIB_POWER_DeepSleepGPRsRetentionEnable Function Enables the General Purpose Registers retention. File plib_power.h C void PLIB_POWER_DeepSleepGPRsRetentionEnable(POWER_MODULE_ID index); Returns None. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1648 Description This function enables the Deep Sleep General Purpose Registers to retain their values when the device enters Deep Sleep/VBAT mode, which means the power to DEEP_SLEEP_GPR_1 to DEEP_SLEEP_GPR_32 will be maintained. Power to DEEP_SLEEP_GPR_0 will be retained by default. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepGPRsRetentionControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_DeepSleepGPRsRetentionEnable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_DeepSleepGPRsRetentionEnable ( POWER_MODULE_ID index) PLIB_POWER_DeepSleepModeIsEnabled Function Returns the enable/disable status of Deep Sleep mode. File plib_power.h C bool PLIB_POWER_DeepSleepModeIsEnabled(POWER_MODULE_ID index); Returns • true - Deep Sleep mode is enabled • false - Deep Sleep mode is not enabled Description This function returns whether or not Deep Sleep mode is enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepMode in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_POWER_DeepSleepModeIsEnabled(POWER_ID_0)) { //Enter Deep Sleep by executing Sleep mode. } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_POWER_DeepSleepModeIsEnabled ( POWER_MODULE_ID index) Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1649 PLIB_POWER_DeepSleepModuleDisable Function Disables the module in Deep Sleep mode. File plib_power.h C void PLIB_POWER_DeepSleepModuleDisable(POWER_MODULE_ID index, DEEP_SLEEP_MODULE module); Returns None. Description This function disables the selected module in Deep Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepModuleControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_DeepSleepModuleDisable(POWER_ID_0 , DEEP_SLEEP_MODULE_RTCC); Parameters Parameters Description index Identifier for the device instance to be configured module Possible module from DEEP_SLEEP_MODULE Function void PLIB_POWER_DeepSleepModuleDisable( POWER_MODULE_ID index, DEEP_SLEEP_MODULE module) PLIB_POWER_DeepSleepModuleEnable Function Enables the module in Deep Sleep mode. File plib_power.h C void PLIB_POWER_DeepSleepModuleEnable(POWER_MODULE_ID index, DEEP_SLEEP_MODULE module); Returns None. Description This function enables the selected module in Deep Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepModuleControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_DeepSleepModuleEnable(POWER_ID_0 , DEEP_SLEEP_MODULE_RTCC); Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1650 Parameters Parameters Description index Identifier for the device instance to be configured module Possible module from DEEP_SLEEP_MODULE Function void PLIB_POWER_DeepSleepModuleEnable( POWER_MODULE_ID index, DEEP_SLEEP_MODULE module) PLIB_POWER_DeepSleepPortPinsStateRelease Function Releases I/O pins upon wake-up from Deep Sleep mode. File plib_power.h C void PLIB_POWER_DeepSleepPortPinsStateRelease(POWER_MODULE_ID index); Returns None. Description This function releases the I/O pins upon wake-up from Deep Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepPortPinsStateControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_DeepSleepPortPinsStateRelease(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_DeepSleepPortPinsStateRelease ( POWER_MODULE_ID index) PLIB_POWER_DeepSleepPortPinsStateRetain Function Enables the I/O pins to retain their previous states upon wake-up from Deep Sleep mode. File plib_power.h C void PLIB_POWER_DeepSleepPortPinsStateRetain(POWER_MODULE_ID index); Returns None. Description This function enables the I/O pins to retain their previous states upon wake-up from Deep Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepPortPinsStateControl in your application to determine whether this feature is available. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1651 Preconditions None. Example PLIB_POWER_DeepSleepPortPinsStateRetain(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_DeepSleepPortPinsStateRetain ( POWER_MODULE_ID index) PLIB_POWER_DeepSleepWakeupEventDisable Function Disables wake-up from Deep Sleep mode by the selected event. File plib_power.h C void PLIB_POWER_DeepSleepWakeupEventDisable(POWER_MODULE_ID index, DEEP_SLEEP_WAKE_UP_EVENT event); Returns None. Description This function disables wake-up from Deep Sleep mode by the selected event. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepWakeupEventControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_DeepSleepWakeupEventDisable(POWER_ID_0 , DEEP_SLEEP_WAKE_UP_EVENT_RTCC); Parameters Parameters Description index Identifier for the device instance to be configured event Possible event from DEEP_SLEEP_WAKE_UP_EVENT Function void PLIB_POWER_DeepSleepWakeupEventDisable( POWER_MODULE_ID index, DEEP_SLEEP_WAKE_UP_EVENT event) PLIB_POWER_DeepSleepWakeupEventEnable Function Enables wake-up from the Deep Sleep mode by the selected event. File plib_power.h C void PLIB_POWER_DeepSleepWakeupEventEnable(POWER_MODULE_ID index, DEEP_SLEEP_WAKE_UP_EVENT event); Returns None. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1652 Description This function enables wake-up from the Deep Sleep mode by the selected event. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepWakeupEventControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_DeepSleepWakeupEventEnable(POWER_ID_0 , DEEP_SLEEP_WAKE_UP_EVENT_RTCC); Parameters Parameters Description index Identifier for the device instance to be configured event Possible event from DEEP_SLEEP_WAKE_UP_EVENT Function void PLIB_POWER_DeepSleepWakeupEventEnable( POWER_MODULE_ID index, DEEP_SLEEP_WAKE_UP_EVENT event) b) Status Functions PLIB_POWER_ClearIdleStatus Function Clears the Idle mode status of the device. File plib_power.h C void PLIB_POWER_ClearIdleStatus(POWER_MODULE_ID index); Returns None. Description This function clears the Idle status bit of the device if it was previously in Idle mode. However, it does not mean that it wakes the device from Idle. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsIdleStatus in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_POWER_DeviceWasInIdleMode(POWER_ID_0)) { PLIB_POWER_ClearIdleStatus (POWER_ID_0); } Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_ClearIdleStatus ( POWER_MODULE_ID index) Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1653 PLIB_POWER_ClearSleepStatus Function Clear the Sleep mode status bit of the device. File plib_power.h C void PLIB_POWER_ClearSleepStatus(POWER_MODULE_ID index); Returns None. Description This function clears the Sleep status bit of the device if it was previously in Sleep mode. However, it does not mean that it wakes the device from sleep. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsSleepStatus in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_POWER_DeviceWasInSleepMode(POWER_ID_0)) { PLIB_POWER_ClearSleepStatus (POWER_ID_0); } Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_ClearSleepStatus ( POWER_MODULE_ID index) PLIB_POWER_DeviceWasInIdleMode Function Returns the Idle mode status of the device. File plib_power.h C bool PLIB_POWER_DeviceWasInIdleMode(POWER_MODULE_ID index); Returns • true - The device was in Idle mode before waking up • false - The device was not in Idle mode Description This function returns the Idle mode status of the device. It indicates whether or not the device was in Idle mode before waking up. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsIdleStatus in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1654 Example if(PLIB_POWER_DeviceWasInIdleMode(POWER_ID_0)) { } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_POWER_DeviceWasInIdleMode ( POWER_MODULE_ID index) PLIB_POWER_DeviceWasInSleepMode Function Returns the Sleep mode status of the device. File plib_power.h C bool PLIB_POWER_DeviceWasInSleepMode(POWER_MODULE_ID index); Returns • true - The device was in Sleep mode before waking up • false - The device was not in Sleep mode Description This function returns the Sleep mode status of the device. It indicates whether or not the device was in Sleep mode before waking up. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsSleepStatus in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_POWER_DeviceWasInSleepMode(POWER_ID_0)) { } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_POWER_DeviceWasInSleepMode ( POWER_MODULE_ID index) PLIB_POWER_HighVoltageOnVDD1V8HasOccurred Function Returns the DDR2 High Voltage Detection status of the device. File plib_power.h C bool PLIB_POWER_HighVoltageOnVDD1V8HasOccurred(POWER_MODULE_ID index); Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1655 Returns • true - A high-voltage condition on the VDD1V8 voltage has occurred • false - A high-voltage condition on the VDD1V8 voltage has not occurred Description This function returns the DDR2 High Voltage Detection status of the device. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHighVoltageOnVDD1V8 in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_POWER_HighVoltageOnVDD1V8HasOccurred(POWER_ID_0)) { } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_POWER_HighVoltageOnVDD1V8HasOccurred ( POWER_MODULE_ID index) PLIB_POWER_VoltageRegulatorIsEnabled Function Provides the status of the voltage regulator during Sleep mode. File plib_power.h C bool PLIB_POWER_VoltageRegulatorIsEnabled(POWER_MODULE_ID index); Returns • true - The voltage regulator will be enabled in Sleep mode • false - The voltage regulator will be disabled in Sleep mode Description This function provides the status of the voltage regulator during Sleep mode for the selected device. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsVoltageRegulatorControl in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_POWER_VoltageRegulatorIsEnabled(POWER_ID_0)) { } Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1656 Function bool PLIB_POWER_VoltageRegulatorIsEnabled ( POWER_MODULE_ID index) PLIB_POWER_DeepSleepStatusClear Function Clears the Deep Sleep mode status bit of the device. File plib_power.h C void PLIB_POWER_DeepSleepStatusClear(POWER_MODULE_ID index); Returns None. Description This function clears the Deep Sleep status bit of the device if it was previously in Deep Sleep mode. However, it does not mean that it wakes the device from Deep Sleep. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepModeOccurrence in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_POWER_DeepSleepModeHasOccurred(POWER_ID_0)) { PLIB_POWER_DeepSleepStatusClear (POWER_ID_0); } Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_DeepSleepStatusClear ( POWER_MODULE_ID index) PLIB_POWER_DeepSleepEventStatusClear Function Clear any events that occurred during Deep Sleep mode. File plib_power.h C void PLIB_POWER_DeepSleepEventStatusClear(POWER_MODULE_ID index, DEEP_SLEEP_EVENT event); Returns None. Description This function accept the events to clear that occurred during Deep Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepEventStatus in your application to determine whether this feature is available. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1657 Preconditions None. Example if((PLIB_POWER_DeepSleepEventStatusGet(POWER_ID_0)& DEEP_SLEEP_EVENT_BOR) != 0) { PLIB_POWER_DeepSleepEventStatusClear(POWER_ID_0, DEEP_SLEEP_EVENT_BOR); //BOR event occurred in Deep Sleep Mode //Therefore, take appropriate action } Parameters Parameters Description index Identifier for the device instance to be configured event The event that occurred during the Deep Sleep Function void PLIB_POWER_DeepSleepEventStatusClear( POWER_MODULE_ID index , DEEP_SLEEP_EVENT event) PLIB_POWER_DeepSleepEventStatusGet Function Returns the events that occurred during Deep Sleep mode. File plib_power.h C DEEP_SLEEP_EVENT PLIB_POWER_DeepSleepEventStatusGet(POWER_MODULE_ID index); Returns DEEP_SLEEP_EVENT - The Event that has occurred during Deep Sleep Description This function returns the events that occurred during Deep Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepEventStatus in your application to determine whether this feature is available. Preconditions None. Example if((PLIB_POWER_DeepSleepEventStatusGet(POWER_ID_0)& (DEEP_SLEEP_EVENT_RTCC_ALARM|DEEP_SLEEP_EVENT_BOR) != 0) { //BOR or RTCC alarm event occurred in Deep Sleep Mode //Therefore, take appropriate action } Parameters Parameters Description index Identifier for the device instance to be configured Function DEEP_SLEEP_EVENT PLIB_POWER_DeepSleepEventStatusGet(POWER_MODULE_ID index) PLIB_POWER_DeepSleepModeHasOccurred Function Returns the Deep Sleep mode status of the device. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1658 File plib_power.h C bool PLIB_POWER_DeepSleepModeHasOccurred(POWER_MODULE_ID index); Returns • true - The device was in Deep Sleep mode before waking up • false - The device was not in Deep Sleep mode Description This function returns whether or not the device was in Deep Sleep mode before waking up. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepModeOccurrence in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_POWER_DeepSleepModeHasOccurred(POWER_ID_0)) { } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_POWER_DeepSleepModeHasOccurred ( POWER_MODULE_ID index) c) HLVD Functions PLIB_POWER_HLVDBandGapVoltageIsStable Function Returns the status of Band Gap voltage. File plib_power.h C bool PLIB_POWER_HLVDBandGapVoltageIsStable(POWER_MODULE_ID index); Returns • true - Band Gap Voltage is stable • false - Band Gap Voltage is unstable Description This function returns whether the Band Gap Voltage is stable or not. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDBandGapVoltageStability in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1659 Example bool BGStatus; BGStatus = PLIB_POWER_HLVDBandGapVoltageIsStable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_POWER_HLVDBandGapVoltageIsStable ( POWER_MODULE_ID index) PLIB_POWER_HLVDDisable Function Disables High/Low-Voltage Detection on VDD. File plib_power.h C void PLIB_POWER_HLVDDisable(POWER_MODULE_ID index); Returns None. Description This function disables the HLVD module. The HLVD module is used to detect high/low-voltage conditions on VDD. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDEnableControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_HLVDDisable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_HLVDDisable ( POWER_MODULE_ID index) PLIB_POWER_HLVDEnable Function Enables High/Low-Voltage Detection (HLVD) on VDD. File plib_power.h C void PLIB_POWER_HLVDEnable(POWER_MODULE_ID index); Returns None. Description This function enables the High/Low-Voltage Detection (HLVD) module. The HLVD module is used to detect high/low-voltage conditions on VDD. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1660 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDEnableControl in your application to determine whether this feature is available. Preconditions Select Low-Voltage or High-Voltage Detection mode by calling PLIB_POWER_HLVDModeSelect. Example PLIB_POWER_HLVDEnable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_HLVDEnable ( POWER_MODULE_ID index) PLIB_POWER_HLVDIsEnabled Function Returns the enable/disable status of High/Low-Voltage Detection on VDD. File plib_power.h C bool PLIB_POWER_HLVDIsEnabled(POWER_MODULE_ID index); Returns • true - HLVD on VDD is enabled • false - HLVD on VDD is not enabled Description This function returns whether or not High/Low-Voltage Detection on VDD is enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDEnableControl in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_POWER_HLVDIsEnabled(POWER_ID_0)) { // HLVD is enabled. } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_POWER_HLVDIsEnabled ( POWER_MODULE_ID index) PLIB_POWER_HLVDLimitSelect Function Selects the HLVD limit. File plib_power.h Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1661 C void PLIB_POWER_HLVDLimitSelect(POWER_MODULE_ID index, HLVD_LIMIT limit); Returns None. Description This function selects voltage limit for HLVD on VDD. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDLimitSelection in your application to determine whether this feature is available. Preconditions The HLVD module should be disabled by calling PLIB_POWER_HLVDDisable. Example PLIB_POWER_HLVDLimitSelect( POWER_ID_0, HLVD_LIMIT_ANALOG_INPUT_ON_HLVDIN ); Parameters Parameters Description index Identifier for the device instance to be configured limit Voltage limit for HLVD on VDD Function void PLIB_POWER_HLVDLimitSelect ( POWER_MODULE_ID index, HLVD_LIMIT limit) PLIB_POWER_HLVDModeSelect Function Selects the Voltage Detection mode. File plib_power.h C void PLIB_POWER_HLVDModeSelect(POWER_MODULE_ID index, HLVD_MODE mode); Returns None. Description This function selects either the High-Voltage or Low-Voltage Detection mode. In High-Voltage Detection (HVD) mode, an event occurs when the voltage equals or exceeds the voltage limit. In Low-Voltage Detection (LVD) mode, an event occurs when the voltage equals or falls below the voltage limit. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDModeControl in your application to determine whether this feature is available. Preconditions The HLVD module should be disabled by calling PLIB_POWER_HLVDDisable. Example PLIB_POWER_HLVDModeSelect( POWER_ID_0, HLVD_MODE_HIGH_VOLTAGE_DETECTION ); Parameters Parameters Description index Identifier for the device instance to be configured mode Voltage Detection mode, either HVD or LVD Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1662 Function void PLIB_POWER_HLVDModeSelect ( POWER_MODULE_ID index, HLVD_MODE mode) PLIB_POWER_HLVDStatusGet Function Returns the HLVD event status. File plib_power.h C bool PLIB_POWER_HLVDStatusGet(POWER_MODULE_ID index); Returns • true - HLVD event interrupt is active • false - HLVD event interrupt is not active Description This function returns the HLVD event interrupt status. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDStatus in your application to determine whether this feature is available. Preconditions None. Example if(PLIB_POWER_HLVDStatusGet(POWER_ID_0)) { //HLVD event has occurred. } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_POWER_HLVDStatusGet( POWER_MODULE_ID index) PLIB_POWER_HLVDStopInIdleDisable Function Continues HLVD operation when the device enters Idle mode. File plib_power.h C void PLIB_POWER_HLVDStopInIdleDisable(POWER_MODULE_ID index); Returns None. Description This function continues HLVD operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDStopInIdleControl in your application to determine whether this feature is available. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1663 Preconditions None. Example PLIB_POWER_HLVDStopInIdleDisable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_HLVDStopInIdleDisable( POWER_MODULE_ID index ) PLIB_POWER_HLVDStopInIdleEnable Function Discontinues HLVD operation when the device enters Idle mode. File plib_power.h C void PLIB_POWER_HLVDStopInIdleEnable(POWER_MODULE_ID index); Returns None. Description This function discontinues HLVD operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDStopInIdleControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_POWER_HLVDStopInIdleEnable(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_POWER_HLVDStopInIdleEnable( POWER_MODULE_ID index ) PLIB_POWER_HLVDStopInIdleIsEnabled Function Returns the Stop in Idle mode status of the HLVD operation. File plib_power.h C bool PLIB_POWER_HLVDStopInIdleIsEnabled(POWER_MODULE_ID index); Returns • true - HLVD discontinues operation when the device enters Idle mode • false - HLVD continues operation when the device enters Idle mode Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1664 Description This function returns whether HLVD continues or discontinues operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsHLVDStopInIdleControl in your application to determine whether this feature is available. Preconditions None. Example bool sidl_status; sidl_status = PLIB_POWER_HLVDStopInIdleIsEnabled(POWER_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_POWER_HLVDStopInIdleIsEnabled( POWER_MODULE_ID index ) d) Deep Sleep Functions PLIB_POWER_DeepSleepGPRRead Function Reads 32-bit data from the Deep Sleep General Purpose Register. File plib_power.h C uint32_t PLIB_POWER_DeepSleepGPRRead(POWER_MODULE_ID index, DEEP_SLEEP_GPR gpr); Returns 32-bit data from the selected Deep Sleep General Purpose Register. Description This function reads 32-bit value from the Deep Sleep General Purpose Register. User can store content in these registers (any application critical content) before entering the Deep Sleep/VBAT modes and read them upon exit. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepGPROperation in your application to determine whether this feature is available. Preconditions The content of the DEEP_SLEEP_GPR_0 register is retained even in the Deep Sleep and VBAT modes, but the DEEP_SLEEP_GPR_1 through DEEP_SLEEP_GPR_32 registers are disabled by default in Deep Sleep and VBAT modes. They can be enabled with PLIB_POWER_DeepSleepGPRsRetentionEnable. Example uint32_t data; //Enable power to DEEP_SLEEP_GPR_1 through DEEP_SLEEP_GPR_32 in Deep Sleep PLIB_POWER_DeepSleepGPRsRetentionEnable(POWER_ID_0); //Write 32-bit data into the DEEP_SLEEP_GPR_1 PLIB_POWER_DeepSleepGPRWrite(POWER_ID_0, DEEP_SLEEP_GPR_1, 0x1234); //Enter the Deep Sleep mode and Exit //Now read the data from DEEP_SLEEP_GPR_1 data = PLIB_POWER_DeepSleepGPRRead(POWER_ID_0, DEEP_SLEEP_GPR_1); Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1665 Parameters Parameters Description index Identifier for the device instance to be configured gpr The available Deep Sleep General Purpose Register Function uint32_t PLIB_POWER_DeepSleepGPRRead( POWER_MODULE_ID index, DEEP_SLEEP_GPR gpr) PLIB_POWER_DeepSleepGPRWrite Function Writes 32-bit data into the Deep Sleep General Purpose Register. File plib_power.h C void PLIB_POWER_DeepSleepGPRWrite(POWER_MODULE_ID index, DEEP_SLEEP_GPR gpr, uint32_t data); Returns None. Description This function accepts a 32-bit value to write into the Deep Sleep General Purpose Register. User can store content in these registers (any application critical content) before entering the Deep Sleep/VBAT modes and read them upon exit. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepGPROperation in your application to determine whether this feature is available. Preconditions The content of the DEEP_SLEEP_GPR_0 register is retained even in the Deep Sleep and VBAT modes, but the DEEP_SLEEP_GPR_1 through DEEP_SLEEP_GPR_32 registers are disabled by default in Deep Sleep and VBAT modes. They can be enabled with PLIB_POWER_DeepSleepGPRsRetentionEnable. Example uint32_t data; //Enable power to DEEP_SLEEP_GPR_1 through DEEP_SLEEP_GPR_32 in Deep Sleep PLIB_POWER_DeepSleepGPRsRetentionEnable(POWER_ID_0); //Write 32-bit data into the DEEP_SLEEP_GPR_1 PLIB_POWER_DeepSleepGPRWrite(POWER_ID_0, DEEP_SLEEP_GPR_1, 0x1234); //Enter the Deep Sleep mode and Exit //Now read the data from DEEP_SLEEP_GPR_1 data = PLIB_POWER_DeepSleepGPRRead(POWER_ID_0, DEEP_SLEEP_GPR_1); Parameters Parameters Description index Identifier for the device instance to be configured gpr The available Deep Sleep General Purpose Register data 32-bit data to write into the Deep Sleep General Purpose Register Function void PLIB_POWER_DeepSleepGPRWrite( POWER_MODULE_ID index, DEEP_SLEEP_GPR gpr, uint32_t data) e) Feature Existence Functions PLIB_POWER_ExistsDeepSleepMode Function Identifies whether the DeepSleepModeControl feature exists on the Power module. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1666 File plib_power.h C bool PLIB_POWER_ExistsDeepSleepMode(POWER_MODULE_ID index); Returns • true - The DeepSleepModeControl feature is supported on the device • false - The DeepSleepModeControl feature is not supported on the device Description This function identifies whether the DeepSleepModeControl feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepModeEnable • PLIB_POWER_DeepSleepModeDisable • PLIB_POWER_DeepSleepModeIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsDeepSleepMode( POWER_MODULE_ID index ) PLIB_POWER_ExistsIdleStatus Function Identifies whether the IdleStatus feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsIdleStatus(POWER_MODULE_ID index); Returns • true - The IdleStatus feature is supported on the device • false - The IdleStatus feature is not supported on the device Description This function identifies whether the IdleStatus feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeviceWasInIdleMode • PLIB_POWER_ClearIdleStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1667 Function PLIB_POWER_ExistsIdleStatus( POWER_MODULE_ID index ) PLIB_POWER_ExistsPeripheralModuleControl Function Identifies whether the PeripheralModuleControl feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsPeripheralModuleControl(POWER_MODULE_ID index); Returns • true - The PeripheralModuleControl feature is supported on the device • false - The PeripheralModuleControl feature is not supported on the device Description This function identifies whether the PeripheralModuleControl feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_PeripheralModuleDisable • PLIB_POWER_PeripheralModuleEnable • PLIB_POWER_PeripheralModuleIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsPeripheralModuleControl( POWER_MODULE_ID index ) PLIB_POWER_ExistsSleepStatus Function Identifies whether the SleepStatus feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsSleepStatus(POWER_MODULE_ID index); Returns • true - The SleepStatus feature is supported on the device • false - The SleepStatus feature is not supported on the device Description This function identifies whether the SleepStatus feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeviceWasInSleepMode • PLIB_POWER_ClearSleepStatus Remarks None. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1668 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsSleepStatus( POWER_MODULE_ID index ) PLIB_POWER_ExistsVoltageRegulatorControl Function Identifies whether the VoltageRegulatorControl feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsVoltageRegulatorControl(POWER_MODULE_ID index); Returns • true - The VoltageRegulatorControl feature is supported on the device • false - The VoltageRegulatorControl feature is not supported on the device Description This function identifies whether the VoltageRegulatorControl feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_VoltageRegulatorEnable • PLIB_POWER_VoltageRegulatorDisable • PLIB_POWER_VoltageRegulatorIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsVoltageRegulatorControl( POWER_MODULE_ID index ) PLIB_POWER_ExistsDeepSleepEventStatus Function Identifies whether the DeepSleepEventStatus feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsDeepSleepEventStatus(POWER_MODULE_ID index); Returns • true - The DeepSleepEventStatus feature is supported on the device • false - The DeepSleepEventStatus feature is not supported on the device Description This function identifies whether the DeepSleepEventStatus feature is available on the Power module. When this function returns true, these Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1669 functions are supported on the device: • PLIB_POWER_DeepSleepEventStatusGet • PLIB_POWER_DeepSleepEventStatusClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsDeepSleepEventStatus( POWER_MODULE_ID index ) PLIB_POWER_ExistsDeepSleepGPROperation Function Identifies whether the DeepSleepGPROperation feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsDeepSleepGPROperation(POWER_MODULE_ID index); Returns • true - The DeepSleepGPROperation feature is supported on the device • false - The DeepSleepGPROperation feature is not supported on the device Description This function identifies whether the DeepSleepGPROperation feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepGPRWrite • PLIB_POWER_DeepSleepGPRRead Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsDeepSleepGPROperation( POWER_MODULE_ID index ) PLIB_POWER_ExistsDeepSleepGPRsRetentionControl Function Identifies whether the DeepSleepGPRsRetentionControl feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsDeepSleepGPRsRetentionControl(POWER_MODULE_ID index); Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1670 Returns • true - The DeepSleepGPRsRetentionControl feature is supported on the device • false - The DeepSleepGPRsRetentionControl feature is not supported on the device Description This function identifies whether the DeepSleepGPRsRetentionControl feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepGPRsRetentionEnable • PLIB_POWER_DeepSleepGPRsRetentionDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsDeepSleepGPRsRetentionControl( POWER_MODULE_ID index ) PLIB_POWER_ExistsDeepSleepModuleControl Function Identifies whether the DeepSleepModuleControl feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsDeepSleepModuleControl(POWER_MODULE_ID index); Returns • true - The DeepSleepModuleControl feature is supported on the device • false - The DeepSleepModuleControl feature is not supported on the device Description This function identifies whether the DeepSleepModuleControl feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepModuleEnable • PLIB_POWER_DeepSleepModuleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsDeepSleepModuleControl( POWER_MODULE_ID index ) PLIB_POWER_ExistsDeepSleepPortPinsStateControl Function Identifies whether the DeepSleepPortPinsStateControl feature exists on the Power module. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1671 File plib_power.h C bool PLIB_POWER_ExistsDeepSleepPortPinsStateControl(POWER_MODULE_ID index); Returns • true - The DeepSleepPortPinsStateControl feature is supported on the device • false - The DeepSleepPortPinsStateControl feature is not supported on the device Description This function identifies whether the DeepSleepPortPinsStateControl feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepPortPinsStateRetain • PLIB_POWER_DeepSleepPortPinsStateRelease Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsDeepSleepPortPinsStateControl( POWER_MODULE_ID index ) PLIB_POWER_ExistsHighVoltageOnVDD1V8 Function Identifies whether the HighVoltageOnVDD1V8 feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsHighVoltageOnVDD1V8(POWER_MODULE_ID index); Returns • true - The HighVoltageOnVDD1V8 feature is supported on the device • false - The HighVoltageOnVDD1V8 feature is not supported on the device Description This function identifies whether the HighVoltageOnVDD1V8 feature is available on the Power module. When this function returns true, this function is supported on the device: • PLIB_POWER_HighVoltageOnVDD1V8HasOccurred Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsHighVoltageOnVDD1V8( POWER_MODULE_ID index ) Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1672 PLIB_POWER_ExistsDeepSleepModeOccurrence Function Identifies whether the DeepSleepModeOccurrence feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsDeepSleepModeOccurrence(POWER_MODULE_ID index); Returns • true - The DeepSleepModeOccurrence feature is supported on the device • false - The DeepSleepModeOccurrence feature is not supported on the device Description This function identifies whether the DeepSleepModeOccurrence feature is available on the Power module. When this function returns true, this function is supported on the device: • PLIB_POWER_DeepSleepModeHasOccurred • PLIB_POWER_DeepSleepStatusClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsDeepSleepModeOccurrence( POWER_MODULE_ID index ) PLIB_POWER_ExistsDeepSleepWakeupEventControl Function Identifies whether the DeepSleepWakeupEventControl feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsDeepSleepWakeupEventControl(POWER_MODULE_ID index); Returns • true - The DeepSleepWakeupEventControl feature is supported on the device • false - The DeepSleepWakeupEventControl feature is not supported on the device Description This function identifies whether the DeepSleepWakeupEventControl feature is available on the Power module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepWakeupEventEnable • PLIB_POWER_DeepSleepWakeupEventDisable Remarks None. Preconditions None. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1673 Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsDeepSleepWakeupEventControl( POWER_MODULE_ID index ) PLIB_POWER_ExistsHLVDBandGapVoltageStability Function Identifies whether the HLVDBandGapVoltageStability feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsHLVDBandGapVoltageStability(POWER_MODULE_ID index); Returns • true - The HLVDBandGapVoltageStability feature is supported on the device • false - The HLVDBandGapVoltageStability feature is not supported on the device Description This function identifies whether the HLVDBandGapVoltageStability feature is available on the Power module. When this function returns true, this function is supported on the device: • PLIB_POWER_HLVDBandGapVoltageIsStable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsHLVDBandGapVoltageStability( POWER_MODULE_ID index ) PLIB_POWER_ExistsHLVDEnableControl Function Identifies whether the HLVDEnableControl feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsHLVDEnableControl(POWER_MODULE_ID index); Returns • true - The HLVDEnableControl feature is supported on the device • false - The HLVDEnableControl feature is not supported on the device Description This function identifies whether the HLVDEnableControl feature is available on the Power module. When this function returns true, this function is supported on the device: • PLIB_POWER_HLVDEnable • PLIB_POWER_HLVDDisable • PLIB_POWER_HLVDIsEnabled Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1674 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsHLVDEnableControl( POWER_MODULE_ID index ) PLIB_POWER_ExistsHLVDLimitSelection Function Identifies whether the HLVDLimitSelection feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsHLVDLimitSelection(POWER_MODULE_ID index); Returns • true - The HLVDLimitSelection feature is supported on the device • false - The HLVDLimitSelection feature is not supported on the device Description This function identifies whether the HLVDLimitSelection feature is available on the Power module. When this function returns true, this function is supported on the device: • PLIB_POWER_HLVDLimitSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsHLVDLimitSelection( POWER_MODULE_ID index ) PLIB_POWER_ExistsHLVDModeControl Function Identifies whether the HLVDModeControl feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsHLVDModeControl(POWER_MODULE_ID index); Returns • true - The HLVDModeControl feature is supported on the device • false - The HLVDModeControl feature is not supported on the device Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1675 Description This function identifies whether the HLVDModeControl feature is available on the Power module. When this function returns true, this function is supported on the device: • PLIB_POWER_HLVDModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsHLVDModeControl( POWER_MODULE_ID index ) PLIB_POWER_ExistsHLVDStatus Function Identifies whether the HLVDStatus feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsHLVDStatus(POWER_MODULE_ID index); Returns • true - The HLVDStatus feature is supported on the device • false - The HLVDStatus feature is not supported on the device Description This function identifies whether the HLVDStatus feature is available on the Power module. When this function returns true, this function is supported on the device: • PLIB_POWER_HLVDStatusGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsHLVDStatus( POWER_MODULE_ID index ) PLIB_POWER_ExistsHLVDStopInIdleControl Function Identifies whether the HLVDStopInIdleControl feature exists on the Power module. File plib_power.h C bool PLIB_POWER_ExistsHLVDStopInIdleControl(POWER_MODULE_ID index); Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1676 Returns • true - The HLVDStopInIdleControl feature is supported on the device • false - The HLVDStopInIdleControl feature is not supported on the device Description This function identifies whether the HLVDStopInIdleControl feature is available on the Power module. When this function returns true, this function is supported on the device: • PLIB_POWER_HLVDStopInIdleEnable • PLIB_POWER_HLVDStopInIdleDisable • PLIB_POWER_HLVDStopInIdleIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_POWER_ExistsHLVDStopInIdleControl( POWER_MODULE_ID index ) f) Data Types and Constants DEEP_SLEEP_EVENT Enumeration Lists the events that occurred during Deep Sleep mode. File help_plib_power.h C typedef enum { DEEP_SLEEP_EVENT_BOR, DEEP_SLEEP_EVENT_RTCC_ALARM, DEEP_SLEEP_EVENT_EXTERNAL_INTERRUPT, DEEP_SLEEP_EVENT_FAULT_DETECTION, DEEP_SLEEP_EVENT_WDT_TIMEOUT, DEEP_SLEEP_EVENT_MCLR } DEEP_SLEEP_EVENT; Members Members Description DEEP_SLEEP_EVENT_BOR BOR event has occurred during Deep Sleep DEEP_SLEEP_EVENT_RTCC_ALARM RTCC alarm has occurred during Deep Sleep DEEP_SLEEP_EVENT_EXTERNAL_INTERRUPT Interrupt-On-Change on pin INT0 has occurred during Deep Sleep DEEP_SLEEP_EVENT_FAULT_DETECTION Fault has occurred during Deep Sleep and some Deep Sleep configuration settings may have been corrupted DEEP_SLEEP_EVENT_WDT_TIMEOUT DSWDT time-out has occurred during Deep Sleep DEEP_SLEEP_EVENT_MCLR Master Clear (MCLR) has occurred during Deep Sleep Description Deep Sleep events This enumeration lists the events that occurred during Deep Sleep mode. Remarks Not all events exist on all devices. Please refer to the specific device data sheet for availability. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1677 DEEP_SLEEP_GPR Enumeration Lists the Deep Sleep General Purpose Registers (GPRs). File help_plib_power.h C typedef enum { DEEP_SLEEP_GPR_0, DEEP_SLEEP_GPR_1, DEEP_SLEEP_GPR_2, DEEP_SLEEP_GPR_3, DEEP_SLEEP_GPR_4, DEEP_SLEEP_GPR_5, DEEP_SLEEP_GPR_6, DEEP_SLEEP_GPR_7, DEEP_SLEEP_GPR_8, DEEP_SLEEP_GPR_9, DEEP_SLEEP_GPR_10, DEEP_SLEEP_GPR_11, DEEP_SLEEP_GPR_12, DEEP_SLEEP_GPR_13, DEEP_SLEEP_GPR_14, DEEP_SLEEP_GPR_15, DEEP_SLEEP_GPR_16, DEEP_SLEEP_GPR_17, DEEP_SLEEP_GPR_18, DEEP_SLEEP_GPR_19, DEEP_SLEEP_GPR_20, DEEP_SLEEP_GPR_21, DEEP_SLEEP_GPR_22, DEEP_SLEEP_GPR_23, DEEP_SLEEP_GPR_24, DEEP_SLEEP_GPR_25, DEEP_SLEEP_GPR_26, DEEP_SLEEP_GPR_27, DEEP_SLEEP_GPR_28, DEEP_SLEEP_GPR_29, DEEP_SLEEP_GPR_30, DEEP_SLEEP_GPR_31, DEEP_SLEEP_GPR_32 } DEEP_SLEEP_GPR; Members Members Description DEEP_SLEEP_GPR_0 Deep Sleep General Purpose Register 0. This will be active in Deep Sleep by default. DEEP_SLEEP_GPR_1 Deep Sleep General Purpose Register 1. DEEP_SLEEP_GPR_2 Deep Sleep General Purpose Register 2. DEEP_SLEEP_GPR_3 Deep Sleep General Purpose Register 3. DEEP_SLEEP_GPR_4 Deep Sleep General Purpose Register 4. DEEP_SLEEP_GPR_5 Deep Sleep General Purpose Register 5. DEEP_SLEEP_GPR_6 Deep Sleep General Purpose Register 6. DEEP_SLEEP_GPR_7 Deep Sleep General Purpose Register 7. DEEP_SLEEP_GPR_8 Deep Sleep General Purpose Register 8. DEEP_SLEEP_GPR_9 Deep Sleep General Purpose Register 9. DEEP_SLEEP_GPR_10 Deep Sleep General Purpose Register 10. DEEP_SLEEP_GPR_11 Deep Sleep General Purpose Register 11. DEEP_SLEEP_GPR_12 Deep Sleep General Purpose Register 12. DEEP_SLEEP_GPR_13 Deep Sleep General Purpose Register 13. DEEP_SLEEP_GPR_14 Deep Sleep General Purpose Register 14. DEEP_SLEEP_GPR_15 Deep Sleep General Purpose Register 15. DEEP_SLEEP_GPR_16 Deep Sleep General Purpose Register 16. DEEP_SLEEP_GPR_17 Deep Sleep General Purpose Register 17. Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1678 DEEP_SLEEP_GPR_18 Deep Sleep General Purpose Register 18. DEEP_SLEEP_GPR_19 Deep Sleep General Purpose Register 19. DEEP_SLEEP_GPR_20 Deep Sleep General Purpose Register 20. DEEP_SLEEP_GPR_21 Deep Sleep General Purpose Register 21. DEEP_SLEEP_GPR_22 Deep Sleep General Purpose Register 22. DEEP_SLEEP_GPR_23 Deep Sleep General Purpose Register 23. DEEP_SLEEP_GPR_24 Deep Sleep General Purpose Register 24. DEEP_SLEEP_GPR_25 Deep Sleep General Purpose Register 25. DEEP_SLEEP_GPR_26 Deep Sleep General Purpose Register 26. DEEP_SLEEP_GPR_27 Deep Sleep General Purpose Register 27. DEEP_SLEEP_GPR_28 Deep Sleep General Purpose Register 28. DEEP_SLEEP_GPR_29 Deep Sleep General Purpose Register 29. DEEP_SLEEP_GPR_30 Deep Sleep General Purpose Register 30. DEEP_SLEEP_GPR_31 Deep Sleep General Purpose Register 31. DEEP_SLEEP_GPR_32 Deep Sleep General Purpose Register 32. Description Deep Sleep General Purpose Register set. This enumeration lists the Deep Sleep General Purpose Registers. These registers can be used to save some application critical content while entering into Deep Sleep mode and can be read upon exit. Remarks Not all GPRs exist on all devices. Please refer to the specific device data sheet for availability. DEEP_SLEEP_MODULE Enumeration Lists the modules that can be enabled/disabled during Deep Sleep mode. File help_plib_power.h C typedef enum { DEEP_SLEEP_MODULE_RTCC } DEEP_SLEEP_MODULE; Members Members Description DEEP_SLEEP_MODULE_RTCC RTCC module Description Deep Sleep Module This enumeration lists the modules that can be enabled/disabled during Deep Sleep mode. Remarks Not all modules exist on all devices. Please refer to the specific device data sheet for availability. DEEP_SLEEP_WAKE_UP_EVENT Enumeration Lists the events that can be used to wake the device from Deep Sleep mode. File help_plib_power.h C typedef enum { DEEP_SLEEP_WAKE_UP_EVENT_RTCC, DEEP_SLEEP_WAKE_UP_EVENT_EXTERNAL_INTERRUPT } DEEP_SLEEP_WAKE_UP_EVENT; Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1679 Members Members Description DEEP_SLEEP_WAKE_UP_EVENT_RTCC Deep Sleep wake-up by RTCC alarm event DEEP_SLEEP_WAKE_UP_EVENT_EXTERNAL_INTERRUPT Deep Sleep wake-up by Interrupt-On-Change (IOC) on INT0 pin Description Deep Sleep Wake-up events This enumeration lists the events that can be used to wake the device from Deep Sleep mode. Remarks Not all events exist on all devices. Please refer to the specific device data sheet for availability. POWER_MODULE Enumeration List of the modules whose power can be controlled. File help_plib_power.h C typedef enum { POWER_MODULE_ADC1, POWER_MODULE_CTMU, POWER_MODULE_CVR, POWER_MODULE_HLVD, POWER_MODULE_HVD1V8, POWER_MODULE_CMP1, POWER_MODULE_CMP2, POWER_MODULE_CMP3, POWER_MODULE_IC1, POWER_MODULE_IC2, POWER_MODULE_IC3, POWER_MODULE_IC4, POWER_MODULE_IC5, POWER_MODULE_IC6, POWER_MODULE_IC7, POWER_MODULE_IC8, POWER_MODULE_IC9, POWER_MODULE_OC1, POWER_MODULE_OC2, POWER_MODULE_OC3, POWER_MODULE_OC4, POWER_MODULE_OC5, POWER_MODULE_OC6, POWER_MODULE_OC7, POWER_MODULE_OC8, POWER_MODULE_OC9, POWER_MODULE_TMR1, POWER_MODULE_TMR2, POWER_MODULE_TMR3, POWER_MODULE_TMR4, POWER_MODULE_TMR5, POWER_MODULE_TMR6, POWER_MODULE_TMR7, POWER_MODULE_TMR8, POWER_MODULE_TMR9, POWER_MODULE_UART1, POWER_MODULE_UART2, POWER_MODULE_UART3, POWER_MODULE_UART4, POWER_MODULE_UART5, POWER_MODULE_UART6, POWER_MODULE_SPI1, POWER_MODULE_SPI2, POWER_MODULE_SPI3, POWER_MODULE_SPI4, POWER_MODULE_SPI5, POWER_MODULE_SPI6, POWER_MODULE_I2C1, Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1680 POWER_MODULE_I2C2, POWER_MODULE_I2C3, POWER_MODULE_I2C4, POWER_MODULE_I2C5, POWER_MODULE_USB, POWER_MODULE_CAN1, POWER_MODULE_CAN2, POWER_MODULE_RTCC, POWER_MODULE_REF_CLK_OUTPUT, POWER_MODULE_REF_CLK_OUTPUT1, POWER_MODULE_REF_CLK_OUTPUT2, POWER_MODULE_REF_CLK_OUTPUT3, POWER_MODULE_REF_CLK_OUTPUT4, POWER_MODULE_REF_CLK_OUTPUT5, POWER_MODULE_PMP, POWER_MODULE_EBI, POWER_MODULE_GPU, POWER_MODULE_GLCD, POWER_MODULE_SDHC, POWER_MODULE_SQI, POWER_MODULE_ETHERNET, POWER_MODULE_DMA, POWER_MODULE_RANDOM_NUM_GENERATOR, POWER_MODULE_DDR2, POWER_MODULE_CRYPTO } POWER_MODULE; Members Members Description POWER_MODULE_ADC1 ADC module POWER_MODULE_CTMU Charge Time Measurement Unit module POWER_MODULE_CVR Comparator Voltage Reference module POWER_MODULE_HLVD Low-Voltage Detection module POWER_MODULE_HVD1V8 High-Voltage Detection module POWER_MODULE_CMP1 Comparator module 1 POWER_MODULE_CMP2 Comparator module 2 POWER_MODULE_CMP3 Comparator module 3 POWER_MODULE_IC1 Input Capture 1 module POWER_MODULE_IC2 Input Capture 2 module POWER_MODULE_IC3 Input Capture 3 module POWER_MODULE_IC4 Input Capture 4 module POWER_MODULE_IC5 Input Capture 5 module POWER_MODULE_IC6 Input Capture 6 module POWER_MODULE_IC7 Input Capture 7 module POWER_MODULE_IC8 Input Capture 8 module POWER_MODULE_IC9 Input Capture 9 module POWER_MODULE_OC1 Output Compare 1 module POWER_MODULE_OC2 Output Compare 2 module POWER_MODULE_OC3 Output Compare 3 module POWER_MODULE_OC4 Output Compare 4 module POWER_MODULE_OC5 Output Compare 5 module POWER_MODULE_OC6 Output Compare 6 module POWER_MODULE_OC7 Output Compare 7 module POWER_MODULE_OC8 Output Compare 8 module POWER_MODULE_OC9 Output Compare 9 module POWER_MODULE_TMR1 Timer1 module POWER_MODULE_TMR2 Timer2 module POWER_MODULE_TMR3 Timer3 module POWER_MODULE_TMR4 Timer4 module POWER_MODULE_TMR5 Timer5 module POWER_MODULE_TMR6 Timer6 module POWER_MODULE_TMR7 Timer7 module Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1681 POWER_MODULE_TMR8 Timer8 module POWER_MODULE_TMR9 Timer9 module POWER_MODULE_UART1 UART1 module POWER_MODULE_UART2 UART2 module POWER_MODULE_UART3 UART3 module POWER_MODULE_UART4 UART4 module POWER_MODULE_UART5 UART5 module POWER_MODULE_UART6 UART6 module POWER_MODULE_SPI1 SPI1 module POWER_MODULE_SPI2 SPI2 module POWER_MODULE_SPI3 SPI3 module POWER_MODULE_SPI4 SPI4 module POWER_MODULE_SPI5 SPI5 module POWER_MODULE_SPI6 SPI6 module POWER_MODULE_I2C1 I2C1 module POWER_MODULE_I2C2 I2C2 module POWER_MODULE_I2C3 I2C3 module POWER_MODULE_I2C4 I2C4 module POWER_MODULE_I2C5 I2C5 module POWER_MODULE_USB USB module POWER_MODULE_CAN1 CAN1 module POWER_MODULE_CAN2 CAN2 module POWER_MODULE_RTCC Real-Time Clock and Calender module POWER_MODULE_REF_CLK_OUTPUT Reference Clock Output module POWER_MODULE_REF_CLK_OUTPUT1 Reference Clock Output module 1 POWER_MODULE_REF_CLK_OUTPUT2 Reference Clock Output module 2 POWER_MODULE_REF_CLK_OUTPUT3 Reference Clock Output module 3 POWER_MODULE_REF_CLK_OUTPUT4 Reference Clock Output module 4 POWER_MODULE_REF_CLK_OUTPUT5 Reference Clock Output module 5 POWER_MODULE_PMP Parallel Master Port module POWER_MODULE_EBI External Bus Interface module POWER_MODULE_GPU Graphics Processing Unit module POWER_MODULE_GLCD Graphics LCD module POWER_MODULE_SDHC Secure Digital Host Controller module POWER_MODULE_SQI Serial Quad Interface module POWER_MODULE_ETHERNET Ethernet module POWER_MODULE_DMA Data Memory Access module POWER_MODULE_RANDOM_NUM_GENERATOR Random Number Generator module POWER_MODULE_DDR2 DDR2 module POWER_MODULE_CRYPTO Cryptographic module Description POWER module enumeration This enumeration lists the modules whose power can be controlled by the Peripheral Module Disable (PMD) Registers. Remarks Not all modules exist on all devices. Please refer to the specific device data sheet for availability. POWER_MODULE_ID Enumeration Identifies the supported Power modules. File help_plib_power.h C typedef enum { Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1682 POWER_ID_0, POWER_NUMBER_OF_MODULES } POWER_MODULE_ID; Members Members Description POWER_ID_0 POWER Module ID POWER_NUMBER_OF_MODULES Number of available POWER modules. Description Power Module ID This enumeration identifies the Power modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on a Microchip microcontroller. Remarks The caller should not rely on the specific numbers assigned to any of these values, as they may change from one processor to the next. Not all modules are available on all microcontrollers. Refer to the "Power-Saving Features" chapter in the specific device data sheet to determine which modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. HLVD_LIMIT Enumeration Lists the voltage limits for the HLVD module. File help_plib_power.h C typedef enum { HLVD_LIMIT_TRIP_POINT_4, HLVD_LIMIT_TRIP_POINT_5, HLVD_LIMIT_TRIP_POINT_6, HLVD_LIMIT_TRIP_POINT_7, HLVD_LIMIT_TRIP_POINT_8, HLVD_LIMIT_TRIP_POINT_9, HLVD_LIMIT_TRIP_POINT_10, HLVD_LIMIT_TRIP_POINT_11, HLVD_LIMIT_TRIP_POINT_12, HLVD_LIMIT_TRIP_POINT_13, HLVD_LIMIT_TRIP_POINT_14, HLVD_LIMIT_ANALOG_INPUT_ON_HLVDIN } HLVD_LIMIT; Members Members Description HLVD_LIMIT_TRIP_POINT_4 Voltage limit is trip point 4 HLVD_LIMIT_TRIP_POINT_5 Voltage limit is trip point 5 HLVD_LIMIT_TRIP_POINT_6 Voltage limit is trip point 6 HLVD_LIMIT_TRIP_POINT_7 Voltage limit is trip point 7 HLVD_LIMIT_TRIP_POINT_8 Voltage limit is trip point 8 HLVD_LIMIT_TRIP_POINT_9 Voltage limit is trip point 9 HLVD_LIMIT_TRIP_POINT_10 Voltage limit is trip point 10 HLVD_LIMIT_TRIP_POINT_11 Voltage limit is trip point 11 HLVD_LIMIT_TRIP_POINT_12 Voltage limit is trip point 12 HLVD_LIMIT_TRIP_POINT_13 Voltage limit is trip point 13 HLVD_LIMIT_TRIP_POINT_14 Voltage limit is trip point 14 HLVD_LIMIT_ANALOG_INPUT_ON_HLVDIN Voltage limit is external analog voltage on the pin HLVDIN Description High/Low-Voltage Detection limits This enumeration lists the voltage limits that can be used as reference to High/Low-Voltage Detection on VDD. Refer to the “Electrical Characteristics― chapter of the specific device data sheet for the actual trip points (i.e., voltages). Peripheral Libraries Help Power Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1683 Remarks Not all voltage limits exist on all devices. Please refer to the specific device data sheet for availability. HLVD_MODE Enumeration Lists the modes for the High/Low Voltage Detection (HLVD) module. File help_plib_power.h C typedef enum { HLVD_MODE_LOW_VOLTAGE_DETECTION, HLVD_MODE_HIGH_VOLTAGE_DETECTION } HLVD_MODE; Members Members Description HLVD_MODE_LOW_VOLTAGE_DETECTION In Low-Voltage Detection (LVD) mode, an event occurs when the voltage equals or falls below the voltage limit. HLVD_MODE_HIGH_VOLTAGE_DETECTION In High-Voltage Detection (HVD) mode, an event occurs when the voltage equals or exceeds the voltage limit. Description High/Low-Voltage Detection modes This enumeration lists the modes those can be used for High/Low Voltage Detection on VDD. Remarks None. Files Files Name Description plib_power.h Defines the Power Peripheral Library interface. help_plib_power.h This is file help_plib_power.h. Description This section lists the source and header files used by the library. plib_power.h Defines the Power Peripheral Library interface. Functions Name Description PLIB_POWER_ClearIdleStatus Clears the Idle mode status of the device. PLIB_POWER_ClearSleepStatus Clear the Sleep mode status bit of the device. PLIB_POWER_DeepSleepEventStatusClear Clear any events that occurred during Deep Sleep mode. PLIB_POWER_DeepSleepEventStatusGet Returns the events that occurred during Deep Sleep mode. PLIB_POWER_DeepSleepGPRRead Reads 32-bit data from the Deep Sleep General Purpose Register. PLIB_POWER_DeepSleepGPRsRetentionDisable Disables the General Purpose Registers retention. PLIB_POWER_DeepSleepGPRsRetentionEnable Enables the General Purpose Registers retention. PLIB_POWER_DeepSleepGPRWrite Writes 32-bit data into the Deep Sleep General Purpose Register. PLIB_POWER_DeepSleepModeDisable Disables Deep Sleep mode. PLIB_POWER_DeepSleepModeEnable Enables Deep Sleep mode. PLIB_POWER_DeepSleepModeHasOccurred Returns the Deep Sleep mode status of the device. PLIB_POWER_DeepSleepModeIsEnabled Returns the enable/disable status of Deep Sleep mode. Peripheral Libraries Help Power Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1684 PLIB_POWER_DeepSleepModuleDisable Disables the module in Deep Sleep mode. PLIB_POWER_DeepSleepModuleEnable Enables the module in Deep Sleep mode. PLIB_POWER_DeepSleepPortPinsStateRelease Releases I/O pins upon wake-up from Deep Sleep mode. PLIB_POWER_DeepSleepPortPinsStateRetain Enables the I/O pins to retain their previous states upon wake-up from Deep Sleep mode. PLIB_POWER_DeepSleepStatusClear Clears the Deep Sleep mode status bit of the device. PLIB_POWER_DeepSleepWakeupEventDisable Disables wake-up from Deep Sleep mode by the selected event. PLIB_POWER_DeepSleepWakeupEventEnable Enables wake-up from the Deep Sleep mode by the selected event. PLIB_POWER_DeviceWasInIdleMode Returns the Idle mode status of the device. PLIB_POWER_DeviceWasInSleepMode Returns the Sleep mode status of the device. PLIB_POWER_ExistsDeepSleepEventStatus Identifies whether the DeepSleepEventStatus feature exists on the Power module. PLIB_POWER_ExistsDeepSleepGPROperation Identifies whether the DeepSleepGPROperation feature exists on the Power module. PLIB_POWER_ExistsDeepSleepGPRsRetentionControl Identifies whether the DeepSleepGPRsRetentionControl feature exists on the Power module. PLIB_POWER_ExistsDeepSleepMode Identifies whether the DeepSleepModeControl feature exists on the Power module. PLIB_POWER_ExistsDeepSleepModeOccurrence Identifies whether the DeepSleepModeOccurrence feature exists on the Power module. PLIB_POWER_ExistsDeepSleepModuleControl Identifies whether the DeepSleepModuleControl feature exists on the Power module. PLIB_POWER_ExistsDeepSleepPortPinsStateControl Identifies whether the DeepSleepPortPinsStateControl feature exists on the Power module. PLIB_POWER_ExistsDeepSleepWakeupEventControl Identifies whether the DeepSleepWakeupEventControl feature exists on the Power module. PLIB_POWER_ExistsHighVoltageOnVDD1V8 Identifies whether the HighVoltageOnVDD1V8 feature exists on the Power module. PLIB_POWER_ExistsHLVDBandGapVoltageStability Identifies whether the HLVDBandGapVoltageStability feature exists on the Power module. PLIB_POWER_ExistsHLVDEnableControl Identifies whether the HLVDEnableControl feature exists on the Power module. PLIB_POWER_ExistsHLVDLimitSelection Identifies whether the HLVDLimitSelection feature exists on the Power module. PLIB_POWER_ExistsHLVDModeControl Identifies whether the HLVDModeControl feature exists on the Power module. PLIB_POWER_ExistsHLVDStatus Identifies whether the HLVDStatus feature exists on the Power module. PLIB_POWER_ExistsHLVDStopInIdleControl Identifies whether the HLVDStopInIdleControl feature exists on the Power module. PLIB_POWER_ExistsIdleStatus Identifies whether the IdleStatus feature exists on the Power module. PLIB_POWER_ExistsPeripheralModuleControl Identifies whether the PeripheralModuleControl feature exists on the Power module. PLIB_POWER_ExistsSleepStatus Identifies whether the SleepStatus feature exists on the Power module. PLIB_POWER_ExistsVoltageRegulatorControl Identifies whether the VoltageRegulatorControl feature exists on the Power module. PLIB_POWER_HighVoltageOnVDD1V8HasOccurred Returns the DDR2 High Voltage Detection status of the device. PLIB_POWER_HLVDBandGapVoltageIsStable Returns the status of Band Gap voltage. PLIB_POWER_HLVDDisable Disables High/Low-Voltage Detection on VDD. PLIB_POWER_HLVDEnable Enables High/Low-Voltage Detection (HLVD) on VDD. PLIB_POWER_HLVDIsEnabled Returns the enable/disable status of High/Low-Voltage Detection on VDD. PLIB_POWER_HLVDLimitSelect Selects the HLVD limit. PLIB_POWER_HLVDModeSelect Selects the Voltage Detection mode. PLIB_POWER_HLVDStatusGet Returns the HLVD event status. PLIB_POWER_HLVDStopInIdleDisable Continues HLVD operation when the device enters Idle mode. PLIB_POWER_HLVDStopInIdleEnable Discontinues HLVD operation when the device enters Idle mode. PLIB_POWER_HLVDStopInIdleIsEnabled Returns the Stop in Idle mode status of the HLVD operation. PLIB_POWER_PeripheralModuleDisable Disable the power supply for the module selected in the source. PLIB_POWER_PeripheralModuleEnable Enable the power supply for the module selected in the source. PLIB_POWER_PeripheralModuleIsEnabled Checks to see whether or not the selected peripheral is enabled. Peripheral Libraries Help Power Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1685 PLIB_POWER_VoltageRegulatorDisable Disables the voltage regulator during Sleep mode. PLIB_POWER_VoltageRegulatorEnable Enable the voltage regulator during Sleep mode. PLIB_POWER_VoltageRegulatorIsEnabled Provides the status of the voltage regulator during Sleep mode. Description Power Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Power Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Power Controller module. File Name plib_power.h Company Microchip Technology Inc. help_plib_power.h Enumerations Name Description DEEP_SLEEP_EVENT Lists the events that occurred during Deep Sleep mode. DEEP_SLEEP_GPR Lists the Deep Sleep General Purpose Registers (GPRs). DEEP_SLEEP_MODULE Lists the modules that can be enabled/disabled during Deep Sleep mode. DEEP_SLEEP_WAKE_UP_EVENT Lists the events that can be used to wake the device from Deep Sleep mode. HLVD_LIMIT Lists the voltage limits for the HLVD module. HLVD_MODE Lists the modes for the High/Low Voltage Detection (HLVD) module. POWER_MODULE List of the modules whose power can be controlled. POWER_MODULE_ID Identifies the supported Power modules. Description This is file help_plib_power.h. Peripheral Libraries Help Power Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1686 Reset Peripheral Library This section describes the Reset Peripheral Library. Introduction This library provides a low-level abstraction of the Reset Controller modules on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The Reset Controller is a key component of a microcontroller. The Reset Controller gives the reset status of the device at any point of time. The following are the key features present on a Reset Controller: • Reset Source Configuration: Provides the ability to enable and disable a source that may reset the device • Reset Status: Identifies the source of a reset and clears it A microcontroller can support one or more of the previously described reset modes. Note: Please refer to the "Resets" chapter in the specific device data sheet to determine the exact set of supported features. Using the Library This topic describes the basic architecture of the Reset Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_reset.h The interface to the Reset Peripheral Library is defined in the plib_reset.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Reset Peripheral Library must include peripheral.h. Peripheral Module IDs Peripheral libraries are indexed to allow a single library to control any number of instances of a peripheral in a single microcontroller. To support this, the first parameter to each operation in a peripheral library is the module instance ID. The module instance ID is defined by an enumeration that is defined in the processor-specific header files (included by the library's interface header). Not all microcontrollers will have all instances of the module listed in this enumeration. Please refer to the "Resets" chapter in the specific device data sheet for availability. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the Reset Controller module on Microchip PIC microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The following figure illustrates the hardware abstraction model for the Reset Peripheral Library. Hardware Abstraction Model Peripheral Libraries Help Reset Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1687 The Reset Controller receives requests from multiple Reset Sources. The Reset Controller controls the overall operation of the reset controller. Source Enable Configuration enables or disables a particular source of reset. Some of the reset sources such as Traps are not controlled by the users, whereas others can be user controlled. Note: Not all features are available on all devices. Refer to the "Resets" chapter in the specific device data sheet for availability. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Reset Controller module. Library Interface Section Description Initialization Functions This section provides a set of functions for configuring and enabling a reset. Status Functions This section provides a function to read the status of a particular reset. NMI Events Functions This section provides functions for NMI events. Feature Existence Functions This section provides functions that determine whether certain features exist. Note: Please refer to the "Resets" chapter in the specific device data sheet to determine the exact set of supported features. How the Library Works Initialization The steps that are required to initialize the Reset Controller module vary for different microcontrollers. Refer to the "Resets" chapter in the specific device data sheet for the correct initialization sequence. The following information provides a general overview. Description Reset Source Setup Some reset sources need to be enabled for it to be able to Reset the device. Use the function PLIB_RESET_SoftwareResetEnable to enable the reset source. Reset Status The status of the reset indicates which source generated the reset. The status of the reset source can be obtained using the function PLIB_RESET_ReasonGet. The reason for the reset can be cleared using the function PLIB_RESET_ReasonClear. Peripheral Libraries Help Reset Peripheral Library Configuring the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1688 Configuring the Library The library is configured for the supported Reset Controller modules when the processor is chosen in the MPLAB X IDE. Library Interface a) Initialization Functions Name Description PLIB_RESET_SoftwareResetEnable Enables the software reset. b) Status Functions Name Description PLIB_RESET_ReasonClear Clears the RCON register. PLIB_RESET_ReasonGet Returns the reason for a reset. PLIB_RESET_ConfigRegReadErrorGet Gets the Configuration register read error. PLIB_RESET_WdtTimeOutHasOccurredInSleep Returns the state of the device when WDT time-out occurred c) NMI Events Functions Name Description PLIB_RESET_NmiCounterValueGet Gets the NMI counter value. PLIB_RESET_NmiCounterValueSet Sets the NMI counter. PLIB_RESET_NmiEventClear Clears the NMI event PLIB_RESET_NmiEventTrigger Triggers the NMI event. PLIB_RESET_NmiReasonGet Returns the reason for the Non-Maskable Interrupt (NMI). d) Feature Existence Functions Name Description PLIB_RESET_ExistsResetReasonStatus Identifies whether the ResetReasonStatus feature exists on the Reset module. PLIB_RESET_ExistsSoftwareResetTrigger Identifies whether the SoftwareResetTrigger feature exists on the Reset module. PLIB_RESET_ExistsConfigRegReadError Identifies whether the ConfigRegReadError feature exists on the Reset module. PLIB_RESET_ExistsNmiControl Identifies whether the NmiControl feature exists on the Reset module. PLIB_RESET_ExistsNmiCounter Identifies whether the NmiCounter feature exists on the Reset module. PLIB_RESET_ExistsWdtoInSleep Identifies whether the WdtoInSleep feature exists on the Reset module. e) Data Types and Constants Name Description RESET_MODULE_ID Identifies the supported Reset modules. RESET_REASON Lists the reset sources. RESET_CONFIG_REG_READ_ERROR Lists the Configuration register read errors. RESET_NMI_COUNT_TYPE Defines NMI counter data type RESET_NMI_REASON Lists the NMI reasons. Description This section describes the Application Programming Interface (API) functions of the Reset Peripheral Library. Refer to each section for a detailed description. a) Initialization Functions PLIB_RESET_SoftwareResetEnable Function Enables the software reset. File plib_reset.h Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1689 C void PLIB_RESET_SoftwareResetEnable(RESET_MODULE_ID index); Returns None. Description This function triggers a software reset. Remarks This function implements an operation of the SoftwareResetTrigger feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsSoftwareResetTrigger function in your application to determine whether this feature is available. Preconditions The system unlock sequence must be performed before calling PLIB_RESET_SoftwareResetEnable. Example //Call system service to unlock the system PLIB_RESET_SoftwareResetEnable( RESET_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RESET_SoftwareResetEnable ( RESET_MODULE_ID index ) b) Status Functions PLIB_RESET_ReasonClear Function Clears the RCON register. File plib_reset.h C void PLIB_RESET_ReasonClear(RESET_MODULE_ID index, RESET_REASON reason); Returns None Description This function clears the particular reset bit in the RCON register. Multiple reasons for a reset can be ORed together and given as an input parameter to clear them simultaneously. Remarks This function implements an operation of the ResetReasonStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsResetReasonStatus function in your application to determine whether this feature is available. Preconditions None. Example PLIB_RESET_ReasonClear( RESET_ID_0, RESET_REASON_MCLR | RESET_REASON_POWERON ); Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1690 Parameters Parameters Description index Identifier for the device instance to be configured reason Select the reset type from enum RESET_REASON Function void PLIB_RESET_ReasonClear( RESET_MODULE_ID index, RESET_REASON reason ) PLIB_RESET_ReasonGet Function Returns the reason for a reset. File plib_reset.h C RESET_REASON PLIB_RESET_ReasonGet(RESET_MODULE_ID index); Returns RESET_REASON - Type of reset (when there is more than one reason for a reset, this function will logically OR (bitwise) the reasons and return the value. Description This function returns the reason a reset has occurred for the selected device. Remarks This function implements an operation of the ResetReasonStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsResetReasonStatus function in your application to determine whether this feature is available. Preconditions None. Example RESET_REASON type; type = PLIB_RESET_ReasonGet ( RESET_ID_0 ); Parameters Parameters Description index Identifier for the device instance to be configured Function RESET_REASON PLIB_RESET_ReasonGet ( RESET_MODULE_ID index ) PLIB_RESET_ConfigRegReadErrorGet Function Gets the Configuration register read error. File plib_reset.h C RESET_CONFIG_REG_READ_ERROR PLIB_RESET_ConfigRegReadErrorGet(RESET_MODULE_ID index); Returns RESET_CONFIG_REG_READ_ERROR - Type of Configuration Register Read Error Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1691 Description This function returns the Configuration register read error, if any, after the reset. Remarks This function implements an operation of the ConfigRegReadError feature. This feature may not be available on all devices. Refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsConfigRegReadError function in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_RESET_ConfigRegReadErrorGet( RESET_ID_0 )== PRIMARY_CONFIG_REG_READ_ERROR ) { //Do Something } Parameters Parameters Description index Identifier for the device instance to be configured Function RESET_CONFIG_REG_READ_ERROR PLIB_RESET_ConfigRegReadErrorGet( RESET_MODULE_ID index ); PLIB_RESET_WdtTimeOutHasOccurredInSleep Function Returns the state of the device when WDT time-out occurred File plib_reset.h C bool PLIB_RESET_WdtTimeOutHasOccurredInSleep(RESET_MODULE_ID index); Returns • true - The device was in Sleep mode when a WDT time-out occurred • false - The device was not in Sleep mode when a WDT time-out occurred Description This function returns whether or not the the device was in Sleep mode when a WDT time-out event occurred. Remarks This function implements an operation of the WdtoInSleep feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsWdtoInSleep function in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_RESET_WdtTimeOutHasOccurredInSleep( RESET_ID_0 )) { //Do Something } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_RESET_WdtTimeOutHasOccurredInSleep ( RESET_MODULE_ID index ) Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1692 c) NMI Events Functions PLIB_RESET_NmiCounterValueGet Function Gets the NMI counter value. File plib_reset.h C RESET_NMI_COUNT_TYPE PLIB_RESET_NmiCounterValueGet(RESET_MODULE_ID index); Returns nmi_count - NMI counter value Description This function returns the NMI Reset counter value. Remarks This function implements an operation of the NmiCounter feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiCounter function in your application to determine whether this feature is available. Preconditions None. Example RESET_NMI_COUNT_TYPE nmi_count; nmi_count = PLIB_RESET_NmiCounterValueGet( RESET_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function RESET_NMI_COUNT_TYPE PLIB_RESET_NmiCounterValueGet ( RESET_MODULE_ID index ) PLIB_RESET_NmiCounterValueSet Function Sets the NMI counter. File plib_reset.h C void PLIB_RESET_NmiCounterValueSet(RESET_MODULE_ID index, RESET_NMI_COUNT_TYPE nmi_count); Returns None. Description This function sets the NMI counter to be expired for a WDT or DMT reset. Remarks NMI counter value range may vary between devices. Please refer to the specific device data sheet. This function implements an operation of the NmiCounter feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiCounter function in your application to determine whether this feature is available. Preconditions The system unlock sequence must be performed before calling PLIB_RESET_NmiCounterValueSet Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1693 Example //Call system service to unlock the system PLIB_RESET_NmiCounterValueSet( RESET_ID_0, 0x54); //Call system service to lock the system Parameters Parameters Description index Identifier for the device instance to be configured nmi_count NMI counter value Function void PLIB_RESET_NmiCounterValueSet ( RESET_MODULE_ID index, RESET_NMI_COUNT_TYPE nmi_count ) PLIB_RESET_NmiEventClear Function Clears the NMI event File plib_reset.h C void PLIB_RESET_NmiEventClear(RESET_MODULE_ID index, RESET_NMI_REASON nmi_reason); Returns None Description This function clears the NMI event. If a WDTO or DMTO NMI event is cleared before the NMI counter reaches zero, no device Reset is asserted. Remarks This function implements an operation of the NmiControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiControl function in your application to determine whether this feature is available. Preconditions The system unlock sequence must be performed before calling PLIB_RESET_NmiEventTrigger. Example //Call system service to unlock the system PLIB_RESET_NmiEventClear( RESET_ID_0, SOFTWARE_NMI ); //Call system service to lock the system Parameters Parameters Description index Identifier for the device instance to be configured nmi_reason Sets of reasons that can cause a NMI Function void PLIB_RESET_NmiEventClear ( RESET_MODULE_ID index, RESET_NMI_REASON nmi_reason ) PLIB_RESET_NmiEventTrigger Function Triggers the NMI event. File plib_reset.h C void PLIB_RESET_NmiEventTrigger(RESET_MODULE_ID index, RESET_NMI_REASON nmi_reason); Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1694 Returns None Description This function triggers the NMI. In case of a Deadman Timer (DMT) or Watchdog Timer (WDT) NMI event, it will also trigger the NMI counter to start the countdown. Remarks This function implements an operation of the NmiControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiControl function in your application to determine whether this feature is available. Preconditions The system unlock sequence must be performed before calling PLIB_RESET_NmiEventTrigger. Example //Call system service to unlock the system PLIB_RESET_NmiEventTrigger( RESET_ID_0, SOFTWARE_NMI ); //Call system service to lock the system Parameters Parameters Description index Identifier for the device instance to be configured nmi_reason Sets of reasons which can cause NMI Function void PLIB_RESET_NmiEventTrigger ( RESET_MODULE_ID index, RESET_NMI_REASON nmi_reason ) PLIB_RESET_NmiReasonGet Function Returns the reason for the Non-Maskable Interrupt (NMI). File plib_reset.h C RESET_NMI_REASON PLIB_RESET_NmiReasonGet(RESET_MODULE_ID index); Returns RESET_NMI_REASON - Sets of reasons that can cause a NMI. Description This function returns the reason that caused the NMI. Remarks This function implements an operation of the NmiControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiControl function in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_RESET_NmiReasonGet( RESET_ID_0 )== WDTO_NMI ) { //Do Something } Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1695 Function RESET_NMI_REASON PLIB_RESET_NmiReasonGet ( RESET_MODULE_ID index ) d) Feature Existence Functions PLIB_RESET_ExistsResetReasonStatus Function Identifies whether the ResetReasonStatus feature exists on the Reset module. File plib_reset.h C bool PLIB_RESET_ExistsResetReasonStatus(RESET_MODULE_ID index); Returns • true - The ResetReasonStatus feature is supported on the device • false - The ResetReasonStatus feature is not supported on the device Description This function identifies whether the ResetReasonStatus feature is available on the Reset module. When this function returns true, these functions are supported on the device: • PLIB_RESET_ReasonGet • PLIB_RESET_ReasonClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RESET_ExistsResetReasonStatus( RESET_MODULE_ID index ) PLIB_RESET_ExistsSoftwareResetTrigger Function Identifies whether the SoftwareResetTrigger feature exists on the Reset module. File plib_reset.h C bool PLIB_RESET_ExistsSoftwareResetTrigger(RESET_MODULE_ID index); Returns • true - The SoftwareResetTrigger feature is supported on the device • false - The SoftwareResetTrigger feature is not supported on the device Description This function identifies whether the SoftwareResetTrigger feature is available on the Reset module. When this function returns true, this function is supported on the device: • PLIB_RESET_SoftwareResetEnable Remarks None. Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1696 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RESET_ExistsSoftwareResetTrigger( RESET_MODULE_ID index ) PLIB_RESET_ExistsConfigRegReadError Function Identifies whether the ConfigRegReadError feature exists on the Reset module. File plib_reset.h C bool PLIB_RESET_ExistsConfigRegReadError(RESET_MODULE_ID index); Returns • true - The ConfigRegReadError feature is supported on the device • false - The ConfigRegReadError feature is not supported on the device Description This function identifies whether the ConfigRegReadError feature is available on the Reset module. When this function returns true, this function is supported on the device: • PLIB_RESET_ConfigRegReadErrorGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RESET_ExistsConfigRegReadError( RESET_MODULE_ID index ) PLIB_RESET_ExistsNmiControl Function Identifies whether the NmiControl feature exists on the Reset module. File plib_reset.h C bool PLIB_RESET_ExistsNmiControl(RESET_MODULE_ID index); Returns • true - The NmiControl feature is supported on the device • false - The NmiControl feature is not supported on the device Description This function identifies whether the NmiControl feature is available on the Reset module. When this function returns true, these functions are supported on the device: • PLIB_RESET_NmiReasonGet Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1697 • PLIB_RESET_NmiEventTrigger • PLIB_RESET_NmiEventClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RESET_ExistsNmiControl( RESET_MODULE_ID index ) PLIB_RESET_ExistsNmiCounter Function Identifies whether the NmiCounter feature exists on the Reset module. File plib_reset.h C bool PLIB_RESET_ExistsNmiCounter(RESET_MODULE_ID index); Returns • true - The NmiCounter feature is supported on the device • false - The NmiCounter feature is not supported on the device Description This function identifies whether the NmiCounter feature is available on the Reset module. When this function returns true, these functions are supported on the device: • PLIB_RESET_NmiCounterValueSet • PLIB_RESET_NmiCounterValueGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RESET_ExistsNmiCounter( RESET_MODULE_ID index ) PLIB_RESET_ExistsWdtoInSleep Function Identifies whether the WdtoInSleep feature exists on the Reset module. File plib_reset.h C bool PLIB_RESET_ExistsWdtoInSleep(RESET_MODULE_ID index); Returns • true - The WdtoInSleep feature is supported on the device Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1698 • false - The WdtoInSleep feature is not supported on the device Description This function identifies whether the WdtoInSleep feature is available on the Reset module. When this function returns true, this function is supported on the device: • PLIB_RESET_WdtTimeOutHasOccurredInSleep Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RESET_ExistsWdtoInSleep( RESET_MODULE_ID index ) e) Data Types and Constants RESET_MODULE_ID Enumeration Identifies the supported Reset modules. File help_plib_reset.h C typedef enum { RESET_ID_0 } RESET_MODULE_ID; Members Members Description RESET_ID_0 RESET Module ID 0 Description Reset Module ID This enumeration identifies the Reset modules that are available on the microcontroller. This is the superset of all the possible instances that might be available on a Microchip microcontroller. Remarks Caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules are available on all devices. Refer to the "Resets" chapter in the specific device data sheet to determine which modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. RESET_REASON Enumeration Lists the reset sources. File help_plib_reset.h C typedef enum { RESET_REASON_NONE = 0x00000000, RESET_REASON_POWERON = 0x00000003, RESET_REASON_BROWNOUT = 0x00000002, RESET_REASON_WDT_TIMEOUT = 0x00000010, Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1699 RESET_REASON_SOFTWARE = 0x00000040, RESET_REASON_MCLR = 0x00000080, RESET_REASON_CONFIG_MISMATCH = 0x00000200, RESET_REASON_VBAT = 0x00010000, RESET_REASON_VBPOR = 0x00020000, RESET_REASON_HIGH_VOLTAGE_DETECT = 0x20000000, RESET_REASON_DMT_TIMEOUT = 0x00000020, RESET_REASON_ALL = 0x200002D3 } RESET_REASON; Members Members Description RESET_REASON_NONE = 0x00000000 The last reset was of unknown type RESET_REASON_POWERON = 0x00000003 The last reset was a power on reset RESET_REASON_BROWNOUT = 0x00000002 The last reset was a brown out reset RESET_REASON_WDT_TIMEOUT = 0x00000010 The last reset was a watch dog timer time-out reset RESET_REASON_SOFTWARE = 0x00000040 The last reset was a software reset RESET_REASON_MCLR = 0x00000080 The last reset was a master clear(MCLR) reset RESET_REASON_CONFIG_MISMATCH = 0x00000200 The last reset was a configuration mismatch reset RESET_REASON_VBAT = 0x00010000 The last reset was a VBAT reset RESET_REASON_VBPOR = 0x00020000 The last reset was a VBPOR reset, because of no supply or Brown-out on VBAT pin RESET_REASON_HIGH_VOLTAGE_DETECT = 0x20000000 The last reset was high voltage detect reset RESET_REASON_DMT_TIMEOUT = 0x00000020 The last reset was a Deadman Timer time-out reset RESET_REASON_ALL = 0x200002D3 All reset flags are high Description RESET source select enumeration This enumeration lists the possible reset sources. Remarks Not all reset sources exist on all devices. Please refer to the specific device data sheet for availability. RESET_CONFIG_REG_READ_ERROR Enumeration Lists the Configuration register read errors. File help_plib_reset.h C typedef enum { PRIMARY_CONFIG_REG_READ_ERROR, PRIMARY_AND_ALTERNATIVE_CONFIG_REG_READ_ERROR, NO_CONFIG_REG_READ_ERROR } RESET_CONFIG_REG_READ_ERROR; Members Members Description PRIMARY_CONFIG_REG_READ_ERROR An error occurred during the read of primary configuration registers PRIMARY_AND_ALTERNATIVE_CONFIG_REG_READ_ERROR An error occurred during the read of primary and alternate configuration register NO_CONFIG_REG_READ_ERROR No error occurred during the read of configuration registers Description RESET Config Register Read Error Enumeration This enumeration lists the possible errors while reading Configuration registers. Remarks Not all errors exist on all devices. Please refer to the specific device data sheet for availability. Peripheral Libraries Help Reset Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1700 RESET_NMI_COUNT_TYPE Type Defines NMI counter data type File plib_reset.h C typedef unsigned int RESET_NMI_COUNT_TYPE; Description RESET_NMI_COUNT_TYPE data type NMI counter data type definition. RESET_NMI_REASON Enumeration Lists the NMI reasons. File help_plib_reset.h C typedef enum { WDTO_NMI, DMTO_NMI, SOFTWARE_NMI, GLOBAL_NMI, LVD_NMI, CF_NMI, WDTS_NMI } RESET_NMI_REASON; Members Members Description WDTO_NMI Watch Dog Timer time-out has caused NMI DMTO_NMI Deadman Timer time-out has caused NMI SOFTWARE_NMI Software triggered NMI will be generated GLOBAL_NMI General NMI or user-initiated NMI has occurred LVD_NMI Low Voltage Detection Condition has caused NMI CF_NMI Clock Failure has caused NMI WDTS_NMI Watch Dog Timer in Sleep has caused NMI Description NMI Reason enumeration This enumeration lists the possible NMI sources. Remarks Not all NMI sources exist on all devices. Please refer to the specific device data sheet for availability. Files Files Name Description plib_reset.h Defines the Reset Peripheral Library interface. help_plib_reset.h This is file help_plib_reset.h. Description This section lists the source and header files used by the library. Peripheral Libraries Help Reset Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1701 plib_reset.h Defines the Reset Peripheral Library interface. Functions Name Description PLIB_RESET_ConfigRegReadErrorGet Gets the Configuration register read error. PLIB_RESET_ExistsConfigRegReadError Identifies whether the ConfigRegReadError feature exists on the Reset module. PLIB_RESET_ExistsNmiControl Identifies whether the NmiControl feature exists on the Reset module. PLIB_RESET_ExistsNmiCounter Identifies whether the NmiCounter feature exists on the Reset module. PLIB_RESET_ExistsResetReasonStatus Identifies whether the ResetReasonStatus feature exists on the Reset module. PLIB_RESET_ExistsSoftwareResetTrigger Identifies whether the SoftwareResetTrigger feature exists on the Reset module. PLIB_RESET_ExistsWdtoInSleep Identifies whether the WdtoInSleep feature exists on the Reset module. PLIB_RESET_NmiCounterValueGet Gets the NMI counter value. PLIB_RESET_NmiCounterValueSet Sets the NMI counter. PLIB_RESET_NmiEventClear Clears the NMI event PLIB_RESET_NmiEventTrigger Triggers the NMI event. PLIB_RESET_NmiReasonGet Returns the reason for the Non-Maskable Interrupt (NMI). PLIB_RESET_ReasonClear Clears the RCON register. PLIB_RESET_ReasonGet Returns the reason for a reset. PLIB_RESET_SoftwareResetEnable Enables the software reset. PLIB_RESET_WdtTimeOutHasOccurredInSleep Returns the state of the device when WDT time-out occurred Types Name Description RESET_NMI_COUNT_TYPE Defines NMI counter data type Description Reset Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Reset Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Reset Controller module. File Name plib_reset.h Company Microchip Technology Inc. help_plib_reset.h Enumerations Name Description RESET_CONFIG_REG_READ_ERROR Lists the Configuration register read errors. RESET_MODULE_ID Identifies the supported Reset modules. RESET_NMI_REASON Lists the NMI reasons. RESET_REASON Lists the reset sources. Description This is file help_plib_reset.h. Peripheral Libraries Help Reset Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1702 RTCC Peripheral Library This section describes the Real-Time Clock and Calendar (RTCC) Peripheral Library. Introduction This module provides real-time clock and calendar functions. The RTCC is intended for applications where accurate time must be maintained for extended periods with minimum to no intervention from the CPU. The module is optimized for low-power usage to provide extended battery life while keeping track of time. Description The RTCC module is a 100-year clock and calendar with automatic leap year detection. The range of the clock is from 00:00:00 (midnight) on January 1, 2000 to 23:59:59 on December 31, 2099. The hours are available in 24-hour (military time) format. The clock provides a granularity of one second with half-second visibility to the user. RTCC Block Diagram Operating Modes Note: Please refer to the "RTCC" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine which features are supported by your device. RTCC Mode The RTCC module is intended to be clocked by an external real-time clock crystal oscillating at 32.768 kHz. The prescaler divides the crystal oscillator frequency to produce a 1 Hz frequency for the clock and calendar. The current Date and Time are stored in a BCD counter. Alarm Mode The RTCC module provides an alarm function that is configurable from a half-second to one year. After the alarm is enabled, the RTCC module can be configured to repeat the alarm at preconfigured intervals. The indefinite repetition of the alarm is provided through the Chime feature. Using the Library This topic describes the basic architecture of the RTCC Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_rtcc.h The interface to the RTCC Peripheral Library is defined in the plib_rtcc.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the RTCC Peripheral Library should include peripheral.h. Library File: The RTCC Peripheral Library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for information on how the peripheral interacts with the framework. Peripheral Libraries Help RTCC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1703 Hardware Abstraction Model This library provides a low-level abstraction of the RTCC module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The RTCC peripheral library provides interface routines to interact with the blocks shown in the following diagram. Hardware Abstraction Model The RTCC Control Logic provides the capability to operate the RTCC module in the RTCC and Alarm modes. The control logic also handles the comparison and the counter increments, which in turn control the alarm generation. This module is also responsible for the generation of a square wave at the RTCC output pin. In addition, the RTCC module provides the RTCC drift calibration. The RTCC Interrupt Logic is primarily used in alarm generation. The various configurations of the alarm and their repetition period may be defined. The RTCC Registers store the actual date and time. Separate registers are present for RTCC and alarm functionality. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the RTCC module. Library Interface Section Description General Functions Provides the setup and configuration of general functionalities in the RTCC module. This section also covers the drift calibration. RTCC Mode Functions Provides configuration of the RTCC-related registers. Updating the Date and Time registers along with reading them accurately is performed. Alarm Mode Functions Provides configuration of the Alarm-related registers. Updating the Date and Time registers along with reading them accurately is performed. In addition, the rate at which an alarm occurs and the frequency is also configured in this mode. Other Functions Provides additional RTCC functions. Feature Existence Functions Provides functions that determine whether certain features exist on a device. How the Library Works Provides information on how the library works. Description The usage model for this library is explained in the following sections. The following diagram describes the major components of the usage model. Peripheral Libraries Help RTCC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1704 Usage Model State Machine This RTCC state machine is provided to give a general idea of the usage model of the peripheral library. Refer to the usage model for more detailed steps for the scenario that is being used. Description The following state machine diagram is for RTCC mode and Alarm Mode during normal operation. RTCC State Machine State Associated Function Setup and Initialization Refer to mode of RTCC for detailed instructions of setup. Peripheral Libraries Help RTCC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1705 Enable Write via Key Sequence For RTCC to perform any function, the module has to be enabled via a series of commands in a special sequence. This is abstracted and is achieved using PLIB_RTCC_WriteEnable. Enable Access of RTC These include the functions needed to set up the RTCC/Alarm, which will be explained in detail in the following sections. Wait for Safe Sync Window To update the RTCC on-the-fly, a safe window period is available, corresponding to 32 clock cycles called RTSYNC. Further sections will explain the functionality in greater detail. Write/Read Date and Time The application may read or write the date and time using PLIB_RTCC_RTCDateGet and PLIB_RTCC_RTCTimeGet or PLIB_RTCC_RTCDateSet and PLIB_RTCC_RTCTimeSet, among others. These functions are device-specific and may not be available for all devices. RTCC Mode Operations This section describes the RTCC mode of operation of the RTCC module. Note: Please refer to the "RTCC" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine which features are supported by your device. Description Enabling the RTCC Module for Write Operations To perform a write to any of the RTCC timer registers the RTCWREN bit must be set. It is recommended that this bit be reset unless a write operation is specifically required. A sequence of commands, each varying across processor families must be executed to set the RTCWREN. Example: Enabling a Write // Assume Interrupts are disabled. // Assume the DMA controller is suspended PLIB_RTCC_WriteEnable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. // This API performs the writing of the sequence // 0xaa996655 and 0x556699aa to the SYSKET in MCU32 // and 0x55 and 0xaa in case of MCU 16 and MCU 8 // This API then sets the RTCWREN. Updating RTCC Time and Date 1. Turn off the RTCC using the API PLIB_RTCC_Disable. 2. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_RTCSyncStatusGet (this operation may not be required on all devices). 3. Update the Date and Time registers using PLIB_RTCC_RTCDateSet and PLIB_RTCC_RTCTimeSet. 4. Turn on the RTCC module using PLIB_RTCC_Enable. Example: Updating RTCC Time and Date // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsigned long date = 0x06102705; // Set date to Friday 27 Oct 2006 PLIB_RTCC_Disable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. while(PLIB_RTCC_RTCSyncStatusGet(MY_RTCC_INSTANCE)); // Wait for clock to turn off PLIB_RTCC_RTCTimeSet(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_RTCDateSet(MY_RTCC_INSTANCE, date); // Update the Date PLIB_RTCC_Enable(MY_RTCC_INSTANCE); Updating RTCC Time and Date using RTSYNC Window 1. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_RTCSyncStatusGet. 2. Update the RTC Date and Time registers using PLIB_RTCC_RTCDateSet and PLIB_RTCC_RTCTimeSet. Peripheral Libraries Help RTCC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1706 Example: Updating RTCC Time and Date Using RTSYNC Window // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsigned long date = 0x06102705; // Set date to Friday 27 Oct 2006 // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. //Disable Critical Interrupts here .... while(PLIB_RTCC_RTCSyncStatusGet(MY_RTCC_INSTANCE)); // Wait for clock to turn off PLIB_RTCC_RTCTimeSet(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_RTCDateSet(MY_RTCC_INSTANCE, date); // Update the Date //Enable Critical Interrupts here .... Updating RTCC Time and Date Using Register Pointers 1. Turn off the RTCC using PLIB_RTCC_Disable. 2. Identify whether the RTCTimeValue and RTCDateValue features exist on the RTCC module using PLIB_RTCC_ExistsRTCTime and PLIB_RTCC_ExistsRTCDate. 3. Update the RTC Date and Time registers using PLIB_RTCC_RTCDateSet 4. and PLIB_RTCC_RTCtimeSet. 5. Turn on the RTCC module using PLIB_RTCC_Enable. Example: Updating RTCC Time and Date Using Register Pointers // Assume Write Enable has been performed correctly PLIB_RTCC_Disable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. PLIB_RTCC_RTCYearSet(MY_RTCC_INSTANCE, 0x0007); // Update the Year PLIB_RTCC_RTCMonthSet(MY_RTCC_INSTANCE,0x10); // Set Month to October PLIB_RTCC_RTCDaySet(MY_RTCC_INSTANCE,0x28); // Set Day to the 27th PLIB_RTCC_RTCWeekDaySet(MY_RTCC_INSTANCE,0x01); // Set the Day of the Week to Sunday PLIB_RTCC_RTCHourSet(MY_RTCC_INSTANCE,0x10); // Set the Hour value to 10 PLIB_RTCC_RTCMinuteSet(MY_RTCC_INSTANCE,0x00); // Set Minute value to 0 PLIB_RTCC_RTCSecondSet(MY_RTCC_INSTANCE,0x00); // Set Seconds value to 0 PLIB_RTCC_Enable(MY_RTCC_INSTANCE); Alarm Mode Operations This section describes the Alarm mode of operation of the RTCC module. Note: Please refer to the "RTCC" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine which features are supported by your device. Description Configuring the One-Time-Per-Day Alarm 1. Turn off the Alarm and also the chime, alarm repeats, and masks using PLIB_RTCC_AlarmDisable. 2. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_AlarmSyncStatusGet (This operation may not be required on all devices). 3. Update the Alarm Date and Time registers using PLIB_RTCC_AlarmTimeSet and PLIB_RTCC_AlarmDateSet. 4. Set the alarm mask to every half-second and the repeat counter to zero using PLIB_RTCC_AlarmMaskModeSelect and PLIB_RTCC_AlarmRepeatCountSet, respectively. 5. Turn on the RTCC Alarm module using PLIB_RTCC_AlarmEnable. Example: Configuring the One-Time-Per-Day Alarm Peripheral Libraries Help RTCC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1707 // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsigned long date = 0x06102705; // Set date to Friday 27 Oct 2006 PLIB_RTCC_AlarmDisable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. while(PLIB_RTCC_AlarmSyncStatusGet(MY_RTCC_INSTANCE)); // Wait for clock to turn off PLIB_RTCC_AlarmTimeSet(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_AlarmDateSet(MY_RTCC_INSTANCE, date); // Update the Date PLIB_RTCC_AlarmMaskModeSelect(MY_RTCC_INSTANCE, RTCC_ALARM_EVERY_HALF_SECOND); PLIB_RTCC_AlarmRepeatCountSet(MY_RTCC_INSTANCE, 0 /*Number of repetitions*/ ); PLIB_RTCC_AlarmEnable(MY_RTCC_INSTANCE); Configuring the Repeat Alarm 1. Turn off the Alarm and also the Chime, alarm repeats, and masks using PLIB_RTCC_AlarmDisable. 2. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_AlarmSyncStatusGet (this operation may not be required on all devices). 3. Update the Alarm Date and Time registers using PLIB_RTCC_AlarmTimeSet and PLIB_RTCC_AlarmDateSet. 4. Set the alarm mask to every half-second and the repeat counter to 10 using PLIB_RTCC_AlarmMaskModeSelect and PLIB_RTCC_AlarmRepeatCountSet, respectively. 5. Turn on the RTCC Alarm module using PLIB_RTCC_AlarmEnable. Example: Configuring the Repeat Alarm // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsigned long date = 0x06102705; // Set date to Friday 27 Oct 2006 PLIB_RTCC_AlarmDisable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. while(PLIB_RTCC_AlarmSyncStatusGet(MY_RTCC_INSTANCE)); // Wait for clock to turn off PLIB_RTCC_AlarmTimeSet(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_AlarmDateSet(MY_RTCC_INSTANCE, date); // Update the Date PLIB_RTCC_AlarmMaskModeSelect(MY_RTCC_INSTANCE, RTCC_ALARM_EVERY_HALF_SECOND); PLIB_RTCC_AlarmRepeatCountSet(MY_RTCC_INSTANCE, 10 /*No of repetitions*/ ); PLIB_RTCC_AlarmEnable(MY_RTCC_INSTANCE); Configuring the Indefinite One-Per-Day Alarm 1. Turn off the Alarm and also the Chime, alarm repeats and masks using PLIB_RTCC_AlarmDisable. 2. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_AlarmSyncStatusGet (This operation may not be required on all devices). 3. Update the Alarm Date and Time registers using PLIB_RTCC_AlarmTimeSet and PLIB_RTCC_AlarmDateSet. 4. Set the alarm mask to every half-second and the repeat counter to '0' using PLIB_RTCC_AlarmMaskModeSelect and PLIB_RTCC_AlarmRepeatCountSet, respectively. 5. Turn on the RTCC Alarm module using PLIB_RTCC_AlarmEnable and enable chime using PLIB_RTCC_AlarmChimeEnable. Example: Configuring the Indefinite One-Per-Day Alarm // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsigned long date = 0x06102705; // Set date to Friday 27 Oct 2006 PLIB_RTCC_AlarmDisable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. while(PLIB_RTCC_AlarmSyncStatusGet(MY_RTCC_INSTANCE)); // Wait for clock to turn off Peripheral Libraries Help RTCC Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1708 PLIB_RTCC_AlarmTimeSet(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_AlarmDateSet(MY_RTCC_INSTANCE, date); // Update the Date PLIB_RTCC_AlarmMaskModeSelect(MY_RTCC_INSTANCE, RTCC_ALARM_EVERY_HALF_SECOND); PLIB_RTCC_AlarmRepeatCountSet(MY_RTCC_INSTANCE, 0 /*No of repetitions*/ ); PLIB_RTCC_AlarmEnable(MY_RTCC_INSTANCE); PLIB_RTCC_AlarmChimeEnable(MY_RTCC_INSTANCE); Other Functionality This section describes the Drift Calibration mode of operation of the RTCC module. Note: Please refer to the "RTCC" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine which features are supported by your device. Description The real-time crystal input can be calibrated using the periodic auto-adjust feature. When properly calibrated, the RTCC module can provide an error of less than 0.66 seconds per month. Calibration has the ability to eliminate an error of up to 260 ppm. The calibration is accomplished by finding the number of error clock pulses and writing this value into the calibration bit fields using PLIB_RTCC_DriftCalibrateSet. Drift Calibration 1. Using another timer resource, the user must find the error of the 32.768 kHz crystal. 2. Once the error is known, it must be converted to the number of error clock pulses per minute, as shown by (Ideal Frequency(32,758) - Measured Frequency) * 60 = Error Clocks Per Minute. 3. If the error is negative, the input to PLIB_RTCC_DriftCalibrateSet is negative. Likewise, if the error is positive, the input is positive. The negative and positive values are the actual number of clock pulses to be added or subtracted from the timer counter per minute. Example: Configuring the One-Time-Per-Day Alarm // Assume Write Enable has been performed correctly // Assume steps 1 and 2 are performed and the error is determined. int driftValue = 0x3FD // 10 bits Adjustment, -3 in value int T0,T1; do { T0 = PLIB_RTCC_RTCTimeGet(MY_RTCC_INSTANCE); T1 = PLIB_RTCC_RTCTimeGet(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE is a specific instance of the hardware peripheral }while(T0!=T1) // Read Valid Time Value if((T0 & 0XFF) == 0) // we are at seconds exactly 00, wait for auto adjust { while PLIB_RTCC_HalfSecondStatusGet(MY_RTCC_INSTANCE); // Wait for the second Half } PLIB_RTCC_DriftCalibrateSet(MY_RTCC_INSTANCE, 0x00); //Clear the calibration PLIB_RTCC_DriftCalibrateSet(MY_RTCC_INSTANCE, 0xdriftValue); Configuring the Library The library is configured for the supported RTCC modules when the processor is chosen in the MPLAB X IDE. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1709 Library Interface a) General Functions Name Description PLIB_RTCC_ClockOutputDisable Disables the specific RTCC module's output pin. PLIB_RTCC_ClockOutputEnable Enables the specific RTCC module's output pin. PLIB_RTCC_ClockRunningStatus Provides the status of the RTCC clock. b) RTCC Mode Functions Name Description PLIB_RTCC_Disable Disables the specific RTCC module on the device. PLIB_RTCC_Enable Enables the specific RTCC module on the device. PLIB_RTCC_WriteDisable Disables writing to the specific RTCC module's value registers. PLIB_RTCC_WriteEnable Enables writing to the specific RTCC module's value registers. PLIB_RTCC_RTCDateGet Returns the contents of the specific RTCC module's Date register. PLIB_RTCC_RTCDateSet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCDayGet Returns the contents of the Days bits in the specific RTCC module's Date register. PLIB_RTCC_RTCDaySet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCHourGet Returns the contents of the Hours bits in the specific RTCC module's Time register. PLIB_RTCC_RTCHourSet Writes the contents of the Hours bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMinuteGet Returns the contents of the Minutes bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMinuteSet Writes the contents of Minutes bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMonthGet Returns the contents of the Months bits in the specific RTCC module's Date register. PLIB_RTCC_RTCMonthSet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCSecondGet The function returns the contents of the Seconds bits in the specific RTCC device's Time register. PLIB_RTCC_RTCSecondSet Writes the contents of Seconds bits in the specific RTCC module's Time register. PLIB_RTCC_RTCTimeGet Returns the contents of the specific RTCC module's Time register. PLIB_RTCC_RTCTimeSet Writes to the specific RTCC module's Time register. PLIB_RTCC_RTCWeekDayGet Returns the contents of the WeekDay bits in the specific RTCC module's Date register. PLIB_RTCC_RTCWeekDaySet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCYearGet Returns the contents of the Year bits in the specific RTCC module's Date register. PLIB_RTCC_RTCYearSet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCSyncStatusGet The function returns the synchronization status bit. c) Alarm Mode Functions Name Description PLIB_RTCC_AlarmChimeDisable Disables the specific RTCC module's chime. PLIB_RTCC_AlarmChimeEnable Enables the specific RTCC module's chime. PLIB_RTCC_AlarmDateGet Returns the contents of the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDateSet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDayGet Returns the contents of the Day bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDaySet Writes to the specific RTCC module's Alarm Date value register. PLIB_RTCC_AlarmDisable Disables the specific RTCC module's alarm. PLIB_RTCC_AlarmEnable Enables the specific RTCC module's alarm. PLIB_RTCC_AlarmHourGet Returns the contents of Hours bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmHourSet The function returns the contents of Hours bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMaskModeSelect Sets the specific RTCC module's alarm mask Configuration bits. PLIB_RTCC_AlarmMinuteGet Returns the contents of Minutes bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMinuteSet Returns the contents of the Minutes bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMonthGet Returns the contents of the Month bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmMonthSet Writes to the specific RTCC module's Alarm Date register. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1710 PLIB_RTCC_AlarmPulseInitialGet Returns the state of the initial alarm pulse. PLIB_RTCC_AlarmPulseInitialSet Enables the determination of the initial alarm pulse. PLIB_RTCC_AlarmRepeatCountGet Reads the specific RTCC module's alarm repeat counter. PLIB_RTCC_AlarmRepeatCountSet Sets the specific RTCC module's alarm repeat counter. PLIB_RTCC_AlarmSecondGet Returns the contents of the Seconds bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmSecondSet Returns the contents of Seconds bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmTimeGet Returns the contents of the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmTimeSet Writes to the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmValueRegisterPointer Sets the specific RTCC module's Alarm register pointer. PLIB_RTCC_AlarmWeekDayGet Returns the contents of the WeekDay bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmWeekDaySet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmSyncStatusGet The function returns the synchronization status bit. d) Other Functions Name Description PLIB_RTCC_ClockSourceSelect Selects the clock source for the RTCC module. PLIB_RTCC_DriftCalibrateGet Reads the specific RTCC module's drift calibration bits. PLIB_RTCC_DriftCalibrateSet Sets the specific RTCC module's drift calibration bits. PLIB_RTCC_HalfSecondStatusGet The function returns the half second status bit. PLIB_RTCC_OutputSelect Selects which signal will be presented on the RTCC pin PLIB_RTCC_StopInIdleDisable Continues normal RTCC operation when the device enters Idle mode. PLIB_RTCC_StopInIdleEnable Disables access to the RTCC module by the Peripheral Bus Clock (PBCLK) when the CPU enters Idle mode. e) Feature Existence Functions Name Description PLIB_RTCC_ExistsAlarmChimeControl Identifies whether the AlarmChimeControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmControl Identifies whether the AlarmControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmDate Identifies whether the AlarmDate feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmMaskControl Identifies whether the AlarmMaskControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmPulseInitial Identifies whether the AlarmPulseInitial feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmRepeatControl Identifies whether the AlarmRepeatControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmTime Identifies whether the AlarmTime feature exists on the RTCC module. PLIB_RTCC_ExistsCalibration Identifies whether the Calibration feature exists on the RTCC module. PLIB_RTCC_ExistsClockRunning Identifies whether the ClockRunning feature exists on the RTCC module. PLIB_RTCC_ExistsClockSelect Identifies whether the ClockSelect feature exists on the RTCC module. PLIB_RTCC_ExistsEnableControl Identifies whether the EnableControl feature exists on the RTCC module. PLIB_RTCC_ExistsHalfSecond Identifies whether the HalfSecond feature exists on the RTCC module. PLIB_RTCC_ExistsOutputControl Identifies whether the OutputControl feature exists on the RTCC module. PLIB_RTCC_ExistsOutputSelect Identifies whether the OutputSelect feature exists on the RTCC module. PLIB_RTCC_ExistsRTCDate Identifies whether the RTCDateValue feature exists on the RTCC module. PLIB_RTCC_ExistsRTCTime Identifies whether the RTCTimeValue feature exists on the RTCC module. PLIB_RTCC_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the RTCC module. PLIB_RTCC_ExistsSynchronization Identifies whether the Synchronization feature exists on the RTCC module. PLIB_RTCC_ExistsWriteEnable Identifies whether the WriteEnable feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmSynchronization Identifies whether the AlarmSynchronization feature exists on the RTCC module. f) Data Types and Constants Name Description RTCC_ALARM_MASK_CONFIGURATION Data type defining the different configurations for the alarm mask bits. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1711 RTCC_MODULE_ID Enumeration: RTCC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the superset of all of the possible instances that may be available on the Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. RTCC_VALUE_REGISTER_POINTER Data type defining the different configurations by which the RTCC Date and Time Registers can be accessed. Description This section describes the Application Programming Interface (API) functions of the RTCC Peripheral Library. Refer to each section for a detailed description. a) General Functions PLIB_RTCC_ClockOutputDisable Function Disables the specific RTCC module's output pin. File plib_rtcc.h C void PLIB_RTCC_ClockOutputDisable(RTCC_MODULE_ID index); Returns None. Description This function disables the specific RTCC module's output pin. Remarks This function implements an operation of the OutputControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsOutputControl in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_RTCC_ClockOutputDisable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_ClockOutputDisable ( RTCC_MODULE_ID index ) PLIB_RTCC_ClockOutputEnable Function Enables the specific RTCC module's output pin. File plib_rtcc.h C void PLIB_RTCC_ClockOutputEnable(RTCC_MODULE_ID index); Returns None. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1712 Description This function enables the specific RTCC module's output and generates a square wave using either the alarm or the 1 Hz clock output on the RTCC pin. Remarks This function implements an operation of the OutputControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsOutputControl in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_RTCC_ClockOutputEnable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_ClockOutputEnable ( RTCC_MODULE_ID index ) PLIB_RTCC_ClockRunningStatus Function Provides the status of the RTCC clock. File plib_rtcc.h C bool PLIB_RTCC_ClockRunningStatus(RTCC_MODULE_ID index); Returns The status of the RTCC clock. Description This function provides the status of the RTCC clock. Remarks This function implements an operation of the ClockRunning feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsClockRunning in your application to automatically determine whether this feature is available. Preconditions None. Example bool status; status = PLIB_RTCC_ClockRunningStatus(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_RTCC_ClockRunningStatus ( RTCC_MODULE_ID index ) b) RTCC Mode Functions Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1713 PLIB_RTCC_Disable Function Disables the specific RTCC module on the device. File plib_rtcc.h C void PLIB_RTCC_Disable(RTCC_MODULE_ID index); Returns None. Description This function disables the specific RTCC module on the device. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsEnableControl in your application to automatically determine whether this feature is available. Preconditions The RTCC module should be unlocked for writing using the function PLIB_RTCC_WriteEnable before this function is called. Example PLIB_RTCC_Disable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_Disable ( RTCC_MODULE_ID index ) PLIB_RTCC_Enable Function Enables the specific RTCC module on the device. File plib_rtcc.h C void PLIB_RTCC_Enable(RTCC_MODULE_ID index); Returns None. Description This function enables the specific RTCC module on the device. Remarks By calling this function, the RTCC pins are controlled by the RTCC module. The RTCC module will continue to function when the device is held in reset. This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsEnableControl in your application to automatically determine whether this feature is available. Preconditions The RTCC module should be unlocked for writing using the function PLIB_RTCC_WriteEnable before this function is called. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1714 Example PLIB_RTCC_Enable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_Enable ( RTCC_MODULE_ID index ) PLIB_RTCC_WriteDisable Function Disables writing to the specific RTCC module's value registers. File plib_rtcc.h C void PLIB_RTCC_WriteDisable(RTCC_MODULE_ID index); Returns None. Description This function disables writing to the specific RTCC module's value registers. Remarks This function implements an operation of the WriteEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsWriteEnable in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_RTCC_WriteDisable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_WriteDisable ( RTCC_MODULE_ID index ) PLIB_RTCC_WriteEnable Function Enables writing to the specific RTCC module's value registers. File plib_rtcc.h C void PLIB_RTCC_WriteEnable(RTCC_MODULE_ID index); Returns None. Description This function enables writing to the specific RTCC module's value registers. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1715 Remarks This function implements an operation of the WriteEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsWriteEnable in your application to automatically determine whether this feature is available. Preconditions The SYSLOCK unlock sequence must be executed prior to calling this function by calling the PLIB_CORE_SysUnlock function. Example PLIB_RTCC_WriteEnable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_WriteEnable ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCDateGet Function Returns the contents of the specific RTCC module's Date register. File plib_rtcc.h C uint32_t PLIB_RTCC_RTCDateGet(RTCC_MODULE_ID index); Returns Date register contents. Description The function returns the contents of the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Date; Date = PLIB_RTCC_RTCDateGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_RTCDateGet ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCDateSet Function Writes to the specific RTCC module's Date register. File plib_rtcc.h Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1716 C void PLIB_RTCC_RTCDateSet(RTCC_MODULE_ID index, uint32_t data); Returns None. Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Example uint32_t data = 0x06102705; //Date = 27 Oct 2006 Friday PLIB_RTCC_RTCDateSet(RTCC_ID_0, data); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_RTCDateSet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_RTCDayGet Function Returns the contents of the Days bits in the specific RTCC module's Date register. File plib_rtcc.h C uint32_t PLIB_RTCC_RTCDayGet(RTCC_MODULE_ID index); Returns Days bits in the Date register. Description The function returns the contents of the Days bits in the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Day; Day = PLIB_RTCC_RTCDayGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1717 Function uint32_t PLIB_RTCC_RTCDayGet ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCDaySet Function Writes to the specific RTCC module's Date register. File plib_rtcc.h C void PLIB_RTCC_RTCDaySet(RTCC_MODULE_ID index, uint32_t day); Returns None. Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Example uint32_t Day = 0x27; //Day = 27th of the month PLIB_RTCC_RTCDaySet(RTCC_ID_0, Day); Parameters Parameters Description index Identifier for the device instance to be configured day The BCD value of the day to set in the Date register Function void PLIB_RTCC_RTCDaySet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_RTCHourGet Function Returns the contents of the Hours bits in the specific RTCC module's Time register. File plib_rtcc.h C uint32_t PLIB_RTCC_RTCHourGet(RTCC_MODULE_ID index); Returns BCD value of the Hours bits in the Time register. Description The function returns the contents of the Hours bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1718 Example uint32_t Hour; Hour = PLIB_RTCC_RTCHourGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_RTCHourGet ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCHourSet Function Writes the contents of the Hours bits in the specific RTCC module's Time register. File plib_rtcc.h C void PLIB_RTCC_RTCHourSet(RTCC_MODULE_ID index, uint32_t hour); Returns None. Description The function writes the contents of the Hours bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Hour = 0x04; PLIB_RTCC_RTCHourSet(RTCC_ID_0, Hour); Parameters Parameters Description index Identifier for the device instance to be configured hour BCD value to be written to the Hours bits in the Time register Function uint32_t PLIB_RTCC_RTCHourSet ( RTCC_MODULE_ID index, uint32_t hour ) PLIB_RTCC_RTCMinuteGet Function Returns the contents of the Minutes bits in the specific RTCC module's Time register. File plib_rtcc.h C uint32_t PLIB_RTCC_RTCMinuteGet(RTCC_MODULE_ID index); Returns BCD value of the Minutes bits in the Time register. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1719 Description The function returns the contents of the Minutes bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Minute; Minute = PLIB_RTCC_RTCMinuteGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_RTCMinuteGet ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCMinuteSet Function Writes the contents of Minutes bits in the specific RTCC module's Time register. File plib_rtcc.h C void PLIB_RTCC_RTCMinuteSet(RTCC_MODULE_ID index, uint32_t minute); Returns None. Description The function writes the contents of these bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Minute = 0x15; PLIB_RTCC_RTCMinuteSet(RTCC_ID_0, Minute); Parameters Parameters Description index Identifier for the device instance to be configured minute BCD value to be written to the Minutes bits in the Time register Function uint32_t PLIB_RTCC_RTCMinuteSet ( RTCC_MODULE_ID index, uint32_t minute ) Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1720 PLIB_RTCC_RTCMonthGet Function Returns the contents of the Months bits in the specific RTCC module's Date register. File plib_rtcc.h C uint32_t PLIB_RTCC_RTCMonthGet(RTCC_MODULE_ID index); Returns Months bits in the Date register. Description The function returns the contents of the Months bits in the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Month; Month = PLIB_RTCC_RTCMonthGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_RTCMonthGet ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCMonthSet Function Writes to the specific RTCC module's Date register. File plib_rtcc.h C void PLIB_RTCC_RTCMonthSet(RTCC_MODULE_ID index, uint32_t month); Returns None. Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1721 Example uint32_t Month = 0x10; //Month = October PLIB_RTCC_RTCMonthSet(RTCC_ID_0, Month); Parameters Parameters Description index Identifier for the device instance to be configured month The BCD value of the month to set in the Date register Function void PLIB_RTCC_RTCMonthSet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_RTCSecondGet Function The function returns the contents of the Seconds bits in the specific RTCC device's Time register. File plib_rtcc.h C uint32_t PLIB_RTCC_RTCSecondGet(RTCC_MODULE_ID index); Returns BCD value of the Seconds bits in the Time register. Description The function returns the contents of the Seconds bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Second; Second = PLIB_RTCC_RTCSecondGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_RTCSecondGet ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCSecondSet Function Writes the contents of Seconds bits in the specific RTCC module's Time register. File plib_rtcc.h C void PLIB_RTCC_RTCSecondSet(RTCC_MODULE_ID index, uint32_t second); Returns None. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1722 Description The function writes the contents of the Seconds bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Second = 0x33; PLIB_RTCC_RTCSecondSet(RTCC_ID_0, Second); Parameters Parameters Description index Identifier for the device instance to be configured second BCD value to be written to the Seconds bits in the Time register Function uint32_t PLIB_RTCC_RTCSecondSet ( RTCC_MODULE_ID index, uint32_t second ) PLIB_RTCC_RTCTimeGet Function Returns the contents of the specific RTCC module's Time register. File plib_rtcc.h C uint32_t PLIB_RTCC_RTCTimeGet(RTCC_MODULE_ID index); Returns Time register contents. Description The function returns the contents of the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Example uint32_t time; time = PLIB_RTCC_RTCTimeGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_RTCTimeGet ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCTimeSet Function Writes to the specific RTCC module's Time register. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1723 File plib_rtcc.h C void PLIB_RTCC_RTCTimeSet(RTCC_MODULE_ID index, uint32_t data); Returns None. Description The function writes to the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Time register, an RTCC write must be enabled using the exact sequences required by the device. Example uint32_t data = 0x04153300; // Time = 4 hours, 15 minutes, and 33 seconds PLIB_RTCC_RTCTimeSet(RTCC_ID_0, data); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_RTCTimeSet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_RTCWeekDayGet Function Returns the contents of the WeekDay bits in the specific RTCC module's Date register. File plib_rtcc.h C uint32_t PLIB_RTCC_RTCWeekDayGet(RTCC_MODULE_ID index); Returns WeekDay field in the Date register. Description The function returns the contents of the WeekDay bits in the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t WeekDay; WeekDay = PLIB_RTCC_RTCWeekDayGet(RTCC_ID_0); Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1724 Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_RTCWeekDayGet ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCWeekDaySet Function Writes to the specific RTCC module's Date register. File plib_rtcc.h C void PLIB_RTCC_RTCWeekDaySet(RTCC_MODULE_ID index, uint32_t weekday); Returns None. Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Example uint32_t WeekDay = 0x05; //WeekDay = Friday PLIB_RTCC_RTCWeekDaySet(RTCC_ID_0, WeekDay); Parameters Parameters Description index Identifier for the device instance to be configured weekday The BCD value of the weekday to set in the Date register Function void PLIB_RTCC_RTCWeekDaySet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_RTCYearGet Function Returns the contents of the Year bits in the specific RTCC module's Date register. File plib_rtcc.h C uint32_t PLIB_RTCC_RTCYearGet(RTCC_MODULE_ID index); Returns Year bits in the Date register. Description The function returns the contents of the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1725 Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Year; Year = PLIB_RTCC_RTCYearGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_RTCYearGet ( RTCC_MODULE_ID index ) PLIB_RTCC_RTCYearSet Function Writes to the specific RTCC module's Date register. File plib_rtcc.h C void PLIB_RTCC_RTCYearSet(RTCC_MODULE_ID index, uint32_t year); Returns None. Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Example uint32_t Year = 0x06; //Year = 2006 PLIB_RTCC_RTCYearSet(RTCC_ID_0, Year); Parameters Parameters Description index Identifier for the device instance to be configured year The BCD value of the year to set in the Date register Function void PLIB_RTCC_RTCYearSet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_RTCSyncStatusGet Function The function returns the synchronization status bit. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1726 File plib_rtcc.h C bool PLIB_RTCC_RTCSyncStatusGet(RTCC_MODULE_ID index); Returns • true - Date and time will change within 32 RTCC clocks • false - Date and time are safe to read, and will not change soon Description The function returns the synchronization status bit, which is used to determine whether it is safe to read the date/time values, or if the values will change within 32 RTCC clocks. Remarks This bit is read-only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsSynchronization in your application to automatically determine whether this feature is available. Preconditions None. Example if (PLIB_RTCC_RTCSyncStatusGet(RTCC_ID_0)) { ... } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_RTCC_RTCSyncStatusGet ( RTCC_MODULE_ID index ) c) Alarm Mode Functions PLIB_RTCC_AlarmChimeDisable Function Disables the specific RTCC module's chime. File plib_rtcc.h C void PLIB_RTCC_AlarmChimeDisable(RTCC_MODULE_ID index); Returns None. Description This function disables the specific RTCC module's chime. The alarm repeat count value bits stop once they reach zero. Remarks This function implements an operation of the AlarmChimeControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmChimeControl in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1727 Example PLIB_RTCC_AlarmChimeDisable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_AlarmChimeDisable ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmChimeEnable Function Enables the specific RTCC module's chime. File plib_rtcc.h C void PLIB_RTCC_AlarmChimeEnable(RTCC_MODULE_ID index); Returns None. Description This function enables the specific RTCC module's chime. The alarm repeat count bits are allowed to rollover. Remarks This function implements an operation of the AlarmChimeControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmChimeControl in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_RTCC_AlarmChimeEnable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_AlarmChimeEnable ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmDateGet Function Returns the contents of the specific RTCC module's Alarm Date register. File plib_rtcc.h C uint32_t PLIB_RTCC_AlarmDateGet(RTCC_MODULE_ID index); Returns Value register. Description The function returns the contents of the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1728 Remarks This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Date; Date = PLIB_RTCC_AlarmDateGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_AlarmDateGet ( AlarmC_MODULE_ID index ) PLIB_RTCC_AlarmDateSet Function Writes to the specific RTCC module's Alarm Date register. File plib_rtcc.h C void PLIB_RTCC_AlarmDateSet(RTCC_MODULE_ID index, uint32_t data); Returns None. Description The function writes to the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Alarm Date register, an RTCC write must be enabled using the exact sequences required by the device. Example uint32_t data = 0x06102705; //Date = 27 Oct 2006 Friday PLIB_RTCC_AlarmDateSet(RTCC_ID_0, data); Parameters Parameters Description index Identifier for the device instance to be configured data The value to set the Alarm Date register to, in BCD format Function void PLIB_RTCC_AlarmDateSet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_AlarmDayGet Function Returns the contents of the Day bits in the specific RTCC module's Alarm Date register. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1729 File plib_rtcc.h C uint32_t PLIB_RTCC_AlarmDayGet(RTCC_MODULE_ID index); Returns Days bits in the Alarm Date register. Description The function returns the contents of Day bits in the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Day; Day = PLIB_RTCC_AlarmDayGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_AlarmDayGet ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmDaySet Function Writes to the specific RTCC module's Alarm Date value register. File plib_rtcc.h C void PLIB_RTCC_AlarmDaySet(RTCC_MODULE_ID index, uint32_t day); Returns None. Description The function writes to the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Alarm Date register, an RTCC write must be enabled using the exact sequences required by the device. Example uint32_t Day = 0x27; //Day = 27th of the month PLIB_RTCC_AlarmDaySet(RTCC_ID_0, Day); Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1730 Parameters Parameters Description index Identifier for the device instance to be configured day The BCD value of the day to set in the Alarm Date register Function void PLIB_RTCC_AlarmDaySet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_AlarmDisable Function Disables the specific RTCC module's alarm. File plib_rtcc.h C void PLIB_RTCC_AlarmDisable(RTCC_MODULE_ID index); Returns None. Description This function disables the specific RTCC module's alarm. RTCC Alarm bit shouldn't be modified when RTCC on bit is enabled and PLIB_RTCC_AlarmSyncStatusGet (ALRMSYNC bit) returns true. Meaning the check RTCC ON (RTCCON<15>) bit and the ALRMSYNC bit should be equal to '1'. Remarks This function implements an operation of the AlarmControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmControl in your application to automatically determine whether this feature is available. Preconditions None. Example // check RTCC enable bit and PLIB_RTCC_AlarmSyncStatusGet return value and // then modify the Alarm bit. PLIB_RTCC_AlarmDisable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_AlarmDisable ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmEnable Function Enables the specific RTCC module's alarm. File plib_rtcc.h C void PLIB_RTCC_AlarmEnable(RTCC_MODULE_ID index); Returns None. Description This function enables the specific RTCC module's alarm. RTCC Alarm bit shouldn't be modified when RTCC on bit is enabled and Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1731 PLIB_RTCC_AlarmSyncStatusGet (ALRMSYNC bit) returns true. Meaning the check RTCC ON (RTCCON<15>) bit and the ALRMSYNC bit should be equal to '1'. Remarks The alarm enable bit is cleared automatically after an alarm event whenever the alarm is not set up to repeat, and chime is disabled. This function implements an operation of the AlarmControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmControl in your application to automatically determine whether this feature is available. Preconditions None. Example // check RTCC enable bit and PLIB_RTCC_AlarmSyncStatusGet return value and // then modify the Alarm bit. PLIB_RTCC_AlarmEnable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_AlarmEnable ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmHourGet Function Returns the contents of Hours bits in the specific RTCC module's Alarm Time register. File plib_rtcc.h C uint32_t PLIB_RTCC_AlarmHourGet(RTCC_MODULE_ID index); Returns BCD value of the Hours bits in the Alarm Time register. Description The function returns the contents of the Hours bits in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Hour; Hour = PLIB_RTCC_AlarmHourGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_AlarmHourGet ( RTCC_MODULE_ID index ) Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1732 PLIB_RTCC_AlarmHourSet Function The function returns the contents of Hours bits in the specific RTCC module's Alarm Time register. File plib_rtcc.h C void PLIB_RTCC_AlarmHourSet(RTCC_MODULE_ID index, uint32_t hour); Returns None Description Returns the contents of the Hours bits in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Hour = 0x04; PLIB_RTCC_AlarmHourSet(RTCC_ID_0, Hour); Parameters Parameters Description index Identifier for the device instance to be configured hour BCD value to be written to the Hours bits in the Alarm Time register Function uint32_t PLIB_RTCC_AlarmHourSet ( RTCC_MODULE_ID index, uint32_t hour ) PLIB_RTCC_AlarmMaskModeSelect Function Sets the specific RTCC module's alarm mask Configuration bits. File plib_rtcc.h C void PLIB_RTCC_AlarmMaskModeSelect(RTCC_MODULE_ID index, RTCC_ALARM_MASK_CONFIGURATION data); Returns None. Description This function sets the specific RTCC module's alarm mask Configuration bits. Remarks The actual definition of this enumeration is device-specific. This function implements an operation of the AlarmMaskControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmMaskControl in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1733 Example uint8_t data = 0; PLIB_RTCC_AlarmMaskModeSelect(RTCC_ID_0, RTCC_ALARM_EVERY_HALF_SECOND); Parameters Parameters Description index Identifier for the device instance to be configured data Alarm mask Configuration bits Function void PLIB_RTCC_AlarmMaskModeSelect ( RTCC_MODULE_ID index, RTCC_ALARM_MASK_CONFIGURATION data ) PLIB_RTCC_AlarmMinuteGet Function Returns the contents of Minutes bits in the specific RTCC module's Alarm Time register. File plib_rtcc.h C uint32_t PLIB_RTCC_AlarmMinuteGet(RTCC_MODULE_ID index); Returns BCD value of the Minutes bits in the Alarm Time register. Description The function returns the contents of the field in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Minute; Minute = PLIB_RTCC_AlarmMinuteGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_AlarmMinuteGet ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmMinuteSet Function Returns the contents of the Minutes bits in the specific RTCC module's Alarm Time register. File plib_rtcc.h C void PLIB_RTCC_AlarmMinuteSet(RTCC_MODULE_ID index, uint32_t minute); Returns None Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1734 Description The function returns the contents of the Minutes bits in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Minute = 0x15; PLIB_RTCC_AlarmMinuteSet(RTCC_ID_0, Minute); Parameters Parameters Description index Identifier for the device instance to be configured minute BCD value to be written to the Minutes bits in the Alarm Time register Function uint32_t PLIB_RTCC_AlarmMinuteSet ( RTCC_MODULE_ID index, uint32_t minute ) PLIB_RTCC_AlarmMonthGet Function Returns the contents of the Month bits in the specific RTCC module's Alarm Date register. File plib_rtcc.h C uint32_t PLIB_RTCC_AlarmMonthGet(RTCC_MODULE_ID index); Returns Months bits in the Date register. Description The function returns the contents of the Months bits in the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Month; Month = PLIB_RTCC_AlarmMonthGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_AlarmMonthGet ( RTCC_MODULE_ID index ) Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1735 PLIB_RTCC_AlarmMonthSet Function Writes to the specific RTCC module's Alarm Date register. File plib_rtcc.h C void PLIB_RTCC_AlarmMonthSet(RTCC_MODULE_ID index, uint32_t month); Returns None. Description The function writes to the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Alarm Date register, an RTCC write must be enabled using the exact sequences required by the device. Example uint32_t Month = 0x10; //Month = October PLIB_RTCC_AlarmMonthSet(RTCC_ID_0, Month); Parameters Parameters Description index Identifier for the device instance to be configured month The BCD value of the month to set in the Alarm Date register Function void PLIB_RTCC_AlarmMonthSet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_AlarmPulseInitialGet Function Returns the state of the initial alarm pulse. File plib_rtcc.h C bool PLIB_RTCC_AlarmPulseInitialGet(RTCC_MODULE_ID index); Returns • 1 - Logical High • 0 - Logical Low Description This function returns the state of the initial alarm pulse. Remarks This function implements an operation of the AlarmPulseInitial feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmPulseInitial in your application to automatically determine whether this feature is available. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1736 Preconditions The ALRMEN bit should be '1' indicating the PLIB_RTCC_AlarmEnable function was called. Example bool PulseValue; PulseValue = PLIB_RTCC_AlarmPulseInitialGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_RTCC_AlarmPulseInitialGet ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmPulseInitialSet Function Enables the determination of the initial alarm pulse. File plib_rtcc.h C void PLIB_RTCC_AlarmPulseInitialSet(RTCC_MODULE_ID index, bool data); Returns None. Description This function enables the determination of initial alarm pulse. Remarks This function implements an operation of the AlarmPulseInitial feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmPulseInitial in your application to automatically determine whether this feature is available. Preconditions The ALRMEN bit should be '0' indicating the PLIB_RTCC_AlarmDisable was called. This function must not be called when the RTCC is ON and the Alarm Sync is 1. Example bool data = 0; PLIB_RTCC_AlarmPulseInitialSet(RTCC_ID_0, data); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_AlarmPulseInitialSet ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmRepeatCountGet Function Reads the specific RTCC module's alarm repeat counter. File plib_rtcc.h C uint8_t PLIB_RTCC_AlarmRepeatCountGet(RTCC_MODULE_ID index); Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1737 Returns uint8_t - The current value of the alarm repeat counter Description This function reads the specific RTCC module's alarm repeat counter. Remarks The counter decrements on any alarm event. The counter is prevented from rolling over unless chime is enabled. This function implements an operation of the AlarmRepeatControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmRepeatControl in your application to automatically determine whether this feature is available. Preconditions None. Example uint8_t currentCount; currentCount = PLIB_RTCC_AlarmRepeatCountGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_RTCC_AlarmRepeatCountGet ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmRepeatCountSet Function Sets the specific RTCC module's alarm repeat counter. File plib_rtcc.h C void PLIB_RTCC_AlarmRepeatCountSet(RTCC_MODULE_ID index, uint8_t data); Returns None. Description This function sets the specific RTCC module's alarm repeat counter. Remarks The counter decrements on any alarm event. The counter is prevented from rolling over unless chime is enabled. This function implements an operation of the AlarmRepeatControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmRepeatControl in your application to automatically determine whether this feature is available. Preconditions None. Example uint8_t data = 0xFF; PLIB_RTCC_AlarmRepeatCountSet(RTCC_ID_0, data); Parameters Parameters Description index Identifier for the device instance to be configured data Alarm repeat counter bits Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1738 Function void PLIB_RTCC_AlarmRepeatCountSet ( RTCC_MODULE_ID index, uint8_t data ) PLIB_RTCC_AlarmSecondGet Function Returns the contents of the Seconds bits in the specific RTCC module's Alarm Time register. File plib_rtcc.h C uint32_t PLIB_RTCC_AlarmSecondGet(RTCC_MODULE_ID index); Returns BCD value of the Seconds bits in the Alarm Time register. Description The function returns the contents of the Seconds bits in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t Second; Second = PLIB_RTCC_AlarmSecondGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_AlarmSecondGet ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmSecondSet Function Returns the contents of Seconds bits in the specific RTCC module's Alarm Time register. File plib_rtcc.h C void PLIB_RTCC_AlarmSecondSet(RTCC_MODULE_ID index, uint32_t second); Returns None Description The function returns the contents of the field in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1739 Preconditions None. Example uint32_t Second = 0x33; PLIB_RTCC_AlarmSecondSet(RTCC_ID_0, Second); Parameters Parameters Description index Identifier for the device instance to be configured second BCD value to be written to the Seconds bits in the Alarm Time register Function uint32_t PLIB_RTCC_AlarmSecondSet ( RTCC_MODULE_ID index, uint32_t second ) PLIB_RTCC_AlarmTimeGet Function Returns the contents of the specific RTCC module's Alarm Time register. File plib_rtcc.h C uint32_t PLIB_RTCC_AlarmTimeGet(RTCC_MODULE_ID index); Returns Value register. Description The function returns the contents of the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t time; time = PLIB_RTCC_AlarmTimeGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_AlarmTimeGet ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmTimeSet Function Writes to the specific RTCC module's Alarm Time register. File plib_rtcc.h C void PLIB_RTCC_AlarmTimeSet(RTCC_MODULE_ID index, uint32_t data); Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1740 Returns None. Description The function writes to the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Alarm Time register, an RTCC write must be enabled using the exact sequences required by the device. Example uint32_t data = 0x04153300; // Time = 4 hours, 15 minutes, and 33 seconds PLIB_RTCC_AlarmTimeSet(RTCC_ID_0, data); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_AlarmTimeSet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_AlarmValueRegisterPointer Function Sets the specific RTCC module's Alarm register pointer. File plib_rtcc.h C void PLIB_RTCC_AlarmValueRegisterPointer(RTCC_MODULE_ID index, uint8_t data); Returns None. Description This function sets the specific RTCC module's Alarm register pointer. Remarks None. Preconditions None. Example uint8_t data = 2; PLIB_RTCC_AlarmValueRegisterPointer(RTCC_ID_0, data); Parameters Parameters Description index Identifier for the device instance to be configured data Alarm register pointer Function void PLIB_RTCC_AlarmValueRegisterPointer ( RTCC_MODULE_ID index, uint8_t data ) Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1741 PLIB_RTCC_AlarmWeekDayGet Function Returns the contents of the WeekDay bits in the specific RTCC module's Alarm Date register. File plib_rtcc.h C uint32_t PLIB_RTCC_AlarmWeekDayGet(RTCC_MODULE_ID index); Returns WeekDay bits in the Alarm Date register. Description The function returns the contents of Weekday bits in the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Preconditions None. Example uint32_t WeekDay; WeekDay = PLIB_RTCC_AlarmWeekDayGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_RTCC_AlarmWeekDayGet ( RTCC_MODULE_ID index ) PLIB_RTCC_AlarmWeekDaySet Function Writes to the specific RTCC module's Alarm Date register. File plib_rtcc.h C void PLIB_RTCC_AlarmWeekDaySet(RTCC_MODULE_ID index, uint32_t weekday); Returns None. Description The function writes to the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Preconditions Prior to writing to the Alarm Date register, an RTCC write must be enabled using the exact sequences required by the device. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1742 Example uint32_t WeekDay = 0x05; //WeekDay = Friday PLIB_RTCC_AlarmWeekDaySet(RTCC_ID_0, WeekDay); Parameters Parameters Description index Identifier for the device instance to be configured weekday The BCD value of the weekday to set in the field of the Alarm Date register Function void PLIB_RTCC_AlarmWeekDaySet ( RTCC_MODULE_ID index, uint32_t data ) PLIB_RTCC_AlarmSyncStatusGet Function The function returns the synchronization status bit. File plib_rtcc.h C bool PLIB_RTCC_AlarmSyncStatusGet(RTCC_MODULE_ID index); Returns • true - Alarm repeat count may change as a result of a half-second rollover during a read. • false - Alarm repeat count is safe to read, and will not change in less than 32 RTC clocks. Description The function returns the synchronization status bit, which is used to determine whether it is safe to read the date/time values, or if the values will change within 32 RTCC clocks. Remarks This bit is read-only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmSynchronization in your application to automatically determine whether this feature is available. Preconditions None. Example if (PLIB_RTCC_AlarmSyncStatusGet(RTCC_ID_0)) { ... } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_RTCC_AlarmSyncStatusGet ( RTCC_MODULE_ID index ) d) Other Functions PLIB_RTCC_ClockSourceSelect Function Selects the clock source for the RTCC module. File plib_rtcc.h Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1743 C void PLIB_RTCC_ClockSourceSelect(RTCC_MODULE_ID index, RTCC_CLOCK_SOURCE_SELECT source); Returns None. Description This function determines which clock source the RTCC module will use depending on the features of the device. Remarks This function implements an operation of the ClockSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsClockSelect in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_RTCC_ClockSourceSelect(RTCC_ID_0, RTCC_CLOCK_SOURCE_SELECT_NONE); Parameters Parameters Description index Identifier for the device instance to be configured source Which clock source will be used Function void PLIB_RTCC_ClockSourceSelect ( RTCC_MODULE_ID index, RTCC_CLOCK_SOURCE_SELECT source ) PLIB_RTCC_DriftCalibrateGet Function Reads the specific RTCC module's drift calibration bits. File plib_rtcc.h C uint16_t PLIB_RTCC_DriftCalibrateGet(RTCC_MODULE_ID index); Returns uint16_t - The current drift calibration value Description This function reads the specific RTCC module's drift calibration bits. Remarks This function implements an operation of the Calibration feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCalibration in your application to automatically determine whether this feature is available. Preconditions None. Example uint16_t calibrationbits; calibrationbits = PLIB_RTCC_DriftCalibrateGet(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1744 Function uint16_t PLIB_RTCC_DriftCalibrateGet ( RTCC_MODULE_ID index ) PLIB_RTCC_DriftCalibrateSet Function Sets the specific RTCC module's drift calibration bits. File plib_rtcc.h C void PLIB_RTCC_DriftCalibrateSet(RTCC_MODULE_ID index, uint16_t calibrationbits); Returns None. Description This function sets the specific RTCC module's drift calibration bits. The error between the system clock and the external clock has to be computed and calibration input must be provided to this function. Remarks This function implements an operation of the Calibration feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCalibration in your application to automatically determine whether this feature is available. Preconditions None. Example uint16_t calibrationbits = 3; //Positive 3 adjustment derived from the formula // Error = (Ideal Freq(32758) - Measured)*60; PLIB_RTCC_DriftCalibrateSet(RTCC_ID_0, calibrationbits); Parameters Parameters Description index Identifier for the device instance to be configured calibrationbits Drift calibration bits Function void PLIB_RTCC_DriftCalibrateSet ( RTCC_MODULE_ID index, uint16_t calibrationbits ) PLIB_RTCC_HalfSecondStatusGet Function The function returns the half second status bit. File plib_rtcc.h C bool PLIB_RTCC_HalfSecondStatusGet(RTCC_MODULE_ID index); Returns • true - Second half period of a second • false - First half period of a second Description The function returns the half second status bit, which is used in the calibration procedure. When the seconds byte is zero, the calibration value must be updated when the half second bit becomes '1'. Remarks This bit is read-only. It is cleared to '0' on a write to the seconds value. This function implements an operation of the HalfSecond feature. This Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1745 feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsHalfSecond in your application to automatically determine whether this feature is available. Preconditions None. Example // Wait for the half second status bit to be '1'. while(PLIB_RTCC_HalfSecondStatusGet(RTCC_ID_0)); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_RTCC_HalfSecondStatusGet ( RTCC_MODULE_ID index ) PLIB_RTCC_OutputSelect Function Selects which signal will be presented on the RTCC pin File plib_rtcc.h C void PLIB_RTCC_OutputSelect(RTCC_MODULE_ID index, RTCC_OUTPUT_SELECT data); Returns None. Description This function selects which signal will be presented on the RTCC pin. Remarks The RTCC module's output pin should be enabled using the function PLIB_RTCC_OutputEnable. This function implements an operation of the OutputSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsOutputSelect in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_RTCC_OutputSelect(RTCC_ID_0, RTCC_OUTPUT_SECONDS_CLOCK); Parameters Parameters Description index Identifier for the device instance to be configured data Enumerated value of which signal to present Function void PLIB_RTCC_OutputSelect ( RTCC_MODULE_ID index, RTCC_OUTPUT_SELECT data ) PLIB_RTCC_StopInIdleDisable Function Continues normal RTCC operation when the device enters Idle mode. File plib_rtcc.h C void PLIB_RTCC_StopInIdleDisable(RTCC_MODULE_ID index); Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1746 Returns None. Description This function continues normal RTCC operation when the device enters Idle mode. Remarks None. This function implements an operation of the StopInIdle feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsStopInIdle in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_RTCC_StopInIdleDisable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_StopInIdleDisable( RTCC_MODULE_ID index) PLIB_RTCC_StopInIdleEnable Function Disables access to the RTCC module by the Peripheral Bus Clock (PBCLK) when the CPU enters Idle mode. File plib_rtcc.h C void PLIB_RTCC_StopInIdleEnable(RTCC_MODULE_ID index); Returns None. Description This function disables access to the RTCC module by the PBCLK when the CPU is in Idle mode. Remarks This function implements an operation of the StopInIdle feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsStopInIdle in your application to automatically determine whether this feature is available. Preconditions None. Example PLIB_RTCC_StopInIdleEnable(RTCC_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_RTCC_StopInIdleEnable( RTCC_MODULE_ID index) e) Feature Existence Functions Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1747 PLIB_RTCC_ExistsAlarmChimeControl Function Identifies whether the AlarmChimeControl feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsAlarmChimeControl(RTCC_MODULE_ID index); Returns • true - The AlarmChimeControl feature is supported on the device • false - The AlarmChimeControl feature is not supported on the device Description This function identifies whether the AlarmChimeControl feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmChimeEnable • PLIB_RTCC_AlarmChimeDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsAlarmChimeControl( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsAlarmControl Function Identifies whether the AlarmControl feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsAlarmControl(RTCC_MODULE_ID index); Returns • true - The AlarmControl feature is supported on the device • false - The AlarmControl feature is not supported on the device Description This function identifies whether the AlarmControl feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmEnable • PLIB_RTCC_AlarmDisable Remarks None. Preconditions None. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1748 Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsAlarmControl( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsAlarmDate Function Identifies whether the AlarmDate feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsAlarmDate(RTCC_MODULE_ID index); Returns • true - The AlarmDate feature is supported on the device • false - The AlarmDate feature is not supported on the device Description This function identifies whether the AlarmDate feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmDateGet • PLIB_RTCC_AlarmDateSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsAlarmDate( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsAlarmMaskControl Function Identifies whether the AlarmMaskControl feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsAlarmMaskControl(RTCC_MODULE_ID index); Returns • true - The AlarmMaskControl feature is supported on the device • false - The AlarmMaskControl feature is not supported on the device Description This function identifies whether the AlarmMaskControl feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_AlarmMaskModeSelect Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1749 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsAlarmMaskControl( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsAlarmPulseInitial Function Identifies whether the AlarmPulseInitial feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsAlarmPulseInitial(RTCC_MODULE_ID index); Returns • true - The AlarmPulseInitial feature is supported on the device • false - The AlarmPulseInitial feature is not supported on the device Description This function identifies whether the AlarmPulseInitialValue feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmPulseInitialSet • PLIB_RTCC_AlarmPulseInitialGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsAlarmPulseInitial( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsAlarmRepeatControl Function Identifies whether the AlarmRepeatControl feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsAlarmRepeatControl(RTCC_MODULE_ID index); Returns • true - The AlarmRepeatControl feature is supported on the device • false - The AlarmRepeatControl feature is not supported on the device Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1750 Description This function identifies whether the AlarmRepeatControl feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmRepeatCountSet • PLIB_RTCC_AlarmRepeatCountRead Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsAlarmRepeatControl( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsAlarmTime Function Identifies whether the AlarmTime feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsAlarmTime(RTCC_MODULE_ID index); Returns • true - The AlarmTime feature is supported on the device • false - The AlarmTime feature is not supported on the device Description This function identifies whether the AlarmTime feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmTimeGet • PLIB_RTCC_AlarmTimeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsAlarmTime( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsCalibration Function Identifies whether the Calibration feature exists on the RTCC module. File plib_rtcc.h Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1751 C bool PLIB_RTCC_ExistsCalibration(RTCC_MODULE_ID index); Returns • true - The Calibration feature is supported on the device • false - The Calibration feature is not supported on the device Description This function identifies whether the Calibration feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_DriftCalibrate Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsCalibration( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsClockRunning Function Identifies whether the ClockRunning feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsClockRunning(RTCC_MODULE_ID index); Returns • true - The ClockRunning feature is supported on the device • false - The ClockRunning feature is not supported on the device Description This function identifies whether the ClockRunning feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_ClockRunningStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsClockRunning( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsClockSelect Function Identifies whether the ClockSelect feature exists on the RTCC module. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1752 File plib_rtcc.h C bool PLIB_RTCC_ExistsClockSelect(RTCC_MODULE_ID index); Returns • true - The ClockSelect feature is supported on the device • false - The ClockSelect feature is not supported on the device Description This function identifies whether the ClockSelect feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_SourceClockSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsClockSelect( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsEnableControl(RTCC_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_Enable • PLIB_RTCC_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsEnableControl( RTCC_MODULE_ID index ) Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1753 PLIB_RTCC_ExistsHalfSecond Function Identifies whether the HalfSecond feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsHalfSecond(RTCC_MODULE_ID index); Returns • true - The HalfSecond feature is supported on the device • false - The HalfSecond feature is not supported on the device Description This function identifies whether the HalfSecond feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_HalfSecondStatusBit Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsHalfSecond( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsOutputControl Function Identifies whether the OutputControl feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsOutputControl(RTCC_MODULE_ID index); Returns • true - The OutputControl feature is supported on the device • false - The OutputControl feature is not supported on the device Description This function identifies whether the OutputControl feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_ClockOutputEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1754 Function PLIB_RTCC_ExistsOutputControl( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsOutputSelect Function Identifies whether the OutputSelect feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsOutputSelect(RTCC_MODULE_ID index); Returns • true - The OutputSelect feature is supported on the device • false - The OutputSelect feature is not supported on the device Description This function identifies whether the OutputSelect feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_SecondsClockOutputSelect • PLIB_RTCC_AlarmPulseOutputSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsOutputSelect( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsRTCDate Function Identifies whether the RTCDateValue feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsRTCDate(RTCC_MODULE_ID index); Returns • true - The RTCDate feature is supported on the device • false - The RTCDate feature is not supported on the device Description This function identifies whether the RTCDateValue feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_RTCDateGet • PLIB_RTCC_RTCDateSet Remarks None. Preconditions None. Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1755 Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsRTCDate( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsRTCTime Function Identifies whether the RTCTimeValue feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsRTCTime(RTCC_MODULE_ID index); Returns • true - The RTCTime feature is supported on the device • false - The RTCTime feature is not supported on the device Description This function identifies whether the RTCTimeValue feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_RTCTimeGet • PLIB_RTCC_RTCTimeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsRTCTime( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsStopInIdleControl Function Identifies whether the StopInIdle feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsStopInIdleControl(RTCC_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_StopInIdleEnable • PLIB_RTCC_StopInIdleDisable Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1756 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsStopInIdleControl( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsSynchronization Function Identifies whether the Synchronization feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsSynchronization(RTCC_MODULE_ID index); Returns • true - The Synchronization feature is supported on the device • false - The Synchronization feature is not supported on the device Description This function identifies whether the Synchronization feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_RTCSyncStatusGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsSynchronization( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsWriteEnable Function Identifies whether the WriteEnable feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsWriteEnable(RTCC_MODULE_ID index); Returns • true - The WriteEnable feature is supported on the device • false - The WriteEnable feature is not supported on the device Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1757 Description This function identifies whether the WriteEnable feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_WriteEnable • PLIB_RTCC_WriteDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsWriteEnable( RTCC_MODULE_ID index ) PLIB_RTCC_ExistsAlarmSynchronization Function Identifies whether the AlarmSynchronization feature exists on the RTCC module. File plib_rtcc.h C bool PLIB_RTCC_ExistsAlarmSynchronization(RTCC_MODULE_ID index); Returns • true - The AlarmSynchronization feature is supported on the device • false - The AlarmSynchronization feature is not supported on the device Description This function identifies whether the AlarmSynchronization feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_AlarmSyncGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_RTCC_ExistsAlarmSynchronization( RTCC_MODULE_ID index ) f) Data Types and Constants RTCC_ALARM_MASK_CONFIGURATION Enumeration Data type defining the different configurations for the alarm mask bits. File plib_rtcc_help.h Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1758 C typedef enum { RTCC_ALARM_EVERY_HALF_SECOND, RTCC_ALARM_EVERY_SECOND, RTCC_ALARM_EVERY_10_SECONDS, RTCC_ALARM_EVERY_MINUTE, RTCC_ALARM_EVERY_10_MINUTES, RTCC_ALARM_EVERY_HOUR, RTCC_ALARM_ONCE_A_DAY, RTCC_ALARM_ONCE_A_WEEK, RTCC_ALARM_ONCE_A_MONTH, RTCC_ALARM_ONCE_A_YEAR } RTCC_ALARM_MASK_CONFIGURATION; Members Members Description RTCC_ALARM_EVERY_HALF_SECOND Alarm every half second RTCC_ALARM_EVERY_SECOND Alarm every second RTCC_ALARM_EVERY_10_SECONDS Alarm every 10 seconds RTCC_ALARM_EVERY_MINUTE Alarm every minute RTCC_ALARM_EVERY_10_MINUTES Alarm every 10 minutes RTCC_ALARM_EVERY_HOUR Alarm every hour RTCC_ALARM_ONCE_A_DAY Alarm every day RTCC_ALARM_ONCE_A_WEEK Alarm every week RTCC_ALARM_ONCE_A_MONTH Alarm every month RTCC_ALARM_ONCE_A_YEAR Alarm every year Description Alarm Mask Configuration This data type defines the different configurations for accessing the alarm mask Configuration bits. Remarks The actual definition of this enumeration is device-specific. RTCC_MODULE_ID Enumeration File plib_rtcc_help.h C typedef enum { RTCC_ID_1, RTCC_NUMBER_OF_MODULES } RTCC_MODULE_ID; Members Members Description RTCC_NUMBER_OF_MODULES The total number of modules available. Description Enumeration: RTCC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the superset of all of the possible instances that may be available on the Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. RTCC_VALUE_REGISTER_POINTER Enumeration Data type defining the different configurations by which the RTCC Date and Time Registers can be accessed. File plib_rtcc_help.h Peripheral Libraries Help RTCC Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1759 C typedef enum { RTCC_REG_YEAR, RTCC_REG_DAY_MONTH, RTCC_REG_HOURS_WEEKDAY, RTCC_REG_MINUTES_SECONDS } RTCC_VALUE_REGISTER_POINTER; Members Members Description RTCC_REG_YEAR The year register is being pointed RTCC_REG_DAY_MONTH The day and month register is being pointed RTCC_REG_HOURS_WEEKDAY The hours and weekday register is being pointed RTCC_REG_MINUTES_SECONDS The minutes and seconds register is being pointed Description Value Register Pointer This data type defines the different configurations by which the RTCC Date and Time Registers can be accessed. Remarks The actual definition of this enumeration is device-specific. Files Files Name Description plib_rtcc.h RTCC Peripheral Library interface header for RTCC common definitions. plib_rtcc_help.h This is file plib_rtcc_help.h. Description This section lists the source and header files used by the library. plib_rtcc.h RTCC Peripheral Library interface header for RTCC common definitions. Functions Name Description PLIB_RTCC_AlarmChimeDisable Disables the specific RTCC module's chime. PLIB_RTCC_AlarmChimeEnable Enables the specific RTCC module's chime. PLIB_RTCC_AlarmDateGet Returns the contents of the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDateSet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDayGet Returns the contents of the Day bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDaySet Writes to the specific RTCC module's Alarm Date value register. PLIB_RTCC_AlarmDisable Disables the specific RTCC module's alarm. PLIB_RTCC_AlarmEnable Enables the specific RTCC module's alarm. PLIB_RTCC_AlarmHourGet Returns the contents of Hours bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmHourSet The function returns the contents of Hours bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMaskModeSelect Sets the specific RTCC module's alarm mask Configuration bits. PLIB_RTCC_AlarmMinuteGet Returns the contents of Minutes bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMinuteSet Returns the contents of the Minutes bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMonthGet Returns the contents of the Month bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmMonthSet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmPulseInitialGet Returns the state of the initial alarm pulse. PLIB_RTCC_AlarmPulseInitialSet Enables the determination of the initial alarm pulse. Peripheral Libraries Help RTCC Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1760 PLIB_RTCC_AlarmRepeatCountGet Reads the specific RTCC module's alarm repeat counter. PLIB_RTCC_AlarmRepeatCountSet Sets the specific RTCC module's alarm repeat counter. PLIB_RTCC_AlarmSecondGet Returns the contents of the Seconds bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmSecondSet Returns the contents of Seconds bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmSyncStatusGet The function returns the synchronization status bit. PLIB_RTCC_AlarmTimeGet Returns the contents of the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmTimeSet Writes to the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmValueRegisterPointer Sets the specific RTCC module's Alarm register pointer. PLIB_RTCC_AlarmWeekDayGet Returns the contents of the WeekDay bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmWeekDaySet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_ClockOutputDisable Disables the specific RTCC module's output pin. PLIB_RTCC_ClockOutputEnable Enables the specific RTCC module's output pin. PLIB_RTCC_ClockRunningStatus Provides the status of the RTCC clock. PLIB_RTCC_ClockSourceSelect Selects the clock source for the RTCC module. PLIB_RTCC_Disable Disables the specific RTCC module on the device. PLIB_RTCC_DriftCalibrateGet Reads the specific RTCC module's drift calibration bits. PLIB_RTCC_DriftCalibrateSet Sets the specific RTCC module's drift calibration bits. PLIB_RTCC_Enable Enables the specific RTCC module on the device. PLIB_RTCC_ExistsAlarmChimeControl Identifies whether the AlarmChimeControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmControl Identifies whether the AlarmControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmDate Identifies whether the AlarmDate feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmMaskControl Identifies whether the AlarmMaskControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmPulseInitial Identifies whether the AlarmPulseInitial feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmRepeatControl Identifies whether the AlarmRepeatControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmSynchronization Identifies whether the AlarmSynchronization feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmTime Identifies whether the AlarmTime feature exists on the RTCC module. PLIB_RTCC_ExistsCalibration Identifies whether the Calibration feature exists on the RTCC module. PLIB_RTCC_ExistsClockRunning Identifies whether the ClockRunning feature exists on the RTCC module. PLIB_RTCC_ExistsClockSelect Identifies whether the ClockSelect feature exists on the RTCC module. PLIB_RTCC_ExistsEnableControl Identifies whether the EnableControl feature exists on the RTCC module. PLIB_RTCC_ExistsHalfSecond Identifies whether the HalfSecond feature exists on the RTCC module. PLIB_RTCC_ExistsOutputControl Identifies whether the OutputControl feature exists on the RTCC module. PLIB_RTCC_ExistsOutputSelect Identifies whether the OutputSelect feature exists on the RTCC module. PLIB_RTCC_ExistsRTCDate Identifies whether the RTCDateValue feature exists on the RTCC module. PLIB_RTCC_ExistsRTCTime Identifies whether the RTCTimeValue feature exists on the RTCC module. PLIB_RTCC_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the RTCC module. PLIB_RTCC_ExistsSynchronization Identifies whether the Synchronization feature exists on the RTCC module. PLIB_RTCC_ExistsWriteEnable Identifies whether the WriteEnable feature exists on the RTCC module. PLIB_RTCC_HalfSecondStatusGet The function returns the half second status bit. PLIB_RTCC_OutputSelect Selects which signal will be presented on the RTCC pin PLIB_RTCC_RTCDateGet Returns the contents of the specific RTCC module's Date register. PLIB_RTCC_RTCDateSet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCDayGet Returns the contents of the Days bits in the specific RTCC module's Date register. PLIB_RTCC_RTCDaySet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCHourGet Returns the contents of the Hours bits in the specific RTCC module's Time register. PLIB_RTCC_RTCHourSet Writes the contents of the Hours bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMinuteGet Returns the contents of the Minutes bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMinuteSet Writes the contents of Minutes bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMonthGet Returns the contents of the Months bits in the specific RTCC module's Date register. PLIB_RTCC_RTCMonthSet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCSecondGet The function returns the contents of the Seconds bits in the specific RTCC device's Time register. PLIB_RTCC_RTCSecondSet Writes the contents of Seconds bits in the specific RTCC module's Time register. PLIB_RTCC_RTCSyncStatusGet The function returns the synchronization status bit. Peripheral Libraries Help RTCC Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1761 PLIB_RTCC_RTCTimeGet Returns the contents of the specific RTCC module's Time register. PLIB_RTCC_RTCTimeSet Writes to the specific RTCC module's Time register. PLIB_RTCC_RTCWeekDayGet Returns the contents of the WeekDay bits in the specific RTCC module's Date register. PLIB_RTCC_RTCWeekDaySet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCYearGet Returns the contents of the Year bits in the specific RTCC module's Date register. PLIB_RTCC_RTCYearSet Writes to the specific RTCC module's Date register. PLIB_RTCC_StopInIdleDisable Continues normal RTCC operation when the device enters Idle mode. PLIB_RTCC_StopInIdleEnable Disables access to the RTCC module by the Peripheral Bus Clock (PBCLK) when the CPU enters Idle mode. PLIB_RTCC_WriteDisable Disables writing to the specific RTCC module's value registers. PLIB_RTCC_WriteEnable Enables writing to the specific RTCC module's value registers. Description Real-Time Clock and Calendar (RTCC) Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the RTCC Peripheral Library for all families of Microchip microcontrollers. The definitions in this file are common to the RTCC peripheral. File Name plib_rtcc.h Company Microchip Technology Inc. plib_rtcc_help.h Enumerations Name Description RTCC_ALARM_MASK_CONFIGURATION Data type defining the different configurations for the alarm mask bits. RTCC_MODULE_ID Enumeration: RTCC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the superset of all of the possible instances that may be available on the Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. RTCC_VALUE_REGISTER_POINTER Data type defining the different configurations by which the RTCC Date and Time Registers can be accessed. Description This is file plib_rtcc_help.h. Peripheral Libraries Help RTCC Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1762 System Bus Peripheral Library This section describes the System Bus Peripheral Library. Introduction This library provides a low-level abstraction of the System Bus on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description The System Bus is a multi-layer crossbar switching matrix that connects initiators to targets. An initiator is a device or peripheral that initiates a data transfer to or from a target. Examples of initiators include the CPU, DMA and Ethernet controller. A target is a memory, bus or peripheral that sends or receives data to/from an initiator. The System Bus allows the system programmer to control which initiators can access each target by defining permission groups for each initiator. Each target has one or more regions (physical address spaces) that can be individually programmed to allow access to different permission groups. By setting initiator permission groups and target region read/write permissions, the system programmer can allow or deny task or program access to system resources. Using the Library This topic describes the basic architecture of the System Bus Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_sb.h The interface to the System Bus Peripheral library is defined in the plib_sb.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the System Bus Peripheral library must include peripheral.h. Library File: The System Bus Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the peripheral interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the System Bus on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description System Bus Software Abstraction Block Diagram Peripheral Libraries Help System Bus Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1763 Hardware Abstraction Model The System Bus Peripheral Library provides interface routines to initialize the bus matrix such that: • Initiator permission groups are assigned • Target regions are defined and given read/write access permissions • Errors are identified, logged and cleared when a permission group violation occurs • CPU and DMA priorities are set Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the System Bus module. Library Interface Section Description Target Initialization Functions This section provides target initialization functions. PGV Error Functions This section provides PGV error functions. Other Functions This section provides additional System Bus functions. Feature Existence Functions This section provides functions that determine whether certain features exist. How the Library Works The System Bus is a crossbar interconnect matrix that provides for simultaneous data transfer between the CPU, memory, and various peripherals on the PIC32 device. In addition, it provides a protection mechanism that allows trusted code to define and restrict access to memory regions and peripherals. A typical application would be a secure bootloader that prevents a third party or untrusted application from accessing regions of Flash memory that contain privileged code or information. The protection mechanism works by dividing the target physical address space into regions, each of which may be accessed by one or more initiators. Individual targets may have one or more regions. Each region can be individually programmed to allow read or write access to one or more permission groups. Each initiator is assigned to a permission group. This library provides interface routines to initialize the System Bus and initiator permission groups. On reset or NMI, the CPU is assigned to permission group 0 (full access). Note: Refer to the "CPU" chapter in the specific device data sheet or the family reference manual section specified in that chapter for information on target region mapping and initiator permission groups for a specific device. Peripheral Libraries Help System Bus Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1764 Initiator Initialization Initializing the initiators for the System Bus is a two-step process: • Set CPU and DMA priorities (if needed) • Assign permission groups to each initiator Priority assignments for CPU and DMA By default, the System Bus uses a least-recently-serviced (LRS) priority arbitration scheme for most initiators, including the CPU and DMA. For applications that require low latency, the user may set the CPU and/or DMA arbitration to fixed high priority. For the CPU, fixed high priority means that the CPU gets arbitration preference while servicing an interrupt over all initiators using LRS arbitration. Priority is set using the PLIB_SB_CPUPrioritySet and PLIB_SB_DMAPrioritySet library functions. Initiator permission groups At reset, all initiators default to permission group 0. Each target region can be individually programmed to allow read or write access to any or all permission groups. By assigning permission groups to initiators and restricting target region read/write access based on permission group, it is possible to restrict initiator access to target regions during normal operations. Permission groups are assigned using the library function PLIB_SB_InitPermGrpSet. Target Initialization Each System Bus target resides in a physical address space that contains one or more regions. Regions are used to provide separate access permissions for different areas within a target address space. Region 0 for any target is defined as the entire address space for that target. At reset, region 0 for all targets is accessible by any initiator with group 0 permissions. Target regions are defined by base (physical) address and size. Read and write permissions are programmed individually for each region. The number of regions for each target varies, depending on the target. Some regions have fixed addresses, sizes and/or permissions. For example, region 0 for all targets encompasses the entire address space for the target, so the address and size are preprogrammed. Similarly, write permission for PFM is disabled for all initiators except the Flash controller. Target region initialization is a four step process: 1. Set the base address of a region using PLIB_SB_PGRegionAddrSet. This function takes an enumerated value for the target region. Only valid target regions should be enumerated for any specific device. 2. Set the size of the region using PLIB_SB_PGRegionSizeSet. 3. Set the read permissions using PLIB_SB_PGRegionReadPermSet. 4. Set the write permissions using PLIB_SB_PGRegionWritePermSet. Note: Please refer to the "Memory Organization" chapter in the specific device data sheet or the family reference manual section specified that chapter for information on target region mapping and initiator permission groups. PGV Error Handling A permission group violation (PGV) occurs when an initiator attempts to access a target without the proper permissions. Any permission group violation will trigger an interrupt to the CPU. If enabled, the System Bus will report a PGV to the error log registers in the System Bus. The PGV interrupt handler can then use this library to retrieve information about the violation and act accordingly. By default, error reporting is disabled in the System Bus and must be enabled during the start-up or boot code. Errors are divided into two categories: primary and secondary. Primary errors are errors arising from secure accesses, such as trying to access a target region without the proper permissions. Secondary errors are errors arising from non-secure accesses, such as trying to access a memory location outside of a target region. PIC32 devices support logging of primary errors only. Primary error logging is enabled using the library function PLIB_SB_PGVErrorReportPrimaryEnable. Primary error reporting can be disabled using the library function PLIB_SB_PGVErrorReportPrimaryDisable. Error logging must be enabled or disabled separately for each target. Once a permission group violation error is logged, the user can use this library to retrieve information from the System Bus error log registers. Each target has its own set of error log registers. The error information available and the library API used to retrieve it are shown in the following table. Error Log Data System Bus Peripheral Library Function Has the specified target reported an error? PLIB_SB_PGVErrorStatus Has the specified target reported more than one error since last cleared? PLIB_SB_PGVErrorMulti Type of error. PLIB_SB_PGVErrorCode Initiator ID. PLIB_SB_PGVErrorInitiatorID OCP command code of the transaction. PLIB_SB_PGVErrorCommandCode Peripheral Libraries Help System Bus Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1765 The region number of the specified target accessed during the violation. PLIB_SB_PGVErrorRegion Permission group of initiator that caused the violation. PLIB_SB_PGVErrorPermissionGroup Once an error is logged, it needs to be cleared by software before any data for a subsequent violation can be logged (for the same target). This is typically done in the exception handler that reads the data. Which function is used depends on whether a single or multiple error violation occurred. Single violations are cleared with PLIB_SB_PGVErrorClearSingle, and multiple violations are cleared with PLIB_SB_PGVErrorClearMulti. Configuring the Library The library is configured for the supported System Bus module when the processor is chosen in the MPLAB X IDE. Library Interface a) Target Initialization Functions Name Description PLIB_SB_PGRegionAddrGet Returns the base address for a permission group region within a target's physical address space. PLIB_SB_PGRegionAddrSet Sets the base address for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionReadPermClear Clears the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionReadPermSet Sets the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionSizeGet Returns the size for a permission group region within a target's physical address space. PLIB_SB_PGRegionSizeSet Sets the size for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionWritePermClear Clears the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionWritePermSet Sets the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. b) PGV Error Functions Name Description PLIB_SB_PGVErrorClearMulti Clears multiple permission group errors for the specified target. PLIB_SB_PGVErrorClearSingle Clears a single permission group error for the specified target. PLIB_SB_PGVErrorCode Returns a value corresponding to the type of error logged for the specified target. PLIB_SB_PGVErrorCommandCode Returns the OCP command code of the transaction that caused the protection violation for the specified target. PLIB_SB_PGVErrorInitiatorID Returns the ID of the Initiator that caused the protection violation PLIB_SB_PGVErrorLogClearMulti Clears a multiple protection group violations error from the specified target error log register. PLIB_SB_PGVErrorLogClearSingle Clears a single protection group violation error from the specified target error log register. PLIB_SB_PGVErrorMulti Indicates if more than one permission group violation has occurred since last cleared. PLIB_SB_PGVErrorPermissionGroup Returns the permission group of the protection region in a target address space that caused the protection violation for the specified target. PLIB_SB_PGVErrorRegion Returns the number of the protection region in the specified target address space that caused the protection violation. PLIB_SB_PGVErrorReportPrimaryDisable Disables primary permission group error reporting for the specified target to the SB flag register. PLIB_SB_PGVErrorReportPrimaryEnable Enables primary permission group error reporting for the specified target to the SB flag register. PLIB_SB_PGVErrorStatus Identifies whether a permission group violation has been reported for the specified target. PLIB_SB_PGVErrGroup0Status Identifies whether a permission group violation has been reported for the Target Group 0. PLIB_SB_PGVErrGroup1Status Identifies whether a permission group violation has been reported for the Target Group 1. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1766 PLIB_SB_PGVErrGroup2Status Identifies whether a permission group violation has been reported for the Target Group 2. PLIB_SB_PGVErrGroup3Status Identifies whether a permission group violation has been reported for the Target Group 3. PLIB_SB_PGVErrGroupStatus Identifies whether a permission group violation has been reported for the specified target group. c) Other Functions Name Description PLIB_SB_CPUPrioritySet Sets the CPU arbitration policy to SRAM when servicing an interrupt PLIB_SB_DMAPrioritySet Sets the DMA arbitration policy PLIB_SB_InitPermGrpSet Sets the read/write permission group(s) for an initiator. The region must also allow read/write access for the permission group for a read/write to occur. d) Feature Existence Functions Name Description PLIB_SB_ExistsCPUPriority Identifies whether the CPUPriority feature exists on the System Bus module. PLIB_SB_ExistsDMAPriority Identifies whether the DMAPriority feature exists on the System Bus module. PLIB_SB_ExistsInitPermGrp Identifies whether the InitPermGrp feature exists on the System Bus module. PLIB_SB_ExistsPGRegAddr Identifies whether the PGRegAddr feature exists on the System Bus module. PLIB_SB_ExistsPGRegRdPerm Identifies whether the PGRegRdPerm feature exists on the System Bus module. PLIB_SB_ExistsPGRegSize Identifies whether the PGRegSize feature exists on the System Bus module. PLIB_SB_ExistsPGRegWrPerm Identifies whether the PGRegWrPerm feature exists on the System Bus module. PLIB_SB_ExistsPGVErrClear Identifies whether the PGVErrClear feature exists on the System Bus module. PLIB_SB_ExistsPGVErrClrMulti Identifies whether the PGVErrClrMulti feature exists on the System Bus module. PLIB_SB_ExistsPGVErrClrSingle Identifies whether the PGVErrClrSingle feature exists on the System Bus module. PLIB_SB_ExistsPGVErrCmdCode Identifies whether the PGVErrCmdCode feature exists on the System Bus module. PLIB_SB_ExistsPGVErrInitID Identifies whether the PGVErrInitID feature exists on the System Bus module. PLIB_SB_ExistsPGVErrPG Identifies whether the PGVErrPG feature exists on the System Bus module. PLIB_SB_ExistsPGVErrRegion Identifies whether the PGVErrRegion feature exists on the System Bus module. PLIB_SB_ExistsPGVErrRptPri Identifies whether the PGVErrRptPri feature exists on the System Bus module. PLIB_SB_ExistsPGVErrStatus Identifies whether the PGVErrStatus feature exists on the System Bus module. PLIB_SB_ExistsPGVErrGroup0Status Identifies whether the PGVErrGroup0Status feature exists on the SB module PLIB_SB_ExistsPGVErrGroup1Status Identifies whether the PGVErrGroup1Status feature exists on the SB module PLIB_SB_ExistsPGVErrGroup2Status Identifies whether the PGVErrGroup2Status feature exists on the SB module PLIB_SB_ExistsPGVErrGroup3Status Identifies whether the PGVErrGroup3Status feature exists on the SB module PLIB_SB_ExistsPGVErrGroupStatus Identifies whether the PGVErrGroupStatus feature exists on the SB module e) Data Types and Constants Name Description PLIB_SB_ARB_POLICY This enumeration lists the possible arbitration policies that can be assigned to the CPU and DMA for SRAM access. PLIB_SB_ERROR Lists the possible System Bus Transaction Error Codes. PLIB_SB_INIT_ID Lists the possible System Bus Initiator IDs. PLIB_SB_INIT_PG Lists the possible Initiator permission groups PLIB_SB_OCP_CMD_CODE Lists the possible OCP Command codes. PLIB_SB_PG_INITIATOR Lists the possible permission group Initiators. PLIB_SB_REGION_PG This enumeration lists the possible permission groups assigned to a region for read and/or write access. PLIB_SB_TGT_ID Lists the possible System Bus Target IDs. PLIB_SB_TGT_REGION Lists the programmable target regions. SB_MODULE_ID Lists the possible Module IDs for the System Bus. Description This section describes the Application Programming Interface (API) functions of the System Bus Peripheral Library. Refer to each section for a detailed description. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1767 a) Target Initialization Functions PLIB_SB_PGRegionAddrGet Function Returns the base address for a permission group region within a target's physical address space. File plib_sb.h C uint32_t PLIB_SB_PGRegionAddrGet(SB_MODULE_ID index, PLIB_SB_TGT_REGION region); Returns uint32_t - The base address of the region. Description This function returns the base address for a permission group region within a target's physical address space. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example uint32_t T1R6BaseAddress; T1R6BaseAddress = PLIB_SB_PGRegionAddrGet(SB_ID_1, PLIB_T1_REGION_6); Parameters Parameters Description index Identifier for the device instance. region The region for which the address is returned. Function uint32_t PLIB_SB_PGRegionAddrGet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region ) PLIB_SB_PGRegionAddrSet Function Sets the base address for a permission group region within a target's physical address space. Not all regions are programmable. File plib_sb.h C void PLIB_SB_PGRegionAddrSet(SB_MODULE_ID index, PLIB_SB_TGT_REGION region, uint32_t phys_addr); Returns None. Description This function sets the base address for a permission group region within a target's physical address space. Not all regions are programmable. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Region 0 of all targets have a defined start address which may not be changed. Some regions (such as those containing peripheral SFRs) are fixed and may not be changed. Please refer to the specific device data sheet for details. Preconditions None. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1768 Example // Set up two regions in PFM with full read and write permission #define REGION_5_BASE_ADDR 0x1D000000 #define REGION_6_BASE_ADDR (REGION5_BASE_ADDR + (32*1024)) #define REGION_5_SIZE 0x06 // 32KB #define REGION_6_SIZE 0x05 // 16KB #define FULL_PERM (REGION_PG_0 | REGION_PG_1 | REGION_PG_2 | REGION_PG_3) PLIB_SB_PGRegionAddrSet(SB_ID_1, PLIB_SB_T1_REGION_5, REGION_5_BASE_ADDR); PLIB_SB_PGRegionAddrSet(SB_ID_1, PLIB_SB_T1_REGION_6, REGION_6_BASE_ADDR); PLIB_SB_PGRegionSizeSet(SB_ID_1, PLIB_SB_T1_REGION_5, REGION_5_SIZE); PLIB_SB_PGRegionSizeSet(SB_ID_1, PLIB_SB_T1_REGION_6, REGION_6_SIZE); PLIB_SB_PGRegionReadPermSet(SB_ID_1, PLIB_T1_REGION_5, FULL_PERM); PLIB_SB_PGRegionReadPermSet(SB_ID_1, PLIB_T1_REGION_6, FULL_PERM); PLIB_SB_PGRegionWritePermSet(SB_ID_1, PLIB_T1_REGION_5, FULL_PERM); PLIB_SB_PGRegionWritePermSet(SB_ID_1, PLIB_T1_REGION_6, FULL_PERM); Parameters Parameters Description index Identifier for the device instance. region The region for which the base address is set. phys_addr The base address of the region. Must be aligned to the intended size of the region. Function void PLIB_SB_PGRegionAddrSet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, uint32_t phys_addr) PLIB_SB_PGRegionReadPermClear Function Clears the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. File plib_sb.h C void PLIB_SB_PGRegionReadPermClear(SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG readPerm); Returns None. Description This function clears the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Default reset value for all programmable regions is read permission for all groups. Preconditions None. Example See the code example for PLIB_SB_PGRegionAddrSet. Parameters Parameters Description index Identifier for the device instance. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1769 region The region number within the target's address space to be given permissions. Not all regions are programmable. readPerm Bitwise OR of the groups given read permission for the region. Function void PLIB_SB_PGRegionReadPermClear( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG readPerm ) PLIB_SB_PGRegionReadPermSet Function Sets the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. File plib_sb.h C void PLIB_SB_PGRegionReadPermSet(SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG readPerm); Returns None. Description This function sets the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Default reset value for all programmable regions is read permission for all groups. Preconditions None. Example See the code example for PLIB_SB_PGRegionAddrSet. Parameters Parameters Description index Identifier for the device instance. region The region number within the target's address space to be given permissions. Not all regions are programmable. readPerm Bitwise OR of the groups given read permission for the region. Function void PLIB_SB_PGRegionReadPermSet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG readPerm ) PLIB_SB_PGRegionSizeGet Function Returns the size for a permission group region within a target's physical address space. File plib_sb.h C uint32_t PLIB_SB_PGRegionSizeGet(SB_MODULE_ID index, PLIB_SB_TGT_REGION region); Returns The size of the region. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1770 Description This function returns the size for a permission group region within a target's physical address space. Not all regions are programmable. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Region 0 of all targets encompasses the entire address range of the target, and may not be changed. Some regions (such as those containing peripheral SFRs) may not be changed. Please refer to the specific device data sheet for details. Preconditions None. Example uint32_t T1R6Size; T1R6Size = PLIB_SB_PGRegionSizeGet(SB_ID_1, PLIB_T1_REGION_6); Parameters Parameters Description index Identifier for the device instance. region The region for which the size is to be set. Not all regions are programmable. Function uint32_t PLIB_SB_PGRegionSizeGet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region ) PLIB_SB_PGRegionSizeSet Function Sets the size for a permission group region within a target's physical address space. Not all regions are programmable. File plib_sb.h C void PLIB_SB_PGRegionSizeSet(SB_MODULE_ID index, PLIB_SB_TGT_REGION region, uint32_t size); Returns None. Description This function sets the size for a permission group region within a target's physical address space. Not all regions are programmable. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Region 0 of all targets encompasses the entire address range of the target, and may not be changed. Some regions (such as those containing peripheral SFRs) may not be changed. Please refer to the specific device data sheet for details. Preconditions None. Example See the code example for PLIB_SB_PGRegionAddrSet. Parameters Parameters Description index Identifier for the device instance. region The region for which the size is to be set. Not all regions are programmable. size The actual size of the region being programmed is calculated as follows 2**(size-1)*1024 bytes Function void PLIB_SB_PGRegionSizeSet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, uint32_t size) Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1771 PLIB_SB_PGRegionWritePermClear Function Clears the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. File plib_sb.h C void PLIB_SB_PGRegionWritePermClear(SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG writePerm); Returns None. Description This function clears the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Default reset value for all programmable regions is write permission for all groups. Some regions may not be programmable by all initiators (flash, for example). Please refer to the specific device data sheet for details. Preconditions None. Example See the code example for PLIB_SB_PGRegionAddrSet. Parameters Parameters Description index Identifier for the device instance. region The region number within the target's address space to be given permissions. Not all regions are programmable. writePerm Bitwise OR of the groups given read permission for the region. Function void PLIB_SB_PGRegionWritePermClear( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG writePerm ) PLIB_SB_PGRegionWritePermSet Function Sets the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. File plib_sb.h C void PLIB_SB_PGRegionWritePermSet(SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG writePerm); Returns None. Description This function sets the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1772 Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Default reset value for all programmable regions is write permission for all groups. Some regions may not be programmable by all initiators (flash, for example). Please refer to the specific device data sheet for details. Preconditions None. Example See the code example for PLIB_SB_PGRegionAddrSet. Parameters Parameters Description index Identifier for the device instance. region The region number within the target's address space to be given permissions. Not all regions are programmable. writePerm Bitwise OR of the groups given read permission for the region. Function void PLIB_SB_PGRegionWritePermSet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG writePerm ) b) PGV Error Functions PLIB_SB_PGVErrorClearMulti Function Clears multiple permission group errors for the specified target. File plib_sb.h C bool PLIB_SB_PGVErrorClearMulti(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns mult - Returns the value of the CLEAR bit in the SBTxECLRM register for the specified target. The act of reading this bit clears the error. Description This function clears multiple permission group errors for the specified target. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example bool mult; mult = PLIB_SB_PGVErrorClearMulti(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target. Function bool PLIB_SB_PGVErrorClearMulti( SB_MODULE_ID index, PLIB_SB_TGT_ID target ) Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1773 PLIB_SB_PGVErrorClearSingle Function Clears a single permission group error for the specified target. File plib_sb.h C bool PLIB_SB_PGVErrorClearSingle(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns sing - Returns the value of the CLEAR bit in the SBTxECLRM register for the specified target. The act of reading this bit clears the error. Description This function clears a single permission group error for the specified target. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example bool sing; sing = PLIB_SB_PGVErrorClearSingle(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target. Function bool PLIB_SB_PGVErrorClearSingle( SB_MODULE_ID index, PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorCode Function Returns a value corresponding to the type of error logged for the specified target. File plib_sb.h C PLIB_SB_ERROR PLIB_SB_PGVErrorCode(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns PLIB_SB_ERROR enumeration representing the type of SB error logged states. Description This function returns a value corresponding to the type of error logged for the specified target. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example PLIB_SB_ERROR error; error = PLIB_SB_ERROR PLIB_SB_PGVErrorCode(SB_ID_1, PLIB_SB_TGT_ID_T0); Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1774 Parameters Parameters Description index Identifier for the device instance. target The target to be read. Function PLIB_SB_ERROR PLIB_SB_PGVErrorCode( SB_MODULE_ID index, PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorCommandCode Function Returns the OCP command code of the transaction that caused the protection violation for the specified target. File plib_sb.h C PLIB_SB_OCP_CMD_CODE PLIB_SB_PGVErrorCommandCode(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns OCP command code Description This function returns the OCP command code of the transaction that caused the protection violation for the specified target. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example PLIB_SB_OCP_CMD_CODE commandCode; commandCode = PLIB_SB_PGVErrorCommandCode(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target. Function PLIB_SB_OCP_CMD_CODE PLIB_SB_PGVErrorCommandCode( SB_MODULE_ID index , PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorInitiatorID Function Returns the ID of the Initiator that caused the protection violation File plib_sb.h C PLIB_SB_INIT_ID PLIB_SB_PGVErrorInitiatorID(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns An enumerated value representing the ID of the initiator that caused the protection violation. Description This function returns the ID of the Initiator that caused the protection violation. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1775 Preconditions None. Example PLIB_SB_INIT_ID id; id = PLIB_SB_PGVErrorInitiatorID(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target. Function PLIB_SB_INIT_ID PLIB_SB_PGVErrorInitiatorID( SB_MODULE_ID index , PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorLogClearMulti Function Clears a multiple protection group violations error from the specified target error log register. File plib_sb.h C void PLIB_SB_PGVErrorLogClearMulti(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns None. Description This function clears a multiple protection group violations error from the specified target error log register. Multiple errors are cleared by writing a '1' to both the MULTI and CODE fields of the SBTxELOG1 register for the specified target. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example PLIB_SB_PGVErrorLogClearMulti(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target to be cleared. Function void PLIB_SB_PGVErrorLogClearMulti( SB_MODULE_ID index, PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorLogClearSingle Function Clears a single protection group violation error from the specified target error log register. File plib_sb.h C void PLIB_SB_PGVErrorLogClearSingle(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1776 Returns None. Description This function clears a single protection group violation error from the specified target error log register. Single errors are cleared by writing a '1' to the CODE field of the SBTxELOG1 register for the specified target. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example PLIB_SB_PGVErrorLogClearSingle(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target to be cleared. Function void PLIB_SB_PGVErrorLogClearSingle( SB_MODULE_ID index, PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorMulti Function Indicates if more than one permission group violation has occurred since last cleared. File plib_sb.h C bool PLIB_SB_PGVErrorMulti(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns • true - Multiple permission group violations. • false - Single or no permission group violations. Description This function indicates if more than one permission group violation has occurred since last cleared. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example bool multiPGV; multiPGV = PLIB_SB_PGVErrorMulti(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target to be read. Function bool PLIB_SB_PGVErrorMulti( SB_MODULE_ID index , PLIB_SB_TGT_ID target ) Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1777 PLIB_SB_PGVErrorPermissionGroup Function Returns the permission group of the protection region in a target address space that caused the protection violation for the specified target. File plib_sb.h C int PLIB_SB_PGVErrorPermissionGroup(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns None. Description This function returns the permission group of the protection region in a target address space that caused the protection violation for the specified target. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example int pg; pg = PLIB_SB_PGVErrorPermissionGroup(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target. Function int PLIB_SB_PGVErrorPermissionGroup( SB_MODULE_ID index , PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorRegion Function Returns the number of the protection region in the specified target address space that caused the protection violation. File plib_sb.h C int PLIB_SB_PGVErrorRegion(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns Region number in target address space or -1 on unrecognized target. Description This function returns the number of the protection region in the specified target address space that caused the protection violation. Note that if there are no other region matches, region 0 (the default region that spans the entire target address space) will always match, and this function will return 0. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example int region; Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1778 region = PLIB_SB_PGVErrorRegion(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target. Function int PLIB_SB_PGVErrorRegion( SB_MODULE_ID index, PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorReportPrimaryDisable Function Disables primary permission group error reporting for the specified target to the SB flag register. File plib_sb.h C void PLIB_SB_PGVErrorReportPrimaryDisable(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns None. Description This function disables primary permission group error reporting for the specified target to the SB flag register. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Reporting of primary errors is disabled at reset. Preconditions None. Example PLIB_SB_PGVErrorReportPrimaryDisable(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target. Function void PLIB_SB_PGVErrorReportPrimaryDisable( SB_MODULE_ID index, PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorReportPrimaryEnable Function Enables primary permission group error reporting for the specified target to the SB flag register. File plib_sb.h C void PLIB_SB_PGVErrorReportPrimaryEnable(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns None. Description This function enables primary permission group error reporting for the specified target to the SB flag register. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1779 Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Reporting of primary errors is disabled at reset. Preconditions None. Example PLIB_SB_PGVErrorReportPrimaryEnable(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target The target. Function void PLIB_SB_PGVErrorReportPrimaryEnable( SB_MODULE_ID index , PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrorStatus Function Identifies whether a permission group violation has been reported for the specified target. File plib_sb.h C bool PLIB_SB_PGVErrorStatus(SB_MODULE_ID index, PLIB_SB_TGT_ID target); Returns • true - Target is reporting a permission group violation. • false - Target is not reporting a permission group violation. Description This function identifies whether a permission group violation has been reported for the specified target. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example bool sbPgv; sbPgv = PLIB_SB_PGVErrorStatus(SB_ID_1, PLIB_SB_TGT_ID_T0); Parameters Parameters Description index Identifier for the device instance. target Target to be checked. Function bool PLIB_SB_PGVErrorStatus ( SB_MODULE_ID index , PLIB_SB_TGT_ID target ) PLIB_SB_PGVErrGroup0Status Function Identifies whether a permission group violation has been reported for the Target Group 0. File plib_sb.h Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1780 C bool PLIB_SB_PGVErrGroup0Status(SB_MODULE_ID index, PLIB_SB_PGV_GROUP0_TGT targetId); Returns • true - Target is reporting a permission group violation. • false - Target is not reporting a permission group violation. Description This function identifies whether a permission group violation has been reported for Target Group 0. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example bool sbPgv; sbPgv = PLIB_SB_PGVErrGroup0Status(SB_ID_0, PLIB_SB_PGV_GROUP0_T1_PGV); Parameters Parameters Description index Identifier for the device instance. targetId Target to be checked. Function bool PLIB_SB_PGVErrGroup0Status( SB_MODULE_ID index, PLIB_SB_PGV_GROUP0_TGT targetId); PLIB_SB_PGVErrGroup1Status Function Identifies whether a permission group violation has been reported for the Target Group 1. File plib_sb.h C bool PLIB_SB_PGVErrGroup1Status(SB_MODULE_ID index, PLIB_SB_PGV_GROUP1_TGT targetId); Returns • true - Target is reporting a permission group violation. • false - Target is not reporting a permission group violation. Description This function identifies whether a permission group violation has been reported for Target Group 1. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example bool sbPgv; sbPgv = PLIB_SB_PGVErrGroup1Status(SB_ID_0, PLIB_SB_PGV_GROUP1_T11_PGV); Parameters Parameters Description index Identifier for the device instance. targetId Target to be checked. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1781 Function bool PLIB_SB_PGVErrGroup1Status( SB_MODULE_ID index, PLIB_SB_PGV_GROUP1_TGT targetId); PLIB_SB_PGVErrGroup2Status Function Identifies whether a permission group violation has been reported for the Target Group 2. File plib_sb.h C bool PLIB_SB_PGVErrGroup2Status(SB_MODULE_ID index, PLIB_SB_PGV_GROUP2_TGT targetId); Returns • true - Target is reporting a permission group violation. • false - Target is not reporting a permission group violation. Description This function identifies whether a permission group violation has been reported for Target Group 2. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example bool sbPgv; sbPgv = PLIB_SB_PGVErrGroup2Status(SB_ID_0, PLIB_SB_PGV_GROUP2_T14_PGV); Parameters Parameters Description index Identifier for the device instance. targetId Target to be checked. Function bool PLIB_SB_PGVErrGroup2Status( SB_MODULE_ID index, PLIB_SB_PGV_GROUP2_TGT targetId); PLIB_SB_PGVErrGroup3Status Function Identifies whether a permission group violation has been reported for the Target Group 3. File plib_sb.h C bool PLIB_SB_PGVErrGroup3Status(SB_MODULE_ID index, PLIB_SB_PGV_GROUP3_TGT targetId); Returns • true - Target is reporting a permission group violation. • false - Target is not reporting a permission group violation. Description This function identifies whether a permission group violation has been reported for Target Group 3. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1782 Example bool sbPgv; sbPgv = PLIB_SB_PGVErrGroup3Status(SB_ID_0, PLIB_SB_PGV_GROUP3_T16_PGV); Parameters Parameters Description index Identifier for the device instance. targetId Target to be checked. Function bool PLIB_SB_PGVErrGroup3Status( SB_MODULE_ID index, PLIB_SB_PGV_GROUP3_TGT targetId); PLIB_SB_PGVErrGroupStatus Function Identifies whether a permission group violation has been reported for the specified target group. File plib_sb.h C bool PLIB_SB_PGVErrGroupStatus(SB_MODULE_ID index, PLIB_SB_PGV_GROUP_ID groupId); Returns • true - Target group is reporting a permission group violation. • false - Target group is not reporting a permission group violation. Description This function identifies whether a permission group violation has been reported for the specified target group. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Preconditions None. Example bool sbPgv; sbPgv = PLIB_SB_PGVErrGroupStatus(SB_ID_0, PLIB_SB_PGV_GROUP0); Parameters Parameters Description index Identifier for the device instance. groupId Target group to be checked. Function bool PLIB_SB_PGVErrGroupStatus( SB_MODULE_ID index, PLIB_SB_PGV_GROUP_ID groupId); c) Other Functions PLIB_SB_CPUPrioritySet Function Sets the CPU arbitration policy to SRAM when servicing an interrupt File plib_sb.h C void PLIB_SB_CPUPrioritySet(SB_MODULE_ID index, PLIB_SB_ARB_POLICY priority); Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1783 Returns None. Description This function sets the CPU arbitration policy to SRAM when servicing an interrupt. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. This function writes to the soft configuration register CFGCON, which is not part of the SB. This should be done by the boot code prior to programming the SB. Note that the system must be unlocked before the priority can be set. Default at reset is PRIORITY_LRS. Preconditions System must be unlocked before the priority can be set. Example PLIB_SB_PriorityUnlock(); PLIB_SB_CPUPrioritySet(SB_ID_1, PRIORITY_HI); Parameters Parameters Description priority Use either high priority or least-recently-serviced algorithm. Function void PLIB_SB_CPUPrioritySet( SB_MODULE_ID index, PLIB_SB_ARB_POLICY priority ) PLIB_SB_DMAPrioritySet Function Sets the DMA arbitration policy File plib_sb.h C void PLIB_SB_DMAPrioritySet(SB_MODULE_ID index, PLIB_SB_ARB_POLICY priority); Returns None. Description This function sets the DMA arbitration. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. This function writes to the soft configuration register CFGCON, which is not part of the SB. This should be done by the boot code prior to programming the SB. Note that the system must be unlocked before the priority can be set. Default at reset is PRIORITY_LRS. Preconditions System must be unlocked before the priority can be set. Example PLIB_SB_PriorityUnlock(); void PLIB_SB_DMAPrioritySet(SB_ID_1, PRIORITY_HI); Parameters Parameters Description priority Use either high priority or least-recently-serviced algorithm. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1784 Function void PLIB_SB_DMAPrioritySet( SB_MODULE_ID index, PLIB_SB_ARB_POLICY priority ) PLIB_SB_InitPermGrpSet Function Sets the read/write permission group(s) for an initiator. The region must also allow read/write access for the permission group for a read/write to occur. File plib_sb.h C void PLIB_SB_InitPermGrpSet(SB_MODULE_ID index, PLIB_SB_PG_INITIATOR initiator, PLIB_SB_INIT_PG pg); Returns None. Description This function sets the read/write permission group(s) for an initiator. The region must also allow read/write access for the permission group for a read/write to occur. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. This function writes to the soft configuration register CFGPG, which is not part of the SB. Permission groups should be assigned by the boot code prior to programming the SB. Default permission group at reset for all initiators is 0. After an NMI, the CPU permission group reverts to 0. All other initiator permission groups remain unchanged. The effective CPU permission group value in debug mode is controlled by boot configuration value DBGPER[2:0]. If DBGPER denies access to the group CPU1PG selects, the effective value selects group 3. Preconditions None. Example PLIB_SB_InitPermGrpSet(SB_ID_1, PLIB_SB_PG_INITIATOR_CPU, PLIB_SB_INIT_PG_1); Parameters Parameters Description initiator The initiator for which permission groups are assigned. pg The permission group(s) to which the initiator is assigned. Function void PLIB_SB_InitPermGrpSet( SB_MODULE_ID index, PLIB_SB_PG_INITIATOR initiator, PLIB_SB_INIT_PG pg ) d) Feature Existence Functions PLIB_SB_ExistsCPUPriority Function Identifies whether the CPUPriority feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsCPUPriority(SB_MODULE_ID index); Returns • true - The CPUPriority feature is supported on the device • false - The CPUPriority feature is not supported on the device Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1785 Description This function identifies whether the CPUPriority feature is available on the System Bus module. When this function returns true, this function is supported on the device: • PLIB_SB_CPUPrioritySet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsCPUPriority( SB_MODULE_ID index ) PLIB_SB_ExistsDMAPriority Function Identifies whether the DMAPriority feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsDMAPriority(SB_MODULE_ID index); Returns • true - The DMAPriority feature is supported on the device • false - The DMAPriority feature is not supported on the device Description This function identifies whether the DMAPriority feature is available on the System Bus module. When this function returns true, this function is supported on the device: • PLIB_SB_DMAPrioritySet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsDMAPriority( SB_MODULE_ID index ) PLIB_SB_ExistsInitPermGrp Function Identifies whether the InitPermGrp feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsInitPermGrp(SB_MODULE_ID index); Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1786 Returns • true - The InitPermGrp feature is supported on the device • false - The InitPermGrp feature is not supported on the device Description This function identifies whether the InitPermGrp feature is available on the System Bus module. When this function returns true, this function is supported on the device: • PLIB_SB_InitPermGrpSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsInitPermGrp( SB_MODULE_ID index ) PLIB_SB_ExistsPGRegAddr Function Identifies whether the PGRegAddr feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGRegAddr(SB_MODULE_ID index); Returns • true - The PGRegAddr feature is supported on the device • false - The PGRegAddr feature is not supported on the device Description This function identifies whether the PGRegAddr feature is available on the System Bus module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGRegionAddrSet • PLIB_SB_PGRegionAddrGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGRegAddr( SB_MODULE_ID index ) PLIB_SB_ExistsPGRegRdPerm Function Identifies whether the PGRegRdPerm feature exists on the System Bus module. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1787 File plib_sb.h C bool PLIB_SB_ExistsPGRegRdPerm(SB_MODULE_ID index); Returns • true - The PGRegRdPerm feature is supported on the device • false - The PGRegRdPerm feature is not supported on the device Description This function identifies whether the PGRegRdPerm feature is available on the System Bus module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGRegionReadPermSet • PLIB_SB_PGRegionReadPermClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGRegRdPerm( SB_MODULE_ID index ) PLIB_SB_ExistsPGRegSize Function Identifies whether the PGRegSize feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGRegSize(SB_MODULE_ID index); Returns • true - The PGRegSize feature is supported on the device • false - The PGRegSize feature is not supported on the device Description This function identifies whether the PGRegSize feature is available on the System Bus module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGRegionSizeSet • PLIB_SB_PGRegionSizeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGRegSize( SB_MODULE_ID index ) Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1788 PLIB_SB_ExistsPGRegWrPerm Function Identifies whether the PGRegWrPerm feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGRegWrPerm(SB_MODULE_ID index); Returns • true - The PGRegWrPerm feature is supported on the device • false - The PGRegWrPerm feature is not supported on the device Description This function identifies whether the PGRegWrPerm feature is available on the System Bus module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGRegionWritePermSet • PLIB_SB_PGRegionWritePermClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGRegWrPerm( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrClear Function Identifies whether the PGVErrClear feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGVErrClear(SB_MODULE_ID index); Returns • true - The PGVErrClear feature is supported on the device • false - The PGVErrClear feature is not supported on the device Description This function identifies whether the PGVErrClear feature is available on the System Bus module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorMulti • PLIB_SB_PGVErrorCode • PLIB_SB_PGVErrorLogClearSingle • PLIB_SB_PGVErrorLogClearMulti Remarks None. Preconditions None. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1789 Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrClear( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrClrMulti Function Identifies whether the PGVErrClrMulti feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGVErrClrMulti(SB_MODULE_ID index); Returns • true - The PGVErrClrMulti feature is supported on the device • false - The PGVErrClrMulti feature is not supported on the device Description This function identifies whether the PGVErrClrMulti feature is available on the System Bus module. When this function returns true, this function is supported on the device: • PLIB_SB_PGVErrorClearMulti Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrClrMulti( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrClrSingle Function Identifies whether the PGVErrClrSingle feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGVErrClrSingle(SB_MODULE_ID index); Returns • true - The PGVErrClrSingle feature is supported on the device • false - The PGVErrClrSingle feature is not supported on the device Description This function identifies whether the PGVErrClrSingle feature is available on the System Bus module. When this function returns true, this function is supported on the device: • PLIB_SB_PGVErrorClearSingle Remarks None. Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1790 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrClrSingle( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrCmdCode Function Identifies whether the PGVErrCmdCode feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGVErrCmdCode(SB_MODULE_ID index); Returns • true - The PGVErrCmdCode feature is supported on the device • false - The PGVErrCmdCode feature is not supported on the device Description This function identifies whether the PGVErrCmdCode feature is available on the System Bus module. When this function returns true, this function is supported on the device: • PLIB_SB_PGVErrorCommandCode Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrCmdCode( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrInitID Function Identifies whether the PGVErrInitID feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGVErrInitID(SB_MODULE_ID index); Returns • true - The PGVErrInitID feature is supported on the device • false - The PGVErrInitID feature is not supported on the device Description This function identifies whether the PGVErrInitID feature is available on the System Bus module. When this function returns true, this function is supported on the device: • PLIB_SB_PGVErrorInitiatorID Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1791 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrInitID( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrPG Function Identifies whether the PGVErrPG feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGVErrPG(SB_MODULE_ID index); Returns • true - The PGVErrPG feature is supported on the device • false - The PGVErrPG feature is not supported on the device Description This function identifies whether the PGVErrPG feature is available on the System Bus module. When this function returns true, this function is supported on the device: • PLIB_SB_PGVErrorPermissionGroup Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrPG( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrRegion Function Identifies whether the PGVErrRegion feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGVErrRegion(SB_MODULE_ID index); Returns • true - The PGVErrRegion feature is supported on the device • false - The PGVErrRegion feature is not supported on the device Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1792 Description This function identifies whether the PGVErrRegion feature is available on the System Bus module. When this function returns true, this function is supported on the device: • PLIB_SB_PGVErrorRegion Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrRegion( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrRptPri Function Identifies whether the PGVErrRptPri feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGVErrRptPri(SB_MODULE_ID index); Returns • true - The PGVErrRptPri feature is supported on the device • false - The PGVErrRptPri feature is not supported on the device Description This function identifies whether the PGVErrRptPri feature is available on the System Bus module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorReportPrimaryEnable • PLIB_SB_PGVErrorReportPrimaryDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrRptPri( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrStatus Function Identifies whether the PGVErrStatus feature exists on the System Bus module. File plib_sb.h C bool PLIB_SB_ExistsPGVErrStatus(SB_MODULE_ID index); Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1793 Returns • true - The PGVErrStatus feature is supported on the device • false - The PGVErrStatus feature is not supported on the device Description This function identifies whether the PGVErrStatus feature is available on the System Bus module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrStatus( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrGroup0Status Function Identifies whether the PGVErrGroup0Status feature exists on the SB module File plib_sb.h C bool PLIB_SB_ExistsPGVErrGroup0Status(SB_MODULE_ID index); Returns • true - The PGVErrGroup0Status feature is supported on the device • false - The PGVErrGroup0Status feature is not supported on the device Description This function identifies whether the PGVErrGroup0Status feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrGroup0Status Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrGroup0Status( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrGroup1Status Function Identifies whether the PGVErrGroup1Status feature exists on the SB module File plib_sb.h Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1794 C bool PLIB_SB_ExistsPGVErrGroup1Status(SB_MODULE_ID index); Returns • true - The PGVErrGroup1Status feature is supported on the device • false - The PGVErrGroup1Status feature is not supported on the device Description This function identifies whether the PGVErrGroup1Status feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrGroup1Status Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrGroup1Status( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrGroup2Status Function Identifies whether the PGVErrGroup2Status feature exists on the SB module File plib_sb.h C bool PLIB_SB_ExistsPGVErrGroup2Status(SB_MODULE_ID index); Returns • true - The PGVErrGroup2Status feature is supported on the device • false - The PGVErrGroup2Status feature is not supported on the device Description This function identifies whether the PGVErrGroup2Status feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrGroup2Status Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrGroup2Status( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrGroup3Status Function Identifies whether the PGVErrGroup3Status feature exists on the SB module Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1795 File plib_sb.h C bool PLIB_SB_ExistsPGVErrGroup3Status(SB_MODULE_ID index); Returns • true - The PGVErrGroup3Status feature is supported on the device • false - The PGVErrGroup3Status feature is not supported on the device Description This function identifies whether the PGVErrGroup3Status feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrGroup3Status Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrGroup3Status( SB_MODULE_ID index ) PLIB_SB_ExistsPGVErrGroupStatus Function Identifies whether the PGVErrGroupStatus feature exists on the SB module File plib_sb.h C bool PLIB_SB_ExistsPGVErrGroupStatus(SB_MODULE_ID index); Returns • true - The PGVErrGroupStatus feature is supported on the device • false - The PGVErrGroupStatus feature is not supported on the device Description This function identifies whether the PGVErrGroupStatus feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrGroupStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SB_ExistsPGVErrGroupStatus( SB_MODULE_ID index ) Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1796 e) Data Types and Constants PLIB_SB_ARB_POLICY Enumeration This enumeration lists the possible arbitration policies that can be assigned to the CPU and DMA for SRAM access. File help_plib_sb.h C typedef enum { PRIORITY_LRS, PRIORITY_HI } PLIB_SB_ARB_POLICY; Members Members Description PRIORITY_LRS Least Recently Serviced Arbitration PRIORITY_HI High Priority Description System Bus Arbitration Policy This enumeration lists the possible arbitration policies that can be assigned to the CPU and DMA for SRAM access. PLIB_SB_ERROR Enumeration Lists the possible System Bus Transaction Error Codes. File help_plib_sb.h C typedef enum { PLIB_SB_ERROR_NONE, PLIB_SB_ERROR_PGV } PLIB_SB_ERROR; Members Members Description PLIB_SB_ERROR_NONE No Error PLIB_SB_ERROR_PGV Permission Group Violation Description PG Error Code This enumeration lists the possible transaction error codes for the System Bus. PLIB_SB_INIT_ID Enumeration Lists the possible System Bus Initiator IDs. File help_plib_sb.h C typedef enum { PLIB_SB_INIT_ID_NONE, PLIB_SB_INIT_ID_CPU_LRS, PLIB_SB_INIT_ID_CPU_HI, PLIB_SB_INIT_ID_DMA1_RD_LRS, PLIB_SB_INIT_ID_DMA1_RD_HI, Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1797 PLIB_SB_INIT_ID_DMA1_WR_LRS, PLIB_SB_INIT_ID_DMA1_WR_HI, PLIB_SB_INIT_ID_USB1, PLIB_SB_INIT_ID_ETH1_RD, PLIB_SB_INIT_ID_ETH1_WR, PLIB_SB_INIT_ID_CAN1, PLIB_SB_INIT_ID_CAN2, PLIB_SB_INIT_ID_SQI1, PLIB_SB_INIT_ID_FLASH_CTL, PLIB_SB_INIT_ID_CRYPTO } PLIB_SB_INIT_ID; Description System Bus Initiator ID This enumeration lists the possible System Bus Initiator IDs. This ID is used for self-reporting and error logging. LRS and HI are System Bus arbitration schemes set by the soft configuration register CFGCON. PLIB_SB_INIT_PG Enumeration Lists the possible Initiator permission groups File help_plib_sb.h C typedef enum { PLIB_SB_INIT_PG_0, PLIB_SB_INIT_PG_1, PLIB_SB_INIT_PG_2, PLIB_SB_INIT_PG_3 } PLIB_SB_INIT_PG; Members Members Description PLIB_SB_INIT_PG_0 Privilege Group 0 PLIB_SB_INIT_PG_1 Privilege Group 1 PLIB_SB_INIT_PG_2 Privilege Group 2 PLIB_SB_INIT_PG_3 Privilege Group 3 Description System Bus Initiator Permission Groups This enumeration lists the possible initiator permission groups for the System Bus. Remarks These values are used to program the CFGPG soft configuration register, which is not part of the System Bus. This should be done by the boot code to set up the desired initiator permissions prior to programming the System Bus. PLIB_SB_OCP_CMD_CODE Enumeration Lists the possible OCP Command codes. File help_plib_sb.h C typedef enum { PLIB_SB_OCP_CMD_IDLE, PLIB_SB_OCP_CMD_WRITE, PLIB_SB_OCP_CMD_READ, PLIB_SB_OCP_CMD_READEX, PLIB_SB_OCP_CMD_WRITE_NON_POST, PLIB_SB_OCP_CMD_BROADCAST } PLIB_SB_OCP_CMD_CODE; Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1798 Description OCP Command Codes This enumeration lists the possible OCP command codes. An OCP command code is logged when a transaction violation occurs. The command code of the offending command can then be read. PLIB_SB_PG_INITIATOR Enumeration Lists the possible permission group Initiators. File help_plib_sb.h C typedef enum { PLIB_SB_PG_INITIATOR_CPU, PLIB_SB_PG_INITIATOR_DMA1, PLIB_SB_PG_INITIATOR_USB1, PLIB_SB_PG_INITIATOR_CAN1, PLIB_SB_PG_INITIATOR_CAN2, PLIB_SB_PG_INITIATOR_ETH1, PLIB_SB_PG_INITIATOR_SQI1, PLIB_SB_PG_INITIATOR_FLASH_CTL, PLIB_SB_PG_INITIATOR_CRYPTO } PLIB_SB_PG_INITIATOR; Description System Bus Initiators This enumeration lists the possible permission group Initiators. PLIB_SB_REGION_PG Enumeration This enumeration lists the possible permission groups assigned to a region for read and/or write access. File help_plib_sb.h C typedef enum { REGION_PG_0, REGION_PG_1, REGION_PG_2, REGION_PG_3 } PLIB_SB_REGION_PG; Members Members Description REGION_PG_0 Privilege Group 0 has read/write permission REGION_PG_1 Privilege Group 1 has read/write permission REGION_PG_2 Privilege Group 2 has read/write permission REGION_PG_3 Privilege Group 3 has read/write permission Description System Bus Region Permission Groups Lists the possible permission groups assigned to a region for read and/or write access. PLIB_SB_TGT_ID Enumeration Lists the possible System Bus Target IDs. File help_plib_sb.h Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1799 C typedef enum { PLIB_SB_TGT_ID_T0, PLIB_SB_TGT_ID_T1, PLIB_SB_TGT_ID_T2, PLIB_SB_TGT_ID_T3, PLIB_SB_TGT_ID_T4, PLIB_SB_TGT_ID_T5, PLIB_SB_TGT_ID_T6, PLIB_SB_TGT_ID_T7, PLIB_SB_TGT_ID_T8, PLIB_SB_TGT_ID_T9, PLIB_SB_TGT_ID_T10, PLIB_SB_TGT_ID_T11, PLIB_SB_TGT_ID_T12, PLIB_SB_TGT_ID_T13 } PLIB_SB_TGT_ID; Members Members Description PLIB_SB_TGT_ID_T0 System Bus PLIB_SB_TGT_ID_T1 Prefetch Module PLIB_SB_TGT_ID_T2 Data RAM 1 PLIB_SB_TGT_ID_T3 Data RAM 2 PLIB_SB_TGT_ID_T4 External Bus Interface PLIB_SB_TGT_ID_T5 Peripheral Bus 1 PLIB_SB_TGT_ID_T6 Peripheral Bus 2 PLIB_SB_TGT_ID_T7 Peripheral Bus 3 PLIB_SB_TGT_ID_T8 Peripheral Bus 4 PLIB_SB_TGT_ID_T9 Peripheral Bus 5 PLIB_SB_TGT_ID_T10 USB PLIB_SB_TGT_ID_T11 Serial Quad Interface PLIB_SB_TGT_ID_T12 Crypto PLIB_SB_TGT_ID_T13 Random Number Generator Description System Bus Target ID This enumeration lists the possible System Bus Target IDs. PLIB_SB_TGT_REGION Enumeration Lists the programmable target regions. File help_plib_sb.h C typedef enum { PLIB_SB_T0_REGION_0, PLIB_SB_T0_REGION_1, PLIB_SB_T1_REGION_0, PLIB_SB_T1_REGION_1, PLIB_SB_T1_REGION_2, PLIB_SB_T1_REGION_3, PLIB_SB_T1_REGION_4, PLIB_SB_T1_REGION_5, PLIB_SB_T1_REGION_6, PLIB_SB_T1_REGION_7, PLIB_SB_T1_REGION_8, PLIB_SB_T2_REGION_0, PLIB_SB_T2_REGION_1, PLIB_SB_T2_REGION_2, PLIB_SB_T3_REGION_0, PLIB_SB_T3_REGION_1, PLIB_SB_T3_REGION_2, Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1800 PLIB_SB_T4_REGION_0 , PLIB_SB_T4_REGION_1 , PLIB_SB_T4_REGION_2 , PLIB_SB_T5_REGION_0 , PLIB_SB_T5_REGION_1 , PLIB_SB_T5_REGION_2 , PLIB_SB_T6_REGION_0 , PLIB_SB_T6_REGION_1 , PLIB_SB_T7_REGION_0 , PLIB_SB_T7_REGION_1 , PLIB_SB_T8_REGION_0 , PLIB_SB_T8_REGION_1 , PLIB_SB_T9_REGION_0 , PLIB_SB_T9_REGION_1 , PLIB_SB_T10_REGION_0 , PLIB_SB_T11_REGION_0 , PLIB_SB_T11_REGION_1 , PLIB_SB_T12_REGION_0 , PLIB_SB_T13_REGION_0 } PLIB_SB_TGT_REGION; Members Members Description PLIB_SB_T0_REGION_0 System Bus Region 0 PLIB_SB_T0_REGION_1 System Bus Region 1 PLIB_SB_T1_REGION_0 Prefetch Module Region 0 PLIB_SB_T1_REGION_1 Prefetch Module Region 1 PLIB_SB_T1_REGION_2 Prefetch Module Region 2 PLIB_SB_T1_REGION_3 Prefetch Module Region 3 PLIB_SB_T1_REGION_4 Prefetch Module Region 4 PLIB_SB_T1_REGION_5 Prefetch Module Region 5 PLIB_SB_T1_REGION_6 Prefetch Module Region 6 PLIB_SB_T1_REGION_7 Prefetch Module Region 7 PLIB_SB_T1_REGION_8 Prefetch Module Region 8 PLIB_SB_T2_REGION_0 Data RAM 1 Region 0 PLIB_SB_T2_REGION_1 Data RAM 1 Region 1 PLIB_SB_T2_REGION_2 Data RAM 1 Region 2 PLIB_SB_T3_REGION_0 Data RAM 2 Region 0 PLIB_SB_T3_REGION_1 Data RAM 2 Region 1 PLIB_SB_T3_REGION_2 Data RAM 2 Region 2 PLIB_SB_T4_REGION_0 External Bus Interface Region 0 PLIB_SB_T4_REGION_1 External Bus Interface Region 1 PLIB_SB_T4_REGION_2 External Bus Interface Region 2 PLIB_SB_T5_REGION_0 Peripheral Bus 1 Region 0 PLIB_SB_T5_REGION_1 Peripheral Bus 1 Region 1 PLIB_SB_T5_REGION_2 Peripheral Bus 1 Region 2 PLIB_SB_T6_REGION_0 Peripheral Bus 2 Region 0 PLIB_SB_T6_REGION_1 Peripheral Bus 2 Region 1 PLIB_SB_T7_REGION_0 Peripheral Bus 3 Region 0 PLIB_SB_T7_REGION_1 Peripheral Bus 3 Region 1 PLIB_SB_T8_REGION_0 Peripheral Bus 4 Region 0 PLIB_SB_T8_REGION_1 Peripheral Bus 4 Region 1 PLIB_SB_T9_REGION_0 Peripheral Bus 5 Region 0 PLIB_SB_T9_REGION_1 Peripheral Bus 5 Region 1 PLIB_SB_T10_REGION_0 USB Region 0 PLIB_SB_T11_REGION_0 Serial Quad Interface Region 0 PLIB_SB_T11_REGION_1 Serial Quad Interface Region 1 PLIB_SB_T12_REGION_0 Crypto Region 9 PLIB_SB_T13_REGION_0 Random Number Generator 0 Peripheral Libraries Help System Bus Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1801 Description Regions This enumeration lists the programmable System Bus target regions. SB_MODULE_ID Enumeration Lists the possible Module IDs for the System Bus. File help_plib_sb.h C typedef enum { SB_ID_1, SB_NUMBER_OF_MODULES } SB_MODULE_ID; Description Module ID This enumeration lists the possible Module IDs for the System Bus. Remarks Refer to the data sheet to get the correct number of modules defined for the desired device. Files Files Name Description plib_sb.h Defines the System Bus Peripheral Library interface help_plib_sb.h This file is used for documentation purposes Description This section lists the source and header files used by the library. plib_sb.h Defines the System Bus Peripheral Library interface Functions Name Description PLIB_SB_CPUPrioritySet Sets the CPU arbitration policy to SRAM when servicing an interrupt PLIB_SB_DMAPrioritySet Sets the DMA arbitration policy PLIB_SB_ExistsCPUPriority Identifies whether the CPUPriority feature exists on the System Bus module. PLIB_SB_ExistsDMAPriority Identifies whether the DMAPriority feature exists on the System Bus module. PLIB_SB_ExistsInitPermGrp Identifies whether the InitPermGrp feature exists on the System Bus module. PLIB_SB_ExistsPGRegAddr Identifies whether the PGRegAddr feature exists on the System Bus module. PLIB_SB_ExistsPGRegRdPerm Identifies whether the PGRegRdPerm feature exists on the System Bus module. PLIB_SB_ExistsPGRegSize Identifies whether the PGRegSize feature exists on the System Bus module. PLIB_SB_ExistsPGRegWrPerm Identifies whether the PGRegWrPerm feature exists on the System Bus module. PLIB_SB_ExistsPGVErrClear Identifies whether the PGVErrClear feature exists on the System Bus module. PLIB_SB_ExistsPGVErrClrMulti Identifies whether the PGVErrClrMulti feature exists on the System Bus module. PLIB_SB_ExistsPGVErrClrSingle Identifies whether the PGVErrClrSingle feature exists on the System Bus module. PLIB_SB_ExistsPGVErrCmdCode Identifies whether the PGVErrCmdCode feature exists on the System Bus module. PLIB_SB_ExistsPGVErrGroup0Status Identifies whether the PGVErrGroup0Status feature exists on the SB module PLIB_SB_ExistsPGVErrGroup1Status Identifies whether the PGVErrGroup1Status feature exists on the SB module PLIB_SB_ExistsPGVErrGroup2Status Identifies whether the PGVErrGroup2Status feature exists on the SB module PLIB_SB_ExistsPGVErrGroup3Status Identifies whether the PGVErrGroup3Status feature exists on the SB module Peripheral Libraries Help System Bus Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1802 PLIB_SB_ExistsPGVErrGroupStatus Identifies whether the PGVErrGroupStatus feature exists on the SB module PLIB_SB_ExistsPGVErrInitID Identifies whether the PGVErrInitID feature exists on the System Bus module. PLIB_SB_ExistsPGVErrPG Identifies whether the PGVErrPG feature exists on the System Bus module. PLIB_SB_ExistsPGVErrRegion Identifies whether the PGVErrRegion feature exists on the System Bus module. PLIB_SB_ExistsPGVErrRptPri Identifies whether the PGVErrRptPri feature exists on the System Bus module. PLIB_SB_ExistsPGVErrStatus Identifies whether the PGVErrStatus feature exists on the System Bus module. PLIB_SB_InitPermGrpSet Sets the read/write permission group(s) for an initiator. The region must also allow read/write access for the permission group for a read/write to occur. PLIB_SB_PGRegionAddrGet Returns the base address for a permission group region within a target's physical address space. PLIB_SB_PGRegionAddrSet Sets the base address for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionReadPermClear Clears the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionReadPermSet Sets the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionSizeGet Returns the size for a permission group region within a target's physical address space. PLIB_SB_PGRegionSizeSet Sets the size for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionWritePermClear Clears the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionWritePermSet Sets the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGVErrGroup0Status Identifies whether a permission group violation has been reported for the Target Group 0. PLIB_SB_PGVErrGroup1Status Identifies whether a permission group violation has been reported for the Target Group 1. PLIB_SB_PGVErrGroup2Status Identifies whether a permission group violation has been reported for the Target Group 2. PLIB_SB_PGVErrGroup3Status Identifies whether a permission group violation has been reported for the Target Group 3. PLIB_SB_PGVErrGroupStatus Identifies whether a permission group violation has been reported for the specified target group. PLIB_SB_PGVErrorClearMulti Clears multiple permission group errors for the specified target. PLIB_SB_PGVErrorClearSingle Clears a single permission group error for the specified target. PLIB_SB_PGVErrorCode Returns a value corresponding to the type of error logged for the specified target. PLIB_SB_PGVErrorCommandCode Returns the OCP command code of the transaction that caused the protection violation for the specified target. PLIB_SB_PGVErrorInitiatorID Returns the ID of the Initiator that caused the protection violation PLIB_SB_PGVErrorLogClearMulti Clears a multiple protection group violations error from the specified target error log register. PLIB_SB_PGVErrorLogClearSingle Clears a single protection group violation error from the specified target error log register. PLIB_SB_PGVErrorMulti Indicates if more than one permission group violation has occurred since last cleared. PLIB_SB_PGVErrorPermissionGroup Returns the permission group of the protection region in a target address space that caused the protection violation for the specified target. PLIB_SB_PGVErrorRegion Returns the number of the protection region in the specified target address space that caused the protection violation. PLIB_SB_PGVErrorReportPrimaryDisable Disables primary permission group error reporting for the specified target to the SB flag register. PLIB_SB_PGVErrorReportPrimaryEnable Enables primary permission group error reporting for the specified target to the SB flag register. PLIB_SB_PGVErrorStatus Identifies whether a permission group violation has been reported for the specified target. Description System Bus Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the System Bus Peripheral Libraries Help System Bus Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1803 Peripheral Library for Microchip microcontrollers. The definitions in this file are for the System Bus controller module. File Name plib_sb.h Company Microchip Technology Inc. help_plib_sb.h Enumerations Name Description PLIB_SB_ARB_POLICY This enumeration lists the possible arbitration policies that can be assigned to the CPU and DMA for SRAM access. PLIB_SB_ERROR Lists the possible System Bus Transaction Error Codes. PLIB_SB_INIT_ID Lists the possible System Bus Initiator IDs. PLIB_SB_INIT_PG Lists the possible Initiator permission groups PLIB_SB_OCP_CMD_CODE Lists the possible OCP Command codes. PLIB_SB_PG_INITIATOR Lists the possible permission group Initiators. PLIB_SB_REGION_PG This enumeration lists the possible permission groups assigned to a region for read and/or write access. PLIB_SB_TGT_ID Lists the possible System Bus Target IDs. PLIB_SB_TGT_REGION Lists the programmable target regions. SB_MODULE_ID Lists the possible Module IDs for the System Bus. Description This file is used for documentation purposes Peripheral Libraries Help System Bus Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1804 SPI Peripheral Library This section describes the Serial Peripheral Interface (SPI) Peripheral Library. Introduction This library provides a low-level abstraction of the Serial Peripheral Interface (SPI) module that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The Serial Peripheral Interface (SPI) module is a synchronous serial interface useful for communicating with other peripherals or microcontroller device. These peripheral devices may be serial EEPROMs, shift registers, display drivers, analog-to-digital converters, etc. SPI is a synchronous serial data link operating at full duplex Master/slave relationship. Two data lines: • MOSI – Master Data Output, Slave Data Input • MISO – Master Data Input, Slave Data Output Two control lines: • SCLK – Clock • /SS – Slave Select (no addressing) Devices communicate in Master/Slave mode where the master device initiates the data frame. Multiple slave devices are allowed with individual slave select (Chip Select) lines. The SPI is sometimes referred to as a "four-wire" serial bus, contrasting with three-, two-, and one-wire serial buses. Using the Library This topic describes the basic architecture of the SPI Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_spi.h The interface to the SPI Peripheral Library is defined in the plib_spi.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the SPI Peripheral library must include peripheral.h. Library File: The SPI Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Hardware Abstraction Model This library provides a low-level abstraction of the SPI module on the Microchip family microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The SPI Peripheral Library provides interface routines to interact with the blocks shown in the following diagram. Hardware Abstraction Model Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1805 The Serial Peripheral Interface (API) module is a synchronous serial interface useful for communicating with external peripherals and other microcontroller devices. The SPI bus specifies four logic signals: • SCLK: serial clock (output from master) • MOSI: master output, slave input (output from master) • MISO: master input, slave output (output from slave) • /SS: slave select (active low, output from master); on certain devices, this pin is implemented using general purpose I/O (GPIO) The SPI bus can operate with a single master device and with one or more slave devices. To begin a communication, the master first configures the clock, using a frequency less than or equal to the maximum frequency the slave device supports. In addition to setting the clock frequency, the master must also configure the clock polarity and phase with respect to the data. The master then transmits the appropriate chip select bit for the desired chip to a logic '0'. A logic '0' is transmitted because the Chip Select line (/SS) is active low, meaning its off state is a logic '1'; the on state is asserted with a logic 0. The master issues the clock cycles. During each SPI clock cycle, a full duplex data transmission occurs: • The master sends a bit on the MOSI line; the slave reads it from that same line • The slave sends a bit on the MISO line; the master reads it from that same line Transmissions may involve any number of clock cycles. When there are no more data to be transmitted, the master stops toggling its clock. Normally, it then deselects the slave. The Baud Rate Generator/Prescaler controls the timing, the desired baud rate can be programmed in the baud rate controller. In the Master mode, the clock becomes the serial clock and is provided to external devices via the SCK pin (the clock can be prescaled by the primary prescaler and the secondary prescaler if device supports). The Buffers are for data transmitted or received by the SPI module over the MISO and MOSI line synchronized with the SCK line by the clock control logic. The Status and Control logic, provide the capability to control different ways of enabling or disabling the master and slave. It also can provides status about the transmitter and receiver. Active-Low Slave Select or Frame Synchronization I/O Pulse allows for a Synchronous Slave mode. The SPI module supports the following four SPI modes. • Standard Mode: In this mode of operation, data can be thought of as taking a direct path between the Most Significant bit (MSb) of one module’s shift register and the Least Significant bit (LSb) of the other, and then into the appropriate Transmit or Receive Buffer. The master provides the serial clock and synchronization signals required to the slave device. • Enhanced Buffer Mode: The operation of this mode is very similar to that of Standard mode. The difference is that data can be thought of as moving from the Shift register to a receive FIFO buffer and moving from the transmit FIFO buffer to the Shift register. • Framed Mode: In this mode of operation, the Frame Master controls the generation of the frame synchronization pulse and provides this pulse to other devices at the Slave Select (/SS) pin. The SPI clock is generated by the SPI Master and is continuously running. The SPI slave module uses a frame synchronization pulse received at the SS pin. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1806 • Audio Protocol Mode: The SPI module provides support to the audio protocol modes; with this mode, the SPI module can be interfaced to most codec devices available today to provide PIC microcontroller-based audio solution Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the SPI module. Library Interface Section Description General Configuration and Status Functions This section provides a set of functions and data types for configuring the SPI and to read the status of the SPI. Data Transfer Functions This section provides a set of functions and data types for Reading and Writing the SPI buffer values. Transmitter Functions This section provides a set of functions for transmitter. Receiver Functions This section provides a set of functions for receiver. Framed Mode Functions Provides control, status, and data transfer routines for Framed SPI mode. Audio Mode Functions Provides control, status routines to support audio protocol functionality. Feature Existence Functions Provides functions that determine whether certain features exist on a device. Note: Not all modes are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. How the Library Works Provides information on how the library works. Description The SPI module has the following operating modes: • Standard SPI • Enhanced Buffer SPI • Framed SPI • Audio Protocol Interface Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. The following diagram shows the general architecture of the SPI Peripheral Library. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1807 State Machine This state machine is provided to give a general idea of the usage model of the peripheral library. Refer to the usage model for more detailed steps for the scenario that is being used. Description SPI State Machine The following state machine diagrams shows the transmission and reception during normal operation. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1808 SPI Routines State Associated Function Setup and Initialization Initialize the SPI by setting prescaler/baud rate generator, interrupt modes. Enable Master Once the SPI has been appropriately set up and initialized, the state machine enables Master mode (PLIB_SPI_MasterEnable). Select Slave Select slave by pulling the /SSx pin low to transmit the data. Write Data To Transfer Write data to the buffer to transmit using PLIB_SPI_BufferWrite. Wait for Transmit Buffer to Clear Buffer Data will be transmitted to transmit buffer and transmit buffer flag will be full. The state machine waits for transmit buffer to clear. Check for status by calling PLIB_SPI_TransmitBufferIsFull. Wait for Receive Buffer Full to Set Slave sends received data back to master. Upon data received receive buffer flag will set. The state machine waits for Receive buffer to clear. Check for status by calling PLIB_SPI_ReceiverBufferIsFull. Read Buffer Read the buffer using PLIB_SPI_BufferRead. Enable Slave Select Enable slave select by calling PLIB_SPI_PinEnable. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Standard SPI Mode In Standard (legacy) Master and Slave modes, data can be thought of as taking a direct path between the Most Significant bit (MSb) of one module’s shift register and the Least Significant bit (LSb) of the other, and then into the appropriate Transmit or Receive buffer. The module configured as the master module provides the serial clock and synchronization signals (as required) to the slave device. Standard Master Mode In Standard Master mode, the input clock is used as the serial clock. The serial clock is output via the SCK pin to slave devices. Clock pulses are only generated when there is data to be transmitted. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1809 Description Setup 1. Select on which edge of the clock data transmission occurs, using PLIB_SPI_OutputDataPhaseSelect and PLIB_SPI_ClockPolaritySelect. 2. Set SPI baud rate using PLIB_SPI_BaudRateSet. 3. If the module needs to operate as a Master, use PLIB_SPI_MasterEnable. Example: Standard Master Mode Communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_SLAVE_SELECT|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. 1. Data to be transmitted is written to the SPI buffer (PLIB_SPI_BufferWrite). 2. When contents of buffer are moved to the shift register, the SPI transmit buffer full flag is cleared (this can be verified using PLIB_SPI_TransmitBufferIsFull). 3. A series of 8/16/32 clock pulses shifts out 8/16/32 bits of transmit data from the shift register to the data out (SDO) pin and simultaneously shifts in the data at the data in (SDI) pin into the shift register. 4. When the transfer is complete, the following events occur: • The SPI interrupt flag is set. Interrupts will occur if SPI interrupts are enabled. The SPI interrupt flag is not cleared automatically by the hardware. • Also, when the ongoing transmit and receive operation is completed, the contents of the shift register are moved to the SPI receive register. • The SPI receive buffer full flag (PLIB_SPI_ReceiverBufferIsFull) is set by the module, indicating that the receive buffer is full. Once the SPI buffer is read by the user application using PLIB_SPI_BufferRead, the hardware clears the SPI receive buffer full flag. 5. If the SPI receive buffer full flag is set when the SPI module needs to transfer data from SPI shift register to SPI receive buffer, the module will set the SPI receive overflow flag (PLIB_SPI_ReceiverHasOverflowed), indicating an overflow condition. 6. Data to be transmitted can be written to SPI buffer (PLIB_SPI_BufferWrite) by the user software at any time as long as the SPI Transmit buffer full flag is clear (PLIB_SPI_TransmitBufferIsFull). The write can occur while SPI shift register is shifting out the previously written data, allowing continuous transmission. Example: Standard Master Mode Communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // Either Poll for Receiver buffer to be full using // PLIB_SPI_ReceiverBufferIsFull or wait for the interrupt Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1810 // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Standard Slave Mode Describes Standard Slave mode. Description Slave Select Synchronization The Slave Select pin (/SS) allows for Synchronous Slave mode. If the slave select is enabled (PLIB_SPI_PinEnable), transmission and reception are enabled in Slave mode only if the /SS pin is driven to a low state. The port output or other peripheral outputs must not be driven to allow the /SS pin to function as an input. If the slave select is enabled and the /SS pin is driven high, the data output (SDO) pin is no longer driven and will tri-state even if the module is in the middle of a transmission. An aborted transmission will be retried the next time the /SS pin is driven low, using the data held in the SPI Transmit buffer. If slave select is not enabled, the /SS pin does not affect the module operation in Slave mode. SPI Transmit Buffer Full Status Operation The function of the SPI Transmit buffer full (PLIB_SPI_TransmitBufferIsFull) is different in the Slave mode of operation. If slave select is disabled (PLIB_SPI_PinDisable), the PLIB_SPI_TransmitBufferIsFull returns a '1' when the SPI buffer is loaded by the user application. It is cleared when the module transfers data from SPI transmit buffer to SPI shift register. This is similar to the SPI Transmit buffer full function in Master mode. If slave select is enabled (PLIB_SPI_PinEnable), PLIB_SPI_TransmitBufferIsFull returns a '1' when the SPI buffer is loaded by the user application. However,PLIB_SPI_TransmitBufferIsFull returns zero only when the SPI module completes data transmission. A transmission will be aborted when the Slave Select pin goes high and may be retried at a later time. Each data word is held in SPI transmit buffer until all bits are transmitted to the receiver. Setup In Standard Slave mode, data is transmitted and received as the external clock pulses appear on the SCK pin. The clock polarity and clock edge (PLIB_SPI_ClockPolaritySelect) determine upon which edge of the clock data transmission occurs. Example: Standard Slave Mode Communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH);//clock polarity and edge is subject to change ... PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1811 // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer (PLIB_SPI_BufferWrite/ PLIB_SPI_BufferRead). The remainder of the operation of the module is identical to that of Standard Master mode. Example: Standard Slave Mode Communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back } Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Enhanced Buffer SPI Mode The operation of Enhanced Buffer Master and Slave modes is very similar to Standard Master and Slave modes. The difference is that data can be thought of as moving from the Shift register to a receive FIFO buffer and moving from the transmit FIFO buffer to the Shift register. Enhanced Buffer Master Mode In Enhanced Buffer Master mode (referred to as a FIFO), the input clock used as the serial clock. The serial clock is output via the SCK pin to slave devices. Clock pulses are only generated when there is data to be transmitted. Description Setup 1. Select on which edge of the clock data transmission occurs, using PLIB_SPI_OutputDataPhaseSelect and PLIB_SPI_ClockPolaritySelect. 2. Set SPI baud rate using PLIB_SPI_BaudRateSet. 3. If the module needs to operate as a Master, use PLIB_SPI_MasterEnable. Example: Enhanced Master Mode Communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1812 // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_SLAVE_SELECT|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); PLIB_SPI_FIFOEnable(MY_SPI_ID); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); The CPU loads data to be transmitted into the transmit buffer by writing the SPI buffer (PLIB_SPI_BufferWrite). An SPI transmission begins after the first buffer write. Up to all pending transmissions can be loaded. The number of pending transfers is indicated by the Buffer Element Count bits through PLIB_SPI_FIFOCountGet. In Master mode, this count reflects the number of transfers pending in the transmit buffer. In Slave mode, it reflects the number of unread receptions in the receive buffer. If the Shift register is empty, the first write will immediately load the Shift register, leaving all transmit buffer locations available. After an SPI transfer completes, the receive buffer location is updated with the received data. The CPU accesses the received data by reading the SPI buffer. After each CPU read, the SPI buffer points to the next buffer location. SPI transfers continue until all pending data transfers have completed. Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. 1. Data to be transmitted is written to the SPI buffer (PLIB_SPI_BufferWrite) and is loaded into the next available transmit buffer location. 2. The SPI transmit buffer full flag (PLIB_SPI_TransmitBufferIsFull) and SPI interrupt flag are set after pending transfers are loaded. 3. The current buffer location’s contents are moved to the Shift register. The SPI transmit buffer is cleared by the module if a buffer location is available for a CPU write. 4. A series of 8/16/32 clock pulses shifts out 8/16/32 bits of transmit data from the shift register to the data out (SDO) pin and simultaneously shifts in the data at the data in (SDI) pin into the shift register. 5. When the transfer is complete, the following events occur: • The contents of the SPI shift register are moved into the next available location in the receive buffer. • If the last unread location is written by the SPI module, the SPI receive buffer full flag (PLIB_SPI_ReceiveBufferIsFull) is set, indicating that all buffer locations are full. Enable the SPI interrupts. The SPI interrupt flag is not cleared automatically by the hardware. • Once the SPI buffer is read (PLIB_SPI_BufferRead) by the user application, the hardware clears the SPI receive buffer full flag (PLIB_SPI_ReceiverBufferIsFull) and the SPI Buffer increments to the next unread receive buffer location. SPI buffer reads beyond the last unread location will not increment the buffer location. 6. When PLIB_SPI_ReceiverBufferIsFull is set, if the SPI module needs to transfer one more data from SPI shift register to the buffer, the module will enable the receive overflow flag (PLIB_SPI_ReceiverHasOverflowed) indicating an overflow condition. 7. Data to be transmitted can be written to the SPI buffer (PLIB_SPI_BufferWrite) by the user application at any time as long as the SPI transmit buffer full flag is clear (PLIB_SPI_TransmitBufferIsFull). Up to all pending transfers can be loaded into the buffer allowing continuous transmission. Example: Enhanced Master Mode communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // Either Poll for Receiver buffer to be full using // PLIB_SPI_ReceiverBufferIsFull or wait for the interrupt // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1813 Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Enhanced Buffer Slave Mode Describes Enhanced Buffer Slave mode. Description Slave Select Synchronization The Slave Select pin allows a Synchronous Slave mode. If the slave select enabled (PLIB_SPI_PinEnable), transmission and reception is enabled in Slave mode only if the /SS pin is driven to a low state. The port output or other peripheral outputs must not be driven to allow the /SS pin to function as an input. If the slave select is enabled and the /SS pin is driven high, the SDO pin is no longer driven and will tri-state even if the module is in the middle of a transmission. An aborted transmission will be retried the next time the /SS pin is driven low using the data held in the SPI transmit buffer. If the Slave select is disabled (PLIB_SPI_PinDisable), the /SS pin does not affect the module operation in Slave mode. SPI Transmit Buffer Full Operation The function of the SPI transmit buffer full flag (PLIB_SPI_TransmitBufferIsFull) is different in the Slave mode of operation. If Slave select is disabled (PLIB_SPI_PinDisable), the SPI Transmit Buffer Full flag (PLIB_SPI_TransmitBufferIsFull) is set when the last available buffer location is loaded by the user application. It is cleared when the module transfers data from the buffer to SPI status register and a buffer location is available for a CPU write. This is similar to the SPI transmit buffer in Master mode. If Slave select is enabled (PLIB_SPI_PinEnable), the SPI transmit buffer is set when the last available buffer location is loaded by the user application. However, it is cleared only when the SPI module completes data transmission, leaving a buffer location available for a CPU write. A transmission will be aborted when the /SS pin goes high and may be retried at a later time. Each data word is held in the buffer until all bits are transmitted to the receiver. Setup In Slave mode, data is transmitted and received as the external clock pulses appear on the SCK pin. PLIB_SPI_OutputDataPhaseSelect and PLIB_SPI_ClockPolaritySelect determine upon which edge of the clock data transmission occurs. The rest of the operation of the module is identical to that of Enhanced Buffer Master mode. Example: Enhanced Slave Mode communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_INPUT_SAMPLING_PHASE_AT_END);//clock polarity and edge is subject to change ... PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); PLIB_SPI_FIFOEnable(MY_SPI_ID); // Optional: Enable interrupts. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1814 // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive: Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer (PLIB_SPI_BufferWrite/PLIB_SPI_BufferRead). The remainder of the operation of the module is identical to that of Enhanced Buffer Master mode. Example: Enhanced Slave Mode communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back } Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Framed SPI Modes The SPI module supports a basic framed SPI protocol while operating in either Master or Slave modes. Description The SPI module supports two framed modes of operation. In Frame Master mode, the SPI module generates the frame synchronization pulse and provides this pulse to other devices at the /SS pin. In Frame Slave mode, the SPI module uses a frame synchronization pulse received at the /SS pin. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1815 The framed SPI modes are supported in conjunction with the unframed Master and Slave modes. This makes four framed SPI configurations: • SPI Master mode and Frame Master mode • SPI Master mode and Frame Slave mode • SPI Slave mode and Frame Master mode • SPI Slave mode and Frame Slave mode These modes determine whether or not the SPI module generates the serial clock and the frame synchronization pulse. SPI Master Mode and Frame Master Mode Describes Master/Frame Master mode. Description In Master/Frame Master mode, the SPI module generates both the clock and frame synchronization signals, as shown in the following figure. In this mode, the serial clock is output continuously at the SCK pin, regardless of whether the module is transmitting. When the SPI buffer is written (PLIB_SPI_BufferWrite), the /SS pin will be driven to its active state on the appropriate transmit edge of the SCK clock, and remain active for one data frame. If the PLIB_SPI_FrameSyncPulseEdgeSelect function decides whether sync pulse precedes the data transmission or coincides with the beginning of the data transmission. The module starts transmitting data on the next transmit edge of the SCK. Setup The mode is enabled by calling PLIB_SPI_MasterEnable, PLIB_SPI_FramedCommunicationEnable and PLIB_SPI_FrameSyncPulseDirectionSelect (as output). Example: SPI Master Mode and Frame Master Mode Communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1816 PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_SLAVE_SELECT|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationEnable(MY_SPI_ID); PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_ID, SPI_FRAME_PULSE_DIRECTION_INPUT); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: SPI Master Mode and Frame Master Mode Communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // Either Poll for Receiver buffer to be full using // PLIB_SPI_ReceiverBufferIsFull or wait for the interrupt // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. SPI Master Mode and Frame Slave Mode Describes Master/Frame Slave mode. Description In Master/Frame Slave mode, the module generates the clock signal but uses the slave module’s frame synchronization signal for data transmission, as shown in the following figure. In this mode, the /SS pin is an input and it is sampled on the sample edge of the SPI clock. When it is sampled in its active state, data will be transmitted on the subsequent transmit edge of the SPI clock. The SPI interrupt flag is set when the transmission is complete. The user application must make sure that the correct data is loaded into the SPI buffer for transmission before the signal is received at the /SS pin. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1817 Setup The mode is enabled by calling PLIB_SPI_MasterEnable, PLIB_SPI_FramedCommunicationEnable, and PLIB_SPI_FrameSyncPulseDirectionSelect. Example: SPI Master Mode and Frame Slave Mode Communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_SLAVE_SELECT|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_FrameSyncPulseCounterSelect(MY_SPI_ID,SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER); PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationEnable(MY_SPI_ID); PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_ID,SPI_FRAME_PULSE_DIRECTION_INPUT); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: SPI Master Mode and Frame Slave Mode Communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // Either Poll for Receiver buffer to be full using // PLIB_SPI_ReceiverBufferIsFull or wait for the interrupt // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. SPI Slave Mode and Frame Master Mode Describes Slave/Frame Master mode. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1818 Description In Slave/Frame Master mode, the module acts as the SPI slave and takes its clock from the other SPI module; however, it produces frame synchronization signals to control data transmission, as shown in the following figure. The input SPI clock will be continuous in Slave mode. The /SS pin will be an output when the Frame sync pulse is output. Therefore, when the SPI buffer is written, the module drives the /SS pin to the active state on the appropriate transmit edge of the SPI clock for one SPI clock cycle. Data will start transmitting on the appropriate SPI clock transmit edge. Setup The mode is enabled by calling PLIB_SPI_SlaveEnable, PLIB_SPI_FramedCommunicationEnable, and PLIB_SPI_FrameSyncPulseDirectionSelect. Example: SPI Slave Mode and Frame Master Mode Communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH);//clock polarity and edge is subject to change ... PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_FrameSyncPulseCounterSelect(MY_SPI_ID,SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER); PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationEnable(MY_SPI_ID); PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_ID,SPI_FRAME_PULSE_DIRECTION_INPUT); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: SPI Slave Mode and Frame Master Mode Communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1819 PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back } Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. SPI Slave Mode and Frame Master Mode Describes Slave/Frame Slave mode. Description In Slave/Frame Slave mode, the module obtains both its clock and frame synchronization signal from the master module, as shown in the following figure. In this mode, both the clock and Slave Select pins will be inputs. The /SS pin is sampled on the sample edge of the SPI clock. When /SS is sampled at its active state, data will be transmitted on the appropriate transmit edge of SCK. Setup The mode is enabled by calling PLIB_SPI_SlaveEnable,PLIB_SPI_FramedCommunicationEnable and PLIB_SPI_FrameSyncPulseDirectionSelect (as input). Example: SPI Slave Mode and Frame Slave Mode Communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH);//clock polarity and edge is subject to change ... Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1820 PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_FrameSyncPulseCounterSelect(MY_SPI_ID,SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER); PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationEnable(MY_SPI_ID); PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_ID,SPI_FRAME_PULSE_DIRECTION_INPUT); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: SPI Slave Mode and Frame Slave Mode Communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back } Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Audio Protocol Interface Mode The SPI module can be interfaced to most codec devices available today to provide PIC microcontroller-based audio solutions. Description The SPI module provides support to the audio protocol functionality via four standard I/O pins. The four pins that make up the audio protocol interface modes are: • SDIx: Serial Data Input for receiving sample digital audio data • SDOx: Serial Data Output for transmitting digital audio data • SCKx: Serial Clock (also known as bit clock) • /SSx: Left/Right Channel Clock The SPI module supports four audio protocol modes and can be operated in any one of these modes: Note: Each of the modes can additionally support some or all of the following features. Please refer to the"Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for more information. I2S Mode The Inter-IC Sound (I2S) protocol enables transmission of two channels of digital audio data over a single serial interface. The I2S specification defines a half-duplex interface that supports transmit or receive, but not both at the same time. With both SDO and SDI available, full-duplex Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1821 operation is supported by this peripheral, as shown in the following figure. Data Transmit and Clocking: • The transmitter shifts the audio sample data’s Most Significant bit (MSb) on the first falling edge of SCK after an LRCK transition • The receiver samples the MSB on the second rising edge of SCK • The left channel data shifts out while LRCK is low and right channel data is shifted out while LRCK is high • The data in the left and right channel consists of a single frame To set the module to I2S mode, the following bits must be set: • Set SPI to I2S Mode by calling PLIB_SPI_AudioProtocolModeSelect • Select PLIB_SPI_FrameSyncPulsePolaritySelect (as active low) • Select PLIB_SPI_ClockPolaritySelect (as active low) Setting these bits enables the SDO and LRCK (/SSx) transitions to occur on the falling edge of SCK (BCLK) and sampling of SDI to occur on the rising edge of SCK. Left-Justified Mode The Left-Justified mode is similar to I2S mode; however, in this mode, the SPI shifts the audio data’s MSb on the first SCK edge that is coincident with an LRCK transition. On the receiver side, the SPI module samples the MSb on the next SCK edge. In general, a codec using justified protocols defaults to transmitting data on the rising edge of SCK and receiving data on the falling edge of SCK. To set the module to Left-Justified mode, the following bits must to be set • Set SPI to Left Justified Mode by calling PLIB_SPI_AudioProtocolModeSelect • Select PLIB_SPI_FrameSyncPulsePolaritySelect (as active high) • Select PLIB_SPI_ClockPolaritySelect (as active high) This enables the SDO and LRCK transitions to occur on the rising edge of SCK. Refer to the following sample waveform diagrams for 16-, 24-, and 32-bit audio data transfers. Right-Justified Mode In Right-Justified mode, the SPI module shifts the audio sample data’s MSb after aligning the data to the last clock cycle. The bits preceding the audio sample data can be driven to logic level 0 . To set the module to Right-Justified mode, the following bits must to be set: • Set SPI to Right Justified Mode by calling PLIB_SPI_AudioProtocolModeSelect • Select PLIB_SPI_FrameSyncPulsePolaritySelect (as active high) • Select PLIB_SPI_ClockPolaritySelect (as active high) This enables the SDO and LRCK transitions to occur on the rising edge of SCK after the Least Significant bit (LSb) being aligned to the last clock cycle. Refer to the following sample waveform diagrams for 16-, 24-, and 32-bit audio data transfers. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1822 PCM/DSP Mode This mode modifies the behavior of LRCK and audio data spacing. In PCM/DSP mode, the LRCK can be a single bit wide (i.e., 1 SCK) or as wide as the audio data (16-, 24-, and 32-bits). The audio data is packed in the frame with the left channel data immediately followed by the right channel data. The frame length is still either 32 or 64 clocks when this device is the master. In PCM/DSP mode, the transmitter drives the audio data’s (left channel) MSb on the first or second transmit edge of SCK (after an LRCK transition). Immediately after the (left channel) LSb, the transmitter drives the (right channel) MSb. To set the module to Left-Justified mode, the following bit must to be set: • Set the SPI module to Right-Justified Mode by calling PLIB_SPI_AudioProtocolModeSelect Refer to the following sample waveform for 16-, 24-, and 32-bit audio data transfers. Mono Mode Versus Stereo Mode The SPI module enables the audio data transmission in Mono or Stereo mode by setting PLIB_SPI_AudioTransmitModeSelect. In Stereo mode, the shift register uses each FIFO location once, which gives each channel a unique stream of data for stereo data. In Mono mode, the shift register uses each FIFO location twice, to give each channel the same mono stream of audio data. Master Mode Describes Master mode for the Audio Protocol Interface mode. Description A few characteristics of Master mode are: • This mode enables the device to generate SCK and LRCK pulses as long as the master mode enabled • The SPI module generates LRCK and SCK continuously in all the cases, regardless of the transmit data while in Master mode • The SPI module drives the leading edge of LRCK and SCK within 1 SCK period and the serial data shifts in and out continuously even when the Transmit FIFO is empty Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1823 The following figure shows a typical interface between the master and slave while in Master mode. Setup To configure the device in Audio Protocol Master, enable master mode through PLIB_SPI_MasterEnable and enable audio mode through PLIB_SPI_AudioProtocolEnable. Example: Audio Mode Communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_DATA_IN|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_AudioProtocolModeSelect(MY_SPI_ID,SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED ); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); PLIB_SPI_AudioProtocolEnable(MY_SPI_ID); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: Audio Mode Communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // wait for transfer to complete while(!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)); // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1824 Slave Mode Describes Slave mode for the Audio Protocol Interface mode. Description A few characteristics of Slave mode are: • This mode enables the device to receive SCK and LRCK pulses as long as slave mode is enabled • The SPI module drives zeros out of SDO, but does not shift data out or in (SDI) until the module receives the LRCK (i.e., the edge that precedes the left channel) • Once the module receives the leading edge of LRCK, it starts receiving data if PLIB_SPI_PinEnable (enables data in) is selected and the serial data shifts out continuously even when the TX FIFO is empty The following figure shows the interface between a SPI module in Audio Slave Interface mode to a codec master device. Setup The SPI module can be configured in Audio Protocol Slave mode by setting PLIB_SPI_SlaveEnable and enabling the audio protocol through PLIB_SPI_AudioProtocolEnable. Example: Slave Mode communication Setup #define MY_SPI_ID SPI_ID_1 #define PERIPHERAL_BUS_CLK 80000000 #define SPI_BAUD_RATE 10000000 //Disable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear(MY_SPI_ID); // Configure General SPI Options // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH);//clock polarity and edge is subject to change ... PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_BaudRateSet(MY_SPI_ID,PERIPHERAL_BUS_CLK,SPI_BAUD_RATE); PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_AudioProtocolModeSelect(MY_SPI_ID,SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED ); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); PLIB_SPI_AudioProtocolEnable(MY_SPI_ID); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer (PLIB_SPI_BufferWrite/ PLIB_SPI_BufferRead). Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1825 Example: Slave Mode communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back } Notes: 1. Refer to the "Interrupts" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Other Features This topic describes the additional features available in the SPI Peripheral Library. Communication Mode The SPI module allows three types of data widths when transmitting and receiving data over a SPI bus. The selection of data width determines the minimum length of the SPI data. The user application should select the appropriate data width to maximize its data throughput. To change the mode of operation on the fly, the SPI module must be idle. If the SPI module is switched off, the new mode will be available when the module is switched on again. The macro, PLIB_SPI_CommunicationWidthSet, allows the module to communicate in either 8-/16-/32-bit modes. The functionality will be the same for each mode, except for the number of bits that are received and transmitted. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Power-Saving Modes Note: Each of the following modes can additionally support some or all of the following features. Please refer to the "Power-Saving Modes" section of the specific device data sheet or the family reference manual section specified in that chapter for more information. Sleep Mode When the device enters Sleep mode, the device clock source and the entire device is shut down. The consequences of entering Sleep depend upon which mode (Master or Slave) the module is configured in at the time that Sleep mode is invoked. Idle Mode When the device enters Idle mode, the device clock is operational, but the CPU and selected peripherals are shut down. The SPI module can continue to operate in Idle mode by calling PLIB_SPI_StopInIdleDisable, or can stop operation in Idle mode by calling PLIB_SPI_StopInIdleEnable. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet to determine availability. Peripheral Libraries Help SPI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1826 SPI Receive-only Operation Calling PLIB_SPI_PinDisable (data in pin) disables the transmission at the SDO pin. This allows the SPI module to be configured for a receive-only mode of operation. This function is applicable to all SPI operating modes. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. SPI Error Handling If a new data word has been shifted and the previous buffer contents have not been read, the status can be read by calling PLIB_SPI_ReceiverHasOverflowed. Any received data is not transferred, and further data reception is disabled until the buffer is cleared by calling PLIB_SPI_ReceiverOverflowClear. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. SPI Master Mode Clock Frequency In Master mode, the PBCLK is divided and then used as the serial clock. The division is based on the settings in the SPIxBRG register. The serial clock is output via the SCKx pin to slave devices. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Interrupts The SPI module has the ability to generate interrupts reflecting the events that occur during the data communication. Interrupts can be enabled or disabled using PLIB_SPI_ErrorInterruptEnable/PLIB_SPI_ErrorInterruptDisable. The following types of interrupts can be generated: • Receive data available interrupts are signalled by SPI receive and transmit flag. This event occurs when there is new data assembled in the SPI receive buffer. • Transmit buffer empty interrupts are signalled by SPI receive and transmit flag. This event occurs when there is space available in the SPI transmit buffer and new data can be written. • Error interrupts are signalled by SPI receive and transmit flag. This event occurs when there is an overflow condition for the receive buffer when there is an underrun of the transmit buffer, or when a frame error event occurs. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Configuring the Library The library is configured for the supported SPI modules when the processor is chosen in the MPLAB X IDE. Library Interface a) General Configuration and Status Functions Name Description PLIB_SPI_BaudRateClockSelect Selects the type of clock is used by the Baud Rate Generator. PLIB_SPI_BaudRateSet Sets the baud rate to the desired value. PLIB_SPI_ClockPolaritySelect Enables clock polarity. PLIB_SPI_CommunicationWidthSelect Selects the data width for the SPI communication. PLIB_SPI_Disable Disables the SPI module. PLIB_SPI_Enable Enables the SPI module. PLIB_SPI_ErrorInterruptDisable Enables SPI error interrupts. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1827 PLIB_SPI_ErrorInterruptEnable Enables SPI error interrupts PLIB_SPI_FIFOCountGet Reads the SPI Buffer Element Count bits for either receive or transmit. PLIB_SPI_FIFODisable Disables the SPI enhanced buffer. PLIB_SPI_FIFOEnable Enables the SPI enhanced buffer. PLIB_SPI_FIFOInterruptModeSelect Selects the SPI buffer interrupt mode. PLIB_SPI_FIFOShiftRegisterIsEmpty Returns the current status of the SPI shift register. PLIB_SPI_InputSamplePhaseSelect Selects the SPI data input sample phase. PLIB_SPI_IsBusy Returns the current SPI module activity status. PLIB_SPI_MasterEnable Enables the SPI in Master mode. PLIB_SPI_OutputDataPhaseSelect Selects serial output data change. PLIB_SPI_PinDisable Enables the selected SPI pins. PLIB_SPI_PinEnable Enables the selected SPI pins. PLIB_SPI_ReadDataIsSignExtended Returns the current status of the receive (RX) FIFO sign-extended data. PLIB_SPI_SlaveEnable Enables the SPI in Slave mode. PLIB_SPI_SlaveSelectDisable Disables Master mode slave select. PLIB_SPI_SlaveSelectEnable Enables Master mode slave select. PLIB_SPI_StopInIdleDisable Continues module operation when the device enters Idle mode. PLIB_SPI_StopInIdleEnable Discontinues module operation when the device enters Idle mode. b) Data Transfer Functions Name Description PLIB_SPI_BufferClear Clears the SPI buffer. PLIB_SPI_BufferRead Returns the SPI buffer value. PLIB_SPI_BufferAddressGet Returns the address of the SPIxBUF (Transmit(SPIxTXB) and Receive (SPIxRXB)) register. PLIB_SPI_BufferRead16bit Returns 16-bit SPI buffer value. PLIB_SPI_BufferRead32bit Returns 32-bit SPI buffer value. PLIB_SPI_BufferWrite Write the data to the SPI buffer. PLIB_SPI_BufferWrite16bit Writes 16-bit data to the SPI buffer. PLIB_SPI_BufferWrite32bit Write 32-bit data to the SPI buffer. c) Framed Mode Functions Name Description PLIB_SPI_FramedCommunicationDisable Disables framed SPI support. PLIB_SPI_FramedCommunicationEnable Enables framed SPI support. PLIB_SPI_FrameErrorStatusGet Returns the current status of the SPI frame error. PLIB_SPI_FrameErrorStatusClear Clears the SPI frame error flag. PLIB_SPI_FrameSyncPulseCounterSelect Selects at which character the SPI frame sync pulse is generated. PLIB_SPI_FrameSyncPulseDirectionSelect Selects the frame sync pulse direction. PLIB_SPI_FrameSyncPulseEdgeSelect Selects the frame sync pulse edge. PLIB_SPI_FrameSyncPulsePolaritySelect Selects the frame sync pulse polarity. PLIB_SPI_FrameSyncPulseWidthSelect Sets the frame sync pulse width. d) Audio Mode Functions Name Description PLIB_SPI_AudioCommunicationWidthSelect Selects the data width for the SPI audio communication. PLIB_SPI_AudioErrorDisable Disables the SPI error. PLIB_SPI_AudioErrorEnable Enables the SPI error. PLIB_SPI_AudioProtocolDisable Audio protocol is disabled. PLIB_SPI_AudioProtocolEnable Audio protocol is enabled. PLIB_SPI_AudioProtocolModeSelect Selects the Audio Protocol mode. PLIB_SPI_AudioTransmitModeSelect Selects the transmit audio data format. e) Transmitter Functions Name Description PLIB_SPI_TransmitBufferIsEmpty Returns the current status of the transmit buffer. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1828 PLIB_SPI_TransmitBufferIsFull Returns the current transmit buffer status of the SPI module. PLIB_SPI_TransmitUnderRunStatusGet Returns the current status of the transmit underrun. PLIB_SPI_TransmitUnderRunStatusClear Clears the SPI transmit underrun flag. f) Receiver Functions Name Description PLIB_SPI_ReceiverBufferIsFull Returns the current status of the SPI receive buffer. PLIB_SPI_ReceiverFIFOIsEmpty Returns the current status of the SPI receive FIFO. PLIB_SPI_ReceiverHasOverflowed Returns the current status of the SPI receiver overflow. PLIB_SPI_ReceiverOverflowClear Clears the SPI receive overflow flag. g) Feature Existence Functions Name Description PLIB_SPI_ExistsAudioCommunicationWidth Identifies whether the AudioCommunicationWidth feature exists on the SPI module. PLIB_SPI_ExistsAudioErrorControl Identifies whether the AudioErrorControl feature exists on the SPI module. PLIB_SPI_ExistsAudioProtocolControl Identifies whether the AudioProtocolControl feature exists on the SPI module. PLIB_SPI_ExistsAudioProtocolMode Identifies whether the AudioProtocolMode feature exists on the SPI module. PLIB_SPI_ExistsAudioTransmitMode Identifies whether the AudioTransmitMode feature exists on the SPI module. PLIB_SPI_ExistsBaudRate Identifies whether the BaudRate feature exists on the SPI module. PLIB_SPI_ExistsBaudRateClock Identifies whether the BaudRateClock feature exists on the SPI module. PLIB_SPI_ExistsBuffer Identifies whether the Buffer feature exists on the SPI module. PLIB_SPI_ExistsBusStatus Identifies whether the BusStatus feature exists on the SPI module. PLIB_SPI_ExistsClockPolarity Identifies whether the ClockPolarity feature exists on the SPI module. PLIB_SPI_ExistsCommunicationWidth Identifies whether the CommunicationWidth feature exists on the SPI module. PLIB_SPI_ExistsEnableControl Identifies whether the EnableControl feature exists on the SPI module. PLIB_SPI_ExistsErrorInterruptControl Identifies whether the ErrorInterruptControl feature exists on the SPI module. PLIB_SPI_ExistsFIFOControl Identifies whether the FIFOControl feature exists on the SPI module. PLIB_SPI_ExistsFIFOCount Identifies whether the FIFOCount feature exists on the SPI module. PLIB_SPI_ExistsFIFOInterruptMode Identifies whether the FIFOInterruptMode feature exists on the SPI module. PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus Identifies whether the FIFOShiftRegisterEmptyStatus feature exists on the SPI module. PLIB_SPI_ExistsFramedCommunication Identifies whether the FramedCommunication feature exists on the SPI module. PLIB_SPI_ExistsFrameErrorStatus Identifies whether the FrameErrorStatus feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseCounter Identifies whether the FrameSyncPulseCounter feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseDirection Identifies whether the FrameSyncPulseDirection feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseEdge Identifies whether the FrameSyncPulseEdge feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulsePolarity Identifies whether the FrameSyncPulsePolarity feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseWidth Identifies whether the FrameSyncPulseWidth feature exists on the SPI module. PLIB_SPI_ExistsInputSamplePhase Identifies whether the InputSamplePhase feature exists on the SPI module. PLIB_SPI_ExistsMasterControl Identifies whether the MasterControl feature exists on the SPI module. PLIB_SPI_ExistsOutputDataPhase Identifies whether the OutputDataPhase feature exists on the SPI module. PLIB_SPI_ExistsPinControl Identifies whether the PinControl feature exists on the SPI module. PLIB_SPI_ExistsReadDataSignStatus Identifies whether the ReadDataSignStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiveBufferStatus Identifies whether the ReceiveBufferStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiveFIFOStatus Identifies whether the ReceiveFIFOStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiverOverflow Identifies whether the ReceiverOverflow feature exists on the SPI module. PLIB_SPI_ExistsSlaveSelectControl Identifies whether the SlaveSelectControl feature exists on the SPI module. PLIB_SPI_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the SPI module. PLIB_SPI_ExistsTransmitBufferEmptyStatus Identifies whether the TransmitBufferEmptyStatus feature exists on the SPI module. PLIB_SPI_ExistsTransmitBufferFullStatus Identifies whether the TransmitBufferFullStatus feature exists on the SPI module. PLIB_SPI_ExistsTransmitUnderRunStatus Identifies whether the TransmitUnderRunStatus feature exists on the SPI module. PLIB_SPI_Exists16bitBuffer Identifies whether the Buffer16bit feature exists on the SPI module. PLIB_SPI_Exists32bitBuffer Identifies whether the Buffer32bit feature exists on the SPI module. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1829 h) Data Types and Constants Name Description SPI_AUDIO_COMMUNICATION_WIDTH Defines the list of SPI audio communication width. SPI_AUDIO_ERROR Defines the list of SPI audio error. SPI_AUDIO_PROTOCOL Data type defining the audio protocol mode. SPI_AUDIO_TRANSMIT_MODE Defines the list of SPI transmit audio mode format. SPI_BAUD_RATE_CLOCK Defines the list of SPI Baud Rate Generator (BRG). SPI_CLOCK_POLARITY Defines the list of SPI clock polarity. SPI_COMMUNICATION_WIDTH Defines the list of SPI communication width. SPI_DATA_TYPE Data type defining the SPI data size. SPI_ERROR_INTERRUPT Defines the list of SPI error interrupts. SPI_FIFO_INTERRUPT Defines the list of SPI Buffer Interrupt mode. SPI_FIFO_TYPE Defines the list of SPI buffer mode. SPI_FRAME_PULSE_DIRECTION Defines the list of SPI frame sync pulse direction. SPI_FRAME_PULSE_EDGE Defines the list of SPI frame sync pulse edge. SPI_FRAME_PULSE_POLARITY Defines the list of SPI frame sync pulse polarity. SPI_FRAME_PULSE_WIDTH Defines the list of SPI frame sync pulse width. SPI_FRAME_SYNC_PULSE Data type defining the frame sync pulse counter values. SPI_INPUT_SAMPLING_PHASE Defines the list of SPI data input sample phase. SPI_MODULE_ID Identifies the supported SPI modules. SPI_OUTPUT_DATA_PHASE Defines the list of SPI serial output data changes. SPI_PIN Data type defining the SPI pin. Description This section describes the Application Programming Interface (API) functions of the SPI Peripheral Library. Refer to each section for a detailed description. a) General Configuration and Status Functions PLIB_SPI_BaudRateClockSelect Function Selects the type of clock is used by the Baud Rate Generator. File plib_spi.h C void PLIB_SPI_BaudRateClockSelect(SPI_MODULE_ID index, SPI_BAUD_RATE_CLOCK type); Returns None. Description This function selects the type of clock is used by the Baud Rate Generator. Remarks This function implements an operation of the baud rate clock control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBaudRateClock" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_BaudRateClockSelect (MY_SPI_INSTANCE, SPI_BAUD_RATE_MCLK_CLOCK); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1830 Parameters Parameters Description index Identifier for the device instance to be configured type One of the SPI_BAUD_RATE_CLOCK enumeration values as the SPI baud clock Function void PLIB_SPI_BaudRateClockSelect ( SPI_MODULE_ID index, SPI_BAUD_RATE_CLOCK type) PLIB_SPI_BaudRateSet Function Sets the baud rate to the desired value. File plib_spi.h C void PLIB_SPI_BaudRateSet(SPI_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate); Returns None. Description This function sets the baud rate to the desired value. Remarks Setting a new baud rate value causes the baud rate timer to reset. This ensures that the baud rate timer does not have to overflow before outputting the new baud rate. If the system clock is changed during an active receive operation, a receive error or data loss may result. To avoid this issue, verify that no receptions are in progress before changing the system clock. This function implements an operation of the baud rate set feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBaudRate" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_BaudRateSet(MY_SPI_INSTANCE, MY_CLOCK_FREQUENCY, 9600); Parameters Parameters Description index Identifier for the device instance to be configured clockFrequency Clock frequency baudrate Baud rate value Function void PLIB_SPI_BaudRateSet( SPI_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate ) PLIB_SPI_ClockPolaritySelect Function Enables clock polarity. File plib_spi.h Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1831 C void PLIB_SPI_ClockPolaritySelect(SPI_MODULE_ID index, SPI_CLOCK_POLARITY polarity); Returns None. Description This function enables clock polarity. Remarks This function implements an operation of the clock polarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsClockPolarity" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_ClockPolaritySelect(MY_SPI_INSTANCE, SPI_CLOCK_POLARITY_IDLE_HIGH ); Parameters Parameters Description index Identifier for the device instance to be configured polarity One of the SPI_CLOCK_POLARITY enumeration values as the SPI clock polarity Function void PLIB_SPI_ClockPolaritySelect( SPI_MODULE_ID index, SPI_CLOCK_POLARITY polarity) PLIB_SPI_CommunicationWidthSelect Function Selects the data width for the SPI communication. File plib_spi.h C void PLIB_SPI_CommunicationWidthSelect(SPI_MODULE_ID index, SPI_COMMUNICATION_WIDTH width); Returns None. Description This function selects the data width for the SPI communication. Remarks This function implements an operation of the communication width feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsCommunicationWidth" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_CommunicationWidthSelect(MY_SPI_INSTANCE, SPI_COMMUNICATION_WIDTH_8BITS); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1832 Parameters Parameters Description index Identifier for the device instance to be configured width One of the SPI_COMMUNICATION_WIDTH enumeration values as the SPI buffer width Function void PLIB_SPI_CommunicationWidthSelect ( SPI_MODULE_ID index, SPI_COMMUNICATION_WIDTH width ) PLIB_SPI_Disable Function Disables the SPI module. File plib_spi.h C void PLIB_SPI_Disable(SPI_MODULE_ID index); Returns None. Description This function disables the SPI module. Remarks This function implements an operation of the enable control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsEnableControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_Disable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_Disable ( SPI_MODULE_ID index) PLIB_SPI_Enable Function Enables the SPI module. File plib_spi.h C void PLIB_SPI_Enable(SPI_MODULE_ID index); Returns None. Description This function enables the SPI module. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1833 Remarks The SCKx, SDOx, SDIx and SSx pins must be assigned to available RPn pins before use. This function implements an operation of the enable control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsEnableControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_Enable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_Enable( SPI_MODULE_ID index ) PLIB_SPI_ErrorInterruptDisable Function Enables SPI error interrupts. File plib_spi.h C void PLIB_SPI_ErrorInterruptDisable(SPI_MODULE_ID index, SPI_ERROR_INTERRUPT error); Returns None. Description This function enables SPI error interrupts. Remarks This function implements an operation of the error interrupt control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsErrorInterruptControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_ErrorInterruptDisable (MY_SPI_INSTANCE, SPI_ERROR_INTERRUPT_FRAME_ERROR_OVERFLOW); Parameters Parameters Description index Identifier for the device instance to be configured error One of the SPI_ERROR_INTERRUPT enumeration values as the SPI interrupt error Function void PLIB_SPI_ErrorInterruptDisable ( SPI_MODULE_ID index, SPI_ERROR_INTERRUPT error) Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1834 PLIB_SPI_ErrorInterruptEnable Function Enables SPI error interrupts File plib_spi.h C void PLIB_SPI_ErrorInterruptEnable(SPI_MODULE_ID index, SPI_ERROR_INTERRUPT error); Returns None. Description This function enables SPI error interrupts. Remarks This function implements an operation of the error interrupt control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsErrorInterruptControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_ErrorInterruptEnable (MY_SPI_INSTANCE, SPI_ERROR_INTERRUPT_FRAME_ERROR_OVERFLOW); Parameters Parameters Description index Identifier for the device instance to be configured type One of the SPI_ERROR_INTERRUPT enumeration values as the SPI interrupt error Function void PLIB_SPI_ErrorInterruptEnable ( SPI_MODULE_ID index, SPI_ERROR_INTERRUPT error) PLIB_SPI_FIFOCountGet Function Reads the SPI Buffer Element Count bits for either receive or transmit. File plib_spi.h C uint8_t PLIB_SPI_FIFOCountGet(SPI_MODULE_ID index, SPI_FIFO_TYPE type); Returns CountValue - Buffer element count bits Description This function reads the number of SPI transfers pending for Master mode and the number of unread SPI transfers for Slave mode. Remarks Valid in Enhanced Buffer mode. This function implements an operation of the FIFO control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOCount" in your application to automatically determine whether this feature is available. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1835 Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. uint8_t count = PLIB_SPI_FIFOCountGet(MY_SPI_INSTANCE,SPI_FIFO_TYPE_TRANSMIT); Parameters Parameters Description index Identifier for the device instance to be configured type One of the SPI_FIFO_TYPE enumeration values Function uint8_t PLIB_SPI_FIFOCountGet ( SPI_MODULE_ID index, SPI_FIFO_TYPE type) PLIB_SPI_FIFODisable Function Disables the SPI enhanced buffer. File plib_spi.h C void PLIB_SPI_FIFODisable(SPI_MODULE_ID index); Returns None. Description This function disables the SPI enhanced buffer. Remarks Enables the legacy standard single buffer mode. This function implements an operation of the FIFO control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FIFODisable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_FIFODisable ( SPI_MODULE_ID index) PLIB_SPI_FIFOEnable Function Enables the SPI enhanced buffer. File plib_spi.h Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1836 C void PLIB_SPI_FIFOEnable(SPI_MODULE_ID index); Returns None. Description This function enables the SPI enhanced buffer. Remarks This enables the enhanced buffer mode. This function implements an operation of the FIFO control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FIFOEnable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_FIFOEnable ( SPI_MODULE_ID index) PLIB_SPI_FIFOInterruptModeSelect Function Selects the SPI buffer interrupt mode. File plib_spi.h C void PLIB_SPI_FIFOInterruptModeSelect(SPI_MODULE_ID index, SPI_FIFO_INTERRUPT mode); Returns None. Description This function selects the SPI buffer interrupt mode from SPI_FIFO_INTERRUPT. Remarks Valid in Enhanced Buffer mode. This function implements an operation of the FIFO interrupt feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOInterruptMode" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FIFOInterruptModeSelect(MY_SPI_INSTANCE, SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_NOT_FULL); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1837 Parameters Parameters Description index Identifier for the device instance to be configured mode One of the SPI_FIFO_INTERRUPT enumeration values as the SPI buffer interrupt mode Function void PLIB_SPI_FIFOInterruptModeSelect ( SPI_MODULE_ID index, SPI_FIFO_INTERRUPT mode) PLIB_SPI_FIFOShiftRegisterIsEmpty Function Returns the current status of the SPI shift register. File plib_spi.h C bool PLIB_SPI_FIFOShiftRegisterIsEmpty(SPI_MODULE_ID index); Returns • true - SPI shift register is empty and ready to send or receive • false - SPI shift register is not empty Description This function returns the current status of the SPI shift register. Remarks Valid in Enhanced Buffer mode. This function implements an operation of the FIFO status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool Status = PLIB_SPI_FIFOShiftRegisterIsEmpty(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SPI_FIFOShiftRegisterIsEmpty ( SPI_MODULE_ID index) PLIB_SPI_InputSamplePhaseSelect Function Selects the SPI data input sample phase. File plib_spi.h C void PLIB_SPI_InputSamplePhaseSelect(SPI_MODULE_ID index, SPI_INPUT_SAMPLING_PHASE phase); Returns None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1838 Description This function selects the input sampling phase in Master mode. Remarks This function implements an operation of the input sample phase feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsInputSamplePhase" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_InputSamplePhaseSelect(MY_SPI_INSTANCE, SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); Parameters Parameters Description index Identifier for the device instance to be configured phase One of the SPI_INPUT_SAMPLING_PHASE as the SPI input sampling phase Function void PLIB_SPI_InputSamplePhaseSelect( SPI_MODULE_ID index, SPI_INPUT_SAMPLING_PHASE phase) PLIB_SPI_IsBusy Function Returns the current SPI module activity status. File plib_spi.h C bool PLIB_SPI_IsBusy(SPI_MODULE_ID index); Returns • true - SPI module is currently busy with some transactions • false - SPI module is currently idle Description This function returns the current SPI module activity status. Remarks This function implements an operation of the bus status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBusStatus" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool status = PLIB_SPI_IsBusy(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SPI_IsBusy ( SPI_MODULE_ID index) Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1839 PLIB_SPI_MasterEnable Function Enables the SPI in Master mode. File plib_spi.h C void PLIB_SPI_MasterEnable(SPI_MODULE_ID index); Returns None. Description This function enables the SPI in Master mode. Remarks This function implements an operation of the master enable control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsMasterControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_MasterEnable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_MasterEnable( SPI_MODULE_ID index) PLIB_SPI_OutputDataPhaseSelect Function Selects serial output data change. File plib_spi.h C void PLIB_SPI_OutputDataPhaseSelect(SPI_MODULE_ID index, SPI_OUTPUT_DATA_PHASE phase); Returns None. Description This function selects serial output data change. Remarks This function implements an operation of the output data phase feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsOutputDataPhase" in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1840 Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_OutputDataPhaseSelect(MY_SPI_INSTANCE, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); Parameters Parameters Description index Identifier for the device instance to be configured data One of the SPI_OUTPUT_DATA_PHASE enumeration values as the SPI serial output data change Function void PLIB_SPI_OutputDataPhaseSelect ( SPI_MODULE_ID index, SPI_OUTPUT_DATA_PHASE data) PLIB_SPI_PinDisable Function Enables the selected SPI pins. File plib_spi.h C void PLIB_SPI_PinDisable(SPI_MODULE_ID index, SPI_PIN pin); Returns None. Description This function enables the selected SPI pins. Remarks This function implements an operation of the pin control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsPinControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_PinDisable(MY_SPI_INSTANCE, SPI_PIN_SLAVE_SELECT); Parameters Parameters Description index Identifier for the device instance to be configured pin One of the SPI_PIN enumeration values as the SPI pin Function void PLIB_SPI_PinDisable ( SPI_MODULE_ID index, SPI_PIN pin) PLIB_SPI_PinEnable Function Enables the selected SPI pins. File plib_spi.h C void PLIB_SPI_PinEnable(SPI_MODULE_ID index, SPI_PIN pin); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1841 Returns None. Description This function enables the selected SPI pins. Remarks This function implements an operation of the pin control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsPinControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_PinEnable(MY_SPI_INSTANCE, SPI_PIN_SLAVE_SELECT); Parameters Parameters Description index Identifier for the device instance to be configured pin One of the SPI_PIN enumeration values as the SPI pin Function void PLIB_SPI_PinEnable ( SPI_MODULE_ID index,SPI_PIN pin) PLIB_SPI_ReadDataIsSignExtended Function Returns the current status of the receive (RX) FIFO sign-extended data. File plib_spi.h C bool PLIB_SPI_ReadDataIsSignExtended(SPI_MODULE_ID index); Returns • true - Data from RX FIFO is sign-extended • false - Data from RX FIFO is not sign-extended Description This function returns the current status of the receive (RX) FIFO sign-extended data. Remarks This function implements an operation of the data sign feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReadDataSignStatus" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool Status = PLIB_SPI_ReadDataIsSignExtended(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1842 Function bool PLIB_SPI_ReadDataIsSignExtended( SPI_MODULE_ID index) PLIB_SPI_SlaveEnable Function Enables the SPI in Slave mode. File plib_spi.h C void PLIB_SPI_SlaveEnable(SPI_MODULE_ID index); Returns None. Description This function enables the SPI in Slave mode. Remarks This function implements an operation of the master enable control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsMasterControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_SlaveEnable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_SlaveEnable( SPI_MODULE_ID index) PLIB_SPI_SlaveSelectDisable Function Disables Master mode slave select. File plib_spi.h C void PLIB_SPI_SlaveSelectDisable(SPI_MODULE_ID index); Returns None. Description This function disables Master mode slave select. Remarks This feature does not support Framed SPI mode. This function implements an operation of the slave select feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsSlaveSelectControl" in your application to automatically determine whether this feature is available. To disable Slave mode slave select pin (SSEN), PLIB_SPI_PinDisable API can be used. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1843 Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_SlaveSelectDisable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_SlaveSelectDisable( SPI_MODULE_ID index) PLIB_SPI_SlaveSelectEnable Function Enables Master mode slave select. File plib_spi.h C void PLIB_SPI_SlaveSelectEnable(SPI_MODULE_ID index); Returns None. Description This function enables Master mode slave select. Remarks This feature does not support Framed SPI mode. This function implements an operation of the Master mode slave select feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsSlaveSelectControl" in your application to automatically determine whether this feature is available. To enable Slave mode slave select pin (SSEN), PLIB_SPI_PinEnable API can be used. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_SlaveSelectEnable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_SlaveSelectEnable( SPI_MODULE_ID index) PLIB_SPI_StopInIdleDisable Function Continues module operation when the device enters Idle mode. File plib_spi.h Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1844 C void PLIB_SPI_StopInIdleDisable(SPI_MODULE_ID index); Returns None. Description This function sets up the SPI module such that module operation is continued when the device enters Idle mode. Remarks This function implements an operation of the stop in idle control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsStopInIdleControl" in your application to determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_StopInIdleDisable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_StopInIdleDisable ( SPI_MODULE_ID index) PLIB_SPI_StopInIdleEnable Function Discontinues module operation when the device enters Idle mode. File plib_spi.h C void PLIB_SPI_StopInIdleEnable(SPI_MODULE_ID index); Returns None. Description This function sets up the SPI module such that module operation is disabled when the device enters Idle mode. Remarks This function implements an operation of the stop in idle control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsStopInIdleControl" in your application to automatically determine if this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_StopInIdleEnable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1845 Function void PLIB_SPI_StopInIdleEnable ( SPI_MODULE_ID index) b) Data Transfer Functions PLIB_SPI_BufferClear Function Clears the SPI buffer. File plib_spi.h C void PLIB_SPI_BufferClear(SPI_MODULE_ID index); Returns None. Description This function clears the SPI buffer. Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBuffer" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_BufferClear(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_BufferClear ( SPI_MODULE_ID index) PLIB_SPI_BufferRead Function Returns the SPI buffer value. File plib_spi.h C uint8_t PLIB_SPI_BufferRead(SPI_MODULE_ID index); Returns Reads the SPI buffer. Description This function returns the SPI buffer value. Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBuffer" in your application to automatically determine whether this feature is Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1846 available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. uint8_t bufferValue = PLIB_SPI_BufferRead(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SPI_BufferRead ( SPI_MODULE_ID index) PLIB_SPI_BufferAddressGet Function Returns the address of the SPIxBUF (Transmit(SPIxTXB) and Receive (SPIxRXB)) register. File plib_spi.h C void* PLIB_SPI_BufferAddressGet(SPI_MODULE_ID index); Returns The address of the SPIxBUF register Description This function returns the address of the SPIxBUF (Transmit(SPIxTXB) and Receive (SPIxRXB)) register. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_BufferAddressGet( SPI_MODULE_ID index ) PLIB_SPI_BufferRead16bit Function Returns 16-bit SPI buffer value. File plib_spi.h C uint16_t PLIB_SPI_BufferRead16bit(SPI_MODULE_ID index); Returns Returns the SPI 16-bit buffer value. Description This function returns 16-bit SPI buffer value. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1847 Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_Exists16bitBuffer" in your application to automatically determine whether this feature is available. Preconditions SPI 16-bit wide communication must be selected using PLIB_SPI_CommunicationWidthSelect. Example #define MY_SPI_INSTANCE SPI_ID_1 uint16_t bufferValue = PLIB_SPI_BufferRead16bit( MY_SPI_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function uint16_t PLIB_SPI_BufferRead16bit ( SPI_MODULE_ID index ) PLIB_SPI_BufferRead32bit Function Returns 32-bit SPI buffer value. File plib_spi.h C uint32_t PLIB_SPI_BufferRead32bit(SPI_MODULE_ID index); Returns Returns the SPI 32-bit buffer value. Description This function returns 32-bit SPI buffer value. Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_Exists32bitBuffer" in your application to automatically determine whether this feature is available. Preconditions SPI 32-bit wide communication must be selected using PLIB_SPI_CommunicationWidthSelect. Example #define MY_SPI_INSTANCE SPI_ID_1 uint32_t bufferValue = PLIB_SPI_BufferRead32bit( MY_SPI_INSTANCE ); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_SPI_BufferRead32bit ( SPI_MODULE_ID index ) PLIB_SPI_BufferWrite Function Write the data to the SPI buffer. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1848 File plib_spi.h C void PLIB_SPI_BufferWrite(SPI_MODULE_ID index, uint8_t data); Returns None. Description This function writes data to the SPI buffer. Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBuffer" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_BufferWrite ( MY_SPI_INSTANCE, 0xFF ); Parameters Parameters Description index Identifier for the device instance to be configured data Data to written to the SPI buffer Function void PLIB_SPI_BufferWrite ( SPI_MODULE_ID index , uint8_t data ) PLIB_SPI_BufferWrite16bit Function Writes 16-bit data to the SPI buffer. File plib_spi.h C void PLIB_SPI_BufferWrite16bit(SPI_MODULE_ID index, uint16_t data); Returns None. Description This function writes 16-bit data to the SPI buffer. Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_Exists16bitBuffer" in your application to automatically determine whether this feature is available. Preconditions SPI 16-bit wide communication must be selected using PLIB_SPI_CommunicationWidthSelect. Example #define MY_SPI_INSTANCE SPI_ID_1 PLIB_SPI_BufferWrite16bit ( MY_SPI_INSTANCE, 0x55AA ); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1849 Parameters Parameters Description index Identifier for the device instance to be configured data 16-bit data to be written to the SPI buffer Function void PLIB_SPI_BufferWrite16bit ( SPI_MODULE_ID index , uint16_t data ) PLIB_SPI_BufferWrite32bit Function Write 32-bit data to the SPI buffer. File plib_spi.h C void PLIB_SPI_BufferWrite32bit(SPI_MODULE_ID index, uint32_t data); Returns None. Description This function writes 32-bit data to the SPI buffer. Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_Exists32bitBuffer" in your application to automatically determine whether this feature is available. Preconditions SPI 32-bit wide communication must be selected using PLIB_SPI_CommunicationWidthSelect. Example #define MY_SPI_INSTANCE SPI_ID_1 PLIB_SPI_BufferWrite ( MY_SPI_INSTANCE, 0x55AA55AA ); Parameters Parameters Description index Identifier for the device instance to be configured data 32-bit data to be written to the SPI buffer Function void PLIB_SPI_BufferWrite32bit ( SPI_MODULE_ID index , uint32_t data ) c) Framed Mode Functions PLIB_SPI_FramedCommunicationDisable Function Disables framed SPI support. File plib_spi.h C void PLIB_SPI_FramedCommunicationDisable(SPI_MODULE_ID index); Returns None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1850 Description This function disables framed SPI support. Remarks This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFramedCommunication" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FramedCommunicationDisable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_FramedCommunicationDisable ( SPI_MODULE_ID index) PLIB_SPI_FramedCommunicationEnable Function Enables framed SPI support. File plib_spi.h C void PLIB_SPI_FramedCommunicationEnable(SPI_MODULE_ID index); Returns None. Description This function enables framed SPI support. Remarks This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFramedCommunication" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FramedCommunicationEnable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_FramedCommunicationEnable ( SPI_MODULE_ID index) Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1851 PLIB_SPI_FrameErrorStatusGet Function Returns the current status of the SPI frame error. File plib_spi.h C bool PLIB_SPI_FrameErrorStatusGet(SPI_MODULE_ID index); Returns • true - Frame error detected • false - No frame error detected Description This function returns the current status of the SPI frame error. Remarks Valid only if Frame mode is enabled. This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameErrorStatus" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool status = PLIB_SPI_FrameErrorStatusGet(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SPI_FrameErrorStatusGet ( SPI_MODULE_ID index) PLIB_SPI_FrameErrorStatusClear Function Clears the SPI frame error flag. File plib_spi.h C void PLIB_SPI_FrameErrorStatusClear(SPI_MODULE_ID index); Returns None. Description This function clears the SPI frame error flag. Remarks This function implements an operation of the frame error status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "ExistsFrameErrorStatus" in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1852 Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameErrorStatusClear(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_FrameErrorStatusClear( SPI_MODULE_ID index) PLIB_SPI_FrameSyncPulseCounterSelect Function Selects at which character the SPI frame sync pulse is generated. File plib_spi.h C void PLIB_SPI_FrameSyncPulseCounterSelect(SPI_MODULE_ID index, SPI_FRAME_SYNC_PULSE pulse); Returns None. Description This function selects at which character the SPI frame sync pulse is generated. Remarks This is valid only when PLIB_SPI_FramedCommunicationEnable is enabled. This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulseCounter" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulseCounterSelect(MY_SPI_INSTANCE, SPI_FRAME_SYNC_PULSE_ON_EVERY_32_DATA_CHARACTER ); Parameters Parameters Description index Identifier for the device instance to be configured pulse One of the SPI_FRAME_SYNC_PULSE enumeration values as the SPI frame sync pulse count Function void PLIB_SPI_FrameSyncPulseCounterSelect ( SPI_MODULE_ID index, SPI_FRAME_SYNC_PULSE pulse) PLIB_SPI_FrameSyncPulseDirectionSelect Function Selects the frame sync pulse direction. File plib_spi.h Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1853 C void PLIB_SPI_FrameSyncPulseDirectionSelect(SPI_MODULE_ID index, SPI_FRAME_PULSE_DIRECTION direction); Returns None. Description This function selects the frame sync pulse direction. Remarks This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulseDirection" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_INSTANCE, SPI_FRAME_PULSE_DIRECTION_INPUT ); Parameters Parameters Description index Identifier for the device instance to be configured direction One of the SPI_FRAME_PULSE_DIRECTION enumeration values as the SPI frame sync pulse polarity Function void PLIB_SPI_FrameSyncPulseDirectionSelect ( SPI_MODULE_ID index, SPI_FRAME_PULSE_DIRECTION direction) PLIB_SPI_FrameSyncPulseEdgeSelect Function Selects the frame sync pulse edge. File plib_spi.h C void PLIB_SPI_FrameSyncPulseEdgeSelect(SPI_MODULE_ID index, SPI_FRAME_PULSE_EDGE edge); Returns None. Description This function selects the frame sync pulse edge. Remarks This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulseEdge" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulseEdgeSelect(MY_SPI_INSTANCE, SPI_FRAME_PULSE_EDGE_COINCIDES_FIRST_BIT_CLOCK); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1854 Parameters Parameters Description index Identifier for the device instance to be configured edge One of the SPI_FRAME_PULSE_EDGE enumeration values as the SPI frame sync pulse edge Function void PLIB_SPI_FrameSyncPulseEdgeSelect ( SPI_MODULE_ID index, SPI_FRAME_PULSE_EDGE edge) PLIB_SPI_FrameSyncPulsePolaritySelect Function Selects the frame sync pulse polarity. File plib_spi.h C void PLIB_SPI_FrameSyncPulsePolaritySelect(SPI_MODULE_ID index, SPI_FRAME_PULSE_POLARITY polarity); Returns None. Description This function selects the frame sync pulse polarity. Remarks Available only for Frame mode. This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulsePolarity" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulsePolaritySelect(MY_SPI_INSTANCE, SPI_FRAME_PULSE_POLARITY_ACTIVE_HIGH ); Parameters Parameters Description index Identifier for the device instance to be configured polarity One of the SPI_FRAME_PULSE_POLARITY enumeration values as the SPI frame sync pulse polarity Function void PLIB_SPI_FrameSyncPulsePolaritySelect ( SPI_MODULE_ID index, SPI_FRAME_PULSE_POLARITY polarity) PLIB_SPI_FrameSyncPulseWidthSelect Function Sets the frame sync pulse width. File plib_spi.h C void PLIB_SPI_FrameSyncPulseWidthSelect(SPI_MODULE_ID index, SPI_FRAME_PULSE_WIDTH width); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1855 Returns None. Description This function sets the frame sync pulse width. Remarks Length of the word is dependent on the communication mode. This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulseWidth" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulseWidthSelect (MY_SPI_INSTANCE,SPI_FRAME_PULSE_WIDTH_ONE_WORD_LENGTH); Parameters Parameters Description index Identifier for the device instance to be configured edge One of the SPI_FRAME_PULSE_WIDTH enumeration values as the SPI frame sync pulse width. Function void PLIB_SPI_FrameSyncPulseWidthSelect ( SPI_MODULE_ID index, SPI_FRAME_PULSE_WIDTH width) d) Audio Mode Functions PLIB_SPI_AudioCommunicationWidthSelect Function Selects the data width for the SPI audio communication. File plib_spi.h C void PLIB_SPI_AudioCommunicationWidthSelect(SPI_MODULE_ID index, SPI_AUDIO_COMMUNICATION_WIDTH mode); Returns None. Description This function selects the data width for the SPI audio communication. Remarks This mode is available only when PLIB_SPI_AudioProtocolEnable is enabled. This function implements an operation of the audio communication width feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioCommunicationWidth" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1856 PLIB_SPI_AudioCommunicationWidthSelect(MY_SPI_INSTANCE, SPI_AUDIO_COMMUNICATION_32DATA_32FIFO_32CHANNEL); Parameters Parameters Description index Identifier for the device instance to be configured width One of the SPI_AUDIO_COMMUNICATION_WIDTH enumeration values as the SPI buffer width Function void PLIB_SPI_AudioCommunicationWidthSelect ( SPI_MODULE_ID index, SPI_AUDIO_COMMUNICATION_WIDTH width ) PLIB_SPI_AudioErrorDisable Function Disables the SPI error. File plib_spi.h C void PLIB_SPI_AudioErrorDisable(SPI_MODULE_ID index, SPI_AUDIO_ERROR error); Returns None. Description This function disables the SPI error. Remarks This function implements an operation of the audio error control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioErrorControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioErrorDisable (MY_SPI_INSTANCE, SPI_AUDIO_ERROR_RECEIVE_OVERFLOW); Parameters Parameters Description index Identifier for the device instance to be configured error One of the SPI_AUDIO_ERROR enumeration values as the SPI error Function void PLIB_SPI_AudioErrorDisable ( SPI_MODULE_ID index, SPI_AUDIO_ERROR error) PLIB_SPI_AudioErrorEnable Function Enables the SPI error. File plib_spi.h C void PLIB_SPI_AudioErrorEnable(SPI_MODULE_ID index, SPI_AUDIO_ERROR error); Returns None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1857 Description This function enables the SPI error. Remarks This function implements an operation of the audio error control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioErrorControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioErrorEnable (MY_SPI_INSTANCE, SPI_AUDIO_ERROR_RECEIVE_OVERFLOW); Parameters Parameters Description index Identifier for the device instance to be configured error One of the SPI_AUDIO_ERROR enumeration values as the SPI error Function void PLIB_SPI_AudioErrorEnable ( SPI_MODULE_ID index, SPI_Audio_ERROR error) PLIB_SPI_AudioProtocolDisable Function Audio protocol is disabled. File plib_spi.h C void PLIB_SPI_AudioProtocolDisable(SPI_MODULE_ID index); Returns None. Description This function disables the audio protocol. Remarks This function implements an operation of the audio protocol control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioProtocolControl" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioProtocolDisable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_AudioProtocolDisable ( SPI_MODULE_ID index) Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1858 PLIB_SPI_AudioProtocolEnable Function Audio protocol is enabled. File plib_spi.h C void PLIB_SPI_AudioProtocolEnable(SPI_MODULE_ID index); Returns None. Description This function enables the audio protocol. Remarks This function implements an operation of the audio protocol control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioProtocolControl" in your application to automatically determine whether this feature is available. Preconditions Disable the SPI module by calling PLIB_SPI_Disable. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioProtocolEnable(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_AudioProtocolEnable ( SPI_MODULE_ID index) PLIB_SPI_AudioProtocolModeSelect Function Selects the Audio Protocol mode. File plib_spi.h C void PLIB_SPI_AudioProtocolModeSelect(SPI_MODULE_ID index, SPI_AUDIO_PROTOCOL mode); Returns None. Description This function selects the Audio Protocol mode. Remarks This function implements an operation of the audio protocol mode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioProtocolMode" in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1859 Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioProtocolModeSelect(MY_SPI_INSTANCE,SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED ); Parameters Parameters Description index Identifier for the device instance to be configured mode One of the SPI_AUDIO_PROTOCOL enumeration values as the audio protocol Function void PLIB_SPI_AudioProtocolModeSelect( SPI_MODULE_ID index, SPI_AUDIO_PROTOCOL mode ) PLIB_SPI_AudioTransmitModeSelect Function Selects the transmit audio data format. File plib_spi.h C void PLIB_SPI_AudioTransmitModeSelect(SPI_MODULE_ID index, SPI_AUDIO_TRANSMIT_MODE mode); Returns None. Description This function selects the transmit audio data format. Remarks This function implements an operation of the audio transmit mode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioTransmitMode" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioTransmitModeSelect (MY_SPI_INSTANCE, SPI_AUDIO_TRANSMIT_MONO); Parameters Parameters Description index Identifier for the device instance to be configured mode One of the SPI_TRANSMIT_AUDIO_MODE enumeration values as the transmit audio format Function void PLIB_SPI_AudioTransmitModeSelect ( SPI_MODULE_ID index, SPI_AUDIO_TRANSMIT_MODE mode) e) Transmitter Functions PLIB_SPI_TransmitBufferIsEmpty Function Returns the current status of the transmit buffer. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1860 File plib_spi.h C bool PLIB_SPI_TransmitBufferIsEmpty(SPI_MODULE_ID index); Returns • true - Transmit buffer is empty • false - Transmit buffer is not empty Description This function returns the current status of the transmit buffer. Remarks This function implements an operation of the transmit buffer empty status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsTransmitBufferEmptyStatus" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool Status = PLIB_SPI_TransmitBufferIsEmpty(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SPI_TransmitBufferIsEmpty ( SPI_MODULE_ID index) PLIB_SPI_TransmitBufferIsFull Function Returns the current transmit buffer status of the SPI module. File plib_spi.h C bool PLIB_SPI_TransmitBufferIsFull(SPI_MODULE_ID index); Returns • true - Transmit not yet started, transmit buffer is full • false - Transmit started, transmit buffer is empty/not full Description This function returns the current transmit buffer status of the SPI module. Remarks In Standard Buffer mode - automatically set in hardware when SPI buffer writes occur, loading the transmit buffer. Automatically cleared in hardware when the SPI module transfers data from the transmit buffer to the shift register. In Enhanced Buffer mode - automatically set in hardware when SPI buffer writes occur, loading the last available buffer. Automatically cleared in hardware when the buffer is available for writing. This function implements an operation of the transmit buffer status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsTransmitBufferFullStatus" in your application to automatically determine whether this feature is available. Preconditions None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1861 Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool buffullstate = PLIB_SPI_TransmitBufferIsFull (MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SPI_TransmitBufferIsFull ( SPI_MODULE_ID index) PLIB_SPI_TransmitUnderRunStatusGet Function Returns the current status of the transmit underrun. File plib_spi.h C bool PLIB_SPI_TransmitUnderRunStatusGet(SPI_MODULE_ID index); Returns • true - Transmit buffer has encountered an underrun condition • false - Transmit buffer run has not encountered an underrun condition Description This function returns the current status of the transmit underrun. Remarks Valid in Framed Sync mode. This function implements an operation of the transmit underrun status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsTransmitUnderRunStatus" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool Status = PLIB_SPI_TransmitUnderRunStatusGet(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SPI_TransmitUnderRunStatusGet( SPI_MODULE_ID index) PLIB_SPI_TransmitUnderRunStatusClear Function Clears the SPI transmit underrun flag. File plib_spi.h C void PLIB_SPI_TransmitUnderRunStatusClear(SPI_MODULE_ID index); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1862 Returns None. Description This function clears the SPI transmit underrun flag. Remarks This function implements an operation of the transmit underrun status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "ExistsTransmitUnderRunStatus" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_TransmitUnderRunStatusClear(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_TransmitUnderRunStatusClear( SPI_MODULE_ID index) f) Receiver Functions PLIB_SPI_ReceiverBufferIsFull Function Returns the current status of the SPI receive buffer. File plib_spi.h C bool PLIB_SPI_ReceiverBufferIsFull(SPI_MODULE_ID index); Returns Receiver Buffer Full Status: • true - Receive complete, receive buffer is full • false - Receive is not complete, receive buffer is empty Description This function returns the current status of the SPI receive buffer. Remarks In Standard Buffer mode - automatically set in hardware when the SPI module transfers data from the shift register to the receive buffer. Automatically cleared in hardware when the core reads the SPI buffer, read in the receive buffer. In Enhanced Buffer mode - automatically set in hardware when the SPI module transfers data from the shift register to the receive buffer, filling the last unread buffer. Automatically cleared in hardware when a buffer is available for a transfer from the shift register. This function implements an operation of the receiver buffer status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReceiveBufferStatus" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1863 // application developer. bool receivefullstate = PLIB_SPI_ReceiverBufferIsFull (MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SPI_ReceiverBufferIsFull ( SPI_MODULE_ID index) PLIB_SPI_ReceiverFIFOIsEmpty Function Returns the current status of the SPI receive FIFO. File plib_spi.h C bool PLIB_SPI_ReceiverFIFOIsEmpty(SPI_MODULE_ID index); Returns • true - Receive FIFO is empty • false - Receive FIFO is not empty Description This function returns the current status of the SPI receive FIFO. Remarks Valid in Enhanced Buffer mode. This function implements an operation of the FIFO status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReceiveFIFOStatus" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool fifostate = PLIB_SPI_ReceiverFIFOIsEmpty (MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SPI_ReceiverFIFOIsEmpty ( SPI_MODULE_ID index) PLIB_SPI_ReceiverHasOverflowed Function Returns the current status of the SPI receiver overflow. File plib_spi.h C bool PLIB_SPI_ReceiverHasOverflowed(SPI_MODULE_ID index); Returns SPI receiver overflow status: • true - A new byte/word is completely received and discarded. The user software has not read the previous data in the SPI buffer register. • false - No Overflow has occurred Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1864 Description This function returns the current status of the SPI receiver overflow. Remarks This function implements an operation of the receiver overflow status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReceiverOverflow" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool overflowstate = PLIB_SPI_ReceiverHasOverflowed(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SPI_ReceiverHasOverflowed ( SPI_MODULE_ID index) PLIB_SPI_ReceiverOverflowClear Function Clears the SPI receive overflow flag. File plib_spi.h C void PLIB_SPI_ReceiverOverflowClear(SPI_MODULE_ID index); Returns None. Description This function clears the SPI receive overflow flag. Remarks This function implements an operation of the receiver overflow status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReceiverOverflow" in your application to automatically determine whether this feature is available. Preconditions None. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_ReceiverOverflowClear(MY_SPI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SPI_ReceiverOverflowClear( SPI_MODULE_ID index) g) Feature Existence Functions Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1865 PLIB_SPI_ExistsAudioCommunicationWidth Function Identifies whether the AudioCommunicationWidth feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsAudioCommunicationWidth(SPI_MODULE_ID index); Returns • true - The AudioCommunicationWidth feature is supported on the device • false - The AudioCommunicationWidth feature is not supported on the device Description This function identifies whether the AudioCommunicationWidth feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_AudioCommunicationWidthSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsAudioCommunicationWidth( SPI_MODULE_ID index ) PLIB_SPI_ExistsAudioErrorControl Function Identifies whether the AudioErrorControl feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsAudioErrorControl(SPI_MODULE_ID index); Returns • true - The AudioErrorControl feature is supported on the device • false - The AudioErrorControl feature is not supported on the device Description This function identifies whether the AudioErrorControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_AudioErrorEnable • PLIB_SPI_AudioErrorDisable Remarks None. Preconditions None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1866 Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsAudioErrorControl( SPI_MODULE_ID index ) PLIB_SPI_ExistsAudioProtocolControl Function Identifies whether the AudioProtocolControl feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsAudioProtocolControl(SPI_MODULE_ID index); Returns • true - The AudioProtocolControl feature is supported on the device • false - The AudioProtocolControl feature is not supported on the device Description This function identifies whether the AudioProtocolControl feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_AudioProtocolEnable • PLIB_SPI_AudioProtocolDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsAudioProtocolControl( SPI_MODULE_ID index ) PLIB_SPI_ExistsAudioProtocolMode Function Identifies whether the AudioProtocolMode feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsAudioProtocolMode(SPI_MODULE_ID index); Returns • true - The AudioProtocolMode feature is supported on the device • false - The AudioProtocolMode feature is not supported on the device Description This function identifies whether the AudioProtocolMode feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_AudioProtocolModeSelect Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1867 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsAudioProtocolMode( SPI_MODULE_ID index ) PLIB_SPI_ExistsAudioTransmitMode Function Identifies whether the AudioTransmitMode feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsAudioTransmitMode(SPI_MODULE_ID index); Returns • true - The AudioTransmitMode feature is supported on the device • false - The AudioTransmitMode feature is not supported on the device Description This function identifies whether the AudioTransmitMode feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_AudioTransmitModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsAudioTransmitMode( SPI_MODULE_ID index ) PLIB_SPI_ExistsBaudRate Function Identifies whether the BaudRate feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsBaudRate(SPI_MODULE_ID index); Returns • true - The BaudRate feature is supported on the device • false - The BaudRate feature is not supported on the device Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1868 Description This function identifies whether the BaudRate feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_BaudRateSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsBaudRate( SPI_MODULE_ID index ) PLIB_SPI_ExistsBaudRateClock Function Identifies whether the BaudRateClock feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsBaudRateClock(SPI_MODULE_ID index); Returns • true - The BaudRateClock feature is supported on the device • false - The BaudRateClock feature is not supported on the device Description This function identifies whether the BaudRateClock feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_BaudRateClockSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsBaudRateClock( SPI_MODULE_ID index ) PLIB_SPI_ExistsBuffer Function Identifies whether the Buffer feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsBuffer(SPI_MODULE_ID index); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1869 Returns • true - The Buffer feature is supported on the device • false - The Buffer feature is not supported on the device Description This function identifies whether the Buffer feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_BufferClear • PLIB_SPI_BufferRead • PLIB_SPI_BufferWrite • PLIB_SPI_BufferAddressGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsBuffer( SPI_MODULE_ID index ) PLIB_SPI_ExistsBusStatus Function Identifies whether the BusStatus feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsBusStatus(SPI_MODULE_ID index); Returns • true - The BusStatus feature is supported on the device • false - The BusStatus feature is not supported on the device Description This function identifies whether the BusStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_IsBusy Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsBusStatus( SPI_MODULE_ID index ) PLIB_SPI_ExistsClockPolarity Function Identifies whether the ClockPolarity feature exists on the SPI module. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1870 File plib_spi.h C bool PLIB_SPI_ExistsClockPolarity(SPI_MODULE_ID index); Returns • true - The ClockPolarity feature is supported on the device • false - The ClockPolarity feature is not supported on the device Description This function identifies whether the ClockPolarity feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_ClockPolaritySelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsClockPolarity( SPI_MODULE_ID index ) PLIB_SPI_ExistsCommunicationWidth Function Identifies whether the CommunicationWidth feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsCommunicationWidth(SPI_MODULE_ID index); Returns • true - The CommunicationWidth feature is supported on the device • false - The CommunicationWidth feature is not supported on the device Description This function identifies whether the CommunicationWidth feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_CommunicationWidthSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsCommunicationWidth( SPI_MODULE_ID index ) Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1871 PLIB_SPI_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsEnableControl(SPI_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_Enable • PLIB_SPI_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsEnableControl( SPI_MODULE_ID index ) PLIB_SPI_ExistsErrorInterruptControl Function Identifies whether the ErrorInterruptControl feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsErrorInterruptControl(SPI_MODULE_ID index); Returns • true - The ErrorInterruptControl feature is supported on the device • false - The ErrorInterruptControl feature is not supported on the device Description This function identifies whether the ErrorInterruptControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_ErrorInterruptEnable • PLIB_SPI_ErrorInterruptDisable Remarks None. Preconditions None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1872 Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsErrorInterruptControl( SPI_MODULE_ID index ) PLIB_SPI_ExistsFIFOControl Function Identifies whether the FIFOControl feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFIFOControl(SPI_MODULE_ID index); Returns • true - The FIFOControl feature is supported on the device • false - The FIFOControl feature is not supported on the device Description This function identifies whether the FIFOControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_FIFOEnable • PLIB_SPI_FIFODisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFIFOControl( SPI_MODULE_ID index ) PLIB_SPI_ExistsFIFOCount Function Identifies whether the FIFOCount feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFIFOCount(SPI_MODULE_ID index); Returns • true - The FIFOCount feature is supported on the device • false - The FIFOCount feature is not supported on the device Description This function identifies whether the FIFOCount feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FIFOCountGet Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1873 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFIFOCount( SPI_MODULE_ID index ) PLIB_SPI_ExistsFIFOInterruptMode Function Identifies whether the FIFOInterruptMode feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFIFOInterruptMode(SPI_MODULE_ID index); Returns • true - The FIFOInterruptMode feature is supported on the device • false - The FIFOInterruptMode feature is not supported on the device Description This function identifies whether the FIFOInterruptMode feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FIFOInterruptModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFIFOInterruptMode( SPI_MODULE_ID index ) PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus Function Identifies whether the FIFOShiftRegisterEmptyStatus feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus(SPI_MODULE_ID index); Returns • true - The FIFOShiftRegisterEmptyStatus feature is supported on the device • false - The FIFOShiftRegisterEmptyStatus feature is not supported on the device Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1874 Description This function identifies whether the FIFOShiftRegisterEmptyStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FIFOShiftRegisterIsEmpty Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus( SPI_MODULE_ID index ) PLIB_SPI_ExistsFramedCommunication Function Identifies whether the FramedCommunication feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFramedCommunication(SPI_MODULE_ID index); Returns • true - The FramedCommunication feature is supported on the device • false - The FramedCommunication feature is not supported on the device Description This function identifies whether the FramedCommunication feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_FramedCommunicationEnable • PLIB_SPI_FramedCommunicationDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFramedCommunication( SPI_MODULE_ID index ) PLIB_SPI_ExistsFrameErrorStatus Function Identifies whether the FrameErrorStatus feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFrameErrorStatus(SPI_MODULE_ID index); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1875 Returns • true - The FrameErrorStatus feature is supported on the device • false - The FrameErrorStatus feature is not supported on the device Description This function identifies whether the FrameErrorStatus feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_FrameErrorStatusGet • PLIB_SPI_FrameErrorStatusClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFrameErrorStatus( SPI_MODULE_ID index ) PLIB_SPI_ExistsFrameSyncPulseCounter Function Identifies whether the FrameSyncPulseCounter feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFrameSyncPulseCounter(SPI_MODULE_ID index); Returns • true - The FrameSyncPulseCounter feature is supported on the device • false - The FrameSyncPulseCounter feature is not supported on the device Description This function identifies whether the FrameSyncPulseCounter feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulseCounterSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFrameSyncPulseCounter( SPI_MODULE_ID index ) PLIB_SPI_ExistsFrameSyncPulseDirection Function Identifies whether the FrameSyncPulseDirection feature exists on the SPI module. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1876 File plib_spi.h C bool PLIB_SPI_ExistsFrameSyncPulseDirection(SPI_MODULE_ID index); Returns • true - The FrameSyncPulseDirection feature is supported on the device • false - The FrameSyncPulseDirection feature is not supported on the device Description This function identifies whether the FrameSyncPulseDirection feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulseDirectionSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFrameSyncPulseDirection( SPI_MODULE_ID index ) PLIB_SPI_ExistsFrameSyncPulseEdge Function Identifies whether the FrameSyncPulseEdge feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFrameSyncPulseEdge(SPI_MODULE_ID index); Returns • true - The FrameSyncPulseEdge feature is supported on the device • false - The FrameSyncPulseEdge feature is not supported on the device Description This function identifies whether the FrameSyncPulseEdge feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulseEdgeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFrameSyncPulseEdge( SPI_MODULE_ID index ) Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1877 PLIB_SPI_ExistsFrameSyncPulsePolarity Function Identifies whether the FrameSyncPulsePolarity feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFrameSyncPulsePolarity(SPI_MODULE_ID index); Returns • true - The FrameSyncPulsePolarity feature is supported on the device • false - The FrameSyncPulsePolarity feature is not supported on the device Description This function identifies whether the FrameSyncPulsePolarity feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulsePolaritySelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsFrameSyncPulsePolarity( SPI_MODULE_ID index ) PLIB_SPI_ExistsFrameSyncPulseWidth Function Identifies whether the FrameSyncPulseWidth feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsFrameSyncPulseWidth(SPI_MODULE_ID index); Returns • true - The FrameSyncPulseWidth feature is supported on the device • false - The FrameSyncPulseWidth feature is not supported on the device Description This function identifies whether the FrameSyncPulseWidth feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulseWidthSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1878 Function PLIB_SPI_ExistsFrameSyncPulseWidth( SPI_MODULE_ID index ) PLIB_SPI_ExistsInputSamplePhase Function Identifies whether the InputSamplePhase feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsInputSamplePhase(SPI_MODULE_ID index); Returns • true - The InputSamplePhase feature is supported on the device • false - The InputSamplePhase feature is not supported on the device Description This function identifies whether the InputSamplePhase feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_InputSamplePhaseSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsInputSamplePhase( SPI_MODULE_ID index ) PLIB_SPI_ExistsMasterControl Function Identifies whether the MasterControl feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsMasterControl(SPI_MODULE_ID index); Returns • true - The MasterControl feature is supported on the device • false - The MasterControl feature is not supported on the device Description This function identifies whether the MasterControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_MasterEnable • PLIB_SPI_SlaveEnable Remarks None. Preconditions None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1879 Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsMasterControl( SPI_MODULE_ID index ) PLIB_SPI_ExistsOutputDataPhase Function Identifies whether the OutputDataPhase feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsOutputDataPhase(SPI_MODULE_ID index); Returns • true - The OutputDataPhase feature is supported on the device • false - The OutputDataPhase feature is not supported on the device Description This function identifies whether the OutputDataPhase feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_OutputDataPhaseSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsOutputDataPhase( SPI_MODULE_ID index ) PLIB_SPI_ExistsPinControl Function Identifies whether the PinControl feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsPinControl(SPI_MODULE_ID index); Returns • true - The PinControl feature is supported on the device • false - The PinControl feature is not supported on the device Description This function identifies whether the PinControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_PinEnable • PLIB_SPI_PinDisable Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1880 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsPinControl( SPI_MODULE_ID index ) PLIB_SPI_ExistsReadDataSignStatus Function Identifies whether the ReadDataSignStatus feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsReadDataSignStatus(SPI_MODULE_ID index); Returns • true - The ReadDataSignStatus feature is supported on the device • false - The ReadDataSignStatus feature is not supported on the device Description This function identifies whether the ReadDataSignStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_ReadDataIsSignExtended Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsReadDataSignStatus( SPI_MODULE_ID index ) PLIB_SPI_ExistsReceiveBufferStatus Function Identifies whether the ReceiveBufferStatus feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsReceiveBufferStatus(SPI_MODULE_ID index); Returns • true - The ReceiveBufferStatus feature is supported on the device • false - The ReceiveBufferStatus feature is not supported on the device Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1881 Description This function identifies whether the ReceiveBufferStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_ReceiverBufferIsFull Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsReceiveBufferStatus( SPI_MODULE_ID index ) PLIB_SPI_ExistsReceiveFIFOStatus Function Identifies whether the ReceiveFIFOStatus feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsReceiveFIFOStatus(SPI_MODULE_ID index); Returns • true - The ReceiveFIFOStatus feature is supported on the device • false - The ReceiveFIFOStatus feature is not supported on the device Description This function identifies whether the ReceiveFIFOStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_ReceiverFIFOIsEmpty Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsReceiveFIFOStatus( SPI_MODULE_ID index ) PLIB_SPI_ExistsReceiverOverflow Function Identifies whether the ReceiverOverflow feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsReceiverOverflow(SPI_MODULE_ID index); Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1882 Returns • true - The ReceiverOverflow feature is supported on the device • false - The ReceiverOverflow feature is not supported on the device Description This function identifies whether the ReceiverOverflow feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_ReceiverHasOverflowed • PLIB_SPI_ReceiverOverflowClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsReceiverOverflow( SPI_MODULE_ID index ) PLIB_SPI_ExistsSlaveSelectControl Function Identifies whether the SlaveSelectControl feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsSlaveSelectControl(SPI_MODULE_ID index); Returns • true - The SlaveSelectControl feature is supported on the device • false - The SlaveSelectControl feature is not supported on the device Description This function identifies whether the SlaveSelectControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_SlaveSelectEnable • PLIB_SPI_SlaveSelectDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsSlaveSelectControl( SPI_MODULE_ID index ) PLIB_SPI_ExistsStopInIdleControl Function Identifies whether the StopInIdle feature exists on the SPI module. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1883 File plib_spi.h C bool PLIB_SPI_ExistsStopInIdleControl(SPI_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_StopInIdleEnable • PLIB_SPI_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsStopInIdleControl( SPI_MODULE_ID index ) PLIB_SPI_ExistsTransmitBufferEmptyStatus Function Identifies whether the TransmitBufferEmptyStatus feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsTransmitBufferEmptyStatus(SPI_MODULE_ID index); Returns • true - The TransmitBufferEmptyStatus feature is supported on the device • false - The TransmitBufferEmptyStatus feature is not supported on the device Description This function identifies whether the TransmitBufferEmptyStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_TransmitBufferIsEmpty Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsTransmitBufferEmptyStatus( SPI_MODULE_ID index ) Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1884 PLIB_SPI_ExistsTransmitBufferFullStatus Function Identifies whether the TransmitBufferFullStatus feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsTransmitBufferFullStatus(SPI_MODULE_ID index); Returns • true - The TransmitBufferFullStatus feature is supported on the device • false - The TransmitBufferFullStatus feature is not supported on the device Description This function identifies whether the TransmitBufferFullStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_TransmitBufferIsFull Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsTransmitBufferFullStatus( SPI_MODULE_ID index ) PLIB_SPI_ExistsTransmitUnderRunStatus Function Identifies whether the TransmitUnderRunStatus feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_ExistsTransmitUnderRunStatus(SPI_MODULE_ID index); Returns • true - The TransmitUnderRunStatus feature is supported on the device • false - The TransmitUnderRunStatus feature is not supported on the device Description This function identifies whether the TransmitUnderRunStatus feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_TransmitUnderRunStatusGet • PLIB_SPI_TransmitUnderRunStatusClear Remarks None. Preconditions None. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1885 Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_ExistsTransmitUnderRunStatus( SPI_MODULE_ID index ) PLIB_SPI_Exists16bitBuffer Function Identifies whether the Buffer16bit feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_Exists16bitBuffer(SPI_MODULE_ID index); Returns • true - The Buffer16bit feature is supported on the device • false - The Buffer16bit feature is not supported on the device Description This function identifies whether the Buffer16bit feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_BufferRead16bit • PLIB_SPI_BufferWrite16bit Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_Exists16bitBuffer( SPI_MODULE_ID index ) PLIB_SPI_Exists32bitBuffer Function Identifies whether the Buffer32bit feature exists on the SPI module. File plib_spi.h C bool PLIB_SPI_Exists32bitBuffer(SPI_MODULE_ID index); Returns • true - The Buffer32bit feature is supported on the device • false - The Buffer32bit feature is not supported on the device Description This function identifies whether the Buffer32bit feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_BufferRead32bit • PLIB_SPI_BufferWrite32bit Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1886 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SPI_Exists32bitBuffer( SPI_MODULE_ID index ) h) Data Types and Constants SPI_AUDIO_COMMUNICATION_WIDTH Enumeration Defines the list of SPI audio communication width. File help_plib_spi.h C typedef enum { SPI_AUDIO_COMMUNICATION_24DATA_32FIFO_32CHANNEL, SPI_AUDIO_COMMUNICATION_32DATA_32FIFO_32CHANNEL, SPI_AUDIO_COMMUNICATION_16DATA_16FIFO_32CHANNEL, SPI_AUDIO_COMMUNICATION_16DATA_16FIFO_16CHANNEL } SPI_AUDIO_COMMUNICATION_WIDTH; Members Members Description SPI_AUDIO_COMMUNICATION_24DATA_32FIFO_32CHANNEL Communication is 24-bit Data,32-bit FIFO,32-bit Channel/64-bit Frame SPI_AUDIO_COMMUNICATION_32DATA_32FIFO_32CHANNEL Communication is 32-bit Data,32-bit FIFO,32-bit Channel/64-bit Frame SPI_AUDIO_COMMUNICATION_16DATA_16FIFO_32CHANNEL Communication is 16-bit Data,16-bit FIFO,32-bit Channel/64-bit Frame SPI_AUDIO_COMMUNICATION_16DATA_16FIFO_16CHANNEL Communication is 16-bit Data,16-bit FIFO,16-bit Channel/64-bit Frame Description SPI Audio Communication Width This macro defines the list of SPI audio communication width. SPI_AUDIO_ERROR Enumeration Defines the list of SPI audio error. File help_plib_spi.h C typedef enum { SPI_AUDIO_ERROR_RECEIVE_OVERFLOW, SPI_AUDIO_ERROR_TRANSMIT_UNDERRUN } SPI_AUDIO_ERROR; Members Members Description SPI_AUDIO_ERROR_RECEIVE_OVERFLOW SPI error for receive overflow SPI_AUDIO_ERROR_TRANSMIT_UNDERRUN SPI error for transmit underrun Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1887 Description SPI Audio Error This macro defines the list of SPI audio error. SPI_AUDIO_PROTOCOL Enumeration Data type defining the audio protocol mode. File help_plib_spi.h C typedef enum { SPI_AUDIO_PROTOCOL_PCM_DSP, SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED, SPI_AUDIO_PROTOCOL_LEFT_JUSTIFIED, SPI_AUDIO_PROTOCOL_I2S } SPI_AUDIO_PROTOCOL; Members Members Description SPI_AUDIO_PROTOCOL_PCM_DSP Audio protocol set to PCM/DSP mode SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED Audio protocol set to Right-Justified mode SPI_AUDIO_PROTOCOL_LEFT_JUSTIFIED Audio protocol set to Left-Justified mode SPI_AUDIO_PROTOCOL_I2S Audio protocol set to I2C mode Description Audio Protocol Mode enumeration This data type defining the audio protocol mode. Remarks This enumeration is processor specific. SPI_AUDIO_TRANSMIT_MODE Enumeration Defines the list of SPI transmit audio mode format. File help_plib_spi.h C typedef enum { SPI_AUDIO_TRANSMIT_MONO, SPI_AUDIO_TRANSMIT_STEREO } SPI_AUDIO_TRANSMIT_MODE; Members Members Description SPI_AUDIO_TRANSMIT_MONO SPI Transmit Audio Data Format is Mono SPI_AUDIO_TRANSMIT_STEREO SPI Transmit Audio Data Format is Stereo Description Audio Transmit mode format This macro defines the list of SPI transmit audio mode format. SPI_BAUD_RATE_CLOCK Enumeration Defines the list of SPI Baud Rate Generator (BRG). Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1888 File help_plib_spi.h C typedef enum { SPI_BAUD_RATE_MCLK_CLOCK, SPI_BAUD_RATE_PBCLK_CLOCK } SPI_BAUD_RATE_CLOCK; Members Members Description SPI_BAUD_RATE_MCLK_CLOCK MCLK is used by the Baud Rate Generator SPI_BAUD_RATE_PBCLK_CLOCK Peripheral bus clock is used by the Baud Rate Generator Description SPI Baud Rate Generator This macro defines the list of the SPI Baud Rate Generator. SPI_CLOCK_POLARITY Enumeration Defines the list of SPI clock polarity. File help_plib_spi.h C typedef enum { SPI_CLOCK_POLARITY_IDLE_HIGH, SPI_CLOCK_POLARITY_IDLE_LOW } SPI_CLOCK_POLARITY; Members Members Description SPI_CLOCK_POLARITY_IDLE_HIGH Idle state for clock is a high level;active state is a low level SPI_CLOCK_POLARITY_IDLE_LOW Idle state for clock is a low level;active state is a high level Description SPI Clock polarity This macro defines the list of SPI clock polarity. SPI_COMMUNICATION_WIDTH Enumeration Defines the list of SPI communication width. File help_plib_spi.h C typedef enum { SPI_COMMUNICATION_WIDTH_32BITS, SPI_COMMUNICATION_WIDTH_16BITS, SPI_COMMUNICATION_WIDTH_8BITS } SPI_COMMUNICATION_WIDTH; Members Members Description SPI_COMMUNICATION_WIDTH_32BITS Communication is 32-bit-wide SPI_COMMUNICATION_WIDTH_16BITS Communication is word-wide SPI_COMMUNICATION_WIDTH_8BITS Communication is byte-wide Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1889 Description SPI Communication Width This macro defines the list of SPI communication width. SPI_DATA_TYPE Type Data type defining the SPI data size. File help_plib_spi.h C typedef uint16_t SPI_DATA_TYPE; Description SPI Data Type definition This data type defines the SPI data size. SPI_ERROR_INTERRUPT Enumeration Defines the list of SPI error interrupts. File help_plib_spi.h C typedef enum { SPI_ERROR_INTERRUPT_FRAME_ERROR_OVERFLOW, SPI_ERROR_INTERRUPT_RECEIVE_OVERFLOW, SPI_ERROR_INTERRUPT_TRANSMIT_UNDERRUN } SPI_ERROR_INTERRUPT; Members Members Description SPI_ERROR_INTERRUPT_FRAME_ERROR_OVERFLOW SPI interrupt for frame error SPI_ERROR_INTERRUPT_RECEIVE_OVERFLOW SPI interrupt for receive overflow error SPI_ERROR_INTERRUPT_TRANSMIT_UNDERRUN SPI interrupt for transmit underrun error Description SPI Error Interrupt This macro defines the list of SPI error interrupts. SPI_FIFO_INTERRUPT Enumeration Defines the list of SPI Buffer Interrupt mode. File help_plib_spi.h C typedef enum { SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_NOT_FULL, SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_1HALF_EMPTY_OR_MORE, SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_COMPLETELY_EMPTY, SPI_FIFO_INTERRUPT_WHEN_TRANSMISSION_IS_COMPLETE, SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_FULL, SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_1HALF_FULL_OR_MORE, SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_NOT_EMPTY, SPI_FIFO_INTERRUPT_WHEN_BUFFER_IS_EMPTY } SPI_FIFO_INTERRUPT; Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1890 Members Members Description SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_NOT_FULL Interrupt when the transmit buffer is not full SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_1HALF_EMPTY_OR_MORE Interrupt when the transmit buffer is half empty SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_COMPLETELY_EMPTY Interrupt when the transmit buffer is empty SPI_FIFO_INTERRUPT_WHEN_TRANSMISSION_IS_COMPLETE Interrupt when transmission is complete SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_FULL Interrupt when receive buffer is full SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_1HALF_FULL_OR_MORE Interrupt when the receive buffer half full or more SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_NOT_EMPTY Interrupt when the receive buffer is not empty SPI_FIFO_INTERRUPT_WHEN_BUFFER_IS_EMPTY Interrupt when the receive buffer is empty Description SPI Buffer Interrupt Mode This macro defines the list of SPI Buffer Interrupt mode. SPI_FIFO_TYPE Enumeration Defines the list of SPI buffer mode. File help_plib_spi.h C typedef enum { SPI_FIFO_TYPE_TRNSMIT, SPI_FIFO_TYPE_RECEIVE } SPI_FIFO_TYPE; Members Members Description SPI_FIFO_TYPE_TRNSMIT Buffer type is transmit SPI_FIFO_TYPE_RECEIVE Buffer type is receive Description SPI Buffer Mode This macro defines the list of SPI buffer mode. SPI_FRAME_PULSE_DIRECTION Enumeration Defines the list of SPI frame sync pulse direction. File help_plib_spi.h C typedef enum { SPI_FRAME_PULSE_DIRECTION_OUTPUT, SPI_FRAME_PULSE_DIRECTION_INPUT } SPI_FRAME_PULSE_DIRECTION; Members Members Description SPI_FRAME_PULSE_DIRECTION_OUTPUT Frame sync pulse direction is output SPI_FRAME_PULSE_DIRECTION_INPUT Frame sync pulse direction is input Description SPI Frame sync pulse direction This macro defines the list of SPI frame sync pulse direction. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1891 SPI_FRAME_PULSE_EDGE Enumeration Defines the list of SPI frame sync pulse edge. File help_plib_spi.h C typedef enum { SPI_FRAME_PULSE_EDGE_COINCIDES_FIRST_BIT_CLOCK, SPI_FRAME_PULSE_EDGE_PRECEDES_FIRST_BIT_CLOCK } SPI_FRAME_PULSE_EDGE; Members Members Description SPI_FRAME_PULSE_EDGE_COINCIDES_FIRST_BIT_CLOCK Frame sync pulse coincides with first bit clock SPI_FRAME_PULSE_EDGE_PRECEDES_FIRST_BIT_CLOCK Frame sync pulse precedes first bit clock Description SPI Frame sync pulse edge This macro defines the list of SPI frame sync pulse edge. SPI_FRAME_PULSE_POLARITY Enumeration Defines the list of SPI frame sync pulse polarity. File help_plib_spi.h C typedef enum { SPI_FRAME_PULSE_POLARITY_ACTIVE_HIGH, SPI_FRAME_PULSE_POLARITY_ACTIVE_LOW } SPI_FRAME_PULSE_POLARITY; Members Members Description SPI_FRAME_PULSE_POLARITY_ACTIVE_HIGH Frame sync pulse is active high SPI_FRAME_PULSE_POLARITY_ACTIVE_LOW Frame sync pulse is active low Description SPI Frame sync pulse polarity This macro defines the list of SPI frame sync pulse polarity. SPI_FRAME_PULSE_WIDTH Enumeration Defines the list of SPI frame sync pulse width. File help_plib_spi.h C typedef enum { SPI_FRAME_PULSE_WIDTH_ONE_WORD_LENGTH, SPI_FRAME_PULSE_WIDTH_ONE_CLOCK_WIDE } SPI_FRAME_PULSE_WIDTH; Members Members Description SPI_FRAME_PULSE_WIDTH_ONE_WORD_LENGTH Frame sync Pulse width as one word length wide SPI_FRAME_PULSE_WIDTH_ONE_CLOCK_WIDE Frame sync Pulse width as one clock wide Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1892 Description SPI Frame sync pulse width This macro defines the list of SPI frame sync pulse width. SPI_FRAME_SYNC_PULSE Enumeration Data type defining the frame sync pulse counter values. File help_plib_spi.h C typedef enum { SPI_FRAME_SYNC_PULSE_ON_EVERY_32_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_16_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_4_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_2_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_DATA_CHARACTER } SPI_FRAME_SYNC_PULSE; Members Members Description SPI_FRAME_SYNC_PULSE_ON_EVERY_32_DATA_CHARACTER Generate a frame sync pulse on every 32 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_16_DATA_CHARACTER Generate a frame sync pulse on every 16 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER Generate a frame sync pulse on every 8 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_4_DATA_CHARACTER Generate a frame sync pulse on every 4 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_2_DATA_CHARACTER Generate a frame sync pulse on every 2 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_DATA_CHARACTER Generate a frame sync pulse on every data character Description Frame Sync Pulse Counter enumeration This data type defining the frame sync pulse counter values. SPI_INPUT_SAMPLING_PHASE Enumeration Defines the list of SPI data input sample phase. File help_plib_spi.h C typedef enum { SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE, SPI_INPUT_SAMPLING_PHASE_AT_END } SPI_INPUT_SAMPLING_PHASE; Members Members Description SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE SPI Data Input Sample phase in middle SPI_INPUT_SAMPLING_PHASE_AT_END SPI Data Input Sample phase at end Description SPI Data Input Sample Phase This macro defines the list of SPI data input sample phase. SPI_MODULE_ID Enumeration Identifies the supported SPI modules. Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1893 File help_plib_spi.h C typedef enum { SPI_ID_1, SPI_ID_2, SPI_ID_3, SPI_ID_4, SPI_NUMBER_OF_MODULES } SPI_MODULE_ID; Members Members Description SPI_ID_1 SPI Module 1 ID SPI_ID_2 SPI Module 2 ID SPI_ID_3 SPI Module 3 ID SPI_ID_4 SPI Module 4 ID SPI_NUMBER_OF_MODULES Number of available SPI modules. Description SPI Module ID This enumeration identifies the SPI modules that are available on a microcontroller. This is the superset of all the possible instances that might be available on Microchip microcontrollers. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. SPI_OUTPUT_DATA_PHASE Enumeration Defines the list of SPI serial output data changes. File help_plib_spi.h C typedef enum { SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK, SPI_OUTPUT_DATA_PHASE_ON_IDLE_TO_ACTIVE_CLOCK } SPI_OUTPUT_DATA_PHASE; Members Members Description SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK Serial output data changes on transition from active clock state to idle clock state SPI_OUTPUT_DATA_PHASE_ON_IDLE_TO_ACTIVE_CLOCK Serial output data changes on transition from idle clock state to active clock state. Description SPI Output Data Phase This macro defines the list of SPI serial output data changes. SPI_PIN Enumeration Data type defining the SPI pin. File help_plib_spi.h Peripheral Libraries Help SPI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1894 C typedef enum { SPI_PIN_DATA_OUT, SPI_PIN_DATA_IN, SPI_PIN_SLAVE_SELECT } SPI_PIN; Members Members Description SPI_PIN_DATA_OUT SPI data output pin SPI_PIN_DATA_IN SPI data input pin SPI_PIN_SLAVE_SELECT SPI slave select pin Description SPI pin This data type defining the SPI pin. Remarks This enumeration is processor specific. Files Files Name Description plib_spi.h SPI Peripheral Library Interface Header for common definitions. help_plib_spi.h Identifies the various enumerations in SPI modules supported Description This section lists the source and header files used by the library. plib_spi.h SPI Peripheral Library Interface Header for common definitions. Functions Name Description PLIB_SPI_AudioCommunicationWidthSelect Selects the data width for the SPI audio communication. PLIB_SPI_AudioErrorDisable Disables the SPI error. PLIB_SPI_AudioErrorEnable Enables the SPI error. PLIB_SPI_AudioProtocolDisable Audio protocol is disabled. PLIB_SPI_AudioProtocolEnable Audio protocol is enabled. PLIB_SPI_AudioProtocolModeSelect Selects the Audio Protocol mode. PLIB_SPI_AudioTransmitModeSelect Selects the transmit audio data format. PLIB_SPI_BaudRateClockSelect Selects the type of clock is used by the Baud Rate Generator. PLIB_SPI_BaudRateSet Sets the baud rate to the desired value. PLIB_SPI_BufferAddressGet Returns the address of the SPIxBUF (Transmit(SPIxTXB) and Receive (SPIxRXB)) register. PLIB_SPI_BufferClear Clears the SPI buffer. PLIB_SPI_BufferRead Returns the SPI buffer value. PLIB_SPI_BufferRead16bit Returns 16-bit SPI buffer value. PLIB_SPI_BufferRead32bit Returns 32-bit SPI buffer value. PLIB_SPI_BufferWrite Write the data to the SPI buffer. PLIB_SPI_BufferWrite16bit Writes 16-bit data to the SPI buffer. PLIB_SPI_BufferWrite32bit Write 32-bit data to the SPI buffer. PLIB_SPI_ClockPolaritySelect Enables clock polarity. PLIB_SPI_CommunicationWidthSelect Selects the data width for the SPI communication. PLIB_SPI_Disable Disables the SPI module. Peripheral Libraries Help SPI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1895 PLIB_SPI_Enable Enables the SPI module. PLIB_SPI_ErrorInterruptDisable Enables SPI error interrupts. PLIB_SPI_ErrorInterruptEnable Enables SPI error interrupts PLIB_SPI_Exists16bitBuffer Identifies whether the Buffer16bit feature exists on the SPI module. PLIB_SPI_Exists32bitBuffer Identifies whether the Buffer32bit feature exists on the SPI module. PLIB_SPI_ExistsAudioCommunicationWidth Identifies whether the AudioCommunicationWidth feature exists on the SPI module. PLIB_SPI_ExistsAudioErrorControl Identifies whether the AudioErrorControl feature exists on the SPI module. PLIB_SPI_ExistsAudioProtocolControl Identifies whether the AudioProtocolControl feature exists on the SPI module. PLIB_SPI_ExistsAudioProtocolMode Identifies whether the AudioProtocolMode feature exists on the SPI module. PLIB_SPI_ExistsAudioTransmitMode Identifies whether the AudioTransmitMode feature exists on the SPI module. PLIB_SPI_ExistsBaudRate Identifies whether the BaudRate feature exists on the SPI module. PLIB_SPI_ExistsBaudRateClock Identifies whether the BaudRateClock feature exists on the SPI module. PLIB_SPI_ExistsBuffer Identifies whether the Buffer feature exists on the SPI module. PLIB_SPI_ExistsBusStatus Identifies whether the BusStatus feature exists on the SPI module. PLIB_SPI_ExistsClockPolarity Identifies whether the ClockPolarity feature exists on the SPI module. PLIB_SPI_ExistsCommunicationWidth Identifies whether the CommunicationWidth feature exists on the SPI module. PLIB_SPI_ExistsEnableControl Identifies whether the EnableControl feature exists on the SPI module. PLIB_SPI_ExistsErrorInterruptControl Identifies whether the ErrorInterruptControl feature exists on the SPI module. PLIB_SPI_ExistsFIFOControl Identifies whether the FIFOControl feature exists on the SPI module. PLIB_SPI_ExistsFIFOCount Identifies whether the FIFOCount feature exists on the SPI module. PLIB_SPI_ExistsFIFOInterruptMode Identifies whether the FIFOInterruptMode feature exists on the SPI module. PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus Identifies whether the FIFOShiftRegisterEmptyStatus feature exists on the SPI module. PLIB_SPI_ExistsFramedCommunication Identifies whether the FramedCommunication feature exists on the SPI module. PLIB_SPI_ExistsFrameErrorStatus Identifies whether the FrameErrorStatus feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseCounter Identifies whether the FrameSyncPulseCounter feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseDirection Identifies whether the FrameSyncPulseDirection feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseEdge Identifies whether the FrameSyncPulseEdge feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulsePolarity Identifies whether the FrameSyncPulsePolarity feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseWidth Identifies whether the FrameSyncPulseWidth feature exists on the SPI module. PLIB_SPI_ExistsInputSamplePhase Identifies whether the InputSamplePhase feature exists on the SPI module. PLIB_SPI_ExistsMasterControl Identifies whether the MasterControl feature exists on the SPI module. PLIB_SPI_ExistsOutputDataPhase Identifies whether the OutputDataPhase feature exists on the SPI module. PLIB_SPI_ExistsPinControl Identifies whether the PinControl feature exists on the SPI module. PLIB_SPI_ExistsReadDataSignStatus Identifies whether the ReadDataSignStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiveBufferStatus Identifies whether the ReceiveBufferStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiveFIFOStatus Identifies whether the ReceiveFIFOStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiverOverflow Identifies whether the ReceiverOverflow feature exists on the SPI module. PLIB_SPI_ExistsSlaveSelectControl Identifies whether the SlaveSelectControl feature exists on the SPI module. PLIB_SPI_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the SPI module. PLIB_SPI_ExistsTransmitBufferEmptyStatus Identifies whether the TransmitBufferEmptyStatus feature exists on the SPI module. PLIB_SPI_ExistsTransmitBufferFullStatus Identifies whether the TransmitBufferFullStatus feature exists on the SPI module. PLIB_SPI_ExistsTransmitUnderRunStatus Identifies whether the TransmitUnderRunStatus feature exists on the SPI module. PLIB_SPI_FIFOCountGet Reads the SPI Buffer Element Count bits for either receive or transmit. PLIB_SPI_FIFODisable Disables the SPI enhanced buffer. PLIB_SPI_FIFOEnable Enables the SPI enhanced buffer. PLIB_SPI_FIFOInterruptModeSelect Selects the SPI buffer interrupt mode. PLIB_SPI_FIFOShiftRegisterIsEmpty Returns the current status of the SPI shift register. PLIB_SPI_FramedCommunicationDisable Disables framed SPI support. PLIB_SPI_FramedCommunicationEnable Enables framed SPI support. PLIB_SPI_FrameErrorStatusClear Clears the SPI frame error flag. PLIB_SPI_FrameErrorStatusGet Returns the current status of the SPI frame error. PLIB_SPI_FrameSyncPulseCounterSelect Selects at which character the SPI frame sync pulse is generated. PLIB_SPI_FrameSyncPulseDirectionSelect Selects the frame sync pulse direction. Peripheral Libraries Help SPI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1896 PLIB_SPI_FrameSyncPulseEdgeSelect Selects the frame sync pulse edge. PLIB_SPI_FrameSyncPulsePolaritySelect Selects the frame sync pulse polarity. PLIB_SPI_FrameSyncPulseWidthSelect Sets the frame sync pulse width. PLIB_SPI_InputSamplePhaseSelect Selects the SPI data input sample phase. PLIB_SPI_IsBusy Returns the current SPI module activity status. PLIB_SPI_MasterEnable Enables the SPI in Master mode. PLIB_SPI_OutputDataPhaseSelect Selects serial output data change. PLIB_SPI_PinDisable Enables the selected SPI pins. PLIB_SPI_PinEnable Enables the selected SPI pins. PLIB_SPI_ReadDataIsSignExtended Returns the current status of the receive (RX) FIFO sign-extended data. PLIB_SPI_ReceiverBufferIsFull Returns the current status of the SPI receive buffer. PLIB_SPI_ReceiverFIFOIsEmpty Returns the current status of the SPI receive FIFO. PLIB_SPI_ReceiverHasOverflowed Returns the current status of the SPI receiver overflow. PLIB_SPI_ReceiverOverflowClear Clears the SPI receive overflow flag. PLIB_SPI_SlaveEnable Enables the SPI in Slave mode. PLIB_SPI_SlaveSelectDisable Disables Master mode slave select. PLIB_SPI_SlaveSelectEnable Enables Master mode slave select. PLIB_SPI_StopInIdleDisable Continues module operation when the device enters Idle mode. PLIB_SPI_StopInIdleEnable Discontinues module operation when the device enters Idle mode. PLIB_SPI_TransmitBufferIsEmpty Returns the current status of the transmit buffer. PLIB_SPI_TransmitBufferIsFull Returns the current transmit buffer status of the SPI module. PLIB_SPI_TransmitUnderRunStatusClear Clears the SPI transmit underrun flag. PLIB_SPI_TransmitUnderRunStatusGet Returns the current status of the transmit underrun. Description SPI Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the SPI PLIB. File Name plib_spi.h Company Microchip Technology Inc. help_plib_spi.h Identifies the various enumerations in SPI modules supported Enumerations Name Description SPI_AUDIO_COMMUNICATION_WIDTH Defines the list of SPI audio communication width. SPI_AUDIO_ERROR Defines the list of SPI audio error. SPI_AUDIO_PROTOCOL Data type defining the audio protocol mode. SPI_AUDIO_TRANSMIT_MODE Defines the list of SPI transmit audio mode format. SPI_BAUD_RATE_CLOCK Defines the list of SPI Baud Rate Generator (BRG). SPI_CLOCK_POLARITY Defines the list of SPI clock polarity. SPI_COMMUNICATION_WIDTH Defines the list of SPI communication width. SPI_ERROR_INTERRUPT Defines the list of SPI error interrupts. SPI_FIFO_INTERRUPT Defines the list of SPI Buffer Interrupt mode. SPI_FIFO_TYPE Defines the list of SPI buffer mode. SPI_FRAME_PULSE_DIRECTION Defines the list of SPI frame sync pulse direction. SPI_FRAME_PULSE_EDGE Defines the list of SPI frame sync pulse edge. SPI_FRAME_PULSE_POLARITY Defines the list of SPI frame sync pulse polarity. SPI_FRAME_PULSE_WIDTH Defines the list of SPI frame sync pulse width. SPI_FRAME_SYNC_PULSE Data type defining the frame sync pulse counter values. SPI_INPUT_SAMPLING_PHASE Defines the list of SPI data input sample phase. Peripheral Libraries Help SPI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1897 SPI_MODULE_ID Identifies the supported SPI modules. SPI_OUTPUT_DATA_PHASE Defines the list of SPI serial output data changes. SPI_PIN Data type defining the SPI pin. Types Name Description SPI_DATA_TYPE Data type defining the SPI data size. Description This enumeration identifies the SPI modules that are available on a microcontroller. This is the superset of all the possible instances that might be available on Microchip microcontrollers. File Name help_plib_spi.h Company Microchip Technology Inc. Peripheral Libraries Help SPI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1898 SQI Peripheral Library This section describes the Serial Quad Interface (SQI) Peripheral Library. Introduction This library provides a low-level abstraction of the Serial Quad Interface (SQI) Peripheral that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the SQI module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The SQI module is a synchronous serial interface that provides access to serial Flash memories and other serial devices. The SQI bus interface consists of four data lines (SQID3-SQID0), a clock line (SQICLK), two select lines (SQICS0 and SQICS1) and the module supports single Lane (identical to SPI), dual Lane, and quad Lane interface modes. SQI operates in only master mode. The SQI module has configurable transmit and receive buffers, programmable baud rates through the internal clock divider, clock phase, and clock polarity control for efficient data operations. Transmit and receive buffers can be accessed through SQITXDATA and SQIRXDATA registers. Similarly, the control buffer can be accessed through the SQI1CON register and is mainly used to pipeline the operations. The SQI module operates in three transfer modes: DMA, PIO, and XIP using three data flow modes:SPI Mode 0 and Mode 3, and a high-speed Serial Flash mode . All three modes use the control buffer to pipeline the command/data sequences on the SQI bus. Following diagrams describe typical SQI hardware interface and software flow. Figure 1 shows the typical hardware interface of SQI module. Figure 1: Hardware Interface Diagram Refer to Section 46. "Serial Quad Interface (SQI)" (DS60001244), which is available on the Microchip website for additional details on control register information and operation. Using the Library This topic describes the basic architecture of the SQI Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_sqi.h The interface to the SQI peripheral library is defined in the plib_sqi.h header file, which is included by the peripheral library header file, Peripheral Libraries Help SQI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1899 peripheral.h. Any C language source (.c) file that uses the SQI peripheral library must include peripheral.h. Library File: The SQI peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the SQI module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description Before jumping into the software abstraction, it is important to understand the SQI hardware a little more in detail. Figure 2 provides a glimpse of SQI hardware block diagram. As shown the diagram the features of SQI are divided into multiple logic blocks and the SQI peripheral library provides APIs to configure the various logic block thus the features. The control and status SFRs block contains all the registers that are used to configure the SQI in a specific mode of operation. The PIO mode of operation of SQI requires a set of registers to be configured by the Host processor and writing to/ reading from the TXDATA and RXDATA registers. The XIP logic facilitates the SQI modules eXecute-In-Place mode of operation, where Host processor programs the set of registers that configure the XIP mode and the engine automatically reads the external Flash and the read data gets mapped into a direct memory region. Where as DMA mode requires the Host processor to program a set of buffer descriptors and instructs SQI to point to the address of those buffer descriptors for the reads and writes. As mentioned earlier there are 3 buffers; transmit, receive and control that are accessed through SQIxTXDATA, SQIxRXDATA, and SQIxCON registers, respectively. Figure 2: SQI Hardware Block Diagram The SQI Peripheral Library takes requests from application software or the SQI device driver and controls the SQI hardware as per the inputs passed to the Library Interface. Figure 3 provides the SQI peripheral library software abstraction_layer diagram. Peripheral Libraries Help SQI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1900 Figure 3: SQI Software Abstraction Model The major components are SQI Peripheral Library are: • Configuration Management • Interrupt Control and Status Management • DMA Mode Management Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the SQI module. Library Interface Section Description Mode Configuration Management Functions These functions are used to set up transfer mode (DMA/XIP/PIO), data mode (SPI Mode 0/Mode 3/Serial Flash), lane mode (single/dual/quad) and XIP control registers. Clock Configuration Management Functions These functions are used to enable the clock, set up a clock divider and check the status of the clock to see if it is stable. XIP Configuration Management Functions These functions are used to set up parameters for XIP mode of operation. PIO Mode Transfer Management Functions These functions are used to set up TXDATA, RXDATA registers and status checks. Interrupt Control and Status Management Functions These functions are used to control the interrupts. SQI supports only status type of interrupts (no error interrupts). DMA Buffer Address Management Functions These functions are used to set up the address of the base descriptor, check the address of the current descriptor DMA Buffer Descriptor Management Functions These functions are used to set up and control 4 words (BD_CTRL, BD_STATUS (reserved), BD_BUF_ADDR and BD_NEXT_PTR) DMA Control and Status Management Functions These functions are used to control the buffer descriptor fetch process and check the status during the buffer descriptor fetches. How the Library Works Note: Not all features are available on all devices. Refer to the "Serial Quad Interface (SQI)" chapter in the specific device data sheet for availability. Peripheral Libraries Help SQI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1901 Core Functionality SQI modules core functionality is to transfer data between the serial device (mostly quad Flash) attached and the PIC microcontroller. To achieve this, SQI module uses 3 transfer modes: DMA, PIO and XIP. Each transfer mode can be configured to use any of the 3 available data flow modes (Mode 0, Mode 3 and Serial Flash Mode) to achieve the transfers. DMA and PIO modes are typically used to transfer data and XIP mode is used for code execution. Each mode of operation requires setting-up the clock, selecting data flow mode and selecting lane mode and other parameters as required by the device driver or application. SQI peripheral library includes complete set of API necessary to perform these operations. The following sections describe the SQI core functionality in each mode of operation. XIP Mode Describes XIP mode. Description XIP (eXecute-In-Place) mode is mostly used to execute the code out of the attached serial Flash device. However, this mode can also be used to transfer data as deemed necessary. In order for SQI to operate in XIP mode, host processor would have to set up the two SFRs dedicated to the XIP mode in addition to SQI configuration and clock control SFRs. Please refer to the specific data sheet and family reference manual for the configuration details. Please note that all the XIP configuration values depend on the parameters of the interfaced serial Flash memory device. In XIP mode, reading values of any other SFRs return the contents of the serial Flash device, the way it is mapped. The following figure shows the XIP mode software flow. Notes: 1. This step configures the SQI configuration fields, SQIEN, CSEN, and DATAEN, with the exception of MODE<1:0>. 2. There are two XIP control registers: SQI1XCON1 and SQI1XCON2. Example: // Example is written to access SST26VF032 Flash device Peripheral Libraries Help SQI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1902 // Example assumes the Flash Device is connected to Chip Select 0 //Global defines #define SST26VF_HS_READ 0x0B #define SST26VF_MODE_CODE 0x0 #define SST26VF_MODE_BYTES 0x0 // Set up SQI Configuration Bits PLIB_SQI_Enable(SQI_ID_1); PLIB_SQI_CSOutputEnableSelect(SQI_ID_1, SQI_CS_OEN_0); PLIB_SQI_DataOutputEnableSelect(SQI_ID_1, SQI_DATA_OEN_QUAD); // Disable All Interrupts PLIB_SQI_InterruptDisable(SQI_ID_1, SQI_ALL_INT); PLIB_SQI_InterruptSignalDisable(SQI_ID_1, SQI_ALL_INT); // Set up SQI Transfer Clock PLIB_SQI_ClockDividerSet(SQI_ID_1,CLK_DIV_1); PLIB_SQI_ClockEnable(SQI_ID_1); while (!PLIB_SQI_ClockIsStable(SQI_ID_1)); // Configure XIP Control 1 SFR PLIB_SQI_XIPControlWord1Set (SQI_ID_1, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SST26VF_HS_READ, ADDR_BYTES_3, DUMMY_BYTES_2 ); // Configure XIP Control 2 SFR PLIB_SQI_XIPControlWord2Set (SQI_ID_1, SST26VF_MODE_CODE, MODE_BYTES_0, SQI_CS_0 ); // Set Transfer Mode to XIP PLIB_SQI_TransferModeSet(SQI_ID_1, SQI_XFER_MODE_XIP); // The SQI is now in XIP mode and should start fetching the code DMA Mode Describes DMA mode. Description DMA mode is used for higher throughput data transfers. In DMA mode, the SQI DMA engine controls the data transfers off-loading the host processor. However, the host processor would have to configure the buffer descriptor and some SQI control SFRs to initiate the DMA process. Once the transactions are in progress, the DMA will be in control and the host processor can get the control through the interrupts or by disabling the DMA. The following figure shows the DMA mode software flow. Peripheral Libraries Help SQI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1903 Notes: 1. Buffer descriptor is a data structure in memory containing 4 words (BD_CTRL, BD_STAT, BD_BUFADDR and BD_NXTPTR). 2. Base address register points to first buffer descriptor in the chain. Example: // Example is written to access SST26VF032 Flash device // Example assumes the Flash Device is connected to Chip Select 0 //Global defines #define SST26VF_EQIO 0x38 #define SST26VF_HS_READ 0x0B #define SST26VF_MODE_CODE 0x0 #define SST26VF_MODE_BYTES 0x0 #define NUMBER_OF_BDs 5 #define POLL_CON_VALUE 10 { // Set up the Buffer Descriptors for ( i=0; i <(NUMBER_OF_BDs-1); i++) { // Set up Buffer Descriptors. Handle structures as application // needs. // Configure SQI Control Fields PLIB_SQI_Enable(SQI_ID_1); PLIB_SQI_CSOutputEnableSelect(SQI_ID_1,SQI_CS_OEN_0); PLIB_SQI_DataOutputEnableSelect(SQI_ID_1,SQI_DATA_OEN_2); Peripheral Libraries Help SQI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1904 PLIB_SQI_BurstEnable(SQI_ID_1); PLIB_SQI_SerialModeSet(SQI_ID_1); PLIB_SQI_TransferModeSet(SQI_ID_1,SQI_XFER_MODE_PIO); // Configure the SQI Transfer Clock PLIB_SQI_ClockDividerSet(SQI_ID_1,CLK_DIV_4); PLIB_SQI_ClockEnable(SQI_ID_1); while (!PLIB_SQI_ClockIsStable(SQI_ID_1)); //Enable Buffer Descriptor Done and Packet Done Interrupts PLIB_SQI_InterruptEnable(SQI_ID_1,BDDONE); PLIB_SQI_InterruptSignalEnable(SQI_ID_1,BDDONE); PLIB_SQI_InterruptEnable(SQI_ID_1,PKTCOMP); PLIB_SQI_InterruptSignalEnable(SQI_ID_1,PKTCOMP); // Send EQIO(0x38) Command to SST26VF032 to Enable Quad Lane Mode // Note: These steps are not in the flow as these are specific to // one Flash Device (SST26VF032) PLIB_SQI_ChipSelectSet(SQI_ID_1,SQI_CS_0); PLIB_SQI_LaneModeSet(SQI_ID_1,SQI_SINGLE_LANE); PLIB_SQI_TransferCommandSet(SQI_ID_1,SQI_CMD_TRANSMIT); // Transfers 1 Command Byte, No Address/Dummy Bytes PLIB_SQI_TransferCountSet(SQI_ID_1, 0x1); PLIB_SQI_TransmitterDataSend(SQI_ID_1, SST26VF_EQIO); // Set the SQI in DMA Mode PLIB_SQI_TransferModeSet(SQI_ID_1,SQI_XFER_MODE_DMA); // Set up the Base Buffer Descriptor Address if (!PLIB_SQI_DMAIsActive(SQI_ID_1)) PLIB_SQI_DMABDBaseAddressSet(SQI_ID_1, (void *) (&MY_BASE_BD_STRUCT)); //Set up DMA Control Register PLIB_SQI_DMABDEnable(SQI_ID_1); PLIB_SQI_DMABDPollEnable(SQI_ID_1); // Set up DMA Polling If (PLIB_SQI_DMABDPollIsEnabled(SQI_ID_1)) // Poll DMA every 10 cycles PLIB_SQI_PollControlSet(SQI_ID_1, MY_POLL_CONTROL_VALUE); // Start the DMA Process - DMA Engine is now in Control If (PLIB_SQI_DMAIsEnabled(SQI_ID_1)) { if (!PLIB_SQI_DMAIsActive(MY_SQI_INSTANCE)) PLIB_SQI_DMABDFetchStart(SQI_ID_1); } } PIO Mode Describes PIO mode. Description PIO mode is mostly used for data transfers. In PIO mode, the SQI module is entirely under the control of host processor. For the SQI module to operate in PIO mode, the host processor would have to set up the configuration, control, and clock control SFRs. Once the transactions are in progress, the host processor can use interrupts and status flags to control the operation. Please refer to the specific device data sheet and family reference manual for the configuration details. The following figure shows the PIO mode software flow. Peripheral Libraries Help SQI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1905 Example: // Example is written to access SST26VF032 Flash device // Example assumes the Flash Device is connected to Chip Select 0 // Example reads the device ID of the SST26VF032 //Global defines #define FALSE 0 #define TRUE 1 #define SST26VF_EQIO 0x38 #define SST26VF_HS_READ 0x0B #define SST26VF_QJEDID_READ 0x9F #define SST26VF_JEDEC_ID 0xBF2602 { int32_t jedecID; // Set up SQI Configuration (SQI1CFG) Register PLIB_SQI_ConfigWordSet(MY_SQI_INSTANCE, 1, SQI_CS_OEN_0, SQI_DATA_OEN_QUAD, 0, 1, 0, 0, 0, SQI_DATA_FORMAT_MSBF, SQI_DATA_MODE_3, Peripheral Libraries Help SQI Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1906 SQI_XFER_MODE_PIO ); PLIB_SQI_ControlBufferThresholdSet(SQI_ID_1,4); // Enable Specific Interrupts PLIB_SQI_InterruptEnable(SQI_ID_1,TXEMPTY|RXFULL/TXTHRIE|RXTHRIE); // Set up SQI Transfer Clock PLIB_SQI_ClockDividerSet(SQI_ID_1,CLK_DIV_1); PLIB_SQI_ClockEnable(SQI_ID_1); while (!PLIB_SQI_ClockIsStable(SQI_ID_1)); // Set up SQI Transmit Command Threshold PLIB_SQI_TxCommandThresholdSet(SQI_ID_1,3); // Set up SQI Receive Buffer Threshold PLIB_SQI_TxBufferThresholdIntSet(SQI_ID_1,3); // Configure SQI Control Fields and Send EQIO(0x38) Command to // SST26VF032 to Enable Quad Lane Mode PLIB_SQI_ControlWordSet(MY_SQI_INSTANCE, 1, SQI_CS_1, SQI_LANE_SINGLE, SQI_CMD_TRANSMIT, 1 ); PLIB_SQI_ControlWordSet(MY_SQI_INSTANCE, 0, SQI_CS_1, SQI_LANE_QUAD, SQI_CMD_TRANSMIT, 1 ); PLIB_SQI_ControlWordSet(MY_SQI_INSTANCE, 0, SQI_CS_1, SQI_LANE_QUAD, SQI_CMD_RECEIVE, 3 ); if ( PLIB_SQI_InterruptFlagGet(SQI_ID_1,TXEMPTY) ) PLIB_SQI_TransmitData(SQI_ID_1, SST26VF_EQIO); //Configure SQI to read JEDEC-ID in Quad Mode if ( PLIB_SQI_InterruptFlagGet(SQI_ID_1,TXEMPTY) ) PLIB_SQI_TransmitData(SQI_ID_1, SST26VF_QJEDID_READ); if (PLIB_SQI_InterruptFlagGet(SQI_ID_1,RXFULL)) jedecID = PLIB_SQI_ReceiveData(SQI_ID_1); if (jedecID == SST26VF_JEDEC_ID) return TRUE; else return FALSE; } Configuring the Library The library is configured for the supported SQI module when the processor is chosen in the MPLAB X IDE. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1907 Library Interface a) Mode Configuration Management Functions Name Description PLIB_SQI_BurstEnable Sets the burst enable (BURSTEN) function for higher throughput. This function is an artifact of the System Bus architecture. PLIB_SQI_ClockDisable Disables the SQI transfer clock. PLIB_SQI_ControlBufferThresholdGet Returns the transmit buffer space in bytes. PLIB_SQI_ControlBufferThresholdSet Sets the control buffer threshold value. PLIB_SQI_ControlWordGet Get the SQI Control Word. PLIB_SQI_ControlWordSet Sets the SQI Control Word. PLIB_SQI_CSOutputEnableSelect Selects the output enables on SQI Chip Select pins. PLIB_SQI_DataFormatGet Returns the data format. PLIB_SQI_DataFormatSet Sets the data format to Least Significant Bit First (LSBF).. PLIB_SQI_DataModeSet Sets the SQI data mode of operation. PLIB_SQI_DataOutputEnableSelect Selects the output enables on SQI data outputs. PLIB_SQI_Disable Disables the SQI module. PLIB_SQI_Enable Enables the SQI module. PLIB_SQI_HoldClear Clears the hold function to be disabled on SQID3 in single and dual lane modes. PLIB_SQI_HoldGet Gets the status of HOLD function on SQID3 pin. PLIB_SQI_HoldSet Sets the hold function to be enabled on SQID3 in single or dual lane modes. PLIB_SQI_LaneModeGet Returns the lane mode (single/dual/quad). PLIB_SQI_LaneModeSet Sets the data lane mode (single/dual/quad). PLIB_SQI_NumberOfReceiveBufferReads Returns the number of receive buffer reads. PLIB_SQI_ReceiveData Reads the data from the receive buffer. PLIB_SQI_ReceiveLatchDisable Disables the receive latch so receive data is discarded when in transmit mode. PLIB_SQI_ReceiveLatchEnable Enables the receive latch so receive data is latched during transmit mode. PLIB_SQI_ReceiveLatchGet Returns the receive latch status in transmit mode. PLIB_SQI_SoftReset Issues a soft reset to the SQI module. PLIB_SQI_TransferModeGet Returns the SQI transfer mode of operation. PLIB_SQI_TransferModeSet Sets the SQI transfer mode of operation. PLIB_SQI_TransmitData Writes data into the SQI transmit buffer. PLIB_SQI_WriteProtectClear Clears the Write-Protect function to be disabled on SQID2 in single or dual lane modes. PLIB_SQI_WriteProtectGet Gets the state of the write-protect feature on SQID2. PLIB_SQI_WriteProtectSet Sets the write-protect feature to be enabled on SQID2 in single or dual lane modes only. PLIB_SQI_ConBufferSoftReset Issues a soft reset to the SQI control buffer. PLIB_SQI_RxBufferSoftReset Issues a soft reset to the SQI receive buffer. PLIB_SQI_TxBufferSoftReset Issues a soft reset to the SQI transmit buffer. PLIB_SQI_TapDelaySet Sets the tap delays. PLIB_SQI_DDRModeGet Return the SQI data rate mode (single/double) value. PLIB_SQI_DDRModeSet Sets SQI communication to DDR mode. b) Clock Configuration Management Functions Name Description PLIB_SQI_ClockDividerSet Sets the SQI clock (that drives the SQI protocol) divider value. Divides the base clock to generate the SQI clock. PLIB_SQI_ClockEnable Enables the SQI transfer clock. PLIB_SQI_ClockIsStable Returns SQI transfer clock state. c) XIP Configuration Management Functions Name Description PLIB_SQI_XIPAddressBytesGet Returns the number of address bytes. PLIB_SQI_XIPAddressBytesSet Sets the number of address bytes. PLIB_SQI_XIPChipSelectGet Returns the current active Chip Select. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1908 PLIB_SQI_XIPChipSelectSet Activates the Chip Select in XIP mode. PLIB_SQI_XIPControlWord1Get Get the XIP mode Control Word 1. PLIB_SQI_XIPControlWord1Set Sets the XIP mode Control Word 1. PLIB_SQI_XIPControlWord2Get Gets the XIP mode Control Word 2. PLIB_SQI_XIPControlWord2Set Sets the XIP mode Control Word 2. PLIB_SQI_XIPDummyBytesGet Sets the number of dummy bytes. PLIB_SQI_XIPDummyBytesSet Sets the number of dummy bytes. PLIB_SQI_XIPLaneModeSet Selects the lane (Single/Dual/Quad) mode for different transaction in XIP mode. PLIB_SQI_XIPModeBytesGet Returns the number of bytes used for mode code command. PLIB_SQI_XIPModeBytesSet Allocates the bytes for mode code command. PLIB_SQI_XIPModeCodeGet Returns the mode code op-code. PLIB_SQI_XIPModeCodeSet Sets the mode code command. PLIB_SQI_XIPReadOpcodeGet Returns the read op code in XIP mode. PLIB_SQI_XIPReadOpcodeSet Sets the read op code in XIP mode. PLIB_SQI_XIPControlWord3Get Gets the XIP mode Control Word 3. PLIB_SQI_XIPControlWord3Set Sets the XIP mode Control Word 3. PLIB_SQI_XIPControlWord4Get Gets the XIP mode Control Word 4. PLIB_SQI_XIPDDRModeSet Selects the rate mode (SDR/DDR) for different transactions in XIP mode. PLIB_SQI_XIPSDRCommandDDRDataGet Returns the SQI command in SDR mode and Data in DDR mode bit value. PLIB_SQI_XIPSDRCommandDDRDataSet Sets the SQI command in SDR mode. PLIB_SQI_XIPControlWord4Set Sets the XIP mode Control Word 4. d) PIO Mode Transfer Management Functions Name Description PLIB_SQI_ByteCountGet Returns the current transmit/receive count. PLIB_SQI_ByteCountSet Sets the transmit/receive count. PLIB_SQI_ChipSelectDeassertDisable Clears the Chip Select deassert. PLIB_SQI_ChipSelectDeassertEnable Sets the Chip Select deassert. PLIB_SQI_ChipSelectGet Returns the Chip Select that is currently active. PLIB_SQI_ChipSelectSet Activates the Chip Select. PLIB_SQI_ConfigWordGet Gets the SQI Configuration Word. PLIB_SQI_ConfigWordSet Sets SQI Configuration Word. PLIB_SQI_ReceiveBufferIsUnderrun Returns the status of receive buffer. PLIB_SQI_RxBufferThresholdGet Returns the receive command threshold. PLIB_SQI_RxBufferThresholdIntGet Sets the receive buffer threshold interrupt. PLIB_SQI_RxBufferThresholdIntSet Sets the receive buffer threshold for interrupt. PLIB_SQI_RxBufferThresholdSet Sets the receive command threshold. PLIB_SQI_TransferDirectionGet Returns the transfer command. PLIB_SQI_TransferDirectionSet Sets the transfer command. PLIB_SQI_TransmitBufferFreeSpaceGet Returns the number of transmit buffer words available. PLIB_SQI_TransmitBufferHasOverflowed Returns the current status of the transmit buffer. PLIB_SQI_TxBufferThresholdGet Returns the transmit command threshold value. PLIB_SQI_TxBufferThresholdIntGet Returns the value to trigger the transmit buffer threshold interrupt. PLIB_SQI_TxBufferThresholdIntSet Sets the value to trigger the transmit buffer threshold interrupt. PLIB_SQI_TxBufferThresholdSet Sets the transmit command threshold. e) Interrupt Control and Status Management Functions Name Description PLIB_SQI_InterruptDisable Disables the interrupt source. PLIB_SQI_InterruptEnable Enables the passed interrupt source. PLIB_SQI_InterruptFlagGet Return SQI Interrupt flag status. PLIB_SQI_InterruptIsEnabled Returns the interrupt state. PLIB_SQI_InterruptSignalDisable Disables the interrupt signal source. PLIB_SQI_InterruptSignalEnable Enables the passed interrupt signal source. PLIB_SQI_InterruptSignalIsEnabled Returns the interrupt signal state. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1909 PLIB_SQI_DataLineStatus Returns the logical status of the SQI data lines. PLIB_SQI_CommandStatusGet Returns the SQI command (transmit/receive/idle). PLIB_SQI_ConBufWordsAvailable Returns the number of control buffer words available. f) DMA Buffer Address Management Functions Name Description PLIB_SQI_DMABDBaseAddressGet Returns the address of the base buffer descriptor. PLIB_SQI_DMABDBaseAddressSet Sets the address of the base buffer descriptor. PLIB_SQI_DMABDCurrentAddressGet Returns the address of the current buffer descriptor in process. g) DMA Buffer Descriptor Management Functions Name Description PLIB_SQI_DMABDControlWordGet Returns Current Buffer Descriptor Control Word Information. PLIB_SQI_DMABDReceiveBufferCountGet Returns the receive buffer space in bytes. PLIB_SQI_DMABDReceiveBufferLengthGet Returns the receive length in bytes. PLIB_SQI_DMABDReceiveStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMABDTransmitBufferCountGet Returns the transmit buffer space in bytes. PLIB_SQI_DMABDTransmitBufferLengthGet Returns the transmit length in bytes. PLIB_SQI_DMABDTransmitStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMABDFetchStop Stops the DMA buffer descriptor fetch process. h) DMA Control and Status Management Functions Name Description PLIB_SQI_DMABDFetchStart Starts the DMA buffer descriptor fetch process. PLIB_SQI_DMABDIsBusy Returns whether or not the DMA Buffer Descriptor is busy. PLIB_SQI_DMABDPollCounterSet Sets the poll counter value. PLIB_SQI_DMABDPollDisable Disables the buffer descriptor polling. PLIB_SQI_DMABDPollEnable Enables the buffer descriptor polling. PLIB_SQI_DMABDPollIsEnabled Returns whether or not the DMA buffer descriptor poll is enabled. PLIB_SQI_DMABDStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMADisable Disables the built-in DMA logic. PLIB_SQI_DMAEnable Enables the built-in DMA logic. PLIB_SQI_DMAHasStarted Returns whether or no the DMA process has started. PLIB_SQI_DMAIsEnabled Returns whether or not DMA is enabled. i) Other Functions Name Description PLIB_SQI_StatusCheckSet Sets the Flash status check related control bits. j) Feature Existence Functions Name Description PLIB_SQI_ExistsBDBaseAddress Identifies whether the BDBaseAddress feature exists on the SQI module. PLIB_SQI_ExistsBDControlWord Identifies whether the BDControlWord feature exists on the SQI module. PLIB_SQI_ExistsBDCurrentAddress Identifies whether the BDCurrentAddress feature exists on the SQI module. PLIB_SQI_ExistsBDPollCount Identifies whether the BDPollCount feature exists on the SQI module. PLIB_SQI_ExistsBDPollingEnable Identifies whether the BDPollingEnable feature exists on the SQI module. PLIB_SQI_ExistsBDProcessState Identifies whether the BDProcessState feature exists on the SQI module. PLIB_SQI_ExistsBDRxBufCount Identifies whether the BDRxBufCount feature exists on the SQI module. PLIB_SQI_ExistsBDRxLength Identifies whether the BDRxLength feature exists on the SQI module. PLIB_SQI_ExistsBDRxState Identifies whether the BDRxState feature exists on the SQI module. PLIB_SQI_ExistsBDTxBufCount Identifies whether the BDTxBufCount feature exists on the SQI module. PLIB_SQI_ExistsBDTxLength Identifies whether the BDTxLength feature exists on the SQI module. PLIB_SQI_ExistsBDTxState Identifies whether the BDTxState feature exists on the SQI module. PLIB_SQI_ExistsBurstControl Identifies whether the BurstControl feature exists on the SQI module. PLIB_SQI_ExistsChipSelect Identifies whether the ChipSelect feature exists on the SQI module. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1910 PLIB_SQI_ExistsClockControl Identifies whether the ClockControl feature exists on the SQI module. PLIB_SQI_ExistsClockDivider Identifies whether the ClockDivider feature exists on the SQI module. PLIB_SQI_ExistsClockReady Identifies whether the ClockReady feature exists on the SQI module. PLIB_SQI_ExistsConBufThreshold Identifies whether the ConBufThreshold feature exists on the SQI module. PLIB_SQI_ExistsConfigWord Identifies whether the ConfigWord feature exists on the SQI module. PLIB_SQI_ExistsControlWord Identifies whether the ControlWord feature exists on the SQI module. PLIB_SQI_ExistsCSDeassert Identifies whether the CSDeassert feature exists on the SQI module. PLIB_SQI_ExistsCSOutputEnable Identifies whether the CSOutputEnable feature exists on the SQI module. PLIB_SQI_ExistsDataFormat Identifies whether the DataFormat feature exists on the SQI module. PLIB_SQI_ExistsDataModeControl Identifies whether the DataModeControl feature exists on the SQI module. PLIB_SQI_ExistsDataOutputEnable Identifies whether the DataOutputEnable feature exists on the SQI module. PLIB_SQI_ExistsDataPinStatus Identifies whether the DataPinStatus feature exists on the SQI module. PLIB_SQI_ExistsDmaEnable Identifies whether the DMAEnable feature exists on the SQI module. PLIB_SQI_ExistsDMAEngineBusy Identifies whether the DMAEngineBusy feature exists on the SQI module. PLIB_SQI_ExistsDMAProcessInProgress Identifies whether the DMAProcessInProgress feature exists on the SQI module. PLIB_SQI_ExistsEnableControl Identifies whether the EnableControl feature exists on the SQI module. PLIB_SQI_ExistsHoldPinControl Identifies whether the HoldPinControl feature exists on the SQI module. PLIB_SQI_ExistsInterruptControl Identifies whether the InterruptControl feature exists on the SQI module. PLIB_SQI_ExistsInterruptSignalControl Identifies whether the InterruptSignalControl feature exists on the SQI module. PLIB_SQI_ExistsInterruptStatus Identifies whether the InterruptStatus feature exists on the SQI module. PLIB_SQI_ExistsLaneMode Identifies whether the LaneMode feature exists on the SQI module. PLIB_SQI_ExistsReceiveLatch Identifies whether the ReceiveLatch feature exists on the SQI module. PLIB_SQI_ExistsRxBufferCount Identifies whether the RxBufferCount feature exists on the SQI module. PLIB_SQI_ExistsRxBufIntThreshold Identifies whether the RxBufIntThreshold feature exists on the SQI module. PLIB_SQI_ExistsRxBufThreshold Identifies whether the RxBufThreshold feature exists on the SQI module. PLIB_SQI_ExistsRxData Identifies whether the RxData feature exists on the SQI module. PLIB_SQI_ExistsRxUnderRun Identifies whether the RxUnderRun feature exists on the SQI module. PLIB_SQI_ExistsSoftReset Identifies whether the SoftReset feature exists on the SQI module. PLIB_SQI_ExistsTransferCommand Identifies whether the TransferCommand feature exists on the SQI module. PLIB_SQI_ExistsTransferCount Identifies whether the TransferCount feature exists on the SQI module. PLIB_SQI_ExistsTransferModeControl Identifies whether the TransferModeControl feature exists on the SQI module. PLIB_SQI_ExistsTxBufferFree Identifies whether the TxBufferFree feature exists on the SQI module. PLIB_SQI_ExistsTxBufIntThreshold Identifies whether the TxBufIntThreshold feature exists on the SQI module. PLIB_SQI_ExistsTxBufThreshold Identifies whether the TxBufThreshold feature exists on the SQI module. PLIB_SQI_ExistsTxData Identifies whether the TxData feature exists on the SQI module. PLIB_SQI_ExistsTxOverFlow Identifies whether the TxOverFlow feature exists on the SQI module. PLIB_SQI_ExistsWPPinControl Identifies whether the WPPinControl feature exists on the SQI module. PLIB_SQI_ExistsXIPChipSelect Identifies whether the XIPChipSelect feature exists on the SQI module. PLIB_SQI_ExistsXIPControlWord1 Identifies whether the XIPControlWord1 feature exists on the SQI module. PLIB_SQI_ExistsXIPControlWord2 Identifies whether the XIPControlWord2 feature exists on the SQI module. PLIB_SQI_ExistsXIPLaneMode Identifies whether the XIPLaneMode feature exists on the SQI module. PLIB_SQI_ExistsXIPModeBytes Identifies whether the XIPModeBytes feature exists on the SQI module. PLIB_SQI_ExistsXIPModeCode Identifies whether the XIPModeCode feature exists on the SQI module. PLIB_SQI_ExistsXIPNumberOfAddressBytes Identifies whether the XIPNumberOfAddressBytes feature exists on the SQI module. PLIB_SQI_ExistsXIPNumberOfDummyBytes Identifies whether the XIPNumberOfDummyBytes feature exists on the SQI module. PLIB_SQI_ExistsXIPReadOpCode Identifies whether the XIPReadOpCode feature exists on the SQI module. PLIB_SQI_ExistsCommandStatus Identifies whether the CommandStatus feature exists on the SQI module. PLIB_SQI_ExistsConBufAvailable Identifies whether the ConBufWordsAvailable feature exists on the SQI module. PLIB_SQI_ExistsConBufferSoftReset Identifies whether the control buffer soft reset feature exists on the SQI module. PLIB_SQI_ExistsDDRMode Identifies whether the DDRMode feature exists on the SQI module. PLIB_SQI_ExistsDMABDFetch Identifies whether the DMABDFetch feature exists on the SQI module. PLIB_SQI_ExistsRxBufferSoftReset Identifies whether the receive buffer soft reset feature exists on the SQI module. PLIB_SQI_ExistsStatusCheck Identifies whether the StatusCheckSet feature exists on the SQI module. PLIB_SQI_ExistsTapDelay Identifies whether the TapDelay feature exists on the SQI module. PLIB_SQI_ExistsTxBufferSoftReset Identifies whether the transmit buffer soft reset feature exists on the SQI module. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1911 PLIB_SQI_ExistsXIPControlWord3 Identifies whether the XIPControlWord3 feature exists on the SQI module. PLIB_SQI_ExistsXIPControlWord4 Identifies whether the XIPControlWord4 feature exists on the SQI module. PLIB_SQI_ExistsXIPDDRMode Identifies whether the XIPDDRMode feature exists on the SQI module. PLIB_SQI_ExistsXIPSDRCommandDDRData Identifies whether the XIPSDRCommandDDRData feature exists on the SQI module. k) Data Types and Constants Name Description SQI_ADDR_BYTES Defines the list of SQI address bytes. SQI_BD_CTRL_WORD Defines the list of SQI Buffer Descriptor control word. SQI_BD_STATE Defines the list of SQI Buffer Descriptor states. SQI_CLK_DIV Defines the list of SQI Clock Divider values. SQI_CS_NUM Defines the list of SQI Chip Selects. SQI_CS_OEN Defines the list of SQI Chip Selects on which output is enable. SQI_DATA_FORMAT Defines the Data Format Options available (LSBF/MSBF). SQI_DATA_MODE Defines the list of SQI Data modes. SQI_DATA_OEN Defines the list of SQI Data pins on which output is enabled. SQI_DATA_TYPE Data type defining the SQI Data size. SQI_DUMMY_BYTES Defines the list of SQI dummy bytes. SQI_INTERRUPTS Defines the list of SQI interrupts. SQI_LANE_MODE Defines the list of SQI Lane modes (single/dual/quad). SQI_MODE_BYTES Defines the list of SQI mode bytes. SQI_MODULE_ID Identifies the supported SQI modules. SQI_XFER_CMD Defines the list of SQI transfer commands. SQI_XFER_MODE Defines the list of SQI Transfer modes. Description This section describes the Application Programming Interface (API) functions of the SQI Peripheral Library. Refer to each section for a detailed description. a) Mode Configuration Management Functions PLIB_SQI_BurstEnable Function Sets the burst enable (BURSTEN) function for higher throughput. This function is an artifact of the System Bus architecture. File plib_sqi.h C void PLIB_SQI_BurstEnable(SQI_MODULE_ID index); Returns None. Description This function enables burst mode for higher throughput. Burst mode should always be enabled. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_BurstEnable(MY_SQI_INSTANCE); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1912 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_BurstEnable ( SQI_MODULE_ID index) PLIB_SQI_ClockDisable Function Disables the SQI transfer clock. File plib_sqi.h C void PLIB_SQI_ClockDisable(SQI_MODULE_ID index); Returns None. Description This function disables the SQI transfer clock (divided clock). Remarks SQICLK is disabled. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ClockDisable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_ClockDisable ( SQI_MODULE_ID index) PLIB_SQI_ControlBufferThresholdGet Function Returns the transmit buffer space in bytes. File plib_sqi.h C uint8_t PLIB_SQI_ControlBufferThresholdGet(SQI_MODULE_ID index); Returns Control buffer threshold space. Description This function returns the threshold value for the control buffer in bytes. Remarks None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1913 Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t conBufThres = PLIB_SQI_ControlBufferThresholdGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_ControlBufferThresholdGet( SQI_MODULE_ID index) PLIB_SQI_ControlBufferThresholdSet Function Sets the control buffer threshold value. File plib_sqi.h C void PLIB_SQI_ControlBufferThresholdSet(SQI_MODULE_ID index, uint8_t threshold); Returns None. Description This function sets the control buffer threshold value in bytes, that is used to signal control buffer threshold interrupts. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_CONBUF_THRESHOLD is the threshold value. PLIB_SQI_ControlBufferThresholdSet(MY_SQI_INSTANCE, MY_CONBUF_THRESHOLD); Parameters Parameters Description index Identifier for the device instance to be configured threshold Control buffer threshold Function void PLIB_SQI_ControlBufferThresholdSet( SQI_MODULE_ID index, uint8_t threshold) PLIB_SQI_ControlWordGet Function Get the SQI Control Word. File plib_sqi.h C uint32_t PLIB_SQI_ControlWordGet(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1914 Returns None. Description This function returns the SQI Control Word. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t sqiCon = PLIB_SQI_ControlWordGet (MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_SQI_ControlWordGet ( SQI_MODULE_ID index) PLIB_SQI_ControlWordSet Function Sets the SQI Control Word. File plib_sqi.h C void PLIB_SQI_ControlWordSet(SQI_MODULE_ID index, bool csDeassert, SQI_CS_NUM csNum, SQI_LANE_MODE laneMode, SQI_XFER_CMD command, uint16_t xferCount); Returns None. Description This function sets the SQI Control Word. This function is a combination of several functions in case the driver plans to write the complete Control Word. In PIO mode, the Control word is before each transfer Remarks Chip select is not actually asserted, only enabled to be asserted. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ControlWordSet(MY_SQI_INSTANCE, 1, SQI_CS_1, SQI_LANE_QUAD, SQI_CMD_TRANSMIT, 5 ); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1915 csDeassert Chip select deassert after transfer csNum Active Chip Select number (0/1) laneMode SQI lane mode (QUAL/DUAL/SINGLE) command Transfer command (TRANSMIT/RECIEVE/IDLE) xferCount Number of bytes to be transmitted/received Function void PLIB_SQI_ControlWordSet( SQI_MODULE_ID index, bool csDeassert, SQI_CS_NUM csNum, SQI_LANE_MODE laneMode, SQI_XFER_CMD command, uint16_t xferCount ) PLIB_SQI_CSOutputEnableSelect Function Selects the output enables on SQI Chip Select pins. File plib_sqi.h C void PLIB_SQI_CSOutputEnableSelect(SQI_MODULE_ID index, SQI_CS_OEN csPins); Returns None. Description This function enables the selected SQI chip selects as outputs. Remarks Chip select is not actually asserted, only enabled to be asserted. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_CSOutputEnableSelect(MY_SQI_INSTANCE, SQI_CS_OEN_0); Parameters Parameters Description index Identifier for the device instance to be configured csPins Chip select pins for which outputs are enabled Function void PLIB_SQI_CSOutputEnableSelect( SQI_MODULE_ID index, SQI_CS_OEN csPins) PLIB_SQI_DataFormatGet Function Returns the data format. File plib_sqi.h C SQI_DATA_FORMAT PLIB_SQI_DataFormatGet(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1916 Returns • true - Data Format is LSBF (i.e., LITTLE-ENDIAN) • false - Data Format is MSBF Description This function returns the SQI data format (LSBF or MSBF). Remarks Typical data format in most of systems is LITTLE-ENDIAN. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_DATA_FORMAT dataFormat = PLIB_SQI_DataFormatGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_DATA_FORMAT PLIB_SQI_DataFormatGet(SQI_MODULE_ID index) PLIB_SQI_DataFormatSet Function Sets the data format to Least Significant Bit First (LSBF).. File plib_sqi.h C void PLIB_SQI_DataFormatSet(SQI_MODULE_ID index, SQI_DATA_FORMAT dataformat); Returns None. Description This function sets the SQI data format to LSBF (i.e., LITTLE-ENDIAN). Remarks Typical data format in most of the Systems is LITTLE ENDIAN. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DataFormatSet(MY_SQI_INSTANCE, SQI_DATA_FORMAT_LSBF); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_DataFormatSet( SQI_MODULE_ID index, SQI_DATA_FORMAT dataformat) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1917 PLIB_SQI_DataModeSet Function Sets the SQI data mode of operation. File plib_sqi.h C void PLIB_SQI_DataModeSet(SQI_MODULE_ID index, SQI_DATA_MODE mode); Returns None. Description This function sets the data mode to be SPI Mode 0, SPI Mode 3, or Serial Flash. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and SQI_DATA_MODE_3 is an enum element. PLIB_SQI_DataModeSet(MY_SQI_INSTANCE, SQI_DATA_MODE_SF); Parameters Parameters Description index Identifier for the device instance to be configured mode Data mode (Mode 0/Mode 3) Function void PLIB_SQI_DataModeSet( SQI_MODULE_ID index, SQI_DATA_MODE mode) PLIB_SQI_DataOutputEnableSelect Function Selects the output enables on SQI data outputs. File plib_sqi.h C void PLIB_SQI_DataOutputEnableSelect(SQI_MODULE_ID index, SQI_DATA_OEN dataPins); Returns None. Description This function enables the selected SQI data lines as outputs. Remarks Chip select is not actually asserted, only enabled to be asserted. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DataOutputEnableSelect(MY_SQI_INSTANCE, SQI_DATA_OEN_DUAL); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1918 Parameters Parameters Description index Identifier for the device instance to be configured dataPins Data pins for which outputs are enabled Function void PLIB_SQI_DataOutputEnableSelect ( SQI_MODULE_ID index, SQI_DATA_OEN dataPins) PLIB_SQI_Disable Function Disables the SQI module. File plib_sqi.h C void PLIB_SQI_Disable(SQI_MODULE_ID index); Returns None. Description This function disables the SQI module. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_Disable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_Disable ( SQI_MODULE_ID index) PLIB_SQI_Enable Function Enables the SQI module. File plib_sqi.h C void PLIB_SQI_Enable(SQI_MODULE_ID index); Returns None. Description This function enables the SQI module. Remarks The SQICLK, SQICSx, SQID0, SQID1, SQID2, and SQID3 pins must be assigned to available RPn pins before use. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1919 Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_Enable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_Enable( SQI_MODULE_ID index ) PLIB_SQI_HoldClear Function Clears the hold function to be disabled on SQID3 in single and dual lane modes. File plib_sqi.h C void PLIB_SQI_HoldClear(SQI_MODULE_ID index); Returns None. Description This function sets SQID3 to be controlled by SQI for normal data operation. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_HoldClear(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_HoldClear ( SQI_MODULE_ID index) PLIB_SQI_HoldGet Function Gets the status of HOLD function on SQID3 pin. File plib_sqi.h C bool PLIB_SQI_HoldGet(SQI_MODULE_ID index); Returns SQID3 as HOLD pin value. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1920 Description This function gets the status of HOLD function on SQID3 pin. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool holdStatus = PLIB_SQI_HoldGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_HoldGet ( SQI_MODULE_ID index) PLIB_SQI_HoldSet Function Sets the hold function to be enabled on SQID3 in single or dual lane modes. File plib_sqi.h C void PLIB_SQI_HoldSet(SQI_MODULE_ID index); Returns None. Description This function sets the SQID3 pin to HIGH/LOW to be be used for hold function in single and dual lane modes for supported Flash memories. Remarks This function should be used only when SQI is in single/dual lane modes. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_HoldSet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_HoldSet ( SQI_MODULE_ID index) PLIB_SQI_LaneModeGet Function Returns the lane mode (single/dual/quad). File plib_sqi.h Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1921 C SQI_LANE_MODE PLIB_SQI_LaneModeGet(SQI_MODULE_ID index); Returns Lane mode (single/dual/quad). Description This function returns the number of lanes (single/dual/quad) used for transfers. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_LANE_MODE laneMode = PLIB_SQI_LaneModeGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_LANE_MODE PLIB_SQI_LaneModeGet (SQI_MODULE_ID index) PLIB_SQI_LaneModeSet Function Sets the data lane mode (single/dual/quad). File plib_sqi.h C void PLIB_SQI_LaneModeSet(SQI_MODULE_ID index, SQI_LANE_MODE mode); Returns None. Description This function sets the number of lanes (single/dual/quad) used for transfers. Remarks None. Preconditions Make sure the output enable is selected on the data lines using PLIB_SQI_DataOutputEnableSelect. The device needs to be programmed to the same mode that the SQI controller is set to (may require special commands). Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_LaneModeSet(MY_SQI_INSTANCE, SQI_LANE_QUAD); Parameters Parameters Description index Identifier for the device instance to be configured mode Lane mode (single/dual/quad) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1922 Function void PLIB_SQI_LaneModeSet ( SQI_MODULE_ID index, SQI_LANE_MODE mode) PLIB_SQI_NumberOfReceiveBufferReads Function Returns the number of receive buffer reads. File plib_sqi.h C uint8_t PLIB_SQI_NumberOfReceiveBufferReads(SQI_MODULE_ID index); Returns Number of Receive Buffer Reads. Description This function returns the number of receive buffer reads for debug purpose. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t rxBufReads = PLIB_SQI_ReceiveBufferReadsGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_ReceiveBufferReadsGet( SQI_MODULE_ID index) PLIB_SQI_ReceiveData Function Reads the data from the receive buffer. File plib_sqi.h C uint32_t PLIB_SQI_ReceiveData(SQI_MODULE_ID index); Returns None. Description This function reads the data from the SQI receive buffer. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1923 // application developer. uint32_t receivedData= PLIB_SQI_ReceiveData(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_SQI_ReceiveData ( SQI_MODULE_ID index) PLIB_SQI_ReceiveLatchDisable Function Disables the receive latch so receive data is discarded when in transmit mode. File plib_sqi.h C void PLIB_SQI_ReceiveLatchDisable(SQI_MODULE_ID index); Returns None. Description This function disables the receive latch, which disables the receive data to be latched in transmit mode. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ReceiveLatchDisable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_ReceiveLatchDisable ( SQI_MODULE_ID index) PLIB_SQI_ReceiveLatchEnable Function Enables the receive latch so receive data is latched during transmit mode. File plib_sqi.h C void PLIB_SQI_ReceiveLatchEnable(SQI_MODULE_ID index); Returns None. Description This function enables the receive latch, which latches receive data in transmit mode. Otherwise, receive data in transmit mode is discarded. Remarks As most of the SQI communication is half-duplex, enable this function only when it is absolutely required. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1924 Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ReceiveLatchEnable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_ReceiveLatchEnable ( SQI_MODULE_ID index) PLIB_SQI_ReceiveLatchGet Function Returns the receive latch status in transmit mode. File plib_sqi.h C bool PLIB_SQI_ReceiveLatchGet(SQI_MODULE_ID index); Returns • true - Receive latch is set • false - Receive latch is not set Description This function returns the receive latch status in transmit mode. Returns true, if latch is set (enabling latching of receive buffer data), false if latch is not set (disabling the latching of the receive buffer data). Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool rxLatch = PLIB_SQI_ReceiveLatchGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_ReceiveLatchGet ( SQI_MODULE_ID index) PLIB_SQI_SoftReset Function Issues a soft reset to the SQI module. File plib_sqi.h C void PLIB_SQI_SoftReset(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1925 Returns None. Description This function issues a software reset to the SQI module clearing all the read/write register, internal state machines and data buffers. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_SoftReset(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_SoftReset ( SQI_MODULE_ID index) PLIB_SQI_TransferModeGet Function Returns the SQI transfer mode of operation. File plib_sqi.h C SQI_XFER_MODE PLIB_SQI_TransferModeGet(SQI_MODULE_ID index); Returns Transfer mode (PIO/DMA/XIP). Description This function returns the SQI transfer mode of operation: PIO, DMA, or XIP. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_XFER_MODE xferMode = PLIB_SQI_TransferModeGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured. Function SQI_XFER_MODE PLIB_SQI_TransferModeGet (SQI_MODULE_ID index) PLIB_SQI_TransferModeSet Function Sets the SQI transfer mode of operation. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1926 File plib_sqi.h C void PLIB_SQI_TransferModeSet(SQI_MODULE_ID index, SQI_XFER_MODE mode); Returns None. Description This function sets the SQI transfer mode of operation, (PIO, DMA, or XIP. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and SQI_XFER_MODE_DMA is an enum element. PLIB_SQI_TransferModeSet(MY_SQI_INSTANCE, SQI_XFER_MODE_DMA); Parameters Parameters Description index Identifier for the device instance to be configured mode Transfer mode (PIO/DMA/XIP) Function void PLIB_SQI_TransferModeSet ( SQI_MODULE_ID index, SQI_XFER_MODE mode) PLIB_SQI_TransmitData Function Writes data into the SQI transmit buffer. File plib_sqi.h C void PLIB_SQI_TransmitData(SQI_MODULE_ID index, uint32_t data); Returns None. Description This function writes the data into the SQI transmit buffer, which will be eventually sent out on SQI bus. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_TRANSMIT_DATA is the data to be sent. PLIB_SQI_TransmitData(MY_SQI_INSTANCE, MY_TRANSMIT_DATA); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1927 data Data to be transmitted Function void PLIB_SQI_TransmitData ( SQI_MODULE_ID index, uint32_t data) PLIB_SQI_WriteProtectClear Function Clears the Write-Protect function to be disabled on SQID2 in single or dual lane modes. File plib_sqi.h C void PLIB_SQI_WriteProtectClear(SQI_MODULE_ID index); Returns None. Description This function disables the SQID2 pin to be used for write-protect. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_WriteProtectClear(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_WriteProtectClear ( SQI_MODULE_ID index) PLIB_SQI_WriteProtectGet Function Gets the state of the write-protect feature on SQID2. File plib_sqi.h C bool PLIB_SQI_WriteProtectGet(SQI_MODULE_ID index); Returns None. Description This function returns the write-protect feature status on the SQID2 pin. Remarks None. Preconditions None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1928 Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool wpStatus = PLIB_SQI_WriteProtectGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_WriteProtectGet ( SQI_MODULE_ID index) PLIB_SQI_WriteProtectSet Function Sets the write-protect feature to be enabled on SQID2 in single or dual lane modes only. File plib_sqi.h C void PLIB_SQI_WriteProtectSet(SQI_MODULE_ID index); Returns None. Description This function enables the SQID2 pin to be used for write-protect in single and dual lane modes for supported Flash memories. Remarks This function should be used only when SQI is in single/dual lane modes. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_WriteProtectSet (MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_WriteProtectSet ( SQI_MODULE_ID index) PLIB_SQI_ConBufferSoftReset Function Issues a soft reset to the SQI control buffer. File plib_sqi.h C void PLIB_SQI_ConBufferSoftReset(SQI_MODULE_ID index); Returns None. Description This function issues a soft reset to the SQI control buffer clearing all the data in the buffer and addresses. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1929 Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ConBufferSoftReset(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_ConBufferSoftReset ( SQI_MODULE_ID index) PLIB_SQI_RxBufferSoftReset Function Issues a soft reset to the SQI receive buffer. File plib_sqi.h C void PLIB_SQI_RxBufferSoftReset(SQI_MODULE_ID index); Returns None. Description This function issues a soft reset to the SQI receive buffer clearing all the data in the buffer and addresses. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_RxBufferSoftReset(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_RxBufferSoftReset ( SQI_MODULE_ID index) PLIB_SQI_TxBufferSoftReset Function Issues a soft reset to the SQI transmit buffer. File plib_sqi.h C void PLIB_SQI_TxBufferSoftReset(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1930 Returns None. Description This function issues a soft reset to the SQI transmit buffer clearing all the data in the buffer and addresses. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_TxBufferSoftReset(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_TxBufferSoftReset ( SQI_MODULE_ID index) PLIB_SQI_TapDelaySet Function Sets the tap delays. File plib_sqi.h C void PLIB_SQI_TapDelaySet(SQI_MODULE_ID index, uint8_t sdrClkInDly, uint8_t dataOutDly, uint8_t clkOutDly); Returns SQI command (transmit/receive/idle) that is currently being executed. Description Sets the tap delays that might be required at the higher interface speeds to handle data set-up and hold delays. Remarks This function should be used only when the SQI returns failures at maximum frequency. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. void PLIB_SQI_TapDelaySet(SQI_MODULE_ID index, 8, 0, 2 ); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_TapDelaySet( SQI_MODULE_ID index, Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1931 uint8_t sdrClkInDly, uint8_t dataOutDly, uint8_t clkOutDly ); PLIB_SQI_DDRModeGet Function Return the SQI data rate mode (single/double) value. File plib_sqi.h C bool PLIB_SQI_DDRModeGet(SQI_MODULE_ID index); Returns None. Description This function returns the SQI communication mode value. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool pioDDRMode = PLIB_SQI_DDRModeGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_DDRModeGet( SQI_MODULE_ID index) PLIB_SQI_DDRModeSet Function Sets SQI communication to DDR mode. File plib_sqi.h C void PLIB_SQI_DDRModeSet(SQI_MODULE_ID index); Returns None. Description This function sets SQI communication to DDR mode. Remarks None. Preconditions None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1932 Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DDRModeSet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_DDRModeSet( SQI_MODULE_ID index) b) Clock Configuration Management Functions PLIB_SQI_ClockDividerSet Function Sets the SQI clock (that drives the SQI protocol) divider value. Divides the base clock to generate the SQI clock. File plib_sqi.h C void PLIB_SQI_ClockDividerSet(SQI_MODULE_ID index, SQI_CLK_DIV clkDivider); Returns None. Description This function sets the SQI clock divider value. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ClockDividerSet(MY_SQI_INSTANCE, CLK_DIV_1); Parameters Parameters Description index Identifier for the device instance to be configured clkDivider Clock divider value Function void PLIB_SQI_ClockDividerSet ( SQI_MODULE_ID index, SQI_CLK_DIV clkDivider) PLIB_SQI_ClockEnable Function Enables the SQI transfer clock. File plib_sqi.h C void PLIB_SQI_ClockEnable(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1933 Returns None. Description This function enables the SQI transfer clock (divided clock). Remarks SQICLK is enabled. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ClockEnable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_ClockEnable ( SQI_MODULE_ID index) PLIB_SQI_ClockIsStable Function Returns SQI transfer clock state. File plib_sqi.h C bool PLIB_SQI_ClockIsStable(SQI_MODULE_ID index); Returns True if clock is stable and false if it is not. Description This function returns the SQI transfer clock state. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool clockState = PLIB_SQI_ClockIsStable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_ClockIsStable ( SQI_MODULE_ID index) c) XIP Configuration Management Functions Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1934 PLIB_SQI_XIPAddressBytesGet Function Returns the number of address bytes. File plib_sqi.h C SQI_ADDR_BYTES PLIB_SQI_XIPAddressBytesGet(SQI_MODULE_ID index); Returns Number of Address Bytes. Description This function returns the number of address bytes to be sent to the flash. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t addressBytes = PLIB_SQI_XIPAddressBytesGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_ADDR_BYTES PLIB_SQI_XIPAddressBytesGet (SQI_MODULE_ID index) PLIB_SQI_XIPAddressBytesSet Function Sets the number of address bytes. File plib_sqi.h C void PLIB_SQI_XIPAddressBytesSet(SQI_MODULE_ID index, SQI_ADDR_BYTES bytes); Returns None. Description This function sets the number of address bytes to be sent to the flash. Typical flash address bytes are 3 (24-bit address). Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPAddressBytesSet(MY_SQI_INSTANCE, ADDR_BYTES_3); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1935 Parameters Parameters Description index Identifier for the device instance to be configured bytes Number of address bytes Function void PLIB_SQI_XIPAddressBytesSet ( SQI_MODULE_ID index, SQI_ADDR_BYTES bytes) PLIB_SQI_XIPChipSelectGet Function Returns the current active Chip Select. File plib_sqi.h C SQI_CS_NUM PLIB_SQI_XIPChipSelectGet(SQI_MODULE_ID index); Returns None. Description This function returns the active Chip Select in XIP mode. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_CS_NUM xipCSActive = (PLIB_SQI_XIPChipSelectGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_CS_NUM PLIB_SQI_XIPChipSelectGet (SQI_MODULE_ID index) PLIB_SQI_XIPChipSelectSet Function Activates the Chip Select in XIP mode. File plib_sqi.h C void PLIB_SQI_XIPChipSelectSet(SQI_MODULE_ID index, SQI_CS_NUM csNum); Returns None. Description This function sets the Chip Select that is active in XIP mode. Remarks None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1936 Preconditions Make sure the Chip Select output enable is selected on the CS lines (PLIB_SQI_CSOutputEnableSelect). Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPChipSelectSet(MY_SQI_INSTANCE, SQI_CS_0); Parameters Parameters Description index Identifier for the device instance to be configured csNum Chip select number Function void PLIB_SQI_XIPChipSelectSet ( SQI_MODULE_ID index, SQI_CS_NUM csNum) PLIB_SQI_XIPControlWord1Get Function Get the XIP mode Control Word 1. File plib_sqi.h C uint32_t PLIB_SQI_XIPControlWord1Get(SQI_MODULE_ID index); Returns None. Description This function returns the XIP mode Control Word 1. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t xipCon1 = PLIB_SQI_XIPControlWord1Set (MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_SQI_XIPControlWord1Get ( SQI_MODULE_ID index) PLIB_SQI_XIPControlWord1Set Function Sets the XIP mode Control Word 1. File plib_sqi.h C void PLIB_SQI_XIPControlWord1Set(SQI_MODULE_ID index, SQI_DUMMY_BYTES dummyBytes, SQI_ADDR_BYTES addressBytes, uint8_t readOpcode, SQI_LANE_MODE dataLaneMode, SQI_LANE_MODE dummyLaneMode, SQI_LANE_MODE modeCodeLaneMode, SQI_LANE_MODE addressLaneMode, SQI_LANE_MODE cmdLaneMode); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1937 Returns None. Description This function sets XIP mode Control Word 1. This function combines work of multiple PLIB APIs and can be used by the driver where complete XIP Control Word 1 is being modified. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPControlWord1Set (MY_SQI_INSTANCE, DUMMY_BYTES_2, ADDR_BYTES_3, 0x0B, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, ); Parameters Parameters Description index Identifier for the device instance to be configured dummyBytes Number of dummy bytes (0-7) addressBytes Number of address bytes (0-4) readOpcode Quad flash read opcode (ex: 0x0B) dataLaneMode Number of SQI data lanes used for sending data bytes dummyLaneMode Number of SQI data lanes used for sending dummy bytes modeCodeLaneMode Number of SQI data lanes used for sending mode code addressLaneMode Number of SQI data lanes used for sending address cmdLaneMode Number of SQI data lanes used for sending command Function void PLIB_SQI_XIPControlWord1Set ( SQI_MODULE_ID index, SQI_DUMMY_BYTES dummyBytes, SQI_ADDR_BYTES addressBytes, uint8_t readOpcode, SQI_LANE_MODE dataLaneMode, SQI_LANE_MODE dummyLaneMode, SQI_LANE_MODE modeCodeLaneMode, SQI_LANE_MODE addressLaneMode, SQI_LANE_MODE cmdLaneMode ) PLIB_SQI_XIPControlWord2Get Function Gets the XIP mode Control Word 2. File plib_sqi.h C uint32_t PLIB_SQI_XIPControlWord2Get(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1938 Returns None. Description This function returns the XIP mode Control Word 2. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t xipCon2 = PLIB_SQI_XIPControlWord2Get (MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_SQI_XIPControlWord2Get ( SQI_MODULE_ID index) PLIB_SQI_XIPControlWord2Set Function Sets the XIP mode Control Word 2. File plib_sqi.h C void PLIB_SQI_XIPControlWord2Set(SQI_MODULE_ID index, SQI_CS_NUM devSelect, SQI_MODE_BYTES modeBytes, uint8_t modeCode); Returns None. Description This function sets XIP mode Control Word 2. This function combines work of multiple PLIB APIs and can be used by the driver where complete XIP Control Word 2 is being modified. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPControlWord2Set (MY_SQI_INSTANCE, SQI_CS_0, MODE_BYTES_0, 0x0 ); Parameters Parameters Description index Identifier for the device instance to be configured modeCode Mode code used for supported flash devices Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1939 modeBytes Number of mode code bytes devSelect Chip select for XIP mode Function void PLIB_SQI_XIPControlWord2Set ( SQI_MODULE_ID index, SQI_CS_NUM devSelect, SQI_MODE_BYTES modeBytes, uint8_t modeCode ) PLIB_SQI_XIPDummyBytesGet Function Sets the number of dummy bytes. File plib_sqi.h C SQI_DUMMY_BYTES PLIB_SQI_XIPDummyBytesGet(SQI_MODULE_ID index); Returns None. Description This function returns the number of dummy bytes to be sent to the flash after the address bytes, i.e., before doing a fast read. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t dummyBytes = PLIB_SQI_XIPDummyBytesGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_DUMMY_BYTES PLIB_SQI_XIPDummyBytesGet (SQI_MODULE_ID index) PLIB_SQI_XIPDummyBytesSet Function Sets the number of dummy bytes. File plib_sqi.h C void PLIB_SQI_XIPDummyBytesSet(SQI_MODULE_ID index, SQI_DUMMY_BYTES bytes); Returns None. Description This function sets the number of dummy bytes to be sent to the flash after the address bytes, i.e., before doing a fast read. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1940 Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPDummyBytesSet(MY_SQI_INSTANCE, DUMMY_BYTE_1); Parameters Parameters Description index Identifier for the device instance to be configured bytes Number of dummy bytes Function void PLIB_SQI_XIPDummyBytesSet ( SQI_MODULE_ID index, SQI_DUMMY_BYTES bytes) PLIB_SQI_XIPLaneModeSet Function Selects the lane (Single/Dual/Quad) mode for different transaction in XIP mode. File plib_sqi.h C void PLIB_SQI_XIPLaneModeSet(SQI_MODULE_ID index, SQI_LANE_MODE dataLanes, SQI_LANE_MODE dummyLanes, SQI_LANE_MODE modeLanes, SQI_LANE_MODE addrLanes, SQI_LANE_MODE cmdLanes); Returns None. Description This function selects the lane (Single/Dual/Quad) mode for different transaction in XIP mode. Remarks This function can't be called when in XIP mode. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPLaneModeSet(MY_SQI_INSTANCE, SQI_QUAD_SINGLE, SQI_QUAD_SINGLE, SQI_QUAD_SINGLE, SQI_QUAD_SINGLE, SQI_QUAD_SINGLE ); Parameters Parameters Description index Identifier for the device instance to be configured dataLanes Data lane mode (single/dual/quad) dummyLanes Dummy lane mode (single/dual/quad) modeLanes Mode lane mode (single/dual/quad) addrLanes Address lane mode (single/dual/quad) cmdLanes Command lane mode (single/dual/quad) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1941 Function void PLIB_SQI_XIPLaneModeSet ( SQI_MODULE_ID index, SQI_LANE_MODE dataLanes, SQI_LANE_MODE dummyLanes, SQI_LANE_MODE modeLanes, SQI_LANE_MODE addrLanes, SQI_LANE_MODE cmdLanes ) PLIB_SQI_XIPModeBytesGet Function Returns the number of bytes used for mode code command. File plib_sqi.h C SQI_MODE_BYTES PLIB_SQI_XIPModeBytesGet(SQI_MODULE_ID index); Returns Number of Bytes used for Mode Code Command. Description This function returns the number of bytes for the mode code command in XIP mode. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_MODE_BYTES modeCodeBytes = PLIB_SQI_XIPModeBytesGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_MODE_BYTES PLIB_SQI_XIPModeBytesGet (SQI_MODULE_ID index) PLIB_SQI_XIPModeBytesSet Function Allocates the bytes for mode code command. File plib_sqi.h C void PLIB_SQI_XIPModeBytesSet(SQI_MODULE_ID index, SQI_MODE_BYTES bytes); Returns None. Description This function sets the number of bytes for the mode code command in XIP mode. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1942 Remarks Refer to serial device data sheet for the details on this command. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPModeBytesSet(MY_SQI_INSTANCE, MODE_BYTES_0); Parameters Parameters Description index Identifier for the device instance to be configured bytes Number of bytes of Mode code Function void PLIB_SQI_XIPModeBytesSet ( SQI_MODULE_ID index, SQI_MODE_BYTES bytes) PLIB_SQI_XIPModeCodeGet Function Returns the mode code op-code. File plib_sqi.h C uint8_t PLIB_SQI_XIPModeCodeGet(SQI_MODULE_ID index); Returns Mode Code Opcode. Description This function returns the mode code command (opcode) in XIP mode for the devices that support it. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t modeCode = PLIB_SQI_XIPModeCodeGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_XIPModeCodeGet ( SQI_MODULE_ID index) PLIB_SQI_XIPModeCodeSet Function Sets the mode code command. File plib_sqi.h Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1943 C void PLIB_SQI_XIPModeCodeSet(SQI_MODULE_ID index, uint8_t code); Returns None. Description This function sets the mode code command in XIP mode for the supported flash devices. Remarks Some of the devices seems to support this command, refer to specific serial device data sheet for op-code and sequence details. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPModeCodeSet(MY_SQI_INSTANCE, MY_MODE_CODE); Parameters Parameters Description index Identifier for the device instance to be configured code Mode code (byte) Function void PLIB_SQI_XIPModeCodeSet ( SQI_MODULE_ID index, uint8_t code) PLIB_SQI_XIPReadOpcodeGet Function Returns the read op code in XIP mode. File plib_sqi.h C uint8_t PLIB_SQI_XIPReadOpcodeGet(SQI_MODULE_ID index); Returns Read Opcode. Description This function returns the read op code used in XIP mode. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t readOpcode = PLIB_SQI_XIPReadOpcodeGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_XIPReadOpcodeGet ( SQI_MODULE_ID index) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1944 PLIB_SQI_XIPReadOpcodeSet Function Sets the read op code in XIP mode. File plib_sqi.h C void PLIB_SQI_XIPReadOpcodeSet(SQI_MODULE_ID index, uint8_t opCode); Returns None. Description This function sets the flash read opcode in XIP mode. Value of read op code depends on the Flash device attached. Remarks Refer to the Flash device data sheet for supported read op codes. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_READ_OPCODE is the op code dependent on // attached serial device. PLIB_SQI_XIPReadOpcodeSet(MY_SQI_INSTANCE, MY_READ_OPCODE); Parameters Parameters Description index Identifier for the device instance to be configured opCode Flash read op code Function void PLIB_SQI_XIPReadOpcodeSet ( SQI_MODULE_ID index, uint8_t opCode ) PLIB_SQI_XIPControlWord3Get Function Gets the XIP mode Control Word 3. File plib_sqi.h C uint32_t PLIB_SQI_XIPControlWord3Get(SQI_MODULE_ID index); Returns None. Description This function returns the XIP mode Control Word 3. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1945 uint32_t xipCon3 = PLIB_SQI_XIPControlWord3Get (MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_SQI_XIPControlWord3Get ( SQI_MODULE_ID index) PLIB_SQI_XIPControlWord3Set Function Sets the XIP mode Control Word 3. File plib_sqi.h C void PLIB_SQI_XIPControlWord3Set(SQI_MODULE_ID index, bool initStatCheck, uint8_t initCmdCount, SQI_LANE_MODE initCmdType, uint8_t initCmd3, uint8_t initCmd2, uint8_t initCmd1); Returns None. Description This function sets XIP mode Control Word 3. This function is used to set multiple commands in XIP mode. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPControlWord2Set (MY_SQI_INSTANCE, 0, 3, SQI_LANE_QUAD, 0x06, //WEN 0x99, //RST 0x66 //RSTEN ); Parameters Parameters Description index Identifier for the device instance to be configured initStatCheck Flash status check at the end of initialization commands initCmdCount Number of mode code bytes initCmdType Chip select for XIP mode initCmd3 Command 3 initCmd2 Command 2 initCmd1 Command 1 Function void PLIB_SQI_XIPControlWord3Set ( SQI_MODULE_ID index, bool initStatCheck, uint8_t initCmdCount, SQI_LANE_MODE initCmdType, uint8_t initCmd3, uint8_t initCmd2, Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1946 uint8_t initCmd1 ) PLIB_SQI_XIPControlWord4Get Function Gets the XIP mode Control Word 4. File plib_sqi.h C uint32_t PLIB_SQI_XIPControlWord4Get(SQI_MODULE_ID index); Returns None. Description This function returns the XIP mode Control Word 4. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t xipCon4 = PLIB_SQI_XIPControlWord4Get (MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_SQI_XIPControlWord4Get ( SQI_MODULE_ID index) PLIB_SQI_XIPDDRModeSet Function Selects the rate mode (SDR/DDR) for different transactions in XIP mode. File plib_sqi.h C void PLIB_SQI_XIPDDRModeSet(SQI_MODULE_ID index); Returns None. Description This function selects the double data rate mode for different transactions (command, address, dummy and data etc.,) in XIP mode of operation Remarks This function can't be called when in XIP mode. The device is set in SDR mode if this function is not invoked. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1947 PLIB_SQI_XIPDDRModeSet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_XIPDDRModeSet ( SQI_MODULE_ID index) PLIB_SQI_XIPSDRCommandDDRDataGet Function Returns the SQI command in SDR mode and Data in DDR mode bit value. File plib_sqi.h C bool PLIB_SQI_XIPSDRCommandDDRDataGet(SQI_MODULE_ID index); Returns Returns true if the bit is set and false if it's cleared. Description This function returns the command to be transferred in SDR mode and data in DDR mode bit value. Some serial flash devices require the sequence to send command in SDR mode and the rest of the data (including address bytes) in DDR mode Remarks This function can't be called when in XIP mode. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool cmdsdrValue = PLIB_SQI_XIPSDRCommandDDRDataGet (MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_XIPSDRCommandDDRDataGet ( SQI_MODULE_ID index) PLIB_SQI_XIPSDRCommandDDRDataSet Function Sets the SQI command in SDR mode. File plib_sqi.h C void PLIB_SQI_XIPSDRCommandDDRDataSet(SQI_MODULE_ID index); Returns None. Description This function sets the command to be transferred in SDR mode and data in DDR mode. Some serial flash devices require the sequence to send command in SDR mode and the rest of the data (including address bytes) in DDR mode Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1948 Remarks This function can't be called when in XIP mode. This function has no affect if the set-up is working in single lane mode. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPSDRCommandDDRDataSet (MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_XIPSDRCommandDDRDataSet ( SQI_MODULE_ID index) PLIB_SQI_XIPControlWord4Set Function Sets the XIP mode Control Word 4. File plib_sqi.h C void PLIB_SQI_XIPControlWord4Set(SQI_MODULE_ID index, bool initStatCheck, uint8_t initCmdCount, SQI_LANE_MODE initCmdType, uint8_t initCmd3, uint8_t initCmd2, uint8_t initCmd1); Returns None. Description This function sets XIP mode Control Word 4. This function is used to set multiple commands in XIP mode. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPControlWord4Set (MY_SQI_INSTANCE, 0, 1, SQI_LANE_QUAD, 0x00, 0x00, 0xC7 //Chip Erase ); Parameters Parameters Description index Identifier for the device instance to be configured initStatCheck Flash status check at the end of initialization commands initCmdCount Number of mode code bytes initCmdType Chip select for XIP mode initCmd3 Command 3 initCmd2 Command 2 Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1949 initCmd1 Command 1 Function void PLIB_SQI_XIPControlWord4Set ( SQI_MODULE_ID index, bool initStatCheck, uint8_t initCmdCount, SQI_LANE_MODE initCmdType, uint8_t initCmd3, uint8_t initCmd2, uint8_t initCmd1 ) d) PIO Mode Transfer Management Functions PLIB_SQI_ByteCountGet Function Returns the current transmit/receive count. File plib_sqi.h C uint16_t PLIB_SQI_ByteCountGet(SQI_MODULE_ID index); Returns Transfer Count. Description This function returns the transmit/receive count, which is set by software and is actively controlled and maintained by hardware. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint16_t xferCount = PLIB_SQI_ByteCountGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured count Transmit/Receive count Function uint16_t PLIB_SQI_ByteCountGet ( SQI_MODULE_ID index) PLIB_SQI_ByteCountSet Function Sets the transmit/receive count. File plib_sqi.h C void PLIB_SQI_ByteCountSet(SQI_MODULE_ID index, uint16_t xferCount); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1950 Returns None. Description This function sets the number of bytes to transmit or receive, which is set by software and is actively controlled and maintained by hardware. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_XFER_COUNT is the transfer count. PLIB_SQI_ByteCountSet(MY_SQI_INSTANCE, MY_XFER_COUNT); Parameters Parameters Description index Identifier for the device instance to be configured count Transmit/Receive count Function void PLIB_SQI_ByteCountSet ( SQI_MODULE_ID index, uint16_t xferCount) PLIB_SQI_ChipSelectDeassertDisable Function Clears the Chip Select deassert. File plib_sqi.h C void PLIB_SQI_ChipSelectDeassertDisable(SQI_MODULE_ID index); Returns None. Description This function disables the Chip Select deassert. Chip Select stays asserted after transmission or reception of specified number of bytes. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ChipSelectDeassertDisable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_ChipSelectDeassertDisable( SQI_MODULE_ID index) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1951 PLIB_SQI_ChipSelectDeassertEnable Function Sets the Chip Select deassert. File plib_sqi.h C void PLIB_SQI_ChipSelectDeassertEnable(SQI_MODULE_ID index); Returns None. Description This function enables Chip Select deassert. Chip Select is deasserted after transmission or reception of the specified number of bytes. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ChipSelectDeassertEnable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_ChipSelectDeassertEnable ( SQI_MODULE_ID index) PLIB_SQI_ChipSelectGet Function Returns the Chip Select that is currently active. File plib_sqi.h C SQI_CS_NUM PLIB_SQI_ChipSelectGet(SQI_MODULE_ID index); Returns Chip Select (2-bit) - Current Chip Select active (0/1). Description This function returns the Chip Select that is currently active. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_CS_NUM csNum = PLIB_SQI_ChipSelectGet(MY_SQI_INSTANCE); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1952 Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_CS_NUM PLIB_SQI_ChipSelectGet(SQI_MODULE_ID index) PLIB_SQI_ChipSelectSet Function Activates the Chip Select. File plib_sqi.h C void PLIB_SQI_ChipSelectSet(SQI_MODULE_ID index, SQI_CS_NUM csNum); Returns None. Description This function sets the Chip Select to be activated on the next transaction. Remarks None. Preconditions Make sure the Chip Select output enable is selected on the CS lines (PLIB_SQI_CSOutputEnableSelect). Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and SQI_CS_NUM_0 is the enum element. PLIB_SQI_ChipSelectSet(MY_SQI_INSTANCE, SQI_CS_NUM_0); Parameters Parameters Description index Identifier for the device instance to be configured csNum Chip select number Function void PLIB_SQI_ChipSelectSet ( SQI_MODULE_ID index, SQI_CS_NUM csNum) PLIB_SQI_ConfigWordGet Function Gets the SQI Configuration Word. File plib_sqi.h C uint32_t PLIB_SQI_ConfigWordGet(SQI_MODULE_ID index); Returns None. Description This function returns the SQI Configuration Word. Remarks None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1953 Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t sqiCfg = PLIB_SQI_ConfigWordGet (MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_SQI_ConfigWordGet ( SQI_MODULE_ID index) PLIB_SQI_ConfigWordSet Function Sets SQI Configuration Word. File plib_sqi.h C void PLIB_SQI_ConfigWordSet(SQI_MODULE_ID index, bool sqiEnable, SQI_CS_OEN csPins, SQI_DATA_OEN dataPins, bool reset, bool burstEn, bool hold, bool writeProtect, bool rxLatch, SQI_DATA_FORMAT lsbf, SQI_DATA_MODE dataMode, SQI_XFER_MODE xferMode); Returns None. Description This function sets the SQI Configuration Word. This function is a combination of several function in case the driver plans to write the complete Configuration Word. Remarks Chip select is not actually asserted, only enabled to be asserted. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ConfigWordSet(MY_SQI_INSTANCE, 1, SQI_CS_OEN_0, SQI_DATA_OEN_QUAD, 0, 1, 0, 0, 0, SQI_DATA_FORMAT_LSBF, SQI_DATA_MODE_3, SQI_XFER_MODE_PIO ); Parameters Parameters Description index Identifier for the device instance to be configured sqiEnable Enables/Disables the SQI module csPins Chip Select Output Enable Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1954 dataPins Data Output Enable reset Resets control, transmit, receive buffers and state machines burstEn Burst Enable (always set to '1') hold SQID2 to act as HOLD# signal in single and dual lane modes writeProtect SQID3 to act as WP# signal in single and dual lane modes rxLatch Activates receive latch in transmit mode lsbf Sets data endian mode to least significant bit first (LSBF) dataMode Sets data mode to mode 0/mode 1/Serial Flash mode xferMode Sets transfer mode to XIP/DMA/PIO mode Function void PLIB_SQI_ConfigWordSet( SQI_MODULE_ID index, bool sqiEnable, SQI_CS_OEN csPins, SQI_DATA_OEN dataPins, bool reset, bool burstEn, bool hold, bool writeProtect, bool rxLatch, SQI_DATA_FORMAT lsbf, SQI_DATA_MODE dataMode, SQI_XFER_MODE xferMode ) PLIB_SQI_ReceiveBufferIsUnderrun Function Returns the status of receive buffer. File plib_sqi.h C bool PLIB_SQI_ReceiveBufferIsUnderrun(SQI_MODULE_ID index); Returns • true - Receive Buffer is underrun • false - Receive Buffer is not underrun Description This function returns the status of the receive buffer. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool rxun = PLIB_SQI_ReceiveBufferIsUnderrun(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_ReceiveBufferIsUnderrun ( SQI_MODULE_ID index) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1955 PLIB_SQI_RxBufferThresholdGet Function Returns the receive command threshold. File plib_sqi.h C uint8_t PLIB_SQI_RxBufferThresholdGet(SQI_MODULE_ID index); Returns Receive Buffer Threshold value. Description This function returns the receive command threshold that is used to monitor receives based on the receive buffer space availability. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t rxBufThres = PLIB_SQI_RxCommandThresholdGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_RxBufferThresholdGet ( SQI_MODULE_ID index) PLIB_SQI_RxBufferThresholdIntGet Function Sets the receive buffer threshold interrupt. File plib_sqi.h C uint8_t PLIB_SQI_RxBufferThresholdIntGet(SQI_MODULE_ID index); Returns Receive Buffer Threshold value (used to trigger an interrupt). Description This function returns the receive buffer threshold used to set an interrupt. Remarks This is a 5-bit field and bits 7, 6, and 5 are ignored in the char. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t rxBufIntThres = PLIB_SQI_RxBufferThresholdIntGet(MY_SQI_INSTANCE); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1956 Parameters Parameters Description index Identifier for the device instance to be configured threshold Receive interrupt (buffer) threshold Function uint8_t PLIB_SQI_RxBufferThresholdIntGet ( SQI_MODULE_ID index) PLIB_SQI_RxBufferThresholdIntSet Function Sets the receive buffer threshold for interrupt. File plib_sqi.h C void PLIB_SQI_RxBufferThresholdIntSet(SQI_MODULE_ID index, uint8_t threshold); Returns None. Description This function sets the receive buffer threshold used to trigger an interrupt. Sets an interrupt condition when receive buffer count is larger than or equal to the receive interrupt threshold bytes. Remarks This is a 5-bit field and bits 7,6,5 are ignored in the char. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_RX_INT_THRESHOLD is the threshold value. PLIB_SQI_RxBufferThresholdIntSet(MY_SQI_INSTANCE, MY_RX_INT_THRESHOLD); Parameters Parameters Description index Identifier for the device instance to be configured threshold Receive buffer threshold for interrupt Function void PLIB_SQI_RxBufferThresholdIntSet ( SQI_MODULE_ID index, uint8_t threshold) PLIB_SQI_RxBufferThresholdSet Function Sets the receive command threshold. File plib_sqi.h C void PLIB_SQI_RxBufferThresholdSet(SQI_MODULE_ID index, uint8_t threshold); Returns None. Description This function sets the receive command threshold that is used to monitor receives based on the receive buffer space availability. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1957 Remarks Valid threshold values are 0-31. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_RECEIVE_THRESHOLD is the receive threshold value. PLIB_SQI_RxCommandThresholdSet(MY_SQI_INSTANCE, MY_RECEIVE_THRESHOLD); Parameters Parameters Description index Identifier for the device instance to be configured threshold Receive command (buffer) threshold Function void PLIB_SQI_RxBufferThresholdSet ( SQI_MODULE_ID index, uint8_t threshold) PLIB_SQI_TransferDirectionGet Function Returns the transfer command. File plib_sqi.h C SQI_XFER_CMD PLIB_SQI_TransferDirectionGet(SQI_MODULE_ID index); Returns Transfer Command (Idle/Receive/Transmit). Description This function returns the transfer command that is active currently. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_XFER_CMD xferDirection = PLIB_SQI_TransferDirectionGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_XFER_CMD PLIB_SQI_TransferDirectionGet (SQI_MODULE_ID index) PLIB_SQI_TransferDirectionSet Function Sets the transfer command. File plib_sqi.h Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1958 C void PLIB_SQI_TransferDirectionSet(SQI_MODULE_ID index, SQI_XFER_CMD command); Returns None. Description This function sets the transfer command to Idle/Transmit/Receive. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and SQI_CMD_TRANSMIT is an enum element. PLIB_SQI_TransferDirectionSet(MY_SQI_INSTANCE, SQI_CMD_TRANSMIT); Parameters Parameters Description index Identifier for the device instance to be configured command Transfer command Function void PLIB_SQI_TransferDirectionSet ( SQI_MODULE_ID index, SQI_XFER_CMD command) PLIB_SQI_TransmitBufferFreeSpaceGet Function Returns the number of transmit buffer words available. File plib_sqi.h C uint8_t PLIB_SQI_TransmitBufferFreeSpaceGet(SQI_MODULE_ID index); Returns Amount of transmit buffer space free in bytes. Description This function returns the number of transmit buffer bytes available. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t txBufFreeSpace = PLIB_SQI_TransmitBufferFreeSpaceGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_TransmitBufferFreeSpaceGet( SQI_MODULE_ID index) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1959 PLIB_SQI_TransmitBufferHasOverflowed Function Returns the current status of the transmit buffer. File plib_sqi.h C bool PLIB_SQI_TransmitBufferHasOverflowed(SQI_MODULE_ID index); Returns • true - Transmit Buffer has overflowed • false - Transmit Buffer has not overflowed Description This function returns the current state of the transmit buffer. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool txOv = PLIB_SQI_TransmitBufferHasOverflowed(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_TransmitBufferHasOverflowed ( SQI_MODULE_ID index) PLIB_SQI_TxBufferThresholdGet Function Returns the transmit command threshold value. File plib_sqi.h C uint8_t PLIB_SQI_TxBufferThresholdGet(SQI_MODULE_ID index); Returns Transmit buffer threshold value. Description This function returns the transmit command threshold value that is used to monitor transmits based on the transmit buffer space availability. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t txThreshold = PLIB_SQI_TxBufferThresholdGet(MY_SQI_INSTANCE); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1960 Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_TxBufferThresholdGet( SQI_MODULE_ID index) PLIB_SQI_TxBufferThresholdIntGet Function Returns the value to trigger the transmit buffer threshold interrupt. File plib_sqi.h C uint8_t PLIB_SQI_TxBufferThresholdIntGet(SQI_MODULE_ID index); Returns Transmit buffer threshold for interrupt. Description This function returns the transmit buffer threshold used to set an interrupt. When enabled, interrupt is triggered when transmit buffer has more space than the transmit interrupt threshold bytes. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t txBufIntThres = PLIB_SQI_TxBufferThresholdIntGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_TxBufferThresholdIntGet ( SQI_MODULE_ID index) PLIB_SQI_TxBufferThresholdIntSet Function Sets the value to trigger the transmit buffer threshold interrupt. File plib_sqi.h C void PLIB_SQI_TxBufferThresholdIntSet(SQI_MODULE_ID index, uint8_t threshold); Returns None. Description This function sets the transmit buffer threshold used for an interrupt. When enabled, interrupt is triggered when transmit buffer has more space than the transmit interrupt threshold bytes. Remarks This is a 5-bit field and bits 7,6,5 are ignored in the char. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1961 Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_TX_INT_THRESHOLD is the threshold value. PLIB_SQI_TxBufferThresholdIntSet(MY_SQI_INSTANCE, MY_TX_INT_THRESHOLD); Parameters Parameters Description index Identifier for the device instance to be configured threshold Transmit interrupt (buffer) threshold Function void PLIB_SQI_TxBufferThresholdIntSet ( SQI_MODULE_ID index, uint8_t threshold) PLIB_SQI_TxBufferThresholdSet Function Sets the transmit command threshold. File plib_sqi.h C void PLIB_SQI_TxBufferThresholdSet(SQI_MODULE_ID index, uint8_t threshold); Returns None. Description This function sets the transmit command threshold, which is used to control transmits based on the transmit buffer space availability. Remarks Valid threshold values are 0-31. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_TRANSMIT_THRESHOLD is the threshold value. PLIB_SQI_TxBufferThresholdSet(MY_SQI_INSTANCE, MY_TRANSMIT_THRESHOLD); Parameters Parameters Description index Identifier for the device instance to be configured threshold Transmit command (buffer) threshold Function void PLIB_SQI_TxBufferThresholdSet( SQI_MODULE_ID index, uint8_t threshold) e) Interrupt Control and Status Management Functions PLIB_SQI_InterruptDisable Function Disables the interrupt source. File plib_sqi.h Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1962 C void PLIB_SQI_InterruptDisable(SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag); Returns None. Description This function disables the interrupt source passed into the function. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and TXFULL is an enum element. PLIB_SQI_InterruptDisable(MY_SQI_INSTANCE, SQI_TXFULL); Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt to be disabled Function void PLIB_SQI_InterruptDisable ( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag) PLIB_SQI_InterruptEnable Function Enables the passed interrupt source. File plib_sqi.h C void PLIB_SQI_InterruptEnable(SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag); Returns None. Description This function enables the interrupt source passed into the function. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_InterruptEnable(MY_SQI_INSTANCE, SQI_TXFULL); Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt to be enabled Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1963 Function void PLIB_SQI_InterruptEnable ( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag) PLIB_SQI_InterruptFlagGet Function Return SQI Interrupt flag status. File plib_sqi.h C bool PLIB_SQI_InterruptFlagGet(SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag); Returns Interrupt status. Description This function returns the SQI interrupt source flag status (set/cleared). Remarks None. Preconditions None. Example if ( PLIB_SQI_InterruptFlagGet(MY_SQI_INSTANCE,SQI_INT_ANY) ) if ( PLIB_SQI_InterruptFlagGet(MY_SQI_INSTANCE,SQI_TXFULL) ) { ... } if ( PLIB_SQI_InterruptFlagGet(MY_SQI_INSTANCE,SQI_RXFULL) ) { ... } . . . } Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt flag of interest Function bool PLIB_SQI_InterruptFlagGet( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag) PLIB_SQI_InterruptIsEnabled Function Returns the interrupt state. File plib_sqi.h C bool PLIB_SQI_InterruptIsEnabled(SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag); Returns • true - Interrupt is enabled • false - Interrupt is disabled Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1964 Description This function returns whether or not the interrupt state is enabled or disabled. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. if (PLIB_SQI_InterruptIsEnabled(MY_SQI_INSTANCE, SQI_TXFULL)) { .. } Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt under check Function bool PLIB_SQI_InterruptIsEnabled ( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag) PLIB_SQI_InterruptSignalDisable Function Disables the interrupt signal source. File plib_sqi.h C void PLIB_SQI_InterruptSignalDisable(SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag); Returns None. Description This function disables the interrupt signals source passed into the function, thus prohibiting it from reaching to the external interrupt controller. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_InterruptSignalDisable(MY_SQI_INSTANCE, SQI_TXFULL); Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt to be disabled Function void PLIB_SQI_InterruptSignalDisable ( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1965 PLIB_SQI_InterruptSignalEnable Function Enables the passed interrupt signal source. File plib_sqi.h C void PLIB_SQI_InterruptSignalEnable(SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag); Returns None. Description This function enables the interrupt signal source to be passed into the function, which allows it to go out to the external Interrupt Controller. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_InterruptSignalEnable(MY_SQI_INSTANCE, SQI_TXFULL); Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt to be enabled Function void PLIB_SQI_InterruptSignalEnable ( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag) PLIB_SQI_InterruptSignalIsEnabled Function Returns the interrupt signal state. File plib_sqi.h C bool PLIB_SQI_InterruptSignalIsEnabled(SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag); Returns • true - Interrupt signal is enabled • false - Interrupt signal is disabled Description This function returns whether the interrupt signal state is enabled or disabled. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1966 if (PLIB_SQI_InterruptSignalIsEnabled(MY_SQI_INSTANCE, SQI_TXFULL)) { .. } Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt signal under check Function bool PLIB_SQI_InterruptSignalIsEnabled ( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag) PLIB_SQI_DataLineStatus Function Returns the logical status of the SQI data lines. File plib_sqi.h C bool PLIB_SQI_DataLineStatus(SQI_MODULE_ID index, uint8_t dataPin); Returns SQIDx Status (High/Low). Description This function returns the logical status of the data lines (0/1). Remarks Parsing values other than 0/1/2/3 returns SQID0 pin status. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool sqiDataLineStatus = PLIB_SQI_DataLineStatus(MY_SQI_INSTANCE, 3); Parameters Parameters Description index Identifier for the device instance to be configured dataPin Data pin for which status will be returned (0/1/2/3) Function bool PLIB_SQI_DataLineStatus( SQI_MODULE_ID index, uint8_t dataPin) PLIB_SQI_CommandStatusGet Function Returns the SQI command (transmit/receive/idle). File plib_sqi.h C uint8_t PLIB_SQI_CommandStatusGet(SQI_MODULE_ID index); Returns SQI command (transmit/receive/idle) that is currently being executed. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1967 Description This function returns the SQI command (transmit/receive/idle) that is currently being executed. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t cmdStat = PLIB_SQI_CommandStatusGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_CommandStatusGet( SQI_MODULE_ID index) PLIB_SQI_ConBufWordsAvailable Function Returns the number of control buffer words available. File plib_sqi.h C uint8_t PLIB_SQI_ConBufWordsAvailable(SQI_MODULE_ID index); Returns Number of words available. Description This function returns the number of control buffer words available. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t numConBuf = PLIB_SQI_ConBufWordsAvailable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_ConBufWordsAvailable( SQI_MODULE_ID index) f) DMA Buffer Address Management Functions Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1968 PLIB_SQI_DMABDBaseAddressGet Function Returns the address of the base buffer descriptor. File plib_sqi.h C void* PLIB_SQI_DMABDBaseAddressGet(SQI_MODULE_ID index); Returns Base Buffer Descriptor address. Description This function returns the address of the base DMA buffer descriptor. Remarks Check to make sure if DMA Buffer Descriptor fetch is in progress. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. void *baseBDAddress; If (!PLIB_SQI_DMAIsActive(MY_SQI_INSTANCE)) { baseBDAddress = PLIB_SQI_DMABDBaseAddressGet(MY_SQI_INSTANCE); } Parameters Parameters Description index Identifier for the device instance to be configured Function void * PLIB_SQI_DMABDBaseAddressGet( SQI_MODULE_ID index) PLIB_SQI_DMABDBaseAddressSet Function Sets the address of the base buffer descriptor. File plib_sqi.h C void PLIB_SQI_DMABDBaseAddressSet(SQI_MODULE_ID index, void * baseBDAddress); Returns None. Description This function writes the address of the base (first/only) buffer descriptor into the buffer descriptor base address register. Remarks Check to make sure if DMA Buffer Descriptor fetch is in progress. Preconditions None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1969 Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. if (!PLIB_SQI_DMAIsActive(MY_SQI_INSTANCE)) PLIB_SQI_DMABDBaseAddressSet(MY_SQI_INSTANCE, (void *) (&MY_BD_STRUCT)); Parameters Parameters Description index Identifier for the device instance to be configured baseBDAddress Base buffer descriptor address Function void PLIB_SQI_DMABDBaseAddressSet ( SQI_MODULE_ID index, void *baseBDAddress) PLIB_SQI_DMABDCurrentAddressGet Function Returns the address of the current buffer descriptor in process. File plib_sqi.h C void* PLIB_SQI_DMABDCurrentAddressGet(SQI_MODULE_ID index); Returns Current Buffer Descriptor Address. Description This function returns the address of the DMA buffer descriptor that is currently in progress. Remarks Check to make sure if DMA Buffer Descriptor fetch is in progress. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t currentBDAddress; If (PLIB_SQI_DMAIsActive(MY_SQI_INSTANCE)) { void* currentBDAddress = PLIB_SQI_DMABDCurrentAddressGet(MY_SQI_INSTANCE); } Parameters Parameters Description index Identifier for the device instance to be configured Function void* PLIB_SQI_DMABDCurrentAddressGet ( SQI_MODULE_ID index) g) DMA Buffer Descriptor Management Functions PLIB_SQI_DMABDControlWordGet Function Returns Current Buffer Descriptor Control Word Information. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1970 File plib_sqi.h C uint16_t PLIB_SQI_DMABDControlWordGet(SQI_MODULE_ID index); Returns Control Word - DMA Buffer Descriptor Control Word Description This function returns current buffer descriptor Control Word information excluding buffer length. This information is returned in transmit and receive status functions. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint16_t dmabdconword; dmabdconword = PLIB_SQI_DMABDControlWordGet(MY_SQI_INSTANCE); switch (dmabdconword) { case BD_ENABLED: ...; case BD_DISABLED: ...; . . . } Parameters Parameters Description index Identifier for the device instance to be configured Function uint16_t PLIB_SQI_DMABDControlWordGet ( SQI_MODULE_ID index) PLIB_SQI_DMABDReceiveBufferCountGet Function Returns the receive buffer space in bytes. File plib_sqi.h C uint8_t PLIB_SQI_DMABDReceiveBufferCountGet(SQI_MODULE_ID index); Returns Receive buffer space in bytes. Description This function returns the current receive buffer space in bytes. Remarks None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1971 Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdRxBufCount = PLIB_SQI_DMABDReceiveBufferCountGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_DMABDReceiveBufferCountGet( SQI_MODULE_ID index) PLIB_SQI_DMABDReceiveBufferLengthGet Function Returns the receive length in bytes. File plib_sqi.h C uint8_t PLIB_SQI_DMABDReceiveBufferLengthGet(SQI_MODULE_ID index); Returns Receive buffer space in bytes. Description This function returns the current receive length in bytes. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdRxBufLength = PLIB_SQI_DMABDReceiveBufferLengthGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_DMABDReceiveBufferLengthGet( SQI_MODULE_ID index) PLIB_SQI_DMABDReceiveStateGet Function Returns the current state of the buffer descriptor in progress. File plib_sqi.h C SQI_BD_STATE PLIB_SQI_DMABDReceiveStateGet(SQI_MODULE_ID index); Returns Status - DMA Buffer Descriptor State Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1972 Description This function returns the current state of the buffer descriptor in progress. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdrxState = PLIB_SQI_DMABDReceiveStateGet(MY_SQI_INSTANCE); switch (bdRxState) { case BD_IDLE: ...; case BD_STATE_FETCH_REQ_PENDING: ...; . . . } Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_BD_STATE uint8_t PLIB_SQI_DMABDReceiveStateGet(SQI_MODULE_ID index) PLIB_SQI_DMABDTransmitBufferCountGet Function Returns the transmit buffer space in bytes. File plib_sqi.h C uint8_t PLIB_SQI_DMABDTransmitBufferCountGet(SQI_MODULE_ID index); Returns Transmit buffer space in bytes. Description This function returns the current transmit buffer space in bytes. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdTxBufCount = PLIB_SQI_DMABDTransmitBufferCountGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1973 Function uint8_t PLIB_SQI_DMABDTransmitBufferCountGet( SQI_MODULE_ID index) PLIB_SQI_DMABDTransmitBufferLengthGet Function Returns the transmit length in bytes. File plib_sqi.h C uint8_t PLIB_SQI_DMABDTransmitBufferLengthGet(SQI_MODULE_ID index); Returns Transmit buffer space in bytes. Description This function returns the current transmit length in bytes. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdTxBufLength = PLIB_SQI_DMABDTransmitBufferLengthGet(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_SQI_DMABDTransmitBufferLengthGet( SQI_MODULE_ID index) PLIB_SQI_DMABDTransmitStateGet Function Returns the current state of the buffer descriptor in progress. File plib_sqi.h C SQI_BD_STATE PLIB_SQI_DMABDTransmitStateGet(SQI_MODULE_ID index); Returns Status - DMA Buffer Descriptor State Description This function returns the current state of the buffer descriptor in progress. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1974 // application developer. uint8_t bdTxState = PLIB_SQI_DMABDTransmitStateGet(MY_SQI_INSTANCE); switch (bdTxState) { case BD_IDLE: ...; case BD_FETCH_REQ_PENDING: ...; . . . } Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_BD_STATE PLIB_SQI_DMABDTransmitStateGet(SQI_MODULE_ID index) PLIB_SQI_DMABDFetchStop Function Stops the DMA buffer descriptor fetch process. File plib_sqi.h C void PLIB_SQI_DMABDFetchStop(SQI_MODULE_ID index); Returns None. Description This function stops the DMA buffer descriptor fetch process. Remarks None. Preconditions PLIB_SQI_DMABDFetchStart is called. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMABDFetchStop(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_DMABDFetchStop ( SQI_MODULE_ID index) h) DMA Control and Status Management Functions PLIB_SQI_DMABDFetchStart Function Starts the DMA buffer descriptor fetch process. File plib_sqi.h Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1975 C void PLIB_SQI_DMABDFetchStart(SQI_MODULE_ID index); Returns None. Description This function starts the DMA buffer descriptor fetch process. Remarks None. Preconditions Make sure the buffer descriptors are set up and the buffer descriptor base address register is pointing to the first/only buffer descriptor. Also ensure any previous buffer descriptor processing is fixed. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMABDFetchStart(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_DMABDFetchStart ( SQI_MODULE_ID index) PLIB_SQI_DMABDIsBusy Function Returns whether or not the DMA Buffer Descriptor is busy. File plib_sqi.h C bool PLIB_SQI_DMABDIsBusy(SQI_MODULE_ID index); Returns • true - DMA Buffer Descriptor is busy • false - DMA Buffer Descriptor is not busy Description This function returns whether or not the DMA buffer descriptor process is busy. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool bdBusy = PLIB_SQI_DMABDIsBusy(MY_SQI_INSTANCE) Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1976 Function bool PLIB_SQI_DMABDIsBusy ( SQI_MODULE_ID index) PLIB_SQI_DMABDPollCounterSet Function Sets the poll counter value. File plib_sqi.h C void PLIB_SQI_DMABDPollCounterSet(SQI_MODULE_ID index, uint16_t pollCount); Returns None. Description This function sets the poll counter value that indicates the number of cycles the DMA would wait before fetching the next descriptor word, if the current descriptor fetched was disabled. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. if (PLIB_SQI_DMABDPollIsEnabled(MY_SQI_INSTANCE) { PLIB_SQI_DMABDPollCounterSet(MY_SQI_INSTANCE, MY_POLL_VALUE); } Parameters Parameters Description index Identifier for the device instance to be configured pollControl Polling value Function void PLIB_SQI_DMABDPollCounterSet( SQI_MODULE_ID index, uint16_t pollCount) PLIB_SQI_DMABDPollDisable Function Disables the buffer descriptor polling. File plib_sqi.h C void PLIB_SQI_DMABDPollDisable(SQI_MODULE_ID index); Returns None. Description This function disables the buffer descriptor polling. Remarks None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1977 Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMABDPollDisable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_DMABDPollDisable ( SQI_MODULE_ID index) PLIB_SQI_DMABDPollEnable Function Enables the buffer descriptor polling. File plib_sqi.h C void PLIB_SQI_DMABDPollEnable(SQI_MODULE_ID index); Returns None. Description This function enables the buffer descriptor polling and works in tandem with poll control register. Remarks Enable this control bit only when you are planning to have dead descriptors in the linked list. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMABDPollEnable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_DMABDPollEnable ( SQI_MODULE_ID index) PLIB_SQI_DMABDPollIsEnabled Function Returns whether or not the DMA buffer descriptor poll is enabled. File plib_sqi.h C bool PLIB_SQI_DMABDPollIsEnabled(SQI_MODULE_ID index); Returns • true - The DMA Poll Control is enabled Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1978 • false - The DMA Poll Control is disabled Description This function returns whether or not the DMA buffer descriptor poll is enabled or disabled. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. If (PLIB_SQI_DMABDPollIsEnabled(MY_SQI_INSTANCE)) { PLIB_SQI_PollControlSet(MY_SQI_INSTANCE, MY_POLL_CONTROL_VALUE); } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_DMABDPollIsEnabled ( SQI_MODULE_ID index) PLIB_SQI_DMABDStateGet Function Returns the current state of the buffer descriptor in progress. File plib_sqi.h C SQI_BD_STATE PLIB_SQI_DMABDStateGet(SQI_MODULE_ID index); Returns Status - DMA Buffer Descriptor State Description This function returns the current state of the buffer descriptor in progress. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdState = PLIB_SQI_DMABDStateGet(MY_SQI_INSTANCE); switch (bdState) { case BD_IDLE: ...; case BD_FETCH_REQ_PENDING: ...; . . . } Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1979 Parameters Parameters Description index Identifier for the device instance to be configured Function SQI_BD_STATE PLIB_SQI_DMABDStateGet(SQI_MODULE_ID index) PLIB_SQI_DMADisable Function Disables the built-in DMA logic. File plib_sqi.h C void PLIB_SQI_DMADisable(SQI_MODULE_ID index); Returns None. Description This function disables the built-in DMA logic for data transfer. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMADisable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_DMADisable ( SQI_MODULE_ID index) PLIB_SQI_DMAEnable Function Enables the built-in DMA logic. File plib_sqi.h C void PLIB_SQI_DMAEnable(SQI_MODULE_ID index); Returns None. Description This function enables the built-in DMA logic for data transfer. Remarks None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1980 Preconditions DMA buffer descriptors need to be setup before enabling the DMA. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMAEnable(MY_SQI_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_SQI_DMAEnable ( SQI_MODULE_ID index) PLIB_SQI_DMAHasStarted Function Returns whether or no the DMA process has started. File plib_sqi.h C bool PLIB_SQI_DMAHasStarted(SQI_MODULE_ID index); Returns • true - The DMA process has started • false - The DMA process has not started Description This function returns whether or not the DMA process has started. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool dmaStarted = PLIB_SQI_DMAHasStarted (MY_SQI_INSTANCE) Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_DMAHasStarted ( SQI_MODULE_ID index) PLIB_SQI_DMAIsEnabled Function Returns whether or not DMA is enabled. File plib_sqi.h C bool PLIB_SQI_DMAIsEnabled(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1981 Returns • true - DMA is enabled • false - DMA is disabled Description This function returns whether or not the DMA is enabled or disabled. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. If (PLIB_SQI_DMAIsEnabled(MY_SQI_INSTANCE)) { ... } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_SQI_DMAIsEnabled ( SQI_MODULE_ID index) i) Other Functions PLIB_SQI_StatusCheckSet Function Sets the Flash status check related control bits. File plib_sqi.h C void PLIB_SQI_StatusCheckSet(SQI_MODULE_ID index, uint16_t statCheckCmd, uint8_t numStatBytes, SQI_LANE_MODE statCmdType, bool statBitPos); Returns None. Description This function sets the Flash status check related control bits and enables the status check for PIO mode. Remarks None. Preconditions None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DDRModeSet(MY_SQI_INSTANCE, 0x05, 1, SQI_LANE_QUAD, 0); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1982 Parameters Parameters Description index Identifier for the device instance to be configured statCheckCmd Status check command to be sent to the Flash numStatBytes Number of status command bytes statCmdType Lane mode (Single/Dual/Quad) for status command Function void PLIB_SQI_StatusCheckSet( SQI_MODULE_ID index, uint16_t statCheckCmd, uint8_t numStatBytes, SQI_LANE_MODE statCmdType, bool statBitPos ) j) Feature Existence Functions PLIB_SQI_ExistsBDBaseAddress Function Identifies whether the BDBaseAddress feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDBaseAddress(SQI_MODULE_ID index); Returns • true - The BDBaseAddress feature is supported on the device • false - The BDBaseAddress feature is not supported on the device Description This function identifies whether the BDBaseAddress feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDBaseAddressSet • PLIB_SQI_DMABDBaseAddressGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDBaseAddress( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDControlWord Function Identifies whether the BDControlWord feature exists on the SQI module. File plib_sqi.h Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1983 C bool PLIB_SQI_ExistsBDControlWord(SQI_MODULE_ID index); Returns • true - The BDControlWord feature is supported on the device • false - The BDControlWord feature is not supported on the device Description This function identifies whether the BDControlWord feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDControlWordGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDControlWord( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDCurrentAddress Function Identifies whether the BDCurrentAddress feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDCurrentAddress(SQI_MODULE_ID index); Returns • true - The BDCurrentAddress feature is supported on the device • false - The BDCurrentAddress feature is not supported on the device Description This function identifies whether the BDCurrentAddress feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDCurrentAddressGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDCurrentAddress( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDPollCount Function Identifies whether the BDPollCount feature exists on the SQI module. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1984 File plib_sqi.h C bool PLIB_SQI_ExistsBDPollCount(SQI_MODULE_ID index); Returns • true - The BDPollCount feature is supported on the device • false - The BDPollCount feature is not supported on the device Description This function identifies whether the BDPollCount feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDPollCounterSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDPollCount( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDPollingEnable Function Identifies whether the BDPollingEnable feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDPollingEnable(SQI_MODULE_ID index); Returns • true - The BDPollingEnable feature is supported on the device • false - The BDPollingEnable feature is not supported on the device Description This function identifies whether the BDPollingEnable feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDPollEnable • PLIB_SQI_DMABDPollDisable • PLIB_SQI_DMABDPollIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDPollingEnable( SQI_MODULE_ID index ) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1985 PLIB_SQI_ExistsBDProcessState Function Identifies whether the BDProcessState feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDProcessState(SQI_MODULE_ID index); Returns • true - The BDProcessState feature is supported on the device • false - The BDProcessState feature is not supported on the device Description This function identifies whether the BDProcessState feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDStateGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDProcessState( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDRxBufCount Function Identifies whether the BDRxBufCount feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDRxBufCount(SQI_MODULE_ID index); Returns • true - The BDRxBufCount feature is supported on the device • false - The BDRxBufCount feature is not supported on the device Description This function identifies whether the BDRxBufCount feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDReceiveBufferCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1986 Function PLIB_SQI_ExistsBDRxBufCount( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDRxLength Function Identifies whether the BDRxLength feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDRxLength(SQI_MODULE_ID index); Returns • true - The BDRxLength feature is supported on the device • false - The BDRxLength feature is not supported on the device Description This function identifies whether the BDRxLength feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDReceiveBufferLengthGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDRxLength( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDRxState Function Identifies whether the BDRxState feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDRxState(SQI_MODULE_ID index); Returns • true - The BDRxState feature is supported on the device • false - The BDRxState feature is not supported on the device Description This function identifies whether the BDRxState feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDReceiveStateGet Remarks None. Preconditions None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1987 Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDRxState( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDTxBufCount Function Identifies whether the BDTxBufCount feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDTxBufCount(SQI_MODULE_ID index); Returns • true - The BDTxBufCount feature is supported on the device • false - The BDTxBufCount feature is not supported on the device Description This function identifies whether the BDTxBufCount feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDTransmitBufferCountGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDTxBufCount( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDTxLength Function Identifies whether the BDTxLength feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDTxLength(SQI_MODULE_ID index); Returns • true - The BDTxLength feature is supported on the device • false - The BDTxLength feature is not supported on the device Description This function identifies whether the BDTxLength feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDTransmitBufferLengthGet Remarks None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1988 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDTxLength( SQI_MODULE_ID index ) PLIB_SQI_ExistsBDTxState Function Identifies whether the BDTxState feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBDTxState(SQI_MODULE_ID index); Returns • true - The BDTxState feature is supported on the device • false - The BDTxState feature is not supported on the device Description This function identifies whether the BDTxState feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDTransmitStateGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBDTxState( SQI_MODULE_ID index ) PLIB_SQI_ExistsBurstControl Function Identifies whether the BurstControl feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsBurstControl(SQI_MODULE_ID index); Returns • true - The BurstControl feature is supported on the device • false - The BurstControl feature is not supported on the device Description This function identifies whether the BurstControl feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_BurstEnable Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1989 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsBurstControl( SQI_MODULE_ID index ) PLIB_SQI_ExistsChipSelect Function Identifies whether the ChipSelect feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsChipSelect(SQI_MODULE_ID index); Returns • true - The ChipSelect feature is supported on the device • false - The ChipSelect feature is not supported on the device Description This function identifies whether the ChipSelect feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ChipSelectSet • PLIB_SQI_ChipSelectGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsChipSelect( SQI_MODULE_ID index ) PLIB_SQI_ExistsClockControl Function Identifies whether the ClockControl feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsClockControl(SQI_MODULE_ID index); Returns • true - The ClockControl feature is supported on the device • false - The ClockControl feature is not supported on the device Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1990 Description This function identifies whether the ClockControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ClockEnable • PLIB_SQI_ClockDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsClockControl( SQI_MODULE_ID index ) PLIB_SQI_ExistsClockDivider Function Identifies whether the ClockDivider feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsClockDivider(SQI_MODULE_ID index); Returns • true - The ClockDivider feature is supported on the device • false - The ClockDivider feature is not supported on the device Description This function identifies whether the ClockDivider feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_ClockDividerSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsClockDivider( SQI_MODULE_ID index ) PLIB_SQI_ExistsClockReady Function Identifies whether the ClockReady feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsClockReady(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1991 Returns • true - The ClockReady feature is supported on the device • false - The ClockReady feature is not supported on the device Description This function identifies whether the ClockReady feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_ClockIsStable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsClockReady( SQI_MODULE_ID index ) PLIB_SQI_ExistsConBufThreshold Function Identifies whether the ConBufThreshold feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsConBufThreshold(SQI_MODULE_ID index); Returns • true - The ConBufThreshold feature is supported on the device • false - The ConBufThreshold feature is not supported on the device Description This function identifies whether the ConBufThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ControlBufferThresholdSet • PLIB_SQI_ControlBufferThresholdGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsConBufThreshold( SQI_MODULE_ID index ) PLIB_SQI_ExistsConfigWord Function Identifies whether the ConfigWord feature exists on the SQI module. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1992 File plib_sqi.h C bool PLIB_SQI_ExistsConfigWord(SQI_MODULE_ID index); Returns • true - The ConfigWord feature is supported on the device • false - The ConfigWord feature is not supported on the device Description This function identifies whether the ConfigWord feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ConfigWordSet • PLIB_SQI_ConfigWordGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsConfigWord( SQI_MODULE_ID index ) PLIB_SQI_ExistsControlWord Function Identifies whether the ControlWord feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsControlWord(SQI_MODULE_ID index); Returns • true - The ControlWord feature is supported on the device • false - The ControlWord feature is not supported on the device Description This function identifies whether the ControlWord feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ControlWordSet • PLIB_SQI_ControlWordGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsControlWord( SQI_MODULE_ID index ) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1993 PLIB_SQI_ExistsCSDeassert Function Identifies whether the CSDeassert feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsCSDeassert(SQI_MODULE_ID index); Returns • true - The CSDeassert feature is supported on the device • false - The CSDeassert feature is not supported on the device Description This function identifies whether the CSDeassert feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ChipSelectDeassertEnable • PLIB_SQI_ChipSelectDeassertDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsCSDeassert( SQI_MODULE_ID index ) PLIB_SQI_ExistsCSOutputEnable Function Identifies whether the CSOutputEnable feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsCSOutputEnable(SQI_MODULE_ID index); Returns • true - The CSOutputEnable feature is supported on the device • false - The CSOutputEnable feature is not supported on the device Description This function identifies whether the CSOutputEnable feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_CSOutputEnableSelect Remarks None. Preconditions None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1994 Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsCSOutputEnable( SQI_MODULE_ID index ) PLIB_SQI_ExistsDataFormat Function Identifies whether the DataFormat feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsDataFormat(SQI_MODULE_ID index); Returns • true - The DataFormat feature is supported on the device • false - The DataFormat feature is not supported on the device Description This function identifies whether the DataFormat feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DataFormatSet • PLIB_SQI_DataFormatGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsDataFormat( SQI_MODULE_ID index ) PLIB_SQI_ExistsDataModeControl Function Identifies whether the DataModeControl feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsDataModeControl(SQI_MODULE_ID index); Returns • true - The DataModeControl feature is supported on the device • false - The DataModeControl feature is not supported on the device Description This function identifies whether the DataModeControl feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DataModeSet Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1995 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsDataModeControl( SQI_MODULE_ID index ) PLIB_SQI_ExistsDataOutputEnable Function Identifies whether the DataOutputEnable feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsDataOutputEnable(SQI_MODULE_ID index); Returns • true - The DataOutputEnable feature is supported on the device • false - The DataOutputEnable feature is not supported on the device Description This function identifies whether the DataOutputEnable feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DataOutputEnableSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsDataOutputEnable( SQI_MODULE_ID index ) PLIB_SQI_ExistsDataPinStatus Function Identifies whether the DataPinStatus feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsDataPinStatus(SQI_MODULE_ID index); Returns • true - The DataPinStatus feature is supported on the device • false - The DataPinStatus feature is not supported on the device Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1996 Description This function identifies whether the DataPinStatus feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DataLineStatus Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsDataPinStatus( SQI_MODULE_ID index ) PLIB_SQI_ExistsDmaEnable Function Identifies whether the DMAEnable feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsDmaEnable(SQI_MODULE_ID index); Returns • true - The DMAEnable feature is supported on the device • false - The DMAEnable feature is not supported on the device Description This function identifies whether the DMAEnable feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMAEnable • PLIB_SQI_DMADisable • PLIB_SQI_DMAIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsDmaEnable( SQI_MODULE_ID index ) PLIB_SQI_ExistsDMAEngineBusy Function Identifies whether the DMAEngineBusy feature exists on the SQI module. File plib_sqi.h Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1997 C bool PLIB_SQI_ExistsDMAEngineBusy(SQI_MODULE_ID index); Returns • true - The DMAEngineBusy feature is supported on the device • false - The DMAEngineBusy feature is not supported on the device Description This function identifies whether the DMAEngineBusy feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMABDIsBusy Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsDMAEngineBusy( SQI_MODULE_ID index ) PLIB_SQI_ExistsDMAProcessInProgress Function Identifies whether the DMAProcessInProgress feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsDMAProcessInProgress(SQI_MODULE_ID index); Returns • true - The DMAProcessInProgress feature is supported on the device • false - The DMAProcessInProgress feature is not supported on the device Description This function identifies whether the DMAProcessInProgress feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_DMAHasStarted Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsDMAProcessInProgress( SQI_MODULE_ID index ) PLIB_SQI_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the SQI module. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1998 File plib_sqi.h C bool PLIB_SQI_ExistsEnableControl(SQI_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_Enable • PLIB_SQI_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsEnableControl( SQI_MODULE_ID index ) PLIB_SQI_ExistsHoldPinControl Function Identifies whether the HoldPinControl feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsHoldPinControl(SQI_MODULE_ID index); Returns • true - The HoldPinControl feature is supported on the device • false - The HoldPinControl feature is not supported on the device Description This function identifies whether the HoldPinControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_HoldSet • PLIB_SQI_HoldClear • PLIB_SQI_HoldGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 1999 Function PLIB_SQI_ExistsHoldPinControl( SQI_MODULE_ID index ) PLIB_SQI_ExistsInterruptControl Function Identifies whether the InterruptControl feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsInterruptControl(SQI_MODULE_ID index); Returns • true - The InterruptControl feature is supported on the device • false - The InterruptControl feature is not supported on the device Description This function identifies whether the InterruptControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_InterruptEnable • PLIB_SQI_InterruptDisable • PLIB_SQI_InterruptIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsInterruptControl( SQI_MODULE_ID index ) PLIB_SQI_ExistsInterruptSignalControl Function Identifies whether the InterruptSignalControl feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsInterruptSignalControl(SQI_MODULE_ID index); Returns • true - The InterruptSignalControl feature is supported on the device • false - The InterruptSignalControl feature is not supported on the device Description This function identifies whether the InterruptSignalControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_InterruptSignalEnable • PLIB_SQI_InterruptSignalDisable • PLIB_SQI_InterruptSignalIsEnabled Remarks None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2000 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsInterruptSignalControl( SQI_MODULE_ID index ) PLIB_SQI_ExistsInterruptStatus Function Identifies whether the InterruptStatus feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsInterruptStatus(SQI_MODULE_ID index); Returns • true - The InterruptStatus feature is supported on the device • false - The InterruptStatus feature is not supported on the device Description This function identifies whether the InterruptStatus feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_InterruptFlagGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsInterruptStatus( SQI_MODULE_ID index ) PLIB_SQI_ExistsLaneMode Function Identifies whether the LaneMode feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsLaneMode(SQI_MODULE_ID index); Returns • true - The LaneMode feature is supported on the device • false - The LaneMode feature is not supported on the device Description This function identifies whether the LaneMode feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_LaneModeSet Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2001 • PLIB_SQI_LaneModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsLaneMode( SQI_MODULE_ID index ) PLIB_SQI_ExistsReceiveLatch Function Identifies whether the ReceiveLatch feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsReceiveLatch(SQI_MODULE_ID index); Returns • true - The ReceiveLatch feature is supported on the device • false - The ReceiveLatch feature is not supported on the device Description This function identifies whether the ReceiveLatch feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ReceiveLatchEnable • PLIB_SQI_ReceiveLatchDisable • PLIB_SQI_ReceiveLatchGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsReceiveLatch( SQI_MODULE_ID index ) PLIB_SQI_ExistsRxBufferCount Function Identifies whether the RxBufferCount feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsRxBufferCount(SQI_MODULE_ID index); Returns • true - The RxBufferCount feature is supported on the device Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2002 • false - The RxBufferCount feature is not supported on the device Description This function identifies whether the RxBufferCount feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_NumberOfReceiveBufferReads Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsRxBufferCount( SQI_MODULE_ID index ) PLIB_SQI_ExistsRxBufIntThreshold Function Identifies whether the RxBufIntThreshold feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsRxBufIntThreshold(SQI_MODULE_ID index); Returns • true - The RxBufIntThreshold feature is supported on the device • false - The RxBufIntThreshold feature is not supported on the device Description This function identifies whether the RxBufIntThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_RxBufferThresholdIntSet • PLIB_SQI_RxBufferThresholdIntGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsRxBufIntThreshold( SQI_MODULE_ID index ) PLIB_SQI_ExistsRxBufThreshold Function Identifies whether the RxBufThreshold feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsRxBufThreshold(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2003 Returns • true - The RxBufThreshold feature is supported on the device • false - The RxBufThreshold feature is not supported on the device Description This function identifies whether the RxBufThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_RxBufferThresholdSet • PLIB_SQI_RxBufferThresholdGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsRxBufThreshold( SQI_MODULE_ID index ) PLIB_SQI_ExistsRxData Function Identifies whether the RxData feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsRxData(SQI_MODULE_ID index); Returns • true - The RxData feature is supported on the device • false - The RxData feature is not supported on the device Description This function identifies whether the RxData feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_ReceiveData Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsRxData( SQI_MODULE_ID index ) PLIB_SQI_ExistsRxUnderRun Function Identifies whether the RxUnderRun feature exists on the SQI module. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2004 File plib_sqi.h C bool PLIB_SQI_ExistsRxUnderRun(SQI_MODULE_ID index); Returns • true - The RxUnderRun feature is supported on the device • false - The RxUnderRun feature is not supported on the device Description This function identifies whether the RxUnderRun feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_ReceiveBufferIsUnderrun Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsRxUnderRun( SQI_MODULE_ID index ) PLIB_SQI_ExistsSoftReset Function Identifies whether the SoftReset feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsSoftReset(SQI_MODULE_ID index); Returns • true - The SoftReset feature is supported on the device • false - The SoftReset feature is not supported on the device Description This function identifies whether the SoftReset feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_SoftReset Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsSoftReset( SQI_MODULE_ID index ) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2005 PLIB_SQI_ExistsTransferCommand Function Identifies whether the TransferCommand feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTransferCommand(SQI_MODULE_ID index); Returns • true - The TransferCommand feature is supported on the device • false - The TransferCommand feature is not supported on the device Description This function identifies whether the TransferCommand feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TransferDirectionSet • PLIB_SQI_TransferDirectionGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTransferCommand( SQI_MODULE_ID index ) PLIB_SQI_ExistsTransferCount Function Identifies whether the TransferCount feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTransferCount(SQI_MODULE_ID index); Returns • true - The TransferCount feature is supported on the device • false - The TransferCount feature is not supported on the device Description This function identifies whether the TransferCount feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ByteCountSet • PLIB_SQI_ByteCountGet Remarks None. Preconditions None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2006 Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTransferCount( SQI_MODULE_ID index ) PLIB_SQI_ExistsTransferModeControl Function Identifies whether the TransferModeControl feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTransferModeControl(SQI_MODULE_ID index); Returns • true - The TransferModeControl feature is supported on the device • false - The TransferModeControl feature is not supported on the device Description This function identifies whether the TransferModeControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TransferModeSet • PLIB_SQI_TransferModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTransferModeControl( SQI_MODULE_ID index ) PLIB_SQI_ExistsTxBufferFree Function Identifies whether the TxBufferFree feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTxBufferFree(SQI_MODULE_ID index); Returns • true - The TxBufferFree feature is supported on the device • false - The TxBufferFree feature is not supported on the device Description This function identifies whether the TxBufferFree feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_TransmitBufferFreeSpaceGet Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2007 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTxBufferFree( SQI_MODULE_ID index ) PLIB_SQI_ExistsTxBufIntThreshold Function Identifies whether the TxBufIntThreshold feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTxBufIntThreshold(SQI_MODULE_ID index); Returns • true - The TxBufIntThreshold feature is supported on the device • false - The TxBufIntThreshold feature is not supported on the device Description This function identifies whether the TxBufIntThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TxBufferThresholdIntSet • PLIB_SQI_TxBufferThresholdIntGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTxBufIntThreshold( SQI_MODULE_ID index ) PLIB_SQI_ExistsTxBufThreshold Function Identifies whether the TxBufThreshold feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTxBufThreshold(SQI_MODULE_ID index); Returns • true - The TxBufThreshold feature is supported on the device • false - The TxBufThreshold feature is not supported on the device Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2008 Description This function identifies whether the TxBufThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TxBufferThresholdSet • PLIB_SQI_TxBufferThresholdGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTxBufThreshold( SQI_MODULE_ID index ) PLIB_SQI_ExistsTxData Function Identifies whether the TxData feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTxData(SQI_MODULE_ID index); Returns • true - The TxData feature is supported on the device • false - The TxData feature is not supported on the device Description This function identifies whether the TxData feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_TransmitData Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTxData( SQI_MODULE_ID index ) PLIB_SQI_ExistsTxOverFlow Function Identifies whether the TxOverFlow feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTxOverFlow(SQI_MODULE_ID index); Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2009 Returns • true - The TxOverFlow feature is supported on the device • false - The TxOverFlow feature is not supported on the device Description This function identifies whether the TxOverFlow feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_TransmitBufferHasOverflowed Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTxOverFlow( SQI_MODULE_ID index ) PLIB_SQI_ExistsWPPinControl Function Identifies whether the WPPinControl feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsWPPinControl(SQI_MODULE_ID index); Returns • true - The WPPinControl feature is supported on the device • false - The WPPinControl feature is not supported on the device Description This function identifies whether the WPPinControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_WriteProtectSet • PLIB_SQI_WriteProtectClear • PLIB_SQI_WriteProtectGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsWPPinControl( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPChipSelect Function Identifies whether the XIPChipSelect feature exists on the SQI module. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2010 File plib_sqi.h C bool PLIB_SQI_ExistsXIPChipSelect(SQI_MODULE_ID index); Returns • true - The XIPChipSelect feature is supported on the device • false - The XIPChipSelect feature is not supported on the device Description This function identifies whether the XIPChipSelect feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPChipSelectSet • PLIB_SQI_XIPChipSelectGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPChipSelect( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPControlWord1 Function Identifies whether the XIPControlWord1 feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPControlWord1(SQI_MODULE_ID index); Returns • true - The XIPControlWord1 feature is supported on the device • false - The XIPControlWord1 feature is not supported on the device Description This function identifies whether the XIPControlWord1 feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPControlWord1Set • PLIB_SQI_XIPControlWord1Get Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPControlWord1( SQI_MODULE_ID index ) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2011 PLIB_SQI_ExistsXIPControlWord2 Function Identifies whether the XIPControlWord2 feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPControlWord2(SQI_MODULE_ID index); Returns • true - The XIPControlWord2 feature is supported on the device • false - The XIPControlWord2 feature is not supported on the device Description This function identifies whether the XIPControlWord2 feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPControlWord2Set • PLIB_SQI_XIPControlWord2Get Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPControlWord2( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPLaneMode Function Identifies whether the XIPLaneMode feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPLaneMode(SQI_MODULE_ID index); Returns • true - The XIPLaneMode feature is supported on the device • false - The XIPLaneMode feature is not supported on the device Description This function identifies whether the XIPLaneMode feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_XIPLaneModeSet Remarks None. Preconditions None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2012 Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPLaneMode( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPModeBytes Function Identifies whether the XIPModeBytes feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPModeBytes(SQI_MODULE_ID index); Returns • true - The XIPModeBytes feature is supported on the device • false - The XIPModeBytes feature is not supported on the device Description This function identifies whether the XIPModeBytes feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPModeBytesSet • PLIB_SQI_XIPModeBytesGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPModeBytes( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPModeCode Function Identifies whether the XIPModeCode feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPModeCode(SQI_MODULE_ID index); Returns • true - The XIPModeCode feature is supported on the device • false - The XIPModeCode feature is not supported on the device Description This function identifies whether the XIPModeCode feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPModeCodeSet • PLIB_SQI_XIPModeCodeGet Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2013 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPModeCode( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPNumberOfAddressBytes Function Identifies whether the XIPNumberOfAddressBytes feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPNumberOfAddressBytes(SQI_MODULE_ID index); Returns • true - The XIPNumberOfAddressBytes feature is supported on the device • false - The XIPNumberOfAddressBytes feature is not supported on the device Description This function identifies whether the XIPNumberOfAddressBytes feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPAddressBytesSet • PLIB_SQI_XIPAddressBytesGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPNumberOfAddressBytes( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPNumberOfDummyBytes Function Identifies whether the XIPNumberOfDummyBytes feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPNumberOfDummyBytes(SQI_MODULE_ID index); Returns • true - The XIPNumberOfDummyBytes feature is supported on the device • false - The XIPNumberOfDummyBytes feature is not supported on the device Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2014 Description This function identifies whether the XIPNumberOfDummyBytes feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPDummyBytesSet • PLIB_SQI_XIPDummyBytesGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPNumberOfDummyBytes( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPReadOpCode Function Identifies whether the XIPReadOpCode feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPReadOpCode(SQI_MODULE_ID index); Returns • true - The XIPReadOpCode feature is supported on the device • false - The XIPReadOpCode feature is not supported on the device Description This function identifies whether the XIPReadOpCode feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPReadOpcodeSet • PLIB_SQI_XIPReadOpcodeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPReadOpCode( SQI_MODULE_ID index ) PLIB_SQI_ExistsCommandStatus Function Identifies whether the CommandStatus feature exists on the SQI module. File plib_sqi.h Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2015 C bool PLIB_SQI_ExistsCommandStatus(SQI_MODULE_ID index); Returns • true - The CommandStatus feature is supported on the device • false - The CommandStatus feature is not supported on the device Description This function identifies whether the CommandStatus feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_CommandStatusGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsCommandStatus( SQI_MODULE_ID index ) PLIB_SQI_ExistsConBufAvailable Function Identifies whether the ConBufWordsAvailable feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsConBufAvailable(SQI_MODULE_ID index); Returns • true - The ConBufWordsAvailable feature is supported on the device • false - The ConBufWordsAvailable feature is not supported on the device Description This function identifies whether the ConBufWordsAvailable feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_ConBufWordsAvailable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsConBufAvailable( SQI_MODULE_ID index ) PLIB_SQI_ExistsConBufferSoftReset Function Identifies whether the control buffer soft reset feature exists on the SQI module. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2016 File plib_sqi.h C bool PLIB_SQI_ExistsConBufferSoftReset(SQI_MODULE_ID index); Returns • true - The control buffer soft reset feature is supported on the device • false - The control buffer soft reset feature is not supported on the device Description This function identifies whether the control buffer soft reset feature is available on the SQI module. When this function returns true, the following function is supported on the device: • PLIB_SQI_ConBufferSoftReset Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsConBufferSoftReset( SQI_MODULE_ID index ) PLIB_SQI_ExistsDDRMode Function Identifies whether the DDRMode feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsDDRMode(SQI_MODULE_ID index); Returns • true - The DDRModeSet and DDRModeGet feature is supported on the device • false - The DDRModeSet and DDRModeGet feature is not supported on the device Description This function identifies whether the DDRModeSet feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DDRModeSet • PLIB_SQI_DDRModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsDDRMode( SQI_MODULE_ID index ) Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2017 PLIB_SQI_ExistsDMABDFetch Function Identifies whether the DMABDFetch feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsDMABDFetch(SQI_MODULE_ID index); Returns • true - The DMABDFetch feature is supported on the device • false - The DMABDFetch feature is not supported on the device Description This function identifies whether the DMABDFetch feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDFetchStart • PLIB_SQI_DMABDFetchStop Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsDMABDFetch( SQI_MODULE_ID index ) PLIB_SQI_ExistsRxBufferSoftReset Function Identifies whether the receive buffer soft reset feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsRxBufferSoftReset(SQI_MODULE_ID index); Returns • true - The receive buffer soft reset feature is supported on the device • false - The receive buffer soft reset feature is not supported on the device Description This function identifies whether the receive buffer soft reset feature is available on the SQI module. When this function returns true, the following function is supported on the device: • PLIB_SQI_RxBufferSoftReset Remarks None. Preconditions None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2018 Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsRxBufferSoftReset( SQI_MODULE_ID index ) PLIB_SQI_ExistsStatusCheck Function Identifies whether the StatusCheckSet feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsStatusCheck(SQI_MODULE_ID index); Returns • true - The StatusCheckSet feature is supported on the device • false - The StatusCheckSet feature is not supported on the device Description This function identifies whether the StatusCheck feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_StatusCheckSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsStatusCheck( SQI_MODULE_ID index ) PLIB_SQI_ExistsTapDelay Function Identifies whether the TapDelay feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTapDelay(SQI_MODULE_ID index); Returns • true - The TapDelaySet feature is supported on the device • false - The TapDelaySet feature is not supported on the device Description This function identifies whether the TapDelay feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_TapDelaySet Remarks None. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2019 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTapDelay( SQI_MODULE_ID index ) PLIB_SQI_ExistsTxBufferSoftReset Function Identifies whether the transmit buffer soft reset feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsTxBufferSoftReset(SQI_MODULE_ID index); Returns • true - The transmit buffer soft reset feature is supported on the device • false - The transmit buffer soft reset feature is not supported on the device Description This function identifies whether the transmit buffer soft reset feature is available on the SQI module. When this function returns true, the following function is supported on the device: • PLIB_SQI_TxBufferSoftReset Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsTxBufferSoftReset( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPControlWord3 Function Identifies whether the XIPControlWord3 feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPControlWord3(SQI_MODULE_ID index); Returns • true - The XIPControlWord3Set and XIPControlWord3Get feature is supported on the device • false - The XIPControlWord3Set and XIPControlWord3Get feature is not supported on the device Description This function identifies whether the XIPControlWord3 feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPControlWord3Set Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2020 • PLIB_SQI_XIPControlWord3Get Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPControlWord3( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPControlWord4 Function Identifies whether the XIPControlWord4 feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPControlWord4(SQI_MODULE_ID index); Returns • true - The XIPControlWord4Set and XIPControlWord4Get feature is supported on the device • false - The XIPControlWord4Set and XIPControlWord4Get feature is not supported on the device Description This function identifies whether the XIPControlWord4 feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPControlWord4Set • PLIB_SQI_XIPControlWord4Get Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPControlWord4( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPDDRMode Function Identifies whether the XIPDDRMode feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPDDRMode(SQI_MODULE_ID index); Returns • true - The XIPDDRModeSet feature is supported on the device • false - The XIPDDRModeSet feature is not supported on the device Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2021 Description This function identifies whether the XIPDDRMode feature is available on the SQI module. When this function returns true, this function is supported on the device: • PLIB_SQI_XIPDDRModeSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPDDRMode( SQI_MODULE_ID index ) PLIB_SQI_ExistsXIPSDRCommandDDRData Function Identifies whether the XIPSDRCommandDDRData feature exists on the SQI module. File plib_sqi.h C bool PLIB_SQI_ExistsXIPSDRCommandDDRData(SQI_MODULE_ID index); Returns • true - The XIPSDRCommandDDRDataSet and XIPSDRCommandDDRDataSetfeatureGet is supported on the device • false - The XIPSDRCommandDDRDataSet and XIPSDRCommandDDRDataGet not supported on the device Description This function identifies whether the XIPSDRCommandDDRData feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPSDRCommandDDRDataSet • PLIB_SQI_XIPSDRCommandDDRDataGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_SQI_ExistsXIPSDRCommandDDRData( SQI_MODULE_ID index ) k) Data Types and Constants SQI_ADDR_BYTES Enumeration Defines the list of SQI address bytes. File help_plib_sqi.h Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2022 C typedef enum { ADDR_BYTES_4, ADDR_BYTES_3, ADDR_BYTES_2, ADDR_BYTES_1, ADDR_BYTES_0 } SQI_ADDR_BYTES; Members Members Description ADDR_BYTES_4 SQI is set to Transmit 4 Address Bytes ADDR_BYTES_3 SQI is set to Transmit 3 Address Bytes ADDR_BYTES_2 SQI is set to Transmit 2 Address Bytes ADDR_BYTES_1 SQI is set to Transmit 1 Address Bytes ADDR_BYTES_0 SQI is set to Transmit No Address Bytes Description SQI Number of Address Bytes This macro defines the list of SQI address bytes. SQI_BD_CTRL_WORD Enumeration Defines the list of SQI Buffer Descriptor control word. File help_plib_sqi.h C typedef enum { BD_ENABLE, BD_DISABLE, CS_1_ACTIVE, CS_0_ACTIVE, FLASH_SC_ENABLE, FLASH_SC_DISABLE, SET_LSBF, SET_MSBF, DMA_LANE_QUAD, DMA_LANE_DUAL, DMA_LANE_SINGLE, DMA_IN_TRANSMIT, DMA_IN_RECEIVE, LAST_BD, NOT_LAST_BD, LAST_PKT, NOT_LAST_PKT, PKT_INT_ENABLE, PKT_INT_DISABLE, BD_DONE_INT_ENABLE, BD_DONE_INT_DISABLE, BD_BUF_LENGTH } SQI_BD_CTRL_WORD; Members Members Description BD_ENABLE Current Buffer Descriptor is Enabled BD_DISABLE Current Buffer Descriptor is Disabled CS_1_ACTIVE Chip Select 1 is Active CS_0_ACTIVE Chip Select 0 is Active FLASH_SC_ENABLE Automatic Status Check Enabled FLASH_SC_DISABLE Automatic Status Check Disabled SET_LSBF Least Significant Bit First SET_MSBF Most Significant Bit First Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2023 DMA_LANE_QUAD DMA writes/reads in Quad Lane Mode DMA_LANE_DUAL DMA writes/reads in Dual Lane Mode DMA_LANE_SINGLE DMA writes/reads in Single Lane Mode DMA_IN_TRANSMIT DMA is Transmitting DMA_IN_RECEIVE DMA is Receiving LAST_BD Indicates Last Buffer Descriptor in the List NOT_LAST_BD Indicates Non Last Buffer Descriptor in the List LAST_PKT Indicates Last Packet of the Data Chunk NOT_LAST_PKT Indicates Non Last Packet of the Data Chunk PKT_INT_ENABLE Indicates Packet Interrupt is Enabled PKT_INT_DISABLE Indicates Packet Interrupt is Disabled BD_DONE_INT_ENABLE Indicates Buffer Descriptor Done Interrupt is Enabled BD_DONE_INT_DISABLE Indicates Buffer Descriptor Done Interrupt is Disabled BD_BUF_LENGTH Indicates Buffer Length Description SQI Buffer Descriptor Control Words This macro defines the list of SQI Buffer Descriptor control word. SQI_BD_STATE Enumeration Defines the list of SQI Buffer Descriptor states. File help_plib_sqi.h C typedef enum { BD_STATE_DISABLED, BD_STATE_DONE, BD_STATE_PROCESSING_DATA, BD_STATE_BEING_FETCHED, BD_STATE_FETCH_REQ_PENDING, BD_STATE_IDLE } SQI_BD_STATE; Members Members Description BD_STATE_DISABLED Fetched Buffer Descriptor is Disabled BD_STATE_DONE Fetched Buffer Descriptor Processed BD_STATE_PROCESSING_DATA Fetched Buffer Descriptor is in Data transfer phase BD_STATE_BEING_FETCHED In the process of Fetching the Buffer Descriptor BD_STATE_FETCH_REQ_PENDING Buffer Descriptor Fetch Request Pending BD_STATE_IDLE Buffer Descriptor process is idle Description SQI Buffer Descriptor (BD) State This macro defines the list of SQI Buffer Descriptor states. SQI_CLK_DIV Enumeration Defines the list of SQI Clock Divider values. File help_plib_sqi.h C typedef enum { CLK_DIV_256, CLK_DIV_128, Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2024 CLK_DIV_64, CLK_DIV_32, CLK_DIV_16, CLK_DIV_8, CLK_DIV_4, CLK_DIV_2, CLK_DIV_1 } SQI_CLK_DIV; Members Members Description CLK_DIV_256 SQI Clock is divided by 256 CLK_DIV_128 SQI Clock is divided by 128 CLK_DIV_64 SQI Clock is divided by 64 CLK_DIV_32 SQI Clock is divided by 32 CLK_DIV_16 SQI Clock is divided by 16 CLK_DIV_8 SQI Clock is divided by 8 CLK_DIV_4 SQI Clock is divided by 4 CLK_DIV_2 SQI Clock is divided by 2 CLK_DIV_1 SQI Clock is not divided Description SQI Clock Divider This macro defines the list of SQI Clock Divider values. SQI_CS_NUM Enumeration Defines the list of SQI Chip Selects. File help_plib_sqi.h C typedef enum { SQI_CS_1, SQI_CS_0 } SQI_CS_NUM; Members Members Description SQI_CS_1 SQI Chip Select 1 SQI_CS_0 SQI Chip Select 0 Description SQI Device Select or Chip Select This macro defines the list of SQI Chip Selects. SQI_CS_OEN Enumeration Defines the list of SQI Chip Selects on which output is enable. File help_plib_sqi.h C typedef enum { SQI_CS_OEN_BOTH, SQI_CS_OEN_1, SQI_CS_OEN_0, SQI_CS_OEN_NONE } SQI_CS_OEN; Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2025 Members Members Description SQI_CS_OEN_BOTH SQI chip select 0 and 1 are enabled SQI_CS_OEN_1 SQI chip select 1 is enabled but chip select 0 is disabled SQI_CS_OEN_0 SQI chip select 0 is enabled but chip select 1 is disabled SQI_CS_OEN_NONE SQI chip select 0 and 1 are disabled Description SQI Chip Select Output Enable This macro defines the list of SQI Chip Selects on which output is enabled. SQI_DATA_FORMAT Enumeration Defines the Data Format Options available (LSBF/MSBF). File help_plib_sqi.h C typedef enum { SQI_DATA_FORMAT_LSBF, SQI_DATA_FORMAT_MSBF } SQI_DATA_FORMAT; Members Members Description SQI_DATA_FORMAT_LSBF SQI Data is Least Significant Bit First Formatted SQI_DATA_FORMAT_MSBF SQI Data is Most Significant Bit First Formatted Description SQI Data Mode This macro defines the Data Formats (LSBF/MSBF). SQI_DATA_MODE Enumeration Defines the list of SQI Data modes. File help_plib_sqi.h C typedef enum { SQI_DATA_MODE_3, SQI_DATA_MODE_0 } SQI_DATA_MODE; Members Members Description SQI_DATA_MODE_3 SQI is in SPI mode 3 SQI_DATA_MODE_0 SQI is in SPI mode 0 Description SQI Data Mode This macro defines the list of SQI Data modes. SQI_DATA_OEN Enumeration Defines the list of SQI Data pins on which output is enabled. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2026 File help_plib_sqi.h C typedef enum { SQI_DATA_OEN_QUAD, SQI_DATA_OEN_DUAL, SQI_DATA_OEN_SINGLE } SQI_DATA_OEN; Members Members Description SQI_DATA_OEN_QUAD SQI data outputs 3 to 0 are enabled (quad lane mode) SQI_DATA_OEN_DUAL SQI data outputs 1 and 0 are enabled (dual lane mode) SQI_DATA_OEN_SINGLE SQI data output 0 is enabled (single lane mode) Description SQI Data Output Enable This macro defines the list of SQI Data Output pins on which output is enabled. SQI_DATA_TYPE Type Data type defining the SQI Data size. File help_plib_sqi.h C typedef uint32_t SQI_DATA_TYPE; Description SQI Data Type definition This data type defines the SQI Data size SQI_DUMMY_BYTES Enumeration Defines the list of SQI dummy bytes. File help_plib_sqi.h C typedef enum { DUMMY_BYTES_7, DUMMY_BYTES_6, DUMMY_BYTES_5, DUMMY_BYTES_4, DUMMY_BYTES_3, DUMMY_BYTES_2, DUMMY_BYTE_1, DUMMY_BYTES_0 } SQI_DUMMY_BYTES; Members Members Description DUMMY_BYTES_7 SQI is set to Transmit 7 Dummy Bytes DUMMY_BYTES_6 SQI is set to Transmit 6 Dummy Bytes DUMMY_BYTES_5 SQI is set to Transmit 5 Dummy Bytes DUMMY_BYTES_4 SQI is set to Transmit 4 Dummy Bytes DUMMY_BYTES_3 SQI is set to Transmit 3 Dummy Bytes DUMMY_BYTES_2 SQI is set to Transmit 2 Dummy Bytes Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2027 DUMMY_BYTE_1 SQI is set to Transmit 1 Dummy Bytes DUMMY_BYTES_0 SQI is set to Transmit No Dummy Bytes Description SQI Number of Dummy Bytes This macro defines the list of SQI dummy bytes after address bytes. SQI_INTERRUPTS Enumeration Defines the list of SQI interrupts. File help_plib_sqi.h C typedef enum { SQI_PKTCOMP, SQI_BDDONE, SQI_CONTHR, SQI_CONEMPTY, SQI_CONFULL, SQI_RXTHR, SQI_RXFULL, SQI_RXEMPTY, SQI_TXTHR, SQI_TXFULL, SQI_TXEMPTY } SQI_INTERRUPTS; Members Members Description SQI_PKTCOMP SQI Packet Complete Interrupt (used in DMA mode) SQI_BDDONE SQI Buffer Descriptor Done Interrupt (used in DMA mode) SQI_CONTHR SQI Control Buffer Threshold Interrupt SQI_CONEMPTY SQI Control Buffer Empty Interrupt SQI_CONFULL SQI Control Buffer Full Interrupt SQI_RXTHR SQI Receive Buffer Threshold Interrupt SQI_RXFULL SQI Receive Buffer Empty Interrupt SQI_RXEMPTY SQI Receive Buffer Full Interrupt SQI_TXTHR SQI Transmit Buffer Threshold Interrupt SQI_TXFULL SQI Transmit Buffer Empty Interrupt SQI_TXEMPTY SQI Transmit Buffer Full Interrupt Description SQI Interrupt List This macro defines the list of SQI interrupts. SQI_LANE_MODE Enumeration Defines the list of SQI Lane modes (single/dual/quad). File help_plib_sqi.h C typedef enum { SQI_LANE_QUAD, SQI_LANE_DUAL, SQI_LANE_SINGLE } SQI_LANE_MODE; Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2028 Members Members Description SQI_LANE_QUAD SQI is set into Quad Lane Mode SQI_LANE_DUAL SQI is set into Dual Lane Mode SQI_LANE_SINGLE SQI is set into Single Lane Mode Description SQI Lane Mode This macro defines the list of SQI Lane modes. SQI_MODE_BYTES Enumeration Defines the list of SQI mode bytes. File help_plib_sqi.h C typedef enum { MODE_BYTES_3, MODE_BYTES_2, MODE_BYTES_1, MODE_BYTES_0 } SQI_MODE_BYTES; Members Members Description MODE_BYTES_3 SQI is set to Transmit 3 Mode Bytes MODE_BYTES_2 SQI is set to Transmit 2 Mode Bytes MODE_BYTES_1 SQI is set to Transmit 1 Mode Bytes MODE_BYTES_0 SQI is set to Transmit No Mode Bytes Description SQI Number of Mode Bytes This macro defines the list of SQI mode bytes allocated for mode code. SQI_MODULE_ID Enumeration Identifies the supported SQI modules. File help_plib_sqi.h C typedef enum { SQI_ID_1, SQI_NUMBER_OF_MODULES } SQI_MODULE_ID; Members Members Description SQI_ID_1 SQI Module 1 ID SQI_NUMBER_OF_MODULES Number of available SQI modules Description SQI Module ID This enumeration identifies the SQI modules that are available on the microcontroller. This is the super set of all the possible instances that might be available on the Microchip microcontrollers. Peripheral Libraries Help SQI Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2029 Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. SQI_XFER_CMD Enumeration Defines the list of SQI transfer commands. File help_plib_sqi.h C typedef enum { SQI_CMD_RECEIVE, SQI_CMD_TRANSMIT, SQI_CMD_IDLE } SQI_XFER_CMD; Members Members Description SQI_CMD_RECEIVE SQI issues a Receive Command SQI_CMD_TRANSMIT SQI issues a Transmit Command SQI_CMD_IDLE SQI is Idle Description SQI Transfer Command This macro defines the list of SQI transfer commands. SQI_XFER_MODE Enumeration Defines the list of SQI Transfer modes. File help_plib_sqi.h C typedef enum { SQI_XFER_MODE_XIP, SQI_XFER_MODE_DMA, SQI_XFER_MODE_PIO } SQI_XFER_MODE; Members Members Description SQI_XFER_MODE_XIP SQI is in XIP mode SQI_XFER_MODE_DMA SQI is in DMA mode SQI_XFER_MODE_PIO SQI is in PIO mode Description SQI Transfer Mode This macro defines the list of SQI Transfer modes. Files Files Name Description plib_sqi.h SQI Peripheral Library Interface Header for common definitions. help_plib_sqi.h Identifies the various enumerations in SQI modules supported. Peripheral Libraries Help SQI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2030 Description This section lists the source and header files used by the library. plib_sqi.h SQI Peripheral Library Interface Header for common definitions. Functions Name Description PLIB_SQI_BurstEnable Sets the burst enable (BURSTEN) function for higher throughput. This function is an artifact of the System Bus architecture. PLIB_SQI_ByteCountGet Returns the current transmit/receive count. PLIB_SQI_ByteCountSet Sets the transmit/receive count. PLIB_SQI_ChipSelectDeassertDisable Clears the Chip Select deassert. PLIB_SQI_ChipSelectDeassertEnable Sets the Chip Select deassert. PLIB_SQI_ChipSelectGet Returns the Chip Select that is currently active. PLIB_SQI_ChipSelectSet Activates the Chip Select. PLIB_SQI_ClockDisable Disables the SQI transfer clock. PLIB_SQI_ClockDividerSet Sets the SQI clock (that drives the SQI protocol) divider value. Divides the base clock to generate the SQI clock. PLIB_SQI_ClockEnable Enables the SQI transfer clock. PLIB_SQI_ClockIsStable Returns SQI transfer clock state. PLIB_SQI_CommandStatusGet Returns the SQI command (transmit/receive/idle). PLIB_SQI_ConBufferSoftReset Issues a soft reset to the SQI control buffer. PLIB_SQI_ConBufWordsAvailable Returns the number of control buffer words available. PLIB_SQI_ConfigWordGet Gets the SQI Configuration Word. PLIB_SQI_ConfigWordSet Sets SQI Configuration Word. PLIB_SQI_ControlBufferThresholdGet Returns the transmit buffer space in bytes. PLIB_SQI_ControlBufferThresholdSet Sets the control buffer threshold value. PLIB_SQI_ControlWordGet Get the SQI Control Word. PLIB_SQI_ControlWordSet Sets the SQI Control Word. PLIB_SQI_CSOutputEnableSelect Selects the output enables on SQI Chip Select pins. PLIB_SQI_DataFormatGet Returns the data format. PLIB_SQI_DataFormatSet Sets the data format to Least Significant Bit First (LSBF).. PLIB_SQI_DataLineStatus Returns the logical status of the SQI data lines. PLIB_SQI_DataModeSet Sets the SQI data mode of operation. PLIB_SQI_DataOutputEnableSelect Selects the output enables on SQI data outputs. PLIB_SQI_DDRModeGet Return the SQI data rate mode (single/double) value. PLIB_SQI_DDRModeSet Sets SQI communication to DDR mode. PLIB_SQI_Disable Disables the SQI module. PLIB_SQI_DMABDBaseAddressGet Returns the address of the base buffer descriptor. PLIB_SQI_DMABDBaseAddressSet Sets the address of the base buffer descriptor. PLIB_SQI_DMABDControlWordGet Returns Current Buffer Descriptor Control Word Information. PLIB_SQI_DMABDCurrentAddressGet Returns the address of the current buffer descriptor in process. PLIB_SQI_DMABDFetchStart Starts the DMA buffer descriptor fetch process. PLIB_SQI_DMABDFetchStop Stops the DMA buffer descriptor fetch process. PLIB_SQI_DMABDIsBusy Returns whether or not the DMA Buffer Descriptor is busy. PLIB_SQI_DMABDPollCounterSet Sets the poll counter value. PLIB_SQI_DMABDPollDisable Disables the buffer descriptor polling. PLIB_SQI_DMABDPollEnable Enables the buffer descriptor polling. PLIB_SQI_DMABDPollIsEnabled Returns whether or not the DMA buffer descriptor poll is enabled. PLIB_SQI_DMABDReceiveBufferCountGet Returns the receive buffer space in bytes. PLIB_SQI_DMABDReceiveBufferLengthGet Returns the receive length in bytes. PLIB_SQI_DMABDReceiveStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMABDStateGet Returns the current state of the buffer descriptor in progress. Peripheral Libraries Help SQI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2031 PLIB_SQI_DMABDTransmitBufferCountGet Returns the transmit buffer space in bytes. PLIB_SQI_DMABDTransmitBufferLengthGet Returns the transmit length in bytes. PLIB_SQI_DMABDTransmitStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMADisable Disables the built-in DMA logic. PLIB_SQI_DMAEnable Enables the built-in DMA logic. PLIB_SQI_DMAHasStarted Returns whether or no the DMA process has started. PLIB_SQI_DMAIsEnabled Returns whether or not DMA is enabled. PLIB_SQI_Enable Enables the SQI module. PLIB_SQI_ExistsBDBaseAddress Identifies whether the BDBaseAddress feature exists on the SQI module. PLIB_SQI_ExistsBDControlWord Identifies whether the BDControlWord feature exists on the SQI module. PLIB_SQI_ExistsBDCurrentAddress Identifies whether the BDCurrentAddress feature exists on the SQI module. PLIB_SQI_ExistsBDPollCount Identifies whether the BDPollCount feature exists on the SQI module. PLIB_SQI_ExistsBDPollingEnable Identifies whether the BDPollingEnable feature exists on the SQI module. PLIB_SQI_ExistsBDProcessState Identifies whether the BDProcessState feature exists on the SQI module. PLIB_SQI_ExistsBDRxBufCount Identifies whether the BDRxBufCount feature exists on the SQI module. PLIB_SQI_ExistsBDRxLength Identifies whether the BDRxLength feature exists on the SQI module. PLIB_SQI_ExistsBDRxState Identifies whether the BDRxState feature exists on the SQI module. PLIB_SQI_ExistsBDTxBufCount Identifies whether the BDTxBufCount feature exists on the SQI module. PLIB_SQI_ExistsBDTxLength Identifies whether the BDTxLength feature exists on the SQI module. PLIB_SQI_ExistsBDTxState Identifies whether the BDTxState feature exists on the SQI module. PLIB_SQI_ExistsBurstControl Identifies whether the BurstControl feature exists on the SQI module. PLIB_SQI_ExistsChipSelect Identifies whether the ChipSelect feature exists on the SQI module. PLIB_SQI_ExistsClockControl Identifies whether the ClockControl feature exists on the SQI module. PLIB_SQI_ExistsClockDivider Identifies whether the ClockDivider feature exists on the SQI module. PLIB_SQI_ExistsClockReady Identifies whether the ClockReady feature exists on the SQI module. PLIB_SQI_ExistsCommandStatus Identifies whether the CommandStatus feature exists on the SQI module. PLIB_SQI_ExistsConBufAvailable Identifies whether the ConBufWordsAvailable feature exists on the SQI module. PLIB_SQI_ExistsConBufferSoftReset Identifies whether the control buffer soft reset feature exists on the SQI module. PLIB_SQI_ExistsConBufThreshold Identifies whether the ConBufThreshold feature exists on the SQI module. PLIB_SQI_ExistsConfigWord Identifies whether the ConfigWord feature exists on the SQI module. PLIB_SQI_ExistsControlWord Identifies whether the ControlWord feature exists on the SQI module. PLIB_SQI_ExistsCSDeassert Identifies whether the CSDeassert feature exists on the SQI module. PLIB_SQI_ExistsCSOutputEnable Identifies whether the CSOutputEnable feature exists on the SQI module. PLIB_SQI_ExistsDataFormat Identifies whether the DataFormat feature exists on the SQI module. PLIB_SQI_ExistsDataModeControl Identifies whether the DataModeControl feature exists on the SQI module. PLIB_SQI_ExistsDataOutputEnable Identifies whether the DataOutputEnable feature exists on the SQI module. PLIB_SQI_ExistsDataPinStatus Identifies whether the DataPinStatus feature exists on the SQI module. PLIB_SQI_ExistsDDRMode Identifies whether the DDRMode feature exists on the SQI module. PLIB_SQI_ExistsDMABDFetch Identifies whether the DMABDFetch feature exists on the SQI module. PLIB_SQI_ExistsDmaEnable Identifies whether the DMAEnable feature exists on the SQI module. PLIB_SQI_ExistsDMAEngineBusy Identifies whether the DMAEngineBusy feature exists on the SQI module. PLIB_SQI_ExistsDMAProcessInProgress Identifies whether the DMAProcessInProgress feature exists on the SQI module. PLIB_SQI_ExistsEnableControl Identifies whether the EnableControl feature exists on the SQI module. PLIB_SQI_ExistsHoldPinControl Identifies whether the HoldPinControl feature exists on the SQI module. PLIB_SQI_ExistsInterruptControl Identifies whether the InterruptControl feature exists on the SQI module. PLIB_SQI_ExistsInterruptSignalControl Identifies whether the InterruptSignalControl feature exists on the SQI module. PLIB_SQI_ExistsInterruptStatus Identifies whether the InterruptStatus feature exists on the SQI module. PLIB_SQI_ExistsLaneMode Identifies whether the LaneMode feature exists on the SQI module. PLIB_SQI_ExistsReceiveLatch Identifies whether the ReceiveLatch feature exists on the SQI module. PLIB_SQI_ExistsRxBufferCount Identifies whether the RxBufferCount feature exists on the SQI module. PLIB_SQI_ExistsRxBufferSoftReset Identifies whether the receive buffer soft reset feature exists on the SQI module. PLIB_SQI_ExistsRxBufIntThreshold Identifies whether the RxBufIntThreshold feature exists on the SQI module. PLIB_SQI_ExistsRxBufThreshold Identifies whether the RxBufThreshold feature exists on the SQI module. PLIB_SQI_ExistsRxData Identifies whether the RxData feature exists on the SQI module. PLIB_SQI_ExistsRxUnderRun Identifies whether the RxUnderRun feature exists on the SQI module. Peripheral Libraries Help SQI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2032 PLIB_SQI_ExistsSoftReset Identifies whether the SoftReset feature exists on the SQI module. PLIB_SQI_ExistsStatusCheck Identifies whether the StatusCheckSet feature exists on the SQI module. PLIB_SQI_ExistsTapDelay Identifies whether the TapDelay feature exists on the SQI module. PLIB_SQI_ExistsTransferCommand Identifies whether the TransferCommand feature exists on the SQI module. PLIB_SQI_ExistsTransferCount Identifies whether the TransferCount feature exists on the SQI module. PLIB_SQI_ExistsTransferModeControl Identifies whether the TransferModeControl feature exists on the SQI module. PLIB_SQI_ExistsTxBufferFree Identifies whether the TxBufferFree feature exists on the SQI module. PLIB_SQI_ExistsTxBufferSoftReset Identifies whether the transmit buffer soft reset feature exists on the SQI module. PLIB_SQI_ExistsTxBufIntThreshold Identifies whether the TxBufIntThreshold feature exists on the SQI module. PLIB_SQI_ExistsTxBufThreshold Identifies whether the TxBufThreshold feature exists on the SQI module. PLIB_SQI_ExistsTxData Identifies whether the TxData feature exists on the SQI module. PLIB_SQI_ExistsTxOverFlow Identifies whether the TxOverFlow feature exists on the SQI module. PLIB_SQI_ExistsWPPinControl Identifies whether the WPPinControl feature exists on the SQI module. PLIB_SQI_ExistsXIPChipSelect Identifies whether the XIPChipSelect feature exists on the SQI module. PLIB_SQI_ExistsXIPControlWord1 Identifies whether the XIPControlWord1 feature exists on the SQI module. PLIB_SQI_ExistsXIPControlWord2 Identifies whether the XIPControlWord2 feature exists on the SQI module. PLIB_SQI_ExistsXIPControlWord3 Identifies whether the XIPControlWord3 feature exists on the SQI module. PLIB_SQI_ExistsXIPControlWord4 Identifies whether the XIPControlWord4 feature exists on the SQI module. PLIB_SQI_ExistsXIPDDRMode Identifies whether the XIPDDRMode feature exists on the SQI module. PLIB_SQI_ExistsXIPLaneMode Identifies whether the XIPLaneMode feature exists on the SQI module. PLIB_SQI_ExistsXIPModeBytes Identifies whether the XIPModeBytes feature exists on the SQI module. PLIB_SQI_ExistsXIPModeCode Identifies whether the XIPModeCode feature exists on the SQI module. PLIB_SQI_ExistsXIPNumberOfAddressBytes Identifies whether the XIPNumberOfAddressBytes feature exists on the SQI module. PLIB_SQI_ExistsXIPNumberOfDummyBytes Identifies whether the XIPNumberOfDummyBytes feature exists on the SQI module. PLIB_SQI_ExistsXIPReadOpCode Identifies whether the XIPReadOpCode feature exists on the SQI module. PLIB_SQI_ExistsXIPSDRCommandDDRData Identifies whether the XIPSDRCommandDDRData feature exists on the SQI module. PLIB_SQI_HoldClear Clears the hold function to be disabled on SQID3 in single and dual lane modes. PLIB_SQI_HoldGet Gets the status of HOLD function on SQID3 pin. PLIB_SQI_HoldSet Sets the hold function to be enabled on SQID3 in single or dual lane modes. PLIB_SQI_InterruptDisable Disables the interrupt source. PLIB_SQI_InterruptEnable Enables the passed interrupt source. PLIB_SQI_InterruptFlagGet Return SQI Interrupt flag status. PLIB_SQI_InterruptIsEnabled Returns the interrupt state. PLIB_SQI_InterruptSignalDisable Disables the interrupt signal source. PLIB_SQI_InterruptSignalEnable Enables the passed interrupt signal source. PLIB_SQI_InterruptSignalIsEnabled Returns the interrupt signal state. PLIB_SQI_LaneModeGet Returns the lane mode (single/dual/quad). PLIB_SQI_LaneModeSet Sets the data lane mode (single/dual/quad). PLIB_SQI_NumberOfReceiveBufferReads Returns the number of receive buffer reads. PLIB_SQI_ReceiveBufferIsUnderrun Returns the status of receive buffer. PLIB_SQI_ReceiveData Reads the data from the receive buffer. PLIB_SQI_ReceiveLatchDisable Disables the receive latch so receive data is discarded when in transmit mode. PLIB_SQI_ReceiveLatchEnable Enables the receive latch so receive data is latched during transmit mode. PLIB_SQI_ReceiveLatchGet Returns the receive latch status in transmit mode. PLIB_SQI_RxBufferSoftReset Issues a soft reset to the SQI receive buffer. PLIB_SQI_RxBufferThresholdGet Returns the receive command threshold. PLIB_SQI_RxBufferThresholdIntGet Sets the receive buffer threshold interrupt. PLIB_SQI_RxBufferThresholdIntSet Sets the receive buffer threshold for interrupt. PLIB_SQI_RxBufferThresholdSet Sets the receive command threshold. PLIB_SQI_SoftReset Issues a soft reset to the SQI module. PLIB_SQI_StatusCheckSet Sets the Flash status check related control bits. PLIB_SQI_TapDelaySet Sets the tap delays. PLIB_SQI_TransferDirectionGet Returns the transfer command. PLIB_SQI_TransferDirectionSet Sets the transfer command. Peripheral Libraries Help SQI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2033 PLIB_SQI_TransferModeGet Returns the SQI transfer mode of operation. PLIB_SQI_TransferModeSet Sets the SQI transfer mode of operation. PLIB_SQI_TransmitBufferFreeSpaceGet Returns the number of transmit buffer words available. PLIB_SQI_TransmitBufferHasOverflowed Returns the current status of the transmit buffer. PLIB_SQI_TransmitData Writes data into the SQI transmit buffer. PLIB_SQI_TxBufferSoftReset Issues a soft reset to the SQI transmit buffer. PLIB_SQI_TxBufferThresholdGet Returns the transmit command threshold value. PLIB_SQI_TxBufferThresholdIntGet Returns the value to trigger the transmit buffer threshold interrupt. PLIB_SQI_TxBufferThresholdIntSet Sets the value to trigger the transmit buffer threshold interrupt. PLIB_SQI_TxBufferThresholdSet Sets the transmit command threshold. PLIB_SQI_WriteProtectClear Clears the Write-Protect function to be disabled on SQID2 in single or dual lane modes. PLIB_SQI_WriteProtectGet Gets the state of the write-protect feature on SQID2. PLIB_SQI_WriteProtectSet Sets the write-protect feature to be enabled on SQID2 in single or dual lane modes only. PLIB_SQI_XIPAddressBytesGet Returns the number of address bytes. PLIB_SQI_XIPAddressBytesSet Sets the number of address bytes. PLIB_SQI_XIPChipSelectGet Returns the current active Chip Select. PLIB_SQI_XIPChipSelectSet Activates the Chip Select in XIP mode. PLIB_SQI_XIPControlWord1Get Get the XIP mode Control Word 1. PLIB_SQI_XIPControlWord1Set Sets the XIP mode Control Word 1. PLIB_SQI_XIPControlWord2Get Gets the XIP mode Control Word 2. PLIB_SQI_XIPControlWord2Set Sets the XIP mode Control Word 2. PLIB_SQI_XIPControlWord3Get Gets the XIP mode Control Word 3. PLIB_SQI_XIPControlWord3Set Sets the XIP mode Control Word 3. PLIB_SQI_XIPControlWord4Get Gets the XIP mode Control Word 4. PLIB_SQI_XIPControlWord4Set Sets the XIP mode Control Word 4. PLIB_SQI_XIPDDRModeSet Selects the rate mode (SDR/DDR) for different transactions in XIP mode. PLIB_SQI_XIPDummyBytesGet Sets the number of dummy bytes. PLIB_SQI_XIPDummyBytesSet Sets the number of dummy bytes. PLIB_SQI_XIPLaneModeSet Selects the lane (Single/Dual/Quad) mode for different transaction in XIP mode. PLIB_SQI_XIPModeBytesGet Returns the number of bytes used for mode code command. PLIB_SQI_XIPModeBytesSet Allocates the bytes for mode code command. PLIB_SQI_XIPModeCodeGet Returns the mode code op-code. PLIB_SQI_XIPModeCodeSet Sets the mode code command. PLIB_SQI_XIPReadOpcodeGet Returns the read op code in XIP mode. PLIB_SQI_XIPReadOpcodeSet Sets the read op code in XIP mode. PLIB_SQI_XIPSDRCommandDDRDataGet Returns the SQI command in SDR mode and Data in DDR mode bit value. PLIB_SQI_XIPSDRCommandDDRDataSet Sets the SQI command in SDR mode. Description Serial Quad Interface (SQI) Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the SQI Peripheral Library. File Name plib_sqi.h Company Microchip Technology Inc. help_plib_sqi.h Identifies the various enumerations in SQI modules supported. Peripheral Libraries Help SQI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2034 Enumerations Name Description SQI_ADDR_BYTES Defines the list of SQI address bytes. SQI_BD_CTRL_WORD Defines the list of SQI Buffer Descriptor control word. SQI_BD_STATE Defines the list of SQI Buffer Descriptor states. SQI_CLK_DIV Defines the list of SQI Clock Divider values. SQI_CS_NUM Defines the list of SQI Chip Selects. SQI_CS_OEN Defines the list of SQI Chip Selects on which output is enable. SQI_DATA_FORMAT Defines the Data Format Options available (LSBF/MSBF). SQI_DATA_MODE Defines the list of SQI Data modes. SQI_DATA_OEN Defines the list of SQI Data pins on which output is enabled. SQI_DUMMY_BYTES Defines the list of SQI dummy bytes. SQI_INTERRUPTS Defines the list of SQI interrupts. SQI_LANE_MODE Defines the list of SQI Lane modes (single/dual/quad). SQI_MODE_BYTES Defines the list of SQI mode bytes. SQI_MODULE_ID Identifies the supported SQI modules. SQI_XFER_CMD Defines the list of SQI transfer commands. SQI_XFER_MODE Defines the list of SQI Transfer modes. Types Name Description SQI_DATA_TYPE Data type defining the SQI Data size. Description This enumeration identifies the SQI modules which are available on the microcontroller. This is the super set of all the possible instances that might be available on the Microchip microcontrollers. File Name help_plib_sqi.h Company Microchip Technology Inc. Peripheral Libraries Help SQI Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2035 Timer Peripheral Library This section describes the Timer Peripheral Library. Introduction This library provides a low-level abstraction of the Timer module on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The timer function is one of the basic features of a microcontroller. Timers are useful for generating accurate time-based periodic interrupts for software application or real-time operating systems. Other uses include counting external pulses or accurate timing measurement of external events using the timer's gate functions or producing precise time delays. Some timers can also be used to control timing of other peripherals. Using the Library This topic describes the basic architecture of the Timer Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_tmr.h The interface to the Timer Peripheral Library is defined in the plib_tmr.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the Timer Peripheral Library must include peripheral.h. Library File: The Timer Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the Timer module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all the functionality of the available timers on the device. Refer to the "Timer" chapters in the specific device data sheet or the family reference manual section specified in that chapter to determine the set of functions that are supported for each Timer module on your device. Description Microchip timers can be classified as: • Overflow-based • Period match-based These timers are essentially counters of a specific size (8-, 16-, or 32-bits wide) that increment based on the clock cycle and the timer prescaler. An application can monitor these counters to determine how much time has elapsed. The prescaler determines the timer granularity (resolution). It is a mechanism for generating the clock for the timer by the CPU clock. Every CPU has a clock source and the frequency of this source decides the rate at which instructions are executed by the processor. Most of the timers have the option of providing input clock prescalers, while some have the optional postscalers. The prescaler is used to divide the clock frequency of the Timer module and produce a clock for the timer. Each timer can be configured with a different source (internal or external) meaning, the source of the timer’s input clock is selectable. Both internal and external sources are available, depending on the part in use, with some timers providing a clock synchronization mechanisms with reference to external source. On some timers the clock edge, either the rising or the falling edge, on which the increment occurs, is selectable. Overflow-based Timers Overflow-based timers provide timer outputs or generate interrupts after a rollover from the maximum possible timer count. Overflow Timer Abstraction Diagram Peripheral Libraries Help Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2036 An overflow interrupt is triggered whenever the timer register overflows (i.e., reaches its maximum value based on its size as depicted by the following diagram). Period Match-based Timers Period match-based timers provide the timer outputs or generate interrupts upon a match between the counter's count value against the preprogrammed period. Period Match Timer Abstraction Diagram Peripheral Libraries Help Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2037 Gated Time Accumulation/Gated Control Mode The Gated Time Accumulation/Gate control mode allows the internal timer to increment based upon the duration of the high time applied to the timer input pin. In the Gated Time Accumulation mode, the timer clock source is derived from the internal system clock. When the input clock pin state is high, the timer will count up until a period match has occurred, or the input pin state is changed to a low state. A pin state transition from high-to-low will trigger an interrupt. Peripheral Libraries Help Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2038 Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Timer module. Library Interface Section Description General Setup Functions This section provides a set of functions that are used for: • Starting and stopping the timer • Setting up Single-shot or Continuous mode of operation • Timer oscillator control • Selecting if the external event can reset the counter • Timer assignment to various modules as the clock source • Setting up the counter resolution Power Control Functions This section provides functions that are required for controlling the timer operation in power-saving modes such as Idle and Sleep. Clock Source Control Functions This section provides a set of functions that are used for: • Selecting the input clock source • Setting up external clock synchronization • Selecting the source edge to increment the counter • Getting the source edge information Gate Control Functions This section provides a set of functions for controlling the gating logic of the timers. Preprocessing Functions This section provides a set of functions that are used for prescaler setup. Period Control Functions This section provides a set of functions for reading and writing the period. Counter Control Functions This section provides a set of functions for: • Reading and writing the counter values • Asynchronous write control Post-processing Functions This section provides a set of functions for controlling how the Timer module operates with other peripherals. This section only covers the peripherals that can be controlled from inside of the Timer module. For peripherals that have a dedicated timer, or the control lies within the peripheral, refer to that peripheral for the interface into the timers. This section can also provide a postscaling option, if available, on the microcontroller. Miscellaneous Functions This section provides a set of functions that are required to read status information. How the Library Works Timer modules can operate in the following modes: • Synchronous Clock Counter • Synchronous External Clock Counter • Asynchronous External Clock Counter • Gated Timer Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine availability. Synchronous Internal Clock Counter This section provides information and examples for setting up Synchronous Internal Clock Counter operation. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine availability. Description Synchronous Clock Counter operation provides the following capabilities: • Elapsed time measurements • Time delays • Periodic timer interrupts Peripheral Libraries Help Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2039 Setup Use the following steps for synchronous internal clock counter setup: 1. Some timer modules support multiple resolutions, which can be selected using PLIB_TMR_Mode16BitEnable or PLIB_TMR_Mode32BitEnable. 2. Set the start value of the timer using PLIB_TMR_Counter16BitSet or PLIB_TMR_Counter32BitSet. 3. The period register value can be set using PLIB_TMR_Period8BitSet, PLIB_TMR_Period16BitSet or PLIB_TMR_Period32BitSet. Use the appropriate function based on the resolution of the timer. 4. Clear the timer register using PLIB_TMR_Counter16BitClear or PLIB_TMR_Counter32BitClear. 5. In this mode, the input clock source for the timer is the internal clock, and is selected using PLIB_TMR_ClockSourceSelect, depending on which clock is used as the internal clock in the timer module of the device. 6. The prescaler for the clock can be selected using PLIB_TMR_PrescaleSelect. Pass in the desired prescaler into the function from the enumeration TMR_PRESCALE. 7. Start the timer once the setup is complete using PLIB_TMR_Start. The timer operation can be stopped using PLIB_TMR_Stop. Example: Synchronous Counter (Internal Clock) Setup // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. // Stop the timer PLIB_TMR_Stop(MY_TIMER_INSTANCE); // Set the prescaler, and set the clock source as internal PLIB_TMR_PrescaleSelect(MY_TIMER_INSTANCE, TMR_PRESCALE_TMRX_VALUE_1); PLIB_TMR_ClockSourceSelect(MY_TIMER_INSTANCE, TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK); // Clear the timer PLIB_TMR_Counter16BitClear(MY_TIMER_INSTANCE); // Load the period register PLIB_TMR_Period16BitSet(MY_TIMER_INSTANCE, 0xFFFF); // Start the timer PLIB_TMR_Start(MY_TIMER_INSTANCE); Timer interrupt is generated if enabled, when the timer count matches the period value if available, or when the counter overflows. Example: Changing Counter Value During Timer Operation // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. uint16_t timer_value; // Clear the timer timer_value = PLIB_TMR_Counter16BitGet(MY_TIMER_INSTANCE); if(timer_value > 0x0ff0) { PLIB_TMR_Counter16BitSet(MY_TIMER_INSTANCE, 0x000a); } Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine availability. Synchronous External Clock Counter This section provides information and examples for Synchronous External Clock Counter operation. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine availability. Description Synchronous external clock counter operation provides the following capabilities: • Counting periodic or non-periodic pulses • Use external clock as time base for timers Setup Use the following steps for synchronous external clock counter setup: 1. Some timer modules support multiple resolutions, which can be selected using PLIB_TMR_Mode16BitEnable or PLIB_TMR_Mode32BitEnable. Peripheral Libraries Help Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2040 2. The period register value can be set using PLIB_TMR_Period16BitSet or PLIB_TMR_Period32BitSet. Use the appropriate function based on the resolution of the timer. 3. Set the start value of the timer using PLIB_TMR_Counter16BitSet or PLIB_TMR_Counter32BitSet. 4. Some timer modules, can select an external clock as its input source. Use PLIB_TMR_ClockSourceSelect to select the external clock source. 5. The clock source is synchronized with the internal clock for synchronous operation. Use PLIB_TMR_ClockSourceExternalSyncEnable to synchronize the external clock source. 6. The prescaler for the clock can be selected using PLIB_TMR_PrescaleSelect. Pass in the desired prescaler into the function from the enumeration TMR_PRESCALE. 7. Clear the timer register using PLIB_TMR_Counter16BitClear or PLIB_TMR_Counter32BitClear. 8. Start the timer once the setup is complete using PLIB_TMR_Start. The timer operation can be stopped using PLIB_TMR_Stop. Example: Synchronous Counter (External Clock) Setup // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. // Stop the timer PLIB_TMR_Stop(MY_TIMER_INSTANCE); // Set the prescaler, and set the clock source as external and enable synchronization PLIB_TMR_PrescaleSelect(MY_TIMER_INSTANCE, TMR_PRESCALE_VALUE_256); PLIB_TMR_ClockSourceSelect(MY_TIMER_INSTANCE, TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN); PLIB_TMR_ClockSourceExternalSyncEnable(MY_TIMER_INSTANCE); // Clear the timer PLIB_TMR_Counter16BitClear(MY_TIMER_INSTANCE); // Load the period register PLIB_TMR_Period16BitSet(MY_TIMER_INSTANCE, 0xFFFF); // Start the timer PLIB_TMR_Start(MY_TIMER_INSTANCE); A timer interrupt is generated if enabled, when the timer count matches the period value if available, or when the counter overflows. Example: Changing Counter Value During Timer Operation // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. uint16_t timer_value; // read the current timer value timer_value = PLIB_TMR_Counter16BitGet(MY_TIMER_INSTANCE); if(timer_value > 0x0ff0) { PLIB_TMR_Counter16BitSet(MY_TIMER_INSTANCE, 0x000a); } Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine availability. Asynchronous Counter This section provides information and examples for setting up Asynchronous Counter operation. Note: Not all features are available on all devices. Refer to the "Timer" chapters in the specific device data sheet for availability. Description Asynchronous Counter operation provides the following capabilities: • The timer can operate in Sleep mode and can generate an interrupt on a period match • The processor can wake up from Sleep on the timer interrupt • The timer can be clocked from the Secondary Oscillator for real-time clock applications Setup Use the following steps for Asynchronous Counter setup: 1. Some timer modules support multiple resolutions, which can be selected using PLIB_TMR_Mode16BitEnable or PLIB_TMR_Mode32BitEnable. 2. The period register value can be set using PLIB_TMR_Period16BitSet or PLIB_TMR_Period32BitSet. Use the appropriate function based on the resolution of the timer. 3. Set the start value of the timer using PLIB_TMR_Counter16BitSet and PLIB_TMR_Counter32BitSet. Peripheral Libraries Help Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2041 4. Some timer modules can select an external clock as its input source. Use PLIB_TMR_ClockSourceSelect to select the external clock source. 5. For Asynchronous mode operation, the clock source is not synchronized with the internal clock. Use PLIB_TMR_ClockSourceExternalSyncDisable to disable the synchronization of the external clock source. 6. The prescaler for the clock can be selected using PLIB_TMR_PrescaleSelect. Pass in the desired prescaler into the function from the enumeration TMR_PRESCALE. 7. Clear the timer register using PLIB_TMR_Counter16BitClear or PLIB_TMR_Counter32BitClear. 8. Start the timer once the setup is complete using PLIB_TMR_Start. The timer operation can be stopped using PLIB_TMR_Stop. Example: Asynchronous Counter Setup // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. // Stop the timer PLIB_TMR_Stop(MY_TIMER_INSTANCE); // Set the prescaler, and set the clock source as external and disable synchronization PLIB_TMR_PrescaleSelect(MY_TIMER_INSTANCE, TMR_PRESCALE_VALUE_64); PLIB_TMR_ClockSourceSelect(MY_TIMER_INSTANCE, TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN); PLIB_TMR_ClockSourceExternalSyncDisable(MY_TIMER_INSTANCE); // Clear the timer PLIB_TMR_Counter16BitClear(MY_TIMER_INSTANCE); // Load the period register PLIB_TMR_Period16BitSet(MY_TIMER_INSTANCE, 0x7F); // Start the timer PLIB_TMR_Start(MY_TIMER_INSTANCE); A timer interrupt is generated if enabled, when the timer count matches the period value if available, or when the counter overflows. Note: Not all features are available on all devices. Refer to the "Timer" chapters in the specific device data sheet for availability. Gated Timer This section provides information and examples for setting up Gated Timer operation. Note: Not all features are available on all devices. Refer to the "Timer" chapters in the specific device data sheet for availability. Description Gated Timer operation can be used to allow measurement of an external signal. Setup Use the following steps for Gated Timer setup: 1. Some timer modules support multiple resolutions, which can be selected using PLIB_TMR_Mode16BitEnable or PLIB_TMR_Mode32BitEnable. 2. The period register value can be set using PLIB_TMR_Period16BitSet or PLIB_TMR_Period32BitSet. Use the appropriate function based on the resolution of the timer. 3. Set the start value of the timer using PLIB_TMR_Counter16BitSet and PLIB_TMR_Counter32BitSet. 4. In this mode, the input clock source for the timer is the internal clock, and is selected using PLIB_TMR_ClockSourceSelect, depending on which clock is used as the internal clock in the timer module of the device. 5. The prescaler for the clock can be selected using PLIB_TMR_PrescaleSelect. Pass in the desired pre scaler into the function from the enumeration TMR_PRESCALE. 6. Clear the timer register using PLIB_TMR_Counter16BitClear or PLIB_TMR_Counter32BitClear. 7. Gated operation can be enabled using the function PLIB_TMR_GateEnable. 8. Start the timer once the setup is complete using PLIB_TMR_Start. The timer operation can be stopped using PLIB_TMR_Stop. Example: Gated Timer Setup // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. // Stop the timer PLIB_TMR_Stop(MY_TIMER_INSTANCE); // Set the prescaler, and set the clock source as external and disable synchronization PLIB_TMR_PrescaleSelect(MY_TIMER_INSTANCE, TMR_PRESCALE_VALUE_64); PLIB_TMR_ClockSourceSelect(MY_TIMER_INSTANCE, TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN); Peripheral Libraries Help Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2042 PLIB_TMR_ClockSourceExternalSyncDisable(MY_TIMER_INSTANCE); // Clear the timer PLIB_TMR_Counter16BitClear(MY_TIMER_INSTANCE); // Load the period register PLIB_TMR_Period16BitSet(MY_TIMER_INSTANCE, 0x7F00); // Enable the gate timer PLIB_TMR_GateEnable(MY_TIMER_INSTANCE); // Start the timer PLIB_TMR_Start(MY_TIMER_INSTANCE); A timer interrupt is generated if enabled, on the falling edge of the gate signal. Note: Not all features are available on all devices. Refer to the "Timer" chapters in the specific device data sheet for availability. Other Features This section provides information on additional features. Description Each of the following modes can additionally support some or all of the features listed. Please refer to the specific device data sheet or family reference manual for details. Operation During Sleep Mode When the Timer module is configured to operate in Asynchronous mode (with an external clock source), it will continue to increment each timer clock (or prescale multiple of clocks) during Sleep mode. Operation During Idle Mode A Timer module can continue to operate in Idle mode by calling PLIB_TMR_StopInIdleDisable, or can stop operation in Idle mode by calling PLIB_TMR_StopInIdleEnable. Timer Mode Control • PLIB_TMR_Mode16BitEnable: This interface enables 16-bit mode and disables 32-bit mode • PLIB_TMR_Mode32BitEnable: This interface enables 32-bit mode and disables 16-bit mode Timer Usage Mode Some timers operate in either Period Match mode or Overflow mode. The mode state can be retrieved from the Timer Peripheral Library using PLI_TMR_IsPeriodMatchBased. This function returns 'true' Period Match mode and 'false' for Overflow mode. Timer Prescaler Information Prescaler divisor information associated with the respective prescaler value selected through TMR_PRESCALE can be retrieved through PLIB_TMR_PrescaleDivisorGet. The true prescaler value can be obtained by using PLIB_TMR_PrescaleGet. Configuring the Library The library is configured for the supported Timer modules when the processor is chosen in the MPLAB X IDE. Library Interface a) General Setup Functions Name Description PLIB_TMR_Mode16BitEnable Enables the Timer module for 16-bit operation and disables all other modes. PLIB_TMR_Mode32BitEnable Enables 32-bit operation on the Timer module combination. PLIB_TMR_Start Starts/enables the indexed timer. PLIB_TMR_Stop Stops/disables the indexed timer. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2043 b) Power Control Functions Name Description PLIB_TMR_StopInIdleDisable Continue module operation when the device enters Idle mode. PLIB_TMR_StopInIdleEnable Discontinues module operation when the device enters Idle mode. c) Clock Source Control Functions Name Description PLIB_TMR_ClockSourceExternalSyncDisable Disables the clock synchronization of the external input. PLIB_TMR_ClockSourceExternalSyncEnable Enables the clock synchronization of the external input. PLIB_TMR_ClockSourceSelect Selects the clock source. d) Gate Control Functions Name Description PLIB_TMR_GateDisable Enables counting regardless of the corresponding timer gate function. PLIB_TMR_GateEnable Enables counting controlled by the corresponding gate function. e) Preprocessing Functions Name Description PLIB_TMR_PrescaleDivisorGet Gets the prescaler divisor information. PLIB_TMR_PrescaleGet Gets the prescaler divisor value. PLIB_TMR_PrescaleSelect Selects the clock prescaler. f) Period Control Functions Name Description PLIB_TMR_Period16BitGet Gets the 16-bit period value. PLIB_TMR_Period16BitSet Sets the 16-bit period value. PLIB_TMR_Period32BitGet Gets the 32-bit period value. PLIB_TMR_Period32BitSet Sets the 32-bit period value. g) Counter Control Functions Name Description PLIB_TMR_Counter16BitClear Clears the 16-bit timer value. PLIB_TMR_Counter16BitGet Gets the 16-bit timer value. PLIB_TMR_Counter16BitSet Sets the 16-bit timer value. PLIB_TMR_Counter32BitClear Clears the 32-bit timer value. PLIB_TMR_Counter32BitGet Gets the 32-bit timer value. PLIB_TMR_Counter32BitSet Sets the 32-bit timer value. PLIB_TMR_CounterAsyncWriteDisable Disables the writes to the counter register until the pending write operation completes. PLIB_TMR_CounterAsyncWriteEnable Enables back-to-back writes with legacy asynchronous timer functionality. PLIB_TMR_CounterAsyncWriteInProgress Returns the status of the counter write in Asynchronous mode. i) Miscellaneous Functions Name Description PLIB_TMR_IsPeriodMatchBased Gets the operating mode state of the Timer module based on Period Match or Overflow mode. j) Feature Existence Functions Name Description PLIB_TMR_ExistsClockSource Identifies whether the ClockSource feature exists on the Timer module. PLIB_TMR_ExistsClockSourceSync Identifies whether the ClockSourceSync feature exists on the Timer module. PLIB_TMR_ExistsCounter16Bit Identifies whether the Counter16Bit feature exists on the Timer module. PLIB_TMR_ExistsCounter32Bit Identifies whether the Counter32Bit feature exists on the Timer module. PLIB_TMR_ExistsCounterAsyncWriteControl Identifies whether the CounterAsyncWriteControl feature exists on the Timer module. PLIB_TMR_ExistsCounterAsyncWriteInProgress Identifies whether the CounterAsyncWriteInProgress feature exists on the Timer module. PLIB_TMR_ExistsEnableControl Identifies whether the EnableControl feature exists on the Timer module. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2044 PLIB_TMR_ExistsGatedTimeAccumulation Identifies whether the GatedTimeAccumulation feature exists on the Timer module. PLIB_TMR_ExistsMode16Bit Identifies whether the Mode16Bit feature exists on the Timer module. PLIB_TMR_ExistsMode32Bit Identifies whether the Mode32Bit feature exists on the Timer module. PLIB_TMR_ExistsPeriod16Bit Identifies whether the Period16Bit feature exists on the Timer module. PLIB_TMR_ExistsPeriod32Bit Identifies whether the Period32Bit feature exists on the Timer module. PLIB_TMR_ExistsPrescale Identifies whether the Prescale feature exists on the Timer module. PLIB_TMR_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the Timer module. PLIB_TMR_ExistsTimerOperationMode Identifies whether the TimerOperationMode feature exists on the Timer module. k) Data Types and Constants Name Description TMR_CLOCK_SOURCE Data type defining the different clock sources. TMR_MODULE_ID Identifies the supported Timer modules. TMR_PRESCALE Defines the list of possible prescaler values. Description This section describes the Application Programming Interface (API) functions of the Timer Peripheral Library. Refer to each section for a detailed description. a) General Setup Functions PLIB_TMR_Mode16BitEnable Function Enables the Timer module for 16-bit operation and disables all other modes. File plib_tmr.h C void PLIB_TMR_Mode16BitEnable(TMR_MODULE_ID index); Returns None. Description This function enables the Timer module for 16-bit operation and disables all other modes. Remarks Calling this function disables the operation of the Timer module 8-bit mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsMode16Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Mode16BitEnable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_Mode16BitEnable( TMR_MODULE_ID index) Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2045 PLIB_TMR_Mode32BitEnable Function Enables 32-bit operation on the Timer module combination. File plib_tmr.h C void PLIB_TMR_Mode32BitEnable(TMR_MODULE_ID index); Returns None. Description This function enables the Timer module and the index +1 Timer module to act as one 32-bit timer module and disables all other modes. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsMode32Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Mode32BitEnable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_Mode32BitEnable( TMR_MODULE_ID index) PLIB_TMR_Start Function Starts/enables the indexed timer. File plib_tmr.h C void PLIB_TMR_Start(TMR_MODULE_ID index); Returns None. Description This function starts/enables the indexed timer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2046 PLIB_TMR_Start(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_Start( TMR_MODULE_ID index) PLIB_TMR_Stop Function Stops/disables the indexed timer. File plib_tmr.h C void PLIB_TMR_Stop(TMR_MODULE_ID index); Returns None. Description This function stops/disables the indexed timer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Stop(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_Stop( TMR_MODULE_ID index) b) Power Control Functions PLIB_TMR_StopInIdleDisable Function Continue module operation when the device enters Idle mode. File plib_tmr.h C void PLIB_TMR_StopInIdleDisable(TMR_MODULE_ID index); Returns None. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2047 Description This function continues module operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsStopInIdleControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_StopInIdleDisable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_StopInIdleDisable( TMR_MODULE_ID index) PLIB_TMR_StopInIdleEnable Function Discontinues module operation when the device enters Idle mode. File plib_tmr.h C void PLIB_TMR_StopInIdleEnable(TMR_MODULE_ID index); Returns None. Description This function discontinues module operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsStopInIdleControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_StopInIdleEnable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_StopInIdleEnable( TMR_MODULE_ID index) c) Clock Source Control Functions Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2048 PLIB_TMR_ClockSourceExternalSyncDisable Function Disables the clock synchronization of the external input. File plib_tmr.h C void PLIB_TMR_ClockSourceExternalSyncDisable(TMR_MODULE_ID index); Returns None. Description This function disables the clock synchronization of the external input. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsClockSourceSync in your application to determine whether this feature is available. Preconditions The timer module must be configured to use the external clock using the function PLIB_TMR_ClockSourceSelect with the clock source as TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN. If the function PLIB_TMR_ClockSourceSelect configures the clock with some other enumeration, this function will have no effect. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_ClockSourceExternalSyncDisable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_ClockSourceExternalSyncDisable( TMR_MODULE_ID index) PLIB_TMR_ClockSourceExternalSyncEnable Function Enables the clock synchronization of the external input. File plib_tmr.h C void PLIB_TMR_ClockSourceExternalSyncEnable(TMR_MODULE_ID index); Returns None. Description This function enables the clock synchronization of the external input. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsClockSourceSync in your application to determine whether this feature is available. Preconditions The timer module must be configured to use the external clock using the function PLIB_TMR_ClockSourceSelect with the clock source as TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN. If the function PLIB_TMR_ClockSourceSelect configures the clock with some other enumeration, this function will have no effect. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2049 Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_ClockSourceExternalSyncEnable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_ClockSourceExternalSyncEnable( TMR_MODULE_ID index) PLIB_TMR_ClockSourceSelect Function Selects the clock source. File plib_tmr.h C void PLIB_TMR_ClockSourceSelect(TMR_MODULE_ID index, TMR_CLOCK_SOURCE source); Returns None. Description This function selects the clock source. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsClockSource in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_ClockSourceSelect(MY_TMR_INSTANCE, TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK); Parameters Parameters Description index Identifier for the device instance to be configured source One of the possible values of TMR_CLOCK_SOURCE Function void PLIB_TMR_ClockSourceSelect( TMR_MODULE_ID index, TMR_CLOCK_SOURCE source) d) Gate Control Functions PLIB_TMR_GateDisable Function Enables counting regardless of the corresponding timer gate function. File plib_tmr.h C void PLIB_TMR_GateDisable(TMR_MODULE_ID index); Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2050 Returns None. Description This function enables counting regardless of the gate function. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGatedTimeAccumulation in your application to determine whether this feature is available. Preconditions The timer must be enabled for this function to take effect. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GateDisable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_GateDisable( TMR_MODULE_ID index) PLIB_TMR_GateEnable Function Enables counting controlled by the corresponding gate function. File plib_tmr.h C void PLIB_TMR_GateEnable(TMR_MODULE_ID index); Returns None. Description This function enables counting controlled by the gate function. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGatedTimeAccumulation in your application to determine whether this feature is available. Preconditions The timer must be enabled, for this function to take effect. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GateEnable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_GateEnable( TMR_MODULE_ID index) e) Preprocessing Functions Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2051 PLIB_TMR_PrescaleDivisorGet Function Gets the prescaler divisor information. File plib_tmr.h C uint16_t PLIB_TMR_PrescaleDivisorGet(TMR_MODULE_ID index, TMR_PRESCALE prescale); Returns prescale divisor value Description This function returns the prescaler divisor information. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPrescale in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint16_t div = PLIB_TMR_PrescaleDivisorGet (MY_TMR_INSTANCE, TMR_PRESCALE_VALUE_1); Parameters Parameters Description index Identifier for the device instance to be configured prescale One of the possible values of TMR_PRESCALE Function uint16_t PLIB_TMR_PrescaleDivisorGet( TMR_MODULE_ID index, TMR_PRESCALE prescale) PLIB_TMR_PrescaleGet Function Gets the prescaler divisor value. File plib_tmr.h C uint16_t PLIB_TMR_PrescaleGet(TMR_MODULE_ID index); Returns Prescaler divisor value. Description This function returns the prescaler divisor value. The value returned will be direct number and not the enum equivalent. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPrescale in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2052 // application developer. uint16_t prescale; prescale = PLIB_TMR_PrescaleGet (MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint16_t PLIB_TMR_PrescaleGet ( TMR_MODULE_ID index ) PLIB_TMR_PrescaleSelect Function Selects the clock prescaler. File plib_tmr.h C void PLIB_TMR_PrescaleSelect(TMR_MODULE_ID index, TMR_PRESCALE prescale); Returns None. Description This function selects the clock prescaler. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPrescale in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_PrescaleSelect(MY_TMR_INSTANCE, TMR_PRESCALE_VALUE_8); Parameters Parameters Description index Identifier for the device instance to be configured prescale One of the possible values of TMR_PRESCALE Function void PLIB_TMR_PrescaleSelect( TMR_MODULE_ID index, TMR_PRESCALE prescale) f) Period Control Functions PLIB_TMR_Period16BitGet Function Gets the 16-bit period value. File plib_tmr.h C uint16_t PLIB_TMR_Period16BitGet(TMR_MODULE_ID index); Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2053 Returns period - 16-bit period value Description This function gets the 16-bit period value. Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod16Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint16_t period = PLIB_TMR_Period16BitGet(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint16_t PLIB_TMR_Period16BitGet( TMR_MODULE_ID index) PLIB_TMR_Period16BitSet Function Sets the 16-bit period value. File plib_tmr.h C void PLIB_TMR_Period16BitSet(TMR_MODULE_ID index, uint16_t period); Returns None. Description This function sets the 16-bit period value. Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod16Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. // where, MY_PERIOD_VALUE is the 16-bit value which needs to be stored in the // period register. PLIB_TMR_Period16BitSet(MY_TMR_INSTANCE, MY_PERIOD_VALUE); Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2054 Parameters Parameters Description index Identifier for the device instance to be configured period 16-bit period register value Function void PLIB_TMR_Period16BitSet( TMR_MODULE_ID index, uint16_t period) PLIB_TMR_Period32BitGet Function Gets the 32-bit period value. File plib_tmr.h C uint32_t PLIB_TMR_Period32BitGet(TMR_MODULE_ID index); Returns period - 32-bit period value Description This function gets the 32-bit period value. Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod32Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint32_t period = PLIB_TMR_Period32BitGet(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_TMR_Period32BitGet( TMR_MODULE_ID index) PLIB_TMR_Period32BitSet Function Sets the 32-bit period value. File plib_tmr.h C void PLIB_TMR_Period32BitSet(TMR_MODULE_ID index, uint32_t period); Returns None. Description This function sets the 32-bit period value. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2055 Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod32Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. // where, MY_PERIOD_VALUE is the 32-bit value which needs to be stored in the // period register. PLIB_TMR_Period32BitSet(MY_TMR_INSTANCE, MY_PERIOD_VALUE); Parameters Parameters Description index Identifier for the device instance to be configured period 32-bit period register value Function void PLIB_TMR_Period32BitSet( TMR_MODULE_ID index, uint32_t period) g) Counter Control Functions PLIB_TMR_Counter16BitClear Function Clears the 16-bit timer value. File plib_tmr.h C void PLIB_TMR_Counter16BitClear(TMR_MODULE_ID index); Returns None. Description This function clears the 16-bit timer value. Remarks When the timer register is written, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter16Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter16BitClear(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2056 Function uint8_t PLIB_TMR_Counter16BitClear( TMR_MODULE_ID index) PLIB_TMR_Counter16BitGet Function Gets the 16-bit timer value. File plib_tmr.h C uint16_t PLIB_TMR_Counter16BitGet(TMR_MODULE_ID index); Returns 16-bit timer value. Description This function gets the 16-bit timer value. Remarks PLIB_TMR_Counter16BitGet does not prevent the timer from incrementing during the same instruction cycle. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter16Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint16_t timerValue = PLIB_TMR_Counter16BitGet(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint16_t PLIB_TMR_Counter16BitGet( TMR_MODULE_ID index) PLIB_TMR_Counter16BitSet Function Sets the 16-bit timer value. File plib_tmr.h C void PLIB_TMR_Counter16BitSet(TMR_MODULE_ID index, uint16_t value); Returns None. Description This function sets the 16-bit timer value. Remarks When the timer register is written to, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter16Bit in your application to determine whether this feature is available. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2057 Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter16BitSet(MY_TMR_INSTANCE, 0x100); Parameters Parameters Description index Identifier for the device instance to be configured value 16-bit value to be set Function void PLIB_TMR_Counter16BitSet( TMR_MODULE_ID index, uint16_t value) PLIB_TMR_Counter32BitClear Function Clears the 32-bit timer value. File plib_tmr.h C void PLIB_TMR_Counter32BitClear(TMR_MODULE_ID index); Returns None. Description This function clears the 32-bit timer value. Remarks When the timer register is written, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter32Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter32BitClear(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_TMR_Counter32BitClear( TMR_MODULE_ID index) PLIB_TMR_Counter32BitGet Function Gets the 32-bit timer value. File plib_tmr.h Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2058 C uint32_t PLIB_TMR_Counter32BitGet(TMR_MODULE_ID index); Returns 32 bit timer value. Description This function gets the 32-bit timer value. Remarks PLIB_TMR_Counter32BitGet does not prevent the timer from incrementing during the same instruction cycle. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter32Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint32_t timerValue = PLIB_TMR_Counter32BitGet(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function uint32_t PLIB_TMR_Counter32BitGet( TMR_MODULE_ID index) PLIB_TMR_Counter32BitSet Function Sets the 32-bit timer value. File plib_tmr.h C void PLIB_TMR_Counter32BitSet(TMR_MODULE_ID index, uint32_t value); Returns None. Description This function sets the 32-bit timer value. Remarks When the timer register is written, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter32Bit in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter32BitSet(MY_TMR_INSTANCE, 0x1000000); Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2059 Parameters Parameters Description index Identifier for the device instance to be configured value 32-bit value to be set Function void PLIB_TMR_Counter32BitSet( TMR_MODULE_ID index, uint32_t value) PLIB_TMR_CounterAsyncWriteDisable Function Disables the writes to the counter register until the pending write operation completes. File plib_tmr.h C void PLIB_TMR_CounterAsyncWriteDisable(TMR_MODULE_ID index); Returns None. Description This function disables the writes to the counter register until the pending write operation completes. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounterAsyncWriteControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_CounterAsyncWriteDisable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_CounterAsyncWriteDisable( TMR_MODULE_ID index) PLIB_TMR_CounterAsyncWriteEnable Function Enables back-to-back writes with legacy asynchronous timer functionality. File plib_tmr.h C void PLIB_TMR_CounterAsyncWriteEnable(TMR_MODULE_ID index); Returns None. Description This function enables back-to-back writes with legacy asynchronous timer functionality. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2060 PLIB_TMR_ExistsCounterAsyncWriteControl in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_CounterAsyncWriteEnable(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_TMR_CounterAsyncWriteEnable( TMR_MODULE_ID index) PLIB_TMR_CounterAsyncWriteInProgress Function Returns the status of the counter write in Asynchronous mode. File plib_tmr.h C bool PLIB_TMR_CounterAsyncWriteInProgress(TMR_MODULE_ID index); Returns • true - Write is in progress • false - Write is complete Description This function returns the status of the counter write in Asynchronous mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounterAsyncWriteInProgress in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. bool inProgress = PLIB_TMR_CounterAsyncWriteInProgress(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_TMR_CounterAsyncWriteInProgress( TMR_MODULE_ID index) h) Post-processing Functions i) Miscellaneous Functions Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2061 PLIB_TMR_IsPeriodMatchBased Function Gets the operating mode state of the Timer module based on Period Match or Overflow mode. File plib_tmr.h C bool PLIB_TMR_IsPeriodMatchBased(TMR_MODULE_ID index); Returns • true - Operation in Period Match mode • false - Operation in Overflow mode Description This function gets the operating mode state of the Timer module based on Period Match or Overflow mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsTimerOperationMode in your application to determine whether this feature is available. Preconditions None. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. bool status = PLIB_TMR_IsPeriodMatchBased(MY_TMR_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_TMR_IsPeriodMatchBased ( TMR_MODULE_ID index) j) Feature Existence Functions PLIB_TMR_ExistsClockSource Function Identifies whether the ClockSource feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsClockSource(TMR_MODULE_ID index); Returns • true - The ClockSource feature is supported on the device • false - The ClockSource feature is not supported on the device Description This function identifies whether the ClockSource feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_ClockSourceSelect Remarks None. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2062 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsClockSource( TMR_MODULE_ID index ) PLIB_TMR_ExistsClockSourceSync Function Identifies whether the ClockSourceSync feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsClockSourceSync(TMR_MODULE_ID index); Returns • true - The ClockSourceSync feature is supported on the device • false - The ClockSourceSync feature is not supported on the device Description This function identifies whether the ClockSourceSync feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_ClockSourceExternalSyncEnable • PLIB_TMR_ClockSourceExternalSyncDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsClockSourceSync( TMR_MODULE_ID index ) PLIB_TMR_ExistsCounter16Bit Function Identifies whether the Counter16Bit feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsCounter16Bit(TMR_MODULE_ID index); Returns • true - The Counter16Bit feature is supported on the device • false - The Counter16Bit feature is not supported on the device Description This function identifies whether the Counter16Bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2063 • PLIB_TMR_Counter16BitSet • PLIB_TMR_Counter16BitGet • PLIB_TMR_Counter16BitClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsCounter16Bit( TMR_MODULE_ID index ) PLIB_TMR_ExistsCounter32Bit Function Identifies whether the Counter32Bit feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsCounter32Bit(TMR_MODULE_ID index); Returns • true - The Counter32Bit feature is supported on the device • false - The Counter32Bit feature is not supported on the device Description This function identifies whether the Counter32Bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Counter32BitSet • PLIB_TMR_Counter32BitGet • PLIB_TMR_Counter32BitClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsCounter32Bit( TMR_MODULE_ID index ) PLIB_TMR_ExistsCounterAsyncWriteControl Function Identifies whether the CounterAsyncWriteControl feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsCounterAsyncWriteControl(TMR_MODULE_ID index); Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2064 Returns • true - The CounterAsyncWriteControl feature is supported on the device • false - The CounterAsyncWriteControl feature is not supported on the device Description This function identifies whether the CounterAsyncWriteControl feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_CounterAsyncWriteEnable • PLIB_TMR_CounterAsyncWriteDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsCounterAsyncWriteControl( TMR_MODULE_ID index ) PLIB_TMR_ExistsCounterAsyncWriteInProgress Function Identifies whether the CounterAsyncWriteInProgress feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsCounterAsyncWriteInProgress(TMR_MODULE_ID index); Returns • true - The CounterAsyncWriteInProgress feature is supported on the device • false - The CounterAsyncWriteInProgress feature is not supported on the device Description This function identifies whether the CounterAsyncWriteInProgress feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_CounterAsyncWriteInProgress Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsCounterAsyncWriteInProgress( TMR_MODULE_ID index ) PLIB_TMR_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the Timer module. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2065 File plib_tmr.h C bool PLIB_TMR_ExistsEnableControl(TMR_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Start • PLIB_TMR_Stop Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsEnableControl( TMR_MODULE_ID index ) PLIB_TMR_ExistsGatedTimeAccumulation Function Identifies whether the GatedTimeAccumulation feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsGatedTimeAccumulation(TMR_MODULE_ID index); Returns • true - The GatedTimeAccumulation feature is supported on the device • false - The GatedTimeAccumulation feature is not supported on the device Description This function identifies whether the GatedTimeAccumulation feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_GateEnable • PLIB_TMR_GateDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsGatedTimeAccumulation( TMR_MODULE_ID index ) Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2066 PLIB_TMR_ExistsMode16Bit Function Identifies whether the Mode16Bit feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsMode16Bit(TMR_MODULE_ID index); Returns • true - The Mode16Bit feature is supported on the device • false - The Mode16Bit feature is not supported on the device Description This function identifies whether the Mode16Bit feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_Mode16BitEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsMode16Bit( TMR_MODULE_ID index ) PLIB_TMR_ExistsMode32Bit Function Identifies whether the Mode32Bit feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsMode32Bit(TMR_MODULE_ID index); Returns • true - The Mode32Bit feature is supported on the device • false - The Mode32Bit feature is not supported on the device Description This function identifies whether the Mode32Bit feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_Mode32BitEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2067 Function PLIB_TMR_ExistsMode32Bit( TMR_MODULE_ID index ) PLIB_TMR_ExistsPeriod16Bit Function Identifies whether the Period16Bit feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsPeriod16Bit(TMR_MODULE_ID index); Returns • true - The Period16Bit feature is supported on the device • false - The Period16Bit feature is not supported on the device Description This function identifies whether the Period16Bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Period16BitSet • PLIB_TMR_Period16BitGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsPeriod16Bit( TMR_MODULE_ID index ) PLIB_TMR_ExistsPeriod32Bit Function Identifies whether the Period32Bit feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsPeriod32Bit(TMR_MODULE_ID index); Returns • true - The Period32Bit feature is supported on the device • false - The Period32Bit feature is not supported on the device Description This function identifies whether the Period32Bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Period32BitSet • PLIB_TMR_Period32BitGet Remarks None. Preconditions None. Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2068 Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsPeriod32Bit( TMR_MODULE_ID index ) PLIB_TMR_ExistsPrescale Function Identifies whether the Prescale feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsPrescale(TMR_MODULE_ID index); Returns • true - The Prescale feature is supported on the device • false - The Prescale feature is not supported on the device Description This function identifies whether the Prescale feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_PrescaleSelect • PLIB_TMR_PrescaleGet • PLIB_TMR_PrescaleDivisorGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsPrescale( TMR_MODULE_ID index ) PLIB_TMR_ExistsStopInIdleControl Function Identifies whether the StopInIdle feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsStopInIdleControl(TMR_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_StopInIdleEnable • PLIB_TMR_StopInIdleDisable Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2069 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsStopInIdleControl( TMR_MODULE_ID index ) PLIB_TMR_ExistsTimerOperationMode Function Identifies whether the TimerOperationMode feature exists on the Timer module. File plib_tmr.h C bool PLIB_TMR_ExistsTimerOperationMode(TMR_MODULE_ID index); Returns • true - The TimerOperationMode feature is supported on the device • false - The TimerOperationMode feature is not supported on the device Description This function identifies whether the TimerOperationMode feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_IsPeriodMatchBased Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_TMR_ExistsTimerOperationMode( TMR_MODULE_ID index ) k) Data Types and Constants TMR_CLOCK_SOURCE Enumeration Data type defining the different clock sources. File help_plib_tmr.h C typedef enum { TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK, TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN } TMR_CLOCK_SOURCE; Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2070 Members Members Description TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK Clock source is the internal clock = FOSC/n (where n, is processor specific) TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN Clock source is the external input pin Description Clock sources selection enumeration This data type defines the different clock sources. TMR_MODULE_ID Enumeration Identifies the supported Timer modules. File help_plib_tmr.h C typedef enum { TMR_ID_0, TMR_ID_1, TMR_ID_2, TMR_ID_3, TMR_ID_4, TMR_ID_5, TMR_ID_6, TMR_ID_7, TMR_ID_8, TMR_ID_9, TMR_NUMBER_OF_MODULES } TMR_MODULE_ID; Members Members Description TMR_ID_0 Timer 0 TMR_ID_1 Timer 1 TMR_ID_2 Timer 2 TMR_ID_3 Timer 3 TMR_ID_4 Timer 4 TMR_ID_5 Timer 5 TMR_ID_6 Timer 6 TMR_ID_7 Timer 7 TMR_ID_8 Timer 8 TMR_ID_9 Timer 9 TMR_NUMBER_OF_MODULES Max number of timers Description TMR Module ID This enumeration identifies the available Timer modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. TMR_PRESCALE Enumeration Defines the list of possible prescaler values. File help_plib_tmr.h Peripheral Libraries Help Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2071 C typedef enum { TMR_PRESCALE_VALUE_1, TMR_PRESCALE_VALUE_2, TMR_PRESCALE_VALUE_4, TMR_PRESCALE_VALUE_8, TMR_PRESCALE_VALUE_16, TMR_PRESCALE_VALUE_32, TMR_PRESCALE_VALUE_64, TMR_PRESCALE_VALUE_256 } TMR_PRESCALE; Members Members Description TMR_PRESCALE_VALUE_1 Timer Prescaler Value 1:1 TMR_PRESCALE_VALUE_2 Timer Prescaler Value 1:2 TMR_PRESCALE_VALUE_4 Timer Prescaler Value 1:4 TMR_PRESCALE_VALUE_8 Timer Prescaler Value 1:8 TMR_PRESCALE_VALUE_16 Timer Prescaler Value 1:16 TMR_PRESCALE_VALUE_32 Timer Prescaler Value 1:32 TMR_PRESCALE_VALUE_64 Timer Prescaler Value 1:64 TMR_PRESCALE_VALUE_256 Timer Prescaler Value 1:256 Description Prescaler Values This macro defines the list of possible prescaler values. Files Files Name Description plib_tmr.h Timer Peripheral Library interface header. help_plib_tmr.h This is file help_plib_tmr.h. Description This section lists the source and header files used by the library. plib_tmr.h Timer Peripheral Library interface header. Functions Name Description PLIB_TMR_ClockSourceExternalSyncDisable Disables the clock synchronization of the external input. PLIB_TMR_ClockSourceExternalSyncEnable Enables the clock synchronization of the external input. PLIB_TMR_ClockSourceSelect Selects the clock source. PLIB_TMR_Counter16BitClear Clears the 16-bit timer value. PLIB_TMR_Counter16BitGet Gets the 16-bit timer value. PLIB_TMR_Counter16BitSet Sets the 16-bit timer value. PLIB_TMR_Counter32BitClear Clears the 32-bit timer value. PLIB_TMR_Counter32BitGet Gets the 32-bit timer value. PLIB_TMR_Counter32BitSet Sets the 32-bit timer value. PLIB_TMR_CounterAsyncWriteDisable Disables the writes to the counter register until the pending write operation completes. PLIB_TMR_CounterAsyncWriteEnable Enables back-to-back writes with legacy asynchronous timer functionality. PLIB_TMR_CounterAsyncWriteInProgress Returns the status of the counter write in Asynchronous mode. PLIB_TMR_ExistsClockSource Identifies whether the ClockSource feature exists on the Timer module. PLIB_TMR_ExistsClockSourceSync Identifies whether the ClockSourceSync feature exists on the Timer module. Peripheral Libraries Help Timer Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2072 PLIB_TMR_ExistsCounter16Bit Identifies whether the Counter16Bit feature exists on the Timer module. PLIB_TMR_ExistsCounter32Bit Identifies whether the Counter32Bit feature exists on the Timer module. PLIB_TMR_ExistsCounterAsyncWriteControl Identifies whether the CounterAsyncWriteControl feature exists on the Timer module. PLIB_TMR_ExistsCounterAsyncWriteInProgress Identifies whether the CounterAsyncWriteInProgress feature exists on the Timer module. PLIB_TMR_ExistsEnableControl Identifies whether the EnableControl feature exists on the Timer module. PLIB_TMR_ExistsGatedTimeAccumulation Identifies whether the GatedTimeAccumulation feature exists on the Timer module. PLIB_TMR_ExistsMode16Bit Identifies whether the Mode16Bit feature exists on the Timer module. PLIB_TMR_ExistsMode32Bit Identifies whether the Mode32Bit feature exists on the Timer module. PLIB_TMR_ExistsPeriod16Bit Identifies whether the Period16Bit feature exists on the Timer module. PLIB_TMR_ExistsPeriod32Bit Identifies whether the Period32Bit feature exists on the Timer module. PLIB_TMR_ExistsPrescale Identifies whether the Prescale feature exists on the Timer module. PLIB_TMR_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the Timer module. PLIB_TMR_ExistsTimerOperationMode Identifies whether the TimerOperationMode feature exists on the Timer module. PLIB_TMR_GateDisable Enables counting regardless of the corresponding timer gate function. PLIB_TMR_GateEnable Enables counting controlled by the corresponding gate function. PLIB_TMR_IsPeriodMatchBased Gets the operating mode state of the Timer module based on Period Match or Overflow mode. PLIB_TMR_Mode16BitEnable Enables the Timer module for 16-bit operation and disables all other modes. PLIB_TMR_Mode32BitEnable Enables 32-bit operation on the Timer module combination. PLIB_TMR_Period16BitGet Gets the 16-bit period value. PLIB_TMR_Period16BitSet Sets the 16-bit period value. PLIB_TMR_Period32BitGet Gets the 32-bit period value. PLIB_TMR_Period32BitSet Sets the 32-bit period value. PLIB_TMR_PrescaleDivisorGet Gets the prescaler divisor information. PLIB_TMR_PrescaleGet Gets the prescaler divisor value. PLIB_TMR_PrescaleSelect Selects the clock prescaler. PLIB_TMR_Start Starts/enables the indexed timer. PLIB_TMR_Stop Stops/disables the indexed timer. PLIB_TMR_StopInIdleDisable Continue module operation when the device enters Idle mode. PLIB_TMR_StopInIdleEnable Discontinues module operation when the device enters Idle mode. Description Timer Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Timer Peripheral Library. File Name plib_tmr.h Company Microchip Technology Inc. help_plib_tmr.h Enumerations Name Description TMR_CLOCK_SOURCE Data type defining the different clock sources. TMR_MODULE_ID Identifies the supported Timer modules. TMR_PRESCALE Defines the list of possible prescaler values. Description This is file help_plib_tmr.h. Peripheral Libraries Help Timer Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2073 USART Peripheral Library This section describes the USART Peripheral Library. Introduction This library provides a low-level abstraction of the USART Peripheral Library on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description The Universal Synchronous/Asynchronous Receiver/Transmitter (USART) module is the key component of the serial communications sub-system of a computer. The USART takes the data and transmits the individual bits in a sequential fashion. While receiving, the USART reassembles the bits into complete bytes. The data can be 8-bit or 9-bit. There are two primary forms of serial transmission: Asynchronous and Synchronous. Asynchronous Asynchronous transmission allows data to be transmitted without the sender having to send a clock signal to the receiver. Instead, the sender and receiver must agree on timing parameters (i.e., baud rate) in advance and special bits are added to each word, which are used to synchronize the sending and receiving units. When a word is given to the USART for asynchronous transmissions, a bit called the "Start" bit is added to the beginning of each word that is to be transmitted. The Start bit is used to alert the receiver that a word of data is about to be sent. After the Start bit, the individual bits of the word of data are sent, with the Least Significant bit (LSb) being sent first. When the entire data word has been sent, the transmitter may add a Parity bit that the transmitter generates. The Parity bit may be used by the receiver to perform simple error checking. Then, at least one Stop bit is sent by the transmitter. The Start bit is always a space and the Stop bits are always marks. Each transmitted bit persists for a period of 1/(Baud Rate). An on-chip dedicated Baud Rate Generator (BRG) is used to derive standard baud rate frequencies. When the receiver has received all of the bits in the data word, it may check for the Parity bits (both sender and receiver must agree on whether a Parity bit is to be used), and then the receiver looks for a Stop bit. If the Stop bit does not appear when it is supposed to, the USART module considers the entire word to be unintelligible and will report a framing error to the host processor when the data word is read. Note: Please refer to the "USART" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details. Synchronous Synchronous serial transmission requires that the sender and receiver share a clock with one another, or that the sender provide a strobe or other timing signal so that the receiver knows when to "read" the next bit of the data. This mode is not available on all microcontrollers. It is typically used in systems with a single master and one or more slaves. The master device contains the necessary circuitry for baud rate generation and supplies the clock for all devices in the system. There are two signal lines a bidirectional data line and a clock line. Since the data line is bidirectional, synchronous operation is only half-duplex. Start and Stop bits are not used in synchronous transmissions. Using the Library This topic describes the basic architecture of the USART Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_usart.h The interface to the USART Peripheral library is defined in the plib_usart.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the USART Peripheral library must include peripheral.h. Library File: The USART Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Hardware Abstraction Model This section describes the hardware abstraction model. Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2074 Description Hardware Abstraction Model Note 1: This feature is not available on all devices. Refer to the "USART" chapter in the specific device data sheet to determine availability. Hardware Abstraction Model The USART Peripheral Library provides interface routines to interact with the blocks shown in the diagram. The Baud Rate Controller controls the timing in Asynchronous mode, the desired baud rate can be programmed in the baud rate controller or, the baud rate controller can be configured to determine the baud rate of the transmitting device automatically. The Transmitter and Receiver are capable of handling 8-bit or 9-bit data, which can be programmed in the control logic. The 9th bit is used to transfer the address or the parity. Enable 9-bit mode if the hardware is to be used for address or parity detection. The Status and Control logic, provide the ability to control different ways the transmitter, receiver, and the baud rate controller can function. It also can provides status about the transmitter, receiver, or the baud rate controller. The Hardware Flow Control uses CTS and the RTS lines to perform handshaking. Flow control is the ability to stop, and then restart the flow without any loss of bytes. Flow control is needed for modems and other hardware to allow a jump in instantaneous flow rates. The USART module provides two types of infrared USART support: one is the IrDA clock output to support the external IrDA encoder and decoder, and the other is the full implementation of the IrDA encoder and decoder. Note: These features are not available on all devices. Please refer to the specific device data sheet to determine availability. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the USART module. Library Interface Section Description General Functions Provides setup and configuration interface routines for • IrDA • Hardware Flow Control • Operation in power saving modes. • and other general setup Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2075 Baud Rate Generator Functions Provides setup and configuration interface routines together with status routines for Baud Rate Generator (BRG). Transmitter Functions Provides setup, data transfer, error and the status interface routines for the transmitter. Receiver Functions Provides setup, data transfer, error and the status interface routines for the receiver. Feature Existence Functions Provides interface routines to determine existence of features. How the Library Works Provides information on how the library works. Description This section provides information on using the peripheral library with the USART module. The usage model for different scenarios is also described. Usage Model State Machine This section describes the transmission and reception state machine. Description The following state machine is for the transmission and reception during normal operation. This state machine provides a general idea of the usage model of the USART Peripheral Library. Refer to the usage model for more detailed steps for the scenario that is being used. Transmit and Receive State machine Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2076 Notes: 1. The wait states shown in red in the diagram can either be achieved using polled functions or using interrupts. 2. Refer to the specific USART mode in use for the setup and initialization steps. 3. Refer to the following table for the functions that can be used at each state. State Associated Function Setup and initialization Refer to the specific USART mode for detailed setup instructions. Wait for data to send Once the USART module has been appropriately set up and initialized, the state machine waits for the application to issue one of the send data functions. Wait for data to be received When the application is using Polled mode, the application can use the function PLIB_USART_ReceiverDataIsAvailable. When the application is using Interrupt mode, the application should wait for a receive interrupt. Enable transmitter Use the function PLIB_USART_TransmitterEnable to enable the transmitter Wait for transmitter to have empty space When the application is using polled mode, the application can use the function PLIB_USART_TransmitterBufferIsFull. When the application is using Interrupt mode, the application should wait for a transmit interrupt. Send data Use the function PLIB_USART_TransmitterByteSend to send data. If an address needs to be transmitted or if a byte needs to be transmitted with a Parity bit use the function PLIB_USART_Transmitter9BitsSend. Disable transmitter Use the function PLIB_USART_TransmitterDisable to disable the transmitter. Get status To get the status of the hardware module, use the set of functions, PLIB_USART_ReceiverFramingErrorHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred, and PLIB_USART_ReceiverOverrunHasOccurred. Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2077 Read data Use the function PLIB_USART_ReceiverByteReceive to read data. Clear overrun error Clear the overrun error using the function PLIB_USART_ReceiverOverrunErrorClear. Asynchronous USART Mode This section provides processes for setting up asynchronous transmission and reception. Description Asynchronous Transmission Setup 1. Set the desired baud rate using either PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 3. If available on the device, enable the asynchronous serial port using PLIB_USART_SyncModeSelect. 4. Set the number of data bits (8 or 9) and other line control modes using PLIB_USART_LineControlModeSelect. 5. Optional (if available on the device): If desired, enable the transmit interrupt. • Ensure that the interrupts are enabled for the system and the peripherals • Select the interrupt priority • Set up the transmit FIFO interrupt mode using PLIB_USART_TransmitterInterruptModeSelect. Refer to USART_TRANSMIT_INTR_MODE for a list of possible values. 6. Enable the USART module using the function PLIB_USART_Enable Example: Asynchronous Transmission Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently //being used by the system. PLIB_USART_BaudRateSet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY, baudRate); // Enable the asynchronous serial port. // enable asynchronous mode if the part supports it PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); /* Select 8 data bits, No parity and one stop bit */ PLIB_USART_LineControlModeSelect(MY_USART_INSTANCE, USART_8N1); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. Enable Transmission 1. Enable the transmission using PLIB_USART_TransmitterEnable. 2. Ensure that the transmit buffer is not full, before attempting to write into the transmit buffer. Either poll using PLIB_USART_TransmitterBufferIsFull or wait for the transmit interrupt. 3. Start the transmission using PLIB_USART_TransmitterByteSend (if transmitting 8-bit data) or PLIB_USART_Transmitter9BitsSend (if transmitting an address or if transmitting a byte with parity). 4. After the transmission is complete, disable the transmitter. Example: Asynchronous Transmission // Enable the transmission PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); // TODO - Either wait for Transmit buffer to be not full or wait for //an transmit interrupt. // Transmit the byte when Transmit buffer is empty. // where, my_byte is the 8 bit data to be transmitted PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, my_byte); Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2078 Asynchronous Transmission of Break Characters A break characters consists of a Start Bit followed by twelve bits of "0" and a Stop Bit. Setup and Transmission 1. Configure the desired mode, using the previous steps described. 2. Enable the transmitter using PLIB_USART_TransmitterEnable. 3. Transmit the break character using PLIB_USART_TransmitterBreakSend function. 4. Check if the break transmission is complete using PLIB_USART_TransmitterBreakSendIsComplete. 5. Transmission of the next bytes can start. Example: USART Break and Sync Transmission // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently //being used by the system. PLIB_USART_BaudRateSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the asynchronous serial port. // enable asynchronous mode if the part supports it PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); /* Select 8 data bits, No parity and one stop bit */ PLIB_USART_LineControlModeSelect(MY_USART_INSTANCE, USART_8N1); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Enable the transmission PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); // Start the transmission // Transmit the break character PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); // Transmit the byte while(PLIB_USART_TransmitterBreakSendIsComplete(MY_USART_INSTANCE)); PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, 0x55); Refer to the following steps for setting up asynchronous receptions and how to receive data. Asynchronous Reception Setup 1. Set the desired baud rate using PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 3. If available on the device, enable the asynchronous serial port using PLIB_USART_SyncModeSelect. 4. Set the number of data bits (8 or 9) and other line control modes using PLIB_USART_LineControlModeSelect. 5. Optional (if available on the device): If desired, enable the receive interrupt. • Ensure that the interrupts are enabled for the system and the peripherals • Select the interrupt priority • Set up the receive FIFO interrupt mode using PLIB_USART_ReceiverInterruptModeSelect. Refer to USART_RECEIVE_INTR_MODE for a list of possible values. 6. Optional: If inverted receive polarity is desired, use PLIB_USART_ReceiverIdleStateLowEnable. 7. If available on the device, enable the reception using PLIB_USART_ReceiverEnable. 8. Enable the USART module using PLIB_USART_Enable. Example: Asynchronous Reception Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently being Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2079 // used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous slave serial port. // enable asynchronous mode if the part supports it PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Start the reception // Enable the continuous reception PLIB_USART_ReceiverEnable(MY_USART_INSTANCE); Reception 1. Either wait for an interrupt, which will be generated when the reception is completed, or poll using PLIB_USART_ReceiverDataIsAvailable. 2. Read the status of the device using PLIB_USART_ReceiverOverrunHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred, and PLIB_USART_ReceiverFramingErrorHasOccurred. 3. Read the data using PLIB_USART_ReceiverByteReceive. 4. If an overrun error occurred, clear the error using PLIB_USART_ReceiverOverrunErrorClear. Example: Asynchronous Reception // TODO - Either wait for Receive buffer to have data or wait for // a receive interrupt. // read the data my_byte = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); // where, my_byte is the 8 bit data received // If overrun error clear the error. if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } Asynchronous Reception with Address Detection Mode A typical multi-processor communication protocol will differentiate between data bytes and address/control bytes. A common method is to use a 9th data bit to identify whether a data byte is address or data information. If the 9th bit is set, the data is processed as address or control information. If the 9th bit is cleared, the received data word is processed as data associated with the previous address/control byte. The protocol operates as follows: • The master device transmits a data word with 9th bit set. The data word contains the address of a slave device. • All slave devices in the communication chain receive the address word and check the slave address. • The slave device that was addressed will receive and process subsequent data bytes sent by the master device. All other slave devices will discard subsequent data bytes until a new address word(9th bit set) is received. This mode will typically be used in RS-485 systems. Setup 1. Set the desired baud rate using PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 3. If available on the device, enable the asynchronous serial port using PLIB_USART_SyncModeSelect. 4. Set the number of data bits (8 or 9) and other line control modes using PLIB_USART_LineControlModeSelect. 5. Optional (if available on the device): If desired, enable the receive interrupt. • Ensure that the interrupts are enabled for the system and the peripherals. Also select the interrupt priority. • Set up the receive FIFO interrupt mode by using the function PLIB_USART_ReceiverInterruptModeSelect. Refer to USART_RECEIVE_INTR_MODE for a list of possible values. • For Address Detect mode, configure PLIB_USART_ReceiverInterruptModeSelect with the receive FIFO interrupt mode as USART_RECEIVE_FIFO_ONE_CHAR. 6. Optional: If inverted receive polarity is desired, use PLIB_USART_ReceiverIdleStateLowEnable. 7. If available on the device, enable the reception using PLIB_USART_ReceiverEnable. 8. Enable address detection using PLIB_USART_ReceiverAddressDetectEnable. 9. Enable the USART module using PLIB_USART_Enable. Note: This feature is not available on all devices. On devices where automatic address detection is available, configure automatic address detection using PLIB_USART_ReceiverAddressAutoDetectEnable. Skip steps 2-6 in the following Reception section during the reception phase. Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2080 Example: Asynchronous Reception Setup ( with address detect enable) // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently // being used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous slave serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Set the reception to 9 bits to enable address byte. PLIB_USART_LineControlModeSelect(MY_USART_INSTANCE, USART_9N1); // Enable address detection. PLIB_USART_ReceiverAddressDetectEnable(MY_USART_INSTANCE); // Start the reception // Enable the continuous reception PLIB_USART_ReceiverEnable(MY_USART_INSTANCE); Reception 1. Either wait for an interrupt, which will be generated when the reception is completed or poll using PLIB_USART_ReceiverDataIsAvailable. 2. Read the address using PLIB_USART_ReceiverByteReceive. 3. The application determines if this is the device address. If the device is addressed, disable address detect using PLIB_USART_ReceiverAddressDetectDisable to allow subsequent data bytes to be received; otherwise, discard the received word. 4. Read the status of the device using PLIB_USART_ReceiverOverrunHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred, and PLIB_USART_ReceiverFramingErrorHasOccurred. 5. If an overrun error occurred, clear the error using PLIB_USART_ReceiverOverrunErrorClear. 6. If the device has been addressed, disable the address detection using PLIB_USART_ReceiverAddressDetectDisable, which will allow all received data into the receive buffer and generate interrupts if desired. 7. Optional (if available on the device): If a long packet is expected, the receive interrupt mode could be changed to buffer more than one data word between interrupts. Use PLIB_USART_ReceiverInterruptModeSelect with USART_RECEIVE_FIFO_HALF_FULL or USART_RECEIVE_FIFO_3B4FULL. 8. When the last data byte has been received, enable the address detect using PLIB_USART_ReceiverAddressDetectEnable, so that only address bytes will be received. 9. Optional (if available on the device): Ensure that the receive interrupt is configured to be triggered after each received word using PLIB_USART_ReceiverInterruptModeSelect with USART_RECEIVE_FIFO_ONE_CHAR. Example: Asynchronous Reception (with Address Detect) // Either wait for Receive buffer to have data or wait for a receive interrupt. int8_t my_address; // Receive the address if(PLIB_USART_ReceiverDataIsAvailable(MY_USART_INSTANCE)) { my_address = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); // where, my_address is the address received } // If overrun error clear the error. if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } if(my_address == MY_DEVICE_ADDRESS) { // The device has been addressed. PLIB_USART_ReceiverAddressDetectDisable(MY_USART_INSTANCE); } Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2081 // TODO - Receive the data bytes for the packet. Either wait for RX buffer //to have data or wait for a receive interrupt. // When all the bytes for the packet are received. // Enable address detection mode PLIB_USART_ReceiverAddressDetectEnable(MY_USART_INSTANCE); Synchronous Master Mode This section provides processes for setting up synchronous master transmission and reception. Note: The features described in this section are not available on all devices. Please refer to the "USART" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details. Description Synchronous Master Transmission Setup 1. Set the desired baud rate using PLIB_USART_BaudRateSet or PLIB_USART_BaudRateHighSet. 2. Enable the synchronous master serial port using PLIB_USART_SyncModeSelect, PLIB_USART_SyncClockSourceSelect, and PLIB_USART_Enable. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 4. Disable receive using PLIB_USART_ReceiverDisable. 5. Optional: If desired set the number of data bits to 9 (to send address byte or to enable parity check) using PLIB_USART_LineControlModeSelect. 6. Optional: If desired, enable the transmit interrupt, ensuring that the interrupts are enabled for the system and the peripherals. Example: Synchronous Master Transmission Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently being used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous master serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); // enable master clock PLIB_USART_SyncClockSourceSelect(MY_USART_INSTANCE, USART_SYNC_CLOCK_SOURCE_MASTER); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO Call the appropriate function. Transmission 1. Enable transmission using PLIB_USART_TransmitterEnable. 2. Ensure that the transmit buffer is not full before attempting to write onto the transmit buffer. Either poll using PLIB_USART_TransmitterBufferIsFull or wait for the transmit interrupt. Note: If using interrupts, make sure that interrupts are also enabled for the system and the peripherals. 3. Start the transmission using PLIB_USART_TransmitterByteSend (if transmitting 8 - bit data) or PLIB_USART_Transmitter9BitsSend (if transmitting address or if transmitting a byte with parity). 4. After the transmission is complete, disable the transmitter. Example: Synchronous Master Transmission // Enable the transmission PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); // TODO Either wait for Transmit buffer to be not full or wait for an transmit interrupt. // Transmit the byte when Transmit buffer is empty. // where, my_byte is the 8 bit data to be transmitted PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, my_byte); Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2082 Synchronous Master Reception Setup 1. Set the desired baud rate using PLIB_USART_BaudRateSet or PLIB_USART_BaudRateHighSet. 2. Enable the synchronous master serial port using PLIB_USART_SyncModeSelect, PLIB_USART_SyncClockSourceSelect, and PLIB_USART_Enable. 3. Set the appropriate IO direction and corresponding to RX and TX I/O pins. 4. Optional: If desired, enable the receive interrupt, ensuring that the interrupts are enabled for the system and the peripherals. 5. Start the reception using PLIB_USART_ReceiverDisable. Example: Synchronous Master Reception Setup uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently being used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); PLIB_USART_HandshakeModeSelect(MY_USART_INSTANCE, USART_HANDSHAKE_MODE_SIMPLEX); // Enable the synchronous master serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_SYNC_MODE); // enable master clock PLIB_USART_SyncClockSourceSelect(MY_USART_INSTANCE, USART_SYNC_CLOCK_SOURCE_MASTER); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Enable receive mode PLIB_USART_ReceiverEnable(MY_USART_INSTANCE); Reception 1. Either wait for an interrupt, which will be generated when the reception is completed, or poll using PLIB_USART_ReceiverDataIsAvailable. Note: If using interrupts, make sure that interrupts are also enabled for the system and the peripherals. 2. Read the status of the device using PLIB_USART_ReceiverOverrunHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred and PLIB_USART_ReceiverFramingErrorHasOccurred. 3. Read the data using PLIB_USART_ReceiverByteReceive. 4. If an overrun error occurred, clear the error using the function PLIB_USART_ReceiverOverrunErrorClear. Example: Synchronous Master Reception // Read the byte // where, my_byte is the 8 bit data to be transmitted my_byte = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } Synchronous Slave Mode This section provides processes for setting up synchronous slave transmission and reception. Note: This feature is not available on all devices. Please refer to the "USART" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details. Description Synchronous Slave Transmission Setup 1. Set the desired baud rate using either PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Enable the synchronous slave serial port using PLIB_USART_SyncModeSelect, PLIB_USART_SyncClockSourceSelect, and PLIB_USART_Enable. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2083 4. Disable receive mode using PLIB_USART_ReceiverDisable. 5. Optional: If desired, enable the transmit interrupt,ensuring that the interrupts are enabled for the system and the peripherals. Example: Synchronous Slave Transmission Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware //peripheral MY_CLOCK_FREQUENCY - is hardware clock frequency which is //currently being used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous slave serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_SYNC_MODE); // enable slave clock PLIB_USART_SyncClockSourceSelect(MY_USART_INSTANCE, USART_SYNC_CLOCK_SOURCE_SLAVE); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Disable receive mode PLIB_USART_ReceiverDisable(MY_USART_INSTANCE); // TODO - If using interrupts Enable the transmit interrupt // TODO - Call the appropriate function for the transmit enable interrupt, // TODO - Also, make sure that the interrupts are enabled for system and the peripherals. Transmission 1. Enable transmission using PLIB_USART_TransmitterEnable. 2. Ensure that the transmit buffer is not full before attempting to write into the transmit buffer. Either poll using PLIB_USART_TransmitterBufferIsFull or wait for the transmit interrupt. Note: If using interrupts, ensure that interrupts are also enabled for the system and the peripherals. 3. Start the transmission using PLIB_USART_TransmitterByteSend (if transmitting 8-bit data) or PLIB_USART_Transmitter9BitsSend (if transmitting address if transmitting a byte with parity) 4. After the transmission is complete, disable the transmitter. Example: Synchronous Slave Transmission // Enable the transmission PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); // TODO - Either wait for Transmit buffer to be not full or wait //for an transmit interrupt. // Transmit the byte when Transmit buffer is empty. PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, my_word); // where, my_word is the 9 bit data to be transmitted Synchronous Slave Reception Setup 1. Set the desired baud rate using PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Enable the synchronous master serial port using PLIB_USART_SyncModeSelect, PLIB_USART_SyncClockSourceSelect, and PLIB_USART_Enable. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 4. Optional: If desired, enable the receive interrupt, ensuring that the interrupts are enabled for the system and the peripherals. 5. Start the reception using PLIB_USART_ReceiverEnable. Example: Synchronous Slave Reception Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently //being used by the system. Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2084 PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous slave serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_SYNC_MODE); // enable master clock PLIB_USART_SyncClockSourceSelect(MY_USART_INSTANCE, USART_SYNC_CLOCK_SOURCE_SLAVE); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Start the reception // Enable the continuous reception PLIB_USART_ReceiverDisable(MY_USART_INSTANCE); Reception 1. Either wait for an interrupt, which will be generated when the reception is completed, or poll using PLIB_USART_ReceiverDataIsAvailable. Note: If using interrupts, ensure that interrupts are also enabled for the system and the peripherals. 2. Read the status of the device using PLIB_USART_ReceiverOverrunHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred, and PLIB_USART_ReceiverFramingErrorHasOccurred. 3. Read the data using PLIB_USART_ReceiverByteReceive. 4. If an overrun error occurred, clear the error using PLIB_USART_ReceiverOverrunErrorClear. Example: Synchronous Slave Reception // Transmit the data my_byte = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); // where, my_byte is the 8 bit data received // If overrun error clear the error. if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } Other Features This section describes additional features of the USART Peripheral Library. Note: The features described in this section are not available on all devices. Please refer to the "USART" chapter in the specific device data sheet or the family reference manual section specified in that chapter for details. Description IrDA Support Support for IrDA is available in some microcontrollers. 1. Enable IrDA support using PLIB_USART_IrDAEnable. IrDA support can be disabled using PLIB_USART_IrDADisable. 2. Optional: If using the external IrDA encoder and decoder, use the function PLIB_USART_OperationModeSelect with USART_ENABLE_TX_RX_BCLK_USED to output the 16x baud clock. 3. Optional: IrDA Transmit Polarity can be inverted using PLIB_USART_TransmitterIdleIsLowEnable. 4. Optional: IrDA Receive Polarity can be inverted using PLIB_USART_ReceiverIdleStateLowEnable. 5. Enable the USART using PLIB_USART_Enable. Loopback Support This is the mode in which the transmission is internally connected to reception. 1. Set the desired baud rate using PLIB_USART_BaudRateSet or PLIB_USART_BaudRateHighSet. 2. Set up the line control parameters (data bits, stop bits, parity, flow control) using PLIB_USART_LineControlModeSelect. Refer to USART_LINECONTROL_MODE for a list of possible values. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 4. Optional: If desired, enable the transmit interrupt, also make sure that the interrupts are enabled for the system and the peripherals. 5. Optional: Also select the interrupt priority. 6. Optional: Also, set up the transmit FIFO interrupt mode using PLIB_USART_TransmitterInterruptModeSelect. Refer to USART_TRANSMIT_INTR_MODE for a list of possible values. Peripheral Libraries Help USART Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2085 7. Enable the USART module using PLIB_USART_Enable and enable the transmission using PLIB_USART_TransmitterEnable. 8. Enable loopback using PLIB_USART_LoopbackEnable. Loopback can be disabled at any time using PLIB_USART_LoopbackDisable 9. Continue with transmission and/or reception using the same steps as for asynchronous transmission/reception. Auto Baud Support 1. Enable the auto baud detection using the function PLIB_USART_BaudRateAutoDetectEnable, which requires a reception of the Sync character (0x55). 2. Optional: Poll PLIB_USART_BaudRateAutoDetectIsComplete to check if the baud rate is detected. 3. Optional: Call PLIB_USART_BaudRateGet to get the baud rate that was detected. 4. Clear the receive interrupt. 5. On some microcontrollers, reading the data using PLIB_USART_ReceiverByteReceive may be required. Flow Control Support The USART can use Simplex or Flow Control modes: • Use PLIB_USART_HandshakeModeSelect to enable flow control (USART_HANDSHAKE_MODE_FLOW_CONTROL) or use simplex mode (USART_HANDSHAKE_MODE_SIMPLEX) selected from USART_HANDSHAKE_MODE. • To configure the USART line control features, use PLIB_USART_LineControlModeSelect selected from USART_LINECONTROL_MODE. • Additionally, the USART pins may need to be configured using PLIB_USART_OperationModeSelect and the appropriate values from USART_OPERATION_MODE. Operation During Sleep Mode When the device enters Sleep mode, all clock sources supplied to the USART modules are shut down. If the device enters Sleep mode in the middle of a USART transmission or reception operation, the operation is aborted and the USART pins are driven to default state. A Start bit, when detected, can wake up the device. • The application needs to enable the wake-up on start bit using PLIB_USART_WakeOnStartEnable just before entering Sleep mode, to wake-up the device • For the device to wake-up from sleep, reception of the Sync character or Wake-up Signal character is required • Optional: If using interrupts, a receive interrupt is generated Operation During Idle Mode When the device enters Idle mode, the system clock sources remain functional and the CPU stops code execution. • USART operation during Idle mode can be stopped using PLIB_USART_StopInIdleEnable. When the device enters Idle mode, the USART module operation is similar to that as in Sleep mode(Refer to Operation in Sleep Mode). • By default, the USART module continues to operate in Idle mode and provide full functionality USART Operation With DMA The DMA module can be used to transfer data between the USART and the CPU, without CPU assistance. 1. Set the desired baud rate using the function PLIB_USART_BaudRateSet or PLIB_USART_BaudRateHighSet. 2. Set up the line control parameters (data bits, stop bits, parity, flow control) using the function PLIB_USART_LineControlModeSelect. Refer to USART_LINECONTROL_MODE for a list of possible values. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 4. Enable the USART module using PLIB_USART_Enable and enable the transmission using PLIB_USART_TransmitterEnable. 5. Enable the Transmit, Receive, and Error interrupts, ensuring that the interrupts are enabled for the system and the peripherals. 6. Select the interrupt priority. 7. Set up the Transmit FIFO Interrupt mode and Receive FIFO Interrupt mode using the PLIB_USART_TransmitterInterruptModeSelect and PLIB_USART_ReceiverInterruptModeSelect functions. To generate interrupts for every character received, use USART_RECEIVE_FIFO_ONE_CHAR from USART_RECEIVE_INTR_MODE. 8. Configure the DMA to be used with the USART receiver and transmitter. Configuring the Library The library is configured for the supported USART modules when the processor is chosen in the MPLAB X IDE. Library Interface a) General Functions Name Description PLIB_USART_Disable Disables the specific USART module PLIB_USART_Enable Enables the specific USART module. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2086 PLIB_USART_HandshakeModeSelect Sets the data flow configuration. PLIB_USART_IrDADisable Disables the IrDA encoder and decoder. PLIB_USART_IrDAEnable Enables the IrDA encoder and decoder. PLIB_USART_LineControlModeSelect Sets the data flow configuration. PLIB_USART_LoopbackDisable Disables Loopback mode. PLIB_USART_LoopbackEnable Enables Loopback mode. PLIB_USART_OperationModeSelect Configures the operation mode of the USART module. PLIB_USART_StopInIdleDisable Disables the Stop in Idle mode (the USART module continues operation when the device is in Idle mode). PLIB_USART_StopInIdleEnable Discontinues operation when the device enters Idle mode. PLIB_USART_WakeOnStartDisable Disables the wake-up on start bit detection feature during Sleep mode. PLIB_USART_WakeOnStartEnable Enables the wake-up on start bit detection feature during Sleep mode. PLIB_USART_WakeOnStartIsEnabled Gets the state of the sync break event completion. PLIB_USART_ErrorsGet Return the status of all errors in the specified USART module. PLIB_USART_InitializeModeGeneral Enables or disables general features of the USART module. PLIB_USART_InitializeOperation Configures the Receive and Transmit FIFO interrupt levels and the hardware lines to be used by the module. PLIB_USART_AddressGet Gets the address for the Address Detect mode. PLIB_USART_AddressMaskGet Gets the address mask for the Address Detect mode. PLIB_USART_AddressMaskSet Sets the address mask for the Address Detect mode. PLIB_USART_AddressSet Sets the address for the Address Detect mode. PLIB_USART_ModuleIsBusy Returns the USART module's running status. PLIB_USART_RunInOverflowDisable Disables the Run in overflow condition mode. PLIB_USART_RunInOverflowEnable Enables the USART module to continue to operate when an overflow error condition has occurred. PLIB_USART_RunInOverflowIsEnabled Gets the status of the Run in Overflow condition. PLIB_USART_RunInSleepModeDisable Turns off the USART module's BRG clock during Sleep mode. PLIB_USART_RunInSleepModeEnable Allows the USART module's BRG clock to run when the device enters Sleep mode. PLIB_USART_RunInSleepModeIsEnabled Gets the status of Run in Sleep mode. b) Baud Rate Generator Functions Name Description PLIB_USART_BaudRateAutoDetectEnable Enables baud rate measurement on the next character, which requires reception of the Sync character. PLIB_USART_BaudRateAutoDetectIsComplete Gets the state of the automatic baud detection. PLIB_USART_BaudRateGet Gets the baud rate current in use. PLIB_USART_BaudRateHighDisable Disables the high baud rate selection. PLIB_USART_BaudRateHighEnable Enables high baud rate selection. PLIB_USART_BaudRateHighSet Sets the baud rate to the desired value. PLIB_USART_BaudRateSet Sets the baud rate to the desired value. PLIB_USART_BaudSetAndEnable Sets the baud rate to the desired value and enables the USART receiver, transmitter and the USART module. PLIB_USART_BRGClockSourceGet Gets the BRG clock source of the USART module. PLIB_USART_BRGClockSourceSelect Configures the BRG clock source of the USART module. c) Transmitter Functions Name Description PLIB_USART_Transmitter9BitsSend Data to be transmitted in the byte mode with the 9th bit. PLIB_USART_TransmitterBreakSend Transmits the break character. PLIB_USART_TransmitterBreakSendIsComplete Returns the status of the break transmission PLIB_USART_TransmitterBufferIsFull Gets the transmit buffer full status. PLIB_USART_TransmitterByteSend Data to be transmitted in the Byte mode. PLIB_USART_TransmitterDisable Disables the specific USART module transmitter. PLIB_USART_TransmitterEnable Enables the specific USART module transmitter. PLIB_USART_TransmitterIdleIsLowDisable Disables the Transmit Idle Low state. PLIB_USART_TransmitterIdleIsLowEnable Enables the Transmit Idle Low state. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2087 PLIB_USART_TransmitterInterruptModeSelect Sets the USART transmitter interrupt mode. PLIB_USART_TransmitterIsEmpty Gets the transmit shift register empty status. PLIB_USART_TransmitterAddressGet Returns the address of the USART TX register d) Receiver Functions Name Description PLIB_USART_ReceiverAddressAutoDetectDisable Disables the automatic Address Detect mode. PLIB_USART_ReceiverAddressAutoDetectEnable Setup the automatic Address Detect mode. PLIB_USART_ReceiverAddressDetectDisable Enables the Address Detect mode. PLIB_USART_ReceiverAddressDetectEnable Enables the Address Detect mode. PLIB_USART_ReceiverAddressIsReceived Checks and return if the data received is an address. PLIB_USART_ReceiverByteReceive Data to be received in the Byte mode. PLIB_USART_ReceiverDataIsAvailable Identifies if the receive data is available for the specified USART module. PLIB_USART_ReceiverDisable Disables the USART receiver. PLIB_USART_ReceiverEnable Enables the USART receiver. PLIB_USART_ReceiverFramingErrorHasOccurred Gets the framing error status. PLIB_USART_ReceiverIdleStateLowDisable Disables receive polarity inversion. PLIB_USART_ReceiverIdleStateLowEnable Enables receive polarity inversion. PLIB_USART_ReceiverInterruptModeSelect Sets the USART receiver FIFO level. PLIB_USART_ReceiverIsIdle Identifies if the receiver is idle. PLIB_USART_ReceiverOverrunErrorClear Clears a USART vverrun error. PLIB_USART_ReceiverOverrunHasOccurred Identifies if there was a receiver overrun error. PLIB_USART_ReceiverParityErrorHasOccurred Gets the parity error status. PLIB_USART_ReceiverAddressGet Returns the address of the USART RX register PLIB_USART_Receiver9BitsReceive Data to be received in the byte mode with the 9th bit. e) Feature Existence Functions Name Description PLIB_USART_ExistsBaudRate Identifies whether the BaudRate feature exists on the USART module. PLIB_USART_ExistsBaudRateAutoDetect Identifies whether the BaudRateAutoDetect feature exists on the USART module. PLIB_USART_ExistsBaudRateHigh Identifies whether the BaudRateHigh feature exists on the USART module. PLIB_USART_ExistsEnable Identifies whether the EnableControl feature exists on the USART module. PLIB_USART_ExistsHandshakeMode Identifies whether the HandShakeMode feature exists on the USART module. PLIB_USART_ExistsIrDA Identifies whether the IrDAControl feature exists on the USART module. PLIB_USART_ExistsLineControlMode Identifies whether the LineControlMode feature exists on the USART module. PLIB_USART_ExistsLoopback Identifies whether the Loopback feature exists on the USART module. PLIB_USART_ExistsOperationMode Identifies whether the OperationMode feature exists on the USART module. PLIB_USART_ExistsReceiver Identifies whether the Receiver feature exists on the USART module. PLIB_USART_ExistsReceiverAddressAutoDetect Identifies whether the ReceiverAddressAutoDetect feature exists on the USART module. PLIB_USART_ExistsReceiverAddressDetect Identifies whether the ReceiverAddressDetect feature exists on the USART module. PLIB_USART_ExistsReceiverDataAvailableStatus Identifies whether the ReceiverDataAvailable feature exists on the USART module PLIB_USART_ExistsReceiverEnable Identifies whether the ReceiverEnableControl feature exists on the USART module. PLIB_USART_ExistsReceiverFramingErrorStatus Identifies whether the ReceiverFramingError feature exists on the USART module. PLIB_USART_ExistsReceiverIdleStateLowEnable Identifies whether the ReceiverPolarityInvert feature exists on the USART module. PLIB_USART_ExistsReceiverIdleStatus Identifies whether the ReceiverIdle feature exists on the USART module. PLIB_USART_ExistsReceiverInterruptMode Identifies whether the ReceiverInterruptMode feature exists on the USART module. PLIB_USART_ExistsReceiverOverrunStatus Identifies whether the ReceiverOverrunError feature exists on the USART module. PLIB_USART_ExistsReceiverParityErrorStatus Identifies whether the ReceiverParityError feature exists on the USART module. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2088 PLIB_USART_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the USART module. PLIB_USART_ExistsTransmitter Identifies whether the Transmitter feature exists on the USART module. PLIB_USART_ExistsTransmitter9BitsSend Identifies whether the Transmitter9Bits feature exists on the USART module. PLIB_USART_ExistsTransmitterBreak Identifies whether the TransmitterBreak feature exists on the USART module. PLIB_USART_ExistsTransmitterBufferFullStatus Identifies whether the TransmitterBufferFull feature exists on the USART module. PLIB_USART_ExistsTransmitterEmptyStatus Identifies whether the TransmitterEmpty feature exists on the USART module. PLIB_USART_ExistsTransmitterEnable Identifies whether the TransmitterEnableControl feature exists on the USART module PLIB_USART_ExistsTransmitterIdleIsLow Identifies whether the TransmitterIdleIsLow feature exists on the USART module. PLIB_USART_ExistsTransmitterInterruptMode Identifies whether the TransmitterInterruptMode feature exists on the USART module. PLIB_USART_ExistsWakeOnStart Identifies whether the WakeOnStart feature exists on the USART module. PLIB_USART_ExistsReceiver9Bits Identifies whether the 9 Bits Receiver feature exists on the USART module. PLIB_USART_ExistsBRGClockSourceSelect Identifies whether the BRG Clock source select feature exists on the USART module. PLIB_USART_ExistsModuleBusyStatus Identifies whether the module running status feature exists on the USART module. PLIB_USART_ExistsReceiverAddress Identifies whether the Receiver Address feature exists on the USART module. PLIB_USART_ExistsReceiverAddressMask Identifies whether the Receiver Address Mask feature exists on the USART module. PLIB_USART_ExistsRunInOverflow Identifies whether the Run in overflow condition feature exists on the USART module. PLIB_USART_ExistsRunInSleepMode Identifies whether the Run in Sleep mode feature exists on the USART module. f) Data Types and Constants Name Description USART_HANDSHAKE_MODE Lists the USART handshake modes. USART_LINECONTROL_MODE Data type defining the different configurations by which the USART data flow can be configured. USART_MODULE_ID Enumeration: USART_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. _USART_MODULE_ID USART_OPERATION_MODE Data type defining the different configurations by which the USART can be enabled. USART_RECEIVE_INTR_MODE Data type defining the different Receive FIFO levels by which the USART receive interrupt modes can be configured. USART_TRANSMIT_INTR_MODE Data type defining the different transmit FIFO levels by which the USART transmit interrupt modes can be configured. Description This section describes the Application Programming Interface (API) functions of the USART Peripheral Library. Refer to each section for a detailed description. a) General Functions PLIB_USART_Disable Function Disables the specific USART module File plib_usart.h C void PLIB_USART_Disable(USART_MODULE_ID index); Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2089 Returns None. Description This function disables the specific USART module. Remarks The default state after any reset for a USART module is the disable state. If the USART is disabled, all of the related pins are in control of the general purpose I/O logic. Disabling the USART module resets the buffers to empty states. Any data characters in the buffers are lost and the baud rate is reset. All error and status bits are also reset. Disabling the USART while the USART is active, will abort all pending transmissions and receptions. Re-enabling the USART will restart the module in the same configuration. When disabled, the USART power consumption is minimal. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_Disable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_Disable ( USART_MODULE_ID index ) PLIB_USART_Enable Function Enables the specific USART module. File plib_usart.h C void PLIB_USART_Enable(USART_MODULE_ID index); Returns None. Description This function enables the specific USART module. Remarks By calling this function, the USART pins are controlled by the USART module. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_Enable(MY_USART_INSTANCE); Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2090 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_Enable ( USART_MODULE_ID index ) PLIB_USART_HandshakeModeSelect Function Sets the data flow configuration. File plib_usart.h C void PLIB_USART_HandshakeModeSelect(USART_MODULE_ID index, USART_HANDSHAKE_MODE handshakeConfig); Returns None. Description This function sets the USART data flow configuration based on the mask provided and the specified baud rate. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsHandshakeMode in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_HandshakeModeSelect(MY_USART_INSTANCE, USART_HANDSHAKE_MODE_SIMPLEX); Parameters Parameters Description index Identifier for the device instance to be configured mode For possible data flow configurations, refer to USART_HANDSHAKE_MODE Function void PLIB_USART_HandshakeModeSelect( USART_MODULE_ID index, USART_HANDSHAKE_MODE handshakeConfig) PLIB_USART_IrDADisable Function Disables the IrDA encoder and decoder. File plib_usart.h C void PLIB_USART_IrDADisable(USART_MODULE_ID index); Returns None. Description This function disables the IrDA encoder and decoder. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2091 Remarks By default, the IrDA Encoder and Decoder are disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsIrDA in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_IrDADisable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_IrDADisable ( USART_MODULE_ID index ) PLIB_USART_IrDAEnable Function Enables the IrDA encoder and decoder. File plib_usart.h C void PLIB_USART_IrDAEnable(USART_MODULE_ID index); Returns None. Description This function enables the IrDA encoder and decoder. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsIrDA in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_IrDAEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_IrDAEnable ( USART_MODULE_ID index ) PLIB_USART_LineControlModeSelect Function Sets the data flow configuration. File plib_usart.h Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2092 C void PLIB_USART_LineControlModeSelect(USART_MODULE_ID index, USART_LINECONTROL_MODE dataFlowConfig); Returns None. Description This function sets the USART data flow configuration based on the mask provided and the specified baud rate. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsLineControlMode in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_LineControlModeSelect(MY_USART_INSTANCE, USART_8N1); Parameters Parameters Description index Identifier for the device instance to be configured mode For possible data flow configurations, refer to USART_LINECONTROL_MODE Function void PLIB_USART_LineControlModeSelect( USART_MODULE_ID index, USART_LINECONTROL_MODE dataFlowConfig) PLIB_USART_LoopbackDisable Function Disables Loopback mode. File plib_usart.h C void PLIB_USART_LoopbackDisable(USART_MODULE_ID index); Returns None. Description This function disables Loopback mode. Remarks By default, Loopback mode is disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsLoopback in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_LoopbackDisable(MY_USART_INSTANCE); Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2093 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_LoopbackDisable ( USART_MODULE_ID index ) PLIB_USART_LoopbackEnable Function Enables Loopback mode. File plib_usart.h C void PLIB_USART_LoopbackEnable(USART_MODULE_ID index); Returns None. Description This function enables Loopback mode. Remarks By default, Loopback mode is disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsLoopback in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_LoopbackEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_LoopbackEnable ( USART_MODULE_ID index ) PLIB_USART_OperationModeSelect Function Configures the operation mode of the USART module. File plib_usart.h C void PLIB_USART_OperationModeSelect(USART_MODULE_ID index, USART_OPERATION_MODE operationmode); Returns None. Description This function configures the operation mode of the USART (i.e., controls the pins used by the USART module). Refer to USART_OPERATION_MODE for the possible settings. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2094 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsOperationMode in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_OperationModeSelect(MY_USART_INSTANCE, USART_ENABLE_TX_RX_BCLK_USED); Parameters Parameters Description index Identifier for the device instance to be configured operationmode One of the possible values from USART_OPERATION_MODE Function void PLIB_USART_OperationModeSelect( USART_MODULE_ID index, USART_OPERATION_MODE operationmode) PLIB_USART_StopInIdleDisable Function Disables the Stop in Idle mode (the USART module continues operation when the device is in Idle mode). File plib_usart.h C void PLIB_USART_StopInIdleDisable(USART_MODULE_ID index); Returns None. Description This function disables the Stop in Idle mode. The USART module continues operation when the device is in Idle mode. Remarks By default, the USART module will continue operation in Idle mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_StopInIdleDisable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_StopInIdleDisable ( USART_MODULE_ID index ) PLIB_USART_StopInIdleEnable Function Discontinues operation when the device enters Idle mode. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2095 File plib_usart.h C void PLIB_USART_StopInIdleEnable(USART_MODULE_ID index); Returns None. Description This function enables the USART module to discontinue operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_StopInIdleEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_StopInIdleEnable ( USART_MODULE_ID index ) PLIB_USART_WakeOnStartDisable Function Disables the wake-up on start bit detection feature during Sleep mode. File plib_usart.h C void PLIB_USART_WakeOnStartDisable(USART_MODULE_ID index); Returns None. Description This function disables the wake-up on start bit detection feature during Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsWakeOnStart in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_WakeOnStartDisable(MY_USART_INSTANCE); Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2096 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_WakeOnStartDisable ( USART_MODULE_ID index ) PLIB_USART_WakeOnStartEnable Function Enables the wake-up on start bit detection feature during Sleep mode. File plib_usart.h C void PLIB_USART_WakeOnStartEnable(USART_MODULE_ID index); Returns None. Description This function enables the wake-up on start feature during Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsWakeOnStart in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_WakeOnStartEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_WakeOnStartEnable ( USART_MODULE_ID index ) PLIB_USART_WakeOnStartIsEnabled Function Gets the state of the sync break event completion. File plib_usart.h C bool PLIB_USART_WakeOnStartIsEnabled(USART_MODULE_ID index); Returns None. Description This function returns the status of the sync break event, when called after enabling using PLIB_USART_WakeOnStartEnable. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsWakeOnStart in your application to determine whether this feature is available. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2097 Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 //Call the interface just prior to entering the sleep mode. PLIB_USART_WakeOnStartEnable(MY_USART_INSTANCE); // Check the status if the Sync break event is over. if(PLIB_USART_WakeOnStartIsEnabled(MY_USART_INSTANCE)) { // Do Something } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_WakeOnStartIsEnabled ( USART_MODULE_ID index ) PLIB_USART_ErrorsGet Function Return the status of all errors in the specified USART module. File plib_usart.h C USART_ERROR PLIB_USART_ErrorsGet(USART_MODULE_ID index); Returns Returns a bitmap of USART error status. Description This function returns status of all errors in the specified USART module. The return value can be bitwise AND'ed with a USART_ERROR type to know the status of a specific error. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Availability of this function can also be determined if all of the followings functions return true: • PLIB_USART_ExistsReceiverFramingErrorStatus • PLIB_USART_ExistsReceiverParityErrorStatus • PLIB_USART_ExistsReceiverOverrunStatus Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 USART_ERROR error; // Get the status of all errors. error = PLIB_USART_ErrorsGet(MY_USART_INSTANCE); // Check if parity error is active if(error & USART_ERROR_PARITY) { // Parity error is active. } else if(error & USART_ERROR_FRAMING) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2098 { // Framing error is active. } Parameters Parameters Description index Identifier for the device instance to be configured Function USART_ERROR PLIB_USART_ErrorsGet ( USART_MODULE_ID index ) PLIB_USART_InitializeModeGeneral Function Enables or disables general features of the USART module. File plib_usart.h C void PLIB_USART_InitializeModeGeneral(USART_MODULE_ID index, bool autobaud, bool loopBackMode, bool wakeFromSleep, bool irdaMode, bool stopInIdle); Returns None. Description This function enables or disables general features of the USART module. Remarks Enabling the wake from sleep feature will cause the first character that is received by the USART module to be discarded. This feature should only be enabled if the CPU is to placed in power saving mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Availability of this function can also be determined if all of the following functions return true: • PLIB_USART_ExistsLoopback • PLIB_USART_ExistsBaudRateAutoDetect • PLIB_USART_ExistsWakeOnStart • PLIB_USART_ExistsIrDA • PLIB_USART_ExistsStopInIdle Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 // Enable loopback, disable IrDA, disable auto baud detection and disable // wake from sleep. Enable stop in idle PLIB_USART_InitializeModeGeneral(MY_USART_INSTANCE, false, true, false, false, true); Parameters Parameters Description index Identifier for the device instance to be configured autobaud If true, auto baud rate detection is enabled. If false the feature is disabled. loopBackMode If true, loop back is enabled. If false the feature is disabled. wakeFromSleep If true, the USART module will wake up the CPU from sleep mode on USART activity. If false the feature is disabled. irdaMode If true, the IrDA mode is enabled. If false the feature is disabled. stopInIdle If true, module will stop functioning when CPU enters Idle mode. If false, the feature is disabled. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2099 Function void PLIB_USART_InitializeModeGeneral( USART_MODULE_ID index, bool autobaud, bool loopBackMode, bool wakeFromSleep, bool irdaMode, bool stopInIdle ); PLIB_USART_InitializeOperation Function Configures the Receive and Transmit FIFO interrupt levels and the hardware lines to be used by the module. File plib_usart.h C void PLIB_USART_InitializeOperation(USART_MODULE_ID index, USART_RECEIVE_INTR_MODE receiveInterruptMode, USART_TRANSMIT_INTR_MODE transmitInterruptMode, USART_OPERATION_MODE operationMode); Returns None. Description This function configures the Receive and Transmit FIFO interrupt levels and the hardware lines to be used by the module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Availability of this function can also be determined if all of the following functions return true: • PLIB_USART_ExistsReceiverInterruptMode • PLIB_USART_ExistsTransmitterInterruptMode • PLIB_USART_ExistsOperationMode Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 // Set receive FIFO to interrupt when FIFO is 3/4 level full // Set Transmit FIFO to interrupt when FIFO is empty // USART module will only use RX and TX hardware lines PLIB_USART_InitializeOperation(MY_USART_INSTANCE, USART_RECEIVE_FIFO_3B4FULL, USART_TRANSMIT_FIFO_EMPTY , USART_ENABLE_TX_RX_USED); Parameters Parameters Description index Identifier for the device instance to be configured receiveInterruptMode Receiver FIFO interrupt level transmitInterruptMode Transmit FIFO interrupt level operationMode Hardware lines to be used by the USART. Function void PLIB_USART_InitializeOperation( USART_MODULE_ID index , USART_RECEIVE_INTR_MODE receiveInterruptMode, USART_TRANSMIT_INTR_MODE transmitInterruptMode, USART_OPERATION_MODE operationMode); PLIB_USART_AddressGet Function Gets the address for the Address Detect mode. File plib_usart.h Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2100 C uint8_t PLIB_USART_AddressGet(USART_MODULE_ID index); Returns • address - The address being used Description This function returns the address value being used for the Address Detect mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddress in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint8_t address = 0; address = PLIB_USART_AddressGet (MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function uint8_t PLIB_USART_AddressGet ( USART_MODULE_ID index ) PLIB_USART_AddressMaskGet Function Gets the address mask for the Address Detect mode. File plib_usart.h C uint8_t PLIB_USART_AddressMaskGet(USART_MODULE_ID index); Returns • mask - Address mask being used Description This function returns the address mask value being used for the Address Detect mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressMask in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint8_t mask = 0; mask = PLIB_USART_AddressMaskGet (MY_USART_INSTANCE); Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2101 Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_USART_AddressMaskGet ( USART_MODULE_ID index ) PLIB_USART_AddressMaskSet Function Sets the address mask for the Address Detect mode. File plib_usart.h C void PLIB_USART_AddressMaskSet(USART_MODULE_ID index, uint8_t mask); Returns None. Description This function sets the address mask for the Address Detect mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressMask in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint8_t mask = 0x0F; PLIB_USART_AddressMaskSet (MY_USART_INSTANCE, mask); Parameters Parameters Description index Identifier for the device instance to be configured mask Address match mask bits Function void PLIB_USART_AddressMaskSet ( USART_MODULE_ID index, uint8_t mask ) PLIB_USART_AddressSet Function Sets the address for the Address Detect mode. File plib_usart.h C void PLIB_USART_AddressSet(USART_MODULE_ID index, uint8_t address); Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2102 Returns None. Description This function sets the address for the Address Detect mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddress in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint8_t address = 0x02; PLIB_USART_AddressSet (MY_USART_INSTANCE, address); Parameters Parameters Description index Identifier for the device instance to be configured address Address Function void PLIB_USART_AddressSet ( USART_MODULE_ID index, uint8_t address ) PLIB_USART_ModuleIsBusy Function Returns the USART module's running status. File plib_usart.h C bool PLIB_USART_ModuleIsBusy(USART_MODULE_ID index); Returns • true - USART module is busy • false - USART module is idle Description This function checks if the USART module status is busy. The following functions should not be used when the module status is busy: • PLIB_USART_LineControlModeSelect • PLIB_USART_BaudRateHighSet • PLIB_USART_BaudRateHighEnable • PLIB_USART_BaudRateHighDisable • PLIB_USART_ReceiverIdleStateLowEnable • PLIB_USART_ReceiverIdleStateLowDisable • PLIB_USART_BaudRateAutoDetectEnable • PLIB_USART_LoopbackEnable • PLIB_USART_LoopbackDisable • PLIB_USART_WakeOnStartEnable • PLIB_USART_WakeOnStartDisable • PLIB_USART_OperationModeSelect • PLIB_USART_HandshakeModeSelect Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2103 • PLIB_USART_IrDAEnable • PLIB_USART_IrDADisable • PLIB_USART_StopInIdleEnable • PLIB_USART_StopInIdleDisable • PLIB_USART_RunInOverflowEnable • PLIB_USART_RunInOverflowDisable • PLIB_USART_BRGClockSourceSelect • PLIB_USART_RunInSleepModeEnable • PLIB_USART_RunInSleepModeDisable Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsModuleBusyStatus in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 bool moduleStatus; moduleStatus = PLIB_USART_ModuleIsBusy (MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_USART_ModuleIsBusy ( USART_MODULE_ID index ) PLIB_USART_RunInOverflowDisable Function Disables the Run in overflow condition mode. File plib_usart.h C void PLIB_USART_RunInOverflowDisable(USART_MODULE_ID index); Returns None. Description This function disables the USART module from accepting new data when an overflow error condition is detected. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsRunInOverflow in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_RunInOverflowDisable (MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2104 Function void PLIB_USART_RunInOverflowDisable ( USART_MODULE_ID index ) PLIB_USART_RunInOverflowEnable Function Enables the USART module to continue to operate when an overflow error condition has occurred. File plib_usart.h C void PLIB_USART_RunInOverflowEnable(USART_MODULE_ID index); Returns None. Description This function enables the USART module to continue to operate when an overflow error condition has occurred. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsRunInOverflow in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_RunInOverflowEnable (MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_RunInOverflowEnable ( USART_MODULE_ID index ) PLIB_USART_RunInOverflowIsEnabled Function Gets the status of the Run in Overflow condition. File plib_usart.h C bool PLIB_USART_RunInOverflowIsEnabled(USART_MODULE_ID index); Returns • true - Run in overflow condition is enabled • false - Run in overflow condition is disabled Description This function indicates if the USART module has been enabled to run in an overflow condition. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsRunInOverflow in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2105 Example #define MY_USART_INSTANCE USART_ID_1 bool status; status = PLIB_USART_RunInOverflowIsEnabled (MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_USART_RunInOverflowIsEnabled ( USART_MODULE_ID index ) PLIB_USART_RunInSleepModeDisable Function Turns off the USART module's BRG clock during Sleep mode. File plib_usart.h C void PLIB_USART_RunInSleepModeDisable(USART_MODULE_ID index); Returns None. Description This function turns off the USART module's BRG clock during Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsRunInSleepMode in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_RunInSleepModeDisable (MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_RunInSleepModeDisable ( USART_MODULE_ID index ) PLIB_USART_RunInSleepModeEnable Function Allows the USART module's BRG clock to run when the device enters Sleep mode. File plib_usart.h C void PLIB_USART_RunInSleepModeEnable(USART_MODULE_ID index); Returns None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2106 Description This function enables the USART module's BRG clock to continue operation when the device enters the Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsRunInSleepMode in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_RunInSleepModeEnable (MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_RunInSleepModeEnable ( USART_MODULE_ID index ) PLIB_USART_RunInSleepModeIsEnabled Function Gets the status of Run in Sleep mode. File plib_usart.h C bool PLIB_USART_RunInSleepModeIsEnabled(USART_MODULE_ID index); Returns • true - Run in Sleep mode is enabled • false - Run in Sleep mode is disabled Description This function indicates if the USART module has been enabled to run in Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsRunInSleepMode in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 bool status; status = PLIB_USART_RunInSleepModeIsEnabled (MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function bool PLIB_USART_RunInSleepModeIsEnabled ( USART_MODULE_ID index ) b) Baud Rate Generator Functions Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2107 PLIB_USART_BaudRateAutoDetectEnable Function Enables baud rate measurement on the next character, which requires reception of the Sync character. File plib_usart.h C void PLIB_USART_BaudRateAutoDetectEnable(USART_MODULE_ID index); Returns None. Description This function enables the baud rate measurement on the next character, which requires reception of the Sync character. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateAutoDetect in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_BaudRateAutoDetectEnable(MY_USART_INSTANCE); // Wait until the baud rate is detected. while(!PLIB_USART_BaudRateAutoDetectIsComplete(MY_USART_INSTANCE)); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_BaudRateAutoDetectEnable ( USART_MODULE_ID index ) PLIB_USART_BaudRateAutoDetectIsComplete Function Gets the state of the automatic baud detection. File plib_usart.h C bool PLIB_USART_BaudRateAutoDetectIsComplete(USART_MODULE_ID index); Returns • true - Baud rate detection is not complete • false - Baud rate detection is complete Description This function gets the state of the automatic baud detection and returns a '0' if the baud rate auto detection is complete. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateAutoDetect in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2108 Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_BaudRateAutoDetectEnable(MY_USART_INSTANCE); // Wait until the baud rate is detected. while(!PLIB_USART_BaudRateAutoDetectIsComplete(MY_USART_INSTANCE)); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_BaudRateAutoDetectIsComplete ( USART_MODULE_ID index ) PLIB_USART_BaudRateGet Function Gets the baud rate current in use. File plib_usart.h C uint32_t PLIB_USART_BaudRateGet(USART_MODULE_ID index, int32_t clockFrequency); Returns • BaudRate - Baud rate value Description This function gets the baud rate that is currently in use. The clock frequency needs to be passed to the function. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRate in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint32_t baudRate ; PLIB_USART_BaudRateSet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY, 9600); baudRate = PLIB_USART_BaudRateGet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY); Parameters Parameters Description index Identifier for the device instance to be configured clockFrequency Clock Frequency Function uint32_t PLIB_USART_BaudRateGet ( USART_MODULE_ID index, int32_t clockFrequency ); PLIB_USART_BaudRateHighDisable Function Disables the high baud rate selection. File plib_usart.h Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2109 C void PLIB_USART_BaudRateHighDisable(USART_MODULE_ID index); Returns None. Description This function disables the high baud rate selection. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateHigh in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_BaudRateHighDisable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_BaudRateHighDisable ( USART_MODULE_ID index ) PLIB_USART_BaudRateHighEnable Function Enables high baud rate selection. File plib_usart.h C void PLIB_USART_BaudRateHighEnable(USART_MODULE_ID index); Returns None. Description This function enables high baud rate selection. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateHigh in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_BaudRateHighEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2110 Function void PLIB_USART_BaudRateHighEnable ( USART_MODULE_ID index ) PLIB_USART_BaudRateHighSet Function Sets the baud rate to the desired value. File plib_usart.h C void PLIB_USART_BaudRateHighSet(USART_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate); Returns None. Description This function sets the baud rate to the desired value. Remarks Setting a new baud rate value causes the baud rate timer to reset. This ensures that the baud rate timer does not have to overflow before outputting the new baud rate. If the system clock is changed during an active receive operation, a receiver error or data loss may result. To avoid this issue verify that no receptions are in progress before changing the system clock. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateHigh in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint32_t baudRateValue ; PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY, 9600); baudRateValue = PLIB_USART_BaudRateGet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY); Parameters Parameters Description index Identifier for the device instance to be configured baudRate Baud Rate Value, it is the baud rate value clockFrequency Clock Frequency Function void PLIB_USART_BaudRateHighSet ( USART_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate ); PLIB_USART_BaudRateSet Function Sets the baud rate to the desired value. File plib_usart.h C void PLIB_USART_BaudRateSet(USART_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate); Returns None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2111 Description This function sets the baud rate to the desired value. Remarks Setting a new baud rate value causes the baud rate timer to reset. This ensures that the baud rate timer does not have to overflow before outputting the new baud rate. If the system clock is changed during an active receive operation, a receiver error or data loss may result. To avoid this issue verify that no receptions are in progress before changing the system clock. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRate in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint32_t baudRateValue ; PLIB_USART_BaudRateSet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY, 9600); baudRateValue = PLIB_USART_BaudRateGet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY); Parameters Parameters Description index Identifier for the device instance to be configured baudRate Baud Rate Value clockFrequency Clock Frequency Function void PLIB_USART_BaudRateSet ( USART_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate ); PLIB_USART_BaudSetAndEnable Function Sets the baud rate to the desired value and enables the USART receiver, transmitter and the USART module. File plib_usart.h C void PLIB_USART_BaudSetAndEnable(USART_MODULE_ID index, uint32_t systemClock, uint32_t baud); Returns None. Description This function sets the baud rate to the desired value and enables the USART receiver, USART transmitter and USART module. Remarks Setting a new baud rate value causes the baud rate timer to reset. This ensures that the baud rate timer does not have to overflow before outputting the new baud rate. If the system clock is changed during an active receive operation, a receiver error or data loss may result. To avoid this issue verify that no receptions are in progress before changing the system clock. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Availability of this function can also be determined if all of the following functions return true: • PLIB_USART_ExistsBaudRate • PLIB_USART_ExistsTransmitterEnable • PLIB_USART_ExistsReceiverEnable • PLIB_USART_ExistsEnable Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2112 Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint32_t baudRateValue ; PLIB_USART_BaudSetAndEnable(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY, 9600); Parameters Parameters Description index Identifier for the device instance to be configured baudRate Baud Rate Value clockFrequency Clock Frequency Function void PLIB_USART_BaudSetAndEnable ( USART_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate ); PLIB_USART_BRGClockSourceGet Function Gets the BRG clock source of the USART module. File plib_usart.h C USART_BRG_CLOCK_SOURCE PLIB_USART_BRGClockSourceGet(USART_MODULE_ID index); Returns One of the possible values of USART_BRG_CLOCK_SOURCE Description This function returns the BRG Clock source of the USART. Refer to USART_BRG_CLOCK_SOURCE for the possible clock sources. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBRGClockSourceSelect in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 USART_BRG_CLOCK_SOURCE brgClockSource; brgClockSource = PLIB_USART_BRGClockSourceGet (MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance Function USART_BRG_CLOCK_SOURCE PLIB_USART_BRGClockSourceGet ( USART_MODULE_ID index ) PLIB_USART_BRGClockSourceSelect Function Configures the BRG clock source of the USART module. File plib_usart.h Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2113 C void PLIB_USART_BRGClockSourceSelect(USART_MODULE_ID index, USART_BRG_CLOCK_SOURCE brgClockSource); Returns None. Description This function configures the BRG Clock source of the USART. Refer to USART_BRG_CLOCK_SOURCE for the possible clock sources. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBRGClockSourceSelect in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_BRGClockSourceSelect (MY_USART_INSTANCE, USART_BRG_CLOCK_SOURCE_FRC_IN_SLEEP); Parameters Parameters Description index Identifier for the device instance to be configured brgClockSource One of the possible values from USART_BRG_CLOCK_SOURCE Function void PLIB_USART_BRGClockSourceSelect ( USART_MODULE_ID index, USART_BRG_CLOCK_SOURCE brgClockSource ) c) Transmitter Functions PLIB_USART_Transmitter9BitsSend Function Data to be transmitted in the byte mode with the 9th bit. File plib_usart.h C void PLIB_USART_Transmitter9BitsSend(USART_MODULE_ID index, int8_t data, bool Bit9th); Returns None. Description The data is transmitted in the byte mode for the specified USART module, with 9th bit. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitter9BitsSend in your application to determine whether this feature is available. Preconditions The USART module should be configured to use the 9 data bits. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2114 Example #define MY_USART_INSTANCE USART_ID_1 uint8_t data = 'a'; if(!PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)) { PLIB_USART_Transmitter9BitsSend(MY_USART_INSTANCE, data, false); } Parameters Parameters Description index Identifier for the device instance to be configured data Data to be transmitted. 9thBit 9th bit of the data to be transmitted. Function void PLIB_USART_Transmitter9BitsSend ( USART_MODULE_ID index, int8_t data, bool 9thBit ) PLIB_USART_TransmitterBreakSend Function Transmits the break character. File plib_usart.h C void PLIB_USART_TransmitterBreakSend(USART_MODULE_ID index); Returns None. Description This function transmits the break character. Remarks After the break has been transmitted, the application can start transmitting next bytes. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterBreak in your application to determine whether this feature is available. Preconditions The application should wait for the transmitter to be idle, before calling this function. Example #define MY_USART_INSTANCE USART_ID_1 // Wait for the Transmit buffer to be empty. while(PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)); // Transmit the break character. PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); // wait for the break transmission to complete while(!PLIB_USART_TransmitterBreakSendIsComplete(MY_USART_INSTANCE)); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_TransmitterBreakSend ( USART_MODULE_ID index ) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2115 PLIB_USART_TransmitterBreakSendIsComplete Function Returns the status of the break transmission File plib_usart.h C bool PLIB_USART_TransmitterBreakSendIsComplete(USART_MODULE_ID index); Returns • true - Transmit break on the next transmission • false - Break transmission completed or not started Description The function returns the status of the break transmission. Remarks After the break has been transmitted, the application can start transmitting next bytes. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterBreak in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 // Wait for the Transmit buffer to be empty. while(PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)); // Transmit the break character. PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); // wait for the break transmission to complete while(!PLIB_USART_TransmitterBreakSendIsComplete(MY_USART_INSTANCE)); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_TransmitterBreakSendIsComplete ( USART_MODULE_ID index ) PLIB_USART_TransmitterBufferIsFull Function Gets the transmit buffer full status. File plib_usart.h C bool PLIB_USART_TransmitterBufferIsFull(USART_MODULE_ID index); Returns • true - The transmit buffer is full • false - The transmit buffer is not full, at least one more character can be written Description This function gets the transmit status of the specified USART module. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2116 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterBufferFullStatus in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 // Wait for the Transmit buffer to be empty. while(PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)); // Transmit the break character. PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_TransmitterBufferIsFull ( USART_MODULE_ID index ) PLIB_USART_TransmitterByteSend Function Data to be transmitted in the Byte mode. File plib_usart.h C void PLIB_USART_TransmitterByteSend(USART_MODULE_ID index, int8_t data); Returns None. Description The data is transmitted in the Byte mode for the specified USART module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitter in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint8_t data = 'a'; if(!PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)) { PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, data); } Parameters Parameters Description index Identifier for the device instance to be configured data Data to be transmitted. Function void PLIB_USART_TransmitterByteSend ( USART_MODULE_ID index, int8_t data ) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2117 PLIB_USART_TransmitterDisable Function Disables the specific USART module transmitter. File plib_usart.h C void PLIB_USART_TransmitterDisable(USART_MODULE_ID index); Returns None. Description This function disables the specific USART module transmitter. Remarks Disabling the transmitter during a transmission will cause the transmission to be aborted. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterDisable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_TransmitterDisable ( USART_MODULE_ID index ) PLIB_USART_TransmitterEnable Function Enables the specific USART module transmitter. File plib_usart.h C void PLIB_USART_TransmitterEnable(USART_MODULE_ID index); Returns None. Description This function enables the specific USART module transmitter. Remarks The transmitter should not be enabled until the USART is enabled. The transmissions will not be enabled otherwise. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterEnable in your application to determine whether this feature is available. Preconditions The USART module should be enabled using the function PLIB_USART_Enable before this function is called. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2118 Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_TransmitterEnable ( USART_MODULE_ID index ) PLIB_USART_TransmitterIdleIsLowDisable Function Disables the Transmit Idle Low state. File plib_usart.h C void PLIB_USART_TransmitterIdleIsLowDisable(USART_MODULE_ID index); Returns None. Description This function disables the Transmit Idle Low state. In USART Synchronous mode, this function configures that the TX polarity the idle state is high. When IrDA is enabled, this function sets the IrDA encoded Transmit Idle state to a '0'. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterIdleIsLow in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterIdleIsLowDisable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_TransmitterIdleIsLowDisable ( USART_MODULE_ID index ) PLIB_USART_TransmitterIdleIsLowEnable Function Enables the Transmit Idle Low state. File plib_usart.h C void PLIB_USART_TransmitterIdleIsLowEnable(USART_MODULE_ID index); Returns None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2119 Description This function enables the Transmit Idle Low state. In the USART Synchronous mode, this function configures that the TX polarity, the idle state is low. When IrDA is enabled, this function sets that IrDA encoded Transmit Idle state to a '1'. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterIdleIsLow in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterIdleIsLowEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_TransmitterIdleIsLowEnable ( USART_MODULE_ID index ) PLIB_USART_TransmitterInterruptModeSelect Function Sets the USART transmitter interrupt mode. File plib_usart.h C void PLIB_USART_TransmitterInterruptModeSelect(USART_MODULE_ID index, USART_TRANSMIT_INTR_MODE fifolevel); Returns None. Description This function sets the condition in which the USART module should generate an interrupt. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterInterruptMode in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterInterruptModeSelect(MY_USART_INSTANCE, USART_TRANSMIT_FIFO_EMPTY ); Parameters Parameters Description index Identifier for the device instance to be configured interruptMode Interrupt mode; for possible configurations, refer to USART_TRANSMIT_INTR_MODE Function void PLIB_USART_TransmitterInterruptModeSelect( USART_MODULE_ID index, USART_TRANSMIT_INTR_MODE interruptMode ) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2120 PLIB_USART_TransmitterIsEmpty Function Gets the transmit shift register empty status. File plib_usart.h C bool PLIB_USART_TransmitterIsEmpty(USART_MODULE_ID index); Returns • true - The transmit shift register is empty • false - The transmit shift register is not empty Description This function gets the transmit shift register empty status. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterEmptyStatus in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 // Wait for the Transmit buffer to be empty. while(!PLIB_USART_TransmitterIsEmpty(MY_USART_INSTANCE)); // Transmit the break character. PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_TransmitterIsEmpty ( USART_MODULE_ID index ) PLIB_USART_TransmitterAddressGet Function Returns the address of the USART TX register File plib_usart.h C void* PLIB_USART_TransmitterAddressGet(USART_MODULE_ID index); Returns Address of the USART TX register Description This function returns the address of the USART TX register. Remarks None. Preconditions None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2121 Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_TransmitterAddressGet( USART_MODULE_ID index ) d) Receiver Functions PLIB_USART_ReceiverAddressAutoDetectDisable Function Disables the automatic Address Detect mode. File plib_usart.h C void PLIB_USART_ReceiverAddressAutoDetectDisable(USART_MODULE_ID index); Returns None. Description This function disables the automatic Address Detect mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressAutoDetect in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverAddressAutoDetectDisable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_ReceiverAddressAutoDetectDisable ( USART_MODULE_ID index ) PLIB_USART_ReceiverAddressAutoDetectEnable Function Setup the automatic Address Detect mode. File plib_usart.h C void PLIB_USART_ReceiverAddressAutoDetectEnable(USART_MODULE_ID index, int8_t Mask); Returns None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2122 Description This function configures the automatic Address Detect mode. Uses the mask as the address character for automatic address detection. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressAutoDetect in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverAddressAutoDetectEnable(MY_USART_INSTANCE, MY_DEVICE_ADDRESS); Parameters Parameters Description index Identifier for the device instance to be configured Mask Address character to be used, when enabled Function void PLIB_USART_ReceiverAddressAutoDetectEnable( USART_MODULE_ID index, int8_t Mask) PLIB_USART_ReceiverAddressDetectDisable Function Enables the Address Detect mode. File plib_usart.h C void PLIB_USART_ReceiverAddressDetectDisable(USART_MODULE_ID index); Returns None. Description This function disables the Address Detect mode. If it is enabled, and the device is addressed, disable the Address Detect mode to continue receiving bytes. Remarks All bytes are received, and the 9th bit can be used as the parity bit. By default, the address detect is disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressDetect in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverAddressDetectDisable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_ReceiverAddressDetectDisable ( USART_MODULE_ID index ) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2123 PLIB_USART_ReceiverAddressDetectEnable Function Enables the Address Detect mode. File plib_usart.h C void PLIB_USART_ReceiverAddressDetectEnable(USART_MODULE_ID index); Returns None. Description This function enables the Address Detect mode. If it is enabled, and the device is addressed, disable the Address Detect mode to continue receiving bytes. Remarks If 9 data bits are not selected, this bit has no effect. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressDetect in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverAddressDetectEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_ReceiverAddressDetectEnable ( USART_MODULE_ID index ) PLIB_USART_ReceiverAddressIsReceived Function Checks and return if the data received is an address. File plib_usart.h C bool PLIB_USART_ReceiverAddressIsReceived(USART_MODULE_ID index); Returns • true - if the data received has the 9th bit set • false - if the address received has the 9th bit cleared Description Checks and return if the data received is an address. The address has the 9th bit set. If data received has the 9th bit set, the function returns true; otherwise, the function returns false. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressDetect in your application to determine whether this feature is available. Preconditions The USART module should be configured to use the 9 data bits. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2124 Example #define MY_USART_INSTANCE USART_ID_1 int8_t address; if(PLIB_USART_ReceiverAddressIsReceived(MY_USART_INSTANCE)) { address = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_ReceiverAddressIsReceived ( USART_MODULE_ID index ) PLIB_USART_ReceiverByteReceive Function Data to be received in the Byte mode. File plib_usart.h C int8_t PLIB_USART_ReceiverByteReceive(USART_MODULE_ID index); Returns • data - Data to be received Description The data to be received in Byte mode from the specified USART module. Call the functions PLIB_USART_ReceiverFramingErrorHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred and PLIB_USART_ReceiverOverrunHasOccurred to get any error that occurred. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiver in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 bool isError; uint8_t mydata; if(PLIB_USART_ReceiverDataIsAvailable(MY_USART_INSTANCE)) { mydata = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); } isError = PLIB_USART_ReceiverFramingErrorHasOccurred(MY_USART_INSTANCE) | PLIB_USART_ReceiverParityErrorHasOccurred(MY_USART_INSTANCE) | PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE); if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2125 Parameters Parameters Description index Identifier for the device instance to be configured Function int8_t PLIB_USART_ReceiverByteReceive ( USART_MODULE_ID index ) PLIB_USART_ReceiverDataIsAvailable Function Identifies if the receive data is available for the specified USART module. File plib_usart.h C bool PLIB_USART_ReceiverDataIsAvailable(USART_MODULE_ID index); Returns • true - The data is available • false - The data is not available Description This function identifies if the receive data is available for the specified USART module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverDataAvailableStatus in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 int8_t mydata; if(PLIB_USART_ReceiverDataIsAvailable(MY_USART_INSTANCE)) { mydata = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_ReceiverDataIsAvailable ( USART_MODULE_ID index ) PLIB_USART_ReceiverDisable Function Disables the USART receiver. File plib_usart.h C void PLIB_USART_ReceiverDisable(USART_MODULE_ID index); Returns None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2126 Description This function disables the USART receiver. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverDisable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_ReceiverDisable ( USART_MODULE_ID index ) PLIB_USART_ReceiverEnable Function Enables the USART receiver. File plib_usart.h C void PLIB_USART_ReceiverEnable(USART_MODULE_ID index); Returns None. Description This function enables the USART receiver. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_ReceiverEnable ( USART_MODULE_ID index ) PLIB_USART_ReceiverFramingErrorHasOccurred Function Gets the framing error status. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2127 File plib_usart.h C bool PLIB_USART_ReceiverFramingErrorHasOccurred(USART_MODULE_ID index); Returns • true - The framing error was detected on the current character • false - The framing error was not detected on the current character Description This function gets the framing error status. Remarks Reading the error clears the error. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverFramingErrorStatus in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 status = PLIB_USART_ReceiverFramingErrorHasOccurred(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_ReceiverFramingErrorHasOccurred ( USART_MODULE_ID index ) PLIB_USART_ReceiverIdleStateLowDisable Function Disables receive polarity inversion. File plib_usart.h C void PLIB_USART_ReceiverIdleStateLowDisable(USART_MODULE_ID index); Returns None. Description This function disables receive polarity inversion. In the USART Synchronous mode, this function configures that the data is not inverted. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverIdleStateLowEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverIdleStateLowDisable(MY_USART_INSTANCE); Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2128 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_ReceiverIdleStateLowDisable ( USART_MODULE_ID index ); PLIB_USART_ReceiverIdleStateLowEnable Function Enables receive polarity inversion. File plib_usart.h C void PLIB_USART_ReceiverIdleStateLowEnable(USART_MODULE_ID index); Returns None. Description This function enables receive polarity inversion. In the USART Synchronous mode, this function configures that the data is inverted. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverIdleStateLowEnable in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverIdleStateLowEnable(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_ReceiverIdleStateLowEnable ( USART_MODULE_ID index ) PLIB_USART_ReceiverInterruptModeSelect Function Sets the USART receiver FIFO level. File plib_usart.h C void PLIB_USART_ReceiverInterruptModeSelect(USART_MODULE_ID index, USART_RECEIVE_INTR_MODE interruptMode); Returns None. Description This function sets the USART receiver FIFO level. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverInterruptMode in your application to determine whether this feature is available. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2129 Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverInterruptModeSelect(MY_USART_INSTANCE, USART_RECEIVE_FIFO_ONE_CHAR ); Parameters Parameters Description index Identifier for the device instance to be configured fifolevel For possible configurations, refer to USART_RECEIVE_INTR_MODE Function void PLIB_USART_ReceiverInterruptModeSelect( USART_MODULE_ID index, USART_RECEIVE_INTR_MODE interruptMode ) PLIB_USART_ReceiverIsIdle Function Identifies if the receiver is idle. File plib_usart.h C bool PLIB_USART_ReceiverIsIdle(USART_MODULE_ID index); Returns • true - The receive buffer is idle • false - The receive buffer is not idle Description This function identifies if the receiver is idle. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverIdleStatus in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 int8_t mydata; if(PLIB_USART_ReceiverIsIdle(MY_USART_INSTANCE)) { mydata = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_ReceiverIsIdle ( USART_MODULE_ID index ) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2130 PLIB_USART_ReceiverOverrunErrorClear Function Clears a USART vverrun error. File plib_usart.h C void PLIB_USART_ReceiverOverrunErrorClear(USART_MODULE_ID index); Returns None. Description This function clears an overrun error. Clearing the error, resets the receive buffer. Remarks WARNING: Calling this API will clear all of the previously received data. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverOverrunStatus in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USART_ReceiverOverrunErrorClear ( USART_MODULE_ID index ) PLIB_USART_ReceiverOverrunHasOccurred Function Identifies if there was a receiver overrun error. File plib_usart.h C bool PLIB_USART_ReceiverOverrunHasOccurred(USART_MODULE_ID index); Returns • true - The receive buffer has overflowed • false - The receive buffer has not overflowed Description This function identifies if there was a receiver overrun error. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverOverrunStatus in your application to determine whether this feature is available. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2131 Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_ReceiverOverrunHasOccurred ( USART_MODULE_ID index ) PLIB_USART_ReceiverParityErrorHasOccurred Function Gets the parity error status. File plib_usart.h C bool PLIB_USART_ReceiverParityErrorHasOccurred(USART_MODULE_ID index); Returns • true - The parity error was detected on the current character • false - The parity error was not detected on the current character Description This function gets the parity error status. Remarks Reading the error clears the error. A Parity error is irrelevant in case of 9-bit mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverParityErrorStatus in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 status = PLIB_USART_ReceiverParityErrorHasOccurred(MY_USART_INSTANCE); Parameters Parameters Description index Identifier for the device instance to be configured Function bool PLIB_USART_ReceiverParityErrorHasOccurred ( USART_MODULE_ID index ) PLIB_USART_ReceiverAddressGet Function Returns the address of the USART RX register File plib_usart.h Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2132 C void* PLIB_USART_ReceiverAddressGet(USART_MODULE_ID index); Returns Address of the USART RX register Description This function returns the address of the USART RX register. Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ReceiverAddressGet( USART_MODULE_ID index ) PLIB_USART_Receiver9BitsReceive Function Data to be received in the byte mode with the 9th bit. File plib_usart.h C int16_t PLIB_USART_Receiver9BitsReceive(USART_MODULE_ID index); Returns • data - Data to be received Description The data to be received in Byte mode from the specified USART module. with the 9th bit. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiver9Bits in your application to determine whether this feature is available. Preconditions None. Example #define MY_USART_INSTANCE USART_ID_1 uint16_t mydata; if(PLIB_USART_ReceiverDataIsAvailable(MY_USART_INSTANCE)) { mydata = PLIB_USART_Receiver9BitsReceive (MY_USART_INSTANCE); } Parameters Parameters Description index Identifier for the device instance to be configured Function int16_t PLIB_USART_Receiver9BitsReceive ( USART_MODULE_ID index ) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2133 e) Feature Existence Functions PLIB_USART_ExistsBaudRate Function Identifies whether the BaudRate feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsBaudRate(USART_MODULE_ID index); Returns • true - The BaudRate feature is supported on the device • false - The BaudRate feature is not supported on the device Description This function identifies whether the BaudRate feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_BaudRateSet • PLIB_USART_BaudRateGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsBaudRate( USART_MODULE_ID index ) PLIB_USART_ExistsBaudRateAutoDetect Function Identifies whether the BaudRateAutoDetect feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsBaudRateAutoDetect(USART_MODULE_ID index); Returns • true - The BaudRateAutoDetect feature is supported on the device • false - The BaudRateAutoDetect feature is not supported on the device Description This function identifies whether the BaudRateAutoDetect feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_BaudRateAutoDetectEnable • PLIB_USART_BaudRateAutoDetectIsComplete Remarks None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2134 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsBaudRateAutoDetect( USART_MODULE_ID index ) PLIB_USART_ExistsBaudRateHigh Function Identifies whether the BaudRateHigh feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsBaudRateHigh(USART_MODULE_ID index); Returns • true - The BaudRateHigh feature is supported on the device • false - The BaudRateHigh feature is not supported on the device Description This function identifies whether the BaudRateHigh feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_BaudRateHighSet • PLIB_USART_BaudRateHighDisable • PLIB_USART_BaudRateHighEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsBaudRateHigh( USART_MODULE_ID index ) PLIB_USART_ExistsEnable Function Identifies whether the EnableControl feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsEnable(USART_MODULE_ID index); Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the USART module. When this function returns true, these functions are Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2135 supported on the device: • PLIB_USART_Disable • PLIB_USART_Enable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsEnable( USART_MODULE_ID index ) PLIB_USART_ExistsHandshakeMode Function Identifies whether the HandShakeMode feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsHandshakeMode(USART_MODULE_ID index); Returns • true - The HandShakeMode feature is supported on the device • false - The HandShakeMode feature is not supported on the device Description This function identifies whether the HandShakeMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_HandshakeModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsHandshakeMode( USART_MODULE_ID index ) PLIB_USART_ExistsIrDA Function Identifies whether the IrDAControl feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsIrDA(USART_MODULE_ID index); Returns • true - The IrDAControl feature is supported on the device Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2136 • false - The IrDAControl feature is not supported on the device Description This function identifies whether the IrDAControl feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_IrDADisable • PLIB_USART_IrDAEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsIrDA( USART_MODULE_ID index ) PLIB_USART_ExistsLineControlMode Function Identifies whether the LineControlMode feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsLineControlMode(USART_MODULE_ID index); Returns • true - The LineControlMode feature is supported on the device • false - The LineControlMode feature is not supported on the device Description This function identifies whether the LineControlMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_LineControlModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsLineControlMode( USART_MODULE_ID index ) PLIB_USART_ExistsLoopback Function Identifies whether the Loopback feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsLoopback(USART_MODULE_ID index); Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2137 Returns • true - The Loopback feature is supported on the device • false - The Loopback feature is not supported on the device Description This function identifies whether the Loopback feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_LoopbackEnable • PLIB_USART_LoopbackDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsLoopback( USART_MODULE_ID index ) PLIB_USART_ExistsOperationMode Function Identifies whether the OperationMode feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsOperationMode(USART_MODULE_ID index); Returns • true - The OperationMode feature is supported on the device • false - The OperationMode feature is not supported on the device Description This function identifies whether the OperationMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_OperationModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsOperationMode( USART_MODULE_ID index ) PLIB_USART_ExistsReceiver Function Identifies whether the Receiver feature exists on the USART module. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2138 File plib_usart.h C bool PLIB_USART_ExistsReceiver(USART_MODULE_ID index); Returns • true - The Receiver feature is supported on the device • false - The Receiver feature is not supported on the device Description This function identifies whether the Receiver feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverByteReceive • PLIB_USART_ReceiverAddressGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiver( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverAddressAutoDetect Function Identifies whether the ReceiverAddressAutoDetect feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverAddressAutoDetect(USART_MODULE_ID index); Returns • true - The ReceiverAddressAutoDetect feature is supported on the device • false - The ReceiverAddressAutoDetect feature is not supported on the device Description This function identifies whether the ReceiverAddressAutoDetect feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverAddressAutoDetectEnable • PLIB_USART_ReceiverAddressAutoDetectDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverAddressAutoDetect( USART_MODULE_ID index ) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2139 PLIB_USART_ExistsReceiverAddressDetect Function Identifies whether the ReceiverAddressDetect feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverAddressDetect(USART_MODULE_ID index); Returns • true - The ReceiverAddressDetect feature is supported on the device • false - The ReceiverAddressDetect feature is not supported on the device Description This function identifies whether the ReceiverAddressDetect feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverAddressDetectEnable • PLIB_USART_ReceiverAddressDetectDisable • PLIB_USART_ReceiverAddressIsReceived Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverAddressDetect( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverDataAvailableStatus Function Identifies whether the ReceiverDataAvailable feature exists on the USART module File plib_usart.h C bool PLIB_USART_ExistsReceiverDataAvailableStatus(USART_MODULE_ID index); Returns • true - The ReceiverDataAvailable feature is supported on the device • false - The ReceiverDataAvailable feature is not supported on the device Description This function identifies whether the ReceiverDataAvailable feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverDataIsAvailable Remarks None. Preconditions None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2140 Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverDataAvailableStatus( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverEnable Function Identifies whether the ReceiverEnableControl feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverEnable(USART_MODULE_ID index); Returns • true - The ReceiverEnableControl feature is supported on the device • false - The ReceiverEnableControl feature is not supported on the device Description This function identifies whether the ReceiverEnableControl feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverEnable • PLIB_USART_ReceiverDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverEnable( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverFramingErrorStatus Function Identifies whether the ReceiverFramingError feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverFramingErrorStatus(USART_MODULE_ID index); Returns • true - The ReceiverFramingError feature is supported on the device • false - The ReceiverFramingError feature is not supported on the device Description This function identifies whether the ReceiverFramingError feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverFramingErrorHasOccurred Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2141 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverFramingErrorStatus( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverIdleStateLowEnable Function Identifies whether the ReceiverPolarityInvert feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverIdleStateLowEnable(USART_MODULE_ID index); Returns • true - The ReceiverPolarityInvert feature is supported on the device • false - The ReceiverPolarityInvert feature is not supported on the device Description This function identifies whether the ReceiverPolarityInvert feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverIdleStateLowEnable • PLIB_USART_ReceiverIdleStateLowDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverIdleStateLowEnable( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverIdleStatus Function Identifies whether the ReceiverIdle feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverIdleStatus(USART_MODULE_ID index); Returns • true - The ReceiverIdle feature is supported on the device • false - The ReceiverIdle feature is not supported on the device Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2142 Description This function identifies whether the ReceiverIdle feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverIsIdle Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverIdleStatus( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverInterruptMode Function Identifies whether the ReceiverInterruptMode feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverInterruptMode(USART_MODULE_ID index); Returns • true - The ReceiverInterruptMode feature is supported on the device • false - The ReceiverInterruptMode feature is not supported on the device Description This function identifies whether the ReceiverInterruptMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverInterruptModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverInterruptMode( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverOverrunStatus Function Identifies whether the ReceiverOverrunError feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverOverrunStatus(USART_MODULE_ID index); Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2143 Returns • true - The ReceiverOverrunError feature is supported on the device • false - The ReceiverOverrunError feature is not supported on the device Description This function identifies whether the ReceiverOverrunError feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverOverrunErrorClear • PLIB_USART_ReceiverOverrunHasOccurred Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverOverrunStatus( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverParityErrorStatus Function Identifies whether the ReceiverParityError feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverParityErrorStatus(USART_MODULE_ID index); Returns • true - The ReceiverParityError feature is supported on the device • false - The ReceiverParityError feature is not supported on the device Description This function identifies whether the ReceiverParityError feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverParityErrorHasOccurred Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverParityErrorStatus( USART_MODULE_ID index ) PLIB_USART_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the USART module. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2144 File plib_usart.h C bool PLIB_USART_ExistsStopInIdle(USART_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Description This function identifies whether the StopInIdle feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_StopInIdleEnable • PLIB_USART_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsStopInIdle( USART_MODULE_ID index ) PLIB_USART_ExistsTransmitter Function Identifies whether the Transmitter feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsTransmitter(USART_MODULE_ID index); Returns • true - The Transmitter feature is supported on the device • false - The Transmitter feature is not supported on the device Description This function identifies whether the Transmitter feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_TransmitterByteSend • PLIB_USART_TransmitterAddressGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsTransmitter( USART_MODULE_ID index ) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2145 PLIB_USART_ExistsTransmitter9BitsSend Function Identifies whether the Transmitter9Bits feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsTransmitter9BitsSend(USART_MODULE_ID index); Returns • true - The Transmitter9Bits feature is supported on the device • false - The Transmitter9Bits feature is not supported on the device Description This function identifies whether the Transmitter9Bits feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_Transmitter9BitsSend Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsTransmitter9BitsSend( USART_MODULE_ID index ) PLIB_USART_ExistsTransmitterBreak Function Identifies whether the TransmitterBreak feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsTransmitterBreak(USART_MODULE_ID index); Returns • true - The TransmitterBreak feature is supported on the device • false - The TransmitterBreak feature is not supported on the device Description This function identifies whether the TransmitterBreak feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_TransmitterBreakSend • PLIB_USART_TransmitterBreakSendIsComplete Remarks None. Preconditions None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2146 Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsTransmitterBreak( USART_MODULE_ID index ) PLIB_USART_ExistsTransmitterBufferFullStatus Function Identifies whether the TransmitterBufferFull feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsTransmitterBufferFullStatus(USART_MODULE_ID index); Returns • true - The TransmitterBufferFull feature is supported on the device • false - The TransmitterBufferFull feature is not supported on the device Description This function identifies whether the TransmitterBufferFull feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_TransmitterBufferIsFull Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsTransmitterBufferFullStatus( USART_MODULE_ID index ) PLIB_USART_ExistsTransmitterEmptyStatus Function Identifies whether the TransmitterEmpty feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsTransmitterEmptyStatus(USART_MODULE_ID index); Returns • true - The TransmitterEmpty feature is supported on the device • false - The TransmitterEmpty feature is not supported on the device Description This function identifies whether the TransmitterEmpty feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_TransmitterIsEmpty Remarks None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2147 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsTransmitterEmptyStatus( USART_MODULE_ID index ) PLIB_USART_ExistsTransmitterEnable Function Identifies whether the TransmitterEnableControl feature exists on the USART module File plib_usart.h C bool PLIB_USART_ExistsTransmitterEnable(USART_MODULE_ID index); Returns • true - The TransmitterEnableControl feature is supported on the device • false - The TransmitterEnableControl feature is not supported on the device Description This function identifies whether the TransmitterEnableControl feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_TransmitterEnable • PLIB_USART_TransmitterDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsTransmitterEnable( USART_MODULE_ID index ) PLIB_USART_ExistsTransmitterIdleIsLow Function Identifies whether the TransmitterIdleIsLow feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsTransmitterIdleIsLow(USART_MODULE_ID index); Returns • true - The TransmitterIdleIsLow feature is supported on the device • false - The TransmitterIdleIsLow feature is not supported on the device Description This function identifies whether the TransmitterIdleIsLow feature is available on the USART module. When this function returns true, these functions are supported on the device: Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2148 • PLIB_USART_TransmitterIdleIsLowDisable • PLIB_USART_TransmitterIdleIsLowEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsTransmitterIdleIsLow( USART_MODULE_ID index ) PLIB_USART_ExistsTransmitterInterruptMode Function Identifies whether the TransmitterInterruptMode feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsTransmitterInterruptMode(USART_MODULE_ID index); Returns • true - The TransmitterInterruptMode feature is supported on the device • false - The TransmitterInterruptMode feature is not supported on the device Description This function identifies whether the TransmitterInterruptMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_TransmitterInterruptModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsTransmitterInterruptMode( USART_MODULE_ID index ) PLIB_USART_ExistsWakeOnStart Function Identifies whether the WakeOnStart feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsWakeOnStart(USART_MODULE_ID index); Returns • true - The WakeOnStart feature is supported on the device • false - The WakeOnStart feature is not supported on the device Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2149 Description This function identifies whether the WakeOnStart feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_WakeOnStartEnable • PLIB_USART_WakeOnStartDisable • PLIB_USART_WakeOnStartIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsWakeOnStart( USART_MODULE_ID index ) PLIB_USART_ExistsReceiver9Bits Function Identifies whether the 9 Bits Receiver feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiver9Bits(USART_MODULE_ID index); Returns • true - The feature is supported on the device • false - The feature is not supported on the device Description This function identifies whether the 9 Bits Receiver feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_Receiver9BitsReceive Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiver9Bits ( USART_MODULE_ID index ) PLIB_USART_ExistsBRGClockSourceSelect Function Identifies whether the BRG Clock source select feature exists on the USART module. File plib_usart.h Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2150 C bool PLIB_USART_ExistsBRGClockSourceSelect(USART_MODULE_ID index); Returns • true - The BRG clock source select feature is supported on the device • false - The BRG clock source select feature is not supported on the device Description This function identifies whether the BRG Clock source select feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_BRGClockSourceSelect • PLIB_USART_BRGClockSourceGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsBRGClockSourceSelect ( USART_MODULE_ID index ) PLIB_USART_ExistsModuleBusyStatus Function Identifies whether the module running status feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsModuleBusyStatus(USART_MODULE_ID index); Returns • true - The Module running status feature is supported on the device • false - The Module running status feature is not supported on the device Description This function identifies whether the module running status feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ModuleIsBusy Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsModuleBusyStatus ( USART_MODULE_ID index ) Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2151 PLIB_USART_ExistsReceiverAddress Function Identifies whether the Receiver Address feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverAddress(USART_MODULE_ID index); Returns • true - The Receiver address feature is supported on the device • false - The Receiver address feature is not supported on the device Description This function identifies whether the Receiver Address feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_AddressSet • PLIB_USART_AddressGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverAddress ( USART_MODULE_ID index ) PLIB_USART_ExistsReceiverAddressMask Function Identifies whether the Receiver Address Mask feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsReceiverAddressMask(USART_MODULE_ID index); Returns • true - The Receiver address mask feature is supported on the device • false - The Receiver address mask feature is not supported on the device Description This function identifies whether the Receiver Address Mask feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_AddressMaskSet • PLIB_USART_AddressMaskGet Remarks None. Preconditions None. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2152 Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsReceiverAddressMask ( USART_MODULE_ID index ) PLIB_USART_ExistsRunInOverflow Function Identifies whether the Run in overflow condition feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsRunInOverflow(USART_MODULE_ID index); Returns • true - The Run in Overflow condition feature is supported on the device • false - The Run in Overflow condition feature is not supported on the device Description This function identifies whether the Run in Overflow condition feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_RunInOverflowEnable • PLIB_USART_RunInOverflowDisable • PLIB_USART_RunInOverflowIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsRunInOverflow ( USART_MODULE_ID index ) PLIB_USART_ExistsRunInSleepMode Function Identifies whether the Run in Sleep mode feature exists on the USART module. File plib_usart.h C bool PLIB_USART_ExistsRunInSleepMode(USART_MODULE_ID index); Returns • true - The Run in Sleep mode feature is supported on the device • false - The Run in Sleep mode feature is not supported on the device Description This function identifies whether the Run in Sleep mode feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_RunInSleepModeEnable • PLIB_USART_RunInSleepModeDisable Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2153 • PLIB_USART_RunInSleepModeIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USART_ExistsRunInSleepMode ( USART_MODULE_ID index ) f) Data Types and Constants USART_HANDSHAKE_MODE Enumeration Lists the USART handshake modes. File plib_usart_help.h C typedef enum { USART_HANDSHAKE_MODE_FLOW_CONTROL, USART_HANDSHAKE_MODE_SIMPLEX } USART_HANDSHAKE_MODE; Members Members Description USART_HANDSHAKE_MODE_FLOW_CONTROL Enables flow control USART_HANDSHAKE_MODE_SIMPLEX Enables simplex mode communication, no flow control Description USART Handshake modes This enumeration lists the USART handshake modes. Remarks None. USART_LINECONTROL_MODE Enumeration Data type defining the different configurations by which the USART data flow can be configured. File plib_usart_help.h C typedef enum { USART_8N1, USART_8E1, USART_8O1, USART_8N2, USART_8E2, USART_8O2, USART_9N1, USART_9N2 } USART_LINECONTROL_MODE; Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2154 Members Members Description USART_8N1 8 Data Bits, No Parity,one Stop Bit USART_8E1 8 Data Bits, Even Parity, 1 stop bit USART_8O1 8 Data Bits, odd Parity, 1 stop bit USART_8N2 8 Data Bits, No Parity,two Stop Bits USART_8E2 8 Data Bits, Even Parity, 2 stop bits USART_8O2 8 Data Bits, odd Parity, 2 stop bits USART_9N1 9 Data Bits, No Parity, 1 stop bit USART_9N2 9 Data Bits, No Parity, 2 stop bits Description Data Flow configuration This data type defines the different configurations by which the USART can be configured for the data flow. Remarks None. USART_MODULE_ID Enumeration File plib_usart_help.h C typedef enum { USART_ID_1, USART_ID_2, USART_ID_3, USART_ID_4, USART_ID_5, USART_ID_6, USART_NUMBER_OF_MODULES } USART_MODULE_ID; Members Members Description USART_ID_1 USART 1 USART_ID_2 USART 2 USART_ID_3 USART 3 USART_ID_4 USART 4 USART_ID_5 USART 5 USART_ID_6 USART 6 USART_NUMBER_OF_MODULES Total number of USART modules available Description Enumeration: USART_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. _USART_MODULE_ID Macro File plib_usart_help.h C #define _USART_MODULE_ID Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2155 USART_OPERATION_MODE Enumeration Data type defining the different configurations by which the USART can be enabled. File plib_usart_help.h C typedef enum { USART_ENABLE_TX_RX_BCLK_USED, USART_ENABLE_TX_RX_CTS_RTS_USED, USART_ENABLE_TX_RX_RTS_USED, USART_ENABLE_TX_RX_USED } USART_OPERATION_MODE; Members Members Description USART_ENABLE_TX_RX_BCLK_USED TX, RX and BCLK pins are used by USART module USART_ENABLE_TX_RX_CTS_RTS_USED TX, RX, CTS and RTS pins are used by USART module USART_ENABLE_TX_RX_RTS_USED TX, RX and RTS pins are used by USART module USART_ENABLE_TX_RX_USED TX and RX pins are used by USART module Description Enable configuration This data type defines the different configurations by which the USART can be enabled. Remarks The actual definition of this enumeration is device-specific. USART_RECEIVE_INTR_MODE Enumeration Data type defining the different Receive FIFO levels by which the USART receive interrupt modes can be configured. File plib_usart_help.h C typedef enum { USART_RECEIVE_FIFO_HALF_FULL, USART_RECEIVE_FIFO_3B4FULL, USART_RECEIVE_FIFO_ONE_CHAR } USART_RECEIVE_INTR_MODE; Members Members Description USART_RECEIVE_FIFO_HALF_FULL Interrupt when receive buffer is half full USART_RECEIVE_FIFO_3B4FULL Interrupt when receive buffer is 3/4 full USART_RECEIVE_FIFO_ONE_CHAR Interrupt when a character is received Description Receive Interrupt mode configuration This data type defining the different Receive FIFO levels by which the USART receive interrupt modes can be configured. Remarks None. USART_TRANSMIT_INTR_MODE Enumeration Data type defining the different transmit FIFO levels by which the USART transmit interrupt modes can be configured. Peripheral Libraries Help USART Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2156 File plib_usart_help.h C typedef enum { USART_TRANSMIT_FIFO_EMPTY, USART_TRANSMIT_FIFO_IDLE, USART_TRANSMIT_FIFO_NOT_FULL } USART_TRANSMIT_INTR_MODE; Members Members Description USART_TRANSMIT_FIFO_EMPTY Interrupt when the transmit buffer becomes empty USART_TRANSMIT_FIFO_IDLE Interrupt when all characters are transmitted USART_TRANSMIT_FIFO_NOT_FULL Interrupt when at least one location is empty in the transmit buffer Description Transmit Interrupt mode configuration This data type defining the different transmit FIFO levels by which the USART transmit interrupt modes can be configured. Remarks None. Files Files Name Description plib_usart.h USART Peripheral Library interface header. plib_usart_help.h Description This section lists the source and header files used by the library. plib_usart.h USART Peripheral Library interface header. Functions Name Description PLIB_USART_AddressGet Gets the address for the Address Detect mode. PLIB_USART_AddressMaskGet Gets the address mask for the Address Detect mode. PLIB_USART_AddressMaskSet Sets the address mask for the Address Detect mode. PLIB_USART_AddressSet Sets the address for the Address Detect mode. PLIB_USART_BaudRateAutoDetectEnable Enables baud rate measurement on the next character, which requires reception of the Sync character. PLIB_USART_BaudRateAutoDetectIsComplete Gets the state of the automatic baud detection. PLIB_USART_BaudRateGet Gets the baud rate current in use. PLIB_USART_BaudRateHighDisable Disables the high baud rate selection. PLIB_USART_BaudRateHighEnable Enables high baud rate selection. PLIB_USART_BaudRateHighSet Sets the baud rate to the desired value. PLIB_USART_BaudRateSet Sets the baud rate to the desired value. PLIB_USART_BaudSetAndEnable Sets the baud rate to the desired value and enables the USART receiver, transmitter and the USART module. PLIB_USART_BRGClockSourceGet Gets the BRG clock source of the USART module. PLIB_USART_BRGClockSourceSelect Configures the BRG clock source of the USART module. PLIB_USART_Disable Disables the specific USART module PLIB_USART_Enable Enables the specific USART module. Peripheral Libraries Help USART Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2157 PLIB_USART_ErrorsGet Return the status of all errors in the specified USART module. PLIB_USART_ExistsBaudRate Identifies whether the BaudRate feature exists on the USART module. PLIB_USART_ExistsBaudRateAutoDetect Identifies whether the BaudRateAutoDetect feature exists on the USART module. PLIB_USART_ExistsBaudRateHigh Identifies whether the BaudRateHigh feature exists on the USART module. PLIB_USART_ExistsBRGClockSourceSelect Identifies whether the BRG Clock source select feature exists on the USART module. PLIB_USART_ExistsEnable Identifies whether the EnableControl feature exists on the USART module. PLIB_USART_ExistsHandshakeMode Identifies whether the HandShakeMode feature exists on the USART module. PLIB_USART_ExistsIrDA Identifies whether the IrDAControl feature exists on the USART module. PLIB_USART_ExistsLineControlMode Identifies whether the LineControlMode feature exists on the USART module. PLIB_USART_ExistsLoopback Identifies whether the Loopback feature exists on the USART module. PLIB_USART_ExistsModuleBusyStatus Identifies whether the module running status feature exists on the USART module. PLIB_USART_ExistsOperationMode Identifies whether the OperationMode feature exists on the USART module. PLIB_USART_ExistsReceiver Identifies whether the Receiver feature exists on the USART module. PLIB_USART_ExistsReceiver9Bits Identifies whether the 9 Bits Receiver feature exists on the USART module. PLIB_USART_ExistsReceiverAddress Identifies whether the Receiver Address feature exists on the USART module. PLIB_USART_ExistsReceiverAddressAutoDetect Identifies whether the ReceiverAddressAutoDetect feature exists on the USART module. PLIB_USART_ExistsReceiverAddressDetect Identifies whether the ReceiverAddressDetect feature exists on the USART module. PLIB_USART_ExistsReceiverAddressMask Identifies whether the Receiver Address Mask feature exists on the USART module. PLIB_USART_ExistsReceiverDataAvailableStatus Identifies whether the ReceiverDataAvailable feature exists on the USART module PLIB_USART_ExistsReceiverEnable Identifies whether the ReceiverEnableControl feature exists on the USART module. PLIB_USART_ExistsReceiverFramingErrorStatus Identifies whether the ReceiverFramingError feature exists on the USART module. PLIB_USART_ExistsReceiverIdleStateLowEnable Identifies whether the ReceiverPolarityInvert feature exists on the USART module. PLIB_USART_ExistsReceiverIdleStatus Identifies whether the ReceiverIdle feature exists on the USART module. PLIB_USART_ExistsReceiverInterruptMode Identifies whether the ReceiverInterruptMode feature exists on the USART module. PLIB_USART_ExistsReceiverOverrunStatus Identifies whether the ReceiverOverrunError feature exists on the USART module. PLIB_USART_ExistsReceiverParityErrorStatus Identifies whether the ReceiverParityError feature exists on the USART module. PLIB_USART_ExistsRunInOverflow Identifies whether the Run in overflow condition feature exists on the USART module. PLIB_USART_ExistsRunInSleepMode Identifies whether the Run in Sleep mode feature exists on the USART module. PLIB_USART_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the USART module. PLIB_USART_ExistsTransmitter Identifies whether the Transmitter feature exists on the USART module. PLIB_USART_ExistsTransmitter9BitsSend Identifies whether the Transmitter9Bits feature exists on the USART module. PLIB_USART_ExistsTransmitterBreak Identifies whether the TransmitterBreak feature exists on the USART module. PLIB_USART_ExistsTransmitterBufferFullStatus Identifies whether the TransmitterBufferFull feature exists on the USART module. PLIB_USART_ExistsTransmitterEmptyStatus Identifies whether the TransmitterEmpty feature exists on the USART module. PLIB_USART_ExistsTransmitterEnable Identifies whether the TransmitterEnableControl feature exists on the USART module PLIB_USART_ExistsTransmitterIdleIsLow Identifies whether the TransmitterIdleIsLow feature exists on the USART module. PLIB_USART_ExistsTransmitterInterruptMode Identifies whether the TransmitterInterruptMode feature exists on the USART module. PLIB_USART_ExistsWakeOnStart Identifies whether the WakeOnStart feature exists on the USART module. PLIB_USART_HandshakeModeSelect Sets the data flow configuration. PLIB_USART_InitializeModeGeneral Enables or disables general features of the USART module. PLIB_USART_InitializeOperation Configures the Receive and Transmit FIFO interrupt levels and the hardware lines to be used by the module. Peripheral Libraries Help USART Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2158 PLIB_USART_IrDADisable Disables the IrDA encoder and decoder. PLIB_USART_IrDAEnable Enables the IrDA encoder and decoder. PLIB_USART_LineControlModeSelect Sets the data flow configuration. PLIB_USART_LoopbackDisable Disables Loopback mode. PLIB_USART_LoopbackEnable Enables Loopback mode. PLIB_USART_ModuleIsBusy Returns the USART module's running status. PLIB_USART_OperationModeSelect Configures the operation mode of the USART module. PLIB_USART_Receiver9BitsReceive Data to be received in the byte mode with the 9th bit. PLIB_USART_ReceiverAddressAutoDetectDisable Disables the automatic Address Detect mode. PLIB_USART_ReceiverAddressAutoDetectEnable Setup the automatic Address Detect mode. PLIB_USART_ReceiverAddressDetectDisable Enables the Address Detect mode. PLIB_USART_ReceiverAddressDetectEnable Enables the Address Detect mode. PLIB_USART_ReceiverAddressGet Returns the address of the USART RX register PLIB_USART_ReceiverAddressIsReceived Checks and return if the data received is an address. PLIB_USART_ReceiverByteReceive Data to be received in the Byte mode. PLIB_USART_ReceiverDataIsAvailable Identifies if the receive data is available for the specified USART module. PLIB_USART_ReceiverDisable Disables the USART receiver. PLIB_USART_ReceiverEnable Enables the USART receiver. PLIB_USART_ReceiverFramingErrorHasOccurred Gets the framing error status. PLIB_USART_ReceiverIdleStateLowDisable Disables receive polarity inversion. PLIB_USART_ReceiverIdleStateLowEnable Enables receive polarity inversion. PLIB_USART_ReceiverInterruptModeSelect Sets the USART receiver FIFO level. PLIB_USART_ReceiverIsIdle Identifies if the receiver is idle. PLIB_USART_ReceiverOverrunErrorClear Clears a USART vverrun error. PLIB_USART_ReceiverOverrunHasOccurred Identifies if there was a receiver overrun error. PLIB_USART_ReceiverParityErrorHasOccurred Gets the parity error status. PLIB_USART_RunInOverflowDisable Disables the Run in overflow condition mode. PLIB_USART_RunInOverflowEnable Enables the USART module to continue to operate when an overflow error condition has occurred. PLIB_USART_RunInOverflowIsEnabled Gets the status of the Run in Overflow condition. PLIB_USART_RunInSleepModeDisable Turns off the USART module's BRG clock during Sleep mode. PLIB_USART_RunInSleepModeEnable Allows the USART module's BRG clock to run when the device enters Sleep mode. PLIB_USART_RunInSleepModeIsEnabled Gets the status of Run in Sleep mode. PLIB_USART_StopInIdleDisable Disables the Stop in Idle mode (the USART module continues operation when the device is in Idle mode). PLIB_USART_StopInIdleEnable Discontinues operation when the device enters Idle mode. PLIB_USART_Transmitter9BitsSend Data to be transmitted in the byte mode with the 9th bit. PLIB_USART_TransmitterAddressGet Returns the address of the USART TX register PLIB_USART_TransmitterBreakSend Transmits the break character. PLIB_USART_TransmitterBreakSendIsComplete Returns the status of the break transmission PLIB_USART_TransmitterBufferIsFull Gets the transmit buffer full status. PLIB_USART_TransmitterByteSend Data to be transmitted in the Byte mode. PLIB_USART_TransmitterDisable Disables the specific USART module transmitter. PLIB_USART_TransmitterEnable Enables the specific USART module transmitter. PLIB_USART_TransmitterIdleIsLowDisable Disables the Transmit Idle Low state. PLIB_USART_TransmitterIdleIsLowEnable Enables the Transmit Idle Low state. PLIB_USART_TransmitterInterruptModeSelect Sets the USART transmitter interrupt mode. PLIB_USART_TransmitterIsEmpty Gets the transmit shift register empty status. PLIB_USART_WakeOnStartDisable Disables the wake-up on start bit detection feature during Sleep mode. PLIB_USART_WakeOnStartEnable Enables the wake-up on start bit detection feature during Sleep mode. PLIB_USART_WakeOnStartIsEnabled Gets the state of the sync break event completion. Description USART Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the USART Peripheral Libraries Help USART Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2159 Peripheral Library for all families of Microchip microcontrollers. The functions in this file are common to the USART module. File Name plib_usart.h Company Microchip Technology Inc. plib_usart_help.h Enumerations Name Description USART_HANDSHAKE_MODE Lists the USART handshake modes. USART_LINECONTROL_MODE Data type defining the different configurations by which the USART data flow can be configured. USART_MODULE_ID Enumeration: USART_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. USART_OPERATION_MODE Data type defining the different configurations by which the USART can be enabled. USART_RECEIVE_INTR_MODE Data type defining the different Receive FIFO levels by which the USART receive interrupt modes can be configured. USART_TRANSMIT_INTR_MODE Data type defining the different transmit FIFO levels by which the USART transmit interrupt modes can be configured. Macros Name Description _USART_MODULE_ID Peripheral Libraries Help USART Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2160 USB Peripheral Library This section describes the USB Peripheral Library. Introduction This library provides a low-level abstraction of the USB module on Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description USB Overview USB is an asynchronous serial interface with a tiered star configuration. USB is implemented as a master/slave configuration. On a given bus, there can be multiple (up to 127) slaves (devices), but there is only one master (host). There are three possible module implementations: host, device and OTG dual role. The user should have an understanding of the USB documents available on the USB implementers web site (www.usb.org). Device The USB device accepts data from the host and responds to requests for data. It performs some peripheral functions, such as a mouse or data storage device. • Functionality may be class or vendor-specific • Draws 100 mA or less before configuration • Can draw up to 500 mA after successful negotiation with the host • Can support low-speed, full-speed or high-speed protocol. Hi-speed support requires implementation of full-speed. (Low, Full, and Hi-Speed supported by this module.) • Supports control transfers. Supports data transfers required for implementation • Optionally supports Session Request Protocol (SRP) • Can be bus-powered or self-powered Host The host is the master in a USB system and is responsible for identifying all devices connected to it (enumeration), initiating all transfers, allocating bus bandwidth and supplying power to any bus-powered USB devices connected directly to it. There are two types of hosts. USB Standard Host: • A large variety of devices are supported • This host supports all USB transfer types • USB hubs are supported to allow connection of multiple devices simultaneously • Device drivers can be updated to support new devices • A type ‘A’ receptacle is used for each port • Each port must be able to deliver a minimum of 100 mA for a configured or unconfigured • device, and optionally, up to 500 mA for a configured device • Full-Speed and Low-Speed must be supported. Hi-Speed can be supported. Peripheral Libraries Help USB Peripheral Library Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2161 • This is a typical personal computer implementation Embedded Host • Only supports a specific list of devices, referred to as a Targeted Peripheral List (TPL) • This type of host is only required to support transfer types required by devices in the TPL • USB hub support is optional (Provided in this module) • Device drivers are not required to be pocketable • A type ‘A’ receptacle is used for each port • Only speeds required by devices in the TLP must be supported. (Low, Full, and Hi-Speed supported by this module.) • Each port must be able to deliver a minimum of 100 mA for a configured or unconfigured device, and optionally, up to 500 mA for a configured device • This is a typical implementation for a microcontroller USB On-the-Go (OTG) The OTG dual role device supports both USB host and device functionality. OTG dual role devices use a micro-AB receptacle. This allows a micro-A or a micro-B plug to be attached. Both the micro-A and micro-B plugs have an additional pin, the ID pin, to signify the connection type. The plug type, micro-A or micro-B, determines the default role of the OTG device, host or USB device. An OTG device will perform the role of a host when a micro-A plug is detected. When a micro-B plug is detected, the role of a USB device is performed. When an OTG device is directly connected to another OTG device using an OTG cable, micro-A to micro-B, Host Negotiation Protocol (HNP) can be used to swap the roles of the host and USB device between the two without disconnecting and reconnecting cabling. To differentiate between the two OTG devices, the term, "A-device", is used to refer to the device connected to the micro-A plug and "B-device" is used to refer to the OTG device connected to the micro-B plug. OTG dual role operating as a host (A-device): • Only supports a specific list of devices, referred to as a Targeted Peripheral List (TPL). Generic class support is not allowed. • Only required to support transaction types required by devices in the TPL • USB hub support is optional. (Multi-point support provided by this module.) • Device drivers are not required to be pocketable • Only a single micro-AB receptacle is used • Only Full-Speed must be supported. Hi-Speed and/or Low-Speed can be supported. (Low, Full, and Hi-Speed supported by this module.) • The USB port must be able to deliver a minimum of 8 mA for a configured or unconfigured device, and optionally, up to 500 mA for a configured device • Supports Host Negotiation Protocol (HNP) and Session Request Protocol (SRP). The host can switch roles to become a device. The initial role as a host or device is determined by the plug type, micro-A or micro-B, inserted into the micro-AB receptacle • The A-device supplies VBUS power, when the bus is powered, even if the roles are swapped using HNP OTG dual role operating as a USB device (B-device): • Class or vendor-specific functionality • Draws 8 mA or less before configuration • Is typically self-powered due to low-current requirements, but can draw up to 500 mA after successful negotiation with the host • Only a single micro-AB receptacle is used • Must support Full-Speed. Support of Low-Speed and/or Hi-Speed is optional • Supports control transactions. Supports data transactions required for implementation. • Supports Session Request Protocol (SRP) and/or Host Negotiation Protocol (HNP). (This module supports both SRP and HNP.) • The A-device supplies VBUS power, when the bus is powered, even if the roles are swapped using HNP Additional Features of the Hi-Speed USB Module • Operates either as a function controller of a Hi-Speed/Full-Speed USB device or as the host/device in a point-to-point or multi-point communications with other USB function • Supports OTG communications with on or more Hi-Speed, Full-Speed, or Low-Speed devices • Provides soft_connect/disconnect. • In addition to Endpoint Zero, supports seven transmit and seven receive endpoints • Dynamic FIFO sizing for Endpoints 1-7. (Endpoint Zero FIFO fixed at 64 bytes.) FIFOs use module-internal SRAM. • Module-internal eight channel DMA with access to all FIFOs • All host transaction scheduling supported in hardware • Supports Link Power Management Using the Library This topic describes the basic architecture of the USB Peripheral Library and provides information and examples on its use. Peripheral Libraries Help USB Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2162 Description Interface Header File: plib_usb.h The interface to the USB Peripheral Library is defined in the plib_usb.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the USB Peripheral Library must include peripheral.h. Library File: The USB Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Hardware Abstraction Models This section describes the hardware abstraction model for the USB Peripheral Library. Description Hardware Abstraction Model The following figure shows the USB Module for the PIC32 family of devices. PIC32 USB Module Peripheral Libraries Help USB Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2163 The USB OTG module contains analog and digital components to provide a USB 2.0 full-speed and low-speed embedded host, full-speed device, or On-The-Go (OTG) implementation with a minimum of external components. This module in Host mode is intended for use as an embedded host and therefore does not implement a Universal Host Controller Interface (UHCI) or a Open Host Controller Interface (OHCI). The USB OTG module consists of the clock generator, the USB voltage comparators, the transceiver, the Serial Interface Engine (SIE), a dedicated USB Bus Master, pull-up and pull-down resistors and the register interface. The clock generator provides the 48 MHz clock, which is required for USB full-speed and low-speed communication. The voltage comparators monitor the voltage on the VBUS pin to determine the state of the bus. The transceiver provides the analog translation between the USB bus and the digital logic. The SIE is a state machine that transfers data to and from the endpoint buffers, and generates the hardware protocol for data transfers. The USB Bus Master transfers data between the data buffers in RAM and the SIE. The integrated pull-up and pull-down resistors eliminate the need for external signaling components. The register interface allows the CPU to configure and communicate with the module. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the USB module. Library Interface Section Description USB Setup Functions This section provides functions to perform general USB peripheral setup such as functions to set USB Speed, control on-chip pull ups, etc. Buffer Descriptor Table Functions This section provides functions that allow the application to setup, configure and access/modify the Buffer Descriptors in the Buffer Descriptor Table. USB Activity Functions This section provides function that allow the application to monitor bus conditions on the USB. USB Bus Signaling Functions This section provides functions that allow the application to generate Reset and Resume Signaling. Last Transaction Status Functions This section provides functions that allow the application to query conditions of the USB peripheral. Endpoints Functions This section provides functions that allow the application to manage endpoints. Interrupts Functions This section provides functions that allow the application to enable, disable and query the status interrupts in the USB peripheral. Host Functions This section provides functions that are required to operate the USB module while in Host mode. On-The-Go (OTG) Functions This section provides functions that are required to operate the USB module while in OTG mode. External Transceiver Support Functions This section provides function that are required to operate to enable/disable the external transceiver interface. Peripheral Libraries Help USB Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2164 VBUS Support Functions This section provides functions that allow VBUS level monitoring and VBUS boost PWM module control. Test Support Functions This section provides functions that enable/disable test signals needed for eye pattern measurement. How the Library Works Provides information on how the library works. Description The following figure describes the abstraction model employed by the USB Peripheral Library. USB Peripheral Library Abstraction Model USB Buffers and the Buffer Descriptor Table (BDT) This section describes USB buffers and the Buffer Descriptor Table. Description All USB endpoints are implemented using buffers and control bits in RAM. Both software and the USB module have access to these buffers and control bits. To arbitrate this access a semaphore flag system is used. Each endpoint can be configured for transmit only, receive only or transmit and receive. Transmit and receive functions have separate buffers. For each buffer there is a Buffer Descriptor (BD) in the Buffer Descriptor Table (BDT). On most devices the BDT has room for two transmit and two receive buffers for each endpoint, supporting ping-pong buffering. Buffer descriptors must be aligned on 512 byte boundaries to enable the USB module to correctly read each entry. The starting address of the Buffer Descriptor Table is set by the PLIB_USB_BDTBaseAddressSet. #define USB_MAX_EP_NUMBER 15 Peripheral Libraries Help USB Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2165 #define BDT_NUM_ENTRIES (((USB_MAX_EP_NUMBER + 1) * 4)-2) volatile union USB_BDT_ENTRY_TAG gBDT[BDT_NUM_ENTRIES] __attribute__ (( aligned (512) )); Each Buffer Descriptor entry in the BDT has a bufferAddress pointer to the Buffer Descriptor's buffer in memory (RAM or FLASH). The following figure shows the structure for PIC32 devices. These devices support ping-pong buffering for all endpoints. Buffer Descriptor Table and Endpoint Buffers With 16 endpoints (Endpoints 0 - 15 ) there are 64 possible entries in the Buffer Descriptor Table: // (Even,Odd) or (Ping,Pong) // (RX,TX) | // (EP0 to EPn) | | volatile USB_BDT_ENTRY myBDT[(USB_MAX_EP_NUMBER + 1)][2][2] __attribute__ (( aligned (512) )); Peripheral library functions are provided to support reading each BD while hiding the details of BDT addressing that can change when ping-pong buffering is disabled for one or more endpoints. The format of Buffer Descriptors vary from family to family and it is not important to know the differences, since peripheral library functions hide these details. To understand the information stored in each Buffer Descriptor Table entry it is informative to look at the C language description for one family of devices. (All device families support the same information but with different ways of packing the data into memory.) For PIC32 devices each BD is 8 bytes long and is described by this C code: typedef union _USB_BDT_ENTRY __attribute__ ((packed)) { uint64_t dlValue; //Double Long Integer Value uint32_t lValue[2]; //Long Integer Values uint16_t sValue[4]; //Short Integer Values Peripheral Libraries Help USB Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2166 struct __attribute__ ((packed)) { USB_BD_STATUS bufferStatus; //(RW) Buffer Status uint16_t byteCount:10; //(RW) Byte Count uint8_t : 6; //( ) Reserved uint32_t bufferAddress; //(RW) Buffer Address in Data Ram or Flash }; } USB_BDT_ENTRY; For transmit buffers, byteCount, is set to the length of the buffer using PLIB_USB_BufferByteCountSet. For receive buffers PLIB_USB_BufferByteCountSet is used to set the maximum allowable receive data length. PLIB_USB_BufferByteCountGet is used to determine how many bytes were actually transmitted or received. The memory address of each buffer is found in bufferAddress. The functions PLIB_USB_BufferAddressSet and PLIB_USB_BufferAddressGet support this field in the Buffer Descriptor. Buffer status is stored in the 16 least significant bits of each BDT entry: typedef union _USB_BD_STATUS __attribute__ ((packed)) { uint16_t sValue; //Short Integer Value struct __attribute__ ((packed)) { uint8_t :2; //( )Reserved uint8_t stallEnable :1; //( W) Buffer Stall Enable uint8_t dataToggleSyncEnable :1; //( W) Data Toggle Synch Enable uint8_t :1; //( ) Reserved uint8_t :1; //( ) Reserved uint8_t dataToggle :1; //(RW) Data Toggle Synch Value uint8_t uSBOwnsBuffer :1; //(RW) USB Ownership of buffer and BDT entry }; struct __attribute__ ((packed)) { uint8_t :2; //( ) Reserved uint8_t packetID :4; //(R ) Packet Identifier (PID) }; } USB_BD_STATUS; The fields stallEnable and dataToggleSyncEnable in the Buffer Descriptor status structure are writeable but not readable. The function PLIB_USB_BufferStallEnable sets the stallEnable bit. (Hardware will clear the bit after receiving a SETUP token from the host.) The functions PLIB_USB_BufferDataToggleSyncEnable and PLIB_USB_BufferDataToggleSyncDisable manipulate dataToggleSyncEnable . On a read from the status structure stallEnable and dataToggleSyncEnable and the next two (reserved) bits are replaced by the Packet Identifier (PID), called packetID in the structure. The function PLIB_USB_BufferPIDGet reads packetID. The rest of the status structure is writeable and readable: dataToggle and uSBOwnsBuffer. The dataToggle (DATA0 or DATA1) of a receive buffer is determined by using PLIB_USB_BufferDataToggleGet. For transmit buffers the dataToggle value is set using PLIB_USB_BufferDataToggleSelect . The field uSBOwnsBuffer is used by both software and the USB module as a semaphore. The function PLIB_USB_BufferReleaseToUSB releases the buffer to the USB module and the function PLIB_USB_BufferReleasedToSW returns a Boolean true when the buffer is released back to software by the USB module. As long as PLIB_USB_BufferReleasedToSW returns false, software should not change the Buffer Descriptor Table entry or its associated buffer. USB Setup Example This section provides example code for setting up the USB module. Description Following is an example of how to set up the USB module: #define USB_MAX_EP_NUMBER 15 #define BDT_NUM_ENTRIES (((USB_MAX_EP_NUMBER + 1) * 4)-2) volatile union USB_BDT_ENTRY_TAG gBDT[BDT_NUM_ENTRIES] __attribute__ (( aligned (512) )); unsigned int bufferTransactionCount[BDT_NUM_ENTRIES]; // Turn off USB module PLIB_USB_Disable( usbID ); // Set up the Hardware if ( usbModuleSetup.StopInIdle ) { PLIB_USB_StopInIdleEnable( usbID ); Peripheral Libraries Help USB Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2167 } else { PLIB_USB_StopInIdleDisable( usbID ); } if ( usbModuleSetup.SuspendInSleep ) { PLIB_USB_AutoSuspendEnable( usbID ); } else { PLIB_USB_AutoSuspendDisable( usbID ); } PLIB_USB_OperatingModeSelect( usbID, usbModuleSetup.OpMode ); PLIB_USB_PingPongModeSelect( usbID, usbModuleSetup.ppMode ); // Reset all ping pong buffers to "Even" PLIB_USB_PingPongFreeze( usbID ); PLIB_USB_PingPongUnfreeze( usbID ); // Interrupt flag cleared on the safer side IFS1bits.USBIF = 0; // Enable USB module interrupts PLIB_USB_InterruptEnable( usbID, DRV_USB_GEN_INT_ENABLES ); // Disable all OTG interrupts PLIB_USB_OTG_InterruptDisable( usbID, DRV_USB_OTB_INT_ENABLES ); // Enable all Error interrupts PLIB_USB_ErrorInterruptEnable( usbID, DRV_USB_ERR_INT_ENABLES ); // Enable the interrupt source in case of interrupt mode IEC1bits.USBIE = 1; // Setting the Interrupt Priority in case of interrupt mode. IPC11bits.USBIP = 4; // Initialize BDT for ( iEntry = 0; iEntry < BDT_NUM_ENTRIES; iEntry++ ) { gBDT[iEntry].lValue[0] = 0ul; gBDT[iEntry].lValue[1] = 0ul; bufferTransactionCount[iEntry] = 0; }//end for ( iEntry = 0; iEntry < BDT_NUM_ENTRIES; iEntry++ ) // Inform USB module of BDT's address in memory PLIB_USB_BDTBaseAddressSet( usbID , (void *)((uint32_t)KVA_TO_PA(gBDT)) ); /***********************/ /* SET UP ENDPOINT ZERO */ /***********************/ PLIB_USB_BufferAddressSet( usbID, (void*)gBDT, PLIB_USB_PingPongModeGet( usbID ), 0, USB_BUFFER_RX, USB_BUFFER_EVEN, pSetupRcvBuffer ); // Configure Endpoint Zero control register PLIB_USB_EP0LSDirectConnectDisable( usbID ); // For Hosts, included for completeness PLIB_USB_EP0NakRetryEnable( usbID ); // For Hosts, included for completeness PLIB_USB_EPnControlTransferEnable( usbID, 0 ); // Enable control transfers PLIB_USB_EPnRxSelect( usbID, 0, USB_EP_RX ); // Enable receive PLIB_USB_EPnHandshakeEnable( usbID, 0 ); // Enable handshaking // Set up Endpoint Zero's receive buffer BDT entries ppMode = PLIB_USB_PingPongModeGet( usbID ); // Ping Pong Mode needed for BDT entry indexing Peripheral Libraries Help USB Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2168 // Clear PID bits PLIB_USB_BufferPIDBitsClear(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN); //Rx0 // Disable buffer stall PLIB_USB_BufferStallDisable(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN); //Rx0 // Enable Data Toggle Synchronization PLIB_USB_BufferDataToggleSyncEnable(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN); //Rx0 // Set Data0/1 to Data0 PLIB_USB_BufferDataToggleSelect(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN,USB_BUFFER_DATA 0); //Rx0 // Setup packets have 8 bytes of data payload PLIB_USB_BufferByteCountSet(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN,8); // Release buffers to USB module PLIB_USB_BufferReleaseToUSB(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN); PLIB_USB_Enable( gDrvUSBObj[hDriver].usbID ); // Turn on USB module Configuring the Library The library is configured for the supported USB module when the processor is chosen in the MPLAB X IDE. Library Interface a) USB Setup Functions Name Description PLIB_USB_AllInterruptEnable Configures the USB peripheral general interrupts, error interrupts and OTG interrupts. PLIB_USB_AutoSuspendDisable Disables USB OTG Auto-suspend mode. PLIB_USB_AutoSuspendEnable Enables USB Auto-suspend mode. PLIB_USB_DeviceAddressGet Returns the address of the USB module in Device mode. PLIB_USB_DeviceAddressSet Sets the USB Device's address. PLIB_USB_Disable Disables (powers down) the USB module. PLIB_USB_Enable Enables (powers up) the USB module. PLIB_USB_FullSpeedDisable Forces the USB module to operate at low speed. PLIB_USB_FullSpeedEnable Enables the USB to operate at full speed. PLIB_USB_OnChipPullUpDisable Disables on-chip pull-ups. PLIB_USB_OnChipPullUpEnable Enables on-chip pull-ups. PLIB_USB_OperatingModeSelect Selects the operating mode of the USB module. PLIB_USB_PingPongModeGet Returns the Ping-Pong Configuration setting. PLIB_USB_PingPongModeSelect Selects the Ping-Pong Configuration setting. PLIB_USB_SleepGuardDisable This function disables Sleep Guard. Entry into Sleep mode is immediate. PLIB_USB_SleepGuardEnable Entry into Sleep mode is blocked if bus activity is detected or if an interrupt is pending. PLIB_USB_StopInIdleDisable Allows the USB module to continue operation when the device enters Idle mode. PLIB_USB_StopInIdleEnable Enables USB module operation to stop when the device enters Idle mode. PLIB_USB_SuspendDisable Disables USB OTG Suspend mode. PLIB_USB_SuspendEnable Enables USB Suspend mode. PLIB_USB_UOEMonitorDisable Disables the OE signal output. PLIB_USB_UOEMonitorEnable Enables the OE signal output. b) Buffer Descriptor Table Functions Name Description PLIB_USB_BDTBaseAddressGet Returns the base address of the Buffer Descriptor Table. PLIB_USB_BDTBaseAddressSet Sets the base address for the Buffer Descriptor Table for PIC32 devices. PLIB_USB_BufferAddressGet Gets the memory address of an endpoint buffer. PLIB_USB_BufferAddressSet Sets the endpoint buffer address. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2169 PLIB_USB_BufferAllCancelReleaseToUSB Cancels all endpoint buffer releases to the USB module and hands over the buffer to the CPU. PLIB_USB_BufferByteCountGet Returns the endpoint buffer byte count. PLIB_USB_BufferByteCountSet Sets the buffer byte count. PLIB_USB_BufferCancelReleaseToUSB Cancels release of the endpoint buffer by software, allowing software to again access the buffer. PLIB_USB_BufferClearAll Clears (zeros out) entries in the Buffer Descriptor Table. PLIB_USB_BufferClearAllDTSEnable Clears the endpoint descriptor entry and enables data toggle synchronization. PLIB_USB_BufferDataToggleGet Returns data synchronization (DATA0 or DATA1) for the endpoint buffer. PLIB_USB_BufferDataToggleSelect Sets the endpoint buffer to DATA0 or DATA1. PLIB_USB_BufferDataToggleSyncDisable Disables DATA0/DATA1 synchronization between the device and host. PLIB_USB_BufferDataToggleSyncEnable Enables DATA0/DATA1 synchronization between the device and host. PLIB_USB_BufferEP0RxStatusInitialize Initializes the Endpoint 0 RX endpoint buffer descriptors. PLIB_USB_BufferIndexGet Gets the Buffer Descriptor Table index for a buffer. PLIB_USB_BufferPIDBitsClear Clears the Buffer Status bits in the Buffer Descriptor Table. PLIB_USB_BufferPIDGet Returns the token packet ID (PID) from the endpoint buffer status. PLIB_USB_BufferReleasedToSW Returns the boolean flag value of 'true' when the buffer has been released by the USB module. PLIB_USB_BufferReleaseToUSB Releases the endpoint buffer by software, allowing the USB module access to the buffer. PLIB_USB_BufferSchedule Hands over a buffer to the USB module along with the buffer address and byte count. PLIB_USB_BufferStallDisable Disables STALL handshaking for the associated endpoint buffer. PLIB_USB_BufferStallEnable Enables STALL handshaking for the associated endpoint buffer. PLIB_USB_BufferStallGet Returns the buffer stall status for an endpoint/direction/ping-pong. c) Endpoints Functions Name Description PLIB_USB_EP0HostSetup Sends token to the specified address. PLIB_USB_EP0LSDirectConnectDisable Disables direct connection to a low-speed device for Endpoint 0. PLIB_USB_EP0LSDirectConnectEnable Enables direct connection to a low-speed device for Endpoint 0. PLIB_USB_EP0NakRetryDisable Disables retrying of NAKed transactions. PLIB_USB_EP0NakRetryEnable Enables retrying NAK'd transactions for Endpoint 0. PLIB_USB_EPnAttributesClear Clears the set attributes of the specified endpoint. PLIB_USB_EPnAttributesSet Configures attributes of the endpoint such as direction, handshake capability and direction. PLIB_USB_EPnControlTransferDisable Disables endpoint control transfers. PLIB_USB_EPnControlTransferEnable Enables endpoint control transfers. PLIB_USB_EPnDirectionDisable Disables the specified endpoint direction. PLIB_USB_EPnHandshakeDisable Disables endpoint handshaking. PLIB_USB_EPnHandshakeEnable Enables endpoint handshaking. PLIB_USB_EPnIsStalled Tests whether the endpoint epValue is stalled. PLIB_USB_EPnRxDisable Disables an endpoint's ability to process IN tokens. PLIB_USB_EPnRxEnable Enables an endpoint to process IN tokens. PLIB_USB_EPnRxSelect Selects receive capabilities of an endpoint. PLIB_USB_EPnStallClear Clears an endpoint's stalled flag. PLIB_USB_EPnTxDisable Disables an endpoint's ability to process OUT tokens. PLIB_USB_EPnTxEnable Enables an endpoint to process OUT tokens. PLIB_USB_EPnTxRxSelect Selects transmit and/or receive capabilities of an endpoint. PLIB_USB_EPnTxSelect Selects transmit capabilities of an endpoint. d) Interrupts Functions Name Description PLIB_USB_InterruptDisable Disables a general interrupt for the USB module. PLIB_USB_InterruptEnable Enables a general interrupt for the USB module. PLIB_USB_InterruptEnableGet Returns the enable/disable status of general USB module interrupts PLIB_USB_InterruptFlagAllGet Returns a logically ORed bit map of active general USB interrupt flags. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2170 PLIB_USB_InterruptFlagClear Clears a general interrupt flag for the USB module. PLIB_USB_InterruptFlagGet Tests a general interrupt flag for the USB module. PLIB_USB_InterruptFlagSet Sets a general interrupt flag for the USB module. PLIB_USB_InterruptIsEnabled Returns true if interrupts are enabled. e) Error Interrupts Functions Name Description PLIB_USB_ErrorInterruptDisable Disables an error interrupt for the USB module. PLIB_USB_ErrorInterruptEnable Enables an error interrupt for the USB module. PLIB_USB_ErrorInterruptFlagAllGet Returns a logically ORed bit map of active error interrupt flags. PLIB_USB_ErrorInterruptFlagClear Clears an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptFlagGet Tests an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptFlagSet Sets an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptIsEnabled Returns true if interrupts are enabled. f) Last Transaction Status Functions Name Description PLIB_USB_LastTransactionDetailsGet Returns the details of the last completed transaction. PLIB_USB_LastTransactionDirectionGet Indicates the direction of the last transaction. PLIB_USB_LastTransactionEndPtGet Returns the endpoint number of the last USB transfer. PLIB_USB_LastTransactionPingPongStateGet Indicates whether the last transaction was to an EVEN buffer or an ODD buffer. g) Host Functions Name Description PLIB_USB_IsBusyWithToken Indicates whether there is a token being executed by the USB module as Host. PLIB_USB_SOFDisable Disables the automatic generation of the SOF token. PLIB_USB_SOFEnable Enables the automatic generation of the SOF token every 1 ms. PLIB_USB_SOFThresholdGet Returns the Start-of-Frame (SOF) Count bits. PLIB_USB_SOFThresholdSet Sets the Start-of-Frame (SOF) threshold value. PLIB_USB_TokenEPGet Returns the specified Endpoint address. PLIB_USB_TokenEPSet Sets the Endpoint address for a host transaction. PLIB_USB_TokenPIDGet Returns the token transaction type. PLIB_USB_TokenPIDSet Sets the token transaction type to pidValue. PLIB_USB_TokenSpeedSelect Selects low speed or full speed for subsequent token executions. h) USB Bus Signaling Functions Name Description PLIB_USB_ResetSignalDisable Disables reset signaling on the USB bus. PLIB_USB_ResetSignalEnable Enables reset signaling on the USB bus. PLIB_USB_ResumeSignalingDisable Disables resume signaling. PLIB_USB_ResumeSignalingEnable Enables resume signaling. i) On-The-Go (OTG) Functions Name Description PLIB_USB_OTG_BSessionHasEnded Returns the status of the B-Session End Indicator bit. PLIB_USB_OTG_IDPinStateIsTypeA Returns the ID Pin state. PLIB_USB_OTG_LineStateIsStable Returns the status of the Line Stable Indicator bit. PLIB_USB_OTG_PullUpPullDownSetup Enables or disables pull-up and pull-down resistors. PLIB_USB_OTG_SessionValid Returns the status of the Session Valid Indicator bit. PLIB_USB_OTG_VBusChargeDisable Disables VBUS line charge. PLIB_USB_OTG_VBusChargeEnable Enables the VBUS line to be charged through a pull-up resistor. PLIB_USB_OTG_VBusChargeTo3V Sets the VBUS line to charge to 3.3V. PLIB_USB_OTG_VBusChargeTo5V Sets the VBUS line to charge to 5V. PLIB_USB_OTG_VBusDischargeDisable Disables VBUS line discharge. PLIB_USB_OTG_VBusDischargeEnable Enables VBUS line to be discharged through a resistor. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2171 PLIB_USB_OTG_VBusPowerOff Turns off power on the VBUS Line. PLIB_USB_OTG_VBusPowerOn Turns on power for the VBUS line. PLIB_USB_OTG_VBusValid Returns the status of the A-VBUS valid indicator. j) OTG Interrupts Functions Name Description PLIB_USB_OTG_InterruptDisable Disables a USB On-The-Go (OTG) Interrupt for the USB module. PLIB_USB_OTG_InterruptEnable Enables a USB On-The-Go (OTG) Interrupt for the USB module. PLIB_USB_OTG_InterruptFlagClear Clears a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptFlagGet Tests a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptFlagSet Sets a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptIsEnabled Returns whether or not interrupts are enabled. k) USB Activity Functions Name Description PLIB_USB_ActivityPending Returns whether or not USB activity is pending. PLIB_USB_FrameNumberGet Returns the USB frame number. PLIB_USB_JStateIsActive Live differential receiver J State flag. PLIB_USB_PacketTransferDisable Disables the Serial Interface Engine (SIE). PLIB_USB_PacketTransferEnable Re-enables the Serial Interface Engine (SIE), allowing token and packet processing. PLIB_USB_PacketTransferIsDisabled Indicates that a setup token has been received from the Host and that token/packet processing is disabled. PLIB_USB_SE0InProgress Returns whether a single-ended zero event is in progress. l) External Transceiver Support Functions Name Description PLIB_USB_I2CInterfaceForExtModuleDisable Specifies external module(s) are controlled via dedicated pins. PLIB_USB_I2CInterfaceForExtModuleEnable Specifies external module(s) are controlled via the I2C interface. PLIB_USB_TransceiverDisable Disables the on-chip transceiver PLIB_USB_TransceiverEnable Enables the on-chip transceiver. m) VBUS Support Functions Name Description PLIB_USB_ExternalComparatorMode2Pin Sets the 2-pin input configuration for VBUS comparators. PLIB_USB_ExternalComparatorMode3Pin Sets the 3-pin input configuration for VBUS Comparators. PLIB_USB_PWMCounterDisable Disables the PWM counter used to generate the VBUS for the USB module. PLIB_USB_PWMCounterEnable Enables the PWM counter used to generate the VBUS for the USB module. PLIB_USB_PWMDisable Disables the PWM Generator. PLIB_USB_PWMEnable Enables the PWM Generator. PLIB_USB_PWMPolaritiyActiveLow Sets the PWM output to active-high and resets low. PLIB_USB_PWMPolarityActiveHigh Sets the PWM output to active-low and resets high. PLIB_USB_VBoostDisable Disables the On-Chip 5V Boost Regulator Circuit Disabled bit. PLIB_USB_VBoostEnable Enables the On-Chip 5V Boost Regulator Circuit Enabled bit. PLIB_USB_VBUSComparatorDisable Disables the on-chip VBUS Comparator. PLIB_USB_VBUSComparatorEnable Enables the on-chip VBUS Comparator. PLIB_USB_VBUSPullUpDisable Disables the pull-up on the VBUS pin. PLIB_USB_VBUSPullUpEnable Enables the pull-up on the VBUS pin. n) Test Support Functions Name Description PLIB_USB_EyePatternDisable Disables the USB eye pattern test. PLIB_USB_EyePatternEnable Enables USB eye pattern test. o) Other Functions Name Description PLIB_USB_ModuleIsBusy Indicates if the USB module is not ready to be enabled. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2172 PLIB_USB_PingPongFreeze Resets all Ping-Pong buffer pointers to even buffers. PLIB_USB_PingPongReset Resets the USB peripheral internal Ping-Pong indicator to point to even buffers. PLIB_USB_PingPongUnfreeze Enables Ping-Pong buffering. PLIB_USB_TokenSend Sends token to the specified address. p) Feature Existence Functions Name Description PLIB_USB_ExistsActivityPending Identifies whether the ActivityPending feature exists on the USB module. PLIB_USB_ExistsALL_Interrupt Identifies whether the ALL_Interrupt feature exists on the USB module. PLIB_USB_ExistsAutomaticSuspend Identifies whether the AutomaticSuspend feature exists on the USB module. PLIB_USB_ExistsBDTBaseAddress Identifies whether the BDTBaseAddress feature exists on the USB module. PLIB_USB_ExistsBDTFunctions Identifies whether the BDTFunctions feature exists on the USB module. PLIB_USB_ExistsBufferFreeze Identifies whether the BufferFreeze feature exists on the USB module. PLIB_USB_ExistsDeviceAddress Identifies whether the DeviceAddress feature exists on the USB module. PLIB_USB_ExistsEP0LowSpeedConnect Identifies whether the EP0LowSpeedConnect feature exists on the USB module. PLIB_USB_ExistsEP0NAKRetry Identifies whether the EP0NAKRetry feature exists on the USB module. PLIB_USB_ExistsEPnRxEnable Identifies whether the EPnRxEnableEnhanced feature exists on the USB module. PLIB_USB_ExistsEPnTxRx Identifies whether the EPnTxRx feature exists on the USB module. PLIB_USB_ExistsERR_Interrupt Identifies whether the ERR_Interrupt feature exists on the USB module. PLIB_USB_ExistsERR_InterruptStatus Identifies whether the ERR_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsEyePattern Identifies whether the EyePattern feature exists on the USB module. PLIB_USB_ExistsFrameNumber Identifies whether the FrameNumber feature exists on the USB module. PLIB_USB_ExistsGEN_Interrupt Identifies whether the GEN_Interrupt feature exists on the USB module. PLIB_USB_ExistsGEN_InterruptStatus Identifies whether the GEN_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsHostBusyWithToken Identifies whether the HostBusyWithToken feature exists on the USB module. PLIB_USB_ExistsHostGeneratesReset Identifies whether the HostGeneratesReset feature exists on the USB module. PLIB_USB_ExistsLastDirection Identifies whether the LastDirection feature exists on the USB module. PLIB_USB_ExistsLastEndpoint Identifies whether the LastEndpoint feature exists on the USB module. PLIB_USB_ExistsLastPingPong Identifies whether the LastPingPong feature exists on the USB module. PLIB_USB_ExistsLastTransactionDetails Identifies whether the LastTransactionDetails feature exists on the USB module. PLIB_USB_ExistsLiveJState Identifies whether the LiveJState feature exists on the USB module. PLIB_USB_ExistsLiveSingleEndedZero Identifies whether the LiveSingleEndedZero feature exists on the USB module. PLIB_USB_ExistsModuleBusy Identifies whether the ModuleBusy feature exists on the USB module. PLIB_USB_ExistsModulePower Identifies whether the ModulePower feature exists on the USB module. PLIB_USB_ExistsNextTokenSpeed Identifies whether the NextTokenSpeed feature exists on the USB module. PLIB_USB_ExistsOnChipPullup Identifies whether the OnChipPullup feature exists on the USB module. PLIB_USB_ExistsOnChipTransceiver Identifies whether the OnChipTransceiver feature exists on the USB module. PLIB_USB_ExistsOpModeSelect Identifies whether the OpModeSelect feature exists on the USB module. PLIB_USB_ExistsOTG_ASessionValid Identifies whether the OTG_ASessionValid feature exists on the USB module. PLIB_USB_ExistsOTG_BSessionEnd Identifies whether the OTG_BSessionEnd feature exists on the USB module. PLIB_USB_ExistsOTG_IDPinState Identifies whether the OTG_IDPinState feature exists on the USB module. PLIB_USB_ExistsOTG_Interrupt Identifies whether the OTG_Interrupt feature exists on the USB module. PLIB_USB_ExistsOTG_InterruptStatus Identifies whether the OTG_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsOTG_LineState Identifies whether the OTG_LineState feature exists on the USB module. PLIB_USB_ExistsOTG_PullUpPullDown Identifies whether the OTG_PullUpPullDown feature exists on the USB module. PLIB_USB_ExistsOTG_SessionValid Identifies whether the OTG_SessionValid feature exists on the USB module. PLIB_USB_ExistsOTG_VbusCharge Identifies whether the OTG_VbusCharge feature exists on the USB module. PLIB_USB_ExistsOTG_VbusDischarge Identifies whether the OTG_VbusDischarge feature exists on the USB module. PLIB_USB_ExistsOTG_VbusPowerOnOff Identifies whether the OTG_VbusPowerOnOff feature exists on the USB module. PLIB_USB_ExistsPacketTransfer Identifies whether the PacketTransfer feature exists on the USB module. PLIB_USB_ExistsPingPongMode Identifies whether the PingPongMode feature exists on the USB module. PLIB_USB_ExistsResumeSignaling Identifies whether the ResumeSignaling feature exists on the USB module. PLIB_USB_ExistsSleepEntryGuard Identifies whether the SleepEntryGuard feature exists on the USB module. PLIB_USB_ExistsSOFThreshold Identifies whether the SOFThreshold feature exists on the USB module. PLIB_USB_ExistsSpeedControl Identifies whether the SpeedControl feature exists on the USB module. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2173 PLIB_USB_ExistsStartOfFrames Identifies whether the StartOfFrames feature exists on the USB module. PLIB_USB_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the USB module. PLIB_USB_ExistsSuspend Identifies whether the Suspend feature exists on the USB module. PLIB_USB_ExistsTokenEP Identifies whether the TokenEP feature exists on the USB module. PLIB_USB_ExistsTokenPID Identifies whether the TokenPID feature exists on the USB module. PLIB_USB_ExistsUOEMonitor Identifies whether the UOEMonitor feature exists on the USB module. q) Data Types and Constants Name Description USB_BUFFER_DATA01 Provides enumeration data toggle for a buffer. USB_BUFFER_DIRECTION Provides enumeration transmit/receive direction for a buffer. USB_BUFFER_PING_PONG Enumerates the ping-pong buffer (Even vs. Odd). USB_BUFFER_SCHEDULE_DATA01 Provides enumeration data toggle for a buffer. USB_EP_TXRX Provides enumeration transmit/receive setup for an endpoint. USB_OPMODES Provides enumeration of operating modes supported by USB. USB_OTG_INTERRUPTS Provides enumeration of interrupts related to the USB On-The-Go (OTG) module. USB_OTG_PULL_UP_PULL_DOWN USB OTG pull-Up and pull-Down resistors for D+ and D- . USB_PID Legal PID values. USB_PING_PONG_MODE Supports the four modes of ping-pong buffering. USB_PING_PONG_STATE Decodes which buffer (Even vs. Odd) was used for the last transaction. USB_TOKEN_SPEED Provides enumeration of available token speeds. USB_MAX_EP_NUMBER Maximum number of endpoints supported (not including EP0). Description This section describes the Application Programming Interface (API) functions of the USB Peripheral Library. Refer to each section for a detailed description. a) USB Setup Functions PLIB_USB_AllInterruptEnable Function Configures the USB peripheral general interrupts, error interrupts and OTG interrupts. File plib_usb.h C void PLIB_USB_AllInterruptEnable(USB_MODULE_ID index, USB_INTERRUPTS usbInterruptsFlag, USB_ERROR_INTERRUPTS usbErrorInterruptsFlag, USB_OTG_INTERRUPTS otgInterruptFlag); Returns None. Description This function configures the USB peripheral general interrupts, error interrupts and OTG interrupts. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsALL_Interrupt in your application to determine whether this feature is available. Preconditions None. Example // This code snippet disables all OTG interrupts, disables // the SOF interrupt and enables all error interrupts. USB_OTG_INTERRUPTS otgInterruptEnables = ~USB_OTG_INT_ALL ; USB_INTERRUPTS generalInterruptEnables = USB_INT_ALL & ~USB_INT_SOF ; Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2174 USB_ERROR_INTERRUPTS errorInterruptEnables = USB_ERR_INT_ALL ; PLIB_USB_AllInterruptEnable(USB_MODULE_ID index, USB_INTERRUPTS usbInterruptsFlag, USB_ERROR_INTERRUPTS usbErrorInterruptsFlag, USB_OTG_INTERRUPTS otgInterruptFlag); Parameters Parameters Description index Identifier for the device instance of interest usbInterruptsFlag General interrupts to be configured usbErrorInterruptsFlag USB Error interrupts to be configured otgInterruptFlag OTG interrupts to be configured Function void PLIB_USB_AllInterruptEnable(USB_MODULE_ID index, USB_INTERRUPTS usbInterruptsFlag, USB_ERROR_INTERRUPTS usbErrorInterruptsFlag, USB_OTG_INTERRUPTS otgInterruptFlag); PLIB_USB_AutoSuspendDisable Function Disables USB OTG Auto-suspend mode. File plib_usb.h C void PLIB_USB_AutoSuspendDisable(USB_MODULE_ID index); Returns None. Description This function disables USB OTG Auto-suspend mode. The USB OTG module will operate normally and does not automatically suspend upon entry to Sleep mode. Software must use PLIB_USB_SuspendEnable to suspend the module, including the USB 48 MHz clock Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsAutomaticSuspend in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_AutoSuspendDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_AutoSuspendDisable ( USB_MODULE_ID index ) PLIB_USB_AutoSuspendEnable Function Enables USB Auto-suspend mode. File plib_usb.h C void PLIB_USB_AutoSuspendEnable(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2175 Returns None. Description This function enables USB Auto-suspend mode. The USB module automatically suspends upon entry to Sleep mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsAutomaticSuspend in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_AutoSuspendEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_AutoSuspendEnable ( USB_MODULE_ID index ) PLIB_USB_DeviceAddressGet Function Returns the address of the USB module in Device mode. File plib_usb.h C uint8_t PLIB_USB_DeviceAddressGet(USB_MODULE_ID index); Returns Device Address Description This function returns the address of the USB module in Device mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsDeviceAddressin your application to determine whether this feature is available. Preconditions None. Example myUSBAddress = PLIB_USB_DeviceAddressGet(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function uint8_t PLIB_USB_DeviceAddressGet ( USB_MODULE_ID index ) PLIB_USB_DeviceAddressSet Function Sets the USB Device's address. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2176 File plib_usb.h C void PLIB_USB_DeviceAddressSet(USB_MODULE_ID index, uint8_t address); Returns None. Description This function sets the USB Device's address as part of enumeration. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsDeviceAddressin your application to determine whether this feature is available. Preconditions USB module must be in Host mode. Example uint8_t myUSBAddress = ....; PLIB_USB_DeviceAddressSet(MY_USB_INSTANCE, myUSBAddress); Parameters Parameters Description index Identifier for the device instance of interest address USB address Function void PLIB_USB_DeviceAddressSet ( USB_MODULE_ID index, uint8_t address ) PLIB_USB_Disable Function Disables (powers down) the USB module. File plib_usb.h C void PLIB_USB_Disable(USB_MODULE_ID index); Returns None. Description This function disables (powers down) the USB module. Remarks For PIC32 devices, the USB module must be in Device mode before the USB module is powered down. For PIC32 devices, all reads or writes to module registers after powering down the module will be invalid until PLIB_USB_ModuleIsBusy (MY_USB_INSTANCE) == false. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsModulePower in your application to determine whether this feature is available. Preconditions None. Example #if defined(__PIC32MX__) // Disable Host, Device, or OTG before powering down PLIB_USB_OperatingModeSelect( MY_USB_INSTANCE, USB_OPMODE_NONE ); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2177 // Turn off USB PLIB_USB_Disable(MY_USB_INSTANCE); // For PIC32, wait until module is no longer busy before trying to // access any USB module registers. while ( PLIB_USB_ModuleIsBusy (MY_USB_INSTANCE) ) { //wait } #endif // Can now read or modify USB module status Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_Disable ( USB_MODULE_ID index ) PLIB_USB_Enable Function Enables (powers up) the USB module. File plib_usb.h C void PLIB_USB_Enable(USB_MODULE_ID index); Returns None. Description This function enables (powers up) the USB module. Remarks See also PLIB_USB_ModuleIsBusy. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsModulePoweryour application to determine whether this feature is available. Preconditions None. Example // Complete Needed setup for the module PLIB_USB_Enable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_Enable ( USB_MODULE_ID index ) PLIB_USB_FullSpeedDisable Function Forces the USB module to operate at low speed. File plib_usb.h C void PLIB_USB_FullSpeedDisable(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2178 Returns None. Description This function forces the USB module to operate at low speed. Remarks For PIC32 devices: Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSpeedControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_FullSpeedDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_FullSpeedDisable ( USB_MODULE_ID index ) PLIB_USB_FullSpeedEnable Function Enables the USB to operate at full speed. File plib_usb.h C void PLIB_USB_FullSpeedEnable(USB_MODULE_ID index); Returns None. Description This function enables the USB to operate at full speed. Remarks For PIC32 devices: Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSpeedControl in your application to determine whether this feature is available. Preconditions Use only before the USB module is enabled by calling PLIB_USB_Enable. Example PLIB_USB_FullSpeedEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_FullSpeedEnable ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2179 PLIB_USB_OnChipPullUpDisable Function Disables on-chip pull-ups. File plib_usb.h C void PLIB_USB_OnChipPullUpDisable(USB_MODULE_ID index); Returns None. Description This function disables on-chip pull-ups. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOnChipPullup in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OnChipPullUpDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_OnChipPullUpDisable ( USB_MODULE_ID index ) PLIB_USB_OnChipPullUpEnable Function Enables on-chip pull-ups. File plib_usb.h C void PLIB_USB_OnChipPullUpEnable(USB_MODULE_ID index); Returns None. Description This function enables on-chip pull-ups. Pull-up on D+ in Full-Speed mode. Pull-up on D- in Low-Speed mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOnChipPullup in your application to determine whether this feature is available. Preconditions Use only before the USB module is enabled by calling PLIB_USB_Enable. Example PLIB_USB_OnChipPullUpEnable(MY_USB_INSTANCE); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2180 Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_OnChipPullUpEnable ( USB_MODULE_ID index ) PLIB_USB_OperatingModeSelect Function Selects the operating mode of the USB module. File plib_usb.h C void PLIB_USB_OperatingModeSelect(USB_MODULE_ID index, USB_OPMODES opMode); Returns None. Description This function selects the operating mode of the USB module, either Host, Device, or OTG. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOpModeSelect in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OperatingModeSelect( MY_USB_INSTANCE, USB_OPMODE_DEVICE ); Parameters Parameters Description index Identifier for the device instance of interest opMode Selected operating mode: USB_OPMODE_DEVICE, USB_OPMODE_HOST, or USB_OPMODE_OTG Function void PLIB_USB_OperatingModeSelect( USB_MODULE_ID index, USB_OPMODES opMode ) PLIB_USB_PingPongModeGet Function Returns the Ping-Pong Configuration setting. File plib_usb.h C USB_PING_PONG_MODE PLIB_USB_PingPongModeGet(USB_MODULE_ID index); Returns Ping-Pong Mode - One of USB_PING_PONG__ALL_BUT_EP0, USB_PING_PONG__FULL_PING_PONG, USB_PING_PONG__EP0_OUT_ONLY, USB_PING_PONG__NO_PING_PONG Description This function returns the Ping-Pong Configuration setting. Remarks None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2181 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPingPongMode in your application to determine whether this feature is available. Preconditions None. Example ppConfig = PLIB_USB_PingPongModeGet(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function USB_PING_PONG_MODE PLIB_USB_PingPongModeGet ( USB_MODULE_ID index ) PLIB_USB_PingPongModeSelect Function Selects the Ping-Pong Configuration setting. File plib_usb.h C void PLIB_USB_PingPongModeSelect(USB_MODULE_ID index, USB_PING_PONG_MODE ppConfig); Returns None. Description This function selects the Ping-Pong Configuration setting. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPingPongMode in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_PingPongModeSelect(MY_USB_INSTANCE,USB_PING_PONG__ALL_BUT_EP0); Parameters Parameters Description index Identifier for the device instance of interest ppConfig Ping-Pong configuration selection. One of USB_PING_PONG__ALL_BUT_EP0, USB_PING_PONG__FULL_PING_PONG, USB_PING_PONG__EP0_OUT_ONLY, USB_PING_PONG__NO_PING_PONG Function void PLIB_USB_PingPongModeSelect ( USB_MODULE_ID index, USB_PING_PONG_MODE ppConfig) PLIB_USB_SleepGuardDisable Function File plib_usb.h C void PLIB_USB_SleepGuardDisable(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2182 Returns None. Description This function disables Sleep Guard. Entry into Sleep mode is immediate. Remarks Not available on all PIC32 devices. Refer to the specific device data sheet for details. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSleepEntryGuard in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_SleepGuardDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_SleepGuardDisable ( USB_MODULE_ID index ) Summary. Disables Sleep Guard. Entry into Sleep mode is immediate. PLIB_USB_SleepGuardEnable Function Entry into Sleep mode is blocked if bus activity is detected or if an interrupt is pending. File plib_usb.h C void PLIB_USB_SleepGuardEnable(USB_MODULE_ID index); Returns None. Description This function block entry into Sleep mode if bus activity is detected or if an interrupt is pending. Remarks Not available on all PIC32 devices. Refer to the specific device data sheet for details. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSleepEntryGuard in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_SleepGuardEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_SleepGuardEnable ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2183 PLIB_USB_StopInIdleDisable Function Allows the USB module to continue operation when the device enters Idle mode. File plib_usb.h C void PLIB_USB_StopInIdleDisable(USB_MODULE_ID index); Returns None. Description This function allows the USB module to continue operation when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_StopInIdleDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_StopInIdleDisable ( USB_MODULE_ID index ) PLIB_USB_StopInIdleEnable Function Enables USB module operation to stop when the device enters Idle mode. File plib_usb.h C void PLIB_USB_StopInIdleEnable(USB_MODULE_ID index); Returns None. Description This function enables USB module operation to stop when the device enters Idle mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsStopInIdle in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_StopInIdleEnable(MY_USB_INSTANCE); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2184 Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_StopInIdleEnable ( USB_MODULE_ID index ) PLIB_USB_SuspendDisable Function Disables USB OTG Suspend mode. File plib_usb.h C void PLIB_USB_SuspendDisable(USB_MODULE_ID index); Returns None. Description This function disables USB OTG Suspend mode. The USB OTG module will operate normally. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSuspend in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_SuspendDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_SuspendDisable ( USB_MODULE_ID index ) PLIB_USB_SuspendEnable Function Enables USB Suspend mode. File plib_usb.h C void PLIB_USB_SuspendEnable(USB_MODULE_ID index); Returns None. Description This function enables USB Suspend mode. The 48 MHz USB clock will be gated off. The transceiver is placed in a low-power state. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSuspend in your application to determine whether this feature is available. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2185 Preconditions None. Example PLIB_USB_SuspendEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_SuspendEnable ( USB_MODULE_ID index ) PLIB_USB_UOEMonitorDisable Function Disables the OE signal output. File plib_usb.h C void PLIB_USB_UOEMonitorDisable(USB_MODULE_ID index); Returns None. Description This function disables the OE signal output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsUOEMonitor in your application to determine whether this feature is available. Preconditions None. Example //Disable the OE output. PLIB_USB_UOEMonitorDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_UOEMonitorDisable( USB_MODULE_ID index ); PLIB_USB_UOEMonitorEnable Function Enables the OE signal output. File plib_usb.h C void PLIB_USB_UOEMonitorEnable(USB_MODULE_ID index); Returns None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2186 Description This function enables the OE signal output. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsUOEMonitor in your application to determine whether this feature is available. Preconditions None. Example //Enable the OE output. PLIB_USB_UOEMonitorEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_UOEMonitorEnable( USB_MODULE_ID index ); b) Buffer Descriptor Table Functions PLIB_USB_BDTBaseAddressGet Function Returns the base address of the Buffer Descriptor Table. File plib_usb.h C void* PLIB_USB_BDTBaseAddressGet(USB_MODULE_ID index); Returns None. Description This function returns the base address of the Buffer Descriptor Table. Remarks Must be set for PIC32 devices using PLIB_USB_BDTBaseAddressSet. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTBaseAddress in your application to determine whether this feature is available. Preconditions None. Example void * pMyBDT; pMyBDT = PLIB_USB_BDTBaseAddressGet(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void * PLIB_USB_BDTBaseAddressGet ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2187 PLIB_USB_BDTBaseAddressSet Function Sets the base address for the Buffer Descriptor Table for PIC32 devices. File plib_usb.h C void PLIB_USB_BDTBaseAddressSet(USB_MODULE_ID index, void* address); Returns None. Description This function sets the base address for the Buffer Descriptor Table. This function is only available on PIC32 devices. Remarks The address of the Buffer Descriptor Table must be 512 byte-aligned. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTBaseAddress in your application to determine whether this feature is available. Preconditions None. Example #if defined(__PIC32MX__) // For PIC32 PLIB_USB_BDTBaseAddressSet(MY_USB_INSTANCE, (void *)((uint32_t)KVA_TO_PA(&myBDT)) ); #else // Everybody else PLIB_USB_BDTBaseAddressSet(MY_USB_INSTANCE, (void *)(&myBDT) ); #endif Parameters Parameters Description index Identifier for the device instance of interest address Physical memory address in RAM of Buffer Descriptor Table Function void PLIB_USB_BDTBaseAddressSet ( USB_MODULE_ID index, void * address ) PLIB_USB_BufferAddressGet Function Gets the memory address of an endpoint buffer. File plib_usb.h C void* PLIB_USB_BufferAddressGet(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns Buffer address in memory. Description This function gets the memory address of an endpoint buffer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2188 Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint Value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function void * PLIB_USB_BufferAddressGet ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferAddressSet Function Sets the endpoint buffer address. File plib_usb.h C void PLIB_USB_BufferAddressSet(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, void* bufferAddress); Returns None. Description This function sets the endpoint buffer address. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD bufferAddress address in memory of endpoint transmit or receive buffer Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2189 Function void PLIB_USB_BufferAddressSet ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, void * bufferAddress ) PLIB_USB_BufferAllCancelReleaseToUSB Function Cancels all endpoint buffer releases to the USB module and hands over the buffer to the CPU. File plib_usb.h C void PLIB_USB_BufferAllCancelReleaseToUSB(USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, int nEndpoints); Returns None. Description This function cancels all endpoint buffer releases to the USB module and hands over the buffer to the CPU. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example //Cancel all buffer releases to USB. //BDT has 3 Endpoints. PLIB_USB_BufferAllCancelReleaseToUSB(MY_USB_INSTANCE, pBDT, USB_PING_PONG_NO_PING_PONG, 3); Parameters Parameters Description index Identifier for the device instance of interest pBDT Pointer to the Buffer Descriptor Table ppMode Buffer Descriptor Table Ping-Pong mode nEndpoints Number of endpoints in the Buffer-Descriptor table Function void PLIB_USB_BufferAllCancelReleaseToUSB(USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, int nEndpoints); PLIB_USB_BufferByteCountGet Function Returns the endpoint buffer byte count. File plib_usb.h Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2190 C uint16_t PLIB_USB_BufferByteCountGet(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns Endpoint buffer byte count. Description This function returns the endpoint buffer byte count, the actual number of bytes transmitted or received. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function uint16_t PLIB_USB_BufferByteCountGet ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferByteCountSet Function Sets the buffer byte count. File plib_usb.h C void PLIB_USB_BufferByteCountSet(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, uint16_t bufferByteCount); Returns None. Description This function sets the number of bytes to be transmitted or the maximum number of bytes to be received. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2191 Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD bufferByteCount number of bytes to be transmitted or the maximum number of bytes to be received Function PLIB_USB_BufferByteCountSet ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, uint16_t bufferByteCount ) PLIB_USB_BufferCancelReleaseToUSB Function Cancels release of the endpoint buffer by software, allowing software to again access the buffer. File plib_usb.h C void PLIB_USB_BufferCancelReleaseToUSB(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns None. Description This function cancels the release of the endpoint buffer by software, allowing software to again access the buffer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function void PLIB_USB_BufferCancelReleaseToUSB ( USB_MODULE_ID index, void * pBDT, Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2192 USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferClearAll Function Clears (zeros out) entries in the Buffer Descriptor Table. File plib_usb.h C void PLIB_USB_BufferClearAll(USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns None. Description This function clears (zeros out) the entries in the Buffer Descriptor Table. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function void PLIB_USB_BufferClearAll( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferClearAllDTSEnable Function Clears the endpoint descriptor entry and enables data toggle synchronization. File plib_usb.h C void PLIB_USB_BufferClearAllDTSEnable(USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection); Returns None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2193 Description This function clears the endpoint descriptor entry and enables data toggle synchronization. Remarks None. Preconditions None. Example //Clear endpoint 6 buffer descriptor transmit entry and //enable data toggle synchronization. PLIB_USB_BufferClearAllDTSEnable ( MY_USB_INSTANCE, pBDT, USB_PING_PONG_NO_PING_PONG, 6, USB_BUFFER_TX); Parameters Parameters Description index Identifier for the device instance of interest pBDT pointer to Buffer Descriptor Table pingpong Ping-Pong mode. epvalue Endpoint to be be affected bufferDirection Endpoint direction Function void PLIB_USB_BufferClearAllDTSEnable( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection); PLIB_USB_BufferDataToggleGet Function Returns data synchronization (DATA0 or DATA1) for the endpoint buffer. File plib_usb.h C USB_BUFFER_DATA01 PLIB_USB_BufferDataToggleGet(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns Data Toggle value, USB_BUFFER_DATA0 or USB_BUFFER_DATA1, for the buffer Description This function returns data synchronization (DATA0 or DATA1) for the endpoint buffer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2194 Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function USB_BUFFER_DATA01 PLIB_USB_BufferDataToggleGet ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferDataToggleSelect Function Sets the endpoint buffer to DATA0 or DATA1. File plib_usb.h C void PLIB_USB_BufferDataToggleSelect(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, USB_BUFFER_DATA01 bufferData01); Returns None. Description This function sets the endpoint buffer to DATA0 or DATA1. Remarks See PLIB_USB_BufferDataToggleGet to determine the received data toggle setting. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD bufferData01 USB_BUFFER_DATA0 or USB_BUFFER_DATA1 Function void PLIB_USB_BufferDataToggleSelect ( USB_MODULE_ID index, void * pBDT, Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2195 USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, USB_BUFFER_DATA01 bufferData01 ) PLIB_USB_BufferDataToggleSyncDisable Function Disables DATA0/DATA1 synchronization between the device and host. File plib_usb.h C void PLIB_USB_BufferDataToggleSyncDisable(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns None. Description This function disables DATA0/DATA1 synchronization between the device and host. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function void PLIB_USB_BufferDataToggleSyncDisable ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferDataToggleSyncEnable Function Enables DATA0/DATA1 synchronization between the device and host. File plib_usb.h C void PLIB_USB_BufferDataToggleSyncEnable(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2196 Returns None. Description This function enables DATA0/DATA1 synchronization between the device and host. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function void PLIB_USB_BufferDataToggleSyncEnable ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferEP0RxStatusInitialize Function Initializes the Endpoint 0 RX endpoint buffer descriptors. File plib_usb.h C void PLIB_USB_BufferEP0RxStatusInitialize(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, USB_BUFFER_PING_PONG pingpong, uint16_t bufferByteCount); Returns None. Description This function initializes the Endpoint 0 RX endpoint buffer descriptors. This function will clear the Endpoint 0 RX Buffer Descriptor status field, load the endpoint size and release the buffer to the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example //Initialize EP0 RX even buffer descriptor and release back to //USB. Buffer size is 64 Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2197 PLIB_USB_BufferEP0RxStatusInitialize ( MY_USB_INSTANCE, pBDT, USB_PING_PONG_NO_PING_PONG, USB_BUFFER_EVEN, 64); Parameters Parameters Description index Identifier for the device instance of interest pBDT Pointer to Buffer Descriptor Table pingpong Ping-Pong mode bufferByteCount size of the EP0 RX buffer in bytes Function void PLIB_USB_BufferEP0RxStatusInitialize ( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, USB_BUFFER_PING_PONG pingpong, uint16_t bufferByteCount ); PLIB_USB_BufferIndexGet Function Gets the Buffer Descriptor Table index for a buffer. File plib_usb.h C uint8_t PLIB_USB_BufferIndexGet(USB_MODULE_ID index, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns Buffer index into the Buffer Descriptor Table. Description This function gets the Buffer Descriptor Table index for a buffer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function uint8_t PLIB_USB_BufferIndexGet ( USB_MODULE_ID index, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2198 PLIB_USB_BufferPIDBitsClear Function Clears the Buffer Status bits in the Buffer Descriptor Table. File plib_usb.h C void PLIB_USB_BufferPIDBitsClear(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns None. Description This function clears the Buffer Status bits in the Buffer Descriptor Table. Remarks Call PLIB_USB_BufferPIDBitsClear before setting buffer control bits. This is equivalent to: PLIB_USB_BufferCancelReleaseToUSB(...) PLIB_USB_BufferDataToggleSelect( ...,USB_BUFFER_DATA0) PLIB_USB_BufferDataToggleSyncDisable(...) PLIB_USB_BufferStallDisable(...) This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions The associated buffer must have been released by the USB module (i.e., PLIB_USB_BufferReleasedToSW returns 'true'. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function void PLIB_USB_BufferPIDBitsClear ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferPIDGet Function Returns the token packet ID (PID) from the endpoint buffer status. File plib_usb.h C uint8_t PLIB_USB_BufferPIDGet(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns Endpoint buffer packet ID (PID). Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2199 Description This function returns the token packet ID (PID) from the endpoint buffer status. Remarks There is no equivalent "Set" routine, since this field is read-only in the buffer status register within the Buffer Descriptor Table. It is set when the buffer has been transmitted or received by the USB module and the usbOwnsBuffer field has been cleared by the USB module, releasing the buffer for software access. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function uint8_t PLIB_USB_BufferPIDGet ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferReleasedToSW Function Returns the boolean flag value of 'true' when the buffer has been released by the USB module. File plib_usb.h C bool PLIB_USB_BufferReleasedToSW(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns • true - The buffer has been released by hardware • false - The buffer is still controlled by hardware Description This function returns the boolean flag value of 'true' when the buffer has been released by the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2200 Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function bool PLIB_USB_BufferReleasedToSW ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferReleaseToUSB Function Releases the endpoint buffer by software, allowing the USB module access to the buffer. File plib_usb.h C void PLIB_USB_BufferReleaseToUSB(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns None. Description This function releases the endpoint buffer by software, allowing the USB module access to buffer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function void PLIB_USB_BufferReleaseToUSB ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2201 USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferSchedule Function Hands over a buffer to the USB module along with the buffer address and byte count. File plib_usb.h C void PLIB_USB_BufferSchedule(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, void * bufferAddress, int16_t bufferByteCount, USB_BUFFER_SCHEDULE_DATA01 bufferData01); Returns None. Description This function sets the endpoint descriptor buffer address, sets the send/receive byte count, and then hands over the buffer to the USB module. Remarks This function does the work of three other functions: PLIB_USB_BufferAddressSet, PLIB_USB_BufferByteCountSet, PLIB_USB_BufferReleaseToUSB This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD bufferAddress Address of the application buffer bufferByteCount Send or expected receive byte count bufferData01 USB_BUFFER_SET_DATA0, USB_BUFFER_SET_DATA1, or USB_BUFFER_DONTCHANGE (The last choice leaves the existing DATA0/1 value of the buffer alone.) Function void PLIB_USB_BufferSchedule( USB_MODULE_ID index , void* pBDT , USB_PING_PONG_MODE ppMode , uint8_t epValue , USB_BUFFER_DIRECTION bufferDirection , USB_BUFFER_PING_PONG bufferPingPong , void * bufferAddress , int16_t bufferByteCount , USB_BUFFER_SCHEDULE_DATA01 bufferData01 ) PLIB_USB_BufferStallDisable Function Disables STALL handshaking for the associated endpoint buffer. File plib_usb.h Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2202 C void PLIB_USB_BufferStallDisable(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns None. Description This function disables STALL handshaking for the associated endpoint buffer. Remarks Release of a STALL handshake for the buffer is done by hardware when the host sends a SETUP token to the associated endpoint or resets the USB module This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. . Preconditions The associated buffer must have been released by the USB module (i.e., PLIB_USB_BufferReleasedToSW returns 'true'). Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function void PLIB_USB_BufferStallDisable ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferStallEnable Function Enables STALL handshaking for the associated endpoint buffer. File plib_usb.h C void PLIB_USB_BufferStallEnable(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns None. Description This function enables STALL handshaking for the associated endpoint buffer. Remarks Release of a STALL handshake for the buffer is done by hardware when the host sends a SETUP token to the associated endpoint or resets the USB module. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions The associated buffer must have been released by the USB module (i.e. PLIB_USB_BufferReleasedToSW returns 'true'). Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2203 Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function void PLIB_USB_BufferStallEnable ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) PLIB_USB_BufferStallGet Function Returns the buffer stall status for an endpoint/direction/ping-pong. File plib_usb.h C bool PLIB_USB_BufferStallGet(USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong); Returns • true - Buffer stall is enabled • false - Buffer stall is not enabled Description This function returns the buffer stall status for an endpoint/direction/ping-pong. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Preconditions the associated buffer must have been released by the USB module (i.e., PLIB_USB_BufferReleasedToSW returns 'true'). Example Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Function bool PLIB_USB_BufferStallGet ( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2204 uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ) c) Endpoints Functions PLIB_USB_EP0HostSetup Function Sends token to the specified address. File plib_usb.h C void PLIB_USB_EP0HostSetup(USB_MODULE_ID index); Returns None. Description This function configures endpoint 0 for typical host operation. Control transfers are enable. Transmit and Receive is enabled. Handshaking is enabled. Low Speed connection is disabled. NAK retry is disabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Preconditions None. Example // Configure endpoint 0 for host operation PLBIB_USB_EP0HostSetup(USB_MODULE_ID index); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_EP0HostSetup(USB_MODULE_ID index); PLIB_USB_EP0LSDirectConnectDisable Function Disables direct connection to a low-speed device for Endpoint 0. File plib_usb.h C void PLIB_USB_EP0LSDirectConnectDisable(USB_MODULE_ID index); Returns None. Description This function disables direct connection to a low-speed device for Endpoint 0. Remarks Host mode and U1EP0 only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEP0LowSpeedConnect in your application to determine whether this feature is available. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2205 Preconditions The USB module must be in Host mode. Example PLIB_USB_EP0LSDirectConnectDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_EP0LSDirectConnectDisable ( USB_MODULE_ID index ) PLIB_USB_EP0LSDirectConnectEnable Function Enables direct connection to a low-speed device for Endpoint 0. File plib_usb.h C void PLIB_USB_EP0LSDirectConnectEnable(USB_MODULE_ID index); Returns None. Description This function enables direct connection to a low-speed device for Endpoint 0. Remarks Host Mode and U1EP0 only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEP0LowSpeedConnect in your application to determine whether this feature is available. Preconditions USB module must be in Host mode. Example PLIB_USB_EP0LSDirectConnectEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_EP0LSDirectConnectEnable ( USB_MODULE_ID index ) PLIB_USB_EP0NakRetryDisable Function Disables retrying of NAKed transactions. File plib_usb.h C void PLIB_USB_EP0NakRetryDisable(USB_MODULE_ID index); Returns None. Description This function disables retrying of NAKed transactions. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2206 Remarks Host/OTG only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEP0NAKRetry in your application to determine whether this feature is available. Preconditions The USB module must be in Host or OTG modes. Example PLIB_USB_EP0NakRetryDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_EP0NakRetryDisable ( USB_MODULE_ID index ) PLIB_USB_EP0NakRetryEnable Function Enables retrying NAK'd transactions for Endpoint 0. File plib_usb.h C void PLIB_USB_EP0NakRetryEnable(USB_MODULE_ID index); Returns None. Description This function enables retrying NAK'd transactions for Endpoint 0. Remarks Host/OTG only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEP0NAKRetry in your application to determine whether this feature is available. Preconditions The USB module must be in Host or OTG modes. Example PLIB_USB_EP0NakRetryEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_EP0NakRetryEnable ( USB_MODULE_ID index ) PLIB_USB_EPnAttributesClear Function Clears the set attributes of the specified endpoint. File plib_usb.h C void PLIB_USB_EPnAttributesClear(USB_MODULE_ID index, uint8_t epValue); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2207 Returns None. Description Clears the set attributes of the specified endpoint. The endpoint transmit receive, handshake and setup packet handling capability is disabled. Remarks None. Preconditions None. Example // This clears up the endpoint 0 attributes and thus disables // the endpoints PLIB_USB_EPnAttributesClear(MY_USB_INSTANCE, 0); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Function void PLIB_USB_EPnAttributesClear ( USB_MODULE_ID index, uint8_t epValue) PLIB_USB_EPnAttributesSet Function Configures attributes of the endpoint such as direction, handshake capability and direction. File plib_usb.h C void PLIB_USB_EPnAttributesSet(USB_MODULE_ID index, uint8_t epValue, int direction, bool isControl, bool handshake); Returns None. Description Configures attributes of the endpoint such as direction, handshake capability and direction. If the isControl flag is true, then the direction and handshake parameters are ignored and the endpoint is configured for control transfers. Remarks None. Preconditions None. Example // This enables endpoint 0 for control transfers. PLIB_USB_EPnAttributesSet(MY_USB_INSTANCE, 0, 0, true, true); // This enables endpoint 2 for non control transfer, direction // is RX and handshake enable. PLIB_USB_EPnAttributesSet(MY_USB_INSTANCE, 2, 1, false, true); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint direction Endpoint direction, if 1 then RX and if 0 then TX. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2208 isControl If true endpoint is configured for control transfers. handshake If true, then handshake is enabled on the endpoint else it is disabled. Function void PLIB_USB_EPnAttributesSet ( USB_MODULE_ID index, uint8_t epValue, int direction, bool isControl, bool handshake) PLIB_USB_EPnControlTransferDisable Function Disables endpoint control transfers. File plib_usb.h C void PLIB_USB_EPnControlTransferDisable(USB_MODULE_ID index, uint8_t epValue); Returns None. Description This function disables endpoint control transfers when endpoint transmit and endpoint receive are both enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_EPnControlTransferDisable(MY_USB_INSTANCE, someEP); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Function void PLIB_USB_EPnControlTransferDisable ( USB_MODULE_ID index, uint8_t epValue ) PLIB_USB_EPnControlTransferEnable Function Enables endpoint control transfers. File plib_usb.h C void PLIB_USB_EPnControlTransferEnable(USB_MODULE_ID index, uint8_t epValue); Returns None. Description This function enables endpoint control transfers when endpoint transmit and endpoint receive are both enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2209 Preconditions None. Example PLIB_USB_EPnControlTransferEnable(MY_USB_INSTANCE, someEP); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Function void PLIB_USB_EPnControlTransferEnable ( USB_MODULE_ID index, uint8_t epValue ) PLIB_USB_EPnDirectionDisable Function Disables the specified endpoint direction. File plib_usb.h C void PLIB_USB_EPnDirectionDisable(USB_MODULE_ID index, uint8_t epValue, int direction); Returns None. Description Disables the specified endpoint direction. Remarks None. Preconditions None. Example // This function disables the TX direction of endpoint 1 PLIB_USB_EPnDirectionDisable(MY_USB_INSTANCE, 1, 1); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint direction If 1, then TX direction is disabled. If 0 RX direction is disabled. Function void PLIB_USB_EPnDirectionDisable ( USB_MODULE_ID index, uint8_t epValue, int direction) PLIB_USB_EPnHandshakeDisable Function Disables endpoint handshaking. File plib_usb.h C void PLIB_USB_EPnHandshakeDisable(USB_MODULE_ID index, uint8_t epValue); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2210 Returns None. Description This function disables endpoint handshaking. Typically used for Isochronous endpoints. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_EPnHandshakeDisable(MY_USB_INSTANCE, someEP); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Function void PLIB_USB_EPnHandshakeDisable ( USB_MODULE_ID index, uint8_t epValue ) PLIB_USB_EPnHandshakeEnable Function Enables endpoint handshaking. File plib_usb.h C void PLIB_USB_EPnHandshakeEnable(USB_MODULE_ID index, uint8_t epValue); Returns None. Description This function enables endpoint handshaking. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_EPnHandshakeEnable(MY_USB_INSTANCE, someEP); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Function void PLIB_USB_EPnHandshakeEnable ( USB_MODULE_ID index, uint8_t epValue ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2211 PLIB_USB_EPnIsStalled Function Tests whether the endpoint epValue is stalled. File plib_usb.h C bool PLIB_USB_EPnIsStalled(USB_MODULE_ID index, uint8_t epValue); Returns • true - The endpoint is stalled • false - The endpoint is not stalled Description This function tests whether the endpoint epValue is stalled. Remarks Not valid before an endpoint is enabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example if( PLIB_USB_EPnIsStalled(MY_USB_INSTANCE, someEP) ) { // Handle the stall } Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Function bool PLIB_USB_EPnIsStalled ( USB_MODULE_ID index, uint8_t epValue ) PLIB_USB_EPnRxDisable Function Disables an endpoint's ability to process IN tokens. File plib_usb.h C void PLIB_USB_EPnRxDisable(USB_MODULE_ID index, uint8_t endpoint); Returns None. Description This function disables an endpoint's ability to process IN tokens. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2212 Example //De-provision endpoint 3 to process IN Token PLIB_USB_EPnRxDisable(MY_USB_INSTANCE, 3); Parameters Parameters Description index Identifier for the device instance of interest endpoint Endpoint to be affected Function void PLIB_USB_EPnRxDisable(USB_MODULE_ID index, uint8_t endpoint); PLIB_USB_EPnRxEnable Function Enables an endpoint to process IN tokens. File plib_usb.h C void PLIB_USB_EPnRxEnable(USB_MODULE_ID index, uint8_t endpoint); Returns None. Description This function enables an endpoint to process IN tokens. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example //Provision endpoint 3 to process IN Token PLIB_USB_EPnRxEnable(MY_USB_INSTANCE, 3); Parameters Parameters Description index Identifier for the device instance of interest endpoint Endpoint to be affected Function void PLIB_USB_EPnRxEnable(USB_MODULE_ID index, uint8_t endpoint); PLIB_USB_EPnRxSelect Function Selects receive capabilities of an endpoint. File plib_usb.h C void PLIB_USB_EPnRxSelect(USB_MODULE_ID index, uint8_t epValue, USB_EP_TXRX epTxRx); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2213 Returns None. Description This function selects receive capabilities of an endpoint. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_EPnRxSelect(MY_USB_INSTANCE, someEP, USB_EP_RX); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint epTxRx Transmit/Receive setting for endpoint: USB_EP_RX, USB_EP_NOTXRX Function void PLIB_USB_EPnRxSelect ( USB_MODULE_ID index, uint8_t epValue, USB_EP_TXRX epTxRx ) PLIB_USB_EPnStallClear Function Clears an endpoint's stalled flag. File plib_usb.h C void PLIB_USB_EPnStallClear(USB_MODULE_ID index, uint8_t epValue); Returns None. Description This function clears an endpoint's stalled flag. Remarks Not valid before an endpoint is enabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example if( PLIB_USB_EPnIsStalled(MY_USB_INSTANCE, someEP) ) { // Handle the stall PLIB_USB_EPnStallClear(MY_USB_INSTANCE, someEP); } Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2214 Function void PLIB_USB_EPnStallClear ( USB_MODULE_ID index, uint8_t epValue ) PLIB_USB_EPnTxDisable Function Disables an endpoint's ability to process OUT tokens. File plib_usb.h C void PLIB_USB_EPnTxDisable(USB_MODULE_ID index, uint8_t endpoint); Returns None. Description This function disables an endpoint's ability to process OUT tokens. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example //De-provision endpoint 3 to process OUT Token PLIB_USB_EPnTxDisable(MY_USB_INSTANCE, 3); Parameters Parameters Description index Identifier for the device instance of interest endpoint Endpoint to be affected Function void PLIB_USB_EPnTxDisable(USB_MODULE_ID index, uint8_t endpoint); PLIB_USB_EPnTxEnable Function Enables an endpoint to process OUT tokens. File plib_usb.h C void PLIB_USB_EPnTxEnable(USB_MODULE_ID index, uint8_t endpoint); Returns None. Description This function enables an endpoint to process OUT tokens. Remarks None. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2215 Example //Provision endpoint 3 to process OUT Token PLIB_USB_EPnTxEnable(MY_USB_INSTANCE, 3); Parameters Parameters Description index Identifier for the device instance of interest endpoint Endpoint to be affected Function void PLIB_USB_EPnTxEnable(USB_MODULE_ID index, uint8_t endpoint); PLIB_USB_EPnTxRxSelect Function Selects transmit and/or receive capabilities of an endpoint. File plib_usb.h C void PLIB_USB_EPnTxRxSelect(USB_MODULE_ID index, uint8_t epValue, USB_EP_TXRX epTxRx); Returns None. Description This function selects transmit and/or receive capabilities of an endpoint. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_EPnTxRxSelect(MY_USB_INSTANCE, someEP, USB_EP_TXRX); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint epTxRx Transmit/Receive setting for endpoint: USB_EP_TX, USB_EP_RX, USB_EP_TX_RX, USB_EP_NOTXRX Function void PLIB_USB_EPnTxRxSelect ( USB_MODULE_ID index, uint8_t epValue, USB_EP_TXRX epTxRx ) PLIB_USB_EPnTxSelect Function Selects transmit capabilities of an endpoint. File plib_usb.h C void PLIB_USB_EPnTxSelect(USB_MODULE_ID index, uint8_t epValue, USB_EP_TXRX epTxRx); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2216 Returns None. Description This function selects transmit capabilities of an endpoint. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_EPnTxSelect(MY_USB_INSTANCE, someEP, USB_EP_TX); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint epTxRx Transmit/Receive setting for endpoint: USB_EP_TX, USB_EP_NOTXRX Function void PLIB_USB_EPnTxSelect ( USB_MODULE_ID index, uint8_t epValue, USB_EP_TXRX epTxRx ) d) Interrupts Functions PLIB_USB_InterruptDisable Function Disables a general interrupt for the USB module. File plib_usb.h C void PLIB_USB_InterruptDisable(USB_MODULE_ID index, USB_INTERRUPTS interruptFlag); Returns None. Description This function disables a general interrupt source for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_InterruptDisable( MY_USB_INSTANCE, USB_INT_ERROR ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2217 Function void PLIB_USB_InterruptDisable( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ) PLIB_USB_InterruptEnable Function Enables a general interrupt for the USB module. File plib_usb.h C void PLIB_USB_InterruptEnable(USB_MODULE_ID index, USB_INTERRUPTS interruptFlag); Returns None. Description This function enables general interrupt sources of the USB module to trigger a USB interrupt. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_InterruptEnable( MY_USB_INSTANCE, USB_INT_ERROR ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USB_InterruptEnable( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ) PLIB_USB_InterruptEnableGet Function Returns the enable/disable status of general USB module interrupts File plib_usb.h C USB_INTERRUPTS PLIB_USB_InterruptEnableGet(USB_MODULE_ID index); Returns A bit map containing status of enabled interrupts. Description Returns the enable/disable status of general USB module interrupts Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2218 Example USB_INTERRUPTS enabledInterrupts; enabledInterrupts = PLIB_USB_InterruptEnableGet( MY_USB_INSTANCE); if(enabledInterrupts|USB_INT_ATTACH) { // This means Attach interrupt is enabled. } Parameters Parameters Description index Identifier for the device instance of interest Function USB_INTERRUPTS PLIB_USB_InterruptEnableGet( USB_MODULE_ID index) PLIB_USB_InterruptFlagAllGet Function Returns a logically ORed bit map of active general USB interrupt flags. File plib_usb.h C USB_INTERRUPTS PLIB_USB_InterruptFlagAllGet(USB_MODULE_ID index); Returns Returns a logically ORed bit map of active general USB interrupt flags. Description This function returns a logically ORed bit map of active general USB interrupt flags. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example USB_INTERRUPTS interruptEnables; interruptEnables = PLIB_USB_InterruptFlagAllGet(MY_USB_INSTANCE); if(interruptEnables | USB_INT_DEVICE_RESET) { // Device received reset signaling } Parameters Parameters Description index Identifier for the device instance of interest Function USB_INTERRUPTS PLIB_USB_InterruptFlagAllGet(USB_MODULE_ID index); PLIB_USB_InterruptFlagClear Function Clears a general interrupt flag for the USB module. File plib_usb.h Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2219 C void PLIB_USB_InterruptFlagClear(USB_MODULE_ID index, USB_INTERRUPTS interruptFlag); Returns None. Description This function clears a general interrupt source flag for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_InterruptFlagClear( MY_USB_INSTANCE, USB_INT_ERROR ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USB_InterruptFlagClear( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ) PLIB_USB_InterruptFlagGet Function Tests a general interrupt flag for the USB module. File plib_usb.h C bool PLIB_USB_InterruptFlagGet(USB_MODULE_ID index, USB_INTERRUPTS interruptFlag); Returns None. Description This function tests a general interrupt source flag for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example if ( PLIB_USB_InterruptFlagGet(MY_USB_INSTANCE,USB_INT_ANY) ) if ( PLIB_USB_InterruptFlagGet(MY_USB_INSTANCE,USB_INT_ERROR) ) { PLIB_USB_InterruptFlagClear(MY_USB_INSTANCE,USB_INT_ERROR); // Error clean up } if ( PLIB_USB_InterruptFlagGet(MY_USB_INSTANCE,USB_INT_HOST_DETACH) ) { PLIB_USB_InterruptFlagClear(MY_USB_INSTANCE,USB_INT_HOST_DETACH); // Device detached clean up } Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2220 . . . } Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function bool PLIB_USB_InterruptFlagGet( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ) PLIB_USB_InterruptFlagSet Function Sets a general interrupt flag for the USB module. File plib_usb.h C void PLIB_USB_InterruptFlagSet(USB_MODULE_ID index, USB_INTERRUPTS interruptFlag); Returns None. Description This function sets a general interrupt source flag for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_InterruptFlagSet( MY_USB_INSTANCE, USB_INT_ERROR ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USB_InterruptFlagSet( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ) PLIB_USB_InterruptIsEnabled Function Returns true if interrupts are enabled. File plib_usb.h C bool PLIB_USB_InterruptIsEnabled(USB_MODULE_ID index, USB_INTERRUPTS interruptFlag); Returns • true - Interrupts are enabled • false - Interrupts are not enabled Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2221 Description This function returns true if interrupts are enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Preconditions None. Example if ( PLIB_USB_InterruptIsEnabled( MY_USB_INSTANCE, USB_INT_ERROR ) ) { } Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function bool PLIB_USB_InterruptIsEnabled( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ) e) Error Interrupts Functions PLIB_USB_ErrorInterruptDisable Function Disables an error interrupt for the USB module. File plib_usb.h C void PLIB_USB_ErrorInterruptDisable(USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag); Returns None. Description This function disables an error interrupt source for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_Interrupt in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_ErrorInterruptDisable( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USB_ErrorInterruptDisable( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2222 PLIB_USB_ErrorInterruptEnable Function Enables an error interrupt for the USB module. File plib_usb.h C void PLIB_USB_ErrorInterruptEnable(USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag); Returns None. Description This function enables error interrupt sources of the USB module to trigger a USB interrupt. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_Interrupt in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_ErrorInterruptEnable( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USB_ErrorInterruptEnable( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ) PLIB_USB_ErrorInterruptFlagAllGet Function Returns a logically ORed bit map of active error interrupt flags. File plib_usb.h C USB_ERROR_INTERRUPTS PLIB_USB_ErrorInterruptFlagAllGet(USB_MODULE_ID index); Returns Returns a logically ORed bit map of active error interrupt flags. Description This function returns a logically ORed bit map of active error interrupt flags. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example USB_ERROR_INTERRUPTS errorInterruptEnables; errorInterruptEnables = PLIB_USB_ErrorInterruptFlagAllGet(MY_USB_INSTANCE); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2223 if(errorInterruptEnables | USB_ERR_INT_DEVICE_EOF_ERROR) { // End of frame error occurred. } Parameters Parameters Description index Identifier for the device instance of interest Function USB_ERROR_INTERRUPTS PLIB_USB_ErrorInterruptFlagAllGet(USB_MODULE_ID index); PLIB_USB_ErrorInterruptFlagClear Function Clears an error interrupt flag for the USB module. File plib_usb.h C void PLIB_USB_ErrorInterruptFlagClear(USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag); Returns None. Description This function clears an error interrupt source flag for the USB module. Remarks None. Preconditions None. Example PLIB_USB_ErrorInterruptFlagClear( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USB_ErrorInterruptFlagClear( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ) PLIB_USB_ErrorInterruptFlagGet Function Tests an error interrupt flag for the USB module. File plib_usb.h C bool PLIB_USB_ErrorInterruptFlagGet(USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag); Returns None. Description This function tests an error interrupt source flag for the USB module. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2224 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example if ( PLIB_USB_ErrorInterruptFlagGet(MY_USB_INSTANCE,USB_ERR_INT_ANY) ) if ( PLIB_USB_ErrorInterruptFlagGet(MY_USB_INSTANCE,USB_ERR_INT_PID_CHECK_FAILURE) ) { PLIB_USB_ErrorInterruptFlagClear(MY_USB_INSTANCE,USB_ERR_INT_PID_CHECK_FAILURE); // PID Error Check failure cleanup } if ( PLIB_USB_ErrorInterruptFlagGet(MY_USB_INSTANCE,USB_ERR_INT_DEVICE_EOF_ERROR) ) { PLIB_USB_ErrorInterruptFlagClear(MY_USB_INSTANCE,USB_ERR_INT_DEVICE_EOF_ERROR); // EOF error cleanup } . . . } Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function bool PLIB_USB_ErrorInterruptFlagGet( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ) PLIB_USB_ErrorInterruptFlagSet Function Sets an error interrupt flag for the USB module. File plib_usb.h C void PLIB_USB_ErrorInterruptFlagSet(USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag); Returns None. Description This function sets an error interrupt source flag for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_ErrorInterruptFlagSet( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2225 Function void PLIB_USB_ErrorInterruptFlagSet( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ) PLIB_USB_ErrorInterruptIsEnabled Function Returns true if interrupts are enabled. File plib_usb.h C bool PLIB_USB_ErrorInterruptIsEnabled(USB_MODULE_ID index, USB_INTERRUPTS interruptFlag); Returns • true - Interrupts are enabled • false - Interrupts are not enabled Description This function determines whether interrupts are enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example if ( PLIB_USB_ErrorInterruptIsEnabled( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ) ) { } Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function bool PLIB_USB_ErrorInterruptIsEnabled( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ) f) Last Transaction Status Functions PLIB_USB_LastTransactionDetailsGet Function Returns the details of the last completed transaction. File plib_usb.h C void PLIB_USB_LastTransactionDetailsGet(USB_MODULE_ID index, USB_BUFFER_DIRECTION * direction, USB_PING_PONG_STATE * pingpong, uint8_t * endpoint); Returns None. Description This function returns the details of the last completed transaction. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2226 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLastTransactionDetails in your application to determine whether this feature is available. Preconditions None. Example USB_BUFFER_DIRECTION direction; USB_PING_PONG_STATE pingpong; uint8_t endpoint; interruptEnables = PLIB_USB_InterruptFlagAllGet(MY_USB_INSTANCE); if(interruptEnables | USB_INT_TOKEN_DONE) { // Find out details of the token PLIB_USB_LastTransactionDetailsGet(MY_USB_INSTANCE, &direction, &pingpong, &endpoint); } Parameters Parameters Description index Identifier for the device instance of interest direction Return value contains direction of the last transfer pingpong Return value contains Ping-Pong indication of the the last transfer endpoint Return value contains the endpoint which processed the last transfer Function void PLIB_USB_LastTransactionDetailsGet(USB_MODULE_ID index, USB_BUFFER_DIRECTION * direction, USB_PING_PONG_STATE * pingpong, uint8_t * endpoint); PLIB_USB_LastTransactionDirectionGet Function Indicates the direction of the last transaction. File plib_usb.h C USB_BUFFER_DIRECTION PLIB_USB_LastTransactionDirectionGet(USB_MODULE_ID index); Returns USB_LastDirection: USB_RECEIVE_TRANSFER or USB_TRANSMIT_TRANSFER Description This function indicates the direction of the last transaction, either transmit or receive. Remarks None. Preconditions None. Example See PLIB_USB_LastTransactionEndPtGet. Parameters Parameters Description index Identifier for the device instance of interest Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2227 Function USB_BUFFER_DIRECTION PLIB_USB_LastTransactionDirectionGet ( USB_MODULE_ID index ) PLIB_USB_LastTransactionEndPtGet Function Returns the endpoint number of the last USB transfer. File plib_usb.h C uint8_t PLIB_USB_LastTransactionEndPtGet(USB_MODULE_ID index); Returns endPoint - Endpoint of last completed USB transfer Description This function returns the endpoint number of the last USB transfer, which is actually the index into the Buffer Descriptor Table of the last USB transfer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLastDirection in your application to determine whether this feature is available. Preconditions None. Example while ( !PLIB_USB_INT_FlagGet(MY_USB_INSTANCE,USB_INT_GEN,TOKEN_DONE) ) { // Do nothing, wait until completion of next transaction } // Retrieve information relating to the last completed transaction endpoint = PLIB_USB_LastTransactionEndPtGet(MY_USB_INSTANCE); direction = PLIB_USB_LastTransactionDirectionGet(MY_USB_INSTANCE); pingPongState = PLIB_USB_LastTransactionPingPongStateGet(MY_USB_INSTANCE); // Clearing the Token Processing Done flag advances the status FIFO to // oldest transaction in the FIFO. Wait for completion of next transaction // before using PLIB_USB_Last*Get functions again to read status. PLIB_USB_INT_FlagClear(MY_USB_INSTANCE,USB_INT_GEN,TOKEN_DONE); Parameters Parameters Description index Identifier for the device instance of interest Function uint8_t PLIB_USB_LastTransactionEndPtGet ( USB_MODULE_ID index ) PLIB_USB_LastTransactionPingPongStateGet Function Indicates whether the last transaction was to an EVEN buffer or an ODD buffer. File plib_usb.h C USB_PING_PONG_STATE PLIB_USB_LastTransactionPingPongStateGet(USB_MODULE_ID index); Returns USB_PING_PONG_STATE. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2228 Description This function indicates whether the last transaction was to an Even buffer or an Odd buffer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLastPingPong in your application to determine whether this feature is available. Preconditions None. Example See PLIB_USB_LastTransactionEndPtGet. Parameters Parameters Description index Identifier for the device instance of interest Function USB_PING_PONG_STATE PLIB_USB_LastTransactionPingPongStateGet ( USB_MODULE_ID index ) g) Host Functions PLIB_USB_IsBusyWithToken Function Indicates whether there is a token being executed by the USB module as Host. File plib_usb.h C bool PLIB_USB_IsBusyWithToken(USB_MODULE_ID index); Returns None. Description This function indicates whether there is a token being executed by the USB module as Host. Software should check that the previous token is finished before issuing a new token. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsHostBusyWithToken in your application to determine whether this feature is available. Preconditions USB module must be in Host mode. Example while( PLIB_USB_IsBusyWithToken(MY_USB_INSTANCE) ) { // do nothing } // Issue new token Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_IsBusyWithToken ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2229 PLIB_USB_SOFDisable Function Disables the automatic generation of the SOF token. File plib_usb.h C void PLIB_USB_SOFDisable(USB_MODULE_ID index); Returns None. Description This function disables the automatic generation of the SOF token. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsStartOfFrames in your application to determine whether this feature is available. Preconditions USB module must be in Host mode. Example PLIB_USB_SOFDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_SOFDisable ( USB_MODULE_ID index ) PLIB_USB_SOFEnable Function Enables the automatic generation of the SOF token every 1 ms. File plib_usb.h C void PLIB_USB_SOFEnable(USB_MODULE_ID index); Returns None. Description This function enables the automatic generation of the SOF token every 1 ms. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsStartOfFrames in your application to determine whether this feature is available. Preconditions USB module must be in Host mode. Example PLIB_USB_SOFEnable(MY_USB_INSTANCE); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2230 Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_SOFEnable ( USB_MODULE_ID index ) PLIB_USB_SOFThresholdGet Function Returns the Start-of-Frame (SOF) Count bits. File plib_usb.h C uint8_t PLIB_USB_SOFThresholdGet(USB_MODULE_ID index); Returns SOF threshold value. Description This function returns the Start-of-Frame (SOF) Count bits. (Value represents 10 + (packet size of n bytes);). Remarks Host mode only. SOF Threshold Value = packet byte count + 10 = 0b0100_1010 = 0x4A = 74 for 64-byte packet = 0b0010_1010 = 0x2A = 42 for 32-byte packet = 0b0001_1010 = 0x1A = 26 for 16-byte packet = 0x0001_0010 = 0x12 = 18 for 8-byte packet This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSOFThreshold in your application to determine whether this feature is available. Preconditions The USB module must be in Host mode. Example thresholdSOF = PLIB_USB_SOFThresholdGet(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function uint8_t PLIB_USB_SOFThresholdGet ( USB_MODULE_ID index ) PLIB_USB_SOFThresholdSet Function Sets the Start-of-Frame (SOF) threshold value. File plib_usb.h C void PLIB_USB_SOFThresholdSet(USB_MODULE_ID index, uint8_t threshold); Returns None. Description This function sets the Start-of-Frame (SOF) threshold value. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2231 Remarks Host mode only. SOF Threshold Value = packet byte count + 10 = 0b0100_1010 = 0x4A = 74 for 64-byte packet = 0b0010_1010 = 0x2A = 42 for 32-byte packet = 0b0001_1010 = 0x1A = 26 for 16-byte packet = 0x0001_0010 = 0x12 = 18 for 8-byte packet This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSOFThreshold in your application to determine whether this feature is available. Preconditions The USB module must be in Host mode. Example // Set SOF threshold for 64-byte packets PLIB_USB_SOFThresholdSet(MY_USB_INSTANCE,64+10); Parameters Parameters Description index Identifier for the device instance of interest threshold SOF threshold Function void PLIB_USB_SOFThresholdSet ( USB_MODULE_ID index, uint8_t threshold ) PLIB_USB_TokenEPGet Function Returns the specified Endpoint address. File plib_usb.h C uint8_t PLIB_USB_TokenEPGet(USB_MODULE_ID index); Returns Endpoint value - 0 <= epValue <= Module Maximum Endpoint. Description This function returns the address of the specified Endpoint. Remarks Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsTokenEP in your application to determine whether this feature is available. Preconditions The USB module must be in Host mode. Example someEP = PLIB_USB_TokenEPGet(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function uint8_t PLIB_USB_TokenEPGet ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2232 PLIB_USB_TokenEPSet Function Sets the Endpoint address for a host transaction. File plib_usb.h C void PLIB_USB_TokenEPSet(USB_MODULE_ID index, uint8_t epValue); Returns None. Description This function sets the Endpoint address for a host transaction. Remarks Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsTokenEP in your application to determine whether this feature is available. Preconditions The USB module must be in Host mode. Example uint8_t someEP = 0x03; PLIB_USB_TokenEPSet(MY_USB_INSTANCE, someEP); Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Function void PLIB_USB_TokenEPSet ( USB_MODULE_ID index, uint8_t epValue ) PLIB_USB_TokenPIDGet Function Returns the token transaction type. File plib_usb.h C USB_PID PLIB_USB_TokenPIDGet(USB_MODULE_ID index); Returns Packet ID of token, USB_PID_SETUP, USB_PID_IN, or USB_PID_OUT Description This function returns the token transaction type. Remarks Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsTokenPID in your application to determine whether this feature is available. Preconditions The USB module must be in Host mode. Example somePID = PLIB_USB_TokenPIDGet(MY_USB_INSTANCE); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2233 Parameters Parameters Description index Identifier for the device instance of interest Function USB_PID PLIB_USB_TokenPIDGet ( USB_MODULE_ID index ) PLIB_USB_TokenPIDSet Function Sets the token transaction type to pidValue. File plib_usb.h C void PLIB_USB_TokenPIDSet(USB_MODULE_ID index, USB_PID pidValue); Returns None. Description This function sets the token transaction type to pidValue. Remarks Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsTokenPID in your application to determine whether this feature is available. Preconditions The USB module must be in Host mode. Example somePID = USB_PID_SETUP; PLIB_USB_TokenPIDSet (MY_USB_INSTANCE, somePID ); Parameters Parameters Description index Identifier for the device instance of interest pidValue USB_PID_SETUP, USB_PID_IN, or USB_PID_OUT Function void PLIB_USB_TokenPIDSet ( USB_MODULE_ID index, USB_PID pidValue) PLIB_USB_TokenSpeedSelect Function Selects low speed or full speed for subsequent token executions. File plib_usb.h C void PLIB_USB_TokenSpeedSelect(USB_MODULE_ID index, USB_TOKEN_SPEED tokenSpeed); Returns None. Description This function selects low speed or full speed for subsequent token executions. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsNextTokenSpeed in your application to determine whether this feature is available. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2234 Preconditions The USB module must be in Host mode. Example PLIB_USB_TokenSpeedSet(MY_USB_INSTANCE,USB_LOWSPEED_TOKENS); Parameters Parameters Description index Identifier for the device instance of interest tokenSpeed Speed for next token execution: USB_LOWSPEED_TOKENS or USB_FULLSPEED_TOKENS Function void PLIB_USB_TokenSpeedSelect ( USB_MODULE_ID index, USB_TOKEN_SPEED tokenSpeed ) h) USB Bus Signaling Functions PLIB_USB_ResetSignalDisable Function Disables reset signaling on the USB bus. File plib_usb.h C void PLIB_USB_ResetSignalDisable(USB_MODULE_ID index); Returns None. Description This function disables reset signaling on the USB bus. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsHostGeneratesReset in your application to determine whether this feature is available. Preconditions The USB module must be in Host mode. Example See PLIB_USB_ResetSignalEnable. Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_ResetSignalDisable ( USB_MODULE_ID index ) PLIB_USB_ResetSignalEnable Function Enables reset signaling on the USB bus. File plib_usb.h C void PLIB_USB_ResetSignalEnable(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2235 Returns None. Description This function enables reset signaling on the USB bus. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsHostGeneratesReset in your application to determine whether this feature is available. Preconditions The USB module must be in Host mode. Example // Snippet to perform a software reset: PLIB_USB_ResetSignalEnable(MY_USB_INSTANCE); // ... delay 50ms PLIB_USB_ResetSignalDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_ResetSignalEnable ( USB_MODULE_ID index ) PLIB_USB_ResumeSignalingDisable Function Disables resume signaling. File plib_usb.h C void PLIB_USB_ResumeSignalingDisable(USB_MODULE_ID index); Returns None. Description This function disables resume signaling. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsResumeSignaling in your application to determine whether this feature is available. Preconditions None. Example See PLIB_USB_ResumeSignalingEnable. Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_ResumeSignalingDisable ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2236 PLIB_USB_ResumeSignalingEnable Function Enables resume signaling. File plib_usb.h C void PLIB_USB_ResumeSignalingEnable(USB_MODULE_ID index); Returns None. Description This function enables resume signaling. Resume allows the peripheral to perform a remote wake-up by executing resume signaling. Remarks Software must enable resume signaling for 10 ms if the device is in Device mode, or for 25 ms if the device is in Host mode, and then disable resume signaling to enable remote wake-up. In Host mode, the USB module will append a low-speed EOP to the end resume signaling when it is disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsResumeSignaling in your application to determine whether this feature is available. Preconditions None. Example // Perform resume signaling: PLIB_USB_ResumeSignalingEnable(MY_USB_INSTANCE); // Delay 10ms PLIB_USB_ResumeSignalingDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_ResumeSignalingEnable ( USB_MODULE_ID index ) i) On-The-Go (OTG) Functions PLIB_USB_OTG_BSessionHasEnded Function Returns the status of the B-Session End Indicator bit. File plib_usb.h C bool PLIB_USB_OTG_BSessionHasEnded(USB_MODULE_ID index); Returns • true - The VBUS Voltage is below VB_SESS_END on the B-device • false - The VBUS voltage is above VB_SESS_END on the B-device Description This function returns the status of the B-Session End Indicator bit. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_BSessionEnd in your application to determine whether this feature is available. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2237 Preconditions The USB module must be in OTG mode. Example if ( !PLIB_USB_OTG_BSessionHasEnded(MY_USB_INSTANCE) ) { // B session valid } else { // B session not valid } Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_OTG_BSessionHasEnded ( USB_MODULE_ID index ) PLIB_USB_OTG_IDPinStateIsTypeA Function Returns the ID Pin state. File plib_usb.h C bool PLIB_USB_OTG_IDPinStateIsTypeA(USB_MODULE_ID index); Returns • true - Type A Cable attached, • false - No cable is attached or a Type B cable is attached Description This function returns ID Pin state. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_IDPinState in your application to determine whether this feature is available. Preconditions The USB module must be in OTG mode. Example if ( PLIB_USB_OTG_IDPinStateIsTypeA(MY_USB_INSTANCE) ) { // Type A cable attached } else { // No cable or Type B cable attached }; Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_OTG_IDPinStateIsTypeA ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2238 PLIB_USB_OTG_LineStateIsStable Function Returns the status of the Line Stable Indicator bit. File plib_usb.h C bool PLIB_USB_OTG_LineStateIsStable(USB_MODULE_ID index); Returns • true - The USB line state has been stable for the previous 1 ms • false - The USB line state has not been stable for the previous 1 ms Description This function returns the status of the Line Stable Indicator bit. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_LineState in your application to determine whether this feature is available. Preconditions The USB module must be in OTG mode. Example if( PLIB_USB_OTG_LineStateIsStable(MY_USB_INSTANCE) ) { // Line has been stable // ... rest of code ... } Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_OTG_LineStateIsStable ( USB_MODULE_ID index ) PLIB_USB_OTG_PullUpPullDownSetup Function Enables or disables pull-up and pull-down resistors. File plib_usb.h C void PLIB_USB_OTG_PullUpPullDownSetup(USB_MODULE_ID index, USB_OTG_PULL_UP_PULL_DOWN resistor, bool enableResistor); Returns None. Description This function enables or disables pull-up and pull-down resistors. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_PullUpPullDown in your application to determine whether this feature is available. Preconditions USB On-The-Go (OTG) must be enabled. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2239 Example // Enable pull-up resistor for D+ PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DPLUS_PULLUP,true); Parameters Parameters Description index Identifier for the device instance of interest resistor USB_OTG_DPLUS_PULLUP, USB_OTG_DMINUS_PULLUP, USB_OTG_DPLUS_PULLDN, or USB_OTG_DMINUS_PULLDN enableResistor true to enable resistor, false to disable it Function void PLIB_USB_OTG_PullUpPullDownSetup( USB_MODULE_ID index, USB_OTG_PULL_UP_PULL_DOWN resistor, bool enableResistor ) PLIB_USB_OTG_SessionValid Function Returns the status of the Session Valid Indicator bit. File plib_usb.h C bool PLIB_USB_OTG_SessionValid(USB_MODULE_ID index); Returns • true - The VBUS voltage is above Session Valid on the A or B device • false - The VBUS voltage is below Session Valid on the A or B device Description This function returns the status of the Session Valid Indicator bit. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_SessionValid in your application to determine whether this feature is available. Preconditions The USB module must be in OTG mode. Example if ( PLIB_USB_OTG_SessionValid(MY_USB_INSTANCE) ) { // Session valid } else { // Session not valid } Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_OTG_SessionValid ( USB_MODULE_ID index ) PLIB_USB_OTG_VBusChargeDisable Function Disables VBUS line charge. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2240 File plib_usb.h C void PLIB_USB_OTG_VBusChargeDisable(USB_MODULE_ID index); Returns None. Description This function disables VBUS line charge. Remarks Not available on PIC32 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusCharge in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OTG_VBusChargeDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_OTG_VBusChargeDisable ( USB_MODULE_ID index ) PLIB_USB_OTG_VBusChargeEnable Function Enables the VBUS line to be charged through a pull-up resistor. File plib_usb.h C void PLIB_USB_OTG_VBusChargeEnable(USB_MODULE_ID index); Returns None. Description This function enables the VBUS line to be charged through a pull-up resistor. Remarks Not available on PIC32 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusDischarge in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OTG_VBusChargeEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_OTG_VBusChargeEnable ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2241 PLIB_USB_OTG_VBusChargeTo3V Function Sets the VBUS line to charge to 3.3V. File plib_usb.h C void PLIB_USB_OTG_VBusChargeTo3V(USB_MODULE_ID index); Returns None. Description This function sets the VBUS line to charge to 3.3V. Remarks Not available on PIC32 devices. Preconditions None. Example PLIB_USB_OTG_VBusChargeTo3V(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_OTG_VBusChargeTo3V( USB_MODULE_ID index ) PLIB_USB_OTG_VBusChargeTo5V Function Sets the VBUS line to charge to 5V. File plib_usb.h C void PLIB_USB_OTG_VBusChargeTo5V(USB_MODULE_ID index); Returns None. Description This function sets the VBUS line to charge to 5V. Remarks Not available on PIC32 devices. Preconditions None. Example PLIB_USB_OTG_VBusChargeTo5V (MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2242 Function void PLIB_USB_OTG_VBusChargeTo5V ( USB_MODULE_ID index ) PLIB_USB_OTG_VBusDischargeDisable Function Disables VBUS line discharge. File plib_usb.h C void PLIB_USB_OTG_VBusDischargeDisable(USB_MODULE_ID index); Returns None. Description This function disables VBUS line discharge. Remarks Not available on PIC32 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusDischarge in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OTG_VBusDischargeDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_OTG_VBusDischargeDisable ( USB_MODULE_ID index ) PLIB_USB_OTG_VBusDischargeEnable Function Enables VBUS line to be discharged through a resistor. File plib_usb.h C void PLIB_USB_OTG_VBusDischargeEnable(USB_MODULE_ID index); Returns None. Description This function enables the VBUS line to be discharged through a resistor. Remarks Not available on PIC32 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusCharge in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OTG_VBusDischargeEnable(MY_USB_INSTANCE); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2243 Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_OTG_VBusDischargeEnable ( USB_MODULE_ID index ) PLIB_USB_OTG_VBusPowerOff Function Turns off power on the VBUS Line. File plib_usb.h C void PLIB_USB_OTG_VBusPowerOff(USB_MODULE_ID index); Returns None. Description This function turns off power on the VBUS Line. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusPowerOnOff in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OTG_VBusPowerOff(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_OTG_VBusPowerOff ( USB_MODULE_ID index ) PLIB_USB_OTG_VBusPowerOn Function Turns on power for the VBUS line. File plib_usb.h C void PLIB_USB_OTG_VBusPowerOn(USB_MODULE_ID index); Returns None. Description This function turns on power for the VBUS line. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusPowerOnOff in your application to determine whether this feature is available. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2244 Preconditions None. Example PLIB_USB_OTG_VBusPowerOn(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_OTG_VBusPowerOn ( USB_MODULE_ID index ) PLIB_USB_OTG_VBusValid Function Returns the status of the A-VBUS valid indicator. File plib_usb.h C bool PLIB_USB_OTG_VBusValid(USB_MODULE_ID index); Returns • true - The VBUS voltage is above VA_VBUS_VLD on the A-device, • false - The VBUS voltage is below VA_VBUS_VLD on the A-device Description This function returns the status of the A-VBUS valid indicator. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_ASessionValid in your application to determine whether this feature is available. Preconditions The USB module must be in OTG mode. Example if ( PLIB_USB_OTG_VBusValid(MY_USB_INSTANCE) ) { // VBUS voltage above session valid for A device } else { // VBUS voltage below session valid for A device } Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_OTG_VBusValid ( USB_MODULE_ID index ) j) OTG Interrupts Functions PLIB_USB_OTG_InterruptDisable Function Disables a USB On-The-Go (OTG) Interrupt for the USB module. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2245 File plib_usb.h C void PLIB_USB_OTG_InterruptDisable(USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag); Returns None. Description This function disables a USB On-The-Go (OTG) interrupt source for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_Interrupt in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OTG_InterruptDisable( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USB_OTG_InterruptDisable( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ) PLIB_USB_OTG_InterruptEnable Function Enables a USB On-The-Go (OTG) Interrupt for the USB module. File plib_usb.h C void PLIB_USB_OTG_InterruptEnable(USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag); Returns None. Description This function enables USB On-The-Go (OTG) interrupt sources of the USB module to trigger a USB interrupt. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_Interrupt in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OTG_InterruptEnable( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2246 Function void PLIB_USB_OTG_InterruptEnable( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ) PLIB_USB_OTG_InterruptFlagClear Function Clears a USB On-The-Go (OTG) Interrupt flag for the USB module. File plib_usb.h C void PLIB_USB_OTG_InterruptFlagClear(USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag); Returns None. Description This function clears a USB On-The-Go (OTG) interrupt source flag for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OTG_InterruptFlagClear( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USB_OTG_InterruptFlagClear( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ) PLIB_USB_OTG_InterruptFlagGet Function Tests a USB On-The-Go (OTG) Interrupt flag for the USB module. File plib_usb.h C bool PLIB_USB_OTG_InterruptFlagGet(USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag); Returns None. Description This function tests a USB On-The-Go (OTG) interrupt source flag for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2247 Example if ( PLIB_USB_OTG_InterruptFlagGet(MY_USB_INSTANCE,USB_OTG_INT_ANY) ) if ( PLIB_USB_OTG_InterruptFlagGet(MY_USB_INSTANCE,USB_OTG_INT_BDEVICE_SESSION_END) ) { PLIB_USB_OTG_InterruptFlagClear(MY_USB_INSTANCE,USB_OTG_INT_ADEVICE_VBUS_VALID ); // Device A VBUS Valid Change } if ( PLIB_USB_OTG_InterruptFlagGet(MY_USB_INSTANCE,USB_OTG_INT_BDEVICE_SESSION_END) ) { PLIB_USB_OTG_InterruptFlagClear(MY_USB_INSTANCE,USB_OTG_INT_BDEVICE_SESSION_END); // Device B VBUS Valid Change } . . . } Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function bool PLIB_USB_OTG_InterruptFlagGet( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ) PLIB_USB_OTG_InterruptFlagSet Function Sets a USB On-The-Go (OTG) Interrupt flag for the USB module. File plib_usb.h C void PLIB_USB_OTG_InterruptFlagSet(USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag); Returns None. Description This function sets a USB On-The-Go (OTG) interrupt source flag for the USB module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_InterruptStatus in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_OTG_InterruptFlagSet( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USB_OTG_InterruptFlagSet( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2248 PLIB_USB_OTG_InterruptIsEnabled Function Returns whether or not interrupts are enabled. File plib_usb.h C bool PLIB_USB_OTG_InterruptIsEnabled(USB_MODULE_ID index, USB_INTERRUPTS interruptFlag); Returns • true - Interrupts are enabled • false - Interrupts are not enabled Description This function returns whether or not interrupts are enabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_Interrupt in your application to determine whether this feature is available. Preconditions None. Example if ( PLIB_USB_OTG_InterruptIsEnabled( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ) ) { } Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function bool PLIB_USB_OTG_InterruptIsEnabled( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ) k) USB Activity Functions PLIB_USB_ActivityPending Function Returns whether or not USB activity is pending. File plib_usb.h C bool PLIB_USB_ActivityPending(USB_MODULE_ID index); Returns • true - The USB module should not be suspended • false - No interrupts are pending or module may be suspended or powered down Description This function returns whether or not USB bus activity has been detected, an interrupt is pending, or an interrupt is yet to be generated. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsActivityPending in your application to determine whether this feature is available. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2249 Preconditions None. Example while ( PLIB_USB_ActivityPending(MY_USB_INSTANCE) ) { // Wait } // Suspend USB module. Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_ActivityPending ( USB_MODULE_ID index ) PLIB_USB_FrameNumberGet Function Returns the USB frame number. File plib_usb.h C uint16_t PLIB_USB_FrameNumberGet(USB_MODULE_ID index); Returns Current frame number in lower 11 bits. Description This function returns the USB frame number in the lower 11 bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsFrameNumber in your application to determine whether this feature is available. Preconditions None. Example frameNumber = PLIB_USB_FrameNumberGet(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function uint16_t PLIB_USB_FrameNumberGet ( USB_MODULE_ID index ) PLIB_USB_JStateIsActive Function Live differential receiver J State flag. File plib_usb.h C bool PLIB_USB_JStateIsActive(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2250 Returns None. Description This function indicates the live JState (differential '0' in low speed, differential '1' in full speed) on the bus. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLiveJState in your application to determine whether this feature is available. Preconditions The USB module must be in Host mode. Example // Enable Host Mode PLIB_USB_OperatingModeSelect(MY_USB_INSTANCE,USB_OPMODE_HOST); // Enable D+ and D- pull-down resistors PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DPLUS_PULLDN, true); PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DMINUS_PULLDN,true); // Disable D+ and D- pull-up resistors PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DPLUS_PULLUP, false); PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DMINUS_PULLUP,false); // Enable SOF Packet generation PLIB_USB_SOFEnable(MY_USB_INSTANCE); // Enable the device attach interrupt PLIB_USB_INT_Enable(MY_USB_INSTANCE,USB_INT_OTG,ACTIVITY_DETECT); // Wait for the Attach interrupt. while(!PLIB_USB_INT_FlagGet(MY_USB_INSTANCE,USB_INT_OTG,ACTIVITY_DETECT) ) { //Do nothing } // Check JState if( PLIB_USB_JStateIsActive(MY_USB_INSTANCE) ) { // Full Speed PLIB_USB_FullSpeedEnable(MY_USB_INSTANCE); } else { // Low Speed PLIB_USB_FullSpeedDisable(MY_USB_INSTANCE); } Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_JStateIsActive ( USB_MODULE_ID index ) PLIB_USB_PacketTransferDisable Function Disables the Serial Interface Engine (SIE). File plib_usb.h Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2251 C void PLIB_USB_PacketTransferDisable(USB_MODULE_ID index); Returns None. if( PLIB_USB_PacketTransferIsDisabled(MY_USB_INSTANCE) ) { // SETUP token received, do the needful operations . . . // SETUP handling completed, enable Setup token and packet processing: PLIB_USB_PacketTransferDisable(MY_USB_INSTANCE); } Description This function disables the Serial Interface Engine (SIE). Remarks Not valid when the USB module is in Host mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPacketTransfer in your application to determine whether this feature is available. Preconditions USB module must be in device mode. Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PacketTransferDisable ( USB_MODULE_ID index ) PLIB_USB_PacketTransferEnable Function Re-enables the Serial Interface Engine (SIE), allowing token and packet processing. File plib_usb.h C void PLIB_USB_PacketTransferEnable(USB_MODULE_ID index); Returns None. if( PLIB_USB_PacketTransferIsDisabled(MY_USB_INSTANCE) ) { // SETUP token received, do the needful operations . . . // SETUP handling completed, enable Setup token and packet processing: PLIB_USB_PacketTransferEnable(MY_USB_INSTANCE); } Description This function re-enables the Serial Interface Engine (SIE), allowing token and packet processing. Remarks Not valid when the USB module is in Host mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPacketTransfer in your application to determine whether this feature is available. Preconditions USB module must be in device mode. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2252 Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PacketTransferEnable ( USB_MODULE_ID index ) PLIB_USB_PacketTransferIsDisabled Function Indicates that a setup token has been received from the Host and that token/packet processing is disabled. File plib_usb.h C bool PLIB_USB_PacketTransferIsDisabled(USB_MODULE_ID index); Returns None. Description This function indicates that a setup token has been received from the Host and that the Serial Interface Engine (SIE) has been turned off, disabling token and packet processing. Remarks Not valid when USB is Host. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPacketTransfer in your application to determine whether this feature is available. Preconditions USB module must be in device mode. Example if( PLIB_USB_PacketTransferIsDisabled(MY_USB_INSTANCE) ) { // SETUP token received, do the needful operations . . . // SETUP handling completed, enable Setup token and packet processing: PLIB_USB_PacketTransferEnable(MY_USB_INSTANCE); } Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_PacketTransferIsDisabled ( USB_MODULE_ID index ) PLIB_USB_SE0InProgress Function Returns whether a single-ended zero event is in progress. File plib_usb.h C bool PLIB_USB_SE0InProgress(USB_MODULE_ID index); Returns • true - A single ended zero event (SE0) is occurring Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2253 • false - A single-ended zero event (SE0) is not occurring Description This function returns whether a single-ended zero event is in progress. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLiveSingleEndedZero in your application to determine whether this feature is available. Preconditions None. Example if( PLIB_USB_SE0InProgress(MY_USB_INSTANCE) ) { // handle the SE0 event } Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_SE0InProgress( USB_MODULE_ID index ) l) External Transceiver Support Functions PLIB_USB_I2CInterfaceForExtModuleDisable Function Specifies external module(s) are controlled via dedicated pins. File plib_usb.h C void PLIB_USB_I2CInterfaceForExtModuleDisable(USB_MODULE_ID index); Returns None. Description Specifies that external module(s) are controlled via dedicated pins. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_I2CInterfaceForExtModuleDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_I2CInterfaceForExtModuleDisable ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2254 PLIB_USB_I2CInterfaceForExtModuleEnable Function Specifies external module(s) are controlled via the I2C interface. File plib_usb.h C void PLIB_USB_I2CInterfaceForExtModuleEnable(USB_MODULE_ID index); Returns None. Description This function specifies that external module(s) are controlled via the I2C interface. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_I2CInterfaceForExtModuleEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_I2CInterfaceForExtModuleEnable ( USB_MODULE_ID index ) PLIB_USB_TransceiverDisable Function Disables the on-chip transceiver File plib_usb.h C void PLIB_USB_TransceiverDisable(USB_MODULE_ID index); Returns None. Description This function disables the on-chip transceiver and enables the interface to the off-chip transceiver. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOnChipTransceiver in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_TransceiverDisable(MY_USB_INSTANCE); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2255 Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_TransceiverDisable ( USB_MODULE_ID index ) PLIB_USB_TransceiverEnable Function Enables the on-chip transceiver. File plib_usb.h C void PLIB_USB_TransceiverEnable(USB_MODULE_ID index); Returns None. Description This function enables the on-chip transceiver. The interface to the off-chip transceiver is disabled. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOnChipTransceiver in your application to determine whether this feature is available. Preconditions Use only before the USB module is enabled by calling PLIB_USB_Enable. Example PLIB_USB_TransceiverEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_TransceiverEnable ( USB_MODULE_ID index ) m) VBUS Support Functions PLIB_USB_ExternalComparatorMode2Pin Function Sets the 2-pin input configuration for VBUS comparators. File plib_usb.h C void PLIB_USB_ExternalComparatorMode2Pin(USB_MODULE_ID index); Returns None. Description This function sets the 2-pin input configuration for VBUS Comparators. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2256 Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_ExternalComparatorMode2Pin(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_ExternalComparatorMode2Pin ( USB_MODULE_ID index ) PLIB_USB_ExternalComparatorMode3Pin Function Sets the 3-pin input configuration for VBUS Comparators. File plib_usb.h C void PLIB_USB_ExternalComparatorMode3Pin(USB_MODULE_ID index); Returns None. Description This function sets the 3-pin input configuration for VBUS comparators. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_ExternalComparatorMode3Pin(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_ExternalComparatorMode3Pin ( USB_MODULE_ID index ) PLIB_USB_PWMCounterDisable Function Disables the PWM counter used to generate the VBUS for the USB module. File plib_usb.h C void PLIB_USB_PWMCounterDisable(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2257 Returns None. Description This function disables the PWM counter used to generate the VBUS for the USB module. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_PWMDisable(MY_USB_INSTANCE); PLIB_USB_PWMCounterDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PWMCounterDisable( USB_MODULE_ID index ); PLIB_USB_PWMCounterEnable Function Enables the PWM counter used to generate the VBUS for the USB module. File plib_usb.h C void PLIB_USB_PWMCounterEnable(USB_MODULE_ID index); Returns None. Description This function enables the PWM counter used to generate the VBUS for the USB module. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_PWMEnable(MY_USB_INSTANCE); PLIB_USB_PWMCounterEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PWMCounterEnable( USB_MODULE_ID index ) PLIB_USB_PWMDisable Function Disables the PWM Generator. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2258 File plib_usb.h C void PLIB_USB_PWMDisable(USB_MODULE_ID index); Returns None. Description This function disables the PWM Generator. PWM output held in a reset state defined by PLIB_USB_PWMPolarityActiveHigh or PLIB_USB_PWMPolarityActiveLow. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_PWMDisable (MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PWMDisable ( USB_MODULE_ID index ) PLIB_USB_PWMEnable Function Enables the PWM Generator. File plib_usb.h C void PLIB_USB_PWMEnable(USB_MODULE_ID index); Returns None. Description This function enables the PWM Generator. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_PWMEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2259 Function void PLIB_USB_PWMEnable ( USB_MODULE_ID index ) PLIB_USB_PWMPolaritiyActiveLow Function Sets the PWM output to active-high and resets low. File plib_usb.h C void PLIB_USB_PWMPolaritiyActiveLow(USB_MODULE_ID index); Returns None. Description This function sets the PWM output to active-high and resets low. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PWMPolaritiyActiveLow ( USB_MODULE_ID index ) PLIB_USB_PWMPolarityActiveHigh Function Sets the PWM output to active-low and resets high. File plib_usb.h C void PLIB_USB_PWMPolarityActiveHigh(USB_MODULE_ID index); Returns None. Description This function sets the PWM output to active-low and resets high. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_PWMPolaritiy (MY_USB_INSTANCE); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2260 Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PWMPolarityActiveHigh ( USB_MODULE_ID index ) PLIB_USB_VBoostDisable Function Disables the On-Chip 5V Boost Regulator Circuit Disabled bit. File plib_usb.h C void PLIB_USB_VBoostDisable(USB_MODULE_ID index); Returns None. Description This function disables the On-Chip 5V Boost Regulator Circuit Disabled bit. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_VBoostDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_VBoostDisable ( USB_MODULE_ID index ) PLIB_USB_VBoostEnable Function Enables the On-Chip 5V Boost Regulator Circuit Enabled bit. File plib_usb.h C void PLIB_USB_VBoostEnable(USB_MODULE_ID index); Returns None. Description This function enables the On-Chip 5V Boost Regulator Circuit Enabled bit. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2261 Preconditions None. Example PLIB_USB_VBoostEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_VBoostEnable ( USB_MODULE_ID index ) PLIB_USB_VBUSComparatorDisable Function Disables the on-chip VBUS Comparator. File plib_usb.h C void PLIB_USB_VBUSComparatorDisable(USB_MODULE_ID index); Returns None. Description This function disables the on-chip VBUS Comparator. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_VBUSComparatorDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_VBUSComparatorDisable ( USB_MODULE_ID index ) PLIB_USB_VBUSComparatorEnable Function Enables the on-chip VBUS Comparator. File plib_usb.h C void PLIB_USB_VBUSComparatorEnable(USB_MODULE_ID index); Returns None. Description This function enables the on-chip VBUS Comparator. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2262 Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_VBUSComparatorEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_VBUSComparatorEnable ( USB_MODULE_ID index ) PLIB_USB_VBUSPullUpDisable Function Disables the pull-up on the VBUS pin. File plib_usb.h C void PLIB_USB_VBUSPullUpDisable(USB_MODULE_ID index); Returns None. Description This function disables the pull-up on the VBUS pin. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_VBUSPullUpDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_VBUSPullUpDisable ( USB_MODULE_ID index ) PLIB_USB_VBUSPullUpEnable Function Enables the pull-up on the VBUS pin. File plib_usb.h C void PLIB_USB_VBUSPullUpEnable(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2263 Returns None. Description This function enables the pull-up on the VBUS pin. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Preconditions None. Example PLIB_USB_VBUSPullUpEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_VBUSPullUpEnable ( USB_MODULE_ID index ) n) Test Support Functions PLIB_USB_EyePatternDisable Function Disables the USB eye pattern test. File plib_usb.h C void PLIB_USB_EyePatternDisable(USB_MODULE_ID index); Returns None. Description This function disables the USB eye pattern test. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEyePattern in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_EyePatternDisable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_EyePatternDisable ( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2264 PLIB_USB_EyePatternEnable Function Enables USB eye pattern test. File plib_usb.h C void PLIB_USB_EyePatternEnable(USB_MODULE_ID index); Returns None. Description This function enables the USB eye pattern test. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEyePattern in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_EyePatternEnable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_EyePatternEnable ( USB_MODULE_ID index ) o) Other Functions PLIB_USB_ModuleIsBusy Function Indicates if the USB module is not ready to be enabled. File plib_usb.h C bool PLIB_USB_ModuleIsBusy(USB_MODULE_ID index); Returns • true - USB module is active or disabled, but not ready to be enabled • false - USB module is not active and is ready to be enabled Description This function indicates if the USB module is not ready to be enabled. Remarks If PLIB_USB_ModuleIsBusy(MY_USB_INSTANCE) == true and the USB module is disabled, and all status returned for the module, all enables/disables for the module will produce undefined results. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsModuleBusyin your application to determine whether this feature is available. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2265 Example #ifdef (__PIC32MX__) while ( PLIB_USB_ModuleIsBusy(MY_USB_INSTANCE) ) { // wait } #endif PLIB_USB_Disable(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function bool PLIB_USB_ModuleIsBusy ( USB_MODULE_ID index ) PLIB_USB_PingPongFreeze Function Resets all Ping-Pong buffer pointers to even buffers. File plib_usb.h C void PLIB_USB_PingPongFreeze(USB_MODULE_ID index); Returns None. Description This function resets all Ping-Pong buffer pointers to even buffers. Remarks Buffers remain "frozen" at "Even" until they are unfrozen using PLIB_USB_PingPongUnfreeze. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBufferFreeze in your application to determine whether this feature is available. Preconditions None. Example // Reset all ping-pong buffers to "Even" PLIB_USB_PingPongFreeze(MY_USB_INSTANCE); PLIB_USB_PingPongUnfreeze(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PingPongFreeze ( USB_MODULE_ID index ) PLIB_USB_PingPongReset Function Resets the USB peripheral internal Ping-Pong indicator to point to even buffers. File plib_usb.h C void PLIB_USB_PingPongReset(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2266 Returns None. Description This function resets the USB peripheral internal Ping-Pong indicator to point to Even buffers. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBufferFreeze in your application to determine whether this feature is available. Preconditions None. Example PLIB_USB_PingPongReset(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PingPongReset ( USB_MODULE_ID index ) PLIB_USB_PingPongUnfreeze Function Enables Ping-Pong buffering. File plib_usb.h C void PLIB_USB_PingPongUnfreeze(USB_MODULE_ID index); Returns None. Description This function enables Ping-Pong buffering. Remarks See PLIB_USB_PingPongFreeze. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBufferFreeze in your application to determine whether this feature is available. Preconditions None. Example // Reset all Ping-Pong buffers to "Even" PLIB_USB_PingPongFreeze(MY_USB_INSTANCE); PLIB_USB_PingPongUnfreeze(MY_USB_INSTANCE); Parameters Parameters Description index Identifier for the device instance of interest Function void PLIB_USB_PingPongUnfreeze ( USB_MODULE_ID index ) PLIB_USB_TokenSend Function Sends token to the specified address. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2267 File plib_usb.h C void PLIB_USB_TokenSend(USB_MODULE_ID index, USB_PID pidValue, uint8_t endpoint, uint8_t deviceAddress, bool isLowSpeed); Returns None. Description This function sends the specified token to the specified endpoint and address. The token is placed on the bus at the next available time. The token can be executed at low speed. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Preconditions None. Example // Send an OUT token to endpoint 1 device address 2 at full speed PLIB_USB_SendToken(MY_USB_INSTANCE, USB_PID_OUT, 1, 2, false); Parameters Parameters Description index Identifier for the device instance of interest pidValue PID of the token to be placed on the bus. endpoint Device endpoint to which the token should be sent. isLowSpeed Is true if the token should be executed at low speed. Function void PLIB_USB_TokenSend(USB_MODULE_ID index, USB_PID pidValue, uint8_t endpoint, uint8_t deviceAddress, bool isLowSpeed); p) Feature Existence Functions PLIB_USB_ExistsActivityPending Function Identifies whether the ActivityPending feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsActivityPending(USB_MODULE_ID index); Returns • true - The ActivityPending feature is supported on the device • false - The ActivityPending feature is not supported on the device Description This function identifies whether the ActivityPending feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_ActivityPending Remarks None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2268 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsActivityPending( USB_MODULE_ID index ) PLIB_USB_ExistsALL_Interrupt Function Identifies whether the ALL_Interrupt feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsALL_Interrupt(USB_MODULE_ID index); Returns • true - The ALL_Interrupt feature is supported on the device • false - The ALL_Interrupt feature is not supported on the device Description This function identifies whether the ALL_Interrupt feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_AllInterruptEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsALL_Interrupt( USB_MODULE_ID index ) PLIB_USB_ExistsAutomaticSuspend Function Identifies whether the AutomaticSuspend feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsAutomaticSuspend(USB_MODULE_ID index); Returns • true - The AutomaticSuspend feature is supported on the device • false - The AutomaticSuspend feature is not supported on the device Description This function identifies whether the AutomaticSuspend feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_AutoSuspendDisable Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2269 • PLIB_USB_AutoSuspendEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsAutomaticSuspend( USB_MODULE_ID index ) PLIB_USB_ExistsBDTBaseAddress Function Identifies whether the BDTBaseAddress feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsBDTBaseAddress(USB_MODULE_ID index); Returns • true - The BDTBaseAddress feature is supported on the device • false - The BDTBaseAddress feature is not supported on the device Description This function identifies whether the BDTBaseAddress feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_BDTBaseAddressGet • PLIB_USB_BDTBaseAddressSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsBDTBaseAddress( USB_MODULE_ID index ) PLIB_USB_ExistsBDTFunctions Function Identifies whether the BDTFunctions feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsBDTFunctions(USB_MODULE_ID index); Returns • true - The BDTFunctions feature is supported on the device • false - The BDTFunctions feature is not supported on the device Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2270 Description This function identifies whether the BDTFunctions feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_BufferAddressGet • PLIB_USB_BufferAddressSet • PLIB_USB_BufferByteCountGet • PLIB_USB_BufferByteCountSet • PLIB_USB_BufferCancelReleaseToUSB • PLIB_USB_BufferAllCancelReleaseToUSB • PLIB_USB_BufferClearAll • PLIB_USB_BufferDataToggleGet • PLIB_USB_BufferDataToggleSelect • PLIB_USB_BufferDataToggleSyncEnable • PLIB_USB_BufferDataToggleSyncDisable • PLIB_USB_BufferIndexGet • PLIB_USB_BufferPIDBitsClear • PLIB_USB_BufferPIDGet • PLIB_USB_BufferReleasedToSW • PLIB_USB_BufferReleaseToUSB • PLIB_USB_BufferSchedule • PLIB_USB_BufferStallDisable • PLIB_USB_BufferStallEnable • PLIB_USB_BufferStallGet • PLIB_USB_BufferEP0RxStatusInitialize • PLIB_USB_BufferClearAllDTSEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsBDTFunctions( USB_MODULE_ID index ) PLIB_USB_ExistsBufferFreeze Function Identifies whether the BufferFreeze feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsBufferFreeze(USB_MODULE_ID index); Returns • true - The BufferFreeze feature is supported on the device • false - The BufferFreeze feature is not supported on the device Description This function identifies whether the BufferFreeze feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_PingPongFreeze • PLIB_USB_PingPongUnfreeze • PLIB_USB_PingPongReset Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2271 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsBufferFreeze( USB_MODULE_ID index ) PLIB_USB_ExistsDeviceAddress Function Identifies whether the DeviceAddress feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsDeviceAddress(USB_MODULE_ID index); Returns • true - The DeviceAddress feature is supported on the device • false - The DeviceAddress feature is not supported on the device Description This function identifies whether the DeviceAddress feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_DeviceAddressSet • PLIB_USB_DeviceAddressGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsDeviceAddress( USB_MODULE_ID index ) PLIB_USB_ExistsEP0LowSpeedConnect Function Identifies whether the EP0LowSpeedConnect feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsEP0LowSpeedConnect(USB_MODULE_ID index); Returns • true - The EP0LowSpeedConnect feature is supported on the device • false - The EP0LowSpeedConnect feature is not supported on the device Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2272 Description This function identifies whether the EP0LowSpeedConnect feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EP0LSDirectConnectEnable • PLIB_USB_EP0LSDirectConnectDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsEP0LowSpeedConnect( USB_MODULE_ID index ) PLIB_USB_ExistsEP0NAKRetry Function Identifies whether the EP0NAKRetry feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsEP0NAKRetry(USB_MODULE_ID index); Returns • true - The EP0NAKRetry feature is supported on the device • false - The EP0NAKRetry feature is not supported on the device Description This function identifies whether the EP0NAKRetry feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EP0NakRetryEnable • PLIB_USB_EP0NakRetryDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsEP0NAKRetry( USB_MODULE_ID index ) PLIB_USB_ExistsEPnRxEnable Function Identifies whether the EPnRxEnableEnhanced feature exists on the USB module. File plib_usb.h Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2273 C bool PLIB_USB_ExistsEPnRxEnable(USB_MODULE_ID index); Returns • true - The EPnRxEnableEnhanced feature is supported on the device • false - The EPnRxEnableEnhanced feature is not supported on the device Description This function identifies whether the EPnRxEnableEnhanced feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EPnRxEnable • PLIB_USB_EPnRxDisable • PLIB_USB_EPnTxEnable • PLIB_USB_EPnTxDisable • PLIB_USB_EPnHandshakeEnable • PLIB_USB_EPnHandshakeDisable • PLIB_USB_EPnControlTransferEnable • PLIB_USB_EPnControlTransferDisable • PLIB_USB_EPnIsStalled • PLIB_USB_EPnStallClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsEPnRxEnable( USB_MODULE_ID index ) PLIB_USB_ExistsEPnTxRx Function Identifies whether the EPnTxRx feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsEPnTxRx(USB_MODULE_ID index); Returns • true - The EPnTxRx feature is supported on the device • false - The EPnTxRx feature is not supported on the device Description This function identifies whether the EPnTxRx feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EPnTxSelect • PLIB_USB_EPnRxSelect • PLIB_USB_EPnTxRxSelect Remarks None. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2274 Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsEPnTxRx( USB_MODULE_ID index ) PLIB_USB_ExistsERR_Interrupt Function Identifies whether the ERR_Interrupt feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsERR_Interrupt(USB_MODULE_ID index); Returns • true - The ERR_Interrupt feature is supported on the device • false - The ERR_Interrupt feature is not supported on the device Description This function identifies whether the ERR_Interrupt feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_ErrorInterruptEnable • PLIB_USB_ErrorInterruptDisable • PLIB_USB_ErrorInterruptIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsERR_Interrupt( USB_MODULE_ID index ) PLIB_USB_ExistsERR_InterruptStatus Function Identifies whether the ERR_InterruptStatus feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsERR_InterruptStatus(USB_MODULE_ID index); Returns • true - The ERR_InterruptStatus feature is supported on the device • false - The ERR_InterruptStatus feature is not supported on the device Description This function identifies whether the ERR_InterruptStatus feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_ErrorInterruptFlagSet • PLIB_USB_ErrorInterruptFlagClear Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2275 • PLIB_USB_ErrorInterruptFlagGet • PLIB_USB_ErrorInterruptFlagAllGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsERR_InterruptStatus( USB_MODULE_ID index ) PLIB_USB_ExistsEyePattern Function Identifies whether the EyePattern feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsEyePattern(USB_MODULE_ID index); Returns • true - The EyePattern feature is supported on the device • false - The EyePattern feature is not supported on the device Description This function identifies whether the EyePattern feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EyePatternDisable • PLIB_USB_EyePatternEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsEyePattern( USB_MODULE_ID index ) PLIB_USB_ExistsFrameNumber Function Identifies whether the FrameNumber feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsFrameNumber(USB_MODULE_ID index); Returns • true - The FrameNumber feature is supported on the device Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2276 • false - The FrameNumber feature is not supported on the device Description This function identifies whether the FrameNumber feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_FrameNumberGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsFrameNumber( USB_MODULE_ID index ) PLIB_USB_ExistsGEN_Interrupt Function Identifies whether the GEN_Interrupt feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsGEN_Interrupt(USB_MODULE_ID index); Returns • true - The GEN_Interrupt feature is supported on the device • false - The GEN_Interrupt feature is not supported on the device Description This function identifies whether the GEN_Interrupt feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_InterruptEnable • PLIB_USB_InterruptDisable • PLIB_USB_InterruptIsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsGEN_Interrupt( USB_MODULE_ID index ) PLIB_USB_ExistsGEN_InterruptStatus Function Identifies whether the GEN_InterruptStatus feature exists on the USB module. File plib_usb.h Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2277 C bool PLIB_USB_ExistsGEN_InterruptStatus(USB_MODULE_ID index); Returns • true - The GEN_InterruptStatus feature is supported on the device • false - The GEN_InterruptStatus feature is not supported on the device Description This function identifies whether the GEN_InterruptStatus feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_InterruptFlagSet • PLIB_USB_InterruptFlagClear • PLIB_USB_InterruptFlagGet • PLIB_USB_InterruptFlagAllGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsGEN_InterruptStatus( USB_MODULE_ID index ) PLIB_USB_ExistsHostBusyWithToken Function Identifies whether the HostBusyWithToken feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsHostBusyWithToken(USB_MODULE_ID index); Returns • true - The HostBusyWithToken feature is supported on the device • false - The HostBusyWithToken feature is not supported on the device Description This function identifies whether the HostBusyWithToken feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_IsBusyWithToken Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsHostBusyWithToken( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2278 PLIB_USB_ExistsHostGeneratesReset Function Identifies whether the HostGeneratesReset feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsHostGeneratesReset(USB_MODULE_ID index); Returns • true - The HostGeneratesReset feature is supported on the device • false - The HostGeneratesReset feature is not supported on the device Description This function identifies whether the HostGeneratesReset feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_ResetSignalEnable • PLIB_USB_ResetSignalDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsHostGeneratesReset( USB_MODULE_ID index ) PLIB_USB_ExistsLastDirection Function Identifies whether the LastDirection feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsLastDirection(USB_MODULE_ID index); Returns • true - The LastDirection feature is supported on the device • false - The LastDirection feature is not supported on the device Description This function identifies whether the LastDirection feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_LastTransactionDirectionGet Remarks None. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2279 Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsLastDirection( USB_MODULE_ID index ) PLIB_USB_ExistsLastEndpoint Function Identifies whether the LastEndpoint feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsLastEndpoint(USB_MODULE_ID index); Returns • true - The LastEndpoint feature is supported on the device • false - The LastEndpoint feature is not supported on the device Description This function identifies whether the LastEndpoint feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_LastTransactionEndPtGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsLastEndpoint( USB_MODULE_ID index ) PLIB_USB_ExistsLastPingPong Function Identifies whether the LastPingPong feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsLastPingPong(USB_MODULE_ID index); Returns • true - The LastPingPong feature is supported on the device • false - The LastPingPong feature is not supported on the device Description This function identifies whether the LastPingPong feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_LastTransactionPingPongStateGet Remarks None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2280 Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsLastPingPong( USB_MODULE_ID index ) PLIB_USB_ExistsLastTransactionDetails Function Identifies whether the LastTransactionDetails feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsLastTransactionDetails(USB_MODULE_ID index); Returns • true - The LastTransactionDetails feature is supported on the device • false - The LastTransactionDetails feature is not supported on the device Description This function identifies whether the LastTransactionDetails feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_LastTransactionDetailsGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsLastTransactionDetails( USB_MODULE_ID index ) PLIB_USB_ExistsLiveJState Function Identifies whether the LiveJState feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsLiveJState(USB_MODULE_ID index); Returns • true - The LiveJState feature is supported on the device • false - The LiveJState feature is not supported on the device Description This function identifies whether the LiveJState feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_JStateIsActive Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2281 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsLiveJState( USB_MODULE_ID index ) PLIB_USB_ExistsLiveSingleEndedZero Function Identifies whether the LiveSingleEndedZero feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsLiveSingleEndedZero(USB_MODULE_ID index); Returns • true - The LiveSingleEndedZero feature is supported on the device • false - The LiveSingleEndedZero feature is not supported on the device Description This function identifies whether the LiveSingleEndedZero feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_SE0InProgress Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsLiveSingleEndedZero( USB_MODULE_ID index ) PLIB_USB_ExistsModuleBusy Function Identifies whether the ModuleBusy feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsModuleBusy(USB_MODULE_ID index); Returns • true - The ModuleBusy feature is supported on the device • false - The ModuleBusy feature is not supported on the device Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2282 Description This function identifies whether the ModuleBusy feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_ModuleIsBusy Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsModuleBusy( USB_MODULE_ID index ) PLIB_USB_ExistsModulePower Function Identifies whether the ModulePower feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsModulePower(USB_MODULE_ID index); Returns • true - The ModulePower feature is supported on the device • false - The ModulePower feature is not supported on the device Description This function identifies whether the ModulePower feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_Enable • PLIB_USB_Disable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsModulePower( USB_MODULE_ID index ) PLIB_USB_ExistsNextTokenSpeed Function Identifies whether the NextTokenSpeed feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsNextTokenSpeed(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2283 Returns • true - The NextTokenSpeed feature is supported on the device • false - The NextTokenSpeed feature is not supported on the device Description This function identifies whether the NextTokenSpeed feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_TokenSpeedSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsNextTokenSpeed( USB_MODULE_ID index ) PLIB_USB_ExistsOnChipPullup Function Identifies whether the OnChipPullup feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOnChipPullup(USB_MODULE_ID index); Returns • true - The OnChipPullup feature is supported on the device • false - The OnChipPullup feature is not supported on the device Description This function identifies whether the OnChipPullup feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OnChipPullUpDisable • PLIB_USB_OnChipPullUpEnable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOnChipPullup( USB_MODULE_ID index ) PLIB_USB_ExistsOnChipTransceiver Function Identifies whether the OnChipTransceiver feature exists on the USB module. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2284 File plib_usb.h C bool PLIB_USB_ExistsOnChipTransceiver(USB_MODULE_ID index); Returns • true - The OnChipTransceiver feature is supported on the device • false - The OnChipTransceiver feature is not supported on the device Description This function identifies whether the OnChipTransceiver feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_TransceiverEnable • PLIB_USB_TransceiverDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOnChipTransceiver( USB_MODULE_ID index ) PLIB_USB_ExistsOpModeSelect Function Identifies whether the OpModeSelect feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOpModeSelect(USB_MODULE_ID index); Returns • true - The OpModeSelect feature is supported on the device • false - The OpModeSelect feature is not supported on the device Description This function identifies whether the OpModeSelect feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OperatingModeSelect Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOpModeSelect( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2285 PLIB_USB_ExistsOTG_ASessionValid Function Identifies whether the OTG_ASessionValid feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_ASessionValid(USB_MODULE_ID index); Returns • true - The OTG_ASessionValid feature is supported on the device • false - The OTG_ASessionValid feature is not supported on the device Description This function identifies whether the OTG_ASessionValid feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_VBusValid Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_ASessionValid( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_BSessionEnd Function Identifies whether the OTG_BSessionEnd feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_BSessionEnd(USB_MODULE_ID index); Returns • true - The OTG_BSessionEnd feature is supported on the device • false - The OTG_BSessionEnd feature is not supported on the device Description This function identifies whether the OTG_BSessionEnd feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_BSessionHasEnded Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2286 Function PLIB_USB_ExistsOTG_BSessionEnd( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_IDPinState Function Identifies whether the OTG_IDPinState feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_IDPinState(USB_MODULE_ID index); Returns • true - The OTG_IDPinState feature is supported on the device • false - The OTG_IDPinState feature is not supported on the device Description This function identifies whether the OTG_IDPinState feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_IDPinStateIsTypeA Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_IDPinState( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_Interrupt Function Identifies whether the OTG_Interrupt feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_Interrupt(USB_MODULE_ID index); Returns • true - The OTG_Interrupt feature is supported on the device • false - The OTG_Interrupt feature is not supported on the device Description This function identifies whether the OTG_Interrupt feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OTG_InterruptEnable • PLIB_USB_OTG_InterruptDisable • PLIB_USB_OTG_InterruptIsEnabled Remarks None. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2287 Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_Interrupt( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_InterruptStatus Function Identifies whether the OTG_InterruptStatus feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_InterruptStatus(USB_MODULE_ID index); Returns • true - The OTG_InterruptStatus feature is supported on the device • false - The OTG_InterruptStatus feature is not supported on the device Description This function identifies whether the OTG_InterruptStatus feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OTG_InterruptFlagSet • PLIB_USB_OTG_InterruptFlagClear • PLIB_USB_OTG_InterruptFlagGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_InterruptStatus( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_LineState Function Identifies whether the OTG_LineState feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_LineState(USB_MODULE_ID index); Returns • true - The OTG_LineState feature is supported on the device • false - The OTG_LineState feature is not supported on the device Description This function identifies whether the OTG_LineState feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_LineStateIsStable Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2288 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_LineState( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_PullUpPullDown Function Identifies whether the OTG_PullUpPullDown feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_PullUpPullDown(USB_MODULE_ID index); Returns • true - The OTG_PullUpPullDown feature is supported on the device • false - The OTG_PullUpPullDown feature is not supported on the device Description This function identifies whether the OTG_PullUpPullDown feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_PullUpPullDownSetup Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_PullUpPullDown( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_SessionValid Function Identifies whether the OTG_SessionValid feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_SessionValid(USB_MODULE_ID index); Returns • true - The OTG_SessionValid feature is supported on the device • false - The OTG_SessionValid feature is not supported on the device Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2289 Description This function identifies whether the OTG_SessionValid feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_SessionValid Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_SessionValid( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_VbusCharge Function Identifies whether the OTG_VbusCharge feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_VbusCharge(USB_MODULE_ID index); Returns • true - The OTG_VbusCharge feature is supported on the device • false - The OTG_VbusCharge feature is not supported on the device Description This function identifies whether the OTG_VbusCharge feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OTG_VBusChargeEnable • PLIB_USB_OTG_VBusChargeDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_VbusCharge( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_VbusDischarge Function Identifies whether the OTG_VbusDischarge feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_VbusDischarge(USB_MODULE_ID index); Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2290 Returns • true - The OTG_VbusDischarge feature is supported on the device • false - The OTG_VbusDischarge feature is not supported on the device Description This function identifies whether the OTG_VbusDischarge feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OTG_VBusDischargeEnable • PLIB_USB_OTG_VBusDischargeDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_VbusDischarge( USB_MODULE_ID index ) PLIB_USB_ExistsOTG_VbusPowerOnOff Function Identifies whether the OTG_VbusPowerOnOff feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsOTG_VbusPowerOnOff(USB_MODULE_ID index); Returns • true - The OTG_VbusPowerOnOff feature is supported on the device • false - The OTG_VbusPowerOnOff feature is not supported on the device Description This function identifies whether the OTG_VbusPowerOnOff feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OTG_VBusPowerOff • PLIB_USB_OTG_VBusPowerOn Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsOTG_VbusPowerOnOff( USB_MODULE_ID index ) PLIB_USB_ExistsPacketTransfer Function Identifies whether the PacketTransfer feature exists on the USB module. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2291 File plib_usb.h C bool PLIB_USB_ExistsPacketTransfer(USB_MODULE_ID index); Returns • true - The PacketTransfer feature is supported on the device • false - The PacketTransfer feature is not supported on the device Description This function identifies whether the PacketTransfer feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_PacketTransferIsDisabled • PLIB_USB_PacketTransferEnable • PLIB_USB_PacketTransferDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsPacketTransfer( USB_MODULE_ID index ) PLIB_USB_ExistsPingPongMode Function Identifies whether the PingPongMode feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsPingPongMode(USB_MODULE_ID index); Returns • true - The PingPongMode feature is supported on the device • false - The PingPongMode feature is not supported on the device Description This function identifies whether the PingPongMode feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_PingPongModeSelect • PLIB_USB_PingPongModeGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2292 Function PLIB_USB_ExistsPingPongMode( USB_MODULE_ID index ) PLIB_USB_ExistsResumeSignaling Function Identifies whether the ResumeSignaling feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsResumeSignaling(USB_MODULE_ID index); Returns • true - The ResumeSignaling feature is supported on the device • false - The ResumeSignaling feature is not supported on the device Description This function identifies whether the ResumeSignaling feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_ResumeSignalingEnable • PLIB_USB_ResumeSignalingDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsResumeSignaling( USB_MODULE_ID index ) PLIB_USB_ExistsSleepEntryGuard Function Identifies whether the SleepEntryGuard feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsSleepEntryGuard(USB_MODULE_ID index); Returns • true - The SleepEntryGuard feature is supported on the device • false - The SleepEntryGuard feature is not supported on the device Description This function identifies whether the SleepEntryGuard feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_SleepGuardEnable • PLIB_USB_SleepGuardDisable Remarks None. Preconditions None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2293 Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsSleepEntryGuard( USB_MODULE_ID index ) PLIB_USB_ExistsSOFThreshold Function Identifies whether the SOFThreshold feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsSOFThreshold(USB_MODULE_ID index); Returns • true - The SOFThreshold feature is supported on the device • false - The SOFThreshold feature is not supported on the device Description This function identifies whether the SOFThreshold feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_SOFThresholdGet • PLIB_USB_SOFThresholdSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsSOFThreshold( USB_MODULE_ID index ) PLIB_USB_ExistsSpeedControl Function Identifies whether the SpeedControl feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsSpeedControl(USB_MODULE_ID index); Returns • true - The SpeedControl feature is supported on the device • false - The SpeedControl feature is not supported on the device Description This function identifies whether the SpeedControl feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_FullSpeedEnable • PLIB_USB_FullSpeedDisable Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2294 Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsSpeedControl( USB_MODULE_ID index ) PLIB_USB_ExistsStartOfFrames Function Identifies whether the StartOfFrames feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsStartOfFrames(USB_MODULE_ID index); Returns • true - The StartOfFrames feature is supported on the device • false - The StartOfFrames feature is not supported on the device Description This function identifies whether the StartOfFrames feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_SOFEnable • PLIB_USB_SOFDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsStartOfFrames( USB_MODULE_ID index ) PLIB_USB_ExistsStopInIdle Function Identifies whether the StopInIdle feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsStopInIdle(USB_MODULE_ID index); Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2295 Description This function identifies whether the StopInIdle feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_StopInIdleEnable • PLIB_USB_StopInIdleDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsStopInIdle( USB_MODULE_ID index ) PLIB_USB_ExistsSuspend Function Identifies whether the Suspend feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsSuspend(USB_MODULE_ID index); Returns • true - The Suspend feature is supported on the device • false - The Suspend feature is not supported on the device Description This function identifies whether the Suspend feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_SuspendEnable • PLIB_USB_SuspendDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsSuspend( USB_MODULE_ID index ) PLIB_USB_ExistsTokenEP Function Identifies whether the TokenEP feature exists on the USB module. File plib_usb.h Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2296 C bool PLIB_USB_ExistsTokenEP(USB_MODULE_ID index); Returns • true - The TokenEP feature is supported on the device • false - The TokenEP feature is not supported on the device Description This function identifies whether the TokenEP feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_TokenEPGet • PLIB_USB_TokenEPSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsTokenEP( USB_MODULE_ID index ) PLIB_USB_ExistsTokenPID Function Identifies whether the TokenPID feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsTokenPID(USB_MODULE_ID index); Returns • true - The TokenPID feature is supported on the device • false - The TokenPID feature is not supported on the device Description This function identifies whether the TokenPID feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_TokenPIDGet • PLIB_USB_TokenPIDSet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsTokenPID( USB_MODULE_ID index ) Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2297 PLIB_USB_ExistsUOEMonitor Function Identifies whether the UOEMonitor feature exists on the USB module. File plib_usb.h C bool PLIB_USB_ExistsUOEMonitor(USB_MODULE_ID index); Returns • true - The UOEMonitor feature is supported on the device • false - The UOEMonitor feature is not supported on the device Description This function identifies whether the UOEMonitor feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_UOEMonitorEnable • PLIB_USB_UOEMonitorDisable Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USB_ExistsUOEMonitor( USB_MODULE_ID index ) q) Data Types and Constants USB_BUFFER_DATA01 Enumeration Provides enumeration data toggle for a buffer. File plib_usb.h C typedef enum { USB_BUFFER_DATA0, USB_BUFFER_DATA1 } USB_BUFFER_DATA01; Members Members Description USB_BUFFER_DATA0 DATA0/1 = 0 USB_BUFFER_DATA1 DATA0/1 = 1 Description USB Endpoint Buffer Data Toggle Enumeration This data type provides enumeration data toggle for a buffer. Remarks None. Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2298 USB_BUFFER_DIRECTION Enumeration Provides enumeration transmit/receive direction for a buffer. File plib_usb.h C typedef enum { USB_BUFFER_RX, USB_BUFFER_TX } USB_BUFFER_DIRECTION; Members Members Description USB_BUFFER_RX Receive USB_BUFFER_TX Transmit Description USB Endpoint Buffer Direction Enumeration This data type provides enumeration transmit/receive direction for a buffer. Remarks None. USB_BUFFER_PING_PONG Enumeration Enumerates the ping-pong buffer (Even vs. Odd). File plib_usb.h C typedef enum { USB_BUFFER_EVEN, USB_BUFFER_ODD } USB_BUFFER_PING_PONG; Members Members Description USB_BUFFER_EVEN Even Buffer USB_BUFFER_ODD Odd Buffer Description Enumeration of USB Buffer Ping-Pong This data type enumerates the ping-pong buffer (Even vs. Odd). Remarks None. USB_BUFFER_SCHEDULE_DATA01 Enumeration Provides enumeration data toggle for a buffer. File plib_usb.h C typedef enum { USB_BUFFER_DONTCHANGE, USB_BUFFER_SET_DATA0, Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2299 USB_BUFFER_SET_DATA1 } USB_BUFFER_SCHEDULE_DATA01; Members Members Description USB_BUFFER_DONTCHANGE Don't Change DATA0/1 USB_BUFFER_SET_DATA0 DATA0/1 = 0 USB_BUFFER_SET_DATA1 DATA0/1 = 1 Description USB Endpoint Buffer Data Toggle Enumeration for Buffer Schedulint This data type provides enumeration data toggle for a buffer. Remarks None. USB_EP_TXRX Enumeration Provides enumeration transmit/receive setup for an endpoint. File plib_usb.h C typedef enum { USB_EP_NOTXRX, USB_EP_RX, USB_EP_TX, USB_EP_TX_RX } USB_EP_TXRX; Members Members Description USB_EP_NOTXRX Nothing enabled for endpoint USB_EP_RX Receive enabled for endpoint USB_EP_TX Transmit enabled for endpoint USB_EP_TX_RX Transmit and Receive enabled for endpoint Description Enumeration of USB Endpoint Transmit/Receive Setup This data type provides enumeration transmit/receive setup for an endpoint. Remarks None. USB_OPMODES Enumeration Provides enumeration of operating modes supported by USB. File plib_usb.h C typedef enum { USB_OPMODE_NONE, USB_OPMODE_DEVICE, USB_OPMODE_HOST, USB_OPMODE_OTG } USB_OPMODES; Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2300 Members Members Description USB_OPMODE_NONE None USB_OPMODE_DEVICE Device USB_OPMODE_HOST Host USB_OPMODE_OTG OTG Description USB Operating Modes Enumeration This data type provides enumeration of the operating modes supported by the USB module. Remarks None. USB_OTG_INTERRUPTS Enumeration Provides enumeration of interrupts related to the USB On-The-Go (OTG) module. File plib_usb.h C typedef enum { USB_OTG_INT_ADEVICE_VBUS_VALID, USB_OTG_INT_OTG_RESERVED, USB_OTG_INT_BDEVICE_SESSION_END, USB_OTG_INT_SESSION_VALID, USB_OTG_INT_ACTIVITY_DETECT, USB_OTG_INT_STABLE_LINE_STATE, USB_OTG_INT_ONE_MS_TIMEOUT, USB_OTG_INT_ID_STATE_CHANGE, USB_OTG_INT_ANY, USB_OTG_INT_ALL } USB_OTG_INTERRUPTS; Members Members Description USB_OTG_INT_ADEVICE_VBUS_VALID State of (VBUS > Va_vbus_vld) on the A device has changed USB_OTG_INT_OTG_RESERVED Reserved. Don't use. USB_OTG_INT_BDEVICE_SESSION_END State of (VBUS < Vb_sess_end) on the B device has changed USB_OTG_INT_SESSION_VALID State of (VBUS > Va_sess_vld) on the A or B devices has changed USB_OTG_INT_ACTIVITY_DETECT Activity detected on the D+, D-, ID, or VBUS lines USB_OTG_INT_STABLE_LINE_STATE USB line state has been stable for 1 ms, but different from last time USB_OTG_INT_ONE_MS_TIMEOUT One millisecond timer has expired USB_OTG_INT_ID_STATE_CHANGE Change in state of ID pin detected. USB_OTG_INT_ANY All or Any of the above USB_OTG_INT_ALL All or Any of the above Description USB OTG Interrupts Enumeration This data type provides enumeration of interrupts related to the USB OTG module. Remarks Not applicable if the USB OTG module is not enabled. USB_OTG_PULL_UP_PULL_DOWN Enumeration USB OTG pull-Up and pull-Down resistors for D+ and D- . Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2301 File plib_usb.h C typedef enum { USB_OTG_DPLUS_PULLUP, USB_OTG_DMINUS_PULLUP, USB_OTG_DPLUS_PULLDN, USB_OTG_DMINUS_PULLDN } USB_OTG_PULL_UP_PULL_DOWN; Members Members Description USB_OTG_DPLUS_PULLUP D+ Pull-Up USB_OTG_DMINUS_PULLUP D- Pull-Up USB_OTG_DPLUS_PULLDN D+ Pull-Down USB_OTG_DMINUS_PULLDN D- Pull-Down Description Enumeration of Pull-Up and Pull-Down Resistors for OTG This data type enumerates the OTG Pull-Up and Pull-Down resistors for D+ and D- . Remarks None. USB_PID Enumeration Legal PID values. File plib_usb.h C typedef enum { USB_PID_SETUP, USB_PID_IN, USB_PID_OUT } USB_PID; Members Members Description USB_PID_SETUP Setup token USB_PID_IN IN token USB_PID_OUT OUT token Description Enumeration of Legal Packet IDs (PIDs) This data type enumerates the valid (i.e., legal) PID values. While the PID field is four bits long, only these values are legal and should be used. The use of any other values may cause unpredictable results. USB_PING_PONG_MODE Enumeration Supports the four modes of ping-pong buffering. File plib_usb.h C typedef enum { USB_PING_PONG_ALL_BUT_EP0, USB_PING_PONG_FULL_PING_PONG, USB_PING_PONG_EP0_OUT_ONLY, Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2302 USB_PING_PONG_NO_PING_PONG } USB_PING_PONG_MODE; Members Members Description USB_PING_PONG_ALL_BUT_EP0 Ping-Pong buffering on all endpoints except Endpoint Zero USB_PING_PONG_FULL_PING_PONG Ping-Pong buffering on all endpoints USB_PING_PONG_EP0_OUT_ONLY Ping-Pong buffering on just Endpoint Zero transmit USB_PING_PONG_NO_PING_PONG No ping-pong buffering Description Enumeration of USB Ping-Pong Modes This data type supports the four modes of ping-pong buffering. Remarks None. USB_PING_PONG_STATE Enumeration Decodes which buffer (Even vs. Odd) was used for the last transaction. File plib_usb.h C typedef enum { USB_PING_PONG_EVEN, USB_PING_PONG_ODD } USB_PING_PONG_STATE; Members Members Description USB_PING_PONG_EVEN Last transaction on Even Buffer USB_PING_PONG_ODD Last transaction on Odd Buffer Description Enumeration of USB Ping-Pong Indicator This data type decodes which buffer (Even vs. Odd) was used for the last transaction. Remarks None. USB_TOKEN_SPEED Enumeration Provides enumeration of available token speeds. File plib_usb.h C typedef enum { USB_LOWSPEED_TOKENS, USB_FULLSPEED_TOKENS } USB_TOKEN_SPEED; Members Members Description USB_LOWSPEED_TOKENS Low Speed Tokens USB_FULLSPEED_TOKENS Full Speed Tokens Peripheral Libraries Help USB Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2303 Description USB Token Speeds Enumeration This data type provides enumeration of available token speeds. Remarks For Host mode only. USB_MAX_EP_NUMBER Macro Maximum number of endpoints supported (not including EP0). File plib_usb.h C #define USB_MAX_EP_NUMBER 15 Description Maximum number of endpoints This constant defines the maximum number of endpoints supported (not including EP0). It is used in dimensioning the Buffer Descriptor Table (BDT) array. Files Files Name Description plib_usb.h USB Peripheral Library Interface Header for common definitions Description This section lists the source and header files used by the library. plib_usb.h USB Peripheral Library Interface Header for common definitions Enumerations Name Description USB_BUFFER_DATA01 Provides enumeration data toggle for a buffer. USB_BUFFER_DIRECTION Provides enumeration transmit/receive direction for a buffer. USB_BUFFER_PING_PONG Enumerates the ping-pong buffer (Even vs. Odd). USB_BUFFER_SCHEDULE_DATA01 Provides enumeration data toggle for a buffer. USB_EP_TXRX Provides enumeration transmit/receive setup for an endpoint. USB_OPMODES Provides enumeration of operating modes supported by USB. USB_OTG_INTERRUPTS Provides enumeration of interrupts related to the USB On-The-Go (OTG) module. USB_OTG_PULL_UP_PULL_DOWN USB OTG pull-Up and pull-Down resistors for D+ and D- . USB_PID Legal PID values. USB_PING_PONG_MODE Supports the four modes of ping-pong buffering. USB_PING_PONG_STATE Decodes which buffer (Even vs. Odd) was used for the last transaction. USB_TOKEN_SPEED Provides enumeration of available token speeds. Functions Name Description PLIB_USB_ActivityPending Returns whether or not USB activity is pending. PLIB_USB_AllInterruptEnable Configures the USB peripheral general interrupts, error interrupts and OTG interrupts. PLIB_USB_AutoSuspendDisable Disables USB OTG Auto-suspend mode. PLIB_USB_AutoSuspendEnable Enables USB Auto-suspend mode. Peripheral Libraries Help USB Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2304 PLIB_USB_BDTBaseAddressGet Returns the base address of the Buffer Descriptor Table. PLIB_USB_BDTBaseAddressSet Sets the base address for the Buffer Descriptor Table for PIC32 devices. PLIB_USB_BufferAddressGet Gets the memory address of an endpoint buffer. PLIB_USB_BufferAddressSet Sets the endpoint buffer address. PLIB_USB_BufferAllCancelReleaseToUSB Cancels all endpoint buffer releases to the USB module and hands over the buffer to the CPU. PLIB_USB_BufferByteCountGet Returns the endpoint buffer byte count. PLIB_USB_BufferByteCountSet Sets the buffer byte count. PLIB_USB_BufferCancelReleaseToUSB Cancels release of the endpoint buffer by software, allowing software to again access the buffer. PLIB_USB_BufferClearAll Clears (zeros out) entries in the Buffer Descriptor Table. PLIB_USB_BufferClearAllDTSEnable Clears the endpoint descriptor entry and enables data toggle synchronization. PLIB_USB_BufferDataToggleGet Returns data synchronization (DATA0 or DATA1) for the endpoint buffer. PLIB_USB_BufferDataToggleSelect Sets the endpoint buffer to DATA0 or DATA1. PLIB_USB_BufferDataToggleSyncDisable Disables DATA0/DATA1 synchronization between the device and host. PLIB_USB_BufferDataToggleSyncEnable Enables DATA0/DATA1 synchronization between the device and host. PLIB_USB_BufferEP0RxStatusInitialize Initializes the Endpoint 0 RX endpoint buffer descriptors. PLIB_USB_BufferIndexGet Gets the Buffer Descriptor Table index for a buffer. PLIB_USB_BufferPIDBitsClear Clears the Buffer Status bits in the Buffer Descriptor Table. PLIB_USB_BufferPIDGet Returns the token packet ID (PID) from the endpoint buffer status. PLIB_USB_BufferReleasedToSW Returns the boolean flag value of 'true' when the buffer has been released by the USB module. PLIB_USB_BufferReleaseToUSB Releases the endpoint buffer by software, allowing the USB module access to the buffer. PLIB_USB_BufferSchedule Hands over a buffer to the USB module along with the buffer address and byte count. PLIB_USB_BufferStallDisable Disables STALL handshaking for the associated endpoint buffer. PLIB_USB_BufferStallEnable Enables STALL handshaking for the associated endpoint buffer. PLIB_USB_BufferStallGet Returns the buffer stall status for an endpoint/direction/ping-pong. PLIB_USB_DeviceAddressGet Returns the address of the USB module in Device mode. PLIB_USB_DeviceAddressSet Sets the USB Device's address. PLIB_USB_Disable Disables (powers down) the USB module. PLIB_USB_Enable Enables (powers up) the USB module. PLIB_USB_EP0HostSetup Sends token to the specified address. PLIB_USB_EP0LSDirectConnectDisable Disables direct connection to a low-speed device for Endpoint 0. PLIB_USB_EP0LSDirectConnectEnable Enables direct connection to a low-speed device for Endpoint 0. PLIB_USB_EP0NakRetryDisable Disables retrying of NAKed transactions. PLIB_USB_EP0NakRetryEnable Enables retrying NAK'd transactions for Endpoint 0. PLIB_USB_EPnAttributesClear Clears the set attributes of the specified endpoint. PLIB_USB_EPnAttributesSet Configures attributes of the endpoint such as direction, handshake capability and direction. PLIB_USB_EPnControlTransferDisable Disables endpoint control transfers. PLIB_USB_EPnControlTransferEnable Enables endpoint control transfers. PLIB_USB_EPnDirectionDisable Disables the specified endpoint direction. PLIB_USB_EPnHandshakeDisable Disables endpoint handshaking. PLIB_USB_EPnHandshakeEnable Enables endpoint handshaking. PLIB_USB_EPnIsStalled Tests whether the endpoint epValue is stalled. PLIB_USB_EPnRxDisable Disables an endpoint's ability to process IN tokens. PLIB_USB_EPnRxEnable Enables an endpoint to process IN tokens. PLIB_USB_EPnRxSelect Selects receive capabilities of an endpoint. PLIB_USB_EPnStallClear Clears an endpoint's stalled flag. PLIB_USB_EPnTxDisable Disables an endpoint's ability to process OUT tokens. PLIB_USB_EPnTxEnable Enables an endpoint to process OUT tokens. PLIB_USB_EPnTxRxSelect Selects transmit and/or receive capabilities of an endpoint. PLIB_USB_EPnTxSelect Selects transmit capabilities of an endpoint. PLIB_USB_ErrorInterruptDisable Disables an error interrupt for the USB module. Peripheral Libraries Help USB Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2305 PLIB_USB_ErrorInterruptEnable Enables an error interrupt for the USB module. PLIB_USB_ErrorInterruptFlagAllGet Returns a logically ORed bit map of active error interrupt flags. PLIB_USB_ErrorInterruptFlagClear Clears an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptFlagGet Tests an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptFlagSet Sets an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptIsEnabled Returns true if interrupts are enabled. PLIB_USB_ExistsActivityPending Identifies whether the ActivityPending feature exists on the USB module. PLIB_USB_ExistsALL_Interrupt Identifies whether the ALL_Interrupt feature exists on the USB module. PLIB_USB_ExistsAutomaticSuspend Identifies whether the AutomaticSuspend feature exists on the USB module. PLIB_USB_ExistsBDTBaseAddress Identifies whether the BDTBaseAddress feature exists on the USB module. PLIB_USB_ExistsBDTFunctions Identifies whether the BDTFunctions feature exists on the USB module. PLIB_USB_ExistsBufferFreeze Identifies whether the BufferFreeze feature exists on the USB module. PLIB_USB_ExistsDeviceAddress Identifies whether the DeviceAddress feature exists on the USB module. PLIB_USB_ExistsEP0LowSpeedConnect Identifies whether the EP0LowSpeedConnect feature exists on the USB module. PLIB_USB_ExistsEP0NAKRetry Identifies whether the EP0NAKRetry feature exists on the USB module. PLIB_USB_ExistsEPnRxEnable Identifies whether the EPnRxEnableEnhanced feature exists on the USB module. PLIB_USB_ExistsEPnTxRx Identifies whether the EPnTxRx feature exists on the USB module. PLIB_USB_ExistsERR_Interrupt Identifies whether the ERR_Interrupt feature exists on the USB module. PLIB_USB_ExistsERR_InterruptStatus Identifies whether the ERR_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsEyePattern Identifies whether the EyePattern feature exists on the USB module. PLIB_USB_ExistsFrameNumber Identifies whether the FrameNumber feature exists on the USB module. PLIB_USB_ExistsGEN_Interrupt Identifies whether the GEN_Interrupt feature exists on the USB module. PLIB_USB_ExistsGEN_InterruptStatus Identifies whether the GEN_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsHostBusyWithToken Identifies whether the HostBusyWithToken feature exists on the USB module. PLIB_USB_ExistsHostGeneratesReset Identifies whether the HostGeneratesReset feature exists on the USB module. PLIB_USB_ExistsLastDirection Identifies whether the LastDirection feature exists on the USB module. PLIB_USB_ExistsLastEndpoint Identifies whether the LastEndpoint feature exists on the USB module. PLIB_USB_ExistsLastPingPong Identifies whether the LastPingPong feature exists on the USB module. PLIB_USB_ExistsLastTransactionDetails Identifies whether the LastTransactionDetails feature exists on the USB module. PLIB_USB_ExistsLiveJState Identifies whether the LiveJState feature exists on the USB module. PLIB_USB_ExistsLiveSingleEndedZero Identifies whether the LiveSingleEndedZero feature exists on the USB module. PLIB_USB_ExistsModuleBusy Identifies whether the ModuleBusy feature exists on the USB module. PLIB_USB_ExistsModulePower Identifies whether the ModulePower feature exists on the USB module. PLIB_USB_ExistsNextTokenSpeed Identifies whether the NextTokenSpeed feature exists on the USB module. PLIB_USB_ExistsOnChipPullup Identifies whether the OnChipPullup feature exists on the USB module. PLIB_USB_ExistsOnChipTransceiver Identifies whether the OnChipTransceiver feature exists on the USB module. PLIB_USB_ExistsOpModeSelect Identifies whether the OpModeSelect feature exists on the USB module. PLIB_USB_ExistsOTG_ASessionValid Identifies whether the OTG_ASessionValid feature exists on the USB module. PLIB_USB_ExistsOTG_BSessionEnd Identifies whether the OTG_BSessionEnd feature exists on the USB module. PLIB_USB_ExistsOTG_IDPinState Identifies whether the OTG_IDPinState feature exists on the USB module. PLIB_USB_ExistsOTG_Interrupt Identifies whether the OTG_Interrupt feature exists on the USB module. PLIB_USB_ExistsOTG_InterruptStatus Identifies whether the OTG_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsOTG_LineState Identifies whether the OTG_LineState feature exists on the USB module. PLIB_USB_ExistsOTG_PullUpPullDown Identifies whether the OTG_PullUpPullDown feature exists on the USB module. PLIB_USB_ExistsOTG_SessionValid Identifies whether the OTG_SessionValid feature exists on the USB module. PLIB_USB_ExistsOTG_VbusCharge Identifies whether the OTG_VbusCharge feature exists on the USB module. PLIB_USB_ExistsOTG_VbusDischarge Identifies whether the OTG_VbusDischarge feature exists on the USB module. PLIB_USB_ExistsOTG_VbusPowerOnOff Identifies whether the OTG_VbusPowerOnOff feature exists on the USB module. PLIB_USB_ExistsPacketTransfer Identifies whether the PacketTransfer feature exists on the USB module. PLIB_USB_ExistsPingPongMode Identifies whether the PingPongMode feature exists on the USB module. PLIB_USB_ExistsResumeSignaling Identifies whether the ResumeSignaling feature exists on the USB module. PLIB_USB_ExistsSleepEntryGuard Identifies whether the SleepEntryGuard feature exists on the USB module. PLIB_USB_ExistsSOFThreshold Identifies whether the SOFThreshold feature exists on the USB module. PLIB_USB_ExistsSpeedControl Identifies whether the SpeedControl feature exists on the USB module. PLIB_USB_ExistsStartOfFrames Identifies whether the StartOfFrames feature exists on the USB module. Peripheral Libraries Help USB Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2306 PLIB_USB_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the USB module. PLIB_USB_ExistsSuspend Identifies whether the Suspend feature exists on the USB module. PLIB_USB_ExistsTokenEP Identifies whether the TokenEP feature exists on the USB module. PLIB_USB_ExistsTokenPID Identifies whether the TokenPID feature exists on the USB module. PLIB_USB_ExistsUOEMonitor Identifies whether the UOEMonitor feature exists on the USB module. PLIB_USB_ExternalComparatorMode2Pin Sets the 2-pin input configuration for VBUS comparators. PLIB_USB_ExternalComparatorMode3Pin Sets the 3-pin input configuration for VBUS Comparators. PLIB_USB_EyePatternDisable Disables the USB eye pattern test. PLIB_USB_EyePatternEnable Enables USB eye pattern test. PLIB_USB_FrameNumberGet Returns the USB frame number. PLIB_USB_FullSpeedDisable Forces the USB module to operate at low speed. PLIB_USB_FullSpeedEnable Enables the USB to operate at full speed. PLIB_USB_I2CInterfaceForExtModuleDisable Specifies external module(s) are controlled via dedicated pins. PLIB_USB_I2CInterfaceForExtModuleEnable Specifies external module(s) are controlled via the I2C interface. PLIB_USB_InterruptDisable Disables a general interrupt for the USB module. PLIB_USB_InterruptEnable Enables a general interrupt for the USB module. PLIB_USB_InterruptEnableGet Returns the enable/disable status of general USB module interrupts PLIB_USB_InterruptFlagAllGet Returns a logically ORed bit map of active general USB interrupt flags. PLIB_USB_InterruptFlagClear Clears a general interrupt flag for the USB module. PLIB_USB_InterruptFlagGet Tests a general interrupt flag for the USB module. PLIB_USB_InterruptFlagSet Sets a general interrupt flag for the USB module. PLIB_USB_InterruptIsEnabled Returns true if interrupts are enabled. PLIB_USB_IsBusyWithToken Indicates whether there is a token being executed by the USB module as Host. PLIB_USB_JStateIsActive Live differential receiver J State flag. PLIB_USB_LastTransactionDetailsGet Returns the details of the last completed transaction. PLIB_USB_LastTransactionDirectionGet Indicates the direction of the last transaction. PLIB_USB_LastTransactionEndPtGet Returns the endpoint number of the last USB transfer. PLIB_USB_LastTransactionPingPongStateGet Indicates whether the last transaction was to an EVEN buffer or an ODD buffer. PLIB_USB_ModuleIsBusy Indicates if the USB module is not ready to be enabled. PLIB_USB_OnChipPullUpDisable Disables on-chip pull-ups. PLIB_USB_OnChipPullUpEnable Enables on-chip pull-ups. PLIB_USB_OperatingModeSelect Selects the operating mode of the USB module. PLIB_USB_OTG_BSessionHasEnded Returns the status of the B-Session End Indicator bit. PLIB_USB_OTG_IDPinStateIsTypeA Returns the ID Pin state. PLIB_USB_OTG_InterruptDisable Disables a USB On-The-Go (OTG) Interrupt for the USB module. PLIB_USB_OTG_InterruptEnable Enables a USB On-The-Go (OTG) Interrupt for the USB module. PLIB_USB_OTG_InterruptFlagClear Clears a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptFlagGet Tests a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptFlagSet Sets a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptIsEnabled Returns whether or not interrupts are enabled. PLIB_USB_OTG_LineStateIsStable Returns the status of the Line Stable Indicator bit. PLIB_USB_OTG_PullUpPullDownSetup Enables or disables pull-up and pull-down resistors. PLIB_USB_OTG_SessionValid Returns the status of the Session Valid Indicator bit. PLIB_USB_OTG_VBusChargeDisable Disables VBUS line charge. PLIB_USB_OTG_VBusChargeEnable Enables the VBUS line to be charged through a pull-up resistor. PLIB_USB_OTG_VBusChargeTo3V Sets the VBUS line to charge to 3.3V. PLIB_USB_OTG_VBusChargeTo5V Sets the VBUS line to charge to 5V. PLIB_USB_OTG_VBusDischargeDisable Disables VBUS line discharge. PLIB_USB_OTG_VBusDischargeEnable Enables VBUS line to be discharged through a resistor. PLIB_USB_OTG_VBusPowerOff Turns off power on the VBUS Line. PLIB_USB_OTG_VBusPowerOn Turns on power for the VBUS line. PLIB_USB_OTG_VBusValid Returns the status of the A-VBUS valid indicator. PLIB_USB_PacketTransferDisable Disables the Serial Interface Engine (SIE). PLIB_USB_PacketTransferEnable Re-enables the Serial Interface Engine (SIE), allowing token and packet processing. Peripheral Libraries Help USB Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2307 PLIB_USB_PacketTransferIsDisabled Indicates that a setup token has been received from the Host and that token/packet processing is disabled. PLIB_USB_PingPongFreeze Resets all Ping-Pong buffer pointers to even buffers. PLIB_USB_PingPongModeGet Returns the Ping-Pong Configuration setting. PLIB_USB_PingPongModeSelect Selects the Ping-Pong Configuration setting. PLIB_USB_PingPongReset Resets the USB peripheral internal Ping-Pong indicator to point to even buffers. PLIB_USB_PingPongUnfreeze Enables Ping-Pong buffering. PLIB_USB_PWMCounterDisable Disables the PWM counter used to generate the VBUS for the USB module. PLIB_USB_PWMCounterEnable Enables the PWM counter used to generate the VBUS for the USB module. PLIB_USB_PWMDisable Disables the PWM Generator. PLIB_USB_PWMEnable Enables the PWM Generator. PLIB_USB_PWMPolaritiyActiveLow Sets the PWM output to active-high and resets low. PLIB_USB_PWMPolarityActiveHigh Sets the PWM output to active-low and resets high. PLIB_USB_ResetSignalDisable Disables reset signaling on the USB bus. PLIB_USB_ResetSignalEnable Enables reset signaling on the USB bus. PLIB_USB_ResumeSignalingDisable Disables resume signaling. PLIB_USB_ResumeSignalingEnable Enables resume signaling. PLIB_USB_SE0InProgress Returns whether a single-ended zero event is in progress. PLIB_USB_SleepGuardDisable This function disables Sleep Guard. Entry into Sleep mode is immediate. PLIB_USB_SleepGuardEnable Entry into Sleep mode is blocked if bus activity is detected or if an interrupt is pending. PLIB_USB_SOFDisable Disables the automatic generation of the SOF token. PLIB_USB_SOFEnable Enables the automatic generation of the SOF token every 1 ms. PLIB_USB_SOFThresholdGet Returns the Start-of-Frame (SOF) Count bits. PLIB_USB_SOFThresholdSet Sets the Start-of-Frame (SOF) threshold value. PLIB_USB_StopInIdleDisable Allows the USB module to continue operation when the device enters Idle mode. PLIB_USB_StopInIdleEnable Enables USB module operation to stop when the device enters Idle mode. PLIB_USB_SuspendDisable Disables USB OTG Suspend mode. PLIB_USB_SuspendEnable Enables USB Suspend mode. PLIB_USB_TokenEPGet Returns the specified Endpoint address. PLIB_USB_TokenEPSet Sets the Endpoint address for a host transaction. PLIB_USB_TokenPIDGet Returns the token transaction type. PLIB_USB_TokenPIDSet Sets the token transaction type to pidValue. PLIB_USB_TokenSend Sends token to the specified address. PLIB_USB_TokenSpeedSelect Selects low speed or full speed for subsequent token executions. PLIB_USB_TransceiverDisable Disables the on-chip transceiver PLIB_USB_TransceiverEnable Enables the on-chip transceiver. PLIB_USB_UOEMonitorDisable Disables the OE signal output. PLIB_USB_UOEMonitorEnable Enables the OE signal output. PLIB_USB_VBoostDisable Disables the On-Chip 5V Boost Regulator Circuit Disabled bit. PLIB_USB_VBoostEnable Enables the On-Chip 5V Boost Regulator Circuit Enabled bit. PLIB_USB_VBUSComparatorDisable Disables the on-chip VBUS Comparator. PLIB_USB_VBUSComparatorEnable Enables the on-chip VBUS Comparator. PLIB_USB_VBUSPullUpDisable Disables the pull-up on the VBUS pin. PLIB_USB_VBUSPullUpEnable Enables the pull-up on the VBUS pin. Macros Name Description USB_MAX_EP_NUMBER Maximum number of endpoints supported (not including EP0). Description USB Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the USB Peripheral Library. Peripheral Libraries Help USB Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2308 File Name plib_usb.h Company Microchip Technology Inc. Peripheral Libraries Help USB Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2309 USBHS Peripheral Library This section describes the Hi-Speed USB (USBHS) Peripheral Library. Introduction This library provides a low-level abstraction of the USBHS module on Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description USB Overview USB is an asynchronous serial interface with a tiered star configuration. USB is implemented as a master/slave configuration. On a given bus, there can be multiple (up to 127) slaves (devices), but there is only one master (host). There are three possible module implementations: host, device and OTG dual role. The user should have an understanding of the USB documents available on the USB implementers web site (www.usb.org). Features of the Hi-Speed USB (USBHS) Module • Operates either as a function controller of a Hi-Speed/Full-Speed USB device or as the host/device in a point-to-point or multi-point communications with other USB function • Supports OTG communications with on or more Hi-Speed, Full-Speed, or Low-Speed devices • Provides soft_connect/disconnect. • In addition to Endpoint Zero, supports seven transmit and seven receive endpoints • Dynamic FIFO sizing for Endpoints 1-7. (Endpoint Zero FIFO fixed at 64 bytes.) FIFOs use module-internal SRAM. • Module-internal eight channel DMA with access to all FIFOs • All host transaction scheduling supported in hardware • Supports Link Power Management Using the Library This topic describes the basic architecture of the USBHS Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_usbhs.h The interface to the USBHS Peripheral Library is defined in the plib_usbhs.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the USBHS Peripheral Library must include peripheral.h. Library File: The USBHS Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Peripheral Libraries Help USBHS Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2310 Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the USBHS module. Library Interface Section Description USBHS Setup Functions This section provides functions to perform general USBHS peripheral setup such as functions to set USB Speed, control on-chip pull ups, etc. Endpoints Functions This section provides functions that allow the application to manage endpoints. Interrupts Functions This section provides functions that allow the application to enable, disable and query the status interrupts in the USBHS peripheral. Device Functions This section provides functions that are required to operate the USBHS module while in Device mode. Host Functions This section provides functions that are required to operate the USBHS module while in Host mode. Status Functions This section provides functions that read the status of the USBHS module. VBUS Support Functions This section provides functions that allow VBUS level monitoring and VBUS boost PWM module control. Feature Existence Functions This section provides functions that identify whether a particular feature exists on the USBHS module. How the Library Works Provides information on how the library works. Configuring the Library The library is configured for the supported High-Speed USB module when the processor is chosen in the MPLAB X IDE. Library Interface a) USBHS Setup Functions Name Description PLIB_USBHS_HighSpeedDisable This is function PLIB_USBHS_HighSpeedDisable. PLIB_USBHS_HighSpeedEnable Sets the operation speed of the USB Module. PLIB_USBHS_ResetDisable This is function PLIB_USBHS_ResetDisable. PLIB_USBHS_ResetEnable This is function PLIB_USBHS_ResetEnable. PLIB_USBHS_ResumeDisable This is function PLIB_USBHS_ResumeDisable. PLIB_USBHS_ResumeEnable This is function PLIB_USBHS_ResumeEnable. PLIB_USBHS_SessionDisable This is function PLIB_USBHS_SessionDisable. PLIB_USBHS_SessionEnable This is function PLIB_USBHS_SessionEnable. PLIB_USBHS_SoftResetDisable Disables soft reset. PLIB_USBHS_SoftResetEnable Enables soft reset. PLIB_USBHS_SuspendDisable This is function PLIB_USBHS_SuspendDisable. PLIB_USBHS_SuspendEnable This is function PLIB_USBHS_SuspendEnable. PLIB_USBHS_DMAOperationEnable This is function PLIB_USBHS_DMAOperationEnable. PLIB_USBHS_TestModeEnter This is function PLIB_USBHS_TestModeEnter. PLIB_USBHS_TestModeExit This is function PLIB_USBHS_TestModeExit. PLIB_USBHS_PhyIDMonitoringDisable This is function PLIB_USBHS_PhyIDMonitoringDisable. PLIB_USBHS_PhyIDMonitoringEnable This is function PLIB_USBHS_PhyIDMonitoringEnable. PLIB_USBHS_USBIDOverrideDisable This is function PLIB_USBHS_USBIDOverrideDisable. PLIB_USBHS_USBIDOverrideEnable This is function PLIB_USBHS_USBIDOverrideEnable. PLIB_USBHS_USBIDOverrideValueSet This is function PLIB_USBHS_USBIDOverrideValueSet. PLIB_USBHS_IsBDevice This is function PLIB_USBHS_IsBDevice. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2311 b) Endpoints Functions Name Description PLIB_USBHS_Endpoint0FIFOFlush This is function PLIB_USBHS_Endpoint0FIFOFlush. PLIB_USBHS_Endpoint0SetupPacketLoad Loads the endpoint 0 FIFO with provided setup packet and then enables the endpoint transmit. PLIB_USBHS_Endpoint0SetupPacketUnload This is function PLIB_USBHS_Endpoint0SetupPacketUnload. PLIB_USBHS_EndpointFIFOLoad Loads the endpoint FIFO with provided data and then enables the endpoint transmit. PLIB_USBHS_EndpointFIFOUnload Unloads the endpoint FIFO. PLIB_USBHS_EndpointRxFIFOFlush This is function PLIB_USBHS_EndpointRxFIFOFlush. PLIB_USBHS_EndpointRxRequestClear This is function PLIB_USBHS_EndpointRxRequestClear. PLIB_USBHS_EndpointRxRequestEnable This is function PLIB_USBHS_EndpointRxRequestEnable. PLIB_USBHS_EndpointTxFIFOFlush This is function PLIB_USBHS_EndpointTxFIFOFlush. PLIB_USBHS_EP0DataEndSet This is function PLIB_USBHS_EP0DataEndSet. PLIB_USBHS_EP0INHandshakeClear This is function PLIB_USBHS_EP0INHandshakeClear. PLIB_USBHS_EP0INHandshakeSend This is function PLIB_USBHS_EP0INHandshakeSend. PLIB_USBHS_EP0INTokenSend This is function PLIB_USBHS_EP0INTokenSend. PLIB_USBHS_EP0OUTHandshakeSend This is function PLIB_USBHS_EP0OUTHandshakeSend. PLIB_USBHS_EP0RxPktRdyServiced This is function PLIB_USBHS_EP0RxPktRdyServiced. PLIB_USBHS_EP0RxPktRdyServicedDataEnd This is function PLIB_USBHS_EP0RxPktRdyServicedDataEnd. PLIB_USBHS_EP0SentStallClear This is function PLIB_USBHS_EP0SentStallClear. PLIB_USBHS_EP0SetupEndServiced This is function PLIB_USBHS_EP0SetupEndServiced. PLIB_USBHS_EP0StallDisable This is function PLIB_USBHS_EP0StallDisable. PLIB_USBHS_EP0StallEnable This is function PLIB_USBHS_EP0StallEnable. PLIB_USBHS_EP0StatusClear This is function PLIB_USBHS_EP0StatusClear. PLIB_USBHS_EP0StatusGet This is function PLIB_USBHS_EP0StatusGet. PLIB_USBHS_EP0TxPktRdy This is function PLIB_USBHS_EP0TxPktRdy. PLIB_USBHS_EP0TxPktRdyDataEnd This is function PLIB_USBHS_EP0TxPktRdyDataEnd. PLIB_USBHS_HostRxEndpointConfigure This is function PLIB_USBHS_HostRxEndpointConfigure. PLIB_USBHS_HostTxEndpointConfigure This is function PLIB_USBHS_HostTxEndpointConfigure. PLIB_USBHS_RxEPINTokenSend This is function PLIB_USBHS_RxEPINTokenSend. PLIB_USBHS_RxEPStatusClear This is function PLIB_USBHS_RxEPStatusClear. PLIB_USBHS_RxEPStatusGet This is function PLIB_USBHS_RxEPStatusGet. PLIB_USBHS_TxEPStatusClear This is function PLIB_USBHS_TxEPStatusClear. PLIB_USBHS_TxEPStatusGet This is function PLIB_USBHS_TxEPStatusGet. PLIB_USBHS_GetEP0CSRAddress This is function PLIB_USBHS_GetEP0CSRAddress. PLIB_USBHS_GetEP0FIFOAddress This is function PLIB_USBHS_GetEP0FIFOAddress. PLIB_USBHS_LoadEPInIndex This is function PLIB_USBHS_LoadEPInIndex. c) Interrupts Functions Name Description PLIB_USBHS_TxInterruptDisable Disables a TX endpoint interrupt source for the USB module. PLIB_USBHS_TxInterruptEnable Enables a TX endpoint Interrupt for the USB module. PLIB_USBHS_GenInterruptDisable Disables a general interrupt for the USB module. PLIB_USBHS_GenInterruptEnable Enables a general interrupt for the USB module. PLIB_USBHS_GenInterruptFlagsGet Gets general interrupt flags. PLIB_USBHS_InterruptEnableSet Enables USB module event interrupts. PLIB_USBHS_DMAInterruptDisable Disables DMA channel interrupts. PLIB_USBHS_DMAInterruptEnable Enables DMA channel interrupts. PLIB_USBHS_DMAInterruptFlagsGet Gets the DMA channel interrupt flags. PLIB_USBHS_TxInterruptFlagsGet Gets the TX endpoint interrupt flags. PLIB_USBHS_RxInterruptDisable Disables a RX endpoint interrupt for the USB module. PLIB_USBHS_RxInterruptEnable Enables a RX endpoint interrupt for the USB module. PLIB_USBHS_RxInterruptFlagsGet Gets RX endpoint interrupt flags. PLIB_USBHS_DMAInterruptGet This is function PLIB_USBHS_DMAInterruptGet. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2312 PLIB_USBHS_GlobalInterruptDisable This is function PLIB_USBHS_GlobalInterruptDisable. PLIB_USBHS_GlobalInterruptEnable This is function PLIB_USBHS_GlobalInterruptEnable. d) Device Functions Name Description PLIB_USBHS_DeviceAddressGet Returns the current USB device address. PLIB_USBHS_DeviceAddressSet Sets the device address. PLIB_USBHS_DeviceAttach This is function PLIB_USBHS_DeviceAttach. PLIB_USBHS_DeviceConnect Tri-states the USB D+ and D- lines. PLIB_USBHS_DeviceDetach This is function PLIB_USBHS_DeviceDetach. PLIB_USBHS_DeviceDisconnect Tri-states the USB D+ and D- lines. PLIB_USBHS_DeviceEPFIFOLoad This is function PLIB_USBHS_DeviceEPFIFOLoad. PLIB_USBHS_DeviceEPFIFOUnload This is function PLIB_USBHS_DeviceEPFIFOUnload. PLIB_USBHS_DeviceRxEndpointConfigure This is function PLIB_USBHS_DeviceRxEndpointConfigure. PLIB_USBHS_DeviceRxEndpointStallDisable This is function PLIB_USBHS_DeviceRxEndpointStallDisable. PLIB_USBHS_DeviceRxEndpointStallEnable This is function PLIB_USBHS_DeviceRxEndpointStallEnable. PLIB_USBHS_DeviceTxEndpointConfigure This is function PLIB_USBHS_DeviceTxEndpointConfigure. PLIB_USBHS_DeviceTxEndpointPacketReady This is function PLIB_USBHS_DeviceTxEndpointPacketReady. PLIB_USBHS_DeviceTxEndpointStallDisable This is function PLIB_USBHS_DeviceTxEndpointStallDisable. PLIB_USBHS_DeviceTxEndpointStallEnable This is function PLIB_USBHS_DeviceTxEndpointStallEnable. e) Host Functions Name Description PLIB_USBHS_HostRxEndpointDataToggleClear This is function PLIB_USBHS_HostRxEndpointDataToggleClear. PLIB_USBHS_HostTxEndpointDataToggleClear This is function PLIB_USBHS_HostTxEndpointDataToggleClear. f) Status Functions Name Description PLIB_USBHS_FullOrHighSpeedIsConnected This is function PLIB_USBHS_FullOrHighSpeedIsConnected. PLIB_USBHS_HighSpeedIsConnected This is function PLIB_USBHS_HighSpeedIsConnected. PLIB_USBHS_HostModeIsEnabled This is function PLIB_USBHS_HostModeIsEnabled. PLIB_USBHS_ModuleSpeedGet Returns the speed at which the module is operating. PLIB_USBHS_DMAErrorGet This is function PLIB_USBHS_DMAErrorGet. PLIB_USBHS_GetReceiveDataCount This is function PLIB_USBHS_GetReceiveDataCount. g) VBUS Support Functions Name Description PLIB_USBHS_VbusLevelGet Returns the current VBUS level encode using the USBHS_VBUS_DETECT_LEVEL enumeration. PLIB_USBHS_VBUSLevelGet This is function PLIB_USBHS_VBUSLevelGet. h) Feature Existence Functions Name Description PLIB_USBHS_ExistsEndpointFIFO Identifies that the Endpoint FIFO feature exists on the Hi-Speed USB module. PLIB_USBHS_ExistsEndpointOperations This is function PLIB_USBHS_ExistsEndpointOperations. PLIB_USBHS_ExistsEP0Status This is function PLIB_USBHS_ExistsEP0Status. PLIB_USBHS_ExistsHighSpeedSupport This is function PLIB_USBHS_ExistsHighSpeedSupport. PLIB_USBHS_ExistsInterrupts This is function PLIB_USBHS_ExistsInterrupts. PLIB_USBHS_ExistsModuleControl This is function PLIB_USBHS_ExistsModuleControl. PLIB_USBHS_ExistsRxEPStatus This is function PLIB_USBHS_ExistsRxEPStatus. PLIB_USBHS_ExistsSoftReset This is function PLIB_USBHS_ExistsSoftReset. PLIB_USBHS_ExistsTxEPStatus This is function PLIB_USBHS_ExistsTxEPStatus. PLIB_USBHS_ExistsClockResetControl This is function PLIB_USBHS_ExistsClockResetControl. PLIB_USBHS_ExistsUSBIDControl This is function PLIB_USBHS_ExistsUSBIDControl. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2313 i) Data Types and Constants Name Description USBHS_CONFIGURATION Provides the enumeration Configuration bits. USBHS_DATA01 Provides an enumeration data toggle for a packet. USBHS_DMA_ASSERT_TIMING Provides enumeration DMA assertion timing (early versus late). USBHS_DMA_BURST_MODE Provides enumeration of all DMA burst modes. USBHS_DMA_INTERRUPT Provides enumeration of interrupts for DMA channels 0-7. USBHS_DMA_REQUEST_MODE Used as an argument to set DMA request mode. USBHS_DMA_TRANSFER_MODE Provides enumeration of all DMA transfer modes. USBHS_DYN_FIFO_PACKET_BUFFERING Provides enumeration of dynamic FIFO double-packet versus single-packet buffering. USBHS_DYN_FIFO_SIZE Provides enumeration of dynamic FIFO sizes. USBHS_ENDPOINT_DIRECTION Used as an argument to identify an endpoint direction. USBHS_LPM_INTERRUPT Provides an enumeration of LPM interrupt sources. USBHS_LPM_LINK_STATE Provides enumeration requested device state after accepting an LPM transaction. USBHS_LPM_MODE Provides enumeration of Link Power Management (LPM) modes. USBHS_OPMODES Provides enumeration of operating modes supported by USB. USBHS_PKTS_PER_MICROFRAME Provides an enumeration of the allowable isochronous packets per microframe when operating in High-Speed mode. USBHS_SPEED Provides enumeration Host endpoint speeds. USBHS_TEST_SPEED Used as an argument for in setting module speeds in Test mode. USBHS_TRANSACTION_TYPE Provides an enumeration of transaction types. USBHS_TXRX_FIFO_STATE Provides enumeration of receive and transmit FIFO states, as reported by status bits. USBHS_MAX_DMA_CHANNEL_NUMBER Number of available DMA Channels. USBHS_MAX_EP_NUMBER Maximum number of endpoints supported (not including EP0). Description This section describes the Application Programming Interface (API) functions of the USBHS Peripheral Library. Refer to each section for a detailed description. a) USBHS Setup Functions PLIB_USBHS_HighSpeedDisable Function File plib_usbhs.h C void PLIB_USBHS_HighSpeedDisable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_HighSpeedDisable. PLIB_USBHS_HighSpeedEnable Function Sets the operation speed of the USB Module. File plib_usbhs.h C void PLIB_USBHS_HighSpeedEnable(USBHS_MODULE_ID index); Returns None. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2314 Description This function sets the operation speed of the USB module. Remarks None. Preconditions None. Example // Enable the USB module for high speed support. PLIB_USBHS_HighSpeedEnable(USBHS_ID_0, USB_SPEED_HIGH); Parameters Parameters Description index Identifier for the device instance to be configured speed The operation speed of the USB module Function void PLIB_USBHS_ModuleSpeedSet(USBHS_MODULE_ID index, uint32_t speed) PLIB_USBHS_ResetDisable Function File plib_usbhs.h C void PLIB_USBHS_ResetDisable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ResetDisable. PLIB_USBHS_ResetEnable Function File plib_usbhs.h C void PLIB_USBHS_ResetEnable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ResetEnable. PLIB_USBHS_ResumeDisable Function File plib_usbhs.h C void PLIB_USBHS_ResumeDisable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ResumeDisable. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2315 PLIB_USBHS_ResumeEnable Function File plib_usbhs.h C void PLIB_USBHS_ResumeEnable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ResumeEnable. PLIB_USBHS_SessionDisable Function File plib_usbhs.h C void PLIB_USBHS_SessionDisable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_SessionDisable. PLIB_USBHS_SessionEnable Function File plib_usbhs.h C void PLIB_USBHS_SessionEnable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_SessionEnable. PLIB_USBHS_SoftResetDisable Function Disables soft reset. File plib_usbhs.h C void PLIB_USBHS_SoftResetDisable(USBHS_MODULE_ID index); Returns None. Description This function disables soft reset. Remarks Valid in both Peripheral and Host mode. Preconditions None. Example PLIB_USBHS_SoftResetDisable(USBHS_ID_0); Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2316 Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USBHS_SoftResetDisable(USBHS_MODULE_ID index); PLIB_USBHS_SoftResetEnable Function Enables soft reset. File plib_usbhs.h C void PLIB_USBHS_SoftResetEnable(USBHS_MODULE_ID index); Returns None. Description This function enables soft reset. Remarks Valid in both Peripheral and Host mode. Preconditions None. Example PLIB_USBHS_SoftResetEnable(USBHS_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USBHS_SoftResetEnable(USBHS_MODULE_ID index); PLIB_USBHS_SuspendDisable Function File plib_usbhs.h C void PLIB_USBHS_SuspendDisable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_SuspendDisable. PLIB_USBHS_SuspendEnable Function File plib_usbhs.h C void PLIB_USBHS_SuspendEnable(USBHS_MODULE_ID index); Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2317 Description This is function PLIB_USBHS_SuspendEnable. PLIB_USBHS_DMAOperationEnable Function File plib_usbhs.h C void PLIB_USBHS_DMAOperationEnable(USBHS_MODULE_ID index, uint8_t endpoint, uint8_t dmaChannel, void * address, uint32_t count, bool direction); Description This is function PLIB_USBHS_DMAOperationEnable. PLIB_USBHS_TestModeEnter Function File plib_usbhs.h C bool PLIB_USBHS_TestModeEnter(USBHS_MODULE_ID index, uint8_t testMode); Description This is function PLIB_USBHS_TestModeEnter. PLIB_USBHS_TestModeExit Function File plib_usbhs.h C bool PLIB_USBHS_TestModeExit(USBHS_MODULE_ID index, uint8_t testMode); Description This is function PLIB_USBHS_TestModeExit. PLIB_USBHS_PhyIDMonitoringDisable Function File plib_usbhs.h C void PLIB_USBHS_PhyIDMonitoringDisable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_PhyIDMonitoringDisable. PLIB_USBHS_PhyIDMonitoringEnable Function File plib_usbhs.h C void PLIB_USBHS_PhyIDMonitoringEnable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_PhyIDMonitoringEnable. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2318 PLIB_USBHS_USBIDOverrideDisable Function File plib_usbhs.h C void PLIB_USBHS_USBIDOverrideDisable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_USBIDOverrideDisable. PLIB_USBHS_USBIDOverrideEnable Function File plib_usbhs.h C void PLIB_USBHS_USBIDOverrideEnable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_USBIDOverrideEnable. PLIB_USBHS_USBIDOverrideValueSet Function File plib_usbhs.h C void PLIB_USBHS_USBIDOverrideValueSet(USBHS_MODULE_ID index, USBHS_USBID_OVERRIDE_VALUE id); Description This is function PLIB_USBHS_USBIDOverrideValueSet. PLIB_USBHS_IsBDevice Function File plib_usbhs.h C bool PLIB_USBHS_IsBDevice(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_IsBDevice. b) Endpoints Functions PLIB_USBHS_Endpoint0FIFOFlush Function File plib_usbhs.h C void PLIB_USBHS_Endpoint0FIFOFlush(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_Endpoint0FIFOFlush. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2319 PLIB_USBHS_Endpoint0SetupPacketLoad Function Loads the endpoint 0 FIFO with provided setup packet and then enables the endpoint transmit. File plib_usbhs.h C void PLIB_USBHS_Endpoint0SetupPacketLoad(USBHS_MODULE_ID index, void * setupPacket, uint8_t deviceAddress, uint8_t hubAddress, uint8_t hubPortAddress, uint32_t speed); Returns None. Description This function loads the endpoint 0 FIFO with provided setup packet. This operation would typically be performed at the start of a endpoint 0 control transfer. Once the FIFO is loaded the function will load the target device address, hub and hub port address and then transmit the packet. Remarks Valid in Host mode only. Setup packet size should be 8 bytes. Packet will always be targeted to endpoint 0 of the target device. Preconditions None. Example // Send a setup packet to device 7 control endpoint // connected directly to module. PLIB_USBHS_Endpoint0SetupPacketLoad(USBHS_ID_0, setupPacket, 7, 0, 0, USB_SPEED_HIGH); Parameters Parameters Description index Identifier for the device instance to be configured setupPacket setup packet to be sent to the device deviceAddress USB address of the device hubAddress USB address of the hub if the device is connected to a hub. Should be zero otherwise. hubPortAddress Port number of the hub port to which the device is connected if it is connected to a hub. Should be zero otherwise. speed Speed of the device to which the packet should be sent. Function void PLIB_USBHS_Endpoint0SetupPacketLoad(USBHS_MODULE_ID index, void * setupPacket, uint8_t deviceAddress, uint8_t hubAddress, uint8_t hubPortAddress, uint32_t speed) PLIB_USBHS_Endpoint0SetupPacketUnload Function File plib_usbhs.h C void PLIB_USBHS_Endpoint0SetupPacketUnload(USBHS_MODULE_ID index, void * dest); Description This is function PLIB_USBHS_Endpoint0SetupPacketUnload. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2320 PLIB_USBHS_EndpointFIFOLoad Function Loads the endpoint FIFO with provided data and then enables the endpoint transmit. File plib_usbhs.h C void PLIB_USBHS_EndpointFIFOLoad(USBHS_MODULE_ID index, uint8_t endpoint, void * source, size_t nBytes); Returns None. Description This function loads the endpoint FIFO with provided data. This operation would typically be performed for a endpoint transmit operation. Once the FIFO is loaded the function will enable the enable the endpoint for transmit. Remarks Valid in both Peripheral and Host mode. Preconditions None. Example // Load endpoint 1 FIFO PLIB_USBHS_EndpointFIFOLoad(USBHS_ID_0, 1, data, 10); Parameters Parameters Description index Identifier for the device instance to be configured endpoint endpoint of which FIFO needs to be loaded source data that should be loaded nBytes number of bytes to load. Function void PLIB_USBHS_EndpointFIFOLoad(USBHS_MODULE_ID index, uint8_t endpoint, void * source, size_t nBytes) PLIB_USBHS_EndpointFIFOUnload Function Unloads the endpoint FIFO. File plib_usbhs.h C int PLIB_USBHS_EndpointFIFOUnload(USBHS_MODULE_ID index, uint8_t endpoint, void * dest); Returns Returns the number of functions that were read. Description This function unloads the endpoint FIFO. This operation would typically be performed for a endpoint receive operation. The unloaded data is stored in provided buffer. Remarks Valid in both Peripheral and Host mode. Preconditions The USB module must be configured for Device mode operation. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2321 Example // Load endpoint 1 FIFO int count; count = PLIB_USBHS_EndpointFIFOUnload(USBHS_ID_0, 1, dest, 10); Parameters Parameters Description index Identifier for the device instance to be configured endpoint endpoint of which FIFO to be unloaded. dest target address where unloaded data should be stored. Function int PLIB_USBHS_EndpointFIFOUnload(USBHS_MODULE_ID index, uint8_t endpoint, void * destination) PLIB_USBHS_EndpointRxFIFOFlush Function File plib_usbhs.h C void PLIB_USBHS_EndpointRxFIFOFlush(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_EndpointRxFIFOFlush. PLIB_USBHS_EndpointRxRequestClear Function File plib_usbhs.h C void PLIB_USBHS_EndpointRxRequestClear(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_EndpointRxRequestClear. PLIB_USBHS_EndpointRxRequestEnable Function File plib_usbhs.h C void PLIB_USBHS_EndpointRxRequestEnable(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_EndpointRxRequestEnable. PLIB_USBHS_EndpointTxFIFOFlush Function File plib_usbhs.h C void PLIB_USBHS_EndpointTxFIFOFlush(USBHS_MODULE_ID index, uint8_t endpoint); Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2322 Description This is function PLIB_USBHS_EndpointTxFIFOFlush. PLIB_USBHS_EP0DataEndSet Function File plib_usbhs.h C void PLIB_USBHS_EP0DataEndSet(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0DataEndSet. PLIB_USBHS_EP0INHandshakeClear Function File plib_usbhs.h C void PLIB_USBHS_EP0INHandshakeClear(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0INHandshakeClear. PLIB_USBHS_EP0INHandshakeSend Function File plib_usbhs.h C void PLIB_USBHS_EP0INHandshakeSend(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0INHandshakeSend. PLIB_USBHS_EP0INTokenSend Function File plib_usbhs.h C void PLIB_USBHS_EP0INTokenSend(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0INTokenSend. PLIB_USBHS_EP0OUTHandshakeSend Function File plib_usbhs.h C void PLIB_USBHS_EP0OUTHandshakeSend(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0OUTHandshakeSend. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2323 PLIB_USBHS_EP0RxPktRdyServiced Function File plib_usbhs.h C void PLIB_USBHS_EP0RxPktRdyServiced(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0RxPktRdyServiced. PLIB_USBHS_EP0RxPktRdyServicedDataEnd Function File plib_usbhs.h C void PLIB_USBHS_EP0RxPktRdyServicedDataEnd(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0RxPktRdyServicedDataEnd. PLIB_USBHS_EP0SentStallClear Function File plib_usbhs.h C void PLIB_USBHS_EP0SentStallClear(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0SentStallClear. PLIB_USBHS_EP0SetupEndServiced Function File plib_usbhs.h C void PLIB_USBHS_EP0SetupEndServiced(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0SetupEndServiced. PLIB_USBHS_EP0StallDisable Function File plib_usbhs.h C void PLIB_USBHS_EP0StallDisable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0StallDisable. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2324 PLIB_USBHS_EP0StallEnable Function File plib_usbhs.h C void PLIB_USBHS_EP0StallEnable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0StallEnable. PLIB_USBHS_EP0StatusClear Function File plib_usbhs.h C void PLIB_USBHS_EP0StatusClear(USBHS_MODULE_ID index, USBHS_EP0_ERROR error); Description This is function PLIB_USBHS_EP0StatusClear. PLIB_USBHS_EP0StatusGet Function File plib_usbhs.h C uint8_t PLIB_USBHS_EP0StatusGet(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0StatusGet. PLIB_USBHS_EP0TxPktRdy Function File plib_usbhs.h C void PLIB_USBHS_EP0TxPktRdy(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0TxPktRdy. PLIB_USBHS_EP0TxPktRdyDataEnd Function File plib_usbhs.h C void PLIB_USBHS_EP0TxPktRdyDataEnd(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_EP0TxPktRdyDataEnd. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2325 PLIB_USBHS_HostRxEndpointConfigure Function File plib_usbhs.h C void PLIB_USBHS_HostRxEndpointConfigure(USBHS_MODULE_ID index, uint8_t hostEndpoint, uint32_t speed, uint32_t pipeType, uint16_t endpointSize, uint16_t receiveFIFOAddress, uint16_t fifoSize, uint8_t targetEndpoint, uint8_t targetDevice, uint8_t targetHub, uint8_t targetHubPort, uint8_t nakInterval); Description This is function PLIB_USBHS_HostRxEndpointConfigure. PLIB_USBHS_HostTxEndpointConfigure Function File plib_usbhs.h C void PLIB_USBHS_HostTxEndpointConfigure(USBHS_MODULE_ID index, uint8_t hostEndpoint, uint32_t speed, uint32_t pipeType, uint16_t endpointSize, uint16_t receiveFIFOAddress, uint16_t fifoSize, uint8_t targetEndpoint, uint8_t targetDevice, uint8_t targetHub, uint8_t targetHubPort, uint8_t nakInterval); Description This is function PLIB_USBHS_HostTxEndpointConfigure. PLIB_USBHS_RxEPINTokenSend Function File plib_usbhs.h C void PLIB_USBHS_RxEPINTokenSend(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_RxEPINTokenSend. PLIB_USBHS_RxEPStatusClear Function File plib_usbhs.h C void PLIB_USBHS_RxEPStatusClear(USBHS_MODULE_ID index, uint8_t endpoint, USBHS_RXEP_ERROR error); Description This is function PLIB_USBHS_RxEPStatusClear. PLIB_USBHS_RxEPStatusGet Function File plib_usbhs.h C uint8_t PLIB_USBHS_RxEPStatusGet(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_RxEPStatusGet. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2326 PLIB_USBHS_TxEPStatusClear Function File plib_usbhs.h C void PLIB_USBHS_TxEPStatusClear(USBHS_MODULE_ID index, uint8_t endpoint, USBHS_TXEP_ERROR error); Description This is function PLIB_USBHS_TxEPStatusClear. PLIB_USBHS_TxEPStatusGet Function File plib_usbhs.h C uint8_t PLIB_USBHS_TxEPStatusGet(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_TxEPStatusGet. PLIB_USBHS_GetEP0CSRAddress Function File plib_usbhs.h C uint8_t * PLIB_USBHS_GetEP0CSRAddress(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_GetEP0CSRAddress. PLIB_USBHS_GetEP0FIFOAddress Function File plib_usbhs.h C uint8_t * PLIB_USBHS_GetEP0FIFOAddress(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_GetEP0FIFOAddress. PLIB_USBHS_LoadEPInIndex Function File plib_usbhs.h C void PLIB_USBHS_LoadEPInIndex(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_LoadEPInIndex. c) Interrupts Functions Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2327 PLIB_USBHS_TxInterruptDisable Function Disables a TX endpoint interrupt source for the USB module. File plib_usbhs.h C void PLIB_USBHS_TxInterruptDisable(USBHS_MODULE_ID index, USBHS_EPTXRX_INTERRUPT interruptFlag); Returns None. Description This function disables a TX endpoint interrupt source for the USB module. Remarks See also PLIB_USBHS_TxInterruptEnable. Preconditions None. Example PLIB_USBHS_TxInterruptDisable( MY_USB_INSTANCE, USBHS_TXRXINT_EP1 ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USBHS_TxInterruptDisable( USBHS_MODULE_ID index, USBHS_EPTXRX_INTERRUPT interruptFlag ) PLIB_USBHS_TxInterruptEnable Function Enables a TX endpoint Interrupt for the USB module. File plib_usbhs.h C void PLIB_USBHS_TxInterruptEnable(USBHS_MODULE_ID index, USBHS_EPTXRX_INTERRUPT interruptFlag); Returns None. Description This function enables the TX endpoint interrupt sources of the USB module that are used to trigger a USB interrupt. Remarks See also PLIB_USBHS_TxInterruptDisable. Preconditions None. Example PLIB_USBHS_TxInterruptEnable( MY_USB_INSTANCE, USBHS_TXRXINT_EP1 ); Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2328 Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USBHS_TxInterruptEnable( USBHS_MODULE_ID index, USBHS_EPTXRX_INTERRUPT interruptFlag ) PLIB_USBHS_GenInterruptDisable Function Disables a general interrupt for the USB module. File plib_usbhs.h C void PLIB_USBHS_GenInterruptDisable(USBHS_MODULE_ID index, USBHS_GEN_INTERRUPT interruptFlag); Returns None. Description This function disables a general interrupt source for the USB module. Remarks See also PLIB_USBHS_GenInterruptEnable. Preconditions None. Example PLIB_USBHS_GenInterruptDisable( MY_USB_INSTANCE, USBHS_GENINT_VBUSERR ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USBHS_GenInterruptDisable( USBHS_MODULE_ID index, USBHS_GEN_INTERRUPT interruptFlag ) PLIB_USBHS_GenInterruptEnable Function Enables a general interrupt for the USB module. File plib_usbhs.h C void PLIB_USBHS_GenInterruptEnable(USBHS_MODULE_ID index, USBHS_GEN_INTERRUPT interruptFlag); Returns None. Description This function enables the general interrupt sources of the USB module that are used to trigger a USB interrupt. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2329 Remarks See also PLIB_USBHS_GenInterruptDisable. Preconditions None. Example PLIB_USBHS_GenInterruptEnable( MY_USB_INSTANCE, USBHS_GENINT_VBUSERR ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USBHS_GenInterruptEnable( USBHS_MODULE_ID index, USBHS_GEN_INTERRUPT interruptFlag ) PLIB_USBHS_GenInterruptFlagsGet Function Gets general interrupt flags. File plib_usbhs.h C USBHS_GEN_INTERRUPT PLIB_USBHS_GenInterruptFlagsGet(USBHS_MODULE_ID index); Returns None. Description This function gets the general interrupt flags. Remarks None. Preconditions None. Example USBHS_GEN_INTERRUPT interruptFlags; interruptFlags = PLIB_USBHS_GenInterruptFlagsGet( MY_USB_INSTANCE ); // All interrupt flags cleared on read. if ( interruptFlags > 0 ) if ( interruptFlags & USBHS_GENINT_SUSPEND ) { // Device has detected suspend signaling on the bus. } if ( interruptFlags & USBHS_GENINT_RESUME ) { // } . . . } Parameters Parameters Description index Identifier for the device instance of interest Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2330 Function USBHS_GEN_INTERRUPT PLIB_USBHS_GenInterruptFlagsGet( USBHS_MODULE_ID index ) PLIB_USBHS_InterruptEnableSet Function Enables USB module event interrupts. File plib_usbhs.h C void PLIB_USBHS_InterruptEnableSet(USBHS_MODULE_ID index, USBHS_GEN_INTERRUPT generalInterrupts, USBHS_EPTXRX_INTERRUPT transmitInterrupts, USBHS_EPTXRX_INTERRUPT receiveInterrupts); Returns None. Description This function enables USB module event interrupts. Combines the functionality of the PLIB_USBHS_RxInterruptEnable, PLIB_USBHS_TxInterruptEnable, and PLIB_USBHS_GenInterruptEnable functions. Remarks None. Preconditions None. Example // Enable the reset interrupt, endpoint 1 transmit interrupt // and endpoint 2 receive interrupts PLIB_USBHS_InterruptEnableSet (USBHS_ID_0, USBHS_GENINT_RESET, USBHS_TXRXINT_EP1, USBHS_TXRXINT_EP2 ); Parameters Parameters Description index Identifier for the device instance of interest generalInterrupts General Module interrupts. transmitInterrupts Transmit Endpoint Interrupts to be enabled. receiveInterrupts Receive Endpoint Interrupts to be enabled. Function void PLIB_USBHS_InterruptEnableSet( USBHS_MODULE_ID index, USBHS_GEN_INTERRUPT generalInterrupts, USBHS_EPTXRX_INTERRUPT transmitInterrupts, USBHS_EPTXRX_INTERRUPT receiveInterrupts); PLIB_USBHS_DMAInterruptDisable Function Disables DMA channel interrupts. File plib_usbhs.h C void PLIB_USBHS_DMAInterruptDisable(USBHS_MODULE_ID index, USBHS_DMA_INTERRUPT nChannelNumber); Returns None. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2331 Description This function disables DMA Channel interrupts. Remarks None. Preconditions None. Example PLIB_USBHS_DMAInterruptDisable (USBHS_ID_0, USBHS_DMAINT_5); Parameters Parameters Description index Identifier for the device instance of interest dmaChannelInterrupt DMA channel Interrupt to disable Function void PLIB_USBHS_DMAInterruptDisable( USBHS_MODULE_ID index, USBHS_DMA_INTERRUPT dmaChannelInterrupt ) PLIB_USBHS_DMAInterruptEnable Function Enables DMA channel interrupts. File plib_usbhs.h C void PLIB_USBHS_DMAInterruptEnable(USBHS_MODULE_ID index, USBHS_DMA_INTERRUPT nChannelNumber); Returns None. Description This function enables DMA Channel interrupts. Remarks None. Preconditions None. Example PLIB_USBHS_DMAInterruptEnable (USBHS_ID_0, USBHS_DMAINT_5); Parameters Parameters Description index Identifier for the device instance of interest dmaChannelInterrupt DMA channel Interrupt to enable Function void PLIB_USBHS_DMAInterruptEnable( USBHS_MODULE_ID index, USBHS_DMA_INTERRUPT dmaChannelInterrupt ) PLIB_USBHS_DMAInterruptFlagsGet Function Gets the DMA channel interrupt flags. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2332 File plib_usbhs.h C USBHS_DMA_INTERRUPT PLIB_USBHS_DMAInterruptFlagsGet(USBHS_MODULE_ID index); Returns None. Description This function gets the DMA channel interrupt flags. Remarks None. Preconditions None. Example USBHS_DMA_INTERRUPT interruptFlags; interruptFlags = PLIB_USBHS_DMAInterruptFlagsGet( MY_USB_INSTANCE ); // All interrupt flags cleared on read. if ( interruptFlags > 0 ) if ( interruptFlags & USBHS_DMAINT_1 ) { // DMA Channel 1 } if (interruptFlags & USBHS_DMAINT_2) { // DMA Channel 2 } . . . } Parameters Parameters Description index Identifier for the device instance of interest Function USBHS_DMA_INTERRUPT PLIB_USBHS_DMAInterruptFlagsGet( USBHS_MODULE_ID index ) PLIB_USBHS_TxInterruptFlagsGet Function Gets the TX endpoint interrupt flags. File plib_usbhs.h C USBHS_EPTXRX_INTERRUPT PLIB_USBHS_TxInterruptFlagsGet(USBHS_MODULE_ID index); Returns None. Description This function gets the TX endpoint interrupt flags. Remarks TX interrupts must first be enabled by calling PLIB_USBHS_TxInterruptEnable. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2333 Preconditions None. Example USBHS_EPTXRX_INTERRUPT interruptFlags; interruptFlags = PLIB_USBHS_TxInterruptFlagsGet( MY_USB_INSTANCE ); // All interrupt flags cleared on read. if ( interruptFlags > 0 ) if ( interruptFlags & USBHS_TXRXINT_EP0 ) { // Endpoint Zero } if ( interruptFlags & USBHS_TXRXINT_EP1 ) { // Endpoint One } . . . } Parameters Parameters Description index Identifier for the device instance of interest Function USBHS_EPTXRX_INTERRUPT PLIB_USBHS_TxInterruptFlagsGet( USBHS_MODULE_ID index ) PLIB_USBHS_RxInterruptDisable Function Disables a RX endpoint interrupt for the USB module. File plib_usbhs.h C void PLIB_USBHS_RxInterruptDisable(USBHS_MODULE_ID index, USBHS_EPTXRX_INTERRUPT interruptFlag); Returns None. Description This function disables a RX endpoint interrupt source for the USB module. Remarks See also PLIB_USBHS_RxInterruptEnable. USBHS_TXRXINT_EP0 is not a valid argument. For endpoint zero, use PLIB_USBHS_TxInterruptDisable. Preconditions None. Example PLIB_USBHS_RxInterruptDisable( MY_USB_INSTANCE, USBHS_TXRXINT_EP1 ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USBHS_RxInterruptDisable( USBHS_MODULE_ID index, Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2334 USBHS_EPTXRX_INTERRUPT interruptFlag ) PLIB_USBHS_RxInterruptEnable Function Enables a RX endpoint interrupt for the USB module. File plib_usbhs.h C void PLIB_USBHS_RxInterruptEnable(USBHS_MODULE_ID index, USBHS_EPTXRX_INTERRUPT interruptFlag); Returns None. Description This function enables RX endpoint interrupt sources of the USB module to trigger a USB interrupt. Remarks See also PLIB_USBHS_RxInterruptDisable. USBHS_TXRXINT_EP0 is not a valid argument. For endpoint zero use PLIB_USBHS_TxInterruptEnable. Preconditions None. Example PLIB_USBHS_RxInterruptEnable( MY_USB_INSTANCE, USBHS_TXRXINT_EP1 ); Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Function void PLIB_USBHS_RxInterruptEnable( USBHS_MODULE_ID index, USBHS_EPTXRX_INTERRUPT interruptFlag ) PLIB_USBHS_RxInterruptFlagsGet Function Gets RX endpoint interrupt flags. File plib_usbhs.h C USBHS_EPTXRX_INTERRUPT PLIB_USBHS_RxInterruptFlagsGet(USBHS_MODULE_ID index); Returns None. Description This function gets the RX endpoint interrupt flags. Remarks RX interrupts must first be enabled by calling PLIB_USBHS_RxInterruptEnable. USBHS_TXRXINT_EP0 is not a valid argument. For endpoint zero use PLIB_USBHS_TxInterruptFlagsGet. Preconditions None. Example USBHS_EPTXRX_INTERRUPT interruptFlags; Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2335 interruptFlags = PLIB_USBHS_RxInterruptFlagsGet( MY_USB_INSTANCE ); // All interrupt flags cleared on read. if ( interruptFlags > 0 ) if ( interruptFlags & USBHS_TXRXINT_EP1 ) { // Endpoint Zero } if ( interruptFlags & USBHS_TXRXINT_EP2 ) { // Endpoint One } . . . } Parameters Parameters Description index Identifier for the device instance of interest Function USBHS_EPTXRX_INTERRUPT PLIB_USBHS_RxInterruptFlagsGet( USBHS_MODULE_ID index ) PLIB_USBHS_DMAInterruptGet Function File plib_usbhs.h C uint8_t PLIB_USBHS_DMAInterruptGet(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_DMAInterruptGet. PLIB_USBHS_GlobalInterruptDisable Function File plib_usbhs.h C void PLIB_USBHS_GlobalInterruptDisable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_GlobalInterruptDisable. PLIB_USBHS_GlobalInterruptEnable Function File plib_usbhs.h C void PLIB_USBHS_GlobalInterruptEnable(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_GlobalInterruptEnable. d) Device Functions Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2336 PLIB_USBHS_DeviceAddressGet Function Returns the current USB device address. File plib_usbhs.h C uint8_t PLIB_USBHS_DeviceAddressGet(USBHS_MODULE_ID index); Returns 7-bit unsigned integer value indicating the current USB device address. Description This function returns the current USB device address. Remarks None. Preconditions The USB module should have been configured for Device mode operation. Example // This code example reads the current assigned USB device address. uint8_t address; address = PLIB_USBHS_DeviceAddressGet(USBHS_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function uint8_t PLIB_USBHS_DeviceAddressGet (USBHS_MODULE_ID index) PLIB_USBHS_DeviceAddressSet Function Sets the device address. File plib_usbhs.h C void PLIB_USBHS_DeviceAddressSet(USBHS_MODULE_ID index, uint8_t address); Returns None. Description This function sets the device address. This function should be called with the address received from the host in the SET_ADDRESS request. Remarks None. Preconditions The USB module must be configured for Device mode operation. Example // This code example assigns a USB device address. uint8_t address; Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2337 PLIB_USBHS_DeviceAddressSet(USBHS_ID_0, address); Parameters Parameters Description index Identifier for the device instance to be configured address 7-bit USB Device address that should be assigned to this device Function void PLIB_USBHS_DeviceAddressSet (USBHS_MODULE_ID index, uint8_t address) PLIB_USBHS_DeviceAttach Function File plib_usbhs.h C void PLIB_USBHS_DeviceAttach(USBHS_MODULE_ID index, uint32_t speed); Description This is function PLIB_USBHS_DeviceAttach. PLIB_USBHS_DeviceConnect Function Tri-states the USB D+ and D- lines. File plib_usbhs.h C void PLIB_USBHS_DeviceConnect(USBHS_MODULE_ID index); Returns None. Description This function enables the USB D+ and D- lines, which connects the device from the host. Remarks Only valid for Device mode. Preconditions The USB module must be configured for Device mode operation. Example // Disconnect the device from the host PLIB_USBHS_DeviceConnect(USBHS_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USBHS_DeviceConnect(USBHS_MODULE_ID index) PLIB_USBHS_DeviceDetach Function File plib_usbhs.h Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2338 C void PLIB_USBHS_DeviceDetach(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_DeviceDetach. PLIB_USBHS_DeviceDisconnect Function Tri-states the USB D+ and D- lines. File plib_usbhs.h C void PLIB_USBHS_DeviceDisconnect(USBHS_MODULE_ID index); Returns None. Description This function tri-states the USB D+ and D- lines, which disconnects the device from the host. Remarks Only valid for Device mode. Preconditions None. Example // Disconnect the device from the host PLIB_USBHS_DeviceDisconnect(USBHS_ID_0); Parameters Parameters Description index Identifier for the device instance to be configured Function void PLIB_USBHS_DeviceDisconnect(USBHS_MODULE_ID index) PLIB_USBHS_DeviceEPFIFOLoad Function File plib_usbhs.h C void PLIB_USBHS_DeviceEPFIFOLoad(USBHS_MODULE_ID index, uint8_t endpoint, void * source, size_t nBytes); Description This is function PLIB_USBHS_DeviceEPFIFOLoad. PLIB_USBHS_DeviceEPFIFOUnload Function File plib_usbhs.h C int PLIB_USBHS_DeviceEPFIFOUnload(USBHS_MODULE_ID index, uint8_t endpoint, void * dest); Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2339 Description This is function PLIB_USBHS_DeviceEPFIFOUnload. PLIB_USBHS_DeviceRxEndpointConfigure Function File plib_usbhs.h C void PLIB_USBHS_DeviceRxEndpointConfigure(USBHS_MODULE_ID index, uint8_t endpoint, uint16_t endpointSize, uint16_t fifoAddress, uint8_t fifoSize, uint32_t transferType); Description This is function PLIB_USBHS_DeviceRxEndpointConfigure. PLIB_USBHS_DeviceRxEndpointStallDisable Function File plib_usbhs.h C void PLIB_USBHS_DeviceRxEndpointStallDisable(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_DeviceRxEndpointStallDisable. PLIB_USBHS_DeviceRxEndpointStallEnable Function File plib_usbhs.h C void PLIB_USBHS_DeviceRxEndpointStallEnable(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_DeviceRxEndpointStallEnable. PLIB_USBHS_DeviceTxEndpointConfigure Function File plib_usbhs.h C void PLIB_USBHS_DeviceTxEndpointConfigure(USBHS_MODULE_ID index, uint8_t endpoint, uint16_t endpointSize, uint16_t fifoAddress, uint8_t fifoSize, uint32_t transferType); Description This is function PLIB_USBHS_DeviceTxEndpointConfigure. PLIB_USBHS_DeviceTxEndpointPacketReady Function File plib_usbhs.h C void PLIB_USBHS_DeviceTxEndpointPacketReady(USBHS_MODULE_ID index, uint8_t endpoint); Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2340 Description This is function PLIB_USBHS_DeviceTxEndpointPacketReady. PLIB_USBHS_DeviceTxEndpointStallDisable Function File plib_usbhs.h C void PLIB_USBHS_DeviceTxEndpointStallDisable(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_DeviceTxEndpointStallDisable. PLIB_USBHS_DeviceTxEndpointStallEnable Function File plib_usbhs.h C void PLIB_USBHS_DeviceTxEndpointStallEnable(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_DeviceTxEndpointStallEnable. e) Host Functions PLIB_USBHS_HostRxEndpointDataToggleClear Function File plib_usbhs.h C void PLIB_USBHS_HostRxEndpointDataToggleClear(USBHS_MODULE_ID index, uint8_t hostEndpoint); Description This is function PLIB_USBHS_HostRxEndpointDataToggleClear. PLIB_USBHS_HostTxEndpointDataToggleClear Function File plib_usbhs.h C void PLIB_USBHS_HostTxEndpointDataToggleClear(USBHS_MODULE_ID index, uint8_t hostEndpoint); Description This is function PLIB_USBHS_HostTxEndpointDataToggleClear. f) Status Functions PLIB_USBHS_FullOrHighSpeedIsConnected Function File plib_usbhs.h Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2341 C bool PLIB_USBHS_FullOrHighSpeedIsConnected(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_FullOrHighSpeedIsConnected. PLIB_USBHS_HighSpeedIsConnected Function File plib_usbhs.h C bool PLIB_USBHS_HighSpeedIsConnected(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_HighSpeedIsConnected. PLIB_USBHS_HostModeIsEnabled Function File plib_usbhs.h C bool PLIB_USBHS_HostModeIsEnabled(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_HostModeIsEnabled. PLIB_USBHS_ModuleSpeedGet Function Returns the speed at which the module is operating. File plib_usbhs.h C bool PLIB_USBHS_ModuleSpeedGet(USBHS_MODULE_ID index); Returns Current module operation speed on the USB. Description This function returns the speed at which the module is operating. In case of device mode operation, this function returns the speed at which the device attached to the host. Remarks None. Preconditions None. Example USB_SPEED speed; speed = PLIB_USBHS_ModuleSpeedGet(USBHS_ID_0); Parameters Parameters Description index Identifier for the device instance of interest Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2342 Function USB_SPEED PLIB_USBHS_ModuleSpeedGet( USBHS_MODULE_ID index ) PLIB_USBHS_DMAErrorGet Function File plib_usbhs.h C bool PLIB_USBHS_DMAErrorGet(USBHS_MODULE_ID index, uint8_t dmaChannel); Description This is function PLIB_USBHS_DMAErrorGet. PLIB_USBHS_GetReceiveDataCount Function File plib_usbhs.h C uint32_t PLIB_USBHS_GetReceiveDataCount(USBHS_MODULE_ID index, uint8_t endpoint); Description This is function PLIB_USBHS_GetReceiveDataCount. g) VBUS Support Functions PLIB_USBHS_VbusLevelGet Function Returns the current VBUS level encode using the USBHS_VBUS_DETECT_LEVEL enumeration. File plib_usbhs.h C USBHS_VBUS_LEVEL PLIB_USBHS_VbusLevelGet(USBHS_MODULE_ID index); Returns Detected VBUS level, see USBHS_VBUS_DETECT_LEVEL enumeration. Description Returns the current VBUS level encode using the USBHS_VBUS_DETECT_LEVEL enumeration. Remarks None. Preconditions None. Example Parameters Parameters Description index Identifier for the device instance of interest Function USBHS_VBUS_DETECT_LEVEL PLIB_USBHS_VbusLevelGet( USBHS_MODULE_ID index ) Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2343 PLIB_USBHS_VBUSLevelGet Function File plib_usbhs.h C USBHS_VBUS_LEVEL PLIB_USBHS_VBUSLevelGet(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_VBUSLevelGet. h) Feature Existence Functions PLIB_USBHS_ExistsEndpointFIFO Function Identifies that the Endpoint FIFO feature exists on the Hi-Speed USB module. File plib_usbhs.h C bool PLIB_USBHS_ExistsEndpointFIFO(USBHS_MODULE_ID index); Returns • true - The feature is supported • false - The feature is not supported Description This interface identifies that the Endpoint FIFO feature is available on the Hi-Speed USB module. When this interface returns true, these functions are supported on the device: • PLIB_USBHS_EndpointFIFOLoad • PLIB_USBHS_EndpointFIFOUnload Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_USBHS_ExistsEndpointFIFO( USBHS_MODULE_ID index ) PLIB_USBHS_ExistsEndpointOperations Function File plib_usbhs.h C bool PLIB_USBHS_ExistsEndpointOperations(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsEndpointOperations. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2344 PLIB_USBHS_ExistsEP0Status Function File plib_usbhs.h C bool PLIB_USBHS_ExistsEP0Status(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsEP0Status. PLIB_USBHS_ExistsHighSpeedSupport Function File plib_usbhs.h C bool PLIB_USBHS_ExistsHighSpeedSupport(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsHighSpeedSupport. PLIB_USBHS_ExistsInterrupts Function File plib_usbhs.h C bool PLIB_USBHS_ExistsInterrupts(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsInterrupts. PLIB_USBHS_ExistsModuleControl Function File plib_usbhs.h C bool PLIB_USBHS_ExistsModuleControl(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsModuleControl. PLIB_USBHS_ExistsRxEPStatus Function File plib_usbhs.h C bool PLIB_USBHS_ExistsRxEPStatus(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsRxEPStatus. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2345 PLIB_USBHS_ExistsSoftReset Function File plib_usbhs.h C bool PLIB_USBHS_ExistsSoftReset(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsSoftReset. PLIB_USBHS_ExistsTxEPStatus Function File plib_usbhs.h C bool PLIB_USBHS_ExistsTxEPStatus(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsTxEPStatus. PLIB_USBHS_ExistsClockResetControl Function File plib_usbhs.h C bool PLIB_USBHS_ExistsClockResetControl(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsClockResetControl. PLIB_USBHS_ExistsUSBIDControl Function File plib_usbhs.h C bool PLIB_USBHS_ExistsUSBIDControl(USBHS_MODULE_ID index); Description This is function PLIB_USBHS_ExistsUSBIDControl. i) Data Types and Constants USBHS_CONFIGURATION Enumeration Provides the enumeration Configuration bits. File plib_usbhs.h C typedef enum { USBHS_CONFIG_SOFTCONN, USBHS_CONFIG_DYNFIFOSIZE, Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2346 USBHS_CONFIG_HBWTXISO, USBHS_CONFIG_HBWRXISO, USBHS_CONFIG_BIGENDIAN, USBHS_CONFIG_AUTOSPLIT, USBHS_CONFIG_AUTOJOIN } USBHS_CONFIGURATION; Members Members Description USBHS_CONFIG_SOFTCONN Soft connect/disconnect supported USBHS_CONFIG_DYNFIFOSIZE Dynamic sizing of FIFO buffers supported USBHS_CONFIG_HBWTXISO High bandwidth TX isochronous transfers supported USBHS_CONFIG_HBWRXISO High bandwidth RX isochronous transfers supported USBHS_CONFIG_BIGENDIAN Big Endian byte ordering supported instead of Little Endian USBHS_CONFIG_AUTOSPLIT Automatic splitting of bulk packets supported USBHS_CONFIG_AUTOJOIN Automatic combining of bulk packets supported Description USBHS Hardware Configuration Bits Enumeration This data type provides the enumeration configuration bits returned by PLIB_USBHS_ConfigurationBitsGet. Remarks See also PLIB_USBHS_ConfigurationBitsGet. USBHS_DATA01 Enumeration Provides an enumeration data toggle for a packet. File plib_usbhs.h C typedef enum { USBHS_DATA0, USBHS_DATA1 } USBHS_DATA01; Members Members Description USBHS_DATA0 DATA0/1 = 0 USBHS_DATA1 DATA0/1 = 1 Description USBHS Endpoint Data Toggle Enumeration This data type provides an enumeration data toggle for a packet. Remarks None. USBHS_DMA_ASSERT_TIMING Enumeration Provides enumeration DMA assertion timing (early versus late). File plib_usbhs.h C typedef enum { USBHS_DMA_ASSERT_EARLY, USBHS_DMA_ASSERT_LATE } USBHS_DMA_ASSERT_TIMING; Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2347 Members Members Description USBHS_DMA_ASSERT_EARLY Assert DMA 8 bytes before filling FIFO USBHS_DMA_ASSERT_LATE Assert DMA when FIFO is full Description USBHS DMA Assertion Timing Enumeration This data type provides enumeration DMA assertion timing (early versus late). Remarks None. USBHS_DMA_BURST_MODE Enumeration Provides enumeration of all DMA burst modes. File plib_usbhs.h C typedef enum { USBHS_DMA_BURST_MODE0, USBHS_DMA_BURST_MODE1, USBHS_DMA_BURST_MODE2, USBHS_DMA_BURST_MODE3 } USBHS_DMA_BURST_MODE; Members Members Description USBHS_DMA_BURST_MODE0 Burst Mode 0: Bursts of unspecified length USBHS_DMA_BURST_MODE1 Burst Mode 1: INCR4 or unspecified length USBHS_DMA_BURST_MODE2 Burst Mode 2: INCR8, INCR4 or unspecified length USBHS_DMA_BURST_MODE3 Burst Mode 3: INCR16, INCR8, INCR4 or unspecified length Description USBHS DMA Burst Modes Enumeration This data type provides enumeration of all DMA burst modes. Remarks None. USBHS_DMA_INTERRUPT Enumeration Provides enumeration of interrupts for DMA channels 0-7. File plib_usbhs.h C typedef enum { USBHS_DMAINT_1, USBHS_DMAINT_2, USBHS_DMAINT_3, USBHS_DMAINT_4, USBHS_DMAINT_5, USBHS_DMAINT_6, USBHS_DMAINT_7, USBHS_DMAINT_8, USBHS_DMAINT_ANY, USBHS_DMAINT_ALL } USBHS_DMA_INTERRUPT; Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2348 Description USBHS DMA Interrupts Enumeration This data type provides the enumeration of interrupts for DMA channels 0-7. Remarks None. USBHS_DMA_REQUEST_MODE Enumeration Used as an argument to set DMA request mode. File plib_usbhs.h C typedef enum { USBHS_DMA_MODE0, USBHS_DMA_MODE1 } USBHS_DMA_REQUEST_MODE; Description USBHS DMA Request Mode Enumeration THis data type is used as an argument to set DMA request mode. Valid only for Endpoints 1-7. Remarks Used by PLIB_USBHS_EPnDMARequestModeSet. USBHS_DMA_TRANSFER_MODE Enumeration Provides enumeration of all DMA transfer modes. File plib_usbhs.h C typedef enum { USBHS_DMA_TRANSFER_MODE0, USBHS_DMA_TRANSFER_MODE1 } USBHS_DMA_TRANSFER_MODE; Description USBHS DMA Transfer Modes Enumeration This data type provides enumeration of all DMA Transfer modes. Remarks None. USBHS_DYN_FIFO_PACKET_BUFFERING Enumeration Provides enumeration of dynamic FIFO double-packet versus single-packet buffering. File plib_usbhs.h C typedef enum { USBHS_FIFO_SINGLEPKT, USBHS_FIFO_DOUBLEPKT } USBHS_DYN_FIFO_PACKET_BUFFERING; Description USBHS Dynamic FIFO Double Packet versus Single Packet Buffering Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2349 This data type provides enumeration of dynamic FIFO double-packet versus single-packet buffering. Remarks None. USBHS_DYN_FIFO_SIZE Enumeration Provides enumeration of dynamic FIFO sizes. File plib_usbhs.h C typedef enum { USBHS_FIFO_SIZE_8BYTES, USBHS_FIFO_SIZE_16BYTES, USBHS_FIFO_SIZE_32BYTES, USBHS_FIFO_SIZE_64BYTES, USBHS_FIFO_SIZE_128BYTES, USBHS_FIFO_SIZE_256BYTES, USBHS_FIFO_SIZE_512BYTES, USBHS_FIFO_SIZE_1024BYTES, USBHS_FIFO_SIZE_2048BYTES, USBHS_FIFO_SIZE_4096BYTES } USBHS_DYN_FIFO_SIZE; Description USBHS Dynamic FIFO Size Enumeration This data type provides enumeration of dynamic FIFO sizes. Remarks FIFO size = 2^(FIFO_Size<3:0> + 3) USBHS_ENDPOINT_DIRECTION Enumeration Used as an argument to identify an endpoint direction. File plib_usbhs.h C typedef enum { USBHS_ENDPOINT_RX, USBHS_ENDPOINT_TX } USBHS_ENDPOINT_DIRECTION; Members Members Description USBHS_ENDPOINT_RX RX endpoint USBHS_ENDPOINT_TX TX endpoint Description USBHS Endpoint Direction Enumeration This data type is used as an argument to identify an endpoint direction. Valid only for Endpoints 1-7. Remarks None. USBHS_LPM_INTERRUPT Enumeration Provides an enumeration of LPM interrupt sources. File plib_usbhs.h Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2350 C typedef enum { USBHS_LPMINT_STALL, USBHS_LPMINT_NYET, USBHS_LPMINT_ACK, USBHS_LPMINT_NOTCOMPLETE, USBHS_LPMINT_RESUMED, USBHS_LPMINT_ERROR } USBHS_LPM_INTERRUPT; Members Members Description USBHS_LPMINT_STALL Host: Device responded with STALL. Peripheral/Device: Sent a STALL. USBHS_LPMINT_NYET Host: Device responded with NYET. Peripheral/Device: Sent a NYET. USBHS_LPMINT_ACK Host: Device responded with ACK. Peripheral/Device: Sent an ACK. USBHS_LPMINT_NOTCOMPLETE Host: LPM transaction failed to complete. Peripheral/Device: NYET sent because data is pending in RX FIFOs. USBHS_LPMINT_RESUMED USB Module has resumed operation. USBHS_LPMINT_ERROR Host: Received Bit Stuff or PID error. Peripheral/Device: Unsupported LinkState field received. Description USBHS Link Power Management (LPM) Interrupts Enumeration This data type provides an enumeration of LPM interrupt sources. Remarks None. USBHS_LPM_LINK_STATE Enumeration Provides enumeration requested device state after accepting an LPM transaction. File plib_usbhs.h C typedef enum { USBHS_LPM_RESERVED_0, USBHS_LPM_L1_STATE, USBHS_LPM_RESERVED_2, USBHS_LPM_RESERVED_3, USBHS_LPM_RESERVED_4, USBHS_LPM_RESERVED_5, USBHS_LPM_RESERVED_6, USBHS_LPM_RESERVED_7, USBHS_LPM_RESERVED_8, USBHS_LPM_RESERVED_9, USBHS_LPM_RESERVED_A, USBHS_LPM_RESERVED_B, USBHS_LPM_RESERVED_C, USBHS_LPM_RESERVED_D, USBHS_LPM_RESERVED_E, USBHS_LPM_RESERVED_F } USBHS_LPM_LINK_STATE; Description USBHS Link Power Management Requested State Enumeration This data type provides enumeration requested device state after accepting an LPM transaction. Remarks Used by PLIB_USBHS_LPMRequestedLinkStateGet and PLIB_USBHS_LPMRequestedLinkStateSet. USBHS_LPM_MODE Enumeration Provides enumeration of Link Power Management (LPM) modes. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2351 File plib_usbhs.h C typedef enum { USBHS_LPM_DISABLED, USBHS_LPM_EXTENDEDNOLPM, USBHS_LPM_DISABLED2, USBHS_LPM_LPMEXTENDED } USBHS_LPM_MODE; Members Members Description USBHS_LPM_DISABLED LPM and Extended transactions not supported and will time-out USBHS_LPM_EXTENDEDNOLPM Extended transactions supported but LPM transactions not supported and produce STALLs USBHS_LPM_DISABLED2 LPM and Extended transactions not supported and will timeout USBHS_LPM_LPMEXTENDED LPM and Extended transactions are supported Description USBHS Link Power Management (LPM) Mode Enumeration This data type provides enumeration of Link Power Management (LPM) modes. Remarks Used by PLIB_USBHS_LPMModeSet. USBHS_OPMODES Enumeration Provides enumeration of operating modes supported by USB. File plib_usbhs.h C typedef enum { USBHS_OPMODE_NONE, USBHS_OPMODE_DEVICE, USBHS_OPMODE_HOST, USBHS_OPMODE_OTG } USBHS_OPMODES; Members Members Description USBHS_OPMODE_NONE None USBHS_OPMODE_DEVICE Device USBHS_OPMODE_HOST Host USBHS_OPMODE_OTG OTG Description USB Operating Modes Enumeration This data type provides enumeration of the operating modes supported by the USB module. Remarks None. USBHS_PKTS_PER_MICROFRAME Enumeration Provides an enumeration of the allowable isochronous packets per microframe when operating in High-Speed mode. File plib_usbhs.h Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2352 C typedef enum { USBHS_ONE_PKTS, USBHS_TWO_PKTS, USBHS_THREE_PKTS, USBHS_RSVD_PKTS } USBHS_PKTS_PER_MICROFRAME; Description USBHS Iso Packets Per Microframe Enumeration This data type provides an enumeration of the allowable isochronous packets per microframe when operating in High-Speed mode. Remarks Used by PLIB_USBHS_EPnPacketsInMicroFrameSet. For Transmit Endpoints: PIC32MZ EC device SFR fields: USBIENCSR0.MULT<1:0> = USBIENCSR0<12:11>, with USBCSR3.ENDPOINT = 1,2,...7 For Receive Endpoints: MG register fields: RXMAXP.m-1 = RXMAXP<12:11>, with INDEX.SelectedEndpoint = 1,2,...7 PIC32MZ EC device SFR fields: USBIENCSR1.MULT<1:0> = USBIENCSR1<12:11>, with USBCSR3.ENDPOINT = 1,2,...7 USBHS_SPEED Enumeration Provides enumeration Host endpoint speeds. File plib_usbhs.h C typedef enum { USBHS_LOW_SPEED, USBHS_FULL_SPEED, USBHS_HIGH_SPEED } USBHS_SPEED; Description USBHS Endpoint Speed Enumeration This data type provides enumeration Host endpoint speeds. Remarks Used by PLIB_USBHS_EPnSpeedSet. USBHS_TEST_SPEED Enumeration Used as an argument for in setting module speeds in Test mode. File plib_usbhs.h C typedef enum { USBHS_TEST_LOW_SPEED, USBHS_TEST_FULL_SPEED, USBHS_TEST_HIGH_SPEED } USBHS_TEST_SPEED; Description USBHS Test Speeds Enumeration This data type is used as an argument for setting module speeds in Test mode. Remarks For use with PLIB_USBHS_TestSpeedForce. Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2353 USBHS_TRANSACTION_TYPE Enumeration Provides an enumeration of transaction types. File plib_usbhs.h C typedef enum { USBHS_TRANSACTION_CONTROL, USBHS_TRANSACTION_ISO, USBHS_TRANSACTION_BULK, USBHS_TRANSACTION_INTERRUPT } USBHS_TRANSACTION_TYPE; Description USBHS Endpoint Transaction Type Enumeration This data type provides an enumeration of transaction types. Remarks Used by PLIB_USBHS_EPnTransactionTypeSet USBHS_TXRX_FIFO_STATE Enumeration Provides enumeration of receive and transmit FIFO states, as reported by status bits. File plib_usbhs.h C typedef enum { USBHS_TX_FIFO_EMPTY, USBHS_TX_FIFO_NOT_EMPTY, USBHS_RX_FIFO_FULL, USBHS_RX_FIFO_NOTFULL } USBHS_TXRX_FIFO_STATE; Members Members Description USBHS_TX_FIFO_EMPTY TX FIFO Empty USBHS_TX_FIFO_NOT_EMPTY TX FIFO NOT Empty USBHS_RX_FIFO_FULL RX FIFO Full USBHS_RX_FIFO_NOTFULL RX FIFO NOT Full Description USBHS FIFO State Enumeration This data type provides enumeration of receive and transmit FIFO states, as reported by status bits. Remarks None. For Transmit Endpoints: MG register fields: TXCSRL.FIFONotEmpty = TXCSRL<1>, with INDEX.SelectedEndpoint = 1,2,...7 PIC32MZ EC device SFR fields: USBIENCSR0.FIFONE = USBIENCSR0<17>, with USBCSR3.ENDPOINT = 1,2,...7 For Receive Endpoints: MG register fields: RXCSRL.FIFOFull = RXCSRL<1>, with INDEX.SelectedEndpoint = 1,2,...7 PIC32MZ EC device SFR fields: USBIENCSR1.FIFOFULL = USBIENCSR1<17>, with USBCSR3.ENDPOINT = 1,2,...7 USBHS_MAX_DMA_CHANNEL_NUMBER Macro Number of available DMA Channels. File plib_usbhs.h Peripheral Libraries Help USBHS Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2354 C #define USBHS_MAX_DMA_CHANNEL_NUMBER 8 Description Number of DMA Channels This constant defines the number of available DMA Channels. USBHS_MAX_EP_NUMBER Macro Maximum number of endpoints supported (not including EP0). File plib_usbhs.h C #define USBHS_MAX_EP_NUMBER 7 Description Maximum number of endpoints This constant defines the maximum number of endpoints supported (not including EP0). Files Files Name Description plib_usbhs.h HS USB PLIB Interface Header for definitions common to the Hi-Speed USB module. Description This section lists the source and header files used by the library. plib_usbhs.h HS USB PLIB Interface Header for definitions common to the Hi-Speed USB module. Enumerations Name Description USBHS_CONFIGURATION Provides the enumeration Configuration bits. USBHS_DATA01 Provides an enumeration data toggle for a packet. USBHS_DMA_ASSERT_TIMING Provides enumeration DMA assertion timing (early versus late). USBHS_DMA_BURST_MODE Provides enumeration of all DMA burst modes. USBHS_DMA_INTERRUPT Provides enumeration of interrupts for DMA channels 0-7. USBHS_DMA_REQUEST_MODE Used as an argument to set DMA request mode. USBHS_DMA_TRANSFER_MODE Provides enumeration of all DMA transfer modes. USBHS_DYN_FIFO_PACKET_BUFFERING Provides enumeration of dynamic FIFO double-packet versus single-packet buffering. USBHS_DYN_FIFO_SIZE Provides enumeration of dynamic FIFO sizes. USBHS_ENDPOINT_DIRECTION Used as an argument to identify an endpoint direction. USBHS_LPM_INTERRUPT Provides an enumeration of LPM interrupt sources. USBHS_LPM_LINK_STATE Provides enumeration requested device state after accepting an LPM transaction. USBHS_LPM_MODE Provides enumeration of Link Power Management (LPM) modes. USBHS_OPMODES Provides enumeration of operating modes supported by USB. USBHS_PKTS_PER_MICROFRAME Provides an enumeration of the allowable isochronous packets per microframe when operating in High-Speed mode. USBHS_SPEED Provides enumeration Host endpoint speeds. USBHS_TEST_SPEED Used as an argument for in setting module speeds in Test mode. USBHS_TRANSACTION_TYPE Provides an enumeration of transaction types. USBHS_TXRX_FIFO_STATE Provides enumeration of receive and transmit FIFO states, as reported by status bits. Peripheral Libraries Help USBHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2355 Functions Name Description PLIB_USBHS_DeviceAddressGet Returns the current USB device address. PLIB_USBHS_DeviceAddressSet Sets the device address. PLIB_USBHS_DeviceAttach This is function PLIB_USBHS_DeviceAttach. PLIB_USBHS_DeviceConnect Tri-states the USB D+ and D- lines. PLIB_USBHS_DeviceDetach This is function PLIB_USBHS_DeviceDetach. PLIB_USBHS_DeviceDisconnect Tri-states the USB D+ and D- lines. PLIB_USBHS_DeviceEPFIFOLoad This is function PLIB_USBHS_DeviceEPFIFOLoad. PLIB_USBHS_DeviceEPFIFOUnload This is function PLIB_USBHS_DeviceEPFIFOUnload. PLIB_USBHS_DeviceRxEndpointConfigure This is function PLIB_USBHS_DeviceRxEndpointConfigure. PLIB_USBHS_DeviceRxEndpointStallDisable This is function PLIB_USBHS_DeviceRxEndpointStallDisable. PLIB_USBHS_DeviceRxEndpointStallEnable This is function PLIB_USBHS_DeviceRxEndpointStallEnable. PLIB_USBHS_DeviceTxEndpointConfigure This is function PLIB_USBHS_DeviceTxEndpointConfigure. PLIB_USBHS_DeviceTxEndpointPacketReady This is function PLIB_USBHS_DeviceTxEndpointPacketReady. PLIB_USBHS_DeviceTxEndpointStallDisable This is function PLIB_USBHS_DeviceTxEndpointStallDisable. PLIB_USBHS_DeviceTxEndpointStallEnable This is function PLIB_USBHS_DeviceTxEndpointStallEnable. PLIB_USBHS_DMAErrorGet This is function PLIB_USBHS_DMAErrorGet. PLIB_USBHS_DMAInterruptDisable Disables DMA channel interrupts. PLIB_USBHS_DMAInterruptEnable Enables DMA channel interrupts. PLIB_USBHS_DMAInterruptFlagsGet Gets the DMA channel interrupt flags. PLIB_USBHS_DMAInterruptGet This is function PLIB_USBHS_DMAInterruptGet. PLIB_USBHS_DMAOperationEnable This is function PLIB_USBHS_DMAOperationEnable. PLIB_USBHS_Endpoint0FIFOFlush This is function PLIB_USBHS_Endpoint0FIFOFlush. PLIB_USBHS_Endpoint0SetupPacketLoad Loads the endpoint 0 FIFO with provided setup packet and then enables the endpoint transmit. PLIB_USBHS_Endpoint0SetupPacketUnload This is function PLIB_USBHS_Endpoint0SetupPacketUnload. PLIB_USBHS_EndpointFIFOLoad Loads the endpoint FIFO with provided data and then enables the endpoint transmit. PLIB_USBHS_EndpointFIFOUnload Unloads the endpoint FIFO. PLIB_USBHS_EndpointRxFIFOFlush This is function PLIB_USBHS_EndpointRxFIFOFlush. PLIB_USBHS_EndpointRxRequestClear This is function PLIB_USBHS_EndpointRxRequestClear. PLIB_USBHS_EndpointRxRequestEnable This is function PLIB_USBHS_EndpointRxRequestEnable. PLIB_USBHS_EndpointTxFIFOFlush This is function PLIB_USBHS_EndpointTxFIFOFlush. PLIB_USBHS_EP0DataEndSet This is function PLIB_USBHS_EP0DataEndSet. PLIB_USBHS_EP0INHandshakeClear This is function PLIB_USBHS_EP0INHandshakeClear. PLIB_USBHS_EP0INHandshakeSend This is function PLIB_USBHS_EP0INHandshakeSend. PLIB_USBHS_EP0INTokenSend This is function PLIB_USBHS_EP0INTokenSend. PLIB_USBHS_EP0OUTHandshakeSend This is function PLIB_USBHS_EP0OUTHandshakeSend. PLIB_USBHS_EP0RxPktRdyServiced This is function PLIB_USBHS_EP0RxPktRdyServiced. PLIB_USBHS_EP0RxPktRdyServicedDataEnd This is function PLIB_USBHS_EP0RxPktRdyServicedDataEnd. PLIB_USBHS_EP0SentStallClear This is function PLIB_USBHS_EP0SentStallClear. PLIB_USBHS_EP0SetupEndServiced This is function PLIB_USBHS_EP0SetupEndServiced. PLIB_USBHS_EP0StallDisable This is function PLIB_USBHS_EP0StallDisable. PLIB_USBHS_EP0StallEnable This is function PLIB_USBHS_EP0StallEnable. PLIB_USBHS_EP0StatusClear This is function PLIB_USBHS_EP0StatusClear. PLIB_USBHS_EP0StatusGet This is function PLIB_USBHS_EP0StatusGet. PLIB_USBHS_EP0TxPktRdy This is function PLIB_USBHS_EP0TxPktRdy. PLIB_USBHS_EP0TxPktRdyDataEnd This is function PLIB_USBHS_EP0TxPktRdyDataEnd. PLIB_USBHS_ExistsClockResetControl This is function PLIB_USBHS_ExistsClockResetControl. PLIB_USBHS_ExistsEndpointFIFO Identifies that the Endpoint FIFO feature exists on the Hi-Speed USB module. PLIB_USBHS_ExistsEndpointOperations This is function PLIB_USBHS_ExistsEndpointOperations. PLIB_USBHS_ExistsEP0Status This is function PLIB_USBHS_ExistsEP0Status. PLIB_USBHS_ExistsHighSpeedSupport This is function PLIB_USBHS_ExistsHighSpeedSupport. PLIB_USBHS_ExistsInterrupts This is function PLIB_USBHS_ExistsInterrupts. Peripheral Libraries Help USBHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2356 PLIB_USBHS_ExistsModuleControl This is function PLIB_USBHS_ExistsModuleControl. PLIB_USBHS_ExistsRxEPStatus This is function PLIB_USBHS_ExistsRxEPStatus. PLIB_USBHS_ExistsSoftReset This is function PLIB_USBHS_ExistsSoftReset. PLIB_USBHS_ExistsTxEPStatus This is function PLIB_USBHS_ExistsTxEPStatus. PLIB_USBHS_ExistsUSBIDControl This is function PLIB_USBHS_ExistsUSBIDControl. PLIB_USBHS_FullOrHighSpeedIsConnected This is function PLIB_USBHS_FullOrHighSpeedIsConnected. PLIB_USBHS_GenInterruptDisable Disables a general interrupt for the USB module. PLIB_USBHS_GenInterruptEnable Enables a general interrupt for the USB module. PLIB_USBHS_GenInterruptFlagsGet Gets general interrupt flags. PLIB_USBHS_GetEP0CSRAddress This is function PLIB_USBHS_GetEP0CSRAddress. PLIB_USBHS_GetEP0FIFOAddress This is function PLIB_USBHS_GetEP0FIFOAddress. PLIB_USBHS_GetReceiveDataCount This is function PLIB_USBHS_GetReceiveDataCount. PLIB_USBHS_GlobalInterruptDisable This is function PLIB_USBHS_GlobalInterruptDisable. PLIB_USBHS_GlobalInterruptEnable This is function PLIB_USBHS_GlobalInterruptEnable. PLIB_USBHS_HighSpeedDisable This is function PLIB_USBHS_HighSpeedDisable. PLIB_USBHS_HighSpeedEnable Sets the operation speed of the USB Module. PLIB_USBHS_HighSpeedIsConnected This is function PLIB_USBHS_HighSpeedIsConnected. PLIB_USBHS_HostModeIsEnabled This is function PLIB_USBHS_HostModeIsEnabled. PLIB_USBHS_HostRxEndpointConfigure This is function PLIB_USBHS_HostRxEndpointConfigure. PLIB_USBHS_HostRxEndpointDataToggleClear This is function PLIB_USBHS_HostRxEndpointDataToggleClear. PLIB_USBHS_HostTxEndpointConfigure This is function PLIB_USBHS_HostTxEndpointConfigure. PLIB_USBHS_HostTxEndpointDataToggleClear This is function PLIB_USBHS_HostTxEndpointDataToggleClear. PLIB_USBHS_InterruptEnableSet Enables USB module event interrupts. PLIB_USBHS_IsBDevice This is function PLIB_USBHS_IsBDevice. PLIB_USBHS_LoadEPInIndex This is function PLIB_USBHS_LoadEPInIndex. PLIB_USBHS_ModuleSpeedGet Returns the speed at which the module is operating. PLIB_USBHS_PhyIDMonitoringDisable This is function PLIB_USBHS_PhyIDMonitoringDisable. PLIB_USBHS_PhyIDMonitoringEnable This is function PLIB_USBHS_PhyIDMonitoringEnable. PLIB_USBHS_ResetDisable This is function PLIB_USBHS_ResetDisable. PLIB_USBHS_ResetEnable This is function PLIB_USBHS_ResetEnable. PLIB_USBHS_ResumeDisable This is function PLIB_USBHS_ResumeDisable. PLIB_USBHS_ResumeEnable This is function PLIB_USBHS_ResumeEnable. PLIB_USBHS_RxEPINTokenSend This is function PLIB_USBHS_RxEPINTokenSend. PLIB_USBHS_RxEPStatusClear This is function PLIB_USBHS_RxEPStatusClear. PLIB_USBHS_RxEPStatusGet This is function PLIB_USBHS_RxEPStatusGet. PLIB_USBHS_RxInterruptDisable Disables a RX endpoint interrupt for the USB module. PLIB_USBHS_RxInterruptEnable Enables a RX endpoint interrupt for the USB module. PLIB_USBHS_RxInterruptFlagsGet Gets RX endpoint interrupt flags. PLIB_USBHS_SessionDisable This is function PLIB_USBHS_SessionDisable. PLIB_USBHS_SessionEnable This is function PLIB_USBHS_SessionEnable. PLIB_USBHS_SoftResetDisable Disables soft reset. PLIB_USBHS_SoftResetEnable Enables soft reset. PLIB_USBHS_SuspendDisable This is function PLIB_USBHS_SuspendDisable. PLIB_USBHS_SuspendEnable This is function PLIB_USBHS_SuspendEnable. PLIB_USBHS_TestModeEnter This is function PLIB_USBHS_TestModeEnter. PLIB_USBHS_TestModeExit This is function PLIB_USBHS_TestModeExit. PLIB_USBHS_TxEPStatusClear This is function PLIB_USBHS_TxEPStatusClear. PLIB_USBHS_TxEPStatusGet This is function PLIB_USBHS_TxEPStatusGet. PLIB_USBHS_TxInterruptDisable Disables a TX endpoint interrupt source for the USB module. PLIB_USBHS_TxInterruptEnable Enables a TX endpoint Interrupt for the USB module. PLIB_USBHS_TxInterruptFlagsGet Gets the TX endpoint interrupt flags. PLIB_USBHS_USBIDOverrideDisable This is function PLIB_USBHS_USBIDOverrideDisable. PLIB_USBHS_USBIDOverrideEnable This is function PLIB_USBHS_USBIDOverrideEnable. PLIB_USBHS_USBIDOverrideValueSet This is function PLIB_USBHS_USBIDOverrideValueSet. Peripheral Libraries Help USBHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2357 PLIB_USBHS_VbusLevelGet Returns the current VBUS level encode using the USBHS_VBUS_DETECT_LEVEL enumeration. PLIB_USBHS_VBUSLevelGet This is function PLIB_USBHS_VBUSLevelGet. Macros Name Description USBHS_MAX_DMA_CHANNEL_NUMBER Number of available DMA Channels. USBHS_MAX_EP_NUMBER Maximum number of endpoints supported (not including EP0). Description Hi-Speed USB (HS USB) Module Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the USB PLIB for families of Microchip microcontrollers that feature the Hi-Speed USB module. Remarks Required to access the High Speed USB Module registers. File Name plib_usbhs.h Company Microchip Technology Inc. Peripheral Libraries Help USBHS Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2358 Watchdog Timer Peripheral Library This section describes the Watchdog Timer (WDT) Peripheral Library. Introduction This library provides a low-level abstraction of the WDT Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by abstracting differences from one microcontroller variant to another. Description The primary function of the Watchdog Timer (WDT) is to reset the microcontroller, in the event of a software malfunction, by resetting the device if it has not been cleared by software. To ensure that application does not hang, the application is supposed to reset the timer periodically. It can also be used to wake the device from Sleep or Idle mode. The WDT is a free-running timer, which uses the Low-Power RC (LPRC) Oscillator and requires no external components. Therefore, the WDT will continue to operate even if the system’s primary clock source is stopped. Using the Library This topic describes the basic architecture of the WDT Peripheral Library and provides information and examples on its use. Description Interface Header File: plib_wdt.h The interface to the WDT Peripheral Library is defined in the plib_wdt.h header file, which is included by the peripheral library header file, peripheral.h. Any C language source (.c) file that uses the WDT Peripheral Library must include peripheral.h. Library File: The WDT Peripheral Library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for information on how the library interacts with the framework. Hardware Abstraction Model This library provides the low-level abstraction of the Watchdog timer module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all of the functionality of the available Watchdog Timer modules on the device. Please refer to the "Watchdog Timer" chapter in the specific device data sheet or the family reference manual section specified in that chapter to determine the set of functions that are supported for each Watchdog Timer module on your device. Description Watchdog Timer Software Abstraction Block Diagram Peripheral Libraries Help Watchdog Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2359 The WDT uses the internal Low-Power RC (LPRC) Oscillator as the clock source. The clock is divided by the configured prescaler value. There may be one more postscaler divisors. The divided clock is then used to increment a counter. The WDT module uses the watchdog register as a timer. If there is no reset signal from the software and if the counter overflows, this results in a reset in normal mode. In the case of Sleep or Idle mode, the overflow will result in a device wake-up. For Windowed mode, resetting the counter when the count is not in the specified window will also lead to a reset. If the device is in Sleep or Idle mode, the reset signal will be used to wake-up the device. Library Overview The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the WDT module Library Interface Section Description General Configuration Functions This includes module enable, module disable, watchdog timer window enable, watchdog timer window disable and the timer reset routines. General Status Functions Status routines for the WDT. How the Library Works This section describes how the Watchdog Timer Peripheral Library works. Description Initializing the WDT module involves these processes. • Selecting the postscaler • Enabling the WDT using PLIB_WDT_Enable • Selecting the window size if the application wants the WDT in Windowed mode using PLIB_WDT_WindowEnable Note: Selecting the postscaler and window size should be done through the Configuration bits. The application should periodically clear the timer once it is enabled; otherwise, a time-out will lead to a device Reset. Use PLIB_WDT_TimerClear to clear the WDT. A timer clear before a time-out may also lead to a reset in Windowed mode. The user application can clear the window only in the allowed window. Refer to the specific device data sheet to determine the allowed window period for your device. Example /************************************************************** * This code fragment assumes the WDT is not enabled through * * device configuration bits. The Postscaler value must be set * Peripheral Libraries Help Watchdog Timer Peripheral Library Using the Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2360 * through the device configuration and window size should be * * set if applicable * **************************************************/ /* Initializing the watchdog involves */ PLIB_WDT_Enable(WDT_ID_0); //Application loop while(1) { PLIB_WDT_TimerClear(WDT_ID_0); //user code } Note: Refer to the specific device data sheet for information on the allowed window periods for your device and other Configuration bit settings. Configuring the Library The library is configured for the supported Watchdog Timer module when the processor is chosen in the MPLAB X IDE. Library Interface a) General Configuration Functions Name Description PLIB_WDT_Disable Disables the WDT module. PLIB_WDT_Enable Enables the WDT module. PLIB_WDT_WindowDisable Disables the WDT Windowed mode. PLIB_WDT_WindowEnable Enables the WDT Window mode. PLIB_WDT_TimerClear Resets the WDT module. b) General Status Functions Name Description PLIB_WDT_IsEnabled Returns the watchdog timer on/off(enable/disable) status. PLIB_WDT_PostscalerValueGet Returns the WDT postscaler value. PLIB_WDT_SleepModePostscalerValueGet Returns the WDT Sleep Mode postscaler value. c) Feature Existence Functions Name Description PLIB_WDT_ExistsEnableControl Identifies whether the EnableControl feature exists on the WDT module. PLIB_WDT_ExistsPostscalerValue Identifies whether the PostscalerValue feature exists on the WDT module. PLIB_WDT_ExistsTimerClear Identifies whether the TimerClear feature exists on the WDT module. PLIB_WDT_ExistsWindowEnable Identifies whether the WindowEnable feature exists on the WDT module. PLIB_WDT_ExistsSleepModePostscalerValue Identifies whether the SleepModePostscalerValue feature exists on the WDT module. d) Data Types and Constants Name Description WDT_MODULE_ID Identifies the supported Watchdog Timer modules. Description This section describes the Application Programming Interface (API) functions of the Watchdog Timer Peripheral Library. Refer to each section for a detailed description. a) General Configuration Functions Peripheral Libraries Help Watchdog Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2361 PLIB_WDT_Disable Function Disables the WDT module. File plib_wdt.h C void PLIB_WDT_Disable(WDT_MODULE_ID index); Returns None. Description This function disables the WDT module if it is enabled in software. Remarks This function will not disable the WDT module if it is enabled through its Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsEnableControl in your application to determine whether this feature is available. Preconditions The WDT module must be enabled through software. Example PLIB_WDT_Disable ( WDT_ID_0 ); Parameters Parameters Description index Identifies the desired WDT module Function void PLIB_WDT_Disable ( WDT_MODULE_ID index ) PLIB_WDT_Enable Function Enables the WDT module. File plib_wdt.h C void PLIB_WDT_Enable(WDT_MODULE_ID index); Returns None. Description This function enables the WDT module. If it is already enabled through the Configuration bits, it will keep it enabled. Remarks Calling this function is not necessary if it is enabled through its Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example PLIB_WDT_Enable ( WDT_ID_0 ); Peripheral Libraries Help Watchdog Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2362 Parameters Parameters Description index Identifies the desired WDT module Function void PLIB_WDT_Enable ( WDT_MODULE_ID index ) PLIB_WDT_WindowDisable Function Disables the WDT Windowed mode. File plib_wdt.h C void PLIB_WDT_WindowDisable(WDT_MODULE_ID index); Returns None. Description This function disables the WDT Windowed mode. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsWindowEnable in your application to determine whether this feature is available. Preconditions None. Example PLIB_WDT_WindowDisable ( WDT_ID_0 ); Parameters Parameters Description index Identifies the desired WDT module Function void PLIB_WDT_WindowDisable ( WDT_MODULE_ID index ) PLIB_WDT_WindowEnable Function Enables the WDT Window mode. File plib_wdt.h C void PLIB_WDT_WindowEnable(WDT_MODULE_ID index); Returns None. Description This function enables the WDT Windowed mode. Remarks The window size must be set through the Configuration bits. The example code doesn't include the settings that should be done through the Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use Peripheral Libraries Help Watchdog Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2363 PLIB_WDT_ExistsWindowEnable in your application to determine whether this feature is available. Preconditions The window size must be set through the Configuration bits. Example PLIB_WDT_WindowEnable ( WDT_ID_0 ); PLIB_WDT_Enable ( WDT_ID_0 ); Parameters Parameters Description index Identifies the desired WDT module Function void PLIB_WDT_WindowEnable ( WDT_MODULE_ID index ) PLIB_WDT_TimerClear Function Resets the WDT module. File plib_wdt.h C void PLIB_WDT_TimerClear(WDT_MODULE_ID index); Returns None. Description This function resets the WDT module. The WDT module should be cleared periodically before the count crosses and forces the device to reset. Remarks Resetting the device before the count reaches the window will cause a reset in Windowed mode. The example code doesn't include the settings that should be done through the Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsTimerClear in your application to determine whether this feature is available. Preconditions None. Example PLIB_WDT_Enable ( WDT_ID_0 ); //Application loop while(1) { PLIB_WDT_TimerClear ( WDT_ID_0 ); //user code } Parameters Parameters Description index Identifies the desired WDT module Function void PLIB_WDT_TimerClear ( WDT_MODULE_ID index ) b) General Status Functions Peripheral Libraries Help Watchdog Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2364 PLIB_WDT_IsEnabled Function Returns the watchdog timer on/off(enable/disable) status. File plib_wdt.h C bool PLIB_WDT_IsEnabled(WDT_MODULE_ID index); Returns • true - If the watchdog timer is on • false - If the watchdog timer is off Description Returns the 'true', if the watchdog timer is already ON. Otherwise returns 'false'. Remarks This function returns 'true' if the device is enabled either though the Configuration bits or in the software. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsEnableControl in your application to determine whether this feature is available. Preconditions None. Example if (PLIB_WDT_IsEnabled ( WDT_ID_0 ) ) { //Do some action } Parameters Parameters Description index Identifies the desired WDT module Function bool PLIB_WDT_IsEnabled ( WDT_MODULE_ID index ) PLIB_WDT_PostscalerValueGet Function Returns the WDT postscaler value. File plib_wdt.h C char PLIB_WDT_PostscalerValueGet(WDT_MODULE_ID index); Returns The postscaler value. Description This function returns the WDT postscaler value. The value will correspond to a division factor. Remarks The value returned will be right-aligned. Refer to the specific device data sheet to get the division factor corresponding to the value. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsPostscalerValue in your application to determine whether this feature is available. Peripheral Libraries Help Watchdog Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2365 Preconditions None. Example uint8_t value; PLIB_WDT_Enable ( WDT_ID_0 ); value = PLIB_WDT_PostscalerValueGet ( WDT_ID_0 ); Parameters Parameters Description index Identifies the desired WDT module Function char PLIB_WDT_PostscalerValueGet ( WDT_MODULE_ID index ) PLIB_WDT_SleepModePostscalerValueGet Function Returns the WDT Sleep Mode postscaler value. File plib_wdt.h C char PLIB_WDT_SleepModePostscalerValueGet(WDT_MODULE_ID index); Returns The Sleep Mode postscaler value. Description This function returns the WDT postscaler value in Sleep Mode. The value will correspond to a division factor. Remarks The value returned will be right-aligned. Refer to the specific device data sheet to get the division factor corresponding to the value. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsSleepModePostscalerValue in your application to determine whether this feature is available. Preconditions None. Example uint8_t value; value = PLIB_WDT_SleepModePostscalerValueGet ( WDT_ID_0 ); Parameters Parameters Description index Identifies the desired WDT module Function char PLIB_WDT_SleepModePostscalerValueGet ( WDT_MODULE_ID index ) c) Feature Existence Functions PLIB_WDT_ExistsEnableControl Function Identifies whether the EnableControl feature exists on the WDT module. Peripheral Libraries Help Watchdog Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2366 File plib_wdt.h C bool PLIB_WDT_ExistsEnableControl(WDT_MODULE_ID index); Returns Existence of the EnableControl feature: • true - When EnableControl feature is supported on the device • false - When EnableControl feature is not supported on the device Description This function identifies whether the EnableControl feature is available on the WDT module. When this function returns true, these functions are supported on the device: • PLIB_WDT_Enable • PLIB_WDT_Disable • PLIB_WDT_IsEnabled Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_WDT_ExistsEnableControl( WDT_MODULE_ID index ) PLIB_WDT_ExistsPostscalerValue Function Identifies whether the PostscalerValue feature exists on the WDT module. File plib_wdt.h C bool PLIB_WDT_ExistsPostscalerValue(WDT_MODULE_ID index); Returns • true - The PostscalerValue feature is supported on the device • false - The PostscalerValue feature is not supported on the device Description This function identifies whether the PostscalerValue feature is available on the WDT module. When this function returns true, this function is supported on the device: • PLIB_WDT_PostscalerValueGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Peripheral Libraries Help Watchdog Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2367 Function PLIB_WDT_ExistsPostscalerValue( WDT_MODULE_ID index ) PLIB_WDT_ExistsTimerClear Function Identifies whether the TimerClear feature exists on the WDT module. File plib_wdt.h C bool PLIB_WDT_ExistsTimerClear(WDT_MODULE_ID index); Returns • true - The TimerClear feature is supported on the device • false - The TimerClear feature is not supported on the device Description This function identifies whether the TimerClear feature is available on the WDT module. When this function returns true, this function is supported on the device: • PLIB_WDT_TimerClear Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_WDT_ExistsTimerClear( WDT_MODULE_ID index ) PLIB_WDT_ExistsWindowEnable Function Identifies whether the WindowEnable feature exists on the WDT module. File plib_wdt.h C bool PLIB_WDT_ExistsWindowEnable(WDT_MODULE_ID index); Returns • true - The WindowEnable feature is supported on the device • false - The WindowEnable feature is not supported on the device Description This function identifies whether the WindowEnable feature is available on the WDT module. When this function returns true, these functions are supported on the device: • PLIB_WDT_WindowEnable • PLIB_WDT_WindowDisable Remarks None. Preconditions None. Peripheral Libraries Help Watchdog Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2368 Parameters Parameters Description index Identifier for the device instance Function PLIB_WDT_ExistsWindowEnable( WDT_MODULE_ID index ) PLIB_WDT_ExistsSleepModePostscalerValue Function Identifies whether the SleepModePostscalerValue feature exists on the WDT module. File plib_wdt.h C bool PLIB_WDT_ExistsSleepModePostscalerValue(WDT_MODULE_ID index); Returns • true - The SleepModePostscalerValue feature is supported on the device • false - The SleepModePostscalerValue feature is not supported on the device Description This function identifies whether the SleepModePostscalerValue feature is available on the WDT module. When this function returns true, this function is supported on the device: • PLIB_WDT_SleepModePostscalerValueGet Remarks None. Preconditions None. Parameters Parameters Description index Identifier for the device instance Function PLIB_WDT_ExistsSleepModePostscalerValue( WDT_MODULE_ID index ) d) Data Types and Constants WDT_MODULE_ID Enumeration Identifies the supported Watchdog Timer modules. File plib_wdt_help.h C typedef enum { WDT_ID_0, WDT_NUMBER_OF_MODULES } WDT_MODULE_ID; Members Members Description WDT_ID_0 WDT Module 1 ID WDT_NUMBER_OF_MODULES Number of available WDT modules. Peripheral Libraries Help Watchdog Timer Peripheral Library Library Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2369 Description Watchdog Timer (WDT) Module ID This enumeration identifies the available Watchdog Timer modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Files Files Name Description plib_wdt.h Watchdog Timer (WDT) Peripheral Library interface header for Watchdog Timer common definitions. plib_wdt_help.h Description This section lists the source and header files used by the library. plib_wdt.h Watchdog Timer (WDT) Peripheral Library interface header for Watchdog Timer common definitions. Functions Name Description PLIB_WDT_Disable Disables the WDT module. PLIB_WDT_Enable Enables the WDT module. PLIB_WDT_ExistsEnableControl Identifies whether the EnableControl feature exists on the WDT module. PLIB_WDT_ExistsPostscalerValue Identifies whether the PostscalerValue feature exists on the WDT module. PLIB_WDT_ExistsSleepModePostscalerValue Identifies whether the SleepModePostscalerValue feature exists on the WDT module. PLIB_WDT_ExistsTimerClear Identifies whether the TimerClear feature exists on the WDT module. PLIB_WDT_ExistsWindowEnable Identifies whether the WindowEnable feature exists on the WDT module. PLIB_WDT_IsEnabled Returns the watchdog timer on/off(enable/disable) status. PLIB_WDT_PostscalerValueGet Returns the WDT postscaler value. PLIB_WDT_SleepModePostscalerValueGet Returns the WDT Sleep Mode postscaler value. PLIB_WDT_TimerClear Resets the WDT module. PLIB_WDT_WindowDisable Disables the WDT Windowed mode. PLIB_WDT_WindowEnable Enables the WDT Window mode. Description Watchdog Timer (WDT) Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Watchdog Timer Peripheral Library for all families of Microchip microcontrollers. The definitions in this file are common to the Watchdog Timer peripheral. File Name plib_wdt.h Company Microchip Technology Inc. plib_wdt_help.h Enumerations Name Description WDT_MODULE_ID Identifies the supported Watchdog Timer modules. Peripheral Libraries Help Watchdog Timer Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2370 Section Data Types & Constants Peripheral Libraries Help Watchdog Timer Peripheral Library Files © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2371 Index _ _ETH_PATTERN_MATCH_MODE_ enumeration 914 _USART_MODULE_ID macro 2155 A About CAN Protocol 302 Abstraction Model 653 Dual Data Rate (DDR) SDRAM Peripheral Library 653 Accessing the Result Buffers 28 ADC Peripheral Library 20 ADC_ACQUISITION_TIME type 81 ADC_BUFFER_MODE enumeration 75 ADC_CLOCK_SOURCE enumeration 75 ADC_CONVERSION_CLOCK type 81 ADC_CONVERSION_TRIGGER_SOURCE enumeration 75 ADC_INPUTS_NEGATIVE enumeration 73 ADC_INPUTS_POSITIVE enumeration 79 ADC_INPUTS_SCAN enumeration 77 ADC_MODULE_ID enumeration 72 ADC_MUX enumeration 76 ADC_RESULT_BUF_STATUS enumeration 76 ADC_RESULT_FORMAT enumeration 79 ADC_SAMPLE type 82 ADC_SAMPLES_PER_INTERRUPT enumeration 74 ADC_SAMPLING_MODE enumeration 77 ADC_VOLTAGE_REFERENCE enumeration 73 ADCHS Peripheral Library 85 ADCHS_AN_INPUT_ID enumeration 196 ADCHS_CHANNEL_ID enumeration 211 ADCHS_CHANNEL_INP_SEL enumeration 210 ADCHS_CHANNEL_TRIGGER_SAMPLING_SEL enumeration 212 ADCHS_CHARGEPUMP_MODE enumeration 198 ADCHS_CLASS12_AN_INPUT_ID enumeration 212 ADCHS_CLOCK_SOURCE enumeration 198 ADCHS_CVD_CAPACITOR enumeration 199 ADCHS_DATA_RESOLUTION enumeration 199 ADCHS_DIGITAL_COMPARATOR_ID enumeration 200 ADCHS_DIGITAL_FILTER_AVERAGE_SAMPLE_COUNT enumeration 201 ADCHS_DIGITAL_FILTER_ID enumeration 201 ADCHS_DIGITAL_FILTER_OVERSAMPLE_RATIO enumeration 202 ADCHS_DIGITAL_FILTER_SIGNIFICANT_BITS enumeration 202 ADCHS_DMA_BUFFER_LENGTH enumeration 203 ADCHS_DMA_COUNT enumeration 203 ADCHS_EARLY_INTERRUPT_PRIOR_CLOCK enumeration 204 ADCHS_FAST_SYNC_PERIPHERAL_CLOCK enumeration 204 ADCHS_FAST_SYNC_SYSTEM_CLOCK enumeration 205 ADCHS_INPUT_MODE enumeration 205 ADCHS_INTERRUPT_BIT_SHIFT_LEFT enumeration 206 ADCHS_MODULE_ID enumeration 210 ADCHS_OUTPUT_DATA_FORMAT enumeration 206 ADCHS_SCAN_TRIGGER_SENSITIVE enumeration 207 ADCHS_SCAN_TRIGGER_SOURCE enumeration 207 ADCHS_TRIGGER_SOURCE enumeration 208 ADCHS_VREF_SOURCE enumeration 209 ADCHS_WARMUP_CLOCK enumeration 209 ADCP Peripheral Library 218 ADCP_CLASS12_INPUT_ID enumeration 254 ADCP_CLOCK_SOURCE enumeration 253 ADCP_DCMP_ID enumeration 258 ADCP_DSH_ID enumeration 255 ADCP_INPUT_ID enumeration 256 ADCP_MODULE_ID enumeration 252 ADCP_ODFLTR_ID enumeration 259 ADCP_ODFLTR_OSR enumeration 259 ADCP_SCAN_TRG_SRC enumeration 260 ADCP_SH_ID enumeration 254 ADCP_SH_MODE enumeration 255 ADCP_TRG_SRC enumeration 261 ADCP_VREF_SOURCE enumeration 253 Alarm Mode Operations 1707 AN_READY type 263 AN_SELECT union 262 Assigning Buffer Memory 305 Asynchronous Counter 2041 Asynchronous USART Mode 2078 Audio Protocol Interface Mode 1821 B BMX Peripheral Library 266 BMX_MODULE_ID enumeration 295 Building the Library 1211 NVM Peripheral Library 1211 Bus Arbiter 268 C Cache Control 268 Cache Control Operations 1504 Cache Line Operations 1504 Cache Status Operations 1505 CAN Bit Time Quanta 304 CAN Peripheral Library 300 CAN_CHANNEL enumeration 379 CAN_CHANNEL_EVENT enumeration 381 CAN_CHANNEL_MASK enumeration 381 CAN_DNET_FILTER_SIZE enumeration 383 CAN_ERROR_STATE enumeration 383 CAN_FILTER enumeration 384 CAN_FILTER_MASK enumeration 386 CAN_FILTER_MASK_TYPE enumeration 386 CAN_ID_TYPE enumeration 387 CAN_MODULE_EVENT enumeration 387 CAN_MODULE_ID enumeration 388 CAN_MSG_EID structure 388 CAN_OPERATION_MODES enumeration 389 CAN_RECEIVE_CHANNEL enumeration 390 CAN_RECEIVE_MODES enumeration 390 CAN_RX_DATA_MODE enumeration 390 CAN_RX_DATA_ONLY_SIZE_BYTES macro 394 CAN_RX_MSG_BUFFER union 391 CAN_RX_MSG_SID structure 391 CAN_TIME_SEGMENT_LENGTH enumeration 392 CAN_TX_CHANNEL_STATUS enumeration 392 CAN_TX_MSG_BUFFER union 393 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2372 CAN_TX_MSG_SID structure 393 CAN_TX_RTR enumeration 394 CAN_TX_RX_MESSAGE_SIZE_BYTES macro 395 CAN_TXCHANNEL_PRIORITY enumeration 394 Capacitive Touch Measurement 446 Channel Configuration 306 Channel Events 309 Channel Management 529 Clock Sources 1300 CMP_CLOCK_DIVIDE enumeration 428 CMP_CVREF_BANDGAP_SELECT enumeration 429 CMP_CVREF_REFERENCE_SELECT enumeration 429 CMP_CVREF_VALUE enumeration 430 CMP_CVREF_VOLTAGE_SOURCE enumeration 430 CMP_FILTER_CLOCK enumeration 431 CMP_INTERRUPT_EVENT enumeration 431 CMP_INVERTING_INPUT enumeration 432 CMP_MASK_A enumeration 432 CMP_MASK_B enumeration 433 CMP_MASK_C enumeration 434 CMP_MODULE_ID enumeration 434 CMP_NON_INVERTING_INPUT enumeration 435 CMP_SPEED_POWER enumeration 435 Communication Mode 1826 Comparator Peripheral Library 399 Configuring a Library 5 Peripheral Library Overview 5 Configuring the Comparator Interrupts 401 Configuring the Library 34, 99, 225, 272, 310, 402, 448, 471, 487, 533, 656, 723, 780, 927, 1048, 1132, 1157, 1211, 1273, 1302, 1415, 1506, 1556, 1642, 1689, 1709, 1766, 1827, 1907, 2043, 2086, 2169, 2311, 2361 ADC Peripheral Library 34 ADCHS Peripheral Library 99 ADCP Peripheral Library 225 BMX Peripheral Library 272 CAN Peripheral Library 310 CTMU Peripheral Library 448 Deadman Timer Peripheral Library 471 DMA Peripheral Library 533 Dual Data Rate (DDR) SDRAM Peripheral Library 656 EBI Peripheral Library 723 GLCD Controller Peripheral Library 927 I2C Peripheral Library 1048 Input Capture Peripheral Library 1132 Interrupt Peripheral Library 1157 NVM Peripheral Library 1211 Oscillator Peripheral Library 1302 Output Compare Peripheral Library 1273 PMP Peripheral Library 1415 Ports Peripheral Library 1556 Power Peripheral Library 1642 Prefetch Cache Peripheral Library 487, 1506 Reset Peripheral Library 1689 RTCC Peripheral Library 1709 SPI Peripheral Library 1827 SQI Peripheral Library 1907 System Bus Peripheral Library 1766 Timer Peripheral Library 2043 USART Peripheral Library 2086 USB Peripheral Library 2169 USBHS Peripheral Library 2311 Watchdog Timer Peripheral Library 2361 Controlling the Conversion Process 26 Controlling the Sampling Process 26 Conversion Sequence Examples 29 Core Functionality 220, 1902 CTMU Peripheral Library 438 CTMU Setup 443 CVREF Setup 400 D DDR_CMD_IDLE_NOP macro 714 DDR_CMD_LOAD_MODE macro 715 DDR_CMD_PRECHARGE_ALL macro 715 DDR_CMD_REFRESH macro 716 DDR_HOST_CMD_REG enumeration 717 DDR_MODULE_ID enumeration 718 DDR_PHY_DDR_TYPE enumeration 714 DDR_PHY_DRIVE_STRENGTH enumeration 715 DDR_PHY_ODT enumeration 715 DDR_PHY_PREAMBLE_DLY enumeration 716 DDR_PHY_SCL_BURST_MODE enumeration 716 DDR_PHY_SCL_DELAY enumeration 716 DDR_TARGET enumeration 718 Deadman Timer Peripheral Library 470 DEEP_SLEEP_EVENT enumeration 1677 DEEP_SLEEP_GPR enumeration 1678 DEEP_SLEEP_MODULE enumeration 1679 DEEP_SLEEP_WAKE_UP_EVENT enumeration 1679 Descriptor Table Example 776 DEVCON_ALT_CLOCK_TARGET enumeration 516 DEVCON_DEBUG_PERIPHERAL enumeration 516 DEVCON_ECC_CONFIG enumeration 517 DEVCON_MODULE_ID enumeration 518 DEVCON_MPLL_OUTPUT_DIVIDER enumeration 519 DEVCON_MPLL_VREF_CONTROL enumeration 519 DEVCON_REGISTER_SET enumeration 517 DEVCON_USB_SLEEP_MODE enumeration 518 Device Control Peripheral Library 486 Display Background Management 924 Display Signal Polarity and Timing Management 924 DMA Mode 1903 DMA Peripheral Library Help 522 DMA_ADDRESS_OFFSET_TYPE enumeration 634 DMA_CHANNEL enumeration 634 DMA_CHANNEL_ADDRESSING_MODE enumeration 635 DMA_CHANNEL_COLLISION enumeration 635 DMA_CHANNEL_DATA_SIZE enumeration 636 DMA_CHANNEL_INT_SOURCE enumeration 647 DMA_CHANNEL_PRIORITY enumeration 636 DMA_CHANNEL_TRANSFER_DIRECTION enumeration 637 DMA_CHANNEL_TRIGGER_TYPE enumeration 637 DMA_CRC_BIT_ORDER enumeration 638 DMA_CRC_BYTE_ORDER enumeration 638 DMA_CRC_TYPE enumeration 638 DMA_DESTINATION_ADDRESSING_MODE enumeration 639 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2373 DMA_INT_TYPE enumeration 639 DMA_MODULE_ID enumeration 640 DMA_PATTERN_LENGTH enumeration 641 DMA_PING_PONG_MODE enumeration 641 DMA_SOURCE_ADDRESSING_MODE enumeration 641 DMA_TRANSFER_MODE enumeration 642 DMA_TRIGGER_SOURCE enumeration 642 DMT_MODULE_ID enumeration 484 Dual Compare Continuous Mode 1272 Dual Data Rate (DDR) SDRAM Peripheral Library 653 E EBI Peripheral Library 722 EBI_ADDRESS_PORT enumeration 757 EBI_CS_TIMING enumeration 758 EBI_MEMORY_SIZE enumeration 758 EBI_MEMORY_TYPE enumeration 759 EBI_MODULE_ID enumeration 760 EBI_PAGE_SIZE enumeration 760 EBI_STATIC_MEMORY_WIDTH enumeration 760 EEPROM Operations 1208 EEPROM_ERROR enumeration 1264 EEPROM_OPERATION_MODE enumeration 1264 Enabling Events 307 Enhanced Buffer Master Mode 1812 Enhanced Buffer Slave Mode 1814 Enhanced Buffer SPI Mode 1812 ETH_AUTOPAD_OPTION enumeration 913 ETH_INTERRUPT_SOURCES enumeration 913 ETH_MIIM_CLK enumeration 914 ETH_PATTERN_MATCH_DISABLED enumeration member 914 ETH_PATTERN_MATCH_MODE enumeration 914 ETH_PATTERN_MATCH_MODE_BROADCAST_ADDR enumeration member 914 ETH_PATTERN_MATCH_MODE_CHECKSUM_MATCH enumeration member 914 ETH_PATTERN_MATCH_MODE_HASH_MATCH enumeration member 914 ETH_PATTERN_MATCH_MODE_MAGIC_PACKET enumeration member 914 ETH_PATTERN_MATCH_MODE_STATION_ADDR enumeration member 914 ETH_PATTERN_MATCH_MODE_UNICAST_ADDR enumeration member 914 ETH_RECEIVE_FILTER enumeration 915 ETH_RMII_SPEED enumeration 916 Ethernet Controller Operation 769 Ethernet DMA and Buffer Management Engine 772 Ethernet Frame Overview 769 Ethernet Peripheral Library 764 Example - Channel Scanning 92, 221 Example - CVD Mode 97 Example - Digital Comparator 95, 224 Example - Digital Filter 93 Example - Digital Oversampling Filter 223 Example - Simultaneous Sampling and Conversion of Three Class 1 Inputs 88 Example - Simultaneous Sampling Three Class 1 Inputs 220 Example Applications 447 Exception Generator 268 Extended ID Message Format 303 F Fail-Safe Clock Monitor 1301 Files 82, 213, 263, 298, 395, 436, 468, 484, 520, 648, 718, 761, 916, 1021, 1125, 1153, 1202, 1265, 1295, 1402, 1496, 1548, 1636, 1684, 1701, 1760, 1802, 1895, 2030, 2072, 2157, 2304, 2355, 2370 ADC Peripheral Library 82 ADCHS Peripheral Library 213 ADCP Peripheral Library 263 BMX Peripheral Library 298 CAN Peripheral Library 395 Comparator Peripheral Library 436 CTMU Peripheral Library 468 DDR Timer Peripheral Library 718 Device Control Peripheral Library 520 DMA Peripheral Library 648 DMT Timer Peripheral Library 484 EBI Peripheral Library 761 Ethernet Peripheral Library 916 GLCD Controller Timer Peripheral Library 1021 I2C Peripheral Library 1125 Input Capture Peripheral Library 1153 Interrupt Peripheral Library 1202 NVM Peripheral Library 1265 Oscillator Peripheral Library 1402 Output Compare Peripheral Library 1295 PMP Peripheral Library 1496 Ports Peripheral Library 1636 Power Peripheral Library 1684 Prefetch Peripheral Library 1548 Reset Peripheral Library 1701 RTCC Peripheral Library 1760 SPI Peripheral Library 1895 SQI Peripheral Library 2030 System Bus Peripheral Library 1802 Timer Peripheral Library 2072 USART Peripheral Library 2157 USB Peripheral Library 2304 USBHS Peripheral Library 2355 Watchdog Timer Peripheral Library 2370 Filters and Masks Configuration 306 Flash ECC Operations 1506 Flash Operations 1208 Flow Control Overview 771 Forming Transfers 1045 Framed SPI Modes 1815 Functionality 88 G Gated Timer 2042 General 24 General Configuration 524, 923 General Setup 443 GLCD Controller Peripheral Library 922 GLCD_IRQ_TRIGGER_CONTROL enumeration 1016 GLCD_LAYER_COLOR_MODE enumeration 1016 GLCD_LAYER_DEST_BLEND_FUNC enumeration 1017 GLCD_LAYER_ID enumeration 1018 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2374 GLCD_LAYER_SRC_BLEND_FUNC enumeration 1018 GLCD_MODULE_ID enumeration 1019 GLCD_RGB_MODE enumeration 1019 GLCD_SIGNAL_POLARITY enumeration 1020 H Handling Errors 1046, 1414 Handling Events 309 Hardware Abstraction Model 20, 87, 219, 266, 300, 399, 438, 470, 486, 522, 765, 922, 1026, 1130, 1155, 1204, 1269, 1297, 1407, 1501, 1551, 1639, 1687, 1704, 1763, 1805, 1900, 2036, 2074, 2359 ADC Peripheral Library 20 ADCHS Peripheral Library 87 ADCP Peripheral Library 219 BMX Peripheral Library 266 CAN Peripheral Library 300 Comparator Peripheral Library 399 CTMU Peripheral Library 438 Deadman Timer Peripheral Library 470 DMA Peripheral Library 522 Ethernet Peripheral Library 765 GLCD Controller Peripheral Library 922 I2C Peripheral Library 1026 Input Capture Peripheral Library 1130 Interrupt Peripheral Library 1155 NVM Peripheral Library 1204 Oscillator Peripheral Library 1297 Output Compare Peripheral Library 1269 PMP Peripheral Library 1407 Ports Peripheral Library 1551 Power Peripheral Library 1639 Prefetch Cache Peripheral Library 486, 1501 Reset Peripheral Library 1687 RTCC Peripheral Library 1704 SPI Peripheral Library 1805 SQI Peripheral Library 1900 System Bus Peripheral Library 1763 Timer Peripheral Library 2036 USART Peripheral Library 2074 USB Peripheral Library 2163 Watchdog Timer Peripheral Library 2359 Hardware Abstraction Models 2163 Hardware Cursor Control and Management 926 help_plib_adc.h 84 help_plib_adchs.h 213 help_plib_adcp.h 264 help_plib_bmx.h 299 help_plib_cmp.h 437 help_plib_devcon.h 521 help_plib_dma.h 652 help_plib_pcache.h 1550 help_plib_ports.h 1638 help_plib_power.h 1686 help_plib_reset.h 1702 help_plib_sb.h 1804 help_plib_spi.h 1897 help_plib_sqi.h 2034 help_plib_tmr.h 2073 HLVD_LIMIT enumeration 1683 HLVD_MODE enumeration 1684 How the Library Works 24, 88, 220, 267, 302, 400, 440, 471, 486, 524, 654, 723, 767, 923, 1027, 1131, 1156, 1205, 1271, 1299, 1408, 1503, 1554, 1641, 1688, 1704, 1764, 1807, 1901, 2039, 2076, 2165, 2311, 2360 ADC Peripheral Library 24 ADCHS Peripheral Library 88 ADCP Peripheral Library 220 BMX Peripheral Library 267 CAN Peripheral Library 302 Comparator Peripheral Library 400 Deadman Timer Peripheral Library 471 Device Control Peripheral Library 486 DMA Peripheral Library 524 Dual Data Rate (DDR) SDRAM Peripheral Library 654 EBI Peripheral Library 723 Ethernet Peripheral Library 767 GLCD Controller Peripheral Library 923 I2C Peripheral Library 1027 Input Capture Peripheral Library 1131 Interrupt Peripheral Library 1156 NVM Peripheral Library 1205 Oscillator Peripheral Library 1299 Output Compare Peripheral Library 1271 PMP Peripheral Library 1408 Ports Peripheral Library 1554 Power Peripheral Library 1641 Prefetch Cache Peripheral Library 1503 Reset Peripheral Library 1688 RTCC Peripheral Library 1704 SPI Peripheral Library 1807 SQI Peripheral Library 1901 System Bus Peripheral Library 1764 Timer Peripheral Library 2039 USART Peripheral Library 2076 Watchdog Timer Peripheral Library 2360 I I2C Peripheral Library 1025 I2C_MODULE_ID enumeration 1125 IC_ALT_TIMERS enumeration 1152 IC_BUFFER_SIZE enumeration 1150 IC_EDGE_TYPES enumeration 1150 IC_EVENTS_PER_INTERRUPT enumeration 1150 IC_INPUT_CAPTURE_MODES enumeration 1151 IC_MODULE_ID enumeration 1151 IC_TIMERS enumeration 1152 Initialization 24, 401, 774, 1409 Initialization of CAN 304 Initializing the I2C 1028 Initiator Initialization 1765 Input Capture Module Setup 1131 Input Capture Peripheral Library 1129 INT_EXTERNAL_SOURCES enumeration 1187 INT_PRIORITY_LEVEL enumeration 1188 INT_SHADOW_REGISTER enumeration 1200 INT_SOURCE enumeration 1188 INT_STATE_GLOBAL type 1200 INT_SUBPRIORITY_LEVEL enumeration 1194 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2375 INT_VECTOR enumeration 1195 INT_VECTOR_SPACING enumeration 1201 Internal FRC Oscillator Tuning 1301 Interrupt Control 926 Interrupt Control and Management 525 Interrupt Peripheral Library 1155 Interrupt State Machine 1039 Interrupts 1827 Introduction 3, 7, 20, 85, 218, 266, 300, 399, 438, 470, 486, 522, 653, 722, 764, 922, 1025, 1129, 1155, 1204, 1268, 1297, 1407, 1501, 1551, 1639, 1687, 1703, 1763, 1805, 1899, 2036, 2074, 2161, 2310, 2359 ADC Peripheral Library 20 ADCHS Peripheral Library 85 ADCP Peripheral Library 218 BMX Peripheral Library 266 CAN Peripheral Library 300 Comparator Peripheral Library 399 CTMU Peripheral Library 438 Deadman Timer Peripheral Library 470 Device Control Peripheral Library 486 DMA Peripheral Library 522 Dual Data Rate (DDR) SDRAM Peripheral Library 653 EBI Peripheral Library 722 Ethernet Peripheral Library 764 Graphics LCD (GLCD) Controller Peripheral Library 922 I2C Peripheral Library 1025 Input Capture Peripheral Library 1129 Interrupt Peripheral Library 1155 NVM Peripheral Library 1204 Oscillator Peripheral Library 1297 Output Compare Peripheral Library 1268 Peripheral Library Overview 3 PMP Peripheral Library 1407 Ports Peripheral Library 1551 Power Peripheral Library 1639 Prefetch Cache Peripheral Library 1501 Reset Peripheral Library 1687 RTCC Peripheral Library 1703 SPI Peripheral Library 1805 SQI Peripheral Library 1899 System Bus Peripheral Library 1763 Timer Peripheral Library 2036 USART Peripheral Library 2074 USB Peripheral Library 2161 USBHS Peripheral Library 2310 Watchdog Timer Peripheral Library 2359 L Layer Management 925 Library Interface 35, 99, 225, 272, 310, 402, 448, 471, 487, 533, 656, 723, 780, 927, 1048, 1132, 1157, 1211, 1273, 1302, 1415, 1506, 1556, 1642, 1689, 1710, 1766, 1827, 1908, 2043, 2086, 2169, 2311, 2361 ADC Peripheral Library 35 ADCHS Peripheral Library 99 ADCP Peripheral Library 225 BMX Peripheral Library 272 CAN Peripheral Library 310 Comparator Peripheral Library 402 CTMU Peripheral Library 448 Deadman Timer Peripheral Library 471 Device Control Peripheral Library 487 DMA Peripheral Library 533 Dual Data Rate (DDR) SDRAM Peripheral Library 656 EBI Peripheral Library 723 Ethernet Peripheral Library 780 GLCD Controller Peripheral Library 927 I2C Peripheral Library 1048 Input Capture Peripheral Library 1132 Interrupt Peripheral Library 1157 NVM Peripheral Library 1211 Oscillator Peripheral Library 1302 Output Compare Peripheral Library 1273 PMP Peripheral Library 1415 Ports Peripheral Library 1556 Power Peripheral Library 1642 Prefetch Cache Peripheral Library 1506 Reset Peripheral Library 1689 RTCC Peripheral Library 1710 SPI Peripheral Library 1827 SQI Peripheral Library 1908 System Bus Peripheral Library 1766 Timer Peripheral Library 2043 USART Peripheral Library 2086 USB Peripheral Library 2169 USBHS Peripheral Library 2311 Watchdog Timer Peripheral Library 2361 Library Overview 23, 87, 219, 267, 302, 400, 440, 471, 486, 523, 654, 722, 766, 923, 1026, 1130, 1156, 1205, 1270, 1298, 1408, 1503, 1554, 1641, 1688, 1704, 1764, 1807, 1901, 2039, 2075, 2164, 2311, 2360 ADCHS Peripheral Library 87 ADCP Peripheral Library 219 CAN Peripheral Library 302 Comparator Peripheral Library 400 CTMU Peripheral Library 440 Deadman Timer Peripheral Library 471 Device Control Peripheral Library 486 DMA Peripheral Library 523 Dual Data Rate (DDR) SDRAM Peripheral Library 654 GLCD Controller Peripheral Library 923 I2C Peripheral Library 1026 Interrupt Peripheral Library 1156 NVM Peripheral Library 1205 Oscillator Peripheral Library 1298 Peripheral Library 23 PMP Peripheral Library 1408 Ports Peripheral Library 1554 Power Peripheral Library 1641 Prefetch Cache Peripheral Library 1503 Reset Peripheral Library 1688 RTCC Peripheral Library 1704 SPI Peripheral Library 1807 SQI Peripheral Library 1901 Timer Peripheral Library 2039 USART Peripheral Library 2075 USB Peripheral Library 2164 USBHS Peripheral Library 2311 Watchdog Timer Peripheral Library 2360 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2376 M Managing Slave Addresses 1044 Master Mode 1823 Measuring Pulse Width 445 Measuring Time Between Pulses 444 Media Independent Interface (MII) 769 Memory Access Control 269 Miscellaneous Control 926 Miscellaneous Functions 1210 Mode Configuration 304 Module Events 310 N NVM Peripheral Library 1204 NVM_BOOT_MEMORY_AREA enumeration 1261 NVM_BOOT_MEMORY_PAGE enumeration 1261 NVM_FLASH_SWAP_LOCK_TYPE enumeration 1263 NVM_MODULE_ID enumeration 1263 NVM_OPERATION_MODE enumeration 1262 O OC_16BIT_TIMERS enumeration 1292 OC_ALT_TIMERS enumeration 1294 OC_BUFFER_SIZE enumeration 1292 OC_COMPARE_MODES enumeration 1292 OC_FAULTS enumeration 1293 OC_MODULE_ID enumeration 1294 Operating as a Master 1411 Operating as a Master Receiver 1035 Operating as a Master Transmitter 1031 Operating as a Slave 1412 Operating as a Slave Receiver 1029 Operating as a Slave Transmitter 1030 Operating/Addressing Mode Management 526 OSC_CLOCK_ID enumeration 1400 OSC_CLOCK_SLEW_TYPE enumeration 1401 OSC_FRC_DIV enumeration 1395 OSC_MODULE_ID enumeration 1395 OSC_OPERATION_ON_WAIT enumeration 1396 OSC_PB_CLOCK_DIV_TYPE macro 1394 OSC_PERIPHERAL_BUS enumeration 1396 OSC_PLL_SELECT enumeration 1397 OSC_REF_DIVISOR_TYPE macro 1394 OSC_REFERENCE enumeration 1397 OSC_REFERENCE_MAX_DIV macro 1394 OSC_SLEEP_TO_STARTUP_CLK_TYPE enumeration 1401 OSC_SYS_TYPE enumeration 1398 OSC_SYSPLL_FREQ_RANGE enumeration 1399 OSC_SYSPLL_IN_CLK_SOURCE enumeration 1399 OSC_SYSPLL_MULTIPLIER_TYPE macro 1395 OSC_SYSPLL_OUT_DIV enumeration 1399 OSC_USBCLOCK_SOURCE enumeration 1400 Oscillator Peripheral Library 1297 Oscillator Selection and Switching 1299 Other Features 1047, 1415, 1826, 2043, 2085 Other Functionality 98, 223, 1709 Output Compare Peripheral Library 1268 P Palette and Gamma Correction Control 926 PCACHE_MODULE_ID enumeration 1546 Peripheral Libraries Help 2 Peripheral Library Overview 3 Peripheral Library Porting Example 7 PGV Error Handling 1765 PIO Mode 1905 plib_adc.h 82 PLIB_ADC_CalibrationDisable function 40 PLIB_ADC_CalibrationEnable function 40 PLIB_ADC_ConversionClockGet function 47 PLIB_ADC_ConversionClockSet function 46 PLIB_ADC_ConversionClockSourceSelect function 48 PLIB_ADC_ConversionHasCompleted function 44 PLIB_ADC_ConversionStart function 44 PLIB_ADC_ConversionStopSequenceDisable function 46 PLIB_ADC_ConversionStopSequenceEnable function 45 PLIB_ADC_ConversionTriggerSourceSelect function 45 PLIB_ADC_Disable function 37 PLIB_ADC_Enable function 37 PLIB_ADC_ExistsCalibrationControl function 58 PLIB_ADC_ExistsConversionClock function 59 PLIB_ADC_ExistsConversionClockSource function 60 PLIB_ADC_ExistsConversionControl function 60 PLIB_ADC_ExistsConversionStatus function 61 PLIB_ADC_ExistsConversionStopSequenceControl function 61 PLIB_ADC_ExistsConversionTriggerSource function 62 PLIB_ADC_ExistsEnableControl function 62 PLIB_ADC_ExistsMuxChannel0NegativeInput function 63 PLIB_ADC_ExistsMuxChannel0PositiveInput function 63 PLIB_ADC_ExistsMuxInputScanControl function 64 PLIB_ADC_ExistsMuxInputScanSelect function 64 PLIB_ADC_ExistsMuxInputScanSelectExtended function 71 PLIB_ADC_ExistsResultBufferFillStatus function 65 PLIB_ADC_ExistsResultBufferMode function 65 PLIB_ADC_ExistsResultFormat function 66 PLIB_ADC_ExistsResultGetByIndex function 67 PLIB_ADC_ExistsSamplesPerInterruptSelect function 67 PLIB_ADC_ExistsSamplingAcquisitionTime function 68 PLIB_ADC_ExistsSamplingAutoStart function 68 PLIB_ADC_ExistsSamplingControl function 69 PLIB_ADC_ExistsSamplingModeControl function 69 PLIB_ADC_ExistsSamplingStatus function 70 PLIB_ADC_ExistsStopInIdleControl function 70 PLIB_ADC_ExistsVoltageReference function 71 PLIB_ADC_InputScanMaskAdd function 41 PLIB_ADC_InputScanMaskAddExtended function 42 PLIB_ADC_InputScanMaskRemove function 41 PLIB_ADC_InputScanMaskRemoveExtended function 43 PLIB_ADC_MuxAInputScanDisable function 56 PLIB_ADC_MuxAInputScanEnable function 57 PLIB_ADC_MuxChannel0InputNegativeSelect function 57 PLIB_ADC_MuxChannel0InputPositiveSelect function 58 PLIB_ADC_ResultBufferModeSelect function 53 PLIB_ADC_ResultBufferStatusGet function 54 PLIB_ADC_ResultFormatSelect function 55 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2377 PLIB_ADC_ResultGetByIndex function 55 PLIB_ADC_SampleAcquisitionTimeSet function 53 PLIB_ADC_SampleAutoStartDisable function 48 PLIB_ADC_SampleAutoStartEnable function 49 PLIB_ADC_SamplesPerInterruptSelect function 50 PLIB_ADC_SamplingIsActive function 50 PLIB_ADC_SamplingModeSelect function 51 PLIB_ADC_SamplingStart function 52 PLIB_ADC_SamplingStop function 52 PLIB_ADC_StopInIdleDisable function 38 PLIB_ADC_StopInIdleEnable function 38 PLIB_ADC_VoltageReferenceSelect function 39 plib_adchs.h 214 PLIB_ADCHS_AnalogInputDataIsReady function 118 PLIB_ADCHS_AnalogInputDataReadyInterruptDisable function 119 PLIB_ADCHS_AnalogInputDataReadyInterruptEnable function 120 PLIB_ADCHS_AnalogInputEarlyInterruptDisable function 120 PLIB_ADCHS_AnalogInputEarlyInterruptEnable function 121 PLIB_ADCHS_AnalogInputEarlyInterruptIsReady function 122 PLIB_ADCHS_AnalogInputEdgeTriggerSet function 130 PLIB_ADCHS_AnalogInputIsAvailable function 123 PLIB_ADCHS_AnalogInputLevelTriggerSet function 131 PLIB_ADCHS_AnalogInputModeGet function 123 PLIB_ADCHS_AnalogInputModeSelect function 127 PLIB_ADCHS_AnalogInputResultGet function 124 PLIB_ADCHS_AnalogInputScanIsComplete function 125 PLIB_ADCHS_AnalogInputScanIsSelected function 125 PLIB_ADCHS_AnalogInputScanRemove function 126 PLIB_ADCHS_AnalogInputScanSelect function 128 PLIB_ADCHS_AnalogInputScanSetup function 131 PLIB_ADCHS_AnalogInputTriggerSourceSelect function 132 PLIB_ADCHS_ChannelAnalogFeatureDisable function 157 PLIB_ADCHS_ChannelAnalogFeatureEnable function 158 PLIB_ADCHS_ChannelConfigurationGet function 159 PLIB_ADCHS_ChannelConfigurationSet function 160 PLIB_ADCHS_ChannelDigitalFeatureDisable function 160 PLIB_ADCHS_ChannelDigitalFeatureEnable function 161 PLIB_ADCHS_ChannelInputSelect function 166 PLIB_ADCHS_ChannelIsReady function 162 PLIB_ADCHS_ChannelIsReadyInterruptDisable function 163 PLIB_ADCHS_ChannelIsReadyInterruptEnable function 163 PLIB_ADCHS_ChannelSetup function 164 PLIB_ADCHS_ChannelTriggerSampleSelect function 129 PLIB_ADCHS_ControlRegistersCanBeUpdated function 106 PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptDisable function 107 PLIB_ADCHS_ControlRegistersCanBeUpdatedInterruptEnable function 107 PLIB_ADCHS_CVDDisable function 115 PLIB_ADCHS_CVDEnable function 116 PLIB_ADCHS_CVDResultGet function 116 PLIB_ADCHS_CVDSetup function 117 PLIB_ADCHS_DigitalComparatorAnalogInputGet function 133 PLIB_ADCHS_DigitalComparatorAnalogInputSelect function 134 PLIB_ADCHS_DigitalComparatorDisable function 135 PLIB_ADCHS_DigitalComparatorEnable function 135 PLIB_ADCHS_DigitalComparatorEventHasOccurred function 136 PLIB_ADCHS_DigitalComparatorInterruptDisable function 137 PLIB_ADCHS_DigitalComparatorInterruptEnable function 138 PLIB_ADCHS_DigitalComparatorLimitSet function 138 PLIB_ADCHS_DigitalComparatorSetup function 139 PLIB_ADCHS_DigitalFilterAveragingModeSampleCountSelect function 141 PLIB_ADCHS_DigitalFilterAveragingModeSetup function 141 PLIB_ADCHS_DigitalFilterDataGet function 142 PLIB_ADCHS_DigitalFilterDataIsReady function 143 PLIB_ADCHS_DigitalFilterDataReadyInterruptDisable function 144 PLIB_ADCHS_DigitalFilterDataReadyInterruptEnable function 145 PLIB_ADCHS_DigitalFilterDisable function 145 PLIB_ADCHS_DigitalFilterEnable function 146 PLIB_ADCHS_DigitalFilterOversamplingModeRatioSelect function 147 PLIB_ADCHS_DigitalFilterOversamplingModeSetup function 147 PLIB_ADCHS_Disable function 103 PLIB_ADCHS_DMABuffer_A_InterruptDisable function 149 PLIB_ADCHS_DMABuffer_A_InterruptEnable function 149 PLIB_ADCHS_DMABuffer_A_IsFull function 150 PLIB_ADCHS_DMABuffer_B_InterruptDisable function 151 PLIB_ADCHS_DMABuffer_B_InterruptEnable function 151 PLIB_ADCHS_DMABuffer_B_IsFull function 152 PLIB_ADCHS_DMADisable function 153 PLIB_ADCHS_DMAEnable function 154 PLIB_ADCHS_DMAOverflowErrorHasOccurred function 154 PLIB_ADCHS_DMASetup function 155 PLIB_ADCHS_DMASourceRemove function 156 PLIB_ADCHS_DMASourceSelect function 157 PLIB_ADCHS_EarlyInterruptDisable function 174 PLIB_ADCHS_EarlyInterruptEnable function 174 PLIB_ADCHS_Enable function 104 PLIB_ADCHS_ExistsAnalogInputCheck function 182 PLIB_ADCHS_ExistsAnalogInputModeControl function 182 PLIB_ADCHS_ExistsAnalogInputScan function 183 PLIB_ADCHS_ExistsChannelAnalogControl function 183 PLIB_ADCHS_ExistsChannelConfiguration function 184 PLIB_ADCHS_ExistsChannelDigitalControl function 185 PLIB_ADCHS_ExistsChannelInputSelectControl function 185 PLIB_ADCHS_ExistsConfiguration function 186 PLIB_ADCHS_ExistsConversionResults function 186 PLIB_ADCHS_ExistsCVD function 187 PLIB_ADCHS_ExistsDigitalComparator function 187 PLIB_ADCHS_ExistsDigitalFilter function 188 PLIB_ADCHS_ExistsDMA function 189 PLIB_ADCHS_ExistsEarlyInterruptControl function 190 PLIB_ADCHS_ExistsEnableControl function 190 PLIB_ADCHS_ExistsExternalConversionRequestControl function 191 PLIB_ADCHS_ExistsFIFO function 191 PLIB_ADCHS_ExistsManualControl function 192 PLIB_ADCHS_ExistsTriggerControl function 193 PLIB_ADCHS_ExistsTriggerSampleControl function 193 PLIB_ADCHS_ExistsTurboMode function 194 PLIB_ADCHS_ExistsUpdateReadyControl function 194 PLIB_ADCHS_ExistsVREFControl function 195 PLIB_ADCHS_ExternalConversionRequestDisable function 108 PLIB_ADCHS_ExternalConversionRequestEnable function 108 PLIB_ADCHS_FIFODataCountGet function 167 PLIB_ADCHS_FIFODataIsAvailable function 167 PLIB_ADCHS_FIFODataIsNegative function 168 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2378 PLIB_ADCHS_FIFODataReadyInterruptDisable function 169 PLIB_ADCHS_FIFODataReadyInterruptEnable function 169 PLIB_ADCHS_FIFODisable function 170 PLIB_ADCHS_FIFOEnable function 170 PLIB_ADCHS_FIFOErrorHasOccurred function 171 PLIB_ADCHS_FIFORead function 172 PLIB_ADCHS_FIFOSourceGet function 172 PLIB_ADCHS_FIFOSourceSelect function 173 PLIB_ADCHS_GlobalLevelSoftwareTriggerDisable function 109 PLIB_ADCHS_GlobalLevelSoftwareTriggerEnable function 109 PLIB_ADCHS_GlobalSoftwareTriggerEnable function 110 PLIB_ADCHS_ScanCompleteInterruptDisable function 111 PLIB_ADCHS_ScanCompleteInterruptEnable function 111 PLIB_ADCHS_Setup function 104 PLIB_ADCHS_SoftwareConversionInputSelect function 112 PLIB_ADCHS_SoftwareConversionStart function 113 PLIB_ADCHS_SoftwareSamplingStart function 113 PLIB_ADCHS_SoftwareSamplingStop function 114 PLIB_ADCHS_TriggerSuspendDisable function 114 PLIB_ADCHS_TriggerSuspendEnable function 115 PLIB_ADCHS_TurboModeChannelSelect function 175 PLIB_ADCHS_TurboModeDisable function 176 PLIB_ADCHS_TurboModeEnable function 177 PLIB_ADCHS_TurboModeErrorHasOccurred function 177 PLIB_ADCHS_VREFFaultHasOccurred function 178 PLIB_ADCHS_VREFFaultInterruptDisable function 179 PLIB_ADCHS_VREFFaultInterruptEnable function 179 PLIB_ADCHS_VREFIsReady function 180 PLIB_ADCHS_VREFReadyInterruptDisable function 180 PLIB_ADCHS_VREFReadyInterruptEnable function 181 plib_adcp.h 263 PLIB_ADCP_AlternateInputSelect function 235 PLIB_ADCP_CalibrationStart function 229 PLIB_ADCP_ChannelScanConfigure function 238 PLIB_ADCP_Class12TriggerConfigure function 240 PLIB_ADCP_Configure function 227 PLIB_ADCP_DefaultInputSelect function 235 PLIB_ADCP_DigCmpAIdGet function 246 PLIB_ADCP_DigCmpConfig function 246 PLIB_ADCP_DigCmpDisable function 245 PLIB_ADCP_DigCmpEnable function 244 PLIB_ADCP_Disable function 228 PLIB_ADCP_Enable function 228 PLIB_ADCP_ExistsCalibration function 231 PLIB_ADCP_ExistsChannelScan function 239 PLIB_ADCP_ExistsConfiguration function 233 PLIB_ADCP_ExistsConversionResults function 244 PLIB_ADCP_ExistsDigCmp function 248 PLIB_ADCP_ExistsEnableControl function 232 PLIB_ADCP_ExistsInputSelect function 236 PLIB_ADCP_ExistsLowPowerControl function 232 PLIB_ADCP_ExistsModeSelect function 237 PLIB_ADCP_ExistsOsampDigFilter function 251 PLIB_ADCP_ExistsReadyStatus function 234 PLIB_ADCP_ExistsTriggering function 241 PLIB_ADCP_GlobalSoftwareTrigger function 239 PLIB_ADCP_IndividualTrigger function 240 PLIB_ADCP_LowPowerStateEnter function 230 PLIB_ADCP_LowPowerStateExit function 230 PLIB_ADCP_LowPowerStateGet function 231 PLIB_ADCP_ModuleIsReady function 233 PLIB_ADCP_OsampDigFilterConfig function 251 PLIB_ADCP_OsampDigFilterDataGet function 250 PLIB_ADCP_OsampDigFilterDataRdy function 249 PLIB_ADCP_OsampDigFilterDisable function 249 PLIB_ADCP_OsampDigFilterEnable function 248 PLIB_ADCP_ResultGet function 242 PLIB_ADCP_ResultReady function 242 PLIB_ADCP_ResultReadyGrpIntConfigure function 243 PLIB_ADCP_SHModeSelect function 237 plib_bmx.h 298 PLIB_BMX_ARB_MODE enumeration 296 PLIB_BMX_ArbitrationModeGet function 280 PLIB_BMX_ArbitrationModeSet function 280 PLIB_BMX_BusExceptionDataDisable function 273 PLIB_BMX_BusExceptionDataEnable function 274 PLIB_BMX_BusExceptionDMADisable function 274 PLIB_BMX_BusExceptionDMAEnable function 275 PLIB_BMX_BusExceptionICDDisable function 275 PLIB_BMX_BusExceptionICDEnable function 276 PLIB_BMX_BusExceptionInstructionDisable function 276 PLIB_BMX_BusExceptionInstructionEnable function 277 PLIB_BMX_BusExceptionIXIDisable function 277 PLIB_BMX_BusExceptionIXIEnable function 278 PLIB_BMX_DATA_RAM_WAIT_STATES enumeration 296 PLIB_BMX_DataRAMKernelProgramOffsetGet function 281 PLIB_BMX_DataRAMPartitionSet function 282 PLIB_BMX_DataRAMSizeGet function 283 PLIB_BMX_DataRAMUserDataOffsetGet function 283 PLIB_BMX_DataRAMUserProgramOffsetGet function 284 PLIB_BMX_DataRamWaitStateGet function 284 PLIB_BMX_DataRamWaitStateSet function 285 PLIB_BMX_DRM_BLOCK_SIZE macro 297 PLIB_BMX_EXCEPTION_SRC enumeration 297 PLIB_BMX_ExistsArbitrationMode function 288 PLIB_BMX_ExistsBusExceptionData function 289 PLIB_BMX_ExistsBusExceptionDMA function 289 PLIB_BMX_ExistsBusExceptionICD function 290 PLIB_BMX_ExistsBusExceptionInstruction function 290 PLIB_BMX_ExistsBusExceptionIXI function 291 PLIB_BMX_ExistsDataRAMPartition function 292 PLIB_BMX_ExistsDataRAMSize function 292 PLIB_BMX_ExistsDataRamWaitState function 293 PLIB_BMX_ExistsProgramFlashBootSize function 293 PLIB_BMX_ExistsProgramFlashMemoryCacheDma function 294 PLIB_BMX_ExistsProgramFlashMemorySize function 294 PLIB_BMX_ExistsProgramFlashPartition function 295 PLIB_BMX_PFM_BLOCK_SIZE macro 297 PLIB_BMX_ProgramFlashBootSizeGet function 286 PLIB_BMX_ProgramFlashMemoryCacheDmaDisable function 279 PLIB_BMX_ProgramFlashMemoryCacheDmaEnable function 279 PLIB_BMX_ProgramFlashMemorySizeGet function 286 PLIB_BMX_ProgramFlashPartitionGet function 287 PLIB_BMX_ProgramFlashPartitionSet function 287 plib_can.h 395 PLIB_CAN_AllChannelEventsGet function 337 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2379 PLIB_CAN_AllChannelOverflowStatusGet function 338 PLIB_CAN_BaudRateGet function 326 PLIB_CAN_BaudRatePrescaleSetup function 327 PLIB_CAN_BitSamplePhaseSet function 329 PLIB_CAN_BusActivityWakeupDisable function 314 PLIB_CAN_BusActivityWakeupEnable function 314 PLIB_CAN_BusLine3TimesSamplingDisable function 325 PLIB_CAN_BusLine3TimesSamplingEnable function 326 PLIB_CAN_ChannelEventClear function 339 PLIB_CAN_ChannelEventDisable function 334 PLIB_CAN_ChannelEventEnable function 340 PLIB_CAN_ChannelEventGet function 340 PLIB_CAN_ChannelForReceiveSet function 330 PLIB_CAN_ChannelForTransmitSet function 331 PLIB_CAN_ChannelReset function 332 PLIB_CAN_ChannelResetIsComplete function 322 PLIB_CAN_ChannelUpdate function 333 PLIB_CAN_DeviceNetConfigure function 323 PLIB_CAN_Disable function 315 PLIB_CAN_Enable function 315 PLIB_CAN_ErrorStateGet function 354 PLIB_CAN_ExistsActiveStatus function 357 PLIB_CAN_ExistsAllChannelEvents function 358 PLIB_CAN_ExistsAllChannelOverflow function 358 PLIB_CAN_ExistsBaudRateGet function 377 PLIB_CAN_ExistsBaudRatePrescaleSetup function 378 PLIB_CAN_ExistsBitSamplePhaseSet function 378 PLIB_CAN_ExistsBusActivityWakeup function 359 PLIB_CAN_ExistsBusLine3TimesSampling function 359 PLIB_CAN_ExistsChannelEvent function 360 PLIB_CAN_ExistsChannelEventEnable function 360 PLIB_CAN_ExistsChannelForReceiveSet function 361 PLIB_CAN_ExistsChannelForTransmitSet function 361 PLIB_CAN_ExistsChannelReset function 362 PLIB_CAN_ExistsChannelUpdate function 362 PLIB_CAN_ExistsDeviceNet function 363 PLIB_CAN_ExistsEnableControl function 364 PLIB_CAN_ExistsErrorState function 364 PLIB_CAN_ExistsFilterConfigure function 365 PLIB_CAN_ExistsFilterEnable function 365 PLIB_CAN_ExistsFilterMaskConfigure function 366 PLIB_CAN_ExistsFilterToChannelLink function 366 PLIB_CAN_ExistsLatestFilterMatchGet function 367 PLIB_CAN_ExistsMemoryBufferAssign function 367 PLIB_CAN_ExistsModuleEventClear function 368 PLIB_CAN_ExistsModuleEventEnable function 368 PLIB_CAN_ExistsModuleInfo function 369 PLIB_CAN_ExistsOperationModeRead function 370 PLIB_CAN_ExistsOperationModeWrite function 370 PLIB_CAN_ExistsPendingEventsGet function 371 PLIB_CAN_ExistsPendingTransmissionsAbort function 371 PLIB_CAN_ExistsPrecalculatedBitRateSetup function 379 PLIB_CAN_ExistsReceivedMessageGet function 372 PLIB_CAN_ExistsReceiveErrorCount function 372 PLIB_CAN_ExistsStopInIdle function 373 PLIB_CAN_ExistsTimeStampEnable function 373 PLIB_CAN_ExistsTimeStampPrescaler function 321 PLIB_CAN_ExistsTimeStampValue function 374 PLIB_CAN_ExistsTransmissionIsAborted function 374 PLIB_CAN_ExistsTransmitBufferGet function 375 PLIB_CAN_ExistsTransmitChannelFlush function 375 PLIB_CAN_ExistsTransmitChannelStatus function 376 PLIB_CAN_ExistsTransmitErrorCountGet function 377 PLIB_CAN_FilterConfigure function 348 PLIB_CAN_FilterDisable function 349 PLIB_CAN_FilterEnable function 350 PLIB_CAN_FilterIsDisabled function 350 PLIB_CAN_FilterMaskConfigure function 351 PLIB_CAN_FilterToChannelLink function 352 plib_can_help.h 398 PLIB_CAN_IsActive function 316 PLIB_CAN_LatestFilterMatchGet function 353 PLIB_CAN_MemoryBufferAssign function 322 PLIB_CAN_ModuleEventClear function 334 PLIB_CAN_ModuleEventDisable function 335 PLIB_CAN_ModuleEventEnable function 336 PLIB_CAN_ModuleEventGet function 336 PLIB_CAN_OperationModeGet function 317 PLIB_CAN_OperationModeSelect function 317 PLIB_CAN_PendingEventsGet function 342 PLIB_CAN_PendingTransmissionsAbort function 342 PLIB_CAN_PrecalculatedBitRateSetup function 328 PLIB_CAN_ReceivedMessageGet function 347 PLIB_CAN_ReceiveErrorCountGet function 354 PLIB_CAN_StopInIdleDisable function 318 PLIB_CAN_StopInIdleEnable function 319 PLIB_CAN_TimeStampDisable function 319 PLIB_CAN_TimeStampEnable function 320 PLIB_CAN_TimeStampPrescalerSet function 321 PLIB_CAN_TimeStampValueGet function 324 PLIB_CAN_TimeStampValueSet function 324 PLIB_CAN_TotalChannelsGet function 355 PLIB_CAN_TotalFiltersGet function 356 PLIB_CAN_TotalMasksGet function 356 PLIB_CAN_TransmissionIsAborted function 343 PLIB_CAN_TransmitBufferGet function 344 PLIB_CAN_TransmitChannelFlush function 345 PLIB_CAN_TransmitChannelStatusGet function 345 PLIB_CAN_TransmitErrorCountGet function 346 plib_cmp.h 436 PLIB_CMP_CVREF_BandGapReferenceSourceSelect function 404 PLIB_CMP_CVREF_Disable function 410 PLIB_CMP_CVREF_Enable function 404 PLIB_CMP_CVREF_OutputDisable function 405 PLIB_CMP_CVREF_OutputEnable function 406 PLIB_CMP_CVREF_ReferenceVoltageSelect function 406 PLIB_CMP_CVREF_SourceNegativeInputSelect function 407 PLIB_CMP_CVREF_SourceVoltageSelect function 407 PLIB_CMP_CVREF_ValueSelect function 408 PLIB_CMP_CVREF_WideRangeDisable function 408 PLIB_CMP_CVREF_WideRangeEnable function 409 PLIB_CMP_CVREF_WideRangeIsEnabled function 410 PLIB_CMP_Disable function 411 PLIB_CMP_Enable function 411 PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect function 419 PLIB_CMP_ExistsCVREFEnableControl function 420 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2380 PLIB_CMP_ExistsCVREFOutputEnableControl function 421 PLIB_CMP_ExistsCVREFRefVoltageRangeSelect function 421 PLIB_CMP_ExistsCVREFValueSelect function 422 PLIB_CMP_ExistsCVREFVoltageRangeSelect function 422 PLIB_CMP_ExistsCVREFWideRangeControl function 423 PLIB_CMP_ExistsEnableControl function 423 PLIB_CMP_ExistsInterruptEventSelect function 424 PLIB_CMP_ExistsInvertingInputSelect function 424 PLIB_CMP_ExistsInvertOutputControl function 425 PLIB_CMP_ExistsNonInvertingInputSelect function 425 PLIB_CMP_ExistsOutputEnableControl function 426 PLIB_CMP_ExistsOutputLevelControl function 426 PLIB_CMP_ExistsOutputStatusGet function 428 PLIB_CMP_ExistsStopInIdle function 427 PLIB_CMP_InterruptEventSelect function 412 PLIB_CMP_InvertingInputChannelSelect function 413 PLIB_CMP_NonInvertingInputChannelSelect function 413 PLIB_CMP_OutputDisable function 414 PLIB_CMP_OutputEnable function 414 PLIB_CMP_OutputInvertDisable function 416 PLIB_CMP_OutputInvertEnable function 416 PLIB_CMP_OutputLogicHigh function 417 PLIB_CMP_OutputLogicLow function 418 PLIB_CMP_OutputStatusGet function 415 PLIB_CMP_StopInIdleModeDisable function 418 PLIB_CMP_StopInIdleModeEnable function 419 plib_ctmu.h 468 PLIB_CTMU_AutomaticADCTriggerDisable function 452 PLIB_CTMU_AutomaticADCTriggerEnable function 452 PLIB_CTMU_CurrentDischargeDisable function 453 PLIB_CTMU_CurrentDischargeEnable function 453 PLIB_CTMU_CurrentRangeSet function 449 PLIB_CTMU_CurrentTrimSet function 454 PLIB_CTMU_Disable function 449 PLIB_CTMU_EdgeDisable function 456 PLIB_CTMU_EdgeEnable function 456 PLIB_CTMU_EdgeIsSet function 458 PLIB_CTMU_EdgePolaritySet function 459 PLIB_CTMU_EdgeSensitivitySet function 459 PLIB_CTMU_EdgeSequenceDisable function 457 PLIB_CTMU_EdgeSequenceEnable function 457 PLIB_CTMU_EdgeSet function 460 PLIB_CTMU_EdgeTriggerSourceSelect function 460 PLIB_CTMU_Enable function 450 PLIB_CTMU_ExistsAutomaticADCTrigger function 461 PLIB_CTMU_ExistsCurrentDischarge function 462 PLIB_CTMU_ExistsCurrentRange function 462 PLIB_CTMU_ExistsCurrentTrim function 463 PLIB_CTMU_ExistsEdgeEnable function 463 PLIB_CTMU_ExistsEdgePolarity function 464 PLIB_CTMU_ExistsEdgeSensitivity function 464 PLIB_CTMU_ExistsEdgeSequencing function 465 PLIB_CTMU_ExistsEdgeStatus function 465 PLIB_CTMU_ExistsEdgeTriggerSource function 466 PLIB_CTMU_ExistsModuleEnable function 467 PLIB_CTMU_ExistsStopInIdle function 467 PLIB_CTMU_ExistsTimePulseGeneration function 468 PLIB_CTMU_StopInIdleDisable function 450 PLIB_CTMU_StopInIdleEnable function 451 PLIB_CTMU_TimePulseGenerationDisable function 454 PLIB_CTMU_TimePulseGenerationEnable function 455 plib_ddr.h 718 PLIB_DDR_AutoPchrgDisable function 663 PLIB_DDR_AutoPchrgEnable function 667 PLIB_DDR_AutoPchrgPowerDownDisable function 665 PLIB_DDR_AutoPchrgPowerDownEnable function 666 PLIB_DDR_AutoPowerDownDisable function 664 PLIB_DDR_AutoPowerDownEnable function 666 PLIB_DDR_AutoSelfRefreshDisable function 665 PLIB_DDR_AutoSelfRefreshEnable function 667 PLIB_DDR_BankAddressSet function 674 PLIB_DDR_BigEndianSet function 659 PLIB_DDR_ChipSelectAddressSet function 675 PLIB_DDR_CmdDataIsComplete function 670 PLIB_DDR_CmdDataSend function 671 PLIB_DDR_CmdDataValid function 671 PLIB_DDR_CmdDataWrite function 673 PLIB_DDR_ColumnAddressSet function 675 PLIB_DDR_ControllerEnable function 672 PLIB_DDR_DataDelaySet function 678 PLIB_DDR_ExistsAddressMapping function 706 PLIB_DDR_ExistsArbitrationControl function 707 PLIB_DDR_ExistsAutoPowerDown function 707 PLIB_DDR_ExistsAutoPrecharge function 708 PLIB_DDR_ExistsAutoSelfRefresh function 709 PLIB_DDR_ExistsDDRCommands function 709 PLIB_DDR_ExistsDDRControllerConfig function 710 PLIB_DDR_ExistsODTConfig function 710 PLIB_DDR_ExistsPHY_DLLCalibration function 711 PLIB_DDR_ExistsPHY_PadConfig function 711 PLIB_DDR_ExistsPHY_SCLConfig function 712 PLIB_DDR_ExistsRefreshConfig function 713 PLIB_DDR_ExistsTimingDelays function 713 PLIB_DDR_FullRateSet function 659 PLIB_DDR_HalfRateSet function 660 PLIB_DDR_LittleEndianSet function 660 PLIB_DDR_MaxCmdBrstCntSet function 672 PLIB_DDR_MaxPendingRefSet function 661 PLIB_DDR_MinCommand function 668 PLIB_DDR_MinLimit function 669 PLIB_DDR_NumHostCmdsSet function 673 PLIB_DDR_OdtReadDisable function 661 PLIB_DDR_OdtReadEnable function 662 PLIB_DDR_OdtReadParamSet function 677 PLIB_DDR_OdtWriteDisable function 662 PLIB_DDR_OdtWriteEnable function 663 PLIB_DDR_OdtWriteParamSet function 677 PLIB_DDR_PHY_AddCtlDriveStrengthSet function 704 PLIB_DDR_PHY_DataDriveStrengthSet function 705 PLIB_DDR_PHY_DDRTypeSet function 689 PLIB_DDR_PHY_DllMasterDelayStartSet function 689 PLIB_DDR_PHY_DllRecalibDisable function 690 PLIB_DDR_PHY_DllRecalibEnable function 691 PLIB_DDR_PHY_DriveStrengthSet function 691 PLIB_DDR_PHY_DrvStrgthCal function 692 PLIB_DDR_PHY_ExternalDllEnable function 692 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2381 PLIB_DDR_PHY_ExtraClockDisable function 693 PLIB_DDR_PHY_ExtraClockEnable function 693 PLIB_DDR_PHY_HalfRateSet function 703 PLIB_DDR_PHY_InternalDllEnable function 694 PLIB_DDR_PHY_OdtCal function 694 PLIB_DDR_PHY_OdtCSDisable function 695 PLIB_DDR_PHY_OdtCSEnable function 695 PLIB_DDR_PHY_OdtDisable function 696 PLIB_DDR_PHY_OdtEnable function 696 PLIB_DDR_PHY_PadReceiveDisable function 701 PLIB_DDR_PHY_PadReceiveEnable function 697 PLIB_DDR_PHY_PreambleDlySet function 698 PLIB_DDR_PHY_ReadCASLatencySet function 698 PLIB_DDR_PHY_SCLCapClkDelaySet function 701 PLIB_DDR_PHY_SCLDDRClkDelaySet function 702 PLIB_DDR_PHY_SCLDelay function 699 PLIB_DDR_PHY_SCLEnable function 699 PLIB_DDR_PHY_SCLStart function 703 PLIB_DDR_PHY_SCLStatus function 704 PLIB_DDR_PHY_SCLTestBurstModeSet function 700 PLIB_DDR_PHY_WriteCASLatencySet function 700 PLIB_DDR_PHY_WriteCmdDelayDisable function 705 PLIB_DDR_PHY_WriteCmdDelayEnable function 706 PLIB_DDR_PowerDownDelaySet function 679 PLIB_DDR_PrechargAllBanksSet function 680 PLIB_DDR_PrechargeToRASDelaySet function 683 PLIB_DDR_RASToCASDelaySet function 683 PLIB_DDR_RASToPrechargeDelaySet function 684 PLIB_DDR_RASToRASBankDelaySet function 685 PLIB_DDR_RASToRASDelaySet function 685 PLIB_DDR_ReadReadDelaySet function 687 PLIB_DDR_ReadToPrechargeDelaySet function 686 PLIB_DDR_ReadWriteDelaySet function 681 PLIB_DDR_RefreshTimingSet function 681 PLIB_DDR_ReqPeriod function 670 PLIB_DDR_RowAddressSet function 676 PLIB_DDR_SelfRefreshDelaySet function 679 PLIB_DDR_TfawDelaySet function 668 PLIB_DDR_WriteReadDelaySet function 688 PLIB_DDR_WriteToPrechargeDelaySet function 687 PLIB_DDR_WriteWriteDelaySet function 682 plib_devcon.h 520 PLIB_DEVCON_2WireJTAGDisableTDO function 489 PLIB_DEVCON_2WireJTAGEnableTDO function 489 PLIB_DEVCON_AlternateClockDisable function 490 PLIB_DEVCON_AlternateClockEnable function 490 PLIB_DEVCON_AnalogIOChargePumpDisable function 498 PLIB_DEVCON_AnalogIOChargePumpEnable function 499 PLIB_DEVCON_BootExtSelect function 500 PLIB_DEVCON_BootIPFSelect function 500 PLIB_DEVCON_DeviceIdGet function 491 PLIB_DEVCON_DeviceRegistersLock function 491 PLIB_DEVCON_DeviceRegistersUnlock function 492 PLIB_DEVCON_DeviceVersionGet function 493 PLIB_DEVCON_ExistsAlternateClock function 508 PLIB_DEVCON_ExistsAnalogChargePumpControl function 499 PLIB_DEVCON_ExistsBootSelection function 514 PLIB_DEVCON_ExistsDeviceRegsLockUnlock function 509 PLIB_DEVCON_ExistsDeviceVerAndId function 509 PLIB_DEVCON_ExistsECCModes function 510 PLIB_DEVCON_ExistsHSUARTControl function 515 PLIB_DEVCON_ExistsIgnoreDebugFreeze function 510 PLIB_DEVCON_ExistsJTAGEnable function 511 PLIB_DEVCON_ExistsJTAGUsesTDO function 511 PLIB_DEVCON_ExistsMPLL function 514 PLIB_DEVCON_ExistsOTPConfigLockUnlock function 515 PLIB_DEVCON_ExistsSystemLockUnlock function 512 PLIB_DEVCON_ExistsTraceOutput function 513 PLIB_DEVCON_ExistsUSB_PHY_SleepModeSet function 513 PLIB_DEVCON_FlashErrCorrectionModeSet function 493 PLIB_DEVCON_HSUARTDisable function 501 PLIB_DEVCON_HSUARTEnable function 501 PLIB_DEVCON_IgnoreDebugFreezeDisable function 494 PLIB_DEVCON_IgnoreDebugFreezeEnable function 494 PLIB_DEVCON_JTAGPortDisable function 495 PLIB_DEVCON_JTAGPortEnable function 495 PLIB_DEVCON_MPLLDisable function 503 PLIB_DEVCON_MPLLEnable function 503 PLIB_DEVCON_MPLLInputDivSet function 504 PLIB_DEVCON_MPLLIsReady function 504 PLIB_DEVCON_MPLLMultiplierSet function 505 PLIB_DEVCON_MPLLODiv1Set function 505 PLIB_DEVCON_MPLLODiv2Set function 506 PLIB_DEVCON_MPLLVrefSet function 506 PLIB_DEVCON_MPLLVregDisable function 507 PLIB_DEVCON_MPLLVregEnable function 507 PLIB_DEVCON_MPLLVregIsReady function 508 PLIB_DEVCON_OTPConfigLock function 502 PLIB_DEVCON_OTPConfigUnlock function 502 PLIB_DEVCON_SystemLock function 496 PLIB_DEVCON_SystemUnlock function 496 PLIB_DEVCON_TraceOutputDisable function 497 PLIB_DEVCON_TraceOutputEnable function 497 PLIB_DEVCON_USBPHYSleepModeSet function 498 plib_dma.h 648 PLIB_DMA_AbortTransferSet function 542 PLIB_DMA_BusyActiveReset function 538 PLIB_DMA_BusyActiveSet function 538 PLIB_DMA_ChannelBitsGet function 609 PLIB_DMA_ChannelPriorityGet function 575 PLIB_DMA_ChannelPrioritySelect function 574 PLIB_DMA_ChannelXAbortIRQSet function 543 PLIB_DMA_ChannelXAddressModeGet function 551 PLIB_DMA_ChannelXAddressModeSelect function 552 PLIB_DMA_ChannelXAutoDisable function 575 PLIB_DMA_ChannelXAutoEnable function 576 PLIB_DMA_ChannelXAutoIsEnabled function 603 PLIB_DMA_ChannelXBufferedDataIsWritten function 604 PLIB_DMA_ChannelXBusyActiveSet function 576 PLIB_DMA_ChannelXBusyInActiveSet function 577 PLIB_DMA_ChannelXBusyIsBusy function 604 PLIB_DMA_ChannelXCellProgressPointerGet function 564 PLIB_DMA_ChannelXCellSizeGet function 565 PLIB_DMA_ChannelXCellSizeSet function 566 PLIB_DMA_ChannelXChainDisable function 577 PLIB_DMA_ChannelXChainEnable function 578 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2382 PLIB_DMA_ChannelXChainIsEnabled function 605 PLIB_DMA_ChannelXChainToHigher function 579 PLIB_DMA_ChannelXChainToLower function 579 PLIB_DMA_ChannelXCollisionStatus function 606 PLIB_DMA_ChannelXDataSizeGet function 566 PLIB_DMA_ChannelXDataSizeSelect function 567 PLIB_DMA_ChannelXDestinationAddressModeGet function 552 PLIB_DMA_ChannelXDestinationAddressModeSelect function 553 PLIB_DMA_ChannelXDestinationPointerGet function 568 PLIB_DMA_ChannelXDestinationSizeGet function 568 PLIB_DMA_ChannelXDestinationSizeSet function 569 PLIB_DMA_ChannelXDestinationStartAddressGet function 559 PLIB_DMA_ChannelXDestinationStartAddressSet function 560 PLIB_DMA_ChannelXDisable function 580 PLIB_DMA_ChannelXDisabledDisablesEvents function 583 PLIB_DMA_ChannelXDisabledEnablesEvents function 584 PLIB_DMA_ChannelXEnable function 580 PLIB_DMA_ChannelXEventIsDetected function 606 PLIB_DMA_ChannelXINTSourceDisable function 547 PLIB_DMA_ChannelXINTSourceEnable function 547 PLIB_DMA_ChannelXINTSourceFlagClear function 548 PLIB_DMA_ChannelXINTSourceFlagGet function 549 PLIB_DMA_ChannelXINTSourceFlagSet function 550 PLIB_DMA_ChannelXINTSourceIsEnabled function 550 PLIB_DMA_ChannelXIsEnabled function 607 PLIB_DMA_ChannelXNullWriteModeDisable function 554 PLIB_DMA_ChannelXNullWriteModeEnable function 554 PLIB_DMA_ChannelXNullWriteModeIsEnabled function 608 PLIB_DMA_ChannelXOperatingTransferModeGet function 555 PLIB_DMA_ChannelXOperatingTransferModeSelect function 555 PLIB_DMA_ChannelXPatternDataGet function 569 PLIB_DMA_ChannelXPatternDataSet function 570 PLIB_DMA_ChannelXPatternIgnoreByteDisable function 585 PLIB_DMA_ChannelXPatternIgnoreByteEnable function 585 PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled function 586 PLIB_DMA_ChannelXPatternIgnoreGet function 586 PLIB_DMA_ChannelXPatternIgnoreSet function 587 PLIB_DMA_ChannelXPatternLengthGet function 588 PLIB_DMA_ChannelXPatternLengthSet function 588 PLIB_DMA_ChannelXPeripheralAddressGet function 560 PLIB_DMA_ChannelXPeripheralAddressSet function 561 PLIB_DMA_ChannelXPingPongModeGet function 608 PLIB_DMA_ChannelXPriorityGet function 581 PLIB_DMA_ChannelXPrioritySelect function 582 PLIB_DMA_ChannelXReloadDisable function 556 PLIB_DMA_ChannelXReloadEnable function 557 PLIB_DMA_ChannelXReloadIsEnabled function 558 PLIB_DMA_ChannelXSourceAddressModeGet function 557 PLIB_DMA_ChannelXSourceAddressModeSelect function 558 PLIB_DMA_ChannelXSourcePointerGet function 571 PLIB_DMA_ChannelXSourceSizeGet function 571 PLIB_DMA_ChannelXSourceSizeSet function 572 PLIB_DMA_ChannelXSourceStartAddressGet function 562 PLIB_DMA_ChannelXSourceStartAddressSet function 562 PLIB_DMA_ChannelXStartAddressOffsetGet function 563 PLIB_DMA_ChannelXStartAddressOffsetSet function 564 PLIB_DMA_ChannelXStartIRQSet function 543 PLIB_DMA_ChannelXTransferCountGet function 573 PLIB_DMA_ChannelXTransferCountSet function 573 PLIB_DMA_ChannelXTransferDirectionGet function 582 PLIB_DMA_ChannelXTransferDirectionSelect function 583 PLIB_DMA_ChannelXTriggerDisable function 544 PLIB_DMA_ChannelXTriggerEnable function 545 PLIB_DMA_ChannelXTriggerIsEnabled function 545 PLIB_DMA_ChannelXTriggerSourceNumberGet function 546 PLIB_DMA_CRCAppendModeDisable function 589 PLIB_DMA_CRCAppendModeEnable function 590 PLIB_DMA_CRCAppendModeIsEnabled function 590 PLIB_DMA_CRCBitOrderSelect function 591 PLIB_DMA_CRCByteOrderGet function 591 PLIB_DMA_CRCByteOrderSelect function 592 PLIB_DMA_CRCChannelGet function 592 PLIB_DMA_CRCChannelSelect function 593 PLIB_DMA_CRCDataRead function 593 PLIB_DMA_CRCDataWrite function 594 PLIB_DMA_CRCDisable function 594 PLIB_DMA_CRCEnable function 595 PLIB_DMA_CRCIsEnabled function 600 PLIB_DMA_CRCPolynomialLengthGet function 595 PLIB_DMA_CRCPolynomialLengthSet function 596 PLIB_DMA_CRCTypeGet function 596 PLIB_DMA_CRCTypeSet function 597 PLIB_DMA_CRCWriteByteOrderAlter function 598 PLIB_DMA_CRCWriteByteOrderMaintain function 598 PLIB_DMA_CRCXOREnableGet function 599 PLIB_DMA_CRCXOREnableSet function 599 PLIB_DMA_Disable function 539 PLIB_DMA_Enable function 539 PLIB_DMA_ExistsAbortTransfer function 609 PLIB_DMA_ExistsBusy function 610 PLIB_DMA_ExistsChannelBits function 611 PLIB_DMA_ExistsChannelX function 611 PLIB_DMA_ExistsChannelXAbortIRQ function 612 PLIB_DMA_ExistsChannelXAuto function 612 PLIB_DMA_ExistsChannelXBusy function 613 PLIB_DMA_ExistsChannelXCellProgressPointer function 613 PLIB_DMA_ExistsChannelXCellSize function 614 PLIB_DMA_ExistsChannelXChain function 614 PLIB_DMA_ExistsChannelXChainEnbl function 615 PLIB_DMA_ExistsChannelXDestinationPointer function 615 PLIB_DMA_ExistsChannelXDestinationSize function 616 PLIB_DMA_ExistsChannelXDestinationStartAddress function 617 PLIB_DMA_ExistsChannelXDisabled function 617 PLIB_DMA_ExistsChannelXEvent function 618 PLIB_DMA_ExistsChannelXINTSource function 618 PLIB_DMA_ExistsChannelXINTSourceFlag function 619 PLIB_DMA_ExistsChannelXPatternData function 619 PLIB_DMA_ExistsChannelXPatternIgnore function 620 PLIB_DMA_ExistsChannelXPatternIgnoreByte function 620 PLIB_DMA_ExistsChannelXPatternLength function 621 PLIB_DMA_ExistsChannelXPriority function 622 PLIB_DMA_ExistsChannelXSourcePointer function 622 PLIB_DMA_ExistsChannelXSourceSize function 623 PLIB_DMA_ExistsChannelXSourceStartAddress function 623 PLIB_DMA_ExistsChannelXStartIRQ function 624 PLIB_DMA_ExistsChannelXTrigger function 624 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2383 PLIB_DMA_ExistsCRC function 625 PLIB_DMA_ExistsCRCAppendMode function 625 PLIB_DMA_ExistsCRCBitOrder function 626 PLIB_DMA_ExistsCRCByteOrder function 627 PLIB_DMA_ExistsCRCChannel function 627 PLIB_DMA_ExistsCRCData function 628 PLIB_DMA_ExistsCRCPolynomialLength function 628 PLIB_DMA_ExistsCRCType function 629 PLIB_DMA_ExistsCRCWriteByteOrder function 629 PLIB_DMA_ExistsCRCXOREnable function 630 PLIB_DMA_ExistsEnableControl function 630 PLIB_DMA_ExistsLastBusAccess function 631 PLIB_DMA_ExistsRecentAddress function 632 PLIB_DMA_ExistsStartTransfer function 632 PLIB_DMA_ExistsStopInIdle function 633 PLIB_DMA_ExistsSuspend function 633 PLIB_DMA_IsBusy function 600 PLIB_DMA_IsEnabled function 601 PLIB_DMA_LastBusAccessIsRead function 601 PLIB_DMA_LastBusAccessIsWrite function 602 PLIB_DMA_RecentAddressAccessed function 602 PLIB_DMA_StartTransferSet function 542 PLIB_DMA_StopInIdleDisable function 540 PLIB_DMA_StopInIdleEnable function 540 PLIB_DMA_SuspendDisable function 541 PLIB_DMA_SuspendEnable function 541 PLIB_DMA_SuspendIsEnabled function 603 plib_dmt.h 485 PLIB_DMT_BAD1Get function 475 PLIB_DMT_BAD2Get function 475 PLIB_DMT_ClearStep1 function 472 PLIB_DMT_ClearStep2 function 473 PLIB_DMT_CounterGet function 476 PLIB_DMT_Disable function 474 PLIB_DMT_Enable function 474 PLIB_DMT_EventOccurred function 479 PLIB_DMT_ExistsCounter function 480 PLIB_DMT_ExistsEnableControl function 481 PLIB_DMT_ExistsPostscalerInterval function 481 PLIB_DMT_ExistsPostscalerValue function 482 PLIB_DMT_ExistsStatus function 482 PLIB_DMT_ExistsStep1 function 483 PLIB_DMT_ExistsStep2 function 483 plib_dmt_help.h 485 PLIB_DMT_IsEnabled function 477 PLIB_DMT_PostscalerIntervalGet function 477 PLIB_DMT_PostscalerValueGet function 478 PLIB_DMT_WindowIsOpen function 479 plib_ebi.h 761 PLIB_EBI_AddressHoldTimeGet function 724 PLIB_EBI_AddressPinEnableBitsSet function 732 PLIB_EBI_AddressSetupTimeGet function 725 PLIB_EBI_BaseAddressGet function 725 PLIB_EBI_BaseAddressSet function 733 PLIB_EBI_ByteSelectPinSet function 733 PLIB_EBI_ChipSelectEnableSet function 734 PLIB_EBI_ControlEnableGet function 726 PLIB_EBI_ControlEnableSet function 742 PLIB_EBI_DataEnableSet function 734 PLIB_EBI_DataTurnAroundTimeGet function 727 PLIB_EBI_ExistsAddressHoldTime function 743 PLIB_EBI_ExistsAddressPinEnableBits function 743 PLIB_EBI_ExistsAddressSetupTime function 744 PLIB_EBI_ExistsBaseAddress function 744 PLIB_EBI_ExistsByteSelectPin function 745 PLIB_EBI_ExistsChipSelectEnable function 746 PLIB_EBI_ExistsControlEnable function 746 PLIB_EBI_ExistsDataEnable function 747 PLIB_EBI_ExistsDataTurnAroundTime function 747 PLIB_EBI_ExistsFlashPowerDownMode function 748 PLIB_EBI_ExistsFlashResetPin function 748 PLIB_EBI_ExistsFlashTiming function 749 PLIB_EBI_ExistsMemoryCharacteristics function 749 PLIB_EBI_ExistsMemoryPaging function 750 PLIB_EBI_ExistsMemoryTimingConfig function 750 PLIB_EBI_ExistsPageMode function 751 PLIB_EBI_ExistsPageReadTime function 751 PLIB_EBI_ExistsReadCycleTime function 752 PLIB_EBI_ExistsReadyMode function 752 PLIB_EBI_ExistsReadyPin1Config function 753 PLIB_EBI_ExistsReadyPin2Config function 754 PLIB_EBI_ExistsReadyPin3Config function 754 PLIB_EBI_ExistsReadyPinSens function 755 PLIB_EBI_ExistsStaticMemoryWidthRegister function 755 PLIB_EBI_ExistsWriteOutputControl function 756 PLIB_EBI_ExistsWritePulseWidth function 756 PLIB_EBI_FlashPowerDownModeGet function 727 PLIB_EBI_FlashPowerDownModeSet function 735 PLIB_EBI_FlashResetPinGet function 728 PLIB_EBI_FlashResetPinSet function 735 PLIB_EBI_FlashTimingGet function 732 PLIB_EBI_FlashTimingSet function 736 plib_ebi_help.h 762 PLIB_EBI_MemoryCharacteristicsSet function 737 PLIB_EBI_MemoryPageSizeGet function 731 PLIB_EBI_MemoryPagingSet function 737 PLIB_EBI_MemoryTimingConfigSet function 738 PLIB_EBI_PageModeGet function 728 PLIB_EBI_PageReadCycleTimeGet function 729 PLIB_EBI_ReadCycleTimeGet function 729 PLIB_EBI_ReadyModeGet function 730 PLIB_EBI_ReadyModeSet function 742 PLIB_EBI_ReadyPin1ConfigSet function 739 PLIB_EBI_ReadyPin2ConfigSet function 739 PLIB_EBI_ReadyPin3ConfigSet function 740 PLIB_EBI_ReadyPinSensSet function 740 PLIB_EBI_StaticMemoryWidthRegisterGet function 730 PLIB_EBI_StaticMemoryWidthRegisterSet function 741 PLIB_EBI_WriteOutputControlSet function 741 PLIB_EBI_WritePulseWidthGet function 731 plib_eth.h 916 PLIB_ETH_AlignErrorCountClear function 882 PLIB_ETH_AlignErrorCountGet function 883 PLIB_ETH_AutoDetectPadClear function 785 PLIB_ETH_AutoDetectPadGet function 786 PLIB_ETH_AutoDetectPadSet function 786 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2384 PLIB_ETH_AutoFlowControlDisable function 860 PLIB_ETH_AutoFlowControlEnable function 860 PLIB_ETH_AutoFlowControlIsEnabled function 861 PLIB_ETH_BackPresNoBackoffDisable function 862 PLIB_ETH_BackPresNoBackoffEnable function 862 PLIB_ETH_BackPresNoBackoffIsEnabled function 863 PLIB_ETH_BackToBackIPGGet function 787 PLIB_ETH_BackToBackIPGSet function 787 PLIB_ETH_CollisionWindowGet function 788 PLIB_ETH_CollisionWindowSet function 788 PLIB_ETH_CRCDisable function 843 PLIB_ETH_CRCEnable function 843 PLIB_ETH_CRCIsEnabled function 844 PLIB_ETH_DataNotValid function 844 PLIB_ETH_DelayedCRCDisable function 789 PLIB_ETH_DelayedCRCEnable function 789 PLIB_ETH_DelayedCRCIsEnabled function 790 PLIB_ETH_Disable function 791 PLIB_ETH_Enable function 791 PLIB_ETH_EthernetIsBusy function 845 PLIB_ETH_ExcessDeferDisable function 792 PLIB_ETH_ExcessDeferEnable function 792 PLIB_ETH_ExcessDeferIsEnabled function 793 PLIB_ETH_ExistsAlignmentErrorCount function 890 PLIB_ETH_ExistsAutoFlowControl function 891 PLIB_ETH_ExistsCollisionCounts function 892 PLIB_ETH_ExistsCollisionWindow function 892 PLIB_ETH_ExistsEnable function 893 PLIB_ETH_ExistsEthernetControllerStatus function 893 PLIB_ETH_ExistsFCSErrorCount function 894 PLIB_ETH_ExistsFramesTransmittedOK function 894 PLIB_ETH_ExistsFramexReceivedOK function 895 PLIB_ETH_ExistsHashTable function 895 PLIB_ETH_ExistsInterPacketGaps function 896 PLIB_ETH_ExistsInterrupt function 897 PLIB_ETH_ExistsMAC_Configuration function 897 PLIB_ETH_ExistsMAC_Resets function 899 PLIB_ETH_ExistsMAC_Testing function 899 PLIB_ETH_ExistsManualFlowControl function 900 PLIB_ETH_ExistsMaxFrameLength function 901 PLIB_ETH_ExistsMIIM_Config function 901 PLIB_ETH_ExistsMIIM_Indicators function 902 PLIB_ETH_ExistsMIIMAddresses function 902 PLIB_ETH_ExistsMIIMReadWrite function 903 PLIB_ETH_ExistsMIIMScanMode function 904 PLIB_ETH_ExistsMIIWriteReadData function 904 PLIB_ETH_ExistsPatternMatch function 905 PLIB_ETH_ExistsPauseTimer function 905 PLIB_ETH_ExistsReceiveBufferSize function 906 PLIB_ETH_ExistsReceiveFilters function 906 PLIB_ETH_ExistsReceiveOverflowCount function 907 PLIB_ETH_ExistsReceiveWmarks function 908 PLIB_ETH_ExistsRetransmissionMaximum function 908 PLIB_ETH_ExistsRMII_Support function 909 PLIB_ETH_ExistsRxBufferCountDecrement function 909 PLIB_ETH_ExistsRxEnable function 910 PLIB_ETH_ExistsRxPacketDescriptorAddress function 910 PLIB_ETH_ExistsStationAddress function 911 PLIB_ETH_ExistsStopInIdle function 911 PLIB_ETH_ExistsTransmitRTS function 912 PLIB_ETH_ExistsTxPacketDescriptorAddress function 913 PLIB_ETH_FCSErrorCountClear function 883 PLIB_ETH_FCSErrorCountGet function 884 PLIB_ETH_FrameLengthCheckDisable function 793 PLIB_ETH_FrameLengthCheckEnable function 794 PLIB_ETH_FrameLengthCheckIsEnabled function 794 PLIB_ETH_FramesRxdOkCountClear function 884 PLIB_ETH_FramesRxdOkCountGet function 885 PLIB_ETH_FramesTxdOkCountClear function 885 PLIB_ETH_FramesTxdOkCountGet function 886 PLIB_ETH_FullDuplexDisable function 795 PLIB_ETH_FullDuplexEnable function 795 PLIB_ETH_FullDuplexIsEnabled function 796 PLIB_ETH_HashTableGet function 848 PLIB_ETH_HashTableSet function 849 PLIB_ETH_HugeFrameDisable function 796 PLIB_ETH_HugeFrameEnable function 797 PLIB_ETH_HugeFrameIsEnabled function 798 PLIB_ETH_InterruptClear function 877 PLIB_ETH_InterruptSet function 878 PLIB_ETH_InterruptsGet function 878 PLIB_ETH_InterruptSourceDisable function 879 PLIB_ETH_InterruptSourceEnable function 879 PLIB_ETH_InterruptSourceIsEnabled function 880 PLIB_ETH_InterruptSourcesGet function 881 PLIB_ETH_InterruptStatusGet function 881 PLIB_ETH_IsEnabled function 798 PLIB_ETH_LinkHasFailed function 845 PLIB_ETH_LongPreambleDisable function 799 PLIB_ETH_LongPreambleEnable function 799 PLIB_ETH_LongPreambleIsEnabled function 800 PLIB_ETH_LoopbackDisable function 800 PLIB_ETH_LoopbackEnable function 801 PLIB_ETH_LoopbackIsEnabled function 801 PLIB_ETH_ManualFlowControlDisable function 863 PLIB_ETH_ManualFlowControlEnable function 864 PLIB_ETH_ManualFlowControlIsEnabled function 864 PLIB_ETH_MaxFrameLengthGet function 802 PLIB_ETH_MaxFrameLengthSet function 802 PLIB_ETH_MCSRxResetDisable function 816 PLIB_ETH_MCSRxResetEnable function 816 PLIB_ETH_MCSRxResetIsEnabled function 817 PLIB_ETH_MCSTxResetDisable function 817 PLIB_ETH_MCSTxResetEnable function 818 PLIB_ETH_MCSTxResetIsEnabled function 818 PLIB_ETH_MIIMClockGet function 803 PLIB_ETH_MIIMClockSet function 804 PLIB_ETH_MIIMIsBusy function 846 PLIB_ETH_MIIMIsScanning function 846 PLIB_ETH_MIIMNoPreDisable function 804 PLIB_ETH_MIIMNoPreEnable function 805 PLIB_ETH_MIIMNoPreIsEnabled function 805 PLIB_ETH_MIIMReadDataGet function 819 PLIB_ETH_MIIMReadStart function 820 PLIB_ETH_MIIMResetDisable function 820 PLIB_ETH_MIIMResetEnable function 821 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2385 PLIB_ETH_MIIMResetIsEnabled function 821 PLIB_ETH_MIIMScanIncrDisable function 822 PLIB_ETH_MIIMScanIncrEnable function 822 PLIB_ETH_MIIMScanIncrIsEnabled function 823 PLIB_ETH_MIIMScanModeDisable function 824 PLIB_ETH_MIIMScanModeEnable function 824 PLIB_ETH_MIIMScanModeIsEnabled function 825 PLIB_ETH_MIIMWriteDataSet function 825 PLIB_ETH_MIIMWriteStart function 826 PLIB_ETH_MIIResetDisable function 826 PLIB_ETH_MIIResetEnable function 827 PLIB_ETH_MIIResetIsEnabled function 827 PLIB_ETH_MultipleCollisionCountClear function 886 PLIB_ETH_MultipleCollisionCountGet function 887 PLIB_ETH_NoBackoffDisable function 865 PLIB_ETH_NoBackoffEnable function 865 PLIB_ETH_NoBackoffIsEnabled function 866 PLIB_ETH_NonBackToBackIPG1Get function 806 PLIB_ETH_NonBackToBackIPG1Set function 806 PLIB_ETH_NonBackToBackIPG2Get function 807 PLIB_ETH_NonBackToBackIPG2Set function 807 PLIB_ETH_PassAllDisable function 849 PLIB_ETH_PassAllEnable function 850 PLIB_ETH_PassAllIsEnabled function 850 PLIB_ETH_PatternMatchChecksumGet function 851 PLIB_ETH_PatternMatchChecksumSet function 851 PLIB_ETH_PatternMatchGet function 852 PLIB_ETH_PatternMatchModeGet function 852 PLIB_ETH_PatternMatchModeSet function 853 PLIB_ETH_PatternMatchOffsetGet function 854 PLIB_ETH_PatternMatchOffsetSet function 854 PLIB_ETH_PatternMatchSet function 855 PLIB_ETH_PauseTimerGet function 808 PLIB_ETH_PauseTimerSet function 809 PLIB_ETH_PHYAddressGet function 828 PLIB_ETH_PHYAddressSet function 828 PLIB_ETH_PurePreambleDisable function 855 PLIB_ETH_PurePreambleEnable function 856 PLIB_ETH_PurePreambleIsEnabled function 856 PLIB_ETH_ReceiveBufferSizeGet function 809 PLIB_ETH_ReceiveBufferSizeSet function 810 PLIB_ETH_ReceiveDisable function 810 PLIB_ETH_ReceiveEnable function 811 PLIB_ETH_ReceiveFilterDisable function 857 PLIB_ETH_ReceiveFilterEnable function 857 PLIB_ETH_ReceiveFilterIsEnable function 858 PLIB_ETH_ReceiveIsBusy function 847 PLIB_ETH_ReceiveIsEnabled function 811 PLIB_ETH_RegisterAddressGet function 829 PLIB_ETH_RegisterAddressSet function 829 PLIB_ETH_ReTxMaxGet function 812 PLIB_ETH_ReTxMaxSet function 812 PLIB_ETH_RMIIResetDisable function 830 PLIB_ETH_RMIIResetEnable function 831 PLIB_ETH_RMIIResetIsEnabled function 831 PLIB_ETH_RMIISpeedGet function 813 PLIB_ETH_RMIISpeedSet function 814 PLIB_ETH_RxBufferCountDecrement function 832 PLIB_ETH_RxDisable function 832 PLIB_ETH_RxEmptyWmarkGet function 866 PLIB_ETH_RxEmptyWmarkSet function 867 PLIB_ETH_RxEnable function 833 PLIB_ETH_RxFullWmarkGet function 868 PLIB_ETH_RxFullWmarkSet function 868 PLIB_ETH_RxFuncResetDisable function 833 PLIB_ETH_RxFuncResetEnable function 834 PLIB_ETH_RxFuncResetIsEnabled function 834 PLIB_ETH_RxIsEnabled function 835 PLIB_ETH_RxOverflowCountClear function 888 PLIB_ETH_RxOverflowCountGet function 888 PLIB_ETH_RxPacketCountGet function 889 PLIB_ETH_RxPacketDescAddrGet function 835 PLIB_ETH_RxPacketDescAddrSet function 836 PLIB_ETH_RxPauseDisable function 869 PLIB_ETH_RxPauseEnable function 869 PLIB_ETH_RxPauseIsEnabled function 870 PLIB_ETH_ShortcutQuantaDisable function 870 PLIB_ETH_ShortcutQuantaEnable function 871 PLIB_ETH_ShortcutQuantaIsEnabled function 871 PLIB_ETH_SimResetDisable function 872 PLIB_ETH_SimResetEnable function 873 PLIB_ETH_SimResetIsEnabled function 873 PLIB_ETH_SingleCollisionCountClear function 889 PLIB_ETH_SingleCollisionCountGet function 890 PLIB_ETH_StationAddressGet function 859 PLIB_ETH_StationAddressSet function 859 PLIB_ETH_StopInIdleDisable function 814 PLIB_ETH_StopInIdleEnable function 815 PLIB_ETH_StopInIdleIsEnabled function 815 PLIB_ETH_TestBackPressDisable function 874 PLIB_ETH_TestBackPressEnable function 874 PLIB_ETH_TestBackPressIsEnabled function 875 PLIB_ETH_TestPauseDisable function 837 PLIB_ETH_TestPauseEnable function 837 PLIB_ETH_TestPauseIsEnabled function 838 PLIB_ETH_TransmitIsBusy function 848 PLIB_ETH_TxFuncResetDisable function 838 PLIB_ETH_TxFuncResetEnable function 839 PLIB_ETH_TxFuncResetIsEnabled function 839 PLIB_ETH_TxPacketDescAddrGet function 840 PLIB_ETH_TxPacketDescAddrSet function 840 PLIB_ETH_TxPauseDisable function 875 PLIB_ETH_TxPauseEnable function 876 PLIB_ETH_TxPauseIsEnabled function 876 PLIB_ETH_TxRTSDisable function 841 PLIB_ETH_TxRTSEnable function 841 PLIB_ETH_TxRTSIsEnabled function 842 plib_glcd.h 1021 PLIB_GLCD_BackgroundColorGet function 944 PLIB_GLCD_BackgroundColorSet function 945 PLIB_GLCD_BackPorchXGet function 933 PLIB_GLCD_BackPorchXYSet function 934 PLIB_GLCD_BackPorchYGet function 934 PLIB_GLCD_BlankingXGet function 941 PLIB_GLCD_BlankingXYSet function 935 PLIB_GLCD_BlankingYGet function 941 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2386 PLIB_GLCD_ClockDividerGet function 943 PLIB_GLCD_ClockDividerSet function 942 PLIB_GLCD_CursorDataGet function 966 PLIB_GLCD_CursorDataSet function 967 PLIB_GLCD_CursorDisable function 967 PLIB_GLCD_CursorEnable function 968 PLIB_GLCD_CursorIsEnabled function 968 PLIB_GLCD_CursorLUTGet function 969 PLIB_GLCD_CursorLUTSet function 969 PLIB_GLCD_CursorXGet function 970 PLIB_GLCD_CursorXYSet function 971 PLIB_GLCD_CursorYGet function 971 PLIB_GLCD_DESignalLevelGet function 985 PLIB_GLCD_Disable function 930 PLIB_GLCD_DitheringDisable function 980 PLIB_GLCD_DitheringEnable function 981 PLIB_GLCD_DitheringIsEnabled function 986 PLIB_GLCD_Enable function 931 PLIB_GLCD_ExistsBackgroundColor function 990 PLIB_GLCD_ExistsBackPorchXY function 991 PLIB_GLCD_ExistsBlankingXY function 992 PLIB_GLCD_ExistsClockDivider function 992 PLIB_GLCD_ExistsCursor function 993 PLIB_GLCD_ExistsCursorData function 993 PLIB_GLCD_ExistsCursorLUT function 994 PLIB_GLCD_ExistsCursorXY function 994 PLIB_GLCD_ExistsDESignalLevel function 995 PLIB_GLCD_ExistsDithering function 996 PLIB_GLCD_ExistsEnable function 996 PLIB_GLCD_ExistsForceOutputBlank function 997 PLIB_GLCD_ExistsFormattingClockDivide function 998 PLIB_GLCD_ExistsFrontPorchXY function 998 PLIB_GLCD_ExistsGlobalColorLUT function 999 PLIB_GLCD_ExistsHSyncInterruptEnable function 999 PLIB_GLCD_ExistsHSyncSignalLevel function 1000 PLIB_GLCD_ExistsIRQTriggerControl function 1001 PLIB_GLCD_ExistsIsLastRow function 1001 PLIB_GLCD_ExistsIsVerticalBlankingActive function 1002 PLIB_GLCD_ExistsLayerBaseAddress function 1002 PLIB_GLCD_ExistsLayerBilinearFilterEnable function 1003 PLIB_GLCD_ExistsLayerColorMode function 1004 PLIB_GLCD_ExistsLayerDestBlendFunc function 1004 PLIB_GLCD_ExistsLayerEnable function 1005 PLIB_GLCD_ExistsLayerForceWithGlobalAlpha function 1005 PLIB_GLCD_ExistsLayerGlobalAlpha function 1006 PLIB_GLCD_ExistsLayerPreMultiplyImageAlpha function 1007 PLIB_GLCD_ExistsLayerResXY function 1007 PLIB_GLCD_ExistsLayerSizeXY function 1008 PLIB_GLCD_ExistsLayerSrcBlendFunc function 1008 PLIB_GLCD_ExistsLayerStartXY function 1009 PLIB_GLCD_ExistsLayerStride function 1010 PLIB_GLCD_ExistsLinesPrefetch function 1010 PLIB_GLCD_ExistsPaletteGammaRamp function 1011 PLIB_GLCD_ExistsResolutionXY function 1012 PLIB_GLCD_ExistsRGBSequentialMode function 1012 PLIB_GLCD_ExistsSignalPolarity function 1013 PLIB_GLCD_ExistsSingleCyclePerLineVsync function 1013 PLIB_GLCD_ExistsVSyncInterruptEnable function 1014 PLIB_GLCD_ExistsVSyncSignalLevel function 1015 PLIB_GLCD_ExistsYUVOutput function 1015 PLIB_GLCD_ForceOutputBlankDisable function 982 PLIB_GLCD_ForceOutputBlankEnable function 982 PLIB_GLCD_ForceOutputBlankIsEnabled function 987 PLIB_GLCD_FormattingClockDivideDisable function 936 PLIB_GLCD_FormattingClockDivideEnable function 936 PLIB_GLCD_FormattingClockDivideIsEnabled function 937 PLIB_GLCD_FrontPorchXGet function 937 PLIB_GLCD_FrontPorchXYSet function 938 PLIB_GLCD_FrontPorchYGet function 938 PLIB_GLCD_GlobalColorLUTGet function 972 PLIB_GLCD_GlobalColorLUTSet function 972 PLIB_GLCD_HSyncInterruptDisable function 975 PLIB_GLCD_HSyncInterruptEnable function 975 PLIB_GLCD_HSyncInterruptIsEnabled function 976 PLIB_GLCD_HSyncSignalLevelGet function 976 PLIB_GLCD_IRQTriggerControlGet function 977 PLIB_GLCD_IRQTriggerControlSet function 978 PLIB_GLCD_IsEnabled function 987 PLIB_GLCD_IsLastRow function 988 PLIB_GLCD_IsVerticalBlankingActive function 988 PLIB_GLCD_LayerBaseAddressGet function 945 PLIB_GLCD_LayerBaseAddressSet function 946 PLIB_GLCD_LayerBilinearFilterDisable function 947 PLIB_GLCD_LayerBilinearFilterEnable function 947 PLIB_GLCD_LayerBilinearFilterIsEnabled function 948 PLIB_GLCD_LayerColorModeGet function 948 PLIB_GLCD_LayerColorModeSet function 949 PLIB_GLCD_LayerDestBlendFuncGet function 950 PLIB_GLCD_LayerDestBlendFuncSet function 951 PLIB_GLCD_LayerDisable function 951 PLIB_GLCD_LayerEnable function 952 PLIB_GLCD_LayerForceWithGlobalAlphaDisable function 952 PLIB_GLCD_LayerForceWithGlobalAlphaEnable function 953 PLIB_GLCD_LayerForceWithGlobalAlphaIsEnabled function 953 PLIB_GLCD_LayerGlobalAlphaGet function 954 PLIB_GLCD_LayerGlobalAlphaSet function 955 PLIB_GLCD_LayerIsEnabled function 955 PLIB_GLCD_LayerPreMultiplyImageAlphaDisable function 956 PLIB_GLCD_LayerPreMultiplyImageAlphaEnable function 956 PLIB_GLCD_LayerPreMultiplyImageAlphaIsEnabled function 957 PLIB_GLCD_LayerResXGet function 958 PLIB_GLCD_LayerResXYSet function 958 PLIB_GLCD_LayerResYGet function 959 PLIB_GLCD_LayerSizeXGet function 960 PLIB_GLCD_LayerSizeXYSet function 960 PLIB_GLCD_LayerSizeYGet function 961 PLIB_GLCD_LayerSrcBlendFuncGet function 961 PLIB_GLCD_LayerSrcBlendFuncSet function 962 PLIB_GLCD_LayerStartXGet function 963 PLIB_GLCD_LayerStartXYSet function 963 PLIB_GLCD_LayerStartYGet function 964 PLIB_GLCD_LayerStrideGet function 965 PLIB_GLCD_LayerStrideSet function 965 PLIB_GLCD_LinesPrefetchGet function 939 PLIB_GLCD_LinesPrefetchSet function 942 PLIB_GLCD_PaletteGammaRampDisable function 973 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2387 PLIB_GLCD_PaletteGammaRampEnable function 974 PLIB_GLCD_PaletteGammaRampIsEnabled function 974 PLIB_GLCD_ResolutionXGet function 940 PLIB_GLCD_ResolutionXYSet function 943 PLIB_GLCD_ResolutionYGet function 940 PLIB_GLCD_RGBSequentialModeGet function 989 PLIB_GLCD_RGBSequentialModeSet function 931 PLIB_GLCD_SignalPolarityGet function 932 PLIB_GLCD_SignalPolaritySet function 933 PLIB_GLCD_SingleCyclePerLineVsyncDisable function 983 PLIB_GLCD_SingleCyclePerLineVsyncEnable function 983 PLIB_GLCD_SingleCyclePerLineVsyncIsEnabled function 984 PLIB_GLCD_VSyncInterruptDisable function 978 PLIB_GLCD_VSyncInterruptEnable function 979 PLIB_GLCD_VSyncInterruptIsEnabled function 979 PLIB_GLCD_VSyncSignalLevelGet function 980 PLIB_GLCD_YUVOutputDisable function 984 PLIB_GLCD_YUVOutputEnable function 985 PLIB_GLCD_YUVOutputIsEnabled function 990 plib_i2c.h 1125 PLIB_I2C_AcksequenceIsInProgress function 1079 PLIB_I2C_ArbitrationLossClear function 1061 PLIB_I2C_ArbitrationLossHasOccurred function 1061 PLIB_I2C_BaudRateGet function 1066 PLIB_I2C_BaudRateSet function 1067 PLIB_I2C_BusIsIdle function 1062 PLIB_I2C_DataLineHoldTimeSet function 1080 PLIB_I2C_Disable function 1051 PLIB_I2C_Enable function 1051 PLIB_I2C_ExistsAcksequenceProgress function 1101 PLIB_I2C_ExistsArbitrationLoss function 1102 PLIB_I2C_ExistsBaudRate function 1103 PLIB_I2C_ExistsBusIsIdle function 1103 PLIB_I2C_ExistsClockStretching function 1104 PLIB_I2C_ExistsDataLineHoldTime function 1104 PLIB_I2C_ExistsGeneralCall function 1105 PLIB_I2C_ExistsGeneralCallAddressDetect function 1105 PLIB_I2C_ExistsHighFrequency function 1106 PLIB_I2C_ExistsIPMI function 1106 PLIB_I2C_ExistsMasterReceiverClock1Byte function 1107 PLIB_I2C_ExistsMasterStart function 1107 PLIB_I2C_ExistsMasterStartRepeat function 1108 PLIB_I2C_ExistsMasterStop function 1109 PLIB_I2C_ExistsModuleEnable function 1109 PLIB_I2C_ExistsReceivedByteAcknowledge function 1110 PLIB_I2C_ExistsReceivedByteAvailable function 1110 PLIB_I2C_ExistsReceivedByteGet function 1111 PLIB_I2C_ExistsReceiverOverflow function 1111 PLIB_I2C_ExistsReservedAddressProtect function 1112 PLIB_I2C_ExistsSlaveAddress10Bit function 1112 PLIB_I2C_ExistsSlaveAddress7Bit function 1113 PLIB_I2C_ExistsSlaveAddressDetect function 1114 PLIB_I2C_ExistsSlaveAddressHoldEnable function 1114 PLIB_I2C_ExistsSlaveBufferOverwrite function 1115 PLIB_I2C_ExistsSlaveBusCollisionDetect function 1115 PLIB_I2C_ExistsSlaveClockHold function 1116 PLIB_I2C_ExistsSlaveDataDetect function 1116 PLIB_I2C_ExistsSlaveDataHoldEnable function 1124 PLIB_I2C_ExistsSlaveInterruptOnStart function 1117 PLIB_I2C_ExistsSlaveInterruptOnStop function 1117 PLIB_I2C_ExistsSlaveMask function 1118 PLIB_I2C_ExistsSlaveReadRequest function 1119 PLIB_I2C_ExistsSMBus function 1119 PLIB_I2C_ExistsStartDetect function 1120 PLIB_I2C_ExistsStopDetect function 1120 PLIB_I2C_ExistsStopInIdle function 1121 PLIB_I2C_ExistsTransmitterByteAcknowledge function 1121 PLIB_I2C_ExistsTransmitterByteComplete function 1122 PLIB_I2C_ExistsTransmitterByteSend function 1122 PLIB_I2C_ExistsTransmitterIsBusy function 1123 PLIB_I2C_ExistsTransmitterOverflow function 1123 PLIB_I2C_GeneralCallDisable function 1052 PLIB_I2C_GeneralCallEnable function 1053 plib_i2c_help.h 1128 PLIB_I2C_HighFrequencyDisable function 1053 PLIB_I2C_HighFrequencyEnable function 1054 PLIB_I2C_IPMIDisable function 1054 PLIB_I2C_IPMIEnable function 1055 PLIB_I2C_MasterReceiverClock1Byte function 1088 PLIB_I2C_MasterReceiverReadyToAcknowledge function 1101 PLIB_I2C_MasterStart function 1089 PLIB_I2C_MasterStartRepeat function 1090 PLIB_I2C_MasterStop function 1090 PLIB_I2C_ReceivedByteAcknowledge function 1096 PLIB_I2C_ReceivedByteGet function 1097 PLIB_I2C_ReceivedByteIsAvailable function 1098 PLIB_I2C_ReceiverByteAcknowledgeHasCompleted function 1099 PLIB_I2C_ReceiverOverflowClear function 1099 PLIB_I2C_ReceiverOverflowHasOccurred function 1100 PLIB_I2C_ReservedAddressProtectDisable function 1056 PLIB_I2C_ReservedAddressProtectEnable function 1056 PLIB_I2C_SlaveAddress10BitGet function 1067 PLIB_I2C_SlaveAddress10BitSet function 1068 PLIB_I2C_SlaveAddress10BitWasDetected function 1069 PLIB_I2C_SlaveAddress7BitGet function 1070 PLIB_I2C_SlaveAddress7BitSet function 1070 PLIB_I2C_SlaveAddressHoldDisable function 1071 PLIB_I2C_SlaveAddressHoldEnable function 1072 PLIB_I2C_SlaveAddressIsDetected function 1072 PLIB_I2C_SlaveAddressIsGeneralCall function 1073 PLIB_I2C_SlaveAddressModeIs10Bits function 1074 PLIB_I2C_SlaveBufferOverwriteDisable function 1081 PLIB_I2C_SlaveBufferOverwriteEnable function 1081 PLIB_I2C_SlaveBusCollisionDetectDisable function 1082 PLIB_I2C_SlaveBusCollisionDetectEnable function 1083 PLIB_I2C_SlaveClockHold function 1083 PLIB_I2C_SlaveClockRelease function 1084 PLIB_I2C_SlaveClockStretchingDisable function 1057 PLIB_I2C_SlaveClockStretchingEnable function 1058 PLIB_I2C_SlaveDataHoldDisable function 1084 PLIB_I2C_SlaveDataHoldEnable function 1085 PLIB_I2C_SlaveDataIsDetected function 1075 PLIB_I2C_SlaveInterruptOnStartDisable function 1086 PLIB_I2C_SlaveInterruptOnStartEnable function 1086 PLIB_I2C_SlaveInterruptOnStopDisable function 1087 PLIB_I2C_SlaveInterruptOnStopEnable function 1088 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2388 PLIB_I2C_SlaveMask10BitGet function 1076 PLIB_I2C_SlaveMask10BitSet function 1077 PLIB_I2C_SlaveMask7BitGet function 1078 PLIB_I2C_SlaveMask7BitSet function 1079 PLIB_I2C_SlaveReadIsRequested function 1075 PLIB_I2C_SMBDisable function 1058 PLIB_I2C_SMBEnable function 1059 PLIB_I2C_StartClear function 1063 PLIB_I2C_StartWasDetected function 1064 PLIB_I2C_StopClear function 1064 PLIB_I2C_StopInIdleDisable function 1059 PLIB_I2C_StopInIdleEnable function 1060 PLIB_I2C_StopWasDetected function 1065 PLIB_I2C_TransmitterByteHasCompleted function 1091 PLIB_I2C_TransmitterByteSend function 1092 PLIB_I2C_TransmitterByteWasAcknowledged function 1092 PLIB_I2C_TransmitterIsBusy function 1093 PLIB_I2C_TransmitterIsReady function 1094 PLIB_I2C_TransmitterOverflowClear function 1095 PLIB_I2C_TransmitterOverflowHasOccurred function 1095 plib_ic.h 1153 PLIB_IC_AlternateClockDisable function 1136 PLIB_IC_AlternateClockEnable function 1137 PLIB_IC_AlternateTimerSelect function 1137 PLIB_IC_Buffer16BitGet function 1139 PLIB_IC_Buffer32BitGet function 1139 PLIB_IC_BufferIsEmpty function 1140 PLIB_IC_BufferOverflowHasOccurred function 1140 PLIB_IC_BufferSizeSelect function 1141 PLIB_IC_Disable function 1133 PLIB_IC_Enable function 1134 PLIB_IC_EventsPerInterruptSelect function 1134 PLIB_IC_ExistsAlternateClock function 1144 PLIB_IC_ExistsAlternateTimerSelect function 1138 PLIB_IC_ExistsBufferIsEmptyStatus function 1144 PLIB_IC_ExistsBufferOverflowStatus function 1145 PLIB_IC_ExistsBufferSize function 1145 PLIB_IC_ExistsBufferValue function 1146 PLIB_IC_ExistsCaptureMode function 1146 PLIB_IC_ExistsEdgeCapture function 1147 PLIB_IC_ExistsEnable function 1147 PLIB_IC_ExistsEventsPerInterruptSelect function 1148 PLIB_IC_ExistsStopInIdle function 1148 PLIB_IC_ExistsTimerSelect function 1149 PLIB_IC_FirstCaptureEdgeSelect function 1135 plib_ic_help.h 1154 PLIB_IC_ModeSelect function 1142 PLIB_IC_StopInIdleDisable function 1142 PLIB_IC_StopInIdleEnable function 1143 PLIB_IC_TimerSelect function 1135 plib_int.h 1202 PLIB_INT_CPUCurrentPriorityLevelGet function 1175 PLIB_INT_Disable function 1158 PLIB_INT_Enable function 1159 PLIB_INT_ExistsCPUCurrentPriorityLevel function 1179 PLIB_INT_ExistsEnableControl function 1179 PLIB_INT_ExistsExternalINTEdgeSelect function 1180 PLIB_INT_ExistsINTCPUPriority function 1181 PLIB_INT_ExistsINTCPUVector function 1181 PLIB_INT_ExistsProximityTimerControl function 1182 PLIB_INT_ExistsProximityTimerEnable function 1182 PLIB_INT_ExistsShadowRegisterAssign function 1186 PLIB_INT_ExistsSingleVectorShadowSet function 1183 PLIB_INT_ExistsSoftwareNMI function 1187 PLIB_INT_ExistsSourceControl function 1183 PLIB_INT_ExistsSourceFlag function 1184 PLIB_INT_ExistsVariableOffset function 1186 PLIB_INT_ExistsVectorPriority function 1184 PLIB_INT_ExistsVectorSelect function 1185 PLIB_INT_ExternalFallingEdgeSelect function 1160 PLIB_INT_ExternalRisingEdgeSelect function 1160 PLIB_INT_GetStateAndDisable function 1177 plib_int_help.h 1203 PLIB_INT_IsEnabled function 1161 PLIB_INT_MultiVectorSelect function 1161 PLIB_INT_PriorityGet function 1162 PLIB_INT_ProximityTimerDisable function 1163 PLIB_INT_ProximityTimerEnable function 1163 PLIB_INT_ProximityTimerGet function 1175 PLIB_INT_ProximityTimerSet function 1176 PLIB_INT_SetState function 1166 PLIB_INT_ShadowRegisterAssign function 1166 PLIB_INT_ShadowRegisterGet function 1178 PLIB_INT_SingleVectorSelect function 1164 PLIB_INT_SingleVectorShadowSetDisable function 1164 PLIB_INT_SingleVectorShadowSetEnable function 1165 PLIB_INT_SoftwareNMITrigger function 1168 PLIB_INT_SourceDisable function 1168 PLIB_INT_SourceEnable function 1169 PLIB_INT_SourceFlagClear function 1169 PLIB_INT_SourceFlagGet function 1170 PLIB_INT_SourceFlagSet function 1171 PLIB_INT_SourceIsEnabled function 1171 PLIB_INT_VariableVectorOffsetGet function 1178 PLIB_INT_VariableVectorOffsetSet function 1167 PLIB_INT_VectorGet function 1176 PLIB_INT_VectorPriorityGet function 1172 PLIB_INT_VectorPrioritySet function 1173 PLIB_INT_VectorSubPriorityGet function 1173 PLIB_INT_VectorSubPrioritySet function 1174 plib_nvm.h 1265 PLIB_NVM_BootFlashBank1LowerRegion function 1230 PLIB_NVM_BootFlashBank2IsLowerRegion function 1230 PLIB_NVM_BootFlashBank2LowerRegion function 1231 PLIB_NVM_BootPageWriteProtectionDisable function 1224 PLIB_NVM_BootPageWriteProtectionEnable function 1225 PLIB_NVM_DataBlockSourceAddress function 1216 PLIB_NVM_EEPROMAddress function 1239 PLIB_NVM_EEPROMDataToWrite function 1240 PLIB_NVM_EEPROMDisable function 1232 PLIB_NVM_EEPROMEnable function 1231 PLIB_NVM_EEPROMEraseStart function 1241 PLIB_NVM_EEPROMErrorClear function 1239 PLIB_NVM_EEPROMErrorGet function 1238 PLIB_NVM_EEPROMIsReady function 1233 PLIB_NVM_EEPROMKeySequenceWrite function 1241 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2389 PLIB_NVM_EEPROMNextWriteCycleIsLong function 1238 PLIB_NVM_EEPROMOperationAbort function 1245 PLIB_NVM_EEPROMOperationHasCompleted function 1243 PLIB_NVM_EEPROMOperationSelect function 1235 PLIB_NVM_EEPROMRead function 1244 PLIB_NVM_EEPROMReadEnable function 1236 PLIB_NVM_EEPROMReadIsEnabled function 1237 PLIB_NVM_EEPROMReadStart function 1243 PLIB_NVM_EEPROMStopInIdleDisable function 1234 PLIB_NVM_EEPROMStopInIdleEnable function 1233 PLIB_NVM_EEPROMStopInIdleIsEnabled function 1234 PLIB_NVM_EEPROMWriteEnable function 1235 PLIB_NVM_EEPROMWriteIsEnabled function 1236 PLIB_NVM_EEPROMWriteStart function 1242 PLIB_NVM_ExistsAddressModifyControl function 1245 PLIB_NVM_ExistsBootFlashBankRegion function 1254 PLIB_NVM_ExistsBootPageWriteProtect function 1246 PLIB_NVM_ExistsEEPROMAddressControl function 1255 PLIB_NVM_ExistsEEPROMDataControl function 1255 PLIB_NVM_ExistsEEPROMEnableControl function 1256 PLIB_NVM_ExistsEEPROMEnableOperationControl function 1256 PLIB_NVM_ExistsEEPROMErrorStatus function 1257 PLIB_NVM_ExistsEEPROMKeySequence function 1258 PLIB_NVM_ExistsEEPROMLongWriteStatus function 1258 PLIB_NVM_ExistsEEPROMOperationAbortControl function 1259 PLIB_NVM_ExistsEEPROMOperationModeControl function 1259 PLIB_NVM_ExistsEEPROMStartOperationControl function 1260 PLIB_NVM_ExistsEEPROMStopInIdleControl function 1260 PLIB_NVM_ExistsFlashBankRegionSelect function 1246 PLIB_NVM_ExistsFlashWPMemoryRangeProvide function 1247 PLIB_NVM_ExistsKeySequence function 1247 PLIB_NVM_ExistsLockBootSelect function 1248 PLIB_NVM_ExistsLockPFMSelect function 1248 PLIB_NVM_ExistsLowVoltageError function 1249 PLIB_NVM_ExistsLowVoltageStatus function 1249 PLIB_NVM_ExistsMemoryModificationControl function 1250 PLIB_NVM_ExistsOperationMode function 1251 PLIB_NVM_ExistsProvideData function 1251 PLIB_NVM_ExistsProvideQuadData function 1252 PLIB_NVM_ExistsSourceAddress function 1252 PLIB_NVM_ExistsSwapLockControl function 1254 PLIB_NVM_ExistsWriteErrorStatus function 1253 PLIB_NVM_ExistsWriteOperation function 1253 PLIB_NVM_FlashAddressToModify function 1217 PLIB_NVM_FlashEraseStart function 1217 PLIB_NVM_FlashProvideData function 1218 PLIB_NVM_FlashProvideQuadData function 1219 PLIB_NVM_FlashRead function 1219 PLIB_NVM_FlashSwapLockSelect function 1222 PLIB_NVM_FlashSwapLockStatusGet function 1223 PLIB_NVM_FlashWriteCycleHasCompleted function 1221 PLIB_NVM_FlashWriteKeySequence function 1220 PLIB_NVM_FlashWriteProtectMemoryAreaRange function 1223 PLIB_NVM_FlashWriteStart function 1220 plib_nvm_help.h 1267 PLIB_NVM_IsBootMemoryLocked function 1225 PLIB_NVM_IsBootPageWriteProtected function 1226 PLIB_NVM_IsProgramFlashMemoryLocked function 1226 PLIB_NVM_LockBootMemory function 1227 PLIB_NVM_LockProgramFlashMemory function 1227 PLIB_NVM_LowVoltageEventIsActive function 1213 PLIB_NVM_LowVoltageIsDetected function 1214 PLIB_NVM_MemoryModifyEnable function 1214 PLIB_NVM_MemoryModifyInhibit function 1215 PLIB_NVM_MemoryOperationSelect function 1216 PLIB_NVM_ProgramFlashBank1LowerRegion function 1228 PLIB_NVM_ProgramFlashBank2IsLowerRegion function 1229 PLIB_NVM_ProgramFlashBank2LowerRegion function 1228 PLIB_NVM_WriteOperationHasTerminated function 1221 plib_oc.h 1295 PLIB_OC_AlternateClockDisable function 1281 PLIB_OC_AlternateClockEnable function 1281 PLIB_OC_AlternateTimerSelect function 1282 PLIB_OC_Buffer16BitSet function 1277 PLIB_OC_Buffer32BitSet function 1278 PLIB_OC_BufferSizeSelect function 1278 PLIB_OC_Disable function 1275 PLIB_OC_Enable function 1275 PLIB_OC_ExistsAlternateClock function 1286 PLIB_OC_ExistsAlternateTimerSelect function 1291 PLIB_OC_ExistsBufferSize function 1286 PLIB_OC_ExistsBufferValue function 1287 PLIB_OC_ExistsCompareModeSelect function 1287 PLIB_OC_ExistsEnableControl function 1288 PLIB_OC_ExistsFaultInput function 1288 PLIB_OC_ExistsFaultStatus function 1289 PLIB_OC_ExistsPulseWidth function 1289 PLIB_OC_ExistsStopInIdle function 1290 PLIB_OC_ExistsTimerSelect function 1290 PLIB_OC_FaultHasOccurred function 1284 PLIB_OC_FaultInputSelect function 1285 plib_oc_help.h 1296 PLIB_OC_IsEnabled function 1276 PLIB_OC_ModeSelect function 1277 PLIB_OC_PulseWidth16BitSet function 1279 PLIB_OC_PulseWidth32BitSet function 1280 PLIB_OC_StopInIdleDisable function 1283 PLIB_OC_StopInIdleEnable function 1284 PLIB_OC_TimerSelect function 1280 plib_osc.h 1402 PLIB_OSC_BTPLLClockOutDisable function 1343 PLIB_OSC_BTPLLClockOutEnable function 1343 PLIB_OSC_BTPLLClockOutStatus function 1344 PLIB_OSC_BTPLLFrequencyRangeGet function 1344 PLIB_OSC_BTPLLFrequencyRangeSet function 1345 PLIB_OSC_BTPLLInputClockSourceGet function 1345 PLIB_OSC_BTPLLInputClockSourceSet function 1346 PLIB_OSC_BTPLLInputDivisorGet function 1347 PLIB_OSC_BTPLLInputDivisorSet function 1347 PLIB_OSC_BTPLLMultiplierGet function 1348 PLIB_OSC_BTPLLMultiplierSelect function 1348 PLIB_OSC_BTPLLOutputDivisorGet function 1349 PLIB_OSC_BTPLLOutputDivisorSet function 1350 PLIB_OSC_ClockHasFailed function 1364 PLIB_OSC_ClockIsReady function 1314 PLIB_OSC_ClockSlewingIsActive function 1314 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2390 PLIB_OSC_ClockStart function 1364 PLIB_OSC_ClockStop function 1365 PLIB_OSC_ClockStopStatus function 1366 PLIB_OSC_ClockSwitchingAbort function 1331 PLIB_OSC_ClockSwitchingIsComplete function 1331 PLIB_OSC_CurrentSysClockGet function 1332 PLIB_OSC_DreamModeDisable function 1312 PLIB_OSC_DreamModeEnable function 1313 PLIB_OSC_DreamModeStatus function 1313 PLIB_OSC_ExistsBTPLLClockOut function 1385 PLIB_OSC_ExistsBTPLLFrequencyRange function 1386 PLIB_OSC_ExistsBTPLLInputClockSource function 1386 PLIB_OSC_ExistsBTPLLInputDivisor function 1387 PLIB_OSC_ExistsBTPLLMultiplier function 1388 PLIB_OSC_ExistsBTPLLOutputDivisor function 1388 PLIB_OSC_ExistsClockDiagStatus function 1389 PLIB_OSC_ExistsClockFail function 1366 PLIB_OSC_ExistsClockReadyStatus function 1382 PLIB_OSC_ExistsClockSlewingStatus function 1383 PLIB_OSC_ExistsDreamModeControl function 1389 PLIB_OSC_ExistsForceLock function 1390 PLIB_OSC_ExistsFRCDivisor function 1367 PLIB_OSC_ExistsFRCTuning function 1367 PLIB_OSC_ExistsOnWaitAction function 1368 PLIB_OSC_ExistsOscCurrentGet function 1368 PLIB_OSC_ExistsOscSelect function 1369 PLIB_OSC_ExistsOscSwitchInit function 1369 PLIB_OSC_ExistsPBClockDivisor function 1370 PLIB_OSC_ExistsPBClockOutputEnable function 1370 PLIB_OSC_ExistsPBClockReady function 1371 PLIB_OSC_ExistsPLLBypass function 1390 PLIB_OSC_ExistsPLLClockLock function 1372 PLIB_OSC_ExistsPLLLockStatus function 1372 PLIB_OSC_ExistsReferenceOscBaseClock function 1373 PLIB_OSC_ExistsReferenceOscChange function 1373 PLIB_OSC_ExistsReferenceOscChangeActive function 1374 PLIB_OSC_ExistsReferenceOscDivisor function 1374 PLIB_OSC_ExistsReferenceOscEnable function 1375 PLIB_OSC_ExistsReferenceOscStopInIdleEnable function 1375 PLIB_OSC_ExistsReferenceOscStopInSleep function 1376 PLIB_OSC_ExistsReferenceOscTrim function 1376 PLIB_OSC_ExistsReferenceOutputEnable function 1377 PLIB_OSC_ExistsResetPLL function 1391 PLIB_OSC_ExistsSecondaryEnable function 1378 PLIB_OSC_ExistsSecondaryReady function 1378 PLIB_OSC_ExistsSleepToStartupClock function 1383 PLIB_OSC_ExistsSlewDivisorStepControl function 1384 PLIB_OSC_ExistsSlewEnableControl function 1384 PLIB_OSC_ExistsSysPLLFrequencyRange function 1379 PLIB_OSC_ExistsSysPLLInputClockSource function 1379 PLIB_OSC_ExistsSysPLLInputDivisor function 1380 PLIB_OSC_ExistsSysPLLMultiplier function 1380 PLIB_OSC_ExistsSysPLLOutputDivisor function 1381 PLIB_OSC_ExistsSystemClockDivisorControl function 1385 PLIB_OSC_ExistsUPLLFrequencyRange function 1391 PLIB_OSC_ExistsUPLLInputDivisor function 1392 PLIB_OSC_ExistsUPLLMultiplier function 1393 PLIB_OSC_ExistsUPLLOutputDivisor function 1393 PLIB_OSC_ExistsUsbClockSource function 1381 PLIB_OSC_ForceSPLLLockDisable function 1350 PLIB_OSC_ForceSPLLLockEnable function 1351 PLIB_OSC_ForceSPLLLockStatus function 1351 PLIB_OSC_FRCDivisorGet function 1329 PLIB_OSC_FRCDivisorSelect function 1330 PLIB_OSC_FRCTuningSelect function 1330 plib_osc_help.h 1405 PLIB_OSC_OnWaitActionGet function 1307 PLIB_OSC_OnWaitActionSet function 1307 PLIB_OSC_PBClockDivisorGet function 1360 PLIB_OSC_PBClockDivisorIsReady function 1361 PLIB_OSC_PBClockDivisorSet function 1361 PLIB_OSC_PBOutputClockDisable function 1362 PLIB_OSC_PBOutputClockEnable function 1363 PLIB_OSC_PBOutputClockIsEnabled function 1363 PLIB_OSC_PLLBypassDisable function 1352 PLIB_OSC_PLLBypassEnable function 1352 PLIB_OSC_PLLBypassStatus function 1353 PLIB_OSC_PLLClockIsLocked function 1334 PLIB_OSC_PLLClockLock function 1335 PLIB_OSC_PLLClockUnlock function 1336 PLIB_OSC_PLLIsLocked function 1336 PLIB_OSC_ReferenceOscBaseClockSelect function 1319 PLIB_OSC_ReferenceOscDisable function 1319 PLIB_OSC_ReferenceOscDivisorValueSet function 1320 PLIB_OSC_ReferenceOscEnable function 1321 PLIB_OSC_ReferenceOscIsEnabled function 1321 PLIB_OSC_ReferenceOscSourceChangeIsActive function 1322 PLIB_OSC_ReferenceOscStopInIdleDisable function 1322 PLIB_OSC_ReferenceOscStopInIdleEnable function 1323 PLIB_OSC_ReferenceOscStopInIdleIsEnabled function 1324 PLIB_OSC_ReferenceOscStopInSleepDisable function 1324 PLIB_OSC_ReferenceOscStopInSleepEnable function 1325 PLIB_OSC_ReferenceOscStopInSleepIsEnabled function 1325 PLIB_OSC_ReferenceOscSwitchIsComplete function 1326 PLIB_OSC_ReferenceOscTrimSet function 1327 PLIB_OSC_ReferenceOutputDisable function 1327 PLIB_OSC_ReferenceOutputEnable function 1328 PLIB_OSC_ReferenceOutputIsEnabled function 1328 PLIB_OSC_ResetPLLAssert function 1358 PLIB_OSC_ResetPLLDeassert function 1359 PLIB_OSC_ResetPLLStatus function 1359 PLIB_OSC_SecondaryDisable function 1316 PLIB_OSC_SecondaryEnable function 1317 PLIB_OSC_SecondaryIsEnabled function 1317 PLIB_OSC_SecondaryIsReady function 1318 PLIB_OSC_SleepToStartupClockGet function 1311 PLIB_OSC_SleepToStartupClockSelect function 1311 PLIB_OSC_SlewDisable function 1308 PLIB_OSC_SlewDivisorStepGet function 1308 PLIB_OSC_SlewDivisorStepSelect function 1309 PLIB_OSC_SlewEnable function 1310 PLIB_OSC_SlewIsEnabled function 1310 PLIB_OSC_SysClockSelect function 1333 PLIB_OSC_SysPLLFrequencyRangeGet function 1337 PLIB_OSC_SysPLLFrequencyRangeSet function 1337 PLIB_OSC_SysPLLInputClockSourceGet function 1338 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2391 PLIB_OSC_SysPLLInputClockSourceSet function 1339 PLIB_OSC_SysPLLInputDivisorGet function 1339 PLIB_OSC_SysPLLInputDivisorSet function 1342 PLIB_OSC_SysPLLMultiplierGet function 1340 PLIB_OSC_SysPLLMultiplierSelect function 1340 PLIB_OSC_SysPLLOutputDivisorGet function 1341 PLIB_OSC_SysPLLOutputDivisorSet function 1341 PLIB_OSC_SystemClockDivisorGet function 1315 PLIB_OSC_SystemClockDivisorSelect function 1316 PLIB_OSC_UPLLFrequencyRangeGet function 1354 PLIB_OSC_UPLLFrequencyRangeSet function 1354 PLIB_OSC_UPLLInputDivisorGet function 1355 PLIB_OSC_UPLLInputDivisorSet function 1355 PLIB_OSC_UPLLMultiplierGet function 1356 PLIB_OSC_UPLLMultiplierSelect function 1356 PLIB_OSC_UPLLOutputDivisorGet function 1357 PLIB_OSC_UPLLOutputDivisorSet function 1358 PLIB_OSC_UsbClockSourceGet function 1333 PLIB_OSC_UsbClockSourceSelect function 1334 plib_pcache.h 1548 PLIB_PCACHE_CacheHitRead function 1524 PLIB_PCACHE_CacheHitWrite function 1524 PLIB_PCACHE_CacheLineAddrGet function 1512 PLIB_PCACHE_CacheLineAddrSet function 1512 PLIB_PCACHE_CacheLineData function 1513 PLIB_PCACHE_CacheLineDeselect function 1514 PLIB_PCACHE_CacheLineFlashTypeBoot function 1514 PLIB_PCACHE_CacheLineFlashTypeInst function 1515 PLIB_PCACHE_CacheLineFlashTypeIsInst function 1515 PLIB_PCACHE_CacheLineInst function 1516 PLIB_PCACHE_CacheLineInvalid function 1516 PLIB_PCACHE_CacheLineIsInst function 1517 PLIB_PCACHE_CacheLineIsLocked function 1518 PLIB_PCACHE_CacheLineIsValid function 1518 PLIB_PCACHE_CacheLineLock function 1519 PLIB_PCACHE_CacheLineMaskGet function 1519 PLIB_PCACHE_CacheLineMaskSet function 1520 PLIB_PCACHE_CacheLineSelect function 1520 PLIB_PCACHE_CacheLineUnlock function 1521 PLIB_PCACHE_CacheLineValid function 1522 PLIB_PCACHE_CacheMissRead function 1525 PLIB_PCACHE_CacheMissWrite function 1525 PLIB_PCACHE_DATA_ENABLE enumeration 1547 PLIB_PCACHE_DataCacheEnableGet function 1508 PLIB_PCACHE_DataCacheEnableSet function 1509 PLIB_PCACHE_ExistsCacheHit function 1534 PLIB_PCACHE_ExistsCacheLine function 1535 PLIB_PCACHE_ExistsCacheLineAddr function 1535 PLIB_PCACHE_ExistsCacheLineFlashType function 1536 PLIB_PCACHE_ExistsCacheLineLock function 1536 PLIB_PCACHE_ExistsCacheLineMask function 1537 PLIB_PCACHE_ExistsCacheLineType function 1538 PLIB_PCACHE_ExistsCacheLineValid function 1538 PLIB_PCACHE_ExistsCacheMiss function 1539 PLIB_PCACHE_ExistsDataCacheEnable function 1539 PLIB_PCACHE_ExistsFlashDEDStatus function 1540 PLIB_PCACHE_ExistsFlashSECCount function 1540 PLIB_PCACHE_ExistsFlashSECInt function 1541 PLIB_PCACHE_ExistsFlashSECStatus function 1541 PLIB_PCACHE_ExistsInvalidateOnPFMProgram function 1542 PLIB_PCACHE_ExistsLeastRecentlyUsedState function 1543 PLIB_PCACHE_ExistsPrefetchAbort function 1543 PLIB_PCACHE_ExistsPrefetchEnable function 1544 PLIB_PCACHE_ExistsWaitState function 1544 PLIB_PCACHE_ExistsWord function 1545 PLIB_PCACHE_FlashDEDStatusClear function 1529 PLIB_PCACHE_FlashDEDStatusGet function 1529 PLIB_PCACHE_FlashSECCountGet function 1530 PLIB_PCACHE_FlashSECCountSet function 1531 PLIB_PCACHE_FlashSECIntDisable function 1531 PLIB_PCACHE_FlashSECIntEnable function 1532 PLIB_PCACHE_FlashSECStatusClear function 1532 PLIB_PCACHE_FlashSECStatusGet function 1533 PLIB_PCACHE_FlashSECStatusSet function 1534 PLIB_PCACHE_InvalidateOnPFMProgramAll function 1509 PLIB_PCACHE_InvalidateOnPFMProgramUnlocked function 1510 PLIB_PCACHE_LeastRecentlyUsedStateRead function 1526 PLIB_PCACHE_MAX_SEC_COUNT macro 1545 PLIB_PCACHE_NUM_LINES macro 1546 PLIB_PCACHE_NUM_WORDS_PER_LINE macro 1546 PLIB_PCACHE_PREFETCH_ENABLE enumeration 1547 PLIB_PCACHE_PrefetchAbortRead function 1528 PLIB_PCACHE_PrefetchAbortWrite function 1528 PLIB_PCACHE_PrefetchEnableGet function 1526 PLIB_PCACHE_PrefetchEnableSet function 1527 PLIB_PCACHE_WaitStateGet function 1511 PLIB_PCACHE_WaitStateSet function 1511 PLIB_PCACHE_WordRead function 1522 PLIB_PCACHE_WordWrite function 1523 plib_pmp.h 1497 PLIB_PMP_AddressGet function 1454 PLIB_PMP_AddressIncrementModeGet function 1418 PLIB_PMP_AddressIncrementModeSelect function 1419 PLIB_PMP_AddressLatchPolaritySelect function 1460 PLIB_PMP_AddressLatchStrobeDisable function 1420 PLIB_PMP_AddressLatchStrobeEnable function 1420 PLIB_PMP_AddressLinesA0A1Get function 1454 PLIB_PMP_AddressLinesA0A1Set function 1455 PLIB_PMP_AddressPortDisable function 1456 PLIB_PMP_AddressPortEnable function 1457 PLIB_PMP_AddressSet function 1456 PLIB_PMP_ChipSelectFunctionSelect function 1421 PLIB_PMP_ChipSelectXDisable function 1422 PLIB_PMP_ChipSelectXEnable function 1422 PLIB_PMP_ChipSelectXIsActive function 1423 PLIB_PMP_ChipSelectXPolaritySelect function 1461 PLIB_PMP_DataSizeSelect function 1424 PLIB_PMP_Disable function 1424 PLIB_PMP_DualBufferDisable function 1434 PLIB_PMP_DualBufferEnable function 1434 PLIB_PMP_DualBufferIsEnabled function 1439 PLIB_PMP_DualModeMasterReceive function 1433 PLIB_PMP_DualModeMasterSend function 1435 PLIB_PMP_DualModeReadAddressGet function 1431 PLIB_PMP_DualModeReadAddressSet function 1431 PLIB_PMP_DualModeWriteAddressGet function 1432 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2392 PLIB_PMP_DualModeWriteAddressSet function 1432 PLIB_PMP_Enable function 1425 PLIB_PMP_ExistsAddressControl function 1462 PLIB_PMP_ExistsAddressLatchPolarity function 1463 PLIB_PMP_ExistsAddressLatchStrobePortControl function 1464 PLIB_PMP_ExistsAddressPortPinControl function 1464 PLIB_PMP_ExistsBufferOverFlow function 1465 PLIB_PMP_ExistsBufferRead function 1465 PLIB_PMP_ExistsBufferType function 1466 PLIB_PMP_ExistsBufferUnderFlow function 1466 PLIB_PMP_ExistsBufferWrite function 1467 PLIB_PMP_ExistsBusyStatus function 1467 PLIB_PMP_ExistsChipSelectEnable function 1468 PLIB_PMP_ExistsChipSelectoperation function 1468 PLIB_PMP_ExistsChipXPolarity function 1469 PLIB_PMP_ExistsCSXActiveStatus function 1470 PLIB_PMP_ExistsDataHoldWaitStates function 1470 PLIB_PMP_ExistsDataSetUpWaitStates function 1471 PLIB_PMP_ExistsDataStrobeWaitStates function 1471 PLIB_PMP_ExistsDataTransferSize function 1472 PLIB_PMP_ExistsDualBufferControl function 1481 PLIB_PMP_ExistsDualModeMasterRXTX function 1482 PLIB_PMP_ExistsDualModeReadAddressControl function 1483 PLIB_PMP_ExistsDualModeWriteAddressControl function 1483 PLIB_PMP_ExistsEnableControl function 1472 PLIB_PMP_ExistsIncrementMode function 1473 PLIB_PMP_ExistsInputBufferFull function 1473 PLIB_PMP_ExistsInputBufferXStatus function 1474 PLIB_PMP_ExistsInterruptMode function 1474 PLIB_PMP_ExistsMasterRXTX function 1475 PLIB_PMP_ExistsMUXModeSelect function 1475 PLIB_PMP_ExistsOperationMode function 1476 PLIB_PMP_ExistsOutPutBufferEmpty function 1477 PLIB_PMP_ExistsOutputBufferXStatus function 1477 PLIB_PMP_ExistsReadChipSelectEnable function 1484 PLIB_PMP_ExistsReadWritePolarity function 1478 PLIB_PMP_ExistsReadWriteStrobePortControl function 1478 PLIB_PMP_ExistsSlaveRX function 1479 PLIB_PMP_ExistsSlaveTX function 1479 PLIB_PMP_ExistsStartReadControl function 1485 PLIB_PMP_ExistsStopInIdleControl function 1480 PLIB_PMP_ExistsWriteChipSelectEnable function 1484 PLIB_PMP_ExistsWriteEnablePolarity function 1480 PLIB_PMP_ExistsWriteEnablePortControl function 1481 plib_pmp_help.h 1499 PLIB_PMP_InputBuffersAreFull function 1443 PLIB_PMP_InputBufferTypeSelect function 1425 PLIB_PMP_InputBufferXByteReceive function 1443 PLIB_PMP_InputBufferXIsFull function 1444 PLIB_PMP_InputOverflowClear function 1441 PLIB_PMP_InputOverflowHasOccurred function 1440 PLIB_PMP_InterruptModeGet function 1426 PLIB_PMP_InterruptModeSelect function 1427 PLIB_PMP_IsDataReceived function 1445 PLIB_PMP_IsDataTransmitted function 1445 PLIB_PMP_IsEnabled function 1438 PLIB_PMP_MasterReceive function 1446 PLIB_PMP_MasterSend function 1447 PLIB_PMP_MultiplexModeGet function 1427 PLIB_PMP_MultiplexModeSelect function 1428 PLIB_PMP_OperationModeGet function 1428 PLIB_PMP_OperationModeSelect function 1429 PLIB_PMP_OutputBuffersAreEmpty function 1447 PLIB_PMP_OutputBufferXByteSend function 1448 PLIB_PMP_OutputBufferXIsEmpty function 1449 PLIB_PMP_OutputUnderflowClear function 1442 PLIB_PMP_OutputUnderflowHasOccurred function 1441 PLIB_PMP_PortIsBusy function 1439 PLIB_PMP_ReadChipSelectXDisable function 1436 PLIB_PMP_ReadChipSelectXEnable function 1436 PLIB_PMP_ReadCycleIsStarted function 1451 PLIB_PMP_ReadCycleStart function 1451 PLIB_PMP_ReadWriteStrobePolaritySelect function 1461 PLIB_PMP_ReadWriteStrobePortDisable function 1458 PLIB_PMP_ReadWriteStrobePortEnable function 1458 PLIB_PMP_SlaveReceive function 1449 PLIB_PMP_SlaveSend function 1450 PLIB_PMP_StopInIdleDisable function 1430 PLIB_PMP_StopInIdleEnable function 1430 PLIB_PMP_WaitStatesDataHoldSelect function 1452 PLIB_PMP_WaitStatesDataSetUpSelect function 1452 PLIB_PMP_WaitStatesStrobeSelect function 1453 PLIB_PMP_WriteChipSelectXDisable function 1437 PLIB_PMP_WriteChipSelectXEnable function 1437 PLIB_PMP_WriteEnableStrobePolaritySelect function 1462 PLIB_PMP_WriteEnableStrobePortDisable function 1459 PLIB_PMP_WriteEnableStrobePortEnable function 1459 plib_ports.h 1636 PLIB_PORTS_AnPinsModeSelect function 1598 PLIB_PORTS_ChangeNoticeDisable function 1579 PLIB_PORTS_ChangeNoticeEnable function 1579 PLIB_PORTS_ChangeNoticeInIdleDisable function 1580 PLIB_PORTS_ChangeNoticeInIdleEnable function 1580 PLIB_PORTS_ChangeNoticeInIdlePerPortDisable function 1581 PLIB_PORTS_ChangeNoticeInIdlePerPortEnable function 1582 PLIB_PORTS_ChangeNoticePerPortHasOccured function 1582 PLIB_PORTS_ChangeNoticePerPortHasOccurred function 1590 PLIB_PORTS_ChangeNoticePerPortTurnOff function 1582 PLIB_PORTS_ChangeNoticePerPortTurnOn function 1583 PLIB_PORTS_ChangeNoticePullDownPerPortDisable function 1584 PLIB_PORTS_ChangeNoticePullDownPerPortEnable function 1584 PLIB_PORTS_ChangeNoticePullUpDisable function 1585 PLIB_PORTS_ChangeNoticePullUpEnable function 1586 PLIB_PORTS_ChangeNoticePullUpPerPortDisable function 1586 PLIB_PORTS_ChangeNoticePullUpPerPortEnable function 1587 PLIB_PORTS_ChannelChangeNoticeDisable function 1591 PLIB_PORTS_ChannelChangeNoticeEdgeDisable function 1595 PLIB_PORTS_ChannelChangeNoticeEdgeEnable function 1596 PLIB_PORTS_ChannelChangeNoticeEnable function 1592 PLIB_PORTS_ChannelChangeNoticeMethodGet function 1597 PLIB_PORTS_ChannelChangeNoticeMethodSelect function 1597 PLIB_PORTS_ChannelChangeNoticePullDownDisable function 1592 PLIB_PORTS_ChannelChangeNoticePullDownEnable function 1593 PLIB_PORTS_ChannelChangeNoticePullUpDisable function 1594 PLIB_PORTS_ChannelChangeNoticePullUpEnable function 1594 PLIB_PORTS_ChannelModeSelect function 1576 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2393 PLIB_PORTS_ChannelSlewRateSelect function 1576 PLIB_PORTS_Clear function 1569 PLIB_PORTS_CnPinsDisable function 1599 PLIB_PORTS_CnPinsEnable function 1600 PLIB_PORTS_CnPinsPullUpDisable function 1600 PLIB_PORTS_CnPinsPullUpEnable function 1601 PLIB_PORTS_DirectionGet function 1569 PLIB_PORTS_DirectionInputSet function 1570 PLIB_PORTS_DirectionOutputSet function 1570 PLIB_PORTS_ExistsAnPinsMode function 1613 PLIB_PORTS_ExistsChangeNotice function 1602 PLIB_PORTS_ExistsChangeNoticeEdgeControl function 1613 PLIB_PORTS_ExistsChangeNoticeEdgeStatus function 1614 PLIB_PORTS_ExistsChangeNoticeInIdle function 1602 PLIB_PORTS_ExistsChangeNoticePerPortInIdle function 1603 PLIB_PORTS_ExistsChangeNoticePerPortStatus function 1604 PLIB_PORTS_ExistsChangeNoticePerPortTurnOn function 1604 PLIB_PORTS_ExistsChangeNoticePullDownPerPort function 1605 PLIB_PORTS_ExistsChangeNoticePullUp function 1605 PLIB_PORTS_ExistsChangeNoticePullUpPerPort function 1606 PLIB_PORTS_ExistsChannelChangeNoticeMethod function 1614 PLIB_PORTS_ExistsLatchRead function 1612 PLIB_PORTS_ExistsPinChangeNotice function 1606 PLIB_PORTS_ExistsPinChangeNoticePerPort function 1607 PLIB_PORTS_ExistsPinMode function 1608 PLIB_PORTS_ExistsPinModePerPort function 1608 PLIB_PORTS_ExistsPortsDirection function 1609 PLIB_PORTS_ExistsPortsOpenDrain function 1609 PLIB_PORTS_ExistsPortsRead function 1610 PLIB_PORTS_ExistsPortsWrite function 1610 PLIB_PORTS_ExistsRemapInput function 1611 PLIB_PORTS_ExistsRemapOutput function 1612 PLIB_PORTS_ExistsSlewRateControl function 1615 PLIB_PORTS_OpenDrainDisable function 1574 PLIB_PORTS_OpenDrainEnable function 1574 PLIB_PORTS_PinChangeNoticeDisable function 1588 PLIB_PORTS_PinChangeNoticeEdgeHasOccurred function 1565 PLIB_PORTS_PinChangeNoticeEdgeIsEnabled function 1566 PLIB_PORTS_PinChangeNoticeEnable function 1588 PLIB_PORTS_PinChangeNoticePerPortDisable function 1589 PLIB_PORTS_PinChangeNoticePerPortEnable function 1589 PLIB_PORTS_PinClear function 1559 PLIB_PORTS_PinDirectionInputSet function 1559 PLIB_PORTS_PinDirectionOutputSet function 1560 PLIB_PORTS_PinGet function 1561 PLIB_PORTS_PinGetLatched function 1564 PLIB_PORTS_PinModePerPortSelect function 1564 PLIB_PORTS_PinModeSelect function 1561 PLIB_PORTS_PinOpenDrainDisable function 1567 PLIB_PORTS_PinOpenDrainEnable function 1568 PLIB_PORTS_PinSet function 1562 PLIB_PORTS_PinSlewRateGet function 1567 PLIB_PORTS_PinToggle function 1562 PLIB_PORTS_PinWrite function 1563 PLIB_PORTS_Read function 1571 PLIB_PORTS_ReadLatched function 1575 PLIB_PORTS_RemapInput function 1577 PLIB_PORTS_RemapOutput function 1578 PLIB_PORTS_Set function 1572 PLIB_PORTS_Toggle function 1572 PLIB_PORTS_Write function 1573 plib_power.h 1684 PLIB_POWER_ClearIdleStatus function 1653 PLIB_POWER_ClearSleepStatus function 1654 PLIB_POWER_DeepSleepEventStatusClear function 1657 PLIB_POWER_DeepSleepEventStatusGet function 1658 PLIB_POWER_DeepSleepGPRRead function 1665 PLIB_POWER_DeepSleepGPRsRetentionDisable function 1648 PLIB_POWER_DeepSleepGPRsRetentionEnable function 1648 PLIB_POWER_DeepSleepGPRWrite function 1666 PLIB_POWER_DeepSleepModeDisable function 1644 PLIB_POWER_DeepSleepModeEnable function 1644 PLIB_POWER_DeepSleepModeHasOccurred function 1658 PLIB_POWER_DeepSleepModeIsEnabled function 1649 PLIB_POWER_DeepSleepModuleDisable function 1650 PLIB_POWER_DeepSleepModuleEnable function 1650 PLIB_POWER_DeepSleepPortPinsStateRelease function 1651 PLIB_POWER_DeepSleepPortPinsStateRetain function 1651 PLIB_POWER_DeepSleepStatusClear function 1657 PLIB_POWER_DeepSleepWakeupEventDisable function 1652 PLIB_POWER_DeepSleepWakeupEventEnable function 1652 PLIB_POWER_DeviceWasInIdleMode function 1654 PLIB_POWER_DeviceWasInSleepMode function 1655 PLIB_POWER_ExistsDeepSleepEventStatus function 1669 PLIB_POWER_ExistsDeepSleepGPROperation function 1670 PLIB_POWER_ExistsDeepSleepGPRsRetentionControl function 1670 PLIB_POWER_ExistsDeepSleepMode function 1666 PLIB_POWER_ExistsDeepSleepModeOccurrence function 1673 PLIB_POWER_ExistsDeepSleepModuleControl function 1671 PLIB_POWER_ExistsDeepSleepPortPinsStateControl function 1671 PLIB_POWER_ExistsDeepSleepWakeupEventControl function 1673 PLIB_POWER_ExistsHighVoltageOnVDD1V8 function 1672 PLIB_POWER_ExistsHLVDBandGapVoltageStability function 1674 PLIB_POWER_ExistsHLVDEnableControl function 1674 PLIB_POWER_ExistsHLVDLimitSelection function 1675 PLIB_POWER_ExistsHLVDModeControl function 1675 PLIB_POWER_ExistsHLVDStatus function 1676 PLIB_POWER_ExistsHLVDStopInIdleControl function 1676 PLIB_POWER_ExistsIdleStatus function 1667 PLIB_POWER_ExistsPeripheralModuleControl function 1668 PLIB_POWER_ExistsSleepStatus function 1668 PLIB_POWER_ExistsVoltageRegulatorControl function 1669 PLIB_POWER_HighVoltageOnVDD1V8HasOccurred function 1655 PLIB_POWER_HLVDBandGapVoltageIsStable function 1659 PLIB_POWER_HLVDDisable function 1660 PLIB_POWER_HLVDEnable function 1660 PLIB_POWER_HLVDIsEnabled function 1661 PLIB_POWER_HLVDLimitSelect function 1661 PLIB_POWER_HLVDModeSelect function 1662 PLIB_POWER_HLVDStatusGet function 1663 PLIB_POWER_HLVDStopInIdleDisable function 1663 PLIB_POWER_HLVDStopInIdleEnable function 1664 PLIB_POWER_HLVDStopInIdleIsEnabled function 1664 PLIB_POWER_PeripheralModuleDisable function 1645 PLIB_POWER_PeripheralModuleEnable function 1645 PLIB_POWER_PeripheralModuleIsEnabled function 1646 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2394 PLIB_POWER_VoltageRegulatorDisable function 1647 PLIB_POWER_VoltageRegulatorEnable function 1647 PLIB_POWER_VoltageRegulatorIsEnabled function 1656 plib_reset.h 1702 PLIB_RESET_ConfigRegReadErrorGet function 1691 PLIB_RESET_ExistsConfigRegReadError function 1697 PLIB_RESET_ExistsNmiControl function 1697 PLIB_RESET_ExistsNmiCounter function 1698 PLIB_RESET_ExistsResetReasonStatus function 1696 PLIB_RESET_ExistsSoftwareResetTrigger function 1696 PLIB_RESET_ExistsWdtoInSleep function 1698 PLIB_RESET_NmiCounterValueGet function 1693 PLIB_RESET_NmiCounterValueSet function 1693 PLIB_RESET_NmiEventClear function 1694 PLIB_RESET_NmiEventTrigger function 1694 PLIB_RESET_NmiReasonGet function 1695 PLIB_RESET_ReasonClear function 1690 PLIB_RESET_ReasonGet function 1691 PLIB_RESET_SoftwareResetEnable function 1689 PLIB_RESET_WdtTimeOutHasOccurredInSleep function 1692 plib_rtcc.h 1760 PLIB_RTCC_AlarmChimeDisable function 1727 PLIB_RTCC_AlarmChimeEnable function 1728 PLIB_RTCC_AlarmDateGet function 1728 PLIB_RTCC_AlarmDateSet function 1729 PLIB_RTCC_AlarmDayGet function 1729 PLIB_RTCC_AlarmDaySet function 1730 PLIB_RTCC_AlarmDisable function 1731 PLIB_RTCC_AlarmEnable function 1731 PLIB_RTCC_AlarmHourGet function 1732 PLIB_RTCC_AlarmHourSet function 1733 PLIB_RTCC_AlarmMaskModeSelect function 1733 PLIB_RTCC_AlarmMinuteGet function 1734 PLIB_RTCC_AlarmMinuteSet function 1734 PLIB_RTCC_AlarmMonthGet function 1735 PLIB_RTCC_AlarmMonthSet function 1736 PLIB_RTCC_AlarmPulseInitialGet function 1736 PLIB_RTCC_AlarmPulseInitialSet function 1737 PLIB_RTCC_AlarmRepeatCountGet function 1737 PLIB_RTCC_AlarmRepeatCountSet function 1738 PLIB_RTCC_AlarmSecondGet function 1739 PLIB_RTCC_AlarmSecondSet function 1739 PLIB_RTCC_AlarmSyncStatusGet function 1743 PLIB_RTCC_AlarmTimeGet function 1740 PLIB_RTCC_AlarmTimeSet function 1740 PLIB_RTCC_AlarmValueRegisterPointer function 1741 PLIB_RTCC_AlarmWeekDayGet function 1742 PLIB_RTCC_AlarmWeekDaySet function 1742 PLIB_RTCC_ClockOutputDisable function 1712 PLIB_RTCC_ClockOutputEnable function 1712 PLIB_RTCC_ClockRunningStatus function 1713 PLIB_RTCC_ClockSourceSelect function 1743 PLIB_RTCC_Disable function 1714 PLIB_RTCC_DriftCalibrateGet function 1744 PLIB_RTCC_DriftCalibrateSet function 1745 PLIB_RTCC_Enable function 1714 PLIB_RTCC_ExistsAlarmChimeControl function 1748 PLIB_RTCC_ExistsAlarmControl function 1748 PLIB_RTCC_ExistsAlarmDate function 1749 PLIB_RTCC_ExistsAlarmMaskControl function 1749 PLIB_RTCC_ExistsAlarmPulseInitial function 1750 PLIB_RTCC_ExistsAlarmRepeatControl function 1750 PLIB_RTCC_ExistsAlarmSynchronization function 1758 PLIB_RTCC_ExistsAlarmTime function 1751 PLIB_RTCC_ExistsCalibration function 1751 PLIB_RTCC_ExistsClockRunning function 1752 PLIB_RTCC_ExistsClockSelect function 1752 PLIB_RTCC_ExistsEnableControl function 1753 PLIB_RTCC_ExistsHalfSecond function 1754 PLIB_RTCC_ExistsOutputControl function 1754 PLIB_RTCC_ExistsOutputSelect function 1755 PLIB_RTCC_ExistsRTCDate function 1755 PLIB_RTCC_ExistsRTCTime function 1756 PLIB_RTCC_ExistsStopInIdleControl function 1756 PLIB_RTCC_ExistsSynchronization function 1757 PLIB_RTCC_ExistsWriteEnable function 1757 PLIB_RTCC_HalfSecondStatusGet function 1745 plib_rtcc_help.h 1762 PLIB_RTCC_OutputSelect function 1746 PLIB_RTCC_RTCDateGet function 1716 PLIB_RTCC_RTCDateSet function 1716 PLIB_RTCC_RTCDayGet function 1717 PLIB_RTCC_RTCDaySet function 1718 PLIB_RTCC_RTCHourGet function 1718 PLIB_RTCC_RTCHourSet function 1719 PLIB_RTCC_RTCMinuteGet function 1719 PLIB_RTCC_RTCMinuteSet function 1720 PLIB_RTCC_RTCMonthGet function 1721 PLIB_RTCC_RTCMonthSet function 1721 PLIB_RTCC_RTCSecondGet function 1722 PLIB_RTCC_RTCSecondSet function 1722 PLIB_RTCC_RTCSyncStatusGet function 1726 PLIB_RTCC_RTCTimeGet function 1723 PLIB_RTCC_RTCTimeSet function 1723 PLIB_RTCC_RTCWeekDayGet function 1724 PLIB_RTCC_RTCWeekDaySet function 1725 PLIB_RTCC_RTCYearGet function 1725 PLIB_RTCC_RTCYearSet function 1726 PLIB_RTCC_StopInIdleDisable function 1746 PLIB_RTCC_StopInIdleEnable function 1747 PLIB_RTCC_WriteDisable function 1715 PLIB_RTCC_WriteEnable function 1715 plib_sb.h 1802 PLIB_SB_ARB_POLICY enumeration 1797 PLIB_SB_CPUPrioritySet function 1783 PLIB_SB_DMAPrioritySet function 1784 PLIB_SB_ERROR enumeration 1797 PLIB_SB_ExistsCPUPriority function 1785 PLIB_SB_ExistsDMAPriority function 1786 PLIB_SB_ExistsInitPermGrp function 1786 PLIB_SB_ExistsPGRegAddr function 1787 PLIB_SB_ExistsPGRegRdPerm function 1787 PLIB_SB_ExistsPGRegSize function 1788 PLIB_SB_ExistsPGRegWrPerm function 1789 PLIB_SB_ExistsPGVErrClear function 1789 PLIB_SB_ExistsPGVErrClrMulti function 1790 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2395 PLIB_SB_ExistsPGVErrClrSingle function 1790 PLIB_SB_ExistsPGVErrCmdCode function 1791 PLIB_SB_ExistsPGVErrGroup0Status function 1794 PLIB_SB_ExistsPGVErrGroup1Status function 1794 PLIB_SB_ExistsPGVErrGroup2Status function 1795 PLIB_SB_ExistsPGVErrGroup3Status function 1795 PLIB_SB_ExistsPGVErrGroupStatus function 1796 PLIB_SB_ExistsPGVErrInitID function 1791 PLIB_SB_ExistsPGVErrPG function 1792 PLIB_SB_ExistsPGVErrRegion function 1792 PLIB_SB_ExistsPGVErrRptPri function 1793 PLIB_SB_ExistsPGVErrStatus function 1793 PLIB_SB_INIT_ID enumeration 1797 PLIB_SB_INIT_PG enumeration 1798 PLIB_SB_InitPermGrpSet function 1785 PLIB_SB_OCP_CMD_CODE enumeration 1798 PLIB_SB_PG_INITIATOR enumeration 1799 PLIB_SB_PGRegionAddrGet function 1768 PLIB_SB_PGRegionAddrSet function 1768 PLIB_SB_PGRegionReadPermClear function 1769 PLIB_SB_PGRegionReadPermSet function 1770 PLIB_SB_PGRegionSizeGet function 1770 PLIB_SB_PGRegionSizeSet function 1771 PLIB_SB_PGRegionWritePermClear function 1772 PLIB_SB_PGRegionWritePermSet function 1772 PLIB_SB_PGVErrGroup0Status function 1780 PLIB_SB_PGVErrGroup1Status function 1781 PLIB_SB_PGVErrGroup2Status function 1782 PLIB_SB_PGVErrGroup3Status function 1782 PLIB_SB_PGVErrGroupStatus function 1783 PLIB_SB_PGVErrorClearMulti function 1773 PLIB_SB_PGVErrorClearSingle function 1774 PLIB_SB_PGVErrorCode function 1774 PLIB_SB_PGVErrorCommandCode function 1775 PLIB_SB_PGVErrorInitiatorID function 1775 PLIB_SB_PGVErrorLogClearMulti function 1776 PLIB_SB_PGVErrorLogClearSingle function 1776 PLIB_SB_PGVErrorMulti function 1777 PLIB_SB_PGVErrorPermissionGroup function 1778 PLIB_SB_PGVErrorRegion function 1778 PLIB_SB_PGVErrorReportPrimaryDisable function 1779 PLIB_SB_PGVErrorReportPrimaryEnable function 1779 PLIB_SB_PGVErrorStatus function 1780 PLIB_SB_REGION_PG enumeration 1799 PLIB_SB_TGT_ID enumeration 1799 PLIB_SB_TGT_REGION enumeration 1800 plib_spi.h 1895 PLIB_SPI_AudioCommunicationWidthSelect function 1856 PLIB_SPI_AudioErrorDisable function 1857 PLIB_SPI_AudioErrorEnable function 1857 PLIB_SPI_AudioProtocolDisable function 1858 PLIB_SPI_AudioProtocolEnable function 1859 PLIB_SPI_AudioProtocolModeSelect function 1859 PLIB_SPI_AudioTransmitModeSelect function 1860 PLIB_SPI_BaudRateClockSelect function 1830 PLIB_SPI_BaudRateSet function 1831 PLIB_SPI_BufferAddressGet function 1847 PLIB_SPI_BufferClear function 1846 PLIB_SPI_BufferRead function 1846 PLIB_SPI_BufferRead16bit function 1847 PLIB_SPI_BufferRead32bit function 1848 PLIB_SPI_BufferWrite function 1848 PLIB_SPI_BufferWrite16bit function 1849 PLIB_SPI_BufferWrite32bit function 1850 PLIB_SPI_ClockPolaritySelect function 1831 PLIB_SPI_CommunicationWidthSelect function 1832 PLIB_SPI_Disable function 1833 PLIB_SPI_Enable function 1833 PLIB_SPI_ErrorInterruptDisable function 1834 PLIB_SPI_ErrorInterruptEnable function 1835 PLIB_SPI_Exists16bitBuffer function 1886 PLIB_SPI_Exists32bitBuffer function 1886 PLIB_SPI_ExistsAudioCommunicationWidth function 1866 PLIB_SPI_ExistsAudioErrorControl function 1866 PLIB_SPI_ExistsAudioProtocolControl function 1867 PLIB_SPI_ExistsAudioProtocolMode function 1867 PLIB_SPI_ExistsAudioTransmitMode function 1868 PLIB_SPI_ExistsBaudRate function 1868 PLIB_SPI_ExistsBaudRateClock function 1869 PLIB_SPI_ExistsBuffer function 1869 PLIB_SPI_ExistsBusStatus function 1870 PLIB_SPI_ExistsClockPolarity function 1870 PLIB_SPI_ExistsCommunicationWidth function 1871 PLIB_SPI_ExistsEnableControl function 1872 PLIB_SPI_ExistsErrorInterruptControl function 1872 PLIB_SPI_ExistsFIFOControl function 1873 PLIB_SPI_ExistsFIFOCount function 1873 PLIB_SPI_ExistsFIFOInterruptMode function 1874 PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus function 1874 PLIB_SPI_ExistsFramedCommunication function 1875 PLIB_SPI_ExistsFrameErrorStatus function 1875 PLIB_SPI_ExistsFrameSyncPulseCounter function 1876 PLIB_SPI_ExistsFrameSyncPulseDirection function 1876 PLIB_SPI_ExistsFrameSyncPulseEdge function 1877 PLIB_SPI_ExistsFrameSyncPulsePolarity function 1878 PLIB_SPI_ExistsFrameSyncPulseWidth function 1878 PLIB_SPI_ExistsInputSamplePhase function 1879 PLIB_SPI_ExistsMasterControl function 1879 PLIB_SPI_ExistsOutputDataPhase function 1880 PLIB_SPI_ExistsPinControl function 1880 PLIB_SPI_ExistsReadDataSignStatus function 1881 PLIB_SPI_ExistsReceiveBufferStatus function 1881 PLIB_SPI_ExistsReceiveFIFOStatus function 1882 PLIB_SPI_ExistsReceiverOverflow function 1882 PLIB_SPI_ExistsSlaveSelectControl function 1883 PLIB_SPI_ExistsStopInIdleControl function 1883 PLIB_SPI_ExistsTransmitBufferEmptyStatus function 1884 PLIB_SPI_ExistsTransmitBufferFullStatus function 1885 PLIB_SPI_ExistsTransmitUnderRunStatus function 1885 PLIB_SPI_FIFOCountGet function 1835 PLIB_SPI_FIFODisable function 1836 PLIB_SPI_FIFOEnable function 1836 PLIB_SPI_FIFOInterruptModeSelect function 1837 PLIB_SPI_FIFOShiftRegisterIsEmpty function 1838 PLIB_SPI_FramedCommunicationDisable function 1850 PLIB_SPI_FramedCommunicationEnable function 1851 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2396 PLIB_SPI_FrameErrorStatusClear function 1852 PLIB_SPI_FrameErrorStatusGet function 1852 PLIB_SPI_FrameSyncPulseCounterSelect function 1853 PLIB_SPI_FrameSyncPulseDirectionSelect function 1853 PLIB_SPI_FrameSyncPulseEdgeSelect function 1854 PLIB_SPI_FrameSyncPulsePolaritySelect function 1855 PLIB_SPI_FrameSyncPulseWidthSelect function 1855 PLIB_SPI_InputSamplePhaseSelect function 1838 PLIB_SPI_IsBusy function 1839 PLIB_SPI_MasterEnable function 1840 PLIB_SPI_OutputDataPhaseSelect function 1840 PLIB_SPI_PinDisable function 1841 PLIB_SPI_PinEnable function 1841 PLIB_SPI_ReadDataIsSignExtended function 1842 PLIB_SPI_ReceiverBufferIsFull function 1863 PLIB_SPI_ReceiverFIFOIsEmpty function 1864 PLIB_SPI_ReceiverHasOverflowed function 1864 PLIB_SPI_ReceiverOverflowClear function 1865 PLIB_SPI_SlaveEnable function 1843 PLIB_SPI_SlaveSelectDisable function 1843 PLIB_SPI_SlaveSelectEnable function 1844 PLIB_SPI_StopInIdleDisable function 1844 PLIB_SPI_StopInIdleEnable function 1845 PLIB_SPI_TransmitBufferIsEmpty function 1860 PLIB_SPI_TransmitBufferIsFull function 1861 PLIB_SPI_TransmitUnderRunStatusClear function 1862 PLIB_SPI_TransmitUnderRunStatusGet function 1862 plib_sqi.h 2031 PLIB_SQI_BurstEnable function 1912 PLIB_SQI_ByteCountGet function 1950 PLIB_SQI_ByteCountSet function 1950 PLIB_SQI_ChipSelectDeassertDisable function 1951 PLIB_SQI_ChipSelectDeassertEnable function 1952 PLIB_SQI_ChipSelectGet function 1952 PLIB_SQI_ChipSelectSet function 1953 PLIB_SQI_ClockDisable function 1913 PLIB_SQI_ClockDividerSet function 1933 PLIB_SQI_ClockEnable function 1933 PLIB_SQI_ClockIsStable function 1934 PLIB_SQI_CommandStatusGet function 1967 PLIB_SQI_ConBufferSoftReset function 1929 PLIB_SQI_ConBufWordsAvailable function 1968 PLIB_SQI_ConfigWordGet function 1953 PLIB_SQI_ConfigWordSet function 1954 PLIB_SQI_ControlBufferThresholdGet function 1913 PLIB_SQI_ControlBufferThresholdSet function 1914 PLIB_SQI_ControlWordGet function 1914 PLIB_SQI_ControlWordSet function 1915 PLIB_SQI_CSOutputEnableSelect function 1916 PLIB_SQI_DataFormatGet function 1916 PLIB_SQI_DataFormatSet function 1917 PLIB_SQI_DataLineStatus function 1967 PLIB_SQI_DataModeSet function 1918 PLIB_SQI_DataOutputEnableSelect function 1918 PLIB_SQI_DDRModeGet function 1932 PLIB_SQI_DDRModeSet function 1932 PLIB_SQI_Disable function 1919 PLIB_SQI_DMABDBaseAddressGet function 1969 PLIB_SQI_DMABDBaseAddressSet function 1969 PLIB_SQI_DMABDControlWordGet function 1970 PLIB_SQI_DMABDCurrentAddressGet function 1970 PLIB_SQI_DMABDFetchStart function 1975 PLIB_SQI_DMABDFetchStop function 1975 PLIB_SQI_DMABDIsBusy function 1976 PLIB_SQI_DMABDPollCounterSet function 1977 PLIB_SQI_DMABDPollDisable function 1977 PLIB_SQI_DMABDPollEnable function 1978 PLIB_SQI_DMABDPollIsEnabled function 1978 PLIB_SQI_DMABDReceiveBufferCountGet function 1971 PLIB_SQI_DMABDReceiveBufferLengthGet function 1972 PLIB_SQI_DMABDReceiveStateGet function 1972 PLIB_SQI_DMABDStateGet function 1979 PLIB_SQI_DMABDTransmitBufferCountGet function 1973 PLIB_SQI_DMABDTransmitBufferLengthGet function 1974 PLIB_SQI_DMABDTransmitStateGet function 1974 PLIB_SQI_DMADisable function 1980 PLIB_SQI_DMAEnable function 1980 PLIB_SQI_DMAHasStarted function 1981 PLIB_SQI_DMAIsEnabled function 1981 PLIB_SQI_Enable function 1919 PLIB_SQI_ExistsBDBaseAddress function 1983 PLIB_SQI_ExistsBDControlWord function 1983 PLIB_SQI_ExistsBDCurrentAddress function 1984 PLIB_SQI_ExistsBDPollCount function 1984 PLIB_SQI_ExistsBDPollingEnable function 1985 PLIB_SQI_ExistsBDProcessState function 1986 PLIB_SQI_ExistsBDRxBufCount function 1986 PLIB_SQI_ExistsBDRxLength function 1987 PLIB_SQI_ExistsBDRxState function 1987 PLIB_SQI_ExistsBDTxBufCount function 1988 PLIB_SQI_ExistsBDTxLength function 1988 PLIB_SQI_ExistsBDTxState function 1989 PLIB_SQI_ExistsBurstControl function 1989 PLIB_SQI_ExistsChipSelect function 1990 PLIB_SQI_ExistsClockControl function 1990 PLIB_SQI_ExistsClockDivider function 1991 PLIB_SQI_ExistsClockReady function 1991 PLIB_SQI_ExistsCommandStatus function 2015 PLIB_SQI_ExistsConBufAvailable function 2016 PLIB_SQI_ExistsConBufferSoftReset function 2016 PLIB_SQI_ExistsConBufThreshold function 1992 PLIB_SQI_ExistsConfigWord function 1992 PLIB_SQI_ExistsControlWord function 1993 PLIB_SQI_ExistsCSDeassert function 1994 PLIB_SQI_ExistsCSOutputEnable function 1994 PLIB_SQI_ExistsDataFormat function 1995 PLIB_SQI_ExistsDataModeControl function 1995 PLIB_SQI_ExistsDataOutputEnable function 1996 PLIB_SQI_ExistsDataPinStatus function 1996 PLIB_SQI_ExistsDDRMode function 2017 PLIB_SQI_ExistsDMABDFetch function 2018 PLIB_SQI_ExistsDmaEnable function 1997 PLIB_SQI_ExistsDMAEngineBusy function 1997 PLIB_SQI_ExistsDMAProcessInProgress function 1998 PLIB_SQI_ExistsEnableControl function 1998 PLIB_SQI_ExistsHoldPinControl function 1999 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2397 PLIB_SQI_ExistsInterruptControl function 2000 PLIB_SQI_ExistsInterruptSignalControl function 2000 PLIB_SQI_ExistsInterruptStatus function 2001 PLIB_SQI_ExistsLaneMode function 2001 PLIB_SQI_ExistsReceiveLatch function 2002 PLIB_SQI_ExistsRxBufferCount function 2002 PLIB_SQI_ExistsRxBufferSoftReset function 2018 PLIB_SQI_ExistsRxBufIntThreshold function 2003 PLIB_SQI_ExistsRxBufThreshold function 2003 PLIB_SQI_ExistsRxData function 2004 PLIB_SQI_ExistsRxUnderRun function 2004 PLIB_SQI_ExistsSoftReset function 2005 PLIB_SQI_ExistsStatusCheck function 2019 PLIB_SQI_ExistsTapDelay function 2019 PLIB_SQI_ExistsTransferCommand function 2006 PLIB_SQI_ExistsTransferCount function 2006 PLIB_SQI_ExistsTransferModeControl function 2007 PLIB_SQI_ExistsTxBufferFree function 2007 PLIB_SQI_ExistsTxBufferSoftReset function 2020 PLIB_SQI_ExistsTxBufIntThreshold function 2008 PLIB_SQI_ExistsTxBufThreshold function 2008 PLIB_SQI_ExistsTxData function 2009 PLIB_SQI_ExistsTxOverFlow function 2009 PLIB_SQI_ExistsWPPinControl function 2010 PLIB_SQI_ExistsXIPChipSelect function 2010 PLIB_SQI_ExistsXIPControlWord1 function 2011 PLIB_SQI_ExistsXIPControlWord2 function 2012 PLIB_SQI_ExistsXIPControlWord3 function 2020 PLIB_SQI_ExistsXIPControlWord4 function 2021 PLIB_SQI_ExistsXIPDDRMode function 2021 PLIB_SQI_ExistsXIPLaneMode function 2012 PLIB_SQI_ExistsXIPModeBytes function 2013 PLIB_SQI_ExistsXIPModeCode function 2013 PLIB_SQI_ExistsXIPNumberOfAddressBytes function 2014 PLIB_SQI_ExistsXIPNumberOfDummyBytes function 2014 PLIB_SQI_ExistsXIPReadOpCode function 2015 PLIB_SQI_ExistsXIPSDRCommandDDRData function 2022 PLIB_SQI_HoldClear function 1920 PLIB_SQI_HoldGet function 1920 PLIB_SQI_HoldSet function 1921 PLIB_SQI_InterruptDisable function 1962 PLIB_SQI_InterruptEnable function 1963 PLIB_SQI_InterruptFlagGet function 1964 PLIB_SQI_InterruptIsEnabled function 1964 PLIB_SQI_InterruptSignalDisable function 1965 PLIB_SQI_InterruptSignalEnable function 1966 PLIB_SQI_InterruptSignalIsEnabled function 1966 PLIB_SQI_LaneModeGet function 1921 PLIB_SQI_LaneModeSet function 1922 PLIB_SQI_NumberOfReceiveBufferReads function 1923 PLIB_SQI_ReceiveBufferIsUnderrun function 1955 PLIB_SQI_ReceiveData function 1923 PLIB_SQI_ReceiveLatchDisable function 1924 PLIB_SQI_ReceiveLatchEnable function 1924 PLIB_SQI_ReceiveLatchGet function 1925 PLIB_SQI_RxBufferSoftReset function 1930 PLIB_SQI_RxBufferThresholdGet function 1956 PLIB_SQI_RxBufferThresholdIntGet function 1956 PLIB_SQI_RxBufferThresholdIntSet function 1957 PLIB_SQI_RxBufferThresholdSet function 1957 PLIB_SQI_SoftReset function 1925 PLIB_SQI_StatusCheckSet function 1982 PLIB_SQI_TapDelaySet function 1931 PLIB_SQI_TransferDirectionGet function 1958 PLIB_SQI_TransferDirectionSet function 1958 PLIB_SQI_TransferModeGet function 1926 PLIB_SQI_TransferModeSet function 1926 PLIB_SQI_TransmitBufferFreeSpaceGet function 1959 PLIB_SQI_TransmitBufferHasOverflowed function 1960 PLIB_SQI_TransmitData function 1927 PLIB_SQI_TxBufferSoftReset function 1930 PLIB_SQI_TxBufferThresholdGet function 1960 PLIB_SQI_TxBufferThresholdIntGet function 1961 PLIB_SQI_TxBufferThresholdIntSet function 1961 PLIB_SQI_TxBufferThresholdSet function 1962 PLIB_SQI_WriteProtectClear function 1928 PLIB_SQI_WriteProtectGet function 1928 PLIB_SQI_WriteProtectSet function 1929 PLIB_SQI_XIPAddressBytesGet function 1935 PLIB_SQI_XIPAddressBytesSet function 1935 PLIB_SQI_XIPChipSelectGet function 1936 PLIB_SQI_XIPChipSelectSet function 1936 PLIB_SQI_XIPControlWord1Get function 1937 PLIB_SQI_XIPControlWord1Set function 1937 PLIB_SQI_XIPControlWord2Get function 1938 PLIB_SQI_XIPControlWord2Set function 1939 PLIB_SQI_XIPControlWord3Get function 1945 PLIB_SQI_XIPControlWord3Set function 1946 PLIB_SQI_XIPControlWord4Get function 1947 PLIB_SQI_XIPControlWord4Set function 1949 PLIB_SQI_XIPDDRModeSet function 1947 PLIB_SQI_XIPDummyBytesGet function 1940 PLIB_SQI_XIPDummyBytesSet function 1940 PLIB_SQI_XIPLaneModeSet function 1941 PLIB_SQI_XIPModeBytesGet function 1942 PLIB_SQI_XIPModeBytesSet function 1942 PLIB_SQI_XIPModeCodeGet function 1943 PLIB_SQI_XIPModeCodeSet function 1943 PLIB_SQI_XIPReadOpcodeGet function 1944 PLIB_SQI_XIPReadOpcodeSet function 1945 PLIB_SQI_XIPSDRCommandDDRDataGet function 1948 PLIB_SQI_XIPSDRCommandDDRDataSet function 1948 plib_tmr.h 2072 PLIB_TMR_ClockSourceExternalSyncDisable function 2049 PLIB_TMR_ClockSourceExternalSyncEnable function 2049 PLIB_TMR_ClockSourceSelect function 2050 PLIB_TMR_Counter16BitClear function 2056 PLIB_TMR_Counter16BitGet function 2057 PLIB_TMR_Counter16BitSet function 2057 PLIB_TMR_Counter32BitClear function 2058 PLIB_TMR_Counter32BitGet function 2058 PLIB_TMR_Counter32BitSet function 2059 PLIB_TMR_CounterAsyncWriteDisable function 2060 PLIB_TMR_CounterAsyncWriteEnable function 2060 PLIB_TMR_CounterAsyncWriteInProgress function 2061 PLIB_TMR_ExistsClockSource function 2062 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2398 PLIB_TMR_ExistsClockSourceSync function 2063 PLIB_TMR_ExistsCounter16Bit function 2063 PLIB_TMR_ExistsCounter32Bit function 2064 PLIB_TMR_ExistsCounterAsyncWriteControl function 2064 PLIB_TMR_ExistsCounterAsyncWriteInProgress function 2065 PLIB_TMR_ExistsEnableControl function 2065 PLIB_TMR_ExistsGatedTimeAccumulation function 2066 PLIB_TMR_ExistsMode16Bit function 2067 PLIB_TMR_ExistsMode32Bit function 2067 PLIB_TMR_ExistsPeriod16Bit function 2068 PLIB_TMR_ExistsPeriod32Bit function 2068 PLIB_TMR_ExistsPrescale function 2069 PLIB_TMR_ExistsStopInIdleControl function 2069 PLIB_TMR_ExistsTimerOperationMode function 2070 PLIB_TMR_GateDisable function 2050 PLIB_TMR_GateEnable function 2051 PLIB_TMR_IsPeriodMatchBased function 2062 PLIB_TMR_Mode16BitEnable function 2045 PLIB_TMR_Mode32BitEnable function 2046 PLIB_TMR_Period16BitGet function 2053 PLIB_TMR_Period16BitSet function 2054 PLIB_TMR_Period32BitGet function 2055 PLIB_TMR_Period32BitSet function 2055 PLIB_TMR_PrescaleDivisorGet function 2052 PLIB_TMR_PrescaleGet function 2052 PLIB_TMR_PrescaleSelect function 2053 PLIB_TMR_Start function 2046 PLIB_TMR_Stop function 2047 PLIB_TMR_StopInIdleDisable function 2047 PLIB_TMR_StopInIdleEnable function 2048 plib_usart.h 2157 PLIB_USART_AddressGet function 2100 PLIB_USART_AddressMaskGet function 2101 PLIB_USART_AddressMaskSet function 2102 PLIB_USART_AddressSet function 2102 PLIB_USART_BaudRateAutoDetectEnable function 2108 PLIB_USART_BaudRateAutoDetectIsComplete function 2108 PLIB_USART_BaudRateGet function 2109 PLIB_USART_BaudRateHighDisable function 2109 PLIB_USART_BaudRateHighEnable function 2110 PLIB_USART_BaudRateHighSet function 2111 PLIB_USART_BaudRateSet function 2111 PLIB_USART_BaudSetAndEnable function 2112 PLIB_USART_BRGClockSourceGet function 2113 PLIB_USART_BRGClockSourceSelect function 2113 PLIB_USART_Disable function 2089 PLIB_USART_Enable function 2090 PLIB_USART_ErrorsGet function 2098 PLIB_USART_ExistsBaudRate function 2134 PLIB_USART_ExistsBaudRateAutoDetect function 2134 PLIB_USART_ExistsBaudRateHigh function 2135 PLIB_USART_ExistsBRGClockSourceSelect function 2150 PLIB_USART_ExistsEnable function 2135 PLIB_USART_ExistsHandshakeMode function 2136 PLIB_USART_ExistsIrDA function 2136 PLIB_USART_ExistsLineControlMode function 2137 PLIB_USART_ExistsLoopback function 2137 PLIB_USART_ExistsModuleBusyStatus function 2151 PLIB_USART_ExistsOperationMode function 2138 PLIB_USART_ExistsReceiver function 2138 PLIB_USART_ExistsReceiver9Bits function 2150 PLIB_USART_ExistsReceiverAddress function 2152 PLIB_USART_ExistsReceiverAddressAutoDetect function 2139 PLIB_USART_ExistsReceiverAddressDetect function 2140 PLIB_USART_ExistsReceiverAddressMask function 2152 PLIB_USART_ExistsReceiverDataAvailableStatus function 2140 PLIB_USART_ExistsReceiverEnable function 2141 PLIB_USART_ExistsReceiverFramingErrorStatus function 2141 PLIB_USART_ExistsReceiverIdleStateLowEnable function 2142 PLIB_USART_ExistsReceiverIdleStatus function 2142 PLIB_USART_ExistsReceiverInterruptMode function 2143 PLIB_USART_ExistsReceiverOverrunStatus function 2143 PLIB_USART_ExistsReceiverParityErrorStatus function 2144 PLIB_USART_ExistsRunInOverflow function 2153 PLIB_USART_ExistsRunInSleepMode function 2153 PLIB_USART_ExistsStopInIdle function 2144 PLIB_USART_ExistsTransmitter function 2145 PLIB_USART_ExistsTransmitter9BitsSend function 2146 PLIB_USART_ExistsTransmitterBreak function 2146 PLIB_USART_ExistsTransmitterBufferFullStatus function 2147 PLIB_USART_ExistsTransmitterEmptyStatus function 2147 PLIB_USART_ExistsTransmitterEnable function 2148 PLIB_USART_ExistsTransmitterIdleIsLow function 2148 PLIB_USART_ExistsTransmitterInterruptMode function 2149 PLIB_USART_ExistsWakeOnStart function 2149 PLIB_USART_HandshakeModeSelect function 2091 plib_usart_help.h 2160 PLIB_USART_InitializeModeGeneral function 2099 PLIB_USART_InitializeOperation function 2100 PLIB_USART_IrDADisable function 2091 PLIB_USART_IrDAEnable function 2092 PLIB_USART_LineControlModeSelect function 2092 PLIB_USART_LoopbackDisable function 2093 PLIB_USART_LoopbackEnable function 2094 PLIB_USART_ModuleIsBusy function 2103 PLIB_USART_OperationModeSelect function 2094 PLIB_USART_Receiver9BitsReceive function 2133 PLIB_USART_ReceiverAddressAutoDetectDisable function 2122 PLIB_USART_ReceiverAddressAutoDetectEnable function 2122 PLIB_USART_ReceiverAddressDetectDisable function 2123 PLIB_USART_ReceiverAddressDetectEnable function 2124 PLIB_USART_ReceiverAddressGet function 2132 PLIB_USART_ReceiverAddressIsReceived function 2124 PLIB_USART_ReceiverByteReceive function 2125 PLIB_USART_ReceiverDataIsAvailable function 2126 PLIB_USART_ReceiverDisable function 2126 PLIB_USART_ReceiverEnable function 2127 PLIB_USART_ReceiverFramingErrorHasOccurred function 2127 PLIB_USART_ReceiverIdleStateLowDisable function 2128 PLIB_USART_ReceiverIdleStateLowEnable function 2129 PLIB_USART_ReceiverInterruptModeSelect function 2129 PLIB_USART_ReceiverIsIdle function 2130 PLIB_USART_ReceiverOverrunErrorClear function 2131 PLIB_USART_ReceiverOverrunHasOccurred function 2131 PLIB_USART_ReceiverParityErrorHasOccurred function 2132 PLIB_USART_RunInOverflowDisable function 2104 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2399 PLIB_USART_RunInOverflowEnable function 2105 PLIB_USART_RunInOverflowIsEnabled function 2105 PLIB_USART_RunInSleepModeDisable function 2106 PLIB_USART_RunInSleepModeEnable function 2106 PLIB_USART_RunInSleepModeIsEnabled function 2107 PLIB_USART_StopInIdleDisable function 2095 PLIB_USART_StopInIdleEnable function 2095 PLIB_USART_Transmitter9BitsSend function 2114 PLIB_USART_TransmitterAddressGet function 2121 PLIB_USART_TransmitterBreakSend function 2115 PLIB_USART_TransmitterBreakSendIsComplete function 2116 PLIB_USART_TransmitterBufferIsFull function 2116 PLIB_USART_TransmitterByteSend function 2117 PLIB_USART_TransmitterDisable function 2118 PLIB_USART_TransmitterEnable function 2118 PLIB_USART_TransmitterIdleIsLowDisable function 2119 PLIB_USART_TransmitterIdleIsLowEnable function 2119 PLIB_USART_TransmitterInterruptModeSelect function 2120 PLIB_USART_TransmitterIsEmpty function 2121 PLIB_USART_WakeOnStartDisable function 2096 PLIB_USART_WakeOnStartEnable function 2097 PLIB_USART_WakeOnStartIsEnabled function 2097 plib_usb.h 2304 PLIB_USB_ActivityPending function 2249 PLIB_USB_AllInterruptEnable function 2174 PLIB_USB_AutoSuspendDisable function 2175 PLIB_USB_AutoSuspendEnable function 2175 PLIB_USB_BDTBaseAddressGet function 2187 PLIB_USB_BDTBaseAddressSet function 2188 PLIB_USB_BufferAddressGet function 2188 PLIB_USB_BufferAddressSet function 2189 PLIB_USB_BufferAllCancelReleaseToUSB function 2190 PLIB_USB_BufferByteCountGet function 2190 PLIB_USB_BufferByteCountSet function 2191 PLIB_USB_BufferCancelReleaseToUSB function 2192 PLIB_USB_BufferClearAll function 2193 PLIB_USB_BufferClearAllDTSEnable function 2193 PLIB_USB_BufferDataToggleGet function 2194 PLIB_USB_BufferDataToggleSelect function 2195 PLIB_USB_BufferDataToggleSyncDisable function 2196 PLIB_USB_BufferDataToggleSyncEnable function 2196 PLIB_USB_BufferEP0RxStatusInitialize function 2197 PLIB_USB_BufferIndexGet function 2198 PLIB_USB_BufferPIDBitsClear function 2199 PLIB_USB_BufferPIDGet function 2199 PLIB_USB_BufferReleasedToSW function 2200 PLIB_USB_BufferReleaseToUSB function 2201 PLIB_USB_BufferSchedule function 2202 PLIB_USB_BufferStallDisable function 2202 PLIB_USB_BufferStallEnable function 2203 PLIB_USB_BufferStallGet function 2204 PLIB_USB_DeviceAddressGet function 2176 PLIB_USB_DeviceAddressSet function 2176 PLIB_USB_Disable function 2177 PLIB_USB_Enable function 2178 PLIB_USB_EP0HostSetup function 2205 PLIB_USB_EP0LSDirectConnectDisable function 2205 PLIB_USB_EP0LSDirectConnectEnable function 2206 PLIB_USB_EP0NakRetryDisable function 2206 PLIB_USB_EP0NakRetryEnable function 2207 PLIB_USB_EPnAttributesClear function 2207 PLIB_USB_EPnAttributesSet function 2208 PLIB_USB_EPnControlTransferDisable function 2209 PLIB_USB_EPnControlTransferEnable function 2209 PLIB_USB_EPnDirectionDisable function 2210 PLIB_USB_EPnHandshakeDisable function 2210 PLIB_USB_EPnHandshakeEnable function 2211 PLIB_USB_EPnIsStalled function 2212 PLIB_USB_EPnRxDisable function 2212 PLIB_USB_EPnRxEnable function 2213 PLIB_USB_EPnRxSelect function 2213 PLIB_USB_EPnStallClear function 2214 PLIB_USB_EPnTxDisable function 2215 PLIB_USB_EPnTxEnable function 2215 PLIB_USB_EPnTxRxSelect function 2216 PLIB_USB_EPnTxSelect function 2216 PLIB_USB_ErrorInterruptDisable function 2222 PLIB_USB_ErrorInterruptEnable function 2223 PLIB_USB_ErrorInterruptFlagAllGet function 2223 PLIB_USB_ErrorInterruptFlagClear function 2224 PLIB_USB_ErrorInterruptFlagGet function 2224 PLIB_USB_ErrorInterruptFlagSet function 2225 PLIB_USB_ErrorInterruptIsEnabled function 2226 PLIB_USB_ExistsActivityPending function 2268 PLIB_USB_ExistsALL_Interrupt function 2269 PLIB_USB_ExistsAutomaticSuspend function 2269 PLIB_USB_ExistsBDTBaseAddress function 2270 PLIB_USB_ExistsBDTFunctions function 2270 PLIB_USB_ExistsBufferFreeze function 2271 PLIB_USB_ExistsDeviceAddress function 2272 PLIB_USB_ExistsEP0LowSpeedConnect function 2272 PLIB_USB_ExistsEP0NAKRetry function 2273 PLIB_USB_ExistsEPnRxEnable function 2273 PLIB_USB_ExistsEPnTxRx function 2274 PLIB_USB_ExistsERR_Interrupt function 2275 PLIB_USB_ExistsERR_InterruptStatus function 2275 PLIB_USB_ExistsEyePattern function 2276 PLIB_USB_ExistsFrameNumber function 2276 PLIB_USB_ExistsGEN_Interrupt function 2277 PLIB_USB_ExistsGEN_InterruptStatus function 2277 PLIB_USB_ExistsHostBusyWithToken function 2278 PLIB_USB_ExistsHostGeneratesReset function 2279 PLIB_USB_ExistsLastDirection function 2279 PLIB_USB_ExistsLastEndpoint function 2280 PLIB_USB_ExistsLastPingPong function 2280 PLIB_USB_ExistsLastTransactionDetails function 2281 PLIB_USB_ExistsLiveJState function 2281 PLIB_USB_ExistsLiveSingleEndedZero function 2282 PLIB_USB_ExistsModuleBusy function 2282 PLIB_USB_ExistsModulePower function 2283 PLIB_USB_ExistsNextTokenSpeed function 2283 PLIB_USB_ExistsOnChipPullup function 2284 PLIB_USB_ExistsOnChipTransceiver function 2284 PLIB_USB_ExistsOpModeSelect function 2285 PLIB_USB_ExistsOTG_ASessionValid function 2286 PLIB_USB_ExistsOTG_BSessionEnd function 2286 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2400 PLIB_USB_ExistsOTG_IDPinState function 2287 PLIB_USB_ExistsOTG_Interrupt function 2287 PLIB_USB_ExistsOTG_InterruptStatus function 2288 PLIB_USB_ExistsOTG_LineState function 2288 PLIB_USB_ExistsOTG_PullUpPullDown function 2289 PLIB_USB_ExistsOTG_SessionValid function 2289 PLIB_USB_ExistsOTG_VbusCharge function 2290 PLIB_USB_ExistsOTG_VbusDischarge function 2290 PLIB_USB_ExistsOTG_VbusPowerOnOff function 2291 PLIB_USB_ExistsPacketTransfer function 2291 PLIB_USB_ExistsPingPongMode function 2292 PLIB_USB_ExistsResumeSignaling function 2293 PLIB_USB_ExistsSleepEntryGuard function 2293 PLIB_USB_ExistsSOFThreshold function 2294 PLIB_USB_ExistsSpeedControl function 2294 PLIB_USB_ExistsStartOfFrames function 2295 PLIB_USB_ExistsStopInIdle function 2295 PLIB_USB_ExistsSuspend function 2296 PLIB_USB_ExistsTokenEP function 2296 PLIB_USB_ExistsTokenPID function 2297 PLIB_USB_ExistsUOEMonitor function 2298 PLIB_USB_ExternalComparatorMode2Pin function 2256 PLIB_USB_ExternalComparatorMode3Pin function 2257 PLIB_USB_EyePatternDisable function 2264 PLIB_USB_EyePatternEnable function 2265 PLIB_USB_FrameNumberGet function 2250 PLIB_USB_FullSpeedDisable function 2178 PLIB_USB_FullSpeedEnable function 2179 PLIB_USB_I2CInterfaceForExtModuleDisable function 2254 PLIB_USB_I2CInterfaceForExtModuleEnable function 2255 PLIB_USB_InterruptDisable function 2217 PLIB_USB_InterruptEnable function 2218 PLIB_USB_InterruptEnableGet function 2218 PLIB_USB_InterruptFlagAllGet function 2219 PLIB_USB_InterruptFlagClear function 2219 PLIB_USB_InterruptFlagGet function 2220 PLIB_USB_InterruptFlagSet function 2221 PLIB_USB_InterruptIsEnabled function 2221 PLIB_USB_IsBusyWithToken function 2229 PLIB_USB_JStateIsActive function 2250 PLIB_USB_LastTransactionDetailsGet function 2226 PLIB_USB_LastTransactionDirectionGet function 2227 PLIB_USB_LastTransactionEndPtGet function 2228 PLIB_USB_LastTransactionPingPongStateGet function 2228 PLIB_USB_ModuleIsBusy function 2265 PLIB_USB_OnChipPullUpDisable function 2180 PLIB_USB_OnChipPullUpEnable function 2180 PLIB_USB_OperatingModeSelect function 2181 PLIB_USB_OTG_BSessionHasEnded function 2237 PLIB_USB_OTG_IDPinStateIsTypeA function 2238 PLIB_USB_OTG_InterruptDisable function 2245 PLIB_USB_OTG_InterruptEnable function 2246 PLIB_USB_OTG_InterruptFlagClear function 2247 PLIB_USB_OTG_InterruptFlagGet function 2247 PLIB_USB_OTG_InterruptFlagSet function 2248 PLIB_USB_OTG_InterruptIsEnabled function 2249 PLIB_USB_OTG_LineStateIsStable function 2239 PLIB_USB_OTG_PullUpPullDownSetup function 2239 PLIB_USB_OTG_SessionValid function 2240 PLIB_USB_OTG_VBusChargeDisable function 2240 PLIB_USB_OTG_VBusChargeEnable function 2241 PLIB_USB_OTG_VBusChargeTo3V function 2242 PLIB_USB_OTG_VBusChargeTo5V function 2242 PLIB_USB_OTG_VBusDischargeDisable function 2243 PLIB_USB_OTG_VBusDischargeEnable function 2243 PLIB_USB_OTG_VBusPowerOff function 2244 PLIB_USB_OTG_VBusPowerOn function 2244 PLIB_USB_OTG_VBusValid function 2245 PLIB_USB_PacketTransferDisable function 2251 PLIB_USB_PacketTransferEnable function 2252 PLIB_USB_PacketTransferIsDisabled function 2253 PLIB_USB_PingPongFreeze function 2266 PLIB_USB_PingPongModeGet function 2181 PLIB_USB_PingPongModeSelect function 2182 PLIB_USB_PingPongReset function 2266 PLIB_USB_PingPongUnfreeze function 2267 PLIB_USB_PWMCounterDisable function 2257 PLIB_USB_PWMCounterEnable function 2258 PLIB_USB_PWMDisable function 2258 PLIB_USB_PWMEnable function 2259 PLIB_USB_PWMPolaritiyActiveLow function 2260 PLIB_USB_PWMPolarityActiveHigh function 2260 PLIB_USB_ResetSignalDisable function 2235 PLIB_USB_ResetSignalEnable function 2235 PLIB_USB_ResumeSignalingDisable function 2236 PLIB_USB_ResumeSignalingEnable function 2237 PLIB_USB_SE0InProgress function 2253 PLIB_USB_SleepGuardDisable function 2182 PLIB_USB_SleepGuardEnable function 2183 PLIB_USB_SOFDisable function 2230 PLIB_USB_SOFEnable function 2230 PLIB_USB_SOFThresholdGet function 2231 PLIB_USB_SOFThresholdSet function 2231 PLIB_USB_StopInIdleDisable function 2184 PLIB_USB_StopInIdleEnable function 2184 PLIB_USB_SuspendDisable function 2185 PLIB_USB_SuspendEnable function 2185 PLIB_USB_TokenEPGet function 2232 PLIB_USB_TokenEPSet function 2233 PLIB_USB_TokenPIDGet function 2233 PLIB_USB_TokenPIDSet function 2234 PLIB_USB_TokenSend function 2267 PLIB_USB_TokenSpeedSelect function 2234 PLIB_USB_TransceiverDisable function 2255 PLIB_USB_TransceiverEnable function 2256 PLIB_USB_UOEMonitorDisable function 2186 PLIB_USB_UOEMonitorEnable function 2186 PLIB_USB_VBoostDisable function 2261 PLIB_USB_VBoostEnable function 2261 PLIB_USB_VBUSComparatorDisable function 2262 PLIB_USB_VBUSComparatorEnable function 2262 PLIB_USB_VBUSPullUpDisable function 2263 PLIB_USB_VBUSPullUpEnable function 2263 plib_usbhs.h 2355 PLIB_USBHS_DeviceAddressGet function 2337 PLIB_USBHS_DeviceAddressSet function 2337 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2401 PLIB_USBHS_DeviceAttach function 2338 PLIB_USBHS_DeviceConnect function 2338 PLIB_USBHS_DeviceDetach function 2338 PLIB_USBHS_DeviceDisconnect function 2339 PLIB_USBHS_DeviceEPFIFOLoad function 2339 PLIB_USBHS_DeviceEPFIFOUnload function 2339 PLIB_USBHS_DeviceRxEndpointConfigure function 2340 PLIB_USBHS_DeviceRxEndpointStallDisable function 2340 PLIB_USBHS_DeviceRxEndpointStallEnable function 2340 PLIB_USBHS_DeviceTxEndpointConfigure function 2340 PLIB_USBHS_DeviceTxEndpointPacketReady function 2340 PLIB_USBHS_DeviceTxEndpointStallDisable function 2341 PLIB_USBHS_DeviceTxEndpointStallEnable function 2341 PLIB_USBHS_DMAErrorGet function 2343 PLIB_USBHS_DMAInterruptDisable function 2331 PLIB_USBHS_DMAInterruptEnable function 2332 PLIB_USBHS_DMAInterruptFlagsGet function 2332 PLIB_USBHS_DMAInterruptGet function 2336 PLIB_USBHS_DMAOperationEnable function 2318 PLIB_USBHS_Endpoint0FIFOFlush function 2319 PLIB_USBHS_Endpoint0SetupPacketLoad function 2320 PLIB_USBHS_Endpoint0SetupPacketUnload function 2320 PLIB_USBHS_EndpointFIFOLoad function 2321 PLIB_USBHS_EndpointFIFOUnload function 2321 PLIB_USBHS_EndpointRxFIFOFlush function 2322 PLIB_USBHS_EndpointRxRequestClear function 2322 PLIB_USBHS_EndpointRxRequestEnable function 2322 PLIB_USBHS_EndpointTxFIFOFlush function 2322 PLIB_USBHS_EP0DataEndSet function 2323 PLIB_USBHS_EP0INHandshakeClear function 2323 PLIB_USBHS_EP0INHandshakeSend function 2323 PLIB_USBHS_EP0INTokenSend function 2323 PLIB_USBHS_EP0OUTHandshakeSend function 2323 PLIB_USBHS_EP0RxPktRdyServiced function 2324 PLIB_USBHS_EP0RxPktRdyServicedDataEnd function 2324 PLIB_USBHS_EP0SentStallClear function 2324 PLIB_USBHS_EP0SetupEndServiced function 2324 PLIB_USBHS_EP0StallDisable function 2324 PLIB_USBHS_EP0StallEnable function 2325 PLIB_USBHS_EP0StatusClear function 2325 PLIB_USBHS_EP0StatusGet function 2325 PLIB_USBHS_EP0TxPktRdy function 2325 PLIB_USBHS_EP0TxPktRdyDataEnd function 2325 PLIB_USBHS_ExistsClockResetControl function 2346 PLIB_USBHS_ExistsEndpointFIFO function 2344 PLIB_USBHS_ExistsEndpointOperations function 2344 PLIB_USBHS_ExistsEP0Status function 2345 PLIB_USBHS_ExistsHighSpeedSupport function 2345 PLIB_USBHS_ExistsInterrupts function 2345 PLIB_USBHS_ExistsModuleControl function 2345 PLIB_USBHS_ExistsRxEPStatus function 2345 PLIB_USBHS_ExistsSoftReset function 2346 PLIB_USBHS_ExistsTxEPStatus function 2346 PLIB_USBHS_ExistsUSBIDControl function 2346 PLIB_USBHS_FullOrHighSpeedIsConnected function 2341 PLIB_USBHS_GenInterruptDisable function 2329 PLIB_USBHS_GenInterruptEnable function 2329 PLIB_USBHS_GenInterruptFlagsGet function 2330 PLIB_USBHS_GetEP0CSRAddress function 2327 PLIB_USBHS_GetEP0FIFOAddress function 2327 PLIB_USBHS_GetReceiveDataCount function 2343 PLIB_USBHS_GlobalInterruptDisable function 2336 PLIB_USBHS_GlobalInterruptEnable function 2336 PLIB_USBHS_HighSpeedDisable function 2314 PLIB_USBHS_HighSpeedEnable function 2314 PLIB_USBHS_HighSpeedIsConnected function 2342 PLIB_USBHS_HostModeIsEnabled function 2342 PLIB_USBHS_HostRxEndpointConfigure function 2326 PLIB_USBHS_HostRxEndpointDataToggleClear function 2341 PLIB_USBHS_HostTxEndpointConfigure function 2326 PLIB_USBHS_HostTxEndpointDataToggleClear function 2341 PLIB_USBHS_InterruptEnableSet function 2331 PLIB_USBHS_IsBDevice function 2319 PLIB_USBHS_LoadEPInIndex function 2327 PLIB_USBHS_ModuleSpeedGet function 2342 PLIB_USBHS_PhyIDMonitoringDisable function 2318 PLIB_USBHS_PhyIDMonitoringEnable function 2318 PLIB_USBHS_ResetDisable function 2315 PLIB_USBHS_ResetEnable function 2315 PLIB_USBHS_ResumeDisable function 2315 PLIB_USBHS_ResumeEnable function 2316 PLIB_USBHS_RxEPINTokenSend function 2326 PLIB_USBHS_RxEPStatusClear function 2326 PLIB_USBHS_RxEPStatusGet function 2326 PLIB_USBHS_RxInterruptDisable function 2334 PLIB_USBHS_RxInterruptEnable function 2335 PLIB_USBHS_RxInterruptFlagsGet function 2335 PLIB_USBHS_SessionDisable function 2316 PLIB_USBHS_SessionEnable function 2316 PLIB_USBHS_SoftResetDisable function 2316 PLIB_USBHS_SoftResetEnable function 2317 PLIB_USBHS_SuspendDisable function 2317 PLIB_USBHS_SuspendEnable function 2317 PLIB_USBHS_TestModeEnter function 2318 PLIB_USBHS_TestModeExit function 2318 PLIB_USBHS_TxEPStatusClear function 2327 PLIB_USBHS_TxEPStatusGet function 2327 PLIB_USBHS_TxInterruptDisable function 2328 PLIB_USBHS_TxInterruptEnable function 2328 PLIB_USBHS_TxInterruptFlagsGet function 2333 PLIB_USBHS_USBIDOverrideDisable function 2319 PLIB_USBHS_USBIDOverrideEnable function 2319 PLIB_USBHS_USBIDOverrideValueSet function 2319 PLIB_USBHS_VbusLevelGet function 2343 PLIB_USBHS_VBUSLevelGet function 2344 plib_wdt.h 2370 PLIB_WDT_Disable function 2362 PLIB_WDT_Enable function 2362 PLIB_WDT_ExistsEnableControl function 2366 PLIB_WDT_ExistsPostscalerValue function 2367 PLIB_WDT_ExistsSleepModePostscalerValue function 2369 PLIB_WDT_ExistsTimerClear function 2368 PLIB_WDT_ExistsWindowEnable function 2368 plib_wdt_help.h 2370 PLIB_WDT_IsEnabled function 2365 PLIB_WDT_PostscalerValueGet function 2365 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2402 PLIB_WDT_SleepModePostscalerValueGet function 2366 PLIB_WDT_TimerClear function 2364 PLIB_WDT_WindowDisable function 2363 PLIB_WDT_WindowEnable function 2363 PMP Peripheral Library 1407 PMP_ACK_MODE enumeration 1485 PMP_ADDRESS_HOLD_LATCH_WAIT_STATES enumeration 1486 PMP_ADDRESS_LATCH enumeration 1486 PMP_ADDRESS_LATCH_WAIT_STATES enumeration 1487 PMP_ADDRESS_PORT enumeration 1487 PMP_ALTERNATE_MASTER_WAIT_STATES enumeration 1488 PMP_CHIP_SELECT enumeration 1489 PMP_CHIPSELECT_FUNCTION enumeration 1489 PMP_DATA_HOLD_STATES enumeration 1490 PMP_DATA_LENGTH enumeration 1490 PMP_DATA_SIZE enumeration 1491 PMP_DATA_WAIT_STATES enumeration 1491 PMP_INCREMENT_MODE enumeration 1491 PMP_INPUT_BUFFER_TYPE enumeration 1492 PMP_INTERRUPT_MODE enumeration 1492 PMP_MASTER_MODE enumeration 1493 PMP_MODULE_ID enumeration 1493 PMP_MUX_MODE enumeration 1494 PMP_OPERATION_MODE enumeration 1494 PMP_PMBE_PORT enumeration 1495 PMP_POLARITY_LEVEL enumeration 1495 PMP_STROBE_WAIT_STATES enumeration 1496 Porting Procedure 7 Ports Change Notification 1555 Ports Control 1554 Ports Function Remap 1555 Ports Peripheral Library 1551 PORTS_AN_PIN enumeration 1632 PORTS_ANALOG_PIN enumeration 1615 PORTS_BIT_POS enumeration 1617 PORTS_CHANGE_NOTICE_EDGE enumeration 1634 PORTS_CHANGE_NOTICE_METHOD enumeration 1635 PORTS_CHANGE_NOTICE_PIN enumeration 1618 PORTS_CHANNEL enumeration 1619 PORTS_CN_PIN enumeration 1633 PORTS_DATA_MASK type 1620 PORTS_DATA_TYPE type 1620 PORTS_MODULE_ID enumeration 1621 PORTS_PIN_MODE enumeration 1621 PORTS_PIN_SLEW_RATE enumeration 1635 PORTS_REMAP_FUNCTION enumeration 1621 PORTS_REMAP_INPUT_FUNCTION enumeration 1624 PORTS_REMAP_INPUT_PIN enumeration 1625 PORTS_REMAP_OUTPUT_FUNCTION enumeration 1626 PORTS_REMAP_OUTPUT_PIN enumeration 1627 PORTS_REMAP_PIN enumeration 1628 Power Peripheral Library 1639 POWER_MODULE enumeration 1680 POWER_MODULE_ID enumeration 1682 Power-Saving Modes 29, 402, 1826 Prefetch Cache Peripheral Library 1501 Prefetch Control Operations 1505 Prefetch Status Operations 1505 PWM Mode with Enabled Faults 1273 R Reading a Capture Value 1131 Receive 778 Receive Filtering Overview 771 Receiving a CAN Message 308 Reduced Media Independent Interface (RMII) 770 Reset Peripheral Library 1687 RESET_CONFIG_REG_READ_ERROR enumeration 1700 RESET_MODULE_ID enumeration 1699 RESET_NMI_COUNT_TYPE type 1701 RESET_NMI_REASON enumeration 1701 RESET_REASON enumeration 1699 RTCC Mode Operations 1706 RTCC Peripheral Library 1703 RTCC_ALARM_MASK_CONFIGURATION enumeration 1758 RTCC_MODULE_ID enumeration 1759 RTCC_VALUE_REGISTER_POINTER enumeration 1759 S Sample Code 772 SB_MODULE_ID enumeration 1802 Setting Bus Speed 305 Single Compare Set High Mode 1271 Single Compare Toggle Mode 1271 Slave Mode 1825 Source/Destination/Peripheral Address Management 530 Source/Destination/Peripheral Data Management 531 Special Considerations 1556 Special Function Modules (CRC) 532 SPI Error Handling 1827 SPI Master Mode and Frame Master Mode 1816 SPI Master Mode and Frame Slave Mode 1817 SPI Master Mode Clock Frequency 1827 SPI Peripheral Library 1805 SPI Receive-only Operation 1827 SPI Slave Mode and Frame Master Mode 1818, 1820 SPI_AUDIO_COMMUNICATION_WIDTH enumeration 1887 SPI_AUDIO_ERROR enumeration 1887 SPI_AUDIO_PROTOCOL enumeration 1888 SPI_AUDIO_TRANSMIT_MODE enumeration 1888 SPI_BAUD_RATE_CLOCK enumeration 1888 SPI_CLOCK_POLARITY enumeration 1889 SPI_COMMUNICATION_WIDTH enumeration 1889 SPI_DATA_TYPE type 1890 SPI_ERROR_INTERRUPT enumeration 1890 SPI_FIFO_INTERRUPT enumeration 1890 SPI_FIFO_TYPE enumeration 1891 SPI_FRAME_PULSE_DIRECTION enumeration 1891 SPI_FRAME_PULSE_EDGE enumeration 1892 SPI_FRAME_PULSE_POLARITY enumeration 1892 SPI_FRAME_PULSE_WIDTH enumeration 1892 SPI_FRAME_SYNC_PULSE enumeration 1893 SPI_INPUT_SAMPLING_PHASE enumeration 1893 SPI_MODULE_ID enumeration 1893 SPI_OUTPUT_DATA_PHASE enumeration 1894 SPI_PIN enumeration 1894 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2403 SQI Peripheral Library 1899 SQI_ADDR_BYTES enumeration 2022 SQI_BD_CTRL_WORD enumeration 2023 SQI_BD_STATE enumeration 2024 SQI_CLK_DIV enumeration 2024 SQI_CS_NUM enumeration 2025 SQI_CS_OEN enumeration 2025 SQI_DATA_FORMAT enumeration 2026 SQI_DATA_MODE enumeration 2026 SQI_DATA_OEN enumeration 2026 SQI_DATA_TYPE type 2027 SQI_DUMMY_BYTES enumeration 2027 SQI_INTERRUPTS enumeration 2028 SQI_LANE_MODE enumeration 2028 SQI_MODE_BYTES enumeration 2029 SQI_MODULE_ID enumeration 2029 SQI_XFER_CMD enumeration 2030 SQI_XFER_MODE enumeration 2030 Standard ID Message Format 303 Standard Master Mode 1809 Standard Slave Mode 1811 Standard SPI Mode 1809 State Machine 1206, 1412, 1705, 1808, 2076 Status (including Channel) 533 Support for Legacy "Ethernet Controller Library" 778 Synchronous External Clock Counter 2040 Synchronous Internal Clock Counter 2039 Synchronous Master Mode 2082 Synchronous Slave Mode 2083 System Bus Peripheral Library 1763 T Target Initialization 1765 Timer Peripheral Library 2036 TMR_CLOCK_SOURCE enumeration 2070 TMR_MODULE_ID enumeration 2071 TMR_PRESCALE enumeration 2071 Transfer/Abort (Asynchronous) Trigger Management 525 Transfer/Abort (Synchronous) 524 Transmit 777 Transmitting a CAN Message 307 U USART Peripheral Library 2074 USART_HANDSHAKE_MODE enumeration 2154 USART_LINECONTROL_MODE enumeration 2154 USART_MODULE_ID enumeration 2155 USART_OPERATION_MODE enumeration 2156 USART_RECEIVE_INTR_MODE enumeration 2156 USART_TRANSMIT_INTR_MODE enumeration 2156 USB Buffers and the Buffer Descriptor Table (BDT) 2165 USB Peripheral Library 2161 USB Setup Example 2167 USB_BUFFER_DATA01 enumeration 2298 USB_BUFFER_DIRECTION enumeration 2299 USB_BUFFER_PING_PONG enumeration 2299 USB_BUFFER_SCHEDULE_DATA01 enumeration 2299 USB_EP_TXRX enumeration 2300 USB_MAX_EP_NUMBER macro 2304 USB_OPMODES enumeration 2300 USB_OTG_INTERRUPTS enumeration 2301 USB_OTG_PULL_UP_PULL_DOWN enumeration 2301 USB_PID enumeration 2302 USB_PING_PONG_MODE enumeration 2302 USB_PING_PONG_STATE enumeration 2303 USB_TOKEN_SPEED enumeration 2303 USBHS Peripheral Library 2310 USBHS_CONFIGURATION enumeration 2346 USBHS_DATA01 enumeration 2347 USBHS_DMA_ASSERT_TIMING enumeration 2347 USBHS_DMA_BURST_MODE enumeration 2348 USBHS_DMA_INTERRUPT enumeration 2348 USBHS_DMA_REQUEST_MODE enumeration 2349 USBHS_DMA_TRANSFER_MODE enumeration 2349 USBHS_DYN_FIFO_PACKET_BUFFERING enumeration 2349 USBHS_DYN_FIFO_SIZE enumeration 2350 USBHS_ENDPOINT_DIRECTION enumeration 2350 USBHS_LPM_INTERRUPT enumeration 2350 USBHS_LPM_LINK_STATE enumeration 2351 USBHS_LPM_MODE enumeration 2351 USBHS_MAX_DMA_CHANNEL_NUMBER macro 2354 USBHS_MAX_EP_NUMBER macro 2355 USBHS_OPMODES enumeration 2352 USBHS_PKTS_PER_MICROFRAME enumeration 2352 USBHS_SPEED enumeration 2353 USBHS_TEST_SPEED enumeration 2353 USBHS_TRANSACTION_TYPE enumeration 2354 USBHS_TXRX_FIFO_STATE enumeration 2354 Using the Library 20, 86, 218, 266, 300, 399, 438, 470, 486, 522, 653, 722, 765, 922, 1025, 1129, 1155, 1204, 1269, 1297, 1407, 1501, 1551, 1639, 1687, 1703, 1763, 1805, 1899, 2036, 2074, 2162, 2310, 2359 ADC Peripheral Library 20 ADCHS Peripheral Library 86 ADCP Peripheral Library 218 BMX Peripheral Library 266 CAN Peripheral Library 300, 399 CTMU Peripheral Library 438 Deadman Timer Peripheral Library 470 Device Control Peripheral Library 486 DMA Peripheral Library 522 Dual Data Rate (DDR) SDRAM Peripheral Library 653 EBI Peripheral Library 722 Ethernet Peripheral Library 765 GLCD Controller Peripheral Library 922 I2C Peripheral Library 1025 Input Capture Peripheral Library 1129 Interrupt Peripheral Library 1155 NVM Peripheral Library 1204 Oscillator Peripheral Library 1297 Output Compare Peripheral Library 1269 PMP Peripheral Library 1407 Ports Peripheral Library 1551 Power Peripheral Library 1639 Prefetch Cache Peripheral Library 1501 Reset Peripheral Library 1687 RTCC Peripheral Library 1703 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2404 SPI Peripheral Library 1805 SQI Peripheral Library 1899 System Bus Peripheral Library 1763 Timer Peripheral Library 2036 USART Peripheral Library 2074 USB Peripheral Library 2162 USBHS Peripheral Library 2310 Watchdog Timer Peripheral Library 2359 W Wait States Initialization 1410 Watchdog Timer Peripheral Library 2359 WDT_MODULE_ID enumeration 2369 X XIP Mode 1902 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v1.11 2405

Quick Guide to Microchip Development Tools Development Tools www.microchip.com/tools 2 www.microchip.com/tools Introduction MPLAB® X IDE, Atmel Studio and Software Tools Microchip is proud to offer development tools for AVR® and SAM MCUs in addition to our classic development tools for PIC® MCUs and dsPIC® DSCs. Together, Microchip offers the strongest development tool chains for the industry’s most popular products. Microchip produces approximately 2,000 development tools, of which only a selection are featured in this document. For the full listing of Microchip’s development tools, please visit the online Development Tools Selector (DTS) at www.microchip.com/dts or visit our application sites on www.microchip.com. Development Tool Selector Microchip’s development tools selector is an online/offline application that allows you to view development tools through a Graphical User Interface (GUI) with filter and search capabilities to easily find development tools associated with Microchip products. Just enter a development tool or Microchip device in the search box and DTS quickly displays all related tools and devices. Updated after every MPLAB X IDE release, DTS is available online and offline at: www.microchip.com/dts. FREE MPLAB® X IDE MPLAB Xpress IDE (cloud-based) Atmel Studio MPLAB XC C Compliers MPLAB Code Configurator Microchip Libraries for Applications (MLA) MPLAB XC PRO C Compiler Licenses MPLAB Harmony Advanced Software Framework Atmel START AVR GCC C Compilers ARM® GCC C Compilers IAR Workbench IAR Workbench Keil MDK 8-bit PIC® MCUs 32-bit PIC MCUs AVR® MCUs SAM MCUs 16-bit PIC MCUs and dsPIC® DSCs Purchase Quick Guide to Microchip Development Tools 3 MPLAB X IDE MPLAB X IDE MPLAB X IDE is Microchip’s free integrated development environment for PIC MCUs and dsPIC DSCs. Incorporating a powerful and highly functional set of features, it allows you to easily develop applications. Based on the NetBeans IDE from Oracle, MPLAB X IDE and runs on Windows®, Linux® and Mac OS X®. Its unified GUI helps to integrate software and hardware development tools from Microchip and third-party sources to give you high-performance application development and extensive debugging capabilities. The flexible and customizable interface allows you to have multiple debug tools connected to your computer at the same time. You can select any tool you desire for a specific project or configuration within a project. With complete project management, visual call graphs, a configurable watch window and a feature-rich editor that includes code-completion and hyperlink navigation, MPLAB X IDE is fully equipped to meet the needs of experienced users while remaining flexible and user-friendly for even those who are new to the IDE. MPLAB Xpress Cloud-based IDE MPLAB Xpress Cloud-Based IDE is an online development environment that contains the most popular features of our awardwinning MPLAB X IDE. This simplified and distilled application is a faithful reproduction of our desktop-based program, which allows you to easily transition between the two environments. MPLAB Xpress is a perfect starting point for new users of PIC MCUs - no downloads, no machine configuration and no waiting to get started on your system development. MPLAB Xpress incorporates the latest version of MPLAB Code Configurator, which enables users to automatically generate initialization and application C code for 8- and 16-bit PIC MCUs and dsPIC DSCs using a graphical interface and pin map. With massive amounts of storage available, you can store your current projects in the Cloud. The Community feature allows you to share your ideas with others and gain inspiration from the shared code repository. Best of all, MPLAB Xpress cloud-based IDE is free and can be accessed from any Internet-connected PC or Mac, anywhere in the world. Compatible Hardware • MPLAB Xpress evaluation boards • Curiosity development boards • Explorer 16/32 Development Board • PICkitTM 3 Programmer/Debugger 4 www.microchip.com/tools MPLAB X IDE Plug-Ins MPLAB X IDE Plug-Ins MPLAB Code Configurator MPLAB Code Configurator (MCC) is a free, graphical programming environment that generates seamless, easy-to-understand C code to be inserted into your project. Using an intuitive interface, it enables and configures a rich set of peripherals and functions specific to your application. MPLAB Code Configurator supports 8-bit, 16-bit and 32-bit PIC microcontrollers. MCC is incorporated into both the down-loadable MPLAB X IDE and the cloud-based MPLAB Xpress IDE. • Free graphical programming environment • Intuitive interface for quick start development • Automated configuration of peripherals and functions • Minimized reliance upon product datasheet • Reduces overall design effort and time • From novice to expert, accelerates generation of production ready code • MPLAB Harmony Configurator (MHC) tool MPLAB Harmony Configurator The MPLAB Harmony Configurator (MHC) is a time-saving hardware configuration utility for MPLAB Harmony, Microchip's award winning software framework. You can use MHC to get visual understanding and control of the configuration of their target device and application. MHC is a fully integrated tool within MPLAB X IDE. • Generates all hardware configuration code • Generates all middleware framework related code • Automatically updates the active MPLAB X IDE project with all required files MPLAB Harmony Graphics Composer MPLAB Harmony Graphics Composer (MHGC) is Microchips industry-leading GUI design tool for PIC32 microcontrollers. As a fully-integrated component of MHC, MHGC will accelerate your application's front end design without leaving the MPLAB X IDE. Integrated Programming Environment The Integrated Programming Environment (IPE) is a software application that provides a simple interface to quickly access key programmer features. IPE provides a secure programming environment for production programming. It is bundled in the MPLAB X IDE installation package. motorBench™ Development Suite The motorBench Development Suite identifies the electrical and mechanical parameters of a motor and then automatically tunes the current and speed control loops. It then generates complete dsPIC33 motor control code into an MPLAB X IDE project. Version 1.x works with the dsPICDEM™ LMCLV-2 Development Board (DM33021-2) and one permanent magnet synchronous motor (AC300022). C: 100 M: 10 Y: 35 K: 15 PMS: 321C C: 0 M: 40 Y: 100 K: 10 PMS: 7563C Quick Guide to Microchip Development Tools 5 Atmel Studio Atmel Studio 7 IDP Atmel Studio 7 is the Integrated Development Platform (IDP) for developing and debugging all AVR and SAM microcontroller applications. The Atmel Studio 7 IDP gives you a seamless and easy-to-use environment to write, build and debug your applications written in C/C++ or assembly code. It also connects seamlessly to the debuggers, programmers and development kits that support AVR and SAM devices. AVR/ARM GNU compiler, assembler and linker are included, IDE and compiler solutions are also available from Keil and IAR. Additionally, Studio 7 includes Gallery, an online app store that allows you to extend your development environment with plug-ins developed by Microchip as well as third-party tool and embedded software vendors. Studio 7 can also seamlessly import your Arduino® sketches as C++ projects, providing a simple transition path from makerspace to marketplace. Data Visualizer The Data Visualizer is a program to process and visualize data. The Data Visualizer is capable of receiving data from various sources such as the Embedded Debugger Data Gateway Interface (DGI) and COM ports. Track your applications run-time using a terminal graph or oscilloscope, or analyze the power consumption of your application through correlation of code execution and power consumption, when used together with a supported probe or board. Having full control of your code’s run-time behavior has never been easier. MPLAB Harmony Software Framework MPLAB Harmony Software Framework for PIC32 MCUs MPLAB Harmony is a flexible, abstracted, fully integrated firmware development environment for PIC32 microcontrollers. It enables robust framework development of interoperable RTOS-friendly libraries with quick and extensive Microchip support for third-party software integration. MPLAB Harmony includes a set of peripheral libraries, drivers and system services that are readily accessible for application development. It features the MPLAB Harmony Configurator plug-in that provides a graphical way to select and configure all MPLAB Harmony components, including middleware, system services and peripherals, with ease. Get the latest updates at www.microchip.com/harmony. MPLAB Harmony 6 www.microchip.com/tools Software Tools Atmel START Atmel START is an innovative online tool for intuitive, graphical configuration of embedded software projects. It lets you select and configure software components, drivers and middleware, as well as complete example projects, specifically tailored to the needs of your application. The configuration stage lets you review dependencies between software components, conflicts and hardware constraints. In the case of a conflict, Atmel START will automatically suggest solutions that fit your specific setup. With graphical pin-mux and clock configuration, you can easily match your software and drivers with your own hardware layout. The tool also provides automated assistance for retargeting projects and applications for different devices. Getting that sample code to run on your board has never been easier. Since Atmel START is an online tool, no installation is required. When you are finished with your configuration, you can download it for use together with your preferred Integrated Development Environment (IDE), including Atmel Studio, Keil or IAR and continue development. If you later need to change the configuration you can load it in Atmel START, reconfigure and continue where you left off. Atmel START is based on the latest generation of the Atmel Software Framework, ASFv4. The driver layer in ASFv4 has been rearchitected for better performance and reduced code size. Care has been taken to make sure that code generated by Atmel START is readable, as well as easy to navigate and extend. Please refer to the user guide to learn more about what’s new in ASFv4. You can download and securely purchase both Microchip and third-party compilers, advanced debugging tools, real-time operating systems, communication systems and other extensions and plug-ins straight from the Atmel Studio 7 development platform. MPLAB MindiTM Analog Simulator MPLAB Mindi Analog Simulator reduces circuit design time and design risk by simulating analog circuits prior to hardware prototyping. The simulation tool uses a SIMetrix/SIMPLIS simulation environment, with options to use SPICE or piecewise linear modeling, that can cover a very wide set of possible simulation needs. This capable simulation interface is paired with proprietary model files from Microchip, to model specific Microchip analog components in addition to generic circuit devices. Finally, this simulation tool installs and runs locally, on the your own PC. Once downloaded, no internet connection is required, and the simulation run time is not dependent on a remotely located server. The result is fast, accurate analog circuit simulations. Benefits include: • Run the simulation tool directly on your own PC; once installed no internet connection is required • Choose from SPICE or piecewise linear SIMPLIS models, for accurate results in fast simulations • Model a wide variety of analog systems using standard or Microchip proprietary component models • Generate time or frequency domain responses for open and closed loop systems • Perform AC, DC and transient analysis • Use sweep modes to identify circuit sensitivities to device behaviors, load variations, or tolerances • Validate system response, control and stability • Identify problems before building hardware Quick Guide to Microchip Development Tools 7 MPLAB XC Compilers Microchip’s line of award-winning MPLAB XC Compilers provides a comprehensive solution for your project’s software development and is offered in free, unrestricted-use downloads. Finding the right compiler to support your device is simple: • MPLAB XC8 supports all 8-bit PIC MCUs • MPLAB XC16 supports all 16-bit PIC MCUs and dsPIC DSCs • MPLAB XC32/32++ supports all 32-bit PIC MCUs Features When combined with Microchip’s award-winning, free integrated development environment, MPLAB X IDE, the full graphical front end provides: • Editing errors and breakpoints that match corresponding lines in the source code • Single stepping through C and C++ source code to inspect variables and structures at critical points • Data structures with defined data types, including floating point, display in watch windows MPLAB XC Compiler Licenses Need to optimize your code size reduction or get better speed from your project’s software? PRO licenses are available to unlock the full potential of the MPLAB XC compiler’s advanced-level optimizations, maximum code size reductions and best performance. The MPLAB XC Compiler contains a free, 60-day trial of a PRO license for evaluation when activated. MPLAB XC Compiler licenses come in a wide variety of licensing options and most come with one year of High Priority Access (HPA). HPA must be renewed at the end of twelve months. HPA includes: • Unlimited advanced optimizations on new compiler versions • New architecture support • Bug fixes • Priority technical support • Free shipping on all development tool orders from www.microchipDIRECT.com License Type Installs On # of Activations # of Users Wait Time Between Users HPA Included Workstation License Workstation 3 1 None Yes Subscription License Workstation 1 1 None No Site License Network 1 Varies by Seat None Yes Network Server License Network 1 Unlimited One Hour Yes Virtual Machine* Network 1 N/A N/A No Dongle License Dongle N/A Unlimited None No *This is license must be used in addition to a network server or site license to enable the license to work in a virtual machine environment. MPLAB XC Compilers 8 www.microchip.com/tools Additional Resources Embedded Code Source The Embedded Code Source is a site that provides one spot where engineers browse and download software/firmware code examples, tools and utilities for your PIC MCU projects. If you are a developer, you get a chance to take advantage of a free ecosystem and framework to deliver code examples that can potentially attract customers to your services. In addition, we now offer the ability for third-party developers to sell their code, via www.microchipDIRECT.com. Gallery The Atmel Gallery app store provides development tools and embedded software for MCU-based application design. When you encounter a need for a tool in the middle of your development process or are seeking some basic source code, you won’t have to leave your environment to search for your solution. From Gallery, you can also download a plug-in that will give you direct access to Spaces, a collaborative workspace. Microchip Library of Applications The Microchip Libraries for Applications (MLA) enhances interoperability for applications that require more than one library for 8-16-bit PIC MCUs. Available software libraries include USB, graphics, file I/O, crypto, Smart Card, MiWi™ protocol, TCP/IP Wi-Fi® and smartphone. The package includes source code, drivers, demos, documentation and utilities. All projects are prebuilt for MPLAB X IDE and respective XC compiler. ClockWorks® Configurator ClockWorks Configurator is an online tool enabling you to create designs/configurations and request data sheets, part numbers and samples for those designs. The user interface is graphical and easy to use, and dynamic data sheets and block diagrams are generated instantly for all of your designs. At each phase email notifications are sent out to all involved parties to keep you up-to-date with the status of your request. ClockWorks Configurator has different views and level of accessibilities based on the user roles. Third-Party Tools Microchip’s third-party tools and providers offer a diverse range of embedded-design development boards and software that complement the development tools we develop in house. Over 300 Microchip third-party recognized providers and premier partners provide development tools for almost every embedded application. Premier third-party partners in particular areas are certified by our engineers to be the best in the industry providing not only a large array of software and hardware tools but superior support for the products as well. Academic Program Microchip’s Academic Program demonstrates our on-going commitment to education by offering unique benefits and resources for educators, researchers and students worldwide. We are a resource for Academia to help integrate Microchip products and technologies into the classroom. Benefits include: • Free access to labs, curriculum and course materials • Silicon donations to help seed labs • One-on-one consultations • Tool samples for professors to evaluate • 25% academic discount on many Microchip and third-party tools • Free training on Microchip products and technologies • Discounts when attending Microchip’s MASTERs Conference Brought to you by Quick Guide to Microchip Development Tools 9 In-Circuit Emulators and Debuggers Microchip offers a range of programmers, emulators, debugger/programmers and extensions to support all device architectures and more are on the way. All solutions are USB-powered and fully integrated into their respective IDE. MPLAB ICD 4 offers debugging and hardware features sufficient for most users. PICkit 3 Debugger/Programmer, Atmel ICE, SAM-ICE Emulator and Power Debugger are economical choices for basic debugging functions. MPLAB REAL ICETM In-Circuit Emulator offers advanced features like data capture, logic trigger and higher-speed debugging with up to 10 foot cable length. Such features are only available from other suppliers on expensive, high-end emulators. MPLAB REAL ICE In-Circuit Emulator and MPLAB ICD 4 can be used as programmers in a production environment. MPLAB ICD 4 In-Circuit Debugger (DV164045) The MPLAB ICD 4 In-Circuit Debugger/Programmer is Microchip’s fastest, cost-effective debugging and programming tool for PIC MCUs and dsPIC DSCs. This speed is provided by a 300 MHz, 32-bit MCU with 2 MB of RAM and a high-speed FPGA to yield faster communications, downloads and debugging. It debugs and programs with the powerful, yet easy-to-use graphical user interface of MPLAB X IDE. The MPLAB ICD 4 is connected to your PC using a high-speed USB 2.0 interface and is connected to the target with a debugging connector which is also compatible with the MPLAB ICD 3 or MPLAB REAL ICE In-Circuit Emulator systems. The MPLAB ICD 4 also works with JTAG interfaces. PICkit 3 In-Circuit Debugger (PG164130) The PICkit 3 In-Circuit Debugger allows debugging and programming of PIC MCUs and dsPIC DSCs at an affordable price point using the powerful graphical user interface of MPLAB X IDE. Power Debugger (ATPOWERDEBUGGER) Power Debugger is a powerful development tool for debugging and programming AVR microcontrollers using UPDI, JTAG, PDI, debugWIRE, aWire, TPI or SPI target interfaces and ARM Cortex-M based SAM microcontrollers using JTAG or SWD target interfaces. The Power Debugger streams power measurements and application debug data to Data Visualizer for real-time analysis. MPLAB REAL ICE In-Circuit Emulator (DV244005) MPLAB REAL ICE In-Circuit Emulator is Microchip’s high-speed emulator for PIC MCUs and dsPIC DSCs. It debugs and programs these devices with the easy-to-use but powerful graphical user interface of the MPLAB X IDE. Atmel ICE (ATATMEL-ICE) Atmel ICE is a powerful development tool for debugging and programming ARM® Cortex®-M based SAM and AVR microcontrollers with on-chip debug capability. Atmel ICE supports: • Programming and on-chip debugging of all 32-bit AVR MCUs on both JTAG and aWire interfaces • Programming and on-chip debugging of all AVR XMEGA devices on both JTAG and PDI 2-wire interfaces • JTAG and SPI programming and debugging of all 8-bit AVR MCUs with OCD support on either JTAG or debugWIRE interfaces • Programming and debugging of all SAM ARM Cortex-M based MCUs on both SWD and JTAG interfaces • Programming of all 8-bit tinyAVR® MCUs with support for the TPI interface In-Circuit Emulators and Debuggers 10 www.microchip.com/tools In-Circuit Emulators and Debuggers SAM ICE (AT91SAM-ICE) SAM ICE is a JTAG emulator designed for SAMA5, SAM3, SAM4, SAM7 and SAM9 ARM core-based MCUs and MPUs, including Thumb mode. It supports download speeds up to 720 KBps and maximum JTAG speeds up to 12 MHz. It also supports Serial Wire Debug (SWD) and Serial Wire Viewer (SWV) from SAM ICE hardware V6. In-Circuit Emulators and Debuggers Product Supported IDE Supported USB 2.0 Speed USB Driver USB Powered Programmable Vpp Power to Target Programmable Vdd Vdd Drain from Target Over Voltage/Current Protection Breakpoints Software Breakpoints Memory for target image storage Serialized USB Trace, Native Trace, Other (SPI, PORT, Inst) Data Capture Logic/Probe Triggers High-Speed Performance PAK (LVDS) Production Programmer Power Measurement/Profiling Part Number MSRP Feature PICkit™ 3 PIC® MCU, dsPIC® DSC MPLAB X IDE Full HID Yes Yes Yes Yes 20 mA Yes, SW Simple Yes 512 KB Yes No No No No No No No PG164130 $47.95 Atmel ICE AVR® MCU, SAM MCU Studio* High, Full HID + Microchip Yes No No No < 1 mA Yes, HW Target Dependent Yes No Yes Coresight, SWO SPI, UART No No No No No ATATMEL-ICE $130.00 SAM ICE SAM MCU, SAM MPU Studio Full Segger Yes No No No < 1 mA Yes Target Dependent Yes No Yes Coresight, SWO No Target Dependent No No No No AT91SAM-ICE $150.00 Power Debugger AVR MCU, SAM MCU Studio High, Full HID + Microchip Yes No No No < 1 mA Yes, HW Target Dependent Yes No Yes Coresight, SWO SPI, UART, I 2C, USART No 4 Channels No No 2 Channels ATPOWERDEBUGGER $190.00 MPLAB REAL ICE™ In-Circuit Emulator PIC MCU, dsPIC DSC MPLAB X IDE High, Full Microchip Yes Yes No Yes w/Power Monitor Board < 1 mA Yes, HW Complex Yes No Yes Yes Yes Yes Yes Yes Yes No DV244005 $499.98 *MPLAB X IDE support for Atmel ICE is planned for late 2017 **Full device support in progress. Please review documentation for complete list of supported devices. In-Circuit Emulators and Debuggers MPLAB® ICD 4 PIC MCU, dsPIC DSC, AVR MCU, PIC32C** MPLAB X IDE High, Full Microchip Yes Yes Yes Yes < 1 mA Yes, HW Complex Yes No Yes No No No No No Yes No DV164045 $249.99 Quick Guide to Microchip Development Tools 11 Curiosity Development Boards Internet of Things Ready Have an Internet of Things (IoT) design idea? Curiosity development boards can make it real. A full complement of accessory boards is available via the MikroElectronika MikroBUS™. Out of the box, the development board offers several options for user interface. Curiosity Development Board (DM164137) • Support 8-, 14- and 20-pin 8-bit PIC MCUs with lowvoltage programming capability Curiosity High Pin Count (HPC) Development Board (DM164136) • Supports 28- or 40-pin 8-bit PIC MCUs with low-voltage programming capability PIC24F Curiosity Development Board (DM240004) • PIC24FJ128GA204 equipped with integrated hardware cryptographic engine PIC32MM USB Curiosity Development Board (DM320107) • PIC32MM0256GPM064 featuring USB 2.0 OTG and DMA • Ideal prototyping board for USB, high resolution audio, Bluetooth Audio, BTLE and other general-purpose applications Curiosity PIC32MZEF Development Board (DM320104) • PIC32MZ2048EFM with integrated FPU, crypto accelerator • Supports PIC32 Audio Codec Daughter Card - AK4642EN (AC320100) Curiosity PIC32MX470 Development Board (DM320103) • PIC32MX470512H with full-speed USB • Excellent development board for audio, USB and Bluetooth applications PIC32MM Curiosity Development Board (DM320101) • PIC32MM0064GPL036 featuring eXtreme Low Power (XLP) technology • Ideal for developing battery-operated applications, portable medical monitoring devices and IoT sensor nodes Curiosity Development Boards 12 www.microchip.com/tools Xplained Boards Xplained Boards Xplained is a fast prototyping and evaluation platform for AVR and ARM-based MCUs. These low-cost, easy-to-use evaluation kits are ideal for demonstrating the features and capabilities of MCUs and MPUs and can be customized with a wide range of expansion boards. Development is easy with a rich selection of example projects and code drivers provided in the Advanced Software Framework (ASF), as well as support in Atmel Studio and from third-party IDEs. Choose from three types of Xplained kits: A few examples of Xplained development boards are shown, many more available on www.microchip.com. ATtiny817 Xplained Pro (ATTINY817-XPRO) The ATtiny817 Xplained Pro Evaluation Kit is a hardware platform for evaluating the latest tinyAVR microcontrollers. The evaluation kit comes with a fully integrated debugger that provides seamless integration with Atmel Studio. ATmega328PB Xplained Mini (ATMEGA328PB-XMINI) The ATmega328PB Xplained Mini Evalutation Kit is a hardware platform for evaluating the ATmega328PB MCU. The evaluation kit comes with a fully integrated debugger that provides seamless integration with Atmel Studio. ATtiny104 Xplained Nano Evaluation Kit (ATTINY104-XNANO) The ATtiny104 Xplained Nano Evaluation Kit is a hardware platform for evaluating ATtiny102/ATtiny104 microcontrollers. Supported by Atmel Studio free integrated development platform, the kit provides easy access to all device I/O, one button and one LED. The Xplained Nano Evaluation Kit includes an on-board programmer. ATtiny817 Xplained Mini (ATTINY817-XMINI) The ATtiny817 Xplained Mini Evaluation Kit is a hardware platform for evaluating ATtiny817, ATtiny816, ATtiny814 and ATtiny417 microcontrollers. The evaluation kit comes with a fully integrated debugger that provides seamless integration with Atmel Studio. Quick Guide to Microchip Development Tools 13 Expansion Boards for Xplained Pro Expansion boards are available for Xplained Pro development board to easily add radio, touch, display and many other functions to the development platform. These expansions are tightly integrated into the Studio 7 development environment and software libraries are available in Microchip’s Advanced Software Framework (ASF). ATWINC1500-XSTK Xplained Pro Starter Kit (ATWINC1500-XSTK) The ATWINC1500-XSTK Xplained Pro Starter Kit is a hardware platform for evaluating the ATWINC1500 low-cost, low-power 802.11 b/g/n Wi-Fi network controller module. BNO055 Xplained Pro Extension Kit (ATBNO055-XPRO) BNO055 Xplained Pro is an extension with the Bosch BNO055 intelligent 9-axis absolute orientation sensor and a RGB LED. It connects to the extension headers of any Xplained Pro Evaluation Kit. Ethernet1 Xplained Pro Extension Kit (ATETHERNET1-XPRO) Ethernet1 Xplained Pro is an extension board in the Xplained Pro Evaluation Platform. The board enables you to experiment with Ethernet network connectivity applications. I/O1 Xplained Pro Extension Kit (ATIO1-XPRO) I/O1 Xplained Pro provides a light sensor, temperature sensor and microSD card. It connects to the extension headers of any Xplained Pro evaluation kit. OLED1 Xplained Pro Extension Kit (ATOLED1-XPRO) OLED1 Xplained Pro is an extension kit with a 128 x 32 OLED display, three LEDs and three push buttons. It connects to the extension headers of any Xplained Pro evaluation kit. PROTO1 Xplained Pro Extension Kit (ATPROTO1-XPRO) PROTO1 Xplained Pro provides easy prototyping on the Xplained Pro platform. It connects to the extension headers of any Xplained Pro evaluation kit and can be used as a gateway to other Xplained Pro extension boards with its own Xplained Pro extension header. RS485 Xplained Pro Extension Evaluation Kit (ATRS485-XPRO) The RS485 Xplained Pro extension evaluation kit is ideal for evaluation and prototyping applications involving RS485/422 features of the SAMC21 Cortex-M0+ processor-based microcontrollers. mikroBUS Xplained Pro (ATMBUSADAPTER-XPRO) The mikroBUS Xplained Pro is an extension Board in the Xplained Pro evaluation platform. It is designed to demonstrate mikroBUS click boardsTM with Xplained Pro MCU boards. Xplained Boards 14 www.microchip.com/tools Starter Kits Starter Kits Starter kits are complete, affordable, turnkey solutions consisting of the hardware and software sufficient for exploring specific applications or the features of the device family they represent. Most kits include an on-board or separate debugger and tutorials. To get started, simply install and start MPLAB X IDE, connect the hardware and step through the easy-to-follow tutorials. MPLAB Xpress Evaluation Boards The centerpiece of the MPLAB Xpress evaluation board is the PIC16 MCU; an 8-bit device with the unique combination of lowpower consumption, performance to handle almost any application task and on-chip peripherals that enable you to control your system with a minimal amount of code. Peripherals can be set up graphically using the MPLAB Code Configurator plug-in, saving you weeks of development time. It features MikroElektronika Click expansion, drag-and-drop programming and seamless integration into MPLAB Xpress cloud-based IDE. • PIC16F18345 (DM164141) • PIC16F18855 (DM164140) • PIC16F18877 (DM164142) Explorer 8 Development Kit (DM160228) The Explorer 8 Development Kit is a full-featured development board and platform for 8-bit PIC microcontrollers. This kit is a versatile development solution, featuring several options for external sensors, off-board communication and human interface. Explorer 16/32 Development Board/Kit • DM240001-2 (stand-alone board) • DM240001-3 (board with PIMs and cables) The Explorer 16/32 Development Board is a modular development system supporting PIC24, dsPIC33 and PIC32 devices. The board comes with several new features including an integrated programmer/debugger, on-board USB communication and USBto-serial communication bridge. The board’s wide ecosystem includes mikroBUS, Pmod and PICtail™ Plus interfaces that support click boards, Pmod boards and PICtail Plus daughter cards. PICDEM Lab II Development Platform (DM163046) The PICDEM™ Lab II Development Platform is a development and teaching platform for use with 8-bit PIC MCUs. At its center, a large prototyping breadboard enables you to easily experiment with different values and configurations of analog components for system optimization. Several external connectors allow for user-customizable expansion, while our library of labs and application notes enrich the development experience. Quick Guide to Microchip Development Tools 15 Starter Kits dsPIC33EP128GS808 Development Board (DM330026) The dsPIC33EP128GS808 Development Board consists of an 80-pin microcontroller for operating on a standalone basis or interfacing with CAN/LIN/J2602 PICtail (Plus) Daughter Board. In the standalone mode, the board can be used for verifying the peripheral functionality. The board contains single order RC filters to emulate power supply functionality in open or closed loop mode along with ADC and PWM peripherals. Intelligent Analog PIC24 Starter Kit (DM240015) This starter kit features the PIC24FJ128GC010 family with advanced integrated analog peripherals. The board includes an analog header, allowing clean signals to be accessed for easy prototyping. The board also includes sensors for light, touch and temperature as well as USB, potentiometer, microphone and headphone interface. Comprehensive demos are included as well as integrated programmer and debugger. PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit (DM320007) The PIC32MZ Embedded Connectivity with Floating Point Unit (FPU) (EF) Family Starter Kit (DM320007 for non-crypto development or DM320007-C for crypto development) provides a low-cost method for the development and testing of USB and Ethernet-based applications with PIC32MZ EF family devices. PIC32MK GP Development Kit (DM320106) The PIC32MK GP Development Kit offers a low-cost solution for those looking to build projects with the PIC32MK series of devices, featuring a rich assortment of CAN, USB, ADC and GPIO type inputs. This board also includes a Soloman Systec SSD1963 graphics driver and 30-pin connector to enable graphics applications with available LCD panels. PIC32MX274 XLP Starter Kit (DM320105) The PIC32MX XLP Starter Kit is a fully integrated 32-bit development platform featuring the high-performance PIC32MX274 series MIPS MCU. The kit includes an integrated programmer/ debugger, and is fully integrated with Microchip’s MPLAB X IDE. Additionally, the starter kit sports BTLE connectivity, a 9-axis accelerometer, light sensor and barometric sensor enabling different IoT data logging applications. Boards are fully integrated into PIC32’s powerful software framework, MPLAB Harmony. Multimedia Expansion Board II (DM320005-5) This board is a highly integrated, compact and flexible development platform. Integrates with the PIC32MZ Starter Kits for a complete graphics development solution. The MEB-II kit features a 4.3" WQVGA maXTouch® display daughter board. 16 www.microchip.com/tools Development Tools Bluetooth BM70 Bluetooth PICtail/PICtail Plus Board (BM-70-PICTAIL) This board is designed to emulate the function of Microchip’s BM70 BLE module, allowing you to evaluate the capabilities of the device. The board includes an integrated configuration and programming interface for plug-and-play capability. The development kit includes the BM70BLES1FC2 module and the BM70BLES1FC2 carrier board. RN4870 Bluetooth Low Energy PICtail/PICtail Plus Daughter Board (RN-4870-SNSR) This board is based on the ultra-compact Bluetooth 4.2 Low Energy RN4870 module. The RN4870 uses a simple ASCII command interface over the UART. The board enables evaluation of the RN4870 and development of Bluetooth low Energy applications. SAMB11 Xplained Pro Evaluation Kit (ATSAMB11-XPRO) This kit is a hardware platform to evaluate the ATSAMB11-MR510CA module for a complete Bluetooth Low Energy application on an ARM Cortex-M0 based MCU. The ATSAMB11-MR510CA module is based on Microchip’s industry leading lowest-power Bluetooth Low Energy 4.1-compliant SoC, ATSAMB11. PIC32 Bluetooth Audio Development Kit (DV320032) The PIC32 Bluetooth Audio Development Kit with PIC32MX470F512L on board offers an excellent means for designing and developing a low-cost Bluetooth audio system. The features include Bluetooth audio streaming with low-cost HCI radio module, compatibility with Bluetooth-enabled smartphones and portable music players, USB memory stick support, 2 inch color LCD display, high-quality 24-bit display and 192 kHz audio conversion for line or headphones. Quick Guide to Microchip Development Tools 17 Application-Specific Development Tools EERAM EERAM I²C PICtail Kit (AC500100) This kit is a package of two I2 C serial EERAM (4 KB [47C04], 16 KB [47C16]) PICtail boards. This kit supports PICtail Plus and mikroBUS connections and operates with the Explorer 8 Development Board, the Explorer 16/32 Development Board and many other tools. Ethernet KSZ9897 Switch Evaluation Board with LAN7801 and KSZ9031 (EVB-KSZ9897) This board features a completely integrated triple speed (10Base-T/100-Base-TX/1000Base-T) Ethernet switch with seven ports. The board has six physical ports and one USB-to-Ethernet port. The board also features the LAN7800 USB-to-Ethernet bridge and KSZ9031 Gigabit PHY. KSZ9477 Managed Switch Evaluation Board with SAMA5D36 MPU (EVB-KSZ9477) This board features a completely integrated triple speed (10Base-T/100-Base-TX/1000Base-T) Ethernet switch with five ports and one SFP port. The ARM-based SAMA5D3 host processor implements advanced switch management features such as IEEE 1588 v2, AVB and authentication while being reprogrammable. LAN9252 EtherCAT® Slave Controller Evaluation Kit with HBI PDI Interface (EVB-LAN9252-HBIPLUS) This board is a standalone platform to develop an EtherCAT slave device with PIC32 or other SoCs/MCUs/MPUs with more advanced features over the standard HBI board. KSZ8851SNL Evaulation Board (KSZ8851SNL-EVAL) This board is for the evaluation of this single-port Ethernet controller. With a 32-pin QFN (5 × 5 mm) package, it is ideal for applications requiring SPI and provides a basic software driver and configuration utility. LAN7800LC Evaluation Board (EVB-LAN7800LC) With a ultra-low cost BOM, this evaluation board integrates the USB Type-C™ connector to implement a high-speed data transfer to Gigabit Ethernet with on-board RJ45 connector. Software drivers for Windows, OS X and Linux operating systems are available. 18 www.microchip.com/tools Development Tools Ethernet PICtail Plus Daughter Board (AC164123) Designed for flexibility while evaluating and developing Ethernet control applications, this board can be plugged into Microchip’s Explorer 16 Development Board (DM240001) and can be used with the Microchip TCP/IP stack to connect with any Microchip 16-bit MCU. Fast 100 Mbps Ethernet PICtail Plus Daughter Board (AC164132) This board is populated with a 64-pin ENC624J600 Ethernet controller and interfaces to the RJ-45 connector. It can be plugged into the Explorer 16 Development Board (DM240001) and the PIC18 Explorer Board (DM183032) allowing connection to any of our 8-, 16- and 32-bit products. PICDEM.net™ 2 Development Board (DM163024) This Internet/Ethernet development board supports both the ENC28J60 Ethernet controller and the single-chip Ethernet PIC18F97J60 MCU. Using this board with our free TCIP/IP stack, you can develop a web server to demonstrate the ability to remotely monitor and control embedded applications over the Internet. PIC32 Ethernet Starter Kit II (DM320004-2) This kit provides the easiest and lowest-cost method to experience 10/100 Ethernet development with PIC32 microcontrollers. It combines LAN8720A and Microchip’s free TCP/IP software. LAN8720A PHY Daughter Board (AC320004-3) Populated with a high-performance, small-footprint, low-power 10Base-T/100Base-TX Ethernet LAN8720A PHY, this board is designed for easy development of RMII Ethernet control applications when plugged into the PIC32-compatible starter kits. LAN9303 PHY Switch Daughter Board (AC320004-4) Used with the PIC32 Ethernet Starter Kit II, this board provides an easy and low-cost way to implement 10/100 Ethernet switching. Combined with Microchip’s free TCP/IP software, this kit gets your project running quickly. Graphics and LCD LCD Explorer XLP Development Board (DM240314) This development board supports 100-pin PIC MCUs with eight common segmented LCD drivers. It ships with the PIC24FJ128GA310 and other families can be evaluated with different processor PIMs. In addition to the display, the board includes a PICtail Plus connector for daughter cards. It can be powered from USB, battery or 9V power supply and includes Vbat battery back-up. PIC24FJ256DA210 Development Board (DM240312) This graphics development board is for developing colorful graphics displays with the PIC24FJ256DA210 family. The board includes touch pads, USB and a PICtail Plus connector for daughter cards. Match this board with your desired display size and it easily connects to the 3.2" Truly TFT Display (AC164127-4), 4.3" Powertip TFT Display (AC164127-6) or Display Prototype Board (AC164139). Quick Guide to Microchip Development Tools 19 Development Tools LoRa 915 MHz RN2903 LoRa Technology Mote (DM164139) The RN2903 LoRa Mote is a LoRaWAN™ Class A end-device based on the RN2903 LoRa modem. As a standalone batterypowered node, the Mote provides a convenient platform to quickly demonstrate the long-range capabilities of the modem, as well as to verify inter-operability when connecting to LoRaWAN v1.0 compliant gateways and infrastructure. LoRa Technology Evaluation Kit (DV164140-2) The LoRa Network Evaluation Kit makes it easy for you to test LoRa technology, range and data rate. The full-featured gateway board includes an LCD screen, SD Card for configuring data, Ethernet connection, 915 MHz antenna and full-band capture radios. The Gateway Evaluation Kit also includes two RN2903 Mote boards (DM164139). Long-Range Wide-Area Network (LoRaWAN) 868 MHz RN2483 LoRa Technology Mote (DM164138) The RN2483 LoRa Motes are LoRaWAN Class A end-devices based on the RN2483 LoRa modem. It is ideal for IoT applications in remote locations. As a standalone battery-powered node, the mote provides a convenient platform to quickly demonstrate the long-range capabilities of the modem, as well as to verify inter-operability when connecting to LoRaWAN v1.0 compliant gateways and infrastructure. RN2483/RN2903 LoRa Technology PICtail/PICtail Plus Daughter Board (RN-2483-PICTAIL for EU, RN2903-PICTAIL for US) The RN2483 and RM2903 LoRa Technology PICtail/PICtail Plus Daughter Boards are development boards that showcase the Microchip RN2483/2903 Low-Power, Long-Range LoRa Technology Transceiver Module. Development of a LoRa system with these modules connected to Microchip’s PIC MCU line is possible on the PIC18 Explorer Boards via the 28-pin PICtail connector, or on the Explorer 16 Boards using the 30-pin card edge PICtail Plus connector. 20 www.microchip.com/tools Development Tools MiWi Wireless Networking Protocol MiWi Protocol Demo Kit – 2.4 GHz MRF24J40 (DM182016-1) The MiWi Protocol Demo Kit – 2.4 GHz MRF24J40 is an easy-to-use evaluation and development platform for IEEE 802.15.4 applications. You can develop/debug and demo application code all on the same platform. The kit includes all hardware needed to rapidly prototype wireless applications, and is pre-programmed with the MiWi Mesh protocol stack. Motor Control and Power Conversion Digital Power Starter Kit (DM330017-2) This kit uses the dsPIC33EP64GS502 DSC to implement a buck converter and a boost converter. The board has an LCD for showing voltage, current, temperature/fault conditions and an integrated programmer/debugger, all powered by the included 9V power supply. Motor Control Starter Kit (DM330015) This board includes a small 3-phase BLDC motor driven by dsPIC33FJ16MC102 motor control device and integrated programmer and debugger, powered by 9V power supply. dsPICDEM MCHV-2/3 Development System (DM330023-2/DM330023-3) This high-voltage development system is targeted to control BLDC motors, PMSM and AC Induction Motors (ACIM) in sensor or sensorless operation. The rated continuous output current from the inverter is 6.5 A (RMS), allows up to approximately 2 kVA output when running from a 208V to 230V single-phase input voltage. The MCHV-3 adds support for Power Factor Correction (PFC) with a maximum output of 1 kW at 400V. Low-Voltage Motor Control Development Bundle (DV330100) Evaluate and develop dual/single motor controls to drive BLDC motors or PMSMs concurrently or one of each. The dsPIC DSC Signal Board supports both 3.3V and 5V operated devices for various applications and frequently used human interface features along with the communication ports. The Motor Control 10–24V Driver Board (Dual/Single) supports currents up to 10A. Buck/Boost Converter PICtail Plus Card (AC164133) This is a development platform for dsPIC SMPS and digital power conversion GS family of digital signal controllers. It consists of two independent DC/DC synchronous buck converters and one independent DC/DC boost converter. The board operates from an input supply of +9V to +15V DC and can be controlled either by interfacing to the 28-pin Starter Development board or to Explorer 16/32 Development Board. Quick Guide to Microchip Development Tools 21 Development Tools Power over Ethernet (PoE) PIC18 PoE Development Kit (DV161001) Consisting of a PIC18 PoE Main Board, PoE Programmer Adapter and I/O Starter Extension, the PIC18 PoE Development Kit provides everything you need to begin developing within the Ethernet of Everything (EoE) environment. Customization and experimentation are simplified via an extension header that is mikroBUS compatible on the PIC18 PoE Main Board allowing for various sensors, controllers and drivers to be easily incorporated into your application. Real-Time Clock/Calendar (RTCC) MCP79410 RTCC PICtail Plus Daughter Board (AC164140) This board demonstrates the MCP7941X and MCP7940X I²C Real-Time Clock/Calendar (RTCC) family. It uses the PICtail Plus, PICtail and PICkit serial connector and operates with the Explorer 16 Development Board, the PICDEM PIC18 Explorer Board, the XLP 16-bit Development Board and the PICkit Serial Analyzer tool. MCP795XX PICtail Plus Daughter Board (AC164147) This board shows the MCP795XX SPI RTCC family functions. It includes the 14-pin MCP795W2X and MCP795W1X devices and both PICtail and PICtail Plus connectors. Operating with the Explorer 16 Development Board and the PICDEM PIC18 Explorer Board, the board hosts a coin cell for RTCC backup. Security AT88CK101 Development Kit (AT88CK101SK-MAH-XPRO) A development tool for applications that protect confidential files, encrypt downloads, perform two-factor logons, authenticate products and prevent software piracy. The starter kit includes an AVR baseboard (ATMicrobase) with a USB interface that lets you learn and experiment on your PC. The CryptoAuthenticationTM Evaluation Studio (ACES), which can be used with this kit includes a configuration environment that allows the ability to configure, demonstrate, and personalize the CryptoAuthentication device. 22 www.microchip.com/tools Development Tools Serial EEPROM MPLAB Starter Kit for Serial Memory Products (DV243003) This kit includes everything necessary to quickly develop a robust and reliable Serial EEPROM design, greatly reducing the time required for system integration and hardware/software fine-tuning. Supports the Microchip UNI/O bus, I²C, SPI and Microwire Serial EEPROMs. Total Endurance (TotalEnduranceSoftware) The software provides functional visibility to serial EEPROM applications. Target systems are input via an advanced mathematical model which predicts back the performance and reliability of the serial EEPROM in that target. Design trade-off analysis takes minutes and delivers robust design results. Serial EEPROM PIM PICtail Pack (AC243003) A package of four serial EEPROM (I2 C, SPI, Microwire, UNI/O®) PICtail boards that interface with the PICtail Plus connector, the MPLAB Starter Kit for Serial Memory Products (DV243003) and the PICkit Debugger. Serial SRAM SPI SRAM PICtail with Battery Backup (AC164151) The AC164151 is a PICtail and PICtail Plus development board that demonstrates the features of the 23LCV1024 1 Mbit Serial SRAM with battery backup on standard development platforms. System-on-Chip SAMR30 Xplained Pro Evaluation Kit (ATSAMR30-XPRO) The SAMR30 Xplained Pro is a hardware platform designed to evaluate the SAMR30G18A SoC. This kit is supported by Atmel Studio, an integrated development platform, which provides predefined application examples. Quick Guide to Microchip Development Tools 23 Development Tools Touch Sensing Technology MGC3130 Single Zone Hillstar Evaluation Kit (DM160218) This kit builds a complete MGC3130 reference system consisting of the MGC3130 module, I2 C-to-USB bridge module and a 4-layer reference electrode 95 × 60 mm sensitive area. The Hillstar package includes an artificial hand for parameterization and performance evaluation of the sensor. With the MGC3130 software package including Aurea graphical user interface and GestIC® technology library, the MGC3130 Software Development Kit (SDK) and a set of electrode reference designs the Hillstar Development Kit is prepared for an easy design-in of the MGC3130 module. QT1 Xplained Pro Extension Kit (ATQT1-XPRO) QT1 Xplained Pro Kit is an extension kit that enables evaluation of self- and mutual-capacitance mode using the Peripheral Touch Controller (PTC). The kit shows how easy it is to design a capacitive touch board solution using the PTC without the need for any external components. The kit includes two boards, one using self capacitance and one using mutual capacitance. QT2 Xplained Pro Extension Kit (ATQT2-XPRO) QT2 Xplained Pro is a QTouch® surface extension board for Xplained Pro boards that demonstrates the PTC as a highperformance touch-surface controller. The PTC controller uses very little power and resources from the MCU, which makes it easy to integrate touch surface support into your main project. QT3 Xplained Pro Extension Kit (ATQT3-XPRO) QT3 Xplained Pro is a QTouch keypad extension board demonstrating an ultra-low power keypad design using the PTC. Utilizing the PTCs, low-power capabilities, it enables the market's lowest-power wake-up on touch. QT4 Xplained Pro (ATQT4-XPRO) The QT4 Xplained Pro is an extension board that enables evaluation of self-capacitance touch and proximity sensors using the PTC. The kit shows how easy it is to design a capacitive touch board solution using the PTC without the need for any external components. QT5 Xplained Pro Extension Kit (ATQT5-XPRO) QT5 Xplained Pro is an extension kit that enables evaluation of mutual-capacitance touch using the PTC. The kit shows how easy it is to design a nice-looking capacitive-touch interface using the PTC module. The kit includes one board with a curved QTouch mutual-capacitance slider and two QTouch mutualcapacitance buttons. QT6 Xplained Pro (ATQT6-XPRO) The QT6 Xplained Pro is a QTouch surface extension board for Xplained Pro boards that demonstrates the PTC as a highperformance touch-surface controller. MTCH108 Evaluation Board (DM160229) The MTCH10X Evaluation Board provides an out-of-the-box experience for performance and the robustness of Microchip touch solutions. 24 www.microchip.com/tools Development Tools CAP1188 Evaluation Kit (DM160222) The CAP1188 Evaluation Kit provides an easy platform for evaluating and developing a variety of capacitive touch sense applications and LED configuration using CAP11XX family. CAP1298 Evaluation Kit (DM160223) The CAP1298 Evaluation Kit provides an easy platform for evaluating and developing a variety of capacitive touch sense and proximity applications using CAP12XX family. Low-Cost mTouch® Evaluation Kit (DM160227) This kit is a platform to evaluate and develop capacitive touch application using mTouch technologies. The kit shows a proximity sensing solution, different button sizes as well as how to use a guard for better noise performance. It also features mTouch algorithm for water rejection. Low-Power Projected Capacitive Touchpad Development Kit (DM160219) This kit allows you to quickly integrate gestures and XY touch into your design. The kit includes everything needed to create a rich user interface, including a USB connection to our GUI for customized solutions. Gestures and Projected Capacitive (PCap) Touch are supported by the MTCH6102, Microchip's turnkey PCap touch controller. tiny817 Water-Tolerance Demo Kit (ATTINY817-QTMOISTD) The tiny817 QTouch Moisture Demo Kit demonstrates the high-performance capacitive touch support of the PTC while achieving best-in-class conducted immunity and moisture tolerance. Quick Guide to Microchip Development Tools 25 Development Tools USB USB4604 Hi-Speed USB 2.0 Programmable 4-Port Controller Hub with FlexConnect and I/O Bridging (EVB-USB4604) The EVB-USB4604 is used to evaluate the full-featured USB46X4 family of programmable controller hubs. It features full programmability and unique features such as FlexConnect and I/O bridging. USB3740 Hi-Speed USB 2.0 2-Port Switch (EVB-USB3740) The EVB-USB3740 is used to evaluate our USB3740 USB 2.0 compliant 2-port switch. Some applications require a single USB port to be shared with other functions. The USB3740 is a small and simple 2-port switch providing system design flexibility. USB375X Hi-Speed USB 2.0 Port Protection with Integrated Switch and Charger Detection (EVB-USB3750) The EVB-USB3750 is used to evaluate our USB375X family of integrated USB 2.0 port protection devices. The USB375X integrates a high level of ESD protection to the USB port, which is typically exposed to the harsh environment of the outside world. It also incorporates our Hi-Speed USB 2.0 switch as well as battery charger detection, all in a conveniently small package. PIC18F Starter Kit (DM180021) The PIC18 Starter Kit functions as a USB mouse, joystick or mass storage device all using the on-board capacitive touch sense pads. It includes a MicroSD™ memory card, potentiometer, acceleration sensor and OLED display. This board features the PIC18F46J50 MCU with 64 KB Flash, 4 KB RAM, XLP low power, mTouch touch sensing and USB. PIC24F Starter Kit (DM240011) The PIC24F Starter Kit contains everything needed to begin exploring the high performance and versatility of the PIC24F microcontroller family. This inexpensive kit includes USB device and host connectors, tri-color LED, capacitive touch pad and an OLED display. Menu driven demonstration software supports data logging, thumb drive and graphics applications to test the PIC24F MCU. 26 www.microchip.com/tools Development Tools Wi-Fi WINC1500 PICtail/PICtail Plus Daughter Board (AC164156) The WINC1500 PICtail/PICtail Plus Daughter Board is a demonstration and development board for the WINC1510-MR210PB Wi-Fi module with PICtail and PICtail Plus connectors to interface with a PIC microcontroller on the Explorer 16 and PIC32 Ethernet Starter II Kit. WINC1500 Xplained Pro Evaluation Board (ATWINC1500-XPRO) The extension board is part of the Xplained Pro evaluation board platform and allows you to evaluate the WINC1500 low-cost, low-power 802.11 b/g/n Wi-Fi network controller module. Quick Guide to Microchip Development Tools 27 Analog Development Tools CAN and LIN dsPIC33EV 5V CAN-LIN Starter Kit (DM330018) The dsPIC33EV 5V CAN-LIN Starter Kit features the dsPIC33EV256GM106 Digital Signal Controller (DSC) for automotive and motor control applications. The starter kit contains serial data ports for CAN, LIN and SENT, a self-contained USB programming/debug interface and an expansion footprint for flexibility in application hardware development. MCP25625 PICtail Plus Daughter Board (ADM00617) The MCP25625 PICtail Plus Daughter Board is a simple CAN board designed to be used with boards containing the PICtail Plus connector. The board also has the PICkit Serial connector for interfacing to the PICkit Serial Analyzer tool. The single-chip solution CAN node consists of the MCP25625 CAN Controller with Integrated Transceiver. SAM HA1G16A Xplained Pro (ATSAMHA1G16A-XPRO) The SAMHA1G16A Xplained Pro Evaluation Kit is ideal for evaluating and prototyping with SAMHA1G16A ARM Cortex-M0+ based microcontrollers. High-Voltage Drivers HV582 96-Channel High-Voltage Driver IC Evaluation Board (ADM00697) HV583 128-Channel High-Voltage Driver IC Evaluation Board (ADM00677) These boards facilitate quick implementations for display and printer driver applications with flexible input/output connection interface. The boards are designed around the HV582/3, a unipolar, 96-channel low-voltage serial to high-voltage parallel converter with push-pull outputs. DN2470-Based Linear Regulator Input Voltage Range Extender Evaluation Board (ADM00682) Universal off-line linear regulation demo using the 700V depletion-mode FET DN2470. The board features off-line regulation using three different selectable LDOs: MCP1754, MCP1755 and MCP1790. LED Drivers HV98100 120VAC Off-Line LED Driver Evaluation Board (ADM00786) The HV98100 120 VAC Off-Line LED Driver Evaluation Board is designed to demonstrate the performance of the HV98100 LED Driver IC. The evaluation board drives a 120V LED string at 120 mA from a 120 VAC input voltage with high input power factor and low total harmonic distortion. Motor Drivers ATA6826-DK (ATA6826-DK) The application board allows loads to be easily adapted via its row connector pins. Design software controls its SPI interface via the PC parallel port. The board contains everything needed to start operation, including a link cable to PC 25-lead 1:1, application note and datasheet. ATA6823-DK (ATA6823-DK) The development kit contains a main board with an H-bridge gate driver (ATA6823), external FETs and DC motor. The controller board is populated with an ATmega88 microcontroller and LCD display. 28 www.microchip.com/tools Development Tools for Professional Makers chipKIT® Development Platform Tools chipKIT platform is a hig-performance, Arduino-compatible computing environment designed for ease-of-use and rapid prototyping. Based on 32-bit PIC MCUs, the platform is targeted for beginners as well as experienced users. It provides a migration path to professional engineering. chipKIT Basic I/O Shield (TDGL005) The chipKIT Basic I/O Shield is an input/output expansion board designed for use with chipKIT microcontroller boards such as the Uno32 and the Max32. The chipKIT Basic I/O Shield provides simple digital input devices such as switches and buttons as well as digital output devices such as discrete LEDs and high-current open FET drivers. It provides more advanced devices such as an I 2 C EEPROM, an I2 C temperature sensor and organic LED graphic display. A potentiometer is also provided for use as an analog input device. chipKIT Lenny Development Board (TCHIP005) The chipKIT Lenny was inspired by the Arduino Leonardo, and adds additional capabilities afforded by its 32-bit microcontroller. The chipKIT Lenny has 27 available I/O lines, six of which can be used as analog inputs. It is based on the 32-bit PIC32MX270F256D microcontroller and operates at 3.3V and 40 MHz. Direct access to the USB peripheral controller enables the chipKIT Lenny to emulate many types of USB devices. chipKIT Starter Pak (TCHIP003) The chipKIT Starter Pak contains everything you need to develop applications with the Arduino-compatible chipKIT platform. The Uno32 (TDGL002) includes an 80 MHz PIC32 processor with 128 KB Flash and 16 KB RAM. The Basic I/O Shield (TDGL005) adds a variety of useful I/O devices such as buttons, switches, OLED graphic display, temperature sensor, EEPROM, transistor outputs and more. A prototype shield kit from NKC Electronics is included, along with an innovative key that can be used to separate shields easily. chipKIT boards work with a Multi-Platform IDE (MPIDE) and software framework that is compatible with most Arduino-based applications. chipKIT uC32 Development Board (TDGL017) This board takes advantage of the powerful PIC32MX340F512 microcontroller, which features a 32-bit MIPS processor core running at 80 MHz, 512 KB of Flash program memory and 32K of SRAM data memory. The board can be programmed using the Arduino IDE. It contains everything needed to start developing embedded applications. It is also fully compatible with the advanced Microchip MPLAB X IDE and the PICkit 3 In-Circuit Programmer/Debugger. Fubarino® SD Development Board (TCHIP010) The Fubarino SD Board brings affordable, breadboard compatible high-speed computing power to the Arduino-compatible chipKIT/MPIDE platform. It is able to run almost all Arduino sketches right out of the box, and includes more memory, speed and I/O pins than a typical Arduino or clone. It also includes a microSD card slot for easy sketch access to huge file storage. Quick Guide to Microchip Development Tools 29 Development Tools for Professional Makers chipKIT Max32 Development Board (TDGL003) chipKIT Max32 Development Board by Digilent is an easy-to-use platform for developing advanced applications. The chipKIT platform uses a modified version of the original Arduino IDE for compatibility with existing code examples, tutorials and resources. It is pin compatible with many Arduino shields that can operate at 3.3V. chipKIT MX3 Development Board (TDGL008) The chipKIT MX3 Development Board by Digilent is a microcontroller development board based on the PIC32MX320F128H MCU. It is compatible with Digilent`s line of Pmod™ peripheral modules and is suitable for use with the MPLAB X IDE and PICkit InCircuit Debugger/Programmer. chipKIT Pro MX7 Development Board (TDGL010) The chipKIT Pro MX7 Development Board is based on the PIC32MX795F512L MCU. It is compatible with Digilent's line of Pmod peripheral modules and is suitable for use with MPLAB X IDE. This board is also compatible with the chipKIT platform's MPIDE development environment. Includes a built-in programmer/debugger compatible with MPLAB X IDE. Digilent PmodWiFi Module (TDGL011) The Digilent PmodWiFi Peripheral Module is an interface board for Microchip's MRF24WB0MA Wi-Fi radio transceiver module. It is compatible with Digilent's PIC32-based development boards (TDGL008, TDGL009, TDGL010) and can be easily connected to any system using standard IDC connectors and cables. A simple SPI interface is used to communicate with the module. Digilent PmodRTCC Peripheral Module (TDGL013) The Digilent PmodRTCC Peripheral Module (Digilent 410-218) is a Real-Time Clock/Calendar powered by Microchip's MCP79410. It is compatible with Digilent's PIC32-based Cerebot development boards (TDGL008, TDGL009, TDGL010) and can be easily connected to any system using standard IDC connectors and cables. An I2 C interface is used to communicate with the module. The PmodRTCC Module provides two available alarms, 128B EEPROM and 64B SRAM. The product includes a coin-cell battery holder. chipKIT PGM Programmer/Debugger (TDGL015) The chipKIT PGM by Digilent (410-242) is a simple, low-cost module that supports in-system programming and debugging of applications written for PIC MCU-based microcontroller boards such as the chipKIT and Cerebot boards. The chipKIT PGM is designed to work with MPLAB X IDE. 30 www.microchip.com/tools Development Tools for Professional Makers chipKIT DP32 Development Board (TDGL019) The chipKIT DP32 is the first chipKIT rapid prototype project board from Digilent. The board adds the power of the Microchip PIC32MX250F128B with a prototyping area in a single board. chipKIT Motor Shield (TDGL020) The chipKIT Motor Shield is an expansion board for use with the chipKIT Uno32 (TDGL002) and chipKIT uC32 (TDGL017). It provides additional circuitry and connectors for the Uno32 and uC32 to drive various motors types. The chipKIT Motor Shield is designed to drive DC motors, servo motors and stepper motors. It also provides additional I/O via an I2 C I/O extender. chipKIT WF32 Wi-Fi Development Board (TDGL021) This board includes several peripherals on board, including a Wi-Fi radio module, USB OTG (host or device) interface, microSD card slot, buttons, LEDs, potentiometer and lots of extra I/O. A full-featured HTML server application is available by download and the board can be powered by USB or an external power supply. chipKIT Wi-FIRE Development Board (TDGL021-2) The chipKIT Wi-FIRE Board enables rapid prototyping with Microchip’s latest PIC32MZ architecture and Imagination Technologies' Flow Cloud Internet connectivity development software. Protoshield Kit for chipKIT Uno32 (TNKC001) This Protoshield kit from NKC Electronics is a great way to expand your chipKIT Uno32. Develop your custom circuits on a solderless breadboard. Arduino Boards for Makers Today, both Microchip AVR 8-bit MCUs and Microchip 32-bit ARM-based MCUs power a variety of Arduino’s easy-to-use boards including: Arduino Zero Based on the Microchip's SAMD21 MCU, the Zero is a simple, elegant and powerful 32-bit extension of the platform aiming to provide creative individuals the potential to realize truly innovative ideas for smart IoT devices, wearable technology, high-tech automation, robotics and projects not yet imagined. Arduino Uno Based on the Microchip AVR ATmega328, the Uno board is a low-cost Arduino board with a simpler circuit. The software onboard includes a USB driver that can simulate a mouse, keyboard and serial port. In addition, the bootloader includes a serial port and USB mass storage driver. Arduino Due Based on an Microchip SAM3 MCU, the Due board is ideal for home automation projects and can run up to 96 MHz. Arduino Wi-Fi Shield 101 Built on an easy-to-use extension that can be seamlessly connected to any Arduino board, the Wi-Fi Shield 101 is powered by the Microchip SmartConnect wireless network controller and an Microchip CryptoAuthentication ATECC108 device. Arduino Leonardo Based on the Microchip megaAVR® ATmega32U4, the Arduino Leonardo is a low-cost Arduino board. It has the same shape and connectors as the UNO board, but it has a simpler circuit. On the software side it provides a USB driver able to simulate a mouse, a keyboard and a serial port. Quick Guide to Microchip Development Tools 31 Third-Party Tools Books Embedded C Programming Book and E3mini Board Bundle for CCS Compilers (TBDL001) This bundle includes Embedded C Programming: Techniques and Applications of C and PIC MCUs, a book by Mark Siegesmund, and the E3mini Development Board. This book provides a hands-on introductory course on concepts of C programming using a PIC microcontroller and the CCS C compiler. Compilers and IDEs CCS provides a line of full-featured C compilers for 8-bit and 16-bit MCUs. These compilers include a generous library of built-in functions, pre-processor commands and ready-to-run example programs to quickly jumpstart any project. Several versions are available, depending on which MCU families you plan to use and whether you prefer a command-line tool or a full-featured IDE. The CCS IDE provides several advanced features, including a unique Profiler Tool to track time and usage information for use on functions, code blocks as well as receiving live data from running programs. CCS compilers are compatible with MPLAB X IDE and MPLAB programmer/ debuggers. For more information, please visit: www.microchip.com/ccs. • PCM - CCS C Command-line Compiler for Midrange Family of PIC MCUs (SW500003-DL) • PCH - CCS C Command-line Compiler for PIC18 Family of PIC MCUs (SW500002-DL) • PCD CCS C Command-line Compiler for PIC24 MCUs/ dsPIC DSCs (SW500021-DL) • PCWH CCS C IDE Compiler for Baseline, Midrange, and PIC18 Families of PIC MCUs (SW500004-DL) • PCWHD CCS C IDE for Microchip 8-bit and 16-bit PIC MCU Families (SW500024-DL) MikroElektronika provides a line of optimizing C, basic and pascal compilers for 8-, 16- and 32-bit MCUs. Each compiler features an intuitive IDE, advanced optimizations, lots of hardware and software libraries and additional tools that will help you in your work. A comprehensive Help file is included with readyto-use examples designed to jump start your projects. The compiler license includes free upgrades and product lifetime tech support, and it can be used on multiple computers (USB dongle included.) Object files created with MikroElektronika compilers can be imported into MPLAB X IDE if desired. For a listing of products, please visit: www.microchip.com/mikroe. SOMNIUM DRT Cortex-M IDE The SOMNIUM DRT Cortex-M IDE provides you with the best possible C/C++ code quality along with state-of-the-art debug, all in a single professional development tools product, allowing you to reach the market faster with reduced costs, all while achieving the best quality design. • TSW1017 - 1-User, Fixed License • TWS1018 – 3-User, Floating License Development Hardware PIC24FJ1024GB610 General Purpose Plug-In Module (PIM) (MA240023) The PIC24FJ1024GB610 Plug-in Module is designed to demonstrate the capabilities of the PIC24FJ1024GB610 family using the Explorer 16 Demonstration Board. Most of the pins from the device are mapped directly to the PIM connector (100-Pin ICE). The exceptions are those pins that are remapped to provide remappable functionality to the pins in the PICtail Plus socket. Click by MikroElektronika Many of Microchip’s latest development boards feature a MikroElektronika Click expansion port which can be used to connect over 340 extensions from MikroElektronika. This makes it easy to extend PIC MCU functionality into Bluetooth, specialized analog, GSM, GPS, UNO, 3D motion and so much more. Visit Microchip’s third-party site for more information. 32 www.microchip.com/tools Third-Party Tools mikromedia workStation v7 (TMIK021) mikromedia workStation v7 provides full development environment for mikromedia boards. It features on-board debugger, multimedia modules, four mikroBUS host sockets and a large breadboard area. mikromedia Board for PIC24 (TMIK010) The Mikromedia Board for PIC24 is a palm-sized unit with amazing multimedia capabilities. Based on the PIC24F256GB110 with USB On-The-Go (OTG), it includes a 320 x 240 TFT display with touchscreen, stereo MP3 codec, 8 Mbit serial Flash, microSD card slot, headphone jack and USB connector. Powered by USB, the board can easily play MP3 files from a microSD card with full 320 kbps quality. mikromedia Board for PIC32 (TMIK012) The Mikromedia Board for PIC32 fits comfortably in the palm of your hand and provides amazing multimedia capability. Based on the PIC32MX460F512L MCU, it includes a 320 x 240 TFT display with touchscreen, stereo codec, 8 Mbit serial Flash, microSD card slot, headphone and microphone jacks and a USB connector. Powered by USB, the board is capable of playing videos directly from a microSD card at 15 fps. mikromedia PROTO Shield (TMIK032) mikromedia PROTO Shield is an extension board that is pin-compatible with all mikromedia boards from MikroElektronika. It enables users to place components and provide additional functionality to the base mikromedia board. CCS EZ Web Lynx 3V Module (TDKEZW3) CCS EZ Web Lynx 5V Module (TDKEZW5) EZ Web Lynx is a simple embedded Ethernet integration device to get a product online fast! This tiny unit can easily be added to any existing electronic design to gain Ethernet capability, reducing development and engineering time. CCS EZ Web Lynx 3V Development Kit (TDKEZW3-DEV) CCS EZ Web Lynx 5V Development Kit (TDKEZW5-DEV) These low-cost kits includes all hardware, software and documentation needed to speed integration of EZ Web Lynx Ethernet modules into your design. Monitor and control analog and digital I/O on the docking station using custom HTML tags. Use the IDE to develop custom dynamic web pages and send alarm/status emails simply by programming in HTML. Complete documentation includes design examples for temperature monitoring, using conditional HTML tags and controlling pin I/O. CCS PRIME8 Production Programmer (Touch Screen) (TPGPRM8-2) The latest version of CCS's Prime8 Production Programmer (53504-830) is a low-cost way to program up to eight devices concurrently. Prime8 operates in standalone mode or when connected to a PC. The unit will supply up to 200 mA at 2–5V to power target devices. It can program all devices in the PIC10, PIC12, PIC14, PIC16, PIC17, PIC18, PIC24, dsPIC DSC and PIC32 families. The newest features include flash-drive readability, faster programming speed and a graphics display touchscreen menu with easy-to-read icons. Quick Guide to Microchip Development Tools 33 Third-Party Tools Development Software Flowcode 7 for AVR/Arduino Products – Standard (TSW1013) Flowcode 7 is a flowchart-style programming tool that enables you to create complex electronic and electromechanical systems. The tool utilizes graphics in place of complex coding, meaning it is ideal for both beginners and experienced engineers. Flowcode 7 software is straight forward and easy to use, so you can develop your ideas in no time. MikroElektronika Visual TFT (SW500189) Visual TFT is a Windows application for rapid development of graphical user interfaces on TFT displays. It generates source code for all MikroElektronika compilers—mikroC, mikroBasic and mikroPascal—for all supported MCU architectures, including PIC MCUs and with many drag-and-drop components makes building applications easy and fast. Visual TFT runs on Windows computers and supports all multimedia boards from MikroElektronika, as well as ten TFT controllers and five different display sizes. SOMNIUM® DRT Atmel Studio Extension (TSW1016) SOMNIUM DRT Atmel Studio Extension enhances the Atmel Studio 7 IDP to provide superior C and C++ code generation quality to help you build smaller, faster, more energy-efficient software for your Microchip SMART MCU without changing your development environment or source code. Achieve the best quality design with reduced costs and reach the market faster. Oscilloscopes Saleae Logic Pro 8 - USB Logic Analyzer (TSAL0004) The Saleae Logic devices connect to your PC over USB. Just download the software at www.saleae.com. Navigate your data easily and intuitively with Logic's fluid and fully animated mouse-driven interface. The Saleae products support decoding for over 20 different protocols. • Saleae Logic 8 - USB Logic Analyzer (TSAL0003) • Saleae Logic Pro 16 - USB Logic Analyzer (TSAL0005) OpenScope: OpenScope MZ Test Instrument (TDGL027) OpenScope MZ (Digilent 410-324) is a portable multi-function programmable instrumentation module. That means it's a device that you connect to your computer (through Wi-Fi or a USB cable) for the purpose of acquiring, analyzing, visualizing and controlling signals from circuits, sensors and other electronic devices. Unlike typical USB instruments, OpenScope MZ can also be programmed to run standalone like an Arduino or Raspberry Pi®, but with high-speed precision analog and digital I/O. At the core of the OpenScope MZ is a powerful Microchip PIC32 MZ Processor. Programmers and Debuggers Softlog offers a full line of production-quality in-circuit GANG programmers. These include: • ICP2GANG-DP 4-Channel GANG Programmer (TPG100004) • ICP2GANG 4-Channel GANG Programmer (TPG100005) • ICP2GANG-DS Secure GANG Programmer (TPG100006) Softlog SEC-DS Secure Programming Upgrade for ICP2 Programmers (SW500090) Softlog SEC4CH-DS Secure Programming Upgrade for ICP2GANG Programmers (SW500091) The Softlog SEC-DS Secure Programming Upgrade is a secure programming extension for Softlog programmers that provides several layers of protection–utilizing breakthrough technology–dramatically reducing the risk of unauthorized reconstruction of hex data and limiting how many times a hex file can be programmed. Secure programming operates on two levels: the admin level and the user level. 34 www.microchip.com/tools Third-Party Tools Softlog ICP2 Production Quality In-Circuit Programmer (TPG100001) The Softlog ICP2 Production Quality In-Circuit Programmer is a cost-effective programmer that operates with a PC or as a standalone unit. Softlog ICP2PORT-P Production Quality In-Circuit Service Programmer (TPG100010) The Softlog ICP2PORT-P Production Quality In-Circuit Service Programmer is specially designed to meet your service programming needs. This compact, battery-powered device supports up to six different programming environments, making it an ideal, low-cost solution for field upgrades Softlog ICP2(HC) Production Quality In-Circuit High Current Programmer (TPG100008) The Softlog ICP2(HC) Production Quality In-Circuit High Current Programmer is a cost-effective programmer that operates with a PC or as a standalone unit. Softlog ICP2PORT Production Quality In-Circuit Service Programmer (TPG100009) The Softlog ICP2PORT Production Quality In-Circuit Service Programmer is specially designed to meet your service programming needs. This compact, battery-powered device supports up to six different programming environments, making it an ideal, low-cost solution for field upgrades. CCS Load-n-Go Handheld In-Circuit Programmer (TPG1LG01) Load-n-Go is a low-cost handheld in-circuit programmer that supports PIC10, PIC12, PIC14, PIC16, PIC18, PIC24 MCU and dsPIC DSC families. Running on four AA batteries this mobile programmer can go where no PC or laptop could go before. The simple user interface seamlessly allows for quick field programming of targets with up to four firmware images. Load-n-Go can also be powered via USB or with a 9V AC adapter and used as a regular ICD/ICSP with the CCS IDE compilers. Tag-Connect In-Circuit Cable Legged Version (TC2030-MCP) Tag-Connect In-Circuit Cable No Legs (TC2030-MCP-NL) Tag-Connect cables provide a simple, reliable means of connecting Debuggers and Programmers or other test equipment to your PCB’s while lowering board costs and facilitating efficient production programming. Quick Guide to Microchip Development Tools 35 Third-Party Tools Protocol Analyzers Total Phase BeagleTM USB 480 Protocol Analyzer (TTP100001) The Beagle USB 480 Protocol Analyzer (Total Phase TP320510) is a low-cost, non-intrusive high-speed USB 2.0 bus monitor that includes real-time USB class-level decoding. The Beagle USB 480 analyzer is capable of capturing and interactively displaying high-speed USB bus-states and traffic in real-time with timing at 16.7 ns resolution and comes complete with software and royalty-free API. Total Phase Beagle USB 12 Protocol Analyzer (TTP100002) The Beagle USB 12 Protocol Analyzer (Total Phase TP320221) is a non-intrusive full/low-speed USB 2.0 protocol analyzer that includes real-time USB descriptor parsing. Developers can monitor what is happening on the USB bus as it happens with 21 ns resolution. Total Phase Beagle I2 C/SPI Protocol Analyzer (TTP100003) The versatile Beagle I2 C/SPI Protocol Analyzer (Total Phase TP320121) is the ideal tool for the embedded engineer who is developing an I2 C or SPI based product. Total Phase Aardvark I2 C/SPI Host Adapter (TTP100005) The Aardvark I2 C/SPI Host Adapter (Total Phase TP240141) is a fast and powerful I2 C bus and SPI bus host adapter through USB. It allows a developer to interface a Windows, Linux, or Mac OS X PC via USB to a downstream embedded system environment and transfer serial messages using the I2 C and SPI protocols. Total Phase I2 C Development Kit (TTP100006) The I2 C Development Kit by Total Phase (TP120112) is a comprehensive and cost-effective kit that bundles together a complete set of Total Phases industry-leading I2 C development tools and popular accessories. With this kit, developers can exercise target devices on an I2 C bus as a master device, simulate an I2C master or slave device, program and verify I2C-based devices and passively monitor an I2 C bus in real time with bit-level timing down to 20 ns. Total Phase KomodoTM CAN Duo Interface (TTP100008) The Komodo CAN Duo Interface (Total Phase TP360110) is a two-channel USB-to-CAN adapter and analyzer. The Komodo interface is an all-in-one tool capable of active CAN data transmission and non-intrusive CAN bus monitoring. The Komodo CAN Duo Interface features two independently customizable CAN channels, a royalty-free API, and cross-platform support for Windows, Linux, and Mac OS X. Wi-Fi CCS EZ Web Lynx Wi-Fi Development Kit (TDKEZWIFI-DEV) This low-cost kit includes all hardware, software and documentation needed to speed integration of EZ Web Lynx Wi-Fi modules into your design. Monitor and control analog and digital I/O on the docking station using custom HTML tags. Use the IDE to develop custom dynamic web pages and send alarm/status emails simply by programming in HTML. www.microchip.com Support Microchip is committed to supporting its customers in developing products faster and more efficiently. We maintain a worldwide network of field applications engineers and technical support ready to provide product and system assistance. For more information, please visit www.microchip.com: • Technical Support: www.microchip.com/support • Evaluation samples of any Microchip device: www.microchip.com/sample • Knowledge base and peer help: www.microchip.com/forums • Sales and Global Distribution: www.microchip.com/sales Training If additional training interests you, Microchip offers several resources including in-depth technical training and reference material, self-paced tutorials and significant online resources. • Overview of Technical Training Resources: www.microchip.com/training • MASTERs Conferences: www.microchip.com/masters • Developer Help Website: www.microchip.com/developerhelp • Technical Training Centers: www.microchip.com/seminars Microchip Technology Inc. | 2355 W. Chandler Blvd. | Chandler AZ, 85224-6199 Sales Office Listing AMERICAS Atlanta, GA Tel: 678-957-9614 Austin, TX Tel: 512-257-3370 Boston, MA Tel: 774-760-0087 Chandler, AZ (HQ) Tel: 480-792-7200 Chicago, IL Tel: 630-285-0071 Dallas, TX Tel: 972-818-7423 Detroit, MI Tel: 248-848-4000 Houston, TX Tel: 281-894-5983 Indianapolis, IN Tel: 317-773-8323 Tel: 317-536-2380 Los Angeles, CA Tel: 949-462-9523 Tel: 951-273-7800 Raleigh, NC Tel: 919-844-7510 New York, NY Tel: 631-435-6000 San Jose, CA Tel: 408-735-9110 Tel: 408-436-4270 Canada - Toronto Tel: 905-695-1980 EUROPE Austria - Wels Tel: 43-7242-2244-39 Denmark - Copenhagen Tel: 45-4450-2828 Finland - Espoo Tel: 358-9-4520-820 France - Paris Tel: 33-1-69-53-63-20 France - Saint Cloud Tel: 33-1-30-60-70-00 Germany - Garching Tel: 49-8931-9700 Germany - Haan Tel: 49-2129-3766-400 Germany - Heilbronn Tel: 49-7131-67-3636 Germany - Karlsruhe Tel: 49-721-62537-0 Germany - Munich Tel: 49-89-627-144-0 Germany - Rosenheim Tel: 49-8031-354-560 EUROPE Israel - Ra’anana Tel: 972-9-744-7705 Italy - Milan Tel: 39-0331-742611 Italy - Padova Tel: 39-049-7625286 Netherlands - Drunen Tel: 31-416-690399 Norway - Trondheim Tel: 47-7289-7561 Poland - Warsaw Tel: 48-22-3325737 Romania - Bucharest Tel: 40-21-407-87-50 Spain - Madrid Tel: 34-91-708-08-90 Sweden - Gothenberg Tel: 46-31-704-60-40 UK - Wokingham Tel: 44-118-921-5800 ASIA/PACIFIC Australia - Sydney Tel: 61-2-9868-6733 China - Beijing Tel: 86-10-8569-7000 China - Chengdu Tel: 86-28-8665-5511 China - Chongqing Tel: 86-23-8980-9588 China - Dongguan Tel: 86-769-8702-9880 China - Guangzhou Tel: 86-20-8755-8029 China - Hangzhou Tel: 86-571-8792-8115 China - Hong Kong SAR Tel: 852-2943-5100 China - Nanjing Tel: 86-25-8473-2460 China - Qingdao Tel: 86-532-8502-7355 China - Shanghai Tel: 86-21-3326-8000 China - Shenyang Tel: 86-24-2334-2829 China - Shenzhen Tel: 86-755-8864-2200 China - Wuhan Tel: 86-27-5980-5300 China - Xiamen Tel: 86-592-2388138 China - Xian Tel: 86-29-8833-7252 ASIA/PACIFIC China - Zhuhai Tel: 86-756-321-0040 India - Bangalore Tel: 91-80-3090-4444 India - New Delhi Tel: 91-11-4160-8631 India - Pune Tel: 91-20-3019-1500 Japan - Osaka Tel: 81-6-6152-7160 Japan - Tokyo Tel: 81-3-6880-3770 Korea - Daegu Tel: 82-53-744-4301 Korea - Seoul Tel: 82-2-554-7200 Malaysia - Kuala Lumpur Tel: 60-3-6201-9857 Malaysia - Penang Tel: 60-4-227-8870 Philippines - Manila Tel: 63-2-634-9065 Singapore Tel: 65-6334-8870 Taiwan - Hsin Chu Tel: 886-3-577-8366 Taiwan - Kaohsiung Tel: 886-7-213-7830 Taiwan - Taipei Tel: 886-2-2508-8600 Thailand - Bangkok Tel: 66-2-694-1351 10/28/16 The Microchip name and logo, the Microchip logo, AVR, dsPIC, chipKIT, ClockWorks, GestIC, maXTouch, megaAVR, MPLAB, PIC, QTouch and tinyAVR are registered trademarks and CryptoAuthentication, Mindi, dsPICDEM, MiWi, motorBench, PICDEM, PICDEM.net, PICkit, PICtail and REAL ICE are trademarks of Microchip Technology Incorporated in the U.S.A. mTouch is a registered trademark of Microchip Technology Inc in the U.S.A. and other countries. ARM and Cortex are registered trademarks of ARM Limited (or its subsidiaries) in the EU and other countries. USB Type-C and USB-C are trademarks of the USB Implementers Forum. All other trademarks mentioned herein are property of their respective companies. © 2017, Microchip Technology Incorporated. All Rights Reserved. 10/17 DS50001894E

MPLAB Harmony Help MPLAB Harmony Integrated Software Framework © 2013-2018 Microchip Technology Inc. All rights reserved. Volume VI: Third-Party Products This volume describes the third-party libraries that are available in MPLAB Harmony. Description MPLAB Harmony enables seamless integration of third-party solutions, such as RTOS, Middleware, Drivers, and so on, into the software framework. Volume VI: Third-Party Products © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 2 Third-Party Products Overview This section provides an overview for the third-party products that are included in MPLAB Harmony. Introduction This topic provides an overview of the Third-Party Libraries in MPLAB Harmony. Description MPLAB Harmony is a flexible, abstracted, fully integrated firmware development platform for PIC32 microcontrollers, which enables seamless integration of third-party solutions, such as RTOS, Middleware, Drivers, and so on, into the software framework. Important Licensing Information OPENRTOS The OPENRTOS demonstrations provided in MPLAB Harmony use the OPENRTOS evaluation license, which is meant for demonstration purposes only. Customers desiring development and production on OPENRTOS must procure a suitable license. Please refer to one of the following documents, which are located in the third-party folder of the MPLAB Harmony installation, for information on obtaining an evaluation license for your device: • OpenRTOS Click Thru Eval License PIC32MXxx.pdf • OpenRTOS Click Thru Eval License PIC32MZxx.pdf Micriµm All Micriµm µC/OS-III demonstrations have added the crt0.S "C" run-time library start-up file to the project. The demonstration sets the linker option "do not link startup code". This is necessary for Micriµm µC/OS-III to work correctly with PIC32 devices as the general exception vector is located in crt0.S. Micriµm µC/OS-III overrides this interrupt source (general exception handler) to perform OS-specific functionality. If the user wants to implement their own application using Micriµm µC/OS-III and a PIC32 device, they must add the crt0.S file to their project and override the general exception interrupt vector. See the current RTOS examples for this implementation. A crt0.S template file can be found in the MPLAB XC32 C/C++ Compiler installation directory: ..\Microchip\xc32\\pic32-libs\libpic32. Important! The Micriµm µC/OS-II and µC/OS-III source code that is distributed with MPLAB Harmony is for FREE short-term evaluation, for educational use, or peaceful research. If you plan or intend to use Micriµm µC/OS-II and µC/OS-III in a commercial application/product, you need to contact Micriµm to properly license µC/OS-II and µC/OS-III for its use in your application/product. The source code is provided for your convenience and to help you experience Micriµm µC/OS-II and µC/OS-III. The fact the source is provided does NOT mean that you can use it commercially without paying a licensing fee. Knowledge of the source code may NOT be used to develop a similar product. If you are unsure about whether you need to obtain a license for your application, please contact Micriµm and discuss the intended use with a sales representative (www.micrium.com). Express Logic ThreadX The source code for the ThreadX demonstration is not freely distributed. To obtain source code and the proper licensing agreement go to the Express Logic ThreadX website: http://rtos.com/products/threadx/. Software License Agreement Refer to the MPLAB Harmony Integrated Software Framework Software License Agreement for complete licensing information. A copy of this agreement is available in the /doc folder of your MPLAB Harmony installation. Volume VI: Third-Party Products Third-Party Products Overview Software License Agreement © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 3 Decoder Library Help This section provides information on the Decoder Library. Introduction This topic provides an overview of the Decoder Library in MPLAB Harmony. Description The Decoder Library source files provided in your installation of MPLAB Harmony are based on the Version 6B release from the Independent JPEG Group (IJG). IJG is an informal group that writes and distributes a widely used free library for JPEG image compression. More Information For more information, please visit: http://ijg.org/. IJG documentation and archive files are accessible at: http://ijg.org/files/. Additional information is also available from the Microchip Third-Party RTOS web page: http://www.microchip.com/devtoolthirdparty/ Volume VI: Third-Party Products Decoder Library Help Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 4 Express Logic ThreadX Library Help This section provides information on the Express Logic ThreadX Library. Introduction This topic provides an overview of the Express Logic ThreadX Library in MPLAB Harmony. Description ThreadX is Express Logic's advanced Real-Time Operating System (RTOS) designed specifically for deeply embedded applications. ThreadX provides advanced scheduling facilities, message passing, interrupt management, and messaging services, as well as many others. ThreadX has many advanced features, including its picokernel™ architecture, preemption-threshold™ scheduling, event-chaining,™ and a rich set of system services. More Information For more information, please read the related documentation, which is available at: http://rtos.com/products/threadx/. Additional information is also available at http://rtos.com/products/threadx/Microchip_PIC32 and from the Microchip Third-Party RTOS web page: http://www.microchip.com/devtoolthirdparty/ Demonstrations See RTOS Demonstrations for information. Volume VI: Third-Party Products Express Logic ThreadX Library Help Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 5 FreeRTOS Library Help This section provides information on the FreeRTOS™ Library. Introduction This topic provides an overview of the FreeRTOS™ Library in MPLAB Harmony. Description FreeRTOS is a small footprint, portable, preemptive, open source, real time kernel that has been designed specifically for use on microcontrollers. FreeRTOS has added support for the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Family devices from v8.2.3 onwards. Use the following procedure to enable PIC32MZ EF FPU support in FreeRTOS tasks: 1. Define the configuration macro, configUSE_TASK_FPU_SUPPORT, to '1' in the FreeRTOSConfig.h file. Enabling this configuration macro allows the application to use FPU operations in main() before scheduler starts. 2. When it is desired to have FPU operations in selected FreeRTOS tasks, call the vPortTaskUsesFPU function at the start of only those tasks that use the FPU. More Information For more information, please read the FreeRTOS Quick Start Guide, which is available at: http://www.freertos.org/FreeRTOS-quick-start-guide.html. Additional information is also available from the Microchip Third-Party RTOS web page: http://www.microchip.com/devtoolthirdparty/ Demonstrations See RTOS Demonstrations for information. Volume VI: Third-Party Products FreeRTOS Library Help Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 6 InterNiche Library Help This section provides information on the InterNiche Library. Introduction This topic provides an overview of the InterNiche Library in MPLAB Harmony. Description Legal Disclaimer A particular InterNiche library is provided as object code for a specific MCU family, and is licensed for distribution with a single product. For additional information, contact sales@iniche.com. More Information For more information, please read the related documentation, which is available at: . Additional information is also available at http://www.iniche.com/ and from the Microchip Third-Party Software Stacks web page: http://www.microchip.com/devtoolthirdparty Volume VI: Third-Party Products InterNiche Library Help Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 7 iREASONING Networks MIB Browser This section describes the iREASONING Networks MIB Browser, which can be used when running certain MPLAB Harmony demonstration applications. Introduction This topic provides an overview of the iREASONING Networks MIB Browser. Description This help file describes how to use the iREASONING Networks MIB Browser to run the TCP/IP SNMP demonstration applications. The MIB Browser can be obtained from: http://www.ireasoning.com/downloadmibbrowserlicense.shtml. The MIB script upload, the MIB tree structure display, and the SNMP query mechanism procedures vary from browser to browser. Important! The use of a MIB browser or other third-party products may require that users review and agree to the terms of a license. Microchip's reference to the iREASONING Networks MIB Browser is for the users' convenience. It is the user's responsibility to obtain information about, and comply with the terms of, any applicable licenses. Getting Started This topic describes how to get started after installing the iREASONING Networks MIB Browser. Description Once your browser installation has been completed, perform the following steps: 1. Copy the mchip.mib file to the MIB file directory of your browser (e.g., C:\Program Files\ireasoning\mibbrowser\mibs). 2. Open the MIB Browser and select File>Load MIBs, and select the mchip.mib, RFC1213.mib, and SNMP-FRAMEWORK-MIB.mib (If SNMPv3 server is enabled) files. The Microchip MIB directory will be displayed in the SNMP MIB pane. The minimum set of RFC 1213 MIB2 variables that are required to identify the Microchip node as an SNMP node to the network are implemented. These variables can be accessed by any SNMP browser with a "public" type community name. Refer to the Microchip application note, AN870 "SNMP V2c Agent for Microchip TCP/IP Stack" (DS00000870) for more details on the MIB scripts, community names, and demonstration SNMP MIB variable tree structure. The following figure shows the variables implemented in the Microchip SNMP Agent. The ASN.1 format mchip.mib file is defined with a private variable tree structure for the MIB variables. Also the mchip.mib file is added with a number of OIDs, which can be accessed only with a SNMPv3 request. The browser can access every variable in the MIB database provided the community name matches. The access to the MIB variables is restricted to the type of the request. The RFC1213 MIB variables can be accessed with a SNMPv2c/v3 request. However, the SNMP-FRAMEWORK-MIB.mib variables can only be accessed with a SNMPv3 request if the credentials are matched and the message is authenticated. To modify these MIB variables, the corresponding changes must be made to both MIB scripts (snmp.mib and mchip.mib). The following figure shows the Microchip private MIB variable tree structure in the browser. Volume VI: Third-Party Products iREASONING Networks MIB Browser Getting Started © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 8 Configuring the Browser This topic describes how to configure the iREASONING Networks MIB Browser for use with the TCP/IP SNMP demonstrations. Description To configure the MIB browser: 1. Select the 'Advanced' tab in the browser. The following configuration window appears: 2. If V2c services are required, select SNMP version V2c, and configure the Read and Write community to the browser. • The V2c agent will respond only to the queries from SNMP MIB browsers using the same community. That is, the V2c agent and the browser should be members of the same community. • If the community fields are left blank, the manager sends the SNMP request with the community name as "public" • The V2c agent is configured by default with three Read communities ("public", "read", " ") and three Write communities ("private","write","public") • The default maximum community length is 8 characters • As the default communities also contain the "public" community name, the agent will respond to all of the browsers requesting the "public" community • At run time, the community names can be dynamically configured using the HTTP interface for SNMP community name configuration Volume VI: Third-Party Products iREASONING Networks MIB Browser Configuring the Browser © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 9 If the V2c agent receives an SNMP request with an unknown community name, the agent will generate an Authentication trap. The V2c agent's multiple community support feature enables the user application to provide limited access to the requesting browser based on the community name used by the browser to access the MIB database variables of the agent. 3. If SNMPv3 services are required, select the SNMP Version as 'V3' in the 'Advanced' tab of the SNMP MIB Browser. The following configuration window appears: 4. If SNMPv3 services are required, the SNMPv3 browser is required to be configured with the user name, authentication and privacy password, message authentication hash type, privacy protocol type. The SNMP server will respond only if one of the user credentials and user security parameters in the following table is configured at the manager. This table is stored in the global structure with the SNMPv3 server stack. The SNMPv3 server would only respond if the request credentials of the MIB browser matches to that of the stored user database of the SNMP server. USER 1 USER 2 USER 3 USM User microchip SnmpAdmin root Security Level auth, priv auth, no priv no auth, no priv Auth Algorithm MD5 SHA1 N/A Auth Password auth12345 ChandlerUS N/A Privacy Algorithm AES N/A N/A Privacy Password priv12345 N/A N/A 5. The Microchip SNMPv3 stack does support only one Context Engine ID with the server. Leave the "Context Name" option in the "Advanced" tab empty. It is ignored on the server. 6. According to the user and the auth and privacy protocols configured with the SNMP browser, the UDP authenticated and encrypted message would be exchanged between server and the client. • If the USER 1 values, as shown in the table, are configured in the MIB browser, the data exchange between the client and server is encrypted and authenticated. The PDU can be captured in the Ethernet packet sniffer like WireShark and examined. As the data is encrypted and authenticated, the data integrity and the privacy is achieved. • If the USER 2 values, as shown in the table, are configured in the MIB browser, the data exchange between the client and server is authenticated. The data integrity will be checked once the data is received at either end. The message authentication mechanism protects from the possible data sniffing and modification threat, and also guarantees that the data is received from the authenticated and guaranteed source. • If the USER3 values, as shown in the table, are configured in the MIB browser, the data exchange between the client and server is neither authenticated nor encrypted. Considering the three USER configurations, if the SNMP server is to be accessed over WAN in the Internet cloud, the data should be encrypted and authenticated to have the highest level of data privacy and integrity. 7. Configure the IPv4 or IPv6 address of the SNMP agent to the 'Address field'. Volume VI: Third-Party Products iREASONING Networks MIB Browser Configuring the Browser © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 10 8. Select the variable to be accessed from the agent MIB database from the SNMP MIBs pane. The OID of the selected variable can be seen in the OID tab in the following figure. 9. Select the SNMP Get operation from the operations tab. 10. The SNMPv3 server demonstration MIB is included with RFC1213 SNMPv2 MIB variables, private MIB variables, and the SNMP-FRAMEWORK-MIB variables. If the SNMPv2C request with a validated community name is generated from the MIB Browser, only a limited set of variables is accessed. The access to the MIB variables is restricted to the type of SNMP version request received. If the SNMPv3 request with correct credentials is generated from the MIB Browser, the complete MIB access is provided. 11. The user will need to decide which part of the MIB should be required to be restricted depending upon the SNMP version type. The MIB design is the one of the important steps in deciding the MIB tree structure and the variable to be placed accordingly. 12. The SNMP server demonstration MIB is added with a static variable OID named "snmpv3PvtObject" with a OID value as 43.6.1.4.1.17095.6.1. This variable is placed in the private branch of the MIB by creating an independent branch. All of the other variables in the private branch are accessible by a SNMPv2c request. The access to this static variable is restricted by the SNMP version type. Only the SNMPv3 request with correct credentials can access this variable. SNMP Operations This topic describes the SNMP operations that can be used with the TCP/IP SNMP demonstrations. Get Operation Get operation description. Description 1. Select the "Advanced" tab and configure the SNMP version to '1' and the Read community to "public". 2. Select "Get" from the operations menu. 3. Select the sysDescr variable from the MIB Tree. The Result Table displays the sysDescr variable information. Repeat this procedure for any MIB variable. For SNMP V2c, repeat the same procedure, substituting '2' in place of '1' in the version configuration. As explained earlier, the V2c agent is configured with three Read and Write community defaults. Configure the browser to use any of these communities and try accessing the MIB variables. You should be able to access some of the MIB variables even with the Read Community configured as any of the 'write' community defaults. For Get operations, if the Read or Write community matches, the agent processes the request. Volume VI: Third-Party Products iREASONING Networks MIB Browser SNMP Operations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 11 For Set operations, the received community names must match any of the 'write' community names. For SNMP V3, substitute '3' in place of '1' in the version configuration in the "Advanced" tab. Configure the other user based auth and priv credentials as explained in the "MIB Browsers" section. With appropriate credentials, all the MIB variables are accessible. Select any of the MIB variables in the MIB tree and do a GET operation. Get_Next Operation Get_Next operation description. Description 1. Repeat the process for the Get operation. 2. Select the sysDescr variable from the MIB tree, and then select "Get Next" from the operations menu. The result table will display the sysObjectID variable information. 3. Repeat Steps 1 and 2 for additional MIB variables to get the information for the corresponding next variable. 4. Set the SNMP MIB Browser version to v1/v2c. Try to access the private MIB variable "snmpv3PvtObject" with OID value as 43.6.1.4.1.17095.6.1. The access should be restricted. Set the version to V3, configure the credentials, again try a Get_Next operation for the same variable. The access should be granted. Get_Bulk Operation Get_Bulk operation description. Description This operation is supported in SNMPv2c and SNMPv3. Get_Bulk enables the collection of bulk information from the agent with a single request from the manager. 1. Configure the SNMP version to '2' or '3' in the SNMP browser. 2. If version is configured to '2', set the Read Community to 'public' or 'read.' 3. If version is configured to '3', configure the appropriate V3 credentials. 4. Select the sysDescr variable from the MIB tree. 5. Select the Get Bulk operation from the Operations menu. The default Non Repeaters and Max Repeaters values are '0' and '10', respectively, and get bulk configuration profile to change Non Repeaters and Max Repeaters parameters. The result table will display information for 10 MIB variables in a single request (if the Max Repetitions = 10 and Non Repeaters = 0 is configured). These variables are the lexicographical successors of the sysDescr variable. The number of variables that the agent will respond with can be Volume VI: Third-Party Products iREASONING Networks MIB Browser SNMP Operations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 12 configured in the browser through the menu selections Tools > Options > Non-Repeaters and Tools > Options > Max-Repetitions. The Non-Repeaters and Max-Repetitions numbers are extracted by the SNMP agent from the received Get_Bulk request and the number of variables that will be included in the response PDU is calculated. for more information on calculating the number of variables, Non-Repeaters, and Max-Repetitions, refer to RFC 3416. Set Operation Set operation description. Description The Set command updates the variable information of the MIB database in the agent. The Set command can be performed only on those variables which are declared as 'READWRITE' in the MIB scripts, and only if the community name matches any one of the 'write' community names configured with the agent. 1. Select the ledD5 variable from the MIB tree. 2. Configure the SNMP version to '1' or '2.' Configure the Write Community to 'public', 'write', or 'private'. 3. If version is configured to '3', configure the appropriate V3 credentials. 4. Select 'Set' from the Operations menu and the SNMP SET window will pop up. Enter the value for the browser in the OID field as per the defined syntax of the mchip.mib and snmp.mib scripts. A success message will appear. A 'Get' operation for the same variable should now return the new 'Set' value for this variable. LED5 on the demonstration board should now be ON. Repeat the procedure to set LED5 to OFF. LED6 can also be set ON or OFF. Table View • Like other operations , table view is used for sequence variables • Create row, delete row is not supported Volume VI: Third-Party Products iREASONING Networks MIB Browser SNMP Operations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 13 • Refresh button is used to get the updated tabular values IPv4TrapTable IPv6TrapTable Walk With IPv4 Address With IPv6 Address Volume VI: Third-Party Products iREASONING Networks MIB Browser SNMP Operations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 14 Trap Test Trap test description. Description Procedure for IPv4 Trap Table Configuration 1. Open the 'Advanced' configuration menu, configure the SNMP version to '2,' and configure the Write Community to "public', 'write', or 'private'. 2. Select the 'IPv4trapEnabled.0' variable from the MIB tree. 3. Select 'Set' from the Operations menu. 4. Enter '1' in the value field of the SNMP SET window. 5. Select 'IPv4trapReceiverIPAddress.0' from the MIB tree. 6. Set the value to the IP address of the personal computer on which the SNMP browser is installed and running. 7. Open the "Trap Receiver' utility that was installed with the iREASONING MIB browser (Start > Programs > iReasoning > MIB Browser > Trap Receiver). Procedure for IPv6 Trap Table Configuration 1. Open the 'Advanced' configuration menu, configure the SNMP version to '2,' and configure the Write Community to "public', 'write', or 'private'. 2. Select the 'IPv6trapEnabled.0' variable from the MIB tree. 3. Select 'Set' from the Operations menu. 4. Enter '1' in the value field of the SNMP SET window. 5. Select 'IPv6trapReceiverIPAddress.0' from the MIB tree. 6. Set the value to the IP address of the personal computer on which the SNMP browser is installed and running. 7. Open the "Trap Receiver' utility that was installed with the iREASONING MIB browser (Start > Programs > iReasoning > MIB Browser > Trap Receiver). SNMPv3 Stack Trap Receiver Settings • iREASONING SNMP version 3 trap receiver receives the traps only with TRAP version 2. • With respect to iREASONING , need SNMPv3 trap setting to receive traps. • Open iReasoning browser > tools > Trap Receiver • Open Trap Receiver >Tools >options >snmpv3TrapReceiver Volume VI: Third-Party Products iREASONING Networks MIB Browser Trap Test © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 15 Note: The same SNMPv3 user table configuration is required while doing SNMPv3 trap receiver configuration. HTTP Configuration HTTP configuration description. Description If an HTTP2 server is used with the Microchip TCP/IP Stack, it is possible to dynamically configure the Read and Write community names through the SNMP Configuration web page. Access the web page using http://mchpboard_e/mpfsupload or http://(for IPv6 it should be http://:80/index.html), and then access the SNMP Configuration web page through the navigation bar. Use "admin" for the username and "microchip" for the password. Volume VI: Third-Party Products iREASONING Networks MIB Browser HTTP Configuration © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 16 Volume VI: Third-Party Products iREASONING Networks MIB Browser HTTP Configuration © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 17 Micrium uC/OS Libraries Help This section provides information on the Micriµm® µC/OS-II™ and µC/OS-III™ Libraries. Introduction This topic provides an overview of the Micriµm µC/OS-II and µC/OS-III Libraries in MPLAB Harmony. Description Micriµm µC/OS-II and µC/OS-III are highly portable, ROMable, scalable, preemptive, real-time, deterministic, multitasking kernels for microprocessors, microcontrollers and DSPs. More Information For more information, please read the related documentation, which is available at: https://doc.micrium.com/display/osiiidoc/. Additional information is also available from the Microchip Third-Party RTOS web page: http://www.microchip.com/devtoolthirdparty/ Demonstrations See RTOS Demonstrations for information. Application Note AN1264 "Integrating Microchip Libraries with a Real-Time Operating System" (DS00001264) Description: This application note examines the reasons for porting to a RTOS-based platform. It then discusses the various changes that may be required to user software to use an RTOS. When discussing this topic, it is easier to do this in the context of a real world application, such as home utility metering, as an example. The demonstration shows how a complex application can be built using Commercial Off-The-Shelf (COTS) hardware and software components. By using an RTOS, the workload involved in integrating multiple libraries has been significantly reduced. Volume VI: Third-Party Products Micrium uC/OS Libraries Help Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 18 OPENRTOS Library Help This section provides information on the OPENRTOS® Library. Introduction This topic provides an overview of the OPENRTOS® Library in MPLAB Harmony. Description OPENRTOS is a small, efficient embedded kernel based on the highly successful FreeRTOS. License Disclaimer The OPENRTOS demonstrations provided in MPLAB Harmony use the OPENRTOS evaluation license, which is meant for demonstration purposes only. Customers desiring development and production on OPENRTOS must procure a suitable license. Please refer to one of the following documents, which are located in the third-party folder of the MPLAB Harmony installation, for information on obtaining an evaluation license for your device: • OpenRTOS Click Thru Eval License PIC32MXxx.pdf • OpenRTOS Click Thru Eval License PIC32MZxx.pdf More Information For more information, please refer to the OPENRTOS documentation, which is available at: http://www.wittenstein-us.com. Additional information is also available from the Microchip Third-Party RTOS web page: http://www.microchip.com/devtoolthirdparty/ Volume VI: Third-Party Products OPENRTOS Library Help Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 19 SEGGER embOS Library Help This section provides information on the SEGGER embOS Library. Introduction This topic provides an overview of the SEGGER embOS Library in MPLAB Harmony. Description SEGGER embOS is a priority-controlled Real-Time Operating System, designed to be used as a foundation for the development of embedded real-time applications. More Information For more information, please read the "embOS CPU-Independent User & Reference Guide", which is available at: https://www.segger.com/embos.html. Additional information is also available from the Microchip Third-Party RTOS web page: http://www.microchip.com/devtoolthirdparty/ Demonstrations See RTOS Demonstrations for information. Legal Disclaimer The source code for this SEGGER embOS RTOS demonstration is not freely distributed. To obtain source code and the proper licensing agreement go to the SEGGER embOS website: https://www.segger.com/license-models.html. The SEGGER embOS source has been installed in the following location: /third_party/rtos/SEGGER so that the applicable MPLAB Harmony demonstrations can work. Application Note AN1264 "Integrating Microchip Libraries with a Real-Time Operating System" (DS00001264) Description: This application note examines the reasons for porting to a RTOS-based platform. It then discusses the various changes that may be required to user software to use an RTOS. When discussing this topic, it is easier to do this in the context of a real world application, such as home utility metering, as an example. The demonstration shows how a complex application can be built using Commercial Off-The-Shelf (COTS) hardware and software components. By using an RTOS, the workload involved in integrating multiple libraries has been significantly reduced. Volume VI: Third-Party Products SEGGER embOS Library Help Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 20 SEGGER emWin Graphics Library Help This topic describes the SEGGER emWin® Graphics Library and tool suite that is available with the MPLAB Harmony installation. Introduction This section provides information about the emWin Graphics Library. Description emWin from SEGGER Microcontroller GmbH & Co. KG, is a software graphics library that provides an efficient, processor and LCD controller-independent graphical user interface (GUI) for applications that operate with a graphical LCD. emWin provides a GUI for a graphics application that is independent of the LCD controller and CPU. This library package, which includes the binary library, headers, and utility tools, is free to use as part of development using 32-bit and 16-bit products from Microchip. Within MPLAB Harmony, emWin uses the Hardware Abstraction Layer (HAL) to interface with the display drivers. The decision to use the standard MPLAB Harmony Graphics Library or the SEGGER emWin Graphics Library can be made during application development by using the MPLAB Harmony Configurator (MHC) in MPLAB Harmony. Refer to the SEGGER emWin website for information regarding the architecture and scope of the library by visiting https://www.segger.com/emwin.html. Refer to Start-to-End Example of SEGGER emWin Graphics with MPLAB Harmony for a step by step guide to using the SEGGER tools and library with MPLAB Harmony. The MPLAB Harmony installation includes two SEGGER emWin demonstrations, emwin_quickstart and emwin_showcase, under the apps/gfx/ directory. These demonstrate SEGGER capabilities as well as SEGGER tool usage and library integration with MPLAB Harmony. SEGGER emWin Library Architecture This section describes the basic architecture of the SEGGER emWin Graphics Library and provides information and examples of how to use it. Description Library File The SEGGER emWin Graphics Library archive file, emWin.a, file is installed with MPLAB Harmony in the /bin/framework/gfx/segger_emwin/lib directory. Abstraction Model This section provides an abstraction of the SEGGER emWin Graphics Library. Description The SEGGER emWin Graphics Library interface defines a superset abstraction of the functionality provided by any specific implementation or configuration of the library. This topic describes how that abstraction is modeled in software. Within MPLAB Harmony, the emWin Graphics Library uses the Hardware Abstraction Layer (HAL) to interface with the display drivers. The decision to use the standard MPLAB Harmony Graphics Library or the SEGGER emWin Graphics Library can be made during application development by using the MPLAB Harmony Configurator (MHC) in MPLAB Harmony. The following diagram shows how a third-party graphics library such as emWin fits into MPLAB Harmony and can be used within MPLAB Harmony for graphics functionality. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help SEGGER emWin Library Architecture © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 21 The emWin library stack has the following layers Widget Layer This layer includes the optional Widget Library. Window Layer This layer includes the optional Window Manager. Rendering Layer This layer includes the required GUI Core, which consists of the Graphic Library, Basic Fonts, and Touch/Mouse support. Output Layer This layer includes the optional memory devices and VNC server, as well as the required driver. Refer to the SEGGER emWin website for more information: https://www.segger.com/emwin.html Library Overview This section provides an overview of the different SEGGER emWin-related installation components within MPLAB Harmony. Description The SEGGER emWin Graphics Library is provided in binary format; therefore, no API source is included in the installation of MPLAB Harmony. As part of MPLAB Harmony, the SEGGER emWin Graphics Library now includes the v5.32 emWin header files and the emWin.a library, as well as utility tools from SEGGER for graphics application development. The header files, which are SEGGER originals with only the license in the header modified to reflect Microchip's contract with SEGGER, are installed in: \bin\framework\gfx\segger_emwin\inc. The emWin.a file for the library is located in: \bin\framework\gfx\segger_emwin\lib. The latest tools for software development utilizing the library are available in: \utilities\segger\emwin. Refer to Library Interface for information on obtaining documentation that describes the APIs included with SEGGER emWin. How the Library Works This section describes the basic architecture of the SEGGER emWin Graphics Library and provides information on and examples of the tools required to use it. Description In addition to the display driver, the SEGGER emWin Graphics Library consists of basic and optional components, as follows: emWin Basic Components Volume VI: Third-Party Products SEGGER emWin Graphics Library Help How the Library Works © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 22 • Graphic Library • Basic Fonts • Simulation Library • emWinView • Bitmap Converter • Color Conversion • Touch/Mouse Support Optional Components • Window Manager • Memory Devices • Anti-aliasing • VNC Server • Font Converter • Multi-layer/Multi-display Refer to the SEGGER emWin website for more information: https://www.segger.com/emwin.html Setup (Initialization) This topic provides information on setup/initialization. Description The SEGGER emWin Graphics Library can be selected in any MPLAB Harmony project by selecting the SEGGER emWin option in the MPLAB Harmony Configurator (MHC) through MPLAB Harmony & Application Configuration > Third Party Libraries > Graphics > Use SEGGER emWin Graphics Library?, as shown in the following figure. This option includes the emWin.a file within the Libraries tab of the application project. From the Options tab, expand Third Party Libraries > Graphics > Use SEGGER emWin Graphics Library?. Configuring the Library The SEGGER emWin Graphics Library includes the system_config.h file. This file is generated by the MPLAB Harmony Configurator (MHC) and defines the user-selected configuration options required to build the library. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help How the Library Works © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 23 This header can be placed anywhere. However, the path of this header needs to be present in the include search path for a successful build. For more details, refer to Applications Help. Library Interface This section provides information on the Application Programming Interface (API) functions provided in the SEGGER emWin Library. Description The SEGGER emWin Library is provided in binary format; therefore, no API source is provided in the installation of MPLAB Harmony. For information on the APIs in SEGGER emWin, refer to the latest "emWin Graphic Library with Graphical User Interface User & Reference Guide", which is available for download from SEGGER by visiting: www.segger.com. • On the main site, download the document by clicking Downloads, and then selecting emWin. In Manuals and software, select the link for the emWin Manual. At the time of this release of MPLAB Harmony, the manual revision was v5.32, Rev.0: https://www.segger.com/admin/uploads/productDocs/UM03001_emWin5.pdf SEGGER Utility Tools This section describes the SEGGER emWin utilities and their usage. Description Your installation of MPLAB Harmony also provides the following SEGGER emWin utilities from the PRO tool suite, which are located in \utilities\segger\emwin. • Binary to C Converter • BMP Converter • emWin VNC Client • emWin SPY • emWin Windows View • GUI Builder • JPEG to Movie Converter • Font Converter (Demonstration Setup Executable) • UTF-8 Text to C Converter The utilities provided in your installation of MPLAB Harmony assist users to: • Design the GUI • Create the graphics resources • Optimize the graphics resources • Monitor the application parameters The output of most of the tools is either a binary file or a C file to be linked with the application code. Please note that the tools can be run only on a host machine with the Windows Operating System. For more information on the SEGGER emWin Graphics Library, its configuration and tools, please refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. There are multiple vital utilities provided with the SEGGER emWin release package within MPLAB Harmony. These utilities are located within your installation of MPLAB Harmony in \utilities\segger\emwin. All of the utilities run on a host computer. The following diagram shows the SEGGER emWin utilities provided in MPLAB Harmony, their output and the integration of the output with the MPLAB Harmony project. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help SEGGER Utility Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 24 GUI Builder (GUIBuilder) This section describes the GUI Builder (GUIBuilder) utility. Description GUIBuilder is a GUI designer utility. A designer having no knowledge of C programming also can use this utility. GUIBuilder also conserves the effort of writing source code by generating the C file that will call the SEGGER emWin Graphics Library APIs. The generated files need further modifications under user-defined code to add more functionality. Binary Name GUIBuilder.exe Usage • Project Path: Set the project path by modifying the ProjectPath variable from GUIBuilder.ini located in the same location as GUIBuilder.exe. • Parent widget: Add a parent widget to each dialog. Available parent widgets are: Frame Window and Window. • Child widget: Add required child widgets. • Widget properties: Modify widget properties such as size, position, and so on. • Save: Save the loaded dialog as C files at the project path. • Modify C files: Modify the C files as required within user code sections. • Integrate: Integrate the generated C files with emWin application. For more information on integration please refer to GUI and Touch Wrapper Library for SEGGER emWin. Input • Widgets • A C file (generated by GUIBuilder) Output • A C file. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help SEGGER Utility Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 25 Binary to C Converter (Bin2C) This section describes the Binary to C Converter (Bin2C) utility. Description The Bin2C utility converts the binary data from a file to a C file, which is linked to the emWin application, and is read using emWin Library API. Please note that the binary data from a file is converted to a C file "as is". To use the data from the C file by the emWin application, further processing may be required. Binary Name Bin2C.exe Usage • Load the binary file into the application. • Convert the file. • The converted C file will be located at the same location as of the binary file and is primarily used to convert JPEG or TTF files. Input • Any binary file. Output • A C file. UTF-8 Text to C Converter (U2C) This section describes the UTF-8 to C Converter (U2C) utility. Description The U2C utility converts UTF-8 text to C code by reading a UTF-8 text file and creating a C file with C strings. Binary Name U2C.exe Usage • UTF-8 text file: To create UTF-8 encoded text file using notepad, load the text under notepad, select File > Save As and select the UTF-8 encoding format while saving the file. • UTF-8 to C: Run U2C.exe. Select the UTF-8 encoded file using Select file…. Click Convert to convert the UTF-8 encoded file to a C file. • Using the string: Copy the converted string from the C file to an array of characters in the application code. Set the text encode format to UTF-8 by using the GUI_UC_SetEncodeUTF8 function. Display the string by passing the array pointer to the GUI_DispString function. Output A C file. Bitmap Converter (BmpCvt) This section describes the Bitmap Converter (BmpCvt) utility. Description The Bitmap Converter utility is used to convert BMP, PNG or GIF files into the desired emWin bitmap format. The utility supports color conversion, which is used as a tool to reduce memory consumption. The Bitmap Converter also supports other simple functions such as: • Scaling the bitmap size • Flipping the bitmap horizontally or vertically • Rotating the bitmap • Inverting the bitmap indices or colors Binary Name BmpCvt.exe Volume VI: Third-Party Products SEGGER emWin Graphics Library Help SEGGER Utility Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 26 Usage • Load the image into the application • Modify the color format, size, flip, rotate • Save the image in the appropriate format Input • BMP file: 1/4/8 bpp (with palette), 16/24/32 bpp, RLE4/8 • GIF file: Please refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. • PNG file: Images with or without alpha channel Output • C file: Link to application code • C stream file: Load on any media • BMP file: Use for further processing • GIF file: Use for further processing • PNG file: Use for further processing Font Converter (SetupFontCvtDemo_V532) This section describes the Font Converter (SetupFontCvtDemo_V532) utility. Description The binary provided is a Microsoft Windows setup utility for the demonstration version of the font converter. The demonstration utility will be available in the host computer once the setup binary is successfully installed into the host computer. The font converter utility converts installed PC fonts into an emWin (bitmap) font. Binary Name SetupFontCvtDemo_V532.exe JPEG to Movie Converter (JPEG2Movie) This section describes the JPEG to Movie Converter (JPEG2Movie) utility. Description The JPEG to Movie Converter utility creates emWin Movie Files (EMF) from multiple JPEG images. The EMF format acts as a container format and can be used to play a movie by using the existing JPEG decoding capability of the SEGGER emWin Graphics Library. Binary Name JPEG2Movie.exe Usage • Frame encoding: If the frame image is raw or has a format other than JPEG, the image need to be encoded into JPEG format. FFmpeg is an open source utility available under LGPL or GPL License, which can be used to convert any movie file to JPEG files for each frame. • Collection: Collect all frames encoded into JPEG format into one folder • Movie encoding: From the command line, change to the directory containing JPEG2Movie and run the command: JPEG2Movie.exe . The output file with EMF format will be created in the same folder containing the JPEG files. Input A folder containing JPEG files. Output A EMF file. emWin VNC Client (emVNC) This section describes the emWin VNC Client (emVNC) utility. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help SEGGER Utility Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 27 Description The emWin Virtual Network Computing (VNC) Client is part of the VNC client server system. The emWin VNC Server runs on the embedded target. The emWin VNC server running on an embedded device allows the display of content from an embedded device to the emWin VNC Client running on the host computer. The emWin VNC Server support is available as a separate package and is not included with your installation of MPLAB Harmony. the emWin VNC server requires a multi-tasking environment with TCP/IP stack support and the TCP/IP stack is not part of the emWin. Binary Name emVNC.exe For more information, please refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. emWin SPY (emWinSPY) This section describes the emWin SPY (emWinSPY) utility. Description The emWin SPY utility is used to show run-time information of the embedded target on a PC. The utility shows information about the currently connected emWin application, such as: memory status, information about existing widows, and a list of user input. The utility can also take captures of the current screen. The embedded device and the host computer communicate through a socket connection (TCP/IP) or SEGGER’s Real-Time Transfer (RTT). Binary Name emWinSPY.exe For more information, please refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. emWin Windows View (emWinView) This section describes the emWin Windows View (emWinView) utility. Description While debugging the emWin application and stepping through the application source code, the display output cannot be seen. The emWin Window View utility solves this problem by showing the simulation display while debugging the simulation. The utility also provides the following additional capabilities: • Multiple windows for each layer • Watching the whole virtual layer in one window • Magnification of each layer window • Composite view if using multiple layers Binary Name emWinView.exe For more information, please refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. GUI and Touch Wrapper Library for SEGGER emWin This section provides information on the GUI and Touch Wrapper for SEGGER emWin. Introduction This section provides an introduction to the GUI and Touch wrapper for MPLAB Harmony compatibility with SEGGER emWin. Description The GUI and Touch Wrapper Library provides a wrapper to SEGGER emWin application code for the purpose of integrating the application code with MPLAB Harmony. The GUI and Touch Wrapper Library provides separate wrappers for GUI and Touch interface for the SEGGER emWin Graphics Library. GUI Wrapper The GUI Wrapper can be used for integrating the dialog code generated by the emWin GUIBuilder utility with MPLAB Harmony. This wrapper also Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 28 initializes the SEGGER emWin Graphics Library and maintains the state machine of the wrapper. It generates the templates for GUI and LCD configuration files required by the emWin application. Touch Wrapper The Touch Wrapper can be used for integrating the SEGGER emWin Touch interface with MPLAB Harmony. This wrapper interfaces the Messaging System Service Library with the emWin Touch interface and decodes the touch data from the Messaging System Service and encodes it as required by the emWin Touch interface. Using the Library This section describes the basic architecture of the GUI and Touch Wrapper Library and provides information and examples on how to use it. Description Interface Header File: emwin_gui_static.h and emwin_touch_static.h The interface to the GUI and Touch Wrapper Library is defined in the emwin_gui_static.h and emwin_touch_static.h header files. Any C language source (.c) file that uses the library should include emwin_gui_static.h and emwin_touch_static.h. The SEGGER emWin Graphics Library includes other header files located at /bin/framework/gfx/segger_emwin/inc and /apps//src/system_config//third_party/gfx/emwin/config. These two paths are required to be included into the project include path. Library Source Files The GUI and Touch Wrapper Library template files are provided in the /third_party/gfx/emwin/gui/templates and /third_party/gfx/emwin/touch/templates directory. The MPLAB Harmony Configurator (MHC) generates C source files using these template files within the application system_config folder. The templates folder may contain optional files and alternate implementations. Please refer to Configuring the Library for instructions on how to select optional features and to Building the Library for instructions on how to build the library. Abstraction Model This library provides an abstraction of the GUI and Touch Wrapper Library. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description The GUI and Touch Wrapper Library interface defines a superset abstraction of the functionality provided by any specific implementation or configuration of the library. This topic describes how that abstraction is modeled in software and introduces the library's interface. Refer to Configuring the Library to determine the actual set of features that are supported for each configuration option. As shown in the following diagram, the GUI and Touch Wrapper Library uses services of the third-party SEGGER emWin Graphics Library and the MPLAB Harmony Messaging System Service Library. The GUI and Touch Wrapper Library writes to the display using the display controller driver. The display controller driver can be from the SEGGER emWin Graphics Library or from MPLAB Harmony. The Messaging System Service services the messages sent by the Touch System Service in First In First Out (FIFO) order. The Touch System Service Library encodes the touch commands from the touch data received from the Touch Controller Driver in MPLAB Harmony. GUI and Touch Wrapper Library Software Abstraction Model Library Overview The Library Interface functions are divided into various sub-sections, each of which interacts with one or more of the items identified in the abstraction model. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 29 Library Interface Section Description GUI Wrapper Functions Provides functions to initialize the GUI Wrapper as well as tasks and screen functions. Touch Wrapper Functions Provides functions for initializing the Touch Wrapper and creating a mail box. How the Library Works This section provides information on how the GUI and Touch Wrapper Library works. Description The following figure highlights the processes that the application must follow to use the GUI and Touch Wrapper Library. Initializing the GUI and Touch Wrappers Describes how to initialize the GUI Wrapper and Touch Wrapper. Description The application needs to initialize the GUI and Touch Wrapper Library. The library is initialized successfully by selecting the correct MHC configuration values. The GUI Wrapper requires the MHC configuration values for “Memory Block Size” and “Number of Screens” to be set. The Touch Wrapper requires the MHC configuration values for “System Message Service Instance” to be set. The following code shows an example of designing the data structure EMWIN_TOUCH_INIT and also shows how example usage of the emWin_TouchInitialize and emWin_GuiInitialize functions. EMWIN_TOUCH_INIT emWinTouchInitData; /* Set the Messaging System Service instance */ emWinTouchInitData.iSysMsg = SYS_MSG_0; /* Initialize the emWin Touch Wrapper */ emWin_TouchInitialize( (SYS_MODULE_INIT *)&emWinTouchInitData ); /* Initialize the emWin GUI Wrapper */ emWin_GuiInitialize(); Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 30 Touch Wrapper Setup Describes how to set up the Touch Wrapper. Description After initializing the Touch Wrapper, the Messaging System Service Mail Box required by the Touch System Service needs to be created. To create the mail box, the user application needs to call the emWin_TouchMailBoxCreate function from the GUI and Touch Wrapper Library. The following code shows an example of creating the mail box using emWin_TouchMailBoxCreate. emWin_TouchMailBoxCreate(); GUI Wrapper Setup Describes how to set up the GUI Wrapper. Description After initializing the GUI Wrapper, it must be set up with the screen or dialog and resources code generated by the emWin tools. This may require initializing the screens parameters such as background color or font by registering the Screen Initialize function using the emWin_GuiScreenInitializeRegister function. After registering the Screen Initialize function, emWin screens or dialogs need to be registered using the emWin_GuiScreenRegister function. Please note the all register functions only perform the registration. The registered function is called at the appropriate occurrence of the state of the GUI Tasks state machine. To start drawing the screens or dialog a starting screen or dialog needs to be set using the emWin_GuiStartScreenSet function. The following code shows an example of setting up the GUI Wrapper. /* Create Screen/dialog function pointer array */ EMWIN_GUI_SCREEN_CREATE emWinScreenCreate[ EMWIN_GUI_NUM_SCREENS ] = { CreateScreen1, CreateScreen2, CreateScreen3 }; /* Screen Initialize Function */ void APP_ScreenInitialize ( void ) { GUI_SetBkColor(GUI_BLACK); GUI_Clear(); } /* Register Screen Initialize Function */ emWin_GuiScreenInitializeRegister( APP_ScreenInitialize ); /* Register Screen/dialog Initialize */ for( screenCount = 0; screenCount < EMWIN_GUI_NUM_SCREENS; screenCount++ ) { emWin_GuiScreenRegister( screenCount, emWinScreenCreate[screenCount]); } /* Set the start Screen/dialog as first screen */ emWin_GuiStartScreenSet( 0 ); GUI Wrapper Screen Change Describes how to change a screen using the GUI Wrapper. Description Once the GUI is set up, emWin_GuiTasks will call APIs to draw the screen, and based on events, the SEGGER emWin Graphics Library will redraw the screen. To draw a new screen based on the event, call the emWin_GuiScreenChange function. The following code shows an example of changing screen on event. /* Abstract of event code from GUIBuilder generated Screen/dialog */ switch(Id) { case ID_BUTTON_0: // Notifications sent by 'Next' switch(NCode) { case WM_NOTIFICATION_CLICKED: // USER START (Optionally insert code for reacting on notification message) // On click of next button set the next screen/dialog emWin_GuiScreenChange(SCREEN_2); // USER END Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 31 break; case WM_NOTIFICATION_RELEASED: // USER START (Optionally insert code for reacting on notification message) // USER END break; // USER START (Optionally insert additional code for further notification handling) // USER END } break; // USER START (Optionally insert additional code for further IDs) // USER END } Configuring the Library The GUI and Touch Wrapper Library includes the system_config.h file. This file is generated by the MPLAB Harmony Configurator (MHC). It defines the user-selected configuration options necessary to build the library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Help section for more details. Building the Library This section lists the files that are available with the GUI and Touch Wrapper Library. It lists the files need to be included in the build based on configuration option selected by the system. Description The following three tables list and describe the header (.h) and source (.c) files that implement this library. The parent folder for these files is /third-party/gfx/emwin. Required File(s) All of the required files listed in the following table are automatically added into the MPLAB X IDE project by the MHC when the library is selected for use. This table lists and describes the source and header files that must always be included in the MPLAB X IDE project to build this library. Source File Name Description gui/emwin_gui_static.h This file should be included by any .c file that accesses the GUI Wrapper API. This file contains the prototypes for the GUI Wrapper APIs. touch/emwin_touch_static.h This file should be included by any .c file that accesses the Touch Wrapper API. This file contains the prototypes for the Touch Wrapper APIs Optional File(s) This table lists and describes the source and header files that may optionally be included if required for the desired implementation. Source File Name Description touch/src/emwin_touch_static.c This file should always be included in the project when using the Touch Wrapper. gui/src/emwin_gui_static.c This file should always be included in the project when using the GUI Wrapper. config/GUI_X_Ex.c This file should always be included in the project when using the GUI Wrapper. config/GUIConf.c This file should always be included in the project when using the GUI Wrapper. config/LCDConf.c This file should always be included in the project when using the GUI Wrapper. Module Dependencies The GUI and Touch Wrapper Library is dependent upon the following modules: • SEGGER emWin Graphics Library • Messaging System Service Library • Touch System Service Library Library Interface This section provides information on the Application Programming Interface (API) functions provided in the GUI and Touch Wrapper Library. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 32 GUI Wrapper Data Types and Constants Name Description EMWIN_GUI_SCREEN_CREATE Pointer to emWin Screen Create function. EMWIN_GUI_SCREEN_INITIALIZE Pointer to emWin Screen Initialize Function. GUI Wrapper Functions Name Description emWin_GuiInitialize Initializes the emWin GUI Wrapper. emWin_GuiScreenChange Sets the ID of the next screen to be drawn. emWin_GuiScreenInitializeRegister Registers the Screen Initialize function. emWin_GuiScreenRegister Register the GUIBuilder generated screen. emWin_GuiStartScreenSet Sets the start screen. emWin_GuiTasks Maintains the emWin GUI Wrapper's state machine. emWin_GuiScreenEnd Ends the already created screen. emWin_GuiScreenGet Gets handle of the screen. Touch Wrapper Data Types and Constants Name Description EMWIN_TOUCH_INIT Defines the data required to initialize the emWin Touch Wrapper. Touch Wrapper Functions Name Description emWin_TouchInitialize Initializes the emWin Touch Wrapper. emWin_TouchMailBoxCreate Create Mail Box for the touch input messages. GUI Wrapper Functions emWin_GuiInitialize Function Initializes the emWin GUI Wrapper. File emwin_gui.h C void emWin_GuiInitialize(); Returns None. Description This function initializes the emWin GUI wrapper. Remarks None. Preconditions None. Example emWin_GuiInitialize(); Function void emWin_GuiInitialize(void) Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 33 emWin_GuiScreenChange Function Sets the ID of the next screen to be drawn. File emwin_gui.h C void emWin_GuiScreenChange(int32_t screenId); Returns None. Description This function sets the ID of the next screen to be drawn. Remarks None. Preconditions The emWin_GuiInitialize function must have been called. All screens must have been registered using emWin_GuiScreenRegister. Example typedef enum { EMWIN_APP_SCREEN_1 = 0, EMWIN_APP_SCREEN_2, EMWIN_APP_SCREEN_3, } EMWIN_APP_SCREEN_ID; //Custom code addition to the Guibuilder Generated Screen 1 code static void _cbDialog(WM_MESSAGE * pMsg) { const void * pData; WM_HWIN hItem; U32 FileSize; int NCode; int Id; // USER START (Optionally insert additional variables) // USER END // Intermediate code. switch(Id) { case ID_BUTTON_0: // Notifications sent by 'ButtonNext' switch(NCode) { case WM_NOTIFICATION_CLICKED: // USER START (Optionally insert code for reacting on notification message) // USER END break; case WM_NOTIFICATION_RELEASED: // USER START (Optionally insert code for reacting on notification message) // Change to new screen with ID EMWIN_APP_SCREEN_2 emWin_GuiScreenChange(EMWIN_APP_SCREEN_2); // USER END break; // USER START (Optionally insert additional code for further notification handling) // USER END } break; // USER START (Optionally insert additional code for further notification handling) // USER END Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 34 } Parameters Parameters Description screenId Index to the array of GUIBuilder generated screens. Function void emWin_GuiScreenChange( int32_t screenId ) emWin_GuiScreenInitializeRegister Function Registers the Screen Initialize function. File emwin_gui.h C void emWin_GuiScreenInitializeRegister(EMWIN_GUI_SCREEN_INITIALIZE screenInit); Returns None. Description This function is used to register the Screen Initialize function. Remarks None. Preconditions The emWin_GuiInitialize function must have been called. Example void APP_ScreenInitialize( void ) { GUI_SetBkColor(GUI_BLACK); GUI_Clear(); } emWin_GuiScreenInitializeRegister( APP_ScreenInitialize ); Parameters Parameters Description screenInit Pointer to the Screen Initialize function. Function void emWin_GuiScreenInitializeRegister ( EMWIN_GUI_SCREEN_INITIALIZE screenInit ) emWin_GuiScreenRegister Function Register the GUIBuilder generated screen. File emwin_gui.h C void emWin_GuiScreenRegister(int32_t screenId, EMWIN_GUI_SCREEN_CREATE screen); Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 35 Returns None. Description This function registers the GUIBuilder generated screens. Remarks None. Preconditions The emWin_GuiInitialize function must have been called. Example EMWIN_GUI_SCREEN_CREATE emWinScreenCreate[ EMWIN_GUI_NUM_SCREENS ] = { Screen_1, Screen_2, Screen_3 }; int32_t screenCount = 0; for( screenCount = 0; screenCount < EMWIN_GUI_NUM_SCREENS; screenCount++ ) { emWin_GuiScreenRegister( screenCount, emWinScreenCreate[screenCount]); } Parameters Parameters Description screenId Index to the array of the screens. screen pointer to the GUIBuilder generated screen. Function void emWin_GuiScreenRegister ( int32_t screenId, EMWIN_GUI_SCREEN_CREATE screen ) emWin_GuiStartScreenSet Function Sets the start screen. File emwin_gui.h C void emWin_GuiStartScreenSet(int32_t screenId); Returns None. Description This functions sets the start screen. Remarks None. Preconditions The emWin_GuiInitialize function must have been called. Example typedef enum Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 36 { EMWIN_APP_SCREEN_1 = 0, EMWIN_APP_SCREEN_2, EMWIN_APP_SCREEN_3, } EMWIN_APP_SCREEN_ID; EMWIN_GUI_SCREEN_CREATE emWinScreenCreate[ EMWIN_GUI_NUM_SCREENS ] = { Screen_1, Screen_2, Screen_3 }; int32_t screenCount = 0; for( screenCount = 0; screenCount < EMWIN_GUI_NUM_SCREENS; screenCount++ ) { emWin_GuiScreenRegister( screenCount, emWinScreenCreate[screenCount]); } emWin_GuiStartScreenSet( EMWIN_APP_SCREEN_2 ); Parameters Parameters Description screenId Index to the array of GUIBuilder generated screens. Function void emWin_GuiStartScreenSet( int32_t screenId ); emWin_GuiTasks Function Maintains the emWin GUI Wrapper's state machine. File emwin_gui.h C void emWin_GuiTasks(); Returns None. Description This function is used to maintain the emWin GUI Wrapper's internal state machine. This function should be called from the SYS_Tasks function. Remarks None. Preconditions The emWin_GuiInitialize function must have been called. All screens must have been registered using emWin_GuiScreenRegister. Example while (true) { emWin_GuiTasks(); //Do other tasks } Function void emWin_GuiTasks(void) Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 37 emWin_GuiScreenEnd Function Ends the already created screen. File emwin_gui.h C void emWin_GuiScreenEnd(int32_t screenId); Returns None. Description This function ends the already created screen. The handle of the ended screen will no longer be valid. This function is used when screen to be end during transition to from the current screen to another screen. Remarks None. Preconditions The emWin_GuiInitialize function must have been called. Example typedef enum { EMWIN_APP_SCREEN_1 = 0, EMWIN_APP_SCREEN_2, EMWIN_APP_SCREEN_3, } EMWIN_APP_SCREEN_ID; //Custom code addition to the Guibuilder Generated Screen 1 code static void _cbDialog(WM_MESSAGE * pMsg) { const void * pData; WM_HWIN hItem; U32 FileSize; int NCode; int Id; // USER START (Optionally insert additional variables) // USER END // Intermediate code. switch(Id) { case ID_BUTTON_0: // Notifications sent by 'ButtonNext' switch(NCode) { case WM_NOTIFICATION_CLICKED: // USER START (Optionally insert code for reacting on notification message) // USER END break; case WM_NOTIFICATION_RELEASED: // USER START (Optionally insert code for reacting on notification message) // Change to new screen with ID EMWIN_APP_SCREEN_2 emWin_GuiScreenChange(EMWIN_APP_SCREEN_2); emWin_GuiScreenEnd(EMWIN_APP_SCREEN_1); // USER END break; // USER START (Optionally insert additional code for further notification handling) // USER END } break; Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 38 // USER START (Optionally insert additional code for further notification handling) // USER END } Parameters Parameters Description screenId Index to the array of GUIBuilder generated screens. Function void emWin_GuiScreenEnd( int32_t screenId ); emWin_GuiScreenGet Function Gets handle of the screen. File emwin_gui.h C WM_HWIN emWin_GuiScreenGet(int32_t screenId); Returns Handle of the already created screen. Returns 0 if the screenId is invalid. Description This functions gets the handle of the screen with screen Id provided by screenId variable. This function is used when objects from one screen to be accessed in another screen. Remarks None. Preconditions The emWin_GuiInitialize function must have been called. Example typedef enum { EMWIN_APP_SCREEN_1 = 0, EMWIN_APP_SCREEN_2, EMWIN_APP_SCREEN_3, } EMWIN_APP_SCREEN_ID; extern GUI_CONST_STORAGE GUI_BITMAP bmMyImage; WM_HWIN hScreen2; // Custom code addition to the Guibuilder Generated Screen 1 code switch(Id) { case ID_BUTTON_0: // Notifications sent by 'ButtonNext' switch(NCode) { case WM_NOTIFICATION_CLICKED: // USER START (Optionally insert code for reacting on notification message) // Set BMP Image in screen 2 based on event on screen 1 hScreen2 = emWin_GuiScreenGet( EMWIN_APP_SCREEN_2 ); hItem = WM_GetDialogItem( hScreen2, ID_SCREEN2_IMAGE_0); IMAGE_SetBitmap( hItem, &bmMyImage ); // USER END break; case WM_NOTIFICATION_RELEASED: // USER START (Optionally insert code for reacting on notification message) // USER END break; // USER START (Optionally insert additional code for further notification handling) Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 39 // USER END } break; // USER START (Optionally insert additional code for further notification handling) // USER END } Parameters Parameters Description screenId Index to the array of GUIBuilder generated screens. Function WM_HWIN emWin_GuiScreenGet( int32_t screenId ) GUI Wrapper Data Types and Constants EMWIN_GUI_SCREEN_CREATE Type Pointer to emWin Screen Create function. File emwin_gui.h C typedef WM_HWIN (* EMWIN_GUI_SCREEN_CREATE)(void); Returns Handle of the created dialog. Description emWin Screen Create Function Pointer This data type defines the function signature for the emWin Screen Create function. The application must register the pointers to the different Screen create functions with signature matching to the types specified by this function pointer. Remarks The array of type EMWIN_GUI_SCREEN_CREATE is initialized by Screen_1, Screen_2 and Screen_3. Screen_1 to Screen_3 are functions auto generated by the emWin tool: GUIBuilder. Example EMWIN_GUI_SCREEN_CREATE emWinScreenCreate[ EMWIN_GUI_NUM_SCREENS ] = { Screen_1, Screen_2, Screen_3 }; int32_t screenCount = 0; for( screenCount = 0; screenCount < EMWIN_GUI_NUM_SCREENS; screenCount++ ) { emWin_GuiScreenRegister( screenCount, emWinScreenCreate[screenCount]); } EMWIN_GUI_SCREEN_INITIALIZE Type Pointer to emWin Screen Initialize Function. File emwin_gui.h C typedef void (* EMWIN_GUI_SCREEN_INITIALIZE)(void); Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 40 Returns None. Description emWin Screen Initialize Function Pointer This data type defines the function signature for the emWin Screen Create function. The application can register this function in case any emWin initialization functions to be called before creation of the screens. Remarks The screen initialize if registered will be called once before screen create. Example void APP_ScreenInitialize( void ) { GUI_SetBkColor(GUI_BLACK); GUI_Clear(); } EMWIN_GUI_SCREEN_INITIALIZE screenInitialize = &APP_ScreenInitialize; emWin_GuiScreenInitializeRegister( screenInitialize ); Touch Wrapper Functions emWin_TouchInitialize Function Initializes the emWin Touch Wrapper. File emwin_touch.h C void emWin_TouchInitialize(const SYS_MODULE_INIT * const init); Returns None. Description This function initializes the emWin Touch Wrapper. Remarks None. Preconditions None. Example EMWIN_TOUCH_INIT touchInit; touchInit.iSysMsg = SYS_MSG_0; emWin_TouchInitialize( &touchInit ); Parameters Parameters Description init Pointer to a data structure containing any data necessary to Initialize the emWin Touch Wrapper. Function void emWin_TouchInitialize( const SYS_MODULE_INIT * const init ) Volume VI: Third-Party Products SEGGER emWin Graphics Library Help GUI and Touch Wrapper Library for SEGGER © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 41 emWin_TouchMailBoxCreate Function Create Mail Box for the touch input messages. File emwin_touch.h C void emWin_TouchMailBoxCreate(); Returns None. Description This function creates Mail Box for the touch input messages. Remarks None. Preconditions The emWin_TouchInitialize function must have been called. Example void APP_Initialize ( void ) { emWin_TouchMailBoxCreate(); } Function void emWin_TouchMailBoxCreate( void ) Touch Wrapper Data Types and Constants EMWIN_TOUCH_INIT Structure Defines the data required to initialize the emWin Touch Wrapper. File emwin_touch.h C typedef struct { SYS_MSG_INSTANCE iSysMsg; } EMWIN_TOUCH_INIT; Members Members Description SYS_MSG_INSTANCE iSysMsg; message system service instance Description emWin Touch Wrapper Initialization Data This data type defines the data required to initialize the emWin Touch Wrapper. Remarks None. Using SEGGER emWin with MPLAB Harmony This section describes using the SEGGER emWin Graphics Library and its utilities with MPLAB Harmony on Microchip development hardware equipped with PIC32 devices. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 42 Description emWin is a third-party graphics library from SEGGER. The graphics library is used to create a GUI application on PIC32-based hardware from Microchip. The library binary and the associated utilities are part of the SEGGER emWin PRO tool suite and are shipped for free with MPLAB Harmony version 1.07 or later under PIC32 license. Important! It is the responsibility of the user to understand and comply with any third party license terms or requirements applicable to the use of such third party software, specifications, systems, or tools. Please consult the MPLAB Harmony Software License Agreement for full details. A PDF copy of the software license agreement is provided in the /doc folder of your installation of MPLAB Harmony. Library Binary The SEGGER emWin Graphics Library binary is located in \bin\framework\gfx\segger_emwin\lib. Linking Applications To link the library binary file, applications require the header files, which are located in \bin\framework\gfx\segger_emwin\inc. Using the Library Binary in an Application To use the emWin library binary in the application, link the library binary to the MPLAB Harmony application and call the library APIs. Supported Features The SEGGER emWin Graphics Library supports the following features: • Bitmaps of different color depths supported • Variety of different fonts are shipped • Ability to define and link new fonts • Ability to show and edit values in decimal, binary, hexadecimal, any font • Window manager support • Widgets support • Input device support (keyboard, mouse, touch) • Any display with any controller supported • Cache support for slower display controllers • Configurable display size • Fast drawing of point, line, circle, and polygon • Different drawing mode SEGGER emWin Utilities Your installation of MPLAB Harmony also provides the following SEGGER emWin utilities from the PRO tool suite, which are located in \ utilities\segger\emwin. • Binary to C Converter • BMP Converter • emWin VNC Client • emWin SPY • emWin Windows View • GUI Builder • JPEG to Movie Converter • Font Converter (Demonstration Setup Executable) • UTF-8 Text to C Converter Refer to SEGGER Utility Tools for more information. The utilities provided in your installation of MPLAB Harmony assist users to: • Design the GUI • Create the graphics resources • Optimize the graphics resources • Monitor the application parameters The output of most of the tools is either a binary file or a C file to be linked with the application code. Please note that the tools can be run only on a host machine with the Windows Operating System. For more information on the SEGGER emWin Graphics Library, its configuration and tools, please refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 43 SEGGER emWin and MPLAB Harmony Integration To run a SEGGER emWin application using MPLAB Harmony on a PIC32 device hardware platform, the following SEGGER emWin modules and MPLAB Harmony modules need to be integrated: • SEGGER emWin application code (generated by SEGGER emWin utilites) • SEGGER emWin Configuration • SEGGER emWin Graphics Library • MPLAB Harmony Display Controller Driver • MPLAB Harmony Messaging System Service • MPLAB Harmony Touch System Service • MPLAB Harmony Touch Controller Driver There are two ways to integrate these modules. One way is to write custom integration wrapper code. Another way is to use the SEGGER emWin Wrapper Library. The Wrapper Library provides a mechanism to integrate these modules. The Wrapper Library is divided into two parts, the GUI Wrapper and the Touch Wrapper. GUI Wrapper The GUI Wrapper code integrates GUI-related SEGGER emWin application code with MPLAB Harmony. It has its own state machine to maintain the GUI states and integrates the following SEGGER emWin and MPLAB Harmony modules: • SEGGER emWin application code • SEGGER emWin configuration • SEGGER emWin Graphics Library • MPLAB Harmony Display Controller Driver Touch Wrapper The Touch Wrapper code integrates touch-related SEGGER emWin application code with MPLAB Harmony and integrates the following SEGGER emWin and MPLAB Harmony modules: • SEGGER emWin Application code • SEGGER emWin Graphics Library • MPLAB Harmony Messaging System Service • MPLAB Harmony Touch System Service • MPLAB Harmony Touch Controller Driver Refer to GUI and Touch Wrapper Library for SEGGER emWin for more information on SEGGER emWin Graphics Library integration with MPLAB Harmony using the Wrapper Library. Getting Started Refer to the Integrating SEGGER emWin and MPLAB Harmony section to get started with designing a GUI using the SEGGER emWin utilities and integrating the GUI with MPLAB Harmony. Configuration Files This section describes the methods and extent of the SEGGER emWin library configurability for the intended processor and application. Some configurations are decided at build time and are not user changeable while some runtime configuration is available to the users. Description The SEGGER emWin Graphics Library is Configurable. The library supports run-time configuration using library APIs and compile-time configuration using library macros. The precompiled library binary is provided in your installation of MPLAB Harmony with certain compile-time configurable macros set. In this case, only run-time configurable parameters can be modified. The configuration macros and APIs need to be defined or called in C header or source files. The configuration C header or source files are either to be manually created or will be generated by MPLAB Harmony Configurator (MHC), based on selection of MHC parameters. The compile-time parameters are located in the GUIConf.h and LCDConf.h header files. The run-time configuration of the library must be done in the C files GUIConf.c, LCDConf.c and GUI_Ex_X.c. If the SEGGER emWin Wrapper Library is selected in MHC, the configuration related files will be generated by the Wrapper Library. The following lists and describes the configuration files. GUI_EX_X.c This C file contains the placeholders of the required timing, logging, and multi-tasking related functions. These functions are called by the SEGGER emWin Graphics Library. GUIConf.c This C file consists of the GUI_X_Config function, which is called by the SEGGER emWin Graphics Library. The GUI_X_Config function is responsible for assigning a memory block to the memory management system. The memory block needs to be accessible 8-, 16-, and 32-bitwise. To pass the memory block to the SEGGER emWin internal memory management system, the GUI_X_Config function must call the GUI_ALLOC_AssignMemory function with the necessary arguments. The memory device uses the memory block passed by the Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 44 GUI_ALLOC_AssignMemory function. GUIConf.h This header file consists of GUI configuration macros. Please note that these macros are fixed at compile-time and and change in the macro values requires recompilation of the SEGGER emWin Graphics Library. GUIConf.h is used to set the following parameters, which are required by the SEGGER emWin Graphics Library during compilation of the library: • Default font • Default color • Default background color • Memory device support • Multi-display or Multi-layer support • Number of layers • Multi-tasking support • Number of tasks • Mouse support • Default skinning support • Window manger support • Window manager transparency support • Rotation support • Cursor support • emWin SPY support • Debug level • Default Memory Copy function • Default Memory Set function • Maximum number of the PID events managed by the input buffer • Maximum number of the key events managed by the input buffer LCDConf.c This C file consists of the LCD_X_Config display configuration function and the display driver callback function, LCD_X_DisplayDriver. These functions are called by the SEGGER emWin Graphics Library. The LCD_X_Config function sets the configuration of the display driver support and sets the run-time configurations for the LCD controller, as follows: • Set the number of buffers for multi-buffer support • Set the display driver parameters and callback functions • Set the color conversion callback functions • Set the custom callback routine for copy operation The LCD_X_DisplayDriver callback function is called by the driver for different tasks. The display driver passes commands for corresponding tasks and a pointer to the command parameters data. Typical commands for the display driver callback are: • LCD controller initialization • LCD ON/OFF • Set layer alpha • Set Color Lookup Table (CLUT) entries • Set virtual screen origin • Set layer position • Set layer size • Set layer visibility • Set video RAM address • Show buffer with given index LCDConf.h This header file consists of general configuration options required for compiling the display driver(s). Please note that these macros are fixed at compile-time and any change in the macro values requires recompilation of the SEGGER emWin Graphics Library. LCDConf.h is used to set the following parameter, which is required by drivers from the SEGGER emWin Graphics Library during compilation of the library: • Display orientation Integrating SEGGER emWin and MPLAB Harmony This section describes the process of integrating SEGGER emWin application code with MPLAB Harmony. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 45 Description The SEGGER emWin application code consists of GUI and graphics resources source code or binary files. The application code needs to be integrated with MPLAB Harmony to run PIC32-based hardware. The SEGGER emWin application code calls SEGGER emWin Graphics library APIs. The SEGGER emWin Graphics Library is a software library and is independent of the underlying hardware. With the help of SEGGER emWin Configuration Source code, MPLAB Harmony performs the I/O task of graphics data generated by SEGGER emWin application code. MPLAB Harmony also passes the pointer input device (PID) data to the SEGGER emWin Graphics Library. The SEGGER emWin Graphics Library recommends implementation of various configuration files to configure the library and LCD interface. To run a SEGGER emWin application using MPLAB Harmony on a PIC32 device hardware platform, the following SEGGER emWin modules and MPLAB Harmony modules must be integrated: • SEGGER emWin application code (generated by SEGGER emWin utilites) • SEGGER emWin Configuration • SEGGER emWin Graphics Library • MPLAB Harmony Display Controller Driver • MPLAB Harmony Messaging System Service • MPLAB Harmony Touch System Service • MPLAB Harmony Touch Controller Driver There are two ways to integrate these modules. One way is to write custom integration wrapper code. Another way is to use the SEGGER emWin Wrapper Library. The Wrapper Library provides a mechanism to integrate these modules. The Wrapper Library is divided into two parts, the GUI Wrapper and the Touch Wrapper. GUI Wrapper The GUI Wrapper code integrates GUI-related SEGGER emWin application code with MPLAB Harmony. It has its own state machine to maintain the GUI states and integrates the following SEGGER emWin and MPLAB Harmony modules: • SEGGER emWin application code • SEGGER emWin configuration • SEGGER emWin Graphics Library • MPLAB Harmony Display Controller Driver Touch Wrapper The Touch Wrapper code integrates touch-related SEGGER emWin application code with MPLAB Harmony and integrates the following SEGGER emWin and MPLAB Harmony modules: • SEGGER emWin Application code • SEGGER emWin Graphics Library • MPLAB Harmony Messaging System Service • MPLAB Harmony Touch System Service • MPLAB Harmony Touch Controller Driver Refer to GUI and Touch Wrapper Library for SEGGER emWin for more information on SEGGER emWin Graphics Library integration with MPLAB Harmony using the Wrapper Library. For more information on adding content to the template, please refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. Wrapper Libraries There are multiple ways to design and implement a GUI using the SEGGER emWin Graphics Library. One way is to use the GUIBuilder utility. GUIBuilder can be used to design a GUI in form of dialogs. This utility also generates the C code implementing the designed dialogs. To integrate the generated dialog code and to maintain the state machine calling the dialog, MPLAB Harmony provides the GUI Wrapper Library. The GUI Wrapper library state machine performs: • Initialization of the SEGGER emWin Graphics Library • Initialization of the dialog • Calls the dialog based on events or external input Similarly, a Touch Wrapper Library is provided by MPLAB Harmony to: • Initialize the touch interface • Decode the touch input • Encode the touch input • Pass the encoded touch input to the SEGGER emWin Graphics Library. The following diagram shows the work flow of SEGGER emWin and MPLAB Harmony integration using the GUI and Touch Wrapper Libraries: Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 46 As shown in the diagram, the emWin GUI files are passed to MPLAB Harmony application. The emWin GUI files may consist of dialog files generated by GUIBuilder and graphics resource files generated by other SEGGER emWin utilities. Please note that these files need to be manually copied and added to the MPLAB Harmony project. The C code from these files is integrated by calling the appropriate GUI wrapper API. The templates for emWin configuration files such as GUI_Ex_X.c, GUIConf.c, LCDConf.c, GUIConf.h, and LCDConf.h, are generated by the GUI Wrapper Library. These configuration files may need further editing to configure the GUI and LCD based on application requirements. The Touch Wrapper Library can be integrated with the MPLAB Harmony application by calling the appropriate Touch Wrapper API. Other MPLAB Harmony modules are integrated by selecting the corresponding BSP in MHC or by selecting required modules separately. MPLAB Harmony Configurator (MHC) This section provides information about configuring MHC for the SEGGER emWin Graphics Library. Description To add the Touch wrapper Library, select “Use SEGGER emWin Touch Wrapper?” in MHC. To further configure the Touch Wrapper Library, set a suitable value for “System Message Service Instance” from the list of values in MHC. The value of the “System Message Service Instance” must be same as the instance of System Message Service selected in MHC for Touch input. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 47 To add the GUI wrapper Library, select “Use SEGGER emWin GUI Wrapper?” in MHC. To further configure the GUI Wrapper Library, set suitable value for “Memory Block Size” and “Number of Screens”. The “Memory Block Size” configuration value represents the size of the memory block assigned to the SEGGER emWin internal memory management system. The memory block is created by defining a static array of a size defined by the “Memory Block Size” configuration value. This memory block is passed to the GUI_ALLOC_AssignMemory function within the GUIConf.c file. Please note the size is bytes and must be 8-, 16-, or 32-bit accessible. The “Number of Screens” configuration value is used to define the array size of dialog creation function. This array is used by the GUI Wrapper to call the appropriate dialog creation function based on the array index. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 48 LCD Integration This topic provides information on LCD integration. Description LCD integration requires the SEGGER emWin Graphics Library to interact with the display controller driver driving the LCD. Generally, there are two types of display controllers: • Display controller with direct interface • Display controller with indirect interface In both cases, the display controller driver is integrated with the SEGGER emWin Graphics Library through the LCDConf.c C file and the LCDConf.h header file. The method of integrating the display controller driver varies with the type of display controller driver. For a display controller with a direct interface, the SEGGER emWin Graphics Library can directly write to and read from the video memory. The video memory can be within the system memory or within the display controller (CPU addressable using address bus). The information required when configuring the direct interface type display controller is about the address range and bus width to the display controller. The interface of the direct interface drivers needs to be created and linked with the SEGGER emWin Graphics Library using the GUI_DEVICE_CreateAndLink function. Further configured is needed by specifying the address of the video memory using the LCD_SetVRAMAddrEx function. If the driver supports more operations, these operations can be registered using the GUI_DEVICE_CreateAndLink function. To achieve this, pass the supported operations through the GUI_DEVICE_API parameter of the GUI_DEVICE_CreateAndLine function. The LCDConf.c code shows a simple example of the configuration of Microchip’s Low-Cost Controllerless (LCC) driver from MPLAB Harmony for PIC32 devices. The code example also shows that GUIDRV_LIN_16 driver functions and GUICC_M565 color conversion functions are registered using the GUI_DEVICE_CreateAndLink function. The GUIDRV_LIN_16 driver API structure is used as the MPLAB Harmony LCC driver structure, which is different from the driver structure required by the SEGGER emWin Graphics Library. The LCC driver returns the video memory address, which is further passed to the SEGGER emWin Graphics Library using the LCD_SetVRAMAddrEx function. Other functions, such as LCD_SetSizeEx and LCD_SetVSizeEx, are used to configure the size of the visible area and virtual area in the vertical and horizontal direction. Configuring the display controller with indirect interface is more complex than with the direct interface. /********************************************************************* * * LCD_X_Config * * Purpose: * Called during the initialization process in order to set up the * display driver configuration. * */ void LCD_X_Config(void) { uintptr_t bufferAddr; GUI_DEVICE_CreateAndLink( GUIDRV_LIN_16, GUICC_M565, 0, 0); if (LCD_GetSwapXY()) { LCD_SetSizeEx (0, DISP_VER_RESOLUTION, DISP_HOR_RESOLUTION); LCD_SetVSizeEx(0, DISP_VER_RESOLUTION, DISP_HOR_RESOLUTION); } else { LCD_SetSizeEx (0, DISP_HOR_RESOLUTION, DISP_VER_RESOLUTION); LCD_SetVSizeEx(0, DISP_HOR_RESOLUTION, DISP_VER_RESOLUTION); } bufferAddr = (uintptr_t) DRV_GFX_LCC_GetBuffer(); LCD_SetVRAMAddrEx( 0, ( void * )bufferAddr ); return; } /********************************************************************* * * LCD_X_DisplayDriver * * Purpose: * To support the according task the routine needs to be adapted to * the display controller. * Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 49 * Parameter: * LayerIndex - Index of layer to be configured * Cmd - Please refer to the details in the switch statement below * pData - Pointer to a LCD_X_DATA structure * * Return Value: * < -1 - Error * -1 - Command not handled * 0 - Ok */ int LCD_X_DisplayDriver(unsigned LayerIndex, unsigned Cmd, void * pData) { int retVal = -1; switch( Cmd ) { case LCD_X_INITCONTROLLER: { retVal = 0; break; } default: { retVal = -1; break; } } return retVal; } Touch Integration This topic provides information on touch integration. Description The SEGGER emWin widgets respond to the pointer input device (PID) event based on the area where the event occurs. If the area falls within the widget area, the widget will react by modifying the predefined or custom widget properties. For example, if the user touches the touch screen within the area of an on-screen button, the button will change its properties, such as color or image. To do this, the location of touch needs to be registered with the SEGGER emWin Graphics Library on the touch event. The MPLAB Harmony Touch System Service will send a message on the touch event. The message will contain the description of the event and the coordinates of touch input. The messages from the Touch System Service need to be decoded and passed to the SEGGER emWin Graphics Library. The implementation of decoding the touch message and registering the touch input with the SEGGER emWin Graphics Library is already provided in the SEGGER emWin Touch Wrapper Library. The following code example shows how the Touch Wrapper Library initializes the Messaging System Service by creating the mailbox, decodes the touch message from the Touch System Service, and registers the decoded touch input with the SEGGER emWin Graphics Library. /* Initialize Message System Service by creating a Mail box */ void emWin_TouchMailBoxCreate( void ) { emWinTouchData.hMsgType = SYS_MSG_TypeCreate ( emWinTouchData.iSysMsg, TYPE_TOUCHSCREEN , 0 ); emWinTouchData.hMailbox = SYS_MSG_MailboxOpen( emWinTouchData.iSysMsg, (SYS_MSG_RECEIVE_CALLBACK) &_emWin_TouchMessageCallback ); SYS_MSG_MailboxMsgAdd( emWinTouchData.hMailbox, emWinTouchData.hMsgType ); return; } In the following code example, iSysMsg is the instance of the Messaging System Service selected in MHC. The _emWin_TouchMessageCallback function is a callback function that decodes the touch message and also registers the touch input using the GUI_TOUCH_StoreStateEx function. /* Decode Touch Message and register the touch input with SEGGER emWin Library */ static void _emWin_TouchMessageCallback( SYS_MSG_OBJECT *pMsg ) { GUI_PID_STATE * pidState = NULL; Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 50 if( NULL == pMsg ) { return; } if( TYPE_TOUCHSCREEN != pMsg->nMessageTypeID ) { return; } pidState = &emWinTouchData.pidState; if( EVENT_INVALID == pMsg->param0 || EVENT_MOVE == pMsg->param0 ) { return; } if( EVENT_PRESS == pMsg->param0 || EVENT_STILLPRESS == pMsg->param0 ) { pidState->Pressed = 1; } else { pidState->Pressed = 0; } pidState->Layer = 0; pidState->x = pMsg->param1; pidState->y = pMsg->param2; GUI_TOUCH_StoreStateEx( pidState ); return; } For more information on configuring the driver using LCDConf.c, please refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. SEGGER emWin Event Handling This section describes the different ways of event handling between MPLAB Harmony and a SEGGER emWin application. Description There are different ways in which an application may need to react to different events. Events can be internal events generated by the SEGGER emWin Graphics Library on touch input, or it can be an external event triggered by a button press from the demonstration hardware. Event Handling Under Same Parent Widget This is a common scenario of a GUI, where an event generated by one widget, changes the behavior of another widget from the same screen. Both widgets are under the common parent dialog widget. To do this, on the notification of event from one widget, get the handle of the other widget and use relevant APIs to modify the behavior of the other widget. For example, we will take into account a parent widget as the Framewin widget. There are two widgets under the Framewin widget: Spinbox and Slider. The following figure shows the example screen of this scenario. After designing this GUI using GUIBuilder and saving it as C file, the generated C file needs to be edited to add the corresponding events. To Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 51 change the value of the spin box by moving the slider, do the following: 1. Open the C file generated by GUIBuilder in MPLAB X IDE. 2. Navigate to the _cbDialog function. 3. Below the notification message for the slider, WM_NOTIFICATION _VALUE_CHANGED, add the following code: /* Get the handle of the Slider */ hItem = WM_GetDialogItem(pMsg->hWin, ID_SLIDER_0); /* Get the current value of the Slider */ value = SLIDER_GetValue(hItem); /* Get the handle of the Spinbox */ hItem = WM_GetDialogItem(pMsg->hWin, ID_SPINBOX_0); /* Set the spinbox value with slider value */ SPINBOX_SetValue(hItem, value); The following code shows the updated dialog file. case ID_SLIDER_0: // Notifications sent by 'Slider' switch(NCode) { case WM_NOTIFICATION_CLICKED: // USER START (Optionally insert code for reacting on notification message) // USER END break; case WM_NOTIFICATION_RELEASED: // USER START (Optionally insert code for reacting on notification message) // USER END break; case WM_NOTIFICATION_VALUE_CHANGED: // USER START (Optionally insert code for reacting on notification message) /* Get the handle of the Slider */ hItem = WM_GetDialogItem(pMsg->hWin, ID_SLIDER_0); /* Get the current value of the Slider */ value = SLIDER_GetValue(hItem); /* Get the handle of the Spinbox */ hItem = WM_GetDialogItem(pMsg->hWin, ID_SPINBOX_0); /* Set the spinbox value with slider value */ SPINBOX_SetValue(hItem, value); // USER END break; // USER START (Optionally insert additional code for further notification handling) // USER END } break; Event Handling Under Different Parent Widgets This scenario occurs when a widget under one parent widget changes behavior of a widget under another parent widget. The two parent widgets are referred to as P1 and P2. The child widgets under parent widgets P1 and P2, are referred to as C1 and C2, respectively. There are two possible cases based on whether parent widget P2 exists at the time of an event generated by C1: • A) P2 parent widget does not exists • B) P2 parent widget exists For case A, the properties of child widget C2 need to be initialized based on the state of child widget C1. For case B, the properties of the child widget C2 can be changed on an event generated by child widget C1. The following section discusses both case A and case B in further detail. Parent Widget P2 Does Not Exist In this example, we have two parent widgets, Dialog1 widget and Dialog2 widget. The Dialog1 parent widget has two child widgets: a check box and a button. Similarly, the Dialog2 parent widget has two child widgets: text and a button. The following figures show examples of both dialogs: Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 52 In this example, to navigate from Dialog1 to Dialog2 the Next button from Dialog1 must be pressed. Similarly, to navigate from Dialog2 to Dialog1 the Previous button from Dialog2 must be pressed. The example starts with Dialog1. Dialog2 will be created only after pressing the Next button in Dialog1. The goal of this example is to change the text from Dialog2 using the check box from Dialog1. By default, the check box from Dialog1 will be clear (i.e., not checked). If the check box remains clear and demonstration is navigated from Dialog1 to Dialog2, the text will have the value value “Disabled”. If the check box from Dialog1 is selected (i.e., checked), on navigating from Dialog1 to Dialog2, the text will have the value “Enabled”. To achieve these results, the text widget from Dialog2 needs to be initialized with a value based on the state of the check box widget from Dialog1. During initialization of the text widget from Dialog2, if the state of the check box widget from Dialog1 is selected, set the value of the text from Dialog2 as “Enabled”; otherwise, set it as “Disabled”. The following code example shows the Dialog2 file generated by GUIBuilder. The file is further edited to add custom initialization code for the text widget. // // Initialization of 'Text_1' // hItem = WM_GetDialogItem(pMsg->hWin, ID_TEXT_0); TEXT_SetTextAlign(hItem, GUI_TA_HCENTER | GUI_TA_VCENTER); TEXT_SetTextColor(hItem, GUI_MAKE_COLOR(0x00000000)); TEXT_SetFont(hItem, GUI_FONT_13B_1); // USER START (Optionally insert additional code for further widget initialization) /* Get handle of checkbox widget from Dialog1 using Dialog1 handle and checkbox widget id. */ hItem = WM_GetDialogItem(hDialog1, 0x802); /* If checkbox is checked set text value to "Enabled" */ if(CHECKBOX_IsChecked(hItem)) { hItem = WM_GetDialogItem(pMsg->hWin, ID_TEXT_0); TEXT_SetText(hItem, "Enabled"); } /* else set text value to "Disabled" */ else { hItem = WM_GetDialogItem(pMsg->hWin, ID_TEXT_0); TEXT_SetText(hItem, "Disabled"); } Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 53 // USER END Parent widget P2 exists To describe this scenario, we will continue to use the previous example of Dialog1 and Dialog2. In the previous example, we have seen initialization of the properties widget C2 based on an event generated by widget C1, while P2 was not in existence at the time C1 generated the event. Both widgets, C1 and C2, are from different parent widgets, P1 and P2, respectively. Once the demonstration navigates from Dialog1 to Dialog2 for the first time, both parent widgets, Dialog1 and Dialog2, will come into existence and will be persistent until the widgets are destroyed. In such a case, to change the property of widget C2 based on an event generated by widget C1, the code required to change the property of widget C2 needs to be added under the widget C1 event handling code. In the previous example, at first, the check box from Dialog1 was selected to change the text value from Dialog2. To demonstrate the scenario where P2 now exists, the demonstration must navigate back to Dialog1 using the “Previous” button from Dialog2, clear the checked check box from Dialog1, and navigate back to Dialog2 using the “Next” button from Dialog1. The text value from Dialog2 will still be “Enabled”. Please note that both Dialog1 and Dialog2 were already created and persistent. Navigating from Dialog1 to Dialog2 will not reinitialize the widgets, as Dialog2 and its child widgets are persistent. To change the value of existing widget text from Dialog2, the TEXT_SetText function must be called under event handler code of the widget check box from Dialog1. Once the suitable code is added, the text from Dialog2 will follow the check box selection from Dialog1. Anytime the check box from Dialog1 is cleared, the text from Dialog2 will reflect the value as “Disabled”. If the check box is selected, the text will reflect the value as “Enabled”. The following code example shows the required code under check box event handler from Dialog1. case WM_NOTIFY_PARENT: Id = WM_GetId(pMsg->hWinSrc); NCode = pMsg->Data.v; switch(Id) { case ID_CHECKBOX_0: // Notifications sent by 'Checkbox_1' switch(NCode) { case WM_NOTIFICATION_CLICKED: // USER START (Optionally insert code for reacting on notification message) // USER END break; case WM_NOTIFICATION_RELEASED: // USER START (Optionally insert code for reacting on notification message) // USER END break; case WM_NOTIFICATION_VALUE_CHANGED: // USER START (Optionally insert code for reacting on notification message) /* If the Dialog2 handle is valid change the properties text widget from Dialog2 */ if(hDialog2) { hItem = WM_GetDialogItem(pMsg->hWin, ID_CHECKBOX_0); /* If checkbox from Dialog1 is checked Set the text value from Dialog2 to Enabled */ if(CHECKBOX_IsChecked(hItem)) { hItem = WM_GetDialogItem(hDialog2, 0x808); TEXT_SetText(hItem, "Enabled"); } /* Otherwise set the text value from Dialog2 to Disabled */ else { hItem = WM_GetDialogItem(hDialog2, 0x808); TEXT_SetText(hItem, "Disabled"); } } // USER END External Event Handling This section describes the method of changing widget properties based on external events. External events can be a button press or an interrupt generated by a peripheral, etc. Based on the external event, properties of targeted widgets are changed. For example, consider a dialog widget as a parent widget with a progress bar as the child widget. The goal of the demonstration is to increment the progress bar value with a hardware button press. The following figure shows the demonstration screen. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 54 It can be observed that at the center of the screen a progress bar is drawn. To change the value of the progress bar on an external event, such as a hardware button press, use the PROGBAR_SetValue function. In this example. to detect the button press of a button from demonstration hardware, the MPLAB Harmony BSP function, BSP_SwitchStateGet, is used. The following code example shows usage of these functions. static int32_t value = 0; /* Verify if button is pressed and valid handle of Dialog containing progress bar is available */ if( BSP_SWITCH_STATE_PRESSED == BSP_SwitchStateGet( BSP_SWITCH_S1 ) && hDialog) { /* Get the handle of Progress bar */ hItem = WM_GetDialogItem( hDialog, 0x801 ); /* Update the value of Progress bar */ PROGBAR_SetValue( hItem, value++); } GUI Resource Management This section describes effective management of GUI resources of the SEGGER emWin Graphics Library. Description The various GUI resources are images, fonts, video streams, etc. The images can be of different types, such as uncompressed bitmap images, images compressed using lossless compression methods, or images compressed using lossy compression methods. Bitmap images can have different types of pixel color formats, such as raw BGR (Blue, Green, and Red) 888, or palletized formats. The bitmap formats containing the raw pixel color format BGR888 will take 1 byte for each color, and eventually, will take 3 bytes for each pixel. Based on the image size, the memory requirement will vary. If image size grows, the memory size required to store the image will also grow. The following example shows the calculation of memory size required for the image. Considering image dimensions in pixels with Image Width = 480 and Image Height = 272, if the color format is BGR888, the size of memory required to store the pixel data will be: Image Size (in bytes) = Image Width x Image Height x Bytes Per Pixel = 480 x 272 x 3 = 391680 bytes. Please note that in this calculation the image header size is ignored. The size of Image is accountable considering the RAM memory size of an embedded system device, which could be in form of 10s of KBytes. There are different methods to handle this scenario, as follows: a) Reduce the size of Image by changing the color format b) Reduce the size of Image by applying compression c) Moving Image to Program Flash memory d) Moving Image to external Flash memory Reducing Image Size by Changing the Color Format In this method, the color format of Image is modified to reduce the size of the image. As seen in the previous formula to calculate the Image size, one of the contributing factors to the image size is: Bytes Per Pixel. To be able to reduce the number of bytes required for storing one pixel, Image size can be reduced. For example, with color format BGR888, the image size in bytes is calculated as 391680 bytes. The same image with a color format of RGB565 will take 261120 bytes. Please note for color format RGB565 it takes 2 bytes for each pixel. Similarly, further reduction in the number bytes required for each pixel, the image size will reduce in proportion. Also note for palletized formats, a few more bytes are required to store the color table. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Using SEGGER emWin with MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 55 Please note that a reduction in the number of bytes required per pixel will reduce the number of colors from image and will affect the image quality, as well. The reduction of the number of colors can be decided based on the number of different colors available in the image and size of the image. For smaller images, the reduction in the number of colors from Image may not be visible, allowing reduction in memory requirements for storing such an image. SEGGER emWin provides the Bitmap Converter utility to achieve the change in color format and saving the image as a C file. The C file can be further linked with the application code. The SEGGER emWin Graphics Library supports drawing of images edited by the Bitmap Converter using the library APIs. For more information on using the Bitmap Converter to change the image format and on the APIs to access the image data, refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. Reduce Image Size by Applying Compression There are various compression algorithms available, which can help reduce the size of the image. The size of the image is reduced by compressing the image data. The compression can be lossless compression or lossy compression. The Bitmap Converter utility can apply the lossless compression algorithm, such as RLE, and the lossy compression algorithm, such as JPEG. The original image size to compressed image size ratio (compression ratio) varies with the image pixel data and applied algorithm. The JPEG algorithm will be more efficient in terms of the compression ratio, but will be less efficient in terms of image quality, as the JPEG algorithm is a lossy compression algorithm. The SEGGER emWin Graphics Library supports drawing of RLE or JPEG compressed images by using suitable library APIs. For more information on using the Bitmap Converter utility to change the image format, refer to the "emWin Graphic Library with Graphical User Interface User and Reference Guide", document UM03001, which is available for download from the SEGGER website at: https://www.segger.com/downloads/emwin. Moving an Image to Program Flash Memory The static image or font data can be placed in the directly accessible memory such as program Flash. The data is placed in directly accessible memory such as program Flash using compiler attribute commands or in some cases by defining static data as const. The XC32 compiler for PIC32 devices places the data into directly accessible program flash memory if the data is defined as const. The only disadvantage in this case is that the program flash size is now reduced by the size of image or font data. By default, SEGGER emWin tools define the image or font data as const or as GUI_CONST_STORAGE. The SEGGER emWin library for PIC32 defines the GUI_CONST_STORAGE as const. Start-to-End Example of SEGGER emWin Graphics with MPLAB Harmony This section provides getting started information for developing a Graphical User Interface (GUI) application using SEGGER emWin and integrating it with MPLAB Harmony on PIC32 development hardware. This process is demonstrated in the emwin_quickstart application under the apps/gfx/ directory that comes with the harmony installation. Refer to the emwin_quickstart application help under apps/gfx/emwin_quickstart. Description In this demonstration we will create two screens/dialog boxes. Screens/dialog boxes are windows that contain one or more widgets. Widgets are elements of the user interface, which react automatically on certain events. Please note that the terms screens and dialogs are used interchangeably in this section. The screen is designed using the GUIBuilder utility. The following figure shows the final screens that will be designed: The demonstration application will navigate from one screen to another screen using buttons on the screen. The demonstration will use the Next button to navigate from the HomeScreen to Screen2 and the Previous button to navigate from Screen2 to the HomeScreen. The buttons will generate an event on a touch input from the display. There are other vital SEGGER emWin tools available in the \utilities\segger\emwin folder of your MPLAB Harmony installation (see SEGGER Utility Tools for more information). This demonstration uses only the GUIBuilder utility to provide a glimpse of how to create and run a SEGGER emWin GUI project within MPLAB Harmony. Also, the widgets used here are the simpler ones limiting the steps required to create a GUI. Hardware Requirements This section provides information about the development hardware used in the demonstration. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 56 Description The demonstration uses the Microchip PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit and the Multimedia Expansion Board II (MEB II). PIC32MZ EF Starter Kit (DM320007) The PIC32MZ EF Starter Kit has an on-board 200 MHz PIC32MZ2048EF144 microcontroller with 2 MB Flash, 512 KB RAM and a Floating Point Unit (FPU). It contains an I2C communication peripheral to work with the touch controller. The PIC32MZ EF Starter Kit uses the Low-Cost Controllerless (LCC) driver to drive the the MEB II display without the need of a separate graphics controller. MEB II (DM320005-2) The MEB II consists of 4.3” WQVGA PCAP touch display daughter board and optional EBI SRAM memory. The resolution of the display on the 4.3” WQVGA PCAP touch display is 480 x 272 pixels, which also consists of a MTCH6301 Touch Controller. Software Requirements This section describes the software requirements of the SEGGER emWin application with MPLAB Harmony. Description The demonstration described in the Getting Started section uses the following development environment: • MPLAB X IDE v3.26 or later (http://www.microchip.com/mplab/mplab-x-ide) • MPLAB XC32 C/C++ Compiler v1.40 or later (http://www.microchip.com/mplab/compilers) • MPLAB Harmony v1.08 or later (http://www.microchip.com/mplab/mplab-harmony) • MPLAB Harmony Configurator v1.0.8.6 or later (install-dir>\utilities\mhc) • GUIBuilder v5.32 or later (install-dir>\utilities\segger\emwin) SEGGER emWin GUI Application Design Process This section describes the process to design and run the SEGGER emWin GUI application. Description The process to design and run the GUI on the demonstration board includes the following: • Configuring the Hardware • Using GUIBuilder to Create Screens/Dialogs • Creating a New MPLAB Harmony Project • Loading the GUIBuilder Output into the MPLAB Harmony Project • Integrating the GUIBuilder Output with MPLAB Harmony • Build and Program the Application • Demonstration Output Configuring the Hardware This section describes how to set up the development hardware for the demonstration. Description Setting up the development hardware includes the following four steps: 1. Jumper Settings: Short the pins, EBIWE and LCD_PCLK, of Jumper J9 on the MEB II. Shorting the pins will allow the WE pin of the EBI peripheral to be used as the pixel clock of the display for the LCC driver with internal frame buffer configuration. 2. Power Supply: Connect the Power supply to the 9V-15V DC Connector on the MEB II. 3. Connecting starter kit to the MEB II: Connect the PIC32MZ EF Starter Kit onto the 168-pin Hirose connector on the MEB II. 4. Connecting the MPLAB REAL ICE: Connect the MPLAB REAL ICE using the RJ12 connector on the MEB II. Using GUIBuilder to Create Screens/Dialog Boxes This section provides an example of Screen/Dialog box design by using the GUIBuilder utility. Description The GUIBuilder utility is a tool for creating dialogs without any knowledge of the C programming language. Instead of writing source code, the widgets can be placed and sized by drag and drop. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 57 GUIBuilder Interface As shown in the following figure, the GUIBuilder Utility window is divided into five areas: • Menu bar • Widget selection bar • Object tree • Widget properties • Editor Steps to Design a Screen 1. Start the GUIBuilder utility. 2. To create a screen/dialog, add a parent widget. Add a Framewin widget by clicking Framewin Dialog from the widget selection bar. The new widget will appear in the top left corner of the Editor pane, as shown in the following figure. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 58 3. Next, we will modify the properties of the Framewin widget. Do the following to edit the name of the widget: • Click the cell containing the text “Framewin” • Replace the text “Framewin” with “HomeScreen” • This screen widget needs to cover the complete display (Resolution 480x272) of the demonstration board. Resize the screen by editing the value of xSize and ySize property of the widget to 480 and 272, respectively. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 59 4. Add text to the screen by clicking the Text widget from widget selection bar, as shown in the following figure. 5. Edit the properties of the text, as follows: • Right click the Text widget box and select Set Text Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 60 • Click the Content cell and change the value to MPLAB Harmony • Change the position of the text widget by setting the value of properties xPos and yPos to 200 and 50, respectively 6. From the widget selection bar, add a button widget by clicking Button. The Button widget appears in the left top corner of the HomeScreen screen/dialog, as shown in the following figure. 7. Edit the properties of Button widget, as follows: • Right click the button from the HomeScreen screen and select Set Text • Set the properties of the button widget xPos, yPos, xSize, ySize, and Text to 400, 180, 60, 60, and Next, respectively. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 61 8. Save the screen design by selecting File > Save from the Menu bar. Alternately, you can also use the keyboard shortcut Ctrl + S to save the project. By default, this will save the screen/dialog design as the C file HomeScreenDLG.c at same location as GUIBuilder. The following figure shows the designed screen/dialog. 9. Next, create another screen using two widgets: Framewin and Button with the properties of each widget as follows: • Framewin widget properties • Button widget properties The designed screen will look like the following figure. By default, saving this screen will generate a file named Screen2DLG.c at the same location as GUIBuilder. Creating a New SEGGER emWin Application Within MPLAB Harmony This section describes the process of creating a new SEGGER emWin application within MPLAB Harmony Description Creating the Application The following steps describe how to create a new SEGGER emWin Graphics application within MPLAB Harmony. This MPLAB Harmony application uses the screen/dialog C files that were created in GUIBuilder Example. 1. Open MPLAB X IDE and create a new project by selecting File > New Project. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 62 2. Choose the project type 32-bit MPLAB Harmony Project, and then click Next. 3. Specify the Name and Location project details, as shown in the following figure: • Harmony Path: Specify the path to your installation of MPLAB Harmony (i.e., ) • Project Location: \apps\gfx • Project Name: emwin_app • Configuration Name: pic32mz_ef_sk_meb2 • Target Device: PIC32MZ2048EFM144 • Click Finish Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 63 4. Once the new project is created in MPLAB X IDE, right click the project and select Set as Main Project. This will apply all future actions to this application in case multiple applications are open. 5. Project properties such as Hardware Tools and Compiler Toolchains need to be set, as shown in the following figure: • Right click the project and select Properties • Select the desired Hardware Tools and Compiler Toolchains • Click Apply, and then click OK 6. Start MHC by selecting Tools > Embedded MPLAB Harmony Configurator. It is assumed that the MHC plug-in is installed in MPLAB X IDE from the location \utilities\MHC. MHC will run only if at least one of the projects is set as the Main Project. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 64 7. In MHC, select the desired Board Support Package (BSP) for the hardware platform, as shown in the following figure: • Expand BSP Configuration and select Use BSP? • Expand Select BSP to Use For PIC32MZ2048EFM144 Device and select PIC32MZ EF Starter Kit w\ Multimedia Expansion Board (MEB) II 8. Select the Clock Diagram tab and configure the following clock settings: • Primary Oscillator Frequency • PLL Clock Source • PLL Divider values • Primary Oscillator Mode Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 65 9. From the Options tab expand Harmony Framework Configuration > Graphics Library > SEGGER emWin Graphics Library and select Use SEGGER emWin Graphics Library?. 10. Based on the BSP selected, the required drivers are selected for the devices including display timing controller, display controller, Touch driver and Touch Bus (I2C) driver. 11. For the MEB II, the touch device (MTCH6301) reports available touch input by raising an external interrupt. The external interrupt pin needs to be mapped from the list of available pins. In this case, RE8 is the correct pin. To map the RE8 pin as an external interrupt pin do the following: • Select the “Pin Table” tab and scroll down the pin table until the external interrupt tab appears Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 66 • Right click the External Interrupt 1 tab and select Isolate • In the External Interrupt 1 row select the RE8 pin to map it as External Interrupt 1 by clicking the blue block beneath RE8 Generate the Code All of required hardware configuration for our demonstration has been selected. It is now time to generate the demonstration hardware related application code. Use the following steps to generate the code: 1. In MHC, click Generate Code. 2. Next, in the Modified Configuration dialog, click Save to save the modified configuration. 3. Then, in the Generate Project dialog, click Generate. This will generate the code for BSP, Drivers, System Services, Configuration, and the application template at the corresponding branch of the application directory tree. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 67 4. MHC will also add the SEGGER emWin Library binary file, emwin.a. to the Libraries folder. Loading the GUIBuilder Output into the MPLAB Harmony Project This section describes the loading of the GUIBuilder output (C files) into your MPLAB Harmony project. Description Perform the following steps to load the previously created screens to your MPLAB Harmony project. 1. Create a folder named emwin_gui with the project path: \ apps\gfx\emwin_app\firmware\src. 2. Copy the GUIBuilder generated files, HomeScreenDLG.c and Screen2DLG.c, that you created in Using GUIBuilder to Create Screens/Dialogs from the location of the GUIBuilder utility to the path: \ apps\gfx\emwin_app\firmware\src\emwin_gui. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 68 3. Create a logical folder named emwin_gui with the project tree location Source Files > app, as follows: • Expand Source Files • Expand app • Right click on the logical folder named app • Click New Logical Folder • Right click the newly created logical folder • Click Rename… • Replace the default name with emwin_gui • Click OK 4. In MPLAB X IDE, add the GUIBuilder generated HomeScreenDLG.c and Screen2DLG.c files to the project, as follows: • Right click the new logical folder emwin_gui • Click Add Existing Item… • Navigate to the folder \ apps\gfx\emwin_app\firmware\src\emwin_gui using the Look in: tab from the Select Item window • Select the files HomeScreenDLG.c and Screen2DLG.c • Click Select Integrating the GUIBuilder Output with MPLAB Harmony This section describes the integration of SEGGER emWin application code with MPLAB Harmony using the MPLAB Harmony GUI and Touch Wrapper Library. Description The emWin Wrapper Library consist of wrapper for GUI and Touch. Each wrapper need to be enabled and configured using MHC. Use the following steps to enable and configure the wrapper library: 1. In MHC, select the Options tab. 2. Enable the SEGGER emWin Touch Wrapper Library by expanding Third Party Libraries > Graphics and selecting Use SEGGER emWin Graphics Library. Then, expand SEGGER emWin Graphics Library and select Use SEGGER emWin Touch Wrapper?. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 69 3. Enable the GUI Wrapper Library by selecting Use SEGGER emWin GUI Wrapper?. 4. Configure the GUI Wrapper Library by expanding emWin GUI Wrapper and setting the Number of Screens to 2. 5. Generate the code by using steps similar to those from Loading the GUIBuilder Output into the MPLAB Harmony Project. The code generation will add the following files: • emwin_gui_static.c • emwin_touch_static.c • GUI_X_Ex.c • GUIConf.c • GUIConf.h • LCDConf.c • LCDCong.h Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 70 6. The generated files will be added to the project at: Source Files\app\system_config\pic32mz_ef_sk_mebii\third_party\gfx\emwin. 7. In MPLAB X IDE, edit the app.c file from Source Files\app, as follows: • Add a global variable: /* Add create screens APIs from HomeScreenDLG.c and Screen2DLG.c to array of screens */ EMWIN_GUI_SCREEN_CREATE emWinScreenCreate [ EMWIN_GUI_NUM_SCREENS ] = { CreateHomeScreen, CreateScreen2 }; • Add a local function: /* Screen Initialize function */ void APP_ScreenInitialize ( void ) { /* Set the Background to black */ GUI_SetBkColor( GUI_BLACK ); /* Clear the screen */ GUI_Clear(); } • Add initialization code to the APP_Initialize function: void APP_Initialize ( void ) { /* Place the App state machine in its initial state. */ appData.state = APP_STATE_INIT; int32_t screenCount = 0; /* Create MailBox for Touch Input */ emWin_TouchMailBoxCreate(); /* Register Screen Initialization */ emWin_GuiScreenInitializeRegister( APP_ScreenInitialize ); /* Register Screens from screen array */ for( screenCount = 0; screenCount < EMWIN_GUI_NUM_SCREENS; screenCount++ ) { emWin_GuiScreenRegister( screenCount, emWinScreenCreate[screenCount]); } /* set the start screen to 0 */ emWin_GuiStartScreenSet ( 0 ); } 8. Add the following code to app.h, which is located in Header Files\app: Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 71 // ***************************************************************************** // ***************************************************************************** // Section: Application Callback Routines // ***************************************************************************** // ***************************************************************************** WM_HWIN CreateHomeScreen(void); WM_HWIN CreateScreen2(void); 9. Make the following additions to HomeScreenDLG.c, which is located in Source Files\app\emwin_gui: • Add the following code with additional includes: // USER START (Optionally insert additional includes) #include "system_config.h" #include "system_definitions.h" // USER END • Add the following code within case WM_NOTIFICATION_CLICKED for the ID_BUTTON_0: emWin_GuiScreenChange(1); 10. The updated code will appear as follows: switch(Id) { case ID_BUTTON_0: // Notifications sent by 'Button' switch(NCode) { case WM_NOTIFICATION_CLICKED: // USER START (Optionally insert code for reacting on notification message) emWin_GuiScreenChange(1); // USER END break; 11. Make the following additions to Screen2DLG.c, which is located in Source Files\app\emwin_gui: • Add the following code within additional includes: // USER START (Optionally insert additional includes) #include "system_config.h" #include "system_definitions.h" // USER END • Add the following code within case WM_NOTIFICATION_CLICKED for the ID_BUTTON_0: emWin_GuiScreenChange(0); 12. The updated code will appear as follows: switch(Id) { case ID_BUTTON_0: // Notifications sent by 'Button' switch(NCode) { case WM_NOTIFICATION_CLICKED: // USER START (Optionally insert code for reacting on notification message) emWin_GuiScreenChange(1); // USER END break; Build and Program the Application This section describes the process to build the application and program the application binary to the development hardware. Description Use the following steps to build and run the application on the development board: 1. To build the project, in MPLAB X IDE, right click the project and click Clean and Build. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 72 2. Once the project is successfully built it needs to be run on the target device by programming the target device with the compiled binary file. Click Make and Program Device Main Project. Demonstration Output This section describes the output of the demonstration from the development hardware. Description Once the device is programmed with the application binary, the output can be observed on the WQVGA PCAP Display board from the MEB II. The demonstration will display the HomeScreen dialog at the beginning. To navigate from the HomeScreen to Screen2 press the Next button. Similarly, to navigate from Screen2 to the HomeScreen, press the Previous button. Volume VI: Third-Party Products SEGGER emWin Graphics Library Help Start-to-End Example of SEGGER emWin © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 73 wolfMQTT Library Help This section provides information on the wolfMQTT Library. Introduction This topic provides an overview of the wolfMQTT Library in MPLAB Harmony. Description Message Queuing Telemetry Transport (MQTT) is a lightweight open messaging protocol that was developed for constrained environments such as Machine-to-Machine (M2M) and Internet of Things (IoT), where a small code footprint is required. MQTT is based on the Pub/Sub messaging principle of publishing messages and subscribing to topics. The protocol efficiently packs messages to keep the overhead very low. The MQTT specification recommends TLS as a transport option to secure the protocol using port 8883 (secure-mqtt). Constrained devices can benefit from using TLS session resumption to reduce the reconnection cost. The wolfMQTT library is a client implementation of the MQTT written in C for embedded use. It supports SSL/TLS via the wolfSSL library. It was built from the ground up to be multi-platform, space conscience and extensible. It supports all Packet Types, all Quality of Service (QoS) levels 0-2, and supports SSL/TLS using the wolfSSL library. This implementation is based on the MQTT v3.1.1 specification. More Information For known issues and additional details about this release, please see the README file in /third_party/tcpip/wolfmqtt. Product information is available from the wolfSSL website: https://www.wolfssl.com/wolfSSL/Products-wolfmqtt.html. For technical documentation, visit: https://www.wolfssl.com/wolfSSL/Docs-wolfmqtt-manual.html. Volume VI: Third-Party Products wolfMQTT Library Help Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 74 wolfSSL Library Help This section provides information on the wolfSSL Library. Introduction This topic provides an overview of the wolfSSL Library in MPLAB Harmony. Description The wolfSSL embedded SSL library (formerly CyaSSL) is a lightweight SSL/TLS library written in ANSI C and targeted for embedded, RTOS, and resource-constrained environments - primarily because of its small size, speed, and feature set. It is commonly used in standard operating environments as well because of its royalty-free pricing and excellent cross platform support. wolfSSL supports industry standards up to the current TLS 1.2 and DTLS 1.2 levels, is up to 20 times smaller than OpenSSL, and offers progressive ciphers such as ChaCha20, Curve25519, NTRU, and Blake2b. User benchmarking and feedback reports dramatically better performance when using wolfSSL over OpenSSL. More Information For known issues and additional details about this release, please see the README file in /third_party/tcpip/wolfssl. Product information is available from the wolfSSL website: https://www.wolfssl.com/wolfSSL/Products-wolfssl.html For technical documentation, visit: https://www.wolfssl.com/wolfSSL/Docs.html Additional information is also available from the Microchip Third-Party Software Stacks web page: http://www.microchip.com/devtoolthirdparty/. Volume VI: Third-Party Products wolfSSL Library Help Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 75 Index A Abstraction Model 21, 29 B Binary to C Converter (Bin2C) 26 Bitmap Converter (BmpCvt) 26 Build and Program the Application 72 Building the Library 32 C Configuration Files 44 Configuring the Browser 9 Configuring the Hardware 57 Configuring the Library 23, 32 Creating a New SEGGER emWin Application Within MPLAB Harmony 62 D Decoder Library Help 4 Demonstration Output 73 E emWin SPY (emWinSPY) 28 emWin VNC Client (emVNC) 27 emWin Windows View (emWinView) 28 EMWIN_GUI_SCREEN_CREATE type 40 EMWIN_GUI_SCREEN_INITIALIZE type 40 emWin_GuiInitialize function 33 emWin_GuiScreenChange function 34 emWin_GuiScreenEnd function 38 emWin_GuiScreenGet function 39 emWin_GuiScreenInitializeRegister function 35 emWin_GuiScreenRegister function 35 emWin_GuiStartScreenSet function 36 emWin_GuiTasks function 37 EMWIN_TOUCH_INIT structure 42 emWin_TouchInitialize function 41 emWin_TouchMailBoxCreate function 42 Express Logic ThreadX Library Help 5 F Font Converter (SetupFontCvtDemo_V532) 27 FreeRTOS Library Help 6 G Get Operation 11 Get_Bulk Operation 12 Get_Next Operation 12 Getting Started 8 GUI and Touch Wrapper Library for SEGGER emWin 28 GUI Builder (GUIBuilder) 25 GUI Resource Management 55 GUI Wrapper Screen Change 31 GUI Wrapper Setup 31 H Hardware Requirements 56 How the Library Works 22, 30 HTTP Configuration 16 I Initializing the GUI and Touch Wrappers 30 Integrating SEGGER emWin and MPLAB Harmony 45 Integrating the GUIBuilder Output with MPLAB Harmony 69 InterNiche Library Help 7 Introduction 3, 4, 5, 6, 7, 8, 18, 19, 20, 21, 28, 74, 75 iREASONING Networks MIB Browser 8 J JPEG to Movie Converter (JPEG2Movie) 27 L LCD Integration 49 Library Interface 24, 32 Library Overview 22, 29 Loading the GUIBuilder Output into the MPLAB Harmony Project 68 M Micrium uC/OS Libraries Help 18 MPLAB Harmony Configurator (MHC) 47 O OPENRTOS Library Help 19 S SEGGER embOS Library Help 20 SEGGER emWin Event Handling 51 SEGGER emWin Graphics Library Help 21 SEGGER emWin GUI Application Design Process 57 SEGGER emWin Library Architecture 21 SEGGER Utility Tools 24 Set Operation 13 Setup (Initialization) 23 SNMP Operations 11 Software License Agreement 3 Third-Party 3 Software Requirements 57 Start-to-End Example of SEGGER emWin Graphics with MPLAB Harmony 56 T Third-Party Products Overview 3 Touch Integration 50 Touch Wrapper Setup 31 Trap Test 15 U Using GUIBuilder to Create Screens/Dialog Boxes 57 Using SEGGER emWin with MPLAB Harmony 42 Using the Library 29 UTF-8 Text to C Converter (U2C) 26 V Volume VI: Third-Party Products 2 W wolfMQTT Library Help 74 wolfSSL Library Help 75 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 76

Data Visualizer Data Visualizer Software User's Guide Description The Data Visualizer is a program to process and visualize data. The Data Visualizer is capable of receiving data from various sources such as the Embedded Debugger Data Gateway Interface (DGI) and COM ports. © 2017 Microchip Technology Inc. User Guide DS40001903B-page 1 Table of Contents Description.......................................................................................................................1 1. Overview....................................................................................................................4 1.1. Getting Help................................................................................................................................. 6 1.2. Key Concepts...............................................................................................................................6 1.2.1. Workspace.....................................................................................................................6 1.2.2. Connection Overview.....................................................................................................7 1.2.3. Embedded Debuggerʼs Data Gateway Interface........................................................... 7 1.2.4. Simple Transfer..............................................................................................................7 1.2.5. Endpoints.......................................................................................................................8 1.3. Launching Data Visualizer............................................................................................................8 2. External Connection................................................................................................ 10 2.1. Data Gateway Interface (DGI)....................................................................................................10 2.1.1. SPI Interface................................................................................................................13 2.1.2. USART Interface..........................................................................................................14 2.1.3. TWI Interface............................................................................................................... 15 2.1.4. GPIO Interface.............................................................................................................16 2.1.5. Power Interface............................................................................................................18 2.1.6. Code Profiling.............................................................................................................. 19 2.1.7. Sink Data Conversion..................................................................................................34 2.1.8. DGI Data Polling..........................................................................................................35 2.2. Serial Port...................................................................................................................................35 3. Visualization.............................................................................................................40 3.1. Terminal......................................................................................................................................40 3.1.1. Terminal Module.......................................................................................................... 40 3.1.2. Terminal Configuration Example..................................................................................41 3.2. Graph......................................................................................................................................... 43 3.2.1. Graph Module..............................................................................................................43 3.2.2. Graph Configuration Example..................................................................................... 52 3.3. Oscilloscope...............................................................................................................................59 3.3.1. Oscilloscope Module....................................................................................................59 3.3.2. Oscilloscope Configuration Example...........................................................................65 3.4. Power Debugging.......................................................................................................................69 3.4.1. Power Debugging Module........................................................................................... 69 3.4.2. Basic Current Measurement........................................................................................74 3.4.3. Power Analysis using Cursors.....................................................................................77 3.4.4. Code Correlation..........................................................................................................78 3.5. Custom Dashboard.................................................................................................................... 82 3.5.1. Dashboard Module...................................................................................................... 82 3.5.2. Dashboard Configuration Example..............................................................................98 4. Utilities................................................................................................................... 104 4.1. Samplerate Counter................................................................................................................. 104 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 2 4.2. File Logger............................................................................................................................... 104 4.2.1. Logging to a Binary File.............................................................................................104 5. Protocols................................................................................................................105 5.1. Data Stream Protocol...............................................................................................................106 5.1.1. Configuration Format.................................................................................................106 5.1.2. Stream Format...........................................................................................................107 5.1.3. Basic Usage...............................................................................................................107 5.1.4. Auto-Configuration.....................................................................................................107 5.1.5. Auto-Configuration Example......................................................................................108 5.1.6. Auto-Configuration Format.........................................................................................118 5.1.7. Signal Connections File Format.................................................................................120 5.2. Atmel Data Protocol................................................................................................................. 121 5.2.1. Transfer using Atmel Data Protocol...........................................................................121 5.2.2. ADP Example............................................................................................................ 122 5.2.3. Message Flow............................................................................................................149 5.2.4. Message Format........................................................................................................149 5.2.5. Message Types..........................................................................................................149 6. Example Code Snippets........................................................................................ 180 6.1. Data Polling Example Code..................................................................................................... 180 6.1.1. Application Interaction using Dashboard Controls.....................................................183 6.2. Terminal Example Code........................................................................................................... 183 6.3. Graph Example Code...............................................................................................................186 6.3.1. Basic Graph...............................................................................................................187 6.3.2. Adding String Markers............................................................................................... 190 6.3.3. Using Horizontal Cursor Code...................................................................................191 6.4. Oscilloscope Example Code.................................................................................................... 193 6.5. Dashboard Example Code....................................................................................................... 197 6.6. Auto-Configuration Example Code...........................................................................................201 7. Known Issues........................................................................................................ 205 8. Document Revision History................................................................................... 206 The Microchip Web Site.............................................................................................. 207 Customer Change Notification Service........................................................................207 Customer Support....................................................................................................... 207 Microchip Devices Code Protection Feature............................................................... 207 Legal Notice.................................................................................................................208 Trademarks................................................................................................................. 208 Quality Management System Certified by DNV...........................................................209 Worldwide Sales and Service......................................................................................210 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 3 1. Overview This chapter gives an overview of the main modules/features of the Data Visualizer. Each module is described in a separate chapter with technical details of the module, and includes an example or use case showing how to use the module. As each chapter is self-contained, it is possible for the user to quickly identify and select the chapter/module of interest. Data Gateway Interface (DGI) Data Gateway Interface (DGI) enables bidirectional communication over SPI, I 2C, and USART, in addition to GPIO monitoring, power measurement, and code profiling. Serial Port Serial Port communicates with any serial port on the system. Terminal Terminal display and send simple text or numeric values. Graph Graph can be used to plot data source values vs. time. • Cursors (time axis) to measure application timing (e.g., PWM frequency) • Horizontal cursor (data values) to control an applicationʼs set point or threshold • Band highlights time periods above customizable thresholds • String markers can be used to add descriptive text to graphed events Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 4 Oscilloscope Oscilloscope • Edge or threshold triggers on rising or falling edges • Run-stop control for single shot or continuous triggering • Cursors (time axis) to measure application timing (e.g., PWM frequency) Power Debugging Power Debugging • Correlation of code execution and power consumption • Displays current and voltage measured using Power Debugger (Embedded debugger on some kits) Custom Dashboard Custom Dashboard • Build a custom user interface to visualize and control user application using: graph, segment display, binary signals, labels, buttons, linear gauge: Value within defined range. Pie Chart (e.g., for packets lost vs. transmitted in wireless application). Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 5 Utilities • Samplerate Counter to validate MCU frequencies (e.g., rate of transmitted ADC samples) • File Logger module logs all incoming data to a file of selectable format 1.1 Getting Help Help can be opened at any time by clicking F1. By selecting a module in the Configuration window and clicking F1, help will be opened at the relevant chapter automatically. 1.2 Key Concepts This section describes the key concepts to understand when working with the Data Visualizer. 1.2.1 Workspace Data Visualizer is made up of several elements such as graphs, interfaces, and controls. All these elements form the workspace. The elements are called modules, in which any of them can be added to the workspace. Figure 1-1. Data Visualizer Workspace 1 2 3 4 5 1. Expand/Collapse Configuration pane button. 2. Configuration and Messages pane. 3. Active modules. 4. Minimize module button. 5. Remove module button.  Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 6 1.2.2 Connection Overview The Data Visualizer communicates with the firmware running in the MCU of the embedded system. Variables in the firmware can be transferred in both directions. In the following example, the temperature value is sent to the visualizer and plotted in a graph. The filter strength value is set by dragging the slider in the visualizer, and is then sent to the MCU. Figure 1-2. Data Visualizer Connection Overview Embedded system MCU PC Temperature int temperature; int filter_strength; Filter USB or Strength serial cable The communication can take place in a serial cable or USB if the embedded system contains an Embedded Debugger. (The Xplained Pro MCU boards contain Embedded Debuggers.) 1.2.3 Embedded Debuggerʼs Data Gateway Interface The Xplained Pro family of boards contain an Embedded Debugger chip. It has a Data Gateway Interface (DGI) that lets the MCU easily communicate with the Data Visualizer through either its SPI or TWI interface, or by GPIO pins. Figure 1-3. The Data Gateway Interface MCU Xplained Pro series board Embedded Debugger SPI TWI GPIO USB In the Data Visualizer, the DGI Control Panel is the module that communicates with the Embedded Debuggerʼs Data Gateway Interface. When the board is connected to the computer with the USB cable, it can be selected in the control panel. A list of available interfaces will appear. Enable one or more of them by checking the boxes. In the figure above, the SPI interface is enabled. The MCU can now communicate with the Data Visualizer on its SPI port. 1.2.4 Simple Transfer Sending a single value from the MCU to the Data Visualizer is quite simple. In the figure below, the MCU sends the temperature variable over its SPI interface. In the visualizer, the SPI interface on the Embedded Debugger has been enabled. The Embedded Debugger will transmit the SPI data to the visualizer through the DGI Control Panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 7 Figure 1-4. A Simple DGI Transfer To visualize the temperature data, a Graph has been added. The SPI data is routed to the plot by dragging the plug icon from the SPI interface in the DGI Control Panel, and dropping it in the plot area. This will add a new plot to the Graph module. 1.2.5 Endpoints Data in the Data Visualizer originates from an endpoint and ends in an endpoint. The endpoints are referred to as sinks and sources. A data source sends data to one or more connected sinks. In the workspace, the endpoints are represented by the graphical symbols shown below. Figure 1-5. Data Source Figure 1-6. Unconnected Data Sink Figure 1-7. Connected Data Sink 1.3 Launching Data Visualizer The Data Visualizer is included as part of the Atmel Studio installer, and can be run either as a Studio extension or in Stand-alone mode. To run the Data Visualizer as an extension inside Atmel Studio, select it in the Tools menu: Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 8 Kits supporting Data Visualizer functionality include a shortcut to the extension on their start page in Atmel Studio. If the stand-alone version of the Data Visualizer has been installed, look for the shortcut in the Windows® start menu. The stand-alone version is available for download from gallery.atmel.com. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 9 2. External Connection All communication to the outside world is handled by modules found under the external connection section. The DGI Control Panel communicates with any tool that has the Data Gateway Interface. It is capable of bidirectional communication over SPI, I2C, and USART, in addition to GPIO monitoring, power measurement, and code profiling. The feature set varies by tool. The Serial Port Control Panel communicates with any serial port on the system. 2.1 Data Gateway Interface (DGI) The Data Gateway Interface is available on most kits with an Embedded Debugger. The DGI control panel can communicate with a DGI device. The figure below shows the DGI control panel module. Figure 2-1. Data Gateway Interface Control Panel Tip:  A new DGI Control Panel can be opened in External Connection in the Modules section of the Configuration tab in the Data Visualizer. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 10 All detected DGI devices are listed in the drop-down list with the kit name and serial number. Using the Connect button will connect to the selected DGI device and query for available interfaces. The available interfaces will be listed under Interfaces. To enable an interface, check the box next to the name. When an interface is enabled, the sources and sinks can be connected to other endpoints. The Gear button is used to configure the interface. See the interface-specific sections for an explanation of the configuration fields. To start polling data from the interfaces, click the Start button. The Reset MCU check box will cause the MCU to be held in Reset during start. The Data Visualizer supports two different protocols for Auto-configuration; the Atmel Data Protocol (ADP) and the Data Stream protocol. When using ADP, the configuration resides in the target application code and the target application sends the configuration settings, upon request, from the Data Visualizer. When using the Data Stream protocol, the configuration resides in files stored on the host computer and the target application just sends an ID to identify which configuration files to be loaded by the Data Visualizer. For more information on ADP, see Atmel Data Protocol. For more information on the Data Stream protocol, see Data Stream Protocol. To enable Auto-configuration the Autodetect protocols option must be enabled. After pushing Connect the Data Visualizer will enable all interfaces while it looks for the ADP handshake message or a Data Stream Configuration packet. If an ADP handshake message is received, the Data Visualizer will request configuration information from the target application. If a Data Stream Configuration packet is found, the Data Visualizer searches through the folders in the Auto-Configuration search path looking for configuration files with names matching the detected ID. Important:  To make sure the Data Visualizer detects the Data Stream Configuration packet, it must be sent by the target at least twice per second. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 11 Important:  Asynchronous serial protocols (e.g., UART protocols used by DGI USART and CDC Virtual COM port interfaces) use the following baud rates for auto-detection: Table 2-1. Baud Rates Used on Asynchronous Interfaces for Auto-Detection of Protocols Baud Rate 9600 19200 38400 57600 115200 230400 500000 1000000 2000000 Using any baud rates not in the table will not work for auto-detection of protocols over asynchronous interfaces (DGI UART and Serial port/CDC Virtual COM port). Tip:  To see the current search path used by Data Visualizer to look for configuration files, check the Show Config search path option. The search path is a semicolon separated list of paths. When Data Visualizer detects an AutoConfiguration ID, it will search through the paths in the list looking for configuration files with the correct file names. If the Data Visualizer cannot find any valid configuration files it will show a browser dialog window asking for the path to the folder where the correct configuration files reside. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 12 After selecting a folder, the folder will be APPENDED to the Auto-Configuration search path. Tip:  To reset the search path and select a new single folder as the search path, click the link on the Autodetect protocols option text. Data Visualizer will then pop up a browser dialog asking for the path to the folder where the configuration files reside. The original search path will be CLEARED and the newly selected folder will be set as search path. Important:  All three configuration files must reside in the same folder. 2.1.1 SPI Interface The SPI interface source contains the raw values received on the SPI interface. The sink sends values received back out on the SPI bus. For further details on the physical part of the SPI interface, see the user guide of the debugging tool to be used to sample the SPI data. Important:  If the SPI sink is connected to a source with a multibyte type, the byte order may be unpredictable. Important:  The SPI hardware module uses an active-low Chip Select (CS) signal. Any data sent when the CS pin is high will be ignored. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 13 The SPI Configuration dialog is opened from the SPI interface in the DGI control panel. Table 2-2. Configuration Field Name Values Usage Transfer Mode • SCK normally low, Read data on rising edge • SCK normally low, Read data on falling edge • SCK normally high, Read data on falling edge • SCK normally high, Read data on rising edge SPI mode, controlling clock phase and sampling. Force synchronization on CS ON or OFF The SPI interface is only enabled after the Chip Select line has toggled twice. Enable timestamping ON or OFF Data is timestamped through the DGI timestamp interface (yields a slower transfer rate). Related Links Sink Data Conversion 2.1.2 USART Interface The USART interface source contains the raw values received on the USART interface. The sink sends values received back out on the USART interface. For further details on the physical part of the USART interface, see the user guide of the debugging tool to be used to sample the USART data. Important:  If the USART sink is connected to a source with a multibyte type, the byte order may be unpredictable. The USART Configuration dialog is opened from the USART interface in the DGI Control Panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 14 Table 2-3. Configuration Field Name Values Usage Baud rate 0-2000000 Baud rate for UART interface in Asynchronous mode Char length 5, 6, 7, or 8 bits Number of bits in each transfer Parity type None, Even, Odd, Mark, or Space Parity type used for communication Stop bits 1, 1.5, or 2 bits Number of Stop bits Synchronous mode ON or OFF Selecting Synchronous or Asynchronous mode Enable timestamping ON or OFF Data is timestamped through the DGI timestamp interface (yields a slower transfer rate) Related Links Sink Data Conversion 2.1.3 TWI Interface The TWI interface source contains the raw values received on the TWI interface. The sink sends values received back out on the TWI interface. For further details on the physical part of the TWI interface, see the user guide of the debugging tool to be used to sample the TWI data. Important:  If the TWI sink is connected to a source with a multibyte type, the byte order may be unpredictable. The TWI Configuration dialog is opened from the TWI interface in the DGI Control Panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 15 Table 2-4. Configuration Field Name Values Usage Address 0-127 TWI slave address Speed 100000, 400000 Speed setting for TWI slave. Used for timing. Enable timestamping ON, OFF Data is timestamped through the DGI timestamp interface (yields a slower transfer rate) Related Links Sink Data Conversion 2.1.4 GPIO Interface The GPIO interface source is of type uint8, and contains the bit values of the enabled GPIO pins. A packet is transmitted every time a pin toggles. The sink sends values received back out to the GPIO pins. For further details on the physical part of the GPIO interface, see the user guide of the debugging tool to be used to sample the GPIO data. The GPIO Configuration dialog is opened from the GPIO interface in the DGI Control Panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 16 Table 2-5. Configuration Field Name Values Usage GPIO 0 Monitor ON, OFF Monitor GPIO pin 0 GPIO 1 Monitor ON, OFF Monitor GPIO pin 1 GPIO 2 Monitor ON, OFF Monitor GPIO pin 2 GPIO 3 Monitor ON, OFF Monitor GPIO pin 3 GPIO 0 Output ON, OFF Enable GPIO pin 0 output GPIO 1 Output ON, OFF Enable GPIO pin 1 output GPIO 2 Output ON, OFF Enable GPIO pin 2 output GPIO 3 Output ON, OFF Enable GPIO pin 3 output Mode Pin, Bus, Latched Bus GPIO pins as separate pins, a 4-bit bus, or a 3-bit bus that is latched on rising edge of GPIO3 Important:  When using any of the bus modes (Bus or Latched Bus) all GPIOs are sampled but only those GPIOs that have monitoring enabled will trigger a sample. For example, if GPIO 0 to GPIO2 all have GPIO Monitor disabled but GPIO 3 has Monitor enabled, then GPIO values will only be sampled when GPIO 3 changes but all four GPIO values will be read when GPIO 3 changes. Related Links Sink Data Conversion Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 17 2.1.5 Power Interface The Power interface measures the power consumption of the connected circuitry. For more information on the hardware part of the power interface, see the user guide of the debugging tool to be used for the power measurements. The Power Configuration window is opened from the Power interface in the DGI Control Panel. The content of the Power Configuration window will vary depending on the capabilities of the connected debugging tool. Table 2-6. Power Configuration Options Field Name Values Usage Enable B Channel ON, OFF Enables the second power measurement channel. The A channel is always enabled. Trigger calibration ON, OFF Triggers the calibration procedure of the current measurement circuitry. For further details, see Power Measurement Calibration. Enable Range Source ON, OFF Provides a range source, indicating which range is in use for the primary power measurement channel. The physical hardware used to measure power consumption will have different configurations depending on the instantaneous current measured. Each configuration is referred to as a range. Lock ChA to High Range ON, OFF On the Power Debugger, the A channel can be locked to the high range to avoid automatic switching to the low range. This allows Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 18 Field Name Values Usage detection of short spikes in current consumption without critical samples being lost when switching between the ranges. Enable Voltage Output ON, OFF Enable Power Debugger Voltage Output with the value given by the Voltage Output slider. Voltage Output 0 - 5500 mV The Power Debugger features an adjustable target supply that can be used to power the target application. This setting controls the output voltage of this supply. The Enable Voltage Output option must be enabled for the setting to take effect. Tip:  Any configuration changes will not take effect until clicking OK in the Power Configuration window. E.g., to enable the Voltage Output the Enable Voltage Output option must be checked, the Voltage Output value set and then after pushing OK the voltage output will actually be enabled and set according to the slider value. Tip:  The channel A range lock will not force the debugger to return to the high current range if already running in the low range. Either wait for a current high enough to force it to change, or simply Stop and Start the debugger. Important:  The Power interface can only be used with the Power module. Neither the Oscilloscope module nor the Graph module can be used with the Power interface. 2.1.6 Code Profiling The Code Profiling interface uses the debug interface of the target device to access internal data like Program Counter and memory locations. It provides timestamped samples of the Program Counter address, allowing an insight in the program execution of the device. The user can also select arbitrary memory addresses to poll and control data variables at those locations. In addition, it is possible to monitor the state of the stack and the Power-Saving/Sleep mode of the target. Finally, it is possible to receive arbitrary data from the target application through a message pipe in the target On-Chip Debug (OCD) system. The availability of the above features varies with target device types and more details can be found in the following sections. 2.1.6.1 Code Profiling Interface For a couple of examples on how to configure and use the Code Profiling interface, see Data Polling Example and Program Counter Polling. Important:  The Code Profiling interface is only available when Data Visualizer is run as an extension within Atmel Studio. This is because it needs to access the debug system on the target device through the Atmel Studio debugger backend. The Code Profiling Configuration window can be opened after enabling the Code Profiling interface in the DGI Control Panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 19 Table 2-7. Configuration Field Name Values Usage Enable Code Location ON, OFF Controls the state of the Program Counter sampling. Enable Stack Monitor ON, OFF Enables polling of the Stack Pointer to monitor stack usage (AVR® MCU with UPDI only) AVR MCU OCD messaging ON, OFF Enables routing of OCD messages to Data Visualizer rather than Atmel Studio. AVR MCU Sleep monitor ON, OFF Enables monitoring of the Sleep state of the MCU (AVR MCU with UPDI only) Add Memory Location Adds a new entry of memory location to poll and control. A text box for entering the address (hexadecimal), selecting data type and a Delete button will appear. Each configuration option is detailed in the following sections. 2.1.6.2 Code Location The Code location feature enables the Data Visualizer to sample the Program Counter of the target device. This makes it possible to see what is being executed on the target at various sample points. It is especially useful together with power measurements to correlate code execution with power consumption. The sampled PC values will only show part of the code execution as in most cases it is impossible to read out the PC values as fast as the target is executing instructions. The sampled values are still useful to indicate which code segment is being executed at any point in time. For an example on how to use the Code location feature, see Program Counter Polling. Important:  The Code location feature is only available on SAM devices and AVR devices featuring the UPDI debugging and programming interface. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 20 2.1.6.3 Stack Monitor The Stack Monitor enables developers to monitor the stack usage of their code at run-time. This is done by sampling the Stack Pointer register via the on-chip debug module. Enable the Stack Monitor in the Code Profiling Configuration dialog, then connect the Stack Monitor source to a graph plot sink and start a debug session. Important:  The Stack Monitor feature is only available on AVR devices featuring the UPDI programming and debugging interface. The Stack Monitor feature is implemented using polling, which means that not all stack levels will be visible. The granularity of the resulting graph is a function of the speed of the device clock, the UPDI clock speed and the nature of the application code. It is recommended to set the UPDI clock to maximum when using the Stack Monitor. The example shown here is tracing the stack as points (not plot) from an application running on an ATtiny817. The points show samples with the Stack Pointer in "Idle state" in the main loop pointing to address 16372 (0x3FF4) and decrementing as functions are called. Note:  The Data Visualizer has no knowledge of the configuration of the stack on the device, and thus only shows raw samples of the Stack Pointer. 2.1.6.4 AVR MCU OCD Messaging The AVR MCU OCD messaging system is a side-channel in the on-chip debug module. It is used extensively in some OCD variants to communicate with the core when it is stopped, but is not used by the system during Run mode. It can be used by end-user code to send messages to the debugger at run time. In Run mode, the debugger constantly polls the OCD for run/stop status, and at the same time picks up any messages. AVR MCU OCD messaging is a channel for code instrumentation without using any dedicated pins (other than the debug pins). Messages are single 8-bit values and are by default sent to Atmel Studio and displayed in the Output window as hex values, unless routed to Data Visualizer. AVR MCU OCD messaging can be used in several ways. The examples below show three examples of various techniques. • No handshaking, no guaranteed delivery • With handshaking, blocking transport • With handshaking, non-blocking transport There is no standard way to use OCD messaging. The techniques shown in these examples each have advantages and disadvantages, and make use of different resources on the target device. Not all AVR Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 21 devices support OCD messaging, and not all applications are suited to the use of OCD messaging. It is essentially a side-channel of the on-chip-debug system. Enable AVR MCU OCD messaging in the Code Profiling Configuration dialog, then connect the AVR MCU OCD messaging source to a graph plot sink and start a debug session. Messages will not appear unless code is instrumented accordingly. The most typical use-case for AVR MCU OCD messaging is ASCII printf-style debugging displayed on a terminal, as demonstrated in the examples. However, it could be used to transport any 8-bit data values, or even a composite structure. Messages can, for example, be sent from an ADC sample-complete interrupt, writing the 8-bit value of an ADC sample directly to the OCD message register. This can then be plotted directly onto a graph in Data Visualizer. The ̔defaultʼ OCD message channel to Atmel Studio operates at a fixed sample rate with 50 ms period. When enabled from Data Visualizer, the polling loop makes use of ̔spareʼ cycles in the debugger to read and transport OCD messages. This leads to a higher throughput, but is also less deterministic in timing. AVR MCU OCD Messaging Without Handshaking The simplest form of using AVR MCU OCD messaging is writing directly to the register without any form of handshaking. This might be appropriate when, for example, execution speed is more important than data completeness. A single write to the OCD message register overwrites the previous value, even if it has not been read by the debugger yet. This could also be used for slow-changing data. The following example shows how to output AVR MCU OCD messages without handshaking on various AVR MCU architectures. OCD Messaging on AVR UPDI Target Device // Example of OCD message on AVR UPDI target // No handshaking, no guarantee #define SYSCFG_OCDM SYSCFG.reserved_0x18 void ocd_putchar (char c) { SYSCFG_OCDM = c; } OCD Messaging on AVR XMEGA® Target Device Note:  DGI-based OCD messaging is not yet supported on XMEGA targets. The code shown here will push OCD messages to Atmel Studio. // Example of OCD message on AVR XMEGA target // No handshaking, no guarantee void ocd_putchar (char c) { OCD.OCDR0 = c; } OCD Messaging on AVR JTAG Target Device // Example of OCD message on AVR JTAG target // No handshaking, no guarantee void ocd_putchar (char c) { OCDR = c; } OCD Messaging with Handshaking and Blocking This example will block on each character sent via the OCD messaging system until it is ready to accept a new character. A simple timeout is employed to prevent full lockup of code if the debugger is Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 22 disconnected. This example runs on an AVR ATtiny817 using the UPDI interface, but a similar mechanism could be used on other AVR MCU architectures supporting OCD messaging. #include #include #define SYSCFG_OCDM SYSCFG.reserved_0x18 #define SYSCFG_OCDMS SYSCFG.reserved_0x19 bool ocd_print_ready (void) { // Has the last character been collected? return !(SYSCFG_OCDMS & (1 << 0)); } bool ocd_print_char (char msg) { // Simple timeout mechanism uint8_t timeout = 0xFF; while (timeout-- && !ocd_print_ready()) ; // If the debugger fails to collect, continue if (!timeout) return false; // Drop off a message SYSCFG_OCDM = msg; return true; } void ocd_print (char* pmsg) { // Send the message while (*pmsg) { if (!ocd_print_char(*pmsg++)) return; } } int main(void) { // Send an OCD message ocd_print ("Hello World\n"); while (1) ; } Interrupt-Driven Bufferred OCD Messaging A more complex method of using AVR MCU OCD messaging involves a small I/O buffer into which a printf function can inject data which will be gradually transferred to the debugger. A timer interrupt is used to periodically service the printf buffer. On each interrupt a character will be sent from the buffer, if the message channel is ready and data is available. This example runs on a megaAVR® device with JTAG interface, but a similar mechanism can be employed on other AVR device architectures supporting OCD messaging. #include #include #include // Buffer allocated to OCD messaging #define OCDR_BUFFER_SIZE 32 static uint8_t ocdr_buffer[OCDR_BUFFER_SIZE]; // Buffer pointers static uint8_t head; static uint8_t tail; // Flag to indicate if a debugger is picking up the messages static uint8_t debugger_attached = 1; Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 23 // Declarations static int ocdr_putchar(char c, FILE *stream); static FILE mystdout = FDEV_SETUP_STREAM(ocdr_putchar, NULL, _FDEV_SETUP_WRITE); // Puts a char into the stream static int ocdr_putchar(char c, FILE *stream) { // If the debugger fails to collect, rather just abort if (!debugger_attached) return 1; // Increment head with wrapping uint8_t tmphead; tmphead = (head + 1 ); if (tmphead >= OCDR_BUFFER_SIZE) tmphead = 0; if (tmphead == tail) { // Overflow, abort debugger_attached = 0; return 0; } // Add data ocdr_buffer[tmphead] = c; head = tmphead; return 1; } // Timer interrupt regularly sends data ISR(TIMER0_OVF_vect) { // If no data, continue if (head == tail) return; // If the previous byte has not been collected, continue if (OCDR & 0x80) return; // Increment tail uint8_t tmptail = (tail + 1); if (tmptail >= OCDR_BUFFER_SIZE) tmptail = 0x00; tail = tmptail; // Send data to debugger OCDR = ocdr_buffer[tmptail]; // Reset attached flag to allow hot-plugging debugger_attached = 1; } void ocdr_printf_init (void) { // Zero buffer pointers head = 0; tail = 0; // TC setup. 8Mhz DIV32 gives ~1ms overflow ticks TIFR = (1 << TOV0); TIMSK = (1 << TOIE0); TCCR0 = (1 << CS01) | (1 << CS00); sei(); } int main(void) { // Port init DDRB |= 0xFF; PORTB = 0x55; // Buffer init stdout = &mystdout; ocdr_printf_init(); // Demo loop uint8_t c = 0; while(1) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 24 { c++; PORTB = ~c; printf("led %d\n", c); // Must delay > ~8ms to guarantee printf delivery uint16_t delay = 0x3FFF; while (delay--) ; } } 2.1.6.5 AVR MCU Sleep Monitor The AVR MCU Sleep Monitor enables developers to monitor the Sleep mode state of the AVR MCU CPU at run-time. Sleep mode is a binary representation, and does not indicate which low-power mode is active (idle, power-down, etc.) The AVR MCU Sleep Monitor can be useful for determining the approximate amount of time the CPU spends in Sleep mode. Enable the AVR MCU Sleep Monitor in the Code Profiling Configuration dialog, then connect the AVR MCU Sleep Monitor source to a graph plot sink, and start a debug session. Important:  The AVR MCU Sleep Monitor feature is only available on AVR devices featuring the UPDI programming and debugging interface. The AVR MCU Sleep Monitor feature is implemented using polling, which means that not ALL Sleep transitions will be visible. The granularity of the resulting graph is a function of the UPDI clock speed and the nature of the application code. It is recommended to set the UPDI clock to maximum when using the AVR MCU Sleep Monitor. The graph below shows an example of the Sleep Monitor in use. A value of ̔ 1ʼ indicates that the MCU is in Sleep mode, and ̔0ʼ means it is running normally. From the plot, one can measure (using cursors) that the MCU is entering and exiting Sleep mode with a period of about 2.2s, and stays ̔awakeʼ for about 275 ms on each wake-up cycle. 2.1.6.6 Data Polling and Control The Data Polling and Control feature makes it possible to continuously sample and alter arbitrary memory locations in the target device. For an example on how to use this feature, see Data Polling and Control Example. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 25 Important:  The Data Polling and Control feature is only available on SAM devices. To add a memory location to be polled and/or controlled do the following. To do:  • Click the Add Memory Location button for each memory location to be added • Fill in the address and format of each location There will be one source and one sink for each memory location. Connect the source to any visualization module to monitor the value of the location and connect any data source to the sink to alter the value of the memory location. Important:  Declaring variables you are interested in polling as volatile will ensure that they are placed in SRAM and that their values will not be cached in registers by the compiler. Registers cannot be polled, only SRAM locations. Tip:  Data polling operates on absolute SRAM locations. It is advised to use global variables for this purpose so that they are always available at the same location in SRAM. Polling locations in the stack can yield unpredictable results based on the stack context at the time of polling. Data Polling Example An example on how to use Program Counter sampling for power consumption analysis can be found in Program Counter Polling. The same Mass Storage Class example used in this section is also suited as an example on how to use the data polling and control of data variables features. A SAM L21 Xplained Pro board is connected to a host computer both through Target USB and Debug USB connectors on the kit. The ATSAML21 target device is running the USB Device MSC Example from ASF for SAM L21 Xplained Pro. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 26 For more information on the hardware setup and target application code used in this example, see Data Polling Example Code. Although this example makes use of the Graph and Dashboard modules the principles are the same for using the Code Profiling interface with the other modules in the Data Visualizer. First, a graph will be set up to monitor variables in the target application. To do:  • Enable the Code Profiling interface by deselecting the check box for the Code Profiling interface in the DGI Control Panel To do:  • Open the Code Profiling Configuration window by pushing the Gear button To do:  • Click the Add Memory Location button for each memory location to be added • Fill in the address and format of each location Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 27 To do:  • Open the Configuration panel in Data Visualizer • Add a graph by double-clicking the Graph module A new Graph element will open with one y axis configured. However, there are two unrelated variables to monitor, therefore, two axes are needed. To do:  • Click the Add axis button to add an additional axis There are now sources (variables) and sinks (axes), to be connected together. To do:  Drag each of the source plugs on the Code Profiling interface into the New plot (sink) jack of each axis. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 28 To do:  In Atmel Studio click Continue (F5) to resume execution. Tip:  A USB device in the HALT state no longer responds to Windows events, and may be disconnected from the bus if held in this state for too long. To remedy this simply reset execution in Atmel Studio. Look at the output in the graph in Data Visualizer. Format the disk and watch how the write cycles counter increments. Both values are plotted on independent axes, so they can be scaled accordingly. The output should look something like this: Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 29 The following part of this example shows how to use a dashboard to interact with the target application. For more information on the required code changes in the target application, see Application Interaction using Dashboard Controls. To do:  • Open Data Visualizer • Connect • Add the location of the frame_comparator in the Code Profiling Configuration window A Data Visualizer dashboard can now be made with controls which manipulate the value of this variable. To do:  • Open the configuration panel • Add a new I/O Dashboard component by double-clicking the I/O Dashboard module Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 30 A slider control can now be added to the dashboard. To do:  • Select the Edit checkbox • Open the Elements tab • Drag a Slider element onto the dashboard A slider control needs to have some configuration parameters. To do:  Select the slider element and set its properties: • Maximum = 500 • Minimum = 100 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 31 A segment display control can now be added to the dashboard. To do:  • Select the Edit checkbox • Open the Elements tab • Drag a Segment Display element onto the dashboard A segment display control needs to have some configuration parameters. To do:  Select the segment display element and set its properties: • Segment Count = 3 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 32 The slider control can now be used as a source which can be connected to any relevant sink in Data Visualizer. The segment display can similarly be used as a sink to connect any relevant source to. The Code Profiling data polling interface provides both a source of data and a sink of data. The slider can now be connected to the sink and the segment display to the source. To do:  • Deselect the Edit checkbox • Select the Show Endpoints checkbox • Connect sources to sinks by dragging each source plug and drop it on a sink Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 33 Now that the connections have been made in Data Visualizer, the system can be put into a running state and interaction with the variable can be made through the GUI. To do:  • Deselect the Show Endpoints checkbox • Start Data Visualizer • Resume execution in Atmel Studio (F5) The slider is now in control of the frame_comparator variable in the application code. Drag the slider, and notice that the LED blink frequency changes. Any change in the slider position will be sent to the target device through the debug interface, and a new value stored in the variable. At the same time, the value is also read back from the target and displayed on the segment display. 2.1.7 Sink Data Conversion Since DGI only can handle 8-bit values natively, all values received by DGI are remapped according to the rules in the following table. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 34 Table 2-8. Data Conversion Data Type Conversion Int8 Cast to uint8. 2ʼs complement value is retained. Uint8 Int16 2ʼs complement value is retained. Split into two uint8 values. Big endian. Uint16 Split into two uint8 values. Big endian. Int32 2ʼs complement value is retained. Split into four uint8 values. Big endian. Uint32 Split into four uint8 values. Big endian. Float Cast to Int32 Double Cast to Int32 XY8 X-value sent first, then Y-value XYu8 X-value sent first, then Y-value XY16 X-value sent first, then Y-value XYu16 X-value sent first, then Y-value XY32 X-value sent first, then Y-value XYu32 X-value sent first, then Y-value XYFloat X-value sent first, then Y-value XYDouble X-value sent first, then Y-value String The ASCII values of each character is sent. A null termination is added. StringFloat Sent as a Int32 with the string following Boolean False is sent as 0, true as 1 2.1.8 DGI Data Polling The communication with the Data Gateway Interface (DGI) is done through a separate C++ DLL. When a session is started, it will poll the DGI device for data each 2 ms. However, because the CPU could be busy with other tasks, the polling might happen with a longer interval. Since the DGI device has a limited buffer, the DLL needs to poll the device regularly to avoid an overflow. Therefore, it is important to keep the CPU usage low during polling sessions. In case of overflow problems, either decrease the transfer rate on the DGI interfaces or decrease the CPU load by shutting down applications. 2.2 Serial Port The Data Visualizer can be connected to a standard PC serial port. The Serial Port Control Panel is by default opened and minimized under the DGI Control Panel when starting the Data Visualizer. To expand it, click the down arrow in the right corner of the minimized panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 35 Tip:  A new Serial Port Control Panel can be opened in External Connection in the Modules section of the Configuration tab in the Data Visualizer. Baud rate, Stop bits, and parity must be set to match the required settings for the communication partner. A sink and a source endpoint is present to represent the outgoing and incoming data for the serial port. The endpoints of the serial port control panel is of uint8 data type, and follows the same conversion rules as the DGI control panel. The Open Terminal check box will cause a terminal module to automatically open and connect the endpoints. When disconnecting from a serial port, the created terminal module will be closed. Figure 2-2. Serial Port Control Panel Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 36 Table 2-9. Configuration Field name Values Usage Baud rate 600-2000000 Baud rate of serial interface Parity None, Even, Odd, Mark, or Space Parity type used for communication Stop bits 1, 1.5, or 2 bits Number of Stop bits DTR ON or OFF Data Terminal Ready control signal of RS-232 serial communication RTS ON or OFF Request To Send control signal of RS-232 serial communication Open Terminal ON or OFF Opens a terminal upon connection with the source and sink connections automatically connected between the Serial Port Control Panel serial port and the terminal Autodetect protocols ON or OFF Auto-detection of the Atmel Data Protocol or Data Stream protocol Auto-configuration. For more information on the protocols, see Atmel Data Protocol and Data Stream Protocol Show Config search path ON or OFF Only available when Autodetect protocols is enabled. Shows the search path for Data Stream Autoconfiguration files The Data Visualizer supports two different protocols for Auto-configuration; the Atmel Data Protocol (ADP) and the Data Stream protocol. When using ADP, the configuration resides in the target application code and the target application sends the configuration settings, upon request, from the Data Visualizer. When using the Data Stream protocol, the configuration resides in files stored on the host computer and the target application just sends an ID to identify which configuration files to be loaded by the Data Visualizer. For more information on ADP, see Atmel Data Protocol. For more information on the Data Stream protocol, see Data Stream Protocol. To enable Auto-configuration the Autodetect protocols option must be enabled. After pushing Connect the Data Visualizer will enable all interfaces while it looks for the ADP handshake message or a Data Stream Configuration packet. If an ADP handshake message is received, the Data Visualizer will request configuration information from the target application. If a Data Stream Configuration packet is found, the Data Visualizer searches through the folders in the Auto-Configuration search path looking for configuration files with names matching the detected ID. Important:  To make sure the Data Visualizer detects the Data Stream Configuration packet, it must be sent by the target at least twice per second. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 37 Important:  Asynchronous serial protocols (e.g., UART protocols used by DGI USART and CDC Virtual COM port interfaces) use the following baud rates for auto-detection: Table 2-10. Baud Rates Used on Asynchronous Interfaces for Auto-Detection of Protocols Baud Rate 9600 19200 38400 57600 115200 230400 500000 1000000 2000000 Using any baud rates not in the table will not work for auto-detection of protocols over asynchronous interfaces (DGI UART and Serial port/CDC Virtual COM port). Tip:  To see the current search path used by Data Visualizer to look for configuration files, check the Show Config search path option. The search path is a semicolon separated list of paths. When Data Visualizer detects an AutoConfiguration ID, it will search through the paths in the list looking for configuration files with the correct file names. If the Data Visualizer cannot find any valid configuration files it will show a browser dialog window asking for the path to the folder where the correct configuration files reside. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 38 After selecting a folder, the folder will be APPENDED to the Auto-Configuration search path. Tip:  To reset the search path and select a new single folder as the search path, click the link on the Autodetect protocols option text. Data Visualizer will then pop up a browser dialog asking for the path to the folder where the configuration files reside. The original search path will be CLEARED and the newly selected folder will be set as search path. Important:  All three configuration files must reside in the same folder. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 39 3. Visualization Incoming data can be visualized using the modules contained under this section. The Terminal displays data as text, either as raw values or ASCII encoded characters. It is also capable of sending text-based data. The Graph module visualizes incoming data over time as plots, bands, and string flags. Cursor helps analyze the data, and can provide output values for setting thresholds. The Oscilloscope module is helpful for analyzing time-repeating patterns in a data stream. The Power Analysis module is made specifically for analyzing power consumption over time. It can also be used with code profiling to visualize Program Counter samples to get an overview of the program execution versus power consumption. The Custom Dashboard module is a customizable canvas to create user interfaces matching the application. It features the most common user inputs such as buttons, sliders, and check-boxes, in addition to graphing, etc. 3.1 Terminal The Terminal module is a raw terminal for displaying and sending simple text or numeric values. 3.1.1 Terminal Module The Terminal module is used to display and send simple text or numeric values. For an example on how to configure a terminal, see Terminal Configuration Example. Figure 3-1. Terminal 1 2 3 4 5 6 7 8 9 1. Input text box. 2. Output text box. 3. Output source. 4. Input sink. 5. Clear button.  6. Automatic line feed checkbox. 7. Hexadecimal mode checkbox. 8. Display timestamp checkbox. 9. Autoscroll checkbox.  3.1.1.1 Connecting the Terminal and Displaying Data Data streams are connected to the terminal through the sink and source endpoints. Drop an external source onto the terminal sink, or drag and drop the terminal source onto an external sink. Data coming into the terminal's sink endpoint will be presented in the input text box. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 40 3.1.1.2 Sending Data When the source of the terminal has been connected to a sink endpoint, data can be sent by typing data in the input text box and pressing enter. Whatever was typed in the text box will be cleared after transmission. The text box supports the use of break characters (e.g. \x55, which will result in the raw value 0x55 being transmitted). 3.1.1.3 Setting Hexadecimal Mode Data is normally assumed to be an ASCII encoded stream of data. To display the hexadecimal value of the data, select the Hexadecimal mode checkbox. 3.1.1.4 Resizing the Input Text Box The input text box is re-sizable by clicking and dragging the lower part of the box. 3.1.2 Terminal Configuration Example The following example shows how to connect the SPI interface to a terminal. However, the procedure is the same for any of the other available data sources. The target code used in this example can be found in Terminal Example Code. To do:  Select correct tool in the DGI Control Panel. To do:  Click Connect to make a connection to the DGI on the selected tool. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 41 To do:  • Click the SPI checkbox • Open the SPI Configuration dialog by clicking the Gear button next to the SPI checkbox To do:  • Set Transfer Mode to SCK normally low, Read data on rising edge • Enable the Force start-up synchronization on CS option To do:  • Open the configuration panel • Add a Terminal view to the Visualizer • Drag the source connector from the interface in the DGI Control Panel into the sink for the Terminal to make a connection Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 42 To do:  • Start the session • Press the button (SW0) on the Xplained Pro board On each button press, LED0 on the board should toggle and a message appear on the terminal. Sometimes more than one message appears for each button press. This is an indication that some debouncing algorithm is needed in the button sample routine. It is a lot easier to spot this problem by looking at the terminal output than to watch the LED toggling. 3.2 Graph The Graph module is a versatile graph plotting tool. 3.2.1 Graph Module The Graph module is a versatile graph plotting tool. The large plot area has one time axis, and one or more value axes (Y axes). The value axes are stacked on top of each other. For an example on how to configure a graph, see Graph Configuration Example. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 43 Figure 3-2. Graph with a Plot, Band, String Marker, and Cursor 1 2 3 4 5 6 7 9 8 1. Plot area. 2. String marker. 3. Horizontal cursor. 4. Plot. 5. Band. 6. Time axis. 7. Y axis.  8. Plot cursors. 9. Configuration panel.  There are four types of elements that can be added to an Y axis: • Plot • Band • String marker • Horizontal cursor Each of these elements are described in the following sections. 3.2.1.1 Graph Configuration Panel Through its Configuration panel, the Graph module is connected to the rest of the system. Here you can add more axes, plots, and other graph elements. Here you will also connect the graph elements by connecting sources and sinks. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 44 Figure 3-3. Graph Controls 1 2 3 1. Add axis button. 2. Auto-scroll checkbox. 3. Automatically fit Y checkbox.  Add Axes Figure 3-4. Graph with Two Y Axes Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 45 Press the Add axis button to add an Y axis to the graph. It will show up in the plot area, and its controls will be added to the bottom of the Configuration panel. Delete Axes 1. If the configuration section for the axis you want to delete is hidden, first expand it by clicking the arrow icon. 2. Delete the axis by pressing its Delete Axis button. Enabling and Disabling Auto-scrolling Auto-scrolling locks the plot area to include the latest arriving samples. If auto-scrolling is disabled, manually scroll the plot by dragging the time axis with the mouse or with the scroll wheel. Auto-scrolling is enabled by selecting the Auto-scroll check box. Auto-sizing the Y Axis When the Automatically Fit Y check box is checked, the Y axis will automatically zoom in or out in order to fit the whole sample range of the plots in that axis. 3.2.1.2 Plot A plot is a curve describing a changing value. The curve is drawn between the data samples it receives from the data source. The samples can arrive sporadically, or at a fixed interval. If the data source is known to be sampling at a fixed rate the plot can be set to this sample rate. This way, the curve will be shown correctly even if there are some elasticity in the transmission of the samples. If the samples come at an irregular rate, set the sample rate to 0. This will make the graph position the samples along the time axis according to the sampleʼs timestamp. If there is more than one plot in the graph, each plot will update when new data arrives for that plot. When adding a plot to an axis, the new plotʼs Plot control panel will be placed under that axis in the Graph configuration panel. Figure 3-5. Plot Controls 1 2 3 5 6 8 9 10 11 4 7 1. Plot label. 2. Enable check box. 3. Line color indicator. 4. Plot type selection 5. Data sink.  6. Sample rate edit box. 7. Sample rate set button. 8. Delete plot button.1 9. Plot status.  10. Show Cursors option. 11. Cursor data.  Adding and Connecting a Plot To connect a plot to a data source, drag the data source plug symbol and drop it on the New plot sink connector symbol. Disable a Plot To stop showing a plot in the graphʼs plot area, deselect the plotʼs Enable check box. Change the Plot Color The plot line's color can be changed: Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 46 1. Click on the plot's line color indicator. 2. In the dialog box that opens, adjust the color by dragging the Red, Green, and Blue sliders. Press OK. 3. The plot line and the line color indicator has now changed to the new color. Change Plot Type The plot type can be changed between Plot and Points by changing the selected type in the Plot type selection. The Plot type will show the graph plot as a continuous line while the Points type will show the actual plot samples as dots only. Plot Data at a Fixed Sample Rate If the data source sends data to the plot at a fixed rate, the plotʼs sample rate can be set. Enter the number in the Sample rate text box and press the Set button. Plot Timestamped Data If the data arrives at irregular intervals, the graph will present a more accurate view if the samples are placed using the sampleʼs timestamp. To plot using timestamps, enter 0 into the Sample rate text box and press the Set button. Remove a Plot To remove a plot from an axis, press the Delete button in the plot's control panel. Cursors If the Show Cursors option is enabled, two vertical cursors will show up in the plot area. The cursors can be moved by the mouse and the Plot Controls panel shows data related to the cursors. 3.2.1.3 Band A band is a vertical marking in the plot area that highlights the plot background with the band color. For example, on the plot of a temperature reading, a band can be added that highlights portions of the plot where the temperature is above a certain value. Figure 3-6. Graph Module Showing a Plot and a Band A band has a minimum and a maximum limit. The band will be active, on, if the input to the band is between these two values. Figure 3-7. Band Controls Adding and Connecting the Band To add a new band and connect it to a data source, drag the data source plug and drop it on the New band sink connector. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 47 Setting the Band Color Click the band color indicator. A dialog box will open. Change the RGB values, and press OK. Note:  When changing the band color, the change will not affect band regions already in the graph. Only new band regions will have the new color. Setting Inverted Band Limits Figure 3-8. Band with Inverted Behavior Min limit Max limit If the maximum limit is set to a value less than the minimum value, the band will behave in an inverted manner. Now, the band will be active when the input value is less than the maximum limit, or if the input value is greater than the minimum limit. • Enter the minimum and maximum values, and make sure the maximum value is less than the minimum value. Press the Set button. Setting the Band Color Click the band color indicator. A dialog box will open. Change the RGB values, and press OK. Note:  When changing the band color, the change will not affect band regions already in the graph. Only new band regions will have the new color. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 48 Remove a Band To remove a band, press the Delete button in the band's control panel. 3.2.1.4 String Markers When the source sends a string, the string marker will attach these short messages to the graph. These markers will be placed according to the timestamp of the sample. Figure 3-9. Graph with Plot and Two String Markers Adding and Connecting a String Marker To add and connect a string marker to a data source, drag the data source plug and drop it on the New string sink connector. Setting the String Marker Color Click on the string color indicator in the String control panel. Change the RGB values, and press OK. Note:  When changing the string marker color, the change will not affect string markers already in the graph. Only new string markers will have the new color. Expanding and Collapsing String Markers When large strings are sent to a string marker, the marker will collapse into a small box to reduce the space it occupies in the plot area. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 49 Figure 3-10. Expanded and Collapsed String Marker To see the text, it must be expanded. • Expand and collapse a string marker by double-clicking the marker Remove a String Marker To remove a string marker, press the Delete button in the string's control panel. 3.2.1.5 Horizontal Cursor The Horizontal cursor is a horizontal line in the graph that, when dragged up or down, outputs a value that can be used as a source. Tip:  Use the Horizontal cursor to control an application's setpoint or threshold. Figure 3-11. Graph Plot and Cursor Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 50 Connecting the Cursor To connect a cursor to a data sink, drag the cursor's data source plug and drop it on the target's data sink connector. Changing the Cursor Value To change the cursor value, position the mouse over the cursor line. The mouse cursor will change into a handle. Click and drag the cursor to its new position. Alternatively, the cursor value can be changed by typing in a new value in the Value field in the Horizontal Cursor configuration. Note that the change won't take effect until the text box is deactivated by clicking with the mouse outside the text box. Changing the Cursor Label To change the label of the cursor type in a new label in the Label field in the Horizontal Cursor Configuration. Note that the change won't take effect until the text box is deactivated by clicking with the mouse outside the text box. Setting the Cursor Color Click the Cursor color indicator in the Cursor control panel. A dialog box will open. Change the RGB values, and press OK. Remove a Cursor To remove a cursor, press the Delete button in the cursor control panel. 3.2.1.6 Zooming and Panning When the Auto-scroll and Automatically fit Y check boxes are checked, the last samples will be shown and the Y axis will be zoomed such that all values will be visible. For manually zooming in or out or inspecting a region in more detail, disable these options and zoom and pan using the mouse. Zooming the X Axis The X axis can be zoomed in two different ways: • Using the mouse scroll wheel 1.1. Click somewhere inside the plot area. 1.2. Press and hold the SHIFT key on the keyboard. 1.3. Scroll the mouse wheel in either direction. The X axis will zoom in or out (depending on which way you turned the mouse wheel), centered around the mouse cursor. • Dragging the X axis resize markers 2.1. Position the mouse cursor over one of the X axis' resize markers. The mouse cursor will change into horizontal resizing arrows. 2.2. Click and drag horizontally. Zooming the Y Axis The Y axis can be zoomed in two different ways: • Using the mouse scroll wheel 1.1. Click somewhere inside the plot area. 1.2. Press and hold the CTRL key on the keyboard. 1.3. Scroll the mouse wheel in either direction. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 51 The Y axis will zoom in or out (depending on which way the mouse wheel is turned), centered around the mouse cursor. • Dragging the X axis resize markers 2.1. Position the mouse cursor over one of the X axis' resize markers. The mouse cursor will change into vertical resizing arrows. 2.2. Click and drag vertically. Panning Panning around the graph can be done in two ways: • Dragging the plot area 1.1. Position the mouse cursor inside the plot area. 1.2. Click and hold the left mouse button. 1.3. Drag the mouse. • Dragging the axes 2.1. Position the mouse cursor over one of the axes. The cursor will change into a pointing hand. 2.2. Click and drag the axis. 3.2.2 Graph Configuration Example This chapter gives an example on how to configure the Graph module to be used with a target application implementing a Night mode switch with a light sensor. Although this example utilizes only some of the data sources available in the Data Visualizer, the procedure will be the same for all data sources. The target code used in this example and a description of the hardware setup can be found in the Graph Example Code chapter. The first part of the configuration example uses the code found in the first subsection of the Graph Example Code chapter (Basic Graph). When changes to the target application code are required as the example progress a link to the corresponding code listing will be provided. To do:  Select correct tool in the DGI Control Panel. To do:  Click Connect to make a connection to the DGI on the selected tool. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 52 To do:  • Click the SPI checkbox • Open the SPI Configuration dialog by clicking the Gear button next to the SPI checkbox To do:  • Open the configuration panel • Add a Graph module to the Data Visualizer • Drag the source connector from the interface in the DGI Control Panel into the sink marked New plot to make a connection to a new plot Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 53 To do:  • Push Start in DGI Control Panel The data will be plotted in the Graph module. It could look something like the picture below when hovering a hand above the light sensor. The light sensor data can be used to switch between Day and Night mode. For the Night mode switch to be useful, the threshold when switching between the modes are important. The Graph module contains a useful feature called Band to mark when the plot data is within a certain range. This can be used to simplify the selection of the mode switch threshold. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 54 To do:  • Drag the interface source to the New band sink To see that the Night mode switch is actually working and switching at the right threshold, the string marker feature of the Graph module is useful. In this example, the CDC USART interface of the target board is used to send a string each time the mode is switched. These messages can then be shown in the graph as string markers. The target application source code for this part of the configuration example can be found in Adding String Markers. To do:  • Open the Serial Port Control panel found under External Connection in the Modules section of the Configuration tab in Data Visualizer Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 55 To do:  • Select the correct COM port corresponding to the connected kit • Set the serial port parameters according to the application code • Make sure the Open Terminal option is not checked To do:  • Drag the serial port source to the New string sink • Click Connect in the Serial Port Control Panel Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 56 String markers will appear as vertical lines with a square on top. By double-clicking the square the string text will be shown. Note that there will naturally be some delay from the ADC data values crosses the threshold until the string message reaches the host computer. In addition, the timestamping of the data is added on the host computer and the two serial interfaces are not synchronized. This results in a misalignment of the string markers compared to the ADC values. DGI includes timestamping functionality on the EDBG on the Xplained Pro and this can be enabled in the DGI Control Panel at a performance cost, but CDC includes no time stamping functionality. Tip:  In this example, a separate serial interface was used for the string marker data. If the number of serial interfaces available are constrained, the same interface could be used to stream both the ADC data and the string marker data by using the Atmel Data Protocol (ADP). For more information, see the Atmel Data Protocol. So far, the Graph module of the Data Visualizer has been used to show the data generated by the light sensor and to show when the Night mode switch toggles between the two modes. The Graph module can also be used to interact with the target application while it is running. In this example, the Night mode threshold can be adjusted dynamically by using a horizontal cursor. The target application source code for this part of the configuration example can be found in Using Horizontal Cursor Code. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 57 To do:  • First, remove the band from the graph as it is of no use when the Night mode threshold is dynamic • Click Add Horiz. Cursor to add a horizontal cursor to the graph • Drag the Horizontal Cursor source to the sink in the Serial Port Control Panel To move the horizontal cursor either drag it or change the value by typing a new value in the Value field in the configuration. Note that the value will not be updated until the Value text box is not in focus, i.e. click somewhere else in the GUI after typing in a value. Every time the cursor is moved the Data Visualizer sends a new float value to the serial port the cursor is connected to. Tip:  Turn off Auto-scroll and Automatically fit Y to more closely examine a plot while it is still running. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 58 3.3 Oscilloscope The Oscilloscope module visualizes data values in real time. The oscilloscope features a trigger submodule to capture repeating signals or rare events. The oscilloscope also has a cursor system to measure various properties of the data streams. 3.3.1 Oscilloscope Module The Oscilloscope module visualizes data values in real time. It has four channels for monitoring four different data streams at the same time. Each channel's data stream is visualized as a graph in the plot area, each with a different color. The vertical position and amplitude of each channel can be modified. For repeating signals, or for capturing rare events, the oscilloscope has a trigger sub-module. The oscilloscope also has a cursor system to measure various properties of the data streams. For an example on how to configure an oscilloscope, see Oscilloscope Configuration Example. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 59 Figure 3-12. The Oscilloscope Module 1 2 3 4 5 6 7 8 9 1. Plot area. 2. Zero-line. 3. Plot. 4. Trigger level indicator line. 5. Time axis scale handle.  6. Time axis. 7. Plot area resize handle. 8. Control panel. 9. Show/hide control area arrow.  3.3.1.1 Oscilloscope Control Panel The Oscilloscope control panel is where the oscilloscope is configured and connected to the rest of the system. The control panel has five sections, which are described in detail in the following sections. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 60 Figure 3-13. Oscilloscope Control Panel Vertical Controls The vertical control section has four sub-sections, one for each of the four oscilloscope channels. The channel controls are disabled until a source is connected to the channel sink. Connecting the Oscilloscope Signals or data streams are connected to the oscilloscope through the channel sink endpoints. Drop an external source onto the sink. When connected, the rest of the channel controls will be enabled. Adjusting the Channel Amplitude When a channel is displayed in the plot area, the signal's height is determined by the channel amplitude setting. The amplitude can be adjusted in three different ways: • Enter an amplitude value into the text box. Deselect the text box to let the new value take effect. • Click on the up/down arrows located to the right of the text box • With the mouse cursor positioned over the text box, scroll the mouse wheel to increase/decrease the amplitude setting Show and Hide a Channel When a channel is in use, the plot can be hidden from the plot area by clearing the Amplitude check box. Click it to show the plot again. Adjusting the Channel Offset The channelʼs vertical position in the plot area can be adjusted with the Offset setting. The offset value is the channelʼs zero-pointʼs distance above the bottom of the plot area. There are four ways to adjust the offset: • Enter an offset value into the text box. Deselect the text box to let the new value take effect. • Click on the up/down arrows located to the right of the text box • With the mouse cursor positioned over the text box, scroll the mouse wheel to increase/decrease the offset setting • If the channelʼs zero line is enabled in the plot area, drag it to a new position Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 61 Show and Hide the Zero Line A zero line is, by default, shown when a channel is enabled by connecting it to a source. The zero line is a horizontal line shown in the plot with the same color as the channelʼs color. It also has a 0 label on the left end. The zero line can be shown/hidden by clicking/clearing the Offset check box. Customize the Channel Name When the oscilloscope module is added to the workspace, the four channels are labeled Channel 1 to Channel 4. The label can be changed, as a reminder of what signal is connected to that channel. • Click inside the label and type in the new name Run Control The Run/Stop and Single buttons are the run control. These buttons control if the plots are updated or not. There are three operating modes: • Stop (the Run/Stop button is red) • Single (the Single button is yellow) • Run (the Run/Stop button is green) Enter Run Mode When the stop or single operating mode is active (red or yellow light), enter the run mode by clicking the Run/Stop button. The button will turn green, and the plots will continuously update according to trigger settings. Enter Single Mode When the stop or run operating mode is active (red or green light), enter the single mode by clicking the Single button. The button will turn yellow, and the plots will trigger and update only once. Enter Stop Mode When the single or run operating mode is active (yellow or green light), enter the stop mode by clicking the Run/Stop button. The button will turn red, and the plots will freeze. Trigger Controls The Oscilloscope trigger sub-module helps to identify and lock on to only the portion of the input signal desired. Depending on the operating mode set by the run controls, the trigger can: • Lock on to a periodic signal and constantly update the plot • Only update the plot when the signal exceeds some level Edge Triggering The edge triggering mechanism is looking for the signal to cross the trigger level. For a positive edge trigger, the signal must go from below the trigger level, to above the trigger level. Figure 3-14. Positive Edge Trigger Trigger level 1 2 3 1. No trigger – the line must cross. 2. No trigger – wrong direction. 3. Trigger point.  Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 62 Figure 3-15. Negative Edge Trigger Trigger level 1 2 3 1. No trigger – the line must cross. 2. No trigger – wrong direction. 3. Trigger point.  Set the Edge Trigger Type The trigger mechanism has two edge trigger modes: Positive and Negative Edge Trigger. • To set the Positive Edge Trigger mode, click the button. The button will be highlighted when activated. • To set the Negative Edge Trigger mode, click the button. The button will be highlighted when activated. Set the Trigger Level The trigger level can be adjusted in three different ways: • Enter a trigger level value into the text box. Press the TAB keyboard button or click the mouse outside the text box to let the new value take effect. • Click on the up/down arrows located to the right of the text box • With the mouse cursor positioned over the text box, scroll the mouse wheel to increase/decrease the trigger level setting • Drag the trigger level line in the plot area to a new position Select the Trigger Source The Oscilloscope trigger sub-module uses one of the channel signals when looking for the trigger condition. • Click the colored Trigger source button corresponding to the channel chosen for use as a trigger source. The active Trigger source button will be highlighted. Set the Trigger Mode The Oscilloscope module supports both Triggered and Free Running mode. • Click Normal to enable Triggered mode. The plot will only be updated when the trigger condition is satisfied. • Click Auto to enable Free Running mode. The plot will be updated continuously and the trigger conditions will be ignored. Horizontal Control The oscilloscope draws the plot lines at a constant speed. The X axis is the time axis. The axis labels show time relative to the trigger point. For the labels to display correctly, the oscilloscope needs to know the sample rate of the source. Set the Sample Rate In the sample rate text box, enter the source's sample rate. Note:  All sources connected to the oscilloscope must have the same sample rate. If not, the plot lines will not be synchronous with the time axis. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 63 Set the Horizontal Resolution The horizontal resolution determines the time axis range, or what time-span is visible in the plot. It can be adjusted in four different ways: • Position the mouse cursor inside the plot area. Use the mouse wheel to zoom in or out. • Enter a resolution value into the text box. Deselect the text box to let the new value take effect. • Click on the up/down arrows located to the right of the text box • With the mouse cursor positioned over the text box, scroll the mouse wheel to increase/decrease the resolution setting • Drag the time axis scale handles to change the resolution Set the Horizontal Offset The horizontal offset is the trigger point's position relative to the center of the plot area. Typically, the offset is changed in order to inspect the plot on either side of the trigger point. There are five different ways of changing the offset: • Position the mouse cursor inside the plot area. Make sure it does not touch any of the trigger line, zero line, or cursor lines. Then, click and drag the mouse horizontally to change the offset. • Position the mouse cursor on the time axis. Then click and drag the mouse horizontally to change the offset. • Enter an offset value into the text box. Deselect the text box to let the new value take effect. • Click on the up/down arrows located to the right of the text box • With the mouse cursor positioned over the text box, scroll the mouse wheel to increase/decrease the offset setting 3.3.1.2 Cursors The oscilloscope has two cursors that can be used to inspect the plots. The cursors simplify measurements such as pulse widths, amplitudes, frequencies, and so on. Each cursor is displayed in the plot area as two lines, one vertical and one horizontal. When the vertical cursor line is moved, the horizontal line will follow so that the plot line, vertical and horizontal cursor lines intersect in the same point. You can set which channel is the source for each of the cursors. At the bottom of the plot area is the data line. It displays the X and Y values for each of the cursors. In addition, ΔX, ΔY, and 1/ΔX is calculated and displayed. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 64 Figure 3-16. Oscilloscope Cursors Show and Hide the Cursors In the Cursor area in the Oscilloscope control panel, toggle the Show button to show or hide the cursors and the cursor data line in the plot area. Select Cursor Source Channel In the Cursor group in the oscilloscopeʼs control panel, click on the Cursor 1 and Cursor 2 drop-down list boxes to select the channel to use as the source for that channel. Pick the color matching the channel chosen for use. The cursorʼs X and Y labels in the data line will change color to match the color of the channel selected. Move a Cursor Only the vertical line (the X value) of a cursor can be moved. The horizontal line (the Y value) will follow. • Position the cursor over the vertical cursor line. The mouse cursor will change into a left/right cursor. Click and drag the cursor to its new position. After repositioning a cursor, the readouts in the data line are updated. Bring a Cursor Into View After some zooming and panning, a cursor can end up far outside the visible region. It is easy to bring it back into view: • Right-click on the X1 or Y1 labels in the data line. From the pop-up menu, select Bring into view. 3.3.2 Oscilloscope Configuration Example This chapter gives an example on how to configure the Oscilloscope module to be used with a target application implementing a Night mode switch with a light sensor. Although this example only utilizes the SPI interface as data source, the procedure will be the same for all data sources. The target code used in this example and a description of the hardware setup can be found in Oscilloscope Example Code. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 65 To do:  Select correct tool in the DGI Control Panel. To do:  Click Connect to make a connection to the DGI on the selected tool. To do:  • Click the SPI checkbox • Open the SPI Configuration dialog by clicking the Gear button next to the SPI checkbox Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 66 To do:  • Open the configuration panel • Add an Oscilloscope module to the Data Visualizer • Drag the source connector from the interface in the DGI Control Panel into the sink for the oscilloscope channel to make a connection Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 67 The Oscilloscope module can now be used to analyze the data acquired from the light sensor when toggling a desk lamp ON and OFF above the I/O1 Xplained Pro. To do:  • Set sample rate to 100 kHz • Enable Trigger on falling Edge and set Mode to Normal • Push Start in the DGI Control Panel • Push the Run-Stop button in the Oscilloscope module After some adjustments of the trigger level by dragging it with the mouse in the oscilloscope plot area, and zooming in on the plot by adjusting the Horizontal and Vertical range, a lamp switch on event could look something like the picture below. By turning on the Cursors it is possible to measure the time it takes for the lamp to settle in the ON state. In this case, it took about 300 ms (ΔX in the plot area). Zooming further in on the plot makes it possible to use the cursors to measure the frequency of the light flickering. The 1/ΔX field in the plot area shows that the frequency is about 100 Hz, which matches well with the 50 Hz AC power of the lamp (the power switches polarity 100 times per second). Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 68 3.4 Power Debugging The Power Debugging module displays current and voltage measurements (commonly referred to as power measurements) generated by the Power interface in the DGI Control Panel. The power measurements can be combined with various other interfaces like GPIO and Code Profiling in the same graph to correlate code execution on the target MCU and power consumption of the target application. 3.4.1 Power Debugging Module The Power Debugging module displays the current consumption of a connected kit. To get started with basic current measurements, see the Basic Current Measurement chapter. For an example on how to use cursors, see Power Analysis using Cursors. For examples on how to correlate current consumption with code execution, see Code Correlation. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 69 Figure 3-17. Power Debugging 1. Current consumption graph. 2. Y-axis of channel A. 3. Channel A average and instant values. 4. Yaxis of channel B. 5. Control Panel. 6. Auto-scroll checkbox. 7. Automatically fit Y checkbox.  8. X-axis (time), unit is [minutes]:[seconds].  Important:  The Power module can only be used with the Power interface. 3.4.1.1 Scaling and Scrolling a Graph Tip:  Turn off Auto-scroll and Automatically fit Y to more closely examine a plot while it is still running. Use the scale and offset controls in order to move the plots as needed. The mouse scroll-wheel is useful in this regard: • Shift-scroll on the plot to zoom on the time (X) axis • Ctrl-scroll on the plot to zoom on the Y axis • Drag the graph to pan on the time (X) axis and move (offset) the Y axis • Drag the scales on the left and right to move respective channels in the Y axis (offset) • Ctrl-scroll on the respective axis scale to zoom that channel • Right-click and drag to select an area to zoom 3.4.1.2 Power Debugging Module Control Panel The Power Debugging module Control Panel is placed in the upper right corner of the module. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 70 Notice:  Not all configuration options in the control panel are available on all tools. For example, only the Power Debugger has both an A channel and a B channel. All options will be visible for all tools, but will have no effect unless the tool supports them. The Auto-scroll option controls the scrolling in the X-axis direction (time axis). To zoom in on and examine the graphs in detail, disable this option. The Automatically fit Y option controls whether the Data Visualizer will automatically adjust the range of the Y axis according to the graph content or not. If this option is enabled, any manual adjustments of the Y axis will be overridden. The Show zero option controls whether the zero-point of the Y axis should always be visible when Automatically fit Y is enabled. Channel Configuration For each power measurement channel there is a Channel configuration section in the Control Panel of the Power Analysis module. The channel section allows the user to enable/disable the current and voltage graphs in the Power Analysis module. Notice:  If the Enable B Channel option in the Power Configuration of the DGI Control Panel (see Power Interface) is not selected, the B channel will not be available even though the tool has a B channel. But the B channel configuration will still be visible in the Control Panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 71 The Range setting enables the measurement range data for the current measurement channel. To cover the full range of current values supported by the current measurement channel, most tools have two or more hardware configurations for each channel. The number of ranges for a channel varies with the connected tool. The switching between the hardware configurations is done automatically based on the instant current measured. Notice:  The range graph will only be visible if the Enable Range Source option in the Power Configuration of the DGI Control Panel is selected. The Mode option allows for different averaging algorithms to be used for the display of data if this is enabled for the current tool. Code Location The Code Location section contains no options, just the source connection. To enable code locations in the Power Analysis graph the Code Profiling interface in the DGI control panel must be enabled and the Enable Code Location option in the Code Profiling Configuration of the DGI Control Panel must be enabled. GPIO Each of the GPIO sources can be switched ON or OFF in the GPIO section of the Control Panel of the Power Analysis module. For GPIO data to be available for the Power Analysis module the GPIO interface has to be enabled in the DGI Control Panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 72 Cursors The Cursors section in the Power Analysis module Control Panel allows the user to enable two vertical cursors in the graph by checking the Enabled box. The cursors can be moved by using the mouse pointer to drag them along the X-axis or they can be centered by pushing the Center button. When the cursors are enabled the section of the graph between the cursors can be used for various measurements. The measurements will be shown in the Cursors section below the graph. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 73 Which measurements to be shown can be selected in the Measurements sub-section of the Cursors section in the Power Analysis module Control Panel. 3.4.2 Basic Current Measurement To do:  Select the correct tool in the DGI Control Panel. To do:  Connect to the DGI on the selected tool. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 74 To do:  Enable the Power interface and modify its settings to monitor the relevant channels. To do:  Start the Data Visualizer session. 3.4.2.1 Two Channel Measurement When using hardware with two measurement channels, the Data Visualizer will display both in the same graph (unless disabled in the Power Configuration). Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 75 On the Control panel on the right of the module the user can show or hide the current and voltage plots as well as range information when available. By default, both channels will be shown in the Power Analysis graph but each plot can be moved up or down to separate them as best suited. 3.4.2.2 Scaling and Scrolling a Graph Tip:  Turn off Auto-scroll and Automatically fit Y to more closely examine a plot while it is still running. Use the scale and offset controls in order to move the plots as needed. The mouse scroll-wheel is useful in this regard: • Shift-scroll on the plot to zoom on the time (X) axis • Ctrl-scroll on the plot to zoom on the Y axis • Drag the graph to pan on the time (X) axis and move (offset) the Y axis • Drag the scales on the left and right to move respective channels in the Y axis (offset) • Ctrl-scroll on the respective axis scale to zoom that channel • Right-click and drag to select an area to zoom 3.4.2.3 Current Averaging The Power Analysis module displays two averaged values per channel. One shows the instantaneous current value, while the other shows the average of the samples visible in the graph view. 3.4.2.4 Power Measurement Calibration To achieve full measurement accuracy on the current measurement hardware, it should be calibrated before running the measurements. The calibration procedure is started through the Power Configuration window in the Power interface in the DGI Control Panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 76 Figure 3-18. Triggering Power Measurement Calibration from the Power Configuration Window To start the calibration procedure, select Trigger calibration and press OK. Then follow the instructions to complete the calibration procedure for the tool. 3.4.3 Power Analysis using Cursors In order to analyze the current more closely, the cursor feature of the Power Analysis module is useful. To do:  • Open the Control Panel in the upper right corner of the Power Analysis module • Expand the Cursors section • Click the Enabled box to turn the cursors on Remember:  If the current measurements are still running, make sure to disable Auto-scroll before enabling the cursors, or else the graph view will rapidly scroll away from the cursors. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 77 The example above shows the current consumption of a target board with a LED that toggles ON and OFF regularly. The cursor data at the bottom of the module shows that the current consumption when the LED is OFF is about 354 μA, while the current consumption when the LED is ON is about 6.5 mA. The average current consumption during one period of the LED toggling is about 580 μA. As the current measurement channel is also monitoring voltage, you can measure the power consumption directly. Enable this by setting the corresponding options in the Measurements section of the Cursors section in the Control Panel of the Power Analysis module. 3.4.4 Code Correlation To optimize current consumption, current measurements must be correlated to the code execution of the application. The Data Visualizer enables code correlation by the use of GPIO instrumentation or program counter sample readout. Crucial to both these methods is the ability to show the code execution related events with the same time base and in the same graph as the current consumption. 3.4.4.1 GPIO Instrumentation By inserting simple GPIO toggling in the application code, the user can generate common reference points between the measured current and the code execution. The Data Visualizer is capable of showing the GPIO events in the same graph as the current measurements. A mass storage application will be used to demonstrate the use of GPIO instrumentation. Both Target USB and Debug USB connectors of a SAM L21 Xplained Pro board is connected to a host computer. The ATSAML21 target device is running the USB Device MSC Example from ASF for SAM L21 Xplained Pro (in Atmel Studio select File→New→Example Project and search for “MSC”). The Current Measurement jumpers on the kit are set to measure MCU current and bypass I/O current. The current graph after running a format of the mass storage device: Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 78 A disk format operation consists of both read and write operations, but with just the current it is difficult to tell what is going on when. To be able to separate the read and write operations, the application code is modified to set GPIO0 (PB01 on the ATSAML21) high on the start of a read operation and set it low at the end of the read operation. GPIO1 (PA16 on the ATSAML21) is similarly toggled for write operations. Both the GPIO interface and the Power interface must be enabled in the DGI Control Panel of the Data Visualizer as shown below. In the Control Panel of the Power Analysis module disable GPIO2 and GPIO3 as shown below. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 79 With the GPIO signals enabled, the user can distinguish the current consumption of the read and write operations. The yellow signal is GPIO0 which signals the read operations and the green signal is GPIO1 showing the write operations. 3.4.4.2 Program Counter Polling Each time the Program Counter (PC) is read out from the target, we get the exact information on the address of the code location currently being executed. The Data Visualizer can show PC values with current measurements in the same graph. This allows the user to see what is being executed by the target CPU at the various sample points of the current consumption graph. The sampled PC values will only show part of the code execution, as in most cases it is impossible to read out the PC values as fast as the target is executing instructions. The sampled values are still useful to indicate which code segment is being executed at any point in time. A SAM L21 Xplained Pro board running a Mass Storage Class example will be used to demonstrate PC polling. Both Target USB and Debug USB connectors of a SAM L21 Xplained Pro board is connected to a host computer. The ATSAML21 target device is running the USB Device MSC Example from ASF for SAM L21 Xplained Pro (in Atmel Studio select File→New→Example Project and search for “MSC”). The Current Measurement jumpers on the kit are set to measure MCU current and bypass I/O current. The current graph after running a format of the mass storage device: A disk format operation consists of both read and write operations, but from the current graph it is difficult to see what is going on when. To get more information on what is going on in the target at the various points in the current graph, the Program Counter sampling feature will be useful. To view Program Counter samples together with current measurement data both the Power interface and the Code Profiling interface must be enabled. To do:  • Enable both Power interface and Code Profiling interface in DGI Control Panel Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 80 To do:  • Open the Code Profiling Configuration dialog by clicking the Gear button on the Code Profiling interface • Select Enable Code Location A typical current graph with Program Counter sampling enabled during a format operation is shown below. The yellow points plotted on the graph represent polled Program Counter values. Their location on the y axis is a visual representation of their location in the code-space of the target device. The relative grouping of samples shows the execution of different functions. Patterns can easily be seen using this technique. Hovering over one of the samples shows the location of that sample in the Code location details box below the graph, as well as the value of the current sample at that point. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 81 Double-clicking on one of the samples will open the editor and highlight the corresponding line of code. The highlighted sample is located in a function called udi_msc_trans_block. This function transfers data from RAM to USB. From the graph it can be seen that the current spike at the marker is generated by the execution of this function as all Program Counter samples are from the same location during this spike. 3.5 Custom Dashboard The Dashboard module is a customizable Graphical User Interface (GUI) panel. It can be used to control and display parameters from the target application. 3.5.1 Dashboard Module The Dashboard module is a customizable Graphical User Interface (GUI) panel. It can be used to control and display parameters from the application firmware. Elements (button, label, slider, etc.) are placed in the dashboard area to form the GUI. Each element can have an endpoint associated with it to send or Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 82 receive values. A slider, for example, has a source that outputs the slider position as a numeric value. Endpoints are shown when the Show Endpoints option is selected. For an example on how to configure a dashboard, see Dashboard Configuration Example. Figure 3-19. Dashboard 1. Dashboard area. 2. Edit checkbox. 3. Show Endpoints checkbox. 4. Height adjustment tab.  3.5.1.1 Edit Panel When going into Edit mode (by selecting the Edit box), the Edit panel will become visible. Here the user can customize the dashboard. Figure 3-20. Edit Panel Placing Elements on the Dashboard By default, the dashboard area is empty. Elements can be placed on the dashboard by following the procedure below. • Click the Edit checkbox • Open the Elements panel in the upper right corner of the dashboard area • Click and hold the element • Drag the mouse over the dashboard area • Drop the element in the dashboard area on the desired location Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 83 Configuring Dashboard Elements All dashboard elements can be configured when in Edit mode. The parameters will vary depending on element type, but the procedure for changing them is the same. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 84 Figure 3-21. Element Configuration 1. Common parameters. 2. Element-specific parameters. 3. Set button.  • Click the Edit checkbox • Select the element to configure by clicking it. The Configuration window will list the configurable parameters for the selected element. • Change the parameters to the desired value • Click the Set button Moving Elements All parameters related to position and size are available in the element configurations. Elements can also be moved by dragging them around in the dashboard area in Edit mode. Resizing can be done by dragging the black tab in the corner after selecting an element. Deleting Elements To delete unwanted elements, simply select the element by left-clicking it, and then right-click it to delete. Important:  This action is permanent, and all configuration is lost after deletion. Loading and Saving The dashboard can be saved by clicking the Save button in Edit mode. All elements and configuration parameters, in addition to dashboard background color, will be stored. To load a dashboard, click the Load button and browse to a valid dashboard save file. The saved file is a text file but could have any file extension containing all configuration parameters for each dashboard element enclosed in curly brackets {} and separated by a semicolon. Each line corresponds to one configuration parameter and the format of each parameter is a list of decimal byte values separated by commas. Each configuration parameter is given by the Least Significant Byte first. The order of the configuration parameters are the same as the order of the configuration parameters in the Configuration window when the Edit option for the dashboard is selected. Comments are marked by Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 85 double forward slashes "//" and the rest of the line is ignored by the parser when encountering double slashes. A simple example of a saved dashboard configuration is given below. A more complex example can be found in Auto-Configuration Example. The file content of the saved configuration for this dashboard is given below. { 0, '\0', 0, 255, 255, 255, 158, 0, }; { 0, // Dashboard ID 0, // Element ID DB_TYPE_LABEL, // Element Type 0, // Z-Index (GUI stack order) 61, 0, // X-coordinate 46, 0, // Y-coordinate 122, 0, // Width 17, 0, // Height 12, // Font Size 1, 0, // Horizontal Alignment 0, // Vertical Alignment 0, 255, 255, 255, // Background Color 255, 0, 0, 0, // Foreground Color 'T', 'E', 'S', 'T', ' ', 'D', 'A', 'S', 'H', 'B', 'O', 'A', 'R', 'D', '\0', // Text }; { 0, // Dashboard ID 1, // Element ID DB_TYPE_BUTTON, // Element Type 0, // Z-Index (GUI stack order) 61, 0, // X-coordinate 70, 0, // Y-coordinate 75, 0, // Width 25, 0, // Height 12, // Font Size 'B', 'u', 't', 't', 'o', 'n', '\0', // Text 0, }; The first element in the file is the dashboard itself. The first line defines the Dashboard ID (0). Then follows the Title of the dashboard (empty string), the background color of the dashboard (Alpha = 0x00, Red = 0xFF, Green = 0xFF and Blue = 0xFF), and the height of the dashboard (two byte value, LSB first; 152, 0 => 152 = 0x0098 pixels). Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 86 The following elements are the Label element and the Button element. Note that strings are null terminated (\0). Checkboxes are usually grouped and only one bit per checkbox is used to indicate the checkbox state. For example, for the Label element there are two checkboxes following each other in the Edit window, one named Bold and one Italic. These are combined into one Configuration byte with bit 0 giving the state of the Bold checkbox and bit 1 giving the state of the Italic checkbox. In the example above, this is the 1 between Font size and Horizontal alignment. The value 1 indicates that the Label text format should be bold but not italic. Drop-down boxes are given as single byte values with a number corresponding to the selected option. The topmost option in the list corresponds to a configuration value of 0. For example, for the Label element the Horizontal Alignment can be either Left=0, Center=1, or Right=2. Setting Background Color The square next to the Load button is the Background color selector. Clicking the selector will bring up the Color selector dialog. Use the sliders to select the desired color, then press OK. 3.5.1.2 Element Types The various dashboard element types are presented in this section. All element types have some common parameters. These are listed in the table below. The following sections will list only the parameters specific to each element type. Table 3-1. Common Element Parameters Parameter Type Usage Z-index Numeric Order index, 0 places the element the farthest to the back Left Numeric Horizontal placement, unit pixels Top Numeric Vertical placement, unit pixels Width Numeric Width of element in pixels Height Numeric Height of element in pixels Label The Label element displays a text string. Figure 3-22. Label Endpoints The Label element has a sink endpoint that accepts all types of sources. Any data sent to the label will be converted to a string and displayed as text. Configuration Table 3-2. Label Specific Parameters Parameter Type Usage Font Size Numeric Adjusts the size of the font Bold Checkbox Sets bold style of the font Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 87 Parameter Type Usage Italic Checkbox Sets italic style of the font Horizontal Alignment Dropdown box Selects the alignment of the text within the specified width Vertical Alignment Dropdown box Selects the alignment of the text within the specified height Background Color Color Sets the background color of the label Foreground Color Color Sets the color of the text Text String Sets the label text Numeric Input The Numeric Input element enables input of numeric values to the dashboard. Figure 3-23. Numerical Input Endpoints The Numeric Input has a source endpoint of type int32. Each time the numerical input value is changed a packet with the value is sent. Configuration Table 3-3. Numerical Input Specific Parameters Parameter Type Usage Minimum Numeric Minimum value of input Maximum Numeric Maximum value of input Value Numeric Initial value Button The Button element will send an event each time it is pressed. The button can either be configured as a normal push button or as a toggle button. The button can have a static text to indicate its functionality. When it is configured as a toggle button the text will be replaced by ON or OFF depending on the state of the button. To replace the ON/OFF text by something else the Text parameter must be given as a '/' delimited text with the first part of the text being the ON state text and the second part the OFF state text. Figure 3-24. Button Endpoints The Button element has a source endpoint of type uint8. Each time the button is pressed a packet is sent. The value of the packet will always be 0 for a normal button and 0 for a toggle button in its OFF state and a 1 for a toggle button in its ON state. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 88 Configuration Table 3-4. Button Parameters Parameter Type Usage Font Size Numeric Sets the font size of the button tag Text String Sets the button tag text. If the button is configured as a toggle button the test should be delimited by '/'. The first part of the text will then be the ON state text while the second part will be the OFF state text. Toggle Button Checkbox Configures the button to be a ON/OFF toggle switch. Radio Group The Radio Group element is a group of radio buttons where only one option can be selected at any time. Initially the first option is selected. Figure 3-25. Radio Group Endpoints The Radio Group element has a source endpoint of type uint16. Each time the state of the element is changed a message is sent with the index of the currently active option. Configuration Table 3-5. Radio Group Specific Parameters Parameter Type Usage Font Size Numeric Font size of the button text Number of Radio Buttons Numeric Number of buttons in the group Orientation Numeric 0 = Horizontal 1 = Vertical Text String '/' delimited text with the text for each button starting with the text for button with index 0 Check Box The Check Box element will send an event each time its state is changed. Figure 3-26. Check Box Endpoints The Check Box element has a source endpoint of type uint8. Every time the state of the element is changed a message is sent. When the box is checked a 1 is sent and when it is unchecked a 0 is sent. Configuration Table 3-6. Check Box Specific Parameters Parameter Type Usage Font Size Numeric Font size for the text Text String Sets the Check Box tag text Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 89 Slider The Slider element is a linear bar with a movable marker. The marker can be moved to adjust the value of the slider. Figure 3-27. Slider Endpoints The Slider element has a source endpoint of type double. When the slider value is changed a packet with the value is sent. Configuration Table 3-7. Slider Parameters Parameter Type Usage Minimum Numeric Sets the minimum value of the slider Maximum Numeric Sets the maximum value of the slider Value Numeric Sets the value of the slider Signal The Signal element is a simple color-based ON/OFF indicator. Figure 3-28. Signal Endpoints The Signal element has a sink endpoint that accepts all data types, but ignores strings and multidimensional values. The color of the signal is decided by a boolean evaluation, if the incoming value is a number it is true if it is greater than 0. Configuration Table 3-8. Signal Parameters Parameter Type Usage Color On Color Selects the color used when the signal is ON Color Off Color Selects the color used when the signal is OFF Progress Bar The Progress bar element is a linear bar that shows the position of a value between a min. and max. value. Figure 3-29. Progress Bar Endpoints The Progress bar element has a sink endpoint that accepts all numeric data types. When a value is received, it will update the amount of colored area of the progress bar depending on the min. and max. values. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 90 Configuration Table 3-9. Progress Bar Parameters Parameter Type Usage Minimum Numeric Sets the minimum value of the progress bar Maximum Numeric Sets the maximum value of the progress bar Value Numeric Sets the value of the progress bar Color Color Sets the color of the progress bar Segment Display The Segment display element simulates a hex-digit LED display. Figure 3-30. Segment Display Endpoints The Segment display element has a sink endpoint that accepts all numeric data types. The value received is displayed. Configuration Table 3-10. Segment Display Parameters Parameter Type Usage Segment Count Numeric Number of hex-segments to display Numeric Base Numeric Sets the base used for displaying numbers Segment Color Color Sets the color of the segment display Graph The Graph element plots the incoming data streams in a two-dimensional graph. The graph can be configured to accept zooming and scrolling by mouse interaction or to be static ignoring any mouse interaction. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 91 Figure 3-31. Graph Endpoints The Graph element has one sink endpoint for each plot. The endpoints accepts all numerical data types. Each plot in the Graph can be shown or hidden dynamically by clicking the legend corresponding to the plot at the bottom of the Graph element. Hidden plots have a gray legend compared to visible plots having the same color on the legend as the plot itself. Figure 3-32. Graph with Visible SPI Output Plot and Hidden TWI Output Plot In the graph above the plot SPI Output is visible while the plot TWI Output is hidden. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 92 Configuration Table 3-11. Graph Specific Parameters Parameter Type Usage Title color Color Selects the color of the title text Background color Color Selects the color of the complete Graph element background Graph background color Color Selects the color of the graph plot area background Title String Title of the graph Number of plots Numeric Number of plots to display in the graph. Each plot will have its own sink endpoint. X Minimum Numeric Minimum value of X axis X Maximum Numeric Maximum value of X axis Y Minimum Numeric Minimum value of Y axis Y Maximum Numeric Maximum value of Y axis Mouse Interaction Checkbox Enable mouse interaction with the Graph element Fit to right Checkbox Expand the Graph element to the right edge of the dashboard Autoscale Checkbox Automatically scale Y axis accoriding to plot data Scroll by time Checkbox Scroll X axis by time. If not checked the X axis will scroll by incoming plot samples. Show plot Checkbox View continuous graph plot (sample points interconnected) Show points Checkbox Show single samples as dots Pie Chart The Pie Chart element displays the value of the incoming streams as slices in a pie chart. Figure 3-33. Pie Chart Endpoints The Pie Chart element has one sink endpoint for each slice in the pie chart. The sink endpoints accepts all numerical data types. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 93 Configuration Table 3-12. Pie Chart Specific Parameters Parameter Type Usage Title color Color Selects the color of the title text Background color Color Selects the element background color Title String Title of the element Number of plots Numeric Number of slizes in the pie chart Rectangle The Rectangle element sends a packet each time it is clicked by the mouse. Figure 3-34. Rectangle Endpoints The Rectangle element has a source endpoint of type uint32. Each time the element is clicked by the mouse pointer a packet with value 0 is sent. Configuration Table 3-13. Rectangle Specific Parameters Parameter Type Usage Background color Color Selects the color of the fill of the rectangle Foreground color Color Selects the color of the frame of the rectangle Surface The Surface element displays grid data as a surface in 3D space. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 94 Figure 3-35. Surface Endpoints The Surface element has one endpoint accepting any source of a grid type. Configuration Table 3-14. Surface Specific Parameters Parameter Type Usage Fill color Color Selects the color of the surface fill Mesh color Color Selects the color of the surface mesh Background color Color Selects the color of the background Background gradient color Color Selects the color of the background gradient Axis color Color Selects the color of the axes Tick color Color Selects the color of the tick labels X Rotation Numeric Sets rotation of view around X Y Rotation Numeric Sets rotation of view around Y Z Rotation Numeric Sets rotation of view around Z Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 95 Parameter Type Usage Show X-axis Checkbox Sets visibility of X-axis Show Y-axis Checkbox Sets visibility of Y-axis Show Z-axis Checkbox Sets visibility of Z-axis Show fill Checkbox Sets visibility of surface fill Show mesh Checkbox Sets visibility of surface mesh Use palette coloring Checkbox Sets usage of palette coloring (red-yellow-green-white) Scaling mode Drop-down box Selects mode of Y-axis auto-scaling Axis minimum Numeric Sets minimum axis value for Y Axis maximum Numeric Sets maximum axis value for Y Table The Table element displays one or more data sources in a table. Two modes are supported, Auto Labels and Manual Labels. In the Auto Labels mode, each cell is split into two fields, the field to the left is a label with the name of the data stream and the field to the right is the actual data of the stream. In the Manual Labels mode each cell can be manually configured to either be a Label cell or a Data cell. The mode is selected by the checkbox named Auto Labels in the configuration, see Configuration. Auto Labels When using the Auto Labels mode each cell is associated with one data source and the name of the data source is shown to the left in the cell and the actual data to the right. The source name is automatically fetched from the source connected to the sink endpoint. The Table element has one endpoint per table cell accepting any data source. The data will be converted to a string and displayed as text. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 96 Endpoints are shown when the Show Endpoints option is selected. Manual Labels When using the Manual Labels mode each cell either is a Label cell or a Data cell. By default all cells are Data cells. Label cells can be configured by setting the Label Configuration string, see Configuration. The Label Configuration string configures which cells are Labels by giving a semicolon separated list of Labels. Each Label is given by the format ::

Features • High performance, low power Atmel® AVR® 8-bit Microcontroller • Advanced RISC architecture – 131 powerful instructions - most single clock cycle execution – 32 × 8 general purpose working registers – Fully static operation – Up to eight MIPS throughput at 8MHz • High endurance non-volatile memory segments – 16K/32Kbytes of in-system self-programmable flash (Atmel ATmega16HVB/32HVB) – 512/1Kbytes EEPROM – 1K/2Kbytes internal SRAM – Write/erase cycles 10,000 flash/100,000 EEPROM – Data retention: 20 years at 85°C/100 years at 25°C (1) – Optional boot code section with independent lock bits In-system programming by on-chip boot program True read-while-write operation – Programming lock for software security • Battery management features – Two, three or four cells in series – High-current protection (charge and discharge) – Over-current protection (charge and discharge) – Short-circuit protection (discharge) – High-voltage outputs to drive N-channel charge/discharge FETs – Optional deep under voltage recovery mode - allowing 0-volt charging without external precharge FET – Optional high-voltage open drain output - allowing 0-volt charging with external precharge FET – Integrated cell balancing FETs • Peripheral features – Two configurable 8-bit or 16-bit timers with separate prescaler, optional input capture (IC), compare mode and CTC – SPI - serial peripheral interface – 12-bit voltage ADC, six external and one internal ADC input – High resolution coulomb counter ADC for current measurements – TWI serial interface supporting SMBus implementation – Programmable watchdog timer • Special microcontroller features – debugWIRE on-chip debug system – In-system programmable via SPI ports – Power-on reset – On-chip voltage regulator with short-circuit monitoring interface – External and Internal interrupt sources – Sleep modes: idle, ADC noise reduction, power-save, and power-off • Additional secure authentication features available only under NDA • Packages – 44-pin TSSOP • Operating voltage: 4V -18V • Maximum withstand voltage (high-voltage pins): 35V • Temperature range: -40°C to 85°C • Speed grade: 1MHz - 8MHz Note: 1. See ”Data retention” on page 8 for details. 8-bit Microcontroller with 16K/32Kbytes In-System Programmable Flash ATmega16HVB ATmega32HVB 8042E–AVR–09/2013 2 8042E–AVR–09/2013 ATmega16HVB/32HVB 1. Pin configurations 1.1 TSSOP Figure 1-1. TSSOP - pinout the Atmel ATmega16HVB/32HVB. 1 44 3 PI PPI NV PV1 PV2 PV3 PV4 PVT VCC GND PC5 PC4(SCL) PC3(INT3/SDA) PC2(INT2) PC1(INT1) PC0(INT0/EXTPROT) PB7(MISO/PCINT11) NC PB6(MOSI/PCINT10) PB5(SCK/PCINT9) PB4(SS/PCINT8) PB3(PCINT7) 2 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 43 42 41 40 39 38 37 36 35 34 33 32 31 30 29 28 27 26 25 24 23 NI NNI VREFGND VREF GND VREG PA0(ADC0/SGND/PCINT0) PA1(ADC1/SGND/PCINT1) PA2(PCINT2/T0) PA3(PCINT3/T1) VCLMP10 VFET BATT VCC GND OD NC OC RESET/dw PB0(PCINT4/ICP00) PB1(PCINT5/CKOUT) PB2(PCINT6) 3 8042E–AVR–09/2013 ATmega16HVB/32HVB 1.2 Pin descriptions 1.2.1 VFET High voltage supply pin. This pin is used as supply for the internal voltage regulator, described in ”Voltage regulator” on page 129. 1.2.2 VCLMP10 Internal 10V clamping of VFET voltage for external decoupling. 1.2.3 VCC Digital supply voltage. Normally connected to VREG. 1.2.4 VREG Output from the internal voltage regulator. Used for external decoupling to ensure stable regulator operation. For details, see ”Voltage regulator” on page 129. 1.2.5 VREF Internal voltage reference for external decoupling. For details, see ”Voltage reference and temperature sensor” on page 122. 1.2.6 VREFGND Ground for decoupling of internal voltage reference. For details, see ”Voltage reference and temperature sensor” on page 122. Do not connect to GND or SGND on PCB. 1.2.7 GND Ground. 1.2.8 Port A (PA3..PA0) Port A serves as a low-voltage 4-bit bi-directional I/O port with internal pull-up resistors (selected for each bit). As inputs, Port A pins that are externally pulled low will source current if the pull-up resistors are activated. The Port A pins are tri-stated when a reset condition becomes active, even if the clock is not running. Port A also serves the functions of various special features of the Atmel ATmega16HVB/32HVB as listed in ”Alternate functions of Port A” on page 74. 1.2.9 Port B (PB7..PB0) Port B is a low-voltage 8-bit bi-directional I/O port with internal pull-up resistors (selected for each bit). As inputs, Port B pins that are externally pulled low will source current if the pull-up resistors are activated. The Port B pins are tri-stated when a reset condition becomes active, even if the clock is not running. Port B also serves the functions of various special features of the ATmega16HVB/32HVB as listed in ”Alternate functions of Port B” on page 75. 1.2.10 Port C (PC5) Port C (PC5) is a high voltage Open Drain output port. 4 8042E–AVR–09/2013 ATmega16HVB/32HVB 1.2.11 Port C (PC4..PC0) Port C is a 5-bit high voltage Open Drain bi-directional I/O port. 1.2.12 OC/OD High voltage output to drive Charge/Discharge FET. For details, see ”FET driver” on page 145. 1.2.13 PI/NI Filtered positive/negative input from external current sense resistor, used to by the Coulomb Counter ADC to measure charge/discharge currents flowing in the battery pack. For details, see ”Coulomb counter – Dedicated fuel gauging Sigma-Delta ADC” on page 108. 1.2.14 PPI/NNI Unfiltered positive/negative input from external current sense resistor, used by the battery protection circuit, for over-current and short-circuit detection. For details, see ”Battery protection” on page 132. 1.2.15 NV/PV1/PV2/PV3/PV4 NV, PV1, PV2, PV3, and PV4 are the inputs for battery cells one, two, three and four, used by the Voltage ADC to measure each cell voltage. For details, see ”Voltage ADC – 7-channel general purpose 12-bit Sigma-Delta ADC” on page 116. 1.2.16 PVT Defines the source voltage level for the Charge FET driver. For details, see ”FET driver” on page 145. 1.2.17 BATT Input for detecting when a charger is connected. Defines the source voltage level for the Discharge FET driver. For details, see ”FET driver” on page 145. 1.2.18 RESET/dw Reset input. A low level on this pin for longer than the minimum pulse length will generate a reset, even if the clock is not running. The minimum pulse length is given in Table 32-3 on page 227. Shorter pulses are not guaranteed to generate a reset. This pin is also used as debugWIRE communication pin. 5 8042E–AVR–09/2013 ATmega16HVB/32HVB 2. Overview The Atmel ATmega16HVB/32HVB is a monitoring and protection circuit for 3- and 4-cell Li-ion applications with focus on highest safety including safe authentication, low cost and high utilization of the cell energy. The device contains secure authentication features as well as autonomous battery protection during charging and discharging. The External Protection Input can be used to implement other battery protection mechanisms using external components, for example, protection against chargers with too high charge voltage can be easily implemented with a few low cost passive components. The feature set makes the ATmega16HVB/32HVB a key component in any system focusing on high security, battery protection, high system utilization and low cost. Figure 2-1. Block diagram. ATmega16HVB/32HVB provides the necessary redundancy on-chip to make sure that the battery is protected in critical failure modes. The chip is specifically designed to provide safety for the battery cells in case of pin shorting, loss of power (either caused by battery pack short or VCC short), illegal charger connection or software runaway. This makes ATmega16HVB/32HVB the ideal one-chip solution for applications with focus on high safety. The ATmega16HVB/32HVB features an integrated voltage regulator that operates at a wide range of input voltages, 4 - 18 volts. This voltage is regulated to a constant supply voltage of PORTA (4) Flash SRAM CPU EEPROM PV2 NV OC FET Control Voltage ADC Voltage Reference Coulomb Counter ADC GND VCC RESET/dW Power Supervision POR & RESET Watchdog Oscillator Watchdog Timer Oscillator Circuits / Clock Generation VREF VREFGND PI NI PA3..0 PA1..0 8/16-bit T/C1 8/16-bit T/C0 PORTB (8) PB7..0 SPI Voltage Regulator Charger Detect VFET VREG BATT PV1 DATA BUS VPTAT Current Protection Security Module PORTC (6) PC5..0 Voltage Regulator Monitor Interface PB0 Oscillator Sampling Interface Program Logic debugWIRE Cell Balancing PV3 TWI PV4 PPI NNI OD PORTA (4) Flash SRAM CPU EEPROM PV2 NV OC FET Control Voltage ADC Voltage Reference Coulomb Counter ADC GND VCC RESET/dW Power Supervision POR & RESET Watchdog Oscillator Watchdog Timer Oscillator Circuits / Clock Generation VREF VREFGND PI NI PA3..0 PA1..0 8/16-bit T/C1 8/16-bit T/C0 PORTB (8) PB7..0 SPI Voltage Regulator Charger Detect VFET VREG BATT PV1 DATA BUS VPTAT Current Protection Security Module PORTC (6) PC5..0 Voltage Regulator Monitor Interface PB0 Oscillator Sampling Interface Program Logic debugWIRE Cell Balancing PV3 TWI PV4 PPI NNI OD 6 8042E–AVR–09/2013 ATmega16HVB/32HVB nominally 3.3 volts for the integrated logic and analog functions. The regulator capabilities, combined with an extremely low power consumption in the power saving modes, greatly enhances the cell energy utilization compared to existing solutions. The chip utilizes the Atmel patented Deep Under-voltage Recovery (DUVR) mode that supports pre-charging of deeply discharged battery cells without using a separate Pre-charge FET. DUVR mode cannot be used in 2-cell applications. Optionally, Pre-charge FETs are supported for integration into many existing battery charging schemes. The battery protection monitors the charge and discharge current to detect illegal conditions and protect the battery from these when required. A 12-bit Voltage ADC allows software to monitor each cell voltage individually with high accuracy. The ADC also provides one internal input channel to measure on-chip temperature and two input channels intended for external thermistors. An 18-bit ADC optimized for Coulomb Counting accumulates charge and discharge currents and reports accumulated current with high resolution and accuracy. It can also be used to provide instantaneous current measurements with 13-bit resolution. Integrated Cell Balancing FETs allow cell balancing algorithms to be implemented in software. The MCU provides the following features: 16K/32Kbytes of In-System Programmable Flash with Read-While-Write capabilities, 512/1Kbytes EEPROM, 1K/2Kbytes SRAM. 32 general purpose working registers, 12 general purpose I/O lines, five general purpose high voltage open drain I/O lines, one general purpose super high voltage open drain output, debugWIRE for on-chip debugging and SPI for In-system Programming, a SM-Bus compliant TWI module, two flexible Timer/Counters with Input Capture and compare modes. Internal and external interrupts, a 12-bit Sigma Delta ADC for voltage and temperature measurements, a high resolution Sigma Delta ADC for Coulomb Counting and instantaneous current measurements, integrated cell balancing FETs, Additional Secure Authentication Features, an autonomous Battery Protection module, a programmable Watchdog Timer with internal Oscillator, and software selectable power saving modes. The AVR core combines a rich instruction set with 32 general purpose working registers. All the 32 registers are directly connected to the Arithmetic Logic Unit (ALU), allowing two independent registers to be accessed in one single instruction executed in one clock cycle. The resulting architecture is more code efficient while achieving throughputs up to ten times faster than conventional CISC microcontrollers. The device is manufactured using the Atmel high voltage high density non-volatile memory technology. The On-chip ISP Flash allows the program memory to be reprogrammed In-System, through an SPI serial interface, by a conventional non-volatile memory programmer or by an Onchip Boot program running on the AVR core. The Boot program can use any interface to download the application program in the Application Flash memory. Software in the Boot Flash section will continue to run while the Application Flash section is updated, providing true ReadWhile-Write operation. By combining an 8-bit RISC CPU with In-System Self-ProgrammableFlash and highly accurate analog front-end in a monolithic chip. The Atmel ATmega16HVB/32HVB is a powerful microcontroller that provides a highly flexible and cost effective solution. It is part of the AVR Battery Management family that provides secure authentication, highly accurate monitoring and autonomous protection for Lithium-ion battery cells. The ATmega16HVB/32HVB AVR is supported with a full suite of program and system development tools including: C Compilers, Macro Assemblers, Program Debugger/Simulators, and Onchip Debugger. 7 8042E–AVR–09/2013 ATmega16HVB/32HVB 2.1 Comparison between the Atmel ATmega16HVB and the Atmel ATmega32HVB The ATmega16HVB and the ATmega32HVB differ only in memory size for flash, EEPROM and internal SRAM. Table 2-1 summarizes the different configuration for the two devices. Table 2-1. Configuration summary. Device Flash EEPROM SRAM ATmega16HVB 16K 512 1K ATmega32HVB 32K 1K 2K 8 8042E–AVR–09/2013 ATmega16HVB/32HVB 3. Disclaimer All parameters contained in this datasheet are preliminary and based on characterization of the Atmel ATmega16/32HVB. 4. Resources A comprehensive set of development tools, application notes and datasheets are available for download on http://www.atmel.com/avr. Note: 1. 5. About code examples This documentation contains simple code examples that briefly show how to use various parts of the device. These code examples assume that the part specific header file is included before compilation. Be aware that not all C compiler vendors include bit definitions in the header files and interrupt handling in C is compiler dependent. Please confirm with the C compiler documentation for more details. For I/O registers located in extended I/O map, “IN”, “OUT”, “SBIS”, “SBIC”, “CBI”, and “SBI” instructions must be replaced with instructions that allow access to extended I/O. Typically “LDS” and “STS” combined with “SBRS”, “SBRC”, “SBR”, and “CBR”. 6. Data retention Reliability Qualification results show that the projected data retention failure rate is much less than one PPM over 20 years at 85°C or 100 years at 25°C. 9 8042E–AVR–09/2013 ATmega16HVB/32HVB 7. AVR CPU core 7.1 Overview This section discusses the Atmel AVR core architecture in general. The main function of the CPU core is to ensure correct program execution. The CPU must therefore be able to access memories, perform calculations, control peripherals, and handle interrupts. Figure 7-1. Block diagram of the AVR architecture. In order to maximize performance and parallelism, the AVR uses a Harvard architecture – with separate memories and buses for program and data. Instructions in the program memory are executed with a single level pipelining. While one instruction is being executed, the next instruction is pre-fetched from the program memory. This concept enables instructions to be executed in every clock cycle. The program memory is In-System Reprogrammable Flash memory. The fast-access Register File contains 32 × 8-bit general purpose working registers with a single clock cycle access time. This allows single-cycle Arithmetic Logic Unit (ALU) operation. In a typFlash Program Memory Instruction Register Instruction Decoder Program Counter Control Lines 32 x 8 General Purpose Registrers ALU Status and Control I/O Lines EEPROM Data Bus 8-bit Data SRAM Direct Addressing Indirect Addressing Interrupt Unit Watchdog Timer I/O Module 2 I/O Module1 I/O Module n 10 8042E–AVR–09/2013 ATmega16HVB/32HVB ical ALU operation, two operands are output from the Register File, the operation is executed, and the result is stored back in the Register File – in one clock cycle. Six of the 32 registers can be used as three 16-bit indirect address register pointers for Data Space addressing – enabling efficient address calculations. One of the these address pointers can also be used as an address pointer for look up tables in Flash program memory. These added function registers are the 16-bit X-register, Y-register, and Z-register, described later in this section. The ALU supports arithmetic and logic operations between registers or between a constant and a register. Single register operations can also be executed in the ALU. After an arithmetic operation, the Status Register is updated to reflect information about the result of the operation. Program flow is provided by conditional and unconditional jump and call instructions, able to directly address the whole address space. Most AVR instructions have a single 16-bit word format. Every program memory address contains a 16-bit or 32-bit instruction. During interrupts and subroutine calls, the return address Program Counter (PC) is stored on the Stack. The Stack is effectively allocated in the general data SRAM, and consequently the Stack size is only limited by the total SRAM size and the usage of the SRAM. All user programs must initialize the SP in the Reset routine (before subroutines or interrupts are executed). The Stack Pointer (SP) is read/write accessible in the I/O space. The data SRAM can easily be accessed through the five different addressing modes supported in the AVR architecture. The memory spaces in the AVR architecture are all linear and regular memory maps. A flexible interrupt module has its control registers in the I/O space with an additional Global Interrupt Enable bit in the Status Register. All interrupts have a separate Interrupt Vector in the Interrupt Vector table. The interrupts have priority in accordance with their Interrupt Vector position. The lower the Interrupt Vector address, the higher the priority. The I/O memory space contains 64 addresses for CPU peripheral functions as Control Registers, SPI, and other I/O functions. The I/O Memory can be accessed directly, or as the Data Space locations following those of the Register File, 0x20 - 0x5F. In addition, the Atmel ATmega16HVB/32HVB has Extended I/O space from 0x60 - 0xFF in SRAM where only the ST/STS/STD and LD/LDS/LDD instructions can be used. 7.2 ALU – Arithmetic Logic Unit The high-performance AVR ALU operates in direct connection with all the 32 general purpose working registers. Within a single clock cycle, arithmetic operations between general purpose registers or between a register and an immediate are executed. The ALU operations are divided into three main categories – arithmetic, logical, and bit-functions. Some implementations of the architecture also provide a powerful multiplier supporting both signed/unsigned multiplication and fractional format. See ”Instruction set summary” on page 259 for a detailed description. 7.3 Status Register The Status Register contains information about the result of the most recently executed arithmetic instruction. This information can be used for altering program flow in order to perform conditional operations. Note that the Status Register is updated after all ALU operations, as specified in the Instruction Set Reference. This will in many cases remove the need for using the dedicated compare instructions, resulting in faster and more compact code. 11 8042E–AVR–09/2013 ATmega16HVB/32HVB The Status Register is not automatically stored when entering an interrupt routine and restored when returning from an interrupt. This must be handled by software. 7.3.1 SREG – AVR Status Register • Bit 7 – I: Global Interrupt Enable The Global Interrupt Enable bit must be set for the interrupts to be enabled. The individual interrupt enable control is then performed in separate control registers. If the Global Interrupt Enable Register is cleared, none of the interrupts are enabled independent of the individual interrupt enable settings. The I-bit is cleared by hardware after an interrupt has occurred, and is set by the RETI instruction to enable subsequent interrupts. The I-bit can also be set and cleared by the application with the SEI and CLI instructions, as described in the Instruction Set Reference. • Bit 6 – T: Bit Copy Storage The Bit Copy instructions BLD (Bit LoaD) and BST (Bit STore) use the T-bit as source or destination for the operated bit. A bit from a register in the Register File can be copied into T by the BST instruction, and a bit in T can be copied into a bit in a register in the Register File by the BLD instruction. • Bit 5 – H: Half Carry Flag The Half Carry Flag H indicates a Half Carry in some arithmetic operations. Half Carry is useful in BCD arithmetic. See the “Instruction Set Description” for detailed information. • Bit 4 – S: Sign Bit, S = N V The S-bit is always an exclusive or between the negative flag N and the Two’s Complement Overflow Flag V. See the “Instruction Set Description” for detailed information. • Bit 3 – V: Two’s Complement Overflow Flag The Two’s Complement Overflow Flag V supports two’s complement arithmetics. See the “Instruction Set Description” for detailed information. • Bit 2 – N: Negative Flag The Negative Flag N indicates a negative result in an arithmetic or logic operation. See the “Instruction Set Description” for detailed information. • Bit 1 – Z: Zero Flag The Zero Flag Z indicates a zero result in an arithmetic or logic operation. See the “Instruction Set Description” for detailed information. • Bit 0 – C: Carry Flag The Carry Flag C indicates a carry in an arithmetic or logic operation. See the “Instruction Set Description” for detailed information. Bit 7 6 5 4 3 2 1 0 0x3F (0x5F) I T H S V N Z C SREG Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 12 8042E–AVR–09/2013 ATmega16HVB/32HVB 7.4 General purpose Register File The Register File is optimized for the AVR Enhanced RISC instruction set. In order to achieve the required performance and flexibility, the following input/output schemes are supported by the Register File: • One 8-bit output operand and one 8-bit result input • Two 8-bit output operands and one 8-bit result input • Two 8-bit output operands and one 16-bit result input • One 16-bit output operand and one 16-bit result input Figure 7-2 shows the structure of the 32 general purpose working registers in the CPU. Figure 7-2. AVR CPU General Purpose Working Registers. Most of the instructions operating on the Register File have direct access to all registers, and most of them are single cycle instructions. As shown in Figure 7-2, each register is also assigned a data memory address, mapping them directly into the first 32 locations of the user Data Space. Although not being physically implemented as SRAM locations, this memory organization provides great flexibility in access of the registers, as the X-pointer, Y-pointer and Z-pointer registers can be set to index any register in the file. 7.4.1 The X-register, Y-register, and Z-register The registers R26..R31 have some added functions to their general purpose usage. These registers are 16-bit address pointers for indirect addressing of the data space. The three indirect address registers X, Y, and Z are defined as described in Figure 7-3 on page 13. 7 0 Addr. R0 0x00 R1 0x01 R2 0x02 … R13 0x0D General R14 0x0E Purpose R15 0x0F Working R16 0x10 Registers R17 0x11 … R26 0x1A X-register Low Byte R27 0x1B X-register High Byte R28 0x1C Y-register Low Byte R29 0x1D Y-register High Byte R30 0x1E Z-register Low Byte R31 0x1F Z-register High Byte 13 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 7-3. The X-register, Y-register, and Z-registers. In the different addressing modes these address registers have functions as fixed displacement, automatic increment, and automatic decrement (see the Instruction Set Reference for details). 7.5 Stack Pointer The Stack is mainly used for storing temporary data, for storing local variables and for storing return addresses after interrupts and subroutine calls. The Stack Pointer Register always points to the top of the Stack. Note that the Stack is implemented as growing from higher memory locations to lower memory locations. This implies that a Stack PUSH command decreases the Stack Pointer. The Stack Pointer points to the data SRAM Stack area where the Subroutine and Interrupt Stacks are located. This Stack space in the data SRAM must be defined by the program before any subroutine calls are executed or interrupts are enabled. The Stack Pointer must be set to point above 0x100. The Stack Pointer is decremented by one when data is pushed onto the Stack with the PUSH instruction, and it is decremented by two when the return address is pushed onto the Stack with subroutine call or interrupt. The Stack Pointer is incremented by one when data is popped from the Stack with the POP instruction, and it is incremented by two when data is popped from the Stack with return from subroutine RET or return from interrupt RETI. The AVR Stack Pointer is implemented as two 8-bit registers in the I/O space. The number of bits actually used is implementation dependent. Note that the data space in some implementations of the AVR architecture is so small that only SPL is needed. In this case, the SPH Register will not be present. 7.5.1 SPH and SPL – Stack Pointer High and Stack Pointer Low 15 XH XL 0 X-register 7 0 7 0 R27 (0x1B) R26 (0x1A) 15 YH YL 0 Y-register 7 0 7 0 R29 (0x1D) R28 (0x1C) 15 ZH ZL 0 Z-register 7 0 7 0 R31 (0x1F) R30 (0x1E) Bit 15 14 13 12 11 10 9 8 0x3E (0x5E) SP15 SP14 SP13 SP12 SP11 SP10 SP9 SP8 SPH 0x3D (0x5D) SP7 SP6 SP5 SP4 SP3 SP2 SP1 SP0 SPL 76543210 Read/Write R/W R/W R/W R/W R/W R/W R/W R/W R/W R/W R/W R/W R/W R/W R/W R/W Initial Value RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND RAMEND 14 8042E–AVR–09/2013 ATmega16HVB/32HVB 7.6 Instruction execution timing This section describes the general access timing concepts for instruction execution. The Atmel AVR CPU is driven by the CPU clock clkCPU, directly generated from the selected clock source for the chip. No internal clock division is used. Figure 7-4 shows the parallel instruction fetches and instruction executions enabled by the Harvard architecture and the fast-access Register File concept. This is the basic pipelining concept to obtain up to one MIPS per MHz with the corresponding unique results for functions per cost, functions per clocks, and functions per power-unit. Figure 7-4. The parallel instruction fetches and instruction executions. Figure 7-5 shows the internal timing concept for the Register File. In a single clock cycle an ALU operation using two register operands is executed, and the result is stored back to the destination register. Figure 7-5. Single cycle ALU pperation. 7.7 Reset and interrupt handling The AVR provides several different interrupt sources. These interrupts and the separate Reset Vector each have a separate program vector in the program memory space. All interrupts are assigned individual enable bits which must be written logic one together with the Global Interrupt Enable bit in the Status Register in order to enable the interrupt. The lowest addresses in the program memory space are by default defined as the Reset and Interrupt Vectors. The complete list of vectors is shown in ”Interrupts” on page 52. The list also determines the priority levels of the different interrupts. The lower the address the higher is the priority level. RESET has the highest priority. clk 1st Instruction Fetch 1st Instruction Execute 2nd Instruction Fetch 2nd Instruction Execute 3rd Instruction Fetch 3rd Instruction Execute 4th Instruction Fetch T1 T2 T3 T4 CPU Total Execution Time Register Operands Fetch ALU Operation Execute Result Write Back T1 T2 T3 T4 clkCPU 15 8042E–AVR–09/2013 ATmega16HVB/32HVB When an interrupt occurs, the Global Interrupt Enable I-bit is cleared and all interrupts are disabled. The user software can write logic one to the I-bit to enable nested interrupts. All enabled interrupts can then interrupt the current interrupt routine. The I-bit is automatically set when a Return from Interrupt instruction – RETI – is executed. There are basically two types of interrupts. The first type is triggered by an event that sets the interrupt flag. For these interrupts, the Program Counter is vectored to the actual Interrupt Vector in order to execute the interrupt handling routine, and hardware clears the corresponding interrupt flag. Interrupt flags can also be cleared by writing a logic one to the flag bit position(s) to be cleared. If an interrupt condition occurs while the corresponding interrupt enable bit is cleared, the interrupt flag will be set and remembered until the interrupt is enabled, or the flag is cleared by software. Similarly, if one or more interrupt conditions occur while the Global Interrupt Enable bit is cleared, the corresponding interrupt flag(s) will be set and remembered until the Global Interrupt Enable bit is set, and will then be executed by order of priority. The second type of interrupts will trigger as long as the interrupt condition is present. These interrupts do not necessarily have interrupt flags. If the interrupt condition disappears before the interrupt is enabled, the interrupt will not be triggered. When the AVR exits from an interrupt, it will always return to the main program and execute one more instruction before any pending interrupt is served. Note that the Status Register is not automatically stored when entering an interrupt routine, nor restored when returning from an interrupt routine. This must be handled by software. When using the CLI instruction to disable interrupts, the interrupts will be immediately disabled. No interrupt will be executed after the CLI instruction, even if it occurs simultaneously with the CLI instruction. The following example shows how this can be used to avoid interrupts during the timed EEPROM write sequence. Assembly code example in r16, SREG ; store SREG value cli ; disable interrupts during timed sequence sbi EECR, EEMPE ; start EEPROM write sbi EECR, EEPE out SREG, r16 ; restore SREG value (I-bit) C code example char cSREG; cSREG = SREG; /* store SREG value */ /* disable interrupts during timed sequence */ _CLI(); EECR |= (1< xxx ; .org 0x4C02 0x4C02 jmp BPINT ; Battery Protection Interrupt Handler 0x4C04 jmp EXT_INT0 ; External Interrupt Request 0 Handler ... ... ... ; 0x4C2C jmp SPM_RDY ; Store Program Memory Ready Handler When the BOOTRST Fuse is programmed and the Boot section size set to 4Kbytes, the most typical and general program setup for the Reset and Interrupt Vector Addresses is: Address Labels Code Comments .org 0x0002 0x0002 jmp BPINT ; Battery Protection Interrupt Handler 0x0004 jmp EXT_INT0 ; External Interrupt Request 0 Handler 0x001C jmp TIM1_COMPB ; Timer1 Compare B Handler 0x001E jmp TIM1_OVF ; Timer1 Overflow Handler 0X0020 jmp TIM0_IC ; Timer0 Input Capture Handler 0x0022 jmp TIM0_COMPA ; Timer0 CompareA Handler 0x0024 jmp TIM0_COMPB ; Timer0 CompareB Handler 0x0026 jmp TIM0_OVF ; Timer0 Overflow Handler 0x0028 jmp TWI_BUS_CD ; Two-wire Bus Connect/Disconnect Handler 0x002A jmp TWI ; Two-wire Serial Interface Handler 0x002C jmp SPI, STC ; SPI, Serial Transfer Complete 0x002E jmp VADC ; Voltage ADC Conversion Complete Handler 0x0030 jmp CCADC_CONV ; CC-ADC Instantaneous Current Conversion Complete Handler 0x0032 jmp CCADC_REC_CUR ; CC-ADC Regular Current Handler 0x0034 jmp CCADC_ACC ; CC-ADC Accumulate Current Conversion Complete Handler 0x0036 jmp EE_RDY ; EEPROM Ready Handler 0x0038 jmp SPM ; Store Program Memory Ready Handler ; 0x003A RESET: ldi r16, high(RAMEND) ; Main program start 0x003B out SPH,r16 ; Set Stack Pointer to top of RAM 0x003C ldi r16, low(RAMEND) 0x003D out SPL,r16 0x003E sei ; Enable interrupts 0x003F xxx 0x0040 ... ... ... ; 55 8042E–AVR–09/2013 ATmega16HVB/32HVB ... ... ... ; 0x002C jmp SPM_RDY ; Store Program Memory Ready Handler ; .org 0x4C00 0x4C00 RESET: ldi r16,high(RAMEND); Main program start 0x4C01 out SPH,r16 ; Set Stack Pointer to top of RAM 0x4C02 ldi r16,low(RAMEND) 0x4C03 out SPL,r16 0x4C04 sei ; Enable interrupts 0x4C05 xxx When the BOOTRST Fuse is programmed, the Boot section size set to 4Kbytes and the IVSEL bit in the MCUCR Register is set before any interrupts are enabled, the most typical and general program setup for the Reset and Interrupt Vector Addresses is: Address Labels Code Comments ; .org 0x4C00 0x4C00 jmp RESET ; Reset handler 0x4C02 jmp BPINT ; Battery Protection Interrupt Handler 0x4C04 jmp EXT_INT0 ; External Interrupt Request 0 Handler ... ... ... ; 0x4C2C jmp SPM_RDY ; Store Program Memory Ready Handler ; 0x4C2E RESET: ldi r16,high(RAMEND); Main program start 0x4C2F out SPH,r16 ; Set Stack Pointer to top of RAM 0x4C30 ldi r16,low(RAMEND) 0x4C31 out SPL,r16 0x4C32 sei ; Enable interrupts 0x4C33 xxx 56 8042E–AVR–09/2013 ATmega16HVB/32HVB 12.3 Moving interrupts between application and boot space The General Interrupt Control Register controls the placement of the Interrupt Vector table. 12.4 Register description 12.4.1 MCUCR – MCU Control Register • Bit 1 – IVSEL: Interrupt Vector Select When the IVSEL bit is cleared (zero), the Interrupt Vectors are placed at the start of the Flash memory. When this bit is set (one), the Interrupt Vectors are moved to the beginning of the Boot Loader section of the Flash. The actual address of the start of the Boot Flash Section is determined by the BOOTSZ Fuses. Refer to the section ”Boot loader support – Read-while-write selfprogramming” on page 188 for details. To avoid unintentional changes of Interrupt Vector tables, a special write procedure must be followed to change the IVSEL bit: a. Write the Interrupt Vector Change Enable (IVCE) bit to one. b. Within four cycles, write the desired value to IVSEL while writing a zero to IVCE. Interrupts will automatically be disabled while this sequence is executed. Interrupts are disabled in the cycle IVCE is set, and they remain disabled until after the instruction following the write to IVSEL. If IVSEL is not written, interrupts remain disabled for four cycles. The I-bit in the Status Register is unaffected by the automatic disabling. Note: If Interrupt Vectors are placed in the Boot Loader section and Boot Lock bit BLB02 is programmed, interrupts are disabled while executing from the Application section. If Interrupt Vectors are placed in the Application section and Boot Lock bit BLB12 is programed, interrupts are disAssembly code example Move_interrupts: ; Enable change of Interrupt Vectors ldi r16, (1< CSn2:0 > 1). The number of system clock cycles from when the timer is enabled to the first count occurs can be from 1 to N+1 system clock cycles, where N equals the prescaler divisor (8, 64, 256, or 1024). It is possible to use the prescaler reset for synchronizing the Timer/Counter to program execution. However, care must be taken if the other Timer/Counter that shares the same prescaler also uses prescaling. A prescaler reset will affect the prescaler period for all Timer/Counters it is connected to. Figure 16-1. Prescaler for timer/counter. PSRSYNC Clear clkTn Tn clkI/O Synchronization CSn0 CSn1 CSn2 n 80 8042E–AVR–09/2013 ATmega16HVB/32HVB 16.2 External clock source An external clock source applied to the Tn pin can be used as Timer/Counter clock (clkTn). The Tn pin is sampled once every system clock cycle by the pin synchronization logic. The synchronized (sampled) signal is then passed through the edge detector. Figure 16-2 shows a functional equivalent block diagram of the Tn synchronization and edge detector logic. The registers are clocked at the positive edge of the internal system clock (clkI/O). The latch is transparent in the high period of the internal system clock. The edge detector generates one clkTn pulse for each positive (CSn2:0 = 7) or negative (CSn2:0 = 6) edge it detects. See Table 16-1 on page 81 for details. Figure 16-2. Tn pin sampling. The synchronization and edge detector logic introduces a delay of 2.5 to 3.5 system clock cycles from an edge has been applied to the Tn pin to the counter is updated. Enabling and disabling of the clock input must be done when Tn has been stable for at least one system clock cycle, otherwise it is a risk that a false Timer/Counter clock pulse is generated. Each half period of the external clock applied must be longer than one system clock cycle to ensure correct sampling. The external clock must be guaranteed to have less than half the system clock frequency (fExtClk < fclk_I/O/2) given a 50/50% duty cycle. Since the edge detector uses sampling, the maximum frequency of an external clock it can detect is half the sampling frequency (Nyquist sampling theorem). However, due to variation of the system clock frequency and duty cycle caused by Oscillator source (crystal, resonator, and capacitors) tolerances, it is recommended that maximum frequency of an external clock source is less than fclk_I/O/2.5. An external clock source can not be prescaled. Note: The synchronization logic on the input pins (Tn) is shown in Figure 16-2. Tn_sync (To Clock Select Logic) Synchronization Edge Detector D Q D Q LE Tn D Q clkI/O 81 8042E–AVR–09/2013 ATmega16HVB/32HVB 16.3 Register description 16.3.1 TCCRnB – Timer/Counter n Control Register B • Bits 2, 1, 0 – CSn2, CSn1, CSn0: Clock Select0, Bit 2, 1, and 0 The Clock Select n bits 2, 1, and 0 define the prescaling source of Timer n. If external pin modes are used for the Timer/Counter n, transitions on the Tn pin will clock the counter even if the pin is configured as an output. This feature allows software control of the counting. 16.3.2 General Timer/Counter Control Register – GTCCR • Bit 7 – TSM: Timer/Counter Synchronization Mode Writing the TSM bit to one activates the Timer/Counter Synchronization mode. In this mode, the value that is written to the PSRSYNC bit is kept, hence keeping the corresponding prescaler reset signals asserted. This ensures that the corresponding Timer/Counters are halted and can be configured to the same value without the risk of one of them advancing during configuration. When the TSM bit is written to zero the PSRSYNC bit is cleared by hardware, and the Timer/Counters start counting simultaneously. • Bit 0 – PSRSYNC: Prescaler Reset When this bit is one, Timer/Counter1 and Timer/Counter0 prescaler will be Reset. This bit is normally cleared immediately by hardware, except if the TSM bit is set. Note that Timer/Counter1 and Timer/Counter0 share the same prescaler and a reset of this prescaler will affect both timers. Bit 7 6 5 4 3 2 1 0 (0x80)(0x81) – – – – – CSn2 CSn1 CSn0 TCCRnB Read/Write R R R R R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Table 16-1. Clock Select Bit description. CSn2 CSn1 CSn0 Description 0 0 0 No clock source (Timer/Counter stopped) 0 0 1 clkI/O/(No prescaling) 0 1 0 clkI/O/8 (From prescaler) 0 1 1 clkI/O/64 (From prescaler) 1 0 0 clkI/O/256 (From prescaler) 1 0 1 clkI/O/1024 (From prescaler) 1 1 0 External clock source on Tn pin. Clock on falling edge 1 1 1 External clock source on Tn pin. Clock on rising edge Bit 7 6 5 4 3 2 1 0 0x23 (0x43) TSM – – – – – – PSRSYNC GTCCR Read/Write R/W R R R R R R R/W Initial Value 0 0 0 0 0 0 0 0 82 8042E–AVR–09/2013 ATmega16HVB/32HVB 17. Timer/Counter (T/C0,T/C1) 17.1 Features • Clear timer on compare match (auto reload) • Input capture unit • Four independent interrupt sources (TOVn, OCFnA, OCFnB, ICFn) • 8-bit mode with two independent output compare units • 16-bit mode with one independent output compare unit 17.2 Overview Timer/Counter n is a general purpose 8-bit/16-bit Timer/Counter module, with two/one Output Compare units and Input Capture feature. The Atmel ATmega16HVB/32HVB has two Timer/Counters, Timer/Counter0 and Timer/Counter1. The functionality for both Timer/Counters is described below. Timer/Counter0 and Timer/Counter1 have different Timer/Counter registers, as shown in ”Register summary” on page 255. The Timer/Counter general operation is described in 8-bit/16-bit mode. A simplified block diagram of the 8-bit/16-bit Timer/Counter is shown in Figure 17-1. CPU accessible I/O Registers, including I/O bits and I/O pins, are shown in bold. The device-specific I/O Register and bit locations are listed in the ”Register description” on page 94. Figure 17-1. 8-bit/16-bit timer/counter block diagram. 17.2.1 Registers The Timer/Counter Low Byte Register (TCNTnL) and Output Compare Registers (OCRnA and OCRnB) are 8-bit registers. Interrupt request (abbreviated to Int.Req. in Figure 17-1) signals are all visible in the Timer Interrupt Flag Register (TIFR). All interrupts are individually masked with the Timer Interrupt Mask Register (TIMSK). TIFR and TIMSK are not shown in the figure. In 16-bit mode the Timer/Counter consists one more 8-bit register, the Timer/Counter High Byte Register (TCNTnH). Furthermore, there is only one Output Compare Unit in 16-bit mode as the two Output Compare Registers, OCRnA and OCRnB, are combined to one 16-bit Output ComClock Select Timer/Counter DATA BUS OCRnB = TCNTnL Noise Canceler ICPn0 = Edge Detector Control Logic TOP Count Clear TOVn (Int. Req.) OCnA (Int. Req.) OCnB (Int. Req.) ICFn (Int. Req.) TCCRnA TCCRnB Tn Edge Detector ( From Prescaler ) clkTn = OCRnA TCNTnH Fixed TOP value ICPn1 83 8042E–AVR–09/2013 ATmega16HVB/32HVB pare Register. OCRnA contains the low byte of the word and OCRnB contains the higher byte of the word. When accessing 16-bit registers, special procedures described in section ”Accessing registers in 16-bit mode” on page 90 must be followed. The Timer/Counter can be clocked internally, via the prescaler, or by an external clock source on the Tn pin. The Clock Select logic block controls which clock source and edge the Timer/Counter uses to increment its value. The Timer/Counter is inactive when no clock source is selected. The output from the Clock Select logic is referred to as the timer clock (clkTn). 17.2.2 Definitions Many register and bit references in this section are written in general form. A lower case “n” replaces the module number, for example Timer/Counter number. A lower case “x” replaces the unit, for example OCRnx and ICPnx describes OCRnA/B and ICP1/0x . However, when using the register or bit defines in a program, the precise form must be used, that is, TCNT0L for accessing Timer/Counter0 counter value and so on. The definitions in Table 17-1 are also used extensively throughout the document. 17.3 Timer/Counter clock sources The Timer/Counter can be clocked internally, via the prescaler, or by an external clock source. The Clock Select logic is controlled by the Clock Select (CSn2:0) bits located in the Timer/Counter Control Register n B (TCCRnB), and controls which clock source and edge the Timer/Counter uses to increment its value. The Timer/Counter is inactive when no clock source is selected. The output from the Clock Select logic is referred to as the timer clock (clkTn). For details on clock sources and prescaler, see ”Timer/Counter0 and Timer/Counter1 prescalers” on page 79. 17.4 Counter unit The main part of the 8-bit Timer/Counter is the counter unit. Figure 17-2 shows a block diagram of the counter and its surroundings. Figure 17-2. Counter unit block diagram. Table 17-1. Definitions. BOTTOM The counter reaches the BOTTOM when it becomes 0 MAX The counter reaches its MAXimum when it becomes 0xFF (decimal 255) in 8-bit mode or 0xFFFF (decimal 65535) in 16-bit mode TOP The counter reaches the TOP when it becomes equal to the highest value in the count sequence. The TOP value can be assigned to be the fixed value 0xFF/0xFFFF (MAX) or the value stored in the OCRnA Register DATA BUS TCNTn Control Logic count TOVn (Int.Req.) Clock Select top Tn Edge Detector ( From Prescaler ) clkTn 84 8042E–AVR–09/2013 ATmega16HVB/32HVB Signal description (internal signals): count Increment or decrement TCNTn by one clkTn Timer/Counter clock, referred to as clkTn in the following top Signalize that TCNTn has reached maximum value The counter is incremented at each timer clock (clkTn) until it passes its TOP value and then restarts from BOTTOM. The counting sequence is determined by the setting of the WGMn0 bits located in the Timer/Counter Control Register (TCCRnA). For more details about counting sequences, see ”Timer/counter timing diagrams” on page 89. clkTn can be generated from an external or internal clock source, selected by the Clock Select bits (CSn2:0). When no clock source is selected (CSn2:0 = 0) the timer is stopped. However, the TCNTn value can be accessed by the CPU, regardless of whether clkTn is present or not. A CPU write overrides (has priority over) all counter clear or count operations. The Timer/Counter Overflow Flag (TOVn) is set when the counter reaches the maximum value and it can be used for generating a CPU interrupt. 17.5 Modes of operation The mode of operation is defined by the Timer/Counter Width (TCWn), Input Capture Enable (ICENn) and the Waveform Generation Mode (WGMn0) bits in ”TCCRnA – Timer/Counter n Control Register A” on page 94. Table 17-2 shows the different Modes of Operation. 17.5.1 Normal 8-bit mode In the normal mode, the counter (TCNTnL) is incrementing until it overruns when it passes its maximum 8-bit value (MAX = 0xFF) and then restarts from the bottom (0x00), see Table 17-2 for bit settings. The Overflow Flag (TOVn) will be set in the same timer clock cycle as the TCNTnL becomes zero. The TOVn Flag in this case behaves like a ninth bit, except that it is only set, not cleared. However, combined with the timer overflow interrupt that automatically clears the TOVn Flag, the timer resolution can be increased by software. There are no special cases to consider in the Normal 8-bit mode, a new counter value can be written anytime. The Output Compare Unit can be used to generate interrupts at some given time. 17.5.2 Clear timer on Compare Match (CTC) 8-bit mode In Clear Timer on Compare or CTC mode, the OCRnA Register is used to manipulate the counter resolution, see Table 17-2 for bit settings. In CTC mode the counter is cleared to zero when Table 17-2. Modes of operation. Mode ICENn TCWn WGMn0 Timer/counter mode of operation TOP Update of OCRx at TOV flag set on 0 0 0 0 Normal 8-bit Mode 0xFF Immediate MAX (0xFF) 1 0 0 1 8-bit CTC OCRnA Immediate MAX (0xFF) 2 0 1 0 16-bit Mode 0xFFFF Immediate MAX (0xFFFF) 3 0 1 1 16-bit CTC OCRnB, OCRnA Immediate MAX (0xFFFF) 410 0 8-bit Input Capture mode 0xFF – MAX (0xFF) 511 0 16-bit Input Capture mode 0xFFFF – MAX (0xFFFF) 85 8042E–AVR–09/2013 ATmega16HVB/32HVB the counter value (TCNTn) matches the OCRnA. The OCRnA defines the top value for the counter, hence also its resolution. This mode allows greater control of the Compare Match output frequency. It also simplifies the operation of counting external events. The timing diagram for the CTC mode is shown in Figure 17-3. The counter value (TCNTn) increases until a Compare Match occurs between TCNTn and OCRnA, and then counter (TCNTn) is cleared. Figure 17-3. CTC Mode, timing diagram. An interrupt can be generated each time the counter value reaches the TOP value by using the OCFnA Flag. If the interrupt is enabled, the interrupt handler routine can be used for updating the TOP value. However, changing TOP to a value close to BOTTOM when the counter is running with none or a low prescaler value must be done with care since the CTC mode does not have the double buffering feature. If the new value written to OCRnA is lower than the current value of TCNTn, the counter will miss the Compare Match. The counter will then have to count to its maximum value (0xFF) and wrap around starting at 0x00 before the Compare Match can occur. As for the Normal mode of operation, the TOVn Flag is set in the same timer clock cycle that the counter counts from MAX to 0x00. 17.5.3 16-bit mode In 16-bit mode, the counter (TCNTnH/L) is a incrementing until it overruns when it passes its maximum 16-bit value (MAX = 0xFFFF) and then restarts from the bottom (0x0000), see Table 17-2 on page 84 for bit settings. The Overflow Flag (TOVn) will be set in the same timer clock cycle as the TCNTnH/L becomes zero. The TOVn Flag in this case behaves like a 17th bit, except that it is only set, not cleared. However, combined with the timer overflow interrupt that automatically clears the TOVn Flag, the timer resolution can be increased by software. There are no special cases to consider in the Normal mode, a new counter value can be written anytime. The Output Compare Unit can be used to generate interrupts at some given time. 17.5.4 Clear timer on Compare Match (CTC) 16-bit mode In Clear Timer on Compare 16-bit mode, OCRAnA/B Registers are used to manipulate the counter resolution, see Table 17-2 on page 84 for bit settings. In CTC mode the counter is cleared to zero when the counter value (TCNTn) matches OCRnA/B, where OCRnB represents the eight most significant bits and OCRnA represents the eight least significant bits. OCRnA/B defines the top value of the counter, hence also its resolution. This mode allows greater control of the Compare Match output frequency. It also simplifies the operation of counting external events. An interrupt can be generated each time the counter reaches the TOP value by using the OCFnA flag. If the interrupt is enabled, the interrupt handler routine can be used for updating the TOP value. However, changing the TOP to a value close the BOTTOM when the counter is running with none or a low prescaler value must be done with care since the CTC mode does not have the double buffering feature. If the new value written to OCRnA/B is lower than the current TCNTn OCnx Interrupt Flag Set Period 1 2 3 4 86 8042E–AVR–09/2013 ATmega16HVB/32HVB value of TCNTn, the counter will miss the Compare Match. The counter will then have to count to its maximum value (0xFFFF) and wrap around starting at 0x0000 before Compare Match can occur. As for the 16-bit Mode, the TOVn Flag is set in the same timer clock cycle that the counter counts from MAX to 0x0000. 17.5.5 8-bit Input capture mode The Timer/Counter can be used in a 8-bit Input Capture mode, see Table 17-2 on page 84 for bit settings. For full description, see “Input capture unit” . 17.5.6 16-bit input capture mode The Timer/Counter can also be used in a 16-bit Input Capture mode, see Table 17-2 on page 84 for bit settings. For full description, see “Input capture unit” . 17.6 Input capture unit The Timer/Counter incorporates an Input Capture unit that can capture external events and give them a time-stamp indicating time of occurrence. The external signal indicates an event, or multiple events. For Timer/Counter0, the events can be applied via the PB0 pin (ICP00), or alternatively via the osi_posedge pin on the Oscillator Sampling Interface (ICP01). For Timer/Counter1, the events can be applied by the Battery Protection Interrupt (ICP10) or alternatively by the Voltage Regulator Interrupt (ICP11). The time-stamps can then be used to calculate frequency, duty-cycle, and other features of the signal applied. Alternatively the timestamps can be used for creating a log of the events. The Input Capture unit is illustrated by the block diagram shown in Figure 17-4. The elements of the block diagram that are not directly a part of the Input Capture unit are gray shaded. Figure 17-4. Input Capture Unit block diagram. The Output Compare Register OCRnA is a dual-purpose register that is also used as an 8-bit Input Capture Register ICRn. In 16-bit Input Capture mode the Output Compare Register OCRnB serves as the high byte of the Input Capture Register ICRn. In 8-bit Input Capture mode the Output Compare Register OCRnB is free to be used as a normal Output Compare Register, but in 16-bit Input Capture mode the Output Compare Unit cannot be used as there are no free Output Compare Register(s). Even though the Input Capture register is called ICRn in this secICFn (Int.Req.) WRITE ICRn (16-bit Register) OCRnB (8-bit) Noise Canceler ICPn0 Edge Detector TEMP (8-bit) DATA BUS (8-bit) OCRnA (8-bit) TCNTn (16-bit Counter) TCNTnH (8-bit) TCNTnL (8-bit) ICNCn ICESn ICPn1 ICSn 87 8042E–AVR–09/2013 ATmega16HVB/32HVB tion, it is referring to the Output Compare Register(s). For more information on how to access the 16-bit registers refer to ”Accessing registers in 16-bit mode” on page 90. When a change of the logic level (an event) occurs on the Input Capture pin (ICPx), and this change confirms to the setting of the edge detector, a capture will be triggered. When a capture is triggered, the value of the counter (TCNTn) is written to the Input Capture Register (ICRn). The Input Capture Flag (ICFn) is set at the same system clock as the TCNTn value is copied into Input Capture Register. If enabled (TICIEn=1), the Input Capture Flag generates an Input Capture interrupt. The ICFn flag is automatically cleared when the interrupt is executed. Alternatively the ICFn flag can be cleared by software by writing a logical one to its I/O bit location. 17.6.1 Input Capture trigger source The default trigger source for the Input Capture unit is the I/O port PB0 in Timer/Counter0 and the Battery Protection Interrupt in Timer/Counter1. Alternatively can the osi_posedge pin on the Oscillator Sampling Interface in Timer/Counter0 and Voltage Regulator Interrupt in Timer/Counter1 be used as trigger sources. The osi_posedge pin in Timer/Counter0 Control Register A (TCCR0A) and the Voltage Regulator Interrupt bit in the Timer/Counter1 Control Register A (TCCR1A) is selected as trigger sources by setting the Input Capture Select (ICS0/1) bit. Be aware that changing trigger source can trigger a capture. The Input Capture Flag must therefore be cleared after the change. Both Input Capture inputs are sampled using the same technique. The edge detector is also identical. However, when the noise canceler is enabled, additional logic is inserted before the edge detector, which increases the delay by four system clock cycles. An Input Capture on Timer/Counter0 can also be triggered by software by controlling the port of the PB0 pin. 17.6.2 Noise canceler The noise canceler improves noise immunity by using a simple digital filtering scheme. The noise canceler input is monitored over four samples, and all four must be equal for changing the output that in turn is used by the edge detector. The noise canceler is enabled by setting the Input Capture Noise Canceler (ICNCn) bit in Timer/Counter Control Register n B (TCCRnB). When enabled the noise canceler introduces additional four system clock cycles of delay from a change applied to the input, to the update of the ICRn Register. The noise canceler uses the system clock and is therefore not affected by the prescaler. 17.6.3 Using the Input Capture unit The main challenge when using the Input Capture unit is to assign enough processor capacity for handling the incoming events. The time between two events is critical. If the processor has not read the captured value in the ICRn Register before the next event occurs, the ICRn will be overwritten with a new value. In this case the result of the capture will be incorrect. When using the Input Capture interrupt, the ICRn Register should be read as early in the interrupt handler routine as possible. The maximum interrupt response time is dependent on the maximum number of clock cycles it takes to handle any of the other interrupt requests. Measurement of an external signal duty cycle requires that the trigger edge is changed after each capture. Changing the edge sensing must be done as early as possible after the ICRn Register has been read. After a change of the edge, the Input Capture Flag (ICFn) must be cleared by software (writing a logical one to the I/O bit location). For measuring frequency only, the trigger edge change is not required. 88 8042E–AVR–09/2013 ATmega16HVB/32HVB Note: 1. See ”OSI – Oscillator sampling interface” on page 29 for details. 2. The noise canceler cannot be used with this source. Note: 1. The noise canceller will filter out the input capture and it is therefore not recommended to use noise canceler with these sources. 17.7 Output compare unit The comparator continuously compares the Timer/Counter (TCNTn) with the Output Compare Registers (OCRnA and OCRnB), and whenever the Timer/Counter equals to the Output Compare Registers, the comparator signals a match. A match will set the Output Compare Flag at the next timer clock cycle. In 8-bit mode the match can set either the Output Compare Flag OCFnA or OCFnB, but in 16-bit mode the match can set only the Output Compare Flag OCFnA as there is only one Output Compare Unit. If the corresponding interrupt is enabled, the Output Compare Flag generates an Output Compare interrupt. The Output Compare Flag is automatically cleared when the interrupt is executed. Alternatively, the flag can be cleared by software by writing a logical one to its I/O bit location. Figure 17-5 shows a block diagram of the Output Compare unit. Figure 17-5. Output Compare Unit, block diagram. 17.7.1 Compare Match Blocking by TCNT0 write All CPU write operations to the TCNTnH/L Register will block any Compare Match that occur in the next timer clock cycle, even when the timer is stopped. This feature allows OCRnA/B to be initialized to the same value as TCNTn without triggering an interrupt when the Timer/Counter clock is enabled. Table 17-3. Timer/Counter0 Input Capture Source (ICS). ICS0 Source 0 ICP00: Port PB0 1 ICP01: osi_posedge pin from OSI module (1)(2) Table 17-4. Timer/Counter1 Input Capture Source (ICS). ICS1 Source 0 ICP10: Battery Protection Interrupt (1) 1 ICP11: Voltage Regulator Interrupt (1) OCFnx (Int.Req.) = (8/16-bit Comparator ) OCRnx DATA BUS TCNTn 89 8042E–AVR–09/2013 ATmega16HVB/32HVB 17.7.2 Using the Output Compare Unit Since writing TCNTnH/L will block all Compare Matches for one timer clock cycle, there are risks involved when changing TCNTnH/L when using the Output Compare Unit, independently of whether the Timer/Counter is running or not. If the value written to TCNTnH/L equals the OCRnA/B value, the Compare Match will be missed. 17.8 Timer/counter timing diagrams The Timer/Counter is a synchronous design and the timer clock (clkTn) is therefore shown as a clock enable signal in the following figures. The figures include information on when Interrupt Flags are set. Figure 17-6 contains timing data for basic Timer/Counter operation. The figure shows the count sequence close to the MAX value. Figure 17-6. Timer/counter timing diagram, no prescaling. Figure 17-7 shows the same timing data, but with the prescaler enabled. Figure 17-7. Timer/counter timing diagram, with prescaler (fclk_I/O/8). Figure 17-8 shows the setting of OCFnA and OCFnB in Normal mode. Figure 17-8. Timer/counter timing diagram, setting of OCFnx, with prescaler (fclk_I/O/8). clkTn (clkI/O/1) TOVn clkI/O TCNTn MAX - 1 MAX BOTTOM BOTTOM + 1 TOVn TCNTn MAX - 1 MAX BOTTOM BOTTOM + 1 clkI/O clkTn (clkI/O/8) OCFnx OCRnx TCNTn OCRnx Value OCRnx - 1 OCRnx OCRnx + 1 OCRnx + 2 clkI/O clkTn (clkI/O/8) 90 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 17-9 shows the setting of OCFnA and the clearing of TCNTn in CTC mode. Figure 17-9. Timer/counter timing diagram, CTC mode, with prescaler (fclk_I/O/8). 17.9 Accessing registers in 16-bit mode In 16-bit mode (the TCWn bit is set to one) the TCNTnH/L and OCRnA/B or TCNTnL/H and OCRnB/A are 16-bit registers that can be accessed by the AVR CPU via the 8-bit data bus. The 16-bit register must be byte accessed using two read or write operations. The 16-bit Timer/Counter has a single 8-bit register for temporary storing of the high byte of the 16-bit access. The same temporary register is shared between all 16-bit registers. Accessing the low byte triggers the 16-bit read or write operation. When the low byte of a 16-bit register is written by the CPU, the high byte stored in the temporary register, and the low byte written are both copied into the 16-bit register in the same clock cycle. When the low byte of a 16-bit register is read by the CPU, the high byte of the 16-bit register is copied into the temporary register in the same clock cycle as the low byte is read. There is one exception in the temporary register usage. In the Output Compare mode the 16-bit Output Compare Register OCRnA/B is read without the temporary register, because the Output Compare Register contains a fixed value that is only changed by CPU access. However, in 16- bit Input Capture mode the ICRn register formed by the OCRnA and OCRnB registers must be accessed with the temporary register. To do a 16-bit write, the high byte must be written before the low byte. For a 16-bit read, the low byte must be read before the high byte. OCFnx OCRnx TCNTn (CTC) TOP TOP - 1 TOP BOTTOM BOTTOM + 1 clkPCK clkTn (clkPCK /8) 91 8042E–AVR–09/2013 ATmega16HVB/32HVB The following code examples show how to access the 16-bit timer registers assuming that no interrupts updates the temporary register. The same principle can be used directly for accessing the OCRnA/B registers. Note: 1. See ”About code examples” on page 8. The assembly code example returns the TCNTnH/L value in the r17:r16 register pair. It is important to notice that accessing 16-bit registers are atomic operations. If an interrupt occurs between the two instructions accessing the 16-bit register, and the interrupt code updates the temporary register by accessing the same or any other of the 16-bit timer registers, then the result of the access outside the interrupt will be corrupted. Therefore, when both the main code and the interrupt code update the temporary register, the main code must disable the interrupts during the 16-bit access. Assembly code example ... ; Set TCNTn to 0x01FF ldi r17,0x01 ldi r16,0xFF out TCNTnH,r17 out TCNTnL,r16 ; Read TCNTn into r17:r16 in r16,TCNTnL in r17,TCNTnH ... C code example unsigned int i; ... /* Set TCNTn to 0x01FF */ TCNTn = 0x1FF; /* Read TCNTn into i */ i = TCNTn; ... 92 8042E–AVR–09/2013 ATmega16HVB/32HVB The following code examples show how to do an atomic read of the TCNTn register contents. Reading any of the OCRn register can be done by using the same principle. Note: 1. See ”About code examples” on page 8. The assembly code example returns the TCNTnH/L value in the r17:r16 register pair. Assembly code example TIMn_ReadTCNTn: ; Save global interrupt flag in r18,SREG ; Disable interrupts cli ; Read TCNTn into r17:r16 in r16,TCNTnL in r17,TCNTnH ; Restore global interrupt flag out SREG,r18 ret C code example unsigned int TIMn_ReadTCNTn( void ) { unsigned char sreg; unsigned int i; /* Save global interrupt flag */ sreg = SREG; /* Disable interrupts */ _CLI(); /* Read TCNTn into i */ i = TCNTn; /* Restore global interrupt flag */ SREG = sreg; return i; } 93 8042E–AVR–09/2013 ATmega16HVB/32HVB The following code examples show how to do an atomic write of the TCNTnH/L register contents. Writing any of the OCRnA/B registers can be done by using the same principle. Note: 1. See ”About code examples” on page 8. The assembly code example requires that the r17:r16 register pair contains the value to be written to TCNTnH/L. 17.9.1 Reusing the temporary high byte register If writing to more than one 16-bit register where the high byte is the same for all registers written, then the high byte only needs to be written once. However, note that the same rule of atomic operation described previously also applies in this case. Assembly code example TIMn_WriteTCNTn: ; Save global interrupt flag in r18,SREG ; Disable interrupts cli ; Set TCNTn to r17:r16 out TCNTnH,r17 out TCNTnL,r16 ; Restore global interrupt flag out SREG,r18 ret C code example void TIMn_WriteTCNTn( unsigned int i ) { unsigned char sreg; unsigned int i; /* Save global interrupt flag */ sreg = SREG; /* Disable interrupts */ _CLI(); /* Set TCNTn to i */ TCNTn = i; /* Restore global interrupt flag */ SREG = sreg; } 94 8042E–AVR–09/2013 ATmega16HVB/32HVB 17.10 Register description 17.10.1 TCCRnA – Timer/Counter n Control Register A • Bit 7 – TCWn: Timer/Counter Width When this bit is written to one 16-bit mode is selected. Timer/Counter n width is set to 16-bits and the Output Compare Registers OCRnA and OCRnB are combined to form one 16-bit Output Compare Register. Because the 16-bit registers TCNTnH/L and OCRnB/A are accessed by the AVR CPU via the 8-bit data bus, special procedures must be followed. These procedures are described in section ”Accessing registers in 16-bit mode” on page 90. • Bit 6 – ICENn: Input Capture Mode Enable The Input Capture Mode is enabled when this bit is written to one. • Bit 5 – ICNCn: Input Capture Noise Canceler Setting this bit activates the Input Capture Noise Canceler. When the noise canceler is activated, the input from the Input Capture Source is filtered. The filter function requires four successive equal valued samples of the Input Capture Source for changing its output. The Input Capture is therefore delayed by four System Clock cycles when the noise canceler is enabled. • Bit 4 – ICESn: Input Capture Edge Select This bit selects which edge on the Input Capture Source that is used to trigger a capture event. When the ICESn bit is written to zero, a falling (negative) edge is used as trigger, and when the ICESn bit is written to one, a rising (positive) edge will trigger the capture. When a capture is triggered according to the ICESn setting, the counter value is copied into the Input Capture Register. The event will also set the Input Capture Flag (ICFn), and this can be used to cause an Input Capture Interrupt, if this interrupt is enabled. • Bit 3 – ICSn: Input Capture Select When written logic one, this bit enables the input capture function in Timer/Counter n to be triggered by the alternative Input Capture Source. To make the comparator trigger the Timer/Counter n Input Capture interrupt, the TICIEn bit in the Timer Interrupt Mask Register (TIMSK) must be set. See Table 17-3 on page 88 and Table 17-4 on page 88. • Bits 2:1 – Reserved These bits are reserved in the Atmel ATmega16HVB/32HVB and will always read as zero. • Bit 0 – WGMn0: Waveform Generation Mode This bit controls the counting sequence of the counter, the source for maximum (TOP) counter value, see Figure 17-6 on page 89. Modes of operation supported by the Timer/Counter unit are: Normal mode (counter) and Clear Timer on Compare Match (CTC) mode (see ”Timer/counter timing diagrams” on page 89). Bit 7 6 5 4 3 2 1 0 0x24 (0x44) TCWn ICENn ICNCn ICESn ICSn – – WGMn0 TCCRnA Read/Write R/W R/W R/W R/W R/W R R R/W Initial Value 0 0 0 0 0 0 0 0 95 8042E–AVR–09/2013 ATmega16HVB/32HVB 17.10.2 TCNTnL – Timer/Counter n Register Low Byte The Timer/Counter Register TCNTnL gives direct access, both for read and write operations, to the Timer/Counter unit 8-bit counter. Writing to the TCNTnL Register blocks (disables) the Compare Match on the following timer clock. Modifying the counter (TCNTnL) while the counter is running, introduces a risk of missing a Compare Match between TCNTnL and the OCRnx Registers. In 16-bit mode the TCNTnL register contains the lower part of the 16-bit Timer/Counter n Register. 17.10.3 TCNTnH – Timer/Counter n Register High Byte When 16-bit mode is selected (the TCWn bit is set to one) the Timer/Counter Register TCNTnH combined to the Timer/Counter Register TCNTnL gives direct access, both for read and write operations, to the Timer/Counter unit 16-bit counter. To ensure that both the high and low bytes are read and written simultaneously when the CPU accesses these registers, the access is performed using an 8-bit temporary high byte register (TEMP). This temporary register is shared by all the other 16-bit registers. See ”Accessing registers in 16-bit mode” on page 90. 17.10.4 OCRnA – Timer/Counter n Output Compare Register A The Output Compare Register A contains an 8-bit value that is continuously compared with the counter value (TCNTnL). A match can be used to generate an Output Compare interrupt. In 16-bit mode the OCRnA register contains the low byte of the 16-bit Output Compare Register. To ensure that both the high and the low bytes are written simultaneously when the CPU writes to these registers, the access is performed using an 8-bit temporary high byte register (TEMP). This temporary register is shared by all the other 16-bit registers. See ”Accessing registers in 16- bit mode” on page 90. 17.10.5 OCRnB – Timer/Counter n Output Compare Register B The Output Compare Register B contains an 8-bit value that is continuously compared with the counter value (TCNTnL in 8-bit mode and TCNTnH in 16-bit mode). A match can be used to generate an Output Compare interrupt. Bit 7 6 5 4 3 2 1 0 0x26 (0x46) TCNTnL[7:0] TCNTnL Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 0x27 (0x47) TCNTnH[7:0] TCNTnH Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 0x28 (0x48) OCRnA[7:0] OCRnA Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 0x29 (0x49) OCRnB[7:0] OCRnB Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 96 8042E–AVR–09/2013 ATmega16HVB/32HVB In 16-bit mode the OCRnB register contains the high byte of the 16-bit Output Compare Register. To ensure that both the high and the low bytes are written simultaneously when the CPU writes to these registers, the access is performed using an 8-bit temporary high byte register (TEMP). This temporary register is shared by all the other 16-bit registers. See ”Accessing registers in 16-bit mode” on page 90. 17.10.6 TIMSKn – Timer/Counter n Interrupt Mask Register • Bit 3 – ICIEn: Timer/Counter n Input Capture Interrupt Enable When this bit is written to one, and the I-flag in the Status Register is set (interrupts globally enabled), the Timer/Counter n Input Capture interrupt is enabled. The corresponding Interrupt Vector (see ”Interrupts” on page 52) is executed when the ICFn flag, located in TIFRn, is set. • Bit 2 – OCIEnB: Timer/Counter n Output Compare Match B Interrupt Enable When the OCIEnB bit is written to one, and the I-bit in the Status Register is set, the Timer/Counter Compare Match B interrupt is enabled. The corresponding interrupt is executed if a Compare Match in Timer/Counter occurs, that is, when the OCFnB bit is set in the Timer/Counter Interrupt Flag Register – TIFRn. • Bit 1 – OCIEnA: Timer/Counter n Output Compare Match A Interrupt Enable When the OCIEnA bit is written to one, and the I-bit in the Status Register is set, the Timer/Counter n Compare Match A interrupt is enabled. The corresponding interrupt is executed if a Compare Match in Timer/Counter n occurs, that is, when the OCFnA bit is set in the Timer/Counter n Interrupt Flag Register – TIFRn. • Bit 0 – TOIEn: Timer/Counter n Overflow Interrupt Enable When the TOIEn bit is written to one, and the I-bit in the Status Register is set, the Timer/Counter n Overflow interrupt is enabled. The corresponding interrupt is executed if an overflow in Timer/Counter n occurs, that is, when the TOVn bit is set in the Timer/Counter n Interrupt Flag Register – TIFRn. 17.10.7 TIFRn – Timer/Counter n Interrupt Flag Register • Bits 3 – ICFn: Timer/Counter n Input Capture Flag This flag is set when a capture event occurs, according to the setting of ICENn, ICESn and ICSn bits in the TCCRnA Register. ICFn is automatically cleared when the Input Capture Interrupt Vector is executed. Alternatively, ICFn can be cleared by writing a logic one to its bit location. Bit 7 6 5 4 3 2 1 0 (0x6E)(0x6F) – – – – ICIEn OCIEnB OCIEnA TOIEn TIMSKn Read/Write R R R R R/W R/W R/W R Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 0x15 (0x35) – – – – ICFn OCFnB OCFnA TOVn TIFRn Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 97 8042E–AVR–09/2013 ATmega16HVB/32HVB • Bit 2 – OCFnB: Output Compare Flag n B The OCFnB bit is set when a Compare Match occurs between the Timer/Counter and the data in OCRnB – Output Compare Register n B. OCFnB is cleared by hardware when executing the corresponding interrupt handling vector. Alternatively, OCFnB is cleared by writing a logic one to the flag. When the I-bit in SREG, OCIEnB (Timer/Counter Compare B Match Interrupt Enable), and OCFnB are set, the Timer/Counter Compare Match Interrupt is executed. The OCFnB is not set in 16-bit Output Compare mode when the Output Compare Register OCRnB is used as the high byte of the 16-bit Output Compare Register or in 16-bit Input Capture mode when the Output Compare Register OCRnB is used as the high byte of the Input Capture Register. • Bit 1 – OCFnA: Output Compare Flag n A The OCFnA bit is set when a Compare Match occurs between the Timer/Counter n and the data in OCRnA – Output Compare Register n. OCFnA is cleared by hardware when executing the corresponding interrupt handling vector. Alternatively, OCFnA is cleared by writing a logic one to the flag. When the I-bit in SREG, OCIEnA (Timer/Counter n Compare Match Interrupt Enable), and OCFnA are set, the Timer/Counter n Compare Match Interrupt is executed. The OCFnA is also set in 16-bit mode when a Compare Match occurs between the Timer/Counter n and 16-bit data in OCRnB/A. The OCFnA is not set in Input Capture mode when the Output Compare Register OCRnA is used as an Input Capture Register. • Bit 0 – TOVn: Timer/Counter n Overflow Flag The bit TOVn is set when an overflow occurs in Timer/Counter n. TOVn is cleared by hardware when executing the corresponding interrupt handling vector. Alternatively, TOVn is cleared by writing a logic one to the flag. When the SREG I-bit, TOIEn (Timer/Counter n Overflow Interrupt Enable), and TOVn are set, the Timer/Counter n Overflow interrupt is executed. 98 8042E–AVR–09/2013 ATmega16HVB/32HVB 18. SPI – Serial Peripheral Interface 18.1 Features • Full-duplex, three-wire synchronous data transfer • Master or slave operation • LSB first or MSB first data transfer • Seven programmable bit rates • End of transmission interrupt flag • Write collision protection flag • Wake-up from idle mode • Double speed (CK/2) master SPI mode 18.2 Overview The Serial Peripheral Interface (SPI) allows high-speed synchronous data transfer between the Atmel ATmega16HVB/32HVB and peripheral devices or between several AVR devices. When the SPI is not used, power consumption can be minimized by writing the PRSPI bit in PRR0 to one. See ”PRR0 – Power Reduction Register 0” on page 40 for details on how to use the PRSPI bit. Figure 18-1. SPI block diagram (1). Note: 1. Refer to ”Alternate port functions” on page 72 for SPI pin placement. SPI2X SPI2X DIVIDER /2/4/8/16/32/64/128 99 8042E–AVR–09/2013 ATmega16HVB/32HVB The interconnection between Master and Slave CPUs with SPI is shown in Figure 18-2. The system consists of two shift Registers, and a Master clock generator. The SPI Master initiates the communication cycle when pulling low the Slave Select SS pin of the desired Slave. Master and Slave prepare the data to be sent in their respective shift Registers, and the Master generates the required clock pulses on the SCK line to interchange data. Data is always shifted from Master to Slave on the Master Out – Slave In, MOSI, line, and from Slave to Master on the Master In – Slave Out, MISO, line. After each data packet, the Master will synchronize the Slave by pulling high the Slave Select, SS, line. When configured as a Master, the SPI interface has no automatic control of the SS line. This must be handled by user software before communication can start. When this is done, writing a byte to the SPI Data Register starts the SPI clock generator, and the hardware shifts the eight bits into the Slave. After shifting one byte, the SPI clock generator stops, setting the end of Transmission Flag (SPIF). If the SPI Interrupt Enable bit (SPIE) in the SPCR Register is set, an interrupt is requested. The Master may continue to shift the next byte by writing it into SPDR, or signal the end of packet by pulling high the Slave Select, SS line. The last incoming byte will be kept in the Buffer Register for later use. When configured as a Slave, the SPI interface will remain sleeping with MISO tri-stated as long as the SS pin is driven high. In this state, software may update the contents of the SPI Data Register, SPDR, but the data will not be shifted out by incoming clock pulses on the SCK pin until the SS pin is driven low. As one byte has been completely shifted, the end of Transmission Flag, SPIF is set. If the SPI Interrupt Enable bit, SPIE, in the SPCR Register is set, an interrupt is requested. The Slave may continue to place new data to be sent into SPDR before reading the incoming data. The last incoming byte will be kept in the Buffer Register for later use. Figure 18-2. SPI Master-slave interconnection. The system is single buffered in the transmit direction and double buffered in the receive direction. This means that bytes to be transmitted cannot be written to the SPI Data Register before the entire shift cycle is completed. When receiving data, however, a received character must be read from the SPI Data Register before the next character has been completely shifted in. Otherwise, the first byte is lost. In SPI Slave mode, the control logic will sample the incoming signal of the SCK pin. To ensure correct sampling of the clock signal, the frequency of the SPI clock should never exceed fosc/4. When the SPI is enabled, the data direction of the MOSI, MISO, SCK, and SS pins is overridden according to Table 18-1 on page 100. For more details on automatic port overrides, refer to ”Alternate port functions” on page 72. SHIFT ENABLE 100 8042E–AVR–09/2013 ATmega16HVB/32HVB Note: 1. See ”Alternate functions of Port B” on page 75 for a detailed description of how to define the direction of the user defined SPI pins. The following code examples show how to initialize the SPI as a Master and how to perform a simple transmission. DDR_SPI in the examples must be replaced by the actual Data Direction Register controlling the SPI pins. DD_MOSI, DD_MISO and DD_SCK must be replaced by the actual data direction bits for these pins, for example, if MOSI is placed on pin PB5, replace DD_MOSI with DDB5 and DDR_SPI with DDRB. Table 18-1. SPI pin overrides (1). Pin Direction, Master SPI Direction, Slave SPI MOSI User Defined Input MISO Input User Defined SCK User Defined Input SS User Defined Input 101 8042E–AVR–09/2013 ATmega16HVB/32HVB Note: 1. See ”About code examples” on page 8. Assembly code example (1) SPI_MasterInit: ; Set MOSI and SCK output, all others input ldi r17,(1< 2.2 CPU clock cycles for fck <12MHz, 3 CPU clock cycles for fck >=12MHz High: > 2.2 CPU clock cycles for fck <12MHz, 3 CPU clock cycles for fck >=12MHz 30.6.1 Serial programming algorithm When writing serial data to the Atmel ATmega16HVB/32HVB, data is clocked on the rising edge of SCK. When reading data from the ATmega16HVB/32HVB, data is clocked on the falling edge of SCK. See ”Serial programming characteristics” on page 234 for timing details. To program and verify the ATmega16HVB/32HVB in the Serial Programming mode, the following sequence is recommended (see four byte instruction formats in Table 30-12 on page 210): 1. Power-up sequence: Make sure the chip is started as explained in Section 11.2.1 ”Power-on reset and charger connect” on page 43 while RESET and SCK are set to “0”. In some systems, the programmer can not guarantee that SCK is held low during power-up. In this case, RESET must be given a positive pulse of at least two CPU clock cycles duration after SCK has been set to “0”. 2. Wait for at least 20ms and enable serial programming by sending the Programming Enable serial instruction to pin MOSI. Table 30-10. Pin mapping serial programming. Symbol Pins I/O Description SCK PB5 I Serial Clock MOSI PB6 I Serial Data in MISO PB7 O Serial Data out GND SCK MISO MOSI RESET +4.0V - 25.0V VFET GND SCK MISO MOSI RESET +4.0V - 25.0V VFET 209 8042E–AVR–09/2013 ATmega16HVB/32HVB 3. The serial programming instructions will not work if the communication is out of synchronization. When in sync. the second byte (0x53), will echo back when issuing the third byte of the Programming Enable instruction. Whether the echo is correct or not, all four bytes of the instruction must be transmitted. If the 0x53 did not echo back, give RESET a positive pulse and issue a new Programming Enable command. 4. The Flash is programmed one page at a time. The memory page is loaded one byte at a time by supplying the 5 LSB of the address and data together with the Load Program memory Page instruction. To ensure correct loading of the page, the data low byte must be loaded before data high byte is applied for a given address. The Program memory Page is stored by loading the Write Program memory Page instruction with the 7/8 MSB of the address (Atmel ATmega16HVB/ATmega32HVB). If polling (RDY/BSY) is not used, the user must wait at least tWD_FLASH before issuing the next page (see Table 30-11). Accessing the serial programming interface before the Flash write operation completes can result in incorrect programming. 5. A: The EEPROM array is programmed one byte at a time by supplying the address and data together with the appropriate Write instruction. An EEPROM memory location is first automatically erased before new data is written. If polling (RDY/BSY) is not used, the user must wait at least tWD_EEPROM before issuing the next byte (see Table 30-11). In a chip erased device, no 0xFFs in the data file(s) need to be programmed. B: The EEPROM array is programmed one page at a time. The Memory page is loaded one byte at a time by supplying the 2 LSB of the address and data together with the Load EEPROM Memory Page instruction. The EEPROM Memory Page is stored by loading the Write EEPROM Memory Page Instruction with the 7/8 MSB of the address (ATmega16HVB/ATmega32HVB). When using EEPROM page access only byte locations loaded with the Load EEPROM Memory Page instruction is altered. The remaining locations remain unchanged. If polling (RDY/BSY) is not used, the used must wait at least tWD_EEPROM before issuing the next page (see Table 30-8 on page 207). In a chip erased device, no 0xFF in the data file(s) need to be programmed. 6. Any memory location can be verified by using the Read instruction which returns the content at the selected address at serial output MISO. 7. At the end of the programming session, RESET can be set high to commence normal operation. 8. Power-off sequence (if needed): Set RESET to “1”. Turn VCC power off. Table 30-11. Minimum wait delay before writing the next flash or EEPROM location. Symbol Minimum wait delay tWD_FLASH 4.5ms tWD_EEPROM 4.0ms tWD_ERASE 4.0ms tWD_FUSE 4.5ms 210 8042E–AVR–09/2013 ATmega16HVB/32HVB 30.6.2 Serial programming instruction set Table 30-12 and Figure 30-2 on page 211 describes the instruction set. Notes: 1. Not all instructions are applicable for all parts. 2. adr = address. 3. Bits are programmed ‘0’, unprogrammed ‘1’. 4. To ensure future compatibility, unused Fuses and Lock bits should be unprogrammed (‘1’). 5. Refer to the corresponding section for Fuse and Lock bits, Calibration and Signature bytes and Page size. 6. Instructions accessing program memory use word address. This address may be random within the page range. 7. See http://www.atmel.com/avr for Application Notes regarding programming and programmers. Table 30-12. Serial programming instruction set. Instruction/operation Instruction format Byte 1 Byte 2 Byte 3 Byte 4 Programming enable $AC $53 $00 $00 Chip erase (program memory/EEPROM) $AC $80 $00 $00 Poll RDY/BSY $F0 $00 $00 data byte out Load instructions Load extended address byte (1) $4D $00 Extended adr $00 Load program memory page, high byte $48 adr MSB adr LSB high data byte in Load program memory page, low byte $40 adr MSB adr LSB low data byte in Load EEPROM memory page (page access) $C1 adr MSB adr LSB data byte in Read instructions Read program memory, high byte $28 adr MSB adr LSB high data byte out Read program memory, low byte $20 adr MSB adr LSB low data byte out Read EEPROM memory $A0 adr MSB adr LSB data byte out Read lock bits $58 $00 $00 data byte out Read signature byte $30 $00 adr LSB data byte out Read fuse bits $50 $00 $00 data byte out Read fuse high bits $58 $08 $00 data byte out Read extended fuse bits $50 $08 $00 data byte out Read calibration byte $38 $00 $00 data byte out Write instructions (6) Write program memory page $4C adr MSB adr LSB $00 Write EEPROM memory $C0 adr MSB adr LSB data byte in Write EEPROM memory page (page access) $C2 adr MSB adr LSB $00 Write lock bits $AC $E0 $00 data byte in Write fuse bits $AC $A0 $00 data byte in Write fuse high bits $AC $A8 $00 data byte in Write extended fuse bits $AC $A4 $00 data byte in 211 8042E–AVR–09/2013 ATmega16HVB/32HVB If the LSB in RDY/BSY data byte out is ‘1’, a programming operation is still pending. Wait until this bit returns ‘0’ before the next instruction is carried out. Within the same page, the low data byte must be loaded prior to the high data byte. After data is loaded to the page buffer, program the EEPROM page, see Figure 30-2. Figure 30-2. Serial programming instruction example. 30.7 Parallel programming This section describes parameters, pin mapping, and commands used to parallel program and verify Flash Program memory, EEPROM Data memory, Memory Lock bits, and Fuse bits in the Atmel ATmega16HVB/32HVB. Pulses are assumed to be at least 250 ns unless otherwise noted. 30.7.1 Considerations for efficient programming The loaded command and address are retained in the device during programming. For efficient programming, the following should be considered. • The command needs only be loaded once when writing or reading multiple memory locations • Skip writing the data value 0xFF, that is the contents of the entire EEPROM (unless the EESAVE Fuse is programmed) and Flash after a Chip Erase Address high byte needs only be loaded before programming or reading a new 256 word window in Flash or 256 byte EEPROM. This consideration also applies to Signature bytes reading. Byte 1 Byte 2 Byte 3 Byte 4 Adr MSB Adr LSB Bit 15 B 0 Serial Programming Instruction Program Memory/ EEPROM Memory Page 0 Page 1 Page 2 Page N-1 Page Buffer Write Program Memory Page/ Write EEPROM Memory Page Load Program Memory Page (High/Low Byte)/ Load EEPROM Memory Page (page access) Byte 1 Byte 2 Byte 3 Byte 4 Bit 15 B 0 Adr MSB Adr LSB Page Offset Page Number Adr MSB Adr LSB 212 8042E–AVR–09/2013 ATmega16HVB/32HVB 30.7.2 Signal names In this section, some pins of the Atmel ATmega16HVB/32HVB are referenced by signal names describing their functionality during parallel programming, see Figure 30-3 and Table 30-13. Pins not described in the following table are referenced by pin names. The XA1/XA0 pins determine the action executed when the XTAL1 pin is given a positive pulse. The bit coding is shown in Table 30-15 on page 213. When pulsing WR or OE, the command loaded determines the action executed. The different Commands are shown in Table 30-16 on page 213. Table 32-18 on page 236 shows the Parallel programming characteristics. Figure 30-3. Parallel programming. Table 30-13. Pin name mapping. Signal name in programming mode Pin name I/O Function RDY/BSY PA0 O 0: Device is busy programming 1: Device is ready for new command BS1 PA1 I Byte select 1 (“0” selects low byte, “1” selects high byte) BS2 PA2 I Byte select 2 (“0” selects low byte, “1” selects 2’nd high byte) PAGEL PA3 I Program memory and EEPROM data page load RESET RESET I DATA PB[7:0] I/O Bi-directional data bus (output when OE is low) WR PC0 I Write pulse (active low) OE PC1 I Output enable (active low) XTAL PC2 I XA0 PC3 I XTAL action bit 0 XA1 PC4 I XTAL action bit 1 VFET +4.0V - 18.0V GND DATA[7:0] +11.5V - 12.5V RESET PAGEL BS2 BS1 X1 X0 OE XTAL1 WR RDY/BSY 213 8042E–AVR–09/2013 ATmega16HVB/32HVB 30.7.3 Enter programming mode The following algorithm puts the device in parallel programming mode: 1. Make sure the chip is started as explained in ”Power-on reset and charger connect” on page 43. 2. Set RESET to “0” and toggle XTAL1 at least six times. 3. Set the Prog_enable pins listed in Table 30-14 to “0000” and wait at least 100ns. 4. Apply 11.5V - 12.5V to RESET. Any activity on Prog_enable pins within 100ns after +12V has been applied to RESET, will cause the device to fail entering programming mode. 5. Wait at least 50µs before sending a new command. 30.7.4 Chip erase The Chip Erase will erase the Flash and EEPROM (1) memories plus Lock bits. The Lock bits are not reset until the program memory has been completely erased. The Fuse bits are not changed. A Chip Erase must be performed before the Flash and/or EEPROM are reprogrammed. Note: 1. The EEPRPOM memory is preserved during Chip Erase if the EESAVE Fuse is programmed. Table 30-14. Pin values used to enter programming mode. Pin Symbol Value PB3 Prog_enable[3] 0 PB2 Prog_enable[2] 0 PB1 Prog_enable[1] 0 PB0 Prog_enable[0] 0 Table 30-15. XA1 and XA0 coding. XA1 XA0 Action when XTAL1 is pulsed 0 0 Load flash or EEPROM address (High or low address byte determined by BS1) 0 1 Load data (High or Low data byte for Flash determined by BS1) 1 0 Load command 1 1 No action, idle Table 30-16. Command byte bit coding. Command byte Command executed 1000 0000 Chip erase 0100 0000 Write fuse bits 0010 0000 Write lock bits 0001 0000 Write flash 0001 0001 Write EEPROM 0000 1000 Read signature bytes and calibration byte 0000 0100 Read fuse and lock bits 0000 0010 Read flash 0000 0011 Read EEPROM 214 8042E–AVR–09/2013 ATmega16HVB/32HVB Load command “Chip Erase”. 1. Set XA1, XA0 to “10”. This enables command loading. 2. Set BS1 to “0”. 3. Set DATA to “1000 0000”. This is the command for Chip Erase. 4. Give XTAL1 a positive pulse. This loads the command. 5. Give WR a negative pulse. This starts the Chip Erase. RDY/BSY goes low. 6. Wait until RDY/BSY goes high before loading a new command. 30.7.5 Programming the flash The Flash is organized in pages, see Table 30-7 on page 207. When programming the Flash, the program data is latched into a page buffer. This allows one page of program data to be programmed simultaneously. The following procedure describes how to program the entire Flash memory: A. Load Command “Write Flash” 1. Set XA1, XA0 to “10”. This enables command loading. 2. Set BS1 to “0”. 3. Set DATA to “0001 0000”. This is the command for Write Flash. 4. Give XTAL1 a positive pulse. This loads the command. B. Load Address Low byte 1. Set XA1, XA0 to “00”. This enables address loading. 2. Set BS1 to “0”. This selects low address. 3. Set DATA = Address low byte (0x00 - 0xFF). 4. Give XTAL1 a positive pulse. This loads the address low byte. C. Load Data Low Byte 1. Set XA1, XA0 to “01”. This enables data loading. 2. Set DATA = Data low byte (0x00 - 0xFF). 3. Give XTAL1 a positive pulse. This loads the data byte. D. Load Data High Byte 1. Set BS1 to “1”. This selects high data byte. 2. Set XA1, XA0 to “01”. This enables data loading. 3. Set DATA = Data high byte (0x00 - 0xFF). 4. Give XTAL1 a positive pulse. This loads the data byte. E. Latch Data 1. Set BS1 to “1”. This selects high data byte. 2. Give PAGEL a positive pulse. This latches the data bytes (see Figure 30-5 on page 216 for signal waveforms). F. Repeat B through E until the entire buffer is filled or until all data within the page is loaded While the lower bits in the address are mapped to words within the page, the higher bits address the pages within the FLASH. This is illustrated in Figure 30-4 on page 215. Note that if less than eight bits are required to address words in the page (pagesize <256), the most significant bit(s) in the address low byte are used to address the page when performing a Page Write. 215 8042E–AVR–09/2013 ATmega16HVB/32HVB G. Load Address High byte 1. Set XA1, XA0 to “00”. This enables address loading. 2. Set BS1 to “1”. This selects high address. 3. Set DATA = Address high byte (0x00 - 0xFF). 4. Give XTAL1 a positive pulse. This loads the address high byte. H. Program Page 1. Give WR a negative pulse. This starts programming of the entire page of data. RDY/BSY goes low. 2. Wait until RDY/BSY goes high (see Figure 30-5 on page 216 for signal waveforms). I. Repeat B through H until the entire Flash is programmed or until all data has been programmed. J. End Page Programming 1. 1. Set XA1, XA0 to “10”. This enables command loading. 2. Set DATA to “0000 0000”. This is the command for No Operation. 3. Give XTAL1 a positive pulse. This loads the command, and the internal write signals are reset. Figure 30-4. Addressing the flash which is organized in pages (1). Note: 1. PCPAGE and PCWORD are listed in Table 30-7 on page 207. PROGRAM MEMORY WORD ADDRESS WITHIN A PAGE PAGE ADDRESS WITHIN THE FLASH INSTRUCTION WORD PAGE PCWORD[PAGEMSB:0]: 00 01 02 PAGEEND PAGE PCPAGE PCWORD PCMSB PAGEMSB PROGRAM COUNTER 216 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 30-5. Programming the flash waveforms (1). Note: 1. “XX” is don’t care. The letters refer to the programming description above. 30.7.6 Programming the EEPROM The EEPROM is organized in pages, see Table 30-8 on page 207. When programming the EEPROM, the program data is latched into a page buffer. This allows one page of data to be programmed simultaneously. The programming algorithm for the EEPROM data memory is as follows (refer to ”Programming the flash” on page 214 for details on Command, Address and Data loading): 1. A: Load Command “0001 0001”. 2. G: Load Address High Byte (0x00 - 0xFF). 3. B: Load Address Low Byte (0x00 - 0xFF). 4. C: Load Data (0x00 - 0xFF). 5. E: Latch data (give PAGEL a positive pulse). K: Repeat 3 through 5 until the entire buffer is filled L: Program EEPROM page 1. Set BS to “0”. 2. Give WR a negative pulse. This starts programming of the EEPROM page. RDY/BSY goes low. 3. Wait until to RDY/BSY goes high before programming the next page (see Figure 30-6 on page 217 for signal waveforms). RDY/BSY WR OE RESET +12V PAGEL BS2 0x10 ADDR. LOW ADDR. HIGH DATA DATA LOW DATA HIGH ADDR. LOW DATA LOW DATA HIGH XA1 XA0 BS1 XTAL1 XX XX XX A B C D EB C D E G H F 217 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 30-6. Programming the EEPROM waveforms. 30.7.7 Reading the flash The algorithm for reading the flash memory is as follows (refer to ”Programming the flash” on page 214 for details on Command and Address loading): 1. A: Load Command “0000 0010”. 2. G: Load Address High Byte (0x00 - 0xFF). 3. B: Load Address Low Byte (0x00 - 0xFF). 4. Set OE to “0”, and BS1 to “0”. The Flash word low byte can now be read at DATA. 5. Set BS to “1”. The Flash word high byte can now be read at DATA. 6. Set OE to “1”. 30.7.8 Reading the EEPROM The algorithm for reading the EEPROM memory is as follows (refer to ”Programming the flash” on page 214 for details on Command and Address loading): 1. A: Load Command “0000 0011”. 2. G: Load Address High Byte (0x00 - 0xFF). 3. B: Load Address Low Byte (0x00 - 0xFF). 4. Set OE to “0”, and BS1 to “0”. The EEPROM Data byte can now be read at DATA. 5. Set OE to “1”. 30.7.9 Programming the fuse low bits The algorithm for programming the Fuse Low bits is as follows (refer to ”Programming the flash” on page 214 for details on Command and Data loading): 1. A: Load Command “0100 0000”. 2. C: Load Data Low Byte. Bit n = “0” programs and bit n = “1” erases the Fuse bit. 3. Give WR a negative pulse and wait for RDY/BSY to go high. RDY/BSY WR OE RESET +12V PAGEL BS2 0x11 ADDR. HIGH DATA ADDR. LOW DATA ADDR. LOW DATA XX XA1 XA0 BS1 XTAL1 XX A G B C EB C E L K 218 8042E–AVR–09/2013 ATmega16HVB/32HVB 30.7.10 Programming the fuse high bits The algorithm for programming the Fuse High bits is as follows (refer to ”Programming the flash” on page 214 for details on Command and Data loading): 1. A: Load Command “0100 0000”. 2. C: Load Data Low Byte. Bit n = “0” programs and bit n = “1” erases the Fuse bit. 3. Set BS1 to “1” and BS2 to “0”. This selects high data byte. 4. Give WR a negative pulse and wait for RDY/BSY to go high. 5. Set BS1 to “0”. This selects low data byte. Figure 30-7. Programming the FUSES waveforms. 30.7.11 Programming the lock bits The algorithm for programming the Lock bits is as follows (refer to ”Programming the flash” on page 214 for details on Command and Data loading): 1. A: Load Command “0010 0000”. 2. C: Load Data Low Byte. Bit n = “0” programs the Lock bit. If LB mode 3 is programmed (LB1 and LB2 is programmed), it is not possible to program the Boot Lock bits by any External Programming mode. 3. Give WR a negative pulse and wait for RDY/BSY to go high. The Lock bits can only be cleared by executing Chip Erase. 30.7.12 Reading the fuse and lock bits The algorithm for reading the Fuse and Lock bits is as follows (refer to ”Programming the flash” on page 214 for details on Command loading): 1. A: Load Command “0000 0100”. 2. Set OE to “0”, BS2 to “0” and BS1 to “0”. The status of the Fuse Low bits can now be read at DATA (“0” means programmed). 3. Set OE to “0”, BS2 to “1” and BS1 to “1”. The status of the Fuse High bits can now be read at DATA (“0” means programmed). 4. Set OE to “0”, BS2 to “0” and BS1 to “1”. The status of the Lock bits can now be read at DATA (“0” means programmed). 5. Set OE to “1”. RDY/BSY WR OE RESET +12V PAGEL 0x40 DATA DATA XX XA1 XA0 BS1 XTAL1 A C 0x40 DATA XX A C Write Fuse Low byte Write Fuse high byte 0x40 DATA XX A C Write Extended Fuse byte BS2 219 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 30-8. Mapping between BS1, BS2 and the fuse and lock bits during read. 30.7.13 Reading the Signature bytes The algorithm for reading the Signature bytes is as follows (refer to ”Programming the flash” on page 214 for details on Command and Address loading): 1. A: Load Command “0000 1000”. 2. B: Load Address Low Byte (0x00 - 0x02). 3. Set OE to “0”, and BS to “0”. The selected Signature byte can now be read at DATA. 4. Set OE to “1”. 30.7.14 Reading the Calibration byte The algorithm for reading the Calibration byte is as follows (refer to ”Programming the flash” on page 214 for details on Command and Address loading): 1. A: Load Command “0000 1000”. 2. B: Load Address Low Byte, 0x00. 3. Set OE to “0”, and BS1 to “1”. The Calibration byte can now be read at DATA. 4. Set OE to “1”. Lock Bits 0 1 BS2 Fuse High Byte 0 1 BS1 DATA Fuse Low Byte 0 1 BS2 Extended Fuse Byte 220 8042E–AVR–09/2013 ATmega16HVB/32HVB 31. Operating circuit Figure 31-1. Operating circuit, 4-cell. R8 R6 D6 D7 D8 D9 D10 ATmega16HVB/32HVB VFET OC PVT OD + PV4 PV3 PV2 PV1 NV PA0/ADC0/SGND PA1/ADC1/SGND RESET VREG PB3 PB4 PB5 PB6 PB7 BATT R7 VREF VREFGND SMBDATA SMBCLK R28 R29 VCC R20 R19 R21 PC5 PA2 R27 PB0 PB1/CKOUT PB2 PC3/SDA PC4/SCL PC0/EXT_PROT D3 R23 R22 PC2 R17 C14 C13 C15 PC1 C7 C6 C5 R5 C16 C12 SW1 D4 SYS PRESENT R24 FUSE BLOW FUSE STATUS R25 R26 F1 D1 R16 Q2 Q3 Q4 PA3 R9 R10 R11 R12 C9 PPI PI NI NNI R13 R14 R18 - R4 R3 R2 R1 S-8244 R15 SENSE VC1 VC2 VC3 VSS VCC ICT CO C8 VCC VCC VCC VCC C10 C4 C3 C2 C1 C11 R30 Q1 D2 D5 RT33 RT32 CELL4 CELL3 CELL2 CELL1 Pack+ PackC18 VCLMP10 Optional secondary protection and fuse blow circuitry R31 R36 R37 221 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 31-2. Operating circuit, 3-cell. R8 R6 D6 D7 D8 D9 D10 ATmega16HVB/32HVB VFET OC PVT OD + PV4 PV3 PV2 PV1 NV PA0/ADC0/SGND PA1/ADC1/SGND RESET VREG PB3 PB4 PB5 PB6 PB7 BATT R7 VREF VREFGND SMBDATA SMBCLK R28 R29 VCC R20 R19 R21 PC5 PA2 R27 PB0 PB1/CKOUT PB2 PC3/SDA PC4/SCL PC0/EXT_PROT D3 R23 R22 PC2 R17 C14 C13 C15 PC1 C6 C5 R5 C12 SW1 D4 SYS PRESENT R24 FUSE BLOW FUSE STATUS R25 R26 F1 D1 R16 Q2 Q3 Q4 PA3 R10 R11 R12 C9 PPI PI NI NNI R13 R14 R18 - R4 R3 R2 S-8244 R15 SENSE VC1 VC2 VC3 VSS VCC ICT CO VCC VCC VCC VCC C10 C4 C3 C2 C11 R30 Q1 D2 D5 CELL3 CELL2 CELL1 Pack+ PackC18 VCLMP10 Optional secondary protection and fuse blow circuitry R9 C7 C16 RT33 RT32 R31 R36 R37 222 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 31-3. Operating circuit, 2-cell. R8 R6 D6 D7 D8 D9 D10 ATmega16HVB/32HVB VFET OC PVT OD + PV4 PV3 PV2 PV1 NV PA0/ADC0/SGND PA1/ADC1/SGND RESET VREG PB3 PB4 PB5 PB6 PB7 BATT R7 VREF VREFGND SMBDATA SMBCLK R28 R29 VCC R20 R19 R21 PA2 PC5 R27 PB0 PB1/CKOUT PB2 PC3/SDA PC4/SCL PC0/EXT_PROT D3 R23 R22 PC2 R17 C14 C13 C15 PC1 C6 C5 R5 C12 SW1 D4 SYS PRESENT R24 FUSE BLOW FUSE STATUS R25 R26 F1 D1 R16 Q2 Q3 Q4 PA3 R10 R11 R12 C9 PPI PI NI NNI R13 R14 R18 - R4 R3 S-8244 R15 SENSE VC1 VC2 VC3 VSS VCC ICT CO VCC VCC VCC VCC C10 C4 C3 C11 R30 Q1 D2 D5 CELL2 CELL1 Pack+ PackC18 VCLMP10 Optional secondary protection and fuse blow circuitry R9 Q5 R34 R35 C16 RT33 RT32 R31 R36 R37 223 8042E–AVR–09/2013 ATmega16HVB/32HVB Table 31-1. Bill of materials. Symbol Number Description C1-C4, C10, C11 6 Capacitor, ceramic, 0.1µF - 1.0µF , 50V, X7R C5-C8 4 Capacitor, ceramic, 0.01µF - 0.5µF, 50V, X7R C9, C12, C13, C15 4 Capacitor, ceramic, 0.1µF, 50V, X7R C14 1 Capacitor, ceramic, 2.2µF - 4.7µF, 10V, X7R C16 1 Capacitor, ceramic, 1µF - 22µF, 10V, X7R C18 1 Capacitor, ceramic, 22nF, 50V, X7R D1 1 Diode, signal D2 1 Diode, double, Shottky D4 1 Diode, signal D3 1 Diode, Zener, value from design considerations D4 1 Diode, Zener, 5V6 D5 1 Diode, double, Zener, 5V6 D6-D10 5 LEDs F1 1 Chemical fuse Q1 1 N-FET, 50V, 0.22A Q2, Q3 2 N-FET, 30V, 10A Q4 1 N-FET, 20V, 1.3A Q5 1 P-FET, 30V, 10A R1-R4 4 Resistor, chip, 1k - 10k, 1/16W, 5% R5-R9 5 Resistor, chip, 10k - 1000, 1/16W, 5% R10 1 Sense resistor, 1m - 10m, 1W, 1% R11, R12 2 Resistor, chip, 10 - 500, 1/16W, 5% R13, R14, R18, R19, R20, R21, R25 7 Resistor, chip 1k, 1/16W, 5% R15 1 Resistor, chip, 100 - 1000, 1/16W, 5% R16, R17 2 Resistor, chip 200k, 1/16W, 5% R22 1 Resistor, value from design considerations R23 1 Resistor, value from design considerations R24 1 Resistor, chip 1k, 1/16W, 5% R26, R27 2 Resistor, chip 100, 1/16W, 5% R28, R29 2 Resistor, chip 1M, 1/16W, 5% R30 1 Resistor, chip 820, 1/16W, 5% R31 1 Resistor, chip 2.4k, 1/16W, 5% R32, R33 2 NTC thermistor, 10k, B = 3000 - 4000 R34 1 Resistor, value determined by battery pack and charger requirements R35 1 Resistor, chip 1M, 1/16W, 5% 224 8042E–AVR–09/2013 ATmega16HVB/32HVB R36, R37 2 Resistor, chip 5.1k, 1/16W, 5% SW 1 Switch, push button U1 1 Atmel ATmega32HVB U2 1 S-8244 secondary protection device (Seiko Instruments) Symbol Number Description 225 8042E–AVR–09/2013 ATmega16HVB/32HVB 32. Electrical characteristics 32.1 Absolute maximum ratings* 32.2 Supply current characteristics Operating temperature .................................... -40C to +85C *NOTICE: Stresses beyond those listed under “Absolute Maximum Ratings” may cause permanent damage to the device. This is a stress rating only and functional operation of the device at these or other conditions beyond those indicated in the operational sections of this specification is not implied. Exposure to absolute maximum rating conditions for extended periods may affect device reliability. Storage temperature...................................... -65°C to +150°C Voltage on PA0 - PA3, PI, NI, PPI and NNI with respect to ground .............................. -0.5V to VREG +0.5V Voltage on PB0 - PB7 with respect to ground .............................. -0.5V to VCC +0.5V Voltage on PC0 - PC4, PV1, and NV with respect to ground..................-0.5V to +6.0V Voltage on OC and OD with respect to ground...-0.5V to +35V Voltage on PC5, BATT, PVT, VFET, PV4, PV3, and PV2 with respect to ground ........................................-0.5V to +25V Voltage on PV4 with respect to PV3: ................. -0.5V to +10V Voltage on PV3 with respect to PV2: ................. -0.5V to +10V Voltage on PV2 with respect to PV1: ................. -0.5V to +10V Voltage on PV1 with respect to NV: ................... -0.5V to +10V Voltage on PVT with respect to VFET: .............................. 10V Voltage on VCLMP10 and RESET with respect to ground ........................................-0.5V to +13V Maximum operating voltage on VREG and VCC.............. 4.5V Maximum operating voltage on VFET ............................... 18V Table 32-1. TA= 25°C unless otherwise noted. Symbol Parameter Condition Minimum Typical Maximum Units IVFET Active current VFET = 16V, CPU clock = 8MHz, All PRR bits set 3.75 5 mA VFET = 16V, CPU clock = 1MHz, All PRR bits set 760 1000 µA Idle current VFET = 16V, CPU clock = 1MHz, All PRR bits set 215 293 ADCNRM current VFET = 16V, CPU clock = 1MHz, All PRR bits except PRVADC are set, VADC enabled 350 Power-save current VFET = 16V, Only WDT enabled, DUVR mode disabled 28 46 VFET = 16V, WDT, CC-ADC, OC, OD and Battery Protection enabled, DUVR mode disabled 115 170 Power-off current VFET = 6V <1 2 226 8042E–AVR–09/2013 ATmega16HVB/32HVB 32.3 NFET driver characteristics Notes: 1. Measures NFET driver’s ability to switch OC/OD from 0V to specified output level with constant resistive load on the pin. Loads above this limit may cause OC/OD not reaching the specified level. Drive capability is highly temperature dependent. Refer to Section 33.2 ”NFET driver characteristics” on page 245 for details. Note: The NFET drivers require a minimum total cell voltage of 6V or higher or a charger connected to turn-on the FETs. Note that this limit only applies if the FET is disabled in advance. If the FET is already enabled, the FET will be fully operational in the entire voltage range of the device (4V to 18V). Table 32-2. TA= 25°C unless otherwise noted. Symbol Parameter Condition Min. Typ. Max. Units VOC,ON OC pin on voltage relative to PVT voltage OC enabled, VFET = 16V 13 V OC enabled, VFET = 10V 13 OC enabled, VFET = 4V 6 VOD,ON OD pin on voltage relative to BATT voltage OD enabled, VFET = 16V 13 OD enabled, VFET = 10V 13 OD enabled, VFET = 4V 6 VOC,OFF OC pin off voltage realtive to GND 0.0 VOD,OFF OD pin off voltage realtive to GND 0.0 tr,OC Rise time on OC pin V(OC-PVT) = 0V to 2V, Ceq = 4.7nF, VFET = 16V 0.8 ms V(OC-PVT) = 0V to 2V, Ceq = 4.7nF, VFET = 10V 1.1 V(OC-PVT) = 0V to 2V, Ceq = 4.7nF, VFET = 6V 3 V(OC-PVT) = 2V to 4V, Ceq = 4.7nF, VFET = 16V 1 V(OC-PVT) = 2V to 4V, Ceq = 4.7nF, VFET = 10V 1.2 V(OC-PVT) = 2V to 4V, Ceq = 4.7nF, VFET = 6V 1.3 tr,OD Rise time on OD pin V(OD-BATT) = 0V to 2V, Ceq = 4.7nF, VFET = 16V 0.8 V(OD-BATT) = 0V to 2V, Ceq = 4.7nF, VFET = 10V 1.1 V(OD-BATT) = 0V to 2V, Ceq = 4.7nF, VFET = 6V 3 V(OD-BATT) = 2V to 4V, Ceq = 4.7nF, VFET = 16V 1 V(OD-BATT) = 2V to 4V, Ceq = 4.7nF, VFET = 10V 1.2 V(OD-BATT) = 2V to 4V, Ceq = 4.7nF, VFET = 6V 1.3 tf,OC Fall time on OC pin V(OD-PVT) = VOC,ON to 0V, Ceq = 4.7nF, VFET = 16V 50 ns tf,OD Fall time on OD pin V(OD-BATT) = VOD,ON to 0V, Ceq = 4.7nF, VFET = 16V 50 ILOAD OC/OD drive capability (1) VFET = 9V, TA = 85°C 3.5 µA VVFET,DUV R Regulated VFET voltage in DUVR mode DUVR enabled, VREF = 1.1V 4.1 4.9 V 227 8042E–AVR–09/2013 ATmega16HVB/32HVB 32.4 Reset characteristics Notes: 1. The voltage at the pack + terminal will be slightly higher than VPOT when the chip is enabled. This is because of an internal Pull-down current on the BATT pin in the range 50µA - 150µA and the RBATT resistor connected between the Pack + terminal and the BATT pin. RBATT = 1k gives a voltage drop 0.05V - 0.15V. 2. The power-on reset will not work unless the voltage has been below VPOT (falling) after a power-off condition. 32.5 Voltage regulator characteristics 32.6 Voltage reference and temperature sensor characteristics Notes: 1. Calibration is done in Atmel factory test. Software should calibrate the VREF by writing the BGCRR and BGCCR registers with the calibration values stored in the signature row. 2. This value is not tested in production. 3. The measured VPTAT voltage must be scaled with the calibration value stored in the VPTAT Calibration Register to get the absolute temperature. The design target accuracy for this parameter assumes an exact calibration temperature. Actual accuracy of this parameter after calibration in Atmel factory test remains to be determined. Table 32-3. TA= -40°C to +85°C unless otherwise noted. Symbol Parameter Condition Min. Typ. Max. Units VPOT Power-on threshold voltage (rising) (1) 4.5 7 V Power-on threshold voltage (falling) (1)(2) 4.5 6.3 t RST Minimum pulse width on RESET Pin 900 ns VBOT Brown-out detection (BOD) trigger level TA = 25°C 2.9 3.1 V VHYST BOD level hysteresis TA = 25°C 50 mV Table 32-4. TA= -40°C to +85°C unless otherwise noted. Symbol Parameter Condition Min. Typ. Max. Unit VVREG Regulator output voltage VFET = 16.8V, IOUT = 20mA 3.1 V VFET = 6V, IOUT = 20mA 3.1 VFET = 4V, IOUT = 7mA 3.1 VRSCL Voltage regulator short- circuit Level at VFET pin 3.3 3.8 VBLOD Voltage Regulator Black-out Detection Level at VREG pin TA = 25°C 2.65 2.75 Table 32-5. TA= -40°C to +85°C unless otherwise noted. Parameter Condition Min. Typ. Max. Units Reference voltage 1.100 V Reference voltage accuracy (1) After factory calibration, TA = 25°C ±0.1 ±0.2 % Temperature drift (1)(2) TA = -40C to +85C 60 90 ppm/K TA = 0C to +60C 25 50 VREF calibration Hold Off Time CREG = 2.2µF, BGCCR write 2 µs CREG = 2.2µf, BGCRR write 5 VPTAT, voltage proportional to absolute temperature (2) 0.6 mV/K VPTAT absolute accuracy (3) ±5 K 228 8042E–AVR–09/2013 ATmega16HVB/32HVB 32.7 ADC characteristics 32.7.1 Voltage ADC characteristics Notes: 1. Value is after Atmel factory offset and gain compensation in production (for details, see Table 29-3, “Signature row addressing.,” on page 196) and it includes drift over the whole temperature range. 2. Value not tested in production but guaranteed by design and characterization. Table 32-6. TA= -40°C to +85°C unless otherwise noted. Parameter Condition Min. Typ. Max. Units Conversion time clkVADC = 1MHz 519 µs Resolution 12 Bits Gain ADC0/1 (un-scaled) 263 µV/LSB Gain cell inputs (x0.2) 1.42 mV/LSB INL (2) ADC0, ADC1 ±1 ±3 CELL1, CELL2, CELL3 ±1 ±3 LSB CELL4 ±2 ±5 Input voltage range ADC0, ADC1, VTEMP 0 1 V Input voltage range CELL1 1.8 5 Input voltage range CELL2 VPV1-GND>1.8V 0 5 Input voltage range CELL3 VPV2-GND>1.8V 0 5 Input voltage range CELL4 VPV3-GND>1.8V 0 5 Offset drift (1)(2) ADC0, ADC1 1 CELL1, CELL2, CELL3 1 LSB CELL4 5 Gain drift (1)(2) ADC0, ADC1 6 CELL1, CELL2, CELL3 7 LSB CELL4 15 229 8042E–AVR–09/2013 ATmega16HVB/32HVB 32.7.2 Coulomb counter ADC characteristics Notes: 1. Values based on characterization data. 2. After software offset compensation, using the polarity switching (CADPOL) feature. 3. Value includes drift over the whole temperature range. 32.8 Clock characteristics Notes: 1. The frequency is stored in the Value after factory calibration at 85°C. 2. Value not tested in production, but is guaranteed by design and characterization over the whole temperature range. 3. The actual oscillator frequency is measured in production and store in the device signature row (for detailes, see ”Reading the signature row from software” on page 195. 4. TA = 0°C to +85°C. Table 32-7. TA= -40°C to +85°C unless otherwise noted. Parameter Condition Min. Typ. Max. Units Conversion time Instantaneous conversion, clkCC-ADC = 32kHz 3.9 ms Accumulated conversion CADAS = 11, clkCC-ADC = 32kHz 1 s Resolution Instantaneous conversion 13 Bits Accumulated conversion 18 Gain Accumulated conversion, CADVSE=0 1.67 µV/LSB Accumulated conversion, CADVSE=1 0.84 Instantaneous conversion, CADVSE=0 53.7 Instantaneous conversion, CADVSE=1 26.9 Input voltage range CADVSE = 0 -200 200 mV CADVSE = 1 -100 100 INL (1) TA= 0°C - 60°C ±0.003 ±0.005 % FSR Offset error (2) Accumulated conversion, TA = 25°C -7 µV Offset error drift (1)(2) Accumulated conversion 30 nV/°C Gain error (1)(3) ±0.4 ±1 % Gain error drift (1) 0.1 Table 32-8. TA= -40°C to +85°C unless otherwise noted. Parameter Condition Min. Typ. Max. Units Calibrated fast RC oscillator Frequency After factory calibration at TA = 25°C 7.92 8 8.08 MHz Frequency drift (2) With run-time calibration with OSI interface and slow RC oscillator as calibration clock 3 % Slow RC oscillator (1) Frequency (3) 91 131 171 kHz Frequency prediction error (4) 0.2 % Ultra low power RC oscillator (1) Frequency (3) 89 128 167 kHz Frequency drift (2) 6 % 230 8042E–AVR–09/2013 ATmega16HVB/32HVB 32.9 Cell balancing characteristic 32.10 Battery protection characteristics Notes: 1. Levels in charge and discharge direction can be configured independent of each other. 2. VSCD = VNNI - VPPI, VCOCD = VPPI - VNNI, VDOCD = VNNI - VPPI, VCHCD = VPPI - VNNI, VDHCD = VNNI - VPPI 32.11 External interrupt characteristics Table 32-9. TA= 25°C unless otherwise noted. Parameter Condition Min. Typ. Max. Unit Balancing current Battery cell voltage VCELL = 4.2V, V-ADC filter resistance = 470 4 mA Table 32-10. TA= -40°C to +85°C unless otherwise noted. Parameter Condition Min. Max. Unit Short circuit detection level error (1) Charge/discharge over current detection level error (1) Charge/discharge high current detection detection level error (1) VSCD, VCOCD, VDOCD, VCHCD, and VDHCD from 20mV to 70mV (2) -10 +10 mV VSCD, VCOCD, VDOCD, VCHCD, and VDHCD from 80mV to 140mV (2) -15 +15 VSCD, VCOCD, VDOCD, VCHCD, and VDHCD from 150mV to 270mV (2) -35 +35 VSCD, VCOCD, VDOCD, VCHCD, and VDHCD at 310mV (2) -50 +50 Table 32-11. Asynchronous external interrupt characteristics. Symbol Parameter Condition Min. Typ. Max. Unit tINT Minimum pulse width for asynchronous external interrupt 50 ns 231 8042E–AVR–09/2013 ATmega16HVB/32HVB 32.12 General I/O lines characteristics 32.12.1 Port A and B characteristics Notes: 1. “Max” means the highest value where the pin is guaranteed to be read as low. 2. “Min” means the lowest value where the pin is guaranteed to be read as high. 3. Although each I/O port can sink more than the test conditions (5mA at VCC = 3.3V) under steady state conditions (non-transient), the following must be observed: - The sum of all IOL should not exceed 20mA If IOL exceeds the test condition, VOL may exceed the related specification. Pins are not guaranteed to sink current greater than the listed test condition. 4. Although each I/O port can source more than the test conditions (2mA at VCC = 3.3V) under steady state conditions (nontransient), the following must be observed: - The sum of all IOH should not exceed 2mA This restriction is put because the device should be within spec throughout the whole operation range. The integrated voltage regulator could have problems providing this output when supplying high currents at low VFET voltages. 5. The typical hysteresis on VIL/VIH is 300mV on all PA and PB pins except PA3. PA3 has a typical hysteresis of 50mV. 32.12.2 Port C characteristics Note: 1. This values is based on characterization and is not tested in production. Table 32-12. TA = -40°C to +85°C, VCC = 3.3V (unless otherwise noted). Symbol Parameter Condition Min. Typ. Max. Units VIL Input low voltage, Except RESET pin -0.5 0.3VCC (1) V VIL1 Input low voltage, RESET pin 0.3VCC (1) VIH Input high voltage, Except RESET pin 0.6VCC (2) VCC + 0.5 VIH1 Input high voltage, RESET pin 0.9VCC (2) VCC + 0.5 VOL Output low voltage IOL = 5mA 0.5 VOH Output high voltage IOH = 2mA 2.3 IIL Input leakage current I/O Pin Pin low (absolute value) 1 µA IIH Input leakage current I/O Pin Pin high (absolute value) 1 RRST Reset pull-up resistor 30 60 k RPU I/O pin pull-up resistor 20 50 Table 32-13. PC0-PC4 characteristics. Symbol Parameter Condition Min. Max. Unit VIL Input low-voltage -0.5 0.8 VIH Input high-voltage 2.1 5.5 V VOL (1) Output low-voltage 350µA sink current 0 0.4 Table 32-14. PC5 characteristic. Symbol Parameter Condition Min. Max. Unit VOL Output low-voltage 500µA sink current 0 0.2 V 232 8042E–AVR–09/2013 ATmega16HVB/32HVB 32.13 2-wire serial interface characteristics Table 32-15 describes the requirements for devices connected to the Two-wire Serial Bus. The Atmel ATmega16HVB/32HVB Two-wire Serial Interface meets or exceeds these requirements under the noted conditions. Timing symbols refer to Figure 32-1 on page 233. Notes: 1. In ATmega16HVB/32HVB, this parameter is characterized and not tested. 2. Cb = capacitance of one bus line in pF. 3. fCK = CPU clock frequency. 4. This requirement applies to all ATmega16HVB/32HVB Two-wire Serial Interface operation. Other devices connected to the Two-wire Serial Bus need only obey the general fSCL requirement. Table 32-15. Two-wire serial bus requirements. Symbol Parameter Condition Minimum Maximum Units VIL Input low-voltage -0.5 0.8 VIH Input high-voltage 2.1 5.5 V VOL (1) Output low-voltage 350µA sink current 0 0.4 tr (1) Rise time for both SDA and SCL 300 tof ns (1) Output fall time from VIHmin to VILmax Cb < 400pF (2) 250 tSP (1) Spikes suppressed by input filter 0 50 Ii Input current each I/O pin 0.1VBUS < Vi < 0.9VBUS -5 5 µA Ci (1) Capacitance for each I/O pin – 10 pF fSCL SCL clock frequency fCK (3) > max(16fSCL, 450Hz) (4) 0 100 kHz Rp Value of pull-up resistor fSCL 100Hz  tHD;STA Hold time (repeated) START condition fSCL 100kHz 4.0 – µs tLOW Low period of the SCL clock fSCL 100kHz 4.7 – tHIGH High period of the SCL clock fSCL 100kHz 4.0 – tSU;STA Set-up time for a repeated START condition fSCL 100kHz 4.7 – tHD;DAT Data hold time fSCL 100kHz 0.3 3.45 tSU;DAT Data setup time fSCL 100kHz 250 – tSU;STO Setup time for STOP condition fSCL 100kHz 4.0 – tBUF Bus free time between a STOP and START condition fSCL 100kHz 4.7 – VBUS – 0.4V 350µA ------------------------------- VBUS – 0.4V 100µA ------------------------------- 233 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 32-1. Two-wire serial bus timing. 32.14 SPI timing characteristics See Figure 32-2 on page 234 and SPI interface timing requirements (Slave mode).234 for details. Note: 1. Refer to ”Serial programming” on page 207 for serial programming requirements. t SU;STA t LOW t HIGH t LOW t of t HD;STA t HD;DAT t SU;DAT t SU;STO t BUF SCL SDA t r Table 32-16. SPI timing parameters. Description Mode Minimum Typical Maximum Units 1 SCK period Master See Figure 18-5 on page 106 ns 2 SCK high/low Master 50% duty cycle 3 Rise/fall time Master 3.6 4 Setup Master 10 5 Hold Master 10 6 Out to SCK Master 0.5 • tsck 7 SCK to out Master 10 8 SCK to out high Master 10 9 SS low to out Slave 15 10 SCK period Slave 4 • tck + 40ns 11 SCK high/low (1) Slave 2 • tck + 20ns 12 Rise/fall time Slave 1.6 µs 13 Setup Slave 10 ns 14 Hold Slave tck 15 SCK to out Slave 15 16 SCK to SS high Slave 20 17 SS high to tri-state Slave 10 18 SS low to SCK Slave 20 234 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 32-2. SPI interface timing requirements (Master mode). SPI interface timing requirements (Slave mode). 32.15 Serial programming characteristics Figure 32-3. Serial programming timing. MOSI (Data Output) SCK (CPOL = 1) MISO (Data Input) SCK (CPOL = 0) SS MSB LSB MSB LSB ... ... 6 1 2 2 4 5 3 7 8 MISO (Data Output) SCK (CPOL = 1) MOSI (Data Input) SCK (CPOL = 0) SS MSB LSB MSB LSB ... ... 10 11 11 13 14 12 15 17 9 X 16 MOSI MISO SCK t OVSH t SHSL t t SHOX SLSH t SLIV 235 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 32-4. Serial programming waveforms. Note: 1. 2.2 tCLCL for fck < 12MHz, 3 tCLCL for fck >= 12MHz. 32.16 Parallel programming characteristics Figure 32-5. Parallel programming timing, including some general timing requirements. MSB MSB LSB LSB SERIAL CLOCK INPUT (SCK) SERIAL DATA INPUT (MOSI) (MISO) SAMPLE SERIAL DATA OUTPUT Table 32-17. Serial programming characteristics, TA = -40C to +85C, VCC = 3.3V (unless otherwise stated). Symbol Parameter Min. Typ. Max. Units 1/tCLCL Oscillator frequency (the Atmel ATmega16HVB/32HVB) 0 8 MHz tCLCL Oscillator period (ATmega16HVB/32HVB) 125 ns t SHSL SCK pulse width high 2.2 tCLCL (1) t SLSH SCK pulse width low 2.2 tCLCL (1) t OVSH MOSI setup to SCK high tCLCL t SHOX MOSI Hold after SCK High 2 tCLCL tSLIV SCK Low to MISO Valid 15 Data & Contol (DATA, XA0/1, BS1, BS2) XTAL1 t XHXL t WLWH t DVXH t XLDX t PLWL t WLRH WR RDY/BSY PAGEL t PHPL t PLBX t BVPH t XLWL t WLBX tBVWL WLRL 236 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 32-6. Parallel programming timing, loading sequence with timing requirements(1). Note: 1. The timing requirements shown in Figure 32-5 on page 235 (that is, tDVXH, tXHXL, and tXLDX) also apply to loading operation. Figure 32-7. Parallel programming timing, reading sequence (within the same page) with timing requirements (1). Note: 1. The timing requirements shown in Figure 32-5 on page 235 (that is, tDVXH, tXHXL, and tXLDX) also apply to reading operation. Table 32-18. Parallel programming characteristics. Symbol Parameter Min. Typ. Max. Units VPP Programming enable voltage (RESET input) 11.5 12.5 V IPP Programming enable current 250 A tDVXH Data and control valid before XTAL1 high 67 ns tXLXH XTAL1 low to XTAL1 high 200 tXHXL XTAL1 pulse Width high 150 tXLDX Data and control hold after XTAL1 low 67 XTAL1 PAGEL t XLXH PLXH t t XLPH DATA ADDR0 (Low Byte) DATA (Low Byte) DATA (High Byte) ADDR1 (Low Byte) BS1 XA0 XA1 LOAD ADDRESS (LOW BYTE) LOAD DATA (LOW BYTE) LOAD DATA (HIGH BYTE) LOAD DATA LOAD ADDRESS (LOW BYTE) XTAL1 OE DATA ADDR0 (Low Byte) DATA (Low Byte) DATA (High Byte) ADDR1 (Low Byte) BS1 XA0 XA1 LOAD ADDRESS (LOW BYTE) READ DATA (LOW BYTE) READ DATA (HIGH BYTE) LOAD ADDRESS (LOW BYTE) t BVDV t OLDV t XLOL t OHDZ 237 8042E–AVR–09/2013 ATmega16HVB/32HVB Notes: 1. tWLRH is valid for the Write Flash, Write Fuse bits and Write Lock bits commands. 2. is valid for the Write EEPROM command. 3. tWLRH_CE is valid for the Chip Erase command. tXLWL XTAL1 low to WR low 0 ns t XLPH XTAL1 low to PAGEL high 0 tPLXH PAGEL low to XTAL1 high 150 tBVPH BS1 valid before PAGEL high 67 tPHPL PAGEL pulse width high 150 tPLBX BS1 hold after PAGEL low 67 t WLBX BS2/1 hold after WR low. (Fuse programming) 3200 BS2/1 hold after WR low. (All other operations) 67 tPLWL PAGEL low to WR low 67 tBVWL BS1 valid to WR low 67 tWLWH WR pulse Width low 150 tWLRL WR low to RDY/BSY low 0 1 µs tWLRH WR low to RDY/BSY high (1) 3.7 4.5 tWLRH_EE WR low to RDY/BSY high ms (2) 2.8 3.6 tWLRH_CE WR low to RDY/BSY high for chip erase (3) 7.5 9.1 tXLOL XTAL1 low to OE low 0 ns tBVDV BS1 valid to DATA valid 0 250 tOLDV OE low to DATA Valid 250 tOHDZ OE high to DATA Tri-stated 250 Table 32-18. Parallel programming characteristics. (Continued) Symbol Parameter Min. Typ. Max. Units 238 8042E–AVR–09/2013 ATmega16HVB/32HVB 33. Typical characteristics All Typical Characteristics contained in this data sheet are based on characterization of the Atmel ATmega16/32HVB. 33.1 Supply current characteristics 33.1.1 Active supply current characteristics Active mode current measurements with all bits in the PRR registers set and all I/O modules turned off. Figure 33-1. Active supply current vs. VVFET, internal RC oscillator, 8MHz. 85°C 25°C -40°C 3.6 3.65 3.7 3.75 3.8 3.85 3.9 3.95 4 4 6 8 10 12 14 16 18 20 VVFET [V] I [mA] VFET 239 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 33-2. Active supply current vs. VVFET, internal RC oscillator, 4MHz. Figure 33-3. Active supply current vs. VVFET, internal RC oscillator, 2MHz. 85°C 25°C -40°C 2.2 2.24 2.28 2.32 2.36 2.4 2.44 4 6 8 10 12 14 16 18 20 VVFET [V] I [mA] VFET 85°C 25°C -40°C 1.21 1.23 1.25 1.27 1.29 1.31 1.33 4 6 8 10 12 14 16 18 20 VVFET [V] I [mA] VFET 240 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 33-4. Active supply current vs. VVFET, internal RC oscillator, 1MHz. 85°C 25°C -40°C 0.72 0.73 0.74 0.75 0.76 0.77 0.78 0.79 0.8 4 6 8 10 12 14 16 18 20 VVFET [V] I [mA] VFET 241 8042E–AVR–09/2013 ATmega16HVB/32HVB 33.1.2 Idle supply current characteristics Idle current consumption measurements with all bits in the PRR registers set and all I/O modules are turned off. Figure 33-5. Idle supply current vs. VVFET, internal RC oscillator, 8MHz. Figure 33-6. Idle supply current vs. VVFET, internal RC oscillator, 4MHz. 85°C 25°C -40°C 0.675 0.695 0.715 0.735 0.755 0.775 0.795 0.815 4 6 8 10 12 14 16 18 20 VVFET [V] I [mA] VFET 85°C 25°C -40°C 0.42 0.43 0.44 0.45 0.46 0.47 0.48 4 6 8 10 12 14 16 18 20 VVFET [V] I [mA] VFET 242 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 33-7. Idle supply current vs. VVFET, internal RC oscillator, 2MHz. Figure 33-8. Idle supply current vs. VVFET, internal RC oscillator, 1MHz. 85°C 25°C -40°C 0.28 0.284 0.288 0.292 0.296 0.3 0.304 0.308 4 6 8 10 12 14 16 18 20 VVFET [V] I [mA] VFET 85°C 25°C -40°C 0.205 0.209 0.213 0.217 0.221 0.225 4 6 8 10 12 14 16 18 20 VVFET [V] I [mA] VFET 243 8042E–AVR–09/2013 ATmega16HVB/32HVB 33.1.3 Power-save current characteristics Power-save current consumption with External Interrupt and SMBus connect/disconnect functionality enabled. The Watchdog Timer, CC-ADC, Current Battery Protection (CBP), VREF, and OC/OD are disabled. Figure 33-9. Power-save supply current vs. VVFET, external interrupt and SMBus enabled, all other modules disabled. Table 33-1 shows additional current consumption that needs to be added to the total power-budget when additional modules are enableds. Note: 1. Default I/O register configuration used. PPI and NNI connected to GND. 2. Measurements done with Fairchild FDS6690A N-Channel MOSFET. Figure 33-11 on page 245 shows Power-Save current consumption vs VFET with all modules listed in Table 33-1 enabled. The increased power consumption for low VFET voltage is caused by the NFET driver operation described in Section 25.3 ”Operation and usage” on page 146. Table 33-1. Typical additional I/O modules current consumption in power-save. I/O modules enabled Typical current consumption WDT VREF CBP (1) OC/OD (2) CC-ADC (TA = 25°C and VVFET = 12V) X 0.8µA X X 12µA XXXX 41µA XXXXX 85µA 85°C 25°C -40°C 17 19 21 23 25 27 29 31 33 35 4 6 8 10 12 14 16 18 20 VVFET [V] I [µA] VFET 244 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 33-10. Power-save supply current vs. VVFET, WDT, VREF, CBP, OC/OD, and CC-ADC enabled. 100 120 140 160 180 200 220 240 4 6 8 10 12 14 16 18 VFET [V] 85°C 25°C -40°C I [µA] VFET 245 8042E–AVR–09/2013 ATmega16HVB/32HVB 33.1.4 Power-off current characteristics Figure 33-11. Power-off supply current vs. VVFET. 33.2 NFET driver characteristics 33.2.1 OC/OD levels Figure 33-12. OC/OD pin voltage vs. VVFET . 85°C 25°C -40°C 0.6 0.8 1 1.2 1.4 1.6 1.8 4 6 8 10 12 14 16 18 20 VVFET [V] I [µA] VFET 85°C 25°C -40°C 6 8 10 12 14 16 18 VVFET [V] 10 15 20 25 30 35 Pin Voltage [V] 246 8042E–AVR–09/2013 ATmega16HVB/32HVB 33.2.2 OC/OD rise time from 0V to 2V gate-source voltage with 4.7nF load Figure 33-13. OC/OD rise time, VGS = 0V to 2V vs. VVFET . 33.2.3 OC/OD rise time from 2V to 4V gate-source voltage with 4.7nF load Figure 33-14. OC/OD rise time, VGS = 2V to 4V vs. VVFET . 0 200 400 600 800 1000 1200 1400 1600 1800 6 8 10 12 14 16 18 VFET [V] Time [µs] T =25°C T =70°C 0 200 400 600 800 1000 1200 1400 1600 6 8 10 12 14 16 18 VFET [V] Time [µs] T =25°C T =70°C 247 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 33-15. OC/OD drive capability vs temperature. 3 3.5 4 4.5 5 5.5 6 6.5 7 7.5 8 -10 10 30 50 70 90 Temperature [°C] Max Load [µA] VFET = 6V VFET = 9.5V VFET = 12V 248 8042E–AVR–09/2013 ATmega16HVB/32HVB 33.3 Battery protection characteristics Figure 33-16. Battery protection level. 33.4 Clock characteristics 33.4.1 Fast RC oscillator characteristics Figure 33-17. Fast RC oscillator frequency vs. temperature (after factory calibration). 10 60 110 160 210 260 310 [mV] Detection Level Max TYP(25°C) F3 F4 F5 F6 F7 F8 F9 FA FB FC FD 77 78 79 7A 7B 7C 7D 37 38 39 3A 3B 3C 3D 17 Min Register Value 7.75 7.8 7.85 7.9 7.95 8 8.05 8.1 -40 -30 -20 -10 0 10 20 30 40 50 60 70 80 90 Temperature [°C] [MHz] Frequency 249 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 33-18. Calibrated fast RC oscillator frequency vs. OSCCAL value. 33.4.2 Ultra low power RC oscillator characteristics Figure 33-19. ULP RC oscillator frequency vs. temperature. 25°C 16 14 12 10 8 6 4 0 16 32 48 64 80 96 112 128 144 160 176 192 208 224 240 256 OSCCAL VALUE FRC (MHz) 105 106 107 108 109 110 111 112 113 -40 -30 -20 -10 0 10 20 30 40 50 60 70 80 90 Temperature [°C] Frequency [kHz] 250 8042E–AVR–09/2013 ATmega16HVB/32HVB 33.4.3 Slow RC oscillator characteristics Figure 33-20. Slow RC oscillator frequency vs. temperature. Figure 33-21. Typical SlowRC frequency frequency prediction error based on algorithm in Section 9.2.2 on page 27. 127.0 128.0 129.0 130.0 131.0 132.0 133.0 134.0 Temperature [°C] Frequency [kHz] -40 -20 0 20 40 60 80 100 -0.4% -0.2% 0.0% 0.2% 0.4% 0.6% 0.8% 1.0% 1.2% 1.4% -40 -20 0 20 40 60 80 100 Temperature [°C] Frequency prediction error [%] 251 8042E–AVR–09/2013 ATmega16HVB/32HVB 33.5 Voltage reference characteristics Figure 33-22. Typical VREF curve with Atmel factory calibration at 25°C and 85°C. Figure 33-23. Typical VREF deviation curve with Atmel factory calibration at 25°C and 85°C. Temperature [°C] -40 -20 0 20 40 60 80 1.091 1.092 1.093 1.094 1.095 1.096 1.097 1.098 1.099 1.100 1.101 VREF [V] 252 8042E–AVR–09/2013 ATmega16HVB/32HVB 33.6 Voltage regulator characteristics Figure 33-24. Voltage regulator vs. VVFET, ILOAD = 10mA. Figure 33-25. Voltage regulator vs. VVFET, ILOAD = 20mA. 85°C 25°C -40°C 3.21 3.22 3.23 3.24 3.25 3.26 3.27 4 6 8 10 12 14 16 18 20 22 24 26 VVFET [V] VREG [V] 85°C 25°C -40°C 2.4 2.5 2.6 2.7 2.8 2.9 3 3.1 3.2 3.3 4 6 8 10 12 14 16 18 20 22 24 26 VVFET [V] VREG [V] 253 8042E–AVR–09/2013 ATmega16HVB/32HVB Figure 33-26. Voltage regulator short-circuit level at VVFET pin vs. temperature. Figure 33-27. BLOD level. 3.45 3.5 3.55 3.6 3.65 3.7 3.75 -40 -30 -20 -10 0 10 20 30 40 50 60 70 80 90 Temperature [°C] VRSCL [V] Rising Falling 2.637 2.639 2.641 2.643 2.645 2.647 2.649 2.651 2.653 2.655 2.657 2.659 2.661 -40 -30 -20 -10 0 10 20 30 40 50 60 70 80 90 Temperature [°C] VBLOD [V] 254 8042E–AVR–09/2013 ATmega16HVB/32HVB 33.7 BOD threshold characteristics Figure 33-28. BOD level. Falling Rising 2.82 2.84 2.86 2.88 2.9 2.92 2.94 2.96 2.98 3 -40 -30 -20 -10 0 10 20 30 40 50 60 70 80 90 Temperature [°C] VCC [V] 255 8042E–AVR–09/2013 ATmega16HVB/32HVB 34. Register summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page (0xFF) Reserved – – – – – – – – (0xFE) BPPLR – – – – – – BPPLE BPPL 137 (0xFD) BPCR – – EPID SCD DOCD COCD DHCD CHCD 138 (0xFC) BPHCTR – – HCPT[5:0] 140 (0xFB) BPOCTR – – OCPT[5:0] 139 (0xFA) BPSCTR – SCPT[6:0] 139 (0xF9) BPCHCD CHCDL[7:0] 142 (0xF8) BPDHCD DHCDL[7:0] 142 (0xF7) BPCOCD COCDL[7:0] 142 (0xF6) BPDOCD DOCDL[7:0] 141 (0xF5) BPSCD SCDL[7:0] 141 (0xF4) Reserved – – – – – – – – (0xF3) BPIFR – – – SCIF DOCIF COCIF DHCIF CHCIF 144 (0xF2) BPIMSK – – – SCIE DOCIE COCIE DHCIE CHCIE 143 (0xF1) CBCR – – – – CBE4 CBE3 CBE2 CBE1 152 (0xF0) FCSR – – – – DUVRD CPS DFE CFE 149 (0xEF) Reserved – – – – – – – – (0xEE) Reserved – – – – – – – – (0xED) Reserved – – – – – – – – (0xEC) Reserved – – – – – – – – (0xEB) Reserved – – – – – – – – (0xEA) CADRDC CADRDC[7:0] 115 (0xE9) CADRCC CADRCC[7:0] 114 (0xE8) CADCSRC - - - - - - - CADVSE 114 (0xE7) CADCSRB – CADACIE CADRCIE CADICIE – CADACIF CADRCIF CADICIF 112 (0xE6) CADCSRA CADEN CADPOL CADUB CADAS[1:0] CADSI[1:0] CADSE 111 (0xE5) CADICH CADIC[15:8] 114 (0xE4) CADICL CADIC[7:0] 114 (0xE3) CADAC3 CADAC[31:24] 114 (0xE2) CADAC2 CADAC[23:16] 114 (0xE1) CADAC1 CADAC[15:8] 114 (0xE0) CADAC0 CADAC[7:0] 114 (0xDF) Reserved – – – – – – – – (0xDE) Reserved – – – – – – – – (0xDD) Reserved – – – – – – – – (0xDC) Reserved – – – – – – – – (0xDB) Reserved – – – – – – – – (0xDA) Reserved – – – – – – – – (0xD9) Reserved – – – – – – – – (0xD8) Reserved – – – – – – – – (0xD7) Reserved – – – – – – – – (0xD6) Reserved – – – – – – – – (0xD5) Reserved – – – – – – – – (0xD4) CHGDCSR – – – BATTPVL CHGDISC1 CHGDISC1 CHGDIF CHGDIE 128 (0xD3) Reserved – – – – – – – – (0xD2) BGCSR – – BGD BGSCDE – – BGSCDIF BGSCDIE 125 (0xD1) BGCRR BGCR[7:0] 124 (0xD0) BGCCR – – BGCC[5:0] 255 (0xCF) Reserved – – – – – – – – (0xCE) Reserved – – – – – – – – (0xCD) Reserved – – – – – – – – (0xCC) Reserved – – – – – – – – (0xCB) Reserved – – – – – – – – (0xCA) Reserved – – – – – – – – (0xC9) Reserved – – – – – – – – (0xC8) ROCR ROCS – – ROCD – – ROCWIF ROCWIE 131 (0xC7) Reserved – – – – – – – – (0xC6) Reserved – – – – – – – – (0xC5) Reserved – – – – – – – – (0xC4) Reserved – – – – – – – – (0xC3) Reserved – – – – – – – – (0xC2) Reserved – – – – – – – – (0xC1) Reserved – – – – – – – – (0xC0) Reserved – – – – – – – – 256 8042E–AVR–09/2013 ATmega16HVB/32HVB (0xBF) Reserved – – – – – – – – (0xBE) TWBCSR TWBCIF TWBCIE – – – TWBDT1 TWBDT0 TWBCIP 184 (0xBD) TWAMR TWAM[6:0] – 184 (0xBC) TWCR TWINT TWEA TWSTA TWSTO TWWC TWEN – TWIE 181 (0xBB) TWDR 2–wire Serial Interface Data Register 183 (0xBA) TWAR TWA[6:0] TWGCE 183 (0xB9) TWSR TWS[7:3] – TWPS1 TWPS0 182 (0xB8) TWBR 2–wire Serial Interface Bit Rate Register 181 (0xB7) Reserved – – – – – – – (0xB6) Reserved – – – – – – – – (0xB5) Reserved – – – – – – – – (0xB4) Reserved – – – – – – – – (0xB3) Reserved – – – – – – – – (0xB2) Reserved – – – – – – – – (0xB1) Reserved – – – – – – – – (0xB0) Reserved – – – – – – – – (0xAF) Reserved – – – – – – – – (0xAE) Reserved – – – – – – – – (0xAD) Reserved – – – – – – – – (0xAC) Reserved – – – – – – – – (0xAB) Reserved – – – – – – – – (0xAA) Reserved – – – – – – – – (0xA9) Reserved – – – – – – – – (0xA8) Reserved – – – – – – – – (0xA7) Reserved – – – – – – – – (0xA6) Reserved – – – – – – – – (0xA5) Reserved – – – – – – – – (0xA4) Reserved – – – – – – – – (0xA3) Reserved – – – – – – – – (0xA2) Reserved – – – – – – – – (0xA1) Reserved – – – – – – – – (0xA0) Reserved – – – – – – – – (0x9F) Reserved – – – – – – – – (0x9E) Reserved – – – – – – – – (0x9D) Reserved – – – – – – – – (0x9C) Reserved – – – – – – – – (0x9B) Reserved – – – – – – – – (0x9A) Reserved – – – – – – – – (0x99) Reserved – – – – – – – – (0x98) Reserved – – – – – – – – (0x97) Reserved – – – – – – – – (0x96) Reserved – – – – – – – – (0x95) Reserved – – – – – – – – (0x94) Reserved – – – – – – – – (0x93) Reserved – – – – – – – – (0x92) Reserved – – – – – – – – (0x91) Reserved – – – – – – – – (0x90) Reserved – – – – – – – – (0x8F) Reserved – – – – – – – – (0x8E) Reserved – – – – – – – – (0x8D) Reserved – – – – – – – – (0x8C) Reserved – – – – – – – – (0x8B) Reserved – – – – – – – – (0x8A) Reserved – – – – – – – – (0x89) OCR1B Timer/Counter1 – Output Compare Register B 95 (0x88) OCR1A Timer/Counter1 – Output Compare Register A 95 (0x87) Reserved – – – – – – – – (0x86) Reserved – – – – – – – – (0x85) TCNT1H Timer/Counter1 (8 Bit) High Byte 95 (0x84) TCNT1L Timer/Counter1 (8 Bit) Low Byte 95 (0x83) Reserved – – – – – – – – (0x82) Reserved – – – – – – – – (0x81) TCCR1B – – – – – CS12 CS11 CS10 81 (0x80) TCCR1A TCW1 ICEN1 ICNC1 ICES1 ICS1 – – WGM10 94 (0x7F) Reserved – – – – – – – – (0x7E) DIDR0 – – – – – – PA1DID PA0DID 121 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page 257 8042E–AVR–09/2013 ATmega16HVB/32HVB (0x7D) Reserved – – – – – – – – (0x7C) VADMUX – – – – VADMUX[3:0] 119 (0x7B) Reserved – – – – – – – – (0x7A) VADCSR – – – – VADEN VADSC VADCCIF VADCCIE 119 (0x79) VADCH – – – – VADC Data Register High byte 120 (0x78) VADCL VADC Data Register Low byte 120 (0x77) Reserved – – – – – – – – (0x76) Reserved – – – – – – – – (0x75) Reserved – – – – – – – – (0x74) Reserved – – – – – – – – (0x73) Reserved – – – – – – – – (0x72) Reserved – – – – – – – – (0x71) Reserved – – – – – – – – (0x70) Reserved – – – – – – – – (0x6F) TIMSK1 – – – – ICIE1 OCIE1B OCIE1A TOIE1 96 (0x6E) TIMSK0 – – – – ICIE0 OCIE0B OCIE0A TOIE0 96 (0x6D) Reserved – – – – – – – – (0x6C) PCMSK1 PCINT[15:8] 60 (0x6B) PCMSK0 – – – – PCINT[3:0] 61 (0x6A) Reserved – – – – – – – – (0x69) EICRA ISC31 ISC30 ISC21 ISC20 ISC11 ISC10 ISC01 ISC00 58 (0x68) PCICR – – – – – – PCIE1 PCIE0 60 (0x67) Reserved – – – – – – – – (0x66) FOSCCAL Fast Oscillator Calibration Register 32 (0x65) Reserved – – – – – – – – (0x64) PRR0 – PRTWI PRVRM – PRSPI PRTIM1 PRTIM0 PRVADC 40 (0x63) Reserved – – – – – – – – (0x62) Reserved – – – – – – – – (0x61) CLKPR CLKPCE – – – – – CLKPS1 CLKPS0 32 (0x60) WDTCSR WDIF WDIE WDP3 WDCE WDE WDP2 WDP1 WDP0 49 0x3F (0x5F) SREG I T H S V N Z C 10 0x3E (0x5E) SPH SP15 SP14 SP13 SP12 SP11 SP10 SP9 SP8 13 0x3D (0x5D) SPL SP7 SP6 SP5 SP4 SP3 SP2 SP1 SP0 13 0x3C (0x5C) Reserved – – – – – – – – 0x3B (0x5B) Reserved – – – – – – – – 0x3A (0x5A) Reserved – – – – – – – – 0x39 (0x59) Reserved – – – – – – – – 0x38 (0x58) Reserved – – – – – – – – 0x37 (0x57) SPMCSR SPMIE RWWSB SIGRD CTPB RFLB PGWRT PGERS SPMEN 202 0x36 (0x56) Reserved – – – – – – – – 0x35 (0x55) MCUCR – – CKOE PUD – – IVSEL IVCE 78/32 0x34 (0x54) MCUSR – – – OCDRF WDRF BODRF EXTRF PORF 49 0x33 (0x53) SMCR – – – – SM[2:0] SE 39 0x32 (0x52) Reserved – – – – – – – – 0x31 (0x51) DWDR debugWIRE Data Register 187 0x30 (0x50) Reserved – – – – – – – – 0x2F (0x4F) Reserved – – – – – – – – 0x2E (0x4E) SPDR SPI Data Register 107 0x2D (0x4D) SPSR SPIF WCOL – – – – – SPI2X 106 0x2C (0x4C) SPCR SPIE SPE DORD MSTR CPOL CPHA SPR1 SPR0 105 0x2B (0x4B) GPIOR2 General Purpose I/O Register 2 24 0x2A (0x4A) GPIOR1 General Purpose I/O Register 1 24 0x29 (0x49) OCR0B Timer/Counter0 Output Compare Register B 95 0x28 (0x48) OCR0A Timer/Counter0 Output Compare Register A 95 0x27 (0x47) TCNT0H Timer/Counter0 (8 Bit) High Byte 95 0x26 (0x46) TCNT0L Timer/Counter0 (8 Bit) Low Byte 95 0x25 (0x45) TCCR0B – – – – – CS02 CS01 CS00 81 0x24 (0x44) TCCR0A TCW0 ICEN0 ICNC0 ICES0 ICS0 – – WGM00 94 0x23 (0x43) GTCCR TSM – – – – – – PSRSYNC 0x22 (0x42) EEARH – – – – – – EEPROM High byte 20 0x21 (0x41) EEARL EEPROM Address Register Low Byte 20 0x20 (0x40) EEDR EEPROM Data Register 20 0x1F (0x3F) EECR – – EEPM1 EEPM0 EERIE EEMPE EEPE EERE 21 0x1E (0x3E) GPIOR0 General Purpose I/O Register 0 24 0x1D (0x3D) EIMSK – – – – INT3 INT2 INT1 INT0 59 0x1C (0x3C) EIFR – – – – INTF3 INTF2 INTF1 INTF0 59 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page 258 8042E–AVR–09/2013 ATmega16HVB/32HVB Notes: 1. For compatibility with future devices, reserved bits should be written to zero if accessed. Reserved I/O memory addresses should never be written. 2. I/O registers within the address range $00 - $1F are directly bit-accessible using the SBI and CBI instructions. In these registers, the value of single bits can be checked by using the SBIS and SBIC instructions. 3. Some of the status flags are cleared by writing a logical one to them. Note that the CBI and SBI instructions will operate on all bits in the I/O register, writing a one back into any flag read as set, thus clearing the flag. The CBI and SBI instructions work with registers 0x00 to 0x1F only. 4. When using the I/O specific commands IN and OUT, the I/O addresses $00 - $3F must be used. When addressing I/O registers as data space using LD and ST instructions, $20 must be added to these addresses. The Atmel ATmega16HVB/32HVB is a complex microcontroller with more peripheral units than can be supported within the 64 location reserved in Opcode for the IN and OUT instructions. For the Extended I/O space from $60 - $FF in SRAM, only the ST/STS/STD and LD/LDS/LDD instructions can be used. 0x1B (0x3B) PCIFR – – – – – – PCIF1 PCIF0 60 0x1A (0x3A) Reserved – – – – – – – – 0x19 (0x39) Reserved – – – – – – – – 0x18 (0x38) Reserved – – – – – – – – 0x17 (0x37) OSICSR – – – OSISEL0 – – OSIST OSIEN 33 0x16 (0x36) TIFR1 – – – – ICF1 OCF1B OCF1A TOV1 96 0x15 (0x35) TIFR0 – – – – ICF0 OCF0B OCF0A TOV0 96 0x14 (0x34) Reserved – – – – – – – – 0x13 (0x33) Reserved – – – – – – – – 0x12 (0x32) Reserved – – – – – – – – 0x11 (0x31) Reserved – – – – – – – – 0x10 (0x30) Reserved – – – – – – – – 0x0F (0x2F) Reserved – – – – – – – – 0x0E (0x2E) Reserved – – – – – – – – 0x0D (0x2D) Reserved – – – – – – – – 0x0C (0x2C) Reserved – – – – – – – – 0x0B (0x2B) Reserved – – – – – – – – 0x0A (0x2A) Reserved – – – – – – – – 0x09 (0x29) Reserved – – – – – – – – 0x08 (0x28) PORTC – – PORTC5 PORTC4 PORTC3 PORTC2 PORTC1 PORTC0 66 0x07 (0x27) Reserved – – – – – – – – 0x06 (0x26) PINC – – – PINC4 PINC3 PINC2 PINC1 PINC0 66 0x05 (0x25) PORTB PORTB7 PORTB6 PORTB5 PORTB4 PORTB3 PORTB2 PORTB1 PORTB0 78 0x04 (0x24) DDRB DDB7 DDB6 DDB5 DDB4 DDB3 DDB2 DDB1 DDB0 78 0x03 (0x23) PINB PINB7 PINB6 PINB5 PINB4 PINB3 PINB2 PINB1 PINB0 78 0x02 (0x22) PORTA – – – – PORTA3 PORTA2 PORTA1 PORTA0 78 0x01 (0x21) DDRA – – – – DDA3 DDA2 DDA1 DDA0 78 0x00 (0x20) PINA – – – – PINA3 PINA2 PINA1 PINA0 78 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page 259 8042E–AVR–09/2013 ATmega16HVB/32HVB 35. Instruction set summary Mnemonics Operands Description Operation Flags #Clocks ARITHMETIC AND LOGIC INSTRUCTIONS ADD Rd, Rr Add two Registers Rd  Rd + Rr Z, C, N, V, H 1 ADC Rd, Rr Add with Carry two Registers Rd  Rd + Rr + C Z, C, N, V, H 1 ADIW Rdl, K Add Immediate to Word Rdh:Rdl  Rdh:Rdl + K Z, C, N, V, S 2 SUB Rd, Rr Subtract two Registers Rd  Rd - Rr Z, C, N, V, H 1 SUBI Rd, K Subtract Constant from Register Rd  Rd - K Z, C, N, V, H 1 SBC Rd, Rr Subtract with Carry two Registers Rd  Rd - Rr - C Z, C, N, V, H 1 SBCI Rd, K Subtract with Carry Constant from Reg. Rd  Rd - K - C Z, C, N, V, H 1 SBIW Rdl,K Subtract Immediate from Word Rdh:Rdl  Rdh:Rdl - K Z, C, N, V, S 2 AND Rd, Rr Logical AND Registers Rd Rd  Rr Z, N, V 1 ANDI Rd, K Logical AND Register and Constant Rd  Rd K Z, N, V 1 OR Rd, Rr Logical OR Registers Rd  Rd v Rr Z, N, V 1 ORI Rd, K Logical OR Register and Constant Rd Rd v K Z, N, V 1 EOR Rd, Rr Exclusive OR Registers Rd  Rd  Rr Z, N, V 1 COM Rd One’s Complement Rd  0xFF  Rd Z, C, N, V 1 NEG Rd Two’s Complement Rd  0x00  Rd Z, C, N, V, H 1 SBR Rd, K Set Bit(s) in Register Rd  Rd v K Z, N, V 1 CBR Rd, K Clear Bit(s) in Register Rd  Rd  (0xFF - K) Z, N, V 1 INC Rd Increment Rd  Rd + 1 Z, N, V 1 DEC Rd Decrement Rd  Rd  1 Z, N, V 1 TST Rd Test for Zero or Minus Rd  Rd  Rd Z, N, V 1 CLR Rd Clear Register Rd  Rd  Rd Z, N ,V 1 SER Rd Set Register Rd  0xFF None 1 MUL Rd, Rr Multiply Unsigned R1:R0  Rd x Rr Z, C 2 MULS Rd, Rr Multiply Signed R1:R0  Rd x Rr Z, C 2 MULSU Rd, Rr Multiply Signed with Unsigned R1:R0  Rd x Rr Z, C 2 FMUL Rd, Rr Fractional Multiply Unsigned R1:R0  (Rd x Rr) << 1 Z, C 2 FMULS Rd, Rr Fractional Multiply Signed R1:R0  (Rd x Rr) << 1 Z, C 2 FMULSU Rd, Rr Fractional Multiply Signed with Unsigned R1:R0  (Rd x Rr) << 1 Z, C 2 BRANCH INSTRUCTIONS RJMP k Relative Jump PC PC + k + 1 None 2 IJMP Indirect Jump to (Z) PC  Z None 2 JMP k Direct Jump PC k None 3 RCALL k Relative Subroutine Call PC  PC + k + 1 None 3 ICALL Indirect Call to (Z) PC  Z None 3 CALL k Direct Subroutine Call PC  k None 4 RET Subroutine Return PC  STACK None 4 RETI Interrupt Return PC  STACK I 4 CPSE Rd, Rr Compare, Skip if Equal if (Rd = Rr) PC PC + 2 or 3 None 1/2/3 CP Rd, Rr Compare Rd  Rr Z, N, V, C, H 1 CPC Rd, Rr Compare with Carry Rd  Rr  C Z, N, V, C, H 1 CPI Rd, K Compare Register with Immediate Rd  K Z, N, V, C, H 1 SBRC Rr, b Skip if Bit in Register Cleared if (Rr(b) = 0) PC  PC + 2 or 3 None 1/2/3 SBRS Rr, b Skip if Bit in Register is Set if (Rr(b) = 1) PC  PC + 2 or 3 None 1/2/3 SBIC P, b Skip if Bit in I/O Register Cleared if (P(b) = 0) PC  PC + 2 or 3 None 1/2/3 SBIS P, b Skip if Bit in I/O Register is Set if (P(b) = 1) PC  PC + 2 or 3 None 1/2/3 BRBS s, k Branch if Status Flag Set if (SREG(s) = 1) then PCPC+k + 1 None 1/2 BRBC s, k Branch if Status Flag Cleared if (SREG(s) = 0) then PCPC+k + 1 None 1/2 BREQ k Branch if Equal if (Z = 1) then PC  PC + k + 1 None 1/2 BRNE k Branch if Not Equal if (Z = 0) then PC  PC + k + 1 None 1/2 BRCS k Branch if Carry Set if (C = 1) then PC  PC + k + 1 None 1/2 BRCC k Branch if Carry Cleared if (C = 0) then PC  PC + k + 1 None 1/2 BRSH k Branch if Same or Higher if (C = 0) then PC  PC + k + 1 None 1/2 BRLO k Branch if Lower if (C = 1) then PC  PC + k + 1 None 1/2 BRMI k Branch if Minus if (N = 1) then PC  PC + k + 1 None 1/2 BRPL k Branch if Plus if (N = 0) then PC  PC + k + 1 None 1/2 BRGE k Branch if Greater or Equal, Signed if (N  V= 0) then PC  PC + k + 1 None 1/2 BRLT k Branch if Less Than Zero, Signed if (N  V= 1) then PC  PC + k + 1 None 1/2 BRHS k Branch if Half Carry Flag Set if (H = 1) then PC  PC + k + 1 None 1/2 BRHC k Branch if Half Carry Flag Cleared if (H = 0) then PC  PC + k + 1 None 1/2 BRTS k Branch if T Flag Set if (T = 1) then PC  PC + k + 1 None 1/2 BRTC k Branch if T Flag Cleared if (T = 0) then PC  PC + k + 1 None 1/2 BRVS k Branch if Overflow Flag is Set if (V = 1) then PC  PC + k + 1 None 1/2 BRVC k Branch if Overflow Flag is Cleared if (V = 0) then PC  PC + k + 1 None 1/2 260 8042E–AVR–09/2013 ATmega16HVB/32HVB BRIE k Branch if Interrupt Enabled if ( I = 1) then PC  PC + k + 1 None 1/2 BRID k Branch if Interrupt Disabled if ( I = 0) then PC  PC + k + 1 None 1/2 BIT AND BIT-TEST INSTRUCTIONS SBI P, b Set Bit in I/O Register I/O(P,b)  1 None 2 CBI P, b Clear Bit in I/O Register I/O(P,b)  0 None 2 LSL Rd Logical Shift Left Rd(n+1)  Rd(n), Rd(0)  0 Z, C, N, V 1 LSR Rd Logical Shift Right Rd(n)  Rd(n+1), Rd(7)  0 Z, C, N, V 1 ROL Rd Rotate Left Through Carry Rd(0)C,Rd(n+1) Rd(n),CRd(7) Z, C, N, V 1 ROR Rd Rotate Right Through Carry Rd(7)C,Rd(n) Rd(n+1),CRd(0) Z, C, N, V 1 ASR Rd Arithmetic Shift Right Rd(n)  Rd(n+1), n=0..6 Z, C, N, V 1 SWAP Rd Swap Nibbles Rd(3..0)Rd(7..4),Rd(7..4)Rd(3..0) None 1 BSET s Flag Set SREG(s)  1 SREG(s) 1 BCLR s Flag Clear SREG(s)  0 SREG(s) 1 BST Rr, b Bit Store from Register to T T  Rr(b) T 1 BLD Rd, b Bit load from T to Register Rd(b)  T None 1 SEC Set Carry C  1 C1 CLC Clear Carry C  0 C 1 SEN Set Negative Flag N  1 N1 CLN Clear Negative Flag N  0 N 1 SEZ Set Zero Flag Z  1 Z1 CLZ Clear Zero Flag Z  0 Z 1 SEI Global Interrupt Enable I  1 I1 CLI Global Interrupt Disable I 0 I 1 SES Set Signed Test Flag S  1 S1 CLS Clear Signed Test Flag S  0 S 1 SEV Set Twos Complement Overflow. V  1 V1 CLV Clear Twos Complement Overflow V  0 V 1 SET Set T in SREG T  1 T1 CLT Clear T in SREG T  0 T 1 SEH Set Half Carry Flag in SREG H  1 H1 CLH Clear Half Carry Flag in SREG H  0 H 1 DATA TRANSFER INSTRUCTIONS MOV Rd, Rr Move Between Registers Rd  Rr None 1 MOVW Rd, Rr Copy Register Word Rd+1:Rd  Rr+1:Rr None 1 LDI Rd, K Load Immediate Rd  K None 1 LD Rd, X Load Indirect Rd  (X) None 2 LD Rd, X+ Load Indirect and Post-Inc. Rd  (X), X  X + 1 None 2 LD Rd, - X Load Indirect and Pre-Dec. X  X - 1, Rd  (X) None 2 LD Rd, Y Load Indirect Rd  (Y) None 2 LD Rd, Y+ Load Indirect and Post-Inc. Rd  (Y), Y  Y + 1 None 2 LD Rd, - Y Load Indirect and Pre-Dec. Y  Y - 1, Rd  (Y) None 2 LDD Rd, Y+q Load Indirect with Displacement Rd  (Y + q) None 2 LD Rd, Z Load Indirect Rd  (Z) None 2 LD Rd, Z+ Load Indirect and Post-Inc. Rd  (Z), Z  Z+1 None 2 LD Rd, -Z Load Indirect and Pre-Dec. Z  Z - 1, Rd  (Z) None 2 LDD Rd, Z+q Load Indirect with Displacement Rd  (Z + q) None 2 LDS Rd, k Load Direct from SRAM Rd  (k) None 2 ST X, Rr Store Indirect (X) Rr None 2 ST X+, Rr Store Indirect and Post-Inc. (X) Rr, X  X + 1 None 2 ST - X, Rr Store Indirect and Pre-Dec. X  X - 1, (X)  Rr None 2 ST Y, Rr Store Indirect (Y)  Rr None 2 ST Y+, Rr Store Indirect and Post-Inc. (Y)  Rr, Y  Y + 1 None 2 ST - Y, Rr Store Indirect and Pre-Dec. Y  Y - 1, (Y)  Rr None 2 STD Y+q, Rr Store Indirect with Displacement (Y + q)  Rr None 2 ST Z, Rr Store Indirect (Z)  Rr None 2 ST Z+, Rr Store Indirect and Post-Inc. (Z)  Rr, Z  Z + 1 None 2 ST -Z, Rr Store Indirect and Pre-Dec. Z  Z - 1, (Z)  Rr None 2 STD Z+q, Rr Store Indirect with Displacement (Z + q)  Rr None 2 STS k, Rr Store Direct to SRAM (k)  Rr None 2 LPM Load Program Memory R0  (Z) None 3 LPM Rd, Z Load Program Memory Rd  (Z) None 3 LPM Rd, Z+ Load Program Memory and Post-Inc Rd  (Z), Z  Z+1 None 3 SPM Store Program Memory (Z)  R1:R0 None - IN Rd, P In Port Rd  P None 1 35. Instruction set summary (Continued) Mnemonics Operands Description Operation Flags #Clocks 261 8042E–AVR–09/2013 ATmega16HVB/32HVB OUT P, Rr Out Port P  Rr None 1 PUSH Rr Push Register on Stack STACK  Rr None 2 POP Rd Pop Register from Stack Rd  STACK None 2 MCU CONTROL INSTRUCTIONS NOP No Operation None 1 SLEEP Sleep (see specific descr. for Sleep function) None 1 WDR Watchdog Reset (see specific descr. for WDR/timer) None 1 BREAK Break For On-chip Debug Only None N/A 35. Instruction set summary (Continued) Mnemonics Operands Description Operation Flags #Clocks 262 8042E–AVR–09/2013 ATmega16HVB/32HVB 36. Ordering information 36.1 The Atmel ATmega16HVB Speed (MHz) Power supply Ordering code Package Operation range 1MHz - 8MHz 4V - 18V ATMEGA16HVB-8X3 44X1 -40C to 85C Package type 44X1 44-lead, 4.4mm body width, plastic thin shrink small outline package (TSSOP) 263 8042E–AVR–09/2013 ATmega16HVB/32HVB 36.2 The Atmel ATmega32HVB Speed (MHz) Power supply Ordering code Package Operation range 1MHz - 8MHz 4V - 18V ATMEGA32HVB-8X3 44X1 -40C to 85C Package type 44X1 44-lead, 4.4mm body width, plastic thin shrink small outline package (TSSOP) 264 8042E–AVR–09/2013 ATmega16HVB/32HVB 37. Packaging information 37.1 44X1 TITLE DRAWING NO. R REV. Note: These drawings are for general information only. Refer to JEDEC Drawing MO-153BE. 2325 Orchard Parkway San Jose, CA 95131 5/16/07 44X1, 44-lead, 4.4 mm Body Width, Plastic Thin Shrink Small Outline Package (TSSOP) 44X1 A COMMON DIMENSIONS (Unit of Measure = mm) SYMBOL MIN NOM MAX NOTE A – – 1.20 A1 0.05 – b 0.17 – 0.27 C 0.09 – 0.20 D 10.90 11.00 11.10 E1 4.30 4.40 4.50 E 6.20 6.40 6.60 e 0.50 TYP L 0.50 0.60 0.70 Ø 0o – 8o Side View Top View End View Ø 1 44 3 2 L C E1 E D e b A A1 0.15 TITLE DRAWING NO. R REV. Note: These drawings are for general information only. Refer to JEDEC Drawing MO-153BE. 2325 Orchard Parkway San Jose, CA 95131 5/16/07 44X1, 44-lead, 4.4mm Body Width, Plastic Thin Shrink Small Outline Package (TSSOP) 44X1 A COMMON DIMENSIONS (Unit of Measure = mm) SYMBOL MIN NOM MAX NOTE A – – 1.20 A1 0.05 – 0.15 b 0.17 – 0.27 C 0.09 – 0.20 D 10.90 11.00 11.10 E1 4.30 4.40 4.50 E 6.20 6.40 6.60 e 0.50 TYP L 0.50 0.60 0.70 Ø 0o – 8o Side View Top View End View Ø 1 44 3 2 L C E1 E D e b A A1 265 8042E–AVR–09/2013 ATmega16HVB/32HVB 38. Errata 38.1 The Atmel ATmega16HVB 38.1.1 Rev. E TWI bus can get stuck if TWI STOP condition bit is set in slave mode If the TWSTO bit in TWCR is set while the TWI starts to receive data in slave mode, it can result in pulling the SCL pin low and then the TWI bus will get stuck. To release the SCL pin and get out of this situation the TWI module needs to be disabled and then re-enabled. Problem fix/workaround While in slave mode the TWSTO bit should be written only to recover from an error condition and then cleared before a data transfer starts. 38.1.2 Rev. D Not sampled. 38.1.3 Rev. C TWI bus can get stuck if TWI STOP condition bit is set in slave mode If the TWSTO bit in TWCR is set while the TWI starts to receive data in slave mode, it can result in pulling the SCL pin low and then the TWI bus will get stuck. To release the SCL pin and get out of this situation the TWI module needs to be disabled and then re-enabled. Problem fix/workaround While in slave mode the TWSTO bit should be written only to recover from an error condition and then cleared before a data transfer starts. 38.1.4 Rev. B Stack pointer initial value The stack pointer in ATmega16HVB is incorrectly initialized to 0x08ff instead of 0x04ff. Problem fix/workaround Initialize the stack pointer in software before the stack is used. Most C-compilers does initialize the stack pointer without manual intervention. Assembly Code Example: ldi r16,high(RAMEND); Main program start out SPH,r16 ; Set Stack Pointer to top of RAM ldi r16,low(RAMEND) out SPL,r16 C Code Example (if required): SP = RAMEND; TWI bus can get stuck if TWI STOP condition bit is set in slave mode If the TWSTO bit in TWCR is set while the TWI starts to receive data in slave mode, it can result in pulling the SCL pin low and then the TWI bus will get stuck. To release the SCL pin and get out of this situation the TWI module needs to be disabled and then re-enabled. Problem fix/workaround While in slave mode the TWSTO bit should be written only to recover from an error condition and then cleared before a data transfer starts. 38.1.5 Rev. A Not sampled. 266 8042E–AVR–09/2013 ATmega16HVB/32HVB 38.2 The Atmel ATmega32HVB 38.2.1 Rev. E TWI bus can get stuck if TWI STOP condition bit is set in slave mode If the TWSTO bit in TWCR is set while the TWI starts to receive data in slave mode, it can result in pulling the SCL pin low and then the TWI bus will get stuck. To release the SCL pin and get out of this situation the TWI module needs to be disabled and then re-enabled. Problem fix/workaround While in slave mode the TWSTO bit should be written only to recover from an error condition and then cleared before a data transfer starts. 38.2.2 Rev. D Not sampled. 38.2.3 Rev. C TWI bus can get stuck if TWI STOP condition bit is set in slave mode If the TWSTO bit in TWCR is set while the TWI starts to receive data in slave mode, it can result in pulling the SCL pin low and then the TWI bus will get stuck. To release the SCL pin and get out of this situation the TWI module needs to be disabled and then re-enabled. Problem fix/workaround While in slave mode the TWSTO bit should be written only to recover from an error condition and then cleared before a data transfer starts. 38.2.4 Rev. B TWI bus can get stuck if TWI STOP condition bit is set in slave mode If the TWSTO bit in TWCR is set while the TWI starts to receive data in slave mode, it can result in pulling the SCL pin low and then the TWI bus will get stuck. To release the SCL pin and get out of this situation the TWI module needs to be disabled and then re-enabled. Problem fix/workaround While in slave mode the TWSTO bit should be written only to recover from an error condition and then cleared before a data transfer starts. 38.2.5 Rev. A Not sampled. 267 8042E–AVR–09/2013 ATmega16HVB/32HVB 39. Revision history Please note that the referring page numbers in this section are referring to this document. The referring revision in this section are referring to the document revision. 39.1 Rev. 8042E-09/2013 39.2 Rev. 8042D-10/2011 1. Updated ”Errata” on page 265: ATmega16HVB: Added errata sections for “Rev. C” , “Rev. D” and “Rev. E” . ATmega32HVB: Added errata sections for “Rev. B” , “Rev. C” , “Rev. D” and “Rev. E” . 1. Operating voltage has been changed from 4V - 25V to 4V - 18V 2. The methods for determing the actual clock period of the ULP Oscillator i Section 9.2.3 on page 27 have been changed 3. In ”Bit 1:0 – CLKPS[1:0]: Clock Prescaler select Bit[1:0]” on page 33 new text has been inserted in and the text “If CKDIBV8 is programmed” has been corrected to “If CKDIV8 is programmed” 4. Note 2 in ”Bit 0 – OSIEN: Oscillator sampling interface enable” on page 34 has been deleted 5. Figure 11-1 on page 43 has been corrected 6. New Note 2 has been added below Table 11-2 on page 51 7. The last sentence in Section 21.5 on page 123 has been corrected 8. The text in Section 25.3.1 on page 146 below Figure 25-2 has been corrected several places 9. VCC in Figure 28-1 on page 186 has been corrected 10. Bit no 4 in Table 30-3 on page 205 has been corrected 11. Note 1 below Table 30-3 on page 205 has been corrected 12. The text in point 4 and 5 in Section 30.6.1 on page 208 has been corrected 13. The VFET value in Figure 30-3 on page 212 has been corrected 14. The table in Section 32.1 on page 225 hase been updated with several new values 15. ILOAD in Table 32-2 on page 226 has been added 16. Note 1 below Table 32-2 on page 226 has been added 17. The maximum value for VBOT in Table 32-3 on page 227 has been added 18. In Table 32-4 on page 227 the maximum value for VRSCL has been corrected and the maximum value for VREG pin has been added 19. In Table 32-7 on page 229 the typical and maximum values for INL has been corrected 20. In Table 32-8 on page 229 the typical value for frequency prediction error (slow RC oscillator) has been corrected 21. In Table 32-10 on page 230 the text below “Parameter” has been corrected 22. In Table 32-12 on page 231 Note 5 has been added 268 8042E–AVR–09/2013 ATmega16HVB/32HVB 39.3 Rev. 8042C-06/2011 23. In Table 32-18 on page 236 the maximum value for tWLRH_CE has been corrected 24. The former figure “Active supply current vs. VVFET, WDT, VREF, CBP, OC/OD and CC-ADC enabled” on page 238 has been removed 25. In Table 33-1 on page 243 the text “CC-OD” has benn changed to “OC-OD” and below “Typical current consumption” the value “55µA” has been changed to “85µA” 26. New text is added below the two notes for Table 33-1 on page 243 27. New Figure 33-11 on page 245 “Power-save supply current vs. VVFET, WDT, VREF, CBP, OC/OD, and CC-ADC enabled” is added 28. The plot in Figure 33-13 on page 246 has been updated 29. The plot in Figure 33-14 on page 246 has been updated 30. New Figure 33-15 on page 247 has been added 31. New Figure 33-21 on page 250 has been added 32. Heading in Figure 33-27 on page 253 has been corrected 33. The power supply voltage in the table in Section 36.1 on page 262 has been corrected 34. The power supply voltage in the table in Section 36.2 on page 263 has been corrected 35. The Section 38. on page 265 has been corrected by adding an errata for “all revisions” 36. The text “...clock period of the Slow RC Oscillator...” in point 2 in Section 9.2.3 on page 27 has been corrected to “...clock period of the ULP RC Oscillator...” 37. Note 1 below Table 19-1 on page 112 has been corrected 38. Note 1 below Table 19-2 on page 112 has been corrected 39. Figure 31-1 on page 220 has been updated 40. Figure 31-2 on page 221 has been updated 41. Figure 31-3 on page 222 has been updated 42. Table 31-1 on page 223 has been updated according to the changes in Figure 31-1 on page 220, Figure 31-2 on page 221, and Figure 31-3 on page 222 1. The columns “Minimum” and “Maximum” in Table 24-5 on page 142 are deleted 2. A new row (“Device lot ID and position”) in Table 29-3 on page 196 is added 3. A new note (“Note 16”) in Table 29-3 on page 196 is added 4. In ”Absolute maximum ratings*” on page 225 the following values have been changed: “Voltage on OC and OD with respect to ground”, “Voltage on PC5, BATT, PVT, VFET, PV4, PV3, and PV2 with respect to ground”, and “Maximum operating voltage on VFET” 5. In Table 32-1 on page 225 the values for “Typical” and “Maximum” in the row “VFET = 16V, WDT, CC-ADC, OC, OD, and battery protection enabled, DUVR mode disabled” are added 6. “Frequency drift” for “Slow RC oscillator” in Table 32-8 on page 229 is deleted 7. A new note (“Note 4”) in Table 32-8 on page 229 is added 8. Table 32-10 on page 230 is updated and corrected 269 8042E–AVR–09/2013 ATmega16HVB/32HVB 39.4 Rev. 8042B-06/2010 39.5 Rev. 8042A-08/2009 9. The text “CEQ = 4.7nF, VFET = 16V” is added to “Condition” for tf ,OC and tf ,OD in Table 32-2 on page 226 10. New Figure 33-1 on page 238 is added 11. Corrected formula in Table 32-15 on page 232 12. Corrected and added some short-cuts in addition to general update and some minor corrections in text 1. Removed direction arrow in Figure 17-1 on page 82. 2. Updated ”Configuring PA1 and PA0 for V-ADC operation” on page 117. 3. Updated ”Operating circuit” on page 220, with correct naming convention for thermistors RT32 and RT33. 1. Initial revision 270 8042E–AVR–09/2013 ATmega16HVB/32HVB 1 8042E–AVR–09/2013 ATmega16HVB/32HVB Table of Contents Features ..................................................................................................... 1 1 Pin configurations .................................................................................... 2 1.1TSSOP ......................................................................................................................2 1.2Pin descriptions .........................................................................................................3 2 Overview ................................................................................................... 5 2.1Comparison between the Atmel ATmega16HVB and the Atmel ATmega32HVB .....7 3 Disclaimer ................................................................................................. 8 4 Resources ................................................................................................. 8 5 About code examples .............................................................................. 8 6 Data retention ........................................................................................... 8 7 AVR CPU core .......................................................................................... 9 7.1Overview ....................................................................................................................9 7.2ALU – Arithmetic Logic Unit .....................................................................................10 7.3Status Register ........................................................................................................10 7.4General purpose Register File .................................................................................12 7.5Stack Pointer ...........................................................................................................13 7.6Instruction execution timing .....................................................................................14 7.7Reset and interrupt handling ...................................................................................14 8 AVR memories ........................................................................................ 17 8.1Overview ..................................................................................................................17 8.2In-system reprogrammable flash program memory .................................................17 8.3SRAM data memory ................................................................................................17 8.4EEPROM data memory ...........................................................................................19 8.5I/O memory ..............................................................................................................19 8.6Register description .................................................................................................20 9 System clock and clock options ........................................................... 25 9.1Clock systems and their distribution ........................................................................25 9.2Clock sources ..........................................................................................................26 9.3Clock startup sequence ...........................................................................................28 9.4Clock output .............................................................................................................28 9.5System clock prescaler ............................................................................................28 2 8042E–AVR–09/2013 ATmega16HVB/32HVB 9.6VADC clock prescaler ..............................................................................................29 9.7OSI – Oscillator sampling interface .........................................................................29 9.8Register description .................................................................................................32 10 Power management and sleep modes ................................................. 35 10.1Sleep modes ..........................................................................................................35 10.2Idle mode ...............................................................................................................37 10.3ADC noise reduction ..............................................................................................37 10.4Power-save mode ..................................................................................................37 10.5Power-off mode .....................................................................................................38 10.6Power Reduction Register .....................................................................................38 10.7Minimizing power consumption .............................................................................38 10.8Register description ...............................................................................................39 11 System control and reset ...................................................................... 42 11.1Resetting the AVR .................................................................................................42 11.2Reset sources ........................................................................................................42 11.3Reset and the voltage reference ...........................................................................45 11.4Watchdog timer .....................................................................................................46 11.5Register description ...............................................................................................49 12 Interrupts ................................................................................................ 52 12.1Overview ................................................................................................................52 12.2Interrupt vectors in Atmel ATmega16HVB/32HVB ................................................52 12.3Moving interrupts between application and boot space .........................................56 12.4Register description ...............................................................................................56 13 External interrupts ................................................................................. 58 13.1Overview ................................................................................................................58 13.2Register description ...............................................................................................58 14 High voltage I/O ports ............................................................................ 62 14.1Overview ................................................................................................................62 14.2High voltage ports as general digital I/O ................................................................63 14.3Overview ................................................................................................................64 14.4Alternate port functions ..........................................................................................64 14.5Register description ...............................................................................................66 15 Low voltage I/O-Ports ............................................................................ 67 15.1Overview ................................................................................................................67 3 8042E–AVR–09/2013 ATmega16HVB/32HVB 15.2Low voltage ports as general digital I/O ................................................................68 15.3Alternate port functions ..........................................................................................72 15.4Register description ...............................................................................................78 16 Timer/Counter0 and Timer/Counter1 prescalers ................................. 79 16.1Overview ................................................................................................................79 16.2External clock source ............................................................................................80 16.3Register description ...............................................................................................81 17 Timer/Counter (T/C0,T/C1) ..................................................................... 82 17.1Features ................................................................................................................82 17.2Overview ................................................................................................................82 17.3Timer/Counter clock sources .................................................................................83 17.4Counter unit ...........................................................................................................83 17.5Modes of operation ................................................................................................84 17.6Input capture unit ...................................................................................................86 17.7Output compare unit ..............................................................................................88 17.8Timer/counter timing diagrams ..............................................................................89 17.9Accessing registers in 16-bit mode ........................................................................90 17.10Register description .............................................................................................94 18 SPI – Serial Peripheral Interface ........................................................... 98 18.1Features ................................................................................................................98 18.2Overview ................................................................................................................98 18.3SS pin functionality ..............................................................................................103 18.4Data modes .........................................................................................................103 18.5Register description .............................................................................................105 19 Coulomb counter – Dedicated fuel gauging Sigma-Delta ADC ...... 108 19.1Features ..............................................................................................................108 19.2Overview ..............................................................................................................108 19.3Normal operation .................................................................................................109 19.4Regular current detection operation ....................................................................110 19.5Offset canceling by polarity switching ..................................................................110 19.6Configuration and usage .....................................................................................111 19.7Register description .............................................................................................111 20 Voltage ADC – 7-channel general purpose 12-bit Sigma-Delta ADC 116 20.1Features ..............................................................................................................116 4 8042E–AVR–09/2013 ATmega16HVB/32HVB 20.2Overview ..............................................................................................................116 20.3Operation .............................................................................................................116 20.4Register description .............................................................................................119 21 Voltage reference and temperature sensor ....................................... 122 21.1Features ..............................................................................................................122 21.2Overview ..............................................................................................................122 21.3Operation .............................................................................................................122 21.4Bandgap calibration .............................................................................................123 21.5Bandgap buffer settling time ................................................................................123 21.6Register description .............................................................................................124 22 Charger detect ...................................................................................... 126 22.1Features ..............................................................................................................126 22.2Overview ..............................................................................................................126 22.3Operation .............................................................................................................127 22.4Register description .............................................................................................128 23 Voltage regulator .................................................................................. 129 23.1Features ..............................................................................................................129 23.2Overview ..............................................................................................................129 23.3Regulator start-up ................................................................................................130 23.4Battery pack short detection ................................................................................130 23.5Black-out detection ..............................................................................................130 23.6Register description .............................................................................................131 24 Battery protection ................................................................................ 132 24.1Features ..............................................................................................................132 24.2Overview ..............................................................................................................132 24.3Operation .............................................................................................................133 24.4External protection input ......................................................................................134 24.5Optimizing usage for low power consumption .....................................................136 24.6Battery protection CPU interface .........................................................................137 24.7Register description .............................................................................................137 25 FET driver ............................................................................................. 145 25.1Features ..............................................................................................................145 25.2Overview ..............................................................................................................145 25.3Operation and usage ...........................................................................................146 5 8042E–AVR–09/2013 ATmega16HVB/32HVB 25.4Register description .............................................................................................149 26 Cell balancing ....................................................................................... 151 26.1Overview ..............................................................................................................151 26.2Register description .............................................................................................152 27 2-wire serial interface .......................................................................... 153 27.1Features ..............................................................................................................153 27.2Two-wire serial interface bus definition ...............................................................153 27.3Data transfer and frame format ...........................................................................154 27.4Multi-master bus systems, arbitration and synchronization .................................157 27.5Overview of the TWI module ...............................................................................159 27.6Using the TWI ......................................................................................................162 27.7Transmission modes ...........................................................................................165 27.8Multi-master systems and arbitration ...................................................................178 27.9Bus connect/disconnect for two-wire serial interface ...........................................179 27.10Register description ...........................................................................................181 28 debugWIRE on-chip debug system .................................................... 186 28.1Features ..............................................................................................................186 28.2Overview ..............................................................................................................186 28.3Physical interface ................................................................................................186 28.4Software break points ..........................................................................................187 28.5Limitations of debugWIRE ...................................................................................187 28.6Register description .............................................................................................187 29 Boot loader support – Read-while-write self-programming ............. 188 29.1Features ..............................................................................................................188 29.2Overview ..............................................................................................................188 29.3Application and boot loader flash sections ..........................................................188 29.4Read-while-write and no read-while-write flash sections .....................................189 29.5Boot loader lock bits ............................................................................................191 29.6Entering the boot loader program ........................................................................192 29.7Addressing the flash during self-programming ....................................................192 29.8Self-programming the flash .................................................................................193 29.9Register description .............................................................................................202 30 Memory programming ......................................................................... 204 30.1Program and data memory lock bits ....................................................................204 6 8042E–AVR–09/2013 ATmega16HVB/32HVB 30.2Fuse bits ..............................................................................................................205 30.3Signature bytes ....................................................................................................206 30.4Calibration bytes ..................................................................................................207 30.5Page size .............................................................................................................207 30.6Serial programming .............................................................................................207 30.7Parallel programming ..........................................................................................211 31 Operating circuit .................................................................................. 220 32 Electrical characteristics ..................................................................... 225 32.1Absolute maximum ratings* .................................................................................225 32.2Supply current characteristics .............................................................................225 32.3NFET driver characteristics .................................................................................226 32.4Reset characteristics ...........................................................................................227 32.5Voltage regulator characteristics .........................................................................227 32.6Voltage reference and temperature sensor characteristics .................................227 32.7ADC characteristics .............................................................................................228 32.8Clock characteristics ............................................................................................229 32.9Cell balancing characteristic ................................................................................230 32.10Battery protection characteristics ......................................................................230 32.11External interrupt characteristics .......................................................................230 32.12General I/O lines characteristics ........................................................................231 32.132-wire serial interface characteristics ................................................................232 32.14SPI timing characteristics ..................................................................................233 32.15Serial programming characteristics ...................................................................234 32.16Parallel programming characteristics ................................................................235 33 Typical characteristics ........................................................................ 238 33.1Supply current characteristics .............................................................................238 33.2NFET driver characteristics .................................................................................245 33.3Battery protection characteristics ........................................................................248 33.4Clock characteristics ............................................................................................248 33.5Voltage reference characteristics ........................................................................251 33.6Voltage regulator characteristics .........................................................................252 33.7BOD threshold characteristics .............................................................................254 34 Register summary ................................................................................ 255 35 Instruction set summary ..................................................................... 259 7 8042E–AVR–09/2013 ATmega16HVB/32HVB 36 Ordering information ........................................................................... 262 36.1The Atmel ATmega16HVB ..................................................................................262 36.2The Atmel ATmega32HVB ..................................................................................263 37 Packaging information ........................................................................ 264 37.144X1 ....................................................................................................................264 38 Errata ..................................................................................................... 265 38.1The Atmel ATmega16HVB ..................................................................................265 38.2The Atmel ATmega32HVB ..................................................................................266 39 Revision history ................................................................................... 267 39.1Rev. 8042E-09/2013 ............................................................................................267 39.2Rev. 8042D-10/2011 ...........................................................................................267 39.3Rev. 8042C-06/2011 ...........................................................................................268 39.4Rev. 8042B-06/2010 ............................................................................................269 39.5Rev. 8042A-08/2009 ............................................................................................269 Table of Contents...................................................................................... 1 8042E–AVR–09/2013 Atmel Corporation 1600 Technology Drive San Jose, CA 95110 USA Tel: (+1) (408) 441-0311 Fax: (+1) (408) 487-2600 www.atmel.com Atmel Asia Limited Unit 01-5 & 16, 19F BEA Tower, Millennium City 5 418 Kwun Tong Roa Kwun Tong, Kowloon HONG KONG Tel: (+852) 2245-6100 Fax: (+852) 2722-1369 Atmel Munich GmbH Business Campus Parkring 4 D-85748 Garching b. Munich GERMANY Tel: (+49) 89-31970-0 Fax: (+49) 89-3194621 Atmel Japan G.K. 16F Shin-Osaki Kangyo Bldg 1-6-4 Osaki, Shinagawa-ku Tokyo 141-0032 JAPAN Tel: (+81) (3) 6417-0300 Fax: (+81) (3) 6417-0370 © 2013 Atmel Corporation. All rights reserved. / Rev.: 8042E–AVR–09/2013 Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life. Atmel®, Atmel logo and combinations thereof, Enabling Unlimited Possibilities®, AVR® and others are registered trademarks or trademarks of Atmel Corporation or its subsidiaries. Other terms and product names may be trademarks of others.

Atmel QTouch Library QTouch Library Peripheral Touch Controller USER GUIDE Description Atmel® QTouch® Peripheral Touch Controller (PTC) offers built-in hardware for capacitive touch measurement on sensors that function as buttons, sliders, and wheels. The PTC supports both mutual and self-capacitance measurement without the need for any external component. It offers superb sensitivity and noise tolerance, as well as self-calibration, and minimizes the sensitivity tuning effort by the user. The PTC is intended for autonomously performing capacitive touch sensor measurements. The external capacitive touch sensor is typically formed on a PCB, and the sensor electrodes are connected to the analog charge integrator of the PTC using the device I/O pins. The PTC supports mutual capacitance sensors organized as capacitive touch matrices in different X-Y configurations, including Indium Tin Oxide (ITO) sensor grids. In mutual capacitance mode, the PTC requires one pin per X-line (drive line) and one pin per Y-line (sense line). In self-capacitance mode, the PTC requires only one pin with a Y-line driver for each self-capacitance sensor. Features • Implements low-power, high-sensitivity, environmentally robust capacitive touch buttons, sliders, and wheels • Supports mutual capacitance and self-capacitance sensing • Up to 32 buttons in self-capacitance mode • Up to 256 buttons in mutual capacitance mode • Supports lumped mode configuration • One pin per electrode - no external components • Load compensating charge sensing • Parasitic capacitance compensation for mutual capacitance mode • Adjustable gain for superior sensitivity • Zero drift over the temperature and VDD range • No need for temperature or VDD compensation • Hardware noise filtering and noise signal de-synchronization for high conducted immunity • Atmel provided QTouch Library firmware and QTouch Composer tool Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 Product Support For assistance related to QTouch capacitive touch sensing software libraries and related issues, contact your local Atmel sales representative or log on to myAtmel Design Support portal to submit a support request or access a comprehensive knowledge base. If you do not have a myAtmel account, please visit http://www.atmel.com/design-support/ to create a new account by clicking on Create Account in the myAtmel menu at the top of the page. When logged in, you will be able to access the knowledge base, submit new support cases from the myAtmel page or review status of your ongoing cases. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 2 Table of Contents Description.......................................................................................................................1 Features.......................................................................................................................... 1 1. Development Tools ................................................................................................... 5 2. Device Variants Supported........................................................................................ 6 3. Capacitive Touch Technology.................................................................................... 8 3.1. Capacitive Touch Sensors............................................................................................................8 3.2. Capacitance Measurement Methods............................................................................................8 3.3. Self-capacitance Measurement Method.......................................................................................8 3.4. Mutual Capacitance Measurement Method..................................................................................9 3.5. Capacitive Touch Lumped Sensors..............................................................................................9 3.6. Capacitive Touch Low Power Sensor......................................................................................... 11 3.7. PTC and its Benefits...................................................................................................................13 3.8. PTC Block Diagram for Self-capacitance and Mutual Capacitance Method.............................. 13 3.9. Design Approach with PTC........................................................................................................ 15 3.10. Capacitive Touch Development Cycle........................................................................................16 4. Touch Sensor Debug and Status Information..........................................................17 4.1. Signal..........................................................................................................................................17 4.2. Reference...................................................................................................................................17 4.3. Delta........................................................................................................................................... 18 4.4. Touch Status & Slider/Wheel Position........................................................................................ 19 5. QTouch Library........................................................................................................ 20 5.1. Overview.....................................................................................................................................20 5.2. Library Parameters.....................................................................................................................21 5.3. Moisture Tolerance..................................................................................................................... 42 5.4. Reading Sensor States...............................................................................................................44 5.5. Application Flow......................................................................................................................... 44 5.6. API Sequence.............................................................................................................................46 5.7. State Machine.............................................................................................................................47 5.8. Operation Modes........................................................................................................................50 5.9. Touch Library API Error.............................................................................................................. 52 6. Tuning for Noise Performance.................................................................................54 6.1. Noise Sources............................................................................................................................ 54 6.2. Noise Counter Measures............................................................................................................54 7. Application Design...................................................................................................60 7.1. Touch Library and Associated Files............................................................................................60 7.2. Code and Data Memory Considerations.................................................................................... 60 8. Example Applications.............................................................................................. 63 8.1. Atmel Board Example Projects...................................................................................................63 8.2. User Board Example Projects.................................................................................................... 66 8.3. Using Atmel Software Framework (ASF) with the Example Projects......................................... 67 8.4. Using Xplained Pro Kit to Program User Board......................................................................... 67 8.5. Using QDebug Touch Data Debug Communication Interface.................................................... 67 8.6. Using Xplained Pro Kit for QDebug Data Streaming from User Board...................................... 68 8.7. Using Atmel ICE for QDebug Data Streaming from User Board................................................ 70 9. Known Issues.......................................................................................................... 71 10. FAQ on PTC Qtouch................................................................................................73 11. Appendix..................................................................................................................74 11.1. Macros........................................................................................................................................74 11.2. Typedef.......................................................................................................................................76 11.3. Enumeration............................................................................................................................... 76 11.4. Datastructures............................................................................................................................ 84 11.5. Global Variables......................................................................................................................... 92 11.6. API..............................................................................................................................................93 12. Revision History.....................................................................................................100 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 4 1. Development Tools The following development tools are required for developing QTouch library using PTC: • Development Environment for GCC Compiler: – QTouch Composer 5.9.116 or later versions – QTouch Library 5.9.211 or later versions Note:  The QTouch Library and Composer extensions work only with Atmel Studio 7 which can be downloaded from http://www.atmel.com/ – Dependent Atmel Studio Extensions • Atmel Software Framework 3.30.1 or later versions • Atmel Kit Extension 7.0.70 or later versions • Development Environment for IAR Compiler: – IAR Embedded Workbench® for ARM® 7.50.1.10273 or later – IAR Embedded Workbench for Atmel AVR® 6.70.1 or later – Atmel Software Framework 3.29.0 or later (optional) – Atmel QTouch Library 5.9.211 IAR Installer (available at http://www.atmel.com/tools/ qtouchlibraryptc.aspx) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 5 2. Device Variants Supported QTouch Library for SAM and ATmega devices are available for the following device variants: Series Variant SAM D20 J Series ATSAMD20J18, ATSAMD20J17, ATSAMD20J16, ATSAMD20J15, ATSAMD20J14 SAM D20 G Series ATSAMD20G18, ATSAMD20G18U, ATSAMD20G17, ATSAMD20G17U, ATSAMD20G16, ATSAMD20G15, ATSAMD20G14 SAM D20 E Series ATSAMD20E18, ATSAMD20E17, ATSAMD20E16, ATSAMD20E15, ATSAMD20E14 SAM D21 J Series ATSAMD21J18A, ATSAMD21J17A, ATSAMD21J16A, ATSAMD21J15A, ATSAMD21J16B, ATSAMD21J15B SAM D21 G Series ATSAMD21G18A, ATSAMD21G17A, ATSAMD21G16A, ATSAMD21G15A, ATSAMD21G15B, ATSAMD21G16B, ATSAMD21G17AU, ATSAMD21G18AU SAM D21 E Series ATSAMD21E18A, ATSAMD21E17A, ATSAMD21E16A, ATSAMD21E15A, ATSAMD21E15B, ATSAMD21E15BU, ATSAMD21E16B, ATSAMD21E16BU SAM D10 C Series ATSAMD10C14A SAM D10 D Series ATSAMD10D14AM, ATSAMD10D14AS, ATSAMD10D14AU SAM D11 C Series ATSAMD11C14A SAM D11 D Series ATSAMD11D14AM, ATSAMD11D14AS, ATSAMD11D14AU SAM L21 E Series ATSAML21E15B, ATSAML21E16B, ATSAML21E17B, ATSAML21E18B SAM L21 G Series ATSAML21G16B, ATSAML21G17B, ATSAML21G18B SAM L21 J Series ATSAML21J16B, ATSAML21J17B, ATSAML21J18B SAM R21 E Series ATSAMR21E16A, ATSAMR21E17A, ATSAMR21E18A, ATSAMR21E19A SAM R21 G Series ATSAMR21G16A, ATSAMR21G17A, ATSAMR21G18A SAM DA1 E Series ATSAMDA1E14A, ATSAMDA1E15A, ATSAMDA1E16A SAM DA1 G Series ATSAMDA1G14A, ATSAMDA1G15A, ATSAMDA1G16A SAM DA1 J Series ATSAMDA1J14A, ATSAMDA1J15A, ATSAMDA1J16A SAM C21 E Series ATSAMC21E15A, ATSAMC21E16A, ATSAMC21E17A, ATSAMC21E18A SAM C21 G Series ATSAMC21G15A, ATSAMC21G16A. ATSAMC21G17A, ATSAMC21G18A SAM C21 J Series ATSAMC21J16A, ATSAMC21J17A, ATSAMC21J18A SAM C20 E Series ATSAMC20E15A, ATSAMC20E16A, ATSAMC20E17A, ATSAMC20E18A SAM C20 G Series ATSAMC20G15A, ATSAMC20G16A. ATSAMC20G17A, ATSAMC20G18A SAM C20 J Series ATSAMC20J16A, ATSAMC20J17A, ATSAMC20J18A SAM L22 G Series ATSAML22G16A, ATSAML22G17A, ATSAML22G18A SAM L22 J Series ATSAML22J16A, ATSAML22J17A, ATSAML22J18A Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 6 Series Variant SAM L22 N Series ATSAML22N16A, ATSAML22N17A, ATSAML22N18A ATmega Series ATmega328PB, ATmega324PB Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 7 3. Capacitive Touch Technology 3.1. Capacitive Touch Sensors Capacitive touch sensors replace conventional mechanical interfaces and operate with no mechanical wear and are closed to the environment. They provide greater flexibility in industrial design and result in differentiating end product design. For more information, refer Capacitive Touch Lumped Sensors and Capacitive Touch Low Power Sensor. Figure 3-1. Sensor Types 3.2. Capacitance Measurement Methods Self-capacitance measurement method involves charging a sense electrode of unknown capacitance to a known potential. The resulting charge is transferred into a measurement circuit. By measuring the charge with one or more charge-and transfer cycles, the capacitance of the sense plate can be determined. Figure 3-2. Capacitance Measurement Principle Mutual capacitance measurement method uses a pair of sensing electrodes. One electrode acts as an emitter into which a charge consisting of logic pulses is driven in burst mode. The other electrode acts as a receiver that couples to the emitter using the overlying panel dielectric. When a finger touches the panel, the field coupling is reduced, and touch is detected. 3.3. Self-capacitance Measurement Method • Uses a single sense electrode (Y-line) – Self-capacitance button can be formed using one channel – Self-capacitance slider and wheel is formed using 3 channels • Robust and easy to use, ideal for low sensors count Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 8 Figure 3-3. Self-capacitance Method 3.4. Mutual Capacitance Measurement Method • Uses a pair of sense electrodes (X-Y lines) – Mutual capacitance buttons use one X-Y channel – Mutual capacitance sliders and wheels can be configured to use 3 to 8 X-Y channels, depending on the sensor size • Suitable for high sensor count • Better moisture tolerance Figure 3-4. Mutual Capacitance Method 3.5. Capacitive Touch Lumped Sensors Lumped sensor configuration is a combination of multiple sense lines (Self-capacitance measurement) or multiple drive and sense lines (Mutual capacitance measurement) to act as one single sensor. Lumped mode acts as a tool for application developers to improve overall system performance. Improved Power Efficiency When multiple sensors are lumped together and treated as one single sensor the time taken to perform scans is reduced. For battery powered applications using multiple buttons, a group of touch sensors can be lumped to form a single lumped sensor and this sensor alone can be scanned, thereby resulting in reduced power consumption. Upon user presence detection on the lumped sensor all configured sensors in the system can then be scanned individually. Improved Response Time Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 9 In high key-count applications, there can be a significant latency between touching a sensor and the detection of a touch contact. This is due to the time taken to sequentially measure the capacitance of each key on each measurement cycle.With a Lumped mode implementation this latency can be reduced by arranging the sensors into groups. When one of those lumped groups shows touch detection, only the keys within that group are individually measured to determine which is touched. E.g. A keyboard consisting 64 keys may be divided into 8 lumped groups of 8. Thus, each measurement cycle is reduced to measure only the 8 lumped sensors. When a touch contact is applied, first the lump sensor shows touch delta, then the 8 component keys are scanned and the location is resolved. Only 16 measurements are required to resolve the touch status of all keys, compared to 64 measurements in the traditional sequential scan of all keys. It offers an additional edge during low power acquisition as a group of keys [in lumped configuration] can be scanned thus reducing the power consumed drastically. Each sensor has its own pre-scaled clock and series resistor for improved noise immunity. Figure 3-5. Self-capacitance Sensors connected to PTC Figure 3-6. Lumped Self-capacitance Sensors connected to PTC In the preceeding figures, individual buttons are shown along with the lumped equivalent for selfcapacitance arrangement. Lumped Mode Pin and Sensor Configuration for Self-capacitance Method: #define DEF_SELFCAP_LINES Y(5), Y(4), Y(11), Y(10), Y(13), Y(7), Y(12), Y(6), LUMP_Y(5,4) touch_ret = touch_selfcap_sensor_config(SENSOR_TYPE_LUMP, CHANNEL_8, CHANNEL_8, NO_AKS_GROUP, 40u, HYST_6_25, RES_8_BIT, &sensor_id); Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 10 Figure 3-7. Lumped Sense Lines Mutual Capacitance Sensors connected to PTC In the preceeding figure, mutual capacitance lumped sensor configuration is presented. Lumped Mode Pin and Sensor Configuration for Mutual Capacitance Method: #define DEF_MUTLCAP_NODES X(8), Y(10), X(9), Y(10), X(2), Y(12), X(3), Y(12), \X(8), Y(12), X(9), Y(12), X(2), Y(13), X(3), Y(13), \X(8), Y(13), X(9), Y(13), LUMP_X(2,3,8,9), LUMP_Y(10,13) touch_ret = touch_mutlcap_sensor_config(SENSOR_TYPE_LUMP, CHANNEL_10, CHANNEL_10, NO_AKS_GROUP, 20u, HYST_6_25, RES_8_BIT, 0, &sensor_id); Limitations of Use Lumped sensor capacitive load should not exceed the maximum sensor load for individual sensors in either mutual or self-capacitance modes. Lumped mode treats the larger sensors as one single sensor therefore the maximum lumped sensor load should also observe this specification, else this will result in calibration error. In mutual capacitance measurement mode the capacitive load of each sensor is normally much lower than that of the self-capacitance method. It is therefore possible as a general rule to use more mutual sensors together as a single lumped sensor. The user can ensure that the lumped sensor does not result in a calibration error (value of 0x80) using p_xxxxcap_measure_data->p_sensors[].state variable. 3.6. Capacitive Touch Low Power Sensor The QTouch Library may be configured to operate PTC touch sensing autonomously using the Event System. In this mode, a single sensor is designated as the ‘Low Power’ key and may be periodically measured for touch detection without any CPU action. The CPU may be held in deep sleep mode throughout the operation, minimizing power consumption. The low power key may be a discrete electrode with one Y (Sense) line for Self-capacitance or One X (Drive) plus one Y (Sense) for mutual capacitance, or it may be a combination of multiple Drive and/or Sense lines as a Lumped mode sensor. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 11 Figure 3-8. Low Power Flow Active Measurement Mode In the active measurement mode all configured sensors are measured at DEF_TOUCH_MEASUREMENT_PERIOD_MS millisecond scan interval. The user application arrangement could be designed such that when no touch activity is detected on any of the configured sensors for NO_ACTIVITY_TRIGGER_TIME milliseconds, then the application switches to low power measurement mode. Low Power Measurement Mode In the low power measurement mode, a designated sensor or a lumped sensor can be scanned as a single sensor. In this mode, the system is in standby sleep mode, the CPU and other peripherals are in sleep, excepting for the event system, the RTC and the PTC module / WDT and PTC module in SAM / Mega devices. A user touch on the designated low power sensor will cause the CPU to wake up and perform active measurement in order to resolve the touch. To keep reference tracking of the designated low power sensor, the RTC/WDT is configured to periodically wake up the CPU every DEF_LOWPOWER_SENSOR_DRIFT_PERIODICITY_MS millisecond to perform one active measurement. Switching between Active Mode and Low Power Mode Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 12 When switching from active to low power mode, all sensors except the lumped sensor are disabled. So, no reference tracking is performed on these sensors during the low power mode. When a touch is detected on the lumped sensor, all disabled sensors shall now be re-enabled and measurement is initiated on the sensors. If the device is in sleep for a very long time, then it is recommended to force calibration on the re-enabled sensors to ensure proper reference values on these sensors. 3.7. PTC and its Benefits • Mixed Hardware + Firmware solution, allows user to define sensor configuration – Peripheral Touch Controller + QTouch library • PTC runs data acquisition autonomously, resulting in low CPU utilization and power consumption – User controlled power-performance trade-off – CPU can sleep during acquisition to save power – Alternatively, CPU can perform other time critical operations during touch acquisition • Robust noise performance Figure 3-9. User Application with PTC Device 3.8. PTC Block Diagram for Self-capacitance and Mutual Capacitance Method The PTC block diagram for self-capacitance measurement is shown in the following figure. Only Y-lines can be connected to self-capacitance sensors and are selected using the Input control. X-lines remain unused and can be used for any other GPIO functionality. The acquisition module along with the compensation circuit helps in measuring the change in capacitance due to user touch. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 13 Figure 3-10. PTC Self-capacitance Method - Block Diagram The PTC block diagram for mutual capacitance measurement is as shown in the following figure. Both Xlines and Y-lines should be connected to mutual capacitance sensors and are selected using the Input control. Figure 3-11. PTC Mutual Capacitance Method - Block Diagram 3.8.1. Compensation Circuit The PTC has an internal compensation circuit which is used to compensate the sensor capacitance. Both self-capacitance and mutual capacitance sensing modes have the same compensation range. But the mutual capacitance mode can compensate more parasitic capacitance compared to self-capacitance mode. The tag_touch_measure_data_t structure contains the p_cc_calibration_vals parameter which represents the current channel's compensation circuit value. For more information, refer Measure Data Type (tag_touch_measure_data_t) . Compensation circuit value used in pF = (p_cc_calibration_vals[channel_no]& 0x0F)*0.00675 + ((p_cc_calibration_vals[channel_no] >> 4) & 0x0F)*0.0675 + ((p_cc_calibration_vals[channel_no] >> 8) & 0x0F)*0.675 + ((p_cc_calibration_vals[channel_no] >> 12) & 0x3 ) * 6.75 Also, the touch_xxxxcap_sensors_calibrate function helps the user to calibrate the compensation circuit according to the sensors used. If the routine fails to calibrate the compensation circuit due to saturation, the measurement will return TOUCH_CC_CALIB_ERROR. The compensation circuit could have Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 14 exceeded its limit. The specific sensor that has failed can be determined using p_xxxxcap_measure_data->p_sensors[].statewhen it contains the value of SENSOR_CALIBRATION_ERROR(0x80u). • Typical compensation circuit value for the self-capacitance mode ranges from 10 to 25 pF and for the mutual capacitance mode it is around 2 pF. • The compensation circuit value is affected by sensor size and the ground surrounding the sensor or trace. The compensation ciruit value ranges from 0.00675 pF to 31.48 pF. • If the compensation circuit value exceeds the limit, to reduce the value, use a mesh instead of a solid plane in the sensor and ground plane. • For detailed sensor design, refer http://www.atmel.com/images/doc10752.pdf. 3.9. Design Approach with PTC Two design approaches are possible when using Atmel MCU along with PTC. The Atmel MCU could be predominantly used as an MCU for touch measurement. Else, the Atmel MCU can function as a Host MCU utilizing peripherals such as the USB, ADC, DAC, SERCOM, DMA and GPIO along with the PTC used for "on-chip" touch functionality. The design approaches are: • Atmel MCU with PTC predominantly functioning as a touch MCU – Used for touch sensor status and rotor/slider position detection – Additionally used to indicate touch status using LED, buzzer etc – Sends touch status and rotor/slider position information to a Host MCU • Atmel MCU functions as a Host MCU with on-chip touch functionality – Can be a cost saving design as a single chip solution with on-chip touch functionality – Utilizes other on-chip peripheral for a desired user application Figure 3-12. PTC Design Approach Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 15 3.10. Capacitive Touch Development Cycle The capacitive touch development cycle involves PCB board design to develop the user interface hardware as well as firmware application development. The QTouch Composer PC software available as part of Atmel Studio extension gallery allows for PTC QTouch Library projects to be generated automatically with a desired user configuration for touch sensors. The QTouch Composer also allows for touch sensor data analysis and performance tuning for sensitivity and noise. Figure 3-13. Capacitive Touch Development Cycle Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 16 4. Touch Sensor Debug and Status Information The touch sensor debug information necessary for tuning of the sensors are signal, reference, delta, and compensation capacitance. While the signal, reference and delta help in sensitivity and noise tuning the sensor parameters, the compensation capacitance is an indicator for extreme sensor design. The sensor status and position information are parameters that must be judged by the user application to initate the relevant touch action. 4.1. Signal Signal value is the raw measurement data on a given touch channel. The value increases upon touch. Figure 4-1. Channel Signal 4.2. Reference Reference value of a touch channel is the long term average measurement on a specific channel. It represents: • Resting signal when there is no touch • Initial value obtained during the calibration process • Reference is adapted by Drift Compensation algorithm Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 17 Figure 4-2. Channel Reference 4.3. Delta Delta value of a touch channel represents touch strength. • Delta = (signal - reference) • Deltas increase with touch Figure 4-3. Sensor Delta Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 18 4.4. Touch Status & Slider/Wheel Position The sensor touch status is the primary touch sensor information utilized by a user application. The sensor state can either be ON or OFF. For sliders and wheel, additionally the touch position is of interest. For an 8-bit resolution, the touch position ranges from 0 to 255 end-to-end. It is possible to configure with a lower resolution by configuring setting in the touch library. The sensor touch status and slider/wheel position must always be used once the library completes the measurements. The touch sensor state for mutual capacitance or self-capacitance sensor can be obtained by reading the following boolean variables. bool sensor_state_self = GET_SELFCAP_SENSOR_STATE(SENSOR_NUMBER); bool sensor_state_mutl = GET_MUTLCAP_SENSOR_STATE(SENSOR_NUMBER); The touch sensor rotor or slider position information for mutual capacitance or self-capacitance sensor can be obtained using the following parameters. uint8_t rotor_slider_position_self = GET_SELFCAP_ROTOR_SLIDER_POSITION(ROTOR_SLIDER_NUMBER); uint8_t rotor_slider_position_mutl = GET_MUTLCAP_ROTOR_SLIDER_POSITION(ROTOR_SLIDER_NUMBER); The touch sensor noise status for mutual capacitance or self-capacitance sensor can be obtained using the following parameters. bool sensor_noise_state_self = GET_SELFCAP_SENSOR_NOISE_STATUS(SENSOR_NUMBER); bool sensor_noise_state_mutl = GET_MUTLCAP_SENSOR_NOISE_STATUS(SENSOR_NUMBER); Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 19 5. QTouch Library Atmel QTouch Library makes it simple for developers to embed capacitive touch button, slider, wheel functionality into general purpose Atmel SMART | ARM and AVR® microcontroller applications. The royalty- free QTouch Library provides several library files for each device and supports different numbers of touch channels, enabling both flexibility and efficiency in touch applications. QTouch Library can be used to develop single-chip solutions for many control applications, or to reduce chip count in more complex applications. Developers have the latitude to implement buttons, sliders, and wheels in a variety of combinations on a single interface. Figure 5-1. QTouch Library 5.1. Overview QTouch Library API for PTC can be used for touch sensor pin configuration, acquisition parameter setting as well as periodic sensor data capture and status update operations. The QTouch Library in turn interfaces with the PTC module to perform the necessary action. The PTC module interfaces with the external capacitive touch sensors and is capable of performing self and mutual capacitance method measurements. The library features low power and lumped mode configuration. Figure 5-2. QTouch Library Overview The QTouch Library API is arranged such that the user application can use standalone self-capacitance or mutual capacitance method or both methods, simultaneously. The following table captures the APIs available for each method. For normal operation, it is sufficient to use the set of Regular APIs for each method. The Helper APIs provides additional flexibility to the user application. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 20 Method Regular API Helper API Mutual capacitance touch_mutlcap_sensors_init touch_mutlcap_sensor_config touch_mutlcap_sensors_calibrate touch_mutlcap_sensors_measure touch_mutlcap_sensors_deinit touch_mutlcap_lowpower_sensor_enable_event_measure touch_mutlcap_sensor_get_delta touch_mutlcap_sensor_update_config touch_mutlcap_sensor_get_config touch_mutlcap_update_global_param touch_mutlcap_get_global_param touch_mutlcap_update_acq_config touch_mutlcap_get_acq_config touch_mutlcap_sensor_disable touch_mutlcap_sensor_reenable touch_multcap_mois_tolrnce_enable touch_multcap_mois_tolrnce_disable touch_mutlcap_cnfg_mois_threshold touch_mutlcap_cnfg_mois_mltchgrp touch_mutlcap_mois_tolrnce_quick_reburst_enable touch_mutlcap_mois_tolrnce_quick_reburst_disable touch_mutlcap_get_libinfo touch_library_get_version_info touch_resume_ptc touch_suspend_ptc Self-capacitance touch_selfcap_sensors_init touch_selfcap_sensor_config touch_selfcap_sensors_calibrate touch_selfcap_sensors_measure touch_selfcap_sensors_deinit touch_selfcap_lowpower_sensor_enable_event_measure touch_selfcap_sensor_get_delta touch_selfcap_sensor_update_config touch_selfcap_sensor_get_config touch_selfcap_update_global_param touch_selfcap_get_global_param touch_selfcap_update_acq_config touch_selfcap_get_acq_config touch_selfcap_sensor_disable touch_selfcap_sensor_reenable touch_selfcap_mois_tolrnce_enable touch_selfcap_mois_tolrnce_disable touch_selfcap_cnfg_mois_threshold touch_selfcap_cnfg_mois_mltchgrp touch_selfcap_mois_tolrnce_quick_reburst_enable touch_selfcap_mois_tolrnce_quick_reburst_disable touch_selfcap_get_libinfo touch_library_get_version_info touch_suspend_ptc touch_resume_ptc 5.2. Library Parameters The QTouch Library configuration parameters are listed in the following table: Configuration Mutual capacitance Self-capacitance Pin Configuration DEF_MUTLCAP_NODES DEF_SELFCAP_LINES Sensor Configuration DEF_MUTLCAP_NUM_CHANNELS DEF_MUTLCAP_NUM_SENSORS DEF_MUTLCAP_NUM_ROTORS_SLIDERS DEF_MUTLCAP_PTC_GPIO_STATE DEF_MUTLCAP_QUICK_REBURST_ENABLE DEF_SELFCAP_NUM_CHANNELS DEF_SELFCAP_NUM_SENSORS DEF_SELFCAP_NUM_ROTORS_SLIDERS DEF_SELFCAP_PTC_GPIO_STATE DEF_SELFCAP_QUICK_REBURST_ENABLE Sensor Individual Parameters Detect Threshold Detect Hysteresis Position Resolution Position Hysteresis AKS group Detect Threshold Detect Hysteresis Position Resolution AKS group Sensor Global Parameters DEF_MUTLCAP_DI DEF_MUTLCAP_TCH_DRIFT_RATE DEF_MUTLCAP_ATCH_DRIFT_RATE DEF_MUTLCAP_MAX_ON_DURATION DEF_MUTLCAP_DRIFT_HOLD_TIME DEF_MUTLCAP_ATCH_RECAL_DELAY DEF_MUTLCAP_ATCH_RECAL_THRESHOLD DEF_MUTLCAP_TOUCH_POSTPROCESS_MODE DEF_MUTLCAP_AKS_ENABLE DEF_MUTLCAP_CSD DEF_MUTLCAP_AUTO_OS_SIGNAL_STABILITY_LIMIT DEF_SELFCAP_DI DEF_SELFCAP_TCH_DRIFT_RATE DEF_SELFCAP_ATCH_DRIFT_RATE DEF_SELFCAP_MAX_ON_DURATION DEF_SELFCAP_DRIFT_HOLD_TIME DEF_SELFCAP_ATCH_RECAL_DELAY DEF_SELFCAP_ATCH_RECAL_THRESHOLD DEF_SELFCAP_TOUCH_POSTPROCESS_MODE DEF_SELFCAP_AKS_ENABLE DEF_SELFCAP_CSD DEF_SELFCAP_AUTO_OS_SIGNAL_STABILITY_ LIMIT Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 21 Configuration Mutual capacitance Self-capacitance Sensor Acquisition Parameters DEF_MUTLCAP_FILTER_LEVEL_PER_NODE DEF_MUTLCAP_AUTO_OS_PER_NODE DEF_MUTLCAP_GAIN_PER_NODE DEF_MUTLCAP_FREQ_MODE DEF_MUTLCAP_HOP_FREQS DEF_MUTLCAP_CLK_PRESCALE_PER_NODE DEF_MUTLCAP_SENSE_RESISTOR_PER_NODE DEF_SELFCAP_FILTER_LEVEL_PER_NODE DEF_SELFCAP_AUTO_OS_PER_NODE DEF_SELFCAP_GAIN_PER_NODE DEF_SELFCAP_FREQ_MODE DEF_SELFCAP_HOP_FREQS DEF_SELFCAP_CLK_PRESCALE_PER_NODE DEF_SELFCAP_SENSE_RESISTOR_PER_NODE Sensor Calibration Auto Tune Setting AUTO_TUNE_PRSC, AUTO_TUNE_RSEL, AUTO_TUNE_NONE AUTO_TUNE_PRSC, AUTO_TUNE_RSEL, AUTO_TUNE_NONE Sensor Noise measurement and Lockout Parameters DEF_MUTLCAP_NOISE_MEAS_ENABLE DEF_MUTLCAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT DEF_MUTLCAP_NOISE_LIMIT DEF_MUTLCAP_NOISE_MEAS_BUFFER_CNT DEF_MUTLCAP_LOCKOUT_SEL DEF_MUTLCAP_LOCKOUT_CNTDOWN DEF_SELFCAP_NOISE_MEAS_ENABLE DEF_SELFCAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT DEF_SELFCAP_NOISE_LIMIT DEF_SELFCAP_NOISE_MEAS_BUFFER_CNT DEF_SELFCAP_LOCKOUT_SEL DEF_SELFCAP_LOCKOUT_CNTDOWN Sensor Acquisition Frequency Auto-tuning Parameters DEF_MUTLCAP_FREQ_AUTO_TUNE_ENABLE DEF_MUTLCAP_FREQ_AUTO_TUNE_SIGNAL_STABILITY_LIMIT DEF_MUTLCAP_FREQ_AUTO_TUNE_IN_CNT DEF_SELFCAP_FREQ_AUTO_TUNE_ENABLE DEF_SELFCAP_FREQ_AUTO_TUNE_SIGNAL_STABILITY_LIMIT DEF_SELFCAP_FREQ_AUTO_TUNE_IN_CNT Common Parameters DEF_TOUCH_MEASUREMENT_PERIOD_MS, DEF_TOUCH_PTC_ISR_LVL Low Power Paramaters DEF_LOWPOWER_SENSOR_EVENT_PERIODICITY, DEF_LOWPOWER_SENSOR_DRIFT_PERIODICITY_MS, DEF_LOWPOWER_SENSOR_ID Moisture Parameters DEF_MUTLCAP_MOIS_TOLERANCE_ENABLE DEF_MUTLCAP_NUM_MOIS_GROUPS DEF_MUTLCAP_MOIS_QUICK_REBURST_ENABLE DEF_SELFCAP_MOIS_TOLERANCE_ENABLE DEF_SELFCAP_NUM_MOIS_GROUPS DEF_SELFCAP_MOIS_QUICK_REBURST_ENABLE 5.2.1. Pin, Channel, and Sensor Parameters Mutual capacitance method uses a pair of sensing electrodes for each touch channel. These electrodes are denoted as X and Y lines. Capacitance measurement is performed sequentially in the order in which touch (X-Y) nodes are specified in the DEF_MUTLCAP_NODES configuration parameter. A mutual capacitance touch button sensor is formed using a single X-Y channel, while a touch rotor or slider sensor is formed using three to eight X-Y channels. Mutual Capacitance Channel (X-Y Sense Node) • SAM D20J and SAM D21J (64 pins): up to 256 touch channels, 16 X and 16 Y-lines • SAM D20G and SAM D21G (48 pins): up to 120 touch channels, 12 X and 10 Y-lines • SAM D20E and SAM D21E (32 pins): up to 60 touch channels, 10 X and 6 Y-lines • SAM R21E(32 pins): up to 12 touch channels, 6 X and 2 Y-lines • SAM R21G(48 pins) up to 48 touch channels, 8 X and 6 Y-lines • SAM DA1J (64 pins): up to 256 touch channels, 16 X and 16 Y-lines • SAM DA1G (48 pins): up to 120 touch channels, 12 X and 10 Y-lines • SAM DA1E (32 pins): up to 60 touch channels, 10 X and 6 Y-lines • SAM D21G17AU and SAM D21G18AU (45 pins): up to 132 touch channels, 12 X and 11 Y-lines • SAM D21E15BU and SAM D21E16BU (35 pins): up to 60 touch channels, 10 X and 6 Y-lines The following devices have X and Y multiplexing option. • SAM D10C14A and SAM D11C14A (14 pins): up to 12 touch channels, 4 X and 3 Y-lines • SAM D10D14 AS/AU and SAM D11D14 AS/AU (20 pins): up to 42 touch channels, 7 X and 6 Ylines • SAM D10D14AM and SAM D11D14AM (24 pins): up to 72 touch channels, 9 X and 8 Y-lines • SAM L21E (32 pins): up to 42 touch channels, 7 X and 6 Y-lines • SAM L21G (48 pins): up to 81 touch channels, 9 X and 9 Y-lines • SAM L21J (64 pins): up to 169 touch channels, 13 X and 13 Y-lines Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 22 • SAM L22G (48 pins): up to 132 touch channels, 11 X and 12 Y-lines • SAM L22J (64 pins): up to 182 touch channels, 13 X and 14 Y-lines • SAM L22N (100 pins): up to 256 touch channels, 16 X and 16 Y-lines • SAM C21E and SAM C20E(32 pins): up to 60 touch channels,10 X and 6 Y-lines • SAM C21G and SAM C20G(48 pins): up to 120 touch channels,12 X and 10-Y lines • SAM C21J and SAM C20J(64 pins): up to 256 touch channels,16 X and 16 Y-lines • ATmega328PB (32 pins): up to 144 touch channels, 12 X and 12 Y-lines • ATmega324PB (44 pins): up to 256 touch channels, 16 X and 16 Y-lines A few pins can be used either as X-line or Y-line. The datasheets of individual devices provide more information about this multiplexing option. Figure 5-3. Mutual Capacitance Sensor Arrangement Figure 5-4. Mutual Capacitance - Channel to Sensor Mapping X-Y node pair can be specified using the configuration parameter DEF_MUTLCAP_NODES in a nonsequential order. The channel numbering is done in the same order as the X-Y node pair specified in the configuration parameter DEF_MUTLCAP_NODES. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 23 Setting Configuration Name Data Type Unit Min Max Typical Mutual Cap Touch Channel Nodes DEF_MUTLCAP_NODES uint16_t array None 1 X-Y node pair 256 X-Y nodepair - Mutual Cap Number of Channels DEF_MUTLCAP_NUM_CHANNELS uint16_t None 1 256 X-Y nodepair - Mutual Cap Number of Sensors DEF_MUTLCAP_NUM_SENSORS uint16_t None 1 256 X-Y nodepair - Mutual Cap Number of Rotors and Sliders DEF_MUTLCAP_NUM_ROTORS_SLIDERS uint8_t None 0 85 node pair - Self-capacitance method uses a single sense electrode, denoted by a Y-line. Capacitance measurement is performed sequentially in the order in which Y-lines are specified in the DEF_SELFCAP_LINES configuration parameter. Self-capacitance touch button sensor is formed using a single - line channel, while a touch rotor or slider sensor can be formed using three Y-line channels. Self-capacitance Channel (Y-sense line) • SAM D20J and SAM D21J (64 pins): up to 16 channels • SAM D20G and SAM D21G (48 pins): up to 10 channels • SAM D20E and SAM D21E (32 pins): up to 6 channels • SAM D10C14A and SAMD 11C14A (14 pins): up to 7 touch channels • SAM D10D14 AS/AU and SAMD 11D14 AS/AU (20 pins): up to 13 touch channels • SAM D10D14AM and SAMD 11D14AM (24 pins): up to 16 touch channels • SAM L21E (32 pins): up to 7 touch channels • SAM L21G (48 pins): up to 10 touch channels • SAM L21J (64 pins): up to 16 touch channels • SAMR21E (32 pins): up to 2 touch channels • SAMR21G (48 pins): up to 6 touch channels • SAM DA1J (64 pins): up to 16 channels • SAM DA1G (48 pins): up to 10 channels • SAM DA1E (32 pins): up to 6 channels • SAM C21E and SAM C20E (32 pins): up to 16 touch channels • SAM C21G and SAM C20G (48 pins): up to 22 touch channels • SAM C21J and SAM C20J (64 pins): up to 32 touch channels • SAM L22G (48 pins): up to 15 touch channels • SAM L22J (64 pins): up to 19 touch channels • SAM L22N (100 pins): up to 24 touch channels • ATmega328PB (32 pins): up to 24 touch channels Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 24 • ATmega324PB (44 pins): up to 32 touch channels Figure 5-5. Self-capacitance Sensor Arrangement Figure 5-6. Self-capacitance Channel to Sensor Mapping Y sense line can be specified using the configuration parameter DEF_SELFCAP_LINES in non-sequential order. The channel numbering is done in the same order as the Y sense line specified in the configuration parameter DEF_SELFCAP_LINES. Setting Configuration Name Data Type Unit Min Max Typical Self Cap touch channel nodes DEF_SELFCAP_NODES uint16_t array None 1 Yline 32 Yline - Self Cap number of channels DEF_SELFCAP_NUM_CHANNELS uint16_t None 1 Yline 32 Yline - Self Cap number of Sensors DEF_SELFCAP_NUM_SENSORS uint16_t None 1 Yline 32 Yline - Self Cap number of Rotors and Sliders DEF_SELFCAP_NUM_ROTORS_SLIDERS uint8_t None 0 Yline 10 Yline - Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 25 The touch sensors must be enabled in the sequential order of the channels specified using the touch_xx_sensor_config() API. For improved EMC performance, a series resistor with value of 1 Kilo-ohm must be used on X and Y lines. For more information about designing the touch sensor, refer to Buttons, Sliders and Wheels Touch Sensor Design Guide available at www.atmel.com. 5.2.2. Sensor Individual Parameters This section explains the settings that are specific to the individual sensor. Detect Threshold A sensor's detect threshold defines how much its signal must increase above its reference level to qualify as a potential touch detect. However, the final detection confirmation must satisfy the Detect Integrator (DI) limit. Larger threshold values desensitize sensors since the signal must change more (i.e. requires larger touch) to exceed the threshold level. Conversely, lower threshold levels make sensors more sensitive. Threshold setting depends on the amount of signal swing when a sensor is touched. Usually, thicker front panels or smaller electrodes have smaller signal swing on touch, thus require lower threshold levels. Typically, detect threshold isset to 50% of touch delta. Desired touch delta for a buttons is ~30 to 80 counts and for wheels or sliders is ~50 to 120 counts. Setting Configuration Name Data Type Unit Min Max Typical Threshold detect_threshold threshold_t Counts 3 255 20-50(For buttons) 30-80(For sliders and wheels Detect Hysteresis This setting is sensor detection hysteresis value. It is expressed as a percentage of the sensor detection threshold setting. Once a sensor goes into detect its threshold level is reduced (by the hysteresis value) in order to avoid the sensor dither in and out of detect if the signal level is close to original threshold level. • Setting of 0 = 50% of detect threshold value (HYST_50) • Setting of 1 = 25% of detect threshold value (HYST_25) • Setting of 2 = 12.5% of detect threshold value (HYST_12_5) • Setting of 3 = 6.25% of detect threshold value (HYST_6_25) Setting Configuration Name Data Type Unit Min Max Typical Hysteresis detect_threshold uint8_t (2bits) Enum HYST_6_25 HYST_50 HYST_6_25 Position Resolution The rotor or slider needs the position resolution (angle resolution in case of rotor and linear resolution in case of slider)to be set. Resolution is the number of bits needed to report the position of rotor or slider. It can have values from 2 bits to 8 bits. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 26 Setting Configuration Name Data Type Unit Min Reported Position Max Reported Position Typical Position Resolution position_resolution uint8_t (3bits) None 2bits 0-3 8bits 0-255 8 Position Hysteresis In case of Mutual Cap, the rotor or slider needs the position hysteresis (angle hysteresis in case of rotor and linear hysteresis in case of slider) to be set. It is the number of positions the user has to move back, before touch position is reported when the direction of scrolling is changed and during the first scrolling after user press. Hysteresis can range from 0 (1 position) to 7 (8 positions). The hysteresis is carried out at 8 bits resolution internally and scaled to desired resolution; therefore at resolutions lower than 8 bits there might be a difference of 1 reported position from the hysteresis setting, depending on where the touch is detected. At lower resolutions, where skipping of the reported positions is observed, hysteresis can be set to 0 (1 position). At Higher resolutions (6 to 8bits), it would be recommended to have a hysteresis of at least 2 positions or more. Note:  It is not valid to have a hysteresis value more than the available bit positions in the resolution. For instance, a hysteresis value of 5 positions with a resolution of 2 bits (4 positions) is invalid. Position hysteresis is invalid (unused) in case of self-capacitance method sensors. Setting Configuration Name Data Type Unit Min Max Typical Position Hysteresis position_hysteresis uint8_t (3bits) - 0 7 8 Adjacent Key Suppression (AKS® ) In designs where the sensors are close together or configured for high sensitivity, multiple sensors might report a detect simultaneously. To allow applications to determine the intended single touch, the touch library provides the user the ability to configure a certain number of sensors in an AKS group. When a group of sensors are in the same AKS group, only the first strongest sensor will report detection. The sensor reporting detection will continue to report detection even if another sensor's delta becomes stronger. The sensor stays indetect until its delta falls lower than its detection threshold. If any more sensors in the AKS group are still in detect onlythe strongest will report detection. At a given time point, only one sensor from each AKS group is reported to be indetect. AKS feature can be enabled or disabled using a macro DEF_XXXXCAP_AKS_ENABLE • 1u = AKS grouping functionality is enabled • 0u = AKS grouping functionality is disabled The library provides the ability to configure a sensor to belong to one of the Adjacent Key Suppression Groups (AKS Group). Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 27 5.2.3. Sensor Global Parameters This section explains the settings that are common all sensors. For instance, if recalibration threshold (one of the global settings) of mutual cap sensors is set as RECAL_100, all mutual capacitance sensors will be configured for a recalibration threshold of 100%.These sensor global parameter settings can be independently set to self-capacitance and mutual capacitance sensors. Detect Integration The QTouch Library features a detect integration mechanism, which confirm detection in a robust environment. The detect integrator (DI) acts as a simple signal filter to suppress false detections caused by spurious events such as electrical noise. A counter is incremented each time the sensor delta has exceeded its threshold and stayed there for a specific numberof acquisitions, without going below the threshold levels. When this counter reaches a preset limit (the DI value) the sensor is finally declared to be touched. If on any acquisition the delta is below the threshold level, the counter is cleared and the process has to start from the beginning. The DI process is applicable to a 'release' (going out of detect) event as well. For example, if the DI value is 10, the device has to exceed its threshold and stay there for (10 + 2) successive acquisitions without going below the threshold level, before the sensor is declared to be touched. Setting Configuration Name Data Type Unit Min Max Typical DI DEF_MUTLCAP_DI, DEF_SELFCAP_DI uint8_t Cycles 0 255 4 Max-ON Duration If an object unintentionally contacts a sensor resulting in a touch detection for a prolonged interval it is usually desirable to recalibrate the sensor in order to restore its function, after a time delay of a few seconds. The Maximum ON duration timer monitors such detections; if detection exceeds the timer's settings, the sensor is automatically recalibrated. After a recalibration has taken place, the affected sensor once again functions normally even if it still in contact with the foreign object. Max-ON duration can be disabled by setting it to zero (infinite timeout) in which case the channel never recalibrates during a continuous detection (but the host could still command it). Setting Configuration Name Data Type Unit Min Max Typical Maximum ON Duration DEF_MUTLCAP_MAX_ON_DURATION, DEF_SELFCAP_MAX_ON_DURATION uint8_t 200ms 0 255 30(6s) Away from Touch and Towards Touch Drift Rate Drift in a general sense means adjusting reference level (of a sensor) to allow compensation for temperature (or other factor) effect on physical sensor characteristics. Decreasing reference level for such compensation is called Negative drift & increasing reference level is called Positive drift. Specifically, the drift compensation should be set to compensate faster for increasing signals than for decreasing signals. Signals can drift because of changes in physical sensor characteristics over time and temperature. It is crucial that such drift be compensated for; otherwise false detections and sensitivity shifts can occur. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 28 Drift compensation occurs only while there is no detection in effect. Once a finger is sensed, the drift compensation mechanism ceases since the signal is legitimately detecting an object. Drift compensation works only when the signal inquestion has not crossed the 'Detect threshold' level. The drift compensation mechanism can be asymmetric. It can be made to occur in one direction faster than it does in the other simply by changing the appropriate setup parameters. Signal values of a sensor tend to increase when an object (touch) is approaching it or a characteristic change of sensor over time and temperature. Increasing signals should not be compensated quickly, as an approaching finger could be compensated for partially or entirely before even touching the channel (towards touch drift). However, an object over the channel which does not cause detection, and for which the sensor has already made full allowance (over some period of time), could suddenly be removed leaving the sensor with an artificially suppressed reference level and thus become insensitive to touch. In the latter case, the sensor should compensate for the object's removal by raising the reference level relatively quickly (away from touch drift). Setting Configuration Name Data Type Unit Min Max Typical Towards touch Drift DEF_MUTLCAP_TCH_DRIFT_RATE, DEF_SELFCAP_TCH_DRIFT_RATE uint8_t 200ms 0 127 20(4s) Away from touch Drift DEF_MUTLCAP_ATCH_DRIFT_RATE, DEF_SELFCAP_ATCH_DRIFT_RATE uint8_t 200ms 0 127 5(1s) Drift Hold Time Drift Hold Time (DHT) is used to restrict drift on all sensors while one or more sensors are activated. It defines the length of time the drift is halted after a key detection.This feature is useful in cases of high density keypads where touching a key or floating a finger over the keypad would cause untouched keys to drift, and therefore create a sensitivity shift, and ultimately inhibit any touch detection. Setting Configuration Name Data Type Unit Min Max Typical Drift Hold Time DEF_MUTLCAP_DRIFT_HOLD_TIME, DEF_SELFCAP_DRIFT_HOLD_TIME uint8_t 200ms 0 255 20(4s) Away From Touch Recalibration Threshold Recalibration threshold is the level beyond which automatic recalibration occurs. Recalibration threshold is expressed as a percentage of the detection threshold setting. This setting is an enumerated value and its settings are as follows: • Setting of 0 = 100% of detect threshold (RECAL_100) • Setting of 1 = 50% of detect threshold (RECAL_50) • Setting of 2 = 25% of detect threshold (RECAL_25) • Setting of 3 = 12.5% of detect threshold (RECAL_12_5) • Setting of 4 = 6.25% of detect threshold (RECAL_6_25) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 29 However, an absolute value of 4 is the hard limit for this setting. For example, if the detection threshold is, 40 and the Recalibration threshold value is set to 4. Although this implies an absolute value of 2 (40 * 6.25% = 2.5), it is hard limited to 4. Setting Configuration Name Data Type Unit Min Max Typical Recalibration threshold DEF_MUTLCAP_ATCH_RECAL_THRESHOLD, DEF_SELFCAP_ATCH_RECAL_THRESHOLD uint8_t Enum RECAL_6_25 Detect threshold RECAL_100 Away From Touch Recalibration Delay If any key is found to have a significant negative delta, it is deemed to be an error condition. If this condition persists for more than the away from touch recalibration delay, i.e., qt_pos_recal_delay period, then an automatic recalibration is carried out. A counter is incremented each time the sensor delta is equal to the away from touch recalibration threshold and stayed there for a specific number of acquisitions. When this counter reaches a preset limit (the PRD value) the sensor is finally recalibrated. If on any acquisition the delta is seen to be greater than the away from touch recalibration threshold level, the counter is cleared and the away from touch drifting is performed. For example, if the away from touch recalibration delay setting is 10, then the delta has to drop below the recalibration threshold and stay there for 10 acquisitions in succession without going below the threshold level, before the sensor is declared to be recalibrated. Away from touch recalibration can be disabled with a setting of 0. Setting Configuration Name Data Type Unit Min Max Typical Away from touch Recalibration Delay DEF_MUTLCAP_ATCH_RECAL_DELAY, DEF_SELFCAP_ATCH_RECAL_DELAY uint8_t Cycles 0 255 10 Sensor Post-Processing Mode When TOUCH_LIBRARY_DRIVEN mode is selected, the library self-initiates repeated touch measurements to resolve touch press, release and calibration. This mode is suited for best response time. When TOUCH_APPLN_DRIVEN mode is selected, the library does not initiate repeated touch measurement to resolve touch press, release and calibration. This mode suits deterministic PTC interrupt execution time for applications requiring stringent CPU time requirements. As repeated touch measurements are delayed due to other critical application code being executed. This mode can potentially affect the touch response time. In order to improve the touch response time with the TOUCH_APPLN_DRIVEN mode, the touch_xxxcap_sensors_measure API call should be modified as below to initiate touch measurements periodically or when the burst again acquisition status flag has been set. if ((touch_time.time_to_measure_touch == 1u) ||(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN) { /* Start a touch sensors measurement process. */ touch_ret = touch_mutlcap_sensors_measure(touch_time.current_time_ms,NORMAL_ACQ_MODE,touch_mutlcap_measure Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 30 _complete_callback); } Setting Configuration Name Data Type Options Typical Sensor postprocessing mode DEF_MUTLCAP_TOUCH_POSTPROCESS_MODE, DEF_SELFCAP_TOUCH_POSTPROCESS_MODE uint16_t TOUCH_LIBRARY_DR IVEN, TOUCH_APPLN_DRIV EN TOUCH_LIBRARY_DRIVEN Charge Share Delay Charge share delay indicates the number of additional charge cycles that are inserted within a capacitance measurement cycle to ensure that the touch sensor is fully charged. The CSD value is dependent on the sensor capacitance along with the series resistor on the Y line. Note:  Any increase in the charge share delay also increases the measurement time for a specific configuration. When manual tuning is performed, the CSD value for the sensor with largest combination of capacitance along with series resistance should be considered. Setting Configuration Name Data Type Options Min Max Typical CSD (Charge Share Delay) DEF_MUTL_CAP_CSD_VALUE, DEF_SELF_CAP_CSD_VALUE uint8_t PTC cycles 0 250 0 How to tune the CSD setting manually? 1. Initially, use an arbitrarily large value such as 64 and note the signal value. A large value ensures that the charge time is enough for full charge transfer 2. Reduce the CSD and verify the signal value drop, until signal is approximately 97-98% of the value used initially. This ensures a good charge transfer without any major loss in the signal. 3. Continue the same procedure [Step 1 and 2] for all the sensors available in the system. Use the largest value of the CSD used in the system for the global setting. Note:  For the same CSD setting, Mutual capacitance has a lower burst time than self-capacitance. A unit increase in mutual capacitance CSD consumes around 12 PTC cycles. Whereas for the selfcapacitance an increase in CSD consumes approximately twice the mutual capacitance CSD time with the same setting. Auto-OS Signal Stability Limit The parameter DEF_XXXXCAP_AUTO_OS_SIGNAL_STABILITY_LIMIT defines the stability limit of the signals for performing over-samples. Stability limit is the variance in sensor signal value under noisy environment. A high level of stability limit is set to auto trigger oversamples on large noise presence. It is recommended to keep this setting close to the lowest sensor detect threshold of the system and tune it further based on the noise. Range: 1 to 1000 5.2.4. Sensor Acquisition Parameters Filter Level The filter level setting controls the number of samples taken to resolve each acquisition. A higher filter level setting provides improved signal to noise ratio under noisy conditions, while increasing the total time Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 31 for measurement resulting in increased power consumption and response time. This setting is available on per channel basis, allowing easy tuning. Setting Configuration Name Data Type Options Min Max Typical Filter level DEF_MUTLCAP_FILTER_LEVEL_PER_NODE, DEF_SELFCAP_FILTER_LEVEL_PER_NODE filter_level_t Number of samples 1 64 16 Auto Oversamples Auto oversample controls the automatic oversampling of sensor channels when unstable signals are detected with the default setting of 'Filter level'. Enabling Auto oversample results in 'Filter level' x 'Auto Oversample' number of samples taken on the corresponding sensor channel when an unstable signal is observed. In a case where 'Filter level' is set to FILTER_LEVEL_4 and 'Auto Oversample' is set to AUTO_OS_4, 4 oversamples are taken with stable signal values and 16 oversamples are taken when unstable signal is detected. This setting is available on per channel basis, allowing easy tuning. A higher filter level setting provides improved signal to noise ratio under noisy conditions, while increasing the total time for measurement resulting in increased power consumption and response time. Figure 5-7. Auto oversamples Auto oversamples can be disabled to obtain best power consumption. Setting Configuration Name Data Type Options Min Max Typical Auto Oversamples DEF_MUTLCAP_AUTO_OS_PER_NODE, DEF_SELFCAP_AUTO_OS_PER_NODE auto_os_t Sample multiplier 2 128 AUTO_OS_NONE Gain Setting Gain setting is applied on a per-channel basis to allow a scaling-up of the touch delta upon contact. Gain setting depends on the sensor design and touch panel thickness. Setting Configuration Name Data Type Options Min Max Typical Gain DEF_MUTLCAP_GAIN_PER_NODE, DEF_SELFCAP_GAIN_PER_NODE gain_t Gain multiplier 1 32 1 (For selfcapacitance) 4 (For mutual capacitance) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 32 The figure shows the expected signal value for a given combination of gain setting and filter level setting. The values provided are only indicative and the actual sensor signal values might be close to the suggested levels. Figure 5-8. Average Settling Signal Value for FILTER LEVEL and GAIN Combination Prescalar Setting The prescaler parameter denotes the clock divider for the particular channel. It can be set on per channel basis and is independent to each sensor node/channel. This parameter is auto tuned based on the auto tune settings. Tuning this parameter allows for improved noise performance. Setting Configuration Name Data Type Options Min Max Typical Prescalar DEF_MUTLCAP_CLK_PRESCALE_PER_NODE, DEF_SELFCAP_CLK_PRESCALE_PER_NODE prsc_div_sel_t PRSC_DIV_SEL_1, PRSC_DIV_SEL_2, PRSC_DIV_SEL_4, PRSC_DIV_SEL_8 PRSC_DIV_SEL_1 PRSC_DIV_SEL_8 PRSC_DIV_SEL_1 Series Resistor Setting The series resistor denotes the resistor used on the particular channel for the acquisition. The value is tunable and allows both auto and manual tuning options. Tuning this parameter allows for improved noise performance. Settin g Configuration Name Data Type Options Min Max Typical Series Resist or DEF_MUTLCAP_SENSE_RESI STOR_PER_NODE DEF_SELFCAP_SENSE_RESI STOR_PER_NODE rsel_val_t RSEL_VAL_0, RSEL_VAL_20, RSEL_VAL_50, RSEL_VAL_100 RSEL_VAL_0 RSEL_VAL_100 RSEL_VAL_100 Boot Prescalar Setting The boot prescaler parameter denotes the clock divider for the particular channel. It can be set on per channel basis and is independent to each sensor node/channel. This setting is used for calibrating the sensors after a power-on. This parameter must be configured as the auto tune is not available. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 33 Setting Configuration Name Data Type Options Min Max Typical Boot Prescalar DEF_MUTLCAP_CC_CAL_CLK_PRESCALE_PER_NODE, DEF_SELFCAP_CC_CAL_CLK_PRESCALE_PER_NODE prsc_div_sel_t PRSC_DIV_SEL_1, PRSC_DIV_SEL_2, PRSC_DIV_SEL_4, PRSC_DIV_SEL_8 PRSC_DIV_SEL_1 PRSC_DIV_SEL_8 PRSC_DIV_SEL_1 Boot Series Resistor Setting The boot series resistor denotes the resistor used on the particular channel on device power-on calibration. This parameter must be configured as the auto tune is not available. Setting Configuration Name Data Type Options Min Max Typical Boot Series Resistor DEF_MUTLCAP_CC_CAL_SENSE_RESISTOR_PER_NODE DEF_SELFCAP_CC_CAL_SENSE_RESISTOR_PER_NODE rsel_val_t RSEL_VAL_0, RSEL_VAL_20, RSEL_VAL_50, RSEL_VAL_100 RSEL_VAL_0 RSEL_VAL_100 RSEL_VAL_100 Frequency Mode Frequency mode setting allows users to tune the PTC touch acquisition frequency characteristics to counter environment noise. FREQ_MODE_HOP When frequency mode hopping option is selected, the PTC runs a frequency hopping cycle with subsequent measurements done using the three PTC acquisition frequency delay settings as specified in DEF_SELFCAP_HOP_FREQS. In this case, an additional software median filter is applied to the measured signal values. FREQ_MODE_SPREAD When frequency mode spread spectrum option is selected, the PTC runs with spread spectrum enabled for jittered delay based acquisition. FREQ_MODE_SPREAD_MEDIAN When frequency mode spread spectrum median option is selected, the PTC runs with spread spectrum enabled. In this case, an additional software median filter is applied to the measured signal values. FREQ_MODE_NONE When frequency mode none option is selected, the PTC runs at constant speed. This mode is suited for best power consumption. Setting Configuration Name Data Type Options Min Max Typical Frequency mode DEF_MUTLCAP_FREQ_MODE , DEF_SELFCAP_FREQ_MODE freq_mode_sel_t FREQ_MODE_NONE, FREQ_MODE_HOP, FREQ_MODE_SPREAD, FREQ_MODE_SPREAD_MEDIAN FREQ_MODE_NONE FREQ_MODE_SPREAD_MEDIAN FREQ_MODE_NONE Frequency Hop Delay The frequency hop delay setting is used when the Frequency mode is set to FREQ_MODE_HOP. A set of three frequency hop delay settings should be specified. This delay setting inserts n PTC clock cycles between consecutive measurements on a given sensor, thereby changing the PTC acquisition frequency. FREQ_HOP_SEL_1 setting inserts 0 PTC clock cycle between consecutive measurements. FREQ_HOP_SEL_16 setting inserts 15 PTC clock cycles. Hence, higher delay setting will increase the total time taken for capacitance measurement on a given sensor as compared to a lower delay setting. A desired setting can be used to avoid noise around the same frequency as the acquisition frequency. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 34 Setting Configuration Name Data Type Unit Min Max Typical Frequency hop delay DEF_MUTLCAP_HOP_FREQS, DEF_SELFCAP_HOP_FREQS freq_hop_sel_t nPTC_clock_cycles FREQ_HOP_SEL_1 FREQ_HOP_ SEL_16 FREQ_HOP_SEL_1, FREQ_HOP_SEL_2, FREQ_HOP_SEL_3 5.2.5. Sensor Calibration Auto Tune Setting Auto tune parameter setting is passed to the touch_xx_sensors_calibrate API in order to allow users to tune the PTC module for power consumption or noise performance. AUTO_TUNE_PRSC When Auto tuning of pre-scaler is selected, the PTC uses the user defined internal series resistor setting (DEF_XXXXCAP_SENSE_RESISTOR_PER_NODE ) and the pre-scaler is adjusted to slow down the PTC operation to ensure full charge transfer. Auto tuning of pre-scaler with RSEL_VAL_100 as the series resistor results in least power consumption while resulting in increased power consumption and touch response time. AUTO_TUNE_RSEL When Auto tuning of the series resistor is selected, the PTC runs at user defined pre-scaler setting speed (DEF_XXXXCAP_CLK_PRESCALE_PER_NODE) and the internal series resistor is tuned automatically to the optimum value to allow for full charge transfer. Auto tuning of series resistor with PRSC_DIV_SEL_1 as the PTC pre-scale results in best case power consumption. AUTO_TUNE_NONE When manual tuning option is selected, the user defined values of PTC pre-scaler and series resistor is used for PTC operation as given in DEF_XXXXCAP_CLK_PRESCALE_PER_NODE and DEF_XXXXCAP_SENSE_RESISTOR_PER_NODE Setting Configuration Name Data Type Unit Values Typical Auto tune Provided to touch_xxcap_sensors_calibrate API input auto_tune_type_t None AUTO_TUNE_NONE, AUTO_TUNE_PRSC,AU TO_TUNE_RSEL AUTO_TUNE_NONE 5.2.6. Sensor Noise Measurement and Lockout Parameters Noise is measured on a per-channel basis after each channel acquisition, using historical data on a rolling window of successive measurements. Reported noise to exclude the instance of an applied or removed touch contact, but the noise indication must react sufficiently fast that false touch detection before noise lockout is prevented. Signal change from sample to sample during the window buffer is compared to the stability limit. Noise is reported only when two changes occur within the window period and both of which exceed the DEF_XXXXCAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT limit. Noise is calculated using the following algorithm: if (swing count > 2) { Nk = ((|Sn – Sn-1| > DEF_XXXXCAP_NOISE_MEAS_SIGNAL_STABILITY))?(0):(|Sn-Sn-1|- DEF_XXXXCAP_NOISE_MEAS_SIGNAL_STABILITY)) } else { Nk = 0 } Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 35 The swing count is number of signal changes that exceed DEF_MUTLCAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT limit during buffer window period. When the measured noise exceeds DEF_MUTLCAP_NOISE_LIMIT, the touch library locks out sensors, reports no touch detection and drifting is stopped. Noise measurement is provided for all the channels. Each byte in p_xxxxcap_measure_data-> p_nm_ch_noise_val provides the noise level associated with that channel. Noise indication is provided for all the sensors configured by the application. A bit is available in p_xxxxcap_measure_data-> p_sensor_noise_status for each sensor to determine whether the sensor is noisy or not. The following code snippet provides the sample code to read the noise status of a particular sensor. Figure 5-9. Noise Calculation Noise Measurement Signal Stability Limit Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 36 The parameter DEF_XXXXAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT is the variance in sensor signal value under noisy environment. Any noise level over and above the noise signal stability limit contributes to the Noise limit. It is recommended to keep this setting close to the lowest sensor detect threshold of the system and tune it further based on the noise. Signal values can change from sample to sample during a window buffer period. The difference between adjacent buffer value is compared to the user configured stability limit. Noise is reported only when two changes occur within the specified window period and only if both of which exceed the stability limit. Range: 1 to 1000 Noise Limit The DEF_XXXXCAP_NOISE_LIMIT specifies the limit to the total noise accumulated over the noise buffer count. If the accumulated noise exceeds the noise limit, then lockout is triggered. There are two purposes for this parameter: • If the noise level calculated during a running window exceeds DEF_XXXXCAP_NOISE_LIMIT, then the corresponding sensor are declared noisy and sensor global noisy bit is set as '1'. • If the noise level calculated during a running window exceeds DEF_XXXXCAP_NOISE_LIMIT, then system triggers the sensor lockout functionality. Range: 1 to 255 Noise Measurement Buffer Count The DEF_XXXXCAP_NOISE_MEAS_BUFFER_CNT parameter is used to select the buffer count for noise measurement buffer. Range: 3 to 10 (If N number of samples differences have to be checked, define this parameter as "N + 1") If N = 4 then set DEF_XXXXCAP_NOISE_MEAS_BUFFER_CNT as 5u. Sensor Lockout Selection This feature locks out the sensors when the measured noise exceeds DEF_XXXXCAP_NOISE_LIMIT and does not report a touch. This prevents post-processing. So, the high level of noise cannot cause the channel to report false touch drift or recalibrate incorrectly. The DEF_XXXXCAP_LOCKOUT_SEL parameter is used to select the lockout functionality method. • If DEF_XXXXCAP_LOCKOUT_SEL is set to SINGLE_SENSOR_LOCKOUT and a sensor's noise level is greater than DEF_XXXXCAP_NOISE_LIMIT, then corresponding sensor is locked out from touch detection and drifting is disabled. • If DEF_XXXXCAP_LOCKOUT_SEL is set to GLOBAL_SENSOR_LOCKOUT and any sensor's noise level is greater than DEF_XXXXCAP_NOISE_LIMIT, then all sensors are locked out from touch detection and drifting is disabled. • If DEF_XXXXCAP_LOCKOUT_SEL is set to NO_LOCKOUT, then lockout feature is disabled. Note:  Global sensors noisy bit will be available for SINGLE_SENSOR_LOCKOUT and GLOBAL_SENSOR_LOCKOUT. Global sensors noisy bit will not be available for NO_LOCK_OUT. Range: 0 to 2 Sensor Lockout Countdown Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 37 If the sensor signal moves from noisy to a good condition and stays there for a DEF_XXXXCAP_ LOCKOUT_CNTDOWN number of measurements, the sensor is unlocked and sensors are ready for touch detection and drifting is enabled. Note:  This parameter is valid only for global lockout. Range: 1 to 255 5.2.7. Sensor Acquisition Frequency Auto Tuning Parameters The Frequency Auto Tune feature provides the best quality of signal data for touch detection by automatically selecting acquisition frequencies showing the best SNR in FREQ_MODE_HOP mode. During each measurement cycle, the signal change since the last acquisition at the same frequency is recorded for each sensor. After the cycle, when all sensors have been measured at the present acquisition frequency, the largest signal variation of all sensors is stored as the variance for that frequency stage. The variance for each frequency stage is compared to the DEF_XXXXCAP_FREQ_AUTO_SIGNAL_ STABILITY_LIMIT limit, and if the limit is exceeded, a per-stage counter is incremented. If the measured variance is lower than the limit, the counter is decremented, if it has not been set as zero. If all frequencies display noise exceeding the stability limit, only the counter for the specific frequency stage with the highest variance is incremented after its cycle. When a frequency counter reaches the DEF_XXXXCAP_FREQ_AUTO_TUNE_IN_CNT (auto-tune count in variable), that frequency stage is selected for auto-tuning. A new frequency selection is applied and the counters and variances for all frequencies are reset. After a frequency has been selected for auto-tuning, the count-in for that frequency stage is set to half the original count-in and the process is repeated until either all frequencies have been measured or a frequency is selected which does not re-trigger autotuning is determined. If all frequencies have been tested, and the variation exceeds the DEF_XXXXCAP_FREQ_AUTO_SIGNAL_STABILITY_LIMIT limit then the frequency with the lowest variance is selected for the frequency stage currently under tuning. The auto-tune process is re-initialized and further tuning does not take place until a frequency stage's high variance counter again reaches the count in limit. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 38 Figure 5-10. Frequency Auto Tune Frequency Auto Tune Signal Stability The DEF_XXXXCAP_FREQ_AUTO_SIGNAL_STABILITY_LIMIT is the variance in sensor signal value under noisy environment. A signal stability limit level is set to auto tune acquisition frequency on noise presence. It is recommended to keep this setting close to the lowest sensor detect threshold of the system and tune it further based on the noise. Range: 1 to 1000 Frequency Auto Tune in Counter The DEF_XXXXCAP_FREQ_AUTO_TUNE_IN_CNT parameter is used to trigger the frequency auto tune.If sensor signal change at each frequency exceeds the value specified as DEF_XXXXCAP_FREQ_AUTO_SIGNAL_STABILITY_LIMIT for DEF_XXXXCAP_FREQ_AUTO_TUNE_IN_CNT, then frequency auto tune will be triggered at this frequency. Range: 1 to 255 Note:  The Frequency Auto Tune feature and related parameters are available only in FREQ_MODE_HOP mode. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 39 5.2.8. Quick Re-burst Parameter Quick Reburst This macro is used to enable or disable quick re-burst feature. When Quick re-burst is enabled, upon user touch and release, only that touched sensor or channel is subsequently measured to resolve detect integration (or debounce). Enabling this feature results in best touch response time. When Quick re-burst is disabled, upon user touch and release, all sensors or channels are measured to resolve detect integration (or debounce). This feature should only be disabled when developing any special application involving all sensor measurements during user activity. Within an AKS (Adjacent Key suppression) group, all the sensors within that group are measured during user touch independent of this feature being enabled or disabled. 5.2.9. Common Parameters Measurement Period The measurement period setting is used to set the periodic interval for touch sensor measurement. The minimum measurement period setting should be greater than the time taken to complete measurement on all sensors. This can be simply determined by calling the touch_xx_sensors_measure API in a while loop and then toggling a GPIO pin in the measurement complete callback. main() { while(1) { touch_ret = touch_mutlcap_sensors_measure(touch_time.current_time_ms,NORMAL_ACQ_MODE,touch_mutlcap_measure _complete_callback); } } void touch_mutlcap_measure_complete_callback( void ) { if (!(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { /* Set the Mutual Cap measurement done flag. */ p_mutlcap_measure_data->measurement_done_touch = 1u; port_pin_toggle_output_level(PIN_PB00); } } Setting Configuration Name Data Type Unit Values Max Typical Sensor measurement interval DEF_TOUCH_MEASUREMENT_PERIOD_MS uint16_t millisecond Should be found through GPIO pin toggle procedure. 65535 20 PTC Interrupt Priority Level The Nested Vectored Interrupt Controller (NVIC) in the SAM has four different priority levels. The priority level of thePTC end of conversion ISR can be selected based on application requirements to accommodate time critical operations. Setting the PTC interrupt priority level to lowest can have an impact on the touch response time, depending on the execution time taken by other higher priority interrupts. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 40 Setting Configuration Name Data Type Unit Min Max Typical PTC interrupt priority level DEF_TOUCH_PTC_ISR_LVL uint8_t None 0 (Highest Priority) 3 (Lowest Priority) 3 To avoid stack overflow, ensure that adequate stack size has been set in the user application.This configuration is applicable only for SAM devices. touch_suspend_app_cb Callback function pointer that must be initialized by the application before a touch library API is called. Touch library would call the function pointed by this function when suspension operation has to be carry on by the application. Setting Configuration Name Data Type Returns Suspend Callback touch_suspend_app_cb void(* volatile touch_suspend_app_cb) (void) void Low power Sensor Event Periodicity When the CPU returns to standby mode from active, the sensor configured as the low power sensor is scanned at this interval. A high value for this parameter will reduce power consumption but increase response time for a low power sensor. The following macros are used for configuring the low power sensor event periodicity: • The macro LOWPOWER_PER0_SCAN_3_P_9_MS sets the scan rate at 3.9ms • The macro LOWPOWER_PER1_SCAN_7_P_8_MS sets the scan rate at 7.8ms • The macro LOWPOWER_PER2_SCAN_15_P_625_MS sets the scan rate at 15.625ms • The macro LOWPOWER_PER3_SCAN_31_P_25_MS sets the scan rate at 31.25ms • The macro LOWPOWER_PER4_SCAN_62_P_5_MS sets the scan rate at 62.5ms • The macro LOWPOWER_PER5_SCAN_125_MS sets the scan rate at 125ms • The macro LOWPOWER_PER6_SCAN_250_MS sets the scan rate at 250ms • The macro LOWPOWER_PER7_SCAN_500_MS sets the scan rate at 500ms Low power Sensor Drift Periodicity This parameter configures the scan interval for a single active measurement during low power mode. This active measurement is required for reference tracking of low power sensor. Setting Configuration Name Data Type Unit Min Max Typical Low power sensor drift rate DEF_LOWPOWER_SENSOR_DRIFT_PERIODICITY_MS uint16_t milliseconds 0 65535 2000 Low power sensor ID Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 41 The macro DEF_LOWPOWER_SENSOR_ID is used to configure a sensor as low power sensor. Only one sensor can be configured as low power sensor. Low power sensor can be a normal sensor or a lumped sensor. 5.2.10. Moisture Parameters Moisture Tolerance Enable The macro DEF_XXXXCAP_MOIS_TOLERANCE_ENABLE is used to Enable or disable Moisture detection feature. Moisture Quick Reburst The macro DEF_XXXXCAP_MOIS_QUICK_REBURST_ENABLE is used to enable or disable quick re-burst feature within a given moisture group. When enabled, if within a given moisture group, when any sensor is touched, repeated measurements are done only that sensor to resolve detect integration or de-bounce. When disabled, if within a given moisture group, when any sensor is touched, repeated measurements are done on all sensors within the moisture group to resolve detect integration or de-bounce. It is recommended to enable this feature for best touch response time. Moisture groups The macro DEF_XXXXCAP_NUM_MOIS_GROUPS specifies the total number of individual moisture group present the system. 5.2.11. PTC Lines Ground Feature PTC GPIO State The macro DEF_XXXXCAP_PTC_GPIO_STATE is used to set the unmeasured self/mutual capacitance PTC lines to Ground / Vcc in between PTC measurement cycle. Setting the PTC lines to GND_WHEN_NOT_MEASURED will set the state of the pin to low whenever the pin is unmeasured. Setting the PTC lines to PULLHIGH_WHEN_NOT_MEASURED will make the PTC lines to float in between sensor measurement in a measurement cycle. It is recommended to set GND_WHEN_NOT_MEASURED configuration to get low power. 5.3. Moisture Tolerance Moisture tolerance check executes at the end of each measurement cycle and compares the sum of delta of all sensors in a moisture tolerance group against pre-configured threshold. If delta sum is greater than sensor moisture lock threshold and less than system moisture lock threshold, then the ON-state sensors within moisture tolerance group will be considered as moisture affected. If delta sum is greater than system moisture lock threshold, all sensors within the moisture tolerance group will be considered as moisture affected. This condition is referred as moisture global lock out. The library will come out of the moisture global lock out state when delta sum is less than threshold for 5 consecutive measurements. Self cap and mutual cap sensors cannot be configured in a single moisture group, Self cap moisture tolerance and mutual cap Moisture tolerance features can be enabled or disabled separately. Note:  Lumped sensor and the sensor which is part of the specific lump should not be assigned to same moisture group. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 42 Figure 5-11. Moisture Tolerance Algorithm 5.3.1. Moisture Tolerance Group This feature enables the customer application to group a set of sensors in to single moisture tolerance group. If moisture on one sensor might affect other sensors due to physical proximity, they must be grouped together into one Moisture tolerance group. Using this feature the application can disable moisture tolerance detection for a set of sensors, Multiple Moisture tolerance groups can be formed by the customer application. The library supports up to a maximum of 8 moisture groups. Note:  Changing the moisture tolerance group configuration during runtime is not recommended. However, muti-touch group configuration can be changed during runtime. 5.3.2. Multi-touch Group If the user wants to touch multiple sensors within the moisture tolerance group simultaneously to indicate a specificrequest, then the application should configure those sensors into single multi-touch group. Multiple multi-touch groups can be formed by the customer application. The library supports a maximum of 8 multi-touch groups within a single moisture tolerance group. Moisture tolerance feature improves a system’s performance under the following scenarios: • Droplets of water sprayed on the front panel surface • Heavy water poured on the front panel surface • Large water puddle on multiple sensors Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 43 • Trickling water on multiple sensors Moisture tolerance feature is not expected to offer any significant performance improvement under the following scenarios: • Large isolated puddle on single sensor • Direct water pour on single sensor Within the same moisture group, user should not configure all the sensors to the single multi-touch group. 5.4. Reading Sensor States When noise immunity and moisture tolerance features are enabled the validity of the sensor sate is based on the moisture status and noise status. Refer Noise Counter Measures and Moisture Parameters for information on noise immunity and moisture tolerance status of sensors. The state of a sensor is valid only when the sensor is not affected by noise and moisture. If a sensor is noisy or affected by moisture, then the state of sensor must be considered as OFF. The code snippet below depicts the same for mutual-cap sensors. When a sensor is touched or released during DI, library will burst on channels corresponding to sensors whose state is other than OFF or DISABLED. If any sensor in an AKS group is in a state other than OFF or DISABLED, the library will burst channels corresponding sensors belong to that AKS group. If a sensor in any moisture group is in a state other than OFF or DISABLED, the library will burst on channels corresponding to sensors belonging to that moisture group. if(! (GET_MUTLCAP_SENSOR_NOISE_STATUS(SENSOR_NUMBER))) { if(! (GET_MUTLCAP_SENSOR_MOIS_STATUS (SENSOR_NUMBER))) { /*Sensor state is valid Read sensor state */ } else { /* Sensor is Moisture affected*/ } } else { /* Sensor is noisy */ } 5.5. Application Flow 5.5.1. Application Flow SAM The application periodically initiates a touch measurement on either mutual capacitance or selfcapacitance sensors. At the end of each sensor measurement, the PTC module generates an end of conversion (EOC) interrupt. The touch measurement is performed sequentially until all the sensors are measured. Additional post-processing is performed on the measured sensor data to determine touch status and rotor/slider position. An interrupt callback function is triggered to indicate completion of measurement. The recommended sequence of operation facilitates the CPU to either sleep or perform other functions during touch sensor measurement. Before using the PTC, the generic clock generator for the PTC peripheral should be set up by the Application. It is recommended to set the PTC generic clock to 4MHz. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 44 Figure 5-12. Application vs QTouch Library Flow 5.5.2. Application Flow - megaAVR The application periodically initiates a touch measurement on either mutual capacitance or selfcapacitance sensors either in polled or interrupt mode. In polling mode, touch API's are blocking API's and will consume more CPU time. In ISR mode, touch API's are non blocking and will generates an end of conversion (EOC) interrupt at the end of each sensor measurement.Touch measurement is intiated on first sensor by calling touch_xxxxcap_sensors_measure() API .The touch measurement is initiated sequentially and additional post-processing is performed on the measured sensor data to determine touch status and rotor/slider position by calling touch_ptc_process() API in application context instead of interrupt context. A callback function is triggered to indicate completion of measurement .The ISR mode sequence of operation facilitates the CPU to either sleep or perform other functions during touch sensor measurement. It is recommended to set the PTC clock to 4MHz. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 45 Figure 5-13. Application vs QTouch Library Flow 5.6. API Sequence The touch_xx_sensors_init API initializes the QTouch Library as well as the PTC module. It also initializes the mutual or self-capacitance method specific pin, register, and global sensor configuration. The touch_xx_sensor_config API configures the individual sensor. The sensor specific configuration parameters can be provided as input arguments to this API. The touch_xx_sensors_calibrate API calibrates all the configured sensors and prepares the sensors for normal operation. The touch_xx_sensors_measure API initiates a sensor measurement on all the configured sensors. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 46 Figure 5-14. API Sequence with Combined self and Mutual Capacitance Sensors Enabled 5.7. State Machine The PTC QTouch Library state machine that presents the various library States and Event transitions can be found in the figure below. The state machine is maintained separately for each of the touch acquisition method, which means the state of mutual capacitance sensor operation can be different from the state of self-capacitance allowing them to co-exist. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 47 Figure 5-15. Library State Machine The touch_xx_sensors_init API initializes the QTouch Library as well as the PTC module. It also initializes the mutual or self-capacitance method specific pin, register, and global sensor configuration. The touch_xx_sensor_config API configures the individual sensor. The sensor specific configuration parameters can be provided as input arguments to this API. The touch_xx_sensors_calibrate API calibrates all the configured sensors and prepares the sensors for normal operation. The touch_xx_sensors_measure API initiates a sensor measurement on all the configured sensors. The touch_xx_sensors_deinit function is used to clear the initialized library state. Used for clearing the internal library data and states. When called will modify the library state to TOUCH_STATE_NULL. The touch_xxxx_lowpower_sensor_enable_event_measure API is used to start a event trigger based low power sensor measurement. Touch Library Suspend Resume Operation The touch library provides touch_suspend_ptc, touch_resume_ptc API to suspend and resume the PTC. When suspend API is called, the touch library initiates the suspend operation and return to the application. After completing the current PTC conversion, the touch library will initiate suspend operation and call the application touch suspend callback function pointer. The suspend complete callback function pointer has to be registered by the application. Note:  If it is not registered, then the suspend call will return TOUCH_INVALID_INPUT_PARAM. The application then should disable corresponding clock to reduce the power consumption. The following flowchart depicts the suspend sequence. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 48 Figure 5-16. Suspend Sequence Touch_suspend_ptc() Is Callback Received? Wait for touch_suspend_callback if touch state is in TOUCH_STATE_BUSY or perform some other application code without calling any Touch _lib APIs Yes disable PTC GCLK disable APBCMASK disable GCLK generator disable GCLK source SUSPENSION_COMPLETE SUPENSION_START No If the touch state is not TOUCH_STATE_BUSY the user can disable the clock and proceed to complete the suspend routine. To resume the operations, perform the following sequence: Figure 5-17. Resume Sequence The SAM controllers may be configured to operate PTC touch sensing autonomously using the Event System. In this mode, a single sensor channel is designated as the 'Low Power' key and may be periodically measured for touch detection without any CPU action. The CPU may be held in STANDBY throughout the operation, minimizing power consumption. The low power key may be a discrete electrode with one Y (Sense) line for self-capacitance or one X (Drive) plus one Y (Sense) for mutual capacitance, or it may be a combination of multiple Drive and/or Sense lines as a lumped mode sensor as described. With this method, a fast response may be achieved even in large key-count applications while operating at an extremely low power level, drawing less than 10uA at 3.3V. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 49 5.8. Operation Modes The QTouch Library can operate in the following sensor measurement modes. • Periodic measurement • Continuous measurement 5.8.1. Periodic Measurement In the periodic measurement mode, sensor measurement is initiated by the application through a periodic event such as timer interrupt. The periodic measurement mode scenario is when none of the sensors are touched. While a long measurement period can be used to achieve lower device power consumption, a short measurement period is required for better touch response time. Hence, the measurement period should be tuned to suit a given application. Typical measurement period can range between 20 millisecond to 250 millisecond. Figure 5-18. Periodic Measurement Mode Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 50 5.8.2. Continuous Measurement In the continuous measurement mode, back to back sensor measurement can be initiated from the touch library. This mode can be triggered to resolve user presence or resolve calibration under the following scenario. • Resolve user presence, when sensor is touched or released • Resolve calibration, when – Sensor is calibrated using the touch_xx_sensors_calibrate API – Sensor is in Away from touch re-calibration condition – Sensor is in Max-on duration condition The TOUCH_BURST_AGAIN acquisition status data bit field in the measure data structure is set to indicate continuous measurement mode. void touch_mutlcap_measure_complete_callback(void) { if (!(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { /* Set the Mutual Cap measurement done flag. */ p_mutlcap_measure_data->measurement_done_touch = 1u; } } Touch Library Acquisition Status Flags The touch library acquisition status information during continuous measurement mode is available using the touch_acq_status_t acq_status element of the touch_measure_data_t touch measure data structure. Table 5-1. Touch Acquisition Status Bit Fields Macro Bitfield Comment TOUCH_NO_ACTIVITY 0x0000u No Touch activity TOUCH_IN_DETECT 0x0001u Atleast one Touch channel is in detect TOUCH_STATUS_CHANGE 0x0002u Change in Touch status of atleast one Touch channel TOUCH_ROTOR_SLIDER_POS_C HANGE 0x0004u Change in Rotor or Slider position of atleast one rotor or slider TOUCH_CHANNEL_REF_CHANGE 0x0008u Change in Reference value of atleast one Touch channel TOUCH_BURST_AGAIN 0x0008u Indicates that reburst is required to resolve Filtering or Calibration state TOUCH_RESOLVE_CAL 0x0200u Indicates that reburst is needed to resolve Calibration TOUCH_RESOLVE_FILTERIN 0x0200u Indicates that reburst is needed to resolve Filtering TOUCH_RESOLVE_DI 0x0800u Indicates that reburst is needed to resolve Detect Integration TOUCH_RESOLVE_POS_RECAL 0x1000u Indicates that reburst is needed to resolve Recalibration Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 51 Macro Bitfield Comment TOUCH_CC_CALIB_ERROR 0x2000u Indicates that CC calibration failed on at least one channel TOUCH_AUTO_OS_IN_PROGRES S 0x4000u Indicates that Auto OS in progress to get stable channel signal The acquisition status flags can be monitored within the measure complete callback as shown. void touch_mutlcap_measure_complete_callback(void) { if ((p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { //Denotes acquisition is incomplete. } if ((p_mutlcap_measure_data->acq_status & TOUCH_RESOLVE_CAL)) { //Denotes sensor calibration is on-going. } if (!(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { //Denotes acquisition is completed. /* Set the Mutual Cap measurement done flag. */ p_mutlcap_measure_data->measurement_done_touch = 1u; } } Continuous Measurement Post Processing Mode The sensor data post-processing mode for QTouch library can be selected using the DEF_xxxxCAP_TOUCH_POSTPROCESS_MODE configuration item available as part of touch.h file. When TOUCH_LIBRARY_DRIVEN mode is selected, the library self-initiates repeated touch measurements to resolve touch press, release and calibration. This mode is suited for best response time. When TOUCH_APPLN_DRIVEN mode is selected, the library does not initiate repeated touch measurement to resolve touch press, release and calibration. This mode suits deterministic PTC interrupt execution time for applications requiring stringent CPU time requirements. As repeated touch measurements are delayed due to other critical application code being executed. This mode can potentially affect the touch response time. In order to improve the response time with the TOUCH_APPLN_DRIVEN mode, the following condition should be applied to initiate sensor measurement, so as to cater for additional measurements without any delay. The same condition can also be applied to other application scenario such as sleep to check for pending acquisitions to be completed before the system can go to sleep. if ((touch_time.time_to_measure_touch == 1u)||(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { /* Start a touch sensors measurement process periodically, or if there is a pending measurement. */ touch_ret = touch_mutlcap_sensors_measure(touch_time.current_time_ms,NORMAL_ACQ_MODE,touch_mutlcap_meas ure_complete_callback); } 5.9. Touch Library API Error The following table provides the touch library API error code information. The API error code type is touch_ret_t enum. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 52 ErrorCode Enumeration Comment TOUCH_SUCCESS Successful completion of operation TOUCH_ACQ_INCOMPLETE Touch Library is busy with pending previous touch measurement TOUCH_INVALID_INPUT_PARAM Invalid input parameter TOUCH_INVALID_LIB_STATE Operation not allowed in the current Touch Library state TOUCH_INVALID_SELFCAP_CONFIG_PARAM Invalid self-capacitance configuration input parameter TOUCH_INVALID_MUTLCAP_CONFIG_PARAM Invalid mutual capacitance configuration input parameter TOUCH_INVALID_RECAL_THRESHOLD Invalid Recalibration threshold input value TOUCH_INVALID_CHANNEL_NUM Channel number parameter exceeded total number of channels configured TOUCH_INVALID_SENSOR_TYPE Invalid sensor type. Sensor type can not be SENSOR_TYPE_UNASSIGNED TOUCH_INVALID_SENSOR_ID Invalid sensor number parameter TOUCH_INVALID_RS_NUM Number of Rotor/Sliders set as 0, when trying to configure a rotor/slider The application error codes in touch projects can be enabled or disabled using a macro DEF_TOUCH_APP_ERR_HANDLER. By default, the value of macro DEF_TOUCH_APP_ERR_HANDLER is set to 0 in order to disable the application error handler. To enable the application error handler, set the macro DEF_TOUCH_APP_ERR_HANDLER as 1. When it is enabled, while(1) is used to trap errors. Refer Application Error Code (tag_touch_app_err_t) for further information. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 53 6. Tuning for Noise Performance The PTC has been designed with great care making it easy to design a capacitive touch solution, while at the same time maintaining high quality of touch and performance. Nevertheless in any touch sensing application, the system designer must consider how electrical interference in the target environment may affect the performance of the sensors. Touch sensors with insufficient tuning can show failures in tests of either radiated or conducted noise, which can occur in the environment or power domain of the appliance or may be generated by the appliance itself during normal operation. In many applications there are quality standards which must be met where EMC performance criteria are clearly defined. However meeting the standards cannot be considered as proof that the system will never show EMC problems, as the standards include only the most commonly occurring types and sources of noise. Noise immunity comes at a cost of increased touch response time and power consumption. The system designer must carry out proper tuning of the touch sensors in order to ensure least power consumption. The PTC QTouch library has anumber of user configurable features which can be tuned to give the best balance between touch response time, noise immunity and power consumption. 6.1. Noise Sources Noise sources that affect touch sensor performance can be classified as follows. Self-generated • Motors • Piezo buzzers • PWM controls Radiated • Fluorescent lamp • Radio transmission • Inductive cook top Conducted • Power supply / charger • Mains supply Applicable EMC standards • Conducted Immunity EN61000-4-6 6.2. Noise Counter Measures The effects of noise are highly dependent on the amplitude of the noise signal induced or injected onto the sensors, and the frequency profile of that noise signal. Generally, this noise can be classified as - • Broadband noise • Narrow band noise 6.2.1. Broadband Noise Counter Measures Broadband noise refers to noise signals whose frequency components are not harmonically related to the capacitance measurement acquisition frequencies of the PTC. Provided that the maximum and minimum voltage levels of the acquisition signal combined with noise signals are within the input range of the PTC and a sufficiently large number of samples are taken, Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 54 broadband noise interference can be averaged out by setting a high value of Filter level (DEF_MUTLCAP_FILTER_LEVEL_PER_NODE, DEF_SELFCAP_FILTER_LEVEL_PER_NODE) and Auto oversample (DEF_MUTLCAP_AUTO_OS_PER_NODE, DEF_SELFCAP_AUTO_OS_PER_NODE) settings. If the noise amplitude is excessive, then PTC components experience saturation of measurement. In this case the acquisition signals combined with the noise signals are outside the input range of the PTC, which results in clipping of the measurements. Often the clipping is not observable in the resolved measurement, as it occurs only on a portion of the measurement samples, but the presence of clipped samples prevents effective averaging of the sample points. In this case, averaging of samples will not result in a noise-free measurement even with large rates of oversampling. The resolved signal will show a shift from its correct level due to asymmetry of signal clipping. Configuration Parameter Setting DEF_MUTLCAP_FILTER_LEVEL_PER_NODE, DEF_SELFCAP_FILTER_LEVEL_PER_NODE FILTER_LEVEL_64 DEF_MUTLCAP_AUTO_OS_PER_NODE, DEF_SELFCAP_AUTO_OS_PER_NODE AUTO_OS_DISABLE DEF_MUTLCAP_FREQ_MODE, DEF_SELFCAP_FREQ_MODE FREQ_MODE_NONE DEF_MUTLCAP_CLK_PRESCALE_PER_NODE, DEF_SELFCAP_CLK_PRESCALE_PER_NODE PRSC_DIV_SEL_1 DEF_MUTLCAP_SENSE_RESISTOR_PER_NODE, DEF_SELFCAP_SENSE_RESISTOR_PER_NODE RSEL_VAL_100 Auto-tune input to touch_mutlcap_sensors_calibrate(), touch_selfcap_sensors_calibrate API AUTO_TUNE_PRSC STEP 1: PREVENT CLIPPING This requires the implementation of a hardware low pass filter in order to reduce the scale of the noise combined with acquisition signal. The sensor capacitance is combined with a series resistor on the Y (Sense) line, either the PTC internal resistor or externally mounted on the PCB. The external series resistor should be mounted between the Y line of the device to the Sensor, closest to the device pin. Note:  Always use an external series resistor for self-capacitance applications in order to prevent clipping. The internal series resistor of the PTC is limited to 100K. Depending on the noise levels, external series resistors up to1 megaohms can be evaluated. STEP 2: CHARGE TRANSFER TEST As an effect of adding a series resistor to form a low pass filter, the time constant for charging the sensors is increased. It is essential to ensure that the sensor capacitance is fully charged and discharged during each measurement sampling. Insufficient charging can be observed as a reduced touch delta or it may be seen on an oscilloscope by connecting to the sense electrode. However, this problem may not be apparent in the touch sensor operation; the application may behave perfectly well even in the presence of low-level noise, but show much worse performance during noise tests with the addition of the resistor compared to a configuration which excludes the resistor. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 55 Charge transfer though Auto tuning setting: The QTouch library Auto tune setting provides a mechanism which carries out a charge transfer test on each enabled key and sets the prescalar to the fastest available setting ensuring full charge transfer. The following combination of setting should be used. • DEF_MUTLCAP_SENSE_RESISTOR_PER_NODE and DEF_SELFCAP_SENSE_RESISTOR_PER_NODE should be set to RSEL_VAL_100. • Auto tune pre-scaler AUTO_TUNE_PRSC should be provided as input parameter to touch_mutlcap_sensors_calibrate( AUTO_TUNE_PRSC )and touch_mutlcap_sensors_calibrate(AUTO_TUNE_PRSC) Testing for Charge transfer by Manual tuning: • If the AUTO_TUNE_NONE setting is provided as an input to the touch_mutlcap_sensors_calibrate(AUTO_TUNE_NONE ) and touch_mutlcap_sensors_calibrate (AUTO_TUNE_NONE) calibration API, then the PTC uses the user defined settings of the PTC Clock pre-scaler ( DEF_MUTLCAP_CLK_PRESCALE, DEF_SELFCAP_CLK_PRESCALE_PER_NODE) and internal series resistor (DEF_MUTLCAP_SENSE_RESISTOR_PER_NODE, DEF_SELFCAP_SENSE_RESISTOR_PER_NODE). • Reference measurement: An acquisition measurement (Signal value) is taken with the prescalar set to maximum, i.e. PRSC_DIV_SEL_8 Test measurement: A second measurement (Signal value) is taken with reduced prescalar: PRSC_DIV_SEL_4 If the difference between the two measurements is less than ~3% (1/32) of the first value, the conclusion is that fullcharge transfer is achieved with PRSC_DIV_SEL_4. This measurement is repeated for PRSC_DIV_SEL_2 and PRSC_DIV_SEL_1 to find the fastest PTC operating speed for which full charge transfer is achieved. STEP 3: ADJUST OVERSAMPLING Once clipping is prevented by hardware filtering and full charge transfer is ensured the next step is to find the best settings for Filter level ( DEF_MUTLCAP_FILTER_LEVEL_PER_NODE , DEF_SELFCAP_FILTER_LEVEL_PER_NODE ) and Auto over samples (DEF_MUTLCAP_AUTO_OS_PER_NODE , DEF_SELFCAP_AUTO_OS_PER_NODE). Auto over samples feature provides the advantage that additional samples are only taken on a sensor which has showna significant change. In the absence of such a change, the measurement cycle can be much shorter compared to applying ( * AUTO_OS) as the oversampling rate on every measurement. Care should be taken when using AUTO_OS to ensure that it does not occur too frequently. The measurement time for FILTER_LEVEL samples can be represented as: A+ (B * FILTER_LEVEL) Where A is the total time for PTC configuration and post-processing, and B is the oversampling period (the per sample measurement time) When AUTO_OS is applied, this time is increased to: A + (B * FILTER_LEVEL*( 1 + AUTO_OS )) FILTER_LEVEL should be sufficiently large to ensure that AUTO_OS is only applied during the worstcase noise circumstances. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 56 6.2.2. Narrowband Noise Counter Measures If the noise includes a frequency component which is related to the PTC capacitance measurement acquisition frequency, then no amount of oversampling will average out the noise effects. Any batch of measurement samples taken with the same sampling frequency will result in a measurement offset. The actual offset resulting from each measurement depends on the relative phase of the noise component and the sampling frequency. This effect is illustrated in the following diagram, where the noise is represented by a sine wave. STEP 4: SELECT FREQUENCY MODE Note:  Step1, Step2 and Step3 provided in the previous section should be used in combination with this step in a system which has both broadband noise and narrow band noise. Default settings provided before STEP1 should be used as a starting point before starting noise tuning. With FREQUENCY_MODE_NONE, a single acquisition frequency is used and samples are taken at the fastest rate possible with the given pre-scalar setting. This gives the best response time, and with sufficient oversampling excellent noise immunity at all noise frequencies which are not related to the sampling frequency. However in the case where the noise is at (or close to) a frequency which is harmonically related to the sampling frequency then the noise issue becomes severe, as illustrated above. This is particularly important in applications where a frequency sweep test is required, such as EN61000-4-6. FREQUENCY_MODE_SPREAD applies a modification to the sampling rate, such that the period between successivesamples is modified in a saw-tooth fashion to apply a wider spectrum to the sampling frequency. The sampling frequency F0 is thus spread across the range (F0/2, F0). With relatively low noise amplitude, this can be effective atimproving performance with minimal cost in response time. FREQUENCY_MODE_HOP utilizes 3 base frequencies and a median filter to avoid using measurements taken at anaffected frequency. The frequencies should be selected to minimize the set of crossover harmonics within the problemfrequency band. Each of the 3 frequencies is used in sequence for each measurement cycle.i.e. • Cycle 1: All sensors measured with Frequency 0 • Cycle 2: All sensors measured with Frequency 1 • Cycle 3: All sensors measured with Frequency 2 • Cycle 4: All sensors measured with Frequency 0 • Cycle 5: All sensors measured with Frequency 1 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 57 If Frequency 0 is related to the noise frequency, then the measurements taken with F0 will show high variation. Using a median filter, this ensures that the outlying measurements will be rejected. In some applications, self-generated noise may be present which affects one or more of the default HOP frequencies. Insuch a case, the HOP frequencies should be changed to avoid this frequency. Some noise frequencies can occur which are close to harmonics of two of the HOP frequencies, in which case thesystem must be tuned with higher settings of FILTER_LEVEL or AUTO_OS to provide enough samples to average the noise out of the measurement. Determining PTC Acquisition Frequency The PTC acquisition frequency is given by the following formula, PTC Acquisition Frequency = (1/ PTC Acquisition Time) The PTC acquisition time is given by the following formula, PTC Acquisition Time = (Cycles per Acquisition + Hop Freq) * PTC IO Clock Period Where, Cycles per Acquisition = Number of PTC clock cycles required for each acquisition. This is a fixed value of 15. Hop Freq = PTC acquisition frequency delay setting This parameter is represented in the touch.h file by the symbols DEF_MUTLCAP_HOP_FREQS and DEF_SELFCAP_HOP_FREQS. The PTC acquisition frequency is dependent on the Generic clock input to PTC and PTC clock pre- scaler setting. This delay setting inserts n PTC clock cycles between consecutive measurements on a given sensor, thereby changing the PTC acquisition frequency. FREQ_HOP_SEL_1 setting inserts 0 PTC clock cycles between consecutive measurements. FREQ_HOP_SEL_16 setting inserts 15 PTC clock cycles. Hence, higher delay setting will increase the total time taken for capacitance measurement on a given sensor as compared to a lower delay setting.A desired setting can be used to avoid noise around the same frequency as the acquisition frequency. Range: FREQ_HOP_SEL_1 to FREQ_HOP_SEL_16 Three frequency hop delay settings need to be specified when assigning values to this parameter. Duration of each PTC clock period is given by the following formula, Where, CLKPTC = Generic clock input to the PTC Refer touch_configure_ptc_clock() API in touch.c file for clock configuration. Prescaler = PTC clock prescaler setting This parameter is represented in the touch.h file by the symbols DEF_MUTLCAP_CLK_PRESCALE_PER_NODE and DEF_SELFCAP_CLK_PRESCALE_PER_NODE. Example: If Generic clock input to PTC = 4MHz, then: • PRSC_DIV_SEL_1 sets PTC Clock to 4MHz • PRSC_DIV_SEL_2 sets PTC Clock to 2MHz • PRSC_DIV_SEL_4 sets PTC Clock to 1MHz • PRSC_DIV_SEL_8 sets PTC Clock to 500KHz Example: Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 58 When CLKPTC = 4MHz, Prescaler = PRSC_DIV_SEL_1, the PTC Acquisition Frequencies obtained are as follows, Hop Freq PTC Acquisition Frequency(kHz) FREQ_HOP_SEL_1 66.67 FREQ_HOP_SEL_2 62.50 FREQ_HOP_SEL_3 58.82 FREQ_HOP_SEL_4 55.56 FREQ_HOP_SEL_5 52.63 FREQ_HOP_SEL_6 50.00 FREQ_HOP_SEL_7 47.62 FREQ_HOP_SEL_8 45.45 FREQ_HOP_SEL_9 43.48 FREQ_HOP_SEL_10 41.67 FREQ_HOP_SEL_11 40.00 FREQ_HOP_SEL_12 38.46 FREQ_HOP_SEL_13 37.04 FREQ_HOP_SEL_14 35.71 FREQ_HOP_SEL_15 34.48 FREQ_HOP_SEL_16 33.33 Note:  The acquisition frequencies may vary based on the tolerance of the clock source. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 59 7. Application Design 7.1. Touch Library and Associated Files The table below provides the mandatory files required to use the QTouch library. In order to add QTouch functionality into an existing user example project, these files and associated library based on the compiler should be added to the user project. Table 7-1. Touch Library Files File Description touch_api_ptc.h QTouch Library API header file, contains API and Data structure used to interface with the library touch.h QTouch library configuration header file touch.c A helper file to demonstrate QTouch library initialization and sensor configuration libsamxxx_qtouch_iar.a or libsamxxx_qtouch_gcc.a QTouch library compiled for IAR or GCC compiler that supports both self-capacitance and mutual capacitance sensors. 7.2. Code and Data Memory Considerations The table below captures the typical code and data memory required for QTouch library. The typical memory requirements provided in the table are arrived considering only Regular API usage in the application. Usage of Helper API would consume additional code memory. Each measurement method requires additional data memory from the application for storing the signals, references, sensor configuration information, and touch status. This data memory is provided by the application as 'data block' array. The size of this data block depends on the number of sensors configured. The PRIV_xx_DATA_BLK_SIZE macro in touch_api_ptc.h calculates the size of this data memory block. Table 7-2. Mutual Capacitance Method Series Code Memory Keys Only Data Memory Keys Only Code Memory Keys with Rotor or Slider Data Memory Keys with Rotor or Slider libsamd1x-qtouch-gcc.a 9602 845 11114 861 libsamd1x-qtouch-iar.a 9005 497 10377 513 libsamd2x-qtouch-gcc.a 9222 841 10734 857 libsamd2x-qtouch-iar.a 8881 497 10254 513 libsaml21-qtouch-gcc.a 9282 841 10794 857 libsaml21-qtouch-iar.a 9744 497 11115 513 libsamda1-qtouch-gcc.a 9222 841 10734 857 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 60 Series Code Memory Keys Only Data Memory Keys Only Code Memory Keys with Rotor or Slider Data Memory Keys with Rotor or Slider libsamda1-qtouch-iar.a 8881 497 10254 513 libsamc2x-qtouch-gcc.a 9752 841 11264 857 libsamc2x-qtouch-iar.a 9209 501 10567 517 libsamr21-qtouch-gcc.a 9246 841 10758 857 libsamr21-qtouch-iar.a 8905 497 10277 513 libsaml22-qtouch-gcc.a 9886 841 11078 857 libsaml22-qtouch-iar.a 9509 501 10981 517 libatmega328pb_qtouch_gcc.a 13338 503 15760 532 libMega328PB_qtouch.r90 10761 578 12391 607 libatmega324pb_qtouch_gcc.a 14082 482 16520 631 atmega324pb_qtouch_iar.r90 10646 441 12379 562 In case of ATmega328PB, for a single touch channel (mutual capacitance mode) without noise, moisture, auto-tune and qdebug features, RAM usage is 503 bytes. RAM usage gets increased by 36 bytes for each additional channel. Table 7-3. Self-capacitance Method Series Code Memory Keys Only Data Memory Keys Only Code Memory Keys with Rotor or Slider Data Memory Keys with Rotor or Slider libsamd1x-qtouch-gcc.a 9576 841 10884 849 libsamd1x-qtouch-iar.a 8952 497 10216 505 libsamd2x-qtouch-gcc.a 9198 845 10506 845 libsamd2x-qtouch-iar.a 8841 497 10101 505 libsam121-qtouch-gcc.a 9258 841 10566 845 libsaml21-qtouch-iar.a 9806 497 11070 505 libsamda1-qtouch-gcc.a 9198 845 10506 845 libsamda1-qtouch-iar.a 8841 497 10101 505 libsamc2x-qtouch-gcc.a 9716 841 11024 845 libsamc2x-qtouch-iar.a 9148 501 10400 509 libsamr21-qtouch-gcc.a 9542 841 10850 845 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 61 Series Code Memory Keys Only Data Memory Keys Only Code Memory Keys with Rotor or Slider Data Memory Keys with Rotor or Slider libsamr21-qtouch-iar.a 8851 497 10115 505 libsaml22-qtouch-gcc.a 9530 841 11158 845 libsaml22-qtouch-iar.a 9410 501 10733 509 libatmega328pb_qtouch_gcc.a 13274 500 15260 519 libMega328PB_qtouch.r90 10705 594 12041 613 libatmega324pb_qtouch_gcc.a 14026 478 16024 593 libMega328PB_qtouch.r90 10596 437 12329 558 In case of ATmega328PB, for a single touch channel (self-capacitance mode) without noise, moisture, auto-tune and qdebug features, RAM usage is 500 bytes. RAM usage gets increased by 32 bytes for each additional channel. Note:  1. The total number of sensors supported by a specific device variant is limited by the number of XYlines as well as code, data, and stack memory requirements. 2. To save the memory utilized for code and data, new lib-nano C library has been used for GCC example projects. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 62 8. Example Applications 8.1. Atmel Board Example Projects The GCC Xplained Pro example projects can be accessed through File>New Example Project menu option in Atmel Studio. The IAR Xplained Pro example projects can be accessed through Atmel QTouch Library PTC Partpack. The following example projects are available for Xplained Pro kits: • SAM D20 Xplained Pro and QT1 Xplained Pro Mutual Capacitance example application • SAM D20 Xplained Pro and QT1 Xplained Pro Self Capacitance example application • SAM D21 Xplained Pro and QT1 Xplained Pro Mutual Capacitance example application • SAM D21 Xplained Pro and QT1 Xplained Pro Self Capacitance example application • SAM D20 Xplained Pro and QT1 Xplained Pro Mutual Capacitance example application with LumpLow Power configuration • SAM D20 Xplained Pro and QT1 Xplained Pro Self Capacitance example application with LumpLow Power configuration • SAM D11 Xplained Pro Self Capacitance example application • SAM D10 Xplained Mini Self Capacitance example application • SAM D20 QTouch Robustness Demo Moisture Example Application (self + mutual) • SAM C20 QTouch Robustness Demo Moisture Example Application • SAM D20 Xplained Pro and QT3 Xplained Pro Mutual Capacitance example application with LumpLow Power configuration • SAM L21 Xplained Pro and QT3 Xplained Pro Mutual Capacitance example application with LumpLow Power configuration • SAM DA1 Xplained Pro and QT4 Xplained Pro Self Capacitance example application • SAM C21 Xplained Pro and QT1 Xplained Pro Mutual Capacitance example application • SAM C21 Xplained Pro and QT1 Xplained Pro Self Capacitance example application • SAM C21 Xplained Pro Self Capacitance example application(on-board sensor) • SAM C21 Xplained Pro and QT5 Xplained Pro Mutual Capacitance example application • SAM L22 Xplained Pro and Touch Segment LCD Xplained Pro Mutual Capacitance example application • ATmega328PB Xplained Mini Self Capacitance example application • ATmega324PB Xplained Pro and QT5 Xplained Pro Mutual Capacitance example application Note:  For SAM L22, it is recommended to set the PTC Clock to 8MHz. Clock Configuration Changes in Projects: • For SAM C20/C21 RevB devices, DPLL is used as the main clock and OSC32K is used as reference clock for the DPLL clock source. For SAM C20/C21 RevC devices, OSC48MHz is used as the main clock. This is demonstrated in the example projects by using the same project for both SAM C20/C21 RevB and SAM C20/C21 RevC devices. • The example projects which have DFLL as main clock source use scaled OSC8MHz/OSC16MHz clock as the reference input clock. • SAM L22 example project configures DFLL for 16MHZ (performance level - PL2) and utilizes it as the main clock. This clock setting offers high performance. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 63 • SAM L22 low power user board project configures DFLL for 8MHZ (performance level - PL0) and utilizes it as the main clock. This clock setting offers low power consumption. • SAM L21/L22 low power example projects are configured in PL0 (Low power oriented mode) with Buck regulator as the main regulator in standby sleep mode. This is the best suitable configuration to achieve low power numbers. The example projects make use of Xplained Pro boards and the extension kits for showcasing touch. Those extension kits are explained in the following sections. QT1 Xplained Pro kit: The QT1 Xplained Pro self-capacitance and mutual capacitance extension boards are supported by SAM D20, SAM D21, SAM DA1, SAM C21, and SAM L22 Xplained Pro Evaluation kits. Figure 8-1. QT1 Xplained Pro Mutual Capacitance and Self-capacitance Note:  SAM C21 Xplained Pro can operate at 3.3V and 5V Vcc, while the QT1 Xplained Pro can operate at a maximum voltage of 3.6V. Please make sure to put the Vcc selection header on the SAM C21 Xplained Pro in the 3.3V position. The QT1 Xplained Pro boards demonstrate the following combinations of buttons, slider, and wheels. • 2 buttons + 2 yellow LED • 1 slider + 8 yellow LED • 1 wheel + 1 RGB LED QT3 Xplained Pro kit: The QT3 Xplained Pro extension board has 12 mutual capacitance buttons on it and it is supported by SAM D20, SAM D21, SAM DA1, SAM L21, SAM L22 and SAM C21 Xplained Pro Evaluation kits. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 64 Figure 8-2. QT3 Xplained Pro QT4 Xplained Pro kit: The QT4 Xplained Pro boards demonstrate the following arrangement. • Two self-capacitance buttons • One unshielded proximity sensor • One proximity sensor with driven shield with external op-amp driver • One LED indicator for each self-capacitive button • One LED indicator for each proximity sensor Figure 8-3. QT4 Xplained Pro QT5 Xplained Pro kit: The QT5 Xplained Pro board demonstrates the following arrangement. • One 4-channel (4X x 1Y) mutual capacitance curved slider • Two mutual capacitance buttons • 16 LEDs arranged as two 7-segment digits separated with a colon • IS31FL3728 I2C LED matrix controller from ISSI Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 65 Figure 8-4. QT5 Xplained Pro 8.2. User Board Example Projects Atmel Studio QTouch Composer can be used to create GCC projects based on the sensor and pin configuration defined by the requirements of a user board. The generated example projects also allow for QDebug data streaming to QTouch Analyzer. The User board example project can be generated by accessing the QTouch Composer using the following menu options in the Atmel Studio. File > New Project > GCC C QTouch Executable Project > Create QTouch Library Project The QTouch Project Builder wizard appears as shown in the screenshot. Selection of sensors, devices, pins, debug interface and tuning of parameters can be done according to user preferences and project can be generated. The figure shows one of the user board generated projects. Figure 8-5. QTouch Project Builder Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 66 Figure 8-6. User Board Example Project 8.3. Using Atmel Software Framework (ASF) with the Example Projects The example projects are based on Atmel Software Framework (ASF). For more information on ASF refer to Atmel Software Framework User Guide http://www.atmel.com/. The Atmel® Software Framework (ASF) is a MCU software library providing a large collection of embedded software for Atmel flash MCUs: mega AVR, AVR XMEGA, AVR UC3 and SAM devices. • It simplifies the usage of microcontrollers, providing an abstraction to the hardware and high- value middleware • ASF is designed to be used for evaluation, prototyping, design and production phases • ASF is integrated in the Atmel Studio IDE with a graphical user interface or available as standalone for GCC, IAR compilers • ASF can be downloaded for free 8.4. Using Xplained Pro Kit to Program User Board The SAM D20 Xplained Pro features a Cortex® Debug Connector (10-pin) for programming and debugging an external target. The connector is limited to the SWD interface and is intended for in-system programming and debugging of SAM D20 devices in the final product developed by the users. For more information refer SAM D20 Xplained Pro User Guide (www.atmel.com). 8.5. Using QDebug Touch Data Debug Communication Interface When using IAR and GCC example projects, QDebug touch data debug communication interface can be enabled. This allows the communication between the touch device and QTouch Analyzer. To enable or disable QDebug, configure DEF_TOUCH_QDEBUG_ENABLE in the touch.h file. When QDebug is enabled and touch debug data is being updated in the QTouch Analyzer, touch response time will be slower due to the debug communication data transfer which increases the delay in the response time. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 67 After tuning the touch sensors using QTouch Analyzer, disable the QDebug for optimized touch performance. Figure 8-7. Atmel DGI Interface for QDebug Data Figure 8-8. QTouch Analyzer view 8.6. Using Xplained Pro Kit for QDebug Data Streaming from User Board SAM D20 Xplained Pro contains Embedded Debugger (EDBG) that features an Atmel Data Gateway Interface (DGI) over SPI and TWI. The DGI can be used to transmit a variety of data from the Xplained Pro kit to the host PC. This arrangement can be used to send QDebug data from a user board to Atmel Studio QTouch Analyzer for touch sensor data analysis and tuning. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 68 Figure 8-9. Using Xplained Pro for Data Streaming from User Board The example project generated using QTouch composer makes use of SPI for data transfer. To stream QDebug data from user board, a relay firmware should be flashed onto the SAM D20/D21 microcontroller on the Xplained Pro kit. After connecting the SAM D20/D21 Xplained Pro to the PC, the device name appears in the connected kits of QTouch Start Page. Right click the device name and choose Enable User Board Analysis to flash the relay firmware. Figure 8-10. Flash Relay Firmware The following table indicates the SPI connection between SAM D20 Xplained Pro Kit and User Board: Table 8-1. SPI Connection Information SAMD20 Xplained Pro Extension header EXT3 UserBoard Pin Pin on EXT3 Function 16 SPIMOSI (PB22) MOSI 17 SPIMISO (PB16) MISO 18 SPISCK(PB23) SCK - SS-Connect to GND 19 GND GND Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 69 8.7. Using Atmel ICE for QDebug Data Streaming from User Board Atmel ICE can be used to stream data from the user board. Refer the following table and connect the mini squid cable from AVR header of Atmel ICE to user board. Atmel-ICE AVR port pins Target pins Mini-squid pin Pin 1 (TCK) SCK 1 Pin 2 (GND) GND 2 Pin 3 (TDO) MISO 3 Pin 4 (VTG) VCC 4 Pin 5 (TMS) SS 5 Pin 6 (nSRST) - 6 Pin 7 (Not Connected) - 7 Pin 8 (nTRST) - 8 Pin 9 (TDI) MOSI 9 Pin 10 (GND) - 0 While creating the project using QTouch composer project builder wizard, the pins SCK, MISO, SS and MOSI can be chosen from the debug interface setup pane as shown in the figure. Figure 8-11. Debug Interface Setup Pane When the connections are made correctly and debug interface setup is also done in the project, flash the project in the user board. Data can be streamed and visualized via QTouch Analyzer. Note:  Atmel ICE would be listed in QTouch Analyzer as QDEBUG_DGI. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 70 9. Known Issues 1. PTC in Self-capacitance Mode The following errata is applicable for SAM D20 (Revision B) Description: The two lowest gain settings are not selectable and an attempt by the QTouch Library to set enable of these may result in a higher sensitivity than optimal for the sensor. The PTC will not detect all touches.This errata does not affect mutual capacitance mode which operates as specified. Fix/workaround: Use SAM D20 revision C or later for self-capacitance capacitive touch sensing. 2. Touch acquisition may fail and stop working The following errata is applicable for QTouch Library versions up to 5.0.7. This issue has been fixed in QTouch Library version 5.0.8 or later. Description: In QTouch applications, where either a single interrupt or a chain of nested non-PTC interrupts has duration longer than the total touch measurement time, the touch acquisition may fail and stop working. This issue occurs most likely in applications with few touch channels (2-3 channels) and a low level of noise handling (filter level 16 or lower and no frequency hopping). In an application with single touch channel and filter level 16, the total measurement time is ~350µs. The total measurement time doubles for two touch channels, and triples for 3 touch channels. It increases up to 10 times or 3.5ms with 10 touch channels. Fix/workaround: • Recommended workaround: – Use QTouch Library version 5.0.8 or later. • Other alternatives: 1. Always ensure that the duration of a single interrupt or a chain of nested non-PTC interrupts does not exceed the total touch measurement time. (or) 2. Add a critical section by disabling interrupts for the touch_xxxxcap_sensors_measure() function as shown in the following code snippet. Disable_global_interrupt(); touch_ret = touch_xxxxcap_sensors_measure( touch_time.current_time_ms, NORMAL_ACQ_MODE, touch_xxxxcap_measure_complete_callback); Enable_global_interrupt(); The Interrupt Blocking Time while executing touch_xxxxcap_sensors_measure API for various CPU frequencies are as follows. CPU Frequency (in MHz) Interrupt Blocking Time ( in μs ) 48 ~77 24 ~124 16 ~176 12 ~223 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 71 The interrupt blocking time varies based on the PTC_GCLK frequency, CPU frequency, and the library version. The actual blocking time can be measured by toggling a GPIO pin before and after the touch_xxxxcap_sensors_measure function. When IAR compiler is used, utilize the system_interrupt_enable_global() and system_interrupt_disable_global() functions to enable and disable the global interrupts, respectively. In case of AVR, use cli() and sei() instructions to disable and enable the global interrupts. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 72 10. FAQ on PTC Qtouch Table 10-1. Frequently Asked Questions Query Answer When can we change an acquisition, sensor configuration or global sensor parameter? After changing an acquisition parameter do we need to recalibrate or reinitialize the sensors and PTC? Its best to call the helper APIs to update these parameter when the measurement_done_touch flag (part of touch_measure_data_t structure) is true, which means the library is not in the middle of an (previously started) incomplete acquisition. Changing Gain and Filter level settings can affect the Signal value, so recalibration is mandatory by invoking the touch_sensors_calibrate() API. Can sensors be disabled and reenabled run time? For example, scan 2 sensors while sleeping and then scan all sensors when the system wakes up. Yes, this is possible using the touch_xxxcap_sensor_disable() and touch_xxxcap_sensor_reenable() API. There is a low amplitude pulse prior to the 16 acquisition samples and a large amplitude pulse after the 16 acquisition samples. These pulses are part of setting up the sense line's initial conditions. Is Detect integration calculated inside the PTC or by QTouch library? This is done by QTouch library. When Auto Oversampling is enabled how can one determine touch timing? The absolute maximum cycle, is the case that auto oversamples is applied to all channels: (Normal acquisition time) x (1 + auto_os). This can only happen with a poorly tuned system, as FILTER_LEVEL should be sufficient to prevent AUTO_OS happening except on a touched key under noisy conditions. Can sensor signal lines (Y or X lines) be used to drive LEDs, etc., when not being used for sensor acquisitions? No. This is not recommended Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 73 11. Appendix 11.1. Macros 11.1.1. Touch Library Acquisition Status Bit Fields Keyword Type Description TOUCH_NO_ACTIVITY 0x0000u No touch activity. TOUCH_IN_DETECT 0x0001u Atleast one touch channel is in detect. TOUCH_STATUS_CHANGE 0x0002u Change in touch status of at least one Touch channel. TOUCH_ROTOR_SLIDER_POS_CHANGE 0x0004u Change in the position of at least one rotor or slider. TOUCH_CHANNEL_REF_CHANGE 0x0008u Changein the reference value of at least one touch channel. TOUCH_BURST_AGAIN 0x0100u Indicates that re-burst is required to resolve filtering or calibration state. TOUCH_RESOLVE_CAL 0X0200u Indicates that re-burst is required to resolve calibration. TOUCH_RESOLVE_FILTERIN 0x0400u Indicates that re-burst is required to resolve calibration. TOUCH_RESOLVE_DI 0x0800u Indicates that re-burst is needed to resolve Detect Integration. TOUCH_RESOLVE_POS_RECAL 0x1000u Indicates that re-burst is needed to resolve recalibration. TOUCH_CC_CALIB_ERROR 0X2000u Indicates that CC calibration failed on at least one channel. TOUCH_AUTO_OS_IN_PROGRESS 0X4000u Indicates that Auto-os in progress to get stable channel signal. 11.1.2. Sensor State Configurations GET_SENSOR_STATE (SENSOR_NUMBER) To get the sensor state (whether detect or not) for parameter that corresponds to the sensor specified using the SENSOR_NUMBER. The macro returns either 0 or 1. If the bit value is 0, the sensor is not in detect. If the bit value is 1, the sensor is in detect. #define GET_XXXXCAP_SENSOR_STATE(SENSOR_NUMBER) p_xxxxcap_measure_data- >p_sensor_states [(SENSOR_NUMBER / 8)] & (1 << (SENSOR_NUMBER % 8))) >> (SENSOR_NUMBER %8) GET_XXXXCAP_SENSOR_MOIS_STATUS (SNSR_NUM) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 74 To get the moisture status of a particular sensor. The return value is 1 in case of sensor is affected by moisture and returns 0 if sensor is affected by moisture. #define GET_XXXXCAP_SENSOR_MOIS_STATUS(SNSR_NUM) ((p_xxxxcap_measure_data- >p_sensor_mois_status [(SNSR_NUM)/8] & (1<<((SNSR_NUM)%8))) >>(SNSR_NUM %8)) GET_XXXXCAP_MOIS_GRP_SUM_DELTA (GRP_ID) To get the xxxxcap moisture group sum delta. The return value is 32 bit integer indicating the sum delta of moisture group. #define GET_XXXXCAP_MOIS_GRP_SUM_DELTA(GRP_ID)(mois_XXXX_grp_delta_arr[(GRP_ID)-1]) GET_XXXXCAP_MOIS_GRP_ADJ_DELTA (GRP_ID) To get the xxxxcap moisture group Adjacent delta .The return value is 32 bit integer indicating the adjacent delta of moisture group. #define GET_MUTLCAP_MOIS_GRP_ADJ_DELTA(GRP_ID)(mois_mutl_grp_adj_delta_arr[(GRP_ID)-1]) GET_MOIS_XXXX_GLOB_LOCK_STATE To get the moisture lock status of xxxxcap moisture groups. The return value is 1 if any moisture group is in moisture global lockout and 0 if no moisture group is in moisture global lockout. #define GET_MOIS_MUT_GLOB_LOCK_STATE(mois_lock_global_mutl) GET_XXXXCAP_SENSOR_NOISE_STATUS (SENSOR_NUMBER) To get the noise status of a particular sensor. The return value is 1 in case of sensor is noisy and returns 0 if sensor is not noisy. #define GET_XXXXCAP_SENSOR_NOISE_STATUS (SENSOR_NUMBER)(p_xxxxcap_measure_data- >p_sensor_noise_status [(SENSOR_NUMBER / 8)] & (1 <<(SENSOR_NUMBER % 8))) >> (SENSOR_NUMBER % 8) GET_ROTOR_SLIDER_POSITION (ROTOR_SLIDER_NUMBER) To get the rotor angle or slider position. These values are valid only when the sensor state for corresponding rotor or slider state is in detect. ROTOR_SLIDER_NUMBER is the parameter for which the position is being obtained. The macro returns rotor angle or sensor position. #define GET_XXXXCAP_ROTOR_SLIDER_POSITION(ROTOR_SLIDER_NUMBER)p_xxxxcap_measure_data- >p_rotor_slider_values [ROTOR_SLIDER_NUMBER] DEF_TOUCH_MUTLCAP must be set to 1 in the application to enable the Mutual capacitance touch acquisition method. DEF_TOUCH_SELFCAP must be set to 1 in the application to enable the Self-capacitance touch acquisition method. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 75 11.2. Typedef Field Unit Description threshold_t uint8_t An unsigned 8-bit number setting a sensor detection threshold. sensor_id_t uint8_t Sensor number type. touch_current_time_t uint16_t Current time type. touch_delta_t int16_t Touch sensor delta value type. touch_acq_status_t uint16_t Status of touch measurement. mois_snsr_threshold_t int32_t Moisture threshold for individual sensor. mois_system_threshold_t int32_t Moisture threshold for the entire system. 11.3. Enumeration 11.3.1. Gain Setting (tag_gain_t) Gain per touch channel. Gain is applied on a per-channel basis to allow a scaling-up of the touch sensitivity on contact. Range: GAIN_1 (no scaling) to GAIN_32 (scale-up by32) Data Fields • GAIN_1 • GAIN_2 • GAIN_4 • GAIN_8 • GAIN_16 • GAIN_32 11.3.2. Filter Level Setting (tag_filter_level_t) Touch library FILTER LEVEL setting. The filter level setting controls the number of samples acquired to resolve each acquisition. A higher filter level setting provides improved signal to noise ratio under noisy conditions, while increasing the total time for measurement which results in increased power consumption. Refer filter_level_t in touch_api_ptc.h Range: FILTER_LEVEL_1 (one sample) to FILTER_LEVEL_64 (64 samples). Data Fields • FILTER_LEVEL_1 • FILTER_LEVEL_2 • FILTER_LEVEL_4 • FILTER_LEVEL_8 • FILTER_LEVEL_16 • FILTER_LEVEL_32 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 76 • FILTER_LEVEL_64 11.3.3. Auto Oversample Setting (tag_auto_os_t) Auto oversample controls the automatic oversampling of sensor channels when unstable signals are detected with the default setting of 'Filter level'. Enabling Auto oversample results in 'Filter level' x 'Auto Oversample' number of samples taken on the corresponding sensor channel when an unstable signal is observed. In a case where 'Filter level' is set to FILTER_LEVEL_4 and 'Auto Oversample' is set to AUTO_OS_4, 4 oversamples are taken with stable signal values and 4+16 oversamples are taken when unstable signal is detected. Range: AUTO_OS_DISABLE (oversample disabled) to AUTO_OS_128 (128 oversamples). Data Fields • AUTO_OS_DISABLE • AUTO_OS_2 • AUTO_OS_4 • AUTO_OS_8 • AUTO_OS_16 • AUTO_OS_32 • AUTO_OS_64 • AUTO_OS_128 11.3.4. Low Power Sensor Scan Rate (tag_lowpower_scan_int_t) When the CPU returns to standby mode from active, the sensor configured as the low power sensor is scanned at this interval. A high value for this parameter will reduce power consumption but increase response time for a low power sensor. Note:  This enum is applicable only for ATmega devices. Range: LOWPOWER_PER0_SCAN_3_P_9_MS to LOWPOWER_PER7_SCAN_250_MS Data Fields • LOWPOWER_PER0_SCAN_3_P_9_MS • LOWPOWER_PER1_SCAN_7_P_8_MS • LOWPOWER_PER2_SCAN_15_P_625_MS • LOWPOWER_PER3_SCAN_31_P_25_MS • LOWPOWER_PER4_SCAN_62_P_5_MS • LOWPOWER_PER5_SCAN_125_MS • LOWPOWER_PER6_SCAN_250_MS 11.3.5. Library Error Code (tag_touch_ret_t) Touch Library error codes. Data Fields • TOUCH_SUCCESS Successful completion of touch operation. • TOUCH_ACQ_INCOMPLETE Library is busy with pending previous touch measurement. • TOUCH_INVALID_INPUT_PARAM Invalid input parameter. • TOUCH_INVALID_LIB_STATE Operation not allowed in the current touch library state. • TOUCH_INVALID_SELFCAP_CONFIG_PARAM Invalid self-capacitance configuration input parameter. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 77 • TOUCH_INVALID_MUTLCAP_CONFIG_PARAM Invalid mutual capacitance configuration input parameter. • TOUCH_INVALID_RECAL_THRESHOLD Invalid recalibration threshold input value. • TOUCH_INVALID_CHANNEL_NUM Channel number parameter exceeded total number of channels configured. • TOUCH_INVALID_SENSOR_TYPE Invalid sensor type. Sensor type must NOT be SENSOR_TYPE_UNASSIGNED. • TOUCH_INVALID_SENSOR_ID Invalid sensor number parameter. • TOUCH_INVALID_RS_NUM Number of rotor/sliders set as 0, while trying to configure a rotor/slider. 11.3.6. Application Error Code (tag_touch_app_err_t) The application error codes are listed below. Data Fields • TOUCH_INIT_CONFIG_ERR The touch_xxxxcap_sensors_init is fed with an incompatible / incomplete parameter. • TOUCH_SENSOR_CONFIG_ERR The touch_xxxxcap_sensor_config is fed with an incompatible parameter / Touch Library state is not in TOUCH_STATE_INIT. • TOUCH_INIT_CALIB_ERR The touch_xxxxcap_sensors_calibrate is fed with an invalid parameter / Touch Library state is TOUCH_STATE_NULL/ TOUCH_STATE_BUSY. • TOUCH_MEASURE_INCOMPLETE The touch_measure api has error due to an invalid input param / it was on an invalid Touch Library state. • TOUCH_MEASURE_CC_CAL_FAILED Hardware calibration error; check the hardware and ensure it is proper. If the error persists, check the user manual for sensor design guidelines. 11.3.7. Touch Channel (tag_channel_t) Sensor start and end channel type of a Sensor. Channel number starts with value 0. Data Fields CHANNEL_0 to CHANNEL_255 11.3.8. Touch Library State (tag_touch_lib_state_t) Touch library state. Data Fields • TOUCH_STATE_NULL Touch library is un-initialized. All sensors are disabled. • TOUCH_STATE_INIT Touch library has been initialized • TOUCH_STATE_READY Touch library is ready to start a new capacitance measurement on enabled sensors. • TOUCH_STATE_CALIBRATE Touch library is performing calibration on all sensors. • TOUCH_STATE_BUSY Touch library is busy with on-going capacitance measurement. 11.3.9. Sensor Type (tag_touch_lib_state_t) Sensor types available. Data Fields • SENSOR_TYPE_UNASSIGNED Sensor is not configured yet • SENSOR_TYPE_KEY Sensor type key Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 78 • SENSOR_TYPE_ROTOR Sensor type rotor • SENSOR_TYPE_LUMP Sensor type lump • SENSOR_TYPE_SLIDER Sensor type slider • MAX_SENSOR_TYPE Max value of enum type for testing 11.3.10. Touch Sensing Type (tag_touch_acq_t) Based on the two types of charge transfer technology, the capacitive touch sensing may be either mutual capacitance sensing or self-capacitance sensing. Data Fields • TOUCH_MUTUAL Mutual capacitance sensing • TOUCH_SELF Self-capacitance sensing • MAX_TOUCH_ACQ Max value of enum 11.3.11. Touch Library Acquisition Mode (tag_touch_acq_mode_t) Touch library acquisition mode. Data Fields RAW_ACQ_MODE When raw acquisition mode is used, the measure_complete_callback function is called immediately once a fresh value of signals are available. In this mode, the Touch Library does not perform any post processing. So, the references, sensor states or rotor/slider position values are not updated in this mode. NORMAL_ACQ_MODE When normal acquisition mode is used, the measure_complete_callback function is called only after the Touch Library completes processing of the signal values obtained. The references, sensor states and rotor/slider position values are updated in this mode. 11.3.12. Calibration Auto tune Setting (tag_auto_tune_type_t) Touch library PTC prescaler clock and series resistor auto tuning setting Data Fields • AUTO_TUNE_NONE Auto tuning mode disabled. This mode uses the user defined PTC prescaler and series resistor values. • AUTO_TUNE_PRSC Auto tune PTC prescaler for best noise performance . This mode uses the user defined series resistor value. • AUTO_TUNE_RSEL Auto tune series resistor for least power consumption. This mode uses the user defined PTC prescaler value. 11.3.13. PTC Acquisition Frequency Mode Setting (tag_freq_mode_sel_t) The frequency mode setting option enables the PTC acquisition to be configured for the following modes. • Frequency hopping and spread spectrum disabled. • Frequency hopping enabled with median filter. • Frequency spread spectrum enabled without median filter. • Frequency spread spectrum enabled with median filter. Range: FREQ_MODE_NONE (no frequency hopping & spread spectrum) to FREQ_MODE_SPREAD_MEDIAN (spread spectrum with median filter) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 79 Data Fields • FREQ_MODE_NONE 0u • FREQ_MODE_HOP 1u • FREQ_MODE_SPREAD 2u • FREQ_MODE_SPREAD_MEDIAN 3u 11.3.14. PTC Clock Pre-scaler Setting (tag_prsc_div_sel_t) Refer touch_configure_ptc_clock() API in touch.c Example: If generic clock input to PTC = 4 MHz, • PRSC_DIV_SEL_1 sets PTC Clock to 4 MHz. • PRSC_DIV_SEL_2 sets PTC Clock to 2 MHz. • PRSC_DIV_SEL_4 sets PTC Clock to 1 MHz. • PRSC_DIV_SEL_8 sets PTC Clock to 500 kHz. Data Fields • PRSC_DIV_SEL_1 • PRSC_DIV_SEL_2 • PRSC_DIV_SEL_4 • PRSC_DIV_SEL_8 11.3.15. PTC Series Resistor Setting (tag_rsel_val_t) For mutual capacitance mode, this series resistor is switched internally on the Y-pin. For self-capacitance mode, the series resistor is switched internally on the sensor pin. Example: • RSEL_VAL_0 sets internal series resistor to 0 Ohms. • RSEL_VAL_20 sets internal series resistor to 20 Kohms. • RSEL_VAL_50 sets internal series resistor to 50 Kohms. • RSEL_VAL_100 sets internal series resistor to 100 Kohms. Data Fields • RSEL_VAL_0 • RSEL_VAL_20 • RSEL_VAL_50 • RSEL_VAL_100 11.3.16. PTC Acquisition Frequency Delay Setting (tag_rsel_val_t) The PTC acquisition frequency is dependent on the generic clock input to PTC and PTC clock prescaler setting. This delay setting inserts n PTC clock cycles between consecutive measurements on a given sensor, thereby changing the PTC acquisition frequency. FREQ_HOP_SEL_1 setting inserts 0 PTC clock cycle between consecutive measurements. FREQ_HOP_SEL_16 setting inserts 15 PTC clock cycles. Hence, higher delay setting will increase the total time required for capacitance measurement on a given sensor as compared to a lower delay setting. A desired setting avoids noise in the same frequency as the acquisition frequency. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 80 • FREQ_HOP_SEL_1 • FREQ_HOP_SEL_2 • FREQ_HOP_SEL_3 • FREQ_HOP_SEL_4 • FREQ_HOP_SEL_5 • FREQ_HOP_SEL_6 • FREQ_HOP_SEL_7 • FREQ_HOP_SEL_8 • FREQ_HOP_SEL_9 • FREQ_HOP_SEL_10 • FREQ_HOP_SEL_11 • FREQ_HOP_SEL_12 • FREQ_HOP_SEL_13 • FREQ_HOP_SEL_14 • FREQ_HOP_SEL_15 • FREQ_HOP_SEL_16 11.3.17. AKS Group (tag_aks_group_t) It provides information about the sensors that belong to specific AKS group. NO_AKS_GROUP indicates that the sensor does not belong to any AKS group and cannot be suppressed. AKS_GROUP_x indicates that the sensor belongs to the AKS group x. Data Fields • NO_AKS_GROUP • AKS_GROUP_1 • AKS_GROUP_2 • AKS_GROUP_3 • AKS_GROUP_4 • AKS_GROUP_5 • AKS_GROUP_6 • AKS_GROUP_7 • MAX_AKS_GROUP Max value of enum type for testing. 11.3.18. Sensor Hysteresis Setting (tag_hysteresis_t) A sensor detection hysteresis value. This is expressed as a percentage of the sensor detection threshold. HYST_x = hysteresis value is x% of detection threshold value (rounded down). Note:  A minimum value of 2 is used. Example: If detection threshold = 20, • HYST_50 = 10 (50% of 20) • HYST_25 = 5 (25% of 20) • HYST_12_5 = 2 (12.5% of 20) • HYST_6_25 = 2 (6.25% of 20 = 1, but value is hard limited to 2) Data Fields • HYST_50 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 81 • HYST_25 • HYST_12_5 • HYST_6_25 • MAX_HYST Max value of enum type for testing. 11.3.19. Sensor Recalibration Threshold (tag_recal_threshold_t) This is expressed as a percentage of the sensor detection threshold. RECAL_x = recalibration threshold is x% of detection threshold value (rounded down). Note:  A minimum value of 4 is used. Example: If detection threshold = 40, • RECAL_100 = 40 (100% of 40) • RECAL_50 = 20 (50% of 40) • RECAL_25 = 10 (25% of 40) • RECAL_12_5 = 5 (12.5% of 40) • RECAL_6_25 = 4 (6.25% of 40 = 2, but value is hard limited to 4) Data Fields • RECAL_100 • RECAL_50 • RECAL_25 • RECAL_12_5 • RECAL_6_25 • MAX_RECAL Max value of enum type for testing. 11.3.20. Rotor Slider Resolution (tag_resolution_t) For rotors and sliders, the resolution of the reported angle or position. • RES_x_BIT = rotor/slider reports x-bit values. Example: If slider resolution is RES_7_BIT, then reported positions are in the range 0..127. Data Fields • RES_1_BIT • RES_2_BIT • RES_3_BIT • RES_4_BIT • RES_5_BIT • RES_6_BIT • RES_7_BIT • RES_8_BIT • MAX_RES Max value of enum type for testing. 11.3.21. PTC Sensor Noise Lockout setting (nm_sensor_lockout_t) The sensor lockout setting option allows the system to be configured in the following modes. • SINGLE_SENSOR_LOCKOUT Single sensor can be locked out. • GLOBAL_SENSOR_LOCKOUT All the sensors are locked out for touch detection. • NO_LOCK_OUT All the sensors are available for touch detection. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 82 Range: SINGLE_SENSOR_LOCKOUT to NO_LOCK_OUT. Data Fields • SINGLE_SENSOR_LOCKOUT 0u • GLOBAL_SENSOR_LOCKOUT 1u • NO_LOCK_OUT 2u 11.3.22. 11_3_21_PTC_GPIO_STATE(ptc_gpio_state_t) Detailed Description PTC lines state in unmeasured condition can be set using this enum • PULLHIGH_WHEN_NOT_MEASURED Indicates that default state of PTC lines are at vcc. • GND_WHEN_NOT_MEASURED Indicates that default state PTC lines are grounded. Range: PULLHIGH_WHEN_NOT_MEASURED=0 and GND_WHEN_NOT_MEASURED. Data Fields • PULLHIGH_WHEN_NOT_MEASURED • GND_WHEN_NOT_MEASURED 11.3.23. Moisture Group Setting (moisture_grp_t) Detailed Description Sensor can be configured in the moisture group using this type. • MOIS_DISABLED Indicates that the sensor does not belong to any moisture group. • MOIS_GROUP_X Indicates that the sensor belongs to the moisture group x. Range: MOIS_DISABLED = 0 to MOIS_GROUP_7. Data Fields • MOIS_DISABLED=0 • MOIS_GROUP_0 • MOIS_GROUP_1 • MOIS_GROUP_2 • MOIS_GROUP_3 • MOIS_GROUP_4 • MOIS_GROUP_5 • MOIS_GROUP_6 • MOIS_GROUP_7 • MOIS_GROUPN 11.3.24. Multi-touch Group Setting (mltch_grp_t) Detailed Description Sensor can be configured in the multi-touch group using this type • MLTCH_NONE Indicates that the sensor does not belong to any multi-touch group. • MLTCH_GROUP_X Indicates that the sensor belongs to the multi-touch group x. Range: MLTCH_NONE=0 to MOIS_GROUP_7. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 83 • MLTCH_NONE=0 • MLTCH_GROUP_0 • MLTCH_GROUP_1 • MLTCH_GROUP_2 • MLTCH_GROUP_3 • MLTCH_GROUP_4 • MLTCH_GROUP_5 • MLTCH_GROUP_6 • MLTCH_GROUP_7 • MLTCH_GROUPN 11.3.25. Touch Mode Configuration (tag_tch_mode) Touch mode can be configured. Note:  This is applicable only for ATmega devices. Data Fields • TCH_MODE_POLLED Polled mode • TCH_MODE_ISR Interrupt mode • TCH_MODE_NONE Touch mode is null. 11.3.26. Trigger Mode (tag_trigger_mode) Trigger source for continuous hardware PTC acquisition. It is n clock cycles of internal 128Khz clock. Note:  This is applicable only for ATmega devices. Data Fields • TCH_TRIGGER_128KHZ_4MS • TCH_TRIGGER_128KHZ_8MS • TCH_TRIGGER_128KHZ_16MS • TCH_TRIGGER_128KHZ_32MS • TCH_TRIGGER_128KHZ_64MS • TCH_TRIGGER_128KHZ_128MS • TCH_TRIGGER_128KHZ_256MS 11.4. Datastructures 11.4.1. Touch Library Timing Info (tag_touch_time_t) Touch library time parameter. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 84 Field Unit Description measurement_period_ms uint16_t Touch measurement period in milliseconds. This variable determines how often a new touch measurement must be done. current_time_ms volatile uint16_t Current time set by timer ISR. time_to_measure_touch volatile uint8_t Flag set by timer ISR when it is time to measure touch. 11.4.2. Sensor Info (tag_sensor_t) Sensor structure for storing sensor related information. Data Fields Keyword Type Description state uint8_t Sensor state (calibrate, on, off, filter-in, filter-out, disable, pos-recal) general_counter uint8_t General purpose counter used for calibrating, drifting, etc ndil_counter uint8_t Counter used for detect integration type_aks_pos_hyst uint8_t bits 7..6: sensor type: {00: key,01: rotor,10: slider,11: reserved} bits 5..3: AKS group (0..7): 0 = no AKS group bit 2 : positive recal flag bits 1..0: hysteresis threshold uint8_t Sensor detection threshold from_channel uint8_t Sensor from channel for keys: from channel = to channel. Rotors: Top channel. Sliders : Left most channel Note:  We need to_channel for rotors/sliders only to_channel uint8_t For keys, this is unused. For rotors: Bottom left channel. For sliders: Middle channel index uint8_t Index into array of rotor/slider values 11.4.3. Global Sensor Configuration Info (tag_touch_global_param_t) Touch library global parameter. Data Fields Field Unit Description di uint8_t Detect Integration (DI) limit. atch_drift_rate uint8_t Sensor away from touch drift rate. tch_drift_rate uint8_t Sensor towards touch drift rate. max_on_duration uint8_t MaximumON time duration. drift_hold_time uint8_t Sensor drift hold time. atch_recal_delay uint8_t Sensor away from touch recalibration delay. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 85 Field Unit Description cal_seq_1_count uint8_t Sensor calibration dummy burst count. cal_seq_2_count uint8_t Sensor calibration settling burst count. recal_threshold recal_threshold_t Sensor away from touch recalibration threshold. touch_postprocess_mode Uint16_t Sensor post-processing mode. auto_os_sig_stability_limit uint8_t Stability limit for Auto Oversample feature. auto_tune_sig_stability_limit uint16_t Stability limit for frequency auto tune feature. auto_freq_tune_in_cnt uint8_t Frequency auto tune In counter. nm_sig_stability_limit uint16_t Stability limit for noise measurement. nm_noise_limit uint8_t Noise limit. nm_enable_sensor_lock_out nm_sensor_lockout_t Sensor lockout feature variable. nm_lockout_countdown uint8_t Lockout countdown for noise measurement. Charge_share_delay uint8_t Charge share delay value; applicable only for SAM C20, SAM C21, SAM L22 and ATmega devices. 11.4.4. Filter Callback Data Type (tag_touch_filter_data_t) Touch library filter callback data type. Data Fields Field Unit Description num_channel_signals uint16_t Length of the measured signal values list. p_channel_signals uint16_t Pointer to measured signal values for each channel. 11.4.5. Measure Data Type (tag_touch_measure_data_t) Touch library measure data type. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 86 Field Unit Description measurement_done_t ouch volatile uint8_t Flag set by touch_xxxxcap_measure_complete_callba ck() function when a latest Touch status is available. acq_status touch_acq_status_t Status of touch measurement. num_channel_signal s uint16_t Length of the measured signal values list. *p_channel_signals uint16_t Pointer to measured signal values for each channel. num_channel_refere nces uint16_t Length of the measured reference values list. *p_channel_referen ces uint16_t Pointer to measured reference values for each channel. num_sensor_states uint8_t Number of sensor state bytes. *p_sensor_states uint8_t Pointer to touch status of each sensor. num_rotor_slider_v alues uint8_t Length of the rotor and slider position values list. *p_rotor_slider_va lues uint8_t Pointer to rotor and slider position values. num_sensors uint16_t Length of the sensors data list. *p_cc_calibration_ vals uint16_t Pointer to calibrated compensation values for a given sensor channel. *p_sensors sensor_t Pointer to sensor data. *p_sensor_noise_st atus uint8_t Pointer to noise status of the sensors. *p_nm_ch_noise_val uint16_t Pointer to noise level value of each channel. *p_sensor_mois_sta tus uint8_t Pointer to moisture status *p_auto_os_status uint8_t Pointer to auto-oversamples status cc_calib_status_fl ag uint8_t Flag is set when CC-calibration is ongoing. 11.4.6. Sensor Configuration Parameter (tag_touch_selfcap_param_t,tag_touch_mutlcap_param_t) Touch library self-capacitance and mutual capacitance sensor parameter. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 87 Field Unit Description aks_group aks_group_t Which AKS group, the sensor belongs to. detect_threshold threshold_t An unsigned 8-bit number setting a sensor detection threshold. detect_hysteresis hysteresis_t A sensor detection hysteresis value. This is expressed as a percentage of the sensor detection threshold. HYST_x = hysteresis value is x% of detection threshold value (rounded down). A minimum value of 2 is used. Example: If detection threshold = 20, HYST_50= 10 (50% of 20) HYST_25= 5 (25% of 20) HYST_12_5 = 2 (12.5% of 20) HYST_6_25 = 2 (6.25% of 20 = 1, but value is hard limited to 2) position_resolution resolution_t For rotors and sliders, the resolution of the reported angle or position. RES_x_BIT = rotor/slider reports x-bit values. Example: If slider resolution is RES_7_BIT, then reported positions are in the range 0..127 position_hysteresis uint8_t Sensor position hysteresis. This is valid only for a rotor or slider. bits 1..0: hysteresis. Note:  This parameter is valid only for mutual capacitance method. 11.4.7. Sensor Acquisition Parameter (tag_touch_selfcap_acq_param_t,_tag_touch_mutlcap_acq_param_t) Sensor acquisition parameter. Data Fields Field Unit Description *p_xxxxcap_gain_per_node gain_t Pointer to gain per node. touch_xxxxcap_freq_mode Freq_mode_sel_t Set-up acquisition frequency mode. *xxxxcap_ptc_prsc prsc_div_sel_t Pointer to PTC clock pre-scaler value. *xxxxcap_resistor_value rsel_val_t Pointer to PTC series resistor value. p_xxxxcap_hop_freqs *freq_hop_sel_t Pointer to acquisition frequency settings. *p_xxxxcap_filter_level filter_level_t Pointer to filter level. *p_xxxxcap_auto_os auto_os_t Pointer to auto oversampling. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 88 Field Unit Description *xxxxcap_ptc_prsc_cc_cal prsc_div_sel_t Pointer to PTC clock prescale value during CC calibration. *xxxxcap_resistor_value_cc_cal rsel_val_t Pointer to PTC sense resistor value during CC calibration. 11.4.8. Self-capacitance Sensor Configuration (touch_selfcap_config_t) Touch Library self-capacitance configuration input type. Data Fields Field Unit Description num_channels uint16_t Number of channels. num_sensors uint16_t Number of sensors. num_rotors_and_sliders uint8_t Number of rotors/ sliders. global_param touch_global_param_t Global sensor configuration information. touch_selfcap_acq_param touch_selfcap_acq_param_t Sensor acquisition parameter information. *p_data_blk uint8_t Pointer to data block buffer. buffer_size uint16_t Size of data block buffer. *p_selfcap_y_nodes uint16_t Pointer to selfcapacitance nodes. self_quick_reburst_enable uint8_t Quick re-burst enable. (touch_filter_data_t *p_filter_data) void(*filter_callback) Self-capacitance filter callback. enable_freq_auto_tune uint8_t Frequency auto tune enable. enable_noise_measurement uint8_t Noise measurement enable. nm_buffer_cnt uint8_t Memory allocation buffer. self_mois_tlrnce_enable uint8_t Self-capacitance moisture tolerance enable flag. self_mois_groups uint8_t Number of selfcapacitance moisture groups. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 89 Field Unit Description self_mois_quick_reburst_enable uint8_t Moisture Quick re-burst enable. self_ptc_gpio_state ptc_gpio_state_t GPIO state for Selfcapacitance PTC pins tlib_feature_list tlib_init_fn_ptr Library feature list. 11.4.9. Mutual Capacitance Sensor Configuration (touch_mutlcap_config_t) Touch Library mutual capacitance configuration input type. Data Fields Field Unit Description num_channels uint16_t Number of channels. num_sensors uint16_t Number of sensors. num_rotors_and_sliders uint8_t Number of rotors/ sliders. global_param touch_global_param_t Noise measurement enable/disable. touch_xxxxcap_acq_param touch_xxxxcap_acq_param_t Sensor acquisition parameter info. *p_data_blk uint8_t Pointer to data block buffer. *buffer_size uint16_t Size of data block buffer. *p_mutlcap_xy_nodes uint16_t Pointer to xy-nodes. mutl_quick_reburst_enable uint8_t Quick re-burst enable. (touch_filter_data_t *p_filter_data) void(* filter_callback ) Mutual capacitance filter callback. enable_freq_auto_tune uint8_t Frequency auto tune enable. enable_noise_measurement uint8_t Noise measurement enable. nm_buffer_cnt uint8_t Memory allocation buffer. mutl_mois_tlrnce_enable uint8_t Mutual capacitance moisture tolerance enable flag. mutl_mois_groups uint8_t Number of mutual capacitance moisture groups. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 90 Field Unit Description mutl_mois_quick_reburst_enable uint8_t Moisture Quick re-burst enable. mutl_ptc_gpio_state ptc_gpio_state_t GPIO state for mutual capacitance PTC pins tlib_feature_list tlib_init_fn_ptr Library feature list. 11.4.10. Moisture Structure (tag_snsr_mois_t) Structure for storing moisture and multi-touch group information. Data Fields Field Unit Description mois_grp uint8_t Moisture group member multch_grp uint8_t Multi-touch group member 11.4.11. Touch Library Input Configuration (touch_config_t) Touch Library Input Configuration Structure. Data Fields Field Unit Description p_mutlcap_config touch_mutlcap_config_t Pointer to mutual capacitance configuration structure. p_selfcap_config touch_selfcap_config_t Pointer to self-capacitance configuration structure. ptc_isr_lvl uint8_t PTC ISR priority level. Note:  This is applicable only for SAM devices. tch_mode tch_mode_t Touch mode configuration. Note:  This is applicable only for ATmega devices. 11.4.12. Library Function List (tag_tlib_init_fn_ptr_t) Touch Library support functions initializer. Data Fields Field Unit Description auto_tune_init void(*auto_tune_init) Auto-tune function initializer auto_os_init uint32_t (*auto_os_init) Auto-OS function initializer lk_chk void(*lk_chk) Sensor lock-out function initializer enable_aks void enable_aks(void) AKS function initializer 11.4.13. Touch Library Information (tag_touch_info_t) Touch Library information structure. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 91 Data Fields Field Unit Description tlib_state touch_tlib_state_t Touch library state is specified num_channels_in_use unit16_t Number of channels in use; irrespective of the corresponding sensor being disabled or enabled num_sensors_in_use uint16_t Number of sensors in use; irrespective of the sensor being disabled or enabled num_rotors_sliders_in_use uint8_t Number of rotor sliders in use; irrespective of the Rotor/Slider being disabled or enabled max_channels_per_rotor_slider uint8_t Max possible number of channels per rotor or slider 11.4.14. Touch Library Version Information (touch_libver_info_t) Touch Library version information structure. Data Fields Field Unit Description chip_id unit32_t Chip ID product_id uint16_t Product ID fw_version uint16_t Touch Library Version Bits[12:15] Reserved Bits[8:11] TLIB_MAJOR_VERSION Bits[4:7] TLIB_MINOR_VERSION Bits[0:3] TLIB_PATCH_VERSION 11.5. Global Variables Field Unit Description touch_time touch_time_t This holds the library timing info touch_acq_status touch_acq_status_t This holds the Touch Library acquisition status cc_cal_max_signal_limit uint16_t CC calibration maximum signal limit variable cc_cal_min_signal_limit uint16_t CC calibration minimum signal limit variable Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 92 Field Unit Description *p_selfcap_measure_data touch_measure_data_t This holds the self-capacitance method measure data pointer *p_mutlcap_measure_data touch_measure_data_t This holds the mutual capacitance method measure data pointer wake_up_touch uint8_t Wake up touch status from Library to Application low_power_mode uint8_t Low power mode status from Library to Application mois_lock_global_mutl uint8_t Moisture global lock variable for mutual capacitance method mois_lock_global_self uint8_t Moisture global lock variable for selfcapacitance method 11.6. API 11.6.1. Sensor Init and De-init touch_ret_t touch_mutlcap_sensors_init (touch_config_t * p_touch_config) touch_ret_t touch_selfcap_sensors_init (touch_config_t * p_touch_config) This API is used to initialize the Touch Library with Mutual cap or Self cap method pin, register and sensor configuration provided by the user. Parameters:p_touch_config Pointer to Touch configuration structure. Returns:touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensors_deinit(void) touch_ret_t touch_selfcap_sensors_deinit(void); This API can be used to de-initialize the sensor for specific sensing group. Parameters: void. Returns: touch_ret_t: Touch Library Error status. 11.6.2. Sensor Setup and Configuration touch_ret_t touch_mutlcap_sensor_config (sensor_type_t sensor_type, channel_t from_channel, channel_t to_channel, aks_group_t aks_group, threshold_t detect_threshold, hysteresis_t detect_hysteresis, resolution_tposition_resolution, uint8_t position_hysteresis, sensor_id_t * p_sensor_id) touch_ret_t touch_selfcap_sensor_config (sensor_type_t sensor_type, channel_t from_channel, channel_t to_channel, aks_group_t aks_group, threshold_t detect_threshold, hysteresis_t detect_hysteresis, resolution_tposition_resolution, sensor_id_t * p_sensor_id) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 93 This API can be used to configure a sensor of type key, rotor or slider. Data Fields: Field Description sensor_type can be of type key, lump, rotor, or slider. from_channel the first channel in the slider sensor. to_channel the last channel in the slider sensor. aks_group which AKS group (if any) the sensor is in. detect_threshold the sensor detection threshold. detect_hysteresis the sensor detection hysteresis value. position_resolution the resolution of the reported position value. position_hysteresis the hysteresis for position value (available only for mutual capacitance mode). p_sensor_id the sensor id value of the configured sensor is updated by the Touch Library. Returns: touch_ret_t: Touch Library Error status. 11.6.3. Sensor Calibration touch_ret_t touch_mutlcap_sensors_calibrate (auto_tune_type_t ) touch_ret_t touch_selfcap_sensors_calibrate (auto_tune_type_t ) This API is used to calibrate the sensors for the first time before starting a Touch measurement. This API can also beused to force calibration of sensors when any of the Touch sensor parameters are changed during runtime. Returns:touch_ret_t: Touch Library Error status. 11.6.4. Sensor Measure touch_ret_t touch_mutlcap_sensors_measure (touch_current_time_t current_time_ms, touch_acq_mode_tmutlcap_acq_mode, void(*)(void) measure_complete_callback) touch_ret_t touch_selfcap_sensors_measure (touch_current_time_t current_time_ms, touch_acq_mode_tselfcap_acq_mode, void(*)(void) measure_complete_callback) This API can be used to start a Touch measurement. Parameters: current_time_ms Current time in millisecond. measure_complete_callback Interrupt callback to indicate measurement completion. Returns: touch_ret_t: Touch Library Error status. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 94 11.6.5. Sensor Suspend and Resume touch_ret_t touch_suspend_ptc(void) touch_ret_t touch_resume_ptc(void) The touch_suspend_ptc function suspends the PTC library's current measurement cycle. The completion of the operation is indicated through callback pointer that must be initialized by the application. Refer Sensor Global Parameters. The touch_resume_ptc function resumes the PTC library's current measurement which was suspended using touch_suspend_ptc. After the touch_resume_ptc function is called by the application, the touch_xxxxcap_sensors_measure API should be called only after the measurement complete callback function is received. Parameters: void. Returns: touch_ret_t: Touch Library Error status. 11.6.6. Sensor Disable and Re-enable touch_ret_t touch_mutlcap_sensor_disable (sensor_id_t sensor_id) touch_ret_t touch_selfcap_sensor_disable (sensor_id_t sensor_id) This API can be used to disable any sensor. Parameters: sensor_id Sensor number which needs to be disabled Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensor_reenable (sensor_id_t sensor_id, uint8_t no_calib) touch_ret_t touch_selfcap_sensor_reenable (sensor_id_t sensor_id, uint8_t no_calib) This API can be used to re-enable a disabled sensor. Parameters: sensor_id Sensor number which needs to be reenabled no_calib When value is set to 1, force calibration is not applicable. When value is set to 0, force calibration is applied Returns: touch_ret_t: Touch Library Error status. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 95 11.6.7. Read-back Sensor Configuration touch_ret_t touch_mutlcap_sensor_get_acq_config (touch_mutlcap_acq_param_t * p_touch_mutlcap_acq_param) touch_ret_t touch_selfcap_sensor_get_acq_config (touch_selfcap_acq_param_t * p_touch_selfcap_acq_param) This API can be used to read back the sensor acquisition parameters. Parameters: p_touch_mutlcap_acq_param The acquisition parameters for the mutual capacitance. p_touch_selfcap_acq_param The acquisition parameters for the self-capacitance. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensor_get_config (sensor_id_t sensor_id, touch_mutlcap_param_t *p_touch_sensor_param) touch_ret_t touch_selfcap_sensor_get_config (sensor_id_t sensor_id, touch_selfcap_param_t *p_touch_sensor_param) This API can be used to read back the sensor configuration parameters. Parameters: sensor_id The sensor id for which the parameters has to be read-back. p_touch_sensor_param The sensor parameters for the mutual or self-capacitance. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensor_get_delta (sensor_id_t sensor_id, touch_delta_t * p_delta) touch_ret_t touch_selfcap_sensor_get_delta (sensor_id_t sensor_id, touch_delta_t * p_delta) This API can be used to retrieve the delta value corresponding to a given sensor. Parameters: sensor_id The sensor id for which delta value is being seeked. p_delta Pointer to the delta variable to be updated by the Touch Library. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_get_global_param (touch_global_param_t * p_global_param) touch_ret_t touch_selfcap_get_global_param (touch_global_param_t * p_global_param) This API can be used to read back the global parameter. Parameters: p_global_param The pointer to global sensor configuration. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 96 Returns: touch_ret_t: Touch Library Error status. 11.6.8. Update Sensor Configuration touch_ret_t touch_mutlcap_sensor_update_acq_config (touch_mutlcap_acq_param_t *p_touch_mutlcap_acq_param) touch_ret_t touch_selfcap_sensor_update_acq_config (touch_selfcap_acq_param_t * p_touch_selfcap_acq_param) This API can be used to update the sensor acquisition parameters. Parameters: p_touch_mutlcap_acq_param The acquisition parameters for the mutual capacitance. p_touch_selfcap_acq_param The acquisition parameters for the self-capacitance. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensor_update_config (sensor_id_t sensor_id, touch_mutlcap_param_t *p_touch_sensor_param) touch_ret_t touch_selfcap_sensor_update_config (sensor_id_t sensor_id, touch_selfcap_param_t *p_touch_sensor_param This API can be used to update the sensor configuration parameters. Parameters: sensor_id The sensor id whose configuration parameters has to be changed. p_touch_sensor_param The touch sensor parameter structure that will be used by the Touch Library to update. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_update_global_param (touch_global_param_t * p_global_param) touch_ret_t touch_selfcap_update_global_param (touch_global_param_t * p_global_param) This API can be used to update the global parameter. Parameters: p_global_param The pointer to global sensor configuration. Returns: touch_ret_t: Touch Library Error status. 11.6.9. Get Library Information and Version touch_ret_t touch_mutlcap_get_libinfo (touch_info_t * p_touch_info) touch_ret_t touch_selfcap_get_libinfo (touch_info_t * p_touch_info) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 97 This API can be used to get the Touch Library configuration. Parameters: p_touch_info Pointer to the Touch info data structure that will be updated by the Touch Library. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_library_get_version_info (touch_libver_info_t * p_touch_libver_info) This API can be used to get the Touch Library version information. Parameters: p_touch_libver_info Pointer to the Touch Library Version info data structure that will be updated by the Touch Library. 11.6.10. Moisture Tolerance API touch_ret_t touch_mutlcap_cnfg_mois_mltchgrp(sensor_id_t snsr_id, moisture_grp_t mois_grpid, mltch_grp_t mltch_grpid) touch_ret_t touch_selfcap_cnfg_mois_mltchgrp(sensor_id_t snsr_id, moisture_grp_t mois_grpid, mltch_grp_t mltch_grpid) This API can be used to assign moisture group and multi touch group for a sensor. Parameters: snsr_id - sensor ID mois_grpid - moisture group ID mltch_grp_t - multi-touch group Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_cnfg_mois_threshold(moisture_grp_t mois_grpid, mois_snsr_threshold_t snsr_threshold, mois_system_threshold_t system_threshold) touch_ret_t touch_selfcap_cnfg_mois_threshold(moisture_grp_t mois_grpid, mois_snsr_threshold_t snsr_threshold, mois_system_threshold_t system_threshold) This API is used to assign moisture sensor threshold and moisture system threshold to a moisture group ID Parameters: mois_grpid - moisture group ID snsr_threshold - moisture sensor threshold system_threshold - moisture system threshold Returns: Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 98 touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_mois_tolrnce_enable(void) touch_ret_t touch_selfcap_mois_tolrnce_enable(void) This API is used to enable moisture tolerance check during run time. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_mois_tolrnce_quick_reburst_enable(void) touch_ret_t touch_selfcap_mois_tolrnce_quick_reburst_enable(void) This API is used to enable moisture tolerance quick re- burst feature during run time. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_mois_tolrnce_disable(void) touch_ret_t touch_selfcap_mois_tolrnce_disable(void) This API is used to disable moisture tolerance check during run time. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_mois_tolrnce_quick_reburst_disable(void) touch_ret_t touch_selfcap_mois_tolrnce_quick_reburst_disable(void) This API is used to disable moisture tolerance quick re- burst feature during run time. Returns: touch_ret_t: Touch Library Error status. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 99 12. Revision History Doc. Rev. Date Comments Rev.M 07/2016 1. Updated the latest software version numbers in Section 1 2. Added a new errata in Section 9 Rev.L 04/2016 Updated Sections 1, 5, and 8 with reference to the latest extension release Rev.K 02/2016 Added ATmega324PB support. Updated Sections 1, 5 and 8 with reference to the latest extension release Rev.J 01/2016 Included the following new sections: 1. Compensation Circuit 2. Using Atmel ICE for Qdebug Data Streaming 3. Application flow for megaAVR Updated Sections 5 and 8 with reference to the latest extension release Rev.I 09/2015 Included Charge share delay Updated Section 5 .2.8 and 5.2.10 - Library parameters for quick re-burst and moisture parameters added Updated Section 11.6.8 - Moisture API's Added Updated section 8 - Example projects updated Rev.H 06/2015 Revised Section 2 - Device Variants Supported and included information on device multiplexing option Updated Section 7.2 - Code and data memory considerations Updated Section 5.2.1 - Pin, Channel, and Sensor Parameters Rev.G 04/2015 Updated Section 2 - Device Variants Supported and included information on device multiplexing option Rev.F 02/2015 Included relevant information regarding low-power and lumped mode support Rev.E 11/2014 Included Section 5.2.6 and 5.2.7 regarding noise counter measures. Included Section 3 regarding overview of capacitive touch technology. Rev.D 02/2014 Global updates across the document related to QTouch Library and QTouch Composer 5.3 Rev.C 10/2013 Included Section 3.3.4, Using QDebug Touch Data Debug Communication Included a note on interrupt handler for IAR example project in Section 3.3.3 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 100 Doc. Rev. Date Comments Rev.B 10/2013 Updated errata in Section 4, Known Issues Rev.A 09/2013 Initial document release Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 101 Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 | www.atmel.com © 2016 Atmel Corporation. / Rev.: Atmel-42195M-Peripheral-Touch-Controller_User Guide-07/2016 Atmel® , Atmel logo and combinations thereof, Enabling Unlimited Possibilities® , AVR ® QTouch® , AKS® and others are registered trademarks or trademarks of Atmel Corporation in U.S. and other countries. ARM® and Cortex® are registered trademarks of ARM Limited. Other terms and product names may be trademarks of others. DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life. SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments unless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specifically designated by Atmel as automotive-grade.

Software Atmel Studio USER GUIDE Preface Atmel® Studio is an Integrated Development Environment (IDE) for writing and debugging AVR® /ARM® applications in Windows® XP/Windows Vista® / Windows 7/8 environments. Atmel Studio provides a project management tool, source file editor, simulator, assembler, and front-end for C/C++, programming, and on-chip debugging. Atmel Studio supports the complete range of Atmel AVR tools. Each new release contains the latest updates for the tools as well as support for new AVR/ARM devices. Atmel Studio has a modular architecture, which allows interaction with 3rd party software vendors. GUI plugins and other modules can be written and hooked to the system. Contact Atmel for more information. Atmel-42167B-Atmel-Studio_User Guide-09/2016 Table of Contents Preface............................................................................................................................ 1 1. Introduction................................................................................................................8 1.1. Features....................................................................................................................................... 8 1.2. New and Noteworthy.................................................................................................................... 8 1.2.1. Atmel Studio 7.0............................................................................................................ 8 1.2.2. Atmel Studio 6.2 Service Pack 2..................................................................................11 1.2.3. Atmel Studio 6.2 Service Pack 1..................................................................................11 1.2.4. Atmel Studio 6.2...........................................................................................................11 1.2.5. Atmel Studio 6.1 Update 2...........................................................................................12 1.2.6. Atmel Studio 6.1 Update 1.1........................................................................................12 1.2.7. Atmel Studio 6.1 Update 1...........................................................................................12 1.2.8. Atmel Studio 6.1.......................................................................................................... 12 1.2.9. Atmel Studio 6.0.......................................................................................................... 12 1.2.10. AVR Studio 5.1.............................................................................................................13 1.3. Installation.................................................................................................................................. 13 1.4. Contact Information.................................................................................................................... 14 2. Getting started......................................................................................................... 16 2.1. Starting Atmel Studio..................................................................................................................16 2.2. Creating a Project.......................................................................................................................17 2.2.1. Introduction.................................................................................................................. 17 2.2.2. Creating a new Project................................................................................................ 17 2.2.3. Choosing a Target Device............................................................................................19 2.2.4. Writing and Compiling Code........................................................................................ 19 3. Project Management................................................................................................22 3.1. Introduction.................................................................................................................................22 3.1.1. The Solution Container................................................................................................ 22 3.1.2. Save and Open Projects..............................................................................................22 3.1.3. Project Output View..................................................................................................... 22 3.1.4. Solution Explorer......................................................................................................... 22 3.1.5. Toolbar Icons............................................................................................................... 23 3.1.6. Hierarchical Display..................................................................................................... 23 3.1.7. Item Management Commands.................................................................................... 23 3.1.8. Project Components.................................................................................................... 23 3.2. GCC Projects..............................................................................................................................25 3.2.1. New Project Wizard..................................................................................................... 25 3.2.2. Starting a New GCC Project for AVR Device...............................................................25 3.2.3. Libraries Options..........................................................................................................29 3.2.4. Starting a New GCC Project for SAM (ARM) Device...................................................33 3.2.5. Code Editing................................................................................................................ 36 3.2.6. Starting a New GCC Static Library Project.................................................................. 37 3.2.7. GCC Project Options and Configuration......................................................................40 3.3. Assembler Projects.....................................................................................................................57 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 2 3.3.1. Create New Assembler Project....................................................................................57 3.3.2. Assembler Options ..................................................................................................... 60 3.4. Import of Projects....................................................................................................................... 62 3.4.1. Introduction.................................................................................................................. 62 3.4.2. Import AVR Studio 4 Project........................................................................................ 62 3.4.3. Import AVR 32 Studio Project...................................................................................... 65 3.4.4. Import Project Template...............................................................................................69 3.5. Debug Object File in Atmel Studio..............................................................................................71 3.5.1. Introduction.................................................................................................................. 71 3.5.2. Atmel Studio Supported Debug Formats..................................................................... 72 3.5.3. Opening Object Debug File in Atmel Studio................................................................ 72 4. Debugging............................................................................................................... 77 4.1. Introduction.................................................................................................................................77 4.1.1. Debug Platform Independent Debug Environment...................................................... 77 4.1.2. Differences Between Platforms....................................................................................77 4.2. Starting a Debug Session...........................................................................................................77 4.3. Ending a Debug Session............................................................................................................77 4.4. Attaching to a Target...................................................................................................................78 4.5. Start without Debugging............................................................................................................. 78 4.5.1. One Click Programming - Program and Run............................................................... 78 4.5.2. Keyboard Shortcut....................................................................................................... 79 4.6. Debug Control............................................................................................................................ 79 4.7. Breakpoints.................................................................................................................................81 4.7.1. General Information on Breakpoints............................................................................ 81 4.7.2. Operations with Breakpoints........................................................................................82 4.7.3. Breakpoint Window......................................................................................................84 4.8. Data Breakpoints........................................................................................................................86 4.8.1. Adding Data Breakpoint...............................................................................................86 4.8.2. Data Breakpoints Window........................................................................................... 87 4.8.3. General Information on Data Breakpoint..................................................................... 98 4.8.4. Data Breakpoint Usage................................................................................................99 4.9. QuickWatch, Watch, Locals, and Autos Windows......................................................................99 4.9.1. Watch Window...........................................................................................................100 4.9.2. Locals Window...........................................................................................................102 4.9.3. Autos Window............................................................................................................103 4.9.4. QuickWatch and Watches..........................................................................................104 4.9.5. Expression Formatting...............................................................................................105 4.10. DataTips................................................................................................................................... 106 4.10.1. Expanding and Editing Information............................................................................107 4.10.2. Making a DataTip Transparent...................................................................................108 4.10.3. Visualizing Complex Data Types............................................................................... 108 4.10.4. Adding Information to a Watch Window.....................................................................108 4.10.5. Importing and Exporting DataTips............................................................................. 108 4.11. Disassembly View ................................................................................................................... 108 4.12. I/O View.................................................................................................................................... 110 4.12.1. About the I/O View..................................................................................................... 110 4.12.2. Using the I/O View Tool.............................................................................................. 111 4.12.3. Editing Values and Bits in Break Mode...................................................................... 111 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 3 4.13. Processor View ........................................................................................................................ 111 4.14. Register View............................................................................................................................112 4.15. Memory View............................................................................................................................112 4.16. Call Stack Window....................................................................................................................113 4.17. Object File Formats.................................................................................................................. 116 4.18. Trace.........................................................................................................................................117 4.18.1. Application Output......................................................................................................117 4.18.2. Program Counter Sampling........................................................................................118 4.18.3. Variable Watching...................................................................................................... 118 4.19. Trace View................................................................................................................................119 4.19.1. Trace View Options....................................................................................................119 4.19.2. Trace View Interpretation...........................................................................................122 5. Programming Dialog..............................................................................................125 5.1. Introduction...............................................................................................................................125 5.2. Interface Settings......................................................................................................................128 5.3. Tool Information........................................................................................................................131 5.4. Board Settings/Tool Settings.................................................................................................... 132 5.4.1. Power Debugger........................................................................................................132 5.4.2. STK600......................................................................................................................132 5.4.3. QT600........................................................................................................................133 5.4.4. STK500......................................................................................................................133 5.5. Card Stack................................................................................................................................134 5.6. Device Information....................................................................................................................135 5.7. Oscillator Calibration................................................................................................................ 136 5.8. Memories..................................................................................................................................137 5.9. Fuse Programming...................................................................................................................139 5.10. Lock Bits...................................................................................................................................140 5.11. Production Signatures.............................................................................................................. 140 5.12. Production Files........................................................................................................................141 5.13. Security.....................................................................................................................................144 5.14. Automatic Firmware Upgrade Detection...................................................................................145 6. Miscellaneous Windows........................................................................................ 146 6.1. Device Pack Manager.............................................................................................................. 146 6.2. User Interface Profile Selection................................................................................................148 6.3. Available Tools View.................................................................................................................149 6.3.1. Introduction................................................................................................................ 149 6.3.2. Tool Actions............................................................................................................... 150 6.3.3. Add a Non-detectable Tool........................................................................................ 150 6.4. Tool Info Window...................................................................................................................... 152 6.4.1. Xplained Pro Kits....................................................................................................... 154 6.4.2. Disable the Tools Info Window...................................................................................154 6.4.3. Manually Showing the Window..................................................................................154 6.5. Firmware Upgrade....................................................................................................................154 6.5.1. Introduction................................................................................................................ 154 6.5.2. Automatic Upgrade.................................................................................................... 154 6.5.3. Manual Upgrade........................................................................................................ 155 6.6. Find and Replace Window........................................................................................................155 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 4 6.7. Export Template Wizard........................................................................................................... 159 6.7.1. Project Template........................................................................................................ 160 6.7.2. Item Template............................................................................................................ 160 6.7.3. Template Parameters.................................................................................................160 6.8. Kit Mode Setting....................................................................................................................... 162 7. Atmel GNU Toolchains...........................................................................................163 7.1. GNU Compiler Collection (GCC)..............................................................................................163 7.2. ARM Compiler and Toolchain Options: GUI ............................................................................ 163 7.3. ARM GNU Toolchain Options...................................................................................................168 7.3.1. ARM/GNU Common Options.....................................................................................168 7.3.2. Compiler Options....................................................................................................... 168 7.3.3. Linker Options............................................................................................................171 7.3.4. Assembler Options.................................................................................................... 172 7.3.5. Preprocessing Assembler Options............................................................................ 172 7.3.6. Archiver Options........................................................................................................ 172 7.4. Binutils......................................................................................................................................173 7.5. AVR Compiler and Toolchain Options: GUI .............................................................................173 7.6. Commonly Used Options..........................................................................................................178 7.6.1. Compiler Options....................................................................................................... 178 7.6.2. Linker Options............................................................................................................181 7.6.3. Assembler Options.................................................................................................... 182 7.7. 8-bit Specific AVR GCC Command Line Options.....................................................................182 7.7.1. AVR C Compiler.........................................................................................................182 7.7.2. AVR C Linker............................................................................................................. 183 7.8. 32-bit Specific AVR GCC Command Line Options...................................................................183 7.8.1. Optimization...............................................................................................................183 7.8.2. Debugging................................................................................................................. 184 7.8.3. AVR32 C Linker......................................................................................................... 185 7.9. Binutils......................................................................................................................................186 8. Extending Atmel Studio......................................................................................... 187 8.1. Extension Manager UI..............................................................................................................187 8.2. Registering at Atmel Extension Gallery....................................................................................188 8.3. Installing New Extensions in Atmel Studio............................................................................... 189 8.4. Visual Assist............................................................................................................................. 192 8.5. Overview of QTouch Composer and Library............................................................................ 193 8.5.1. Installation..................................................................................................................194 8.5.2. Overview of QTouch Project Builder.......................................................................... 194 8.5.3. Overview of QTouch Analyzer................................................................................... 195 8.6. Scripting Extensions.................................................................................................................196 8.6.1. Debug Scripting......................................................................................................... 196 9. Menus and Settings...............................................................................................199 9.1. Customizing Existing Menus and Toolbars...............................................................................199 9.2. Reset Your Settings..................................................................................................................200 9.3. Options Dialog Box...................................................................................................................201 9.3.1. Environment Options................................................................................................. 201 9.3.2. Project Options.......................................................................................................... 218 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 5 9.3.3. Source Control...........................................................................................................221 9.3.4. Text Editor Options.................................................................................................... 221 9.3.5. Debugger................................................................................................................... 237 9.3.6. Atmel Software Framework Settings......................................................................... 238 9.3.7. Builder........................................................................................................................239 9.3.8. Device and Tool Libraries.......................................................................................... 239 9.3.9. Status Management...................................................................................................239 9.3.10. Text Templating..........................................................................................................240 9.3.11. Toolchain....................................................................................................................240 9.3.12. GDB Settings............................................................................................................. 241 9.4. Code Snippet Manager............................................................................................................ 242 9.4.1. Managing Code Snippets.......................................................................................... 242 9.4.2. Code Snippet Manager Layout.................................................................................. 243 9.4.3. Modifying Existing Code Snippets............................................................................. 243 9.5. External Tools...........................................................................................................................244 9.5.1. Add an External Tool to the Tools Menu.................................................................... 244 9.5.2. Pass Variables to External Tools................................................................................245 9.5.3. Initial Directory........................................................................................................... 246 9.5.4. Run Behavior............................................................................................................. 246 9.5.5. Assign a Keyboard Shortcut...................................................................................... 246 9.6. Predefined Keyboard Shortcuts............................................................................................... 246 10. Command Line Utility (CLI)................................................................................... 262 11. Frequently Asked Questions..................................................................................263 11.1. Compatibility with Legacy AVR Software and Third-party Products.........................................265 11.1.1. How do I Import External ELF Files for Debugging?................................................. 265 11.1.2. How do I Reuse My AVR Studio 4 Projects with the New Atmel Studio?.................. 265 11.2. Atmel Studio Interface.............................................................................................................. 266 11.2.1. How can I Start Debugging My Code? What is the Keyboard Shortcut for Debugging? ...................................................................................................................................266 11.2.2. What is a Solution?....................................................................................................266 11.2.3. What is a Project........................................................................................................266 11.2.4. How can I use an External Makefile for my Project?................................................. 266 11.2.5. When Watching a Variable, the Debugger says Optimized away......................266 11.2.6. When Starting a Debug Session, I get an Error Stating that Debug Tool is not Set ...................................................................................................................................267 11.3. Performance Issues..................................................................................................................267 11.3.1. Atmel Studio Takes a Very Long Time to Start on My PC, but Runs Well in a VM Environment. Is there Something I Can do With This?..............................................267 11.3.2. Verification and Programming often Fails with a Serial Port Buffer Overrun Error Message when using STK500................................................................................... 267 11.3.3. I've connected my Tool through a USB Hub, and now I get Error Messages and Inconsistent Results while Programming and Debugging......................................... 267 11.4. Driver and USB Issues............................................................................................................. 267 11.4.1. How do I get my Tool to be Recognized by Atmel Studio?........................................ 267 11.4.2. The Firmware upgrade Process fails or is Unstable on a Virtualized Machine..........268 11.4.3. Debugging never Breaks under a Virtualized Machine..............................................268 11.4.4. No Tool is recognized by Atmel Studio, but the Driver seems to be Working............268 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 6 11.4.5. Firmware Upgrade Fails on VirtualBox...................................................................... 268 11.4.6. Common Jungo USB Errors...................................................................................... 269 11.4.7. Issues with ARM Compatible Tools........................................................................... 270 12. Document Revision History................................................................................... 272 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 7 1. Introduction 1.1. Features Atmel Studio provides a large set of features for project development and debugging. The most notable features are listed below. • Rich code editor for C/C++ and Assembly featuring the powerful Visual Assist extension • Cycle correct simulator with advanced debug functionality • Atmel Software Framework allowing creation of modular applications and providing building blocks for a prototype on any AVR platform • Debugging on actual devices using Debugging Tools • Rich SDK to enable tight integration of customer plugins • Compatible with many Microsoft® Visual Studio® plugins 1.2. New and Noteworthy New features available. 1.2.1. Atmel Studio 7.0 Atmel Studio 7.0.1006 The following changes are done in Atmel Studio 7.0.1006: • New Atmel Start extension that allows the user to create and configure Atmel Start projects within Atmel Studio • Ability to load multiple modules in a debug session (experimental) • AVR 8-bit GCC Toolchain 3.5.3 with upstream versions: – gcc 4.9.2 – Binutils 2.26 – avr-libc 2.0.0 – gdb 7.8 • ARM GCC Toolchain 5.3.1 with upstream versions: – gcc (ARM/embedded-5-branch revision 234589) – Binutils 2.26 – gdb 7.10 Atmel Studio 7.0.1006 contains a fix for the following issues that were present in 7.0.943: • AVRSV-6878: Atmel Studio write the write-once wdt registers on some SAM devices. • AVRSV-7470: SAM Cortex® -M7 devices fails launch occasionally. • AVRSV-7471: Devices with external and internal RAM lists all the RAM as available. • AVRSV-7473: Atmel Studio hangs during startup. • AVRSV-7474: Kits connected to Atmel Studio are not getting enumerated in the QTouch Start Page. • AVRSV-7477: Show all files does not work from solution explorer. • AVRSV-7482: Exception when adding breakpoint on SAM4L. • AVRSV-7486: Debugging may fail in Cortex-M0+ SAM devices at high clock speeds. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 8 Atmel Studio 7.0.943 Atmel Studio 7.0.943 contains a fix for the following issue: • AVRSV-7459: Projects containing files with upper case file names can fail to build. Saving files with upper case file names converts file name to lower case. Atmel Studio 7.0.934 The following changes are done in Atmel Studio 7.0.934: • AVR 8-bit GCC Toolchain 3.5.2 with upstream versions: – gcc 4.9.2 – Binutils 2.26 – avr-libc 2.0.0 – gdb 7.8 • AVR 32-bit GCC Toolchain 3.4.3 with upstream versions: – gcc 4.4.7 – Binutils 2.23.1 – Newlib 1.16.0 • ARM GCC Toolchain 4.9.3 with upstream versions: – gcc (ARM/embedded-4_9-branch revision 224288) – Binutils 2.24 – gdb 7.8.0.20150304-cvs Atmel Studio 7.0.934 resolves the following issues present in Atmel Studio 7.0.790: • AVRSV-7376: Atmel-ICE slow programming. • AVRSV-7379: Unhandled exception when writing fuses or lockbits when Auto Read is turned off. • AVRSV-7396: Some machines shows an error regarding 'Exception in MemoryPressureReliever'. • AVRSV-7400: When in Standard mode, Disable debugWire and Close are not visible in the Debug menu. • AVRSV-7408: When using Atmel Studio in Standard mode, the Set Startup Project menu is missing. Atmel Studio 7.0.790 The following features are added in Atmel Studio 7.0.790: • Support for mass storage mode in embedded debugger (EDBG), enabling drag and drop programming • Introduction of user interface profiles. The user can choose an interface where some of the toolbar buttons and menu items are removed. • Support for importing libraries to previously imported sketches. Added support for Arduino Zero and Zero Pro. • Parallel build turned on by default Atmel Studio 7.0.790 resolves the following issues present in Atmel Studio 7.0.634: • AVRSV-7084: Persist user settings during upgrade. • AVRSV-7014: Some ATmega and ATtiny devices failed to start debugging with the Simulator. • AVRSV-7230: "Show all files" in Solution Explorer not consistent. • AVRSV-7062: Firmware upgrade of Xplained Mini kits not detected. • AVRSV-7164: Reading flash to .bin file created incorrect .bin file. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 9 • AVRSV-7106: Hex files with Unix® or mixed file endings fail to load. • AVRSV-7126: Databreakpoints for ARM should not be limited to RAM. Atmel Studio 7.0.634 This release adds device support for the SAM B11 device family. Atmel Studio 7.0.634 resolves the following issues present in Atmel Studio 7.0.594: • AVRSV-6873: Jungo Driver issue with Windows 10. Note:  If you install this version of Atmel Studio in parallel with an older Studio versions or IAR Embedded Workbench® and are using AVR Dragon™ , AVRISP mkII, JTAGICE mkII, AVR ONE!, STK® 600, or QT600 read How to downgrade to use older Jungo drivers. • AVRSV-6676: Launching debugging fails due to issue with Intel graphics driver. Atmel Studio 7.0.594 Atmel Studio 7.0.594 resolves the following issues present in Atmel Studio 7.0.582: • AVRSV-7008: Opening a 6.2 project in Atmel studio 7.0.582 persists Debug configuration settings for all the other configurations. • AVRSV-6983: Uninstalling Studio extensions does not work in some cases. • AVRSV-7018: Project Creation fails with some culture specific user names. • AVRSV-7019: Help Viewer does not work on 32-bit machines. • Issues with getting tools/debuggers recognized or visible see section 2.4 in ‘Atmel Studio 7.0.594- readme.pdf’ for workarounds. Atmel Studio 7.0.582 • Updated to Visual Studio Isolated Shell 2015 • Integration with Atmel Start. – This tool will help you select and configure software components, drivers, middle-ware, and example projects to tailor your embedded application in a usable and optimized manner • New device support system, CMSIS Pack compliant • Data Visualizer, used for processing and visualizing data • Updated help system, improved context sensitive help • Atmel Software Framework version 3.27.3. ASF is an extensive software library of software stacks and examples. • A major upgrade of the Visual Assist extension to Atmel Studio that assists with reading, writing, refactoring, navigating code fast • Import Arduino Sketch projects into Atmel Studio • Support for Flip-compatible bootloaders in atprogram and programming dialogue. The connected device appears as a tool. • AVR 8-bit GCC Toolchain 3.5.0 with upstream versions1 : – gcc 4.9.2 – Binutils 2.25 – avr-libc 1.8.0svn – gdb 7.8 • AVR 32-bit GCC Toolchain 3.4.3 with upstream versions1 : – gcc 4.4.7 – Binutils 2.23.1 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 10 – Newlib 1.16.0 • ARM GCC Toolchain 4.9.3 with upstream versions1 : – gcc 4.9 (revision 221220) – Binutils 2.24 – gdb 7.8.0.20150304-cvs 1.2.2. Atmel Studio 6.2 Service Pack 2 • Atmel Software Framework 3.21.0 • Added support for the ATSAML21 device family • Added support for the ATSAMV7 device family, based on the ATM Cortex-M7 core 1.2.3. Atmel Studio 6.2 Service Pack 1 • Atmel Software Framework 3.19.0 • AVR 8-bit Toolchain 3.4.5 with upstream versions: – GCC 4.8.1 – Binutils 2.41 – avr-libc 1.8.0svn – gdb 7.8 • AVR 32-bit Toolchain 3.4.2 with upstream versions: – GCC 4.4.7 – Binutils 2.23.1 • ARM GCC Toolchain 4.8.4 with upstream versions: – GCC 4.8.4 – Binutils 2.23.1 – gdb 7.8 • Support for trace buffers for ARM (MTB) and 32-bit AVR UC3 (NanoTrace) • Support for attaching to targets 1.2.4. Atmel Studio 6.2 • Atmel Software Framework 3.17.0 • AVR 8-bit Toolchain 3.4.4 (with upstream GCC 4.8.1) • AVR 32-bit Toolchain 3.4.2 (with upstream GCC 4.4.7) • ARM GCC Toolchain 4.8.3 • Support for Atmel-ICE • Support for Xplained Mini • Support for data breakpoints • Read OSCCAL calibration for tinyAVR® and megaAVR® • Create ELF production files for AVR 8-bit using the programming dialogue • Live Watch 1 For more information, see the readme that is installed as part of the toolchain. 2 For more information, see the readme that is installed as part of the toolchain. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 11 • Non-intrusive trace support for SAM3 and SAM4 family of devices including – Interrupt trace and monitoring – Data trace – FreeRTOS™ awareness – Statistical code profiling • Polled Data trace support for Cortex M0+ • Default debugger for SAM devices is now GDB. GDB does in some scenarios handle debugging of optimized code better. • Support to create a GCC Board project (Atmel board\User board) for ALL the installed versions of ASF • New ASF Board Wizard, to Add or Remove Board Project Template • Improved loading time of New Example Project dialog, by loading only one ASF version by default • IDR events now gets displayed in a separate pane in the output window • LSS file syntax highlighting 1.2.5. Atmel Studio 6.1 Update 2 • Support for SAM D20 devices on the JTAGICE3 • Atmel Software Framework 3.11.0 1.2.6. Atmel Studio 6.1 Update 1.1 • Fix programming of boot section for XMEGA devices introduced in 6.1 update 1 • Fix SAM4LSP32 bare-bone project setup 1.2.7. Atmel Studio 6.1 Update 1 • Atmel Software Framework 3.9.1 • Extension Development Kit (XDK). Support for packaging an Embedded Application project into an Atmel Gallery Extension. • Support for SAM D20 and SAM4N devices • ARM GCC Toolchain 4.7.3 with experimental newlib-nano and multilibs 1.2.8. Atmel Studio 6.1 • Support for Embedded Debugger platform • Support for Xplained Pro kits • Atmel Software Framework 3.8.0 • AVR 8-bit Toolchain 3.4.2 (with upstream GCC 4.7.2) • AVR 32-bit Toolchain 3.4.2 (with upstream GCC 4.4.7) • ARM GCC Toolchain 4.7.3 • CMSIS 3.20 • Updated Visual Assist • Command line utility for firmware upgrade • Stimulus for simulator. Create a stimuli file to write register values while executing simulation. 1.2.9. Atmel Studio 6.0 • Support for Atmel ARM-based MCUs with Atmel SAM-ICE • Atmel Software Framework 3.1.3 • AVR Toolchain 3.4.0 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 12 • ARM Toolchain 3.3.1 • Atmel Software Framework Explorer • Support for QTouch Composer as extension • Updated Visual Assist • New extension gallery 1.2.10. AVR Studio 5.1 • New version of AVR Software Framework (ASF) • Availability and installation of new ASF versions through extension manager, without having to upgrade Studio 5 • Support for side by side versioning of ASF, with the ability to upgrade projects • Syntax highlighting and better debugging support for C++ projects • Support for importing AVR 32 Studio C++ projects • New version of AVR Toolchain • New command line utility (atprogram) with support for all Atmel AVR tools and devices • Enhancements to programming dialog including support for ELF programming • New version of Visual Assist with several enhancements and bugfixes 1.3. Installation Installation instructions. Supported Operating Systems • Windows 7 Service Pack 1 or higher • Windows Server 2008 R2 Service Pack 1 or higher • Windows 8 / 8.1 • Windows Server 2012 and Windows Server 2012 R2 • Windows 10 Supported Architectures • 32-bit (x86) • 64-bit (x64) Hardware Requirements • Computer that has a 1.6GHz or faster processor • RAM – 1GB RAM for x86 – 2GB RAM for x64 – An additional 512MB RAM if running in a Virtual Machine • 6GB of available hard disk space Downloading and Installing • Download the latest Atmel Studio installer • Atmel Studio can be run side by side with older versions of Atmel Studio and AVR Studio® . Uninstallation of previous versions is not required. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 13 • Verify the hardware and software requirements from the "System Requirements" section • Make sure your user have local administrator privileges • Save all your work before starting. The installation might prompt you to restart, if required. • Disconnect all Atmel USB/Serial hardware devices • Double click the installer executable file and follow the installation wizard • Once finished, the installer displays an option to Start Atmel Studio after completion. If you choose to open, then note that Atmel Studio will launch with administrative privileges, since the installer was either launched as administrator or with elevated privileges. 1.4. Contact Information Report any problems you experience with this version of Atmel Studio. We would also like to receive good ideas and requests that can help to improve further development and releases of Atmel Studio. Check out the Atmel Knowledge Base for any issues that you might encounter. From the same page, it is possible to contact Atmel Support through the new support portal which is linked up with your myAtmel account. For the latest updates of Atmel Studio, visit the Atmel web site: www.atmel.com. Reporting Bugs Copy the information from the version dialog (see the figure below) and include it in the email to Atmel. Also, make sure to provide a detailed description of the problem: 1. Describe how to recreate the problem. 2. Attach any test program that causes the problem. 3. Check that the copied version information contains used debug platform and device. The version dialog is opened by the file menu Help → About Atmel Studio. Debug platform and device are only displayed if you are in debug mode. Push the copy button to copy the contents to the clipboard. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 14 Figure 1-1. Atmel Studio About Box Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 15 2. Getting started 2.1. Starting Atmel Studio Atmel Studio is started by clicking on the Atmel Studio 7.0 shortcut in the Start-up menu. Once started, the start page is displayed. From within this page you can create new projects and reopen recently used projects, as well as browse through articles providing tutorials, help and news. The Start page can also be accessed from View → Start Page, or Alt V G . Figure 2-1. The Project Related Section of the Start Page The left section of the start page contains project-related items: • New project - Use this to create a new project. If you are new to the concept of software development with Atmel Studio, refer to the step-by-step guides. The project settings and available options are described in detail in Project Management. • New example project - To take a step-by-step tour of the available Atmel platforms' functionalities using the Atmel Software Framework, click this button. • Open project - Load an existing project, not mentioned on the Recent projects pane. The Recent projects lists the most recently opened projects. Clicking on any of the links will open the project, restoring it and the GUI to its last saved settings. You can select the number of projects you would like to be shown in the Menus and Settings. Discover Atmel Studio Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 16 This section contains links to helpful information about how to use Atmel Studio and related tools. Announcements In the Announcements section you can read the Atmel RSS feed or any other RSS feed. From the Tools > Options... menu, select Start Page > Feeds to configure which RSS feeds that should be seen. In order to turn ON or OFF the feeds, use the Show feeds check-box. 2.2. Creating a Project 2.2.1. Introduction Atmel Studio is based on Visual Studio, and hence the application development process is organized into projects and The Solution Container. The following sections demonstrates how to create a new GCC C executable project and write a simple application. 2.2.2. Creating a new Project On the Start Page discussed in Getting started, click the New Project option. Figure 2-2. Project Options The project wizard appears. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 17 Figure 2-3. Project Wizard About project types Table 2-1. Project Types Category Project templates Description C/C++ GCC C ASF Board Project Select this template to create an AVR 8-bit or AVR/ARM 32- bit ASF Board project. C/C++ GCC C Executable Project Select this template to create an AVR 8-bit or AVR/ARM 32- bit GCC project. C/C++ GCC C Static Library Project Select this template to create an AVR 8-bit or AVR/ARM 32- bit GCC static library(LIB) project. C/C++ GCC C++ Executable Project Select this template to create an AVR 8-bit or AVR/ARM 32- bit C++ project. C/C++ GCC C++ Static Library Project Select this template to create an AVR 8-bit or AVR/ARM 32- bit C++ static library (LIB) project. Assembler Assembler Project Select this template to create an AVR 8-bit Assembler project. Category Project Templates Description Note:  Extensions and plugins to Atmel Studio may provide new project templates. Create a project Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 18 1. In the New Project dialog box, select Installed Templates. This lists the available project types. 2. For this example, create an GCC C Executable Project. 3. In the Name box, type a name for the new project. 4. In the Location box, select a save location. 5. Atmel Studio will suggest a name in the Solution name box. You can override this name if wanted. 6. Leave the Create directory for solution checkbox checked. 7. Click OK. 2.2.3. Choosing a Target Device When a new project is created, the Device Selection dialog is displayed and you will be prompted to select the project target device. Figure 2-4. Device Selection The device selection dialog lists all supported devices for the current project type. To narrow down the selection of devices, select the device family in the Device Family field, or use the Search for Device field to view a filtered list of devices matching your search string. Select a device 1. In the Device Selection dialog, select ATxmega128A1. 2. Click OK. 2.2.4. Writing and Compiling Code Your solution and project has been created. You can now start editing your application. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 19 Figure 2-5. Code Editor Atmel Studio automatically opens the newly created C file in the source editor. If the file is closed at any time, double click on [Project_name].c - in this case GccApplication1.c - to open it in the editor. At this time the C file contains only an include statement for I/O manipulation and a simple main() function. Create and build a simple application 1. Replace the original main function with the following source code: #define MAXINT 200000 int main(void) { unsigned int t=1000, k=0, l=5, pn=2; unsigned int primes[t]; primes[0]=2; primes[1]=3; while (pn < t || primes[pn] < MAXINT) { for ( k = 0; k <= pn; k++) { if (l % primes[k] == 0) { goto otog; } else { if (k == pn) primes[pn++]=l; } } otog: l += 2; } Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 20 return 0; } 2. To compile the project, press F7 key or select Build Solution from the Build menu. Atmel Studio now builds the application. All output from the compiler is listed in the output window. This concludes the introduction to creating code projects in Atmel Studio. All aspects of projects are described in detail in Project Management. The next section will describe how to debug this application using the built-in simulator. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 21 3. Project Management 3.1. Introduction Atmel Studio is an Integrated Development Environment (IDE) for writing and debugging applications for AVR/ARM platforms. Currently as a code writing environment, it supports the included AVR Assembler and any external AVRGCC/ARMGCC compiler in a complete IDE environment. Using Atmel Studio as an IDE gives you several advantages: 1. Editing and debugging in the same application window allows for a faster error tracking. 2. Breakpoints are saved and restored between sessions, even if the code was edited in the meantime. 3. Project item management is made convenient and portable. 3.1.1. The Solution Container With AVR Studio 5, the concept of "solution" is introduced. The solution is a container that may contain several projects. A project cannot exist outside a solution. If you try to open a project file ( .cproj or .asmproj extension) a solution will be created for you. This allow you to keep for example a bootloader project, and several application projects in the same solution. In practice the Solution is stored as an .atsln file. In general, projects that are added to the solution are placed in a separate folder inside the folder that the .atsln file recides in. 3.1.2. Save and Open Projects All projects are saved under a chosen name with the .cproj extension for GCC projects and .asmproj extension for 8-bit assembler projects. The user can reopen a project, either from the file menu, from the recently used projects list, or from the Project menu, under Open project. 3.1.3. Project Output View After building, assembling, or compiling the project, the operation result will be shown in the build output window. If any errors occur, the user can double-click on the message, which will position the marker over the corresponding line in the source window. 3.1.4. Solution Explorer Solution Explorer allows you to view items and perform item management tasks in a solution or a project. It also allows you to use the Atmel Studio editors to work on files outside the context of a solution or project. By default it appears on the right side of the Atmel Studio GUI. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 22 Figure 3-1. The Solution Explorer Pane 3.1.5. Toolbar Icons Buttons specific to the item selected in the tree view appear on the Solution Explorer. • Displays the appropriate property user interface for the selected item in the tree view. • Shows all project items, including those that have been excluded in the project and those that are hidden. 3.1.6. Hierarchical Display A single solution and all its projects appear in a hierarchical display. This allows you to work on several projects at the same time and at the same time keep track of all projects and items. Most source control system extensions (such as AnkhSVN) will also add icon overlays to the item icons, to signal the up-todate status of the project items that are under revision control. 3.1.7. Item Management Commands Solution Explorer supports a variety of management commands for each project or solution item. Right click on any item to get a menu with the available commands for that particular item. 3.1.8. Project Components A project will contain a set of device specific components. This includes startup code, linker scripts, and other support libraries. Components are small pieces of code or other supporting files that are included in any project. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 23 Figure 3-2. Project Components Components that are included in a project are listed in the Component drop-down. Selecting a component from the drop-down menu shows the component version, the files that the component is contributing with, and the dependencies that the component has. The version of the component can be changed by clicking the Change version button. 3.1.8.1. Change Version Components are versioned when added to the project. To change the version that is used, use this dialog. There are two options when choosing the version of a component Use a specific version Lock the project to a specific version of the component. Use the latest version Choose the most recent version of the component that is available. Figure 3-3. Change Version Components are part of the device packs in Atmel Studio. These device packs are managed using the Device Pack Manager. Related Links Device Pack Manager on page 146 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 24 3.2. GCC Projects 3.2.1. New Project Wizard Select File → New from the menu, and the dialog below will appear. The startup wizard will also have an option to start a new project. Figure 3-4. New Project Project types Currently several project types are available in the Project Type box. AVR board examples - to guide you through the usage of the AVR boards, User board project - if you have created your own product with the AVR tools, and a general AVR GCC project - a board independent project with a GNU compiler. It is also possible to create an AVR Assembler project and a general AVR Solution, which may include any supported source code type. Tip:  Projects can also be created by loading supported object files. If you want to create such a project, you should use the File → Open file menu. Project name and initial file Input the project name. The project main file, which is generated automatically, will be named with the same name by default (ASM or C). If you wish, you can change this name. It is possible to check a box to create a new folder, bearing the project name. This box is unchecked by default. You can choose to create a new solution in the Solution drop-down menu, or to reuse existing code. Input the solution name in the Solution Name field. If you are satisfied with the project name and type, press OK and proceed to the debugging platform selection stage. You can also leave the platform undefined for now, but then the you will have to select the debug platform and device upon starting a debug session. See also Assembler Projects, Object File Formats 3.2.2. Starting a New GCC Project for AVR Device 1. Create a new project by selecting New Project from the Project menu. This will open the Project Wizard. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 25 2. Select C/C++→GCC C Executable Project as a template, then specify a project name, select a location, and write a solution name for the project. A file with the same name as the project will be created and added to the project by default. It will contain an empty main() function. If you want to change the name of the initial file, just edit the main file name afterward. Press OK when you are satisfied with the settings. 3. Select C/C++→GCC C Static Library Project as a template, then specify a project name, select a location, and write a solution name for the project. This creates a Static Library (LIB) project, which is a good way to reuse code. Tip:  See section Starting a New GCC Static Library Project to learn more about Static Library projects. 4. A device selection table will appear. Choose the appropriate target platform for your project. To start you can select the ATxmega128A1 device. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 26 Figure 3-5. Device Selection 5. The project tree will be set up. Notice that the initial file created in step 2 has been added to the project node. Also, the initial file will be opened in the editor. 6. In order to facilitate applications development and verification you can also use the Driver Selection Wizard, invoked from Project → ASF Wizard... Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 27 In the ASF Wizard you can select which Drivers, Components, and Services you would like to use in the project for current build architecture and board. 7. Now, write the following code into the open editor window. #define MAXINT 200000 int main(void) { unsigned int t=1000, k=0, l=5, pn=2; unsigned int primes[t]; primes[0]=2; primes[1]=3; while (pn < t || primes[pn] < MAXINT) { for ( k = 0; k <= pn; k++) { if (l % primes[k] == 0) { goto otog; } else { if (k == pn) primes[pn++]=l; } } otog: l += 2; } return 0; } 8. Build the project. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 28 Figure 3-6. View of a GCC Project after Build Completed Dependencies All the included files are listed here. Double click on any file to open it in the editor. Output Files All output files will be displayed below this item. Libraries All Static Library files, Toolchain Library, and other Library Files will be displayed below this item. Tip:  See section Library Options to know more about Library options. 3.2.3. Libraries Options All Static Library files, Toolchain Library, and other Library Files will be displayed below this item. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 29 Figure 3-7. Libraries 3.2.3.1. Toolchain Libraries The toolchain libraries would be listed here. The Library search path provided by the toolchain would be enumerated to form the library list. 3.2.3.2. Project Libraries The projects available at the current Solution would be enumerated and the static libraries would be listed here. 3.2.3.3. Browse Libraries You can browse for other libraries. 3.2.3.4. How to Add Project Library Tip:  Ensure you have static library projects in the current solution. Right click on Project or Libraries Node in the project to invoke "Add Library" Wizard. Select Project Libraries Tab; here would see the all the static libraries in current solution listed. Select the Static Library which you would like to add. Click OK. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 30 Figure 3-8. View of a Project after Adding Libraries Also you will see that at Project → Project Dependencies Static Library added. Figure 3-9. View of a Project Dependencies after Adding Libraries 3.2.3.5. How to Add Toolchain Library Right click on Project or Libraries Node in the project to invoke "Add Library" Wizard. Select Toolchain Libraries Tab; here you will see the available toolchain libraries for the currently selected toolchain for project. Select the libraries which you like to add. Click OK. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 31 Figure 3-10. View of a Project after Adding Libraries You will also be able to see the new library added in the Toolchain Linker Settings. Figure 3-11. View of a Linker Option after Adding Libraries Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 32 3.2.4. Starting a New GCC Project for SAM (ARM) Device 1. Create a new project by selecting New Project from the Project menu. This will open the Project Wizard. 2. Select C/C++ → GCC C Executable Project as a template, then specify a project name, select a location, and write a solution name for the project. Some start-up files will be added to the project by default, which will contain some device specific functions and libraries. Press OK when you are satisfied with the settings. 3. Select C/C++ → GCC C Static Library Project as a template, then specify a project name, select a location, and write a solution name for the project. This creates a Static Library (LIB) project, which is a good way to reuse code. Tip:  See section Static Library Project to learn more about Static Library projects. 4. A device selection table will appear. Choose the device family as SAM3 or SAM4 and select the target platform for your project. To start you can select the ATSAM3S1A device. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 33 5. The project tree will be set up. Notice that the initial files created in step 2 has been added to the project node. Also, the file containing main() function will be opened in the editor. Here is a list of files that will be created: – A file with the same name as the project will be created and added to the project by default. It will contain the main() function. – A startup file(startup_*.c) will be available at "cmsis\src" directory. It contains the default interrupt handlers for all the peripherals. – A system file(system_*.c) available at "cmsis\src" provides the system level initialization functions that are called on start-up – Linker scripts with appropriate sections based on the device will be created at "cmsis \LinkerScripts" directory in the project folder – In case if you have deleted any files in cmsis folder and want to revert it back or if you have changed the device, just right click the Project and click "CMSIS Update from Atmel" to get the appropriate files. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 34 Note:  It is recommended not to change the contents of the startup_*.c and system_*.c files unless you have no other choice. These startup, system, and linker scripts will not be created for ARM static library projects. 6. In order to facilitate applications development and verification you can also use the Driver Selection Wizard, invoked from Project → ASF Wizard. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 35 In the ASF Wizard you can select which Drivers, Components, and Services you would like to use in the project for current build architecture and board. 7. Now, write the following code into the open editor window: #define MAXINT 200000 int main(void) { unsigned int t=1000, k=0, l=5, pn=2; unsigned int primes[t]; primes[0]=2; primes[1]=3; while (pn < t || primes[pn] < MAXINT) { for ( k = 0; k <= pn; k++) { if (l % primes[k] == 0) { goto otog; } else { if (k == pn) primes[pn++]=l; } } otog: l += 2; } return 0; } 8. Build the project. 3.2.5. Code Editing For the following part of the introduction we will reuse the same code as you have previously seen. #define MAXINT 200000 int main(void) { unsigned int t=1000, k=0, l=5, pn=2; unsigned int primes[t]; primes[0]=2; primes[1]=3; while (pn < t || primes[pn] < MAXINT) { for ( k = 0; k <= pn; k++) { if (l % primes[k] == 0) { goto otog; } else { if (k == pn) primes[pn++]=l; } } otog: l += 2; } return 0; } Atmel Studio has a rich editor that is made even richer by Atmel and third-party plugins. Atmel Studio has an automatic code generation faculty for snippets of C source code. To use it select and right click the part of the code you wish to enclose in a conditional structure (like for,while,if … etc). Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 36 Using the code snippets you can add parts to your core source. In some snippets the variable names and exit conditions are parametric within the IDE, so as if only one instance is changed all instances within the snippet will also change, such is the case of for loop. Table 3-1. Using "Surround With" ⇒ ⇒ 3.2.6. Starting a New GCC Static Library Project 3.2.6.1. Why Static Libraries Static Libraries (LIB) is a good way to reuse code. Rather than re-creating the same routines/functions in all the programs, the user can write them once and reference from the applications that need the functionality. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 37 3.2.6.2. Create New Static Library Project Figure 3-12. New Static Library Project Click OK to create the Static Library project. A default source file with the same name as the project will be added to the solution. You may then write and compile your routines/functions. You can also add new source files or header files into the project. Open the Project Properties on the menu Project → "Your_project_name Properties". This menu item is only available when a Static Library project is open. Select the Build property page. Here you will see that the Artifact Type is selected as Static Library. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 38 Figure 3-13. Static Library Build Properties Compile the project by selecting Build Solution from the Build menu. This creates a Static Library, which can be used by other programs. 3.2.6.3. Static Library Project Options (AVR/GNU Archiver) The AVR/GNU archiver, avr-ar, combines a collection of object files into a single archive file, also known as a library. Open the Project Properties on the menu Project → "Your_project_name Properties". This menu item is only available when a Static Library project is open. In order to configure Static Library options, click on the Toolchain property tab. In the Toolchain property page, you will see AVR/GNU Archiver active and enabled. You may also see that the AVR/GNU Linker is disabled for a static library project. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 39 Figure 3-14. AVR/GNU Archiver Setup Dialog, Command Line Shown You can set the AVR/GNU Archiver flags at the Archiver Flags textbox in the above General options. Now, save the project and compile by selecting Build Solution from the Build menu. 3.2.7. GCC Project Options and Configuration Project options and configuration can be set up by either right clicking on the Solution Explorer → Project Properties, or by pressing Alt Enter . This will call up the Project properties window, it has seven tabs: If a tab supports properties that are configuration specific, then the tab has two slide-down menus: The Configuration field defines the project configurations to modify. By default, two configurations are provided in each project - Debug and Release. The Platform field is set to AVR. If a tab supports configuration independent properties, then the Configuration and Platform fields are disabled. Note:  Use the "Save All ( Ctrl Shift S )" from the File menu or toolbar to update the changes in the project file whenever changes are made. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 40 3.2.7.1. Build Options Figure 3-15. Build Configuration In the Build tab page, you can configure whether you want to use an external Makefile for your project. In that case, just tick the Use External Makefile check box and browse to select the correct path of make file. Build Commandline will be provided to the external makefile when build is invoked for the project. The default build target is "all". Clean Commandline will be provided to the external makefile when clean is invoked for the project. The default clean target is "clean". Besides the external make file configuration, you can also specify the type of application to build. The options are Executable or Static Library, which can be selected using the Artifact Type combo box. Note:  Custom makefile must fulfill those conditions: 1. Target name must equal project name. 2. Makefile and target must exist in the same folder (can be referenced with NTFS links too). Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 41 3.2.7.2. Build Events Figure 3-16. Build Events Options The Build events tab contains a list of scheduled events for each configuration, launched by the prebuild and post-build scripts. These events can be added, deleted, or modified by clicking either the Edit pre-build... or Edit post-build... buttons. Upon clicking these buttons, you should manually add your commands in the following dialog. As of the current release it is possible to use environment variables and values declared within them as a link with other available applications. In order to use that function press the Show Macros button. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 42 Figure 3-17. Build Event Editor Macros Expands the edit box to display the list of macros/environment variables to insert in the command line edit box. Macro Table List the available macros/environment variables and its value. You can select only one macro at a time to insert into the command line edit box. MSBuild also provides a set of reserved properties that store information about the project file and the MSBuild binaries. These properties may also be listed in the edit box. See Macros/environment variables below for a description which are specific to Atmel Studio. Table 3-2. Atmel Studio Build Macro Table Macro Description $(AVRSTUDIO_EXE_PATH) The installation directory of Atmel Studio (defined with drive and path) $(SolutionDir) The directory of the solution (defined with drive and path) $(SolutionPath) The absolute path name of the solution (defined with drive, path, base name, and file extension) $(SolutionFileName) The file name of the solution $(SolutionName) The base name of the solution $(SolutionExt) The file extension of the solution. It includes the '.' before the file extension. $(Configuration) The name of the current project configuration, for example, "Debug" $(Platform) The name of the currently targeted platform, for example, "AVR" $(DevEnvDir) The installation directory of Atmel Studio (defined with drive and path) $(ProjectVersion) The version of the project Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 43 Macro Description $(ProjectGuid) A unique identifier of the project $(avrdevice) The name of the currently selected device $(avrdeviceseries) The series of the selected device. Used internally by the Atmel Studio. $(OutputType) Defines if the current project is an Executable or a Static Library type $(Language) Language of the current project; for example, C, CPP, or Assembler $(OutputFileName) The file name of the primary output file for the build (defined as base file name) $(OutputFileExtension) The file extension of the primary output file for the build. It includes the '.' before the file extension $(OutputDirectory) The absolute path of the output file directory $(AssemblyName) The assembly name of the primary output for the build $(Name) The base name of the project $(RootNamespace) The base name of the project $(ToolchainName) The name of the toolchain $(ToolchainFlavour) The name of the toolchain's compiler Macro Description Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 44 3.2.7.3. Compiler and Toolchain Options Figure 3-18. Compiler and Toolchain Options AVR GNU C Compiler Options Table 3-3. AVR GNU C compiler Options Option Description General options -mcall-prologues Use subroutines for functions prologues and epilogues -mno-interrupts Change stack pointer without disabling interrupts -funsigned-char Default char type is unsigned -funsigned-bitfield Default bit field is unsigned Preprocessor options -nostdinc Do not search system directories -F Preprocess only Symbols options Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 45 Option Description There one can define (-D) or undefine (-U) a number of in-source symbols. New symbol declarations can be added, modified, or reordered, using the interface buttons below: • Add a new symbol. This and all following icons are reused with the same meaning in other parts of Atmel Studio interface. • Remove a symbol. • Edit symbol. • Move the symbol up in the parsing order. • Move the symbol down in the parsing order. Include directories Contains all the included header and definition directories, can be modified, using the same interface as symbols. Optimization options Optimization level (drop down menu): -O0, - O1, -O2, -O3, -Os No optimization, optimize for speed (level 1 - 3), optimize for size Other optimization flags (manual input form) Here you should write optimization flags specific for the platform and your requirements -ffunction-sections Prepare functions for garbage collection, if a function is never used, its memory will be scrapped -fpack-struct Pack structure members together -fshort-enums Allocate only as many bytes needed by the enumerated types -mshort-calls Use rjmp/rcall limited range instructions on the >8K devices Debug options Debug level (drop down menu): none, -g1, - g2, -g3 Specifies the level of tracing and debugging code and headers left or inserted in the source code Other debug options (form field) Architecture specific debug options Warning messages output options -Wall All warnings -Werror Escalate warnings to errors -fsyntax-only Check syntax only Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 46 Option Description -pedantic Check conformity to GNU, raise warnings on nonstandard programming practice -pedantic-errors Same as above, plus escalate warnings to errors Miscellaneous options Other flags (form field) Input other project-specific flags -v Verbose -ansi Support ANSI programs -save-temps Do not delete temporary files Option Description AVR GCC Linker Options Table 3-4. AVR GCC Linker Options Option Description -Wl -nostartfiles Do not use standard files -Wl -nodefault Do not use default libraries -Wl -nostdlib No start-up or default libraries -Wl -s Omit all symbol information -Wl -static Link statically Libraries options Libraries -Wl, -l (form field) You can add, prioritize, or edit library names here, using these buttons: , , , , Library search path -Wl,-L (form field) You can add, prioritize or edit path where the linker will search for dynamically linked libraries, same interface as above Optimization options -Wl, -gc-sections Garbage collect unused sections --rodata-writable Put read-only data in writable spaces -mrelax Relax branches Miscellaneous options Other linker flags (form field) Input other project-specific flags Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 47 AVR Assembler Options Table 3-5. AVR Assembler Options Option Description Optimization options Assembler flags (form field) Miscellaneous assembler flags Include path (form field) You can add, prioritize or edit path to the architecture and platform specific included files here -v Announce version in the assembler output Debugging options Debugging level (drop down menu) -Wa -g1, - Wa, -g2, -Wa, -g3 Defines a level of debugging symbol and debugging source insertion 3.2.7.4. Device Options This tab allows you to select and change the device for the current project and is similar to the device selector, see Figure 3-5. Tip:  Click on the Device button on the Device and Debugger toolbar to get to this tab quickly while editing. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 48 3.2.7.5. Tool Options This tab allows you to select and change the debugger platform for the current project. Tip:  Click on the Device button on the Device and Debugger toolbar to get to this tab quickly while editing. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 49 Select tool/debugger from the drop-down list. Current selection is shown. Select Interface from the drop-down list. Current selection is shown. Note:  Only tools and interfaces valid for the current device selection are shown. Further Properties are dependent on tool and interface selected. JTAG If you have selected JTAG as the programming interface, clock speed, use external reset - and daisy chain setting may be available. This depends on the tool and device. JTAG clock JTAG clock is the maximum speed the tool will try to clock the device at. The clock range is different for different tools and devices. If there are restrictions, they will be stated in a message below the clock slider. Clock can be set to Manual (all tools), Auto (SAM-ICE only), or Adaptive (SAM-ICE only). Use external reset If checked, the tool will pull the external reset line low when trying to connect to the device. JTAG daisy chain settings Specify the JTAG daisy chain settings relevant to the device to program. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 50 Target is not part of a daisy chain. Select this option when the target device is not part of a daisy chain. Daisy chain - Manual. Allows you to manually configure the JTAG daisy chain in case you are programming in a system-on-board. • Devices before - specifies the number of devices preceding the target device. • Instruction bits before - specifies the total size of the instruction registers of all devices, preceding the target device. • Devices after - specifies the number of devices following the target device. • Instruction bits after - specifies the total size of the instruction registers of all devices, following the target device. Daisy chain-Auto. Automatically detects the devices in the JTAG daisy chain. Allows you to select the device in the JTAG daisy chain. Auto-detection is supported only for SAM devices. PDI The PDI interface has only one setting – the PDI clock speed. PDI Clock is the maximum speed the tool will try to clock the device at. The clock range is different for different tools and devices. If there are restrictions, they will be stated in a message below the clock slider. The clock can not be adjusted on all tools, so an empty Interface settings page will be presented. Programming and debug settings In the drop-down menu it is possible to specify which parts of memory that should be erased during a programming/debug cycle. • Skip programming - specifies that no programming should occur. The tool will try to attach to the program already in memory. • Erase only program area - specifies that only the program area of memory should be erased. • Erase entire chip - specifies that the entire chip is to be erased. The "Preserve Eeprom" option lets you decide whether EEPROM data should be written when launching a debug session. When this checkbox is checked, EEPROM data in the object file will be written to the device at the start of each debug session. The EESAVE fuse will be set and cleared accordingly. When a device is programmed at the start of a debug session, the default behavior is to erase the content of the device (chip erase, if available). This can be changed by selecting a different option from the drop down box under "Programming settings". Keep timers running in stop mode Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 51 When checked, the timers set in the program will continue to run even when the program breaks at breakpoint or is halted This setting is only enabled for certain tool/interfaces. Override Vector Table Offset Register At reset, load PC and SP from the specified address. Note:  The tool you select on this page is also used with the command Start without Debugging. That is why you also can select tools that do not have debugging capabilities. See Start without Debugging for more information. 3.2.7.6. Advanced Options Setting ToolchainFlavour This section allows you to set the flavour of the toolchain for the current project. Default flavour of the respective toolchain is selected. The toolchain path configured in the flavour is used for building the projects. For configuring and adding new flavours Toolchain. Use GDB This section allows you to select whether GDB has to be used for the current project. The Current GDB Path will be computed by the following 1. The Current GDB Path is taken from 'Tools → Options → Debugger → GDB Settings if configured GDB Settings. 2. Otherwise it is taken from selected Toolchain Flavor if GDB is found there. The Current GDB Path will be overridden when we use the option "Override Current GDB Path" in the "Advanced" project property page. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 52 Note:  The option "Use GDB" is enabled by default for ARM based devices and also the following warning will be shown for AVR 32-bit devices if GDB is enabled. 3.2.7.7. Creating ELF Files with Other Memory Types ELF files that contains data for all memory types can be made with the GCC compiler. The data sections are specified in code as shown in following code examples. Creating ELF Files for tinyAVR, megaAVR, and XMEGA devices This code shows how to add memory sections for tinyAVR, megaAVR, and XMEGA devices (except ATtiny4/5/9/10) . This example is for an ATxmega128A1 device. For other devices, it has to be modified accordingly. #include // Example data for ATxmega128A1 const char eeprdata[] __attribute__ ((section (".eeprom"))) = "Hello EEPROM"; // The order of the fuse values is from low to high. 0xA2 is written to Fuse byte 0, 0x00 to byte 1... const uint8_t fusedata[] __attribute__ ((section (".fuse"))) = {0xA2, 0x00, 0xFF, 0xFF, 0xFF, 0xF5}; Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 53 const uint8_t lockbits[] __attribute__ ((section (".lockbits"))) = {0xFC}; const char userdata[] __attribute__ ((section (".user_signatures"))) = "Hello User Signatures"; // Remember to set the following Toolchain project options, // under AVR/GNU -> Miscellaneous: // // -Wl,--section-start,.user_signatures=0x00850000 int main(void) { while(1) { // TODO:: Please write your application code } } Linker setup for User Signature section The User Signatures section must have a specific Linker Setup, as shown below. This is necessary to get the correct address offset for the user signature section in the elf file. Other memory sections gets the correct address automatically. Figure 3-19. Linker Setup for User Signature Section Creating ELF Files for ATtiny4/5/9/10 This code shows how to add memory sections for ATtiny10. #include typedef struct _tagConfig { unsigned char f1; } Config; typedef struct _tagLock { unsigned char f1; } Lock; Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 54 typedef struct _tagSig { unsigned char f1; unsigned char f2; unsigned char f3; } Signature; Config __config __attribute__((section(".config"))) = { f1 : 0xfb, // Set CKOUT }; Lock __lock __attribute__((section(".lock"))) = { f1 : 0xfc, // Further programming and verification disabled }; Signature __sig __attribute__((section(".signature"))) = { f1 : 0x03, f2 : 0x90, f3 : 0x1e, }; int main(void) { while(1) { // TODO:: Write your application code } } Creating ELF Files for UC3 The example below shows how to add data for the user page in UC3 devices. #include const char userdata[] __attribute__((section(".userpage"))) = "Hello Page"; int main(void) { while(1) { //TODO:: Write your application code } } Project Properties If the memory sections are defined but not referenced in the application code, the "Garbage collect unused sections" option in Project Properties → Linker → Optimization must be unchecked. Otherwise the linker will not include the sections in the .elf file. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 55 Figure 3-20. Project Properties Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 56 3.3. Assembler Projects 3.3.1. Create New Assembler Project Figure 3-21. New Assembler Project After pressing OK, you are asked to select your microcontroller. You can try out the Assembler build and code debugging, using a simple LED-chaser code, given below. It should fit any AVR 8-bit microcontroller, simply change the port (in this case E) to your hardware. start: nop ldi R16, 0xff sts PORTE_DIR, r16 ldi r17, 0x80 output: sts PORTE_OUT, r17 rol r17 ldi r16, 0x00 delay: ldi r18, 0x00 delay1: inc r18 brne delay1 inc r16 brne delay break rjmp output Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 57 When a new project is created or an old project is loaded, the project view will be displayed with all the project files. Files can be added, created, or removed from the project list using the context menu in the Solution explorer window. Figure 3-22. View of an Assembler Project All the source files will be listed at the end of the list. Double click on any file to open it in the editor. All custom include files will be listed directly under the project name item, unless you create a new folder in the project. Figure 3-23. View of an Assembler Project after Build Completed Dependencies: All include files are listed here. Double click on any file to open it in the editor. Labels: All labels in your assembler program are listed here. Double click on any item to show its location in the source. A marker will point to the correct line. Output Files: All output files will be displayed below this item. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 58 Figure 3-24. File Context Menu Table 3-6. File Context Menu Menu text Shortcut Description Open Right click O Open the selected file Open With... Right click n Open selected file with another editor or tool Cut Ctrl X Cut the file from current category Copy Ctrl C Copy the file from current category Remove DEL Remove the selected file from the project Rename F2 Rename the selected file Set As EntryFile Set the selected file as entry file Properties Alt ENTER Current file properties Menu text Shortcut Description All the interface views are docked by default. You can switch between docked and undocked views by dragging windows around to a desirable location, or by dragging and dropping a window on a quick docking menu of the Visual Studio IDE. The quick docking menu will appear every time you start dragging an interface view or window. 3.3.1.1. Project Context Menu Several build commands are available from the menu and the toolbars. There is also a context menu for the project: Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 59 Figure 3-25. Project Context Menu Table 3-7. Project Context Menu Menu text Shortcut Description Build Right click+u Build the selected project Rebuild Right click e Will clean the project and build it Clean Right click n Clean up and erase artifacts Add Ctrl Shift A / Shift Alt A (existing item) Add new files or existing files to the project Set as StartUp Project Right click + a Will set up to automatically open current project at start up Cut Ctrl X Cut project to paste it as a sub-project to another solution Remove Del Remove project or sub-project under cursor Rename F2 Rename current project Unload Project Right click l Unload active project files from the IDE Properties Alt Enter Project properties 3.3.2. Assembler Options Open the options window on the menu Project → "Your_project_name Properties". This menu item is only available when an assembler project is open. After opening the Project properties window, you will see six tabs, in order to configure assembler options click on the Toolchain. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 60 Figure 3-26. Assembler Setup Dialog, Command Line Shown Figure 3-27. Assembler Setup Dialog, General Options Shown 3.3.2.1. Description of the Various Settings Configuration menu allows to choose which stages of project maturity are going to be affected by the modifications to the project properties. By default Debug is the initial stage and initially active configuration. Following options are available: 1. Debug. 2. Release. 3. All configurations. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 61 Platform menu shows compatible target platforms available for prototyping. Hex Output format The following file formats can be selected as additional output format: 1. Intel Hex. 2. Generic Hex. 3. Motorola Hex (S-record). Wrap relative jumps The AVR RJMP/RCALL instructions allow a 12-bit PC-relative offset, corresponding to ±2k words. For devices having 4k words (8kB) or less FLASH program memory, the Wrap option causes the assembler's offset calculation to wrap around over the addressable program memory range, enabling the entire program memory to be addressed using these instructions. For devices with more than 4k words of program memory, using this option may cause unpredictable results and it should be turned OFF. If it is left ON, the assembler will produce a warning when wrap takes effect: Attention:  Wrap rjmp/rcall illegal for device > 4k words - Turn off wrap option and use jmp/call. This diagnostic is given as a warning and not an error to retain compatibility with earlier versions of the assembler, but should be treated as an error by the user. The JMP/CALL 2-word instructions take 22-bit absolute addresses and should be used instead. Unsupported Instructions. By default, this option is set to give a warning when the assembler finds unsupported instructions for the actual device. Optionally, you can output an error. Include Paths (-I). Additional include paths can be set here, when using third party modules or your own IP. Assembler's default include path:\Atmel\AVR Tools\AvrAssembler2\Appnotes. Other optimization flags can be set to tailor optimization to your specific needs, see Assembler help for more information. 3.4. Import of Projects 3.4.1. Introduction Atmel Studio allow import of projects from several pre-existing project sources. This section details how to import existing projects. 3.4.2. Import AVR Studio 4 Project Click the menu File → Import → AVR Studio 4 Project.. or Ctrl+4. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 62 An Import AVR Studio 4 Project dialog will appear. Type the name of your project or browse to the project location by clicking the Browse button of the APS File location Tab. Atmel Studio will proceed with conversion also updates the progress, warnings, and errors. They will be shown in the Summary window. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 63 Check Show conversion log after this page is closed to view the complete conversion log. Click Finish to access your newly converted project. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 64 Note:  Currently, conversion only adds a project file and solution file if the Solution Folder is the same as the APS File Location. No other files will be modified. 3.4.3. Import AVR 32 Studio Project Click the menu File → Import → AVR Studio 32 Project.. or Ctrl+3. An "Import AVR Studio 32 Project" dialog will appear. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 65 Type the name of your workspace or browse to the workspace location by clicking the ... (Browse button) of the Workspace Tab. Click Find Projects to find all the project files and populate other folders available in the workspace. The Available AVR32 C/C++ Projects tab will be populated with all AVR32 C/C++ Projects that can be imported and it will also display total number of available projects. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 66 The Invalid AVR32 Projects tab will be populated with all Unsupported AVR32 Projects that can not be imported and it will also display total number of non convertible projects along with reason. Atmel Studio will proceed with conversion also updates the progress, warnings, and errors. They will be shown in the Summary window. Check "Show conversion log after this page is closed" to view the complete conversion log. Click Finish to access your newly converted project. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 67 Note:  • The current version of AVR32 Importer supports AVR32 C/C++ Projects • AP7 device family is currently not supported by Atmel Studio • Currently, conversion only adds project files and solution file if the Solution Folder is the same as the Workspace folder. No other files will be modified. • Pre/Post builds settings are not imported • Automatically generate listing (*.lss) files setting is not imported Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 68 3.4.4. Import Project Template A number of predefined project can be imported to Atmel Studio by File → Import → Project Template..or Ctrl+T These templates provide a starting point to begin creating new projects or expanding current projects. Project templates provide the basic files needed for a particular project type, include standard assembly references, and set default project properties and compiler options. In the " Import Project Template " window specify the following: • Specify the location of your project template • Specify the save location. The combo box will show installed templates that are available in the New Project → Installed Templates. Select any template under which you would like to add your template. You can also add your template at the root by selecting in "Add to folder". Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 69 • You can create a separate folder by specifying the name of the folder under the specified "Add to Folder (Optional)", where you want to add your project template. The resulting project template will be added to the existing installed templates and can be accessed from File → New → Project .. or Ctrl+Shift+N. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 70 Note:  "Import Project Template Importer" will work with template created for the same version. 3.5. Debug Object File in Atmel Studio 3.5.1. Introduction Debug session requires you to load an object file which is supported by Atmel Studio. The debug file contains symbolic information for debugging. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 71 3.5.2. Atmel Studio Supported Debug Formats Table 3-8. Object File Formats Supported by Atmel Studio Object file format Extension Description UBROF .d90 UBROF is an IAR proprietary format. The debug output file contains a complete set of debug information and symbols to support all type of watches. UBROF8 and earlier versions are supported. This is the default output format of IAR EW 2.29 and earlier versions. See below how to force IAR EW 3.10 and later versions to generate UBROF8. ELF/DWARF .elf ELF/DWARF debug information is an open standard. The debug format supports a complete set of debug information and symbols to support all type of watches. The version of the format read by Atmel Studio is DWARF2. AVR-GCC versions configured for DWARF2 output can generate this format. AVRCOFF .cof COFF is an open standard intended for 3rd party vendors creating extensions or tools supported by the Atmel Studio. AVR Assembler format .obj The AVR assembler output file format contains source file info for source stepping. It is an Atmel internal format only. The .map file are automatically parsed to get some watch information. Before debugging, make sure you have set up your compiler/assembler to generate a debug file like one of the formats above. 3rd party compiler vendors should output the ELF/DWARF object file format. 3.5.3. Opening Object Debug File in Atmel Studio Steps to create an Object Project • On the File menu, click Open, and then click Open Object File For Debugging. Open Object File For Debugging wizard will appear. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 72 • – In the Select the object file to debug, select your object file to debug. The object file must be supported by Atmel Studio. – In the Project Name, type a name for the project. Atmel Studio will suggest a name, which you can override if wanted. – In the Location, select a save location. Atmel Studio will suggest a name, which you can override if wanted. – Maintain Folder Hierarchy for Source Files option is selected by default which would create a similar folder structure in the Solution Explorer as that of the source project i.e. the project used to create the object file. Otherwise, all the files are added to the root folder of the project file i.e. the user would not see any folder in the Solution explorer. – Add File As Link option is selected by default in which the object project shall refer the files from its original location without a local copy into the project directory. If the option is not selected, Atmel Studio would copy the files into the object project directory. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 73 • Click Next. The Device Selection dialog will appear. – Choose the appropriate target device. The target device should be the same, which was originally chosen to create the object file. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 74 • Click Finish. The object project files re-mapper appears. In this particular dialog you need to remap your original files of the project using, which the elf projects was created. If files are present at their original place, it will show remapped already in dialog. If files are missing, you will have to remap it manually. Check the screen shot below. If the user resolves the parent folder for any original file, all other files in subsequent directory will be remapped recursively. So, it is useful for the user to remap the number of files by just remapping only one. • Now the Object Project is Created. The files that are not remapped properly are shown in solution explorer like "libgcc.S", with warning sign . Press F5 to debug this Project. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 75 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 76 4. Debugging 4.1. Introduction Atmel Studio can be targeted towards the built-in Simulator, or a variety of tools (see Available Tools View), for example AVR ONE!, JTAGICE mkII or JTAGICE3 (bought separately). 4.1.1. Debug Platform Independent Debug Environment Independent of which debug platform is running, the Atmel Studio environment will appear identical. When switching between debug platforms, all environment options are kept for the new platform. Some platforms have unique features, and new functionality/windows will appear. 4.1.2. Differences Between Platforms Although all debug platforms appear identical in the debug environment there will be small differences between them. A real-time emulator will be significantly faster than the simulator for large projects. An emulator will also allow debugging while the system is connected to the actual hardware environment, while the simulator only allow predefined stimulus to be applied. In the simulator, all registers are always potentially available for display, which might not be the case with an emulator. 4.2. Starting a Debug Session To start a debug session and halt, press Alt+F5 or choose Debug → Start Debugging and Break from the menu, alternatively, press the toolbar button as illustrated below: Figure 4-1. Starting a Debug Session To start a debug session and keep executing, press F5 or press the toolbar button with the continue symbol, or choose Debug → Continue from the menu as illustrated below: Figure 4-2. Starting a Debug Session 4.3. Ending a Debug Session To end the debug session use the Stop Debugging button or keyboard shortcut Shift F5 . Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 77 4.4. Attaching to a Target To attach a target, use the Attach to Target option in the Debug menu, or the attach icon in the debug toolbar. This causes Atmel Studio to launch a debug session on the selected target without uploading a new application or causing a reset. Once the debug session is established, the core of the target is halted and the current execution position of the target is mapped to the code in the project. This means that the state of the target is kept and is inspect-able with normal debug techniques, and the program halts in the current position. Full run control and symbolic debugging should be available after a successful attach. Note:  • The code in the project is mapped to the content of the running target, without any possibility to verify the correctness of this mapping. This means that if the project contains code that is not on the target, then the state and run control might not reflect the truth, as variables and functions might have different code locations on the target than in the project. • The ability to activate a debug session without resetting a target is architecture dependent. Not all architectures supports this feature. Attention:  Physically connecting a debug probe to a target might cause the target to reset, as most debug probes needs an electrical connection to the reset line of the device. Normal electrical precautions needs to be taken to avoid this. 4.5. Start without Debugging 4.5.1. One Click Programming - Program and Run The Start without Debugging command is a one-click alternative to the programming dialog. Execute it by selecting Debug → Start without Debugging from the menu, or press the button on the toolbar. Figure 4-3. Start without Debugging This will build the solution (if any changes are made) and program the target device without starting a debug session. Start without Debugging uses the tool and interface settings specified in the project options. This is different from what takes place when using the stand-alone Programming Dialog, which is not related to the project at all. Note:  Programmers and starter kits can also be used with the Start without Debugging command, not only debuggers. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 78 The Start without Debugging command will also program the EEPROM, fuses, lockbits, and user signature (XMEGA only) segments if they are present in the object file. The GCC compiler can generate ELF object format files with such segments. See Creating ELF Files with Other Memory Types for more information. Note:  The user signature is not erased by Start without Debugging. The programmed user signature from the ELF file will be AND-ed with the content in the device. If you want to replace the signatures with what is in the file, you must perform a user signature erase manually. 4.5.2. Keyboard Shortcut By default, there is no keyboard shortcut to this function, but you might want to add one if you use it a lot. To add one, simply click the Tools → Options menu button and go to Environment → Keyboard. Start typing startwithouttdebugging in the Show commands containing input field, and select Debug.StartWithoutDebugging in the list. Then select the Press shortcut keys input field, and press the desired key combination. You can for example press Ctrl+F5. Note that this shortcut is already assigned to the BreakAll command. If you choose to override it, press the Assign button to assign the new keyboard shortcut. Or, you can select an unused key combination. Figure 4-4. Add Keyboard Shortcut 4.6. Debug Control Several commands are available for controlling the debugger. They are available from both the Debug menu and several toolbars. The Atmel Studio Integrated Development Environment (IDE) has two major operating modes; design mode and debug mode. Design mode is when you are editing the source code project, while debug mode is when you debug your project. The IDE adapts to modes, and menus an toolbars changes. Note:  Some debug commands are available in design mode, some in debug mode. • In design mode, the available debug commands are those that will start the debug session, e.g. Start Debugging and Break, Start Debugging, Start without Debugging. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 79 • In debug mode, you will find commands like Break All, Step Out, and Reset. Start Debugging and Break Starts the debugger, and breaks the execution on the first statement of the program. Start Debugging Starts the debugger, and runs the program. In debug mode and stopped, it resumes execution. Start Without Debugging Programs the project without starting debugging. For details, see Start without Debugging. Break All Halts the debugger. Stop Debugging Stops and terminates the debug session, and returns to design mode. Restart Restarts the debugger and reloads the program. Reset Resets the program to the first statement. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 80 Disable debugWire and Close Available when debugging a device using the debugWire interface. The command disables the debugWire interface (enabling the use of the ISP interface) and terminates the debug session. Step Into Executes one instruction. When in disassembly level, one assembly level instruction is executed, otherwise one source level instruction is executed. Step Over Similar to Step Into, Step Over executes one instruction. However, if the instruction contains a function call/subroutine call, the function/subroutine is executed as well. If a user breakpoint is encountered during Step Over, execution is halted. Step Out Continue execution until the current function has completed. If a user breakpoint is encountered during Step Over, execution is halted. If a Step Out command is issued when the program is on the top level, the program will continue executing until it reaches a breakpoint or it is stopped by the user. Quick Watch Adds a Quick Watch for the variable or expression under the cursor. For details, see QuickWatch and Watches. Toggle Breakpoint Toggle the breakpoint status for the instruction where the cursor is placed. Note that this function is only available when the source window or disassembly window is the active view. New Breakpoint Create a new breakpoint at the location of the cursor. For more information, see Breakpoints. Disable All Breakpoints This function clears all set program breakpoints, including breakpoints which have been disabled. Clear All DataTips Clear all marked Data Tips. For more information, see DataTips. Export Data Tips Save all marked Data Tips to a file in Visual Studio Shell format. Import DataTips Load Data Tips from a Visual Studio Shell file. Options and Settings Debug options and settings, see Debugger. 4.7. Breakpoints 4.7.1. General Information on Breakpoints A breakpoint tells the debugger to temporarily suspend execution of a program when a specific condition takes place, e.g. when a certain instruction is about to be executed. Breakpoints provide a powerful tool that enables you to suspend execution where and when you need to. Rather than stepping through your code line by line or instruction by instruction, you can allow your program to run until it hits a breakpoint, and then start to debug. This speeds up the debugging process. 4.7.1.1. Breakpoint Glyphs The source windows and the isassembly window show breakpoint locations by displaying symbols called glyphs in the left margin. The following table describes these glyphs. If you rest the mouse on a breakpoint glyph, a breakpoint tip appears with more information. This information is especially useful for error and warning breakpoints. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 81 Table 4-1. Breakpoint Glyphs Glyph Description Normal breakpoint. The solid glyph indicates that the breakpoint is enabled. The hollow glyph indicates that it is disabled. Advanced breakpoint. Active/disabled. The + sign indicates that the breakpoint has at least one advanced feature (such as condition, hit count, or filter) attached to it. Breakpoint error. The X indicates that the breakpoint could not be set because of an error condition. Breakpoint warning. The exclamation mark indicates that a breakpoint could not be set because of a temporary condition. Usually, this means that the code at the breakpoint or tracepoint location has not been loaded. It can also be seen if you attach to a process and the symbols for that process are not loaded. When the code or symbols are loaded, the breakpoint will be enabled and the glyph will change. 4.7.2. Operations with Breakpoints 4.7.2.1. To Set a Breakpoint 1. In a source window, click a line of executable code where you want to set a breakpoint. On the right-click menu, click Breakpoint, and then click Insert Breakpoint. —or— In a source window, click a line of executable code where you want to set a breakpoint. On the Debug menu, click Toggle Breakpoint. 4.7.2.2. To Set an Address Breakpoint 1. On the Debug menu, point to Windows, and then click Disassembly if the Disassembly window is not already visible. You need to be in a debug session for this option to be visible. 2. In the Disassembly window, click a line of code, and then click Toggle Breakpoint on the Debug menu. —or— Right-click a line of code, and then select Insert Breakpoint . 4.7.2.3. To Edit a Breakpoint Location 1. In the Breakpoints window, right-click a breakpoint, then click Location on the right-click menu. —or— In a source, Disassembly, or Call Stack window, right-click a line that contains a breakpoint glyph, and then click Location from Breakpoints on the right-click menu. Note:  In a source window, you might have to right-click the exact character where the breakpoint is set. This is necessary if the breakpoint is set on a specific character within a line of source code. 4.7.2.4. Hit Count Keeps Track of How Many Times a Breakpoint is Hit By default, execution breaks every time that a breakpoint is hit. You can choose to: Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 82 • Break always (the default) • Break when the hit count equals a specified value • Break when the hit count equals a multiple of a specified value • Break when the hit count is greater than or equal to a specified value If you want to keep track of the number of times a breakpoint is hit but never break execution, you can set the hit count to a very high value so that the breakpoint is never hit. The specified hit count is retained only for the debugging session. When the debugging session ends, the hit count is reset to zero. 4.7.2.5. To Specify a Hit Count 1. In the Breakpoints window, right-click a breakpoint, and then click Hit Count on the right-click menu. —or— In a source, Disassembly, or Call Stack window, right-click a line that contains a breakpoint, and then click Hit Count from the Breakpoints sub menu on the right-click menu. 2. In the Hit Count dialog box, select the behavior you want from the When the breakpoint is hit list. If you choose any setting other than Break always, a text box appears next to the list. Edit the integer that appears in the text box to set the hit count you want. 3. Click OK. 4.7.2.6. To Enable or Disable a Single Breakpoint In a source, Disassembly, or Call Stack window, right-click a line that contains a breakpoint glyph, point to Breakpoint, then click Enable Breakpoint or Disable Breakpoint. —or— In the Breakpoints window, select or clear the check box next to the breakpoint. To enable or disable all breakpoints From the Debug menu, click Enable All Breakpoints. 4.7.2.7. To Delete a Breakpoint In the Breakpoints window, right-click a breakpoint, and then click Delete on the right-click menu. —or— In a source window or a Disassembly window, click the breakpoint glyph. 4.7.2.8. To Delete all Breakpoints From the Debug menu, click Delete All Breakpoints . Confirmation Prompt When you delete all breakpoints, a prompt requesting confirmation of the action might appear, depending on options settings. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 83 4.7.3. Breakpoint Window Figure 4-5. Breakpoint Window You can open the Breakpoints window from the Debug menu. 4.7.3.1. To Open the Breakpoints Window On the Debug menu, point to Windows, and then click Breakpoints. 4.7.3.2. To Go to the Location of a Breakpoint In the Breakpoints window, double-click a breakpoint. —or— In the Breakpoints window, right-click a breakpoint and choose Go To Source Code or Go To Disassembly. —or— Click a breakpoint, and then click the Go To Source Code or Go To Disassembly tool. 4.7.3.3. To Display Additional Columns In the toolbar at the top of the Breakpoints window, click the Columns tool, and then select the name of the column you want to display. 4.7.3.4. To Export all Breakpoints that Match the Current Search Criteria In the Breakpoints window toolbar, click the Export all breakpoints matching current search criteria icon. 1. The Save As dialog box appears. 2. In the Save As dialog box, type a name in the File name box. 3. This is the name of the XML file that will contain the exported breakpoints. Note the folder path shown at the top of the dialog box. To save the XML file to a different location, change the folder path shown in that box, or click Browse Folders to browse for a new location. 4. Click Save. 4.7.3.5. To Export Selected Breakpoints 1. In the Breakpoints window, select the breakpoints you want to export. To select multiple breakpoints, hold down the Ctrl key and click additional breakpoints. 2. Right-click in the breakpoints list, and choose Export selected. 3. The Save As dialog box appears. 4. In the Save As dialog box, type a name in the File name box. This is the name of the XML file that will contain the exported breakpoints. The folder path is shown at the top of the dialog box. To save the XML file to a different location, change the folder path shown in that box, or click Browse Folders to browse for a new location. 5. Click Save. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 84 4.7.3.6. To Import Breakpoints 1. In the Breakpoints window toolbar, click the Import breakpoints from a file icon. 2. The Open dialog box appears. 3. In the Open dialog box, browse to the directory where your file is located, and then type the file name or select the file from the file list. 4. Click OK. 4.7.3.7. To View Breakpoints that Match a Specified String In the Search box, perform one of the following actions: 1. Type your search string in the Search box and press ENTER. —or— 2. Click the Search drop-down list and select a string from the list of previous search strings. To limit the search to a specified column, click the In Column drop-down list and then click the name of the column that you want to search in. 4.7.3.8. To View all Breakpoints after a Search In the Search box, select and delete the search string and then press ENTER. 4.7.3.9. Breakpoint Labels In Atmel Studio, you can use labels to help keep track of your breakpoints. A label is a name that you can attach to a breakpoint or a group of breakpoints. You can create a name for a label or you can choose from among a list of existing labels. You can attach multiple labels to each breakpoint. Labels are useful when you want to mark a group of breakpoints that are related in some way. After you have labeled the breakpoints, you can use the search function in the Breakpoints window to find all breakpoints that have a specified label. The search function searches all columns of information that are visible in the Breakpoints window. To make your labels easy to search for, avoid using label names that might conflict with strings that appear in another column. For example, if you have a source file that is named "Program.c", "Program.c" will appear in the name of any breakpoint set in that file. If you use "Prog" as a label name, all breakpoints set in Program.c will appear when you search for breakpoints labeled "Prog". 4.7.3.10. To Label Breakpoints 1. In the Breakpoints window, select one or more breakpoints. 2. To select multiple breakpoints, use the Ctrl key when selecting breakpoints. 3. Right-click the selected breakpoints, and then click Edit labels. 4. The Edit breakpoint labels dialog box appears. 5. Select one or more labels in the Choose among existing labels box. —or— Type a new label name in the Type a new label box, and then click Add. 4.7.3.11. To Search for Breakpoints that have a Specified Label 1. In the Breakpoints window toolbar, click the In Column box and select Labels from the drop-down list. 2. In the Search box, type the name of the label you want to search for and press Enter. 4.7.3.12. To Remove Labels from Breakpoints 1. In the Breakpoints window, select one or more breakpoints. Press Ctrl left-click to select multiple breakpoints. 2. Right-click the selected breakpoints, and then click Edit labels. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 85 3. The Edit breakpoint labels dialog box appears. 4. In the Choose among existing labels box, clear the checkboxes for labels that you want to remove from the selected breakpoints. 4.7.3.13. To Sort the Breakpoint List by Label 1. In the Breakpoints window, right-click the breakpoint list. 2. Point to Sort by and then click Label. (Optional) To change the sort order, right-click the breakpoint list again, point to Sort by, and then click Sort Ascending or Sort Descending. 4.8. Data Breakpoints Data breakpoints allow you to break execution when the value stored at a specified memory location is accessed (read/write). In general, Data Breakpoint hardware module listens on the data address and data value lines between the CPU and the data cache and can halt the CPU, if the address and/or value meets a stored compare value. Unlike program breakpoints, data breakpoints halt on the next instruction after the load/store instruction that caused the breakpoint has completed. 4.8.1. Adding Data Breakpoint Adding Data Breakpoint using code editor context menu You can add Data breakpoint from code editor. Select the variable in code editor and select Breakpoint → Add Databreakpoint from context menu. This adds data breakpoint for a given variable address. Default access mode is write and default mask is none. You can invoke the same command using short cut key Ctrl + Shift + R . Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 86 Figure 4-6. Adding Data Breakpoint from the Context Menu Adding Data Breakpoint from Debug menu You can add new Data breakpoint from Debug → New Breakpoint → New Data Breakpoint. This opens the Data Breakpoint Configuration window. Adding Data Breakpoint from Data Breakpoints tool window You can add new Data breakpoint using the New button in Data Breakpoints tool window. This opens the Data Breakpoint Configuration window. Note:  You can add or modify Data breakpoint only in debug mode. 4.8.2. Data Breakpoints Window 4.8.2.1. Data Breakpoints Tool Window The Data Breakpoint window provides the options to set data breakpoint and lists the added data breakpoints. Enable this window by choosing Debug → Windows → Data Breakpoints. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 87 Figure 4-7. Data Breakpoint Window Data Breakpoints toolbar has following elements: • - provides the data breakpoint configuration window to add a new data breakpoint. • - provides the data breakpoint configuration window to edit the selected data breakpoint. • - removes the selected data breakpoint. You can invoke the same command using the Delete key. • - removes the all data breakpoints. • - enable or disable all the data breakpoints. Data Breakpoints window displays several columns related to breakpoint configuration. Some of the columns are dynamically hidden based on the breakpoints configuration. E.g.: if none of the breakpoints has Mask configured, then Mask related columns are not displayed. Name column has three parts: • Check box - Use Check box to enable or disable breakpoint. • Icon - Glyph to represent the current state of the breakpoint. The following table describes these glyphs. If you rest the mouse on a breakpoint glyph, a breakpoint tip appears with more information. This information is especially useful for error and warning breakpoints. • Text - Displays the configured location expression for breakpoint. Table 4-2. Breakpoint Icons Icon Description Normal breakpoint. The solid glyph indicates that the breakpoint is enabled. The hollow glyph indicates that it is disabled. Advanced breakpoint. Active/disabled. The + sign indicates that the breakpoint has hit count attached to it. Tracepoint. Active/disabled. Hitting this point performs a specified action but doesn't break program execution. Advanced tracepoint. Active/disabled. The + sign indicates that the tracepoint has hit count attached to it. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 88 Icon Description Breakpoint or tracepoint error. The X indicates that the breakpoint or tracepoint couldn't be set because of an error condition. Check Message column for more details on error message. Breakpoint or tracepoint is set but with warning. Check Message column for more details on warning message. 4.8.2.2. Data Breakpoint Configuration Window for Mega This window provides configuration options related to data breakpoint for ATmega devices. Address mask is optional. Location You can enter a specific address in RAM (e.g.: 0x8004) directly or an expression that evaluates to an address in RAM (e.g.: &x). Make sure the expression you enter represents the address of the data to monitor. Note:  Data breakpoints on local variables can result in false hits due to reuse of stack memory. Suggestion to declare it as static for debugging purpose. Access Mode You can configure the breakpoint to break on specific Access Mode. Three types of access modes are supported. • Read - Program breaks on read at specified location. • Write (Default) - Program breaks on write at specified location. • Read/Write - Program breaks on read or write at specified location. Address Mask Address Mask on Mega Data Breakpoints is optional. Use address mask to break on more than one address or a range of address on particular access. Mask Mask value to mask the Location address to define more than one address or range of address. Bits with value 1 in the mask are significant bits and 0 are don't care bits. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 89 In general for a given address A and mask M, an address B successfully matches when: (A) & (M) == (B) & (M), where A is resolved address for the expression entered in Location, M is mask value entered in Mask and B is any address in RAM. Masked Address This is a read only field which shows the range of matching addresses on which program can break. The masked address is shown in the binary format for simplicity. 'X' represents don't care bits, remaining bits are expected to match. E.g. 0b000000010XX000XX means it can break as per access mode, at addresses which has all bits as per this string except X bits. In this case 0th, 1st, 5th, and 6th bit (lsb) can be anything since these bits are don't care (X). Note:  ATmega devices don't support Data Masks. 4.8.2.3. Data Breakpoint Configuration Window for XMEGA This window provides configuration options related to data breakpoint for XMEGA devices. Location You can enter a specific address in RAM (e.g.: 0x8004) directly or an expression that evaluates to an address in RAM (e.g.: &x). Make sure the expression you enter represents the address of the data to monitor. Note:  Data breakpoints on local variables can result in false hits due to reuse of stack memory. Suggestion to declare it as static for debugging purpose. Access Mode You can configure the breakpoint to break on specific Access Mode. Three types of access modes are supported. • Read - Program breaks on read at specified location. • Write (Default) - Program breaks on write at specified location. • Read/Write - Program breaks on read or write at specified location. Data Match Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 90 Use the Data Match option to configure Data Breakpoint to compare the data at specified location based on one of the following conditions: • Location content is equal to the value • Location content is greater than the value • Location content is less than or equal to the value • Location content is within the range • Location content is outside the range • Bits of the location is equal to the value Note:  Bit Mask: It is an 8-bit value where bits with '1' are significant and the bits with '0' are don't care. In general for a given value V and bit mask M, the break event is triggered when the value in the location field VL satisfies the condition (V) & (M) == (VL) & (M) For example, using Value = 0xA0 and Bit Mask = 0xF0 will trigger a break event when the location field has any of the values between0xA0 to 0xAF. Note:  Condition Value field has to be of 1 byte. 4.8.2.4. Data Breakpoint Configuration Window for UC3 This window provides configuration options related to data breakpoint for UC3 devices. Location You can enter a specific address in RAM (e.g.: 0x8004) directly or an expression that evaluates to an address in RAM (e.g.: &x). Make sure the expression you enter represents the address of the data to monitor. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 91 Note:  Data breakpoints on local variables can result in false hits due to reuse of stack memory. Suggestion to declare it as static for debugging purpose. Access Mode You can configure the breakpoint to break on specific Access Mode. Three types of access modes are supported. • Read - Program breaks on read at specified location. • Write (Default) - Program breaks on write at specified location. • Read/Write - Program breaks on read or write at specified location. Access Size You can configure the breakpoint to break on specific Access Size. Four types of access size are supported. • Any Access (Default) - Program breaks on any access size at specified location. • Byte Access - Program breaks on Byte access at specified location. • HalfWord Access - Program breaks on HalfWord access at specified location. • Word Access - Program breaks on Word access at specified location. Example for setting access size Configuration: Code: 1: int word = 0; 2: short *halfWord = (short*)&word; 3: Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 92 4: int main(void) 5: { 6: word = 0xAABBCCFF; 7: *halfWord = 0xDDEE; 8: } For the above configuration and code, program breaks at line eight after halfWord access. Data Match Use the Data Match option to configure Data Breakpoint to compare the data at specified location with a 32-bit value. Break event is triggered on a successful match. Value 32-bit (4-byte) value to compare with data at Location address. The value can be decimal or hexadecimal (e.g.: 100 or 0x64). Based on Access Size, respective bytes are used for data comparison. For example, if you select "HalfWord Access" as Access Size and enter 0xAABBCCDD as Value, then only the last two bytes (0xCCDD) are used for data comparison. You could further refine the Value by specifying Mask. Mask (Byte) Each check box controls the significance of respective byte in the Value field. Select appropriate check box to mask specific byte in the Value field. The number of check boxes displayed is decided based on Access Size. Four check boxes (one per byte) are displayed for "Any" and "Word Access", two check boxes for "HalfWord Access" and one check box for "Byte Access". Match Value A read only field, which displays masked value based on Access Size, Value, and Mask (Byte) field. Masked byte is represented as 'XX', which means that byte is insignificant in data comparison. 4.8.2.5. Data Breakpoint Configuration Window for SAM Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 93 Provides the configuration options related to data breakpoint for SAM devices. Address mask and Data match are optional. Location You can enter a specific address (e.g.: 0x8004) directly or an expression that evaluates to an address (e.g.: &x). Make sure the expression you enter represents the address of the data to monitor. Note:  Data breakpoints on local variables can result in false hits due to reuse of stack memory. Suggestion to declare it as static for debugging purpose. Access Mode You can configure the breakpoint to break on a specific Access Mode. Three types of access modes are supported. • Read - Program breaks on read at specified location. • Write (Default) - Program breaks on write at specified location. • Read/Write - Program breaks on read or write at specified location. Address Mask Use this setting to define range of addresses to monitor for access. Byte Count You can enter a number of address locations to monitor starting at Location address. The actual range of monitored address can be wider than the expected range. E.g.: if the Location is 0x23FA and the Byte Count is 5, then the actual range of the monitored address is [0x23F8 to 0x23FF]. The way actual range is computed is by calculating the number of least significant bits that has to be masked in the Location address (0x23FA) in order to cover the expected range [0x23FA to 0x23FA + 5]. In this case the number of bits to be masked is three. As a result the actual range [0x23F8 to 0x23FF] is wider than the expected range [0x23FA to 0x23FF]. Mask Size This is a read only field, which displays the number of least significant bits masked in the Location address. Mask Size is calculated based on the Byte Count and Location addresses. Address Range This is a read only field, which displays the actual range of address monitored for access. Range is closed interval including both minimum and maximum address. Data Match Use the Data Match option to configure Data Breakpoint to compare the data at specified location with a 32-bit value. Break event is triggered on a successful match. Value 32-bit (4-byte) value to compare with data at the Location address. The value can be decimal or hexadecimal (e.g.: 100 or 0x64). You could further refine the Value by specifying Mask. Mask You can use Mask to extract appropriate bytes from Value to use for data comparison. E.g.: if the Value is 0xAABBCCDD and Mask is HalfWord, then last two bytes (0xCCDD) is extracted from Value and used for data comparison. This means data comparison would succeed for the following matches 0xXXXXCCDD, 0xXXCCDDXX, and 0xCCDDXXXX, where X is a don't care hexadecimal digit (0 to F). Three types of Mask's are supported. • Byte - Last byte extracted from Value is used for data comparison. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 94 • HalfWord - Last two bytes extracted from Value is used for data comparison. • Word (Default) - Whole four bytes from Value is used for data comparison. Match Value This is a read only field which displays match values. Data Match Example Byte matching example • Location = 0x200008D4 • Value = 0x0000CCAA • Mask = Byte The program breaks when Location0x200008D4 has any of the following values: • 0xXXXXXXAA • 0xXXXXAAXX • 0xXXAAXXXX • 0xAAXXXXXX HalfWord matching example • Location = 0x200008D4 • Value = 0x0000CCAA • Mask = HalfWord The program breaks when Location0x200008D4 has any of the following values: • 0xXXXXCCAA • 0xXXCCAAXX • 0xCCAAXXXX Word matching example • Location = 0x200008D4 • Value = 0x0000CCAA • Mask = Word The program breaks when Location 0x200008D4 has the following value: • 0x00000CCAA Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 95 4.8.2.6. Data Breakpoint Configuration Window for Simulator Tool The above configuration window is displayed for any device architecture when a simulator tool is selected. Location You can enter a specific address in RAM (e.g.: 0x8004) directly or an expression that evaluates to an address in RAM (e.g.: &x). Make sure the expression you enter represents the address of the data to monitor. Note:  Data breakpoints on local variables can result in false hits due to reuse of stack memory. Suggestion to declare it as static for debugging purpose. Access Mode You can configure the breakpoint to break on specific Access Mode. Three types of access modes are supported. • Read - Program breaks on read at specified location. • Write (Default) - Program breaks on write at specified location. • Read/Write - Program breaks on read or write at specified location. Byte Count You can enter number of address locations to monitor starting at Location address. Note:  • Simulator supports unlimited number of data breakpoints 4.8.2.7. How to: Specify a Data Breakpoint Hit Count Hit count The number of times the value stored in the specified memory location is accessed (read/write). To specify a hit count To specify or edit the Hit Count property, you must open the Hit Count Dialog Box. In Data Breakpoints window, select a breakpoint row, and then choose Hit Count on the context menu. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 96 Figure 4-8. Hit Count Dialog Box To set or modify a hit count property, use the following controls: • When the breakpoint is hit: This setting determines how the breakpoint should behave when it is hit. You can choose to: • Break always (the default) • Break when the hit count equals a specified value • Break when the hit count equals a multiple of a specified value • Break when the hit count is greater or equal to a specified value • Current hit count: This value shows the number of times the data breakpoint has been hit. A read/ write data for a variable will be converted into multiple instructions, resulting in several memory access. So the data breakpoint hits multiple times for the same variable and the hit count will be updated accordingly. • Reset: This button resets the value shown for the Current hit count to 0. If you choose any option other than the default in When the breakpoint is hit list control, an edit box appears next to it. Edit the value in this edit box to set the hit count value. For example, you might choose break when hit count is equal to and enter 5. This causes execution to stop the 5th time the breakpoint is hit, not on any other hit. 4.8.2.8. When Breakpoint is Hit Dialog Box With this dialog box you can print a message in the output window when a data breakpoint is hit. To open the When Breakpoint Is Hit Dialog Box, go to the Data Breakpoints window, select a breakpoint row, and then choose When Hit on the context menu. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 97 Specify the message • You can use any of the keywords that are described on the When Breakpoint Is Hit dialog box. E.g.: Process Id : $PID. • You can also specify expressions in the message by placing it in the curly braces, such as sum={a +b} Specify the breakpoint behavior To break execution when the breakpoint is hit, clear the Continue Execution check box. When Continue Execution is checked, execution is not halted. In both cases, the message is printed. 4.8.3. General Information on Data Breakpoint • Data Breakpoint can be edited/added only in debug mode • Local variables must always be qualified with the function name. This is also the case if the user wants to add a variable from the function that the program has stopped in. Data breakpoints on local variables can result in false hits due to reuse of stack memory. Tip:  Declare local variables as static and provide the static variable's address in the location field, the address of the static variable is fixed during compilation/linking. • Global variables are initialized with default values during the start up, the valid data breakpoint for global variables will hit in the disassembly or initialization code during the start up Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 98 • There can be several instructions to perform read/write data for a variable, for example 'int' data type can have two individual byte read/write instructions so the data breakpoint hits twice for the same variable • Data breakpoint event can occur when the bus access happens for the specific address • Maximum number of data breakpoint supported: (this may vary based on specific device/family refer data sheet) Architecture Maximum Data breakpoint supported ATmega • Two without Data Mask (OR) • One without Data Mask and one with Data Mask XMEGA • Two without Data Mask (OR) • One without Data Mask and one with Data Mask (OR) • Two with Data Mask UC3 • Two without Data Mask (OR) • One without Data Mask and one with Data Mask (OR) • Two with Data Mask SAM Device dependent refer data sheet Tiny Does not support data breakpoint Most of the devices conforms to the above limit. Note:  ATmega and SAM device uses multiple hardware resources when a data breakpoint with data mask is set. Hence, using data mask can reduce the number of data breakpoint that can be set. 4.8.4. Data Breakpoint Usage 4.8.4.1. Stack Overflow Detection Using Data Breakpoint You can decide on maximum stack size for the your application and calculate the approximate end address for the stack. In the end address set the data breakpoint for address range by applying address mask and access type as Read/Write. Note:  The above method may cause false break when heap memory tries to access the specified stack end address. 4.9. QuickWatch, Watch, Locals, and Autos Windows The Atmel Studio debugger provides several windows, collectively known as variable windows, for displaying variable information while you are debugging. Each variable window has a grid with three columns: Name, Value, and Type. The Name column shows the names of variables added automatically in the Auto and Locals windows. In the Watch window, the Name column is where you can add your own variables or expressions. See how to watch an expression in the Debugger. The Value and Type columns display the value and data type of the corresponding variable or expression result. You can edit the value of a variable in the Value column. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 99 The variable windows, Autos, Locals, and Watch, display the values of certain variables during a debugging session. The QuickWatch dialog box can also display variables. When the debugger is in break mode, you can use the variable windows to edit the values of most variables that appear in these locations. Note:  Editing floating-point values can result in minor inaccuracies because of decimal-to-binary conversion of fractional components. Even a seemingly harmless edit can result in changes to some of the least significant bits in the floating-point variable. When an expression is evaluated in the Watch window, you might see a refresh icon. This indicates an error or out-of-date value. For more information, see How to: Refresh Watch Values. If you want to, you can enter an expression for a value. The debugger will evaluate the expression and replace it with the resulting value. The debugger accepts most valid language expressions in a Watch window. For more information, see Expression Formatting. If you are programming in native code, you might sometimes have to qualify the context of a variable name or an expression that contains a variable name. The context means the function, source file, and module where a variable is located. If you have to do this, you can use the context operator syntax. For more information, see Context Operator (C/C++ Language Expressions). Evaluating some expressions can change the value of a variable or otherwise affect the state of your program. For example, evaluating the following expression changes the value of var1 and var2: var1 = var2++ var1 = var2++ Expressions that change data are said to have side effects, which can produce unexpected results if you are not aware of them. Therefore, make sure you understand the effect of an expression before you execute it. To edit a value in a variable window 1. The debugger must be in break mode. 2. If the variable is an array or an object, a tree control appears next to the name in the Name box. In the Name column, expand the variable, if necessary, to find the element whose value you want to edit. 3. In the row you want to change, double-click the Value column. 4. Type the new value. 5. Press ENTER. To display a variable window On the Debug menu, choose Windows, then choose the name of the variable window you want to display (Autos, Locals, Watch, or Watch1 through Watch4). You cannot access these menu items or display these windows in design mode. To display these menu items, the debugger must be running or in break mode. 4.9.1. Watch Window Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 100 The Watch window and QuickWatch dialog box are places where you can enter variable names and expressions that you want to watch during a debugging session. The QuickWatch dialog box enables you to examine a single variable or expression at a time. It is useful for taking a quick look at one value or a larger data structure. The Watch window can store several variables and expressions that you want to view over the course of the debugging session. Atmel Studio has multiple Watch windows, which are numbered Watch1 through Watch4. A variable name is the simplest expression you can enter. If you are debugging native code, you can use register names as well as variable names. The debugger can accept much more complex expressions than that, however. For example, you could enter the following expression to find the average value of three variables: (var1 + var2 + var3) / 3 The debugger accepts most valid language expressions in a Watch window. For more information, see Expression Formatting. If you are programming in native code, you may sometimes need to qualify the context of a variable name or an expression containing a variable name. The context means the function, source file, and module where a variable is located. If you have to do this, you can use the context operator syntax. Expressions that Affect the State of Your Program Evaluating some expressions can change the value of a variable or otherwise affect the state of your program. For example, evaluating the following expression changes the value of var1: var1 = var2 Expressions that change data are said to have side effects. If you enter an expression that has a side effect into the Watch window, the side effect will occur every time the expression is evaluated by the Watch window. This can produce unexpected results if you are unaware that the expression has side effects. An expression that is known to have side effects is only evaluated one time, when you first enter it. Subsequent evaluations are disabled. You can manually override this behavior by clicking an update icon that appears next to the value. Unexpected side effects are frequently the result of function evaluation. For example, you could enter the following function call into the Watch window: PrintFunc1(var1) Func1(var1) If you call a function from the Watch window or QuickWatch, the function you are calling might change data, creating a side effect. One way to avoid possible unexpected side effects from function evaluation is Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 101 to turn OFF automatic function evaluation in the Options dialog box. This disables automatic evaluation of newer language features, such as properties. However, it is safer. Note:  When you examine an expression in the Watch window, you might see an update icon, which resembles two green arrows, circling in opposite directions within a green circle. This is especially likely if you have turned OFF automatic function evaluation. The update icon indicates an error or out-of-date value. The Atmel Studio debugger automatically expands common data types to show their most important elements. You add expansions for custom data types. For more information, see Displaying Custom Data Types and Visualizers. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Menus and Settings. To evaluate an expression in the Watch window 1. In the Watch window, click an empty row in the Name column. The debugger must be in break mode at this point. Type or paste the variable name or expression you want to watch. —or— Drag a variable to a row in the Watch window. 2. Press ENTER. 3. The result appears in the Value column. If you type the name of an array or object variable, a tree control appears next to the name in the Name column. Expand or collapse the variable in the Name column. 4. The expression remains in the Watch window until you remove it. To evaluate an expression in QuickWatch 1. In the QuickWatch dialog box, type or paste the variable, register, or expression into the Expression text box. 2. Click Reevaluate or press ENTER. 3. The value appears in the Current value box. 4. If you type the name of an array or object variable in the Expression box, a tree control appears next to the name in the Current value box. Expand or collapse the variable in the Name column. To reevaluate a previous expression in QuickWatch 1. In the QuickWatch dialog box, click the down arrow that appears to the right of the Expression box. 2. Choose one of the previous expressions from the drop-down list. 3. Click Reevaluate. 4.9.2. Locals Window Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 102 The Locals window displays variables local to the current context. 4.9.2.1. To Display the Locals Window From the Debug menu, choose Windows and click Locals. (The debugger must be running or in break mode.) 4.9.2.2. To Choose an Alternative Context The default context is the function containing the current execution location. You can choose an alternate context to display in the Locals window: • Use the Debug Location toolbar to select the desired function, thread, or program • Double click on an item in the Call Stack or Threads window To view or modify information in the Locals window, the debugger must be in break mode. If you choose Continue, some information may appear in the Locals window while your program executes, but it will not be current until the next time your program breaks (in other words, it hits a breakpoint or you choose Break All from the Debug menu). 4.9.2.3. To Modify the Value of a Variable in the Locals Window 1. The debugger must be in break mode. 2. In the Locals window, select the value you want to edit by double-clicking on it or by using the TAB key. 3. Type the new value, and press ENTER. Attention:  Editing floating-point values can result in minor inaccuracies because of decimal-to-binary conversion of fractional components. Even a seemingly harmless edit can result in changes to some of the least significant bits in the floating-point variable. Setting Numeric Format You can set the numeric format used in the debugger windows to decimal or hexadecimal. Right click inside the Locals window, and check/uncheck the Hexadecimal display menu item. 4.9.3. Autos Window The Autos window displays variables used in the current statement and the previous statement. The current statement is the statement at the current execution location (the statement that will be executed next if execution continues). The debugger identifies these variables for you automatically, hence the window name. Structure and array variables have a tree control that you can use to display or hide the elements. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 103 To display the Autos window From the Debug menu, choose Windows and click Autos. (The debugger must be running or in break mode.) 4.9.3.1. To Modify the Value of a Variable in the Autos Window 1. The debugger must be in break mode. 2. Display the Autos window, if necessary. 3. In the Value column, double-click the value you want to change. -orSingle-click to select the line, then press the TAB key. 4. Type the new value, and press ENTER. Attention:  Editing floating-point values can result in minor inaccuracies because of decimal-to-binary conversion of fractional components. Even a seemingly harmless edit can result in changes to some of the least significant bits in the floating-point variable. 4.9.3.2. Setting Numeric Format You can set the numeric format used in the debugger windows to decimal or hexadecimal. Right click inside the Autos window, and check/uncheck the Hexadecimal display menu item. 4.9.4. QuickWatch and Watches While debugging you might want to track a value of a variable or an expression. To do so you can right click at the expression under cursor and select Add a Watch or Quickwatch. The QuickWatch dialog box lets you examine and evaluate variables and expressions. Because QuickWatch is a modal dialog box, you have to close it before you can continue to debug. You can also edit the value of a variable in QuickWatch. For more information on how to watch a variable, see Watch Window. Some users might wonder why QuickWatch is useful. Why not add the variable or expression to the Watch window? That is possible, but if you just want to do a quick scratch calculation that involves one or Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 104 more variables, you do not want to clutter the Watch window with such calculations. That is when the QuickWatch dialog box is especially useful. Another feature of the QuickWatch dialog box is that it is resizeable. If you want to examine the members of a large object, it is frequently easier to expand and examine the tree QuickWatch than it is in the Watch, Locals, or Autos window. The QuickWatch dialog box does not allow you to view more than one variable or expression at a time. Also, because QuickWatch is a modal dialog box, you cannot perform operations such as stepping through your code while QuickWatch is open. If you want to do these things, use the Watch window instead. Some expressions have side effects that change the value of a variable or otherwise change the state of your program when they are executed. Evaluating an expression in the QuickWatch dialog box will have the same effect as executed the expression in your code. This can produce unexpected results if you do not consider the side effects of the expression. Note:  In Atmel Studio, you can view a variable's value by placing the cursor over the variable. A small box called a DataTip appears and shows the value. To open the QuickWatch dialog box While in break mode, choose QuickWatch on the Debug menu. To open the QuickWatch dialog box with a variable added While in break mode, right-click a variable name in the source window name and choose QuickWatch. This automatically places the variable into the QuickWatch dialog box. To add a QuickWatch expression to the Watch window In the QuickWatch dialog box, click Add Watch. Whatever expression that was displayed in the QuickWatch dialog box is added to the list of expressions in the Watch window. The expression will normally be added to the Watch1 window. 4.9.5. Expression Formatting The Atmel Studio debugger includes expression evaluators that work when you enter an expression in the QuickWatch and Watches, Memory View, Watch Window, or Immediate window. The expression evaluators are also at work in the Breakpoints window and many other places in the debugger. General Syntax: Val, formatString Format Specifier for values The following tables show the format specifiers recognized by the debugger. Table 4-3. Debug Format Specifiers for Values Specifier Format Expression Value displayed d,i signed decimal integer 0xF000F065, d -268373915 u unsigned decimal integer 0x0065, u 101 b unsigned binary number 0xaa,b2 0b10101010 o unsigned octal integer 0xF065, o 0170145 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 105 Specifier Format Expression Value displayed x,X Hexadecimal integer 61541, x 0x0000F065 1,2,4,8 As a suffix specifying number of bytes for: d, i, u, o, x, X. 00406042,x2 0x0c22 s String 0x2000, s "Hello World" f signed floating point (3./2.), f 1.500000 e signed scientific notation (3./2.), e 1.500000e+000 g signed floating point or signed scientific notation, whichever is shorter (3./2.), g 1.5 c Single character 0x0065, c 101 'e' Size Specifier for Pointers as Arrays If you have a pointer to an object you want to view as an array, you can use an integer to specify the number of array elements: ptr,10 or array,20 Memory type specifier The following memory type specifiers will force the memory reference to a specific memory type. To be used in the memory window in the address field, you should have a pointer to an object you want to view as an array. You can use an integer to specify the number of the array elements: Table 4-4. Debug Memory Type Specifiers Specifier Expression Value displayed flash or program Program memory 0,flash data Data memory 0x2000,data sram SRAM 0x100,sram reg or registers registers 1,reg io, eeprom, fusebytes, lockbytes, signature, usersign, prodsign Memory types with same names 4.10. DataTips DataTips provide a convenient way to view information about variables in your program during debugging. DataTips work only in break mode and only with variables that are in the current scope of execution. In Atmel Studio, DataTips can be pinned to a specific location in a source file, or they can float on top of all Atmel Studio windows. To display a DataTip (in break mode only) 1. In a source window, place the mouse pointer over any variable in the current scope. A DataTip appears. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 106 2. The DataTip disappears when you remove the mouse pointer. To pin the DataTip so that it remains open, click the Pin to source icon, or – Right-click on a variable, then click Pin to source The pinned DataTip closes when the debugging session ends. To unpin a DataTip and make it float • In a pinned DataTip, click the Unpin from source icon The pin icon changes to the unpinned position. The DataTip now floats above any open windows. The floating DataTip closes when the debugging session ends. To repin a floating DataTip • In a DataTip, click the pin icon The pin icon changes to the pinned position. If the DataTip is outside a source window, the pin icon is disabled and the DataTip cannot be pinned. To close a DataTip • Place the mouse pointer over a DataTip, and then click the Close icon To close all DataTips • On the Debug menu, click Clear All DataTips To close all DataTips for a specific file • On the Debug menu, click Clear All DataTips Pinned to File 4.10.1. Expanding and Editing Information You can use DataTips to expand an array, a structure, or an object to view its members. You can also edit the value of a variable from a DataTip. To expand a variable to see its elements: • In a DataTip, put the mouse pointer over the + sign that comes before the variable name The variable expands to show its elements in tree form. When the variable is expanded, you can use the arrow keys on your keyboard to move up and down. Alternatively, you can use the mouse. To edit the value of a variable using a DataTip 1. In a DataTip, click the value. This is disabled for read-only values. 2. Type a new value and press ENTER. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 107 4.10.2. Making a DataTip Transparent If you want to see the code that is behind a DataTip, you can make the DataTip temporarily transparent. This does not apply to DataTips that are pinned or floating. To make a DataTip transparent • In a DataTip, press CTRL The DataTip will remain transparent as long as you hold down the CTRL key. 4.10.3. Visualizing Complex Data Types If a magnifying glass icon appears next to a variable name in a DataTip, one or more Visualizers are available for variables of that data type. You can use a visualizer to display the information in a more meaningful, usually graphical, manner. To view the contents of a variable using a visualizer • Click the magnifying glass icon to select the default visualizer for the data type -orClick the pop-up arrow next to the visualizer to select from a list of appropriate visualizers for the data type. A visualizer displays the information. 4.10.4. Adding Information to a Watch Window If you want to continue to watch a variable, you can add the variable to the Watch window from a DataTip. To add a variable to the Watch window • Right-click a DataTip, and then click Add Watch The variable is added to the Watch window. If you are using an edition that supports multiple Watch windows, the variable is added to Watch 1. 4.10.5. Importing and Exporting DataTips You can export DataTips to an XML file, which can be shared with a colleague or edited using a text editor. To Export DataTips 1. On the Debug menu, click Export DataTips. The Export DataTips dialog box appears. 2. Use standard file techniques to navigate to the location where you want to save the XML file, type a name for the file in the File name box, and then click OK. To Import DataTips 1. On the Debug menu, click Import DataTips. The Import DataTips dialog box appears. 2. Use the dialog box to find the XML file that you want to open and click OK. 4.11. Disassembly View The Disassembly window is only available when debugging. When any supported high level language is used, the source window is automatically displayed and the disassembly window is OFF. Enable it by choosing Debug → Windows → Disassembly or Ctrl Alt D during a debugging session. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 108 The disassembly window shows your program code disassembled. Program execution and AVR instructions can be followed in this view. By right clicking inside the Disassembly window you will be able to set breakpoints, run to the position of the cursor, or go to the source code. You cannot modify the source code from the Disassembly window. In addition to assembly instructions, the Disassembly window can show the following optional information: • Memory address where each instruction is located. For native applications, this is the actual memory address. • Source code from which the assembly code derives • Code bytes byte representations of the actual machine • Symbol names for the memory addresses • Line numbers corresponding to the source code Assembly-language instructions consist of mnemonics, which are abbreviations for instruction names, and symbols that represent variables, registers, and constants. Each machine-language instruction is represented by one assembly-language mnemonic, usually followed by one or more variables, registers, or constants. Because assembly code relies heavily on processor registers or, in the case of managed code, common language runtime registers, you will often find it useful to use the Disassembly window in conjunction with the Registers window, which allows you to examine register contents. Note:  You may see inconsistencies in instructions that work on explicit addresses. This stems from the historic difference between the AVR Assembler and Assembly Language and the GCC Assembler and the assembly used on bigger computer systems. You might therefore encounter disassemblies that look like the one below. 13: asm volatile ("JMP 0x0001778A"); 0000007D 0c.94.c5.bb JMP 0x0000BBC5 Jump > Here the assembly instruction JMP 0x0001778A is being assembled by the GCC Assembler, and disassembled using the built-in disassembler in Atmel Studio, which resolves the jump to 0x0000BBC5, which is exactly half of the address in the initial assembly. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 109 It should be noted that the addresses are always of the same dimension as the line addresses shown in the disassembly, so the code is functionally similar. 4.12. I/O View 4.12.1. About the I/O View The purpose of the I/O View is to provide an overview of the registers of the target device for the current project. It serves as a quick reference during design, and is capable of displaying register values when the project is in debug mode. The view supports both 32- and 8-bit devices equally. The default view of the tool window is a vertically split window with peripheral groups in the top section, and registers in the bottom section. Each peripheral typically has a set of defined settings and value enumerations, which can be displayed by expanding a register in the peripheral view (top section). The register view (bottom section) will display all registers which belong to a selected peripheral group. If no peripheral is selected, the view is empty. Each register can also be expanded to display the pre-defined value groupings which belongs to the register. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 110 4.12.2. Using the I/O View Tool The I/O View is confined to a single tool window in the development environment. There can only be one instance of the I/O view at a time. To open the window, select Debug → Windows → I/O View. When in design mode, the I/O View will be disabled for inputs. It is still possible to change the layout or filters, and to navigate the view, but no values can be set or read. To read or change a value in the registers, AVR Studio must be in debug break mode (execution paused). In this mode, all the controls of the I/O View will be enabled and values can be read and updated in the view. In addition to simply displaying the value of a register, the I/O View will display each bit in the register in a separate column. Bits which are set will have a dark color by default, and cleared bits will have no color (default white). To change a bit, simply click it, and the value will be toggled. 4.12.3. Editing Values and Bits in Break Mode When the project is in debug break mode, any value can be changed by clicking the value field and writing a new value. Some values and bits cannot be modified as they are read-only, and some bits may be write-only. See the documentation for each device for more information. When a bit or value is set, it is immediately read back from the device, ensuring that the I/O View only displays actual values from the device. If a new value is set, but the I/O view does not update as expected, the register might be writeonly or simply not accessible. When a register has changed since last time it was displayed, it will indicate so with a red colored value and bits in the display. If a bit has been set since last time, it will be solid red. If it has been cleared it will simply have a red border. This feature can be toggled on or off in the toolbar. 4.13. Processor View Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 111 Debug → Processor View. The processor view offers a simulated or direct view of the current target device MPU or MCU. On the picture above you can see a partial list of the simulated device's ATxmega128U1 registers. The program counter shows the address of the instruction being executed, the stack pointer shows the application's current stack pointer value. The X,Y, and Z registers are temporary pointers that can be used in indirect passing or retrieving arguments or objects to and from functions. Cycle counter counts the cycles elapsed from the simulation’s start. Status register or SREG shows the currently set flags. Further on you will be able to toggle a setting for displaying the flag names. The stop watch field allows you to make rudimentary profiling of your application. It is influenced by the frequency set in the Frequency field, which defines target MCU/MPU frequency, in case when the prototyping board is connected. Each register can be displayed in hexadecimal, decimal, octal, and binary (flag) format by right-clicking and choosing Display in binary, etc., or Display in.... Each field can also be modified, as shown in the below image. If a field is a status or flags register, composed of a number of the one-bit flags, you can toggle individual flags by clicking on them - . The processor view is only active in the debug mode. 4.14. Register View Debug → Windows → Register View or Ctrl Alt G. The register view offers a simple way to see the data and system registers of your target or simulated device. You cannot modify the registers' contents from the Register view. 4.15. Memory View Debug → Windows → Memory view, or Ctrl Alt M n where n is the memory's number. The memory view gives you an outline of the memory. It is possible to select among the attached memories to see all the Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 112 segments by switching between them in a Segment drop-down menu on top of the memory view. You can also specify the starting address for the memory view window in the Address form field on top of the memory view. In order to specify the address you can use either a normal hexadecimal entry or an expression. See Expression Formatting. The Columns drop-down menu allows you to specify how many byte-aligned memory columns you wish to see at one time, most often this should be left at Auto setting, but if you have to manually check a fixed-length type values and you know how many words or bytes those values occupy, you could align the memory view so that each row will correspond to a desired number of values. 4.16. Call Stack Window Note:  Call Stack Window is currently only supported for 32-bit devices. Call stack shows the hierarchical information of callers of the current method. By default, the Call Stack window displays the name of each function. To display Call Stack, Click the menu, Debug → Windows → Call Stack. Along with function name, optional information such as module name, line number, etc. may also be displayed. The display of this optional information can be turned ON or OFF. To switch ON/OFF the optional information displayed, Right-click the Call Stack window and select or deselect Show Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 113 Stack frame of the current execution pointer is indicated by an yellow arrow. By default, this is the frame whose information appears in the source, Disassembly, Locals, Watch, and Auto windows. The stack frame context can also be changed to be another frame displayed in the Call Stack window. Warning:  Call Stack may not show all the call frames with Optimization levels -O1 and higher. To switch to another stack frame 1. In the Call Stack window, right-click the frame whose code and data you want to view. 2. Select Switch to Frame. A green arrow with a curly tail indicates the changed stack context. The execution pointer remains in the original frame, which is still marked with the yellow arrow. If you select Step or Continue from the Debug menu, the execution will be continued from the yellow arrow, not the frame you selected. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 114 To view the source/disassembly code for a function on the call stack 1. In the Call Stack window, right-click the function whose source code you want to see and select Go To Source Code. 2. In the Call Stack window, right-click the function whose disassembly code you want to see and select Go To Disassembly. To set a breakpoint on the exit point of a function call In the Call Stack window, right-click the stack frame to which you would like to add the breakpoint. Select "BreakPoint → Insert Breakpoint" to add the breakpoint. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 115 4.17. Object File Formats While Atmel Studio uses ELF/DWARF as the preferred object file-/debug info-format, You may debug other formats. Several object file formats from various compiler vendors are supported. You can open and debug these files, but you may not be able to edit the code from within Atmel Studio. Using your own editor to edit code and Atmel Studio to debug (use the reload button), you will still have a powerful code/ debug environment. All external debug sessions require you to load an object file supported by Atmel Studio. An object file for debugging usually contains symbolic information which is not included in a release file. The debug information enables Atmel Studio to give extended possibilities when debugging, e.g. Source file stepping and breakpoints set in high level language like C. Precompiled object files can be opened by using the menu command Open file → Open Object File for Debugging. See section Debug Object File in Atmel Studio for more info. Table 4-5. Object File Formats Supported by Atmel Studio Object file format Extension Description UBROF .d90 UBROF is an IAR proprietary format. The debug output file contains a complete set of debug information and symbols to support all type of watches. UBROF8 and earlier versions are supported. This is the default output format of IAR EW 2.29 and earlier versions. See below how to force IAR EW 3.10 and later versions to generate UBROF8. ELF/DWARF .elf ELF/DWARF debug information is an open standard. The debug format supports a complete set of debug information and symbols to support all types of watches. The version of the format read by Atmel Studio is DWARF2. AVR-GCC versions configured for DWARF2 output can generate this format. AVRCOFF .cof COFF is an open standard intended for 3rd party vendors creating extensions or tools supported by the Atmel Studio. AVR Assembler format .obj The AVR assembler output file format contains source file info for source stepping. It is an Atmel internal format only. The .map file are automatically parsed to get some watch information. Before debugging, make sure you have set up your external compiler/assembler to generate an object file with debug information in one of the formats above. 3 rd party compiler vendors should output the ELF/DWARF object file format to ensure support in Atmel Studio. Optionally you could provide an extension to have both debugging and compile support. See Contact Information for more information. Tip:  How to generate AVR-compatible ELF file in IARW32: In the Project options → Output format dialog choose elf/dwarf, and in the Project options → Format variant select ARM-compatible "-yes". Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 116 Tip:  How to force IAR EW 3.10 and later versions to generate UBROF8: By default IAR EW 3.10 and later versions output UBROF9. Currently, Atmel Studio cannot read this format. To force the debug format to UBROF8 open the project options dialog and change the Output format setting to ubrof 8 (forced). Note that the default file name extension is changed from '.d90' to '.dbg' when selecting this option. To keep the '.d90' extension, click the Override default check button and change the extension. 4.18. Trace In Atmel Studio, trace is provided on a plug-in basis. This means that different plugins separate from the core of Atmel Studio will be the provider of the different graphics view to visualize trace. In the realm of trace, there are some terminology that describe the different trace sources that a device and tool combination supports. These high level source names are mapped to different architecture specific trace sources. The following sections will describe some of the high level trace sources that might be available, and how it is mapped to the target architecture. Only a high level description of the different sources will be given, as the device specific details are available in the respective datasheet. Note:  The architecture for discovering trace capabilities in Atmel Studio is based on what the chip itself reports. This means that a debug session needs to be running so that the capabilities can be probed. This means that when activating a trace source, Atmel Studio might fail if the device does not support the source that was asked for during launch. 4.18.1. Application Output Application output is a common name for a technique that provides what is known as a stimuli port. This implies some mean for the application running on the device to output data to a debugger that is connected. 4.18.1.1. ITM ITM is an optional part of the debug system on ARM cores. The module provides a set of registers that an application can write data to, that will be streamed out to the debugger. 4.18.1.2. IDR Events When the application program writes a byte of data to the OCDR register of an AVR device while being debugged, the debugger reads this value out and displays it as IDR events in the output window as shown in the figure below. The OCDR register is polled at a given interval, so writing to it at a higher frequency than the one specified for the debugger will not yield reliable results. The datasheet of the device will explain how to check that a given value has been read. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 117 Figure 4-9. IDR Events Note that the Output window does not have the “IDR Messages” drop down if no IDR events have been sent from the debugger. 4.18.2. Program Counter Sampling This trace source involves some sort of sample system that reads out the program counter of the device periodically. This can then be used to graph where execution time is being spent, based on some statistical average. 4.18.2.1. ARM Implementations There are two ways of sampling the program counter on an ARM Cortex core. The first is using an optional module in the debug system that emits the program counter to the debugger without any impact on the core itself. The program counter is emitted on the SWO pin. As not all Cortex implementation can emit the program counter, Atmel Studio also supports doing a periodical readout of the program counter while to core is running. This is possible as most Cortex devices supports readout of memory while the core is running, with a small impact on the running application as the debug system needs to access the memory bus. 4.18.2.2. AVR 32-bit Implementation Reading the program counter on the AVR 32-bit core is possible in the same way as mentioned in ARM Implementations, as the core supports live readout of memory while the core is running. 4.18.3. Variable Watching Watching variables are usually covered by data breakpoints, see Data Breakpoints. However, on some systems it is also possible to make a data breakpoint emit the information to the debugger without halting the core, meaning that it is possible to watch variables in applications that for instance has some sort of external timing requirement that a data breakpoint would cause to fail. 4.18.3.1. ARM Implementations Data breakpoints on a Cortex core can be changed to emit a trace packet if the debug system implements the needed modules. This means that it is possible to get information about reads or writes to a specific memory location without an interference with the execution on the core. As a fallback to this, it is also possible to read a memory location at a given interval while the core is executing. This will not be any specific event data, but means that if the core supports live memory readout, it is possible to sample some parts of the memory. This has a minor impact on the execution, as the debug system needs to have access to the memory bus. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 118 4.18.3.2. AVR 32-bit Implementation The AVR 32-bit core also supports live readout of memory locations. This means that Atmel Studio can poll a memory location while to core is executing, giving a statistical view of how the variable is changing over time. 4.19. Trace View The Trace View allows you to record the program counter trace when a target is running. The program counter branches are mapped with the respective source line information. It also contains coverage and statistics for the source lines executed. To open the Trace View, go to Debug → Windows → Trace View. To use the functionality of the Trace View, a project has to be opened in Atmel Studio. Figure 4-10. Opening Trace View From the Menu 4.19.1. Trace View Options The Trace View toolbar has the following elements: • - Starts the program trace • - Stops the program trace • - Clears the program trace • - Toggles the highlighting of source code • - Configures the device to record the program trace • - Finds the exception record in the Trace Stack view • - Exports coverage statistics into an xml/xslt report 4.19.1.1. Starting the Program Trace The Program Trace can be started by clicking the play button in the Trace View Window. The start button is enabled during debug. Trace can be started and stopped any number of times in a debug session. Starting a new trace session clears all trace information of the previous trace session. Note:  A region of SRAM has to be allocated to let the device record the trace. Refer to Trace View Settings for more information. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 119 Figure 4-11. Trace View Window 4.19.1.2. Stop Trace Trace can be stopped in run or debug mode. The trace session will be ended automatically without user intervention when the debugging session ends. 4.19.1.3. Clear Trace The clear button clears the trace in the Trace View Window. New trace information will be logged in the same tool window with continuous sequence number. Clear can be done any number of times within a trace session. Once cleared the trace data cannot be recovered. 4.19.1.4. Highlight Source Code Highlight is a toggle button which toggles between highlighting and non-highlighting of the source code. The source code that are covered are highlighted with a green color and remaining source lines with a red color representing the uncovered source code for the current execution. Figure 4-12. Code Highlight Note:  Only the compilable lines are taken into consideration. For example, lines with comments and variable declaration are ignored. 4.19.1.5. Trace View Settings The device has to be configured to record the trace information in SRAM. The allocated size for recording the program trace can be configured from this setting. The memory can be allocated in: • Source code, allocating a global array • Linker scripts, reserving an amount of the memory map Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 120 Select the memory size to be allocated for recording the program trace. Copy the snippet of code displayed in configuration window by clicking on the CopyToClipBoard button and paste into your source code. Follow the instructions given in the dialog to enable the tracing capability. Figure 4-13. Trace Settings Window Through Source Code Note:  If both the linker script and the source code is configured for trace, the linker script settings takes the higher precedence over source code settings. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 121 Figure 4-14. Trace Settings Window through Linker Script 4.19.2. Trace View Interpretation The Trace View window contains the following items: • Trace Stack View • Coverage View 4.19.2.1. Trace Stack View Trace Stack View is populated with program trace information while the target is in a running or debugging state. Trace Stack View contains a sequence number, source and destination address, and a repeat count. A new program trace record is shown when a branching instruction happens on the target, for example as a function call or a return from a function. • Sequence Number - Number that keeps track of the order of the record. This number is reset for every trace session. This number will be continued without break when trace is cleared using clear button from the toolbar. • Source - Represents the instruction/source line from which the branch happened. For example, in a function call, Source is the source line from where the function is being called. • Destination - Represents the instruction/source line to which the branching happened. For example, in a function call, Destination is the source code of the starting line of the function. • Repeat Count - Represents the number of times the same source and destination combination occurred consecutively. For example, if there is a delay which is logging the same packets, it will be grouped together and number of times record occurrence is termed as repeat count Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 122 The source and destination contains instruction address, function name, source file name, and line number. If the source line cannot be mapped only the instruction address is given. Double click on the source or destination navigates the cursor in the editor to the appropriate line. Navigation keys Up, Down, Left, Right, and Tab can be used to locate the source/disassembly view for the trace records. The program trace that is shown in the TraceStack view are cut down to the latest 20000 records by default. The threshold value can be changed using the slider. The program trace records are highlighted with a yellow color when the branching instruction was not an expected one. Unexpected branches usually happens due to some exception, and the entry and exit of the exception handler is highlighted with yellow color. The branching inside the exception are not highlighted. Figure 4-15. Exception Record Tip:  The next and previous exception records can be easily navigated to by using the up and down arrow buttons in the trace view window tool bar. There are some exceptional cases where some program traces could be missed. In that case there will be a packet with red color which represents that there are some discontinuation of the program trace information in the sequence. Since the number of missed packets are unknown, the sequence number shown in the Trace Stack view will be continued without any break except adding a red colored packet with a sequence number for it. Note:  The disassembly view is not supported when navigation keys are used, but it is supported when the record is double clicked using mouse. 4.19.2.2. Coverage View The coverage view shows statistics on the source covered as part of the current target execution. All the files and functions are listed in the coverage view with the information of number of lines covered or uncovered against the total number of lines in the source file. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 123 Figure 4-16. Code Coverage Note:  Only the compilable lines are taken into consideration for the statistics. For example, lines with comments and variable declaration are not taken into account. A coverage report can be exported. Click the export icon in the trace view toolbar to invoke the export operation. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 124 5. Programming Dialog 5.1. Introduction The Device Programming window (also known as the programming dialog), gives you the most low-level control of the debugging and programming tools. With it, you can program the device's different memories, fuses, and lockbits, erase memories, and write user signatures. It can also adjust some of the starter kit properties such as voltage and clock generators. Note:  If you are editing a code project in Atmel Studio and want to see the results of a compilation by downloading the code into the device, take a look at the Start without Debugging command. It is a sort of one-click programming alternative to the programming dialog. See section Start without Debugging for more information. The programming dialog is accessible from a button on the standard toolbar or the menu Tools → Device Programming. Figure 5-1. Device Programming Icon Figure 5-2. Opening Device Programming Dialog Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 125 Figure 5-3. Device Programming The programming dialog contains the following options and tabs: Top status bar Tool You can choose which tool you want to use from this drop-down menu. Only tools connected to the machine are listed. Also, if a tool is used in a debug session, it will not be listed. Several tools of the same type can be connected at the same time. In order to identify them, the serial number will be shown below the tool name in the list. When a tool is selected, the name (and serial number) will be shown in the title bar of the Device Programming dialog. Note:  The Simulator will only offer limited support for the programming dialog features. The Simulator has no persistent memory, so you will not be able to make permanent changes to any simulated devices. Device As soon as a tool is selected, the device list will show all devices supported by that tool. There are two ways to select a device: • Select from the list Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 126 Click on the arrow. This will reveal the list of supported devices. Click to select. • Select by typing. In this example, we will select the ATxmega128A3: 2.1. Double-click in the text field to select the text already present. 2.2. Start typing some part of the device's name, in this example 128A. The list updates while you type, showing all devices containing what is typed. 2.3. Press the Arrow Down keyboard button to move the selection into the list. Use the up and down keys to navigate. Press ENTER to make a selection. 2.4. The ATxmega128A3 is now selected. Note:  A red border around the device selector indicates that the text entered is not a valid device name. Continue typing until the device name is complete, or select from the list. Interface When a tool and a device is selected, the interface list will show the available interfaces. Only interfaces available on both the tool and the device will appear in this menu. Select the interface to use to program the AVR. Apply button When tool, device, and interface is selected, press the Apply button to make the selections take effect. This will establish connection to the tool. The list on the left side of the window will be updated with the relevant pages for the selected tool. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 127 If a different tool, device, or interface is selected, the Apply button must be pressed again, to make the new selections take effect. Device ID Press the Read button to read the signature bytes from the device. The device's unique tag will appear in this field, and can be used for tool compatibility checking and to obtain help either from customer support or from the people at AVR Freaks® . Target voltage All tools are capable of measuring the target's operating voltage. Press the refresh button to make a new measurement. A warning message will appear if the measured voltage is outside the operating range for the selected device, and the target voltage box will turn red. 5.2. Interface Settings The programming interfaces have different settings. Some interfaces have no settings at all, some interfaces settings are only available on some tools. This section will describe all settings, but they are not available for all tools and devices. JTAG If you have selected JTAG as the programming interface, clock speed, use external reset and daisy chain setting may be available. This depends on the tool and device. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 128 JTAG Clock JTAG clock is the maximum speed the tool will try to clock the device at. The clock range is different for different tools and devices. If there are restrictions, they will be stated in a message below the clock slider. Use external reset If checked the tool will pull the external reset line low when trying to connect to the device. JTAG Daisy chain settings Specify the JTAG daisy chain settings relevant to the device to program. Target is not part of a daisy chain. Select this option when the target device is not part of a daisy chain. Daisy chain-Manual. Allows you to manually configure the JTAG daisy chain in case you are programming in a system-on-board. • Devices before - specifies the number of devices preceding the target device. • Instruction bits before - specifies the total size of the instruction registers of all devices, preceding the target device. • Devices after - specifies the number of devices following the target device. • Instruction bits after - specifies the total size of the instruction registers of all devices, following the target device. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 129 Daisy chain-Auto. Automatically detects the devices in the JTAG daisy chain. Allows you to select the device in the JTAG daisy chain. Auto-detection is supported only for SAM devices. To accept the changes and configure the tool, press the Set button. PDI The PDI interface has only one setting – the PDI clock speed. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 130 PDI Clock is the maximum speed the tool will try to clock the device at. The clock range is different for different tools and devices. If there are restrictions, they will be stated in a message below the clock slider. To apply the changes and configure the tool, press the Set button. The clock cannot be adjusted on all tools, so an empty Interface settings page will be presented. 5.3. Tool Information Figure 5-4. Tool Info The Tool information page contains a number of useful tool parameters. Tool Name denotes the common name for the connected tool. Debug Host is the debug session's host IP address for the remote debugging case. If the tool is connected to your machine, then the loopback interface IP (127.0.0.1) will show. Debug Port is the port opened specifically for the remote debugging access to the debugging tool. The port is automatically assigned when Atmel Studio starts, and is usually 4711. Serial number - tool serial number. Connection - Microsoft Driver Framework Method's name used to connect the Tool on your PC. xxx version - Firmware, hardware and FPGA file versions are listed here. Using the link on the bottom of the dialog you can access extensive information on your tool online. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 131 5.4. Board Settings/Tool Settings Some tools (Power Debugger, STK500, STK600, QT600) have on-board voltage and clock generators. They can be controlled from the Board settings/Tool settings page. 5.4.1. Power Debugger The Power Debugger has a single voltage source and two channels of voltage/current measurement. Figure 5-5. Power Debugger Tool Settings The voltage output (VOUT) is adjusted by the slider, or by typing a voltage in the Generated text boxes below the slider. After adjusting the set-point, press the Write button to apply the changes. The value is then sent to the tool, and the measured value is read back. Press the Read button to read both the set-point (Generated) and the Measured values from the Power Debugger. Note:  There may be slight differences between the Generated and the Measured voltages. The output voltage range is 1.6V to 5.5V. The Channel A and Channel B measurements are snapshots of analog readings taken by the Power Debugger. The tool is optimized for real-time monitoring of voltage and current, and this snapshot is thus approximate. It does not perform calibration compensation, and readings are locked in the highest-current range. For best results, use the Atmel Data Visualizer. Note:  When no load is connected to a measurement channel, non-zero measurements can be expected. 5.4.2. STK600 The STK600 has three voltage sources and one clock generator. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 132 Figure 5-6. STK600 Board Settings The set-points of the three voltage sources (VTG, ARef0, and ARef1) are adjusted by the means of three sliders. It is also possible to type a voltage in the Generated text boxes below the sliders. When you drag the sliders, the text boxes will update. And when you type a value in the text box, the slider will move. After adjusting the set-points, press the Write button to apply the changes. The values are sent to the tool, and measure values are read back. Measurements are shown in the Measured row, and shown as blue columns as part of the slider controls. The measured values cannot be edited. Press the Read button to read both the set-point (Generated) and the Measured values from the STK600. Note:  What is the difference between the Generated and the Measured voltages? The generated voltage is the setting on the adjustable power supply, the measured voltage is the readout from the builtin volt meter. If the measured value is different from the generated voltage, this may indicate that the target circuitry draws a lot of current from the generator. Note:  If the VTARGET jumper on STK600 is not mounted, the measured voltage will be 0, unless an external voltage is applied to the VTARGET net. The Clock generator is also adjusted by dragging the slider or typing into the text box below. Press the Write button to apply the new value. 5.4.3. QT600 The QT600 has only one setting, the VTarget voltage. This voltage can be set to five fixed voltages: 0, 1.8, 2.7, 3.3, and 5V. Press the Write button to apply the changes. The actual VTarget value is read back automatically when pressing the Write button. It is also possible to read it back manually using the Read button. 5.4.4. STK500 STK500 has settings similar to the STK600, but only one Aref voltage and combined generated/measured values. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 133 5.5. Card Stack The STK600 uses a combination of routing and socket cards to let all AVR devices to be mounted. Given the device, only certain combinations of routing and socket cards are valid. The Card stack page has information about this. Figure 5-7. Card Stack The card stack page tells which cards are mounted on the STK600 and if they support the selected device. If they do match, a list of devices supported by that card combination is listed. If the mounted cards do not match, a list of suggested card combinations will be listed. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 134 5.6. Device Information Figure 5-8. Device Information The device information page contains basic information on the selected device. When the page is accessed, it will try to read the JTAG (or device) signature from the connected device. In the upper part of the dialog you can see the device name, its signature, the JTAG part identification number, and the device revision (extracted from the JTAG signature). In the lower part of the dialog you see the device variants and characteristics of each variant. Acceptable voltage range, followed by maximum operating clock speed, and the sizes of on-chip memories. The two links on the bottom of the dialog offer you to see a slightly more detailed device information in the purchase catalog online, or to download a complete datasheet of the target device. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 135 5.7. Oscillator Calibration Figure 5-9. Oscillator Calibration Oscillator Calibration Byte(s) for ATtiny and ATmega parts From the Advanced tab you can read the Oscillator Calibration Byte(s) for ATtiny and ATmega parts. The oscillator calibration byte is a value that can be written to the OSCCAL register found in selected devices, in order to tune the internal RC Oscillator to run as close to a chosen clock frequency as possible. Program The oscillator calibration byte is stored in the device during manufacturing and can not be erased or altered by the user. It is automatically transferred to the OSCCAL register during device start-up, or set during program initialization, depending on the device. On devices where the application sets it during program initialization, it must be transferred to FLASH or EEPROM first, using the programming dialog or the command line tools. Reading and Writing the Oscillator Calibration Byte for ATtiny and ATmega parts The calibration value is read from the storage in the device and shown in the Value text box by pressing the Read button. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 136 The calibration byte is programmed into FLASH or EEPROM memory by pressing the Write button. Memory type and address must be specified first. 5.8. Memories Figure 5-10. Memories Programming From the Memories tab you can access all the programmable memories on the target device. Memory is erased by first selecting the memory type and then clicking on the Erase button. Selecting Erase Chip will erase the entire contents of the device, including FLASH, EEPROM (unless the EESAVE fuse is programmed), and lock-bits, but not Userpages if the device contains this. Program To program a file into the device's Flash memory, write the full path and file name in the combo box in the flash section. Or, select the file by pressing the browse button (...). Now, press the Program button to program the file into the memory. If the Erase device before programming check box is checked, a chip erase operation will be performed before the programming operation starts. If the Verify device after programming check box is checked, the content will be verified after the programming operation is done. Some devices can also be programmed through a flashloader. This is mainly an advanced technique, but it will usually give a significant speedup in the programming speed. For devices where this is supported, a Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 137 checkbox will be shown named Program flash from RAM. If this box is checked, the base address of the location of the flashloader needs to be given. Verify To verify the flash content of the device, first select the file you want to verify against. Then press the Verify button. Read The contents of the Flash memory can be read out in Intel® hexadecimal file format, using the Read button. Pressing the Read button will bring up a dialog offering you to specify where the file will be saved. EEPROM The device's EEPROM memory can be programmed in a similar way. User Signatures The XMEGA device's User Signature memory can be programmed the same way. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 138 5.9. Fuse Programming Figure 5-11. Fuse Programming The Fuses page presents the fuses of the selected device. Press the Read button to read the current value of the fuses, and the Program button to write the current fuse setting to the device. Fuse settings are presented as check boxes or as drop down lists. Detailed information on which fuses are available in the different programming modes and their functions can be found in the device datasheet. Note that the selected fuse setting is not affected by erasing the device with a chip-erase cycle (i.e. pressing the Chip Erase button on the Memories page). Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 139 Fuse values can also be written directly into the fuse registers in the lower pane as hexadecimal values. Auto read If this check box is checked, the fuse settings will be read from the device each time you enter the fuse page. Verify after programming When this check box is checked, the settings will be verified after a programming operation is completed. The appearance of the fuse glyph describes whether the fuse information is up to date compared to the state of the device. the fuse value is up to date. i.e the same state as in the device. the fuse has been modified by the user and it is not yet programmed into the device. the fuse state is unknown, it has not been read from the device, nor modified by the user. 5.10. Lock Bits The lock bit page is similar to the fuse page. For usage, see section Fuse Programming. 5.11. Production Signatures The production signature page is only visible for AVR XMEGA devices and shows factory programmed data in the production signature row. It contains calibration data for functions such as oscillators and analog modules. The production signature row can not be written or erased. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 140 Figure 5-12. Production Signatures 5.12. Production Files The ELF production file format can hold the contents of both Flash, EEPROM, and User Signatures (XMEGA devices only) as well as the Fuse- Lockbit configuration in one single file. The format is based on the Executable and Linkable Format (ELF). The production file format is currently supported for tinyAVR, megaAVR, and XMEGA. See Creating ELF Files with Other Memory Types for description on how to configure the project in order to generate such files. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 141 Figure 5-13. Production Files Programming Program device from ELF production file: To program your device from an ELF file, you must first select a source file by typing its full path into the combo box, or by pressing the browse button . Depending on the contents of your file, check boxes for the different memory segments will be activated. It is possible to select one or several of the memory segments that the ELF production file contains. You can then program and verify the device with the content of these segments in one single operation. Select which memory segments you want to program ticking off the corresponding check boxes. Select the Erase memory before programming check box, if you want an erase operation to be performed before the programming operation. Note:  The erase memory operation will depend on the device selection. For tinyAVR and megaAVR, both Flash, EEPROM, and lockbits will be erased (chip erase) independent of which memories are selected, while for XMEGA only the selected memories will be erased. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 142 Select the Verify device after programming check box, if you want the contents to be verified after the programming operation is done. Select the Verify Device ID check box, if you want to verify the device id stored in the file (signature bytes) with the connected device. Now, press the Program button to program the file into the memory. You can verify the contents of the device against an ELF file by pressing the Verify button. The verification will only verify the contents of the selected memory segments. Figure 5-14. Production Files Creation Save to ELF production file: Prior to creating the ELF file, specify the input file path for FLASH, EEPROM, and Usersignature on the production file tab. Then configure the Fuse and Lockbits on the corresponding tab and program it. The Fuse and Lockbits, which are programmed in the device will be taken as input while creating ELF file. Back on the production file tab, press the "Save" button" to generate the ELF file. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 143 You must specify which segments are to be present in the production ELF file by ticking the corresponding check boxes. 5.13. Security The security bit allows the entire chip to be locked from external JTAG or other debug access for code security. Once set, the only way to clear the security bit is through the Chip Erase command. Figure 5-15. Security Page To check the state of the security bit, press the Read button on the Security page of the programming dialog. The value should now read Cleared or Set. Set meaning that the security bit is set, and Cleared meaning that it is not set. If the Auto Read check box is ticked off, the Read operation will be performed automatically when the Security page is opened. To set the security bit, simply press the Set button on the Security page of the programming dialog. Now the device is locked for all further JTAG or aWire access except for the Chip Erase command. Locked device When the security bit is set, the device is locked for most external debug access. Attempts to program or read any memories or fuses, will cause an error message to appear. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 144 Figure 5-16. Security Bit Error To unset the security bit, issue the Chip Erase command. This can be done from the Memories page, see Memories. 5.14. Automatic Firmware Upgrade Detection As mentioned in the Firmware Upgrade section, you may encounter a dialog stating that your tool's firmware is out of date when you open the Device Programming dialog. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 145 6. Miscellaneous Windows 6.1. Device Pack Manager The Device Pack Manager is used to manage the devices supported by Atmel Studio. The Device Pack Manager is launched from Tools → Device Pack Manager. Figure 6-1. Device Pack Manager Menu Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 146 Figure 6-2. Device Pack Manager The Device Pack Manager consists of two panes. The left pane shows the list of packs that are installed. The right pane shows the devices that are provided by the pack selected in the left pane. Packs can have any of the following statuses: Up to date Pack is already up to date and latest. Update Available New update is available. Not Installed Pack is not installed, but can be downloaded. Actions Install selected packs Download and install all packs that have been selected using the check-boxes besides the version. Install all updates Download and install all available updates. Browse pack file Install an already downloaded pack file. Uninstall Uninstalls all packs that have been selected using the check-boxes besides the version. Check for Updates Check for new and updated packs. Search The search box can be used to search after a specific pack, or a device in any of the packs. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 147 Reset cache Resetting the cache will re-index all installed packs. This does not uninstall or remove anything. It is in the Advanced menu. Note:  After installing, updating, or removing packs, Atmel Studio has to be restarted before the changes becomes visible. 6.2. User Interface Profile Selection Different user interface profiles targeted for different use is available in Atmel Studio. The user interface profile controls the visibility of menus, window layouts, toolbars, context menus, and other elements of Atmel Studio. The following modes are available: Standard The default profile. Includes the most used windows and menus. Advanced The profile used in previous versions of Atmel Studio. This profile includes advanced debugging and re-factoring tools. Figure 6-3. Profile Selection The profile selection window is shown the first time Atmel Studio is started. Selecting a profile in the list will show a description of the profile. Clicking the Apply button applies the profile to Atmel Studio. The profile can be changed at any time by navigating to Tools → Select Profile, or by clicking the profile name that is displayed in the top right corner of Atmel Studio. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 148 Figure 6-4. Selected Profile When switching profiles, any changes done to the active profile is saved. Going back to the previous profile will restore the changes as well as the profile. Using the Reset option discards any changes saved to the profile and restores it to the default profile. 6.3. Available Tools View 6.3.1. Introduction The Available Tools view (View → Available Atmel Tools) contains a list of all connected tools such as programmers, debuggers and starter kits. The Simulator is always present. Other tools will show up when they are connected to the PC. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 149 6.3.2. Tool Actions The following actions can be selected by right clicking tools in the Available Tools view: Device Programming Opens the Device Programming window with the tool preselected. Self test Some tools are capable of performing a self test. Follow the displayed instructions. Add target Adds a tool to the list of available tools that is not auto-detectable. See Add a Non-detectable Tool for more information. Upgrade Starts the firmware upgrade tool with the selected tool. Show Info Window Shows the Tool Info window. Not all tools supports this feature. See Tool Info Window for more information. 6.3.3. Add a Non-detectable Tool The STK500 does not have a USB connection, and cannot be automatically detected by Atmel Studio. So it must be added to the list of available tools before it can be used by the Device Programming window. To add an STK500, right click inside the Available Tools view, select Add target and select the STK500 as the tool and the COM port your STK500 will be connected to. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 150 Press the Apply button, and the STK500 will be displayed in the list of available tools. Note:  An STK500 that has been added will be visible in the Available Tools view event even if no STK500 is connected to the specified COM port. If you want to remove STK500 from the list, you can right click on it and select Remove from the context menu. 6.3.3.1. Add J-Link over IP In the Add target dialog, it is possible to add a remote Segger J-Link debug probe. Both using a debug probe with built-in ethernet such as the J-Link PRO3 and any other Segger probe by using the J-Link Remote Server software4 . Figure 6-5. Add J-Link over IP To add a debug probe that is connected to a J-Link Remote Server, choose Connect by hostname and enter the IP address or the hostname of the computer running the J-Link Remote Server. If the J-Link 3 See https://www.segger.com/jlink-pro.html 4 See https://www.segger.com/jlink-remoteserver.html Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 151 Remote server is running on a non-standard port5 then the port also needs to be entered. If the J-Link Remote Server is running on the default port, the port can be left empty. To add a debug probe that has built-in ethernet, choose Connect by serial number in the Add target dialog, and enter the serial number of the debug probe. 6.4. Tool Info Window The Tools Info window shows information about connected tools. At the moment, only the Xplained Pro series is supported. 5 The standard port of the J-Link Remote Server is port 19020 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 152 Figure 6-6. The Tool Info Window When a tool is connected, the window will open. It has a short description about the tool, an image of the tool, and a section of links to then user guide, relevant datasheets on the internet, etc. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 153 There is also a table with technical details about the tool, such as firmware version, serial number, etc. 6.4.1. Xplained Pro Kits The Xplained Pro family of boards supports a range of expansion boards. When an Xplained Pro board is connected, the Tool Info window will show a list on the left side of the window, containing the main board, and all connected expansions. Click on the main board and the expansion to see details about the different boards. 6.4.2. Disable the Tools Info Window By deselecting the Show page on connect check box, the window will not automatically open when Atmel Studio is open and you connect the kit. This feature works on a per-tool basis, which means you can select for every tool you have, if they should show the Tool Info window when connected. 6.4.3. Manually Showing the Window If you want to see the Tool Info window again after it has been closed, you can right-click on the tool in the Available Tools view, and select Show Info Window. Figure 6-7. Show Tool Info Window See also Available Tools View. 6.5. Firmware Upgrade 6.5.1. Introduction Atmel Studio will include the latest firmware for all Atmel tools. New firmware may provide support for new devices and bugfixes. 6.5.2. Automatic Upgrade Atmel Studio will automatically upgrade the tool's firmware when needed. A potential firmware upgrade is triggered once you start using a tool. Examples: the first time you launch a debug session or the first time you select the tool in the Device Programming dialog. The tool cannot be used by Atmel Studio if the user chooses not to upgrade. You can also check for firmware upgrades by using the Available Tools view (View → Available Atmel Tools). Right click on a tool and select Upgrade. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 154 For a description on how to do manual upgrade, downgrade and upgrade with a custom firmware image, see Manual Upgrade. 6.5.3. Manual Upgrade Atmel Studio includes a command line utility called atfw.exe which can be used to do manual upgrade of most Atmel tools. atfw.exe is installed in the atbackend subfolder. atfw.exe can be used to: • Perform upgrade from a script • Upgrade using a custom firmware file • Read out firmware version For details on how to upgrade using this utility, execute atfw.exe -h. Note:  If a tool is locked in firmware upgrade mode, and normal reset does not restore normal operation, a forced firmware upgrade should reset the tool to a working state. To do a firmware upgrade on a tool already in upgrade mode, invoke atfw the same way as normal firmware upgrade. Some warnings may be displayed as the tool is unable to switch the tool to upgrade mode, but should proceed with the upgrade. If a tool listing is done, the tool will have a name that is related to the mode it is in. atfw should however be invoked with the tool name as it is presented to the user in normal operation. 6.6. Find and Replace Window You can use the Find and Replace window to search for text strings, expressions, or entity names within the code of your documents. To access this window, from the Edit menu, click Find and Replace, and then select one of the options listed. The Find and Replace window contains a toolbar with two drop-downs, one for find operations and one for replace operations. When you select an operation, the corresponding options for the operation are displayed. You can search and replace in one or more files or an entire solution for text, code, or symbols. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 155 Figure 6-8. Find and Replace Quick Find allows you to search the code of one or more open documents for a string or expression. The selection moves from match to match, allowing you to review each match in its surrounding context. Note:  The matches found are not listed in the Find Results window. You can use any of the following methods to display Quick Find in the Find and Replace window. To display Quick Find 1. On the Edit menu, expand Find and Replace. 2. Choose Quick Find. -orIf the Find and Replace window is already open, on the toolbar, click the triangular View button on the left drop-down and then choose Quick Find. Quick Find can search through a document either forward or backward from the insertion point. The search automatically continues past the end or start of the document into the unsearched portion. A message appears when the entire document has been searched. Find what These controls allow you to specify the string or expression that will be matched. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 156 Reuse one of the last 20 search strings by selecting it from this drop-down list, or type a new text string or expression to find. Table 6-1. Quick Find Option Description [string with wildcards] If you want to use wildcards such as asterisks (*) and question marks (?) in your search string, select the Use check box under Find options and then choose Wildcards. [regular expression] To instruct the search engine to expect regular expressions, select the Use check box under Find options and then choose Regular expressions. Expression Builder This triangular button next to the Find what field becomes available when the Use check box is selected in Find options and Regular Expressions appears in the drop-down list. Click this button to display a list of wildcards or regular expressions, depending upon the Use option selected. Choosing any item from this list adds it into the Find what string. Find Next Click this button to find the next instance of the Find what string within the search scope chosen in Look in. Bookmark All Click this button to display blue bookmarks at the left edge of the code editor to indicate each line where an instance of the Find what string occurs. Look in The option chosen from the Look in drop-down list determines whether Quick Find searches only in currently active files. Look in Select a predefined search scope from this list. Table 6-2. Look in Scopes Option Description Selection This option is available when text is selected in the code editor. Searches only the selected text in the currently active document. The name of this option indicates the location of the insertion point in the code editor. Searches within the current procedure, module, paragraph, or code block. Current Document This option is available when a document is open in an editor. Searches only the active document for the Find what string. Current Window This option is available when a searchable tool window, such as the View in Browser window, has focus. Searches all content displayed in this window for the Find what string. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 157 Option Description All Open Documents Searches all files currently open for editing as if they were one document. When the starting point of the search is reached in the current file, the search automatically moves to the next file and continues until the last open file has been searched for the Find what string. Current Project Searches all files in the current project as if they were one document. When the starting point of the search is reached in one file, the search continues in the next until the last file in the project has been searched. Find options You can expand or collapse the Find options section. The following options can be selected or cleared: Match case Only displays instances of the Find what string that are matched both by content and by case. For example, a search for "MyObject" with Match case selected will return "MyObject" but not "myobject" or "MYOBJECT". Match whole word Only displays instances of the Find what string that are matched in complete words. For example, a search for "MyObject" will return "MyObject" but not "CMyObject" or "MyObjectC". Search up When selected, files are searched from the insertion point to the top of the file. Search hidden text When selected, the search will also include concealed and collapsed text, such as the metadata of a design-time control; a hidden region of an outlined document; or a collapsed class or method. Use Indicates how to interpret special characters entered in the Find what or Replace with text boxes. The options include: Table 6-3. Search with Special Characters Option Description Wildcards Special characters such as asterisks (*) and question marks (?) represent one or more characters. For a list, see Wildcards (Visual Studio). Regular Expressions Special notations define patterns of text to match. For a list, see Regular Expressions (Visual Studio). Toolbar A toolbar, with two drop-downs, appears at the top of the Find and Replace window. These drop-downs allow you to choose the type of search or replace you intend to perform and changes the options displayed in the window to match. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 158 Table 6-4. Find and Replace Toolbar Drop-down View menu Find (left drop-down) Quick Find Find in Files Find Symbol Replace (right drop-down) Quick Replace Replace in Files Figure 6-9. Find Results Figure 6-10. Find Symbol Results 6.7. Export Template Wizard Atmel Studio project and item templates provide reusable and customizable project and item stubs that accelerate the development process because users do not have to create new projects and items from scratch. Note:  This functionality is inherited from Microsoft Visual Studio® and the documentation from Microsoft goes beyond what is mentioned in this section. See MSDN for in-depth information. Open the Export Template Wizard by clicking File → Export Template.... This opens the Export Template Wizard shown in the figure below. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 159 Figure 6-11. Export Template Wizard... 6.7.1. Project Template A Project template is a template that contains a whole project. This template can be redistributed to other users to ease setup of a default project. The code, which is to be template, can contain parameters that are substituted on creation. See Default Template Parameters for information on this. The template wizard is mostly self explanatory, and on completion the created template will be available in the File → File → New Project... dialog. 6.7.2. Item Template An Item template is a template that contains a single file or collection of files. The code which is to be templated can contain parameters that are substituted on creation. See Default Template Parameters for information on this. The template wizard is mostly self explanatory, and on completion the created template will be available as a file type when files are added to the project. 6.7.3. Template Parameters All templates support parameter substitution to enable replacement of key parameters, such as class names and namespaces, when the template is instantiated. These parameters are replaced by the template wizard that runs in the background when a user clicks OK in the New Project or Add New Item dialog boxes. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 160 6.7.3.1. Declaring and Enabling Template Parameters Template parameters are declared in the format $parameter$. 6.7.3.2. Default Template Parameters The table below lists the reserved template parameters that can be used by any template. Note:  Template parameters are case-sensitive. Table 6-5. Template Parameters Parameter Description $itemname$ The name provided by the user in the Add New Item dialog box $machinename$ The current computer name $projectname$ The name provided by the user in the New Project dialog box $registeredorganization$ The registry key value from HKLM\Software\Microsoft\Windows NT \CurrentVersion\RegisteredOrganization $safeitemname$ The name provided by the user in the Add New Item dialog box, with all unsafe characters and spaces removed $safeprojectname$ The name provided by the user in the New Project dialog box, with all unsafe characters and spaces removed $time$ The current time in the format DD/MM/YYYY 00:00:00 $userdomain$ The current user domain $username$ The current user name $year$ The current year in the format YYYY $guid[1-10]$ A GUID used to replace the project GUID in a project file. You can specify up to 10 unique GUIDs (for example, guid1) 6.7.3.3. Custom Template Parameters You can use the CustomParameter element in your .vstemplate file to add new parameters to a template. 1. Locate the TemplateContent element in the .vstemplate file for the template. 2. Add a CustomParameters element and one or more CustomParameter child elements as children of the TemplateContent element. Figure 6-12. Adding Custom Parameters ... 3. Use the parameter in one or more of the code files in the template as shown in Default Template Parameters. More information on this can be found on MSDN. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 161 6.8. Kit Mode Setting Some kits operate with different modes. This window can be used to change the mode. Figure 6-13. Kit Mode Settings Some examples of the choices that can be made are listed in the following table. Select mode Persistent Resulting mode Mass Storage Yes Auto, enumerating as a Mass Storage Device kit DGI Auto, enumerating as a DGI kit Mass Storage No Mass Storage, enumerating once as a Mass Storage Device kit before returning to the previous mode DGI DGI, enumerating once as a DGI kit before return to the previous mode Note:  When the persistent mode is used, the kit will reboot into Auto mode, since the persistent choice changes the kit default. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 162 7. Atmel GNU Toolchains Atmel GNU Toolchains are a set of standalone command line programs used to create applications for Atmel SAM and Atmel AVR microcontrollers. 7.1. GNU Compiler Collection (GCC) The GNU Compiler Collection is used by Atmel Studio at the build stage. The architecture specific versions of the GNU Compiler Collection supports c-code compilation, assembly and linking of C and C+ +. The AVR GNU compiler collection is distributed under the terms of the GNU General Public License, http://www.gnu.org/licenses/gpl.html. A copy of this license is also found in the installation folder of Atmel Studio . 7.2. ARM Compiler and Toolchain Options: GUI To get help about ARM GCC Toolchain, you can do the following: • For general information about GCC, visit the official GNU GCC web site • Alternatively, you can write arm-none-eabi-gcc --help and see the explanation of some of the parameters in the command output This section illustrates the GUI options that are available for the ARM GNU Toolchain in Atmel Studio. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 163 Figure 7-1. ARM GNU Toolchain Properties Table 7-1. ARM GNU Common Options Option Description Thumb(-mthumb)/Arm(-marm) Switch between Arm and Thumb processor mode Table 7-2. ARM GNU C Compiler Options Option Description Preprocessor options -nostdinc Do not search system include directories -E Preprocess only; Do not compile, Assemble or link Symbols options Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 164 Option Description There one can define (-D) or undefine (-U) a number of in-source symbols. New symbol declarations can be added, modified, or reordered, using the interface buttons below: • Add a new symbol. This and all following icons are reused with the same meaning in other parts of Atmel Studio interface. • Remove a symbol. • Edit symbol. • Move the symbol up in the parsing order. • Move the symbol down in the parsing order. Include directories Default Include Path Enabling this option will add the include path that are specific for the selected SAM device Contains all the included header and definition directories, can be modified, using the same interface as symbols Optimization options Optimization level (drop down menu): -O0, - O1, -O2, -O3, -Os No optimization, optimize for speed (level 1 - 3), optimize for size Other optimization flags (manual input form) Here you should write optimization flags specific for the platform and your requirements -ffunction-sections Place each function into its own section -funsafe-math-optimizations Enable unsafe match optimizations -ffast-math Enable fast math -fpic Generate position independent code Debug options Debug level (drop down menu): none, -g1, - g2, -g3 Specifies the level of tracing and debugging code and headers left or inserted in the source code Other debug options (form field) Architecture specific debug options Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 165 Option Description -pg Generate gprof information -p Generate prof information Warning messages output options -Wall All warnings -Werror Treat all warnings as errors -fsyntax-only Check syntax only -pedantic Check conformity to GNU, raise warnings on nonstandard programming practice -pedantic-errors Same as above, plus escalate warnings to errors -w Inhibits all warnings Miscellaneous options Other flags (form field) Input other project-specific flags -v Verbose (Display the programs invoked by the compiler) -ansi Support ANSI programs -save-temps Do not delete intermediate files Option Description Table 7-3. ARM GCC Linker Options Option Description -Wl -nostartfiles Do not use standard files -Wl -nodefault Do not use default libraries -Wl -nostdlib No start-up or default libraries -Wl -s Omit all symbol information -Wl -static Link statically -Map Generates Map file Libraries options Libraries -Wl, -l (form field) You can add, prioritize or edit library names here, using those buttons: , , , , Library search path -Wl, -L (form field) You can add, prioritize or edit path where the linker will search for dynamically linked libraries, same interface as above Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 166 Option Description Optimization options -Wl, -gc-sections Garbage collect unused sections -funsafe-math-optimizations Enable unsafe math optimizations -ffast-math Enable fast math -fpic Generate position independent code Miscellaneous options Other linker flags (form field) Input other project-specific flags Option Description Linker Scripts • In "linker->miscellaneous->linker flags" ($LinkerScript_FLASH) is added by default. It will be replaced with the appropriate (device_name)_flash.ld file during Build. Similarly ($LinkerScript_SRAM) will be replaced with the appropriate (device_name)_sram.ld file. • You can always override the default flash linker scripts by replacing ($LinkerScript_FLASH) or ($LinkerScript_SRAM) with your custom linker script option - T"custom_linker_script.ld". Note:  These device specific linker scripts will be available in the "ProjectFolder/Linkerscripts" directory. In case of changing the device after project creation, Atmel Studio will automatically add the correct linker scripts for the selected device. ARM Assembler Options Table 7-4. Arm Assembler Options Option Description Optimization options Assembler flags (form field) Miscellaneous assembler flags Include path (form field) You can add, prioritize or edit path to the architecture and platform specific included files here -v Announce version in the assembler output -W Suppress Warnings Debugging options Debugging level (drop down menu) None , (-g). Enable debugging symbols and debugging source insertion Option Description ARM Preprocessing Assembler Options Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 167 Table 7-5. ARM Preprocessing Assembler Options Option Description Optimization options Assembler flags (form field) Miscellaneous assembler flags Include path (form field) You can add, prioritize or edit path to the architecture and platform specific included files here -v Announce version in the assembler output -W Suppress Warnings Debugging options Debugging level (drop down menu) None , -Wa -g. Enables debugging symbols and debugging source insertion Option Description 7.3. ARM GNU Toolchain Options 7.3.1. ARM/GNU Common Options • Thumb(-mthumb)/Arm(-marm) Allows you to select the processor mode. 7.3.2. Compiler Options 7.3.2.1. Preprocessor • -nostdinc Do not search the standard system directories for header files. Only the directories you have specified with -I options (and the directory of the current file, if appropriate) are searched. • -E Stop after the preprocessing stage; do not run the compiler proper. The output is in the form of preprocessed source code, which is sent to the standard output. Input files which don't require preprocessing are ignored. 7.3.2.2. Symbols • -D • -D name Predefine name as a macro, with definition 1. Eg: • -D name=value Predefine name as a macro, with definition value. The contents of definition are tokenized and processed as if they appeared during translation phase three in a #define directive. In particular, the definition will be truncated by embedded newline characters. • -U Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 168 Cancel any previous definition of name, either built in or provided with a -D option. -D and -U options are processed in the order they are given on the command line. All -imacros file and - include file options are processed after all -D and -U options. 7.3.2.3. Directories • -I dir Add the directory dir to the list of directories to be searched for header files. Directories named by -I are searched before the standard system include directories. If the directory dir is a standard system include directory, the option is ignored to ensure that the default search order for system directories and the special treatment of system headers are not defeated . 7.3.2.4. Optimization • There is a general switch ‘-O’ which specifies the level of optimization used when generating the code: – -Os Signal that the generated code should be optimized for code size. The compiler will not care about the execution performance of the generated code. – -O0 No optimization. GCC will generate code that is easy to debug but slower and larger than with the incremental optimization levels outlined below. – -O1 or -O This will optimize the code for both speed and size. Most statements will be executed in the same order as in the C/C++ code and most variables can be found in the generated code. This makes the code quite suitable for debugging. This is default. – -O2 Turn on most optimizations in GCC except for some optimizations that might drastically increase code size. This also enables instruction scheduling, which allows instructions to be shuffled around to minimize CPU stall cycles because of data hazards and dependencies, for CPU architectures that might benefit from this. Overall this option makes the code quite small and fast, but hard to debug. – -O3 Turn on some extra performance optimizations that might drastically increase code size but increase performance compared to the -O2 and -O1 optimization levels. This includes performing function inlining • Other optimization options – -ffunction-sections – -fdata-sections Place each function or data item into its own section in the output file if the target supports arbitrary sections. The name of the function or the name of the data item determines the section's name in the output file. Only use these options when there are significant benefits from doing so. When you specify these options, the assembler and linker will create larger object and executable files and will also be slower. – -funroll-loops Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 169 Perform loop unrolling when iteration count is known. If code size is not a concern then some extra performance might be obtained by making gcc unroll loops by using the ‘-funroll-loops’’ switch in addition to the ‘-O3’ switch. 7.3.2.5. Debugging • -g level (Debugging level) • -g1 It produces minimal information, enough for making backtraces in parts of the program that you don't plan to debug. This includes descriptions of functions and external variables, but no information about local variables and no line numbers. • -g2 It is the default debugging level. • -g3 It includes extra information, such as all the macro definitions present in the program. Some debuggers support macro expansion when you use -g3. 7.3.2.6. Warnings • -Wall Show all warnings. • -Werror Show warnings as errors. • -fsyntax-only Check the code for syntax errors, but don't do anything beyond that. • -pedantic Issue all the warnings demanded by strict ISO C, reject all programs that use forbidden extensions, and some other programs that do not follow ISO C. Valid ISO C programs should compile properly with or without this option (though a rare few will require -ansi or a -std option specifying the required version of ISO C). However, without this option, certain GNU extensions and traditional C features are supported as well. With this option, they are rejected. • -pedantic-errors Pedantic warnings are produced as errors. • -w Inhibit all warning messages. 7.3.2.7. Miscellaneous • -v Verbose option. It prints (on standard error output) the commands executed to run the stages of compilation. Also print the version number of the compiler driver program and of the preprocessor and the compiler proper. • -ansi Support ANSI programs. This turns off certain features of GCC that are incompatible with ISO C90 (when compiling C code). For the C compiler, it disables recognition of C++ style // comments as well as the inline keyword. The -ansi option does not cause non-ISO programs to be rejected gratuitously. For that, -pedantic is required in addition to -ansi. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 170 7.3.3. Linker Options 7.3.3.1. General • -Wl,option Pass option as an option to the linker. If option contains commas, it is split into multiple options at the commas. You can use this syntax to pass an argument to the option. For example, `-Wl,- Map,output.map' passes `-Map output.map' to the linker. • -Wl, -nostartfiles Do not use the standard system startup files when linking. The standard system libraries are used normally, unless -nostdlib or -nodefaultlibs is used. • -Wl,-nodefault Do not use the standard system libraries when linking. Only the libraries you specify will be passed to the linker, options specifying linkage of the system libraries, such as -static-libgcc or - shared-libgcc, will be ignored. The standard start-up files are used normally, unless - nostartfiles is used. The compiler may generate calls to memcmp, memset, memcpy and memmove. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified. • -Wl,-nostdlib Do not use the standard system start-up files or libraries when linking. One of the standard libraries bypassed by -nostdlib and -nodefaultlibs is libgcc.a, a library of internal subroutines that GCC uses to overcome shortcomings of particular machines, or special needs for some languages. In most cases, you need libgcc.a even when you want to avoid other standard libraries. In other words, when you specify -nostdlib or -nodefaultlibs you should usually specify -lgcc as well. This ensures that you have no unresolved references to internal GCC library subroutines. • -Wl,-s Remove all symbol table and relocation information from the executable. • -Wl,-static On systems that support dynamic linking, this prevents linking with the shared libraries. On other systems, this option has no effect. • -Wl,-Map Generates Map file. 7.3.3.2. Libraries • -Wl,-llibrary Search the library named library when linking. It makes a difference where in the command you write this option; the linker searches and processes libraries and object files in the order they are specified. Thus, foo.o -lz bar.o searches library z after file foo.o but before bar.o. The linker searches a standard list of directories for the library, which is actually a file named liblibrary.a. The linker then uses this file as if it had been specified precisely by name. • -Wl, Ldir Add directory dir to the list of directories to be searched for -l. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 171 7.3.3.3. Optimization • -Wl, --gc-sections Garbage collect unused sections. Enable garbage collection of unused input sections. It is ignored on targets that do not support this option. The default behavior (of not performing this garbage collection) can be restored by specifying `--no-gc-sections' on the command line. `--gc-sections' decides which input sections are used by examining symbols and relocations. The section containing the entry symbol and all sections containing symbols undefined on the command-line will be kept, as will sections containing symbols referenced by dynamic objects. • -funsafe-math-optimizations Enable unsafe math optimizations. • -ffast-math Enable fast math • -fpic Generate position independent code. 7.3.4. Assembler Options • -I Use this option to add a path to the list of directories as searches for files specified in .include directives (see .include). You may use -I as many times as necessary to include a variety of paths. The current working directory is always searched first; after that, as searches any `-I' directories in the same order as they were specified (left to right) on the command line. • -v Announce version. • Debugging(-g) Use this option to enable the debug level. 7.3.5. Preprocessing Assembler Options • -I Use this option to add a path to the list of directories as searches for files specified in .include directives (see .include). You may use -I as many times as necessary to include a variety of paths. The current working directory is always searched first; after that, as searches any `-I' directories in the same order as they were specified (left to right) on the command line. • -v Announce version. • Debugging(Wa,-g) Use this option to enable the debug level. 7.3.6. Archiver Options • -r Replace existing or insert new file(s) into the archive. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 172 7.4. Binutils The following ARM GNU Binutils are available: • arm-none-eabi-ld - GNU linker. • arm-none-eabi-as - GNU assembler. • arm-none-eabi-addr2line - Converts addresses into filenames and line numbers. • arm-none-eabi-ar - A utility for creating, modifying and extracting from archives. • arm-none-eabi-c++filt - Filter to demangle encoded C++ symbols. • arm-none-eabi-nm - Lists symbols from object files. • arm-none-eabi-objcopy - Copies and translates object files. • arm-none-eabi-objdump - Displays information from object files. • arm-none-eabi-ranlib - Generates an index to the contents of an archive. • arm-none-eabi-readelf - Displays information from any ELF format object file. • arm-none-eabi-size - Lists the section sizes of an object or archive file. • arm-none-eabi-strings - Lists printable strings from files. • arm-none-eabi-strip - Discards symbols. For more information about each util, use the built in help command: --help. 7.5. AVR Compiler and Toolchain Options: GUI To get help about AVR GNU toolchain, you can do the following: • For information about avr32-gcc usage in Atmel Studio and general parameters consult the GCC Project Options and Configuration section • The API reference for the AVR libc implementation can be found here The API Alphabetical index can be consulted here • For general information about GCC, visit the official GNU GCC web site • Alternatively you can write avr32-gcc --help and see explanations on some of the parameters in the command output This section illustrates the GUI options that are available for the AVR GNU toolchain from the Atmel Studio frontend. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 173 Figure 7-2. AVR GNU Toolchain Options AVR GNU C Compiler Options Table 7-6. AVR GNU C Compiler Options Option Description General options -mcall-prologues Use subroutines for functions prologues and epilogues -mno-interrupts Change stack pointer without disabling interrupts -funsigned-char Default char type is unsigned -funsigned-bitfield Default bit field is unsigned Preprocessor options -nostdinc Do not search system directories -E Preprocess only Symbols options Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 174 Option Description There one can define (-D) or undefine (-U) a number of in-source symbols. New symbol declarations can be added, modified, or reordered, using the interface buttons below: • Add a new symbol. This and all following icons are reused with the same meaning in other parts of Atmel Studio interface. • Remove a symbol. • Edit symbol. • Move the symbol up in the parsing order. • Move the symbol down in the parsing order. Include directories Contains all the included header and definition directories, can be modified, using the same interface as symbols. Optimization options Optimization level (drop down menu): -O0, - O1, -O2, -O3, -Os No optimization, optimize for speed (level 1 - 3), optimize for size Other optimization flags (manual input form) Here you should write optimization flags specific for the platform and your requirements -ffunction-sections Prepare functions for garbage collection, if a function is never used, its memory will be scrapped -fpack-struct Pack structure members together -fshort-enums Allocate only as many bytes needed by the enumerated types -mshort-calls Use rjmp/rcall limited range instructions on the >8K devices Debug options Debug level (drop down menu): none, -g1, - g2, -g3 Specifies the level of tracing and debugging code and headers left or inserted in the source code Other debug options (form field) Architecture specific debug options Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 175 Option Description Warning messages output options -Wall All warnings -Werror Escalate warnings to errors -fsyntax-only Check syntax only -pedantic Check conformity to GNU, raise warnings on nonstandard programming practice -pedantic-errors Same as above, plus escalate warnings to errors Miscellaneous options Other flags (form field) Input other project-specific flags -v Verbose -ansi Support ANSI programs -save-temps Do not delete temporary files AVR GCC Linker Options Table 7-7. AVR GCC Linker Options Option Description -Wl -nostartfiles Do not use standard files -Wl -nodefault Do not use default libraries -Wl -nostdlib No start-up or default libraries -Wl -s Omit all symbol information -Wl -static Link statically Libraries options Libraries -Wl, -l (form field) You can add, prioritize or edit library names here, using those buttons: , , , , Library search path -Wl,-L (form field) You can add, prioritize or edit path where the linker will search for dynamically linked libraries, same interface as above Optimization options -Wl, -gc-sections Garbage collect unused sections --rodata-writable Put read-only data in writable spaces -mrelax Relax branches Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 176 Option Description Miscellaneous options Other linker flags (form field) Input other project-specific flags Memory Settings Displays a dialog where it is possible to configure memory segments. (Syntax for specifying segment values: =

, for example boot=0xff) The address must be given as a hexadecimal number prefixed with 0x. It is interpreted as a word address for flash memory and a byte addresse for SRAM and EEPROM memory. Figure 7-3. Memory settings Notes about the AVR port of gcc The AVR is a Harvard architecture CPU. This means that it separates instruction memory and data memory. The gcc was originally designed to support Von Neumann architectures which define a single storage structure to hold both instructions and data. This dichotomy is solved by a series of nifty tricks in the AVR port of gcc, of which three should be noted: • The .text segment starts at 0x0 • The .data segment starts at 0x800000 • The .eeprom segment starts at 0x810000 These peculiarities have been abstracted away by the GUI , but users will see the truth when building projects with relocated segments. A relocation definition for flash will be passed to the GNU linker via avr-gcc as the option: • -Wl,-section-start=bootloader=0x1fc00 Note that the address has been multiplied by 2 to get the byte address. A relocation definition for the .data section will be passed as: Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 177 • -Wl,-section-start=anewdatasegment=0x800 AVR Assembler Options Table 7-8. AVR Assembler Options Option Description Optimization options Assembler flags (form field) Miscellaneous assembler flags Include path (form field) You can add, prioritize or edit path to the architecture and platform specific included files here -v Announce version in the assembler output Debugging options Debugging (drop down menu) None, -Wa -g Enables debugging symbol and debugging source insertion 7.6. Commonly Used Options 7.6.1. Compiler Options 7.6.1.1. General • -funsigned-char Each kind of machine has a default for what char should be. It is either like unsigned char by default or like signed char by default. This option says that the default char type is unsigned. • -funsigned-bitfields These options control whether a bit-field is signed or unsigned, when the declaration does not use either signed or unsigned. This options says that the default bitfield type is unsigned. 7.6.1.2. Preprocessor • -nostdinc Do not search the standard system directories for header files. Only the directories you have specified with -I options (and the directory of the current file, if appropriate) are searched. • -E Stop after the preprocessing stage; do not run the compiler proper. The output is in the form of preprocessed source code, which is sent to the standard output. Input files which don't require preprocessing are ignored. 7.6.1.3. Symbols • -D • -D name Predefine name as a macro, with definition 1. E.g.: • -D name=value Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 178 Predefine name as a macro, with definition value. The contents of definition are tokenized and processed as if they appeared during translation phase three in a #define directive. In particular, the definition will be truncated by embedded newline characters. • -U Cancel any previous definition of name, either built in or provided with a -D option. -D and -U options are processed in the order they are given on the command line. All -imacros file and - include file options are processed after all -D and -U options. 7.6.1.4. Directories • -I dir Add the directory dir to the list of directories to be searched for header files. Directories named by -I are searched before the standard system include directories. If the directory dir is a standard system include directory, the option is ignored to ensure that the default search order for system directories and the special treatment of system headers are not defeated . 7.6.1.5. Optimization • There is a general switch ‘-O’ which specifies the level of optimization used when generating the code: – -Os Signal that the generated code should be optimized for code size. The compiler will not care about the execution performance of the generated code. – -O0 No optimization. This is the default. GCC will generate code that is easy to debug but slower and larger than with the incremental optimization levels outlined below. – -O1 or -O This will optimize the code for both speed and size. Most statements will be executed in the same order as in the C/C++ code and most variables can be found in the generated code. This makes the code quite suitable for debugging. – -O2 Turn on most optimizations in GCC except for some optimizations that might drastically increase code size. This also enables instruction scheduling, which allows instructions to be shuffled around to minimize CPU stall cycles because of data hazards and dependencies, for CPU architectures that might benefit from this. Overall this option makes the code quite small and fast, but hard to debug. – -O3 Turn on some extra performance optimizations that might drastically increase code size but increase performance compared to the -O2 and -O1 optimization levels. This includes performing function inlining • Other optimization options – -ffunction-sections – -fdata-sections Place each function or data item into its own section in the output file if the target supports arbitrary sections. The name of the function or the name of the data item determines the section's name in the output file. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 179 Only use these options when there are significant benefits from doing so. When you specify these options, the assembler and linker will create larger object and executable files and will also be slower. – -funroll-loops If code size is not a concern then some extra performance might be obtained by making gcc unroll loops by using the ‘-funroll-loops’’ switch in addition to the ‘-O3’ switch. 7.6.1.6. Debugging • -g level (Debugging level) • -g1 It produces minimal information, enough for making back-traces in parts of the program that you don't plan to debug. This includes descriptions of functions and external variables, but no information about local variables and no line numbers. • -g2 It is the default debugging level. • -g3 It includes extra information, such as all the macro definitions present in the program. Some debuggers support macro expansion when you use -g3. 7.6.1.7. Warnings • -Wall Show all warnings. • -Werror Show warnings as errors. • -fsyntax-only Check the code for syntax errors, but don't do anything beyond that. • -pedantic Issue all the warnings demanded by strict ISO C, reject all programs that use forbidden extensions, and some other programs that do not follow ISO C. Valid ISO C programs should compile properly with or without this option (though a rare few will require -ansi or a -std option specifying the required version of ISO C). However, without this option, certain GNU extensions and traditional C features are supported as well. With this option, they are rejected. • -pedantic-errors Pedantic warnings are produced as errors. • -w Inhibit all warning messages. 7.6.1.8. Miscellaneous • -v Verbose option. It prints (on standard error output) the commands executed to run the stages of compilation. Also print the version number of the compiler driver program and of the preprocessor and the compiler proper. • -ansi Support ANSI programs. This turns off certain features of GCC that are incompatible with ISO C90 (when compiling C code). For the C compiler, it disables recognition of C++ style // comments as Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 180 well as the inline keyword. The -ansi option does not cause non-ISO programs to be rejected gratuitously. For that, -pedantic is required in addition to -ansi. 7.6.2. Linker Options 7.6.2.1. General • -Wl,option Pass option as an option to the linker. If option contains commas, it is split into multiple options at the commas. You can use this syntax to pass an argument to the option. For example, `-Wl,- Map,output.map' passes `-Map output.map' to the linker. • -Wl, -nostartfiles Do not use the standard system startup files when linking. The standard system libraries are used normally, unless -nostdlib or -nodefaultlibs is used. • -Wl,-nodefault Do not use the standard system libraries when linking. Only the libraries you specify will be passed to the linker, options specifying linkage of the system libraries, such as -static-libgcc or - shared-libgcc, will be ignored. The standard start-up files are normally used, unless - nostartfiles is used. The compiler may generate calls to memcmp, memset, memcpy, and memmove. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified. • -Wl,-nostdlib Do not use the standard system start-up files or libraries when linking. One of the standard libraries bypassed by -nostdlib and -nodefaultlibs is libgcc.a, a library of internal subroutines that GCC uses to overcome shortcomings of particular machines, or special needs for some languages. In most cases, you need libgcc.a even when you want to avoid other standard libraries. In other words, when you specify -nostdlib or -nodefaultlibs you should usually specify -lgcc as well. This ensures that you have no unresolved references to internal GCC library subroutines. • -Wl,-s Remove all symbol table and relocation information from the executable. • -Wl,-static On systems that support dynamic linking, this prevents linking with the shared libraries. On other systems, this option has no effect. 7.6.2.2. Libraries • -Wl,-llibrary Search the library named library when linking. It makes a difference where in the command you write this option; the linker searches and processes libraries and object files in the order they are specified. Thus, foo.o -lz bar.o searches library z after file foo.o but before bar.o. The linker searches a standard list of directories for the library, which is actually a file named liblibrary.a. The linker then uses this file as if it had been specified precisely by name. • -Wl, Ldir Add directory dir to the list of directories to be searched for -l. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 181 7.6.2.3. Optimization • -Wl, --gc-sections Garbage collect unused sections. Enable garbage collection of unused input sections. It is ignored on targets that do not support this option. The default behavior (of not performing this garbage collection) can be restored by specifying `--no-gc-sections' on the command line. `--gc-sections' decides which input sections are used by examining symbols and relocations. The section containing the entry symbol and all sections containing symbols undefined on the command-line will be kept, as will sections containing symbols referenced by dynamic objects. • --rodata-writable Put read-only data in writable data section. 7.6.3. Assembler Options • -I Use this option to add a path to the list of directories as searches for files specified in .include directives (see .include). You may use -I as many times as necessary to include a variety of paths. The current working directory is always searched first; after that, as searches any `-I' directories in the same order as they were specified (left to right) on the command line. • -v Announce version. 7.7. 8-bit Specific AVR GCC Command Line Options This section describes the options specific to AVR 8-bit Toolchain. 7.7.1. AVR C Compiler 7.7.1.1. General • -mcall-prologues Functions prologues/epilogues are expanded as call to appropriate subroutines. Code size will be smaller. • -mno-interrupts Change the stack pointer without disabling interrupts. Generated code is not compatible with hardware interrupts. Code size will be smaller. • -mno-tablejump Do not generate table jump instructions (removed from gcc 4.5.1 coz same as -fno-jump-tables). • -msize Output instruction sizes to the asm file (removed from avr-gcc coz same as using -dp switch which prints the instruction length). 7.7.1.2. Optimization • -fpack-struct Without a value specified, pack all structure members together without holes. When a value is specified (which must be a small power of two), pack structure members according to this value, representing the maximum alignment (that is, objects with default alignment requirements larger than this will be output potentially unaligned at the next fitting location). Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 182 • -fshort-enums Allocate to an enum type only as many bytes as it needs for the declared range of possible values. Specifically, the enum type will be equivalent to the smallest integer type which has enough room. • -mshort-calls Use rjmp/rcall (limited range) on >8K devices. 7.7.1.3. Miscellaneous • -save-temps Do not delete temporary files. Store the usual "temporary" intermediate files permanently; place them in the current directory and name them based on the source file. Thus, compiling foo.c with -c -save-temps would produce files foo.i and foo.s, as well as foo.o. This creates a preprocessed foo.i output file even though the compiler now normally uses an integrated preprocessor. 7.7.2. AVR C Linker 7.7.2.1. Optimization • -mrelax Relax branches. Linker relaxing is enabled in the linker by passing the ‘—relax’ option to the linker. Using GCC as a frontend for the linker, this option is automatically passed to the linker when using ‘-O2’ or ‘-O3’ or explicitly using the ‘-mrelax’ option. When this option is used, GCC outputs pseudo instructions like lda.w, call etc. The linker can then, if the input file is tagged as relaxable, convert a pseudo instruction into the best possible instruction with regards to the final symbol address. 7.8. 32-bit Specific AVR GCC Command Line Options 7.8.1. Optimization • -mfast-float The switch, causes fast, non-ieee compliant versions of some of the optimized AVR 32-bit floatingpoint library functions to be used. This switch is by default enabled if the ‘-ffast-math’ switch is used. • -funsafe-math-optimizations Allow optimizations for floating-point arithmetic that (a) assume that arguments and results are valid and (b) may violate IEEE or ANSI standards. When used at link-time, it may include libraries or start-up files that change the default FPU control word or other similar optimizations. This option is not turned ON by any ‘-O’ option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions. It may, however, yield faster code for programs that do not require the guarantees of these specifications. Enables ‘- fno-signed-zeros’, ‘-fno-trapping-math’, ‘-fassociative-math’ and ‘-freciprocal-math’. • -ffast-math This option causes the preprocessor macro __FAST_MATH__ to be defined. This option is not turned on by any ‘-O’ option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions. It may, however, yield faster code for programs that do not require the guarantees of these specifications. It sets ‘-fnomath-errno’, ‘-funsafe-math-optimizations’, ‘-ffinite-math-only’, ‘-fno-rounding-math’, ‘-fno-signalingnans’ and ‘-fcx-limited-range’. • -fpic Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 183 Generate position-independent code (PIC) suitable for use in a shared library, if supported for the target machine. Such code accesses all constant addresses through a global offset table (GOT). The dynamic loader resolves the GOT entries when the program starts (the dynamic loader is not part of GCC; it is part of the operating system). If the GOT size for the linked executable exceeds a machine-specific maximum size, you get an error message from the linker indicating that ‘-fpic’ does not work; in that case, recompile with ‘-fPIC’ instead. (These maximums are 8k on the SPARC and 32k on the m68k and RS/6000. The 386 has no such limit.) Position-independent code requires special support, and therefore works only on certain machines. For the 386, GCC supports PIC for System V but not for the Sun 386i. Code generated for the IBM RS/6000 is always positionindependent. When this flag is set, the macros __pic__ and __PIC__ are defined to 1. • -mno-init-got Do not initialize GOT register before using it when compiling PIC code. • -masm-addr-pseudos This option is enabled by default and causes GCC to output the pseudo instructions call and lda.w for calling direct functions and loading symbol addresses respectively. It can be turned OFF by specifying the switch ‘-mno-asm-addr-pseudos’. The advantage of using these pseudo-instructions is that the linker can optimize these instructions at link time if linker relaxing is enabled. The ‘- mrelax’ option can be passed to GCC to signal to the assembler that it should generate a relaxable object file. • -mforce-double-align Force double-word alignment for double-word memory accesses. • -mimm-in-const-pool When GCC needs to move immediate values not suitable for a single move instruction into a register, it has two possible choices; it can put the constant into the code somewhere near the current instruction (the constant pool) and then use a single load instruction to load the value or it can use two immediate instruction for loading the value directly without using a memory load. If a load from the code memory is faster than executing two simple one-cycle immediate instructions, then putting these immediate values into the constant pool will be most optimal for speed. This is often true for MCU architectures implementing an instruction cache, whereas architectures with code executing from internal flash will probably need several cycles for loading values from code memory. By default GCC will use the constant pool for AVR 32-bit products with an instruction cache and two immediate instructions for flash-based MCUs. This can be overridden by using the option ‘-mimm-in-const-pool’ or its negated option ‘-mno-imm-in-const-pool’. • -muse-rodata-sections By default GCC will output read-only data into the code (.text) section. If the code memory is slow it might be more optimal for performance to put read-only data into another faster memory, if available. This can be done by specifying the switch ‘-muse-rodata-section’, which makes GCC put read-only data into the .rodata section. Then the linker file can specify where the content of the .rodata section should be placed. For systems running code from flash this might however mean that the read-only data must be placed in flash and then copied over to another memory at start-up, which means that extra memory usage is required with this scheme. 7.8.2. Debugging • -pg Generate extra code to write profile information suitable for the analysis program gprof. You must use this option when compiling the source files you want data about, and you must also use it when linking. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 184 • -p Generate extra code to write profile information suitable for the analysis program prof. You must use this option when compiling the source files you want data about, and you must also use it when linking. 7.8.3. AVR32 C Linker 7.8.3.1. Optimization • -mfast-float Enable fast floating-point library. Enabled by default if the -funsafe-math-optimizations switch is specified. • -funsafe-math-optimizations Allow optimizations for floating-point arithmetic that (a) assume that arguments and results are valid and (b) may violate IEEE or ANSI standards. When used at link-time, it may include libraries or start-up files that change the default FPU control word or other similar optimizations. This option is not turned on by any ‘-O’ option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions. It may, however, yield faster code for programs that do not require the guarantees of these specifications. Enables ‘- fno-signed-zeros’, ‘-fno-trapping-math’, ‘-fassociative-math’, and ‘-freciprocal-math’. The default is ‘- fno-unsafe-math-optimizations’. • -ffast-math This option causes the preprocessor macro __FAST_MATH__ to be defined. This option is not turned on by any ‘-O’ option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions. It may, however, yield faster code for programs that do not require the guarantees of these specifications. It sets ‘-fnomath-errno’, ‘-funsafe-math-optimizations’, ‘-ffinite-math-only’, ‘-fno-rounding-math’, ‘-fno-signalingnans’, and ‘-fcx-limited-range’. • -fpic Generate position-independent code (PIC) suitable for use in a shared library, if supported for the target machine. Such code accesses all constant addresses through a global offset table (GOT). The dynamic loader resolves the GOT entries when the program starts (the dynamic loader is not part of GCC; it is part of the operating system). If the GOT size for the linked executable exceeds a machine-specific maximum size, you get an error message from the linker indicating that ‘-fpic’ does not work; in that case, recompile with ‘-fPIC’ instead. (These maximums are 8k on the SPARC and 32k on the m68k and RS/6000. The 386 has no such limit.) Position-independent code requires special support, and therefore works only on certain machines. For the 386, GCC supports PIC for System V but not for the Sun 386i. Code generated for the IBM RS/6000 is always positionindependent. When this flag is set, the macros __pic__ and __PIC__ are defined to 1. • -Wl,--direct-data Allow direct data references when optimizing. To enable the linker to convert an lda.w into an immediate move instruction, i.e. linker relaxing, the option ‘—direct-data’ must be given to the linker. 7.8.3.2. Miscellaneous • -Xlinker[option] Pass option as an option to the linker. You can use this to supply system-specific linker options which GCC does not know how to recognize. If you want to pass an option that takes a separate argument, you must use -Xlinker twice, once for the option and once for the argument. For example, to pass -assert definitions, you must write `-Xlinker -assert -Xlinker definitions'. It does not Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 185 work to write -Xlinker "-assert definitions", because this passes the entire string as a single argument, which is not what the linker expects. When using the GNU linker, it is usually more convenient to pass arguments to linker options using the option=value syntax than as separate arguments. For example, you can specify `-Xlinker -Map=output.map' rather than `-Xlinker -Map - Xlinker output.map'. Other linkers may not support this syntax for command-line options. 7.9. Binutils The following AVR 32-bit GNU Binutils are available: • avr32-ld- GNU linker. • avr32-as - GNU assembler. • avr32-addr2line - Converts addresses into file-names and line numbers. • avr32-ar - A utility for creating, modifying and extracting from archives. • avr32-c++filt - Filter to demangle encoded C++ symbols. • avr32-nm - Lists symbols from object files. • avr32-objcopy - Copies and translates object files. • avr32-objdump - Displays information from object files. • avr32-ranlib - Generates an index to the contents of an archive. • avr32-readelf - Displays information from any ELF format object file. • avr32-size - Lists the section sizes of an object or archive file. • avr32-strings - Lists printable strings from files. • avr32-strip - Discards symbols. For more information about each util, use the built in help command: avr32- -- help. • For general information about GNU Assembler (GAS), GNU linker and other binutils, visit the official GNU Binutils web site. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 186 8. Extending Atmel Studio Atmel Studio includes a tool named Extension Manager that lets you add, remove, enable, and disable Atmel Studio extensions. To open Extension Manager, on the Tools menu, click Extension Manager. Extension developers are advised to uninstall previous versions of extensions in progress, and uninstall or disable potentially conflicting extensions to prevent conflicts during development. 8.1. Extension Manager UI The Extension Manager window is divided into three panes. The left pane lets you select by group: installed extensions and new extensions from the online gallery. Figure 8-1. Extension Manager The extensions are displayed in the middle pane. You can sort the list by name or author from the combobox above the list. When you select an extension in the middle pane, information about it appears in the right pane. Extension installed by the current user can be uninstalled or disabled, extensions distributed with Atmel Studio cannot be changed. The Extension Manager window also includes a search box. Depending on the selection in the left pane, you can search installed extensions, the online gallery, or available updates. Online Gallery Extension Manager can install extensions from the Atmel Studio Gallery. These extensions may be packages, templates, or other components that add functionality to Atmel Studio. To get started with the extension manager check the Installing New Extensions in Atmel Studio. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 187 Extension Types Extension Manager supports extensions in the VSIX package format, which may include project templates, item templates, toolbox items, Managed Extension Framework (MEF) components, and VSPackages. Extension Manager can also download and install MSI-based extensions, but it cannot enable or disable them. Atmel Studio Gallery contains both VSIX and MSI extensions. Dependency Handling If a user tries to install an extension that has dependencies, the installer verifies that those dependencies are already installed. If they are not installed, Extension Manager shows the user a list of dependencies that must be installed before the extension can be installed. Installing Without Using Extension Manager Extensions that have been packaged in .vsix files may be available in locations other than the Atmel Studio Gallery. Extension Manager cannot detect these files. However, you can install a .vsix file by double-clicking it and then following the setup instructions. When the extension is installed, you can use Extension Manager to enable it, disable it, or remove it. 8.2. Registering at Atmel Extension Gallery In order to download extensions, registering at the Atmel Extension Gallery is required. The first time Updates are accessed or a download is invoked, this login screen is displayed: Figure 8-2. Extension Manager Registration Follow the instructions on the screen. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 188 8.3. Installing New Extensions in Atmel Studio Step 1 Figure 8-3. Extension Manager Opening the extension manager window will show extensions installed. In order to find and install a new extension, click the Available Downloads tab on the left pane. Step 2 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 189 Figure 8-4. Retrieving List of Extensions Updating the available extension list will take some time. Step 3 Figure 8-5. List of Extensions Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 190 A green check mark identifies already installed extensions. Select QTouch Composer and press Download. If you have not previously registered as a user in the Extension Gallery you will be taken to the Registering at Atmel Extension Gallery at this point. . Figure 8-6. Extension Download Progression Download will start as indicated in the status bar of Atmel Studio. If the extension is distributed as a standalone installer you will be asked for location to save the file. Downloading can take several minutes for large files. A dialog with a running bar is displayed during download. Not that download can take a long time for large extensions. Press Cancel to abort the download. Step 4 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 191 Figure 8-7. Extension License A license agreement will appear for you to read, most of the times, when you install a new extension. Read it carefully and install only the extensions you really need as most of the extensions' authors do not take liability in a possible malfunction resulting from installation of mutually incompatible extensions and collateral damages, for example if extension security is breached. Step 5 Once the extension is downloaded a message in the lower status bar will appear. Figure 8-8. Extension Manager Restart Warning Click the Restart Now button to restart the IDE immediately, otherwise if you plan to restart it later - click the Close button. If you have an unsaved project you will be requested to save the changes you made, before restarting. Step 6 Figure 8-9. QTouch Composer Button After restarting Atmel Studio, a new button is added for starting QTouch Composer. 8.4. Visual Assist The Atmel Studio comes with a preinstalled extension - the Visual Assist from WholeTomato Software. The documentation on Visual Assist is available from several sources: • Go to the www.wholetomato.com. Click in the left hand menu to browse documentation by feature. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 192 Figure 8-10. WholeTomato Software Documentation • Jump directly to relevant documentation using hyperlinks in the Visual Assist options dialog Figure 8-11. Visual Assist Options • Click terms in the Glossary 8.5. Overview of QTouch Composer and Library The Atmel QTouch Composer and library allows you to easily and seamlessly develop capacitive touch functionality for your application. This simplifies the design process by tying together the tools required to edit the code in Atmel Studio and tune the touch design. QTouch Composer, formerly called QTouch Studio, is fully integrated in Atmel Studio 6 as an extension. QTouch Library is a software framework extension to Atmel studio, which allows you to add touch functionality on various Atmel devices. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 193 8.5.1. Installation 1. Start Atmel Studio. 2. Go to Tools → Extension Manager → Online Gallery. 3. Select QTouch Library and click “Download” and then install it. 4. Select QTouch Composer and click “Download” and then install it. 5. Click “Restart Now” button in the Extension manager window. 6. After starting Atmel Studio, go to Tools → Extension Manager. Check QTouch library and QTouch composer are listed and status is enabled. 8.5.2. Overview of QTouch Project Builder QTouch Project builder will guide you through all steps from selecting device and touch sensors to automatically generate a complete touch project. 1. Start Atmel Studio. 2. Open the File menu. Click on "New → Project". 3. The “New Project” dialog is opened. Select “GCC C QTouch Executable Project” in the New Project dialog. Enter the following details in the “New Project” dialog and click on the button OK. – Name of the project – Location of the project and solution – Name of the solution Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 194 4. The “QTouch Project Builder” wizard is opened, which will guide through the steps involved in creating a project. Sample QTouch Project creation video here. 8.5.3. Overview of QTouch Analyzer QTouch Analyzer reads and interprets touch data sent from QTouch kit into different views. The Analyzer is separated into Kit View, Kit/Sensor Properties, Sensor Data, Trace View, Power View, and Graph view. When touch kit is connected and Atmel Studio is opened, QTouch Analyzer window opens up and connection information is updated. The Virtual Kit view shows touch events such as button press, wheel, and slider use. The image is updated based on the touch data read from the connected Touch Kit. The Kit/Sensor Properties view allows you to view and modify the kit/sensor configuration options. The Sensor Data View provides touch data information of the currently connected kit. The Graph View displays one or more selected touch data's on a graph. Graph shall display most recent touch data. The data set to show can be selected from the data set list at the right side of the view. The datasets are displayed in tabbed pages representing the Signals, Deltas, References, and Wheel/Slider positions. Each data set selection list follows normal selection convention; click on an item in the list to selected that one item. To select a continuous range of items first click on first item then hold down the SHIFT key and select the last item in the range. Multiple items can also be selected one at a time by holding down the CTRL key prior to selecting the next item in the list. In the last case the items need not be in a continuous range. Using CTRL select method also allows deselection of individual items from a selection of multiple items. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 195 The Trace contains one or more data series with touch data in a chart. The trace keeps all historical data of one single reading session (pressing start and stop reading), and the data can be saved in a separate file and opened again later. 8.6. Scripting Extensions Atmel Studio provides some scripting hooks that can be executed automatically by the IDE. These extensions are mainly written in Python, and will execute for instance when a breakpoint is hit, when an expression is evaluated or when the program is being reset. 8.6.1. Debug Scripting The debug scripting interface is function based and depends on certain, named functions to be defined in a Python® file. The function will then be called when the corresponding event is occurring inside Atmel Studio. Attention:  Error checking is kept at a minimum for the functions exported into the Python environment so that the time used on initialization during normal sessions are kept low. This means that there are many ways to crash Atmel Studio through this interface. To load a Python file, place a file named debughooks.py in the Debug folder of your project, next to the ELF file, or one folder up where the project file is. It is also possible to place this file inside the Atmel Studio installation directory to make the script load for all projects. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 196 Note:  The Python file is loaded and compiled when a project is launched, so changes to the Python file during a debug session will not be active until the next debug session is started. The Python file is running in an IronPython context, with full access to .NET and a Python 2.7 runtime. See http:// ironpython.net/documentation/dotnet/ for more information of the runtime. The functions that Atmel Studio will try to load is shown below with its function signature. def should_process_breakpoint(studio_interface, breakpoint_address, breakpoint_id, obj): """ Called to determine if a breakpoint should cause Atmel Studio to enter debug mode. If this function returns False, Atmel Studio will not break at the breakpoint. """ return True def has_processed_breakpoint(studio_interface, breakpoint_address, breakpoint_id, obj): """ This function is called if Atmel Studio is breaking at a breakpoint. The GUI is now in halted mode. """ pass def on_reset(studio_interface, reset_address): """ This function is called when the target is reset. The address where the reset went to is 'reset_address'. """ pass def on_eval_expr(studio_interface, expression): """ This function is called for each expression that is evaluated in Atmel Studio. This includes the watch window and other windows that show data from the target. Pass the 'expression' string through to evaluate it, or return another expression to be evaluated to override the expression. This override is not visible in the Atmel Studio GUI. """ return expression Note:  Atmel Studio expects all these functions to be available if the script has been found and is loaded correctly. If for instance the should_process_breakpoint is undefined, breakpoints might start to misbehave as the return value of a undefined function is in itself undefined. In the code shown above, the main interface back into the Atmel Studio is the studio_interface object. This object contains some functions to show messages and do target interaction. The Print function in the studio_interface object is used to show text in the output window inside Atmel Studio. The function takes two arguments, the string to print and the name of the tab in the output window. The example below prints all evaluated expression to the “Expressions” tab. def on_eval_expr(studio_interface, expression): studio_interface.Print("Evaluating {}".format(expression), "Expressions") return expression Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 197 Note:  The severity level of text sent through Print is set to INFO, which means that the output may be masked by Atmel Studio. To lower the threshold, go to Tools > Tools, select Status Management, and set the Display Threshold to INFO. The ExecStmt function in the studio_interface object is used to execute statements in the debugger. This can for instance be used to set variables. See MSDN Debugger.ExecuteStatement Method for more information. The WriteMemory and ReadMemory are symmetric functions for reading and writing memory on the target. It is important to use a System.Array[System.Byte] object to pass the data between the script and Atmel Studio. import System def should_process_breakpoint(studio_interface, breakpoint_address, breakpoint_id, obj): vals = System.Array[System.Byte]([1, 2, 3, 4, 5, 6, 7, 8, 9]) studio_interface.WriteMemory(data=vals, adr=0, type="eeprom") ret = studio_interface.ReadMemory(adr=0, type="eeprom", count=9) studio_interface.Print("ret == vals => {!r}".format(ret == vals), "Python") return True The CalcNumericValue is a shorthand for the CalcValue call. It will return the numeric value of the symbol or the provided default value if the function fails to retrieve the value of the symbol. def should_process_breakpoint(studio_interface, breakpoint_address, breakpoint_id, obj): a = studio_interface.CalcNumericValue("a", 0) if a == 0: studio_interface.Print("a was 0 or default", "Value scripts") else: studio_interface.Print("a = {}".format(a), "Value scripts") return True The CalcValue function is used to retrieve information about a symbol in the scope where the target code is running. The return value of this call is a list of information, containing the address of the symbol, symbol information and value. The objects sent in this list contains all known information about a symbol, but the most useful field is the last element which contains the value of the evaluated symbol. def should_process_breakpoint(studio_interface, breakpoint_address, breakpoint_id, obj): a = studio_interface.CalcValue("a") # a now contains all information about the variable a. # It is a list with the following members: # a = [ # , # , # , # '1' ] <-- This is the value of the symbol as a string, here it had the value 1 studio_interface.Print("Value of a = {}".format(a[3]), "Value Scripts") return True Note:  The different objects returned by the CalcValue call contains objects that are either internal, or documented in the Atmel Studio SDK. Use the python dir() command to look at the fields that are exported. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 198 9. Menus and Settings 9.1. Customizing Existing Menus and Toolbars You can add or remove commands on any menu or toolbar, or change the order and grouping of those commands. You can also add toolbars, and change the layout, position, and content of existing toolbars in the integrated development environment (IDE). To add a command to a menu or toolbar 1. On the Tools menu, click Customize. 2. In the Customize dialog box, on the Commands tab, under Choose a menu or tool bar to rearrange, select the menu or tool bar you want to change and then click Add command. 3. In the Add Command dialog box, select a category name on the Categories list and then, on the Commands list, select the command you want to add. 4. Click OK. 5. Click Close. To remove a command from a menu or toolbar 1. On the Tools menu, click Customize. 2. In the Customize dialog box, on the Commands tab, under Choose a menu or toolbar to rearrange, select the menu or toolbar you want to change. 3. Select the command you want to remove, and then click Delete. 4. Click Close. To separate commands on a menu or toolbar 1. On the Tools menu, click Customize. 2. In the Customize dialog box, on the Commands tab, under Choose a menu or toolbar to rearrange, select the menu or toolbar you want to change. 3. Select the command you want to separate from the commands above it. 4. In the Modify Selection list, select Begin a Group. 5. A separator bar appears on the list of commands, above the selected command. 6. Click OK. 7. Click Close. The command appears on the menu or toolbar with a separator before it. To add a new menu 1. On the Tools menu, click Customize. 2. In the Customize dialog box, on the Commands tab, click Add New Menu. The menu appears, named New Menu. 3. In the Modify Selection list, enter the name for the new menu. 4. Click OK. 5. Click Close. The command appears on the menu or toolbar before it. To change the order of menus 1. On the Tools menu, click Customize. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 199 2. In the Customize dialog box, on the Commands tab, under Choose a menu or toolbar to rearrange, select the menu or toolbar you want to move. 3. Select Move Up or Move Down to move the command. 4. Click OK. 5. Click Close. The command appears on the menu or toolbar with a separator before it. To create a toolbar 1. On the Tools menu, click Customize. 2. In the Customize dialog box, on the Toolbars tab, click New. 3. In the New Toolbar dialog box, type a name for the toolbar. 4. Use the steps described earlier in this topic to add commands to the toolbar. Changing Toolbar Layout You can arrange toolbars by dragging them in the main docking area, or by using the Customize dialog box to move them to other docking areas. To arrange toolbars in the main docking area 1. Drag a toolbar by its left edge to move it where you want it. 2. Surrounding toolbars will be automatically rearranged. 3. To change the docking location of a toolbar. 4. On the Tools menu, click Customize. 5. In the Customize dialog box, on the Toolbars tab, on the Modify Selection list, select a dock location. 6. Click Close. For more information about how to improve the usability and accessibility of toolbars, see How to: Set Accessibility Options. Resetting the Main Menu and Shortcut Menus If you change the locations of commands or change command icons, you can reset them to their original configurations. To reset a menu or toolbar 1. On the Tools menu, click Customize. 2. In the Customize dialog box, on the Commands tab, under Choose a menu or toolbar to rearrange, select the menu or toolbar you want to reset. 3. Click Reset all. The selected menu bar, toolbar, or context menu returns to its original configuration. 9.2. Reset Your Settings You can reset the integrated development environment (IDE) to a previous state using the Import and Export Settings wizard. All settings and categories are applied by default; if you want to specify which settings to change, use the option Import selected environment settings. To reset your settings 1. On the Tools menu, click Import and Export Settings. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 200 2. On the Welcome to the Import and Export Settings Wizard page, click Reset all settings, and then click Next. 3. If you want to save your current settings combination, click Yes, save my current settings, specify a file name, and then click Next. —or— If you want to delete your current settings combination, choose No, just reset settings, overwriting my current settings, and then click Next. This option does not delete default settings, which will still be available the next time you use the wizard. 4. In Which collection of settings do you want to reset to, select a settings collection from the list. 5. Click Finish. The Reset Complete page alerts you to any problems encountered during the reset. 9.3. Options Dialog Box The Options dialog box enables you to configure the integrated development environment (IDE) to your needs. For example, you can establish a default save location for your projects, alter the default appearance and behavior of windows, and create shortcuts for commonly used commands. There are also options specific to your development language and platform. You can access Options from the Tools menu. Note:  The options available in dialog boxes, and the names and locations of menu commands you see, might differ from what is described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. Layout of the Options dialog box The Options dialog box is divided into two parts: a navigation pane on the left and a display area on the right. The tree control in the navigation pane includes folder nodes, such as Environment, Text Editor, Projects and Solutions, and Source Control. Expand any folder node to list the pages of options that it contains. When you select the node for a particular page, its options appear in the display area. Options for an IDE feature do not appear in the navigation pane until the feature is loaded into memory. Therefore, the same options might not be displayed as you begin a new session that were displayed as you ended the last. When you create a project or run a command that uses a particular application, nodes for relevant options are added to the Options dialog box. These added options will then remain available as long as the IDE feature remains in memory. Note:  Some settings collections scope the number of pages that appear in the navigation pane of the Options dialog box. You can choose to view all possible pages by selecting Show all settings. How options are applied Clicking OK in the Options dialog box saves all settings on all pages. Clicking on Cancel any page cancels all change requests, including any just made on other Options pages. Some changes to option settings, such as those made on Fonts and Colors, Environment, Options Dialog Box, will only take effect after you close and reopen Atmel Studio. 9.3.1. Environment Options The pages in the Environment folder in the Options dialog box let you set how certain elements of the integrated development environment (IDE) display and behave. You can access the Environment pages by clicking Options on the Tools menu, and then clicking Environment. 9.3.1.1. General Environment Settings Items shown in Window menu Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 201 Customizes the number of windows that appear in the Windows list of the Window menu. Type a number between 1 and 24. By default, the number is 10. Items shown in recently used lists Customizes the number of most recently used projects and files that appear on the File menu. Type a number between 1 and 24. By default, the number is 10. This is an easy way to retrieve recently used projects and files. Automatically adjust visual experience based on client performance Specifies whether Atmel Studio sets the adjustment to the visual experience automatically or you set the adjustment explicitly. This adjustment may change the display of colors from gradients to flat colors, or it may restrict the use of animations in menus or pop-up windows. Enable rich client experience Enables the full visual experience of Atmel Studio, including gradients and animations. Clear this option when using Remote Desktop connections or older graphics adapters, because these features may have poor performance in those cases. This option is available only when you clear the Automatically adjust visual experience based on client option. Use hardware graphics acceleration if available Uses hardware graphics acceleration if it is available, rather than software acceleration. Show status bar Displays the status bar. The status bar is located at the bottom of the IDE window and displays information about the progress of ongoing operations. Close button affects active tool window only Specifies that when the Close button is clicked, only the tool window that has focus is closed and not all of the tool windows in the docked set. By default, this option is selected. Auto Hide button affects active tool window only Specifies that when the Auto Hide button is clicked, only the tool window that has focus is hidden automatically and not all of the tool windows in the docked set. By default, this option is not selected. Restore File Associations Registers file types that are typically associated with Atmel Studio. Registration causes Windows to display the correct icons in Windows Explorer, and to recognize Atmel Studio as the correct application for opening these file types. This option can be useful if you have two different versions of Atmel Studio installed on the same computer, and you later uninstall one of the versions. After uninstalling, the icons for Atmel Studio files no longer appear in Windows Explorer. In addition, Windows no longer recognizes Atmel Studio as the default application for editing these files. This option restores those associations. 9.3.1.2. Add-in/Macros Security Add-in Security Settings To enhance security by preventing malicious add-ins from automatically activating, Atmel Studio provides settings in a Tools Options page named Add-in/Macros Security. In addition, this options page allows you to specify the folders in which Atmel Studio searches for .Addin registration files. This enhances security by allowing you to limit the locations where .Addin registration files can be read, helping prevent malicious .Addin files from inadvertently being used. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 202 The settings in the Add-in/Macros Security, Environment, and Options Dialog Box that relate to add-in security are: • Allow add-in components to load. Checked by default. When checked, add-ins are allowed to load in Atmel Studio. When unchecked, add-ins are prohibited from loading in Atmel Studio. • Allow add-in components to load from a URL. Unchecked by default. When checked, add-ins are allowed to be loaded from external Web sites. When unchecked, remote add-ins are prohibited from loading in Atmel Studio. If an add-in cannot load for some reason, then it cannot be loaded from the web. This setting controls only the loading of the add-in DLL. The .Addin registration files must always be located on the local system. Default .Add-In File Search Locations In addition to the security settings, the options page has a list containing folders in which to search for .Addin registration files. By default, the following tokens are included: • %ALLUSERSDOCUMENTS% • %ALLUSERSPROFILE% • %APPDATA% • %VSAPPDATA% • %VSCOMMONAPPDATA% • %VSMYDOCUMENTS% When Atmel Studio begins searching for .AddIn files, it replaces these tokens with the following path strings: Table 9-1. AddIn Files Search Path Tokens Token Path %ALLUSERSDOCUMENTS% %PUBLIC%\Documents %ALLUSERSPROFILE% %ALLUSERSPROFILE% (defined by OS) %APPDATA% %USERPROFILE%\AppData %VSAPPDATA% %USERPROFILE%\AppData\Roaming\Microsoft\AVR Studio 5\ --OR-- %USERPROFILE%\AppData\Local\Microsoft\Atmel Studio 6\ %VSCOMMONAPPDATA% %ProgramData%\Microsoft\Atmel Studio 6\ %VSMYDOCUMENTS% \Atmel Studio 6 Note:  Some of the default paths may resolve to targets that do not exist on your system. You can remove these predefined tokens from the list by highlighting the token and clicking Remove. To add other folders to the search list, click Add and specify a folder in the Browse for Folder dialog box. For more information, see Add-In Registration. 9.3.1.3. AutoRecover Use this page of the Options dialog box to specify whether or not files are automatically backed up. This page also allows you to specify whether or not modified files are restored when the integrated development environment (IDE) shuts down unexpectedly. You can access this dialog box by selecting Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 203 the Tools menu and choosing Options, and then selecting the Environment folder and choosing the AutoRecover page. If this page does not appear in the list, select Show all settings in the Options dialog box. Save AutoRecover information every minutes Use this option to customize how often a file is automatically saved in the editor. For previously saved files, a copy of the file is saved in \...\My Documents\Atmel Studio 6.2\Backup Files \. If the file is new and has not been manually saved, the file is auto-saved using a randomly generated file name. Keep AutoRecover information for days Use this option to specify how long Atmel Studio keeps files created for auto recovery. 9.3.1.4. Find and Replace Use this page of the Options dialog box to control message boxes and other aspects of a find and replace operation. You can access this dialog box from the Tools menu by clicking Options, expanding Environment, and then clicking Find and Replace. If this page does not appear in the list, select Show all settings in the Options dialog box. Display informational messages Select this option to display all Find and Replace informational messages that have the Always show this message option. For example, if you chose not to display the message "Find reached the starting point of the search.", selecting this option would cause this informational message to appear again when you use Find and Replace. If you do not want to see any informational messages for Find and Replace, clear this option. When you have cleared the Always show this message option on some, but not all, Find and Replace informational messages, the Display informational messages check box appears to be filled but not selected. To restore all optional Find and Replace messages, clear this option and then select it again. Note:  This option does not affect any Find and Replace informational messages that do not display the Always show this message option. Display warning messages Select this option to display all cautionary Find and Replace messages that have the Always show this message option. For example, if you chose not to display the Replace All warning message that appears when you attempt to make replacements in files not currently opened for editing, selecting this option would cause this warning message to appear again when you attempt to Replace All. If you do not want to see any cautionary messages for Find and Replace, clear this option. When you have cleared the Always show this message option on some, but not all, Find and Replace warning messages, the Display warning messages check box appears to be filled but not selected. To restore all optional Find and Replace messages, clear this option and then select it again. Note:  This option does not affect any Find and Replace warning messages that do not display the Always show this message option. Automatically populate Find What with text from the editor Select this option to paste the text on either side of the current editor's insertion point into the Find what field when you select any view of the Find and Replace Window window from the Edit menu. Clear this option to use the last search pattern from the previous search as the Find what string. Hide Find and Replace window after a match is located for Quick Find or Quick Replace Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 204 Select this option to automatically close the Find and Replace window when the first match is found for Quick Find. To go to the next match, use the shortcut key for Edit.FindNext, usually F3, or display the Find and Replace window again. 9.3.1.5. Fonts and Colors The Fonts and Colors page of the Options dialog box lets you establish a custom font and color scheme for various user interface elements in the integrated development environment (IDE). You can access this dialog box by clicking Options on the Tools menu, and then selecting the Fonts and Colors page in the Environment folder. If this page does not appear in the list, select Show all settings in the Options dialog box. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Color scheme changes do not take effect during the session in which you make them. You can evaluate color changes by opening another instance of Atmel Studio and producing the conditions under which you expect your changes to apply. Show settings for Lists all of the user interface elements for which you can change font and color schemes. After selecting an item from this list you can customize color settings for the item selected in Display items. Text Editor Changes to font style, size, and color display settings for Text Editor affect the appearance of text in your default text editor. Documents opened in a text editor outside the IDE will not be affected by these settings. For information about changing your default text editor, see How to: Change or Add a Default Editor. Printer Changes to font style, size, and color display settings for Printer affect the appearance of text in printed documents. Note:  As needed, you can select a different default font for printing than that used for display in the text editor. This can be useful when printing code that contains both single-byte and double-byte characters. Statement Completion Changes the font style and size for the text that appears in statement completion pop-up in the editor. Editor Tool tip Changes the font style and size for the text that appears in ToolTips displayed in the editor. Environment Font Changes the font style and size for all IDE user interface elements that do not already have a separate option in Show settings for. For example, this option applies to the Start Page but would not affect the Output window. [All Text Tool Windows] Changes to font style, size, and color display settings for this item affect the appearance of text in tool windows that have output panes in the IDE. For example, Output window, Command window, Immediate window, etc. Note:  Changes to the text of [All Text Tool Windows] items do not take effect during the session in which you make them. You can evaluate such changes by opening another instance of Atmel Studio. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 205 Use Defaults/Use Resets the font and color values of the list item selected in Show settings for. The Use button appears when other display schemes are available for selection. For example, you can choose from two schemes for the Printer. Font (bold type indicates fixed-width fonts) Lists all the fonts installed on your system. When the drop-down menu first appears, the current font for the element selected in the Show settings for field is highlighted. Fixed fonts — which are easier to align in the editor — appear in bold. Size Lists available point sizes for the highlighted font. Changing the size of the font affects all Display items for the Show settings for selection. Display items Lists the items for which you can modify the foreground and background color. Note:  PlainText is the default display item. As such, properties assigned to PlainText will be overridden by properties assigned to other display items. For example, if you assign the color blue to PlainText and the color green to Identifier, all identifiers will appear in green. In this example, Identifier properties override PlainText properties. Some of display items include: Display items Description. Plain Text Text in the editor. Selected Text Text that is included in the current selection when the editor has focus. Inactive Selected Text Text that is included in the current selection when the editor has lost focus. Indicator Margin The margin at the left of the Code Editor where breakpoints and bookmark icons are displayed. Line Numbers Optional numbers that appear next to each line of code. Visible White Space Spaces, tabs and word wrap indicators. Bookmark Lines that have bookmarks. Bookmark is visible only if the indicator margin is disabled. Brace Matching (Highlight) Highlighting that is typically bold formatting for matching braces. Brace Matching (Rectangle) Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 206 Highlighting that is typically a grey rectangle in the background. Breakpoint (Enabled) Specifies the highlight color for statements or lines containing simple breakpoints. This option is applicable only if statement-level breakpoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Breakpoint (Error) Specifies the highlight color for statements or lines containing breakpoints that are in an error state. Applicable only if statement-level breakpoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Breakpoint (Warning) Specifies the highlight color for statements or lines containing breakpoints that are in a warning state. Applicable only if statement-level breakpoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Breakpoint - Advanced (Disabled) Specifies the highlight color for statements or lines containing disabled conditional or hit-counted breakpoints. Applicable only if statement-level breakpoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Breakpoint - Advanced (Enabled) Specifies the highlight color for statements or lines containing conditional or hit-counted breakpoints. Applicable only if statement-level breakpoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Breakpoint - Advanced (Error) Specifies the highlight color for statements or lines containing conditional or hit-counted breakpoints that are in an error state. Applicable only if statement-level breakpoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Breakpoint - Advanced (Warning) Specifies the highlight color for statements or lines containing conditional or hit-counted breakpoints that are in a warning state. Applicable only if statement-level breakpoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Code Snippet Dependent Field A field that will be updated when the current editable field is modified. Code Snippet Field Editable Field when a code snippet is active. Collapsible Text A block of text or code that can be toggled in and out of view within the Code Editor. Comment Code comments. Compiler Error Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 207 Blue squiggles in the editor indicating a compiler error. Coverage Not Touched Area Code that has not been covered by a unit test. Coverage Partially Touched Area Code that has been partially covered by a unit test. Coverage Touched Area Code that has been completely covered by a unit test. Current list location Current line navigated to in a list tool window, such as the Output window or Find Results windows. Current Statement Specifies the highlight color for the source statement or line that indicates the current step position when debugging. Debugger Data Changed The color of text used to display changed data inside the Registers and Memory windows. Definition Window Background The background color of the Code Definition window. Definition Window Current Match The current definition in the Code Definition window. Disassembly File Name The color of text used to display file name breaks inside the Disassembly window. Disassembly Source The color of text used to display source lines inside the Disassembly window. Disassembly Symbol The color of text used to display symbol names inside the Disassembly window. Disassembly Text The color of text used to display op-code and data inside the Disassembly window. Excluded Code that is not to be compiled, per a conditional preprocessor directive such as #if. Identifier Identifiers in code such as the class names, methods names, and variable names. Keyword Keywords for the given language that are reserved. For example: class and namespace. Memory Address The color of text used to display the address column inside the Memory window. Memory Changed The color of text used to display changed data inside the Memory window. Memory Data The color of text used to display data inside the Memory window. Memory Unreadable The color of text used to display unreadable memory areas within the Memory window. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 208 Number A number in code that represents an actual numeric value. Operators such as +, -, and !=. Other Error Other error types not covered by other error squiggles. Currently, this includes rude edits in Edit and Continue. Preprocessor Keyword Keywords used by the preprocessor such as #include. Read-Only Region Code that cannot be edited. For example code displayed in the Code Definition View window or code that cannot be modified during Edit and Continue. Register Data The color of text used to display data inside the Registers window. Register NAT The color of text used to display unrecognized data and objects inside the Registers window. Stale Code Superseded code awaiting an update. In some cases, Edit and Continue cannot apply code changes immediately, but will apply them later as you continue debugging. This occurs if you edit a function that must call the function currently executing, or if you add more than 64 bytes of new variables to a function waiting on the call stack. When this happens, the debugger displays a "Stale Code Warning" dialog box, and the superseded code continues to execute until the function in question finishes and is called again. Edit and Continue applies the code changes at that time. String String literals. Syntax Error Parse errors. Task List Shortcut. If a Task List shortcut is added to a line, and the indicator margin is disabled, the line will be highlighted. Tracepoint (Enabled) Specifies the highlight color for statements or lines containing simple tracepoints. This option is applicable only if statement-level tracepoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Tracepoint (Error) Specifies the highlight color for statements or lines containing tracepoints that are in an error state. This option is applicable only if statement-level tracepoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Tracepoint (Warning) Specifies the highlight color for statements or lines containing tracepoints that are in a warning state. This option is applicable only if statement-level tracepoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Tracepoint - Advanced (Disabled) Specifies the highlight color for statements or lines containing disabled conditional or hit-counted tracepoints. This option is applicable only if statement-level tracepoints are active or the Highlight entire Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 209 source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Tracepoint - Advanced (Enabled) Specifies the highlight color for statements or lines containing conditional or hit-counted tracepoints. This option is applicable only if statement-level tracepoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Tracepoint - Advanced (Error) Specifies the highlight color for statements or lines containing conditional or hit-counted tracepoints that are in an error state. This option is applicable only if statement-level tracepoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Tracepoint - Advanced (Warning) Specifies the highlight color for statements or lines containing conditional or hit-counted tracepoints that are in a warning state. This option is applicable only if statement-level tracepoints are active or the Highlight entire source line for breakpoints or current statement option is selected on General, Debugging, Options Dialog Box. Track Changes after save Lines of code that have been modified since the file was opened but are saved to disk. Track Changes before save Lines of code that have been modified since the file was opened but are not saved to disk. User Types Types defined by users. User Types (Delegates) Type color for delegates. User Types (Enums) Type color used for enums. User Types (Interfaces) Type color for interfaces. User Types (Value types) Type color for value types such as structs in C. Warning Compiler warnings. Warning Lines Path Used for Static Analysis warning lines. XML Attribute Attribute names. XML Attribute Quotes The quote characters for XML attributes. XML Attribute Value Contents of XML attributes. XML Cdata Section Contents of . Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 210 XML Comment The contents of . XML Delimiter XML Syntax delimiters, including <, , ?>, , and [, ]. XML Doc Attribute The value of an XML documentation attribute, such as where the "I" is colorized. XML Doc Comment The comments enclosed in the XML documentation comments. XML Doc Tag The tags in XML documentation comments, such as /// . XML Keyword DTD keywords such as CDATA, IDREF, and NDATA. XML Name Element Names and Processing Instructions target name. XML Processing Instruction Contents of Processing Instructions, not including target name. XML Text Plain Text element content. XSLT Keyword XSLT element names. Item foreground Lists the available colors you can choose for the foreground of the item selected in Display items. Because some items are related, and should therefore maintain a consistent display scheme, changing the foreground color of the text also changes the defaults for elements such as Compiler Error, Keyword, or Operator. Automatic Items can inherit the foreground color from other display items such as Plain Text. Using this option, when you change the color of an inherited display item, the color of the related display items also change automatically. For example, if you selected the Automatic value for Compiler Error and later changed the color of Plain Text to Red, the Compiler Error would also automatically inherit the color Red. Default the color that appears for the item the first time you start AVR Studio 5. Clicking the Use Defaults button resets to this color. Custom Displays the Color dialog box to allow you to set a custom color for the item selected in the Display items list. Note:  Your ability to define custom colors may be limited by the color settings for your computer display. For example, if your computer is set to display 256 colors and you select a custom color from the Color dialog box, the IDE defaults to the closest available Basic color and displays the color black in the Color preview box. Item background Provides a color palette from which you can choose a background color for the item selected in Display items. Because some items are related, and should therefore maintain a consistent display scheme, changing the background color of text also changes the defaults for elements such as Compiler Error, Keyword, or Operator. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 211 Automatic Items can inherit the background color from other display items such as Plain Text. Using this option, when you change the color of an inherited display item, the color of the related display items also change automatically. For example, if you selected the Automatic value for Compiler Error and later changed the color of Plain Text to Red, Compiler Error would also automatically inherit the color Red. Clicking the Use Defaults button resets to this color. Custom Displays the Color dialog box to allow you to set a custom color for the item selected in the Display items list. Bold Select this option to display the text of selected Display items in bold text. Bold text is easier to identify in the editor. Sample Displays a sample of the font style, size, and color scheme for the Show settings for and Display items selected. You can use this box to preview the results as you experiment with different formatting options. 9.3.1.6. Language and International Settings The International Settings page allows you to change the default language when you have more than one language version of the integrated development environment (IDE) installed on your machine. You can access this dialog box by selecting Options from the Tools menu and then choosing International Settings from the Environment folder. If this page does not appear in the list, select Show all settings in the Options dialog box. Any changes you make on this page apply only to the default IDE and do not take effect until the environment is restarted. Language Lists the available languages for the installed product language versions. This option is unavailable unless you have more than one language version installed on your machine. If multiple languages of products or a mixed language installation of products share the environment, the language selection is changed to Same as Microsoft Windows. Caution:  In a system with multiple languages installed, the build tools are not affected by this setting. These tools use the version for last language installed and the tools for the previously installed language are overwritten because the build tools do not use the satellite DLL model. 9.3.1.7. Keyboard Settings The shortcut key combinations in the scheme currently applied, (Default), depend on the settings you have selected as well as any customizations you might have made. For more information about the shortcut keys associated with a settings combination, see Working with Settings. Visual Studio also includes seven other keyboard mapping schemes, each of which differs from the others in the shortcut key combinations assigned by default to various UI elements. For a list of these combinations, organized by mapping scheme, see Pre-defined Keyboard Shortcuts. Commands with shortcut key combinations that are part of the Global scope can be superseded by commands in other scopes depending on the current context of the integrated development environment (IDE). For example, if you are editing a file, commands that are part of the Text Editor scope have precedence over commands in the Global scope that start with the same key combination. For example, if several Global commands have key combinations that start with CTRL + K and the Text Editor also has several commands with key combinations that start with CTRL + K, when you are editing code the Text Editor key combinations will work and the Global key combinations will be ignored. Note:  The options available in dialog boxes, and the names and locations of menu commands you see, might differ from what is described in Help depending on your active settings or edition. This Help page Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 212 was written with General Development Settings in mind. To change your settings, from the Tools menu, choose Import and Export Settings. For more information, see Working with Settings. Determine the Shortcut Key Assigned to a Command You can manually search for a command to determine whether or not it has an assigned shortcut key combination. To determine the shortcut key combination for a command 1. On the Tools menu, click Options. 2. Expand the Environment folder and select Keyboard. Note:  If you do not see the Keyboard page, check Show all settings located in the lower left of the Options dialog box. In the Show commands containing box, enter the name of the command without spaces. For example, solutionexplorer. 3. In the list, select the correct command. For example, View.SolutionExplorer. 4. If a shortcut key combination exists for the command, the combination appears in the Shortcut(s) for selected command drop-down list. Create Custom Shortcut Keys You can create new shortcut key combinations for any command or change the shortcut key combination for commands with existing combinations. To create a new shortcut key combination 1. On the Tools menu, click Options. 2. Expand the Environment folder, and select Keyboard. Note:  If you do not see the Keyboard page, check Show all settings located in the lower left corner of the Options dialog box. In the Show commands containing box, enter the name of the command without spaces. For example, solutionexplorer. 3. In the list, select the command you want to assign to a shortcut key combination. 4. On the Use new shortcut in drop-down list, select the feature area in which you want to use the shortcut. For example, you can choose Global if you want the shortcut to work in all contexts. Unless the same shortcut is mapped (as Global) in another editor, you can use it. Otherwise, the editor overrides the shortcut. Note:  The following keys cannot be assigned to a command in Global: PRINT SCRN/SYS RQ, SCROLL LOCK, PAUSE/BREAK, TAB, CAPS LOCK, INSERT, HOME, END, PAGE UP, PAGE DOWN, Windows logo keys, Application key, any of the ARROW keys, or ENTER; NUM LOCK, DEL, or CLEAR on the numeric keypad; or CTRL+ALT+DELETE. 5. Place the cursor in the Press shortcut key(s) box, and then use the keyboard to enter the key combination you intend to use for the command. Note:  Shortcuts can contain the SHIFT, ALT, and/or CTRL keys in combination with letters. Be sure to check the Shortcut currently used by box to see if the key combination is already assigned to another command in the mapping scheme. Press BACKSPACE to delete the key combination, if the combination is already in use, before trying another combination. 6. Click Assign. Note:  Changes made by using the Assign button are not canceled if you click the Cancel button. Exporting and Importing Shortcut Keys Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 213 You can share the shortcut key combinations in the current keyboard mapping scheme by exporting the information to a file so others can import the data. To export shortcut keys only 1. On the Tools menu, choose Import and Export Settings Wizard. 2. Select Export select environment settings and then click Next. 3. Under What settings do you want to export?, clear all categories selected by default. 4. Expand Options and then expand Environment. 5. Select Keyboard and then click Next. 6. For What do you want to name your settings file?, enter a name and then click Finish. To import only shortcut keys 1. On the Tools menu, click Import and Export Settings Wizard. 2. Select Import select environment settings and then click Next. 3. Click No, just import new settings, overwriting my current settings and then click Next. 4. Under My Settings, select the settings file that contains the shortcut keys you want to import, or click Browse to locate the correct settings file. 5. Click Next. 6. Under Which settings do you want to import?, clear all categories. 7. Expand Options and then expand Environment. 8. Select Keyboard and then click Finish. 9.3.1.8. Start-up Page — to Change the Default UI Displayed when You Start Atmel Studio 1. On the Tools menu, chose Options. 2. Expand Environment and then chose Startup. 3. From the At startup drop-down list, chose one of the options. For more information, see Startup, Environment, Options Dialog Box. 4. Click OK. Your changes take affect the next time you start Atmel Studio. Use this page to specify what content or user interface (UI), if any, is displayed when you start Atmel Studio. To access this page, on the Tools menu, click Options, expand Environment, and then click Startup. If this page does not appear in the list in the Options dialog box, select Show all settings. Note:  The options available in dialog boxes, and the names and locations of menu commands you see, might differ from what is described in Help depending on your active settings or edition. This Help page was written with General Development settings in mind. To change your settings, on the Tools menu, click Import and Export Settings. At start-up You can specify what you want to view every time you start AVR Studio 5. Open Home Page Displays the default Web page specified by the Home page option in Web Browser, Environment, Options Dialog Box. Load last loaded solution Loads the last saved solution in its previous state. Any files that were open in the solution when it was last closed are opened and displayed when you start Atmel Studio. If no solution is loaded when you exit the product, no solution is loaded when you return. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 214 Show Open Project dialog box Displays the Open Project dialog box when you start Atmel Studio. The dialog box uses the folder set in the Atmel Studio Projects location field of the Projects and Solutions, Environment, Options Dialog Box. Show New Project dialog box Displays the New Project dialog box when you open Atmel Studio. Show empty environment Displays an empty integrated development environment (IDE) when you start Atmel Studio. Show Start Page Displays the Start Page associated with the settings that you have currently applied when you start Atmel Studio. Start Page news channel Specifies the RSS feed used to display content in the Atmel Studio News section of the Start Page. Download content every n minutes Specifies how often the IDE checks for new RSS feed content and product headlines for the Start Page. If this setting is not selected, RSS feed content and product headlines are not downloaded to the Start Page. Customize Start Page If you have custom Start Pages installed, you can specify which Start Page to load. The Customize Start Page drop-down list includes an (Default Start Page) entry to load the default Atmel Studio Start Page, and an entry for each custom Start Page on your system. Any .XAML file in your user start pages directory is considered a custom start page. For more information, see Custom Start Pages. 9.3.1.9. Import and Export Settings Use this page of the Options dialog box to set preferences for saving settings files as well as specifying whether or not to use team settings files stored on a server. You can access this dialog box by selecting Options from the Tools menu and choosing the Import and Export Settings page from the Environment folder. Tip:  If this page does not appear in the list, select Show all setting in the Options dialog box. Note:  The options available in dialog boxes, and the names and locations of menu commands you see, might differ from what is described in Help depending on your active settings or edition. This Help page was written with General Development Settings in mind. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Automatically load and save settings Automatically save my settings to this file: Displays the location and name of the .vssettings file you are currently using. When you close the IDE, any changes you have made, such as moving windows or changing option selections, are saved to the current file. The next time you start the IDE, your settings are loaded. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 215 Team settings Use team settings file: When selected, allows you to navigate to a shared .vssettings file by using the Browse button. This settings file is automatically re-applied each time Atmel Studio detects if a newer version is available. Note:  The location of the team settings file must be specified as a UNC path or local path. URLs and other protocols are not supported paths. 9.3.1.10. Task List This Options page allows you to add, delete, and change the comment tokens that generate Task List reminders. To display these settings, select Options from the Tools menu, expand the Environment folder, and choose Task List. Confirm deletion of tasks When selected, a message box is displayed whenever a User Task is deleted from the Task List, allowing you to confirm the deletion. This option is selected by default. Note:  To delete a Task Comment, use the link to find the comment, and then remove it from your code. Hide full file paths When selected, the File column of the Task List displays only the names of files to be edited, not their full paths. Tokens When you insert a comment into your code whose text begins with a token from the Token List, the Task List displays your comment as new entry whenever the file is opened for editing. You can click this Task List entry to jump directly to the comment line in your code. For more information, see How to: Create Task List Comments. Token List Displays a list of tokens, and allows you to add or remove custom tokens. Comment tokens are case sensitive. Note:  If you do not type the desired token exactly as it appears in the Token List, a comment task will not be displayed in the Task List. Priority Sets the priority of tasks that use the selected token. Task comments that begin with this token are automatically assigned the designated priority in the Task List. Name Enter the token string. This enables the Add button. On Add, this string is included in the Token List, and comments that begin with this name will be displayed in the Task List. Add Enabled when you enter a new Name. Click to add a new token string using the values entered in the Name and Priority fields. Delete Click to delete the selected token from the Token List. You cannot delete the default comment token. Change Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 216 Click to make changes to an existing token using the values entered in the Name and Priority fields. Note:  You cannot rename or delete the default comment token, but you can change its priority level. 9.3.1.11. Web Browser Options Sets options for both the internal Web browser and Internet Explorer. To access this dialog box, click Options on the Tools menu, expand the Environment folder, and select Web Browser. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Attention:  Opening certain files or components from the Web can execute code on your computer. For more information, see Code Access Security. Home page Sets the page displayed when you open the Integrated Development Environment Web Browser. Search page Lets you designate a Search page for the internal Web browser. This location can differ from the search page used by instances of Internet Explorer initiated outside of the integrated development environment (IDE). View Source in Sets the editor used to open a Web page when you choose View Source on the page from the internal Web browser. Source editor Select to view source in the Code and Text Editor. HTML editor Select to view source in the HTML Designer. Use this selection to edit the Web page in one of two views: Design view or the standard text-based Source view. External editor Select to view source in another editor. Specify the path of any editor you choose, for example, Notepad.exe. Internet Explorer Options Click to change options for Internet Explorer in the Internet Properties dialog box. Changes made in this dialog box affect both the internal Web browser and instances of Internet Explorer initiated outside of the Atmel Studio IDE (for example, from the Start menu). 9.3.1.12. Custom Start Pages The Atmel Studio Start Page is a Windows Presentation Foundation (WPF) Extensible Application Markup Language (XAML) page that runs in an Atmel Studio tool window. The Start Page tool window can run Atmel Studio internal commands. When Atmel Studio starts, it opens the current default Start Page. If you have installed a third-party Start Page, you can set that page as the default by using the Options dialog box. Installing and Applying a Custom Start Page Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 217 You can install custom Start Pages by using the Online Gallery section of Extension Manager. You can also install directly from a Web site or local intranet page by locating and opening a .vsix file that contains a custom Start Page, or by copying the Start Page files and pasting them into in the Documents\Atmel Studio\StartPages\ folder on your computer. You can apply a custom Start Page by selecting it in the Options dialog box. Start pages installed by Extension Manager will appear in the Customize Start Page list as [InstalledExtension] Extension Name. Start pages dropped into the \StartPages folder will include a partial file path in the list entry, as shown in the following example. Documents\Atmel Studio 6\StartPages\StartPage.xaml To apply a custom Start Page 1. On the Tools menu, click Options. 2. On the left side of the Options dialog box, expand the Environment node, and then click Startup. 3. In the Customize Start Page list, select the Start Page you want. 4. This list includes every .xaml file in your user Start Pages folder and any installed extensions of type StartPage. 5. Click OK. Troubleshooting It is possible for an error in a third-party Start Page to cause Atmel Studio to crash. If this happens, you can start Atmel Studio in safe mode by adding the /SafeMode switch to the application, i.e. avrstudio5.exe /SafeMode. This prevents the bad Start Page from loading. You can then return to the Options dialog box and reset Atmel Studio to use the default Start Page. 9.3.2. Project Options 9.3.2.1. General Settings Sets the default path of Atmel Studio project folders, and determines the default behavior of the Output window, Task List, and Solution Explorer as projects are developed and built. To access this dialog box, on the Tools menu, click Options, expand Projects and Solutions, and click General. Note:  The options are available in the dialog boxes, and the names and locations of menu commands you see, might differ from what is described in Help depending on your active settings or edition. This Help page was written with the General Development settings in mind. To view or change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Projects location Sets the default location where new projects and solution folders and directories are created. Several dialog boxes also use the location set in this option for folder starting points. For example, the Open Project dialog box uses this location for the My Projects shortcut. User project templates location Sets the default location that is used by the New Project dialog box to create the list of My Templates. For more information, see How to: Locate and Organize Project and Item Templates. User item templates location Sets the default location that is used by the Add New Item dialog box to create the list of My Templates. For more information, see How to: Locate and Organize Project and Item Templates. Always show Error List if build finishes with errors Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 218 Opens the Error List window on build completion, only if a project failed to build. Errors that occur during the build process are displayed. When this option is cleared, the errors still occur but the window does not open when the build is complete. This option is enabled by default. Track Active Item in Solution Explorer When selected, Solution Explorer automatically opens and the active item is selected. The selected item changes as you work with different files in a project or solution, or different components in a designer. When this option is cleared, the selection in Solution Explorer does not change automatically. This option is enabled by default. Show advanced build configurations When selected, the build configuration options appear on the Project Property Pages dialog box and the Solution Property Pages dialog box. When cleared, the build configuration options do not appear on the Project Property Pages dialog box and the Solution Property Pages dialog box for projects that contain one configuration or the two configurations debug and release. If a project has a user-defined configuration, the build configuration options are shown. When deselected, the commands on the Build menu, such as Build Solution, Rebuild Solution, and Clean Solution, are performed on the Release configuration and the commands on the Debug menu, such as Start Debugging and Start Without Debugging, are performed on the Debug configuration. Always show solution When selected, the solution and all commands that act on solutions are always shown in the IDE. When cleared, all projects are created as standalone projects and you do not see the solution in Solution Explorer or commands that act on solutions in the IDE if the solution contains only one project. Save new projects when created When selected, you can specify a location for your project in the New Project dialog box. When cleared, all new projects are created as temporary projects. When you are working with temporary projects, you can create and experiment with a project without having to specify a disk location. Warn user when the project location is not trusted If you attempt to create a new project or open an existing project in a location that is not fully trusted (for example, on a UNC path or an HTTP path), a message is displayed. Use this option to specify whether the message is displayed each time that you attempt to create or open a project in a location that is not fully trusted. Show Output window when build starts Automatically displays the Output Window in the IDE at the outset of solution builds. For more information, see How to: Control the Output Window. This option is enabled by default. Prompt for symbolic renaming when renaming files When selected, displays a message box asking whether or not AVR Studio 5 should also rename all references in the project to the code element. 9.3.2.2. Build and Run Options Determines whether changed files are automatically saved when a project or its solution is built, the maximum number of Visual C++ projects that can build at the same time, and certain default behavior on Run. To access this dialog box, on the Tools menu, click Options, click Projects and Solutions, and then click Build and Run. Save all changes Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 219 Automatically saves changes to the solution file and all project files that were changed since the last build when you press F5, or click Start on the Debug menu or Build on the Build menu. No prompt is given. Items are saved with their current names. By default, this option is enabled. Save changes to open documents only Automatically saves changes to all open documents when you press F5, or click Start on the Debug menu or Build on the Build menu. No prompt is given. Prompt to save all changes When selected, displays a dialog box that asks whether you want to save changes to the solution and project items when you press F5 or click Start on the Debug menu or Build on the Build menu. The Save As dialog box is displayed so that you can assign a name and location to your project. If this option is not selected, the project runs by using the memory image that contains your changes, but the changes are not saved. Don't save any changes When you run your project, the integrated development environment (IDE) runs the code version in the open documents and does not save changes to open documents. Maximum number of parallel project builds Specifies the maximum number of projects that can build at the same time. To optimize the build process, the maximum number of parallel project builds is automatically set to the number of CPUs of your computer. The maximum is 32. For more information, see Multiprocessor Builds. Only build start-up projects and dependencies on Run When selected, pressing F5 or clicking Start on the Debug menu or Build on the Build menu only builds the start-up project and its dependencies. When this option is cleared, pressing F5 builds all projects, dependencies, and solution files. By default, this option is cleared. Always build The message box is not displayed and the out of date project configuration is built. This option is set when you select Do not show this dialog again in the message, and then click Yes. Never build The message box is not displayed and the out of date project configuration is not built. This option is set when you select Do not show this dialog again in the message, and then click No. Prompt to build Displays the message box every time that a project configuration is out of date. Prompt to launch Displays the message box every time that build errors occur. Do not launch The message box is not displayed and the application is not started. This option is set when you select Do not show this dialog again in the message box, and then click No. Launch old version The message box is not displayed and the newly built version of the application is not started. This option is set when you select Do not show this dialog again in the message box, and then click Yes. For new solutions use the currently selected project as the start-up project Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 220 If selected, new solutions use the currently selected project as the start-up project. MSBuild project build output verbosity Sets the verbosity level for the build output. For more information, see the /verbosity switch in MSBuild Command Line Reference. MSBuild project build log file verbosity Sets the verbosity level for the build log file. For more information, see the /verbosity switch in MSBuild Command Line Reference. 9.3.3. Source Control If you have plugins for source control (SVN, ClearCase, Vault, Git, etc.) installed, you should select it from the drop-down list in this section, to activate and use your plugin with the source repository. 9.3.4. Text Editor Options 9.3.4.1. General Settings This dialog box lets you change global settings for the Visual Studio Code and Text Editor. To display this dialog box, click Options on the Tools menu, expand the Text Editor folder, and then click General. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Settings Drag and drop text editing When selected, this enables you to move text by selecting and dragging the text with the mouse to another location within the current document or any other open document. Automatic delimiter highlighting When selected, delimiter characters that separate parameters or item-value pairs, as well as matching braces, are highlighted. Track changes When selected, the code editor's selection margin displays a vertical yellow line to mark code recently changed, and vertical green lines next to unchanged code. Auto-detect UTF-8 encoding without signature By default, the editor detects encoding by searching for byte order marks or charset tags. If neither is found in the current document, the code editor attempts to auto-detect UTF-8 encoding by scanning byte sequences. To disable the auto-detection of encoding, clear this option. Display Selection margin When selected, a vertical margin along the left edge of the editor's text area is displayed. You can click this margin to select an entire line of text, or click and drag to select consecutive lines of text. Selection Margin on / Selection Margin off Indicator margin When selected, a vertical margin outside the left edge of the editor's text area is displayed. When you click in this margin, an icon and ToolTip that are related to the text appear. For example, breakpoint or task list shortcuts appear in the indicator margin. Indicator Margin information does not print. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 221 Vertical scroll bar When selected, a vertical scrollbar which allows you to scroll up and down to view elements that fall outside the viewing area of the Editor is displayed. If vertical scrollbars are not available, you can use the Page Up, Page Down, and cursor keys to scroll. Horizontal scroll bar When selected, a horizontal scrollbar which allows you to scroll from side-to-side to view elements that fall outside the viewing area of the Editor is displayed. If horizontal scrollbars are unavailable, you can use the cursor keys to scroll. 9.3.4.2. File Extensions and Associations There you can specify tool association of the source file extensions. 9.3.4.3. General Language Options This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To open this dialog box, select Options from the Tools menu. Within the Text Editor folder, expand the All Languages sub folder and then select General. Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the General options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the sub folder for that language and select its option pages. A grayed checkmark is displayed when an option has been selected on the General options pages for some programming languages, but not for others. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Statement Completion Auto list members When selected, pop-up lists of available members, properties, values, or methods are displayed by IntelliSense as you type in the editor. Choose any item from the pop-up list to insert the item into your code. Selecting this option enables the Hide advanced members option. For more information, see List Members. Hide advanced members When selected, shortens pop-up statement completion lists by displaying only those items most commonly used. Other items are filtered from the list. Parameter information When selected, the complete syntax for the current declaration or procedure is displayed under the insertion point in the editor, with all of its available parameters. The next parameter you can assign is displayed in bold. For more information, see Parameter Info. Settings Enable virtual space Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 222 When this option is selected and Word wrap is cleared, you can click anywhere beyond the end of a line in the Code Editor, and type. This feature can be used to position comments at a consistent point next to your code. Word wrap When selected, any portion of a line that extends horizontally beyond the viewable editor area is automatically displayed on the next line. Selecting this option enables the Show visual glyphs for word wrap option. Note:  The Virtual Space feature is turned off while Word Wrap is on. Show visual glyphs for word wrap When selected, a return-arrow indicator is displayed where a long line wraps onto a second line. Clear this option if you prefer not to display these indicators. Note:  These reminder arrows are not added to your code, and do not print. They are for reference only. Apply Cut or Copy commands to blank lines when there is no selection This option sets the behavior of the editor when you place the insertion point on a blank line, select nothing, and then Copy or Cut. When this option is selected, the blank line is copied or cut. If you then Paste, a new and blank line is inserted. When this option is cleared, the Cut command removes blank lines. However, the data on the Clipboard is preserved. Therefore, if you then use the Paste command, the content most recently copied onto the Clipboard is pasted. If nothing has been copied previously, nothing is pasted. This setting has no effect on Copy or Cut when a line is not blank. If nothing is selected, the entire line is copied or cut. If you then Paste, the text of the entire line and its endline character are pasted. Tip:  To display indicators for spaces, tabs, and line ends, and thus distinguish indented lines from lines that are entirely blank, select Advanced from the Edit menu and choose View White Space. Display Line numbers When selected, a line number appears next to each line of code. Note:  These line numbers are not added to your code, and do not print. They are for reference only. Enable single-click URL navigation When selected, the mouse cursor changes to a pointing hand as it passes over a URL in the editor. You can click the URL to display the indicated page in your Web browser. Navigation bar When selected, the Navigation bar at the top of the code editor is displayed. Its drop-down Objects and Members lists allow you to choose a particular object in your code, select from its members, and navigates to the declaration of the selected member in the Code Editor. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 223 9.3.4.4. Tabs Dialog This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To display these options, select Options from the Tools menu. Within the Text Editor folder expand the All Languages sub folder, and then choose Tabs. Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the Tabs options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the sub folder for that language and select its option pages. If different settings are selected on the Tabs options pages for particular programming languages, then the message "The indentation settings for individual text formats conflict with each other," is displayed for differing Indenting options; and the message "The tab settings for individual text formats conflict with each other," is displayed for differing Tab options. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Indenting None When selected, new lines are not indented. The insertion point is placed in the first column of a new line. Block When selected, new lines are automatically indented. The insertion point is placed at the same starting point as the preceding line. Smart When selected, new lines are positioned to fit the code context, per other code formatting settings and IntelliSense conventions for your development language. This option is not available for all development languages. For example, lines enclosed between an opening brace ( { ) and a closing brace ( } ) might automatically be indented an extra tab stop from the position of the aligned braces. Tab and indent size Sets the distance in spaces between tab stops and for automatic indentation. The default is four spaces. Tab characters, space characters, or both will be inserted to fill the specified size. Insert spaces When selected, indent operations insert only space characters, not TAB characters. If the Tab and Indent size is set to 5, for example, then five space characters are inserted whenever you press the TAB key or the Increase Indent button on the Formatting toolbar. Keep tabs When selected, each indent operation inserts one TAB character. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 224 9.3.4.5. AVR Assembler Language-specific Settings General Language Options This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To open this dialog box, select Options from the Tools menu. Within the Text Editor folder, expand the All Languages sub folder and then choose General. Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the General options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the sub folder for that language and select its option pages. A grayed checkmark is displayed when an option has been selected on the General options pages for some programming languages, but not for others. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Statement Completion Auto list members When selected, pop-up lists of available members, properties, values, or methods are displayed by IntelliSense as you type in the editor. Choose any item from the pop-up list to insert the item into your code. Selecting this option enables the Hide advanced members option. For more information, see List Members. Hide advanced members When selected it shortens the pop-up statement completion lists by displaying only those items most commonly used. Other items are filtered from the list. Parameter information When selected, the complete syntax for the current declaration or procedure is displayed under the insertion point in the editor, with all of its available parameters. The next parameter you can assign is displayed in bold. For more information, see Parameter Info. Settings Enable virtual space When this option is selected and Word wrap is cleared, you can click anywhere beyond the end of a line in the Code Editor and type. This feature can be used to position comments at a consistent point next to your code. Word wrap When selected, any portion of a line that extends horizontally beyond the viewable editor area is automatically displayed on the next line. Selecting this option enables the Show visual glyphs for word wrap option. Note:  The Virtual Space feature is turned off while Word Wrap is on. Show visual glyphs for word wrap Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 225 When selected, a return-arrow indicator is displayed where a long line wraps onto a second line. Clear this option if you prefer not to display these indicators. Note:  These reminder arrows are not added to your code, and do not print. They are for reference only. Apply Cut or Copy commands to blank lines when there is no selection This option sets the behavior of the editor when you place the insertion point on a blank line, select nothing, and then Copy or Cut. When this option is selected, the blank line is copied or cut. If you then Paste, a new, blank line is inserted. When this option is cleared, the Cut command removes blank lines. However, the data on the Clipboard is preserved. Therefore, if you then use the Paste command, the content most recently copied onto the Clipboard is pasted. If nothing has been copied previously, nothing is pasted. This setting has no effect on Copy or Cut when a line is not blank. If nothing is selected, the entire line is copied or cut. If you then Paste, the text of the entire line and its endline character are pasted. Tip:  To display indicators for spaces, tabs, and line ends, and thus distinguish indented lines from lines that are entirely blank, select Advanced from the Edit menu and choose View White Space. Display Line numbers When selected, a line number appears next to each line of code. Note:  These line numbers are not added to your code, and do not print. They are for reference only. Enable single-click URL navigation When selected, the mouse cursor changes to a pointing hand as it passes over a URL in the editor. You can click the URL to display the indicated page in your Web browser. Navigation bar When selected, displays the Navigation bar at the top of the code editor. Its dropdown Objects and Members lists allow you to choose a particular object in your code, select from its members, and navigates to the declaration of the selected member in the Code Editor. Tabs Dialog This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To display these options, select Options from the Tools menu. Within the Text Editor folder expand the All Languages sub folder, and then choose Tabs. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 226 Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the Tabs options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the sub folder for that language and select its option pages. If different settings are selected on the Tabs options pages for particular programming languages, then the message "The indentation settings for individual text formats conflict with each other," is displayed for differing Indenting options; and the message "The tab settings for individual text formats conflict with each other," is displayed for differing Tab options. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Indenting None When selected, new lines are not indented. The insertion point is placed in the first column of a new line. Block When selected, new lines are automatically indented. The insertion point is placed at the same starting point as the preceding line. Smart When selected, new lines are positioned to fit the code context, per other code formatting settings and IntelliSense conventions for your development language. This option is not available for all development languages. For example, lines enclosed between an opening brace ( { ) and a closing brace ( } ) might automatically be indented an extra tab stop from the position of the aligned braces. Tab and indent size Sets the distance in spaces between tab stops and for automatic indentation. The default is four spaces. Tab characters, space characters, or both will be inserted to fill the specified size. Insert spaces When selected, indent operations insert only space characters, not TAB characters. If the Tab and Indent size is set to 5, for example, then five space characters are inserted whenever you press the TAB key or the Increase Indent button on the Formatting toolbar. Keep tabs When selected, each indent operation inserts one TAB character. 9.3.4.6. AVR GCC Language-specific Settings General Language Options This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To open this dialog box, select Options from the Tools menu. Within the Text Editor folder, expand the All Languages sub folder and then choose General. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 227 Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the General options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the sub folder for that language and select its option pages. A grayed checkmark is displayed when an option has been selected on the General options pages for some programming languages, but not for others. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Statement Completion Auto list members When selected, pop-up lists of available members, properties, values, or methods are displayed by IntelliSense as you type in the editor. Choose any item from the pop-up list to insert the item into your code. Selecting this option enables the Hide advanced members option. For more information, see List Members. Hide advanced members When selected it shortens the pop-up statement completion lists by displaying only those items most commonly used. Other items are filtered from the list. Parameter information When selected, the complete syntax for the current declaration or procedure is displayed under the insertion point in the editor, with all of its available parameters. The next parameter you can assign is displayed in bold. For more information, see Parameter Info. Settings Enable virtual space When this option is selected and Word wrap is cleared, you can click anywhere beyond the end of a line in the Code Editor and type. This feature can be used to position comments at a consistent point next to your code. Word wrap When selected, any portion of a line that extends horizontally beyond the viewable editor area is automatically displayed on the next line. Selecting this option enables the Show visual glyphs for word wrap option. Note:  The Virtual Space feature is turned off while Word Wrap is on. Show visual glyphs for word wrap When selected, a return-arrow indicator is displayed where a long line wraps onto a second line. Clear this option if you prefer not to display these indicators. Note:  These reminder arrows are not added to your code, and do not print. They are for reference only. Apply Cut or Copy commands to blank lines when there is no selection Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 228 This option sets the behavior of the editor when you place the insertion point on a blank line, select nothing, and then Copy or Cut. When this option is selected, the blank line is copied or cut. If you then Paste, a new, blank line is inserted. When this option is cleared, the Cut command removes blank lines. However, the data on the Clipboard is preserved. Therefore, if you then use the Paste command, the content most recently copied onto the Clipboard is pasted. If nothing has been copied previously, nothing is pasted. This setting has no effect on Copy or Cut when a line is not blank. If nothing is selected, the entire line is copied or cut. If you then Paste, the text of the entire line and its endline character are pasted. Tip:  To display indicators for spaces, tabs, and line ends, and thus distinguish indented lines from lines that are entirely blank, select Advanced from the Edit menu and choose View White Space. Display Line numbers When selected, a line number appears next to each line of code. Note:  These line numbers are not added to your code, and do not print. They are for reference only. Enable single-click URL navigation When selected, the mouse cursor changes to a pointing hand as it passes over a URL in the editor. You can click the URL to display the indicated page in your Web browser. Navigation bar When selected, displays the Navigation bar at the top of the code editor. Its drop-down Objects and Members lists allow you to choose a particular object in your code, select from its members, and navigates to the declaration of the selected member in the Code Editor. Tabs Dialog This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To display these options, select Options from the Tools menu. Within the Text Editor folder expand the All Languages subfolder, and then choose Tabs. Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the Tabs options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the subfolder for that language and select its option pages. If different settings are selected on the Tabs options pages for particular programming languages, then the message "The indentation settings for individual text formats conflict with each other," is displayed for differing Indenting options; and the message "The tab settings for individual text formats conflict with each other," is displayed for differing Tab options. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 229 Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Indenting None When selected, new lines are not indented. The insertion point is placed in the first column of a new line. Block When selected, new lines are automatically indented. The insertion point is placed at the same starting point as the preceding line. Smart When selected, new lines are positioned to fit the code context, per other code formatting settings and IntelliSense conventions for your development language. This option is not available for all development languages. For example, lines enclosed between an opening brace ( { ) and a closing brace ( } ) might automatically be indented an extra tab stop from the position of the aligned braces. Tab and indent size Sets the distance in spaces between tab stops and for automatic indentation. The default is four spaces. Tab characters, space characters, or both will be inserted to fill the specified size. Insert spaces When selected, indent operations insert only space characters, not TAB characters. If the Tab and Indent size is set to 5, for example, then five space characters are inserted whenever you press the TAB key or the Increase Indent button on the Formatting toolbar. Keep tabs When selected, each indent operation inserts one TAB character. 9.3.4.7. Plain Text Settings General Language Options This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To open this dialog box, select Options from the Tools menu. Within the Text Editor folder, expand the All Languages subfolder and then choose General. Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the General options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the subfolder for that language and select its option pages. A grayed checkmark is displayed when an option has been selected on the General options pages for some programming languages, but not for others. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 230 Statement Completion Auto list members When selected, pop-up lists of available members, properties, values, or methods are displayed by IntelliSense as you type in the editor. Choose any item from the pop-up list to insert the item into your code. Selecting this option enables the Hide advanced members option. For more information, see List Members. Hide advanced members When selected, it shortens the pop-up statement completion lists by displaying only those items most commonly used. Other items are filtered from the list. Parameter information When selected, the complete syntax for the current declaration or procedure is displayed under the insertion point in the editor, with all of its available parameters. The next parameter you can assign is displayed in bold. For more information, see Parameter Info. Settings Enable virtual space When this option is selected and Word wrap is cleared, you can click anywhere beyond the end of a line in the Code Editor and type. This feature can be used to position comments at a consistent point next to your code. Word wrap When selected, any portion of a line that extends horizontally beyond the viewable editor area is automatically displayed on the next line. Selecting this option enables the Show visual glyphs for word wrap option. Note:  The Virtual Space feature is turned OFF while Word Wrap is ON. Show visual glyphs for word wrap When selected, a return-arrow indicator is displayed where a long line wraps onto a second line. Clear this option if you prefer not to display these indicators. Note:  These reminder arrows are not added to your code, and do not print. They are for reference only. Apply Cut or Copy commands to blank lines when there is no selection This option sets the behavior of the editor when you place the insertion point on a blank line, select nothing, and then Copy or Cut. When this option is selected, the blank line is copied or cut. If you then Paste, a new, blank line is inserted. When this option is cleared, the Cut command removes blank lines. However, the data on the Clipboard is preserved. Therefore, if you then use the Paste command, the content most recently copied onto the Clipboard is pasted. If nothing has been copied previously, nothing is pasted. This setting has no effect on Copy or Cut when a line is not blank. If nothing is selected, the entire line is copied or cut. If you then Paste, the text of the entire line and its endline character are pasted. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 231 Tip:  To display indicators for spaces, tabs, and line ends, and thus distinguish indented lines from lines that are entirely blank, select Advanced from the Edit menu and choose View White Space. Display Line numbers When selected, a line number appears next to each line of code. Note:  These line numbers are not added to your code, and do not print. They are for reference only. Enable single-click URL navigation When selected, the mouse cursor changes to a pointing hand as it passes over a URL in the editor. You can click the URL to display the indicated page in your Web browser. Navigation bar When selected, displays the Navigation bar at the top of the code editor. Its drop-down Objects and Members lists allow you to choose a particular object in your code, select from its members, and navigates to the declaration of the selected member in the Code Editor. Tabs Dialog This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To display these options, select Options from the Tools menu. Within the Text Editor folder expand the All Languages subfolder, and then choose Tabs. Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the Tabs options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the subfolder for that language and select its option pages. If different settings are selected on the Tabs options pages for particular programming languages, then the message "The indentation settings for individual text formats conflict with each other," is displayed for differing Indenting options; and the message "The tab settings for individual text formats conflict with each other," is displayed for differing Tab options. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Indenting None When selected, new lines are not indented. The insertion point is placed in the first column of a new line. Block When selected, new lines are automatically indented. The insertion point is placed at the same starting point as the preceding line. Smart Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 232 When selected, new lines are positioned to fit the code context, per other code formatting settings and IntelliSense conventions for your development language. This option is not available for all development languages. For example, lines enclosed between an opening brace ( { ) and a closing brace ( } ) might automatically be indented an extra tab stop from the position of the aligned braces. Tab and indent size Sets the distance in spaces between tab stops and for automatic indentation. The default is four spaces. Tab characters, space characters, or both will be inserted to fill the specified size. Insert spaces When selected, indent operations insert only space characters, not TAB characters. If the Tab and Indent size is set to 5, for example, then five space characters are inserted whenever you press the TAB key or the Increase Indent button on the Formatting toolbar. Keep tabs When selected, each indent operation inserts one TAB character. 9.3.4.8. XML Settings General Language Options This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To open this dialog box, select Options from the Tools menu. Within the Text Editor folder, expand the All Languages subfolder and then choose General. Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the General options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the subfolder for that language and select its option pages. A grayed checkmark is displayed when an option has been selected on the General options pages for some programming languages, but not for others. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Statement Completion Auto list members When selected, pop-up lists of available members, properties, values, or methods are displayed by IntelliSense as you type in the editor. Choose any item from the pop-up list to insert the item into your code. Selecting this option enables the Hide advanced members option. For more information, see List Members. Hide advanced members When selected, shortens pop-up statement completion lists by displaying only those items most commonly used. Other items are filtered from the list. Parameter information Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 233 When selected, the complete syntax for the current declaration or procedure is displayed under the insertion point in the editor, with all of its available parameters. The next parameter you can assign is displayed in bold. For more information, see Parameter Info. Settings Enable virtual space When this option is selected and Word wrap is cleared, you can click anywhere beyond the end of a line in the Code Editor and type. This feature can be used to position comments at a consistent point next to your code. Word wrap When selected, any portion of a line that extends horizontally beyond the viewable editor area is automatically displayed on the next line. Selecting this option enables the Show visual glyphs for word wrap option. Note:  The Virtual Space feature is turned off while Word Wrap is on. Show visual glyphs for word wrap When selected, a return-arrow indicator is displayed where a long line wraps onto a second line. Clear this option if you prefer not to display these indicators. Note:  These reminder arrows are not added to your code, and do not print. They are for reference only. Apply Cut or Copy commands to blank lines when there is no selection This option sets the behavior of the editor when you place the insertion point on a blank line, select nothing, and then Copy or Cut. When this option is selected, the blank line is copied or cut. If you then Paste, a new, blank line is inserted. When this option is cleared, the Cut command removes blank lines. However, the data on the Clipboard is preserved. Therefore, if you then use the Paste command, the content most recently copied onto the Clipboard is pasted. If nothing has been copied previously, nothing is pasted. This setting has no effect on Copy or Cut when a line is not blank. If nothing is selected, the entire line is copied or cut. If you then Paste, the text of the entire line and its endline character are pasted. Tip:  To display indicators for spaces, tabs, and line ends, and thus distinguish indented lines from lines that are entirely blank, select Advanced from the Edit menu and choose View White Space. Display Line numbers When selected, a line number appears next to each line of code. Note:  These line numbers are not added to your code, and do not print. They are for reference only. Enable single-click URL navigation When selected, the mouse cursor changes to a pointing hand as it passes over a URL in the editor. You can click the URL to display the indicated page in your Web browser. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 234 Navigation bar When selected, displays the Navigation bar at the top of the code editor. Its drop-down Objects and Members lists allow you to choose a particular object in your code, select from its members, and navigates to the declaration of the selected member in the Code Editor. Tabs Dialog This dialog box allows you to change the default behavior of the Code Editor. These settings also apply to other editors based upon the Code Editor, such as the HTML Designer's Source view. To display these options, select Options from the Tools menu. Within the Text Editor folder expand the All Languages subfolder, and then choose Tabs. Caution:  This page sets default options for all development languages. Remember that resetting an option in this dialog will reset the Tabs options in all languages to whatever choices are selected here. To change Text Editor options for just one language, expand the subfolder for that language and select its option pages. If different settings are selected on the Tabs options pages for particular programming languages, then the message "The indentation settings for individual text formats conflict with each other," is displayed for differing Indenting options; and the message "The tab settings for individual text formats conflict with each other," is displayed for differing Tab options. Note:  The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Working with Settings. Indenting None When selected, new lines are not indented. The insertion point is placed in the first column of a new line. Block When selected, new lines are automatically indented. The insertion point is placed at the same starting point as the preceding line. Smart When selected, new lines are positioned to fit the code context, per other code formatting settings and IntelliSense conventions for your development language. This option is not available for all development languages. For example, lines enclosed between an opening brace ( { ) and a closing brace ( } ) might automatically be indented an extra tab stop from the position of the aligned braces. Tab and indent size Sets the distance in spaces between tab stops and for automatic indentation. The default is four spaces. Tab characters, space characters, or both will be inserted to fill the specified size. Insert spaces When selected, indent operations insert only space characters, not TAB characters. If the Tab and Indent size is set to 5, for example, then five space characters are inserted whenever you press the TAB key or the Increase Indent button on the Formatting toolbar. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 235 Keep tabs When selected, each indent operation inserts one TAB character. XML Formatting Options This dialog box allows you to specify the formatting settings for the XML Editor. You can access the Options dialog box from the Tools menu. Note:  These settings are available when you select the Text Editor folder, the XML folder, and then the Formatting option from the Options dialog box. Attributes Preserve manual attribute formatting Attributes are not reformatted. This is the default. Note:  If the attributes are on multiple lines, the editor indents each line of attributes to match the indentation of the parent element. Align attributes each on their own line Aligns the second and subsequent attributes vertically to match the indentation of the first attribute. The following XML text is an example of how the attributes would be aligned. Auto Reformat On paste from the Clipboard Reformats XML text pasted from the Clipboard. On completion of end tag Reformats the element when the end tag is completed. Mixed Content Preserve mixed content by default Determines whether the editor reformats mixed content. By default, the editor attempts to reformat mixed content, except when the content is found in an xml:space="preserve" scope. If an element contains a mix of text and markup, the contents are considered to be mixed content. The following is an example of an element with mixed content. c:\data\AlphaProject\ test1.txt test2.txt XML Miscellaneous Options This dialog box allows you to change the autocompletion and schema settings for the XML Editor. You can access the Options dialog box from the Tools menu. Note:  These settings are available when you select the Text Editor folder, the XML folder, and then the Miscellaneous option from the Options dialog box. Auto Insert Close tags Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 236 If the autocompletion setting is checked, the editor automatically adds an end tag when you type a right angle bracket (>) to close a start tag, if the tag is not already closed. This is the default behavior. The completion of an empty element does not depend on the autocompletion setting. You can always autocomplete an empty element by typing a backslash (/). Attribute quotes When authoring XML attributes, the editor inserts the =" " characters and positions the caret (^) inside the double quotes. Selected by default. Namespace declarations The editor automatically inserts namespace declarations wherever they are needed. Selected by default. Other markup (Comments, CDATA) Comments, CDATA, DOCTYPE, processing instructions, and other markup are auto-completed. Selected by default. Network Automatically download DTDs and schemas Schemas and document type definitions (DTDs) are automatically downloaded from HTTP locations. This feature uses System.Net with auto-proxy server detection enabled. Selected by default. Outlining Enter outlining mode when files open Turns on the outlining feature when a file is opened. Selected by default. Caching Schemas Specifies the location of the schema cache. The browse button ( ...) opens the Directory Browse dialog box at the current schema cache location. You can select a different directory, or you can select a folder in the dialog, right-click, and choose Open to see what is in the directory. 9.3.5. Debugger 9.3.5.1. Usage In Atmel Studio, you can specify various settings for debugger behavior, including how variables are displayed, whether certain warnings are presented, how breakpoints are set, and how breaking affects running programs. You specify debugger settings in the Options dialog box. To set debugger options On the Tools menu, click Options. In the Options dialog box, open the Debugging folder. In the Debugging folder, choose the category of options you want. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 237 9.3.5.2. AVR Debugger Settings AVR Communication Timeout Shows the timeout delay used for communication with the back-end. If the watchdog detects that timeout is exceeded the back-end is restarted. 20000ms by default. AVR Debugger Path Shows the path to the AVR Debugger. AVR Debugger Port Indicates the Windows Comm API Port number, used by the AVR debugger. 0 by default. RPC transaction times File name to put statistic logging in. This is log data from the communication with the back-end. Empty means no logging. Note that the file must be written to a directory where the user has write permission. E.g. C:/tmp/transactionlog.csv User Tool polling Use internal port polling method for hardware tool discovery, instead of relying on Windows Comm Framework. Must restart Atmel Studio if activated, it may slow down your PC considerably, so use it only if you have errors related to Windows Comm Framework. Disabled by default. 9.3.6. Atmel Software Framework Settings Path of the application used to compare files An application is normally used to compare files in the Atmel Software Framework, as such you must specify a path here. Command line arguments used for file comparison Command line argument macros: • %original - Path of the original Software Framework file. • %mine - Path of the modified file in the local project If the command line for the configured file compare application is FileCompare.exe filepath1 filepath2, specify %original for filepath1 and %mine for filepath2. For example, if configuring WinMerge as the compare application, specify the following command line arguments: %original %mine /s /u. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 238 9.3.7. Builder Figure 9-1. Builder ShellUtils Packages It will list Default, Custom, and installed Shell Utility extensions. ShellUtils Path Based on the package selected the ShellUtils Path will point to the corresponding utilities folder. If you select a custom ShellUtil package then you can configure a custom Shell utilities folder by clicking on ... button. If you select default or installed shell extension package then the path will be read only and point to the package path. Make Configuration You can configure the path to the Make executable by clicking on ... button by default it points to INSTALLDIR\shellUtils\make.exe and you can enable parallel build of projects by checking the box. 9.3.8. Device and Tool Libraries In the Devices sub-menu you can specify the path to custom libraries for your device. In the Tools submenu, you can specify the path to custom tools for your device. 9.3.9. Status Management Contains path to the log files and logging settings. Location Path to the log file. You can change it by clicking and browsing to the desired location. Severity threshold How severe the incident must be in order to generate a log entry. You can choose whether you want to have an output when all operations are successful - OK level, when some unorthodox code is present - Info level, when some operations have been canceled - Cancel setting. If you want to generate output Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 239 only in the case when the code is potentially unstable or erroneous, choose either Warning or Error setting. Component filter Filter messages coming from the source code for standard or custom components in your design. Severity threshold Meaning identical to the Severity threshold for your source code log generation. Use filter Whether the logging process should use a filter to separate components output from your code output. 9.3.10. Text Templating Show security message Display a dialog prompting the user to ensure that the text templates are from a trusted source when a text transformation operation is initiated. 9.3.11. Toolchain Figure 9-2. Toolchain Flavor Configuration Toolchain Toolchain is used to compile, link, and transform the source code to an executable form targeting the AVR devices. By default, AVR Studio has the following Toolchain Type extensions. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 240 Table 9-2. Toolchain Options Toolchain type Language Description AVR Assembler Assembly Used for building 8-Bit Assembler projects Atmel AVR 8-bit C Used for building 8-Bit C/C++ projects C++ Atmel AVR 32-bit C Used for building 32-Bit C/C++ projects C++ Atmel ARM 32-bit C Used for building ARM C/C++ projects C++ 9.3.11.1. Flavor Flavor identifies a particular version of Toolchain extension of a desired Toolchain type. You could have different flavors of same Toolchain type extensions installed for Atmel Studio. Add Flavor 1. Select a Toolchain type for which the new Flavor is to be added. Figure 9-3. Add Toolchain Flavor 2. Enter a new Flavor Name. 3. Configure the Toolchain path for the Flavor. The path should contain desired Toolchain executable, e.g. avr-gcc.exe for Atmel AVR 8-bit. 4. Click the Add button. Set Default Flavor 1. Select a Flavor to set as default. The flavor would be the default for the selected toolchain type. Hence, a new project using the toolchain type, would use the configured Flavor settings. 2. You can view and switch between various Flavors after creating the project through the project properties page shown in Advanced Options. Delete Flavor Pressing the Delete Flavor button deletes the Flavor configuration. Note:  If the customized default flavor is deleted, then the Native flavor will be set as default. Also the projects that were configured with the deleted flavor will be changed to the default flavor of the respective toolchain type when the project is opened the next time. 9.3.12. GDB Settings We can configure architecture specific GDB path in this page. This will override the default toolchain flavor GDB path. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 241 9.4. Code Snippet Manager Code snippets are particularly useful when writing AVR GCC applications. You can use the Code Snippets Manager to add folders to the folder list that the Code Snippet Picker scans for XML .snippet files. Having these building blocks of code at your disposal can facilitate project development. The Code Snippets Manager can be accessed from the Tools menu. 9.4.1. Managing Code Snippets To access the Code Snippets Manager On the Tools menu, click Code Snippets Manager. To add a directory to the Code Snippet Manager 1. In the Language: drop-down list, select the language that you want to add a directory to. 2. Click Add. This opens the Code Snippets Directory window. 3. Select the directory that you want to add to the Code Snippets Manager and click OK. The directory will now be used to search for available code snippets. To remove a directory from the Code Snippet Manager 1. Select the directory that you want to remove. 2. Click Remove. To import a code snippet into the Code Snippet Manager 1. In the Language: drop-down list, select the language that you want to add the code snippet to. 2. Select the existing folder that you want to place the imported code snippet into. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 242 3. Click Import. This opens the Code Snippets Directory window. 4. Select the code snippet file that you want to add to the Code Snippets Manager and click OK. The code snippet is now available for insertion into the code editor. 9.4.2. Code Snippet Manager Layout Language Selects the development language whose code snippet folders are displayed in the folder list. Location Displays the path to the folders in the folder list, or to the code snippet file selected there. Folder list Shows the set of sub-folders, if any, and the code snippet files available for the Language selected. Click any folder to expand it and list its files. Description Displays information on the folder or code snippet file selected in the folder list. When a code snippet file is selected, displays the text from its Author, Description, Shortcut, and Type fields. Add Opens the Code Snippet Directory dialog box. Allows you to navigate to the desired snippets folder on your local drive or server, and include it in the folder list. Remove Removes a selected top-level folder and its contents from the folder list. Does not physically delete the folder. Import Opens the Code Snippet Directory dialog box. Allows you to navigate to the desired snippet on your local drive or server, and add it to an existing code snippet folder. Security Whenever you store a new snippet in a folder accessed by the Code Snippets Manager, you are responsible for ensuring that its code is constructed as securely as the rest of your application. Because using code snippets saves development time, snippets can be reused frequently as you construct applications. You should therefore make sure that model code saved in snippets is designed to address security issues. Development teams should establish procedures to review code snippets for compliance with general security standards. 9.4.3. Modifying Existing Code Snippets IntelliSense Code Snippets are XML files with a .snippet file name extension that can be easily modified using any XML editor, including Atmel Studio. To modify an existing IntelliSense Code Snippet 1. Use the Code Snippets Manager to locate the snippet that you want to modify. 2. Copy the path of the code snippet to the clipboard and click OK. 3. On the File menu, click Open, and click File. 4. Paste the snippet path into the File location box and click OK. 5. Modify the snippet. 6. On the File menu, click Save. You must have write access to the file to save it. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 243 9.5. External Tools You can add items to the Tools menu that allow you to launch external tools from within Visual Studio. For example, you can add an item to the Tools menu to launch utilities such as avrdude or a diffing tool. 9.5.1. Add an External Tool to the Tools Menu You can add a command to the Tools menu to start another application, such as Notepad, from within the integrated development environment (IDE). Figure 9-4. External Tool Dialog The dialog contains a list box where all previously defined external tools are listed. If you have not defined any tool, the list box will be empty. • On the Tools menu, choose External Tools • In the External Tools dialog box, choose Add, and enter a name for the menu option in the Title box Tip:  Type an ampersand before one of the letters in the tool name to create an accelerator key for the command when it appears on the Tools menu. For example, if you use M&y External Tool, the letter 'y' will be the accelerator key. See Assign a Keyboard Shortcut for more information. • In the Command box, enter the path to the file you intend to launch, or choose Browse (...) to navigate to the file. Files types that you can launch include .exe, .bat, .com, .cmd, and .pif. Note:  If the file resides on the system path, you can enter just the file name. If not, enter the full path to the file. • Select Use output window and Close on exit, as appropriate, and then choose OK Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 244 9.5.2. Pass Variables to External Tools You can specify that certain information be passed to a command when it is launched, such as command line switches for console applications. Fill in the Arguments box with the necessary launch arguments, either manually or using the auto-fill button. The auto-fill argument button can provide you with the macros described in the table below. Table 9-3. External Tools Macros Name Argument Description Item Path $(ItemPath) The complete file name of the current source (defined as drive + path + file name); blank if a non-source window is active. Item Directory $(ItemDir) The directory of the current source (defined as drive + path); blank if a non-source window is active. Item File Name $(ItemFilename) The file name of the current source (defined as file name); blank if a non-source window is active. Item Extension $(ItemExt) The file name extension of the current source. Current Line $(CurLine) The current line position of the cursor in the editor. Current Column $(CurCol) The current column position of the cursor in the editor. Current Text $(CurText) The selected text. Target Path $(TargetPath) The complete file name of the item to be built, (defined as drive + path + file name). Target Directory $(TargetDir) The directory of the item to be built. Target Name $(TargetName) The file name of the item to be built. Target Extension $(TargetExt) The file name extension of the item to be built. Binary Directory $(BinDir) The final location of the binary that is being built (defined as drive + path). Project Directory $(ProjectDir) The directory of the current project (defined as drive + path). Project file name $(ProjectFileName) The file name of the current project (defined as drive + path + file name). Solution Directory $(SolutionDir) The directory of the current solution (defined as drive + path). Solution file name $(SolutionFileName) The file name of the current solution (defined as drive + path + file name). Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 245 9.5.3. Initial Directory You can also specify the working directory for the tool or command. For example, if the tool reads file system data from the current directory, the tool requires that certain program components are present in the current directory at start-up. 9.5.4. Run Behavior Underneath the argument boxes you can modify the tool behavior. Use output window - if this box is checked, the tool will output processing information to the Atmel Studio output window, otherwise the output will be suppressed. Close on exit - if the box is checked the tool window, if any will be automatically closed after completing all operations. Prompt for arguments - used for toolchain automation. If the box is checked, external tool will require user intervention to input additional processing parameters, otherwise the tool will be silent. Treat output as Unicode - internationalization option. Some tools have a capacity to output Unicode results for better interpretation. This option allows for correct output rendering if you are using such a tool. 9.5.5. Assign a Keyboard Shortcut To assign a shortcut (accelerator) to a command, add an ampersand (&) in the title of the tool, just before the letter that you want to use as the access key. After the ampersand has been added the accelerator needs to be included as a keyboard shortcut. • On the Tools menu, click Options • Select Keyboard on the Environment page • In the Show commands containing list, type Tools • In the Command names list, locate the appropriate External Command n entry Note:  You can define keyboard shortcuts for up to twenty external tools. External tools are listed as External Command 1-20 in the Command names list. The numbers correspond to the number to the left of the custom external command name on the Tools menu. If the menu command already has a shortcut assigned to it, that information appears in the Shortcuts for selected command list. • Put the cursor in the Press shortcut keys box, and then press the keys you want to assign to the external tool Note:  If the keyboard shortcut is already assigned to another command, the Shortcut currently assigned to list will display that information. • Click Assign 9.6. Predefined Keyboard Shortcuts The Atmel Studio uses the Visual Studio Shell framework from Microsoft Visual Studio 2010 and therefore the integrated development environment (IDE) includes several predefined keyboard shortcut schemes, identical to those in the Visual Studio. When you start Atmel Studio for the first time and select your settings, the associated schemes are automatically set. Thereafter, by using the keyboard options page in the Options dialog box, you can choose from additional schemes and you can also create your own keyboard shortcuts. Designers and Editors, Shared Shortcuts These shortcuts work in both designers and editors. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 246 Command Description General development, web Edit.Copy Copies the selected item to the Clipboard. CTRL+C or CTRL +INSERT Edit.Cut Deletes the selected item from the file and copies it to the Clipboard. CTRL+X or SHIFT +DELETE Edit.CycleClipboardRing Pastes an item from the Clipboard ring to the cursor location in the file. To paste the next item in the Clipboard ring instead, press the shortcut again. CTRL+SHIFT+V Edit.Delete Deletes one character to the right of the cursor. DELETE Edit.Find Displays the Quick tab of the Find and Replace dialog box. CTRL+F Edit.FindAllReferences Displays the list of references for the selected symbol. SHIFT+ALT+F Edit.FindinFiles Displays the In Files tab of the Find and Replace dialog box. CTRL+SHIFT+F Edit.FindNext Finds the next occurrence of the search text. F3 Edit.FindNextSelected Finds the next occurrence of the currently selected text, or the word at the cursor. CTRL+F3 Edit.FindPrevious Finds the previous occurrence of the search text. SHIFT+F3 Edit.FindPreviousSelected Finds the previous occurrence of the currently selected text, or the word at the cursor. CTRL+SHIFT+F3 Edit.FindSymbol Displays the Find Symbol pane of the Find and Replace dialog box. ALT+F12 Edit.GoToFindCombo Puts the cursor in the Find/Command box on the Standard toolbar. CTRL+D Edit.IncrementalSearch Activates incremental search. If incremental search is on, but no input is passed, the previous search query is used. If search input has been found, the next invocation searches for the next occurrence of the input text. CTRL+I Edit.Paste Inserts the Clipboard contents at the cursor. CTRL+V or SHIFT +INSERT Edit.QuickFindSymbol Searches for the selected object or member and displays the matches in the Find Symbol Results window. SHIFT+ALT+F12 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 247 Command Description General development, web Edit.NavigateTo Displays the Navigate To dialog box. CTRL+, Edit.Redo Repeats the most recent action. CTRL+Y or SHIFT+ALT +BACKSPACE or CTRL +SHIFT+Z Edit.Replace Displays the replace options on the Quick tab of the Find and Replace dialog box. CTRL+H Edit.ReplaceinFiles Displays the replace options on the In Files tab of the Find and Replace dialog box. CTRL+SHIFT+H Edit.SelectAll Selects everything in the current document. CTRL+A Edit.StopSearch Stops the current Find in Files operation. ALT+F3, S Edit.Undo Reverses the last editing action. CTRL+Z or ALT +BACKSPACE View.ViewCode For the selected item, opens the corresponding file and puts the cursor in the correct location. CTRL+ALT+0 Text Navigation These shortcuts are for moving around in an open document. Command Description Shortcut Edit.CharLeft Moves the cursor one character to the left. LEFT ARROW Edit.CharRight Moves the cursor one character to the right. RIGHT ARROW Edit.DocumentEnd Moves the cursor to the last line of the document. CTRL+END Edit.DocumentStart Moves the cursor to the first line of the document. CTRL+HOME Edit.GoTo Displays the Go To Line dialog box. CTRL+G Edit.GoToDefinition Navigates to the declaration for the selected symbol in code. ALT+G Edit.GoToNextLocation Moves the cursor to the next item, such as a task in the Task List window or a search match in the Find Results window. Subsequent invocations move to the next item in the list. F8 Edit.GoToPrevLocation Moves the cursor back to the previous item. SHIFT+F8 Edit.IncrementalSearch Starts incremental search. If incremental search is started but you have not typed any characters, recalls the previous pattern. If text has been found, searches for the next occurrence. CTRL+I Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 248 Command Description Shortcut Edit.LineDown Moves the cursor down one line. DOWN ARROW Edit.LineEnd Moves the cursor to the end of the current line. END Edit.LineStart Moves the cursor to the start of the line. HOME Edit.LineUp Moves the cursor up one line. UP ARROW Edit.NextBookmark Moves to the next bookmark in the document. CTRL+K, CTRL +N Edit.NextBookmarkInFolder If the current bookmark is in a folder, moves to the next bookmark in that folder. Bookmarks outside the folder are skipped. If the current bookmark is not in a folder, moves to the next bookmark at the same level. If the Bookmark window contains folders, bookmarks in folders are skipped. CTRL+SHIFT+K, CTRL+SHIFT+N Edit.PageDown Scrolls down one screen in the editor window. PAGE DOWN Edit.PageUp Scrolls up one screen in the editor window. PAGE UP Edit.PreviousBookmark Moves the cursor to the location of the previous bookmark. CTRL+K, CTRL +P Edit.PreviousBookmarkInFolder If the current bookmark is in a folder, moves to the previous bookmark in that folder. Bookmarks outside the folder are skipped. If the current bookmark is not in a folder, moves to the previous bookmark at the same level. If the Bookmark window contains folders, bookmarks in folders are skipped. CTRL+SHIFT+K, CTRL+SHIFT+P Edit.ReverseIncrementalSearch Changes the direction of incremental search to start at the bottom of the file and progress toward the top. CTRL+SHIFT+I Edit.ScrollLineDown Scrolls text down one line. Available in text editors only. CTRL+DOWN ARROW Edit.ScrollLineUp Scrolls text up one line. Available in text editors only. CTRL+UP ARROW Edit.ViewBottom Moves to the last visible line of the active window. CTRL+PAGE DOWN Edit.ViewTop Moves to the first visible line of the active window. CTRL+PAGE UP Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 249 Command Description Shortcut Edit.WordNext Moves the cursor to the right one word. CTRL+RIGHT ARROW Edit.WordPrevious Moves the cursor to the left one word. CTRL+LEFT ARROW View.NavigateBackward Moves to the previously browsed line of code. CTRL+- View.NavigateForward Moves to the next browsed line of code. CTRL+SHIFT+- View.NextError Moves to the next error entry in the Error List window, which automatically scrolls to the affected section of text in the editor. CTRL+SHIFT +F12 View.NextTask Moves to the next task or comment in the Task List window. Visual Assist shortcuts These shortcuts are for Visual Assist. Command Description Shortcut VAssistX.FindReference Find all references to the marked text. SHIFT+ALT+F VAssistX.FindSymbolDialog Opens the symbols dialog listing all symbols in the project. SHIFT+ALT+S VAssistX.GotoImplementation Go to implementation. ALT+G VAssistX.ListMethodsInCurrentFile Opens the list of all methods in the current file. ALT+M VAssistX.OpenCorrespondingFile Opens the corresponding file (i.e. .h/.c). ALT+O VAssistX.OpenFileInSolutionDialog Displays a list of all files in the solution. SHIFT+ALT+O VAssistX.Paste Shows the paste history menu. CTRL+SHIFT+V VAssistX.RefactorContextMenu Shows the refactor context menu. SHIFT+ALT+Q VAssistX.RefactorRename Shows the rename dialog. SHIFT+ALT+R VAssistX.ScopeNext Jump to next scope. ALT+Down Arrow VAssitX.ScopePrevious Jump to previous scope. ALT+Up Arrow Text Selection These shortcuts are for selecting text in an open document. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 250 Command Description Shortcut Edit.CharLeftExtend Moves the cursor one character to the left and extends the current selection. SHIFT+LEFT ARROW Edit.CharLeftExtendColumn Moves the cursor to the left one character, extending the column selection. SHIFT+ALT+LEFT ARROW Edit.CharRightExtend Moves the cursor one character to the right and extends the current selection. SHIFT+RIGHT ARROW Edit.CharRightExtendColumn Moves the cursor to the right one character, extending the column selection. SHIFT+ALT+RIGHT ARROW Edit.DocumentEndExtend Selects the text from the cursor to the last line of the document. CTRL+SHIFT+END Edit.DocumentStartExtend Selects the text from the cursor to the first line of the document. CTRL+SHIFT +HOME Edit.LineDownExtend Extends text selection down one line, starting at the location of the cursor. SHIFT+DOWN ARROW Edit.LineDownExtendColumn Moves the pointer down one line, extending the column selection. SHIFT+ALT+DOWN ARROW Edit.LineEndExtend Selects text from the cursor to the end of the current line. SHIFT+END Edit.LineEndExtendColumn Moves the cursor to the end of the line, extending the column selection. SHIFT+ALT+END Edit.LineStartExtend Selects text from the cursor to the start of the line. SHIFT+HOME Edit.LineStartExtendColumn Moves the cursor to the start of the line, extending the column selection. SHIFT+ALT+HOME Edit.LineUpExtend Selects text up, line by line, starting from the location of the cursor. SHIFT+UP ARROW Edit.LineUpExtendColumn Moves the cursor up one line, extending the column selection. SHIFT+ALT+UP ARROW Edit.PageDownExtend Extends selection down one page. SHIFT+PAGE DOWN Edit.PageUpExtend Extends selection up one page. SHIFT+PAGE UP Edit.SelectCurrentWord Selects the word that contains the cursor or the word to the right of the cursor. CTRL+W Edit.SelectionCancel Cancels the current selection. ESC Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 251 Command Description Shortcut Edit.ViewBottomExtend Moves the cursor and extends the selection to the last line in view. CTRL+SHIFT +PAGE DOWN Edit.ViewTopExtend Extends the selection to the top of the active window. CTRL+SHIFT +PAGE UP Edit.WordNextExtend Extends the selection one word to the right. CTRL+SHIFT +RIGHT ARROW Edit.WordNextExtendColumn Moves the cursor to the right one word, extending the column selection. CTRL+SHIFT+ALT +RIGHT ARROW Edit.WordPreviousExtend Extends the selection one word to the left. CTRL+SHIFT+LEFT ARROW Edit.WordPreviousExtendColumn Moves the cursor to the left one word, extending the column selection. CTRL+SHIFT+ALT +LEFT ARROW Text Viewing These shortcuts are for changing how text is displayed without changing the text itself, for example, by hiding a selected area or by outlining methods. Command Description Shortcut Edit.ClearBookmarks Removes all bookmarks in all open documents. CTRL+K, CTRL+L Edit.CollapseAllOutlining Collapses all regions on the page to show just the outermost groups in the hierarchy; typically the using/imports section and the namespace definition. CTRL+M, CTRL+A Edit.CollapseCurrentRegion Collapses the region that contains the cursor to show just the top line of the region, followed by an ellipsis. Regions are indicated by triangles on the left edge of the document window. CTRL+M, CTRL+S Edit.CollapseTag Hides the selected HTML tag and displays an ellipsis (. . .) instead. You can view the complete tag as a tooltip by putting the mouse pointer over the ellipsis. CTRL+M, CTRL+T Edit.CollapsetoDefinitions Collapses existing regions to provide a high-level view of the types and members in the source file. CTRL+M, CTRL+O Edit.EnableBookmark Enables bookmark usage in current document. Edit.ExpandAllOutlining Expands all collapsed regions on the page. CTRL+M, CTRL+X Edit.ExpandCurrentRegion Expands the current region. Put the cursor on a collapsed region to use this command. CTRL+M, CTRL+E Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 252 Command Description Shortcut Edit.HideSelection Hides the selected text. A signal icon marks the location of the hidden text in the file. CTRL+M, CTRL+H Edit.StopHidingCurrent Removes the outlining information for the currently selected region. CTRL+M, CTRL+U Edit.StopOutlining Removes all outlining information from the whole document. CTRL+M, CTRL+P Edit.ToggleAllOutlining Toggles all previously collapsed outlining regions between collapsed and expanded states. CTRL+M, CTRL+L Edit.ToggleBookmark Sets or removes a bookmark at the current line. CTRL+K, CTRL+K Edit.ToggleOutliningExpansion Toggles the currently selected collapsed region between the collapsed and expanded state. CTRL+M, CTRL+M Edit.ToggleTaskListShortcut Sets or removes a shortcut at the current line. CTRL+K, CTRL+H Edit.ToggleWordWrap Enables or disables word-wrap in an editor. CTRL+E, CTRL+W Edit.ViewWhiteSpace Shows or hides spaces and tab marks. CTRL+R, CTRL+W Text Manipulation These shortcuts are for deleting, moving, or formatting text in an open document. Command Description Shortcut Edit.BreakLine Inserts a new line. ENTER Edit.CharTranspose Swaps the characters on either side of the cursor. For example, AC|BD becomes AB|CD. CTRL+T Edit.CommentSelection Applies comment characters for the current language to the current selection. CTRL+K, CTRL+C Edit.CompleteWord Completes the current word in the completion list. ALT+RIGHT ARROW or CTRL+SPACEBAR Edit.DeleteBackwards Deletes one character to the left of the cursor. BACKSPACE Edit.FormatDocument Formats the current document according to the indentation and code formatting settings specified on the Formatting pane in the Options dialog box, for the current language. CTRL+K, CTRL+D Edit.FormatSelection Formats the current selection according to the indentation and code formatting settings specified on the Formatting pane in the Options dialog box, for the current language. CTRL+K, CTRL+F Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 253 Command Description Shortcut Edit.InsertSnippet Displays the Code Snippet Picker. The selected code snippet will be inserted at the cursor position. CTRL+K, CTRL+X Edit.InsertTab Indents the line of text a specified number of spaces. TAB Edit.LineCut Cuts all selected lines, or the current line if nothing has been selected, to the Clipboard. CTRL+L Edit.LineDelete Deletes all selected lines, or the current line if no selection has been made. CTRL+SHIFT+L Edit.LineOpenAbove Inserts a blank line above the cursor. CTRL+SHIFT+ENTER Edit.LineOpenBelow Inserts a blank line below the cursor. CTRL+ENTER Edit.LineTranspose Moves the line that contains the cursor below the next line. SHIFT+ALT+T Edit.ListMembers Invokes the IntelliSense completion list. CTRL+J Edit.MakeLowercase Changes the selected text to lowercase characters. CTRL+U Edit.MakeUppercase Changes the selected text to uppercase characters. CTRL+SHIFT+U Edit.OvertypeMode Toggles between insert and over-type insertion modes. INSERT Edit.ParameterInfo Displays the name, number, and type of parameters required for the specified method. CTRL+SHIFT +SPACEBAR Edit.SurroundWith Displays the Code Snippet Picker. The selected code snippet will be wrapped around the selected text. CTRL+K, CTRL+S Edit.TabifySelectedLines Replaces spaces with tabs in the selected text. Edit.TabLeft Moves selected lines to the left one tab stop. SHIFT+TAB Edit.UncommentSelection Removes the comment syntax from the current line of code. CTRL+K, CTRL+U Edit.UntabifySelectedLines Replaces tabs with spaces in selected text. Edit.WordDeleteToEnd Deletes the word to the right of the cursor. CTRL+DELETE Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 254 Command Description Shortcut Edit.WordDeleteToStart Deletes the word to the left of the cursor. CTRL+BACKSPACE Edit.WordTranspose Transposes the words on either side of the cursor. For example, |End Sub would be changed to read Sub End|. CTRL+SHIFT+T File and Project Operations These shortcuts are for file and project operations, and can be used anywhere in the IDE. Command Description Shortcut Build.BuildSelection Builds the selected project and its dependencies. Build.BuildSolution Builds all the projects in the solution. F7 Build.Cancel Stops the current build. CTRL+BREAK Build.Compile Creates an object file that contains machine code, linker directives, sections, external references, and function/ data names for the selected file. CTRL+F7 Build.RebuildSolution Rebuilds the solution. CTRL+ALT+F7 File.NewFile Displays the New File dialog box so that you can add a new file to the current project. CTRL+N File.NewProject Displays the New Project dialog box. CTRL+SHIFT+N File.OpenFile Displays the Open File dialog box. CTRL+O File.OpenProject Displays the Open Project dialog box so that you can add existing projects to your solution. CTRL+SHIFT+O File.Print Displays the Print dialog box so that you can select printer settings. CTRL+P File.Rename Lets you modify the name of the item selected in Solution Explorer. F2 File.SaveAll Saves all documents in the current solution and all files in the external files project. CTRL+SHIFT+S File.SaveSelectedItems Saves the selected items in the current project. CTRL+S File.SaveSelectedItemsAs Displays the Save File As dialog box when items are selected in the editor. Project.AddExistingItem Displays the Add Existing Item dialog box, which lets you add an existing file to the current project. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 255 Command Description Shortcut Project.AddNewItem Displays the Add New Item dialog box, which lets you add a new file to the current project. Project.Properties Displays the Project Properties dialog box for the current project in the editing frame. Window Management These shortcuts are for moving, closing, or navigating in tool windows and document windows. Command Description Shortcut View.FullScreen Toggles Full Screen mode ON and OFF. SHIFT+ALT +ENTER Window.ActivateDocumentWindow Closes a menu or dialog box, cancels an operation in progress, or puts focus in the current document window. ESC Window.CloseDocumentWindow Closes the current tab. CTRL+F4 Window.CloseToolWindow Closes the current tool window. SHIFT+ESC Window.Dock Returns a floating tool or document window to its most recent docked location in the IDE. Window.NextDocumentWindow Cycles through the open documents. CTRL+F6 Window.NextDocumentWindowNav Displays the IDE Navigator, with the first document window selected. CTRL+TAB Window.NextPane Moves to the next pane of the current tool or document window. ALT+F6 Window.NextToolWindow Moves to the next tool window. Window.NextToolWindowNav Displays the IDE Navigator, with the first tool window selected. ALT+F7 Window.PreviousDocumentWindow Moves to the previous document in the editor. CTRL+SHIFT+F6 Window.PreviousDocumentWindowNav Displays the IDE Navigator, with the previous document window selected. CTRL+SHIFT +TAB Window.PreviousPane Moves to the previously selected window. SHIFT+ALT+F6 Window.ShowEzMDIFileList Displays a pop-up listing all open documents only. CTRL+ALT +DOWN ARROW Tool Windows Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 256 These shortcuts are for opening tool windows anywhere in the IDE. Command Description Shortcut Tools.CodeSnippetsManager Displays the Code Snippets Manager, which lets you search for and insert code snippets in files. CTRL+K, CTRL+B Tools.GoToCommandLine Puts the pointer in the Find/Command box on the Standard toolbar. CTRL+/ View.BookmarkWindow Displays the Bookmark window. CTRL+K, CTRL+W View.CallHierarchy Displays the Call Hierarchy window. CTRL+ALT+K View.CommandWindow Displays the Command window, where commands can be invoked to make changes to the IDE. CTRL+ALT+A View.EditLabel Lets you change the name of the selected item in Solution Explorer. F2 View.ErrorList Displays the Error List window. CTRL+\, E View.FindSymbolResults Displays the Find Symbol Results window. CTRL+ALT+F12 View.Output Displays the Output window to view status messages at run time. CTRL+ALT+O View.SolutionExplorer Displays Solution Explorer, which lists the projects and files in the current solution. CTRL+ALT+L View.TaskList Displays the Task List window, which displays custom tasks, comments, shortcuts, warnings, and error messages. CTRL+\, T View.WebBrowser Displays the Web Browser window, which lets you view pages on the Internet. CTRL+ALT+R Window.PreviousToolWindow Brings focus to the previous tool-window. Window.PreviousToolWindowNav Displays the IDE Navigator, with the previous tool window selected. SHIFT+ALT+F7 Bookmark Window These shortcuts are for working with bookmarks, either in the Bookmarks window or in the editor. For more information, see . Command Description Shortcut Edit.ClearBookmarks Removes all bookmarks in all open documents. CTRL+K, CTRL+L Edit.EnableBookmark Enables bookmark usage in current document. Edit.NextBookmark Moves to the next bookmark in the document. CTRL+K, CTRL+N Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 257 Command Description Shortcut Edit.NextBookmarkInFolder If the current bookmark is in a folder, moves to the next bookmark in that folder. Bookmarks outside the folder are skipped. If the current bookmark is not in a folder, moves to the next bookmark at the same level. If the Bookmark window contains folders, bookmarks in folders are skipped. CTRL+SHIFT+K, CTRL+SHIFT+N Edit.ToggleBoomark Toggles a bookmark on the current line in the document. CTRL+K, CTRL+K View.BookmarkWindow Displays the Bookmark window. CTRL+K, CTRL +W Edit.PreviousBookmark Moves the cursor to the location of the previous bookmark. CTRL+K, CTRL+P Edit.PreviousBookmarkInFolder If the current bookmark is in a folder, moves to the previous bookmark in that folder. Bookmarks outside the folder are skipped. If the current bookmark is not in a folder, moves to the previous bookmark at the same level. If the Bookmark window contains folders, bookmarks in folders are skipped. CTRL+SHIFT+K, CTRL+SHIFT+P Debugging These shortcuts are for debugging code. Command Description Shortcut Debug.Autos Displays the Auto window, which displays variables used in the current line of code and the previous line of code. CTRL+ALT+V, A Debug.BreakAll Temporarily stops execution of all processes in a debugging session. Available only in Run mode. CTRL+F5 Debug.BreakatFunction Displays the New Breakpoint dialog box. CTRL+B Debug.Breakpoints Displays the Breakpoints dialog box, where you can add, remove, and modify breakpoints. ALT+F9 or CTRL +ALT+B Debug.CallStack Displays the Call Stack window, which displays a list of all active methods or stack frames for the current thread of execution. ALT+7 or CTRL +ALT+C Debug.DeleteAllBreakpoints Clears all the breakpoints in the project. CTRL+SHIFT+F9 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 258 Command Description Shortcut Debug.Disassembly Displays the Disassembly window. CTRL+ALT+D or ALT+8 Debug.EnableBreakpoint Toggles the breakpoint between disabled and enabled. CTRL+F9 Debug.Exceptions Displays the Exceptions dialog box. CTRL+ALT+E Debug.Immediate Displays the Immediate window, where expressions can be evaluated. CTRL+ALT+I Debug.Locals Displays the Locals window, which displays the local variables and their values for each method in the current stack frame. ALT+4 or CTRL +ALT+V, L Debug.Memory1 Displays the Memory 1 window to view large buffers, strings, and other data that do not display clearly in the Watch or Variables windows. CTRL+ALT+M, 1 Debug.Memory2 Displays the Memory 2 window to view large buffers, strings, and other data that do not display clearly in the Watch or Variables windows. CTRL+ALT+M, 2 Debug.Memory3 Displays the Memory 3 window to view large buffers, strings, and other data that do not display clearly in the Watch or Variables windows. CTRL+ALT+M, 3 Debug.Memory4 Displays the Memory 4 window to view large buffers, strings, and other data that do not display clearly in the Watch or Variables windows. CTRL+ALT+M, 4 Debug.Modules Displays the Modules window, which lets you view the .dll or .exe files that are used by the program. In multiprocess debugging, you can right-click and then click Show Modules for all Programs. CTRL+ALT+U Debug.ParallelStacks Opens the Parallel Stacks window. CTRL+SHIFT+D, S Debug.ParallelTasks Opens the Parallel Tasks window. CTRL+SHIFT+D, K Debug.Processes Displays the Processes window. Available in Run mode. CTRL+ALT+Z Debug.QuickWatch Displays the QuickWatch dialog box that has the current value of the selected expression. Available only in Break mode. Use this command to examine the current value of a variable, property, or other expression for which you have not defined a watch expression. CTRL+ALT+Q or SHIFT+F9 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 259 Command Description Shortcut Debug.Registers Displays the Registers window, which displays registers content for debugging native code applications. ALT+5 or CTRL +ALT+G Debug.RunToCursor In Break mode, resumes execution of your code from the current statement to the selected statement. The Current Line of Execution margin indicator appears in the Margin Indicator bar. In Design mode, starts the debugger and executes your code to the pointer location. CTRL+F10 Debug.Start Launches the application under the debugger based off of the settings from the start-up project. When in Break mode, invoking this command will run the application until the next breakpoint. F5 Debug.StepInto Executes code one statement at a time, following execution into method calls. F11 Debug.StepIntoCurrentProcess Available from the Processes window. CTRL+ALT+F11 Debug.StepOver Sets the execution point to the line of code you select. F10 Debug.StopDebugging Stops running the current application under the debugger. CTRL+SHIFT+F5 Debug.Threads Displays the Threads window to view the running threads. CTRL+ALT+H Debug.ToggleBreakpoint Sets or removes a breakpoint at the current line. F9 Debug.Watch1 Displays the Watch window, which displays the values of selected variables or watch expressions. CTRL+ALT+W, 1 Debug.Watch2 Displays the Watch2 window to view the values of selected variables or watch expressions. CTRL+ALT+W, 2 Debug.Watch3 Displays the Watch3 window to view the values of selected variables or watch expressions. CTRL+ALT+W, 3 Debug.Watch4 Displays the Watch4 window to view the values of selected variables or watch expressions. CTRL+ALT+W, 4 Help These shortcuts are for viewing topics in Help and moving among them. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 260 Command Description Shortcut Help.F1Help Displays a topic from Help that corresponds to the user interface that has focus. F1 Help.ManageHelpSettings Displays the Help Library Manager. CTRL+ALT+F1 Help.WindowHelp Displays a topic from Help that corresponds to the user interface that has focus. SHIFT+F1 Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 261 10. Command Line Utility (CLI) Atmel Studio comes with a command line software utility called atprogram.exe. Tip:  You can start a command shell with the PATH set up to run atprogram by clicking on Start > All Programs > Atmel AVR Tools > Atmel Studio 6.2 Command Prompt as shown in the figure below. atprogram.exe can be used to: • Program a .bin .hex or .elf file to a device • Verify that the programming was correct • Read, write, and erase the device memories • Program fuses, lock bits, security bits, user page, and user signature • Program a production file to a device 6 • List out all connected tools • Set interface and interface clock speeds To get help on how to use the utility, execute: atprogram.exe. This will print out the atprogram CLI help text on stdout. 6 The ELF production file format can hold the contents of both Flash, EEPROM and User Signatures (XMEGA devices only) as well as the Fuse- LockBit configuration in one single file. The format is based on the Executable and Linkable Format (ELF). The production file format is currently supported for tinyAVR, megaAVR, and XMEGA. See Creating ELF Files with Other Memory Types for description on how to configure the project in order to generate such files. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 262 11. Frequently Asked Questions Frequently asked questions about Atmel Studio. What is the Atmel USB Driver? The Atmel USB Driver is a cumulative installer that bundles the Jungo USB driver for the AVR tools and the Segger USB Driver for SAM tools. I get an error during installation of the Atmel USB Driver Package. During installation of the Atmel USB Driver Package, you might get the error 0x800b010a - A certificate chain could not be built to a trusted root authority. This means that the certificate that signs the installer could not be validated using the certificate authority built in to Windows. The reason for not being able to validate the certificate is because the certificate chain needs to be updated through Windows Update. Make sure that you have received all updates, so that Windows is able to validate the certificate. If you are not able to update your computer due to the computer being offline or restricted in some way, then the root certificate update can be downloaded from http://support2.microsoft.com/kb/931125. Will Atmel Studio work in parallel with older versions of Atmel Studio, AVR Studio, and AVR32 Studio? Yes, it will work side by side between major and minor versions. Side by side installation with different build numbers are not possible. If you are uninstalling AVR Studio 4.0 or AVR32 Studio be careful when you manually delete folders or registry entries after uninstall, as there might be other keys and folders deployed by Atmel Studio inside the Atmel folder and registry paths. Note that drivers may be incompatible between versions. I have AVR Studio 4 in my PC. When installing Atmel Studio it updated the Jungo USB driver. Will AVR Studio 4 still work? Yes, it will work. If Jungo driver is already present and its version is anything less than the new one, then the installer will update the Jungo driver you already have. The newest Jungo USB driver (version 12) breaks compatibility with older versions. See KB: Downgrading tools for how to switch between Jungo versions. Atmel Studio cannot find any debuggers or programmers when Norton AntiVirus is running. Atmel Studio might not show any connected tools if Norton AntiVirus is running. To make it work make sure Norton AntiVirus allows atprogram.exe to communicate with Atmel Studio by adding atbackend.exe as an exception in the Norton AntiVirus allowed programs. This is the same with any anti-virus program that by default blocks ports. Windows shows a message box with the following message when attempting to run Atmel Studio installer: "Windows cannot access the specified device, path or file. You may not have the appropriate permissions to access the item. " This might be caused by an anti-virus program blocking the installation of the Atmel Studio. We have seen this with the Sophos antivirus package. Temporarily disable the Sophos service running on the machine (or any corresponding anti-virus service), and attempt installation. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 263 Atmel Studio takes a very long time to start, but runs well in a VM environment. The Visual Studio shell (and thus Atmel Studio) does a considerable amount of processing during start-up. Parts of the operations are WPF operations which benefits greatly by updated graphics libraries and drivers. Installing the latest graphics driver may give a performance boost both during normal operation and during start-up. Verification and programming often fails with a serial port buffer overrun error message when using STK500. This is a known issue. Due to DPC latency, serial communication can have buffer overruns on the UART chipset. A workaround which works for most systems is to use an USB to serial adapter. When launching from a guest account, the following error is displayed when starting Atmel Studio: "Exception has been thrown by the target of an invocation". Atmel Studio neither installs under guest account and nor runs under it. Can install and run Atmel Studio from within a Virtual Machine. Yes, with simulator there should be no issues. However with physical devices like debuggers and programmers, the VM must offer support for physical USB and Serial port connections. How can I reduce the startup time of Atmel Studio? • Make sure you have uninstalled unwanted extensions • Disable Allow Add-in components to load: 2.1. Go to Tools, Options, Add-in/Macro Security. 2.2. Then uncheck the Allow Add-in components to load option. • Disable the start-up page: 3.1. Go to Tools, Options, Environment, Startup, At Startup. 3.2. Select the Show empty environment option. How to improve studio performance for any supported version of Windows? • Make sure your system has the latest version of the Windows Automation API • Exclude the following directories and files from your antivirus scanner: – The Atmel Studio installation directory, and all files and folders inside it – %AppData%\Roaming\Atmel directory, and all files and folders inside it – %AppData%\Local\Atmel directory, and all files and folders inside it – Your project directories • Visual Studio Shell requires a lot of swap space. Increase the paging file. Also put the system to maximize performance. Both options are found in the System, Properties, Performance, Settings menu. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 264 Should I install the latest Windows Automation API 3.0? Yes, if your OS is any of the following: • Windows Server 2008 How can I make sure my system has the latest Windows Automation API 3.0? Your system has the latest Windows Automation API if you have Windows 7 or Windows 8. Only Windows XP, Windows Vista, Windows Server 2003, and Windows Server 2008 have the old version of the API. Find the UIAutomationCore.dll file in your system (normally found in the windows folder) and compare the version number of that file. The version should be 7.X.X.X. for the new API. The latest API can be found at http://support.microsoft.com/kb/971513. My Project is large and it takes a long time to open. Is there any option to avoid this delay? Visual Assist X parses all the files when we opening the existing project. You could disable this option: 1. Go to VAssistX, Visual Assist X Options, Performance. 2. Uncheck the Parse all files when opening the project. I have the limited RAM size in my system and I work long hours in the same instance of Atmel Studio. After some time, Atmel Studio becomes slow on my system. Press Ctrl+Shift+Alt+F12 twice to force Atmel Studio to garbage collect. Does Atmel Studio perform better on multi-core processors than on singlecore systems? Yes, Atmel Studio performs better on a multi-core system. How can I make my projects build faster? You can enable parallel build Option from Tools, Options, Builder, GNU Make, Make Parallel Execution Of Build. This option will enable the parallel execution feature in the GNU make utility. This option may cause the build log to be displayed unordered. 11.1. Compatibility with Legacy AVR Software and Third-party Products 11.1.1. How do I Import External ELF Files for Debugging? Use the File → Open object file for debugging. 11.1.2. How do I Reuse My AVR Studio 4 Projects with the New Atmel Studio? 1. Click the menu File→Import AVR Studio 4 project. 2. An "Import AVR Studio 4 Project" dialog will appear. 3. Type in the name of your project or browse to the project location by clicking the Browse button of the APFS File location Tab. 4. Name the new solution resulting from the conversion of your project in the Solution Folder Tab. 5. Click Next. 6. Atmel Studio will proceed with conversion. Depending on the complexity and specificity of your project there might be some warnings and errors. They will be shown in the Summary window. 7. Click Finish to access your newly converted project. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 265 11.2. Atmel Studio Interface 11.2.1. How can I Start Debugging My Code? What is the Keyboard Shortcut for Debugging? Unlike the AVR Studio 4 to build your project, without starting debugging, you should press F7. If you need to rebuild your project after a change to the source files, press Ctrl Alt F7 . To Start debugging - press F5. To open the Debugging Interface without running directly, press the Debug→Start Debugging and Break menu button, or press F11. To start a line-by-line debugging press F10, to start an instruction by instruction debugging session - press F11. To run your project without debugging, press the Debug→Start Without Debugging menu button. 11.2.2. What is a Solution? A solution is a structure for organizing projects in Atmel Studio. The solution maintains the state information for projects in .sln (text-based, shared) and .suo (binary, user-specific solution options) files. 11.2.3. What is a Project A project is a logic folder that contains references to all the source files contained in your project, all the included libraries and all the built executables. Projects allow seamless reuse of code and easy automation of the build process for complex applications. 11.2.4. How can I use an External Makefile for my Project? The usage of external makefiles and other project options can be configured in the project properties. Remember that an external makefile has to contain the rules needed by Atmel Studio to work. 11.2.5. When Watching a Variable, the Debugger says Optimized away Most compilers today are what is known as an optimizing compiler. This means that the compiler will employ a number of tricks to reduce the size of your program, or speed it up. Note:  This behavior is usually controlled by the -On switches. The cause of this error is usually trying to debug parts of code that does nothing. Trying to watch the variable a in the following example may cause this behavior. int main() { int a = 0; while (a < 42) { a += 2; } } The reason for a to be optimized away is obvious as the incrementation of a does not affect any other part of our code. This example of a busy wait loop is a prime example of unexpected behavior if you are unaware of this fact. To fix this, either lower the optimization level used during compilation, or preferably declare a as volatile. Other situations where a variable should be declared volatile is if some variable is shared between the code and a ISR7 . For a thorough walk through of this issue, have a look at Cliff Lawsons excellent tutorial on this issue. 7 Interrupt Service Routine Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 266 11.2.6. When Starting a Debug Session, I get an Error Stating that Debug Tool is not Set The reason for this message is that there are no tool capable to debug that are selected for your project. Go to the Tool project pane and change the to a supported tool. If the tool you have selected does support debug, then check that the correct interface is chosen and that the frequency is according to the specification. If the issue persist, try to lower the frequency to a frequency where programming is stable, and then slowly increase the frequency as long as it keeps stable. 11.3. Performance Issues 11.3.1. Atmel Studio Takes a Very Long Time to Start on My PC, but Runs Well in a VM Environment. Is there Something I Can do With This? Visual Studio shell (and thus Atmel Studio) uses WPF as a graphics library and does a lot of processing in the GUI thread. WPF has support for hardware acceleration. Some graphics card drivers does not utilize this well and spend time in kernel space even when no graphics update is required. Installing the latest graphics driver may give a performance boost. 11.3.2. Verification and Programming often Fails with a Serial Port Buffer Overrun Error Message when using STK500 This is a known issue. Interrupt DPC latency for serial communication may be disrupted by other drivers, thus causing buffer overruns on the UART chipset. A workaround which works for most systems is to use a USB to serial adapter. 11.3.3. I've connected my Tool through a USB Hub, and now I get Error Messages and Inconsistent Results while Programming and Debugging Tools and devices should be connected directly to an USB port on your debugging PC. If this is not an option, you may reduce/eliminate problems by: • Disconnect any other USB devices connected to the hub • Switch ports on the USB hub • Set the tool clock frequency low. E.g. Set JTAG Clock < 600kHz. • If Use external reset is an option for your tool/device combination, enable this Note:  The AVR Dragon should be connected through a powered USB hub. This because the power supply on the Dragon can be too weak if the motherboard does not provided enough power. If the Dragon times out or freezes, then the hub might be of to low quality. 11.4. Driver and USB Issues 11.4.1. How do I get my Tool to be Recognized by Atmel Studio? This should happen automatically, but sometimes the Windows driver does not recognize the tool correctly. To correct this, you have to check that the tool is listed under the Jungo item in the device manager in Windows. If your tool is not listed, try to find it under Unknown devices. If it is located there, try to reinstall the driver by double clicking the tool, click the Driver tab and choose Update Driver. Let Windows search for the driver. The driver should be reinstalled and the tool should be displayed under Jungo. Now, the tool should be usable from Atmel Studio. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 267 11.4.2. The Firmware upgrade Process fails or is Unstable on a Virtualized Machine Most tools will perform a reset when asked to switch from normal operation mode to firmware upgrade mode. This forces the tool to re-enumerate on the USB bus, and the virtualization software may not reattach to it making your virtualized system with a disconnected tool. Normal virtualization software supports the idea of USB filters where you set a collection of USB devices you want to automatically attach to a given guest operating system. Check the manual for your virtualization solution to see how this is done, or see the Firmware Upgrade Fails on VirtualBox. 11.4.3. Debugging never Breaks under a Virtualized Machine Some virtualization solutions have a limit on how many USB endpoints it supports. This may become an issue if the number of endpoints is lower than the required number for the tool. Usually this causes programming to work as expected but debug not to work as debug events are transmitted on a higher endpoint number. Check with your virtualization software how many endpoints are available, and on other endpoint specific issues with your virtualization software regarding this. 11.4.4. No Tool is recognized by Atmel Studio, but the Driver seems to be Working On some systems the Jungo driver is known not to activate properly. This can be seen as the WinDriver unit under Jungo in the device manager in Windows is missing. To remedy this, try the following: 1. In your Device Manager, right click on your computer name (the very top item) and choose Add Legacy Hardware. 2. Click next, and choose to install the hardware manually. 3. Choose the Show All Devices item on the top of the list, and click next. 4. Click the Have Disk button. 5. Navigate to the folder Atmel USB which is located under the install directory for Atmel Studio (typical location is C:\Program Files (x86)\Atmel\Atmel USB. 6. Choose the usb32 or usb64 folder depending on the architecture you are running. 7. Inside there should be only one file named windrvr#.inf, where the hash is the revision number for the driver. Double click this, click OK, and the WinDriver should appear in the list. If you get an error message, you probably have chosen the wrong architecture. 8. Click Next until finished. 9. Verify that the WinDriver has appeared under Jungo. The tools should be working straight away, but you may have to restart your machine if you are still having problems. 11.4.5. Firmware Upgrade Fails on VirtualBox When doing a firmware upgrade on any tool, the tool needs to be reconnected in another mode than the one used during regular operation. This causes the tool to be re-enumerated, and can cause the tool to be disconnected from the VirtualBox instance and returned to the host operating system. To make the tool connect automatically to the VirtualBox instance, you need to set up a couple of USB filters. More information on USB filters can be found in the VirtualBox documentation. Make two filters that are similar to the two shown in the figure below. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 268 Figure 11-1. VirtualBox USB Filter Note that the example in the figure above is specific for the JTAGICE mkII. There are one entry for the tool, here the JTAGICE mkII, and one for AVRBLDR, which is the firmware upgrade mode for the tool. The name, serial, Vendor ID, and Product ID may be different for your tool, so change those values accordingly. Note:  This section contains specifics to VirtualBox. The same logic applies to other virtualization software, but the steps may differ. 11.4.6. Common Jungo USB Errors Jungo is the driver stack that is used for older programmers and debuggers, up to the JTAGICE3. Common Jungo USB Error Codes Table 11-1. Common Jungo USB Errors Error Cause Resolution Internal system error USB subsystem malfunctions Reinstall driver and check Driver and USB Issues page Conflict between read and write operations Directional error in data Disconnect and reconnect the tool Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 269 Error Cause Resolution Data mismatch Expected and received/sent data error Make sure that you use the latest driver for your USB controller and the latest firmware for your tool Packet size is zero Sent or received a zero packet Insufficient resources Unable to set up send/receive buffers due to memory limitation Free more memory or try to restart your machine USB descriptor error Error in control data on USB bus Try connection tool to another USB port Wrong unique ID Device not found Wrong unique ID Timeout expired Error Cause Resolution 11.4.7. Issues with ARM Compatible Tools In some rare instances all ARM compatible tools disappears from Atmel Studio. This has been tracked down to different dll load strategies used in different versions of Windows. To check that it is a dll load error, try to read out the chip information using atprogram. This can be done by opening the Atmel Studio command prompt from the Tools menu inside Atmel Studio or from the start menu. In the command prompt, enter the following command and check that it does not fail. atprogram -t -i -d info In the snippet above, replace with the tool name, e.g. atmelice, samice, or edbg. Likewise, replace interface with the used interface and the device with the full device name, e.g. atsam3s4c. Invoking the above command should output information about the memory layout, the supply voltage for the chip, and the fuse settings. If it fails it is likely a driver issue, which is covered by Driver and USB Issues. If atprogram is able to communicate with the device it means that the issue is most likely a wrong version of JLinkArm.dll being loaded due to loader precedence. To check this, use the Procmon tool to check what dll is being loaded. Download the Procmon tool, open it, and configure the filter shown in the figure below. Then start Atmel Studio. A couple of seconds after Atmel Studio has started, one line should become visible showing the path to where the dll is being loaded from. It should be loaded from the atbackend folder inside the Atmel Studio installation directory. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 270 Figure 11-2. Procmon Filter Configuration If the path of the dll is different it means that Atmel Studio has picked up the wrong dll, and this dll is incompatible with the dll shipped with Atmel Studio. An example of this is shown in the figure below. Figure 11-3. Procmon Filter Configuration To solve the above issue, we recommend backing up the dll that is being loaded and then replacing it with the JLinkARM.dll found in the atbackend directory inside the Atmel Studio installation directory. This can be done given the assumption that the dll bundled with Atmel Studio is newer than the one that is being loaded, and the dll is backwards compatible. Note:  Remember to back up the offending JLinkARM.dll before replacing it, as it is not given that it will be compatible with the program that deployed it. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 271 12. Document Revision History Doc Rev. Date Comments 42167B 09/2016 Section "Power Debugger" is added 42167A 07/2016 Initial document release. Atmel Atmel Studio [USER GUIDE] Atmel-42167B-Atmel-Studio_User Guide-09/2016 272 Index A AsmToolchainOptions 3, 60 Atmel Studio 1 AVR Studio 1 C Choose file 201 D Device selection 26, 33 T ToolchainOptions 5, 163, 173 Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 | www.atmel.com © 2016 Atmel Corporation. / Rev.: Atmel-42167B-Atmel-Studio_User Guide-09/2016 Atmel® , Atmel logo and combinations thereof, Enabling Unlimited Possibilities® , AVR® , megaAVR® , STK® , tinyAVR® , XMEGA® , and others are registered trademarks or trademarks of Atmel Corporation in U.S. and other countries. ARM® , ARM Connected® logo, Cortex® , and others are the registered trademarks or trademarks of ARM Ltd. Windows® is a registered trademark of Microsoft Corporation in U.S. and or other countries. Other terms and product names may be trademarks of others. DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life. SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments unless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specifically designated by Atmel as automotive-grade.

Atmel-8291C-AVR-XMEGA B -09/2014 This document contains complete and detailed description of all modules included in the Atmel®AVR®XMEGA® B microcontroller family. The Atmel AVR XMEGA B is a family of lowpower, high-performance, and peripheral-rich CMOS 8/16-bit microcontrollers based on the AVR enhanced RISC architecture with integrated LCD controller. The available Atmel AVR XMEGA B modules described in this manual are: z Atmel AVR CPU z Memories z DMAC - Direct memory access controller z Event system z System clock and clock options z Power management and sleep modes z System control and reset z WDT - Watchdog timer z Interrupts and programmable multilevel interrupt controller z PORT - I/O ports z TC - 16-bit timer/counters z AWeX - Advanced waveform extension z Hi-Res - High resolution extension z RTC - Real-time counter z USB - Universal serial bus interface z TWI - Two-wire serial interface z SPI - Serial peripheral interface z USART - Universal synchronous and asynchronous serial receiver and transmitter z IRCOM - Infrared communication module z AES and DES cryptographic engine z CRC - Cyclic redundancy check z LCD - Liquid Crystal Display controller z ADC - Analog-to-digital converter z AC - Analog comparator z IEEE 1149.1 JTAG interface z PDI - Program and debug interface z Memory programming z Peripheral address map z Register summary z Interrupt vector summary z Instruction set summary 8-bit Atmel XMEGA B Microcontroller XMEGA B MANUAL XMEGA B [MANUAL] 2 Atmel-8291C-AVR-XMEGA B -09/2014 1. About the Manual This document contains in-depth documentation of all peripherals and modules available for the Atmel AVR XMEGA B microcontroller family. All features are documented on a functional level and described in a general sense. All peripherals and modules described in this manual may not be present in all Atmel AVR XMEGA B devices. For all device-specific information such as characterization data, memory sizes, modules, peripherals available and their absolute memory addresses, refer to the device datasheets. When several instances of a peripheral exists in one device, each instance will have a unique name. For example each port module (PORT) have unique name, such as PORTA, PORTB, etc. Register and bit names are unique within one module instance. For more details on applied use and code examples for peripherals and modules, refer to the Atmel AVR XMEGA specific application notes available from http://www.atmel.com/avr. 1.1 Reading the Manual The main sections describe the various modules and peripherals. Each section contains a short feature list and overview describing the module. The remaining section describes the features and functions in more detail. The register description sections list all registers and describe each register, bit and flag with their function. This includes details on how to set up and enable various features in the module. When multiple bits are needed for a configuration setting, these are grouped together in a bit group. The possible bit group configurations are listed for all bit groups together with their associated Group Configuration and a short description. The Group Configuration refers to the defined configuration name used in the Atmel AVR XMEGA assembler header files and application note source code. The register summary sections list the internal register map for each module type. The interrupt vector summary sections list the interrupt vectors and offset address for each module type. 1.2 Resources A comprehensive set of development tools, application notes, and datasheets are available for download from http://www.atmel.com/avr. 1.3 Recommended Reading z Atmel AVR XMEGA B device datasheets z AVR XMEGA application notes This manual contains general modules and peripheral descriptions. The AVR XMEGA B device datasheets contains the device-specific information. The XMEGA application notes and Atmel Software Framework contain example code and show applied use of the modules and peripherals. For new users, it is recommended to read the AVR1000 - Getting Started Writing C Code for Atmel XMEGA. XMEGA B [MANUAL] 3 Atmel-8291C-AVR-XMEGA B -09/2014 2. Overview The AVR XMEGA B microcontrollers is a family of low-power, high-performance, and peripheral-rich CMOS 8/16-bit microcontrollers based on the AVR enhanced RISC architecture. By executing powerful instructions in a single clock cycle, the Atmel AVR XMEGA B devices achieve throughputs approaching one million instructions per second (MIPS) per megahertz, allowing the system designer to optimize power consumption versus processing speed. The AVR CPU combines a rich instruction set with 32 general purpose working registers. All 32 registers are directly connected to the arithmetic logic unit (ALU), allowing two independent registers to be accessed in a single instruction, executed in one clock cycle. The resulting architecture is more code efficient while achieving throughputs many times faster than conventional single-accumulator or CISC based microcontrollers. The Atmel AVR XMEGA B devices provide the following features: in-system programmable flash with read-while-write capabilities; internal EEPROM and SRAM; two-channel DMA controller; four-channel event system and programmable multilevel interrupt controller; up to 53 general purpose I/O lines; 16-bit real-time counter (RTC); up to three flexible 16-bit timer/counters with capture, compare and PWM modes; up to two USARTs; one I2 C and SMBUS compatible two-wire serial interface (TWI); one full-speed USB 2.0 interface; one serial peripheral interface (SPI); one LCD controller supporting display capacity up to 4 Common and up to 40 Segment terminals; CRC module; AES and DES cryptographic engine; up to two 8-channel, 12-bit ADCs with programmable gain; up to four analog comparators with window mode; programmable watchdog timer with separate internal oscillator; accurate internal oscillators with PLL and prescaler; and programmable brown-out detection. The program and debug interface (PDI), a fast, two-pin interface for programming and debugging, is available. Selected devices also have an IEEE std. 1149.1 compliant JTAG interface, and this can also be used for on-chip debug and programming. The Atmel AVR XMEGA devices have five software selectable power saving modes. The idle mode stops the CPU while allowing the SRAM, DMA controller, event system, interrupt controller, and all peripherals to continue functioning. The power-down mode saves the SRAM and register contents, but stops the oscillators, disabling all other functions until the next TWI, USB resume, or pin-change interrupt, or reset. In power-save mode, the asynchronous real-time counter continues to run, allowing the application to maintain a timer base while the rest of the device is sleeping. In this mode, the LCD controller is allowed to refresh data to the panel. In standby mode, the external crystal oscillator keeps running while the rest of the device is sleeping. This allows very fast startup from the external crystal, combined with low power consumption. In extended standby mode, both the main oscillator and the asynchronous timer continue to run. In this mode, the LCD controller is allowed to refresh data to the panel. To further reduce power consumption, the peripheral clock to each individual peripheral can optionally be stopped in active mode and idle sleep mode. The devices are manufactured using Atmel high-density, nonvolatile memory technology. The program flash memory can be reprogrammed in-system through the PDI or JTAG interfaces. A boot loader running in the device can use any interface to download the application program to the flash memory. The boot loader software in the boot flash section will continue to run while the application flash section is updated, providing true read-while-write operation. By combining an 8/16-bit RISC CPU with In-system, self-programmable flash, the Atmel AVR XMEGA is a powerful microcontroller family that provides a highly flexible and cost effective solution for many embedded applications. The Atmel AVR XMEGA B devices are supported with a full suite of program and system development tools, including C compilers, macro assemblers, program debugger/simulators, programmers, and evaluation kits. XMEGA B [MANUAL] 4 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 2-1. Atmel AVR XMEGA B block diagram. In Table 2-1 on page 5 a feature summary for the XMEGA B family is shown, split into one feature summary column for each sub-family. Each sub-family has identical feature set, but different memory options, refer to their device datasheet for ordering codes and memory options. Power Supervision POR/BOD & RESET PORT A (8) PORT B (8) EVENT ROUTING NETWORK DMA Controller BUS Matrix SRAM ADCA ACA ADCB ACB OCD PORT M (8) PDI SEG[31..24] / PM[0..7] SEG[0..23] COM[0..3] PA[0..7] PB[0..7]/ JTAG Watchdog Timer Watchdog Oscillator Interrupt Controller DATA BUS Prog/Debug Controller VCC GND PORT R (2) PR[0..1] Oscillator Control Real Time Counter Event System Controller JTAG PDI_DATA RESET / PDI_CLK PORT B Sleep Controller DES CRC IRCOM PORT G (8) SEG[39..32] / PG[0..7] LCD POWER[0..4] PORT C (8) PC[0..7] TCC0:1 USARTC0 SPIC TWIC PD[0..2] PE[0..7] PORT D (3) TCE0 USARTE0 PORT E (8) USB EVENT ROUTING NETWORK AES Int. Refs. AREFA AREFB Tempref VCC/10 CPU NVM Controller Flash EEPROM DATA BUS LCD TOSC1 TOSC2 To Clock Generator XTAL2 / TOSC2 XTAL1 / TOSC1 Oscillator Circuits/ Clock Generation (Alternate) Digital function Analog function / Oscillators Programming, debug, test External clock / Crystal pins General Purpose I/O Ground Power LCD XMEGA B [MANUAL] 5 Atmel-8291C-AVR-XMEGA B -09/2014 Table 2-1. XMEGA B feature summary overview. Feature Details / sub-family B1 B3 Pins, I/O Total 100 64 Programmable I/O pins 53 36 Memory Program memory (KB) 64 - 128 64 - 128 Boot memory (KB) 4 - 8 4 - 8 SRAM (KB) 4 - 8 4 - 8 EEPROM 2 2 - 4 General purpose registers 16 16 Package TQFP 100A 64A QFN /VQFN – 64M2 BGA 100C1/100C2 – QTouch Sense channels 56 56 DMA Controller Channels 2 2 Event System Channels 4 4 QDEC 1 1 Crystal Oscillator 0.4 - 16MHz XOSC Yes Yes 32.768 kHz TOSC Yes Yes Internal Oscillator 2MHz calibrated Yes Yes 32MHz calibrated Yes Yes 128MHz PLL Yes Yes 32.768kHz calibrated Yes Yes 32kHz ULP Yes Yes Timer / Counter TC0 - 16-bit, 4 CC 2 1 TC1 - 16-bit, 2 CC 1 1 TC2 - 2x 8-bit 2 1 Hi-Res 1 1 AWeX 1 1 RTC 1 1 RTC32 Serial Communication USB full-speed device 1 1 USART 2 1 SPI 1 1 TWI 1 1 XMEGA B [MANUAL] 6 Atmel-8291C-AVR-XMEGA B -09/2014 Crypto /CRC AES-128 Yes Yes DES Yes Yes CRC-16 Yes Yes CRC-32 Yes Yes Liquid Crystal Display Controller (LCD) Segments 40 25 Common terminals 4 4 Analog to Digital Converter (ADC) 2 1 Resolution (bits) 12 12 Sampling speed (kbps) 300 300 Input channels per ADC 16 8 Conversion channels 1 1 Analog Comparator (AC) 4 2 Program and Debug Interface PDI Yes Yes JTAG Yes Yes Boundary scan Yes Yes Feature Details / sub-family B1 B3 XMEGA B [MANUAL] 7 Atmel-8291C-AVR-XMEGA B -09/2014 3. Atmel AVR CPU 3.1 Features z 8/16-bit, high-performance Atmel AVR RISC CPU z 142 instructions z Hardware multiplier z 32x8-bit registers directly connected to the ALU z Stack in RAM z Stack pointer accessible in I/O memory space z Direct addressing of up to 16MB of program memory and 16MB of data memory z True 16/24-bit access to 16/24-bit I/O registers z Efficient support for 8-, 16-, and 32-bit arithmetic z Configuration change protection of system-critical features 3.2 Overview All Atmel AVR XMEGA devices use the 8/16-bit AVR CPU. The main function of the CPU is to execute the code and perform all calculations. The CPU is able to access memories, perform calculations, control peripherals, and execute the program in the flash memory. Interrupt handling is described in a separate section, “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. 3.3 Architectural Overview In order to maximize performance and parallelism, the AVR CPU uses a Harvard architecture with separate memories and buses for program and data. Instructions in the program memory are executed with single-level pipelining. While one instruction is being executed, the next instruction is pre-fetched from the program memory. This enables instructions to be executed on every clock cycle. For a summary of all AVR instructions, refer to “Instruction Set Summary” on page 395. For details of all AVR instructions, refer to http://www.atmel.com/avr. Figure 3-1. Block diagram of the AVR CPU architecture. XMEGA B [MANUAL] 8 Atmel-8291C-AVR-XMEGA B -09/2014 The arithmetic logic unit (ALU) supports arithmetic and logic operations between registers or between a constant and a register. Single-register operations can also be executed in the ALU. After an arithmetic operation, the status register is updated to reflect information about the result of the operation. The ALU is directly connected to the fast-access register file. The 32 x 8-bit general purpose working registers all have single clock cycle access time allowing single-cycle arithmetic logic unit operation between registers or between a register and an immediate. Six of the 32 registers can be used as three 16-bit address pointers for program and data space addressing, enabling efficient address calculations. The memory spaces are linear. The data memory space and the program memory space are two different memory spaces. The data memory space is divided into I/O registers, SRAM, and external RAM. In addition, the EEPROM can be memory mapped in the data memory. All I/O status and control registers reside in the lowest 4KB addresses of the data memory. This is referred to as the I/O memory space. The lowest 64 addresses can be accessed directly, or as the data space locations from 0x00 to 0x3F. The rest is the extended I/O memory space, ranging from 0x0040 to 0x0FFF. I/O registers here must be accessed as data space locations using load (LD/LDS/LDD) and store (ST/STS/STD) instructions. The SRAM holds data. Code execution from SRAM is not supported. It can easily be accessed through the five different addressing modes supported in the AVR architecture. The first SRAM address is 0x2000. Data addresses 0x1000 to 0x1FFF are reserved for memory mapping of EEPROM. The program memory is divided in two sections, the application program section and the boot program section. Both sections have dedicated lock bits for write and read/write protection. The SPM instruction that is used for selfprogramming of the application flash memory must reside in the boot program section. The application section contains an application table section with separate lock bits for write and read/write protection. The application table section can be used for save storing of nonvolatile data in the program memory. 3.4 ALU - Arithmetic Logic Unit The arithmetic logic unit supports arithmetic and logic operations between registers or between a constant and a register. Single-register operations can also be executed. The ALU operates in direct connection with all 32 general purpose registers. In a single clock cycle, arithmetic operations between general purpose registers or between a register and an immediate are executed and the result is stored in the register file. After an arithmetic or logic operation, the status register is updated to reflect information about the result of the operation. ALU operations are divided into three main categories – arithmetic, logical, and bit functions. Both 8- and 16-bit arithmetic is supported, and the instruction set allows for efficient implementation of 32-bit arithmetic. The hardware multiplier supports signed and unsigned multiplication and fractional format. 3.4.1 Hardware Multiplier The multiplier is capable of multiplying two 8-bit numbers into a 16-bit result. The hardware multiplier supports different variations of signed and unsigned integer and fractional numbers: z Multiplication of unsigned integers z Multiplication of signed integers z Multiplication of a signed integer with an unsigned integer z Multiplication of unsigned fractional numbers z Multiplication of signed fractional numbers z Multiplication of a signed fractional number with an unsigned one A multiplication takes two CPU clock cycles. XMEGA B [MANUAL] 9 Atmel-8291C-AVR-XMEGA B -09/2014 3.5 Program Flow After reset, the CPU starts to execute instructions from the lowest address in the flash program memory ‘0.’ The program counter (PC) addresses the next instruction to be fetched. Program flow is provided by conditional and unconditional jump and call instructions capable of addressing the whole address space directly. Most AVR instructions use a 16-bit word format, while a limited number use a 32-bit format. During interrupts and subroutine calls, the return address PC is stored on the stack. The stack is allocated in the general data SRAM, and consequently the stack size is only limited by the total SRAM size and the usage of the SRAM. After reset, the stack pointer (SP) points to the highest address in the internal SRAM. The SP is read/write accessible in the I/O memory space, enabling easy implementation of multiple stacks or stack areas. The data SRAM can easily be accessed through the five different addressing modes supported in the AVR CPU. 3.6 Instruction Execution Timing The AVR CPU is clocked by the CPU clock, clkCPU. No internal clock division is used. Figure 3-2 on page 9 shows the parallel instruction fetches and instruction executions enabled by the Harvard architecture and the fast-access register file concept. This is the basic pipelining concept used to obtain up to 1MIPS/MHz performance with high power efficiency. Figure 3-2. The parallel instruction fetches and instruction executions. Figure 3-3 on page 9 shows the internal timing concept for the register file. In a single clock cycle, an ALU operation using two register operands is executed and the result is stored back to the destination register. Figure 3-3. Single Cycle ALU Operation clk 1st Instruction Fetch 1st Instruction Execute 2nd Instruction Fetch 2nd Instruction Execute 3rd Instruction Fetch 3rd Instruction Execute 4th Instruction Fetch T1 T2 T3 T4 CPU Total Execution Time Register Operands Fetch ALU Operation Execute Result Write Back T1 T2 T3 T4 clkCPU XMEGA B [MANUAL] 10 Atmel-8291C-AVR-XMEGA B -09/2014 3.7 Status Register The status register (SREG) contains information about the result of the most recently executed arithmetic or logic instruction. This information can be used for altering program flow in order to perform conditional operations. Note that the status register is updated after all ALU operations, as specified in the instruction set reference. This will in many cases remove the need for using the dedicated compare instructions, resulting in faster and more compact code. The status register is not automatically stored when entering an interrupt routine nor restored when returning from an interrupt. This must be handled by software. The status register is accessible in the I/O memory space. 3.8 Stack and Stack Pointer The stack is used for storing return addresses after interrupts and subroutine calls. It can also be used for storing temporary data. The stack pointer (SP) register always points to the top of the stack. It is implemented as two 8-bit registers that are accessible in the I/O memory space. Data are pushed and popped from the stack using the PUSH and POP instructions. The stack grows from a higher memory location to a lower memory location. This implies that pushing data onto the stack decreases the SP, and popping data off the stack increases the SP. The SP is automatically loaded after reset, and the initial value is the highest address of the internal SRAM. If the SP is changed, it must be set to point above address 0x2000, and it must be defined before any subroutine calls are executed or before interrupts are enabled. During interrupts or subroutine calls, the return address is automatically pushed on the stack. The return address can be two or three bytes, depending on program memory size of the device. For devices with 128KB or less of program memory, the return address is two bytes, and hence the stack pointer is decremented/incremented by two. For devices with more than 128KB of program memory, the return address is three bytes, and hence the SP is decremented/incremented by three. The return address is popped off the stack when returning from interrupts using the RETI instruction, and from subroutine calls using the RET instruction. The SP is decremented by one when data are pushed on the stack with the PUSH instruction, and incremented by one when data is popped off the stack using the POP instruction. To prevent corruption when updating the stack pointer from software, a write to SPL will automatically disable interrupts for up to four instructions or until the next I/O memory write. 3.9 Register File The register file consists of 32 x 8-bit general purpose working registers with single clock cycle access time. The register file supports the following input/output schemes: z One 8-bit output operand and one 8-bit result input z Two 8-bit output operands and one 8-bit result input z Two 8-bit output operands and one 16-bit result input z One 16-bit output operand and one 16-bit result input Six of the 32 registers can be used as three 16-bit address register pointers for data space addressing, enabling efficient address calculations. One of these address pointers can also be used as an address pointer for lookup tables in flash program memory. XMEGA B [MANUAL] 11 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 3-4. AVR CPU general purpose working registers. The register file is located in a separate address space, and so the registers are not accessible as data memory. 3.9.1 The X-, Y-, and Z- Registers Registers R26..R31 have added functions besides their general-purpose usage. These registers can form 16-bit address pointers for addressing data memory. These three address registers are called the X-register, Y-register, and Z-register. The Z-register can also be used as an address pointer to read from and/or write to the flash program memory, signature rows, fuses, and lock bits. Figure 3-5. The X-, Y- and Z-registers. 7 0 Addr. R0 0x00 R1 0x01 R2 0x02 … R13 0x0D General R14 0x0E Purpose R15 0x0F Working R16 0x10 Registers R17 0x11 … R26 0x1A X-register Low Byte R27 0x1B X-register High Byte R28 0x1C Y-register Low Byte R29 0x1D Y-register High Byte R30 0x1E Z-register Low Byte R31 0x1F Z-register High Byte Bit (individually) 7 R27 0 7 R26 0 X-register XH XL Bit (X-register) 15 8 7 0 Bit (individually) 7 R29 0 7 R28 0 Y-register YH YL Bit (Y-register) 15 8 7 0 Bit (individually) 7 R31 0 7 R30 0 Z-register ZH ZL Bit (Z-register) 15 8 7 0 XMEGA B [MANUAL] 12 Atmel-8291C-AVR-XMEGA B -09/2014 The lowest register address holds the least-significant byte (LSB), and the highest register address holds the mostsignificant byte (MSB). In the different addressing modes, these address registers function as fixed displacement, automatic increment, and automatic decrement (see the instruction set reference for details). 3.10 RAMP and Extended Indirect Registers In order to access program memory or data memory above 64KB, the address pointer must be larger than 16 bits. This is done by concatenating one register to one of the X-, Y-, or Z-registers. This register then holds the most-significant byte (MSB) in a 24-bit address or address pointer. These registers are available only on devices with external bus interface and/or more than 64KB of program or data memory space. For these devices, only the number of bits required to address the whole program and data memory space in the device is implemented in the registers. 3.10.1 RAMPX, RAMPY and RAMPZ Registers The RAMPX, RAMPY and RAMPZ registers are concatenated with the X-, Y-, and Z-registers, respectively, to enable indirect addressing of the whole data memory space above 64KB and up to 16MB. Figure 3-6. The combined RAMPX + X, RAMPY + Y and RAMPZ + Z registers. When reading (ELPM) and writing (SPM) program memory locations above the first 128KB of the program memory, RAMPZ is concatenated with the Z-register to form the 24-bit address. LPM is not affected by the RAMPZ setting. 3.10.2 RAMPD Register This register is concatenated with the operand to enable direct addressing of the whole data memory space above 64KB. Together, RAMPD and the operand will form a 24-bit address. Figure 3-7. The combined RAMPD + K register. Bit (Individually) 7 0 7 0 7 0 RAMPX XH XL Bit (X-pointer) 23 16 15 8 7 0 Bit (Individually) 7 0 7 0 7 0 RAMPY YH YL Bit (Y-pointer) 23 16 15 8 7 0 Bit (Individually) 7 0 7 0 7 0 RAMPZ ZH ZL Bit (Z-pointer) 23 16 15 8 7 0 Bit (Individually) 7 0 15 0 RAMPD K Bit (D-pointer) 23 16 15 0 XMEGA B [MANUAL] 13 Atmel-8291C-AVR-XMEGA B -09/2014 3.10.3 EIND - Extended Indirect Register EIND is concatenated with the Z-register to enable indirect jump and call to locations above the first 128KB (64K words) of the program memory. Figure 3-8. The combined EIND + Z register. 3.11 Accessing 16-bit Registers The AVR data bus is 8 bits wide, and so accessing 16-bit registers requires atomic operations. These registers must be byte-accessed using two read or write operations. 16-bit registers are connected to the 8-bit bus and a temporary register using a 16-bit bus. For a write operation, the low byte of the 16-bit register must be written before the high byte. The low byte is then written into the temporary register. When the high byte of the 16-bit register is written, the temporary register is copied into the low byte of the 16-bit register in the same clock cycle. For a read operation, the low byte of the 16-bit register must be read before the high byte. When the low byte register is read by the CPU, the high byte of the 16-bit register is copied into the temporary register in the same clock cycle as the low byte is read. When the high byte is read, it is then read from the temporary register. This ensures that the low and high bytes of 16-bit registers are always accessed simultaneously when reading or writing the register. Interrupts can corrupt the timed sequence if an interrupt is triggered and accesses the same 16-bit register during an atomic 16-bit read/write operation. To prevent this, interrupts can be disabled when writing or reading 16-bit registers. The temporary registers can also be read and written directly from user software. 3.11.1 Accessing 24- and 32-bit Registers For 24- and 32-bit registers, the read and write access is done in the same way as described for 16-bit registers, except there are two temporary registers for 24-bit registers and three for 32-bit registers. The least-significant byte must be written first when doing a write, and read first when doing a read. 3.12 Configuration Change Protection System critical I/O register settings are protected from accidental modification. The SPM instruction is protected from accidental execution, and the LPM instruction is protected when reading the fuses and signature row. This is handled globally by the configuration change protection (CCP) register. Changes to the protected I/O registers or bits, or execution of protected instructions, are only possible after the CPU writes a signature to the CCP register. The different signatures are described in the register description. There are two modes of operation: one for protected I/O registers, and one for the protected instructions, SPM/LPM. 3.12.1 Sequence for write operation to protected I/O registers 1. The application code writes the signature that enable change of protected I/O registers to the CCP register. 2. Within four instruction cycles, the application code must write the appropriate data to the protected register. Most protected registers also contain a write enable/change enable bit. This bit must be written to one in the same operation as the data are written. The protected change is immediately disabled if the CPU performs write operations to the I/O register or data memory or if the SPM, LPM, or SLEEP instruction is executed. Bit (Individually) 7 0 7 0 7 0 EIND ZH ZL Bit (D-pointer) 23 16 15 8 7 0 XMEGA B [MANUAL] 14 Atmel-8291C-AVR-XMEGA B -09/2014 3.12.2 Sequence for execution of protected SPM/LPM 1. The application code writes the signature for the execution of protected SPM/LPM to the CCP register. 2. Within four instruction cycles, the application code must execute the appropriate instruction. The protected change is immediately disabled if the CPU performs write operations to the data memory or if the SLEEP instruction is executed. Once the correct signature is written by the CPU, interrupts will be ignored for the duration of the configuration change enable period. Any interrupt request (including non-maskable interrupts) during the CCP period will set the corresponding interrupt flag as normal, and the request is kept pending. After the CCP period is completed, any pending interrupts are executed according to their level and priority. DMA requests are still handled, but do not influence the protected configuration change enable period. A signature written by DMA is ignored. 3.13 Fuse Lock For some system-critical features, it is possible to program a fuse to disable all changes to the associated I/O control registers. If this is done, it will not be possible to change the registers from the user software, and the fuse can only be reprogrammed using an external programmer. Details on this are described in the datasheet module where this feature is available. XMEGA B [MANUAL] 15 Atmel-8291C-AVR-XMEGA B -09/2014 3.14 Register Descriptions 3.14.1 CCP – Configuration Change Protection register z Bit 7:0 – CCP[7:0]: Configuration Change Protection The CCP register must be written with the correct signature to enable change of the protected I/O register or execution of the protected instruction for a maximum period of four CPU instruction cycles. All interrupts are ignored during these cycles. After these cycles, interrupts will automatically be handled again by the CPU, and any pending interrupts will be executed according to their level and priority. When the protected I/O register signature is written, CCP[0] will read as one as long as the protected feature is enabled. Similarly when the protected SPM/LPM signature is written, CCP[1] will read as one as long as the protected feature is enabled. CCP[7:2] will always read as zero. Table 3-1 shows the signature for the various modes. Table 3-1. Modes of CPU change protection. 3.14.2 RAMPD – Extended Direct Addressing register This register is concatenated with the operand for direct addressing (LDS/STS) of the whole data memory space on devices with more than 64KB of data memory. This register is not available if the data memory, including external memory, is less than 64KB. z Bit 7:0 – RAMPD[7:0]: Extended Direct Addressing bits These bits hold the MSB of the 24-bit address created by RAMPD and the 16-bit operand. Only the number of bits required to address the available data memory is implemented for each device. Unused bits will always read as zero. Bit 7 6 5 4 3 2 1 0 +0x04 CCP[7:0] Read/Write W W W W W W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Signature Group Configuration Description 0x9D SPM Protected SPM/LPM 0xD8 IOREG Protected IO register Bit 7 6 5 4 3 2 1 0 +0x08 RAMPD[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 16 Atmel-8291C-AVR-XMEGA B -09/2014 3.14.3 RAMPX – Extended X-Pointer register This register is concatenated with the X-register for indirect addressing (LD/LDD/ST/STD) of the whole data memory space on devices with more than 64KB of data memory. This register is not available if the data memory, including external memory, is less than 64KB. z Bit 7:0 – RAMPX[7:0]: Extended X-pointer Address bits These bits hold the MSB of the 24-bit address created by RAMPX and the 16-bit X-register. Only the number of bits required to address the available data memory is implemented for each device. Unused bits will always read as zero. 3.14.4 RAMPY – Extended Y-Pointer register This register is concatenated with the Y-register for indirect addressing (LD/LDD/ST/STD) of the whole data memory space on devices with more than 64KB of data memory. This register is not available if the data memory, including external memory, is less than 64KB. z Bit 7:0 – RAMPY[7:0]: Extended Y-pointer Address bits These bits hold the MSB of the 24-bit address created by RAMPY and the 16-bit Y-register. Only the number of bits required to address the available data memory is implemented for each device. Unused bits will always read as zero. 3.14.5 RAMPZ – Extended Z-Pointer register This register is concatenated with the Z-register for indirect addressing (LD/LDD/ST/STD) of the whole data memory space on devices with more than 64KB of data memory. RAMPZ is concatenated with the Z-register when reading (ELPM) program memory locations above the first 64KB and writing (SPM) program memory locations above the first 128KB of the program memory. This register is not available if the data memory, including external memory and program memory in the device, is less than 64KB. z Bit 7:0 – RAMPZ[7:0]: Extended Z-pointer Address bits These bits hold the MSB of the 24-bit address created by RAMPZ and the 16-bit Z-register. Only the number of bits required to address the available data and program memory is implemented for each device. Unused bits will always read as zero. Bit 7 6 5 4 3 2 1 0 +0x09 RAMPX[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0A RAMPY[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 Bit 7 6 5 4 3 2 1 0 +0x0B RAMPZ[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 17 Atmel-8291C-AVR-XMEGA B -09/2014 3.14.6 EIND – Extended Indirect register This register is concatenated with the Z-register for enabling extended indirect jump (EIJMP) and call (EICALL) to the whole program memory space on devices with more than 128KB of program memory. The register should be used for jumps to addresses below 128KB if ECALL/EIJMP are used, and it will not be used if CALL and IJMP commands are used. For jump or call to addresses below 128KB, this register is not used. This register is not available if the program memory in the device is less than 128KB. z Bit 7:0 – EIND[7:0]: Extended Indirect Address bits These bits hold the MSB of the 24-bit address created by EIND and the 16-bit Z-register. Only the number of bits required to access the available program memory is implemented for each device. Unused bits will always read as zero. 3.14.7 SPL – Stack Pointer Register Low The SPH and SPL register pair represent the 16-bit SP value. The SP holds the stack pointer that points to the top of the stack. After reset, the stack pointer points to the highest internal SRAM address. To prevent corruption when updating the stack pointer from software, a write to SPL will automatically disable interrupts for the next four instructions or until the next I/O memory write. Only the number of bits required to address the available data memory, including external memory, up to 64KB is implemented for each device. Unused bits will always read as zero. Note: 1. Refer to specific device datasheets for exact initial values. z Bit 7:0 – SP[7:0]: Stack Pointer Register Low These bits hold the LSB of the 16-bit stack pointer (SP). 3.14.8 SPH – Stack Pointer Register High Note: 1. Refer to specific device datasheets for exact initial values. z Bit 7:0 – SP[15:8]: Stack Pointer Register High These bits hold the MSB of the 16-bit stack pointer (SP). Bit 7 6 5 4 3 2 1 0 +0x0C EIND[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0D SP[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value(1) 0/1 0/1 0/1 0/1 0/1 0/1 0/1 0/1 Bit 7 6 5 4 3 2 1 0 +0x0E SP[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value(1) 0/1 0/1 0/1 0/1 0/1 0/1 0/1 0/1 XMEGA B [MANUAL] 18 Atmel-8291C-AVR-XMEGA B -09/2014 3.14.9 SREG – Status Register The status register (SREG) contains information about the result of the most recently executed arithmetic or logic instruction. z Bit 7 – I: Global Interrupt Enable The global interrupt enable bit must be set for interrupts to be enabled. If the global interrupt enable register is cleared, none of the interrupts are enabled independent of the individual interrupt enable settings. This bit is not cleared by hardware after an interrupt has occurred. This bit can be set and cleared by the application with the SEI and CLI instructions, as described in “Instruction Set Description.” Changing the I flag through the I/O-register result in a onecycle wait state on the access. z Bit 6 – T: Bit Copy Storage The bit copy instructions bit load (BLD) and bit store (BST) use the T bit as source or destination for the operated bit. A bit from a register in the register file can be copied into this bit by the BST instruction, and this bit can be copied into a bit in a register in the register file by the BLD instruction. z Bit 5 – H: Half Carry Flag The half carry flag (H) indicates a half carry in some arithmetic operations. Half carry Is useful in BCD arithmetic. See “Instruction Set Description” for detailed information. z Bit 4 – S: Sign Bit, S = N ⊕ V The sign bit is always an exclusive or between the negative flag, N, and the two’s complement overflow flag, V. See “Instruction Set Description” for detailed information. z Bit 3 – V: Two’s Complement Overflow Flag The two’s complement overflow flag (V) supports two’s complement arithmetic. See “Instruction Set Description” for detailed information. z Bit 2 – N: Negative Flag The negative flag (N) indicates a negative result in an arithmetic or logic operation. See “Instruction Set Description” for detailed information. z Bit 1 – Z: Zero Flag The zero flag (Z) indicates a zero result in an arithmetic or logic operation. See “Instruction Set Description” for detailed information. z Bit 0 – C: Carry Flag The carry flag (C) indicates a carry in an arithmetic or logic operation. See “Instruction Set Description” for detailed information. Bit 7 6 5 4 3 2 1 0 +0x0F I THSVNZC Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 19 Atmel-8291C-AVR-XMEGA B -09/2014 3.15 Register Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 Reserved – – – – – – – – +0x01 Reserved – – – – – – – – +0x02 Reserved – – – – – – – – +0x03 Reserved – – – – – – – – +0x04 CCP CCP[7:0] 15 +0x05 Reserved – – – – – – – – +0x06 Reserved – – – – – – – – +0x07 Reserved – – – – – – – – +0x08 RAMPD RAMPD[7:0] 15 +0x09 RAMPX RAMPX[7:0] 16 +0x0A RAMPY RAMPY[7:0] 16 +0x0B RAMPZ RAMPZ[7:0] 16 +0x0C EIND EIND[7:0] 17 +0x0D SPL SPL[7:0] 17 +0x0E SPH SPH[7:0] 17 +0x0F SREG I T H S V N Z C 18 XMEGA B [MANUAL] 20 Atmel-8291C-AVR-XMEGA B -09/2014 4. Memories 4.1 Features z Flash program memory z One linear address space z In-system programmable z Self-programming and boot loader support z Application section for application code z Application table section for application code or data storage z Boot section for application code or bootloader code z Separate read/write protection lock bits for all sections z Built in fast CRC check of a selectable flash program memory section z Data memory z One linear address space z Single-cycle access from CPU z SRAM z EEPROM z Byte and page accessible z Optional memory mapping for direct load and store z I/O memory z Configuration and status registers for all peripherals and modules z 4 bit-accessible general purpose registers for global variables or flags z Bus arbitration z Safe and deterministic handling of priority between CPU, DMA controller, and other bus masters z Separate buses for SRAM, EEPROM, I/O memory, and external memory access z Simultaneous bus access for CPU and DMA controller z Production signature row memory for factory programmed data z ID for each microcontroller device type z Serial number for each device z Calibration bytes for factory calibrated peripherals z User signature row z One flash page in size z Can be read and written from software z Content is kept after chip erase 4.2 Overview This section describes the different memory sections. The AVR architecture has two main memory spaces, the program memory and the data memory. Executable code can reside only in the program memory, while data can be stored in the program memory and the data memory. The data memory includes the internal SRAM, and EEPROM for nonvolatile data storage. All memory spaces are linear and require no memory bank switching. Nonvolatile memory (NVM) spaces can be locked for further write and read/write operations. This prevents unrestricted access to the application software. A separate memory section contains the fuse bytes. These are used for configuring important system functions, and can only be written by an external programmer. 4.3 Flash Program Memory All XMEGA devices contain on-chip, in-system reprogrammable flash memory for program storage. The flash memory can be accessed for read and write from an external programmer through the PDI or from application software running in the device. XMEGA B [MANUAL] 21 Atmel-8291C-AVR-XMEGA B -09/2014 All AVR CPU instructions are 16 or 32 bits wide, and each flash location is 16 bits wide. The flash memory is organized in two main sections, the application section and the boot loader section, as shown in Figure 4-1 on page 21. The sizes of the different sections are fixed, but device-dependent. These two sections have separate lock bits, and can have different levels of protection. The store program memory (SPM) instruction, which is used to write to the flash from the application software, will only operate when executed from the boot loader section. The application section contains an application table section with separate lock settings. This enables safe storage of nonvolatile data in the program memory. Figure 4-1. Flash memory sections. 4.3.1 Application Section The Application section is the section of the flash that is used for storing the executable application code. The protection level for the application section can be selected by the boot lock bits for this section. The application section can not store any boot loader code since the SPM instruction cannot be executed from the application section. 4.3.2 Application Table Section The application table section is a part of the application section of the flash memory that can be used for storing data. The size is identical to the boot loader section. The protection level for the application table section can be selected by the boot lock bits for this section. The possibilities for different protection levels on the application section and the application table section enable safe parameter storage in the program memory. If this section is not used for data, application code can reside here. 4.3.3 Boot Loader Section While the application section is used for storing the application code, the boot loader software must be located in the boot loader section because the SPM instruction can only initiate programming when executing from this section. The SPM instruction can access the entire flash, including the boot loader section itself. The protection level for the boot loader section can be selected by the boot loader lock bits. If this section is not used for boot loader software, application code can be stored here. Application Flash Section 0x000000 End Application Start Boot Loader Flashend Application Table Flash Section Boot Loader Flash Section XMEGA B [MANUAL] 22 Atmel-8291C-AVR-XMEGA B -09/2014 4.3.4 Production Signature Row The production signature row is a separate memory section for factory programmed data. It contains calibration data for functions such as oscillators and analog modules. Some of the calibration values will be automatically loaded to the corresponding module or peripheral unit during reset. Other values must be loaded from the signature row and written to the corresponding peripheral registers from software. For details on calibration conditions such as temperature, voltage references, etc., refer to the device datasheet. The production signature row also contains an ID that identifies each microcontroller device type and a serial number for each manufactured device. The serial number consists of the production lot number, wafer number, and wafer coordinates for the device. The production signature row cannot be written or erased, but it can be read from application software and external programmers. For accessing the production signature row, refer to “NVM Flash Commands” on page 380. 4.3.5 User Signature Row The user signature row is a separate memory section that is fully accessible (read and write) from application software and external programmers. It is one flash page in size, and is meant for static user parameter storage, such as calibration data, custom serial number, identification numbers, random number seeds, etc. This section is not erased by chip erase commands that erase the flash, and requires a dedicated erase command. This ensures parameter storage during multiple program/erase operations and on-chip debug sessions. 4.4 Fuses and Lockbits The fuses are used to configure important system functions, and can only be written from an external programmer. The application software can read the fuses. The fuses are used to configure reset sources such as brownout detector, watchdog and startup configuration. The lock bits are used to set protection levels for the different flash sections (i.e., if read and/or write access should be blocked). Lock bits can be written by external programmers and application software, but only to stricter protection levels. Chip erase is the only way to erase the lock bits. To ensure that flash contents are protected even during chip erase, the lock bits are erased after the rest of the flash memory has been erased. An unprogrammed fuse or lock bit will have the value one, while a programmed fuse or lock bit will have the value zero. Both fuses and lock bits are reprogrammable like the flash program memory. For some fuse bytes, leaving them unprogrammed (0xFF) will result in invalid settings. The user must ensure that the fuse bytes are programmed to values which give valid settings. Refer to the detailed description of the individual fuse bytes for further information. 4.5 Data Memory The data memory contains the I/O memory, internal SRAM, optionally memory mapped and EEPROM. The data memory is organized as one continuous memory section, as shown in Figure 4-2 on page 23. XMEGA B [MANUAL] 23 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 4-2. Data memory map. I/O memory, EEPROM, and SRAM will always have the same start addresses for all XMEGA devices. 4.6 Internal SRAM The internal SRAM always starts at hexadecimal address 0x2000. SRAM is accessed by the CPU using the load (LD/LDS/LDD) and store (ST/STS/STD) instructions. 4.7 EEPROM All XMEGA devices have EEPROM for nonvolatile data storage. It is addressable in a separate data space (default) or memory mapped and accessed in normal data space. The EEPROM supports both byte and page access. Memory mapped EEPROM allows highly efficient EEPROM reading and EEPROM buffer loading. When doing this, EEPROM is accessible using load and store instructions. Memory mapped EEPROM will always start at hexadecimal address 0x1000. 4.8 I/O Memory The status and configuration registers for peripherals and modules, including the CPU, are addressable through I/O memory locations. All I/O locations can be accessed by the load (LD/LDS/LDD) and store (ST/STS/STD) instructions, which are used to transfer data between the 32 registers in the register file and the I/O memory. The IN and OUT instructions can address I/O memory locations in the range of 0x00 to 0x3F directly. In the address range 0x00 - 0x1F, single-cycle instructions for manipulation and checking of individual bits are available. 4.8.1 General Purpose I/O Registers The lowest 4 I/O memory addresses are reserved as general purpose I/O registers. These registers can be used for storing global variables and flags, as they are directly bit-accessible using the SBI, CBI, SBIS, and SBIC instructions. 4.9 Data Memory and Bus Arbitration Since the data memory is organized as four separate sets of memories, the different bus masters (CPU, DMA controller read and DMA controller write, etc.) can access different memory sections at the same time. See Figure 4-3 on page 24. I/O Memory (Up to 4 KB) EEPROM (Up to 4 KB) Internal SRAM 0x0000 0x1000 0x2000 Start/End Address Data Memory XMEGA B [MANUAL] 24 Atmel-8291C-AVR-XMEGA B -09/2014 The USB module acts as a bus master, and is connected directly to internal SRAM through a pseudo-dual-port (PDP) interface. Figure 4-3. Bus access. 4.9.1 Bus Priority When several masters request access to the same bus, the bus priority is in the following order (from higher to lower priority): 1. Bus Master with ongoing access. 2. Bus Master with ongoing burst. z Alternating DMA controller read and DMA controller write when they access the same data memory section. 3. Bus Master requesting burst access. z CPU has priority. 4. Bus Master requesting bus access. z CPU has priority. 4.10 Memory Timing Read and write access to the I/O memory takes one CPU clock cycle. A write to SRAM takes one cycle, and a read from SRAM takes two cycles. For burst read (DMA), new data are available every cycle. EEPROM page load (write) takes one cycle, and three cycles are required for read. For burst read, new data are available every second cycle. Refer to the instruction summary for more details on instructions and instruction timing. 4.11 Device ID and Revision Each device has a three-byte device ID. This ID identifies Atmel as the manufacturer of the device and the device type. A separate register contains the revision number of the device. Peripherals and system modules Bus matrix DMA CPU RAM OCD USART SPI Timer / Counter TWI USB Interrupt Controller Power Management SRAM External Programming AVR core PDI CH0 ADC AC Crypto modules Event System Controller Oscillator Control CH1 Non-Volatile Memory EEPROM Flash CRC Real Time Counter I/O NVM Controller XMEGA B [MANUAL] 25 Atmel-8291C-AVR-XMEGA B -09/2014 4.12 I/O Memory Protection Some features in the device are regarded as critical for safety in some applications. Due to this, it is possible to lock the I/O register related to the clock system, the event system, and the advanced waveform extensions. As long as the lock is enabled, all related I/O registers are locked and they can not be written from the application software. The lock registers themselves are protected by the configuration change protection mechanism. For details, refer to “Configuration Change Protection” on page 13. XMEGA B [MANUAL] 26 Atmel-8291C-AVR-XMEGA B -09/2014 4.13 Register Description – NVM Controller 4.13.1 ADDR0 – Address register 0 The ADDR0, ADDR1, and ADDR2 registers represent the 24-bit value, ADDR. This is used for addressing all NVM sections for read, write, and CRC operations. z Bit 7:0 – ADDR[7:0]: Address Byte 0 This register gives the address low byte when accessing NVM locations. 4.13.2 ADDR1 – Address register 1 z Bit 7:0 – ADDR[15:8]: Address Byte 1 This register gives the address high byte when accessing NVM locations. 4.13.3 ADDR2 – Address register 2 z Bit 7:0 – ADDR[23:16]: Address Byte 2 This register gives the address extended byte when accessing NVM locations. 4.13.4 DATA0 – Data register 0 The DATA0, DATA1, and DATA registers represent the 24-bit value, DATA. This holds data during NVM read, write, and CRC access. z Bit 7:0 – DATA[7:0]: Data Byte 0 This register gives the data value byte 0 when accessing NVM locations. Bit 7 6 5 4 3 2 1 0 +0x00 ADDR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1 1 1 1 1 1 1 Bit 7 6 5 4 3 2 1 0 +0x01 ADDR[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x02 ADDR[23:16] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x04 DATA[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 27 Atmel-8291C-AVR-XMEGA B -09/2014 4.13.5 DATA1 – Data register 1 z Bit 7:0 – DATA[15:8]: Data Byte 1 This register gives the data value byte 1 when accessing NVM locations. 4.13.6 DATA2 – Data register 2 z Bit 7:0 – DATA[23:16]: Data Byte 2 This register gives the data value byte 2 when accessing NVM locations. 4.13.7 CMD – Command register z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 6:0 – CMD[6:0]: Command These bits define the programming commands for the flash. Bit 6 is only set for external programming commands. See “Memory Programming” on page 375” for programming commands. 4.13.8 CTRLA – Control register A z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – CMDEX: Command Execute Setting this bit will execute the command in the CMD register. This bit is protected by the configuration change protection (CCP) mechanism. Refer to “Configuration Change Protection” on page 13 for details on the CCP. Bit 7 6 5 4 3 2 1 0 +0x05 DATA[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x06 DATA[23:16] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0A – CMD[6:0] Read/Write R R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0B – – – – – – – CMDEX Read/Write R RRRRRRS Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 28 Atmel-8291C-AVR-XMEGA B -09/2014 4.13.9 CTRLB – Control register B z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3 – EEMAPEN: EEPROM Data Memory Mapping Enable Setting this bit enables data memory mapping of the EEPROM section. The EEPROM can then be accessed using load and store instructions. z Bit 2 – FPRM: Flash Power Reduction Mode Setting this bit enables power saving for the flash memory. If code is running from the application section, the boot loader section will be turned off, and vice versa. If access to the section that is turned off is required, the CPU will be halted for a time equal to the start-up time from the idle sleep mode. z Bit 1 – EPRM: EEPROM Power Reduction Mode Setting this bit enables power saving for the EEPROM. The EEPROM will then be turned off in a manner equal to entering sleep mode. If access is required, the bus master will be halted for a time equal to the start-up time from idle sleep mode. z Bit 0 – SPMLOCK: SPM Locked This bit can be written to prevent all further self-programming. The bit is cleared at reset, and cannot be cleared from software. This bit is protected by the configuration change protection (CCP) mechanism. Refer to “Configuration Change Protection” on page 13 for details on the CCP. 4.13.10 INTCTRL – Interrupt Control register z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:2 – SPMLVL[1:0]: SPM Ready Interrupt Level These bits enable the interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. This is a level interrupt that will be triggered only when the NVMBUSY flag in the STATUS register is set to zero. Thus, the interrupt should not be enabled before triggering an NVM command, as the NVMBUSY flag will not be set before the NVM command is triggered. The interrupt should be disabled in the interrupt handler. z Bit 1:0 – EELVL[1:0]: EEPROM Ready Interrupt Level These bits enable the EEPROM ready interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. This is a level interrupt that will be triggered only when the NVMBUSY flag in the STATUS register is set to zero. Thus, the interrupt should not be enabled before triggering an NVM command, as the NVMBUSY flag will not be set before the NVM command is triggered. The interrupt should be disabled in the interrupt handler. Bit 7 6 5 4 3 2 1 0 +0x0C – – – – EEMAPEN FPRM EPRM SPMLOCK Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0D – – – – SPMLVL[1:0] EELVL[1:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 29 Atmel-8291C-AVR-XMEGA B -09/2014 4.13.11 STATUS – Status register z Bit 7 – NVMBUSY: Nonvolatile Memory Busy The NVMBUSY flag indicates if the NVM (Flash, EEPROM, lock bit) is being programmed. Once an operation is started, this flag is set and remains set until the operation is completed. The NVMBUSY flag is automatically cleared when the operation is finished. z Bit 6 – FBUSY: Flash Busy The FBUSY flag indicates if a flash programming operation is initiated. Once an operation is started, the FBUSY flag is set and the application section cannot be accessed. The FBUSY flag is automatically cleared when the operation is finished. z Bit 5:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – EELOAD: EEPROM Page Buffer Active Loading The EELOAD flag indicates that the temporary EEPROM page buffer has been loaded with one or more data bytes. It remains set until an EEPROM page write or a page buffer flush operation is executed. For more details, see “Flash and EEPROM Programming Sequences” on page 377. z Bit 0 – FLOAD: Flash Page Buffer Active Loading The FLOAD flag indicates that the temporary flash page buffer has been loaded with one or more data bytes. It remains set until an application page write, boot page write, or page buffer flush operation is executed. For more details, see “Flash and EEPROM Programming Sequences” on page 377. 4.13.12 LOCKBITS – Lock Bit register This register is a mapping of the NVM lock bits into the I/O memory space, which enables direct read access from the application software. Refer to “LOCKBITS – Lock Bit register” on page 33 for a description. Bit 7 6 5 4 3 2 1 0 +0x04 NVMBUSY FBUSY – – – – EELOAD FLOAD Read/Write R R RRRR R R Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x07 BLBB[1:0] BLBA[1:0] BLBAT[1:0] LB[1:0] Read/Write R R R RRRRR Initial Value 11111111 XMEGA B [MANUAL] 30 Atmel-8291C-AVR-XMEGA B -09/2014 4.14 Register Descriptions – Fuses and Lock Bits 4.14.1 FUSEBYTE1 – Fuse Byte1 z Bit 7:4 – WDWPER[3:0]: Watchdog Window Timeout Period These fuse bits are used to set initial value of the closed window for the Watchdog Timer in Window Mode. During reset these fuse bits are automatically written to the WPER bits Watchdog Window Mode Control Register. Refer to “WINCTRL – Window Mode Control register” on page 113 for details. z Bit 3:0 – WDPER[3:0]: Watchdog Timeout Period These fuse bits are used to set the initial value of the watchdog timeout period. During reset these fuse bits are automatically written to the PER bits in the watchdog control register. Refer to “CTRL – Control register” on page 112 for details. 4.14.2 FUSEBYTE2 – Fuse Byte2 z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to one when this register is written. z Bit 6 – BOOTRST: Boot Loader Section Reset Vector This fuse can be programmed so the reset vector is pointing to the first address in the boot loader flash section. The device will then start executing from the boot loader flash section after reset. Table 4-1. Boot reset fuse. z Bit 5 – TOSCSEL: 32.768kHz Timer Oscillator Pin Selection This fuse is used to select the pin location for the 32.768kHz timer oscillator (TOSC). This fuse is available only on devices where XTAL and TOSC pins by default are shared. Bit 7 6 5 4 3 2 1 0 +0x01 WDWPER[3:0] WDPER[3:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x02 – BOOTRST TOSCSEL – – – BODPD[1:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1 1 1 1 1 1 1 BOOSTRST Reset address 0 Reset vector = Boot loader reset 1 Reset vector = Application reset (address 0x0000) XMEGA B [MANUAL] 31 Atmel-8291C-AVR-XMEGA B -09/2014 Table 4-2. TOSCSEL fuse. Note: 1. See the device datasheet for alternate TOSC position. z Bit 4:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to one when this register is written. z Bit 1:0 – BODPD[1:0]: BOD Operation in Power-down Mode These fuse bits set the BOD operation mode in all sleep modes except idle mode. For details on the BOD and BOD operation modes, refer to “Brownout Detection” on page 104. Table 4-3. BOD operation modes in sleep modes. 4.14.3 FUSEBYTE4 – Fuse Byte4 z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to one when this register is written. z Bit: 4 – RSTDISBL: External Reset Disable This fuse can be programmed to disable the external reset pin functionality. When this is done, pulling the reset pin low will not cause an external reset. A reset is required before this bit will be read correctly after it is changed. z Bit 3:2 – STARTUPTIME[1:0]: Start-up time These fuse bits can be used to set at a programmable timeout period from when all reset sources are released until the internal reset is released from the delay counter. A reset is required before these bits will be read correctly after they are changed. The delay is timed from the 1kHz output of the ULP oscillator. Refer to “Reset Sequence” on page 103 for details. TOSCSEL Group configuration Description 0 ALTERNATE(1) TOSC1/2 on separate pins 1 XTAL TOSC1/2 shared with XTAL BODPD[1:0] Description 00 Reserved 01 BOD enabled in sampled mode 10 BOD enabled continuously 11 BOD disabled Bit 7 6 5 4 3 2 1 0 +0x04 – – – RSTDISBL STARTUPTIME[1:0] WDLOCK – Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1 1 1 1 1 1 1 XMEGA B [MANUAL] 32 Atmel-8291C-AVR-XMEGA B -09/2014 Table 4-4. Start-up time z Bit 1 – WDLOCK: Watchdog Timer Lock The WDLOCK fuse can be programmed to lock the watchdog timer configuration. When this fuse is programmed, the watchdog timer configuration cannot be changed, and the ENABLE bit in the watchdog CTRL register is automatically set at reset and cannot be cleared from the application software. The WEN bit in the watchdog WINCTRL register is not set automatically, and needs to be set from software. A reset is required before this bit will be read correctly after it is changed. Table 4-5. Watchdog timer lock z Bit 0 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to one when this register is written. 4.14.4 FUSEBYTE5 – Fuse Byte 5 z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to one when this register is written. z Bit 5:4 – BODACT[1:0]: BOD Operation in Active Mode These fuse bits set the BOD operation mode when the device is in active and idle modes. For details on the BOD and BOD operation modes. Refer to “Brownout Detection” on page 104. Table 4-6. BOD operation modes in active and idle modes STARTUPTIME[1:0 1kHz ULP oscillator cycles 00 64 01 4 10 Reserved 11 0 WDLOCK Description 0 Watchdog timer locked for modifications 1 Watchdog timer not locked Bit 7 6 5 4 3 2 1 0 +0x05 – – BODACT[1:0] EESAVE BODLEVEL[2:0] Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 1 1 – – – – – – BODACT[1:0] Description 00 Reserved 01 BOD enabled in sampled mode 10 BOD enabled continuously 11 BOD disabled XMEGA B [MANUAL] 33 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 3 – EESAVE: EEPROM is Preserved through the Chip Erase A chip erase command will normally erase the flash, EEPROM, and internal SRAM. If this fuse is programmed, the EEPROM is not erased during chip erase. This is useful if EEPROM is used to store data independently of the software revision. Table 4-7. EEPROM preserved through chip erase Changes to the EESAVE fuse bit take effect immediately after the write timeout elapses. Hence, it is possible to update EESAVE and perform a chip erase according to the new setting of EESAVE without leaving and reentering programming mode. z Bit 2:0 – BODLEVEL[2:0]: Brownout Detection Voltage Level These fuse bits sets the BOD voltage level. Refer to “Reset System” on page 102 for details. For BOD level nominal values, see Table 9-2 on page 105. 4.14.5 LOCKBITS – Lock Bit register z Bit 7:6 – BLBB[1:0]: Boot Lock Bit Boot Loader Section These lock bits control the software security level for accessing the boot loader section. The BLBB bits can only be written to a more strict locking. Resetting the BLBB bits is possible by executing a chip erase command. Table 4-8. Boot lock bit for the boot loader section EESAVE Description 0 EEPROM is preserved during chip erase 1 EEPROM is erased during chip erase Bit 7 6 5 4 3 2 1 0 +0x07 BLBB[1:0] BLBA[1:0] BLBAT[1:0] LB[1:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1 1 1 1 1 1 1 BLBB[1:0] Group Configuration Description 11 NOLOCK No lock – no restrictions for SPM and (E)LPM accessing the boot loader section. 10 WLOCK Write lock – SPM is not allowed to write the boot loader section. 01 RLOCK Read lock – (E)LPM executing from the application section is not allowed to read from the boot loader section. If the interrupt vectors are placed in the application section, interrupts are disabled while executing from the boot loader section. 00 RWLOCK Read and write lock – SPM is not allowed to write to the boot loader section, and (E)LPM executing from the application section is not allowed to read from the boot loader section. If the interrupt vectors are placed in the application section, interrupts are disabled while executing from the boot loader section. XMEGA B [MANUAL] 34 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 5:4 – BLBA[1:0]: Boot Lock Bit Application Section These lock bits control the software security level for accessing the application section according to Table 4-9 on page 34. The BLBA bits can only be written to a more strict locking. Resetting the BLBA bits is possible only by executing a chip erase command. Table 4-9. Boot lock bit for the application section z Bit 3:2 – BLBAT[1:0]: Boot Lock Bit Application Table Section These lock bits control the software security level for accessing the application table section for software access. The BLBAT bits can only be written to a more strict locking. Resetting the BLBAT bits is possible only by executing a chip erase command. Table 4-10. Boot lock bit for the application table section z Bit 1:0 – LB[1:0]: Lock Bits(1) These lock bits control the security level for the flash and EEPROM during external programming. These bits are writable only through an external programming interface. Resetting the lock bits is possible only by executing a chip erase BLBA[1:0] Group Configuration Description 11 NOLOCK No Lock - no restrictions for SPM and (E)LPM accessing the application section. 10 WLOCK Write lock – SPM is not allowed to write the application section. 01 RLOCK Read lock – (E)LPM executing from the boot loader section is not allowed to read from the application section. If the interrupt vectors are placed in the boot loader section, interrupts are disabled while executing from the application section. 00 RWLOCK Read and write lock – SPM is not allowed to write to the application section, and (E)LPM executing from the boot loader section is not allowed to read from the application section. If the interrupt vectors are placed in the boot loader section, interrupts are disabled while executing from the application section. BLBAT[1:0] Group Configuration Description 11 NOLOCK No lock – no restrictions for SPM and (E)LPM accessing the application table section. 10 WLOCK Write lock – SPM is not allowed to write the application table 01 RLOCK Read lock – (E)LPM executing from the boot loader section is not allowed to read from the application table section. If the interrupt vectors are placed in the boot loader section, interrupts are disabled while executing from the application section. 00 RWLOCK Read and write lock – SPM is not allowed to write to the application table section, and (E)LPM executing from the boot loader section is not allowed to read from the application table section. If the interrupt vectors are placed in the boot loader section, interrupts are disabled while executing from the application section. XMEGA B [MANUAL] 35 Atmel-8291C-AVR-XMEGA B -09/2014 command. All other access; using the TIF and OCD, is blocked if any of the Lock Bits are written to 0. These bits do not block any software access to the memory. Table 4-11. Lock bit protection mode. Note: 1. Program the Fuse Bits and Boot Lock Bits before programming the Lock Bits. LB[1:0] Group Configuration Description 11 NOLOCK3 No lock – no memory locks enabled. 10 WLOCK Write lock – programming of the flash and EEPROM is disabled for the programming interface. Fuse bits are locked for write from the programming interface. 00 RWLOCK Read and write lock – programming and read/verification of the flash and EEPROM are disabled for the programming interface. The lock bits and fuses are locked for read and write from the programming interface. XMEGA B [MANUAL] 36 Atmel-8291C-AVR-XMEGA B -09/2014 4.15 Register Description – Production Signature Row 4.15.1 RCOSC2M – Internal 2MHz Oscillator Calibration register z Bit 7:0 – RCOSC2M[7:0]: Internal 2MHz Oscillator Calibration Value This byte contains the oscillator calibration value for the internal 2MHz oscillator. Calibration of the oscillator is performed during production test of the device. During reset this value is automatically loaded into calibration register B for the 2MHz DFLL. Refer to “CALB – DFLL Calibration register B” on page 92 for more details. 4.15.2 RCOSC2MA – Internal 2MHz Oscillator Calibration register z Bit 7:0 – RCOSC2MA[7:0]: Internal 2MHz Oscillator Calibration Value This byte contains the oscillator calibration value for the internal 2MHz oscillator. Calibration of the oscillator is performed during production test of the device. During reset this value is automatically loaded into calibration register A for the 2MHz DFLL. Refer to “CALA – DFLL Calibration Register A” on page 92 for more details. 4.15.3 RCOSC32K – Internal 32.768kHz Oscillator Calibration register z Bit 7:0 – RCOSC32K[7:0]: Internal 32.768kHz Oscillator Calibration Value This byte contains the oscillator calibration value for the internal 32.768kHz oscillator. Calibration of the oscillator is performed during production test of the device. During reset this value is automatically loaded into the calibration register for the 32.768kHz oscillator. Refer to “RC32KCAL – 32kHz Oscillator Calibration register” on page 90 for more details. 4.15.4 RCOSC32M – Internal 32MHz Oscillator Calibration register z Bit 7:0 – RCOSC32M[7:0]: Internal 32MHz Oscillator Calibration Value This byte contains the oscillator calibration value for the internal 32MHz oscillator. Calibration of the oscillator is performed during production test of the device. During reset this value is automatically loaded into calibration register B for the 32MHz DFLL. Refer to “CALB – DFLL Calibration register B” on page 92 for more details. Bit 7 6 5 4 3 2 1 0 0x00 RCOSC2M[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x01 RCOSC2MA[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x02 RCOSC32K[7:0] Read/Write RRRR R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x03 RCOSC32M[7:0] Read/Write RRRR R R R R Initial Value x x x x x x x x XMEGA B [MANUAL] 37 Atmel-8291C-AVR-XMEGA B -09/2014 4.15.5 RCOSC32MA – Internal 32MHz RC Oscillator Calibration register z Bit 7:0 – RCOSC32MA[7:0]: Internal 32MHz Oscillator Calibration Value This byte contains the oscillator calibration value for the internal 32MHz oscillator. Calibration of the oscillator is performed during production test of the device. During reset this value is automatically loaded into calibration register A for the 32MHz DFLL. Refer to “CALA – DFLL Calibration Register A” on page 92 for more details. 4.15.6 LOTNUM0 – Lot Number register 0 LOTNUM0, LOTNUM1, LOTNUM2, LOTNUM3, LOTNUM4 and LOTNUM5 contain the lot number for each device. Together with the wafer number and wafer coordinates this gives a serial number for the device. z Bit 7:0 – LOTNUM0[7:0]: Lot Number Byte 0 This byte contains byte 0 of the lot number for the device. 4.15.7 LOTNUM1 – Lot Number register 1 z Bit 7:0 – LOTNUM1[7:0]: Lot Number Byte 1 This byte contains byte 1 of the lot number for the device. 4.15.8 LOTNUM2 – Lot Number Register 2 z Bit 7:0 – LOTNUM2[7:0]: Lot Number Byte 2 This byte contains byte 2 of the lot number for the device. Bit 7 6 5 4 3 2 1 0 0x04 RCOSC32MA[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x08 LOTNUM0[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x09 LOTNUM1[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x0A LOTNUM2[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x XMEGA B [MANUAL] 38 Atmel-8291C-AVR-XMEGA B -09/2014 4.15.9 LOTNUM3 – Lot Number register 3 z Bit 7:0 – LOTNUM3[7:0]: Lot Number Byte 3 This byte contains byte 3 of the lot number for the device. 4.15.10 LOTNUM4 – Lot Number register 4 z Bit 7:0 – LOTNUM4[7:0]: Lot Number Byte 4 This byte contains byte 4 of the lot number for the device. 4.15.11 LOTNUM5 – Lot Number register 5 z Bit 7:0 – LOTNUM5[7:0]: Lot Number Byte 5 This byte contains byte 5 of the lot number for the device. 4.15.12 WAFNUM – Wafer Number register z Bit 7:0 – WAFNUM[7:0]: Wafer Number This byte contains the wafer number for each device. Together with the lot number and wafer coordinates this gives a serial number for the device. Bit 7 6 5 4 3 2 1 0 0x0B LOTNUM3[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x0C LOTNUM4[7:0] Read/Write RRRR R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x0D LOTNUM5[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x10 WAFNUM[7:0] Read/Write R R R R R R R R Initial Value 0 0 0 x x x x x XMEGA B [MANUAL] 39 Atmel-8291C-AVR-XMEGA B -09/2014 4.15.13 COORDX0 – Wafer Coordinate X register 0 COORDX0, COORDX1, COORDY0 and COORDY1 contain the wafer X and Y coordinates for each device. Together with the lot number and wafer number, this gives a serial number for each device. z Bit 7:0 – COORDX0[7:0]: Wafer Coordinate X Byte 0 This byte contains byte 0 of wafer coordinate X for the device. 4.15.14 COORDX1 – Wafer Coordinate X register 1 z Bit 7:0 – COORDX0[7:0]: Wafer Coordinate X Byte 1 This byte contains byte 1 of wafer coordinate X for the device. 4.15.15 COORDY0 – Wafer Coordinate Y register 0 z Bit 7:0 – COORDY0[7:0]: Wafer Coordinate Y Byte 0 This byte contains byte 0 of wafer coordinate Y for the device. 4.15.16 COORDY1 – Wafer Coordinate Y register 1 z Bit 7:0 – COORDY1[7:0]: Wafer Coordinate Y Byte 1 This byte contains byte 1 of wafer coordinate Y for the device. Bit 7 6 5 4 3 2 1 0 0x12 COORDX0[7:0] Read/Write RRRR R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x13 COORDX1[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x14 COORDY0[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x15 COORDY1[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x XMEGA B [MANUAL] 40 Atmel-8291C-AVR-XMEGA B -09/2014 4.15.17 USBCAL0 – USB Calibration register 0 USBCAL0 and USBCAL1 contain the calibration value for the USB pins. Calibration is done during production to enable operation without requiring external components on the USB lines for the device. The calibration bytes are not loaded automatically into the USB calibration registers, and so this must be done from software. z Bit 7:0 – USBCAL0[7:0]: USB Pad Calibration byte 0 This byte contains byte 0 of the USB pin calibration data, and must be loaded into the USB CALL register. 4.15.18 USBCAL1 – USB Pad Calibration register 1 z Bit 7:0 – USBCAL1[7:0]: USB Pad Calibration byte 1 This byte contains byte 1 of the USB pin calibration data, and must be loaded into the USB CALH register. 4.15.19 USBRCOSC – USB RCOSC Calibration z Bit 7:0 – USBRCOSC[7:0]: 48MHz RSCOSC Calibration This byte contains a 48MHz calibration value for the internal 32MHz oscillator. When this calibration value is written to calibration register B for the 32MHz DFLL, the oscillator is calibrated to 48MHz to enable full-speed USB operation from internal oscillator. Note: The COMP2 and COMP1 registers inside the DFLL32M must be set to B71B. 4.15.20 ADCACAL0 – ADCA Calibration register 0 ADCACAL0 and ADCACAL1 contain the calibration value for the analog to digital converter A (ADCA). Calibration is done during production test of the device. The calibration bytes are not loaded automatically into the ADC calibration registers, so this must be done from software. z Bit 7:0 – ADCACAL0[7:0]: ADCA Calibration Byte 0 This byte contains byte 0 of the ADCA calibration data, and must be loaded into the ADCA CALL register. Bit 7 6 5 4 3 2 1 0 0x1A USBCAL0[7:0] Read/Write RRRR R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x1B USBCAL1[7:0] Read/Write RRRR R R R R Initial Value xxxx x x x x Bit 7 6 5 4 3 2 1 0 0x1C USBRCOSC[7:0] Read/Write RRRR R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x20 ADCACAL0[7:0] Read/Write RRRR R R R R Initial Value xxxx x x x x XMEGA B [MANUAL] 41 Atmel-8291C-AVR-XMEGA B -09/2014 4.15.21 ADCACAL1 – ADCA Calibration register 1 z Bit 7:0 – ADCACAL1[7:0]: ADCA Calibration Byte 1 This byte contains byte 1 of the ADCA calibration data, and must be loaded into the ADCA CALH register. 4.15.22 TEMPSENSE0 – Temperature Sensor Calibration register 0 TEMPSENSE0 and TEMPSENSE1 contain the 12-bit ADCA value from a temperature measurement done with the internal temperature sensor. The measurement is done in production test at 85°C and can be used for single- or multipoint temperature sensor calibration. z Bit 7:0 – TEMPSENSE0[7:0]: Temperature Sensor Calibration Byte 0 This byte contains the byte 0 of the temperature measurement. 4.15.23 TEMPSENSE1 – Temperature Sensor Calibration register 1 z Bit 7:0 – TEMPSENSE1[7:0]: Temperature Sensor Calibration Byte 1 This byte contains byte 1 of the temperature measurement. Bit 7 6 5 4 3 2 1 0 0x21 ADCACAL1[7:0] Read/Write RRRR R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x2E TEMPSENSE0[7:0] Read/Write R R R R R R R R Initial Value x x x x x x x x Bit 7 6 5 4 3 2 1 0 0x2F TEMPSENSE1[7:0] Read/Write R R R R R R R R Initial Value 0 0 0 0 x x x x XMEGA B [MANUAL] 42 Atmel-8291C-AVR-XMEGA B -09/2014 4.16 Register Description – General Purpose I/O Memory 4.16.1 GPIORn – General Purpose I/O register n These are general purpose registers that can be used to store data, such as global variables and flags, in the bitaccessible I/O memory space. 4.17 Register Descriptions – MCU Control 4.17.1 DEVID0 – Device ID register 0 DEVID0, DEVID1 and DEVID2 contain the byte identification that identifies each microcontroller device type. For details on the actual ID, refer to the device datasheets. z Bit 7:0 – DEVID0[7:0]: Device ID Byte 0 Byte 0 of the device ID. This byte will always be read as 0x1E. This indicates that the device is manufactured by Atmel. 4.17.2 DEVID1 – Device ID register 1 z Bit 7:0 – DEVID[7:0]: Device ID Byte 1 Byte 1 of the device ID indicates the flash size of the device. 4.17.3 DEVID2 – Device ID register 2 z Bit 7:0 – DEVID2[7:0]: Device ID Byte 2 Byte 2 of the device ID indicates the device number. Bit 7 6 5 4 3 2 1 0 +n GPIORn[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 00000 Bit 7 6 5 4 3 2 1 0 +0x00 DEVID0[7:0] Read/Write R R RRRRRR Initial Value 00011110 Bit 7 6 5 4 3 2 1 0 +0x01 DEVID1[7:0] Read/Write R R RRRRRR Initial Value 1/0 1/0 1/0 1/0 1/0 1/0 1/0 1/0 Bit 7 6 5 4 3 2 1 0 +0x02 DEVID2[7:0] Read/Write R R RRRRRR Initial Value 1/0 1/0 1/0 1/0 1/0 1/0 1/0 1/0 XMEGA B [MANUAL] 43 Atmel-8291C-AVR-XMEGA B -09/2014 4.17.4 REVID – Revision ID z Bit 7:4 – Reserved These bits are unused and reserved for future use. z Bit 3:0 – REVID[3:0]: Revision ID These bits contains the device revision. 0 = A, 1 = B, and so on. 4.17.5 ANAINIT – Analog Initialization register z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1:0 – STARTUPDLYx Setting these bits enables sequential start of the internal components used for the ADC, DAC, and analog comparator with the main input/output connected to that port. When this is done, the internal components such as voltage reference and bias currents are started sequentially when the module is enabled. This reduces the peak current consumption during startup of the module. For maximum effect, the start-up delay should be set so that it is larger than 0.5μs. Table 4-12. Analog start-up delay 4.17.6 EVSYSLOCK – Event System Lock register z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. Bit 7 6 5 4 3 2 1 0 +0x03 – – – – REVID[3:0] Read/Write R RRRRRRR Initial Value 0 0 0 0 1/0 1/0 1/0 1/0 Bit 7 6 5 4 3 2 1 0 +0x07 – – – – – – STARTUPDLYA[1:0] Read/Write R R R R R R R/W R/W Initial Value 0 0 0 00000 STARTUPDLYx Group Configuration Description 00 NONE Direct startup 11 2CLK 2 * CLKPER 10 8CLK 8 * CLKPER 11 32CLK 32 * CLKPER Bit 7 6 5 4 3 2 1 0 +0x08 – – – – – – – EVSYS0LOCK Read/Write R R R R R R R R/W Initial Value 0 0 0 0000 0 XMEGA B [MANUAL] 44 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 0 – EVSYS0LOCK: Setting this bit will lock all registers in the event system related to event channels 0 to 3 against further modification. The following registers in the event system are locked: CH0MUX, CH0CTRL, CH1MUX, CH1CTRL, CH2MUX, CH2CTRL, CH3MUX, and CH3CTRL. This bit is protected by the configuration change protection mechanism. For details, refer to “Configuration Change Protection” on page 13. 4.17.7 AWEXLOCK – Advanced Waveform Extension Lock register z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – AWEXCLOCK: Advanced Waveform Extension Lock for TCC0 Setting this bit will lock all registers in the AWEXC module for timer/counter C0 for against further modification. This bit is protected by the configuration change protection mechanism. For details, refer to “Configuration Change Protection” on page 13. Bit 7 6 5 4 3 2 1 0 +0x09 – – – – – – – AWEXCLOCK Read/Write R R R R R R R R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 45 Atmel-8291C-AVR-XMEGA B -09/2014 4.18 Register Summary - NVM Controller 4.19 Register Summary - Fuses and Lock Bits 4.20 Register Summary - Production Signature Row Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 ADDR0 Address Byte 0 25 +0x01 ADDR1 Address Byte 1 25 +0x02 ADDR2 Address Byte 2 25 +0x03 Reserved – – – – – – – – +0x04 DATA0 Data Byte 0 26 +0x05 DATA1 Data Byte 1 26 +0x06 DATA2 Data Byte 2 26 +0x07 Reserved – – – – – – – – +0x08 Reserved – – – – – – – – +0x09 Reserved – – – – – – – – +0x0A CMD – CMD[6:0] 26 +0x0B CTRLA – – – – – – – CMDEX 27 +0x0C CTRLB – – – – EEMAPEN FPRM EPRM SPMLOCK 27 +0x0D INTCTRL – – – – SPMLVL[1:0] EELVL[1:0] 28 +0x0E Reserved – – – – – – – – +0x0F STATUS NVMBUSY FBUSY – – – – EELOAD FLOAD 28 +0x10 LOCKBITS BLBB[1:0] BLBA[1:0] BLBAT[1:0] LB[1:0] 29 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 Reserved – – – – – – – – +0x01 FUSEBYTE1 WDWPER3:0] WDPER[3:0] 30 +0x02 FUSEBYTE2 – BOOTRST TOSCSEL – – – BODPD[1:0] 30 +0x03 Reserved – – – – – – – – +0x04 FUSEBYTE4 – – – RSTDISBL STARTUPTIME[1:0] WDLOCK – 31 +0x05 FUSEBYTE5 – – BODACT[1:0] EESAVE BODLEVEL[2:0] 32 +0x06 Reserved – – – – – – – – +0x07 LOCKBITS BLBB[1:0] BLBA[1:0] BLBAT[1:0] LB[1:0] 34 Address Auto Load Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page 0x00 YES RCOSC2M RCOSC2M[7:0] 36 0x01 YES RCOSC2MA RCOSC2MA[7:0] 37 0x02 YES RCOSC32K RCOSC32K[7:0] 36 0x03 YES RCOSC32M RCOSC32M[7:0] 36 0x04 YES RCOSC32MA RCOSC32MA[7:0] 37 0x05 Reserved – – – – – – – – 0x06 Reserved – – – – – – – – 0x07 Reserved – – – – – – – – 0x08 NO LOTNUM0 LOTNUM0[7:0] 37 0x09 NO LOTNUM1 LOTNUM1[7:0] 37 0x0A NO LOTNUM2 LOTNUM2[7:0] 37 0x0B NO LOTNUM3 LOTNUM3[7:0] 38 0x0C NO LOTNUM4 LOTNUM4[7:0] 38 0x0D NO LOTNUM5 LOTNUM5[7:0] 38 0x0E Reserved – – – – – – – – 0x0F Reserved – – – – – – – – 0x10 NO WAFNUM WAFNUM[7:0] 38 0x11 Reserved – – – – – – – – 0x12 NO COORDX0 COORDX0[7:0] 39 0x13 NO COORDX1 COORDX1[7:0] 39 0x14 NO COORDY0 COORDY0[7:0] 39 0x15 NO COORDY1 COORDY1[7:0] 39 0x16 Reserved – – – – – – – – 0x17 Reserved – – – – – – – – 0x18 Reserved – – – – – – – – 0x19 Reserved – – – – – – – – 0x1A USBCAL0 USBCAL0[7:0] 40 0x1B USBCAL1 USBCAL1[7:0] 40 0x1C USBRCOSC USBRCOSC[7:0] 40 XMEGA B [MANUAL] 46 Atmel-8291C-AVR-XMEGA B -09/2014 4.21 Register Summary – General Purpose I/O Registers 4.22 Register Summary – MCU Control 4.23 Interrupt Vector Summary – NVM Controller 0x1D Reserved – – – – – – – – 0x0E Reserved – – – – – – – – 0x1E Reserved – – – – – – – – 0x20 NO ADCACAL0 ADCACAL0[7:0] 40 0x21 NO ADCACAL1 ADCACAL1{7:0] 41 0x22 Reserved – – – – – – – – 0x23 Reserved – – – – – – – – 0x24 Reserved – – – – – – – – 0x25 Reserved – – – – – – – – 0x26 Reserved – – – – – – – – 0x27 Reserved – – – – – – – – 0x28 Reserved – – – – – – – – 0x29 Reserved – – – – – – – – 0x2A Reserved – – – – – – – – 0x2B Reserved – – – – – – – – 0x2C Reserved – – – – – – – – 0x2D Reserved – – – – – – – – 0x2E NO TEMPSENSE0 TEMPSENSE0[7:0] 41 0x2F NO TEMPSENSE1 – – – – TEMPSENSE1[11:8] 41 0x38 Reserved – – – – – – – – 0x39 Reserved – – – – – – – – 0x3A Reserved – – – – – – – – 0x3B Reserved – – – – – – – – 0x3C Reserved – – – – – – – – 0x3D Reserved – – – – – – – – 0x3E Reserved – – – – – – – – Address Auto Load Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 GPIOR0 GPIOR[7:0] 42 +0x01 GPIOR1 GPIOR[7:0] 42 +0x02 GPIOR2 GPIOR[7:0] 42 +0x03 GPIOR3 GPIOR[7:0] 42 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 DEVID0 DEVID0[7:0] 42 +0x01 DEVID1 DEVID1[7:0] 42 +0x02 DEVID2 DEVID2[7:0] 42 +0x03 REVID – – – – REVID[3:0] 43 +0x04 Reserved – – – – – – – – +0x05 Reserved – – – – – – – – +0x06 Reserved – – – – – – – – +0x07 ANAINIT – – – – STARTUPDLYB[1:0] STARTUPDLYA[1:0] 43 +0x08 EVSYSLOCK – – – – – – – EVSYS0LOC 43 +0x09 AWEXLOCK – – – – – – – AWEXCLOCK 44 +0x0A Reserved – – – – – – – – +0x0B Reserved – – – – – – – – Offset Source Interrupt Description 0x00 EE_vect Nonvolatile memory EEPROM interrupt vector 0x02 SPM_vect Nonvolatile memory SPM interrupt vector XMEGA B [MANUAL] 47 8291C–AVR–09/2014 5. DMAC - Direct Memory Access Controller 5.1 Features z Allows high speed data transfers with minimal CPU intervention z from data memory to data memory z from data memory to peripheral z from peripheral to data memory z from peripheral to peripheral z Two DMA channels with separate z transfer triggers z interrupt vectors z addressing modes z Programmable channel priority z From 1 byte to 16MB of data in a single transaction z Up to 64KB block transfers with repeat z 1, 2, 4, or 8 byte burst transfers z Multiple addressing modes z Static z Incremental z Decremental z Optional reload of source and destination addresses at the end of each z Burst z Block z Transaction z Optional interrupt on end of transaction z Optional connection to CRC generator for CRC on DMA data 5.2 Overview The two-channel direct memory access (DMA) controller can transfer data between memories and peripherals, and thus offload these tasks from the CPU. It enables high data transfer rates with minimum CPU intervention, and frees up CPU time. The two DMA channels enable up to two independent and parallel transfers. The DMA controller can move data between SRAM and peripherals, between SRAM locations and directly between peripheral registers. With access to all peripherals, the DMA controller can handle automatic transfer of data to/from communication modules. The DMA controller can also read from memory mapped EEPROM. Data transfers are done in continuous bursts of 1, 2, 4, or 8 bytes. They build block transfers of configurable size from 1 byte to 64KB. A repeat counter can be used to repeat each block transfer for single transactions up to 16MB. Source and destination addressing can be static, incremental or decremental. Automatic reload of source and/or destination addresses can be done after each burst or block transfer, or when a transaction is complete. Application software, peripherals, and events can trigger DMA transfers. The two DMA channels have individual configuration and control settings. This include source, destination, transfer triggers, and transaction sizes. They have individual interrupt settings. Interrupt requests can be generated when a transaction is complete or when the DMA controller detects an error on a DMA channel. To allow for continuous transfers, two channels can be interlinked so that the second takes over the transfer when the first is finished, and vice versa. XMEGA B [MANUAL] 48 8291C–AVR–09/2014 Figure 5-1. DMA Overview. 5.3 DMA Transaction A complete DMA read and write operation between memories and/or peripherals is called a DMA transaction. A transaction is done in data blocks, and the size of the transaction (number of bytes to transfer) is selectable from software and controlled by the block size and repeat counter settings. Each block transfer is divided into smaller bursts. 5.3.1 Block Transfer and Repeat The size of the block transfer is set by the block transfer count register, and can be anything from 1 byte to 64KB. A repeat counter can be enabled to set a number of repeated block transfers before a transaction is complete. The repeat is from 1 to 255, and an unlimited repeat count can be achieved by setting the repeat count to zero. 5.3.2 Burst Transfer Since the AVR CPU and DMA controller use the same data buses, a block transfer is divided into smaller burst transfers. The burst transfer is selectable to 1, 2, 4, or 8 bytes. This means that if the DMA acquires the data bus and a transfer request is pending, it will occupy the bus until all bytes in the burst are transferred. A bus arbiter controls when the DMA controller and the AVR CPU can use the bus. The CPU always has priority, and so as long as the CPU requests access to the bus, any pending burst transfer must wait. The CPU requests bus access when it executes an instruction that writes or reads data to SRAM, I/O memory, EEPROM or the external bus interface. For more details on memory access bus arbitration, refer to “Data Memory” on page 22. Figure 5-2. DMA transaction. R/W Master port Arbitration BUF Bus matrix Arbiter Read Write Slave port Read / Write CTRL DMA Channel 1 DMA trigger / Event DMA Channel 0 SRCADDR TRFCNT DESTADDR TRIGSRC REPCNT Control Logic Enable Burst CTRLA CTRLB XMEGA B [MANUAL] 49 8291C–AVR–09/2014 5.4 Transfer Triggers DMA transfers can be started only when a DMA transfer request is detected. A transfer request can be triggered from software, from an external trigger source (peripheral), or from an event. There are dedicated source trigger selections for each DMA channel. The available trigger sources may vary from device to device, depending on the modules or peripherals that exist in the device. Using a transfer trigger for a module or peripherals that does not exist will have no effect. For a list of all transfer triggers, refer to “TRIGSRC – Trigger Source” on page 57. By default, a trigger starts a block transfer operation. When the block transfer is complete, the channel is automatically disabled. When enabled again, the channel will wait for the next block transfer trigger. It is possible to select the trigger to start a burst transfer instead of a block transfer. This is called a single-shot transfer, and for each trigger only one burst is transferred. When repeat mode is enabled, the next block transfer does not require a transfer trigger. It will start as soon as the previous block is done. If the trigger source generates a transfer request during an ongoing transfer, this will be kept pending, and the transfer can start when the ongoing one is done. Only one pending transfer can be kept, and so if the trigger source generates more transfer requests when one is already pending, these will be lost. 5.5 Addressing The source and destination address for a DMA transfer can either be static or automatically incremented or decremented, with individual selections for source and destination. When address increment or decrement is used, the default behaviour is to update the address after each access. The original source and destination addresses are stored by the DMA controller, and so the source and destination addresses can be individually configured to be reloaded at the following points: z End of each burst transfer z End of each block transfer z End of transaction z Never reloaded 5.6 Priority Between Channels If several channels request a data transfer at the same time, a priority scheme is available to determine which channel is allowed to transfer data. Application software can decide whether one or more channels should have a fixed priority or if a round robin scheme should be used. A round robin scheme means that the channel that last transferred data will have the lowest priority. 5.7 Double Buffering To allow for continuous transfer, two channels can be interlinked so that the second takes over the transfer when the first is finished, and vice versa. This leaves time for the application to process the data transferred by the first channel, prepare fresh data buffers, and set up the channel registers again while the second channel is working. This is referred to as double buffering or chained transfers. When double buffering is enabled for a channel pair, it is important that the two channels are configured with the same repeat count. The block sizes need not be equal, but for most applications they should be, along with the rest of the channel’s operation mode settings. Note that the double buffering channel pairs are limited to channels 0 and 1 as the first pair and channels 2 and 3 as the second pair. However, it is possible to have one pair operate in double buffered mode while the other is left unused or operating independently. 5.8 Transfer Buffers To avoid unnecessary bus loading when doing data transfer between memories with different access timing (for example, I/O register and external memory), the DMA controller has a four-byte buffer. Two bytes will be read from the source address and written to this buffer before a write to the destination is started. XMEGA B [MANUAL] 50 8291C–AVR–09/2014 5.9 Error detection The DMA controller can detect erroneous operation. Error conditions are detected individually for each DMA channel, and the error conditions are: z Write to memory mapped EEPROM locations z Reading EEPROM when the EEPROM is off (sleep entered) z DMA controller or a busy channel is disabled in software during a transfer 5.10 Software Reset Both the DMA controller and a DMA channel can be reset from the user software. When the DMA controller is reset, all registers associated with the DMA controller, including channels, are cleared. A software reset can be done only when the DMA controller is disabled. When a DMA channel is reset, all registers associated with the DMA channel are cleared. A software reset can be done only when the DMA channel is disabled. 5.11 Protection In order to ensure safe operation, some of the channel registers are protected during a transaction. When the DMA channel busy flag (CHnBUSY) is set for a channel, the user can modify only the following registers and bits: z CTRL register z INTFLAGS register z TEMP registers z CHEN, CHRST, TRFREQ, and REPEAT bits of the channel CTRL register z TRIGSRC register 5.12 Interrupts The DMA controller can generate interrupts when an error is detected on a DMA channel or when a transaction is complete for a DMA channel. Each DMA channel has a separate interrupt vector, and there are different interrupt flags for error and transaction complete. If repeat is not enabled, the transaction complete flag is set at the end of the block transfer. If unlimited repeat is enabled, the transaction complete flag is also set at the end of each block transfer. XMEGA B [MANUAL] 51 8291C–AVR–09/2014 5.13 Register Description – DMA Controller 5.13.1 CTRL – Control register z Bit 7 – ENABLE: Enable Setting this bit enables the DMA controller. If the DMA controller is enabled and this bit is written to zero, the ENABLE bit is not cleared before the internal transfer buffer is empty, and the DMA data transfer is aborted. z Bit 6 – RESET: Software Reset Writing a one to RESET will be ignored as long as DMA is enabled (ENABLE = 1). This bit can be set only when the DMA controller is disabled (ENABLE = 0). z Bit 5:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2 – DBUFMODE: Double Buffer Mode This bit enables the double buffer mode. z Bit 1 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bits to zero when this register is written. z Bit 0 – PRIMODE: Channel Priority Mode This bit determines the internal channel priority according to Table 5-1. Table 5-1. Channel priority settings 5.13.2 INTFLAGS – Interrupt Status register z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. Bit 7 6 5 4 3 2 1 0 +0x00 ENABLE RESET – – – DBUFMODE – PRIMODE Read/Write R/W R/W R R R R/W R R/W Initial Value 0 0 0 0 0 0 0 0 PRIMODE Group Configuration Description 0 RR01 Round robin 1 CH01 Channel0 has priority Bit 7 6 5 4 3 2 1 0 +0x03 – – CH1ERRIF CH0ERRIF – – CH1TRNFIF CH0TRNFIF Read/Write R R R/W R/W R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 52 8291C–AVR–09/2014 z Bit 5:4 – CHnERRIF[1:0]: Channel n Error Interrupt Flag If an error condition is detected on DMA channel n, the CHnERRIF flag will be set. Writing a one to this bit location will clear the flag. z Bit 3:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1:0 – CHnTRNFIF[1:0]: Channel n Transaction Complete Interrupt Flag When a transaction on channel n has been completed, the CHnTRFIF flag will be set. If unlimited repeat count is enabled, this flag is read as one after each block transfer. Writing a one to this bit location will clear the flag. 5.13.3 STATUS – Status register z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5:4 – CHnBUSY[1:0]: Channel Busy When channel n starts a DMA transaction, the CHnBUSY flag will be read as one. This flag is automatically cleared when the DMA channel is disabled, when the channel n transaction complete interrupt flag is set, or if the DMA channel n error interrupt flag is set. z Bit 3:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written z Bit 1:0 – CHnPEND[1:0]: Channel Pending If a block transfer is pending on DMA channel n, the CHnPEND flag will be read as one. This flag is automatically cleared when the block transfer starts or if the transfer is aborted. 5.13.4 TEMPL – Temporary register Low z Bit 7:0 – TEMP[7:0]: Temporary register 0 This register is used when reading 16- and 24-bit registers in the DMA controller. Byte 1 of the 16/24-bit register is stored here when it is written by the CPU. Byte 1 of the 16/24-bit register is stored when byte 0 is read by the CPU. This register can also be read and written from the user software. Reading and writing 16- and 24-bit registers requires special attention. For details, refer to “Accessing 16-bit Registers” on page 13. Bit 7 6 5 4 3 2 1 0 +0x04 – – CH1BUSY CH0BUSY – – CH1PEND CH0PEND Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x06 TEMP[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 53 8291C–AVR–09/2014 5.13.5 TEMPH – Temporary Register High z Bit 7:0 – TEMP[15:8]: Temporary Register This register is used when reading and writing 24-bit registers in the DMA controller. Byte 2 of the 24-bit register is stored when it is written by the CPU. Byte 2 of the 24-bit register is stored here when byte 1 is read by the CPU. This register can also be read and written from the user software. Reading and writing 24-bit registers requires special attention. For details, refer to “Accessing 16-bit Registers” on page 13. 5.14 Register Description – DMA Channel 5.14.1 CTRLA – Control register A z Bit 7 – ENABLE: Channel Enable Setting this bit enables the DMA channel. This bit is automatically cleared when the transaction is completed. If the DMA channel is enabled and this bit is written to zero, the CHEN bit is not cleared until the internal transfer buffer is empty and the DMA transfer is aborted. z Bit 6 – RESET: Software Reset Setting this bit will reset the DMA channel. It can only be set when the DMA channel is disabled (CHEN = 0). Writing a one to this bit will be ignored as long as the channel is enabled (CHEN=1). This bit is automatically cleared when reset is completed. z Bit 5 – REPEAT: Repeat Mode Setting this bit enables the repeat mode. In repeat mode, this bit is cleared by hardware at the beginning of the last block transfer. The REPCNT register should be configured before setting the REPEAT bit. z Bit 4 – TRFREQ: Transfer Request Setting this bit requests a data transfer on the DMA channel. This bit is automatically cleared at the beginning of the data transfer. Writing this bit does not have any effect unless the channel is enabled. z Bit 3 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 2 – SINGLE: Single-Shot Data transfer Setting this bit enables the single-shot mode. The channel will then do a burst transfer of BURSTLEN bytes on the transfer trigger. A write to this bit will be ignored while the channel is enabled. Bit 7 6 5 4 3 2 1 0 +0x07 TEMP[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x00 ENABLE RESET REPEAT TRFREQ – SINGLE BURSTLEN[1:0] Read/Write R/W R/W R/W R/W R R/W R/W R/W Initial Value 0 0 000000 XMEGA B [MANUAL] 54 8291C–AVR–09/2014 z Bit 1:0 – BURSTLEN[1:0]: Burst Mode These bits decide the DMA channel burst mode according to Table 5-2 on page 54. These bits cannot be changed if the channel is busy. Table 5-2. DMA channel burst mode Table 5-3. Summary of triggers, transaction complete flag and channel disable according to DMA channel configuration. 5.14.2 CTRLB – Control register B z Bit 7 – CHBUSY: Channel Busy When the DMA channel starts a DMA transaction, the CHBUSY flag will be read as one. This flag is automatically cleared when the DMA channel is disabled, when the channel transaction complete interrupt flag is set or when the channel error interrupt flag is set. BURSTLEN[1:0] Group Configuration Description 00 1BYTE 1 byte burst mode 01 2BYTE 2 bytes burst mode 10 4BYTE 4 bytes burst mode 11 8BYTE 8 bytes burst mode REPEAT SINGLE REPCNT Trigger Flag Set After Channel Disabled After 0 0 0 Block 1 block 1 block 0 0 1 Block 1 block 1 block 0 0 n > 1 Block 1 block 1 block 0 1 0 BURSTLEN 1 block 1 block 0 1 1 BURSTLEN 1 block 1 block 0 1 n > 1 BURSTLEN 1 block 1 block 1 0 0 Block Each block Each block 1 0 1 Transaction 1 block 1 block 1 0 n > 1 Transaction n blocks n blocks 1 1 0 BURSTLEN Each block Never 1 1 1 BURSTLEN 1 block 1 block 1 1 n > 1 BURSTLEN n blocks n blocks Bit 7 6 5 4 3 2 1 0 +0x01 CHBUSY CHPEND ERRIF TRNIF ERRINTLVL[1:0] TRNINTLVL[1:0] Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 55 8291C–AVR–09/2014 z Bit 6 – CHPEND: Channel Pending If a block transfer is pending on the DMA channel, the CHPEND flag will be read as one. This flag is automatically cleared when the transfer starts or if the transfer is aborted. z Bit 5 – ERRIF: Error Interrupt Flag If an error condition is detected on the DMA channel, the ERRIF flag will be set and the optional interrupt is generated. Since the DMA channel error interrupt shares the interrupt address with the DMA channel n transaction complete interrupt, ERRIF will not be cleared when the interrupt vector is executed. This flag is cleared by writing a one to this location. z Bit 4 – TRNIF: Channel n Transaction Complete Interrupt Flag When a transaction on the DMA channel has been completed, the TRNIF flag will be set and the optional interrupt is generated. When repeat is not enabled, the transaction is complete and TRNIFR is set after the block transfer. When unlimited repeat is enabled, TRNIF is also set after each block transfer. Since the DMA channel transaction n complete interrupt shares the interrupt address with the DMA channel error interrupt, TRNIF will not be cleared when the interrupt vector is executed. This flag is cleared by writing a one to this location. z Bit 3:2 – ERRINTLVL[1:0]: Channel Error Interrupt Level These bits enable the interrupt for DMA channel transfer errors and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will trigger for the conditions when ERRIF is set. z Bit 1:0 – TRNINTLVL[1:0]: Channel Transaction Complete Interrupt Level These bits enable the interrupt for DMA channel transaction completes and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will trigger for the conditions when TRNIF is set. 5.14.3 ADDRCTRL – Address Control register z Bit 7:6 – SRCRELOAD[1:0]: Channel Source Address Reload These bits decide the DMA channel source address reload according to Table 5-4. A write to these bits is ignored while the channel is busy. Table 5-4. DMA channel source address reload settings Bit 7 6 5 4 3 2 1 0 +0x02 SRCRELOAD[1:0] SRCDIR[1:0] DESTRELOAD[1:0] DESTDIR[1:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0000000 SRCRELOAD[1:0] Group Configuration Description 00 NONE No reload performed. 01 BLOCK DMA source address register is reloaded with initial value at end of each block transfer. 10 BURST DMA source address register is reloaded with initial value at end of each burst transfer. 11 TRANSACTION DMA source address register is reloaded with initial value at end of each transaction. XMEGA B [MANUAL] 56 8291C–AVR–09/2014 z Bit 5:4 – SRCDIR[1:0]: Channel Source Address Mode These bits decide the DMA channel source address mode according to Table 5-5. These bits cannot be changed if the channel is busy. Table 5-5. DMA channel source address mode settings. z Bit 3:2 – DESTRELOAD[1:0]: Channel Destination Address Reload These bits decide the DMA channel destination address reload according to Table 5-6. These bits cannot be changed if the channel is busy. Table 5-6. DMA channel destination address reload settings z Bit 1:0 – DESTDIR[1:0]: Channel Destination Address Mode These bits decide the DMA channel destination address mode according to Table 5-7. These bits cannot be changed if the channel is busy. Table 5-7. DMA channel destination address mode settings SRCDIR[1:0] Group Configuration Description 00 FIXED Fixed 01 INC Increment 10 DEC Decrement 11 - Reserved DESTRELOAD[1:0] Group Configuration Description 00 NONE No reload performed. 01 BLOCK DMA channel destination address register is reloaded with initial value at end of each block transfer. 10 BURST DMA channel destination address register is reloaded with initial value at end of each burst transfer. 11 TRANSACTION DMA channel destination address register is reloaded with initial value at end of each transaction. DESTDIR[1:0] Group Configuration Description 00 FIXED Fixed 01 INC Increment 10 DEC Decrement 11 - Reserved XMEGA B [MANUAL] 57 8291C–AVR–09/2014 5.14.4 TRIGSRC – Trigger Source z Bit 7:0 – TRIGSRC[7:0]: Channel Trigger Source Select These bits select which trigger source is used for triggering a transfer on the DMA channel. A zero value means that the trigger source is disabled. For each trigger source, the value to put in the TRIGSRC register is the sum of the module’s or peripheral’s base value and the offset value for the trigger source in the module or peripheral. Table 5-8 on page 57 shows the base value for all modules and peripherals. Table 5-9 on page 58 to Table 5-11 on page 58 shows the offset value for the trigger sources in the different modules and peripheral types. For modules or peripherals which do not exist for a device, the transfer trigger does not exist. Refer to the device datasheet for the list of peripherals available. If the interrupt flag related to the trigger source is cleared or the interrupt level enabled so that an interrupt is triggered, the DMA request will be lost. Since a DMA request can clear the interrupt flag, interrupts can be lost. Note: For most trigger sources, the request is cleared by accessing a register belonging to the peripheral with the request. Refer to the different peripheral chapters for how requests are generated and cleared. Table 5-8. DMA trigger source base values for all modules and peripherals. Bit 7 6 5 4 3 2 1 0 +0x03 TRIGSRC[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 TRIGSRC Base Value Group Configuration Description 0x00 OFF Software triggers only 0x01 SYS Event system DMA triggers base value 0x04 AES AES DMA trigger value 0x10 ADCA ADCA DMA trigger value 0x40 TCC0 Timer/counter C0 DMA triggers base value 0x46 TCC1 Timer/counter C1 triggers base value 0x4A SPIC SPI C DMA trigger value 0x4B USARTC0 USART C0 DMA triggers base value 0x60 TCD0 Timer/counter D0 DMA triggers base value 0x6A SPID SPI D DMA triggers value 0x6B USARTD0 USART D0 DMA triggers base value 0x80 TCE0 Timer/counter E0 DMA triggers base value 0x8B USARTE0 USART E0 DMA triggers base value 0xA0 TCF0 Timer/counter F0 DMA triggers base value 0xAB USARTF0 USART F0 DMA triggers base value XMEGA B [MANUAL] 58 8291C–AVR–09/2014 Note: 1. CC channel C and D triggers are available only for timer/counters 0. The group configuration is the “base_offset;” for example, TCC1_CCA for the timer/counter C1 CC channel A the transfer trigger. 5.14.5 TRFCNTL – Channel Block Transfer Count register Low The TRFCNTH and TRFCNTL register pair represents the 16-bit value TRFCNT. TRFCNT defines the number of bytes in a block transfer. The value of TRFCNT is decremented after each byte read by the DMA channel. When TRFCNT reaches zero, the register is reloaded with the last value written to it. z Bit 7:0 – TRFCNT[7:0]: Channel n Block Transfer Count low byte These bits hold the LSB of the 16-bit block transfer count. The default value of this register is 0x1. If a user writes 0x0 to this register and fires a DMA trigger, DMA will be doing 0xFFFF transfers. Table 5-9. DMA trigger source offset values for event system triggers. TRGSRC Offset Value Group Configuration Description +0x00 CH0 Event channel 0 +0x01 CH1 Event channel 1 +0x02 CH2 Event channel 2 Table 5-10. DMA trigger source offset values for timer/ counter triggers. TRGSRC Offset Value Group Configuration Description +0x00 OVF Overflow/underflow +0x01 ERR Error +0x02 CCA Compare or capture channel A +0x03 CCB Compare or capture channel B +0x04 CCC(1) Compare or capture channel C +0x05 CCD(1) Compare or capture channel D Table 5-11. DMA trigger source offset values for USART triggers. TRGSRC Offset Value Group Configuration Description 0x00 RXC Receive complete 0x01 DRE Data register empty Bit 7 6 5 4 3 2 1 0 +0x04 TRFCNT[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 59 8291C–AVR–09/2014 5.14.6 TRFCNTH – Channel Block Transfer Count register High Reading and writing 16-bit values requires special attention. For details, refer to “Accessing 16-bit Registers” on page 13. z Bit 7:0 – TRFCNT[15:8]: Channel n Block Transfer Count high byte These bits hold the MSB of the 16-bit block transfer count. The default value of this register is 0x1. If a user writes 0x0 to this register and fires a DMA trigger, DMA will be doing 0xFFFF transfers. 5.14.7 REPCNT – Repeat Counter register REPCNT counts how many times a block transfer is performed. For each block transfer, this register will be decremented. When repeat mode is enabled (see REPEAT bit in “ADDRCTRL – Address Control register” on page 55), this register is used to control when the transaction is complete. The counter is decremented after each block transfer if the DMA has to serve a limited number of repeated block transfers. When repeat mode is enabled, the channel is disabled when REPCNT reaches zero and the last block transfer is completed. Unlimited repeat is achieved by setting this register to zero. 5.14.8 SRCADDR0 – Source Address 0 SRCADDR0, SRCADDR1, and SRCADDR2 represent the 24-bit value SRCADDR, which is the DMA channel source address. SRCADDR2 is the most significant byte in the register. SRCADDR may be automatically incremented or decremented based on settings in the SRCDIR bits in “ADDRCTRL – Address Control register” on page 55. z Bit 7:0 – SRCADDR[7:0]: Channel Source Address byte 0 These bits hold byte 0 of the 24-bit source address. Bit 7 6 5 4 3 2 1 0 +0x05 TRFCNT[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 00000 Bit 7 6 5 4 3 2 1 0 +0x06 REPCNT[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 Bit 7 6 5 4 3 2 1 0 +0x08 SRCADDR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 60 8291C–AVR–09/2014 5.14.9 SRCADDR1 – Channel Source Address 1 z Bit 7:0 – SRCADDR[15:8]: Channel Source Address byte 1 These bits hold byte 1 of the 24-bit source address. 5.14.10 SRCADDR2 – Channel Source Address 2 Reading and writing 24-bit values require special attention. For details, refer to “Accessing 24- and 32-bit Registers” on page 13. z Bit 7:0 – SRCADDR[23:16]: Channel Source Address byte 2 These bits hold byte 2 of the 24-bit source address. 5.14.11 DESTADDR0 – Channel Destination Address 0 DESTADDR0, DESTADDR1, and DESTADDR2 represent the 24-bit value DESTADDR, which is the DMA channel destination address. DESTADDR2 holds the most significant byte in the register. DESTADDR may be automatically incremented or decremented based on settings in the DESTDIR bits in “ADDRCTRL – Address Control register” on page 55. z Bit 7:0 – DESTADDR[7:0]: Channel Destination Address byte 0 These bits hold byte 0 of the 24-bit source address. Bit 7 6 5 4 3 2 1 0 +0x09 SRCADDR[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 00000 Bit 7 6 5 4 3 2 1 0 +0x0A SRCADDR[23:16] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0C DESTADDR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 61 8291C–AVR–09/2014 5.14.12 DESTADDR1 – Channel Destination Address 1 z Bit 7:0 – DESTADDR[15:8]: Channel Destination Address byte 1 These bits hold byte 1 of the 24-bit source address. 5.14.13 DESTADDR2 – Channel Destination Address 2 Reading and writing 24-bit values require special attention. For details, refer to “Accessing 24- and 32-bit Registers” on page 13. z Bit 7:0 – DESTADDR[23:16]: Channel Destination Address byte 2 These bits hold byte 2 of the 24-bit source address. Bit 7 6 5 4 3 2 1 0 +0x0D DESTADDR[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0E DESTADDR[23:16] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 62 8291C–AVR–09/2014 5.15 Register Summary – DMA Controller 5.16 Register Summary – DMA Channel 5.17 DMA Interrupt Vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL ENABLE RESET – – – DBUFMODE – PRIMODE 51 +0x01 Reserved – – – – – – – – +0x02 Reserved – – – – – – – – +0x03 INTFLAGS – – CH1ERRIF CH0ERRIF – – CH1TRNFIF CH0TRNFIF 51 +0x04 STATUS – – CH1BUSY CH0BUSY – – CH1PEND CH0PEND 52 +0x05 Reserved – – – – – – – – +0x06 TEMPL TEMP[7:0] 52 +0x07 TEMPH TEMP[15:8] 53 +0x10 CH0 Offset Offset address for DMA Channel 0 +0x20 CH1 Offset Offset address for DMA Channel 1 +0x30 Reserved – – – – – – – – +0x40 Reserved – – – – – – – – Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRLA ENABLE RESET REPEAT TRFREQ – SINGLE BURSTLEN[1:0] 53 +0x01 CTRLB CHBUSY CHPEND ERRIF TRNIF ERRINTLVL[1:0] TRNINTLVL[1:0] 54 +0x02 ADDCTRL SRCRELOAD[1:0] SRCDIR[1:0] DESTRELOAD[1:0] DESTDIR[1:0] 55 +0x03 TRIGSRC TRIGSRC[7:0] 57 +0x04 TRFCNTL TRFCNT[7:0] 58 +0x05 TRFCNTH TRFCNT[15:8] 59 +0x06 REPCNT REPCNT[7:0] 59 +0x07 Reserved – – – – – – – – +0x08 SRCADDR0 SRCADDR[7:0] 59 +0x09 SRCADDR1 SRCADDR[15:8] 60 +0x0A SRCADDR2 SRCADDR[23:16] 60 +0x0B Reserved – – – – – – – – +0x0C DESTADDR0 DESTADDR[7:0] 60 +0x0D DESTADDR1 DESTADDR[15:8] 61 +0x0E DESTADDR2 DESTADDR[23:16] 61 +0x0F Reserved – – – – – – – – Offset Source Interrupt Description 0x00 CH0_vect DMA controller channel 0 interrupt vector 0x02 CH1_vect DMA controller channel 1 interrupt vector XMEGA B [MANUAL] 63 8291C–AVR–09/2014 6. Event System 6.1 Features z System for direct peripheral-to-peripheral communication and signaling z Peripherals can directly send, receive, and react to peripheral events z CPU and DMA controller independent operation z 100% predictable signal timing z Short and guaranteed response time z Four event channels for up to eight different and parallel signal routings and configurations z Events can be sent and/or used by most peripherals, clock system, and software z Additional functions include z Quadrature decoders z Digital filtering of I/O pin state z Works in active mode and idle sleep mode 6.2 Overview The event system enables direct peripheral-to-peripheral communication and signaling. It allows a change in one peripheral’s state to automatically trigger actions in other peripherals. It is designed to provide a predictable system for short and predictable response times between peripherals. It allows for autonomous peripheral control and interaction without the use of interrupts CPU or DMA controller resources, and is thus a powerful tool for reducing the complexity, size and execution time of application code. It also allows for synchronized timing of actions in several peripheral modules. A change in a peripheral’s state is referred to as an event, and usually corresponds to the peripheral’s interrupt conditions. Events can be directly passed to other peripherals using a dedicated routing network called the event routing network. How events are routed and used by the peripherals is configured in software. Figure 6-1 on page 64 shows a basic diagram of all connected peripherals. The event system can directly connect together analog converters, analog comparators, I/O port pins, the real-time counter, timer/counters, IR communication module (IRCOM) and USB interface. It can also be used to trigger DMA transactions (DMA controller). Events can also be generated from software and the peripheral clock. XMEGA B [MANUAL] 64 8291C–AVR–09/2014 Figure 6-1. Event system overview and connected peripherals. The event routing network consists of four software-configurable multiplexers that control how events are routed and used. These are called event channels, and allow for up to four parallel event configurations and routings. The maximum routing latency is two peripheral clock cycles. The event system works in both active mode and idle sleep mode. 6.3 Events In the context of the event system, an indication that a change of state within a peripheral has occurred is called an event. There are two main types of events: signaling events and data events. Signaling events only indicate a change of state while data events contain additional information about the event. The peripheral from which the event originates is called the event generator. Within each peripheral (for example, a timer/counter), there can be several event sources, such as a timer compare match or timer overflow. The peripheral using the event is called the event user, and the action that is triggered is called the event action. Timer / Counters USB ADC Real Time Counter Port pins CPU / Software DMA Controller IRCOM Event Routing Network Event System Controller clkPER Prescaler AC XMEGA B [MANUAL] 65 8291C–AVR–09/2014 Figure 6-2. Example of event source, generator, user, and action. Events can also be generated manually in software. 6.3.1 Signaling Events Signaling events are the most basic type of event. A signaling event does not contain any information apart from the indication of a change in a peripheral. Most peripherals can only generate and use signaling events. Unless otherwise stated, all occurrences of the word ”event” are to be understood as meaning signaling events. 6.3.2 Data Events Data events differ from signaling events in that they contain information that event users can decode to decide event actions based on the receiver information. Although the event routing network can route all events to all event users, those that are only meant to use signaling events do not have decoding capabilities needed to utilize data events. How event users decode data events is shown in Table 6-1 on page 66. Event users that can utilize data events can also use signaling events. This is configurable, and is described in the datasheet module for each peripheral. 6.3.3 Peripheral Clock Events Each event channel includes a peripheral clock prescaler with a range from 1 (no prescaling) to 32768. This enables configurable periodic event generation based on the peripheral clock. It is possible to periodically trigger events in a peripheral or to periodically trigger synchronized events in several peripherals. Since each event channel include a prescaler, different peripherals can receive triggers with different intervals. 6.3.4 Software Events Events can be generated from software by writing the DATA and STROBE registers. The DATA register must be written first, since writing the STROBE register triggers the operation. The DATA and STROBE registers contain one bit for each event channel. Bit n corresponds to event channel n. It is possible to generate events on several channels at the same time by writing to several bit locations at once. Software-generated events last for one clock cycle and will overwrite events from other event generators on that event channel during that clock cycle. Table 6-1 on page 66 shows the different events, how they can be manually generated, and how they are decoded. Event User Event Routing Network | Compare Match Over-/Underflow Error Timer/Counter Syncsweep Single Conversion ADC Event Generator Event Source Event Action Event Action Selection XMEGA B [MANUAL] 66 8291C–AVR–09/2014 Table 6-1. Manually generated events and decoding of events. 6.4 Event Routing Network The event routing network routes the events between peripherals. It consists of eight multiplexers (CHnMUX), which can each be configured to route any event source to any event users. The output from a multiplexer is referred to as an event channel. For each peripheral, it is selectable if and how incoming events should trigger event actions. Details on configurations can be found in the datasheet for each peripheral. The event routing network is shown in Figure 6-3 on page 67. STROBE DATA Data Event User Signaling Event User 0 0 No event No event 0 1 Data event 01 No event 1 0 Data event 02 Signaling event 1 1 Data event 03 Signaling event XMEGA B [MANUAL] 67 8291C–AVR–09/2014 Figure 6-3. Event routing network. Four multiplexers means that it is possible to route up to four events at the same time. It is also possible to route one event through several multiplexers. Not all XMEGA devices contain all peripherals. This only means that a peripheral is not available for generating or using events. The network configuration itself is compatible between all devices. 6.5 Event Timing An event normally lasts for one peripheral clock cycle, but some event sources, such as a low level on an I/O pin, will generate events continuously. Details on this are described in the datasheet for each peripheral, but unless otherwise stated, an event lasts for one peripheral clock cycle. (48) PORTA PORTB PORTC PORTD PORTE PORTF ADCA TCF0 (6) TCE0 TCD0 TCC0 TCC1 (6) (4) (4) (4) (4) (10) (6) (29) (4) (4) (4) RTC ClkPER (8) (8) (8) (8) (8) (8) CH0MUX[7:0] CH1MUX[7:0] CH2MUX[7:0] CH3MUX[7:0] CH0CTRL[7:0] CH1CTRL[7:0] CH2CTRL[7:0] CH3CTRL[7:0] Event Channel 3 Event Channel 2 Event Channel 1 Event Channel 0 (6) (16) (2) ACA (3) USB (4) XMEGA B [MANUAL] 68 8291C–AVR–09/2014 It takes a maximum of two peripheral clock cycles from when an event is generated until the event actions in other peripherals are triggered. This ensures short and 100% predictable response times, independent of CPU or DMA controller load or software revisions. 6.6 Filtering Each event channel includes a digital filter. When this is enabled, an event must be sampled with the same value for a configurable number of system clock cycles before it is accepted. This is primarily intended for pin change events. 6.7 Quadrature Decoder The event system includes one quadrature decoder (QDEC), which enable the device to decode quadrature input on I/O pins and send data events that a timer/counter can decode to count up, count down, or index/reset. Table 6-2 summarizes which quadrature decoder data events are available, how they are decoded, and how they can be generated. The QDEC and related features, control and status registers are available for event channel 0. Table 6-2. Quadrature decoder data events. 6.7.1 Quadrature Operation A quadrature signal is characterized by having two square waves that are phase shifted 90 degrees relative to each other. Rotational movement can be measured by counting the edges of the two waveforms. The phase relationship between the two square waves determines the direction of rotation. Figure 6-4. Quadrature signals from a rotary encoder. Figure 6-4 shows typical quadrature signals from a rotary encoder. The signals QDPH0 and QDPH90 are the two quadrature signals. When QDPH90 leads QDPH0, the rotation is defined as positive or forward. When QDPH0 leads QDPH90, the rotation is defined as negative or reverse. The concatenation of the two phase signals is called the quadrature state or the phase state. STROBE DATA Data Event User Signaling Event User 0 0 No event No event 0 1 Index/reset No event 1 0 Count down Signaling event 1 1 Count up Signaling event XMEGA B [MANUAL] 69 8291C–AVR–09/2014 In order to know the absolute rotary displacement, a third index signal (QINDX) can be used. This gives an indication once per revolution. 6.7.2 QDEC Setup For a full QDEC setup, the following is required: z Tho or three I/O port pins for quadrature signal input z Two event system channels for quadrature decoding z One timer/counter for up, down, and optional index count The following procedure should be used for QDEC setup: 1. Choose two successive pins on a port as QDEC phase inputs. 2. Set the pin direction for QDPH0 and QDPH90 as input. 3. Set the pin configuration for QDPH0 and QDPH90 to low level sense. 4. Select the QDPH0 pin as a multiplexer input for an event channel, n. 5. Enable quadrature decoding and digital filtering in the event channel. 6. Optional: 1. Set up a QDEC index (QINDX). 2. Select a third pin for QINDX input. 3. Set the pin direction for QINDX as input. 4. Set the pin configuration for QINDX to sense both edges. 5. Select QINDX as a multiplexer input for event channel n+1 6. Set the quadrature index enable bit in event channel n+1. 7. Select the index recognition mode for event channel n+1. 7. Set quadrature decoding as the event action for a timer/counter. 8. Select event channel n as the event source for the timer/counter. z Set the period register of the timer/counter to ('line count' * 4 - 1), the line count of the quadrature encoder. z Enable the timer/counter without clock prescaling. The angle of a quadrature encoder attached to QDPH0, QDPH90 (and QINDX) can now be read directly from the timer/counter count register. If the count register is different from BOTTOM when the index is recognized, the timer/counter error flag is set. Similarly, the error flag is set if the position counter passes BOTTOM without the recognition of the index. XMEGA B [MANUAL] 70 8291C–AVR–09/2014 6.8 Register Description 6.8.1 CHnMUX – Event Channel n Multiplexer register z Bit 7:0 – CHnMUX[7:0]: Channel Multiplexer These bits select the event source according to Table 6-3. This table is valid for all XMEGA devices regardless of whether the peripheral is present or not. Selecting event sources from peripherals that are not present will give the same result as when this register is zero. When this register is zero, no events are routed through. Manually generated events will override CHnMUX and be routed to the event channel even if this register is zero. Table 6-3. CHnMUX[7:0] bit settings. Bit 7 6 5 4 3 2 1 0 CHnMUX[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 CHnMUX[7:4] CHnMUX[3:0] Group Configuration Event Source 0000 0 0 0 0 None (manually generated events only) 0000 0 0 0 1 (Reserved) 0000 0 0 1 X (Reserved) 0000 0 1 X X (Reserved) 0000 1 0 0 0 RTC_OVF RTC overflow 0000 1 0 0 1 RTC_CMP RTC compare match 0000 1 0 1 0 USB start of frame on CH0(2) USB error on CH1(2) USB overflow on CH2(2) USB setup on CH3(2) 0000 1 0 1 X (Reserved) 0000 1 1 X X (Reserved) 0001 0 0 0 0 ACA_CH0 ACA channel 0 0001 0 0 0 1 ACA_CH1 ACA channel 1 0001 0 0 1 0 ACA_WIN ACA window 0001 0 0 1 1 (Reserved) 0001 0 1 X X (Reserved) 0001 1 X X X (Reserved) 0010 0 0 0 0 ADCA_CH0 ADCA 0010 0 0 0 1 (Reserved) 0010 0 0 1 X (Reserved) 0010 0 1 X X (Reserved) XMEGA B [MANUAL] 71 8291C–AVR–09/2014 Notes: 1. The description of how the ports generate events is described in “Port Event” on page 130. 2. The different USB events can be selected for only event channel, 0 to 3. Table 6-4. Timer/counter events 0010 1 X X X (Reserved) 0011 X X X X (Reserved) 0100 X X X X (Reserved) 0101 0 n PORTA_PINn(1) PORTA pin n (n= 0, 1, 2 ... or 7) 0101 1 n PORTB_PINn(1) PORTB pin n (n= 0, 1, 2 ... or 7) 0110 0 n PORTC_PINn(1) PORTC pin n (n= 0, 1, 2 ... or 7) 0110 1 n PORTD_PINn(1) PORTD pin n (n= 0, 1, 2 ... or 7) 0111 0 n PORTE_PINn(1) PORTE pin n (n= 0, 1, 2 ... or 7) 0111 1 n PORTF_PINn(1) PORTF pin n (n= 0, 1, 2 ... or 7) 1000 M PRESCALER_M ClkPER divide by 2M (M=0 to 15) 1001 X X X X (Reserved) 1010 X X X X (Reserved) 1011 X X X X (Reserved) 1100 0 E See Table 6-4 Timer/counter C0 event type E 1100 1 E See Table 6-4 Timer/counter C1 event type E 1101 0 E See Table 6-4 Timer/counter D0 event type E 1111 1 X X X (Reserved) 1110 0 E See Table 6-4 Timer/counter E0 event type E 1111 1 X X X (Reserved) 1111 0 E See Table 6-4 Timer/counter F0 event type E 1111 1 X X X (Reserved) T/C Event E Group Configuration Event Type 0 0 0 TCxn_OVF Over/Underflow (x = C, D, E or F) (n= 0 or 1) 0 0 1 TCxn_ERR Error (x = C, D, E or F) (n= 0 or 1) 0 1 X – (Reserved) 1 0 0 TCxn_CCA Capture or compare A (x = C, D, E or F) (n= 0 or 1) 1 0 1 TCxn_CCB Capture or compare B (x = C, D, E or F) (n= 0 or 1) 1 1 0 TCxn_CCC Capture or compare C (x = C, D, E or F) (n= 0) 1 1 1 TCxn_CCD Capture or compare D (x = C, D, E or F) (n= 0) CHnMUX[7:4] CHnMUX[3:0] Group Configuration Event Source XMEGA B [MANUAL] 72 8291C–AVR–09/2014 6.8.2 CHnCTRL – Event Channel n Control register Note: 1. Only available for CH0CTRL and CH2CTRL. These bits are reserved in CH1CTRL and CH3CTRL. z Bit 7 – Reserved This bit is reserved and will always be read as zero. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 6:5 – QDIRM[1:0]: Quadrature Decode Index Recognition Mode These bits determine the quadrature state for the QDPH0 and QDPH90 signals, where a valid index signal is recognized and the counter index data event is given according to Table 6-5. These bits should only be set when a quadrature encoder with a connected index signal is used.These bits are available only for CH0CTRL and CH2CTRL. Table 6-5. QDIRM bit settings. z Bit 4 – QDIEN: Quadrature Decode Index Enable When this bit is set, the event channel will be used as a QDEC index source, and the index data event will be enabled. This bit is available only for CH0CTRL and CH2CTRL. z Bit 3 – QDEN: Quadrature Decode Enable Setting this bit enables QDEC operation. This bit is available only for CH0CTRL and CH2CTRL. z Bit 2:0 – DIGFILT[2:0]: Digital Filter Coefficient These bits define the length of digital filtering used, according to Table 6-6 on page 72. Events will be passed through to the event channel only when the event source has been active and sampled with the same level for the number of peripheral clock cycles defined by DIGFILT. Bit 7 6 5 4 3 2 1 0 – QDIRM[1:0](1) QDIEN(1) QDEN(1) DIGFILT[2:0] – – – – – DIGFILT[2:0] Read/Write R R/W R/W R/W R/W R/W R/W R Initial Value 0 0 0 0 0 0 0 0 QDIRM[1:0] Index Recognition State 0 0 {QDPH0, QDPH90} = 0b00 0 1 {QDPH0, QDPH90} = 0b01 1 0 {QDPH0, QDPH90} = 0b10 1 1 {QDPH0, QDPH90} = 0b11 Table 6-6. Digital filter coefficient values . DIGFILT[2:0] Group Configuration Description 000 1SAMPLE One sample 001 2SAMPLES Two samples 010 3SAMPLES Three samples XMEGA B [MANUAL] 73 8291C–AVR–09/2014 6.8.3 STROBE – Strobe register If the STROBE register location is written, each event channel will be set according to the STROBE[n] and corresponding DATA[n] bit settings, if any are unequal to zero. A single event lasting for one peripheral clock cycle will be generated. 6.8.4 DATA – Data register This register contains the data value when manually generating a data event. This register must be written before the STROBE register. For details, See ”STROBE – Strobe register” on page 73. 011 4SAMPLES Four samples 100 5SAMPLES Five samples 101 6SAMPLES Six samples 110 7SAMPLES Seven samples 111 8SAMPLES Eight samples Table 6-6. Digital filter coefficient values (Continued). DIGFILT[2:0] Group Configuration Description Bit 7 6 5 4 3 2 1 0 +0x10 STROBE[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x11 DATA[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 74 8291C–AVR–09/2014 6.9 Register Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CH0MUX CH0MUX[7:0] 70 +0x01 CH1MUX CH1MUX[7:0] 70 +0x02 CH2MUX CH2MUX[7:0] 70 +0x03 CH3MUX CH3MUX[7:0] 70 +0x04 Reserved – – – – – – – – +0x05 Reserved – – – – – – – – +0x06 Reserved – – – – – – – – +0x07 Reserved – – – – – – – – +0x08 CH0CTRL – QDIRM[1:0] QDIEN QDEN DIGFILT[2:0] 72 +0x09 CH1CTRL – – – – – DIGFILT[2:0] 72 +0x0A CH2CTRL – QDIRM[1:0] QDIEN QDEN DIGFILT[2:0] 72 +0x0B CH3CTRL – – – – – DIGFILT[2:0] 72 +0x0C Reserved – – – – – – – – +0x0D Reserved – – – – – – – – +0x0E Reserved – – – – – – – – +0x0F Reserved – – – – – – – – +0x10 STROBE STROBE[7:0] 73 +0x11 DATA DATA[7:0] 73 XMEGA B [MANUAL] 75 8291C–AVR–09/2014 7. System Clock and Clock Options 7.1 Features z Fast start-up time z Safe run-time clock switching z Internal oscillators: z 32MHz run-time calibrated and tunable oscillator z 2MHz run-time calibrated oscillator z 32.768kHz calibrated oscillator z 32kHz ultra low power (ULP) oscillator with 1kHz output z External clock options z 0.4MHz - 16MHz crystal oscillator z 32.768kHz crystal oscillator z External clock z PLL with 20MHz - 128MHz output frequency z Internal and external clock options and 1x to 31x multiplication z Lock detector z Clock prescalers with 1x to 2048x division z Fast peripheral clocks running at 2 and 4 times the CPU clock z Automatic run-time calibration of internal oscillators z External oscillator and PLL lock failure detection with optional non-maskable interrupt 7.2 Overview XMEGA devices have a flexible clock system supporting a large number of clock sources. It incorporates both accurate internal oscillators and external crystal oscillator and resonator support. A high-frequency phase locked loop (PLL) and clock prescalers can be used to generate a wide range of clock frequencies. A calibration feature (DFLL) is available, and can be used for automatic run-time calibration of the internal oscillators to remove frequency drift over voltage and temperature. An oscillator failure monitor can be enabled to issue a non-maskable interrupt and switch to the internal oscillator if the external oscillator or PLL fails. When a reset occurs, all clock sources except the 32kHz ultra low power oscillator are disabled. After reset, the device will always start up running from the 2MHz internal oscillator. During normal operation, the system clock source and prescalers can be changed from software at any time. Figure 7-1 on page 76 presents the principal clock system in the XMEGA family of devices. Not all of the clocks need to be active at a given time. The clocks for the CPU and peripherals can be stopped using sleep modes and power reduction registers, as described in “Power Management and Sleep Modes” on page 94. XMEGA B [MANUAL] 76 8291C–AVR–09/2014 Figure 7-1. The clock system, clock sources, and clock distribution. Real Time Counter Peripherals RAM AVR CPU Non-Volatile Memory Watchdog Timer Brown-out Detector System Clock Prescalers USB Prescaler System Clock Multiplexer (SCLKSEL) PLLSRC RTCSRC DIV32 32 kHz Int. ULP 32.768 kHz Int. OSC 32.768 kHz TOSC 2 MHz Int. Osc 32 MHz Int. Osc 0.4 – 16 MHz XTAL DIV32 DIV32 DIV4 XOSCSEL PLL USBSRC TOSC1 TOSC2 XTAL1 XTAL2 clkSYS clkRTC clkPER2 clkPER clkCPU clkPER4 clkUSB XMEGA B [MANUAL] 77 8291C–AVR–09/2014 7.3 Clock Distribution Figure 7-1 on page 76 presents the principal clock distribution system used in XMEGA devices. 7.3.1 System Clock - ClkSYS The system clock is the output from the main system clock selection. This is fed into the prescalers that are used to generate all internal clocks except the asynchronous and USB clocks. 7.3.2 CPU Clock - ClkCPU The CPU clock is routed to the CPU and nonvolatile memory. Halting the CPU clock inhibits the CPU from executing instructions. 7.3.3 Peripheral Clock - ClkPER The majority of peripherals and system modules use the peripheral clock. This includes the DMA controller, event system, interrupt controller, external bus interface and RAM. This clock is always synchronous to the CPU clock, but may run even when the CPU clock is turned off. 7.3.4 Peripheral 2x/4x Clocks - ClkPER2/ClkPER4 Modules that can run at two or four times the CPU clock frequency can use the peripheral 2x and peripheral 4x clocks. 7.3.5 Asynchronous Clock - ClkRTC The asynchronous clock allows the real-time counter (RTC) to be clocked directly from an external 32.768kHz crystal oscillator or the 32 times prescaled output from the internal 32.768kHz oscillator or ULP oscillator. The dedicated clock domain allows operation of this peripheral even when the device is in sleep mode and the rest of the clocks are stopped. 7.3.6 USB Clock - ClkUSB The USB device module requires a 12MHz or 48MHz clock. It has a separate clock source selection in order to avoid system clock source limitations when USB is used. 7.4 Clock Sources The clock sources are divided in two main groups: internal oscillators and external clock sources. Most of the clock sources can be directly enabled and disabled from software, while others are automatically enabled or disabled, depending on peripheral settings. After reset, the device starts up running from the 2MHz internal oscillator. The other clock sources, DFLLs and PLL, are turned off by default. 7.4.1 Internal Oscillators The internal oscillators do not require any external components to run. For details on characteristics and accuracy of the internal oscillators, refer to the device datasheet. 7.4.1.1 32kHz Ultra Low Power Oscillator This oscillator provides an approximate 32kHz clock. The 32kHz ultra low power (ULP) internal oscillator is a very low power clock source, and it is not designed for high accuracy.The oscillator employs a built-in prescaler that provides a 1kHz output, see “RTCCTRL – RTC Control register” on page 85 for details. The oscillator is automatically enabled/disabled when it is used as clock source for any part of the device. This oscillator can be selected as the clock source for the RTC. 7.4.1.2 32.768kHz Calibrated Oscillator This oscillator provides an approximate 32.768kHz clock. It is calibrated during production to provide a default frequency close to its nominal frequency. The calibration register can also be written from software for run-time calibration of the oscillator frequency. The oscillator employs a built-in prescaler, which provides both a 32.768kHz output and a 1.024kHz XMEGA B [MANUAL] 78 8291C–AVR–09/2014 output, see “RTCCTRL – RTC Control register” on page 85 for details. 7.4.1.3 32MHz Run-time Calibrated Oscillator The 32MHz run-time calibrated internal oscillator is a high-frequency oscillator. It is calibrated during production to provide a default frequency close to its nominal frequency. A digital frequency looked loop (DFLL) can be enabled for automatic run-time calibration of the oscillator to compensate for temperature and voltage drift and optimize the oscillator accuracy. This oscillator can also be adjusted and calibrated to any frequency between 30MHz and 55MHz. The production signature row contains 48 MHz calibration values intended used when the oscillator is used a full-speed USB clock source. 7.4.1.4 2MHz Run-time Calibrated Oscillator The 2MHz run-time calibrated internal oscillator is the default system clock source after reset. It is calibrated during production to provide a default frequency close to its nominal frequency. A DFLL can be enabled for automatic run-time calibration of the oscillator to compensate for temperature and voltage drift and optimize the oscillator accuracy. 7.4.2 External Clock Sources The XTAL1 and XTAL2 pins can be used to drive an external oscillator, either a quartz crystal or a ceramic resonator. XTAL1 can be used as input for an external clock signal. The TOSC1 and TOSC2 pins is dedicated to driving a 32.768kHz crystal oscillator. 7.4.2.1 0.4MHz - 16MHz Crystal Oscillator This oscillator can operate in four different modes optimized for different frequency ranges, all within 0.4MHz - 16MHz. Figure 7-2 shows a typical connection of a crystal oscillator or resonator. Figure 7-2. Crystal oscillator connection. Two capacitors, C1 and C2, may be added to match the required load capacitance for the connected crystal. 7.4.2.2 External Clock Input To drive the device from an external clock source, XTAL1 must be driven as shown in Figure 7-3 on page 78. In this mode, XTAL2 can be used as a general I/O pin. Figure 7-3. External clock drive configuration. C1 C2 XTAL2 XTAL1 GND General Purpose I/O XTAL2 XTAL1 External Clock Signal XMEGA B [MANUAL] 79 8291C–AVR–09/2014 7.4.2.3 32.768kHz Crystal Oscillator A 32.768kHz crystal oscillator can be connected between the TOSC1 and TOSC2 pins and enables a dedicated low frequency oscillator input circuit. A typical connection is shown in Figure 7-4 on page 79. A low power mode with reduced voltage swing on TOSC2 is available. This oscillator can be used as a clock source for the system clock and RTC, and as the DFLL reference clock. Figure 7-4. 32.768kHz crystal oscillator connection. Two capacitors, C1 and C2, may be added to match the required load capacitance for the connected crystal. For details on recommended TOSC characteristics and capacitor load, refer to device datasheets. 7.5 System Clock Selection and Prescalers All the calibrated internal oscillators, the external clock sources (XOSC), and the PLL output can be used as the system clock source. The system clock source is selectable from software, and can be changed during normal operation. Built-in hardware protection prevents unsafe clock switching. It is not possible to select a non-stable or disabled oscillator as the clock source, or to disable the oscillator currently used as the system clock source. Each oscillator option has a status flag that can be read from software to check that the oscillator is ready. The system clock is fed into a prescaler block that can divide the clock signal by a factor from 1 to 2048 before it is routed to the CPU and peripherals. The prescaler settings can be changed from software during normal operation. The first stage, prescaler A, can divide by a factor of from 1 to 512. Then, prescalers B and C can be individually configured to either pass the clock through or combine divide it by a factor from 1 to 4. The prescaler guarantees that derived clocks are always in phase, and that no glitches or intermediate frequencies occur when changing the prescaler setting. The prescaler settings are updated in accordance with the rising edge of the slowest clock. Figure 7-5. System clock selection and prescalers. Prescaler A divides the system clock, and the resulting clock is clkPER4. Prescalers B and C can be enabled to divide the clock speed further to enable peripheral modules to run at twice or four times the CPU clock frequency. If Prescalers B and C are not used, all the clocks will run at the same frequency as the output from Prescaler A. The system clock selection and prescaler registers are protected by the configuration change protection mechanism, employing a timed write procedure for changing the system clock and prescaler settings. For details, refer to “Configuration Change Protection” on page 13. C1 C2 TOSC2 TOSC1 GND Prescaler A 1, 2, 4, ... , 512 Prescaler B 1, 2, 4 Prescaler C 1, 2 Internal 2MHz Osc. Internal 32.768kHz Osc. Internal 32MHz Osc. External Oscillator or Clock. ClkCPU Clock Selection ClkPER ClkSYS ClkPER4 ClkPER2 Internal PLL. XMEGA B [MANUAL] 80 8291C–AVR–09/2014 7.6 PLL with 1x-31x Multiplication Factor The built-in phase locked loop (PLL) can be used to generate a high-frequency system clock. The PLL has a userselectable multiplication factor of from 1 to 31. The output frequency, fOUT, is given by the input frequency, fIN, multiplied by the multiplication factor, PLL_FAC. Four different clock sources can be chosen as input to the PLL: z 2MHz internal oscillator z 32MHz internal oscillator divided by 4 z 0.4MHz - 16MHz crystal oscillator z External clock To enable the PLL, the following procedure must be followed: 1. Enable reference clock source. 2. Set the multiplication factor and select the clock reference for the PLL. 3. Wait until the clock reference source is stable. 4. Enable the PLL. Hardware ensures that the PLL configuration cannot be changed when the PLL is in use. The PLL must be disabled before a new configuration can be written. It is not possible to use the PLL before the selected clock source is stable and the PLL has locked. The reference clock source cannot be disabled while the PLL is running. 7.7 DFLL 2MHz and DFLL 32MHz Two built-in digital frequency locked loops (DFLLs) can be used to improve the accuracy of the 2MHz and 32MHz internal oscillators. The DFLL compares the oscillator frequency with a more accurate reference clock to do automatic run-time calibration of the oscillator and compensate for temperature and voltage drift. The choices for the reference clock sources are: z 32.768kHz calibrated internal oscillator z 32.768kHz crystal oscillator connected to the TOSC pins z External clock z USB start of frame The DFLLs divide the oscillator reference clock by 32 to use a 1.024kHz reference. The reference clock is individually selected for each DFLL, as shown on Figure 7-6 on page 81. f OUT f IN = ⋅ PLL_FAC XMEGA B [MANUAL] 81 8291C–AVR–09/2014 Figure 7-6. DFLL reference clock selection. The ideal counter value representing the frequency ratio between the internal oscillator and a 1.024kHz reference clock is loaded into the DFLL oscillator compare register (COMP) during reset. For the 32MHz oscillator, this register can be written from software to make the oscillator run at a different frequency or when the ratio between the reference clock and the oscillator is different (for example when the USB start of frame is used). The 48MHz calibration values must be read from the production signature row and written to the 32MHz CAL register before the DFLL is enabled with USB SOF as reference source. The value that should be written to the COMP register is given by the following formula: When the DFLL is enabled, it controls the ratio between the reference clock frequency and the oscillator frequency. If the internal oscillator runs too fast or too slow, the DFLL will decrement or increment its calibration register value by one to adjust the oscillator frequency. The oscillator is considered running too fast or too slow when the error is more than a half calibration step size. 32.768 kHz Crystal Osc External Clock 32.768 kHz Int. Osc DFLL32M 32 MHz Int. RCOSC DFLL2M 2 MHz Int. RCOSC clkRC32MCREF clkRC2MCREF TOSC1 TOSC2 XTAL1 DIV32 DIV32 XOSCSEL USB Start of Frame XMEGA B [MANUAL] 82 8291C–AVR–09/2014 Figure 7-7. Automatic run-time calibration. The DFLL will stop when entering a sleep mode where the oscillators are stopped. After wake up, the DFLL will continue with the calibration value found before entering sleep. The reset value of the DFLL calibration register can be read from the production signature row. When the DFLL is disabled, the DFLL calibration register can be written from software for manual run-time calibration of the oscillator. 7.8 PLL and External Clock Source Failure Monitor A built-in failure monitor is available for the PLL and external clock source. If the failure monitor is enabled for the PLL and/or the external clock source, and this clock source fails (the PLL looses lock or the external clock source stops) while being used as the system clock, the device will: z Switch to run the system clock from the 2MHz internal oscillator z Reset the oscillator control register and system clock selection register to their default values z Set the failure detection interrupt flag for the failing clock source (PLL or external clock) z Issue a non-maskable interrupt (NMI) If the PLL or external clock source fails when not being used for the system clock, it is automatically disabled, and the system clock will continue to operate normally. No NMI is issued. The failure monitor is meant for external clock sources above 32kHz. It cannot be used for slower external clocks. When the failure monitor is enabled, it will not be disabled until the next reset. The failure monitor is stopped in all sleep modes where the PLL or external clock source are stopped. During wake up from sleep, it is automatically restarted. The PLL and external clock source failure monitor settings are protected by the configuration change protection mechanism, employing a timed write procedure for changing the settings. For details, refer to “Configuration Change Protection” on page 13. DFLL CNT COMP 0 tRCnCREF Frequency OK RCOSC fast, CALA decremented RCOSC slow, CALA incremented clkRCnCREF XMEGA B [MANUAL] 83 8291C–AVR–09/2014 7.9 Register Description – Clock 7.9.1 CTRL – Control register z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2:0 – SCLKSEL[2:0]: System Clock Selection These bits are used to select the source for the system clock. See Table 7-1 for the different selections. Changing the system clock source will take two clock cycles on the old clock source and two more clock cycles on the new clock source. These bits are protected by the configuration change protection mechanism. For details, refer to “Configuration Change Protection” on page 13. SCLKSEL cannot be changed if the new clock source is not stable. The old clock can not be disabled until the clock switching is completed. Table 7-1. System clock selection. 7.9.2 PSCTRL – Prescaler register This register is protected by the configuration change protection mechanism. For details, refer to “Configuration Change Protection” on page 13. z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. Bit 7 6 5 4 3 2 1 0 +0x00 – – – – – SCLKSEL[2:0] Read/Write R R R R R R/W R/W R/W Initial Value 0 0 0 00000 SCLKSEL[2:0] Group Configuration Description 000 RC2MHZ 2MHz internal oscillator 001 RC32MHZ 32MHz internal oscillator 010 RC32KHZ 32.768kHz internal oscillator 011 XOSC External oscillator or clock 100 PLL Phase locked loop 101 – Reserved 110 – Reserved 111 – Reserved Bit 7 6 5 4 3 2 1 0 +0x01 – PSADIV[4:0] PSBCDIV Read/Write R R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 84 8291C–AVR–09/2014 z Bit 6:2 – PSADIV[4:0]: Prescaler A Division Factor These bits define the division ratio of the clock prescaler A according to Table 7-2. These bits can be written at run-time to change the frequency of the ClkPER4 clock relative to the system clock, ClkSYS. Table 7-2. Prescaler A division factor. z Bit 1:0 – PSBCDIV: Prescaler B and C Division Factors These bits define the division ratio of the clock prescalers B and C according to Table 7-3. Prescaler B will set the clock frequency for the ClkPER2 clock relative to the ClkPER4 clock. Prescaler C will set the clock frequency for the ClkPER and ClkCPU clocks relative to the ClkPER2 clock. Refer to Figure 7-5 on page 79 fore more details. Table 7-3. Prescaler B and C division factors. PSADIV[4:0] Group Configuration Description 00000 1 No division 00001 2 Divide by 2 00011 4 Divide by 4 00101 8 Divide by 8 00111 16 Divide by 16 01001 32 Divide by 32 01011 64 Divide by 64 01101 128 Divide by 128 01111 256 Divide by 256 10001 512 Divide by 512 10101 – Reserved 10111 – Reserved 11001 – Reserved 11011 – Reserved 11101 – Reserved 11111 – Reserved PSBCDIV[1:0] Group Configuration Prescaler B division Prescaler C division 00 1_1 No division No division 01 1_2 No division Divide by 2 10 4_1 Divide by 4 No division 11 2_2 Divide by 2 Divide by 2 XMEGA B [MANUAL] 85 8291C–AVR–09/2014 7.9.3 LOCK – Lock register z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – LOCK: Clock System Lock When this bit is written to one, the CTRL and PSCTRL registers cannot be changed, and the system clock selection and prescaler settings are protected against all further updates until after the next reset. This bit is protected by the configuration change protection mechanism. For details, refer to “Configuration Change Protection” on page 13. The LOCK bit can be cleared only by a reset. 7.9.4 RTCCTRL – RTC Control register z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:1 – RTCSRC[2:0]: RTC Clock Source These bits select the clock source for the real-time counter according to Table 7-4. Table 7-4. RTC clock source selection. z Bit 0 – RTCEN: RTC Clock Source Enable Setting the RTCEN bit enables the selected RTC clock source for the real-time counter. Bit 7 6 5 4 3 2 1 0 +0x02 – – – – – – – LOCK Read/Write R R R R R R R R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x03 – – – – RTCSRC[2:0] RTCEN Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 RTCSRC[2:0] Group Configuration Description 000 ULP 1kHz from 32kHz internal ULP oscillator 001 TOSC 1.024kHz from 32.768kHz crystal oscillator on TOSC 010 RCOSC 1.024kHz from 32.768kHz internal oscillator 011 — Reserved 100 — Reserved 101 TOSC32 32.768kHz from 32.768kHz crystal oscillator on TOSC 110 RCOSC32 32.768kHz from 32.768kHz internal oscillator 111 EXTCLK External clock from TOSC1 XMEGA B [MANUAL] 86 8291C–AVR–09/2014 7.9.5 USBSCTRL – USB Control register z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5:3 – USBPSDIV[2:0]: USB Prescaler Division Factor These bits define the division ratio of the USB clock prescaler according to Table 7-5. These bits are locked as long as the USB clock source is enabled. Table 7-5. USB prescaler division factor. z Bit 2:1 – USBSRC[1:0]: USB Clock Source These bits select the clock source for the USB module according to Table 7-6. Table 7-6. USB clock source. Note: 1. The 32MHz internal oscillator must be calibrated to 48MHz before selecting this as source for the USB device module. Refer to “DFLL 2MHz and DFLL 32MHz” on page 80. z Bit 0 – USBSEN: USB Clock Source Enable Setting this bit enables the selected clock source for the USB device module. Bit 7 6 5 4 3 2 1 0 +0x04 – – USBPSDIV[2:0] USBSRC[1:0] USBSEN Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 USBPSDIV[2:0] Group Configuration Description 000 1 No division 001 2 Divide by 2 010 4 Divide by 4 011 8 Divide by 8 100 16 Divide by 16 101 32 Divide by 32 110 — Reserved 111 — Reserved USBSRC[1:0] Group Configuration Description 00 PLL PLL 01 RC32M 32MHz internal oscillator(1) XMEGA B [MANUAL] 87 8291C–AVR–09/2014 7.10 Register Description – Oscillator 7.10.1 CTRL – Oscillator Control register z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4 – PLLEN: PLL Enable Setting this bit enables the PLL. Before the PLL is enabled, it must be configured with the desired multiplication factor and clock source. See ”STATUS – Oscillator Status register” on page 87. z Bit 3 – XOSCEN: External Oscillator Enable Setting this bit enables the selected external clock source. Refer to “XOSCCTRL – XOSC Control register” on page 88 for details on how to select the external clock source. The external clock source should be allowed time to stabilize before it is selected as the source for the system clock. See ”STATUS – Oscillator Status register” on page 87. z Bit 2 – RC32KEN: 32.768kHz Internal Oscillator Enable Setting this bit enables the 32.768kHz internal oscillator. The oscillator must be stable before it is selected as the source for the system clock. See ”STATUS – Oscillator Status register” on page 87. z Bit 1 – RC32MEN: 32MHz Internal Oscillator Enable Setting this bit will enable the 32MHz internal oscillator. The oscillator must be stable before it is selected as the source for the system clock. See ”STATUS – Oscillator Status register” on page 87. z Bit 0 – RC2MEN: 2MHz Internal Oscillator Enable Setting this bit enables the 2MHz internal oscillator. The oscillator must be stable before it is selected as the source for the system clock. See ”STATUS – Oscillator Status register” on page 87. By default, the 2MHz internal oscillator is enabled and this bit is set. 7.10.2 STATUS – Oscillator Status register z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4 – PLLRDY: PLL Ready This flag is set when the PLL has locked on the selected frequency and is ready to be used as the system clock source. z Bit 3 – XOSCRDY: External Clock Source Ready This flag is set when the external clock source is stable and is ready to be used as the system clock source. z Bit 2 – RC32KRDY: 32.768kHz Internal Oscillator Ready This flag is set when the 32.768kHz internal oscillator is stable and is ready to be used as the system clock source. Bit 7 6 5 4 3 2 1 0 +0x00 – – – PLLEN XOSCEN RC32KEN RC32MEN RC2MEN Read/Write R R R R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 1 Bit 7 6 5 4 3 2 1 0 +0x01 – – – PLLRDY XOSCRDY RC32KRDY RC32MRDY RC2MRDY Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 88 8291C–AVR–09/2014 z Bit 1 – RC32MRDY: 32MHz Internal Oscillator Ready This flag is set when the 32MHz internal oscillator is stable and is ready to be used as the system clock source. z Bit 0 – RC2MRDY: 2MHz Internal Oscillator Ready This flag is set when the 2MHz internal oscillator is stable and is ready to be used as the system clock source. 7.10.3 XOSCCTRL – XOSC Control register z Bit 7:6 – FRQRANGE[1:0]: 0.4 - 16MHz Crystal Oscillator Frequency Range Select These bits select the frequency range for the connected crystal oscillator according to Table 7-7. Table 7-7. 16MHz crystal oscillator frequency range selection. z Bit 5 – X32KLPM: Crystal Oscillator 32.768kHz Low Power Mode Setting this bit enables the low power mode for the 32.768kHz crystal oscillator. This will reduce the swing on the TOSC2 pin. z Bit 4 – XOSCPWR: Crystal Oscillator Drive Setting this bit will increase the current in the 0.4MHz - 16MHz crystal oscillator and increase the swing on the XTAL2 pin. This allows for driving crystals with higher load or higher frequency than specified by the FRQRANGE bits. z Bit 3:0 – XOSCSEL[3:0]: Crystal Oscillator Selection These bits select the type and start-up time for the crystal or resonator that is connected to the XTAL or TOSC pins. See Table 7-8 on page 89 for crystal selections. If an external clock or external oscillator is selected as the source for the system clock, see “CTRL – Oscillator Control register” on page 87. This configuration cannot be changed. Bit 7 6 5 4 3 2 1 0 +0x02 FRQRANGE[1:0] X32KLPM XOSCPWR XOSCSEL[3:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0000 FRQRANGE[1:0] Group Configuration Typical Frequency Range Recommended Range for Capacitors C1 and C2 (pF) 00 04TO2 0.4MHz - 2MHz 100-300 01 2TO9 2MHz - 9MHz 10-40 10 9TO12 9MHz - 12MHz 10-40 11 12TO16 12MHz - 16MHz 10-30 XMEGA B [MANUAL] 89 8291C–AVR–09/2014 Table 7-8. External oscillator selection and start-up time.. Notes: 1. This option should be used only when frequency stability at startup is not important for the application. The option is not suitable for crystals. 2. This option is intended for use with ceramic resonators. It can also be used when the frequency stability at startup is not important for the application. 3. When the external oscillator is used as the reference for a DFLL, only EXTCLK and 32KHZ can be selected. 7.10.4 XOSCFAIL – XOSC Failure Detection register z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3 – PLLFDIF: PLL Fault Detection Flag If PLL failure detection is enabled, PLLFDIF is set when the PLL looses lock. Writing logic one to this location will clear PLLFDIF. z Bit 2 – PLLFDEN: PLL Fault Detection Enable Setting this bit will enable PLL failure detection. A non-maskable interrupt will be issued when PLLFDIF is set. This bit is protected by the configuration change protection mechanism. Refer to “Configuration Change Protection” on page 13 for details. z Bit 1 – XOSCFDIF: Failure Detection Interrupt Flag If the external clock source oscillator failure monitor is enabled, XOSCFDIF is set when a failure is detected. Writing logic one to this location will clear XOSCFDIF. z Bit 0 – XOSCFDEN: Failure Detection Enable Setting this bit will enable the failure detection monitor, and a non-maskable interrupt will be issued when XOSCFDIF is set. This bit is protected by the configuration change protection mechanism. Refer to “Configuration Change Protection” on page 13 for details. Once enabled, failure detection can only be disabled by a reset. XOSCSEL[3:0] Group Configuration Selected Clock Source Start-up Time 0000 EXTCLK(3) External Clock 6 CLK 0010 32KHZ(3) 32.768kHz TOSC 16K CLK 0011 XTAL_256CLK(1) 0.4MHz - 16MHz XTAL 256 CLK 0111 XTAL_1KCLK(2) 0.4MHz - 16MHz XTAL 1K CLK 1011 XTAL_16KCLK 0.4MHz - 16MHz XTAL 16K CLK Bit 7 6 5 4 3 2 1 0 +0x03 – – – – PLLFDIF PLLFDEN XOSCFDIF XOSCFDEN Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 90 8291C–AVR–09/2014 7.10.5 RC32KCAL – 32kHz Oscillator Calibration register z Bit 7:0 – RC32KCAL[7:0]: 32.768kHz Internal Oscillator Calibration bits This register is used to calibrate the 32.768kHz internal oscillator. A factory-calibrated value is loaded from the signature row of the device and written to this register during reset, giving an oscillator frequency close to 32.768kHz. The register can also be written from software to calibrate the oscillator frequency during normal operation. 7.10.6 PLLCTRL – PLL Control register z Bit 7:6 – PLLSRC[1:0]: Clock Source The PLLSRC bits select the input source for the PLL according to Table 7-9. Table 7-9. PLL clock source. Notes: 1. The 32.768kHz TOSC cannot be selected as the source for the PLL. An external clock must be a minimum 0.4MHz to be used as the source clock. z Bit 5 – PLLDIV: PLL Divided Output Enable Setting this bit will divide the output from the PLL by 2. z Bit 4:0 – PLLFAC[4:0]: Multiplication Factor These bits select the multiplication factor for the PLL. The multiplication factor can be in the range of from 1x to 31x. 7.10.7 DFLLCTRL – DFLL Control register z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. Bit 7 6 5 4 3 2 1 0 +0x04 RC32KCAL[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value x xxxxxxx Bit 7 6 5 4 3 2 1 0 +0x05 PLLSRC[1:0] PLLDIV PLLFAC[4:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 PLLSRC[1:0] Group Configuration PLL Input Source 00 RC2M 2MHz internal oscillator 01 — Reserved 10 RC32M 32MHz internal oscillator 11 XOSC External clock source(1) Bit 7 6 5 4 3 2 1 0 +0x06 – – – – – RC32MCREF[1:0] RC2MCREF Read/Write R R R R R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 91 8291C–AVR–09/2014 z Bit 2:1 – RC32MCREF[1:0]: 32MHz Oscillator Calibration Reference These bits are used to select the calibration source for the 32MHz DFLL according to the Table 7-10. These bits will select only which calibration source to use for the DFLL. In addition, the actual clock source that is selected must enabled and configured for the calibration to function. Table 7-10. 32MHz oscillator reference selection. z Bit 0 – RC2MCREF: 2MHz Oscillator Calibration Reference This bit is used to select the calibration source for the 2MHz DFLL. By default, this bit is zero and the 32.768kHz internal oscillator is selected. If this bit is set to one, the 32.768kHz crystal oscillator on TOSC is selected as the reference. This bit will select only which calibration source to use for the DFLL. In addition, the actual clock source that is selected must enabled and configured for the calibration to function. 7.11 Register Description – DFLL32M/DFLL2M 7.11.1 CTRL – DFLL Control register z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – ENABLE: DFLL Enable Setting this bit enables the DFLL and auto-calibration of the internal oscillator. The reference clock must be enabled and stable before the DFLL is enabled. After disabling the DFLL, the reference clock can not be disabled before the ENABLE bit is read as zero. RC32MCREF[1:0] Group Configuration Description 00 RC32K 32.768kHz internal oscillator 01 XOSC32 32.768kHz crystal oscillator on TOSC 10 USBSOF USB start of frame 11 – Reserved Bit 7 6 5 4 3 2 1 0 +0x00 – – – – – – – ENABLE Read/Write R R R R R R R R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 92 8291C–AVR–09/2014 7.11.2 CALA – DFLL Calibration Register A The CALA and CALB registers hold the 13-bit DFLL calibration value that is used for automatic run-time calibration of the internal oscillator. When the DFLL is disabled, the calibration registers can be written by software for manual run-time calibration of the oscillator. The oscillators will also be calibrated according to the calibration value in these registers when the DFLL is disabled. z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 6:0 – CALA[6:0]: DFLL Calibration Bits These bits hold the part of the oscillator calibration value that is used for automatic runtime calibration. A factorycalibrated value is loaded from the signature row of the device and written to this register during reset, giving an oscillator frequency approximate to the nominal frequency for the oscillator. The bits cannot be written when the DFLL is enabled. 7.11.3 CALB – DFLL Calibration register B z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5:0 – CALB[5:0]: DFLL Calibration bits These bits hold the part of the oscillator calibration value that is used to select the oscillator frequency. A factorycalibrated value is loaded from the signature row of the device and written to this register during reset, giving an oscillator frequency approximate to the nominal frequency for the oscillator. These bits are not changed during automatic run-time calibration of the oscillator. The bits cannot be written when the DFLL is enabled. When calibrating to a frequency different from the default, the CALA bits should be set to a middle value to maximize the range for the DFLL. 7.11.4 COMP1 – DFLL Compare register 1 The COMP1 and COMP2 register pair represent the frequency ratio between the oscillator and the reference clock. The initial value for these registers is the ratio between the internal oscillator frequency and a 1.024kHz reference z Bit 7:0 – COMP1[7:0]: Compare value byte 1 These bits hold byte 1 of the 16-bit compare register. Bit 7 6 5 4 3 2 1 0 +0x02 – CALA[6:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 x x x x x x x Bit 7 6 5 4 3 2 1 0 +0x03 – – CALB[5:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 x x x x x x Bit 7 6 5 4 3 2 1 0 +0x05 COMP[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 93 8291C–AVR–09/2014 7.11.5 COMP2 – DFLL Compare register 2 z Bit 7:0 – COMP2[15:8]: Compare Register value byte 2 These bits hold byte 2 of the 16-bit compare register. Table 7-11. Nominal DFLL32M COMP values for different output frequencies. Bit 7 6 5 4 3 2 1 0 +0x06 COMP[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Oscillator Frequency (MHz) COMP Value (ClkRCnCREF = 1.024kHz) 30.0 0x7270 32.0 0x7A12 34.0 0x81B3 36.0 0x8954 38.0 0x90F5 40.0 0x9896 42.0 0xA037 44.0 0xA7D8 46.0 0xAF79 48.0 0xB71B 50.0 0xBEBC 52.0 0xC65D 54.0 0xCDFE XMEGA B [MANUAL] 94 8291C–AVR–09/2014 7.12 Register Summary - Clock 7.13 Register Summary - Oscillator 7.14 Register Summary - DFLL32M/DFLL2M 7.15 Oscillator Failure Interrupt Vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL – – – – – SCLKSEL[2:0] 83 +0x01 PSCTRL – PSADIV[4:0] PSBCDIV[1:0] 83 +0x02 LOCK – – – – – – – LOCK 85 +0x03 RTCCTRL – – – – RTCSRC[2:0] RTCEN 85 +0x04 USBSCTR – – USBPSDIV[2:0] USBSRC[1:0] USBSEN 85 +0x05 Reserved – – – – – – – – +0x06 Reserved – – – – – – – – +0x07 Reserved – – – – – – – – Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL – – – PLLEN XOSCEN RC32KEN R32MEN RC2MEN 87 +0x01 STATUS – – – PLLRDY XOSCRDY RC32KRD R32MRDY RC2MRDY 87 +0x02 XOSCCTR FRQRANGE[1:0] X32KLPM XOSCPW XOSCSEL[3:0] 88 +0x03 XOSCFAIL – – – – PLLFDIF PLLFDEN XOSCFDIF XOSCFDEN 89 +0x04 RC32KCAL RC32KCAL[7:0] 90 +0x05 PLLCTRL PLLSRC[1:0] – PLLFAC[4:0] 90 +0x06 DFLLCTRL – – – – – RC32MCREF[1:0] RC2MCREF 90 +0x07 Reserved – – – – – – – – Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL – – – – – – – ENABLE 91 +0x01 Reserved – – – – – – – – +0x02 CALA – CALA[6:0] 92 +0x03 CALB – – CALB[5:0] 92 +0x04 Reserved – – – – – – – – +0x05 COMP1 COMP[7:0] 92 +0x06 COMP2 COMP[15:8] 93 +0x07 Reserved – – – – – – – – Offset Source Interrupt Description 0x00 OSCF_vect PLL and external oscillator failure interrupt vector (NMI) XMEGA B [MANUAL] 95 Atmel-8291C-AVR-XMEGA B -09/2014 8. Power Management and Sleep Modes 8.1 Features z Power management for adjusting power consumption and functions z Five sleep modes z Idle z Power down z Power save z Standby z Extended standby z Power reduction register to disable clock and turn off unused peripherals in active and idle modes 8.2 Overview Various sleep modes and clock gating are provided in order to tailor power consumption to application requirements. This enables the XMEGA microcontroller to stop unused modules to save power. All sleep modes are available and can be entered from active mode. In active mode, the CPU is executing application code. When the device enters sleep mode, program execution is stopped and interrupts or a reset is used to wake the device again. The application code decides which sleep mode to enter and when. Interrupts from enabled peripherals and all enabled reset sources can restore the microcontroller from sleep to active mode. In addition, power reduction registers provide a method to stop the clock to individual peripherals from software. When this is done, the current state of the peripheral is frozen, and there is no power consumption from that peripheral. This reduces the power consumption in active mode and idle sleep modes and enables much more fine-tuned power management than sleep modes alone. 8.3 Sleep Modes Sleep modes are used to shut down modules and clock domains in the microcontroller in order to save power. XMEGA microcontrollers have five different sleep modes tuned to match the typical functional stages during application execution. A dedicated sleep instruction (SLEEP) is available to enter sleep mode. Interrupts are used to wake the device from sleep, and the available interrupt wake-up sources are dependent on the configured sleep mode. When an enabled interrupt occurs, the device will wake up and execute the interrupt service routine before continuing normal program execution from the first instruction after the SLEEP instruction. If other, higher priority interrupts are pending when the wake-up occurs, their interrupt service routines will be executed according to their priority before the interrupt service routine for the wake-up interrupt is executed. After wake-up, the CPU is halted for four cycles before execution starts. Table 8-1 on page 96 shows the different sleep modes and the active clock domains, oscillators, and wake-up sources. XMEGA B [MANUAL] 96 Atmel-8291C-AVR-XMEGA B -09/2014 Table 8-1. Active clock domains and wake-up sources in the different sleep modes. The wake-up time for the device is dependent on the sleep mode and the main clock source. The startup time for the system clock source must be added to the wake-up time for sleep modes where the system clock source is not kept running. For details on the startup time for the different oscillator options, refer to “System Clock and Clock Options” on page 77. The content of the register file, SRAM and registers are kept during sleep. If a reset occurs during sleep, the device will reset, start up, and execute from the reset vector. 8.3.1 Idle Mode In idle mode the CPU and nonvolatile memory are stopped (note that any ongoing programming will be completed), but all peripherals, including the interrupt controller, event system and DMA controller are kept running. Any enabled interrupt will wake the device. 8.3.2 Power-down Mode In power-down mode, all clocks, including the real-time counter clock source, are stopped. This allows operation only of asynchronous modules that do not require a running clock. The only interrupts that can wake up the MCU are the twowire interface address match interrupt, asynchronous port interrupts, and the USB resume interrupt. 8.3.3 Power-save Mode Power-save mode is identical to power down, with two exceptions: 1. If the real-time counter (RTC) is enabled, it will keep running during sleep, and the device can also wake up from either an RTC overflow or compare match interrupt. 2. If the LCD is enabled, it will keep running during sleep, and the device can wake up from LCD frame completed interrupt. 8.3.4 Standby Mode Standby mode is identical to power down, with the exception that the enabled system clock sources are kept running while the CPU, peripheral, and RTC/LCD clocks are stopped. This reduces the wake-up time. Active Clock Domain Oscillators Wake-up Sources Sleep Modes CPU Clock Peripheral and USB Clock RTC and LCD Clock System Clock Source RTC Clock Source USB Resume Asynchronous Port Interrupts TWI Address Match Interrupts RTC and LCD Clock Interrupts All Interrupts Idle X X X X X X X X X Power down X X X Power save X X X X X X Standby X X X X Extended standby X X X X X X X XMEGA B [MANUAL] 97 Atmel-8291C-AVR-XMEGA B -09/2014 8.3.5 Extended Standby Mode Extended standby mode is identical to power-save mode, with the exception that the enabled system clock sources are kept running while the CPU and peripheral clocks are stopped. This reduces the wake-up time. 8.4 Power Reduction Registers The power reduction (PR) registers provide a method to stop the clock to individual peripherals. When this is done, the current state of the peripheral is frozen and the associated I/O registers cannot be read or written. Resources used by the peripheral will remain occupied; hence, the peripheral should be disabled before stopping the clock. Enabling the clock to a peripheral again puts the peripheral in the same state as before it was stopped. This can be used in idle mode and active modes to reduce the overall power consumption. In all other sleep modes, the peripheral clock is already stopped. Not all devices have all the peripherals associated with a bit in the power reduction registers. Setting a power reduction bit for a peripheral that is not available will have no effect. 8.5 Minimizing Power Consumption There are several possibilities to consider when trying to minimize the power consumption in an AVR MCU controlled system. In general, correct sleep modes should be selected and used to ensure that only the modules required for the application are operating. All unneeded functions should be disabled. In particular, the following modules may need special consideration when trying to achieve the lowest possible power consumption. 8.5.1 Analog-to-Digital Converter - ADC When entering idle mode, the ADC should be disabled if not used. In other sleep modes, the ADC is automatically disabled. When the ADC is turned off and on again, the next conversion will be an extended conversion. Refer to “ADC – Analog-to-Digital Converter” on page 326 for details on ADC operation. 8.5.2 Analog Comparator - AC When entering idle mode, the analog comparator should be disabled if not used. In other sleep modes, the analog comparator is automatically disabled. However, if the analog comparator is set up to use the internal voltage reference as input, the analog comparator should be disabled in all sleep modes. Otherwise, the internal voltage reference will be enabled, irrespective of sleep mode. Refer to “AC – Analog Comparator” on page 352 for details on how to configure the analog comparator. 8.5.3 Brownout Detector If the brownout detector is not needed by the application, this module should be turned off. If the brownout detector is enabled by the BODLEVEL fuses, it will be enabled in all sleep modes, and always consume power. In the deeper sleep modes, it can be turned off and set in sampled mode to reduce current consumption. Refer to “Brownout Detection” on page 109 for details on how to configure the brownout detector. 8.5.4 Watchdog Timer If the watchdog timer is not needed in the application, the module should be turned off. If the watchdog timer is enabled, it will be enabled in all sleep modes and, hence, always consume power. Refer to “WDT – Watchdog Timer” on page 115 for details on how to configure the watchdog timer. 8.5.5 Port Pins When entering a sleep mode, all port pins should be configured to use minimum power. Most important is to ensure that no pins drive resistive loads. In sleep modes where the Peripheral Clock (ClkPER) is stopped, the input buffers of the device will be disabled. This ensures that no power is consumed by the input logic when not needed. 8.5.6 On-chip Debug Systems If the On-chip debug system is enabled and the chip enters sleep mode, the main clock source is enabled and hence always consumes power. In the deeper sleep modes, this will contribute significantly to the total current consumption. XMEGA B [MANUAL] 98 Atmel-8291C-AVR-XMEGA B -09/2014 8.6 Register Description – Sleep 8.6.1 CTRL – Control Register z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:1 – SMODE[2:0]: Sleep Mode selection These bits select sleep modes according to Table 8-2. Table 8-2. Sleep mode selection. z Bit 0 – SEN: Sleep Enable This bit must be set to make the MCU enter the selected sleep mode when the SLEEP instruction is executed. To avoid unintentional entering of sleep modes, it is recommended to write SEN just before executing the SLEEP instruction and clear it immediately after waking up. 8.7 Register Description – Power Reduction 8.7.1 PRGEN – General Power Reduction register z Bit 7 – LCD: LCD Module Setting this bit stops the clock to the LCD module. When the bit is cleared the peripheral should be reinitialized to ensure proper operation. Bit 7 6 5 4 3 2 1 0 +0x00 – – – – SMODE[2:0] SEN Read/Write R R R R R/W R/W R/W R/W Initial Value 00000000 SMODE[2:0] Group configuration Description 000 IDLE Idle mode 001 – Reserved 010 PDOWN Power-down mode 011 PSAVE Power-save mode 100 – Reserved 101 – Reserved 110 STDBY Standby mode 111 ESTDBY Extended standby mode Bit 7 6 5 4 3 2 1 0 +0x00 LCD USB – AES – RTC EVSYS DMA Read/Write R/W R/W R R/W R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 99 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 6 – USB: USB Module Setting this bit stops the clock to the USB module. When this bit is cleared, the peripheral should be reinitialized to ensure proper operation. z Bit 5 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 4 – AES: AES Module Setting this bit stops the clock to the AES module. When this bit is cleared, the peripheral should be reinitialized to ensure proper operation. z Bit 3 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 2 – RTC: Real-Time Counter Setting this bit stops the clock to the real-time counter. When this bit is cleared, the peripheral should be reinitialized to ensure proper operation. z Bit 1 – EVSYS: Event System Setting this stops the clock to the event system. When this bit is cleared, the module will continue as before it was stopped. z Bit 0 – DMA: DMA Controller Setting this bit stops the clock to the DMA controller. This bit can be set only if the DMA controller is disabled. 8.7.2 PRPA/B – Power Reduction Port A/B register Note: Disabling of analog modules stops the clock to the analog blocks themselves and not only the interfaces. z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – ADC: Power Reduction ADC Setting this bit stops the clock to the ADC. The ADC should be disabled before stopped. z Bit 0 – AC: Power Reduction Analog Comparator Setting this bit stops the clock to the analog comparator. The AC should be disabled before shutdown. 8.7.3 PRPC/E – Power Reduction Port C/E Register z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. Bit 7 6 5 4 3 2 1 0 +0x01/+0x02 – – – – – – ADC AC Read/Write R R R R R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x03/+0x04/ +0x05/+0x06 – TWI – USART0 SPI HIRES TC1 TC0 Read/Write R R/W R R/W R/W R/W R/W R/W Initial Value 0 0000000 XMEGA B [MANUAL] 100 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 6 – TWI: Two-Wire Interface Setting this bit stops the clock to the two-wire interface. When this bit is cleared, the peripheral should be reinitialized to ensure proper operation. z Bit 5 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 4 – USART0 Setting this bit stops the clock to USART0. When this bit is cleared, the peripheral should be reinitialized to ensure proper operation. z Bit 3 – SPI: Serial Peripheral Interface Setting this bit stops the clock to the SPI. When this bit is cleared, the peripheral should be reinitialized to ensure proper operation. z Bit 2 – HIRES: High-Resolution Extension Setting this bit stops the clock to the high-resolution extension for the timer/counters. When this bit is cleared, the peripheral should be reinitialized to ensure proper operation. z Bit 1 – TC1: Timer/Counter 1 Setting this bit stops the clock to timer/counter 1. When this bit is cleared, the peripheral will continue like before the shut down. z Bit 0 – TC0: Timer/Counter 0 Setting this bit stops the clock to timer/counter 0. When this bit is cleared, the peripheral will continue like before the shut down. XMEGA B [MANUAL] 101 Atmel-8291C-AVR-XMEGA B -09/2014 8.8 Register Summary - Sleep 8.9 Register Summary - Power Reduction Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL – – – – SMODE[2:0] SEN 98 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 PRGEN LCD USB – AES – RTC EVSYS DMA 98 +0x01 PRPA – – – – – – ADC AC 99 +0x02 PRPB – – – – – – ADC AC 99 +0x03 PRPC – TWI – USART0 SPI HIRES TC1 TC0 99 +0x04 Reserved – – – – – – – – +0x05 PRPE – – – USART0 – – – TC0 99 XMEGA B [MANUAL] 102 Atmel-8291C-AVR-XMEGA B -09/2014 9. Reset System 9.1 Features z Reset the microcontroller and set it to initial state when a reset source goes active z Multiple reset sources that cover different situations z Power-on reset z External reset z Watchdog reset z Brownout reset z PDI reset z Software reset z Asynchronous operation z No running system clock in the device is required for reset z Reset status register for reading the reset source from the application code 9.2 Overview The reset system issues a microcontroller reset and sets the device to its initial state. This is for situations where operation should not start or continue, such as when the microcontroller operates below its power supply rating. If a reset source goes active, the device enters and is kept in reset until all reset sources have released their reset. The I/O pins are immediately tri-stated. The program counter is set to the reset vector location, and all I/O registers are set to their initial values. The SRAM content is kept. However, if the device accesses the SRAM when a reset occurs, the content of the accessed location can not be guaranteed. After reset is released from all reset sources, the default oscillator is started and calibrated before the device starts running from the reset vector address. By default, this is the lowest program memory address, 0, but it is possible to move the reset vector to the lowest address in the boot section. The reset functionality is asynchronous, and so no running system clock is required to reset the device. The software reset feature makes it possible to issue a controlled system reset from the user software. The reset status register has individual status flags for each reset source. It is cleared at power-on reset, and shows which sources have issued a reset since the last power-on. An overview of the reset system is shown in Figure 9-1 on page 103. XMEGA B [MANUAL] 103 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 9-1. Reset system overview. 9.3 Reset Sequence A reset request from any reset source will immediately reset the device and keep it in reset as long as the request is active. When all reset requests are released, the device will go through three stages before the device starts running again: z Reset counter delay z Oscillator startup z Oscillator calibration If another reset requests occurs during this process, the reset sequence will start over again. 9.3.1 Reset Counter The reset counter can delay reset release with a programmable period from when all reset requests are released. The reset delay is timed from the 1kHz output of the ultra low power (ULP) internal oscillator, and in addition 24 System clock (clkSYS) cycles are counted before reset is released. The reset delay is set by the STARTUPTIME fuse bits. The selectable delays are shown in Table 9-1. Table 9-1. Reset delay MCU Status Register (MCUSR) Brown-out BODLEVEL [2:0] Reset Delay Counters TIMEOUT PORF BORF EXTRF WDRF ULP Oscillator SPIKE FILTER Pull-up Resistor JTRF Watchdog Reset SUT[1:0] Power-on Reset Software Reset External Reset PDI Reset SUT[1:0] Number of 1kHz ULP Oscillator Clock Cycles Recommended Usage 00 64K ClkULP+ 24 ClkSYS Stable frequency at startup 01 4K ClkULP + 24 ClkSYS Slowly rising power 10 Reserved - 11 24 ClkSYS Fast rising power or BOD enabled XMEGA B [MANUAL] 104 Atmel-8291C-AVR-XMEGA B -09/2014 Whenever a reset occurs, the clock system is reset and the internal 2MHz internal oscillator is chosen as the source for ClkSYS. 9.3.2 Oscillator Startup After the reset delay, the 2MHz internal oscillator clock is started, and its calibration values are automatically loaded from the calibration row to the calibration registers. 9.4 Reset Sources 9.4.1 Power-on Reset A power-on reset (POR) is generated by an on-chip detection circuit. The POR is activated when the VCC rises and reaches the POR threshold voltage (VPOT), and this will start the reset sequence. The POR is also activated to power down the device properly when the VCC falls and drops below the VPOT level. The VPOT level is higher for falling VCCthan for rising VCC. Consult the datasheet for POR characteristics data. Figure 9-2. MCU startup, RESET tied to VCC. Figure 9-3. MCU startup, RESET extended externally, 9.4.2 Brownout Detection The on-chip brownout detection (BOD) circuit monitors the VCC level during operation by comparing it to a fixed, programmable level that is selected by the BODLEVEL fuses. If disabled, BOD is forced on at the lowest level during chip erase and when the PDI is enabled. When the BOD is enabled and VCC decreases to a value below the trigger level (VBOT- in Figure 9-4), the brownout reset is immediately activated. V RESET TIME-OUT INTERNAL RESET t TOUT VPOT VRST CC RESET TIME-OUT INTERNAL RESET t TOUT VPOT VRST VCC XMEGA B [MANUAL] 105 Atmel-8291C-AVR-XMEGA B -09/2014 When VCC increases above the trigger level (VBOT+ in Figure 9-4), the reset counter starts the MCU after the timeout period, tTOUT, has expired. The trigger level has a hysteresis to ensure spike free brownout detection. The hysteresis on the detection level should be interpreted as VBOT+= VBOT + VHYST/2 and VBOT- = VBOT - VHYST/2. The BOD circuit will detect a drop in VCC only if the voltage stays below the trigger level for longer than tBOD. Figure 9-4. Brownout detection reset. For BOD characterization data consult the device datasheet. The programmable BODLEVEL setting is shown in Table 9- 2. Table 9-2. Programmable BODLEVEL setting. Notes: 1. The values are nominal values only. For accurate, actual numbers, consult the device datasheet. 2. Changing these fuse bits will have no effect until leaving programming mode. The BOD circuit has three modes of operation: z Disabled: In this mode, there is no monitoring of the VCC level. z Enabled: In this mode, the VCC level is continuously monitored, and a drop in VCC below VBOT for a period of tBOD will give a brownout reset z Sampled: In this mode, the BOD circuit will sample the VCC level with a period identical to that of the 1kHz output from the ultra low power (ULP) internal oscillator. Between each sample, the BOD is turned off. This mode will BOD level Fuse BODLEVEL[2:0](2) VBOT(1) Unit BOD level 0 111 1.6 V BOD level 1 110 1.8 BOD level 2 101 2.0 BOD level 3 100 2.2 BOD level 4 011 2.4 BOD level 5 010 2.6 BOD level 6 001 2.8 BOD level 7 000 3.0 VCC TIME-OUT INTERNAL RESET VBOTVBOT+ t TOUT t BOD XMEGA B [MANUAL] 106 Atmel-8291C-AVR-XMEGA B -09/2014 reduce the power consumption compared to the enabled mode, but a fall in the VCC level between two positive edges of the 1kHz ULP oscillator output will not be detected. If a brownout is detected in this mode, the BOD circuit is set in enabled mode to ensure that the device is kept in reset until VCC is above VBOT again The BODACT fuse determines the BOD setting for active mode and idle mode, while the BODPD fuse determines the brownout detection setting for all sleep modes, except idle mode. Table 9-3. BOD setting fuse decoding. 9.4.3 External Reset The external reset circuit is connected to the external RESET pin. The external reset will trigger when the RESET pin is driven below the RESET pin threshold voltage, VRST, for longer than the minimum pulse period, tEXT. The reset will be held as long as the pin is kept low. The RESET pin includes an internal pull-up resistor. Figure 9-5. External reset characteristics. For external reset characterization data consult the device datasheet. 9.4.4 Watchdog Reset The watchdog timer (WDT) is a system function for monitoring correct program operation. If the WDT is not reset from the software within a programmable timout period, a watchdog reset will be given. The watchdog reset is active for one to two clock cycles of the 2MHz internal oscillator. BODACT[1:0]/ BODPD[1:0] Mode 00 Reserved 01 Sampled 10 Enabled 11 Disabled CC t EXT XMEGA B [MANUAL] 107 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 9-6. Watchdog reset. For information on configuration and use of the WDT, refer to the “WDT – Watchdog Timer” on page 110. 9.4.5 Software Reset The software reset makes it possible to issue a system reset from software by writing to the software reset bit in the reset control register.The reset will be issued within two CPU clock cycles after writing the bit. It is not possible to execute any instruction from when a software reset is requested until it is issued. Figure 9-7. Software reset. 9.4.6 Program and Debug Interface Reset The program and debug interface reset contains a separate reset source that is used to reset the device during external programming and debugging. This reset source is accessible only from external debuggers and programmers. 1-2 2MHz CC Cycles 1-2 2MHz CC Cycles SOFTWARE XMEGA B [MANUAL] 108 Atmel-8291C-AVR-XMEGA B -09/2014 9.5 Register Description 9.5.1 STATUS – Status register z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5 – SRF: Software Reset Flag This flag is set if a software reset occurs. The flag will be cleared by a power-on reset or by writing a one to the bit location. z Bit 4 – PDIRF: Program and Debug Interface Reset Flag This flag is set if a programming interface reset occurs. The flag will be cleared by a power-on reset or by writing a one to the bit location. z Bit 3 – WDRF: Watchdog Reset Flag This flag is set if a watchdog reset occurs. The flag will be cleared by a power-on reset or by writing a one to the bit location. z Bit 2 – BORF: Brownout Reset Flag This flag is set if a brownout reset occurs. The flag will be cleared by a power-on reset or by writing a one to the bit location. z Bit 1 – EXTRF: External Reset Flag This flag is set if an external reset occurs. The flag will be cleared by a power-on reset or by writing a one to the bit location. z Bit 0 – PORF: Power On Reset Flag This flag is set if a power-on reset occurs. Writing a one to the flag will clear the bit location. 9.5.2 CTRL – Control register z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – SWRST: Software Reset Bit 7 6 5 4 3 2 1 0 +0x00 – – SRF PDIRF WDRF BORF EXTRF PORF Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value - ------- Bit 7 6 5 4 3 2 1 0 +0x01 – – – – – – – SWRST Read/Write R R R R R R R R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 109 Atmel-8291C-AVR-XMEGA B -09/2014 When this bit is set, a software reset will occur. The bit is cleared when a reset is issued. This bit is protected by the configuration change protection mechanism. For details, refer to “Configuration Change Protection” on page 13. 9.6 Register Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 STATUS – – SRF PDIRF WDRF BORF EXTRF PORF 108 +0x01 CTRL – – – – – – – SWRST 108 XMEGA B [MANUAL] 110 Atmel-8291C-AVR-XMEGA B -09/2014 10. WDT – Watchdog Timer 10.1 Features z Issues a device reset if the timer is not reset before its timeout period z Asynchronous operation from dedicated oscillator z 1kHz output of the 32kHz ultra low power oscillator z 11 selectable timeout periods, from 8ms to 8s. z Two operation modes: z Normal mode z Window mode z Configuration lock to prevent unwanted changes 10.2 Overview The watchdog timer (WDT) is a system function for monitoring correct program operation. It makes it possible to recover from error situations such as runaway or deadlocked code. The WDT is a timer, configured to a predefined timeout period, and is constantly running when enabled. If the WDT is not reset within the timeout period, it will issue a microcontroller reset. The WDT is reset by executing the WDR (watchdog timer reset) instruction from the application code. The window mode makes it possible to define a time slot or window inside the total timeout period during which WDT must be reset. If the WDT is reset outside this window, either too early or too late, a system reset will be issued. Compared to the normal mode, this can also catch situations where a code error causes constant WDR execution. The WDT will run in active mode and all sleep modes, if enabled. It is asynchronous, runs from a CPU-independent clock source, and will continue to operate to issue a system reset even if the main clocks fail. The configuration change protection mechanism ensures that the WDT settings cannot be changed by accident. For increased safety, a fuse for locking the WDT settings is also available. 10.3 Normal Mode Operation In normal mode operation, a single timeout period is set for the WDT. If the WDT is not reset from the application code before the timeout occurs, then the WDT will issue a system reset. There are 11 possible WDT timeout (TOWDT) periods, selectable from 8ms to 8s, and the WDT can be reset at any time during the timeout period. A new WDT timeout period will be started each time the WDT is reset by the WDR instruction. The default timeout period is controlled by fuses. Normal mode operation is illustrated in Figure 10-1 on page 110. Figure 10-1. Normal mode operation. XMEGA B [MANUAL] 111 Atmel-8291C-AVR-XMEGA B -09/2014 10.4 Window Mode Operation In window mode operation, the WDT uses two different timeout periods, a "closed" window timeout period (TOWDTW) and the normal timeout period (TOWDT). The closed window timeout period defines a duration of from 8ms to 8s where the WDT cannot be reset. If the WDT is reset during this period, the WDT will issue a system reset. The normal WDT timeout period, which is also 8ms to 8s, defines the duration of the "open" period during which the WDT can (and should) be reset. The open period will always follow the closed period, and so the total duration of the timeout period is the sum of the closed window and the open window timeout periods. The default closed window timeout period is controlled by fuses (both open and closed periods are controlled by fuses). The window mode operation is illustrated in Figure 10-2. Figure 10-2. Window mode operation. 10.5 Watchdog Timer Clock The WDT is clocked from the 1kHz output from the 32kHz ultra low power (ULP) internal oscillator. Due to the ultra low power design, the oscillator is not very accurate, and so the exact timeout period may vary from device to device. When designing software which uses the WDT, this device-to-device variation must be kept in mind to ensure that the timeout periods used are valid for all devices. For more information on ULP oscillator accuracy, consult the device datasheet. 10.6 Configuration Protection and Lock The WDT is designed with two security mechanisms to avoid unintentional changes to the WDT settings. The first mechanism is the configuration change protection mechanism, employing a timed write procedure for changing the WDT control registers. In addition, for the new configuration to be written to the control registers, the register’s change enable bit must be written at the same time. The second mechanism locks the configuration by setting the WDT lock fuse. When this fuse is set, the watchdog time control register cannot be changed; hence, the WDT cannot be disabled from software. After system reset, the WDT will resume at the configured operation. When the WDT lock fuse is programmed, the window mode timeout period cannot be changed, but the window mode itself can still be enabled or disabled. XMEGA B [MANUAL] 112 Atmel-8291C-AVR-XMEGA B -09/2014 10.7 Registers Description 10.7.1 CTRL – Control register z Bits 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bits 5:2 – PER[3:0]: Timeout Period These bits determine the watchdog timeout period as a number of 1kHz ULP oscillator cycles. In window mode operation, these bits define the open window period. The different typical timeout periods are found in Table 10-1. The initial values of these bits are set by the watchdog timeout period (WDP) fuses, which are loaded at power-on. In order to change these bits, the CEN bit must be written to 1 at the same time. These bits are protected by the configuration change protection mechanism. For a detailed description, refer to “Configuration Change Protection” on page 13. Table 10-1. Watchdog timeout periods Note: Reserved settings will not give any timeout. Bit 7 6 5 4 3 2 1 0 +0x00 – – PER[3:0] ENABLE CEN Read/Write (unlocked) R R R/W R/W R/W R/W R/W R/W Read/Write (locked) R RRRRRRR Initial Value (x = fuse) 0 0 XXXXX0 PER[3:0] Group Configuration Typical Timeout Periods 0000 8CLK 8ms 0001 16CLK 16ms 0010 32CLK 32ms 0011 64CLK 64ms 0100 128CLK 0.128s 0101 256CLK 0.256s 0110 512CLK 0.512s 0111 1KCLK 1.0s 1000 2KCLK 2.0s 1001 4KCLK 4.0s 1010 8KCLK 8.0s 1011 – Reserved 1100 – Reserved 1101 – Reserved 1110 – Reserved 1111 – Reserved XMEGA B [MANUAL] 113 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 1 – ENABLE: Enable This bit enables the WDT. Clearing this bit disables the watchdog timer. In order to change this bit, the CEN bit in “CTRL – Control register” on page 112 must be written to one at the same time. This bit is protected by the configuration change protection mechanism, For a detailed description, refer to “Configuration Change Protection” on page 13. z Bit 0 – CEN: Change Enable This bit enables the ability to change the configuration of the “CTRL – Control register” on page 112. When writing a new value to this register, this bit must be written to one at the same time for the changes to take effect. This bit is protected by the configuration change protection mechanism. For a detailed description, refer to “Configuration Change Protection” on page 13. 10.7.2 WINCTRL – Window Mode Control register z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5:2 – WPER[3:0]: Window Mode Timeout Period These bits determine the closed window period as a number of 1kHz ULP oscillator cycles in window mode operation. The typical different closed window periods are found in Table 10-2. The initial values of these bits are set by the watchdog window timeout period (WDWP) fuses, and are loaded at power-on. In normal mode these bits are not in use. In order to change these bits, the WCEN bit must be written to one at the same time. These bits are protected by the configuration change protection mechanism. For a detailed description, refer to “Configuration Change Protection” on page 13. Table 10-2. Watchdog closed window periods Bit 7 6 5 4 3 2 1 0 +0x01 – – WPER[3:0] WEN WCEN Read/Write (unlocked) R R R/W R/W R/W R/W R/W R/W Read/Write (locked) R R R R R R R/W R/W Initial Value (x = fuse) 0 0 XXXXX0 WPER[3:0] Group Configuration Typical Closed Window Periods 0000 8CLK 8ms 0001 16CLK 16ms 0010 32CLK 32ms 0011 64CLK 64ms 0100 128CLK 0.128s 0101 256CLK 0.256s 0110 512CLK 0.512s 0111 1KCLK 1.0s 1000 2KCLK 2.0s 1001 4KCLK 4.0s XMEGA B [MANUAL] 114 Atmel-8291C-AVR-XMEGA B -09/2014 Note: Reserved settings will not give any timeout for the window. z Bit 1 – WEN: Window Mode Enable This bit enables the window mode. In order to change this bit, the WCEN bit in “WINCTRL – Window Mode Control register” on page 113 must be written to one at the same time. This bit is protected by the configuration change protection mechanism. For a detailed description, refer to “Configuration Change Protection” on page 13. z Bit 0 – WCEN: Window Mode Change Enable This bit enables the ability to change the configuration of the “WINCTRL – Window Mode Control register” on page 113. When writing a new value to this register, this bit must be written to one at the same time for the changes to take effect. This bit is protected by the configuration change protection mechanism, but not protected by the WDT lock fuse. 10.7.3 STATUS – Status register z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – SYNCBUSY: Synchronization Busy Flag This flag is set after writing to the CTRL or WINCTRL registers and the data are being synchronized from the system clock to the WDT clock domain. This bit is automatically cleared after the synchronization is finished. Synchronization will take place only when the ENABLE bit for the Watchdog Timer is set. 10.8 Register Summary 1010 8KCLK 8.0s 1011 – Reserved 1100 – Reserved 1101 – Reserved 1110 – Reserved 1111 – Reserved WPER[3:0] Group Configuration Typical Closed Window Periods Bit 7 6 5 4 3 2 1 0 +0x02 – – – – – – – SYNCBUSY Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL – – PER[3:0] ENABLE CEN 112 +0x01 WINCTRL – – WPER[3:0] WEN WCEN 113 +0x02 STATUS – – – – – – – SYNCBUSY 114 XMEGA B [MANUAL] 115 Atmel-8291C-AVR-XMEGA B -09/2014 11. Interrupts and Programmable Multilevel Interrupt Controller 11.1 Features z Short and predictable interrupt response time z Separate interrupt configuration and vector address for each interrupt z Programmable multilevel interrupt controller z Interrupt prioritizing according to level and vector address z Three selectable interrupt levels for all interrupts: low, medium and high z Selectable, round-robin priority scheme within low-level interrupts z Non-maskable interrupts for critical functions z Interrupt vectors optionally placed in the application section or the boot loader section 11.2 Overview Interrupts signal a change of state in peripherals, and this can be used to alter program execution. Peripherals can have one or more interrupts, and all are individually enabled and configured. When an interrupt is enabled and configured, it will generate an interrupt request when the interrupt condition is present. The programmable multilevel interrupt controller (PMIC) controls the handling and prioritizing of interrupt requests. When an interrupt request is acknowledged by the PMIC, the program counter is set to point to the interrupt vector, and the interrupt handler can be executed. All peripherals can select between three different priority levels for their interrupts: low, medium, and high. Interrupts are prioritized according to their level and their interrupt vector address. Medium-level interrupts will interrupt low-level interrupt handlers. High-level interrupts will interrupt both medium- and low-level interrupt handlers. Within each level, the interrupt priority is decided from the interrupt vector address, where the lowest interrupt vector address has the highest interrupt priority. Low-level interrupts have an optional round-robin scheduling scheme to ensure that all interrupts are serviced within a certain amount of time. Non-maskable interrupts (NMI) are also supported, and can be used for system critical functions. 11.3 Operation Interrupts must be globally enabled for any interrupts to be generated. This is done by setting the global interrupt enable ( I ) bit in the CPU status register. The I bit will not be cleared when an interrupt is acknowledged. Each interrupt level must also be enabled before interrupts with the corresponding level can be generated. When an interrupt is enabled and the interrupt condition is present, the PMIC will receive the interrupt request. Based on the interrupt level and interrupt priority of any ongoing interrupts, the interrupt is either acknowledged or kept pending until it has priority. When the interrupt request is acknowledged, the program counter is updated to point to the interrupt vector. The interrupt vector is normally a jump to the interrupt handler; the software routine that handles the interrupt. After returning from the interrupt handler, program execution continues from where it was before the interrupt occurred. One instruction is always executed before any pending interrupt is served. The PMIC status register contains state information that ensures that the PMIC returns to the correct interrupt level when the RETI (interrupt return) instruction is executed at the end of an interrupt handler. Returning from an interrupt will return the PMIC to the state it had before entering the interrupt. The status register (SREG) is not saved automatically upon an interrupt request. The RET (subroutine return) instruction cannot be used when returning from the interrupt handler routine, as this will not return the PMIC to its correct state. XMEGA B [MANUAL] 116 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 11-1. Interrupt controller overview. 11.4 Interrupts All interrupts and the reset vector each have a separate program vector address in the program memory space. The lowest address in the program memory space is the reset vector. All interrupts are assigned individual control bits for enabling and setting the interrupt level, and this is set in the control registers for each peripheral that can generate interrupts. Details on each interrupt are described in the peripheral where the interrupt is available. All interrupts have an interrupt flag associated with it. When the interrupt condition is present, the interrupt flag will be set, even if the corresponding interrupt is not enabled. For most interrupts, the interrupt flag is automatically cleared when executing the interrupt vector. Writing a logical one to the interrupt flag will also clear the flag. Some interrupt flags are not cleared when executing the interrupt vector, and some are cleared automatically when an associated register is accessed (read or written). This is described for each individual interrupt flag. If an interrupt condition occurs while another, higher priority interrupt is executing or pending, the interrupt flag will be set and remembered until the interrupt has priority. If an interrupt condition occurs while the corresponding interrupt is not enabled, the interrupt flag will be set and remembered until the interrupt is enabled or the flag is cleared by software. Similarly, if one or more interrupt conditions occur while global interrupts are disabled, the corresponding interrupt flag will be set and remembered until global interrupts are enabled. All pending interrupts are then executed according to their order of priority. Interrupts can be blocked when executing code from a locked section; e.g., when the boot lock bits are programmed. This feature improves software security. Refer to “Memory Programming” on page 375 for details on lock bit settings. Interrupts are automatically disabled for up to four CPU clock cycles when the configuration change protection register is written with the correct signature. Refer to “Configuration Change Protection” on page 13 for more details. 11.4.1 NMI – Non-Maskable Interrupts Which interrupts represent NMI and which represent regular interrupts cannot be selected. Non-maskable interrupts must be enabled before they can be used. Refer to the device datasheet for NMI present on each device. An NMI will be executed regardless of the setting of the I bit, and it will never change the I bit. No other interrupts can interrupt a NMI handler. If more than one NMI is requested at the same time, priority is static according to the interrupt vector address, where the lowest address has highest priority. 11.4.2 Interrupt Response Time The interrupt response time for all the enabled interrupts is three CPU clock cycles, minimum; one cycle to finish the ongoing instruction and two cycles to store the program counter to the stack. After the program counter is pushed on the stack, the program vector for the interrupt is executed. The jump to the interrupt handler takes three clock cycles. Peripheral 1 Interrupt Controller INT REQ INT LEVEL INT REQ INT LEVEL CPU INT REQ CTRL LEVEL Enable CPU.SREG Global Interrupt Enable Priority decoder STATUS INTPRI INT ACK INT ACK Peripheral n INT LEVEL INT REQ INT ACK CPU CPU INT ACK CPU ”RETI” Sleep Controller Wake-up XMEGA B [MANUAL] 117 Atmel-8291C-AVR-XMEGA B -09/2014 If an interrupt occurs during execution of a multicycle instruction, this instruction is completed before the interrupt is served. See Figure 11-2 on page 117 for more details. Figure 11-2. Interrupt execution of a multicycle instruction. If an interrupt occurs when the device is in sleep mode, the interrupt execution response time is increased by five clock cycles. In addition, the response time is increased by the start-up time from the selected sleep mode. A return from an interrupt handling routine takes four to five clock cycles, depending on the size of the program counter. During these clock cycles, the program counter is popped from the stack and the stack pointer is incremented. XMEGA B [MANUAL] 118 Atmel-8291C-AVR-XMEGA B -09/2014 11.5 Interrupt level The interrupt level is independently selected for each interrupt source. For any interrupt request, the PMIC also receives the interrupt level for the interrupt. The interrupt levels and their corresponding bit values for the interrupt level configuration of all interrupts is shown in Table 11-1. Table 11-1. Interrupt levels The interrupt level of an interrupt request is compared against the current level and status of the interrupt controller. An interrupt request of a higher level will interrupt any ongoing interrupt handler from a lower level interrupt. When returning from the higher level interrupt handler, the execution of the lower level interrupt handler will continue. 11.6 Interrupt priority Within each interrupt level, all interrupts have a priority. When several interrupt requests are pending, the order in which interrupts are acknowledged is decided both by the level and the priority of the interrupt request. Interrupts can be organized in a static or dynamic (round-robin) priority scheme. High- and medium-level interrupts and the NMI will always have static priority. For low-level interrupts, static or dynamic priority scheduling can be selected. 11.6.1 Static priority Interrupt vectors (IVEC) are located at fixed addresses. For static priority, the interrupt vector address decides the priority within one interrupt level, where the lowest interrupt vector address has the highest priority. Refer to the device datasheet for the interrupt vector table with the base address for all modules and peripherals with interrupt capability. Refer to the interrupt vector summary of each module and peripheral in this manual for a list of interrupts and their corresponding offset address within the different modules and peripherals. Interrupt Level Configuration Group Configuration Description 00 OFF Interrupt disabled. 01 LO Low-level interrupt 10 MED Medium-level interrupt 11 HI High-level interrupt XMEGA B [MANUAL] 119 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 11-3. Static priority. 11.6.2 Round-robin Scheduling To avoid the possible starvation problem for low-level interrupts with static priority, where some interrupts might never be served, the PMIC offers round-robin scheduling for low-level interrupts. When round-robin scheduling is enabled, the interrupt vector address for the last acknowledged low-level interrupt will have the lowest priority the next time one or more interrupts from the low level is requested. Figure 11-4. Round-robin scheduling. XMEGA B [MANUAL] 120 Atmel-8291C-AVR-XMEGA B -09/2014 11.7 Interrupt vector locations Table 11-2 shows reset and Interrupt vectors placement for the various combinations of BOOTRST and IVSEL settings. If the program never enables an interrupt source, the Interrupt Vectors are not used, and regular program code can be placed at these locations. This is also the case if the Reset Vector is in the Application section while the Interrupt Vectors are in the Boot section or vice versa. Table 11-2. Reset and interrupt vectors placement BOOTRST IVSEL Reset Address Interrupt Vectors Start Address 1 0 0x0000 0x0002 1 1 0x0000 Boot Reset Address + 0x0002 0 0 Boot Reset Address 0x0002 0 1 Boot Reset Address Boot Reset Address + 0x0002 XMEGA B [MANUAL] 121 Atmel-8291C-AVR-XMEGA B -09/2014 11.8 Register Description 11.8.1 STATUS – Status register z Bit 7 – NMIEX: Non-Maskable Interrupt Executing This flag is set if a non-maskable interrupt is executing. The flag will be cleared when returning (RETI) from the interrupt handler. z Bit 6:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2 – HILVLEX: High-level Interrupt Executing This flag is set when a high-level interrupt is executing or when the interrupt handler has been interrupted by an NMI. The flag will be cleared when returning (RETI) from the interrupt handler. z Bit 1 – MEDLVLEX: Medium-level Interrupt Executing This flag is set when a medium-level interrupt is executing or when the interrupt handler has been interrupted by an interrupt from higher level or an NMI. The flag will be cleared when returning (RETI) from the interrupt handler. z Bit 0 – LOLVLEX: Low-level Interrupt Executing This flag is set when a low-level interrupt is executing or when the interrupt handler has been interrupted by an interrupt from higher level or an NMI. The flag will be cleared when returning (RETI) from the interrupt handler. 11.8.2 INTPRI – Interrupt priority register z Bit 7:0 – INTPRI: Interrupt Priority When round-robin scheduling is enabled, this register stores the interrupt vector of the last acknowledged low-level interrupt. The stored interrupt vector will have the lowest priority the next time one or more low-level interrupts are pending. The register is accessible from software to change the priority queue. This register is not reinitialized to its initial value if round-robing scheduling is disabled, and so if default static priority is needed, the register must be written to zero. Bit 7 6 5 4 3 2 1 0 +0x00 NMIEX – – – – HILVLEX MEDLVLEX LOLVLEX Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x01 INTPRI[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 122 Atmel-8291C-AVR-XMEGA B -09/2014 11.8.3 CTRL – Control register z Bit 7 – RREN: Round-robin Scheduling Enable When the RREN bit is set, the round-robin scheduling scheme is enabled for low-level interrupts. When this bit is cleared, the priority is static according to interrupt vector address, where the lowest address has the highest priority. z Bit 6 – IVSEL: Interrupt Vector Select When the IVSEL bit is cleared (zero), the interrupt vectors are placed at the start of the application section in flash. When this bit is set (one), the interrupt vectors are placed in the beginning of the boot section of the flash. Refer to the device datasheet for the absolute address. This bit is protected by the configuration change protection mechanism. Refer to “Configuration Change Protection” on page 13 for details. z Bit 5:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2 – HILVLEN: High-level Interrupt Enable (1) When this bit is set, all high-level interrupts are enabled. If this bit is cleared, high-level interrupt requests will be ignored. z Bit 1 – MEDLVLEN: Medium-level Interrupt Enable(1) When this bit is set, all medium-level interrupts are enabled. If this bit is cleared, medium-level interrupt requests will be ignored. z Bit 0 – LOLVLEN: Low-level Interrupt Enable(1) When this bit is set, all low-level interrupts are enabled. If this bit is cleared, low-level interrupt requests will be ignored. Note: 1. Ignoring interrupts will be effective one cycle after the bit is cleared. 11.9 Register Summary Bit 7 6 5 4 3 2 1 0 +0x02 RREN IVSEL – – – HILVLEN MEDLVLEN LOLVLEN Read/Write R/W R/W R R R R/W R/W R/W Initial Value 0 00000 0 0 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 STATUS NMIEX – – – – HILVLEX MEDLVLEX LOLVLEX 121 +0x01 INTPRI INTPRI[7:0] 121 +0x02 CTRL RREN IVSEL – – – HILVLEN MEDLVLEN LOLVLEN 122 XMEGA B [MANUAL] 123 Atmel-8291C-AVR-XMEGA B -09/2014 12. I/O Ports 12.1 Features z General purpose input and output pins with individual configuration z Output driver with configurable driver and pull settings: z Totem-pole z Wired-AND z Wired-OR z Bus-keeper z Inverted I/O z Input with synchronous and/or asynchronous sensing with interrupts and events z Sense both edges z Sense rising edges z Sense falling edges z Sense low level z Optional pull-up and pull-down resistor on input and Wired-OR/AND configurations z Asynchronous pin change sensing that can wake the device from all sleep modes z Two port interrupts with pin masking per I/O port z Efficient and safe access to port pins z Hardware read-modify-write through dedicated toggle/clear/set registers z Configuration of multiple pins in a single operation z Mapping of port registers into bit-accessible I/O memory space z Peripheral clocks output on port pin z Real-time counter clock output to port pin z Event channels can be output on port pin z Remapping of digital peripheral pin functions z Selectable USART, SPI, and timer/counter input/output pin locations 12.2 Overview AVR XMEGA microcontrollers have flexible general purpose I/O ports. One port consists of up to eight port pins: pin 0 to 7. Each port pin can be configured as input or output with configurable driver and pull settings. They also implement synchronous and asynchronous input sensing with interrupts and events for selectable pin change conditions. Asynchronous pin-change sensing means that a pin change can wake the device from all sleep modes, included the modes where no clocks are running. All functions are individual and configurable per pin, but several pins can be configured in a single operation. The pins have hardware read-modify-write (RMW) functionality for safe and correct change of drive value and/or pull resistor configuration. The direction of one port pin can be changed without unintentionally changing the direction of any other pin. The port pin configuration also controls input and output selection of other device functions. It is possible to have both the peripheral clock and the real-time clock output to a port pin, and available for external use. The same applies to events from the event system that can be used to synchronize and control external functions. Other digital peripherals, such as USART, SPI, and timer/counters, can be remapped to selectable pin locations in order to optimize pin-out versus application needs. Figure 12-1 on page 124 shows the I/O pin functionality and the registers that are available for controlling a pin. XMEGA B [MANUAL] 124 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 12-1. General I/O pin functionality. 12.3 I/O Pin Use and Configuration Each port has one data direction (DIR) register and one data output value (OUT) register that are used for port pin control. The data input value (IN) register is used for reading the port pins. In addition, each pin has a pin configuration (PINnCTRL) register for additional pin configuration. Direction of the pin is decided by the DIRn bit in the DIR register. If DIRn is written to one, pin n is configured as an output pin. If DIRn is written to zero, pin n is configured as an input pin. When direction is set as output, the OUTn bit in OUT is used to set the value of the pin. If OUTn is written to one, pin n is driven high. If OUTn is written to zero, pin n is driven low. The IN register is used for reading pin values. A pin value can always be read regardless of whether the pin is configured as input or output, except if digital input is disabled. The I/O pins are tri-stated when a reset condition becomes active, even if no clocks are running. The pin n configuration (PINnCTRL) register is used for additional I/O pin configuration. A pin can be set in a totem-pole, wired-AND, or wired-OR configuration. It is also possible to enable inverted input and output for a pin. A totem-pole output has four possible pull configurations: totem-pole (push-pull), pull-down, pull-up, and bus-keeper. The bus-keeper is active in both directions. This is to avoid oscillation when disabling the output. The totem-pole Q D R Q D R Synchronizer D Q R D Q R DIRn OUTn PINnCTRL INn Pxn D Q R C o n t r o l L o g i c Input Disable Wired AND/OR Digital Input Pin Analog Input/Output Inverted I/O Pull Enable Pull Keep Pull Direction XMEGA B [MANUAL] 125 Atmel-8291C-AVR-XMEGA B -09/2014 configurations with pull-up and pull-down have active resistors only when the pin is set as input. This feature eliminates unnecessary power consumption. For wired-AND and wired-OR configuration, the optional pull-up and pull-down resistors are active in both input and output directions. Since pull configuration is configured through the pin configuration register, all intermediate port states during switching of the pin direction and pin values are avoided. The I/O pin configurations are summarized with simplified schematics in Figure 12-2 on page 125 to Figure 12-7 on page 127. 12.3.1 Totem-pole In the totem-pole (push-pull) configuration, the pin is driven low or high according to the corresponding bit setting in the OUT register. In this configuration, there is no current limitation for sink or source other than what the pin is capable of. If the pin is configured for input, the pin will float if no external pull resistor is connected. Figure 12-2. I/O pin configuration - Totem-pole (push-pull). 12.3.1.1 Totem-pole with Pull-down In this mode, the configuration is the same as for totem-pole mode, expect the pin is configured with an internal pull-down resistor when set as input. Figure 12-3. I/O pin configuration - Totem-pole with pull-down (on input). XMEGA B [MANUAL] 126 Atmel-8291C-AVR-XMEGA B -09/2014 12.3.1.2 Totem-pole with Pull-up In this mode, the configuration is as for totem-pole, expect the pin is configured with internal pull-up when set as input. Figure 12-4. I/O pin configuration - Totem-pole with pull-up (on input). 12.3.2 Bus-keeper In the bus-keeper configuration, it provides a weak bus-keeper that will keep the pin at its logic level when the pin is no longer driven to high or low. If the last level on the pin/bus was 1, the bus-keeper configuration will use the internal pull resistor to keep the bus high. If the last logic level on the pin/bus was 0, the bus-keeper will use the internal pull resistor to keep the bus low. Figure 12-5. I/O pin configuration - Totem-pole with bus-keeper. XMEGA B [MANUAL] 127 Atmel-8291C-AVR-XMEGA B -09/2014 12.3.3 Wired-OR In the wired-OR configuration, the pin will be driven high when the corresponding bits in the OUT and DIR registers are written to one. When the OUT register is set to zero, the pin is released, allowing the pin to be pulled low with the internal or an external pull-resistor. If internal pull-down is used, this is also active if the pin is set as input. Figure 12-6. Output configuration - Wired-OR with optional pull-down. 12.3.4 Wired-AND In the wired-AND configuration, the pin will be driven low when the corresponding bits in the OUT and DIR registers are written to zero. When the OUT register is set to one, the pin is released allowing the pin to be pulled high with the internal or an external pull-resistor. If internal pull-up is used, this is also active if the pin is set as input. Figure 12-7. Output configuration - Wired-AND with optional pull-up. XMEGA B [MANUAL] 128 Atmel-8291C-AVR-XMEGA B -09/2014 12.4 Reading the Pin Value Independent of the pin data direction, the pin value can be read from the IN register, as shown in Figure 12-1 on page 124. If the digital input is disabled, the pin value cannot be read. The IN register bit and the preceding flip-flop constitute a synchronizer. The synchronizer introduces a delay on the internal signal line. Figure 12-8 on page 128 shows a timing diagram of the synchronization when reading an externally applied pin value. The maximum and minimum propagation delays are denoted as tpd,max and tpd,min, respectively. Figure 12-8. Synchronization when reading a pin value. XMEGA B [MANUAL] 129 Atmel-8291C-AVR-XMEGA B -09/2014 12.5 Input Sense Configuration Input sensing is used to detect an edge or level on the I/O pin input. The different sense configurations that are available for each pin are detection of a rising edge, falling edge, or any edge or detection of a low level. High level can be detected by using the inverted input configuration. Input sensing can be used to trigger interrupt requests (IREQ) or events when there is a change on the pin. The I/O pins support synchronous and asynchronous input sensing. Synchronous sensing requires the presence of the peripheral clock, while asynchronous sensing does not require any clock. Figure 12-9. Input sensing. 12.6 Port Interrupt Each port has two interrupt vectors, and it is configurable which pins on the port will trigger each interrupt. Port interrupts must be enabled before they can be used. Which sense configurations can be used to generate interrupts is dependent on whether synchronous or asynchronous input sensing is available for the selected pin. For synchronous sensing, all sense configurations can be used to generate interrupts. For edge detection, the changed pin value must be sampled once by the peripheral clock for an interrupt request to be generated. For asynchronous sensing, only port pin 2 on each port has full asynchronous sense support. This means that for edge detection, pin 2 will detect and latch any edge and it will always trigger an interrupt request. The other port pins have limited asynchronous sense support. This means that for edge detection, the changed value must be held until the device wakes up and a clock is present. If the pin value returns to its initial value before the end of the device wake-up time, the device will still wake up, but no interrupt request will be generated. A low level can always be detected by all pins, regardless of a peripheral clock being present or not. If a pin is configured for low-level sensing, the interrupt will trigger as long as the pin is held low. In active mode, the low level must be held until the completion of the currently executing instruction for an interrupt to be generated. In all sleep modes, the low level must be kept until the end of the device wake-up time for an interrupt to be generated. If the low level disappears before the end of the wake-up time, the device will still wake up, but no interrupt will be generated. Table 12-1, Table 12-2, and Table 12-3 on page 130 summarize when interrupts can be triggered for the various input sense configurations. D Q R INVERTED I/O Interrupt Control D Q R Pxn Synchronizer INn EDGE DETECT Synchronous sensing EDGE DETECT Asynchronous sensing IRQ Synchronous Events Asynchronous Events XMEGA B [MANUAL] 130 Atmel-8291C-AVR-XMEGA B -09/2014 Table 12-1. Synchronous sense support. Table 12-2. Full asynchronous sense support. Table 12-3. Limited asynchronous sense support. 12.7 Port Event Port pins can generate an event when there is a change on the pin. The sense configurations decide the conditions for each pin to generate events. Event generation requires the presence of a peripheral clock, and asynchronous event generation is not possible. For edge sensing, the changed pin value must be sampled once by the peripheral clock for an event to be generated. For level sensing, a low-level pin value will not generate events, and a high-level pin value will continuously generate events. For events to be generated on a low level, the pin configuration must be set to inverted I/O. Table 12-4. Event sense support Sense Settings Supported Interrupt Description Rising edge Yes Always triggered Falling edge Yes Always triggered Any edge Yes Always triggered Low level Yes Pin level must be kept unchanged during wake up Sense Settings Supported Interrupt Description Rising edge Yes Always triggered Falling edge Yes Always triggered Both edges Yes Always triggered Low level Yes Pin level must be kept unchanged during wake up Sense Settings Supported Interrupt Description Rising edge No - Falling edge No - Any edge Yes Pin value must be kept unchanged during wake up Low level Yes Pin level must be kept unchanged during wake up Sense Settings Signal event Data event Rising edge Rising edge Pin value Falling edge Falling edge Pin value Both edge Any edge Pin value Low level Pin value Pin value XMEGA B [MANUAL] 131 Atmel-8291C-AVR-XMEGA B -09/2014 12.8 Alternate Port Functions Most port pins have alternate pin functions in addition to being a general purpose I/O pin. When an alternate function is enabled, it might override the normal port pin function or pin value. This happens when other peripherals that require pins are enabled or configured to use pins. If and how a peripheral will override and use pins is described in the section for that peripheral. The port override signals and related logic (grey) are shown in Figure 12-10 on page 131. These signals are not accessible from software, but are internal signals between the overriding peripheral and the port pin. Figure 12-10. Port override signals and related logic. Q D R Q D R Synchronizer D Q R D Q R DIRn OUTn PINnCTRL INn Pxn D Q R C o n t r o l L o g i c Digital Input Disable (DID) Wired AND/OR Digital Input Pin Analog Input/Output Inverted I/O Pull Enable Pull Keep Pull Direction DID Override Enable DID Override Value OUT Override Enable OUT Override Value DIR Override Enable DIR Override Value XMEGA B [MANUAL] 132 Atmel-8291C-AVR-XMEGA B -09/2014 12.9 Clock and Event Output It is possible to output the peripheral clock and event channel 0 events to a pin. This can be used to clock, control, and synchronize external functions and hardware to internal device timing. The output port pin is selectable. If an event occurs, it remains visible on the port pin as long as the event lasts; normally one peripheral clock cycle. 12.10 Multi-pin configuration The multi-pin configuration function is used to configure multiple port pins using a single write operation to only one of the port pin configuration registers. A mask register decides which port pin is configured when one port pin register is written, while avoiding several pins being written the same way during identical write operations. 12.11 Virtual Ports Virtual port registers allow the port registers to be mapped virtually in the bit-accessible I/O memory space. When this is done, writing to the virtual port register will be the same as writing to the real port register. This enables the use of I/O memory-specific instructions, such as bit-manipulation instructions, on a port register that normally resides in the extended I/O memory space. There are four virtual ports, and so four ports can be mapped at the same time. XMEGA B [MANUAL] 133 Atmel-8291C-AVR-XMEGA B -09/2014 12.12 Register Descriptions – Ports 12.12.1 DIR – Data Direction register z Bit 7:0 – DIR[7:0]: Data Direction This register sets the data direction for the individual pins of the port. If DIRn is written to one, pin n is configured as an output pin. If DIRn is written to zero, pin n is configured as an input pin. 12.12.2 DIRSET – Data Direction Set Register z Bit 7:0 – DIRSET[7:0]: Port Data Direction Set This register can be used instead of a read-modify-write to set individual pins as output. Writing a one to a bit will set the corresponding bit in the DIR register. Reading this register will return the value of the DIR register. 12.12.3 DIRCLR – Data Direction Clear register z Bit 7:0 – DIRCLR[7:0]: Port Data Direction Clear This register can be used instead of a read-modify-write to set individual pins as input. Writing a one to a bit will clear the corresponding bit in the DIR register. Reading this register will return the value of the DIR register. Bit 7 6 5 4 3 2 1 0 +0x00 DIR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x01 DIRSET[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0000000 Bit 7 6 5 4 3 2 1 0 +0x02 DIRCLR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 134 Atmel-8291C-AVR-XMEGA B -09/2014 12.12.4 DIRTGL – Data Direction Toggle register z Bit 7:0 – DIRTGL[7:0]: Port Data Direction Toggle This register can be used instead of a read-modify-write to toggle the direction of individual pins. Writing a one to a bit will toggle the corresponding bit in the DIR register. Reading this register will return the value of the DIR register. 12.12.5 OUT – Data Output Value register z Bit 7:0 – OUT[7:0]: Port Data Output value This register sets the data output value for the individual pins of the port. If OUTn is written to one, pin n is driven high. If OUTn is written to zero, pin n is driven low. For this setting to have any effect, the pin direction must be set as output. 12.12.6 OUTSET – Data Output Value Set register z Bit 7:0 – OUTSET[7:0]: Data Output Value Set This register can be used instead of a read-modify-write to set the output value of individual pins to one. Writing a one to a bit will set the corresponding bit in the OUT register. Reading this register will return the value in the OUT register. 12.12.7 OUTCLR – Data Output Value Clear register z Bit 7:0 – OUTCLR[7:0]: Data Output Value Clear This register can be used instead of a read-modify-write to set the output value of individual pins to zero. Writing a one to a bit will clear the corresponding bit in the OUT register. Reading this register will return the value in the OUT register. Bit 7 6 5 4 3 2 1 0 +0x03 DIRTGL[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x04 OUT[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0000 Bit 7 6 5 4 3 2 1 0 +0x05 OUTSET[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x06 OUTCLR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 XMEGA B [MANUAL] 135 Atmel-8291C-AVR-XMEGA B -09/2014 12.12.8 OUTTGL – Data Output Value Toggle register z Bit 7:0 – OUTTGL[7:0]: Port Data Output Value Toggle This register can be used instead of a read-modify-write to toggle the output value of individual pins. Writing a one to a bit will toggle the corresponding bit in the OUT register. Reading this register will return the value in the OUT register. 12.12.9 IN – Data Input Value register z Bit 7:0 – IN[7:0]: Data Input Value This register shows the value present on the pins if the digital input driver is enabled. INn shows the value of pin n of the port. The input is not sampled and cannot be read if the digital input buffers are disabled. 12.12.10INTCTRL – Interrupt Control register z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:2/1:0 – INTnLVL[1:0]: Interrupt n Level These bits enable port interrupt n and select the interrupt level as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. Bit 7 6 5 4 3 2 1 0 +0x07 OUTTGL[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x08 IN[7:0] Read/Write RRRRRRRR Initial Value 0 0000000 Bit 7 6 5 4 3 2 1 0 +0x09 – – – – INT1LVL[1:0] INT0LVL[1:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0000000 XMEGA B [MANUAL] 136 Atmel-8291C-AVR-XMEGA B -09/2014 12.12.11INT0MASK – Interrupt 0 Mask register z Bit 7:0 – INT0MSK[7:0]: Interrupt 0 Mask bits These bits are used to mask which pins can be used as sources for port interrupt 0. If INT0MASKn is written to one, pin n is used as source for port interrupt 0.The input sense configuration for each pin is decided by the PINnCTRL registers. 12.12.12INT1MASK – Interrupt 1 Mask register z Bit 7:0 – INT1MASK[7:0]: Interrupt 1 Mask bits These bits are used to mask which pins can be used as sources for port interrupt 1. If INT1MASKn is written to one, pin n is used as source for port interrupt 1.The input sense configuration for each pin is decided by the PINnCTRL registers. 12.12.13INTFLAGS – Interrupt Flag register z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1:0 – INTnIF: Interrupt n Flag The INTnIF flag is set when a pin change/state matches the pin's input sense configuration, and the pin is set as source for port interrupt n. Writing a one to this flag's bit location will clear the flag. For enabling and executing the interrupt, refer to the interrupt level description. Bit 7 6 5 4 3 2 1 0 +0x0A INT0MSK[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0B INT1MSK[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0000000 Bit 7 6 5 4 3 2 1 0 +0x0C – – – – – – INT1IF INT0IF Read/Write R R R R R R R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 137 Atmel-8291C-AVR-XMEGA B -09/2014 12.12.14REMAP – Pin Remap register The pin remap functionality is available for PORTC - PORTF only. z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5 – SPI: SPI Remap Setting this bit to one will swap the pin locations of the SCK and MOSI pins to have pin compatibility between SPI and USART when the USART is operating as a SPI master. z Bit 4 – USART0: USART0 Remap Setting this bit to one will move the pin location of USART0 from Px[3:0] to Px[7:4]. z Bit 3 – TC0D: Timer/Counter 0 Output Compare D Setting this bit will move the location of OC0D from Px3 to Px7. z Bit 2 – TC0C: Timer/Counter 0 Output Compare C Setting this bit will move the location of OC0C from Px2 to Px6. z Bit 1 – TC0B: Timer/Counter 0 Output Compare B Setting this bit will move the location of OC0B from Px1 to Px5. If this bit is set and PWM from both timer/counter 0 and timer/counter 1 is enabled, the resulting PWM will be an OR-modulation between the two PWM outputs. z Bit 0 – TC0A: Timer/Counter 0 Output Compare A Setting this bit will move the location of OC0A from Px0 to Px4. If this bit is set and PWM from both timer/counter 0 and timer/counter 1 is enabled, the resulting PWM will be an OR-modulation between the two PWM outputs. See Figure 12- 11. Figure 12-11.I/O timer/counter. Bit 7 6 5 4 3 2 1 0 +0x0E – – SPI USART0 TC0D TC0C TC0B TC0A Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 0 0000000 OC0A OC1A OCA XMEGA B [MANUAL] 138 Atmel-8291C-AVR-XMEGA B -09/2014 12.12.15PINnCTRL – Pin n Configuration Register z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 6 – INVEN: Inverted I/O Enable Setting this bit will enable inverted output and input data on pin n. z Bit 5:3 – OPC: Output and Pull Configuration These bits set the output/pull configuration on pin n according to Table 12-5. Table 12-5. Output/pull configuration z Bit 2:0 – ISC[2:0]: Input/Sense Configuration These bits set the input and sense configuration on pin n according to Table 12-6 on page 138. The sense configuration decides how the pin can trigger port interrupts and events. If the input buffer is not disabled, the input cannot be read in the IN register. Table 12-6. Input/sense configuration. Bit 7 6 5 4 3 2 1 0 – INVEN OPC[2:0] ISC[2:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 OPC[2:0] Group Configuration Description Output Configuration Pull Configuration 000 TOTEM Totem-pole (N/A) 001 BUSKEEPER Totem-pole Bus-keeper 010 PULLDOWN Totem-pole Pull-down (on input) 011 PULLUP Totem-pole Pull-up (on input) 100 WIREDOR Wired-OR (N/A) 101 WIREDAND Wired-AND (N/A) 110 WIREDORPULL Wired-OR Pull-down 111 WIREDANDPULL Wired-AND Pull-up ISC[2:0] Group Configuration Description 000 BOTHEDGES Sense both edges 001 RISING Sense rising edge 010 FALLING Sense falling edge 011 LEVEL Sense low level(1) XMEGA B [MANUAL] 139 Atmel-8291C-AVR-XMEGA B -09/2014 Note: 1. A low-level pin value will not generate events, and a high-level pin value will continuously generate events. 2. Only PORTA - PORTF support the input buffer disable option. If the pin is used for analog functionality, such as AC or ADC, it is recommended to configure the pin to INPUT_DISABLE. 100 – Reserved 101 – Reserved 110 – Reserved 111 INTPUT_DISABLE Digital input buffer disabled(2) ISC[2:0] Group Configuration Description XMEGA B [MANUAL] 140 Atmel-8291C-AVR-XMEGA B -09/2014 12.13 Register Descriptions – Port Configuration 12.13.1 MPCMASK – Multi-pin Configuration Mask register z Bit 7:0 – MPCMASK[7:0]: Multi-pin Configuration Mask The MPCMASK register enables configuration of several pins of a port at the same time. Writing a one to bit n makes pin n part of the multi-pin configuration. When one or more bits in the MPCMASK register is set, writing any of the PINnCTRL registers will update only the PINnCTRL registers matching the mask in the MPCMASK register for that port. The MPCMASK register is automatically cleared after any PINnCTRL register is written. 12.13.2 VPCTRLA – Virtual Port-map Control register A z Bit 7:4 – VP1MAP: Virtual Port 1 Mapping These bits decide which ports should be mapped to Virtual Port 1. The registers DIR, OUT, IN, and INTFLAGS will be mapped. Accessing the virtual port registers is equal to accessing the actual port registers. See Table 12-7 on page 141 for configuration. z Bit 3:0 – VP0MAP: Virtual Port 0 Mapping These bits decide which ports should be mapped to Virtual Port 0. The registers DIR, OUT, IN, and INTFLAGS will be mapped. Accessing the virtual port registers is equal to accessing the actual port registers. See Table 12-7 on page 141 for configuration. 12.13.3 VPCTRLB – Virtual Port-map Control register B z Bit 7:4 – VP3MAP: Virtual Port 3 Mapping These bits decide which ports should be mapped to Virtual Port 3. The registers DIR, OUT, IN, and INTFLAGS will be mapped. Accessing the virtual port registers is equal to accessing the actual port registers. See Table 12-7 on page 141 for configuration. Bit 7 6 5 4 3 2 1 0 +0x00 MPCMASK[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x02 VP1MAP[3:0] VP0MAP[3:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 Bit 7 6 5 4 3 2 1 0 +0x03 VP3MAP[3:0] VP2MAP[3:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 141 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 3:0 – VP2MAP: Virtual Port 2 Mapping These bits decide which ports should be mapped to Virtual Port 2. The registers DIR, OUT, IN, and INTFLAGS will be mapped. Accessing the virtual port registers is equal to accessing the actual port registers. See Table 12-7 on page 141 for configuration. Table 12-7. Virtual port mapping 12.13.4 CLKEVOUT – Clock and Event Out register z Bit 7 – CLKEVPIN: Clock and Event Output Pin Select Setting this pin enables output of clock and event pins on port pin 4 instead of port pin 7. z Bit 6 – RTCOUT: RTC Clock Output Enable Setting this bit enables output of the RTC clock source on PORTC pin 6. z Bit 5:4 – EVOUT[1:0]: Event Output Port These bits decide which port event channel 0 from the event system will be output to. Pin 7 on the selected port is the default used, and the CLKOUT bits must be set differently from those of EVOUT. The port pin must be configured as output for the event to be available on the pin. VPnMAP[3:0] Group Configuration Description 0000 PORTA PORTA mapped to Virtual Port n 0001 PORTB PORTB mapped to Virtual Port n 0010 PORTC PORTC mapped to Virtual Port n 0011 PORTD PORTD mapped to Virtual Port n 0100 PORTE PORTE mapped to Virtual Port n 0101 PORTF PORTF mapped to Virtual Port n 0110 PORTG PORTG mapped to Virtual Port n 0111 PORTH PORTH mapped to Virtual Port n 1000 PORTJ PORTJ mapped to Virtual Port n 1001 PORTK PORTK mapped to Virtual Port n 1010 PORTL PORTL mapped to Virtual Port n 1011 PORTM PORTM mapped to Virtual Port n 1100 PORTN PORTN mapped to Virtual Port n 1101 PORTP PORTP mapped to Virtual Port n 1110 PORTQ PORTQ mapped to Virtual Port n 1111 PORTR PORTR mapped to Virtual Port n Bit 7 6 5 4 3 2 1 0 +0x04 CLKEVPIN RTCOUT EVOUT[1:0] CLKOUTSEL[1:0] CLKOUT[1:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 142 Atmel-8291C-AVR-XMEGA B -09/2014 Table 12-8 on page 142 shows the possible configurations. z Bits 3:2 – CLKOUTSEL[1:0]: Clock Output Select These bits are used to select which of the peripheral clocks will be output to the port pin if CLKOUT is configured. z Bit 1:0 – CLKOUT[1:0]: Clock Output Port These bits decide which port the peripheral clock will be output to. Pin 7 on the selected port is the default used. The CLKOUT setting will override the EVOUT setting. Thus, if both are enabled on the same port pin, the peripheral clock will be visible. The port pin must be configured as output for the clock to be available on the pin. Table 12-10 shows the possible configurations. Table 12-8. Event output pin selection. EVOUT[1:0] Group Configuration Description 00 OFF Event output disabled 01 PC Event channel 0 output on PORTC 10 PD Event channel 0 output on PORTD 11 PE Event channel 0 output on PORTE Table 12-9. Clock output clock selection. CLKOUTSEL[1:0] Group Configuration Description 00 CLK1X CLKPER output to pin 01 CLK2X CLKPER2 output to pin 10 CLK4X CLKPER4 output to pin 11 – (Reserved) Table 12-10. Clock output port configurations. CLKOUT[1:0] Group Configuration Description 00 OFF Clock output disabled 01 PC Clock output on PORTC 10 PD Clock output on PORTD 11 PE Clock output on PORTE XMEGA B [MANUAL] 143 Atmel-8291C-AVR-XMEGA B -09/2014 12.13.5 EVCTRL – Event Control register z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2:0 – EVOUTSEL[2:0]: Event Channel Output Selection These bits define which channel from the event system is output to the port pin. Table 12-11 shows the available selections. Bit 7 6 5 4 3 2 1 0 +0x06 – – – – – EVOUTSEL[2:0] Read/Write R R R R R R/W R/W R/W Initial Value 0 0 0 0 0 000 Table 12-11. Event channel output selection. EVOUTSEL[2:0] Group Configuration Description 000 0 Event channel 0 output to pin 001 1 Event channel 1 output to pin 010 2 Event channel 2 output to pin 011 3 Event channel 3 output to pin 100 4 Event channel 4 output to pin 101 5 Event channel 5 output to pin 110 6 Event channel 6 output to pin 111 7 Event channel 7 output to pin XMEGA B [MANUAL] 144 Atmel-8291C-AVR-XMEGA B -09/2014 12.14 Register Descriptions – Virtual Port 12.14.1 DIR – Data Direction register z Bit 7:0 – DIR[7:0]: Data Direction This register sets the data direction for the individual pins in the port mapped by VPCTRLA, virtual port-map control register A or VPCTRLB, virtual port-map control register B. When a port is mapped as virtual, accessing this register is identical to accessing the actual DIR register for the port. 12.14.2 OUT – Data Output Value register z Bit 7:0 – OUT[7:0]: Data Output value This register sets the data output value for the individual pins in the port mapped by VPCTRLA, virtual port-map control register A or VPCTRLB, virtual port-map control register B. When a port is mapped as virtual, accessing this register is identical to accessing the actual OUT register for the port. 12.14.3 IN – Data Input Value register z Bit 7:0 – IN[7:0]: Data Input value This register shows the value present on the pins if the digital input buffer is enabled. The configuration of VPCTRLA, virtual port-map control register A or VPCTRLB, virtual port-map control register A, decides the value in the register. When a port is mapped as virtual, accessing this register is identical to accessing the actual IN register for the port. Bit 7 6 5 4 3 2 1 0 +0x00 DIR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x01 OUT[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0000000 Bit 7 6 5 4 3 2 1 0 +0x02 IN[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 145 Atmel-8291C-AVR-XMEGA B -09/2014 12.14.4 INTFLAGS – Interrupt Flag register z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1:0 – INTnIF: Interrupt n Flag The INTnIF flag is set when a pin change/state matches the pin's input sense configuration, and the pin is set as source for port interrupt n. Writing a one to this flag's bit location will clear the flag. For enabling and executing the interrupt, refer to the interrupt level description. The configuration of VPCTRLA, virtual port-map control register A, or VPCTRLB, Virtual Port-map Control Register B, decides which flags are mapped. When a port is mapped as virtual, accessing this register is identical to accessing the actual INTFLAGS register for the port. Bit 7 6 5 4 3 2 1 0 +0x03 – – – – – – INT1IF INT0IF Read/Write R R R R R R R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 146 Atmel-8291C-AVR-XMEGA B -09/2014 12.15 Register Summary – Ports 12.16 Register Summary – Port Configuration 12.17 Register Summary – Virtual Ports Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 DIR DIR[7:0] 133 +0x01 DIRSET DIRSET[7:0] 133 +0x02 DIRCLR DIRCLR[7:0] 133 +0x03 DIRTGL DIRTGL[7:0] 134 +0x04 OUT OUT[7:0] 134 +0x05 OUTSET OUTSET[7:0] 134 +0x06 OUTCLR OUTCLR[7:0] 134 +0x07 OUTTGL OUTTGL[7:0] 135 +0x08 IN IN[7:0] 135 +0x09 INTCTRL – – – – INT1LVL[1:0] INT0LVL[1:0] 135 +0x0A INT0MASK INT0MSK[7:0] 136 +0x0B INT1MASK INT1MSK[7:0] 136 +0x0C INTFLAGS – – – – – – INT1IF INT0IF 136 +0x0D Reserved – – – – – – – – +0x0E REMAP – – SPI USART0 TC0D TC0C TC0B TC0A 137 +0x0F Reserved – – – – – – – – +0x10 PIN0CTRL – INVEN OPC[2:0] ISC[2:0] 138 +0x11 PIN1CTRL – INVEN OPC[2:0] ISC[2:0] 138 +0x12 PIN2CTRL – INVEN OPC[2:0] ISC[2:0] 138 +0x13 PIN3CTRL – INVEN OPC[2:0] ISC[2:0] 138 +0x14 PIN4CTRL – INVEN OPC[2:0] ISC[2:0] 138 +0x15 PIN5CTRL – INVEN OPC[2:0] ISC[2:0] 138 +0x16 PIN6CTRL – INVEN OPC[2:0] ISC[2:0] 138 +0x17 PIN7CTRL – INVEN OPC[2:0] ISC[2:0] 138 +0x18 Reserved – – – – – – – – +0x19 Reserved – – – – – – – – +0x1A Reserved – – – – – – – – +0x1B Reserved – – – – – – – – +0x1C Reserved – – – – – – – – +0x1D Reserved – – – – – – – – +0x1E Reserved – – – – – – – – +0x1F Reserved – – – – – – – – Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 MPCMASK MPCMASK[7:0] 140 +0x01 Reserved – – – – – – – – +0x02 VPCTRLA VP1MAP[3:0] VP0MAP[3:0] 140 +0x03 VPCTRLB VP3MAP[3:0] VP2MAP[3:0] 140 +0x04 CLKEVOU CLKEVPIN RTCOUT EVOUT[1:0] CLKOUTSEL CLKOUT[1:0] 141 +0x05 Reserved – – – – – – – – +0x06 EVCTRL – – – – – EVCTRL[2:0] 143 +0x07 Reserved – – – – – – – – Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 DIR DIR[7:0] 144 +0x01 OUT OUT[7:0] 144 +0x02 IN IN[7:0] 144 +0x03 INTFLAGS – – – – – – INT1IF INT0IF 145 XMEGA B [MANUAL] 147 Atmel-8291C-AVR-XMEGA B -09/2014 12.18 Interrupt Vector Summary – Ports Offset Source Interrupt Description 0x00 INT0_vect Port interrupt vector 0 offset 0x02 INT1_vect Port interrupt vector 1 offset XMEGA B [MANUAL] 148 Atmel-8291C-AVR-XMEGA B -09/2014 13. TC0/1 – 16-bit Timer/Counter Type 0 and 1 13.1 Features z 16-bit timer/counter z 32-bit timer/counter support by cascading two timer/counters z Up to four compare or capture (CC) channels z Four CC channels for timer/counters of type 0 z Two CC channels for timer/counters of type 1 z Double buffered timer period setting z Double buffered capture or compare channels z Waveform generation: z Frequency generation z Single-slope pulse width modulation z Dual-slope pulse width modulation z Input capture: z Input capture with noise cancelling z Frequency capture z Pulse width capture z 32-bit input capture z Timer overflow and error interrupts/events z One compare match or input capture interrupt/event per CC channel z Can be used with event system for: z Quadrature decoding z Count and direction control z Capture z Can be used with DMA and to trigger DMA transactions z High-resolution extension z Increases frequency and waveform resolution by 4x (2-bit) or 8x (3-bit) z Advanced waveform extension: z Low- and high-side output with programmable dead-time insertion (DTI) z Event controlled fault protection for safe disabling of drivers 13.2 Overview Atmel AVR XMEGA devices have a set of flexible, 16-bit timer/counters (TC). Their capabilities include accurate program execution timing, frequency and waveform generation, and input capture with time and frequency measurement of digital signals. Two timer/counters can be cascaded to create a 32-bit timer/counter with optional 32-bit capture. A timer/counter consists of a base counter and a set of compare or capture (CC) channels. The base counter can be used to count clock cycles or events. It has direction control and period setting that can be used for timing. The CC channels can be used together with the base counter to do compare match control, frequency generation, and pulse width waveform modulation, as well as various input capture operations. A timer/counter can be configured for either capture or compare functions, but cannot perform both at the same time. A timer/counter can be clocked and timed from the peripheral clock with optional prescaling or from the event system. The event system can also be used for direction control and capture trigger or to synchronize operations. There are two differences between timer/counter type 0 and type 1. Timer/counter 0 has four CC channels, and timer/counter 1 has two CC channels. All information related to CC channels 3 and 4 is valid only for timer/counter 0. Only Timer/Counter 0 has the split mode feature that split it into two 8-bit Timer/Counters with four compare channels each. XMEGA B [MANUAL] 149 Atmel-8291C-AVR-XMEGA B -09/2014 Some timer/counters have extensions to enable more specialized waveform and frequency generation. The advanced waveform extension (AWeX) is intended for motor control and other power control applications. It enables low- and highside output with dead-time insertion, as well as fault protection for disabling and shutting down external drivers. It can also generate a synchronized bit pattern across the port pins. The high-resolution (hi-res) extension can be used to increase the waveform output resolution by four or eight times by using an internal clock source running up to four times faster than the peripheral clock. A block diagram of the 16-bit timer/counter with extensions and closely related peripheral modules (in grey) is shown in Figure 13-1 on page 149. Figure 13-1. 16-bit timer/counter and closely related peripherals. 13.2.1 Definitions The following definitions are used throughout the documentation: Table 13-1. Timer/counter definitions In general, the term “timer” is used when the timer/counter clock control is handled by an internal source, and the term “counter” is used when the clock control is handled externally (e.g. counting external events). When used for compare operations, the CC channels are referred to as “compare channels.” When used for capture operations, the CC channels are referred to as “capture channels.” Name Description BOTTOM The counter reaches BOTTOM when it becomes zero. MAX The counter reaches MAXimum when it becomes all ones. TOP The counter reaches TOP when it becomes equal to the highest value in the count sequence. The TOP value can be equal to the period (PER) or the compare channel A (CCA) register setting. This is selected by the waveform generator mode. UPDATE The timer/counter signals an update when it reaches BOTTOM or TOP, depending on the waveform generator mode. XMEGA B [MANUAL] 150 Atmel-8291C-AVR-XMEGA B -09/2014 13.3 Block Diagram Figure 13-2 on page 150 shows a detailed block diagram of the timer/counter without the extensions. Figure 13-2. Timer/counter block diagram. The counter register (CNT), period registers with buffer (PER and PERBUF), and compare and capture registers with buffers (CCx and CCxBUF) are 16-bit registers. All buffer register have a buffer valid (BV) flag that indicates when the buffer contains a new value. During normal operation, the counter value is continuously compared to zero and the period (PER) value to determine whether the counter has reached TOP or BOTTOM. The counter value is also compared to the CCx registers. These comparisons can be used to generate interrupt requests, request DMA transactions or generate events for the event system. The waveform generator modes use these comparisons to set the waveform period or pulse width. A prescaled peripheral clock and events from the event system can be used to control the counter. The event system is also used as a source to the input capture. Combined with the quadrature decoding functionality in the event system (QDEC), the timer/counter can be used for quadrature decoding. Base Counter Compare/Capture (Unit x = {A,B,C,D}) Counter = CCx CCBUFx Waveform Generation BV = PERBUF PER CNT BV = 0 "count" "clear" "direction" "load" Control Logic CTRLD CTRLA OVF/UNF (INT/DMA Req.) ERRIF (INT Req.) TOP "match" CCxIF (INT/DMA Req.) Control Logic Clock Select "ev" UPDATE BOTTOM OCx Out Event Select XMEGA B [MANUAL] 151 Atmel-8291C-AVR-XMEGA B -09/2014 13.4 Clock and Event Sources The timer/counter can be clocked from the peripheral clock (clkPER) or the event system, and Figure 13-3 shows the clock and event selection. Figure 13-3. Clock and event selection. The peripheral clock is fed into a common prescaler (common for all timer/counters in a device). Prescaler outputs from 1 to 1/1024 are directly available for selection by the timer/counter. In addition, the whole range of prescaling from 1 to 215 times is available through the event system. Clock selection (CLKSEL) selects one of the prescaler outputs directly or an event channel as the counter (CNT) input. This is referred to as normal operation of the counter. For details, refer to “Normal Operation” on page 152. By using the event system, any event source, such as an external clock signal on any I/O pin, may be used as the clock input. In addition, the timer/counter can be controlled via the event system. The event selection (EVSEL) and event action (EVACT) settings are used to trigger an event action from one or more events. This is referred to as event action controlled operation of the counter. For details, refer to “Event Action Controlled Operation” on page 153. When event action controlled operation is used, the clock selection must be set to use an event channel as the counter input. By default, no clock input is selected and the timer/counter is not running. 13.5 Double Buffering The period register and the CC registers are all double buffered. Each buffer register has a buffer valid (BV) flag, which indicates that the buffer register contains a valid, i.e. new, value that can be copied into the corresponding period or CC register. When the period register and CC channels are used for a compare operation, the buffer valid flag is set when data is written to the buffer register and cleared on an UPDATE condition. This is shown for a compare register in Figure 13-4 on page 152. clkPER / 2{0,...,15} CKSEL CNT EVACT clkPER / {1,2,4,8,64,256,1024} Common Prescaler clkPER event channels (Encoding) Event System EVSEL Control Logic events XMEGA B [MANUAL] 152 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 13-4. Period and compare double buffering. When the CC channels are used for a capture operation, a similar double buffering mechanism is used, but in this case the buffer valid flag is set on the capture event, as shown in Figure 13-5. For capture, the buffer register and the corresponding CCx register act like a FIFO. When the CC register is empty or read, any content in the buffer register is passed to the CC register. The buffer valid flag is passed to set the CCx interrupt flag (IF) and generate the optional interrupt. Figure 13-5. Capture double buffering. Both the CCx and CCxBUF registers are available as an I/O register. This allows initialization and bypassing of the buffer register and the double buffering function. 13.6 Counter Operation Depending on the mode of operation, the counter is cleared, reloaded, incremented, or decremented at each timer/counter clock input. 13.6.1 Normal Operation In normal operation, the counter will count in the direction set by the direction (DIR) bit for each clock until it reaches TOP or BOTTOM. When up-counting and TOP is reached, the counter will be set to zero when the next clock is given. When down-counting, the counter is reloaded with the period register value when BOTTOM is reached. BV UPDATE "write enable" "data write" = CNT "match" CCxBUF EN CCx EN BV "capture" IF CNT CCxBUF EN CCx EN "INT/DMA request" data read XMEGA B [MANUAL] 153 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 13-6. Normal operation. As shown in Figure 13-6, it is possible to change the counter value when the counter is running. The write access has higher priority than count, clear, or reload, and will be immediate. The direction of the counter can also be changed during normal operation. Normal operation must be used when using the counter as timer base for the capture channels. 13.6.2 Event Action Controlled Operation The event selection and event action settings can be used to control the counter from the event system. For the counter, the following event actions can be selected: z Event system controlled up/down counting. z Event n will be used as count enable. z Event n+1 will be used to select between up (1) and down (0). The pin configuration must be set to low level sensing. z Event system controlled quadrature decode counting. 13.6.3 32-bit Operation Two timer/counters can be used together to enable 32-bit counter operation. By using two timer/counters, the overflow event from one timer/counter (least-significant timer) can be routed via the event system and used as the clock input for another timer/counter (most-significant timer). 13.6.4 Changing the Period The counter period is changed by writing a new TOP value to the period register. If double buffering is not used, any period update is immediate, as shown in Figure 13-7 on page 153. Figure 13-7. Changing the period without buffering. CNT BOTTOM MAX "update" TOP CNT written DIR CNT MAX New TOP written to PER that is higher than current CNT Counter Wraparound New TOP written to PER that is lower than current CNT "update" "write" BOTTOM XMEGA B [MANUAL] 154 Atmel-8291C-AVR-XMEGA B -09/2014 A counter wraparound can occur in any mode of operation when up-counting without buffering, as shown in Figure 13-8. This due to the fact that CNT and PER are continuously compared, and if a new TOP value that is lower than current CNT is written to PER, it will wrap before a compare match happen. Figure 13-8. Unbuffered dual-slope operation. When double buffering is used, the buffer can be written at any time and still maintain correct operation. The period register is always updated on the UPDATE condition, as shown for dual-slope operation in Figure 13-9. This prevents wraparound and the generation of odd waveforms. Figure 13-9. Changing the period using buffering. 13.7 Capture Channel The CC channels can be used as capture channels to capture external events and give them a timestamp. To use capture, the counter must be set for normal operation. Events are used to trigger the capture; i.e., any events from the event system, including pin change from any pin, can trigger a capture operation. The event source select setting selects which event channel will trigger CC channel A. The subsequent event channels then trigger events on subsequent CC channels, if configured. For example, setting the event source select to event channel 2 results in CC channel A being triggered by event channel 2, CC channel B triggered by event channel 3, and so on. CNT MAX New TOP written to PER that is higher than current CNT New TOP written to PER that is lower than current CNT "update" "write" Counter Wraparound BOTTOM CNT MAX New Period written to PERBUF that is higher than current CNT New Period written to PERBUF that is lower than current CNT "update" "write" New PER is updated with PERBUF value. BOTTOM XMEGA B [MANUAL] 155 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 13-10.Event source selection for capture operation. The event action setting in the timer/counter will determine the type of capture that is done. The CC channels must be enabled individually before capture can be done. When the capture condition occur, the timer/counter will time-stamp the event by copying the current CNT value in the count register into the enabled CC channel register. When an I/O pin is used as an event source for the capture, the pin must be configured for edge sensing. For details on sense configuration on I/O pins, refer to “Input Sense Configuration” on page 129. If the period register value is lower than 0x8000, the polarity of the I/O pin edge will be stored in the most-significant bit (msb) of the capture register. If the msb of the capture register is zero, a falling edge generated the capture. If the msb is one, a rising edge generated the capture. 13.7.1 Input Capture Selecting the input capture event action makes the enabled capture channel perform an input capture on an event. The interrupt flags will be set and indicate that there is a valid capture result in the corresponding CC register. At the same time, the buffer valid flags indicate valid data in the buffer registers. The counter will continuously count from BOTTOM to TOP, and then restart at BOTTOM, as shown in Figure 13-11. The figure also shows four capture events for one capture channel. Figure 13-11.Input capture timing. 13.7.2 Frequency Capture Selecting the frequency capture event action makes the enabled capture channel perform an input capture and restart on positive edge events. This enables the timer/counter to measure the period or frequency of a signal directly. The capture result will be the time (T) from the previous timer/counter restart until the event occurred. This can be used to calculate the frequency (f) of the signal: Event System CH0MUX CH1MUX CHnMUX Rotate Event channel n Event Source Selection CCA capture CCB capture CCC capture CCD capture Event channel 0 Event channel 1 events CNT TOP BOTTOM Capture 0 Capture 1 Capture 2 Capture 3 f 1 T = --- XMEGA B [MANUAL] 156 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 13-12 on page 156 shows an example where the period of an external signal is measured twice. Figure 13-12.Frequency capture of an external signal. Since all capture channels use the same counter (CNT), only one capture channel must be enabled at a time. If two capture channels are used with different sources, the counter will be restarted on positive edge events from both input sources, and the result will have no meaning. 13.7.3 Pulse Width Capture Selecting the pulse width measure event action makes the enabled compare channel perform the input capture action on falling edge events and the restart action on rising edge events. The counter will then restart on positive edge events, and the input capture will be performed on the negative edge event. The event source must be an I/O pin, and the sense configuration for the pin must be set to generate an event on both edges. Figure 13-13 on page 156 shows and example where the pulse width is measured twice for an external signal. Figure 13-13.Pulse width capture of an external signal. Period (T) external signal events CNT MAX BOTTOM "capture" Pulsewitdh (tp) external signal events CNT MAX BOTTOM "capture" XMEGA B [MANUAL] 157 Atmel-8291C-AVR-XMEGA B -09/2014 13.7.4 32-bit Input Capture Two timer/counters can be used together to enable true 32-bit input capture. In a typical 32-bit input capture setup, the overflow event of the least-significant timer is connected via the event system and used as the clock input for the mostsignificant timer. The most-significant timer will be updated one peripheral clock period after an overflow occurs for the least-significant timer. To compensate for this, the capture event for the most-significant timer must be equally delayed by setting the event delay bit for this timer. 13.7.5 Capture Overflow The timer/counter can detect buffer overflow of the input capture channels. When both the buffer valid flag and the capture interrupt flag are set and a new capture event is detected, there is nowhere to store the new timestamp. If a buffer overflow is detected, the new value is rejected, the error interrupt flag is set, and the optional interrupt is generated. 13.8 Compare Channel Each compare channel continuously compares the counter value (CNT) with the CCx register. If CNT equals CCx, the comparator signals a match. The match will set the CC channel's interrupt flag at the next timer clock cycle, and the event and optional interrupt are generated. The compare buffer register provides double buffer capability equivalent to that for the period buffer. The double buffering synchronizes the update of the CCx register with the buffer value to either the TOP or BOTTOM of the counting sequence according to the UPDATE condition. The synchronization prevents the occurrence of odd-length, nonsymmetrical pulses for glitch-free output. 13.8.1 Waveform Generation The compare channels can be used for waveform generation on the corresponding port pins. To make the waveform visible on the connected port pin, the following requirements must be fulfilled: 1. A waveform generation mode must be selected. 2. Event actions must be disabled. 3. The CC channels used must be enabled. This will override the corresponding port pin output register. 4. The direction for the associated port pin must be set to output. Inverted waveform output is achieved by setting the invert output bit for the port pin. 13.8.2 Frequency (FRQ) Waveform Generation For frequency generation the period time (T) is controlled by the CCA register instead of PER. The waveform generation (WG) output is toggled on each compare match between the CNT and CCA registers, as shown in Figure 13-14 on page 158. XMEGA B [MANUAL] 158 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 13-14.Frequency waveform generation. The waveform frequency (fFRQ) is defined by the following equation: where N represents the prescaler divider used. The waveform generated will have a maximum frequency of half of the peripheral clock frequency (fclkPER) when CCA is set to zero (0x0000) and no prescaling is used. This also applies when using the hi-res extension, since this increases the resolution and not the frequency. 13.8.3 Single-slope PWM Generation For single-slope PWM generation, the period (T) is controlled by PER, while CCx registers control the duty cycle of the WG output. Figure 13-15 shows how the counter counts from BOTTOM to TOP and then restarts from BOTTOM. The waveform generator (WG) output is set on the compare match between the CNT and CCx registers and cleared at TOP. Figure 13-15.Single-slope pulse width modulation. The PER register defines the PWM resolution. The minimum resolution is 2 bits (PER=0x0003), and the maximum resolution is 16 bits (PER=MAX). The following equation calculate the exact resolution for single-slope PWM (RPWM_SS): The single-slope PWM frequency (fPWM_SS) depends on the period setting (PER) and the peripheral clock frequency (fclkPER), and can be calculated by the following equation: CNT MAX "update" TOP Period (T) Direction Change CNT written BOTTOM WG Output f FRQ fclkPER 2N CCA ( ) + 1 = ---------------------------------- CNT MAX TOP Period (T) "match" BOTTOM WG Output CCx=BOTTOM CCx CCx=TOP "update" RPWM_SS log( ) PER 1 + log( ) 2 = --------------------------------- XMEGA B [MANUAL] 159 Atmel-8291C-AVR-XMEGA B -09/2014 where N represents the prescaler divider used. The waveform generated will have a maximum frequency of half of the peripheral clock frequency (fclkPER) when CCA is set to zero (0x0000) and no prescaling is used. This also applies when using the hi-res extension, since this increases the resolution and not the frequency. 13.8.4 Dual-slope PWM For dual-slope PWM generation, the period (T) is controlled by PER, while CCx registers control the duty cycle of the WG output. Figure 13-16 shows how for dual-slope PWM the counter counts repeatedly from BOTTOM to TOP and then from TOP to BOTTOM. The waveform generator output is set on BOTTOM, cleared on compare match when up-counting, and set on compare match when down-counting. Figure 13-16.Dual-slope pulse width modulation. Using dual-slope PWM results in a lower maximum operation frequency compared to the single-slope PWM operation. The period register (PER) defines the PWM resolution. The minimum resolution is 2 bits (PER=0x0003), and the maximum resolution is 16 bits (PER=MAX). The following equation calculate the exact resolution for dual-slope PWM (RPWM_DS): The PWM frequency depends on the period setting (PER) and the peripheral clock frequency (fclkPER), and can be calculated by the following equation: N represents the prescaler divider used. The waveform generated will have a maximum frequency of half of the peripheral clock frequency (fclkPER) when CCA is set to zero (0x0000) and no prescaling is used. This also applies when using the hi-res extension, since this increases the resolution and not the frequency. 13.8.5 Port Override for Waveform Generation To make the waveform generation available on the port pins, the corresponding port pin direction must be set as output. The timer/counter will override the port pin values when the CC channel is enabled (CCENx) and a waveform generation mode is selected. f PWM_SS fclkPER N( ) PER 1 + = ----------------------------- CNT MAX TOP Period (T) BOTTOM WG Output CCx=BOTTOM CCx CCx=TOP "match" "update" RPWM_DS log( ) PER 1 + log( ) 2 = --------------------------------- f PWM_DS fclkPER 2NPER = -------------------- XMEGA B [MANUAL] 160 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 13-17 on page 160 shows the port override for a timer/counter. The timer/counter CC channel will override the port pin output value (OUT) on the corresponding port pin. Enabling inverted I/O on the port pin (INVEN) inverts the corresponding WG output. Figure 13-17.Port override for timer/counter 0 and 1. 13.9 Interrupts and events The timer/counter can generate both interrupts and events. The counter can generate an interrupt on overflow/underflow, and each CC channel has a separate interrupt that is used for compare or capture. In addition, an error interrupt can be generated if any of the CC channels is used for capture and a buffer overflow condition occurs on a capture channel. Events will be generated for all conditions that can generate interrupts. For details on event generation and available events, refer to “Event System” on page 63. 13.10 DMA Support The interrupt flags can be used to trigger DMA transactions. Table 13-2 lists the transfer triggers available from the timer/counter and the DMA action that will clear the transfer trigger. For more details on using DMA, refer to “DMAC - Direct Memory Access Controller” on page 47. Table 13-2. DMA request sources 13.11 Timer/Counter Commands A set of commands can be given to the timer/counter by software to immediately change the state of the module. These commands give direct control of the UPDATE, RESTART, and RESET signals. An update command has the same effect as when an update condition occurs. The update command is ignored if the lock update bit is set. The software can force a restart of the current waveform period by issuing a restart command. In this case the counter, direction, and all compare outputs are set to zero. A reset command will set all timer/counter registers to their initial values. A reset can be given only when the timer/counter is not running (OFF). OUT CCExEN INVEN OCx Waveform Request Acknowledge Comment OVFIF/UNFIF DMA controller writes to CNT DMA controller writes to PER DMA controller writes to PERBUF DMA controller writes to DTHSBUF or DTLSBUF in AWeX when in Pattern Generation Mode ERRIF N/A CCxIF DMA controller access of CCx DMA controller access of CCxBUF Input capture operation Output compare operation XMEGA B [MANUAL] 161 Atmel-8291C-AVR-XMEGA B -09/2014 13.12 Register Description 13.12.1 CTRLA – Control register A z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:0 – CLKSEL[3:0]: Clock Select These bits select the clock source for the timer/counter according to Table 13-3. CLKSEL=0001 must be set to ensure a correct output from the waveform generator when the hi-res extension is enabled. Table 13-3. Clock select options 13.12.2 CTRLB – Control register B z Bit 7:4 – CCxEN: Compare or Capture Enable Setting these bits in the FRQ or PWM waveform generation mode of operation will override the port output register for the corresponding OCn output pin. When input capture operation is selected, the CCxEN bits enable the capture operation for the corresponding CC channel. Bit 7 6 5 4 3 2 1 0 +0x00 – – – – CLKSEL[3:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 00000000 CLKSEL[3:0] Group Configuration Description 0000 OFF None (i.e, timer/counter in OFF state) 0001 DIV1 Prescaler: Clk 0010 DIV2 Prescaler: Clk/2 0011 DIV4 Prescaler: Clk/4 0100 DIV8 Prescaler: Clk/8 0101 DIV64 Prescaler: Clk/64 0110 DIV256 Prescaler: Clk/256 0111 DIV1024 Prescaler: Clk/1024 1nnn EVCHn Event channel n, n= [0,...,7] Bit 7 6 5 4 3 2 1 0 +0x01 CCDEN CCCEN CCBEN CCAEN – WGMODE[2:0] Read/Write R/W R/W R/W R/W R R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 162 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 3 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 2:0 – WGMODE[2:0]: Waveform Generation Mode These bits select the waveform generation mode, and control the counting sequence of the counter, TOP value, UPDATE condition, interrupt/event condition, and type of waveform that is generated according to Table 13-4. No waveform generation is performed in the normal mode of operation. For all other modes, the result from the waveform generator will only be directed to the port pins if the corresponding CCxEN bit has been set to enable this. The port pin direction must be set as output. Table 13-4. Timer waveform generation mode. 13.12.3 CTRLC – Control register C z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:0 – CMPx: Compare Output Value x These bits allow direct access to the waveform generator's output compare value when the timer/counter is set in the OFF state. This is used to set or clear the WG output value when the timer/counter is not running. WGMODE[2:0] Group Configuration Mode of Operation Top Update OVFIF/Event 000 NORMAL Normal PER TOP TOP 001 FRQ Frequency CCA TOP TOP 010 Reserved - - - 011 SINGLESLOPE Single-slope PWM PER BOTTOM BOTTOM 100 Reserved - - - 101 DSTOP Dual-slope PWM PER BOTTOM TOP 110 DSBOTH Dual-slope PWM PER BOTTOM TOP and BOTTOM 111 DSBOTTOM Dual-slope PWM PER BOTTOM BOTTOM Bit 7 6 5 4 3 2 1 0 +0x02 – – – – CMPD CMPC CMPB CMPA Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0000 XMEGA B [MANUAL] 163 Atmel-8291C-AVR-XMEGA B -09/2014 13.12.4 CTRLD – Control register D z Bit 7:5 – EVACT[2:0]: Event Action These bits define the event action the timer will perform on an event according to Table 13-5 on page 163. The EVSEL setting will decide which event source or sources have control in this case. Table 13-5. Timer event action selection. Selecting any of the capture event actions changes the behavior of the CCx registers and related status and control bits to be used for capture. The error status flag (ERRIF) will indicate a buffer overflow in this configuration. See “Event Action Controlled Operation” on page 153 for further details. z Bit 4 – EVDLY: Timer Delay Event When this bit is set, the selected event source is delayed by one peripheral clock cycle. This is intended for 32-bit input capture operation. Adding the event delay is necessary to compensate for the carry propagation delay when cascading two counters via the event system. z Bit 3:0 – EVSEL[3:0]:Timer Event Source Select These bits select the event channel source for the timer/counter. For the selected event channel to have any effect, the event action bits (EVACT) must be set according to Table 13-6. When the event action is set to a capture operation, the selected event channel n will be the event channel source for CC channel A, and event channel (n+1)%8, (n+2)%8, and (n+3)%8 will be the event channel source for CC channel B, C, and D. Table 13-6. Timer event source selection Bit 7 6 5 4 3 2 1 0 +0x03 EVACT[2:0] EVDLY EVSEL[3:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 EVACT[2:0] Group Configuration Event Action 000 OFF None 001 CAPT Input capture 010 UPDOWN Externally controlled up/ down count 011 QDEC Quadrature decode 100 RESTART Restart waveform period 101 FRQ Frequency capture 110 PW Pulse width capture 111 Reserved EVSEL[3:0] Group Configuration Event Source 0000 OFF None 0001 – Reserved 0010 – Reserved 0011 – Reserved XMEGA B [MANUAL] 164 Atmel-8291C-AVR-XMEGA B -09/2014 13.12.5 CTRLE – Control register E z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1:0 – BYTEM[1:0]: Byte Mode These bits select the timer/counter operation mode according to Table 13-7. Table 13-7. Clock select 13.12.6 INTCTRLA – Interrupt Enable register A z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. 0100 – Reserved 0101 – Reserved 0110 – Reserved 0111 – Reserved 1nnn CHn Event channel n, n={0,...,7} EVSEL[3:0] Group Configuration Event Source Bit 7 6 5 4 3 2 1 0 +0x04 – – – – – – BYTEM[1:0] Read/Write R R R R R R R R/W Initial Value 00000000 BYTEM[1:0] Group Configuration Description 00 NORMAL Timer/counter is set to normal mode (timer/counter type 0) 01 BYTEMODE Upper byte of the counter (CNTH) will be set to zero after each counter clock cycle 10 SPLITMODE Timer/counter 0 is split into two 8-bit timer/counters (timer/counter type 2) 11 – Reserved Bit 7 6 5 4 3 2 1 0 +0x06 – – – – ERRINTLVL[1:0] OVFINTLVL[1:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 165 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 3:2 – ERRINTLVL[1:0]:Timer Error Interrupt Level These bits enable the timer error interrupt and select the interrupt level as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. z Bit 1:0 – OVFINTLVL[1:0]:Timer Overflow/Underflow Interrupt Level These bits enable the timer overflow/underflow interrupt and select the interrupt level as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. 13.12.7 INTCTRLB – Interrupt Enable register B z Bit 7:0 – CCxINTLVL[7:0] - Compare or Capture x Interrupt Level These bits enable the timer compare or capture interrupt for channel x and select the interrupt level as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. 13.12.8 CTRLFCLR/CTRLFSET – Control register F Clear/Set This register is mapped into two I/O memory locations, one for clearing (CTRLxCLR) and one for setting the register bits (CTRLxSET) when written. Both memory locations will give the same result when read. The individual status bit can be set by writing a one to its bit location in CTRLxSET, and cleared by writing a one to its bit location in CTRLxCLR. This allows each bit to be set or cleared without use of a read-modify-write operation on a single register. 13.12.8.1 CTRLFCLR 13.12.8.2 CTRLFSET z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:2 – CMD[1:0]: Command These bits can be used for software control of update, restart, and reset of the timer/counter. The command bits are always read as zero. Bit 7 6 5 4 3 2 1 0 +0x07 CCDINTLVL[1:0] CCCINTLVL[1:0] CCBINTLVL[1:0] CCAINTLVL[1:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0000000 Bit 7 6 5 4 3 2 1 0 +0x08 – – – – CMD[1:0] LUPD DIR Read/Write R R R R R R R/W R/W Initial Value 0 0 0 00000 Bit 7 6 5 4 3 2 1 0 +0x09 – – – – CMD[1:0] LUPD DIR Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 00000 XMEGA B [MANUAL] 166 Atmel-8291C-AVR-XMEGA B -09/2014 Table 13-8. Command selections z Bit 1 – LUPD: Lock Update When this bit is set, no update of the buffered registers is performed, even though an UPDATE condition has occurred. Locking the update ensures that all buffers, including DTI buffers, are valid before an update is performed. This bit has no effect when input capture operation is enabled. z Bit 0 – DIR: Counter Direction When zero, this bit indicates that the counter is counting up (incrementing). A one indicates that the counter is in the down-counting (decrementing) state. Normally this bit is controlled in hardware by the waveform generation mode or by event actions, but this bit can also be changed from software. 13.12.9 CTRLGCLR/CTRLGSET – Control register G Clear/Set Refer to “CTRLFCLR/CTRLFSET – Control register F Clear/Set” on page 165 for information on how to access this type of status register. z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4:1 – CCxBV: Compare or Capture x Buffer Valid These bits are set when a new value is written to the corresponding CCxBUF register. These bits are automatically cleared on an UPDATE condition. Note that when input capture operation is used, this bit is set on a capture event and cleared if the corresponding CCxIF is cleared. z Bit 0 – PERBV: Period Buffer Valid This bit is set when a new value is written to the PERBUF register. This bit is automatically cleared on an UPDATE condition. CMD Group Configuration Command Action 00 NONE None 01 UPDATE Force update 10 RESTART Force restart 11 RESET Force hard reset (ignored if T/C is not in OFFstate) Bit 7 6 5 4 3 2 1 0 +0x0A/ +0x0B – – – CCDBV CCCBV CCBBV CCABV PERBV Read/Write R R R R/W R/W R/W R/W R/W Initial Value 0 0 0 00000 XMEGA B [MANUAL] 167 Atmel-8291C-AVR-XMEGA B -09/2014 13.12.10INTFLAGS – Interrupt Flag register z Bit 7:4 – CCxIF: Compare or Capture Channel x Interrupt Flag The compare or capture interrupt flag (CCxIF) is set on a compare match or on an input capture event on the corresponding CC channel. For all modes of operation except for capture, the CCxIF will be set when a compare match occurs between the count register (CNT) and the corresponding compare register (CCx). The CCxIF is automatically cleared when the corresponding interrupt vector is executed. For input capture operation, the CCxIF will be set if the corresponding compare buffer contains valid data (i.e., when CCxBV is set). The flag will be cleared when the CCx register is read. Executing the interrupt vector in this mode of operation will not clear the flag. The flag can also be cleared by writing a one to its bit location. The CCxIF can be used for requesting a DMA transfer. A DMA read or write access of the corresponding CCx or CCxBUF will then clear the CCxIF and release the request. z Bit 3:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – ERRIF: Error Interrupt Flag This flag is set on multiple occasions, depending on the mode of operation. In the FRQ or PWM waveform generation mode of operation, ERRIF is set on a fault detect condition from the fault protection feature in the AWeX extention. For timer/counters which do not have the AWeX extention available, this flag is never set in FRQ or PWM waveform generation mode. For capture operation, ERRIF is set if a buffer overflow occurs on any of the CC channels. For event controlled QDEC operation, ERRIF is set when an incorrect index signal is given. This flag is automatically cleared when the corresponding interrupt vector is executed. The flag can also be cleared by writing a one to this location. z Bit 0 – OVFIF: Overflow/Underflow Interrupt Flag This flag is set either on a TOP (overflow) or BOTTOM (underflow) condition, depending on the WGMODE setting. OVFIF is automatically cleared when the corresponding interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. OVFIF can also be used for requesting a DMA transfer. A DMA write access of CNT, PER, or PERBUF will then clear the OVFIF bit. Bit 7 6 5 4 3 2 1 0 +0x0C CCDIF CCCIF CCBIF CCAIF – – ERRIF OVFIF Read/Write R/W R/W R/W R/W R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 168 Atmel-8291C-AVR-XMEGA B -09/2014 13.12.11TEMP – Temporary bits for 16-bit Access The TEMP register is used for single-cycle, 16-bit access to the 16-bit timer/counter registers by the CPU. The DMA controller has a separate temporary storage register. There is one common TEMP register for all the 16-bit Timer/counter registers. For more details, refer to “Accessing 16-bit Registers” on page 13. 13.12.12CNTL – Counter register Low The CNTH and CNTL register pair represents the 16-bit value, CNT. CNT contains the 16-bit counter value in the timer/counter. CPU and DMA write access has priority over count, clear, or reload of the counter. For more details on reading and writing 16-bit registers, refer to “Accessing 16-bit Registers” on page 13. z Bit 7:0 – CNT[7:0]: Counter low byte These bits hold the LSB of the 16-bit counter register. 13.12.13CNTH – Counter register High z Bit 7:0 – CNT[15:8]: Counter high byte These bits hold the MSB of the 16-bit counter register. 13.12.14PERL – Period register Low The PERH and PERL register pair represents the 16-bit value, PER. PER contains the 16-bit TOP value in the timer/counter. z Bit 7:0 – PER[7:0]: Period low byte These bits hold the LSB of the 16-bit period register. Bit 7 6 5 4 3 2 1 0 +0x0F TEMP[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 00000 Bit 7 6 5 4 3 2 1 0 +0x20 CNT[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x21 CNT[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x26 PER[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1 111111 XMEGA B [MANUAL] 169 Atmel-8291C-AVR-XMEGA B -09/2014 13.12.15PERH – Period register High z Bit 7:0 – PER[15:8]: Period high byte These bits hold the MSB of the 16-bit period register. 13.12.16CCxL – Compare or Capture x register Low The CCxH and CCxL register pair represents the 16-bit value, CCx. These 16-bit register pairs have two functions, depending of the mode of operation. For capture operation, these registers constitute the second buffer level and access point for the CPU and DMA. For compare operation, these registers are continuously compared to the counter value. Normally, the outputs form the comparators are then used for generating waveforms. CCx registers are updated with the buffer value from their corresponding CCxBUF register when an UPDATE condition occurs. z Bit 7:0 – CCx[7:0]: Compare or Capture x low byte These bits hold the LSB of the 16-bit compare or capture register. 13.12.17CCxH – Compare or Capture x register High z Bit 7:0 – CCx[15:8]: Compare or Capture x high byte These bits hold the MSB of the 16-bit compare or capture register. Bit 7 6 5 4 3 2 1 0 +0x27 PER[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1 1 1 1 1 1 1 Bit 7 6 5 4 3 2 1 0 CCx[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CCx[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 170 Atmel-8291C-AVR-XMEGA B -09/2014 13.12.18PERBUFL – Timer/Counter Period Buffer Low The PERBUFH and PERBUFL register pair represents the 16-bit value, PERBUF. This 16-bit register serves as the buffer for the period register (PER). Accessing this register using the CPU or DMA will affect the PERBUFV flag. z Bit 7:0 – PERBUF[7:0]: Period Buffer low byte These bits hold the LSB of the 16-bit period buffer register. 13.12.19PERBUFH – Timer/Counter Period Buffer High z Bit 7:0 – PERBUF[15:8]: Period Buffer high byte These bits hold the MSB of the 16-bit period buffer register. 13.12.20CCxBUFL – Compare or Capture x Buffer register Low The CCxBUFH and CCxBUFL register pair represents the 16-bit value, CCxBUF. These 16-bit registers serve as the buffer for the associated compare or capture registers (CCx). Accessing any of these registers using the CPU or DMA will affect the corresponding CCxBV status bit. z Bit 7:0 – CCxBUF[7:0]: Compare or Capture Buffer low byte These bits hold the LSB of the 16-bit compare or capture buffer register. Bit 7 6 5 4 3 2 1 0 +0x36 PERBUF[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1111111 Bit 7 6 5 4 3 2 1 0 +0x37 PERBUF[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1 1 1 1 1 1 1 Bit 7 6 5 4 3 2 1 0 CCxBUFx[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 171 Atmel-8291C-AVR-XMEGA B -09/2014 13.12.21CCxBUFH – Compare or Capture x Buffer register High z Bit 7:0 – CCxBUF[15:8]: Compare or Capture Buffer high byte These bits hold the MSB of the 16-bit compare or capture buffer register. Bit 7 6 5 4 3 2 1 0 CCxBUF[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 172 Atmel-8291C-AVR-XMEGA B -09/2014 13.13 Register Summary 13.14 Interrupt Vector Summary Note: 1. Available only on timer/counters with four compare or capture channels. Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRLA – – – – CLKSEL[3:0] 161 +0x01 CTRLB CCDEN CCCEN CCBEN CCAEN – WGMODE[2:0] 161 +0x02 CTRLC – – – – CMPD CMPC CMPB CMPA 162 +0x03 CTRLD EVACT[2:0] EVDLY EVSEL[3:0] 163 +0x04 CTRLE – – – – – – BYTEM 164 +0x05 Reserved – – – – – – – – +0x06 INTCTRLA – – – – ERRINTLVL[1:0] OVINTLVL[1:0] 164 +0x07 INTCTRLB CCCINTLVL[1:0] CCCINTLVL[1:0] CCBINTLVL[1:0] CCAINTLVL[1:0] 164 +0x08 CTRLFCLR – – – – CMD[1:0] LUPD DIR 165 +0x09 CTRLFSET – – – – CMD[1:0] LUPD DIR 166 +0x0A CTRLGCLR – – – CCDBV CCCBV CCBBV CCABV PERBV 166 +0x0B CTRLGSET – – – CCDBV CCCBV CCBBV CCABV PERBV 166 +0x0C INTFLAGS CCDIF CCCIF CCBIF CCAIF – – ERRIF OVFIF 167 +0x0D Reserved – – – – – – – – +0x0E Reserved – – – – – – – – +0x0F TEMP TEMP[7:0] 168 +0x10 to Reserved – – – – – – – – +0x20 CNTL CNT[7:0] 168 +0x21 CNTH CNT[15:8] 168 +0x22 to Reserved – – – – – – – – +0x26 PERL PER[7:0] 168 +0x27 PERH PER[8:15] 169 +0x28 CCAL CCA[7:0] 169 +0x29 CCAH CCA[15:8] 169 +0x2A CCBL CCB[7:0] 169 +0x2B CCBH CCB[15:8] 169 +0x2C CCCL CCC[7:0] 169 +0x02D CCCH CCC[15:8] 169 +0x2E CCDL CCD[7:0] 169 +0x2F CCDH CCD[15:8] 169 +0x30 to Reserved – – – – – – – – +0x36 PERBUFL PERBUF[7:0] 170 +0x37 PERBUFH PERBUF[15:8] 170 +0x38 CCABUFL CCABUF[7:0] 170 +0x39 CCABUFH CCABUF[15:8] 171 +0x3A CCBBUFL CCBBUF[7:0] 170 +0x3B CCBBUFH CCBBUF[15:8] 171 +0x3C CCCBUFL CCCBUF[7:0] 170 +0x3D CCCBUFH CCCBUF[15:8] 171 +0x3E CCDBUFL CCDBUF[7:0] 170 +0x3F CCDBUFH CCDBUF[15:8] 171 Offset Source Interrupt Description 0x00 OVF_vect Timer/counter overflow/underflow interrupt vector offset 0x02 ERR_vect Timer/counter error interrupt vector offset 0x04 CCA_vect Timer/counter compare or capture channel A interrupt vector offset 0x06 CCB_vect Timer/counter compare or capture channel B interrupt vector offset 0x08 CCC_vect(1) Timer/counter compare or capture channel C interrupt vector offset 0x0A CCD_vect(1) Timer/counter compare or capture channel D interrupt vector offset XMEGA B [MANUAL] 173 Atmel-8291C-AVR-XMEGA B -09/2014 14. TC2 – 16-bit Timer/Counter Type 2 14.1 Features z A system of two eight-bit timer/counters z Low-byte timer/counter z High-byte timer/counter z Eight compare channels z Four compare channels for the low-byte timer/counter z Four compare channels for the high-byte timer/counter z Waveform generation z Single slope pulse width modulation z Timer underflow interrupts/events z One compare match interrupt/event per compare channel for the low-byte timer/counter z Can be used with the event system for count control z Can be used to trigger DMA transactions 14.2 Overview A timer/counter 2 is realized when a timer/counter 0 is set in split mode. It is a system of two eight-bit timer/counters, each with four compare channels. This results in eight configurable pulse width modulation (PWM) channels with individually controlled duty cycles, and is intended for applications that require a high number of PWM channels. The two eight-bit timer/counters in this system are referred to as the low-byte timer/counter and high-byte timer/counter, respectively. The difference between them is that only the low-byte timer/counter can be used to generate compare match interrupts, events and DMA triggers. The two eight-bit timer/counters have a shared clock source and separate period and compare settings. They can be clocked and timed from the peripheral clock, with optional prescaling, or from the event system. The counters are always counting down. The timer/counter 2 is set back to timer/counter 0 by setting it in normal mode; hence, one timer/counter can exist only as either type 0 or type 2. A detailed block diagram of the timer/counter 2 showing the low-byte (L) and high-byte (H) timer/counter register split and compare modules is shown in Figure 14-1 on page 174. XMEGA B [MANUAL] 174 Atmel-8291C-AVR-XMEGA B -09/2014 14.3 Block Diagram Figure 14-1. Block diagram of the 16-bit timer/counter 0 with split mode. 14.4 Clock Sources The timer/counter can be clocked from the peripheral clock (clkPER) and from the event system. Figure 14-2 shows the clock and event selection. Figure 14-2. Clock selection. Base Counter Compare (Unit x = {A,B,C,D}) Counter HPER = 0 Control Logic CTRLA HUNF (INT/DMA Req.) BOTTOML LPER Compare (Unit x = {A,B,C,D}) Waveform Generation LCMPx (INT/DMA Req.) OCLx Out = LCMPx "match" BOTTOMH LCNT "count low" "load low" = HCMPx Waveform Generation "match" OCHx Out = 0 "count high" "load high" HCNT Clock Select LUNF (INT/DMA Req.) clkPER / 2{0,...,15} CLKSEL CNT clkPER / {1,2,4,8,64,256,1024} Common Prescaler clkPER event channels Event System events XMEGA B [MANUAL] 175 Atmel-8291C-AVR-XMEGA B -09/2014 The peripheral clock (clkPER) is fed into the common prescaler (common for all timer/counters in a device). A selection of prescaler outputs from 1 to 1/1024 is directly available. In addition, the whole range of time prescalings from 1 to 215 is available through the event system. The clock selection (CLKSEL) selects one of the clock prescaler outputs or an event channel for the high-byte counter (HCNT) and low-byte counter (LCNT). By using the event system, any event source, such as an external clock signal, on any I/O pin can be used as the clock input. By default, no clock input is selected, and the counters are not running. 14.5 Counter Operation The counters will always count in single-slope mode. Each counter counts down for each clock cycle until it reaches BOTTOM, and then reloads the counter with the period register value at the following clock cycle. Figure 14-3. Counter operation. As shown in Figure 14-3, the counter can change the counter value while running. The write access has higher priority than the count clear, and reloads and will be immediate. 14.5.1 Changing the Period The counter period is changed by writing a new TOP value to the period register. Since the counter is counting down, the period register can be written at any time without affecting the current period, as shown in Figure 14-4 on page 175. This prevents wraparound and generation of odd waveforms. Figure 14-4. Changing the period. 14.6 Compare Channel Each compare channel continuously compares the counter value with the CMPx register. If CNT equals CMPx, the comparator signals a match. For the low-byte timer/counter, the match will set the compare channel's interrupt flag at the next timer clock cycle, and the event and optional interrupt is generated. The high-byte timer/counter does not have compare interrupt/event. CNT BOTTOM MAX "reload" TOP CNT written CNT MAX New TOP written to PER that is higher than current CNT New TOP written to PER that is lower than current CNT "reload" "write" BOTTOM XMEGA B [MANUAL] 176 Atmel-8291C-AVR-XMEGA B -09/2014 14.6.1 Waveform Generation The compare channels can be used for waveform generation on the corresponding port pins. To make the waveform visible on the connected port pin, the following requirements must be fulfilled: 1. The compare channels to be used must be enabled. This will override the corresponding port pin output register. 2. The direction for the associated port pin must be set to output. Inverted waveform output can be achieved by setting invert I/O on the port pin. Refer to “I/O Ports” on page 123 for more details. 14.6.2 Single-slope PWM Generation For PWM generation, the period (T) is controlled by the PER register, while the CMPx registers control the duty cycle of the waveform generator (WG) output. Figure 14-5 on page 176 shows how the counter counts from TOP to BOTTOM, and then restarts from TOP. The WG output is set on the compare match between the CNT and CMPx registers, and cleared at BOTTOM. Figure 14-5. Single-slope pulse width modulation. The PER register defines the PWM resolution. The minimum resolution is two bits (PER=0x0003), and the maximum resolution is eight bits (PER=MAX). The following equation is used to calculate the exact resolution for a single-slope PWM (RPWM_SS) waveform: The single, slow PWM frequency (fPWM_SS) depends on the period setting (PER) and the peripheral clock frequency (fPER), and it is calculated by using the following equation: where N represents the prescaler divider used (1, 2, 4, 8, 64, 256, 1024, or event channel n). 14.6.3 Port Override for Waveform Generation To make the waveform generation available on the port pins, the corresponding port pin direction must be set as output. The timer/counter will override the port pin values when the CMP channel is enabled (LCMPENx/HCMPENx). Figure 14-6 on page 177 shows the port override for the low- and high-byte timer/counters. For the low-byte timer/counter, CMP channels A to D will override the output value (OUTxn) of port pins 0 to 3 on the corresponding port pins (Pxn). For the high-byte timer/counter, CMP channels E to H will override port pins 4 to 7. Enabling inverted I/O on the port pin (INVENxn) inverts the corresponding WG output. CNT MAX TOP Period (T) "match" BOTTOM WG Output CMPx=BOT CMPx CMPx=TOP RPWM_SS log( ) PER 1 + log( ) 2 = --------------------------------- f PWM_SS f PER N( ) PER 1 + = ----------------------------- XMEGA B [MANUAL] 177 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 14-6. Port override for low- and high-byte timer/counters. 14.7 Interrupts and Events The timer/counters can generate interrupts and events. The counter can generate an interrupt on underflow, and each CMP channel for the low-byte counter has a separate compare interrupt. Events will be generated for all conditions that can generate interrupts. For details on event generation and available events, refer to “Event System” on page 63. 14.8 DMA Support Timer/counter underflow and compare interrupt flags can trigger a DMA transaction. The acknowledge condition that clears the flag/request is listed in Table 14-1. Table 14-1. DMA request sources. 14.9 Timer/Counter Commands A set of commands can be given to the timer/counter by software to immediately change the state of the module. These commands give direct control of the update, restart, and reset signals. The software can force a restart of the current waveform period by issuing a restart command. In this case the counter, direction, and all compare outputs are set to zero. A reset command will set all timer/counter registers to their initial values. A reset can only be given when the timer/counter is not running (OFF). OUT LCMPENx / HCMPENx INVEN OCx Waveform Request Acknowledge Comment LUNFIF DMAC writes to LCNT DMAC writes to LPER HUNFIF DMAC writes to HCNT DMAC writes to HPER CCIF{D,C,B,A} DMAC access of LCMP{D,C,B,A} Output compare operation XMEGA B [MANUAL] 178 Atmel-8291C-AVR-XMEGA B -09/2014 14.10 Register Description 14.10.1 CTRLA – Control register A z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:0 – CLKSEL[3:0]: Clock Select These bits select clock source for the timer/counter according to Table 14-2. The clock select is identical for both highand low-byte timer/counters. Table 14-2. Clock select 14.10.2 CTRLB – Control register B z Bit 7:0 – HCMPENx/LCMPENx: High/Low Byte Compare Enable x Setting these bits will enable the compare output and override the port output register for the corresponding OCn output pin. Bit 7 6 5 4 3 2 1 0 +0x00 – – – – CLKSEL[3:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 00000000 CLKSEL[3:0] Group Configuration Description 0000 OFF None (i.e., timer/counter in OFF state) 0001 DIV1 Prescaler: ClkPER 0010 DIV2 Prescaler: ClkPER/2 0011 DIV4 Prescaler: ClkPER/4 0100 DIV8 Prescaler: ClkPER/8 0101 DIV64 Prescaler: ClkPER/64 0110 DIV256 Prescaler: ClkPER/256 0111 DIV1024 Prescaler: ClkPER/1024 1nnn EVCHn Event channel n, n= [0,...,7] Bit 7 6 5 4 3 2 1 0 +0x01 HCMPEND HCMPENC HCMPENB HCMPENA LCMPEND LCMPENC LCMPENB LCMPENA Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 XMEGA B [MANUAL] 179 Atmel-8291C-AVR-XMEGA B -09/2014 14.10.3 CTRLC – Control register C z Bit 7:0 – HCMPx/LCMPx: High/Low Compare x Output Value These bits allow direct access to the waveform generator's output compare value when the timer/counter is OFF. This is used to set or clear the WG output value when the timer/counter is not running. 14.10.4 CTRLE – Control register E z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0:1 – BYTEM[1:0]: Byte Mode These bits select the timer/counter operation mode according to Table 14-3. Table 14-3. Byte mode. Bit 7 6 5 4 3 2 1 0 +0x02 HCMPD HCMPC HCMPB HCMPA LCMPD LCMPC LCMPB LCMPA Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0000 Bit 7 6 5 4 3 2 1 0 +0x04 – – – – – – BYTEM[1:0] Read/Write R R R R R R R/W R/W Initial Value 00000000 BYTEM[1:0] Group Configuration Description 00 NORMAL Timer/counter is set to normal mode (timer/counter type 0) 01 BYTEMODE Upper byte of the counter (HCNT) will be set to zero after each counter clock. 10 SPLITMODE Timer/counter is split into two eight-bit timer/counters (timer/counter type 2) 11 — Reserved XMEGA B [MANUAL] 180 Atmel-8291C-AVR-XMEGA B -09/2014 14.10.5 INTCTRLA – Interrupt Enable register A z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:2 – HUNFINTLVL[1:0]: High-byte Timer Underflow Interrupt Level These bits enable the high-byte timer underflow interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will be triggered when HUNFIF in the INTFLAGS register is set. z Bit 1:0 – LUNFINTLVL[1:0]: Low-byte Timer Underflow Interrupt Level These bits enable the low-byte timer underflow interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will be triggered when LUNFIF in the INTFLAGS register is set. 14.10.6 INTCTRLB – Interrupt Enable register B z Bit 7:0 – LCMPxINTLVL[1:0]: Low-byte Compare x Interrupt Level These bits enable the low-byte timer compare interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will be triggered when LCMPxIF in the INTFLAGS register is set. 14.10.7 CTRLF – Control register F z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:2 – CMD[1:0]: Timer/Counter Command These command bits are used for software control of timer/counter update, restart, and reset. The command bits are always read as zero. The CMD bits must be used together with CMDEN. Bit 7 6 5 4 3 2 1 0 +0x06 – – – – HUNFINTLVL[1:0] LUNFINTLVL[1:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0000 Bit 7 6 5 4 3 2 1 0 +0x07 LCMPDINTLVL[1:0] LCMPCINTLVL[1:0] LCMPBINTLVL[1:0] LCMPAINTLVL[1:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0000000 Bit 7 6 5 4 3 2 1 0 +0x08 – – – – CMD[1:0] CMDEN[1:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 00000 XMEGA B [MANUAL] 181 Atmel-8291C-AVR-XMEGA B -09/2014 Table 14-4. Command selections. z Bit 1:0 – CMDEN[1:0]: Command Enable These bits are used to indicate for which timer/counter the command (CMD) is valid. Table 14-5. Command enable selections. 14.10.8 INTFLAGS – Interrupt Flag register z Bit 7:4 – LCMPxIF: Compare Channel x Interrupt Flag The compare interrupt flag (LCMPxIF) is set on a compare match on the corresponding CMP channel. For all modes of operation, LCMPxIF will be set when a compare match occurs between the count register (LCNT) and the corresponding compare register (LCMPx). The LCMPxIF is automatically cleared when the corresponding interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. z Bit 3:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – HUNFIF: High-byte Timer Underflow Interrupt Flag HUNFIF is set on a BOTTOM (underflow) condition. This flag is automatically cleared when the corresponding interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. z Bit 0 – LUNFIF: Low-byte Timer Underflow Interrupt Flag LUNFIF is set on a BOTTOM (underflow) condition. This flag is automatically cleared when the corresponding interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. CMD Group Configuration Description 00 NONE None 01 — Reserved 10 RESTART Force restart 11 RESET Force hard reset (ignored if T/C is not in OFF state) CMDEN Group Configuration Description 00 – Reserved 01 LOW Command valid for low-byte T/C 10 HIGH Command valid for high-byte T/C 11 BOTH Command valid for both low-byte and high-byte T/C Bit 7 6 5 4 3 2 1 0 +0x0C LCMPDIF LCMPCIF LCMPBIF LCMPAIF – – HUNFIF LUNFIF Read/Write R/W R/W R/W R/W R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 182 Atmel-8291C-AVR-XMEGA B -09/2014 14.10.9 LCNT – Low-byte Count register z Bit 7:0 – LCNT[7:0] LCNT contains the eight-bit counter value for the low-byte timer/counter. The CPU and DMA write accesses have priority over count, clear, or reload of the counter. 14.10.10HCNT – High-byte Count register z Bit 7:0 – HCNT[7:0] HCNT contains the eight-bit counter value for the high-byte timer/counter. The CPU and DMA write accesses have priority over count, clear, or reload of the counter. 14.10.11LPER – Low-byte Period register z Bit 7:0 – LPER[7:0] LPER contains the eight-bit period value for the low-byte timer/counter. 14.10.12HPER – High-byte Period register z Bit 7:0 – HPER[7:0] HPER contains the eight-bit period for the high-byte timer/counter. Bit 7 6 5 4 3 2 1 0 +0x20 LCNT[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x21 HCNT[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x27 LPER[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x26 HPER[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 XMEGA B [MANUAL] 183 Atmel-8291C-AVR-XMEGA B -09/2014 14.10.13LCMPx – Low-byte Compare register x z Bit 7:0 – LCMPx[7:0], x=[A, B, C, D] LCMPx contains the eight-bit compare value for the low-byte timer/counter. These registers are all continuously compared to the counter value. Normally, the outputs from the comparators are then used for generating waveforms. 14.10.14HCMPx – High-byte Compare register x z Bit 7:0 – HCMPx[7:0], x=[A, B, C, D] HCMPx contains the eight-bit compare value for the high-byte timer/counter. These registers are all continuously compared to the counter value. Normally the outputs from the comparators are then used for generating waveforms. Bit 7 6 5 4 3 2 1 0 LCMPx[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 HCMPx[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 184 Atmel-8291C-AVR-XMEGA B -09/2014 14.11 Register Summary 14.12 Interrupt Vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRLA – – – – CLKSEL[3:0] 178 +0x01 CTRLB HCMPDEN HCMPCEN HCMPBEN HCMPAEN LCMPDEN LCMPCEN LCMPBEN LCMPAEN 178 +0x02 CTRLC HCMPD HCMPC HCMPB HCMPA LCMPD LCMPC LCMPB LCMPA 179 +0x03 Reserved – – – – – – – – +0x04 CTRLE – – – – – – BYTEM[1:0] 179 +0x05 Reserved – – – – – – – – +0x06 INTCTRLA – – – – HUNFINTLVL[1:0] LUNFINTLVL[1:0] 180 +0x07 INTCTRLB LCMPDINTLVL[1:0] LCMPCINTLVL[1:0] LCMPBINTLVL[1:0] LCMPAINTLVL[1:0] 180 +0x08 Reserved – – – – – – – – +0x09 CTRLF – – – – CMD[1:0] CMDEN[1:0] 180 +0x0A Reserved – – – – – – – – +0x0B Reserved – – – – – – – – +0x0C INTFLAGS LCMPDIF LCMPCIF LCMPBIF LCMPAIF – – HUNFIF LUNFIF 181 +0x0D Reserved – – – – – – – – +0x0E Reserved – – – – – – – – +0x0F Reserved – – – – – – – – +0x10 to Reserved – – – – – – – – +0x20 LCNT Low-byte Timer/Counter Count Register 182 +0x21 HCNT High-byte Timer/Counter Count Register 182 +0x22 to Reserved – – – – – – – – +0x26 LPER Low-byte Timer/Counter Period Register 182 +0x27 HPER High-byte Timer/Counter Period Register 183 +0x28 LCMPA Low-byte Compare Register A 183 +0x29 HCMPA High-byte Compare Register A 183 +0x2A LCMPB Low-byte Compare Register B 183 +0x2B HCMPB High-byte Compare Register B 183 +0x2C LCMPC Low-byte Compare Register C 183 +0x02D HCMPC High-byte Compare Register C 183 +0x2E LCMPD Low-byte Compare Register D 183 +0x2F HCMPD High-byte Compare Register D 183 +0x30 to Reserved – – – – – – – – Offset Source Interrupt Description 0x00 LUNF_vect Low-byte Timer/counter underflow interrupt vector offset 0x02 HUNF_vect High-byte Timer/counter underflow interrupt vector offset 0x4 LCMPA_vect Low-byte Timer/counter compare channel A interrupt vector offset 0x6 LCMPB_vect Low-byte Timer/counter compare channel B interrupt vector offset 0x8 LCMPC_vect Low-byte Timer/counter compare channel C interrupt vector offset 0x0A LCMPD_vect Low-byte Timer/counter compare channel D interrupt vector offset XMEGA B [MANUAL] 185 Atmel-8291C-AVR-XMEGA B -09/2014 15. AWeX – Advanced Waveform Extension 15.1 Features z Waveform output with complementary output from each compare channel z Four dead-time insertion (DTI) units z 8-bit resolution z Separate high and low side dead-time setting z Double buffered dead time z Optionally halts timer during dead-time insertion z Pattern generation unit creating synchronised bit pattern across the port pins z Double buffered pattern generation z Optional distribution of one compare channel output across the port pins z Event controlled fault protection for instant and predictable fault triggering 15.2 Overview The advanced waveform extension (AWeX) provides extra functions to the timer/counter in waveform generation (WG) modes. It is primarily intended for use with different types of motor control and other power control applications. It enables low- and high side output with dead-time insertion and fault protection for disabling and shutting down external drivers. It can also generate a synchronized bit pattern across the port pins. Figure 15-1. Advanced waveform extention and closely related peripherals (grey). As shown in Figure 15-1 on page 185, each of the waveform generator outputs from timer/counter 0 are split into a complimentary pair of outputs when any AWeX features are enabled. These output pairs go through a dead-time insertion (DTI) unit that generates the non-inverted low side (LS) and inverted high side (HS) of the WG output with deadtime insertion between LS and HS switching. The DTI output will override the normal port value according to the port Timer/Counter 0 AWeX WG Channel A DTI Channel A WG Channel B DTI Channel B WG Channel C DTI Channel C WG Channel D DTI Channel D Port Override Pattern Generation Px0 Px1 Px2 Px3 Px4 Px5 Px6 Px7 Event System Fault Protection XMEGA B [MANUAL] 186 Atmel-8291C-AVR-XMEGA B -09/2014 override setting. Refer to “I/O Ports” on page 123 for more details. The pattern generation unit can be used to generate a synchronized bit pattern on the port it is connected to. In addition, the WG output from compare channel A can be distributed to and override all the port pins. When the pattern generator unit is enabled, the DTI unit is bypassed. The fault protection unit is connected to the event system, enabling any event to trigger a fault condition that will disable the AWeX output. The event system ensures predictable and instant fault reaction, and gives flexibility in the selection of fault triggers. 15.3 Port Override The port override logic is common for all the timer/counter extensions. Figure 15-2 on page 187 shows a schematic diagram of the port override logic. When the dead-time enable (DTIENx) bit is set, the timer/counter extension takes control over the pin pair for the corresponding channel. Given this condition, the output override enable (OOE) bits take control over the CCxEN bits. XMEGA B [MANUAL] 187 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 15-2. Timer/counter extensions and port override logic. 15.4 Dead-time Insertion The dead-time insertion (DTI) unit generates OFF time where the non-inverted low side (LS) and inverted high side (HS) of the WG output are both low. This OFF time is called dead time, and dead-time insertion ensures that the LS and HS never switch simultaneously. The DTI unit consists of four equal dead-time generators, one for each compare channel in timer/counter 0. Figure 15-3 on page 188 shows the block diagram of one DTI generator. The four channels have a common register that controls the OUT0 OUTOVEN0 CCAEN DTICCAEN INVEN0 OUT1 OUTOVEN1 CCBEN INVEN1 Px0 Px1 Channel A DTI LS HS OC0A OC0B OCALS OCAHS WG 0A WG 0B WG 0A CWCM OUT2 OUTOVEN2 CCCEN DTICCBEN INVEN2 OUT3 OUTOVEN3 CCDEN INVEN3 Px2 Px3 Channel B DTI LS HS OC0C OC0D OCBLS OCBHS WG 0C WG 0D OUT4 OUTOVEN4 CCAEN DTICCCEN INVEN4 OUT5 OUTOVEN5 CCBEN INVEN5 Px4 Px5 Channel C DTI LS HS OC1A OC1B OCCLS OCCHS WG 1A WG 1B OUT6 OUTOVEN6 DTICCDEN INVEN6 OUT7 OUTOVEN7 INVEN7 Px6 Px7 Channel D DTI LS HS OCDLS OCDHS WG 0B WG 0D WG 0C "0" "0" XMEGA B [MANUAL] 188 Atmel-8291C-AVR-XMEGA B -09/2014 dead time. The high side and low side have independent dead-time setting, and the dead-time registers are double buffered. Figure 15-3. Dead-time generator block diagram. As shown in Figure 15-4 on page 188, the 8-bit dead-time counter is decremented by one for each peripheral clock cycle, until it reaches zero. A nonzero counter value will force both the low side and high side outputs into their OFF state. When a change is detected on the WG output, the dead-time counter is reloaded according to the edge of the input. A positive edge initiates a counter reload of the DTLS register, and a negative edge a reload of DTHS register. Figure 15-4. Dead-time generator timing diagram. 15.5 Pattern Generation The pattern generator unit reuses the DTI registers to produce a synchronized bit pattern across the port it is connected to. In addition, the waveform generator output from compare channel A (CCA) can be distributed to and override all the port pins. These features are primarily intended for handling the commutation sequence in brushless DC motor (BLDC) and stepper motor applications. A block diagram of the pattern generator is shown in “Pattern generator block diagram.” on page 189. For each port pin where the corresponding OOE bit is set, the multiplexer will output the waveform from CCA. Dead Time Generator Edge Detect BV BV D Q = 0 DTLSBUF DTLS DTHSBUF DTHS "DTLS" (To PORT) "DTHS" (To PORT) Counter EN LOAD WG output "dti_cnt" "WG output" "DTLS" "DTHS" tDTILS tDTIHS T tP XMEGA B [MANUAL] 189 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 15-5. Pattern generator block diagram. As with the other timer/counter double buffered registers, the register update is synchronized to the UPDATE condition set by the waveform generation mode. If the synchronization provided is not required by the application, the application code can simply access the DTIOE and PORTx registers directly. The pin directions must be set for any output from the pattern generator to be visible on the port. 15.6 Fault Protection The fault protection feature enables fast and deterministic action when a fault is detected. The fault protection is event controlled. Thus, any event from the event system can be used to trigger a fault action, such as over-current indication from analog comparator or ADC measurements. When fault protection is enabled, an incoming event from any of the selected event channels can trigger the event action. Each event channel can be separately enabled as a fault protection input, and the specified event channels will be ORed together, allowing multiple event sources to be used for fault protection at the same time. 15.6.1 Fault Actions When a fault is detected, the direction clear action will clear the direction (DIR) register in the associated port, setting all port pins as tri-stated inputs. The fault detection flag is set, the timer/counter’s error interrupt flag is set, and the optional interrupt is generated. There is maximum of two peripheral clock cycles from when an event occurs in a peripheral until the fault protection triggers the event action. Fault protection is fully independent of the CPU and DMA, but requires the peripheral clock to run. 15.6.2 Fault Restore Modes How the AWeX and timer/counter return from the fault state to normal operation after a fault, when the fault condition is no longer active, can be selected from one of two different modes: z In latched mode, the waveform output will remain in the fault state until the fault condition is no longer active and the fault detect flag has been cleared by software. When both of these conditions are met, the waveform output will return to normal operation at the next UPDATE condition. z In cycle-by-cycle mode the waveform output will remain in the fault state until the fault condition is no longer active. When this condition is met, the waveform output will return to normal operation at the next UPDATE condition. Timer/Counter 0 (TCx0) BV DTLSBUF BV OUTOVEN DTHSBUF OUTx UPDATE CCA WG output EN EN 1 to 8 Expand Px[7:0] XMEGA B [MANUAL] 190 Atmel-8291C-AVR-XMEGA B -09/2014 When returning from a fault state the DIR[7:0] bits corresponding to the enabled DTI channels are restored. OUTOVEN is unaffected by the fault except that writing to the register from software is blocked. The UPDATE condition used to restore normal operation is the same as the one in the timer/counter. 15.6.3 Change Protection To avoid unintentional changes in the fault protection setup, all the control registers in the AWeX extension can be protected by writing the corresponding lock bit in the advanced waveform extension lock register. For more details, refer to “I/O Memory Protection” on page 25 and “AWEXLOCK – Advanced Waveform Extension Lock register” on page 44. When the lock bit is set, control register A, the output override enable register, and the fault detection event mask register cannot be changed. To avoid unintentional changes in the fault event setup, it is possible to lock the event system channel configuration by writing the corresponding event system lock register. For more details, refer to “I/O Memory Protection” on page 25 and “EVSYSLOCK – Event System Lock register” on page 43. 15.6.4 On-Chip Debug When fault detection is enabled, an on-chip debug (OCD) system receives a break request from the debugger, which will by default function as a fault source. When an OCD break request is received, the AWeX and corresponding timer/counter will enter a fault state, and the specified fault action will be performed. After the OCD exits from the break condition, normal operation will be started again. In cycle-by-cycle mode, the waveform output will start on the first UPDATE condition after exit from break, while in latched mode, the fault condition flag must be cleared in software before the output will be restored. This feature guarantees that the output waveform enters a safe state during a break. It is possible to disable this feature. XMEGA B [MANUAL] 191 Atmel-8291C-AVR-XMEGA B -09/2014 15.7 Register Description 15.7.1 CTRL – Control register z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5 – PGM: Pattern Generation Mode Setting this bit enables the pattern generation mode. This will override the DTI, and the pattern generation reuses the dead-time registers for storing the pattern. z Bit 4 – CWCM: Common Waveform Channel Mode If this bit is set, the CC channel A waveform output will be used as input for all the dead-time generators. CC channel B, C, and D waveforms will be ignored. z Bit 3:0 – DTICCxEN: Dead-Time Insertion CCx Enable Setting these bits enables the dead-time generator for the corresponding CC channel. This will override the timer/counter waveform outputs. 15.7.2 FDEMASK – Fault Detect Event Mask register z Bit 7:0 – FDEVMASK[7:0]: Fault Detect Event Mask These bits enable the corresponding event channel as a fault condition input source. Events from all event channels will be ORed together, allowing multiple sources to be used for fault detection at the same time. When a fault is detected, the fault detect flag (FDF) is set and the fault detect action (FDACT) will be performed. Bit 7 6 5 4 3 2 1 0 +0x00 – – PGM CWCM DTICCDEN DTICCCEN DTICCBEN DTICCAEN Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x02 FDEVMASK[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 XMEGA B [MANUAL] 192 Atmel-8291C-AVR-XMEGA B -09/2014 15.7.3 FDCTRL - Fault Detection Control register z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4 – FDDBD: Fault Detection on Debug Break Detection By default, when this bit is cleared and fault protection is enabled, and OCD break request is treated as a fault. When this bit is set, an OCD break request will not trigger a fault condition. z Bit 3 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 2 – FDMODE: Fault Detection Restart Mode This bit sets the fault protection restart mode. When this bit is cleared, latched mode is used, and when it is set, cycle-bycycle mode is used. In latched mode, the waveform output will remain in the fault state until the fault condition is no longer active and the FDF has been cleared by software. When both conditions are met, the waveform output will return to normal operation at the next UPDATE condition. In cycle-by-cycle mode, the waveform output will remain in the fault state until the fault condition is no longer active. When this condition is met, the waveform output will return to normal operation at the next UPDATE condition. z Bit 1:0 – FDACT[1:0]: Fault Detection Action These bits define the action performed, according to Table 15-1, when a fault condition is detected. Table 15-1. Fault action. Bit 7 6 5 4 3 2 1 0 +0x03 – – – FDDBD – FDMODE FDACT[1:0] Read/Write R R R R/W R R/W R/W R/W Initial Value 00000000 FDACT[1:0] Group Configuration Description 00 NONE None (fault protection disabled) 01 – Reserved 10 – Reserved 11 CLEARDIR Clear all direction (DIR) bits which correspond to the enabled DTI channel(s); i.e., tri-state the outputs XMEGA B [MANUAL] 193 Atmel-8291C-AVR-XMEGA B -09/2014 15.7.4 STATUS – Status register z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2 – FDF: Fault Detect Flag This flag is set when a fault detect condition is detected; i.e., when an event is detected on one of the event channels enabled by FDEVMASK. This flag is cleared by writing a one to its bit location. z Bit 1 – DTHSBUFV: Dead-time High Side Buffer Valid If this bit is set, the corresponding DT buffer is written and contains valid data that will be copied into the DTLS register on the next UPDATE condition. If this bit is zero, no action will be taken. The connected timer/counter unit’s lock update (LUPD) flag also affects the update for dead-time buffers. z Bit 0 – DTLSBUFV: Dead-time Low Side Buffer Valid If this bit is set, the corresponding DT buffer is written and contains valid data that will be copied into the DTHS register on the next UPDATE condition. If this bit is zero, no action will be taken. The connected timer/counter unit's lock update (LUPD) flag also affects the update for dead-time buffers. 15.7.5 DTBOTH – Dead-time Concurrent Write to Both Sides z Bit 7:0 – DTBOTH: Dead-time Both Sides Writing to this register will update the DTHS and DTLS registers at the same time (i.e., at the same I/O write access). 15.7.6 DTBOTHBUF – Dead-time Concurrent Write to Both Sides Buffer register z Bit 7:0 – DTBOTHBUF: Dead-time Both Sides Buffer Writing to this memory location will update the DTHSBUF and DTLSBUF registers at the same time (i.e., at the same I/O write access). Bit 7 6 5 4 3 2 1 0 +0x04 – – – – – FDF DTHSBUFV DTLSBUFV Read/Write R R R R R R/W R/W R/W Initial Value 00000 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x06 DTBOTH[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x07 DTBOTHBUF[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 194 Atmel-8291C-AVR-XMEGA B -09/2014 15.7.7 DTLS – Dead-time Low Side register z Bit 7:0 – DTLS: Dead-time Low Side This register holds the number of peripheral clock cycles for the dead-time low side. 15.7.8 DTHS – Dead-time High Side register z Bit 7:0 – DTHS: Dead-time High Side This register holds the number of peripheral clock cycles for the dead-time high side. 15.7.9 DTLSBUF – Dead-time Low Side Buffer register z Bit 7:0 – DTLSBUF: Dead-time Low Side Buffer This register is the buffer for the DTLS register. If double buffering is used, valid content in this register is copied to the DTLS register on an UPDATE condition. 15.7.10 DTHSBUF – Dead-time High Side Buffer register z Bit 7:0 – DTHSBUF: Dead-time High Side Buffer This register is the buffer for the DTHS register. If double buffering is used, valid content in this register is copied to the DTHS register on an UPDATE condition. Bit 7 6 5 4 3 2 1 0 +0x08 DTLS[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x09 DTHS[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0A DTLSBUF[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x0B DTHSBUF[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 195 Atmel-8291C-AVR-XMEGA B -09/2014 15.7.11 OUTOVEN – Output Override Enable register Note: 1. Can be written only if the fault detect flag (FDF) is zero. z Bit 7:0 – OUTOVEN[7:0]: Output Override Enable These bits enable override of the corresponding port output register (i.e., one-to-one bit relation to pin position). The port direction is not overridden. 15.8 Register Summary Bit 7 6 5 4 3 2 1 0 +0x0C OUTOVEN[7:0] Read/Write R/W(1) R/W(1) R/W(1) R/W(1) R/W(1) R/W(1) R/W(1) R/W(1) Initial Value 0 0 0 0 0 0 0 0 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Pag +0x00 CTRL – – PGM CWCM DTICDAE DTICCCE DTICCBEN DTICCAEN 191 +0x01 Reserved – – – – – – – – +0x02 FDEMASK FDEVMASK[7:0] 191 +0x03 FDCTRL – – – FDDBD – FDMODE FDACT[1:0] 192 +0x04 STATUS – – – – – FDF DTBHSV DTBLSV 193 +0x05 Reserved – – – – – – – – +0x06 DTBOTH DTBOTH[7:0] 193 +0x07 DTBOTHBUF DTBOTHBUF[7:0] 193 +0x08 DTLS DTLS[7:0] 194 +0x09 DTHS DTHS[7:0] 194 +0x0A DTLSBUF DTLSBUF[7:0] 194 +0x0B DTHSBUF DTHSBUF[7:0] 194 +0x0C OUTOVEN OUTOVEN[7:0] 195 XMEGA B [MANUAL] 196 Atmel-8291C-AVR-XMEGA B -09/2014 16. Hi-Res – High-Resolution Extension 16.1 Features z Increases waveform generator resolution up to 8x (3 bits) z Supports frequency, single-slope PWM, and dual-slope PWM generation z Supports the AWeX when this is used for the same timer/counter 16.2 Overview The high-resolution (hi-res) extension can be used to increase the resolution of the waveform generation output from a timer/counter by four or eight. It can be used for a timer/counter doing frequency, single-slope PWM, or dual-slope PWM generation. It can also be used with the AWeX if this is used for the same timer/counter. The hi-res extension uses the peripheral 4x clock (ClkPER4). The system clock prescalers must be configured so the peripheral 4x clock frequency is four times higher than the peripheral and CPU clock frequency when the hi-res extension is enabled. Refer to “System Clock Selection and Prescalers” on page 79 for more details. Figure 16-1. Timer/counter operation with hi-res extension enabled. When the hi-res extension is enabled, the timer/counter must run from a non-prescaled peripheral clock. The timer/counter will ignore its two least-significant bits (lsb) in the counter, and counts by four for each peripheral clock cycle. Overflow/underflow and compare match of the 14 most-significant bits (msb) is done in the timer/counter. Count and compare of the two lsb is handled and compared in the hi-res extension running from the peripheral 4x clock. The two lsb of the timer/counter period register must be set to zero to ensure correct operation. If the count register is read from the application code, the two lsb will always be read as zero, since the timer/counter run from the peripheral clock. The two lsb are also ignored when generating events. When the hi-res plus feature is enabled, the function is the same as with the hi-res extension, but the resolution will increase by eight instead of four. This also means that the 3 lsb are handled by the hi-res extension instead of 2 lsb, as when only hi-res is enabled. The extra resolution is achieved by counting on both edges of the peripheral 4x clock. The hi-res extension will not output any pulse shorter than one peripheral clock cycle; i.e., a compare value lower than four will have no visible output. CNT[15:2] HiRes CCxBUF[15:0] = 0 = " match" = PER[15:2] 0 Waveform Generation BOTTOM TOP Time /Counter CCx[15:2] [1:0] 2 2 2 0 AWeX Fault Protection Dead - Time Insertion Pattern Generation clkPER clkPER4 Pxn XMEGA B [MANUAL] 197 Atmel-8291C-AVR-XMEGA B -09/2014 16.3 Register Description 16.3.1 CTRLA – Control register A z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2 – HRPLUS: High Resolution Plus Setting this bit enables high resolution plus. Hi-res plus is the same as hi-res, but will increase the resolution by eight (3 bits) instead of four. The extra resolution is achieved by operating at both edges of the peripheral 4x clock. z Bit 1:0 – HREN[1:0]: High Resolution Enable These bits enables the high-resolution mode for a timer/counter according to Table 16-1. Setting one or both HREN bits will enable high-resolution waveform generation output for the entire general purpose I/O port. This means that both timer/counters connected to the same port must enable hi-res if both are used for generating PWM or FRQ output on pins. Table 16-1. High resolution enable. 16.4 Register Summary Bit 7 6 5 4 3 2 1 0 +0x00 – – – – – HRPLUS HREN[1:0] Read/Write R R R R R R/W R/W R/W Initial Value 00000000 HREN[1:0] High Resolution Enabled 00 None 01 Timer/counter 0 10 Timer/counter 1 11 Both timer/counters Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRLA – – – – – HRPLUS HREN[1:0] 197 XMEGA B [MANUAL] 198 Atmel-8291C-AVR-XMEGA B -09/2014 17. RTC – Real-Time Counter 17.1 Features z 16-bit resolution z Selectable clock source z 32.768kHz external crystal z External clock z 32.768kHz internal oscillator z 32kHz internal ULP oscillator z Programmable 10-bit clock prescaling z One compare register z One period register z Clear counter on period overflow z Optional interrupt/event on overflow and compare match 17.2 Overview The 16-bit real-time counter (RTC) is a counter that typically runs continuously, including in low-power sleep modes, to keep track of time. It can wake up the device from sleep modes and/or interrupt the device at regular intervals. The reference clock is typically the 1.024kHz output from a high-accuracy crystal of 32.768kHz, and this is the configuration most optimized for low power consumption. The faster 32.768kHz output can be selected if the RTC needs a resolution higher than 1ms. The RTC can also be clocked from an external clock signal, the 32.768kHz internal oscillator or the 32kHz internal ULP oscillator. The RTC includes a 10-bit programmable prescaler that can scale down the reference clock before it reaches the counter. A wide range of resolutions and time-out periods can be configured. With a 32.768kHz clock source, the maximum resolution is 30.5μs, and time-out periods can range up to 2000 seconds. With a resolution of 1s, the maximum timeout period is more than18 hours (65536 seconds). The RTC can give a compare interrupt and/or event when the counter equals the compare register value, and an overflow interrupt and/or event when it equals the period register value. Figure 17-1. Real-time counter overview. 32.768kHz Crystal Osc 32.768kHz Int. Osc TOSC1 TOSC2 External Clock DIV32 DIV32 32kHz int ULP (DIV32) RTCSRC 10-bit prescaler clkRTC CNT PER COMP = = ”match”/ Compare TOP/ Overflow XMEGA B [MANUAL] 199 Atmel-8291C-AVR-XMEGA B -09/2014 17.2.1 Clock Domains The RTC is asynchronous, operating from a different clock source independently of the main system clock and its derivative clocks, such as the peripheral clock. For control and count register updates, it will take a number of RTC clock and/or peripheral clock cycles before an updated register value is available in a register or until a configuration change has effect on the RTC. This synchronization time is described for each register. Refer to “RTCCTRL – RTC Control register” on page 85 for selecting the asynchronous clock source for the RTC. 17.2.2 Interrupts and Events The RTC can generate both interrupts and events. The RTC will give a compare interrupt and/or event at the first count after the counter value equals the Compare register value. The RTC will give an overflow interrupt request and/or event at the first count after the counter value equals the Period register value. The overflow will also reset the counter value to zero. Due to the asynchronous clock domain, events will be generated only for every third overflow or compare match if the period register is zero. If the period register is one, events will be generated only for every second overflow or compare match. When the period register is equal to or above two, events will trigger at every overflow or compare match, just as the interrupt request. XMEGA B [MANUAL] 200 Atmel-8291C-AVR-XMEGA B -09/2014 17.3 Register Descriptions 17.3.1 CTRL – Control register z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2:0 – PRESCALER[2:0]: Clock Prescaling factor These bits define the prescaling factor for the RTC clock according to Table 17-1. Table 17-1. Real-time counter clock prescaling factor. 17.3.2 STATUS – Status register z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – SYNCBUSY: Synchronization Busy Flag This flag is set when the CNT, CTRL, PER, or COMP register is busy synchronizing between the RTC clock and system clock domains. THis flag is automatically cleared when the synchronisation is complete Bit 7 6 5 4 3 2 1 0 +0x00 – – – – – PRESCALER[2:0] Read/Write R R R R R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 PRESCALER[2:0] Group Configuration RTC Clock Prescaling 000 OFF No clock source, RTC stopped 001 DIV1 RTC clock / 1 (no prescaling) 010 DIV2 RTC clock / 2 011 DIV8 RTC clock / 8 100 DIV16 RTC clock / 16 101 DIV64 RTC clock / 64 110 DIV256 RTC clock / 256 111 DIV1024 RTC clock / 1024 Bit 7 6 5 4 3 2 1 0 +0x01 – – – – – – – SYNCBUSY Read/Write RRRRRRR R Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 201 Atmel-8291C-AVR-XMEGA B -09/2014 17.3.3 INTCTRL – Interrupt Control register z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:2 – COMPINTLVL[1:0]: Compare Match Interrupt Enable These bits enable the RTC compare match interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will trigger when COMPIF in the INTFLAGS register is set. z Bit 1:0 – OVFINTLVL[1:0]: Overflow Interrupt Enable These bits enable the RTC overflow interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will trigger when OVFIF in the INTFLAGS register is set. 17.3.4 INTFLAGS – Interrupt Flag register z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – COMPIF: Compare Match Interrupt Flag This flag is set on the next count after a compare match condition occurs. It is cleared automatically when the RTC compare match interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. z Bit 0 – OVFIF: Overflow Interrupt Flag This flag is set on the next count after an overflow condition occurs. It is cleared automatically when the RTC overflow interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. Bit 7 6 5 4 3 2 1 0 +0x02 – – – – COMPINTLVL[1:0] OVFINTLVL[1:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0000000 Bit 7 6 5 4 3 2 1 0 +0x03 – – – – – – COMPIF OVFIF Read/Write R R R R R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 202 Atmel-8291C-AVR-XMEGA B -09/2014 17.3.5 TEMP – Temporary register z Bit 7:0 – TEMP[7:0]: Temporary bits This register is used for 16-bit access to the counter value, compare value, and TOP value registers. The low byte of the 16-bit register is stored here when it is written by the CPU. The high byte of the 16-bit register is stored when the low byte is read by the CPU. For more details, refer to “Accessing 16-bit Registers” on page 13. 17.3.6 CNTL – Counter register Low The CNTH and CNTL register pair represents the 16-bit value, CNT. CNT counts positive clock edges on the prescaled RTC clock. Reading and writing 16-bit values requires special attention. Refer to “Accessing 16-bit Registers” on page 13 for details. Due to synchronization between the RTC clock and system clock domains, there is a latency of two RTC clock cycles from updating the register until this has an effect. Application software needs to check that the SYNCBUSY flag in the “STATUS – Status register” on page 200 is cleared before writing to this register. z Bit 7:0 – CNT[7:0]: Counter Value low byte These bits hold the LSB of the 16-bit real-time counter value. 17.3.7 CNTH – Counter Register High z Bit 7:0 – CNT[15:8]: Counter Value high byte These bits hold the MSB of the 16-bit real-time counter value. Bit 7 6 5 4 3 2 1 0 +0x04 TEMP[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x08 CNT[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 Bit 7 6 5 4 3 2 1 0 +0x09 CNT[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 203 Atmel-8291C-AVR-XMEGA B -09/2014 17.3.8 PERL – Period register Low The PERH and PERL register pair represents the 16-bit value, PER. PER is constantly compared with the counter value (CNT). A match will set OVFIF in the INTFLAGS register and clear CNT. Reading and writing 16-bit values requires special attention. Refer to “Accessing 16-bit Registers” on page 13 for details. Due to synchronization between the RTC clock and system clock domains, there is a latency of two RTC clock cycles from updating the register until this has an effect. Application software needs to check that the SYNCBUSY flag in the “STATUS – Status register” on page 200 is cleared before writing to this register. z Bit 7:0 – PER[7:0]: Period low byte These bits hold the LSB of the 16-bit RTC TOP value. 17.3.9 PERH – Period register High z Bits 7:0 – PER[15:8]: Period high byte These bits hold the MSB of the 16-bit RTC TOP value. 17.3.10 COMPL – Compare register Low The COMPH and COMPL register pair represent the 16-bit value, COMP. COMP is constantly compared with the counter value (CNT). A compare match will set COMPIF in the INTFLAGS register. Reading and writing 16-bit values requires special attention. Refer “Accessing 16-bit Registers” on page 13 for details. Due to synchronization between the RTC clock and system clock domains, there is a latency of two RTC clock cycles from updating the register until this has an effect. Application software needs to check that the SYNCBUSY flag in the “STATUS – Status register” on page 200 is cleared before writing to this register. If the COMP value is higher than the PER value, no RTC compare match interrupt requests or events will ever be generated. z Bit 7:0 – COMP[7:0]: Compare value low byte These bits hold the LSB of the 16-bit RTC compare value. Bit 7 6 5 4 3 2 1 0 +0x0A PER[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1 111111 Bit 7 6 5 4 3 2 1 0 +0x0B PER[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 1 1111111 Bit 7 6 5 4 3 2 1 0 +0x0C COMP[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 204 Atmel-8291C-AVR-XMEGA B -09/2014 17.3.11 COMPH – Compare register High z Bit 7:0 – COMP[15:8]: Compare value high byte These bits hold the MSB of the 16-bit RTC compare value. Bit 76543210 +0x0D COMP[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 205 Atmel-8291C-AVR-XMEGA B -09/2014 17.4 Register Summary 17.5 Interrupt Vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL – – – – – PRESCALER[2:0] 200 +0x01 STATUS – – – – – – – SYNCBUSY 200 +0x02 INTCTRL – – – – COMPINTLVL[1:0] OVFINTLVL[1:0] 201 +0x03 INTFLAGS – – – – – – COMPIF OVFIF 201 +0x04 TEMP TEMP[7:0] 202 +0x08 CNTL CNT[7:0] 202 +0x09 CNTH CNT[15:8] 202 +0x0A PERL PER[7:0] 203 +0x0B PERH PER[15:8] 203 +0x0C COMPL COMP[7:0] 204 +0x0D COMPH COMP[15:8] 203 Offset Source Interrupt Description 0x00 OVF_vect Real-time counter overflow interrupt vector 0x02 COMP_vect Real-time counter compare match interrupt vector XMEGA B [MANUAL] 206 Atmel-8291C-AVR-XMEGA B -09/2014 18. USB – Universal Serial Bus Interface 18.1 Features z USB 2.0 full speed (12Mbps) and low speed (1.5Mbps) device compliant interface z Integrated on-chip USB transceiver, no external components needed z 16 endpoint addresses with full endpoint flexibility for up to 31 endpoints z One input endpoint per endpoint address z One output endpoint per endpoint address z Endpoint address transfer type selectable to z Control transfers z Interrupt transfers z Bulk transfers z Isochronous transfers z Configurable data payload size per endpoint, up to 1023 bytes z Endpoint configuration and data buffers located in internal SRAM z Configurable location for endpoint configuration data z Configurable location for each endpoint's data buffer z Built-in direct memory access (DMA) to internal SRAM for: z Endpoint configurations z Reading and writing endpoint data z Ping-pong operation for higher throughput and double buffered operation z Input and output endpoint data buffers used in a single direction z CPU/DMA controller can update data buffer during transfer z Multipacket transfer for reduced interrupt load and software intervention z Data payload exceeding maximum packet size is transferred in one continuous transfer z No interrupts or software interaction on packet transaction level z Transaction complete FIFO for workflow management when using multiple endpoints z Tracks all completed transactions in a first-come, first-served work queue z Clock selection independent of system clock source and selection z Minimum 1.5MHz CPU clock required for low speed USB operation z Minimum 12MHz CPU clock required for full speed operation z Connection to event system z On chip debug possibilities during USB transactions 18.2 Overview The USB module is a USB 2.0 full speed (12Mbps) and low speed (1.5Mbps) device compliant interface. The USB supports 16 endpoint addresses. All endpoint addresses have one input and one output endpoint, for a total of 31 configurable endpoints and one control endpoint. Each endpoint address is fully configurable and can be configured for any of the four transfer types: control, interrupt, bulk, or isochronous. The data payload size is also selectable, and it supports data payloads up to 1023 bytes. No dedicated memory is allocated for or included in the USB module. Internal SRAM is used to keep the configuration for each endpoint address and the data buffer for each endpoint. The memory locations used for endpoint configurations and data buffers are fully configurable. The amount of memory allocated is fully dynamic, according to the number of endpoints in use and the configuration of these. The USB module has built-in direct memory access (DMA), and will read/write data from/to the SRAM when a USB transaction takes place. To maximize throughput, an endpoint address can be configured for ping-pong operation. When done, the input and output endpoints are both used in the same direction. The CPU or DMA controller can then read/write one data buffer while the USB module writes/reads the others, and vice versa. This gives double buffered communication. XMEGA B [MANUAL] 207 Atmel-8291C-AVR-XMEGA B -09/2014 Multipacket transfer enables a data payload exceeding the maximum packet size of an endpoint to be transferred as multiple packets without software intervention. This reduces the CPU intervention and the interrupts needed for USB transfers. For low-power operation, the USB module can put the microcontroller into any sleep mode when the USB bus is idle and a suspend condition is given. Upon bus resumes, the USB module can wake up the microcontroller from any sleep mode. Figure 18-1. USB OUT transfer: data packet from host to USB device. Figure 18-2. USB IN transfer: data packet from USB device to host after request from host. 18.3 Operation This section gives an overview of the USB module operation during normal transactions. For general details on USB and the USB protocol, please refer to http://www.usb.org and the USB specification documents. Internal SRAM USB USB Endpoints Configuration Table USBEPPTR USB Buffers ENDPOINT 1 DATA ENDPOINT 2 DATA ENDPOINT 3 DATA D A T A 0 D A T A 0 D A T A 0 D A T A 1 D A T A 0 D A T A 1 D A T A 0 D A T A 1 D A T A 0 D A T A 1 D A T A 0 BULK OUT EPT 2 BULK OUT EPT 3 BULK OUT EPT 1 DP DM HOST time D A T A 0 D A T A 0 D A T A 0 D A T A 1 D A T A 0 D A T A 1 D A T A 0 D A T A 1 D A T A 0 D A T A 1 D A T A 0 EPT 2 EPT 3 EPT 1 DP DM HOST I N T O K E N I N T O K E N I N T O K E N EPT 2 EPT 3 EPT 1 time Internal SRAM USB USB Endpoints Configuration Table USBEPPTR USB Buffers ENDPOINT 1 DATA ENDPOINT 2 DATA ENDPOINT 3 DATA CPU XMEGA B [MANUAL] 208 Atmel-8291C-AVR-XMEGA B -09/2014 18.3.1 Start of Frame When a start of frame (SOF) token is detected and storing of the frame numbers is enabled, the frame number from the token is stored in the frame number register (FRAMENUM) and the start of frame interrupt flag (SOFIF) in the interrupt flag B clear/set register (INTFLAGSBCLR/SET) is set. If there was a CRC or bit-stuff error, the frame error (FRAMEERR) flag in FRAMENUM is set. 18.3.2 SETUP When a SETUP token is detected, the USB module fetches the endpoint control register (CTRL) from the addressed output endpoint in the endpoint configuration table. If the endpoint type is not set to control, the USB module returns to idle and waits for the next token packet. Figure 18-3. SETUP transaction. The USB module then fetches the endpoint data pointer register (DATAPTR) and waits for a DATA0 packet. If a PID error or any other PID than DATA0 is detected, the USB module returns to idle and waits for the next token packet. The incoming data are written to the data buffer pointed to by DATAPTR. If a bit-stuff error is detected in the incoming data, the USB module returns to idle and waits for the next token packet. If the number of received data bytes exceeds the endpoint's maximum data payload size, as specified by the data size (SIZE) in the endpoint CTRL register, the remaining received data bytes are discarded. The packet will still be checked for bit-stuff and CRC errors. Software must never report a maximum data payload size to the host that is greater than specified in SIZE. If there was a bit-stuff or CRC error in the packet, the USB module returns to idle and waits for the next token packet. If data was successfully received, an ACK handshake is returned to the host, and the number of received data bytes, excluding the CRC, is written to the endpoint byte counter (CNT). If the number of received data bytes is the maximum data payload specified by SIZE, no CRC data are written in the data buffer. If the number of received data bytes is the maximum data payload specified by SIZE minus one, only the first CRC data byte is written in the data buffer. If the number of received data bytes is equal or less than the data byte payload specified by SIZE minus two, the two CRC data bytes are written in the data buffer. Finally, the setup transaction complete flag (SETUP), data buffer 0 not acknowledge flag (NACK0), and data toggle flag (TOGGLE) are set, while the remaining flags in the endpoint status register (STATUS) are cleared for the addressed input and output endpoints. The setup transaction complete interrupt flag (SETUPIF) in INTFLAGSBCLR/SET is set. The STALL flag in the endpoint CTRL register is cleared for the addressed input and output endpoints. When a SETUP token is detected and the device address of the token packet does not match that of the endpoint, the packet is discarded, and the USB module returns to idle and waits for the next token packet. 18.3.3 OUT When an OUT token is detected, the USB module fetches the endpoint CTRL and STATUS register data from the addressed output endpoint in its endpoint configuration table. If the endpoint is disabled, the USB module returns to idle and waits for the next token packet. SETUP TOKEN ADDRESS ADDRESS MATCH? ENDPOINT LEGAL ENDPOINT? EP TYPE CTRL SET? PID PID OK? DATA BIT STUFF BIT STUFF OK? CRC OK? ACK IDLE No No No No No No READ CONFIG UPDATE STATUS STORE DATA Yes Yes Yes Yes Yes Yes CRC XMEGA B [MANUAL] 209 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 18-4. OUT transaction. The USB module then fetches the endpoint DATAPTR register and waits for a DATA0 or DATA1 packet. If a PID error or any other PID than DATA0 or DATA1 is detected, the USB module returns to idle and waits for the next token packet. If the STALL flag in the endpoint CTRL register is set, the incoming data are discarded. If the endpoint is not isochronous, and the bit stuffing and CRC of the received data are OK, a STALL handshake is returned to the host, and the STALL interrupt flag is set. For isochronous endpoints, data from both a DATA0 and DATA1 packet will be accepted. For other endpoint types, the PID is checked against TOGGLE. If they don't match, the incoming data are discarded and a NAK handshake is returned to the host. If BUSNACK0 is set, the incoming data are discarded. The overflow flag (OVF) in the endpoint STATUS register and the overflow interrupt flag (OVFIF) in the INTFLAGSASET/CLR register are set. If the endpoint is not isochronous, a NAK handshake is returned to the host. The incoming data are written to the data buffer pointed to by DATAPTR. If a bit-stuff error is detected in the incoming data, the USB module returns to idle and waits for the next token packet. If the number of received data bytes exceeds the maximum data payload specified by SIZE, the remaining received data bytes are discarded. The packet will still be checked for bit-stuff and CRC errors. If there was a bit-stuff or CRC error in the packet, the USB module returns to idle and waits for the next token packet. If the endpoint is isochronous and there was a bit-stuff or CRC error in the incoming data, the number of received data bytes, excluding CRC, is written to the endpoint CNT register. Finally, CRC and BUSNACK0 in the endpoint and STATUS and CRCIF in INTFLAGSASET/CLR are set. If data was successfully received, an ACK handshake is returned to the host if the endpoint is not isochronous, and the number of received data bytes, excluding CRC, is written to CNT. If the number of received data bytes is the maximum data payload specified by SIZE no CRC data are written in the data buffer. If the number of received data bytes is the maximum data payload specified by SIZE minus one, only the first CRC data byte is written in the data buffer If the number of received data bytes is equal or less than the data payload specified by SIZE minus two, the two CRC data bytes are written in the data buffer. Finally, the transaction complete flag (TRNCOMPL0) and BUSNACK0 are set and TOGGLE is toggled if the endpoint is not isochronous. The transaction complete interrupt flag (TRNIF) in INTFLAGSBCLR/SET is set. The endpoint's configuration table address is written to the FIFO if the transaction complete FIFO mode is enabled. OUT TOKEN ADDRESS ADDRESS MATCH? ENDPOINT LEGAL ENDPOINT? EP STATUS ENABLED? PID PID OK? DATA BIT STUFF BIT STUFF OK? CRC OK? ACK IDLE No No No No No STALL & ISO? STALL? STALL ISO? DATA No BUSNACK0 SET? NAK Yes No No No READ CONFIG UPDATE STATUS STORE DATA STORE DATA No Yes Yes Yes Yes Yes Yes Yes READ CONFIG PIDO/1 OK? NAK UPDATE STATUS No Yes DATA BIT STUFF CRC BIT STUFF OK? CRC OK? BUSNACK0 SET? CRC Yes No Yes Yes No Yes No Yes XMEGA B [MANUAL] 210 Atmel-8291C-AVR-XMEGA B -09/2014 When an OUT token is detected and the device address of the token packet does not match that of the endpoint, the packet is discarded and the USB module returns to idle and waits for the next token packet. 18.3.4 IN If an IN token is detected the, the USB module fetches the endpoint CTRL and STATUS register data from the addressed input endpoint in the endpoint configuration table. If the endpoint is disabled, the USB module returns to idle and waits for the next token packet. If the STALL flag in endpoint CTRL register is set, and the endpoint is not isochronous, a STALL handshake is returned to the host, the STALL flag in the endpoint STATUS register and the STALL interrupt flag (STALLIF) in INTFLAGSACLR/SET are set. If BUSNACK0 is set, OVF in the endpoint STATUS register and OVFIF in the INTFLAGSACLR/SET register are set. If the endpoint is not isochronous, a NAK handshake is returned to the host. The data in the data buffer pointed to by the endpoint DATAPTR register are sent to the host in a DATA0 packet if the endpoint is isochronous; otherwise, a DATA0 or DATA1 packet according to TOGGLE is sent. When the number of data bytes specified in endpoint CNT is sent, the CRC is appended and sent to the host. If not, a ZLP handshake is returned to the host. For isochronous endpoints, BUSNACK0 and TRNCOMPL0 in the endpoint STATUS register are set. TRNIF is set, and the endpoint's configuration table address is written to the FIFO if the transaction complete FIFO mode is enabled. For all non-isochronous endpoints, the USB module waits for an ACK handshake from the host. If an ACK handshake is not received within 16 USB clock cycles, the USB module returns to idle and waits for the next token packet. If an ACK handshake was successfully received, BUSNACK0 and TRNCOMPL0 are set and TOGGLE is toggled. TRNIF is set and the endpoint's configuration table address is written to the FIFO if the transaction complete FIFO mode is enabled. When an IN token is detected and the device address of the token packet does not match that of the endpoint, the packet is discarded and the USB module returns to idle and waits for the next token packet. Figure 18-5. IN transaction. IN TOKEN ADDRESS ADDRESS MATCH? ENDPOINT LEGAL ENDPOINT? EP STATUS ENABLED? DATA ACK PAYLOAD OK? IDLE No No No No STALL & NO ISO? STALL NAK No READ CONFIG READ DATA READ CONFIG UPDATE STATUS Yes Yes Yes Yes Yes BUSNACK0 SET? ISO? Yes No ISO? ACK SET? Yes No Yes Yes No No ZLP CRC XMEGA B [MANUAL] 211 Atmel-8291C-AVR-XMEGA B -09/2014 18.4 SRAM Memory Mapping The USB module uses internal SRAM to store the: z Endpoint configuration table z USB frame number z Transaction complete FIFO The endpoint pointer register (EPPTR) is used to set the SRAM address for the endpoint configuration table. The USB frame number (FRAMENUM) and transaction complete FIFO (FIFO) locations are derived from this. The locations of these areas are selectable inside the internal SRAM. Figure on page 211 gives the relative memory location of each area. Figure 18-6. SRAM memory mapping. 18.5 Clock Generation The USB module requires a minimum 6MHz clock for USB low speed operation, and a minimum 48MHz clock for USB full speed operation. It can be clocked from internal or external clock sources by using the internal PLL, or directly from the 32MHz internal oscillator when it is tuned and calibrated to 48MHz. The CPU and peripherals clocks must run at a minimum of 1.5MHz for low speed operation, and a minimum of 12MHz for full speed operation. The USB module clock selection is independent of and separate from the main system clock selection. Selection and setup are done using the main clock control settings. For details, refer to “System Clock and Clock Options” on page 75. The Figure 18-7 on page 212 shows an overview of the USB module clock selection. FIFO EP_ADDRH_MAX EP_ADDRL_0 EP_ADDRH_0 (MAXEP+1) x 4 Bytes Active when FIFOEN==1 ENDPOINT DESCRIPTORS TABLE STATUS CTRL CNTL CNTH DATAPTRL DATAPTRH AUXDATAL AUXDATAH ENDPOINT 0 OUT STATUS CTRL CNTL CNTH DATAPTRL DATAPTRH AUXDATAL AUXDATAH ENDPOINT 0 IN STATUS CTRL CNTL CNTH DATAPTRL DATAPTRH AUXDATAL AUXDATAH ENDPOINT MAXEP IN (MAXEP+1) x 16 Bytes FRAME NUMBER FRAMENUML FRAMENUMH 2 Bytes Active when STFRNUM==1 0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 (MAXEP+1)<<4 EPPTR EPPTR + (MAXEP+1)*16 SRAM ADDRESS XMEGA B [MANUAL] 212 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 18-7. Clock generation configuration. 18.6 Ping-pong Operation When an endpoint is configured for ping-pong operation, it uses the input and output data buffers to create a single, double-buffered endpoint that can be set to input or output direction. This provides double-buffered communication, as the CPU or DMA controller can access one of the buffers, while the other buffer is processing an ongoing transfer. Pingpong operation is identical to the IN and OUT transactions described above, unless otherwise noted in this section. Pingpong operation is not possible for control endpoints. When ping-pong operation is enabled for an endpoint, the endpoint in the opposite direction must be disabled. The data buffer, data pointer, byte counter, and auxiliary data from the enabled endpoint are used as bank 0, and, correspondingly, bank 1 for the opposite endpoint direction. The bank select (BANK) flag in the endpoint STATUS register indicates which data bank will be used in the next transaction. It is updated after each transaction. The TRNCOMPL0/TRNCOMPL1, underflow/overflow (UDF/OVF), and CRC flags in the STATUS register are set for either the enabled or the opposite endpoint direction according to the BANK flag. The data toggle (TOGGLE), data buffer 0/1 not acknowledge (BUSNACK0 and BUSNACK1), and BANK flags are updated for the enabled endpoint direction only. Figure 18-8. Ping-pong operation overview. USB module 48MHz full speed 6MHz for low speed USBSRC USB clock prescaler USBPSDIV PLL 48MHz Internal Oscillator Bank0 Available time for data processing by CPU to avoid NACK Without Ping-Pong With Ping-Pong Bank1 Endpoint single bank Endpoint Double bank USB data packet t t XMEGA B [MANUAL] 213 Atmel-8291C-AVR-XMEGA B -09/2014 18.7 Multipacket Transfers Multipacket transfer enables a data payload exceeding the maximum data payload size of an endpoint to be transferred as multiple packets without any software intervention. This reduces interrupts and software intervention to the higher level USB transfer, and frees up significant CPU time. Multipacket transfer is identical to the IN and OUT transactions described above, unless otherwise noted in this section. The application software provides the size and address of the SRAM buffer to be processed by the USB module for a specific endpoint, and the USB module will then split the buffer in the required USB data transfer. Figure 18-9. Multipacket overview. 18.7.1 For Input Endpoints The total number of data bytes to be sent is written to CNT, as for normal operation. The auxiliary data register (AUXDATA) is used to store the number of bytes that will be sent, and must be written to zero for a new transfer. When an IN token is received, the endpoint’s CNT and AUXDATA are fetched. If CNT minus AUXDATA is less than the endpoint SIZE, endpoint CNT minus endpoint AUXDATA number bytes are transmitted; otherwise, SIZE number of bytes are transmitted. If endpoint CNT is a multiple of SIZE and auto zero length packet (AZLP) is enabled, the last packet sent will be zero length. If a maximum payload size packet was sent (i.e., not the last transaction), AUXDATA is incremented by SIZE. TOGGLE will be toggled after the transaction has completed if the endpoint is not isochronous. If a short packet was sent (i.e., the last transaction), AUXDATA is incremented by the data payload. TOGGLE will be toggled if the endpoint is not isochronous, and BUSNACK, TRNIF, and TRNCOMPL0 will be set. 18.7.2 For Output Endpoints The number of data bytes received is stored in the endpoint’s CNT register, as for normal operation. Since the endpoint’s CNT is updated after each transaction, it must be set to zero when setting up a new transfer. The total number of bytes to be received must be written to AUXDATA. This value must be a multiple of SIZE, except for ISO 1023 bytes endpoints; otherwise, excess data may be written to SRAM locations used by other parts of the application. TOGGLE management is as for non-isochronous packets, and BUSNACK0/BUSNACK1 management is as for normal operation. If a maximum payload size packet is received, CNT is incremented by SIZE after the transaction has completed, and TOGGLE toggles if the endpoint is not isochronous. If the updated endpoint CNT is equal to AUXDATA, then BUSNACK0/BUSNACK1, TRNIF, and TRNCOMPL0/TRNCOMPL1 will be set. If a short or oversized packet is received, the endpoint’s CNT register will be incremented by the data payload after the transaction has completed. TOGGLE will be toggled if the endpoint is not isochronous, and BUSNACK0/BUSNACK1, TRNIF, and TRNCOMPL0/TRNCOMPL1 will be set. Transfer Complete Interrupt and data processing Without multipacket With multipacket XMEGA B [MANUAL] 214 Atmel-8291C-AVR-XMEGA B -09/2014 18.8 Auto Zero Length Packet Some IN transfer requires a zero length packet to be generated in order to signal end of transfer to the host. The auto zero length packet (AZLP) function can be enabled to perform this generation automatically, thus removing the need for application software or CPU intervention to perform this task. 18.9 Transaction Complete FIFO The transaction complete FIFO provides a convenient way to keep track of the endpoints that have completed IN or OUT transactions and need firmware intervention. It creates a first-come, first-served work queue for the application software. The FIFO size is (MAXEP[3:0] + 1) × 4 bytes, and grows downward, starting from EPPTR - 1. This SRAM memory is allocated only when the FIFO is enabled. Figure 18-10.Transfer complete FIFO. To manage the FIFO, a five-bit write pointer (FIFOWP) and five-bit read pointer (FIFORP) are used by the USB module and application software, respectively. FIFORP and FIFOWP are one's complemented, and thus hold negative values. The SRAM location of the data is the sum of EPPTR and the read or write pointer. The number of items in the FIFO is the difference between FIFOWP and FIFORP. For the programmer, the FIFORP and FIFOWP values have to be cast to a signed 8-bit integer, and then the offset into the FIFO from this signed integer must be deducted. The transaction complete interrupt flag (TRNIF) in the INFLAGSB[CLR,SET] register is set to indicate a non-empty FIFO when FIFORP != FIFOWP, cleared when they are equal, and also set when the FIFO is full. Each time an endpoint IN or OUT transaction completes successfully, its endpoint configuration table address is stored in the FIFO at the current write pointer position (i.e., EPPTR + 2 × FIFOWP) and FIFOWP is decremented. When the pointer reaches the FIFO size, it wraps to zero. When application software reads FIFORP, this is decremented in the same way. Reading the write pointer has no effect. The endpoint configuration table address can then be read directly from (EPPTR + 2 × FIFORP). Figure 18-11.USB transaction complete FIFO example. USB_TC_ FIFO TC_EP_ ADDRH_0 TC_EP_ ADDRL_0 TC_EP_ ADDRH_ MAX ENDPOINT DESCRIPTOR TABLE TC_EP_ ADDRH_1 TC_EP_ ADDRL_1 INTERNAL SRAM TC_EP_ ADDRH_2 TC_EP_ ADDRH_2 FIFOWP FIFORP EPPTR SRAM ADDRESS EPPTR – 4x( MAXEP+1) Ep X EpY EpZ t FIFO X Y Z FIFOWP FIFORP FIFO X Y FIFOWP FIFORP FIFO X FIFOWP FIFORP FIFO FIFOWP FIFORP XMEGA B [MANUAL] 215 Atmel-8291C-AVR-XMEGA B -09/2014 18.10 Interrupts and Events The USB module can generate interrupts and events. The module has 10 interrupt sources. These are split between two interrupt vectors, the transaction complete (TRNCOMPL) interrupt and the bus event (BUSEVENT) interrupt. An interrupt group is enabled by setting its interrupt level (INTLVL), while different interrupt sources are enabled individually or in groups. Figure 18-12 on page 215 summarizes the interrupts and event sources for the USB module, and shows how they are enabled. Figure 18-12.Interrupts and events scheme summary. 18.10.1 Transaction Complete Interrupt The transaction complete interrupt is generated per endpoint. When an interrupt occurs, the associated endpoint number is registered and optionally added to the FIFO. The following two interrupt sources use the interrupt vector: SUSPENDIF SOFIE RESUMEIF RSTIF CRCIF UNFIF OVFIF STALLIF BSEVIE STALLIE BUSSERRIE SOFIF SETUPIE TRNIF TRNIE SETUPIF Busevent Interrupt request Transaction Complete Interrupt request XMEGA B [MANUAL] 216 Atmel-8291C-AVR-XMEGA B -09/2014 Table 18-1. Transaction complete interrupt sources. 18.10.2 Bus Event Interrupt The bus event (BUSEVENT) interrupt is used for all interrupts that signal various types of USB line events or error conditions. These interrupts are related to the USB lines, and are generated for the USB module and per endpoint. The following eight interrupts use the interrupt vector: Table 18-2. Bus event interrupt source. 18.10.3 Events The USB module can generate several events, and these are available to the event system, allowing latency-free signaling to other peripherals or performance analysis of USB operation. Table 18-3. Event sources. 18.11 VBUS Detection Atmel AVR XMEGA devices can use any general purpose I/O pin to implement a VBUS detection function, and do not use a dedicated VBUS detect pin. Interrupt source Description Transfer complete (TRNIF) An IN or OUT transaction is completed Setup complete (SETUPIF) A SETUP transaction is completed Interrupt source Description Start of frame (SOFIF) A SOF token has been received Suspend (SUSPENDIF) The bus has been idle for 3ms Resume (RESUMEIF) A non-idle state is detected when the bus is suspended. The interrupt is asynchronous and can wake the device from all sleep modes Reset (RSTIF) A reset condition has been detected on the bus Isochronous CRC error (CRCIF) A CRC or bit-stuff error has been detected in an incoming packet to an isochronous endpoint Underflow (UNFIF) An endpoint is unable to return data to the host Overflow (OVFIF) An endpoint is unable to accept data from the host STALL (STALLIF) A STALL handshake has been returned to the host Event source Description SETUP SETUPIF Start of Frame SOFIF CRC error CRCIF Underflow/overflow UNFIF and OVFIF XMEGA B [MANUAL] 217 Atmel-8291C-AVR-XMEGA B -09/2014 18.12 On-chip Debug When a break point is reached during on-chip debug (OCD) sessions, the CPU clock can be below 12MHz. If this happens, the USB module will behave as follows: USB OCD break mode disabled: The USB module immediately acknowledges any OCD break request. The USB module will not be able to follow up on transactions received from the USB host, and its behaviour from the host point of view is not predictable. USB OCD break mode enabled: The USB module will immediately acknowledge any OCD break request only if there are no ongoing USB transactions. If there is an ongoing USB transaction, the USB module will acknowledge any OCD break request only when the ongoing USB transaction has been completed. The USB module will NACK any further transactions received from the USB host, whether they are SETUP, IN (ISO, BULK), or OUT (ISO, BULK). XMEGA B [MANUAL] 218 Atmel-8291C-AVR-XMEGA B -09/2014 18.13 Register Description – USB 18.13.1 CTRLA – Control register A z Bit 7 – ENABLE: USB Enable Setting this bit enables the USB interface. Clearing this bit disables the USB interface and immediately aborts any ongoing transactions. z Bit 6 – SPEED: Speed Select This bit selects between low and full speed operation. By default, this bit is zero, and low speed operation is selected. Setting this bit enables full speed operation. z Bit 5 – FIFOEN: USB FIFO Enable Setting this bit enables the USB transaction complete FIFO, and the FIFO stores the endpoint configuration table address of each endpoint that generates a transaction complete interrupt. Clearing this bit disables the FIFO and frees the allocated SRAM memory. z Bit 4 – STFRNUM: Store Frame Number Enable Setting this bit enables storing of the last SOF token frame number in the frame number (FRAMENUM) register. Clearing this bit disables the function. z Bit 3:0 – MAXEP[3:0]: Maximum Endpoint Address These bits select the number of endpoint addresses used by the USB module. Incoming packets with a higher endpoint number than this address will be discarded. Packets with endpoint addresses lower than or equal to this address will cause the USB module to look up the addressed endpoint in the endpoint configuration table. 18.13.2 CTRLB – Control register B z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4 – PULLRST: Pull during Reset Setting this bit enables the pull-up on the USB lines to also be held when the device enters reset. The bit will be cleared on a power-on reset. z Bit 3 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. Bit 7 6 5 4 3 2 1 0 +0x00 ENABLE SPEED FIFOEN STFRNUM MAXEP[3:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x01 – – – PULLRST – RWAKEUP GNACK ATTACH Read/Write R R R R/W R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 219 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 2 – RWAKEUP: Remote Wake-up Setting this bit sends an upstream resume on the USB lines if the bus is in the suspend state for at least 5 ms. z Bit 1 – GNACK: Global NACK When this bit is set, the USB module will NACK all incoming transactions. Expect for a SETUP packet, this prevents the USB module from performing any on-chip SRAM access, giving all SRAM bandwidth to the CPU and/or DMA controller. z Bit 0 – ATTACH: Attach Setting this bit enables the internal D+ or D- pull-up (depending on the USB speed selection), and attaches the device to the USB lines. Clearing this bit disconnects the device from the USB lines. 18.13.3 STATUS – Status register z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3 – URESUME: Upstream Resume This flag is set when an upstream resume is sent. z Bit 2 – RESUME: Resume This flag is set when a downstream resume is received. z Bit 1 – SUSPEND: Bus Suspended This flag is set when the USB lines are in the suspended state (the bus has been idle for at least 3ms). z Bit 0 – BUSRST: Bus Reset This flag is set when a reset condition has been detected (the bus has been driven to SE0 for at least 2.5μs). 18.13.4 ADDR – Address register z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 6:0 – ADDR[6:0]: Device Address These bits contain the USB address the device will respond to. Bit 7 6 5 4 3 2 1 0 +0x02 – – – – URESUME RESUME SUSPEND BUSRST Read/Write RRRRRRRR Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x03 – ADDR[6:0] Read/Write R R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 220 Atmel-8291C-AVR-XMEGA B -09/2014 18.13.5 FIFOWP – FIFO Write Pointer register z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4:0 – FIFOWP[4:0]: FIFO Write Pointer These bits contain the transaction complete FIFO write pointer. This register must be read only by the CPU or DMA controller. Writing this register will flush the FIFO write and read pointers. 18.13.6 FIFORP – FIFO Read Pointer register z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4:0 – FIFORP[4:0]: FIFO Read Pointer These bits contain the transaction complete FIFO read pointer. This register must only be read by the CPU or DMA controller. Writing this register will flush the FIFO write and read pointer. 18.13.7 EPPTRL – Endpoint Configuration Table Pointer Low The EPPTRL and EPPTRH registers represent the 16-bit value, EPPTR, that contains the address to the endpoint configuration table. The pointer to the endpoint configuration table must be aligned to a 16-bit word; i.e., EPPTR[0] must be zero. Only the number of bits required to address the available internal SRAM memory is implemented for each device. Unused bits will always be read as zero. z Bit 7:0 – EPPTR[7:0]: Endpoint Configuration Table Pointer low byte This register contains the eight lsbs of the endpoint configuration table pointer (EPPTR). Bit 7 6 5 4 3 2 1 0 +0x04 – – – FIFOWP[4:0] Read/Write R R R R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x05 – – – FIFORP[4:0] Read/Write R R R R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x06 EPPTR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 221 Atmel-8291C-AVR-XMEGA B -09/2014 18.13.8 EPPTRH – Endpoint Configuration Table Pointer High z Bit 7:0 – EPPTR[15:8]: Endpoint Configuration Table Pointer high byte This register contains the eight msbs of the endpoint configuration table pointer (EPPTR). 18.13.9 INTCTRLA – Interrupt Control register A z Bit 7 – SOFIE: Start Of Frame Interrupt Enable Setting this bit enables the start of frame (SOF) interrupt for the conditions that set the start of frame interrupt flag (SOFIF) in the INTFLAGSACLR/ INTFLAGSASET register. The INTLVL bits must be nonzero for the interrupts to be generated. z Bit 6 – BUSEVIE: Bus Event Interrupt Enable Setting this bit will enable the interrupt for the following three bus events: 1. Suspend: An interrupt will be generated for the conditions that set the suspend interrupt flag (SUSPENDIF) in the INTFLAGSACLR/SET register. 2. Resume: An interrupt will be generated for the conditions that set the resume interrupt flag (RESUMEIF) in the INTFLAGSACLR/SET register. 3. Reset: An interrupt will be generated for the conditions that set the reset interrupt flag (RESETIF) in the INTFLAGSACLR/SET register. The INTLVL bits must be nonzero for the interrupts to be generated. z Bit 5 – BUSERRIE: Bus Error Interrupt Enable Setting this bit will enable the interrupt for the following three bus error events: 1. Isochronous CRC Error: An interrupt will be generated for the conditions that set the CRC interrupt flag (CRCIF) in the INTFLAGSACLR/SET register during isochronous transfers. 2. Underflow: An interrupt will be generated for the conditions that set the underflow interrupt flag (UNFIF) in the INTFLAGSACLR/SET register. 3. Overflow: An interrupt will be generated for the conditions that set the overflow interrupt flag (OVFIF) in the INTFLAGSACLR/SET register. The INTLVL bits must be nonzero for the interrupts to be generated. z Bit 4 – STALLIE: STALL Interrupt Enable Setting this bit enables the STALL interrupt for the conditions that set the stall interrupt flag (STALLIF) in the INTFLAGSACLR/SET register. The INTLVL bits must be nonzero for the interrupts to be generated. Bit 7 6 5 4 3 2 1 0 +0x07 EPPTR[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x06 SOFIE BUSEVIE BUSERRIE STALLIE – – INTLVL[1:0] Read/Write R/W R/W R/W R/W R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 222 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 3:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1:0 – INTLVL[1:0]: Interrupt Level These bits enable the USB interrupts and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. In addition, each USB interrupt source must be separately enabled. 18.13.10INTCTRLB – Interrupt Control register B z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – TRNIE: Transaction Complete Interrupt Enable Setting this bit enables the transaction complete interrupt for IN and OUT transactions. The INTLVL bits must be nonzero for interrupts to be generated. z Bit 0 – SETUPIE: SETUP Transaction Complete Interrupt Enable Setting this bit enables the SETUP Transaction Complete Interrupt for SETUP transactions. The INTLVL bits must be non-zero for the interrupts to be generated. 18.13.11INTFLAGSACLR/ INTFLAGSASET – Clear/ Set Interrupt Flag register A This register is mapped into two I/O memory locations, one for clearing (INTFLAGSACLR) and one for setting (INTFLAGSASET) the flags. The individual flags can be set by writing a one to their bit locations in INFLAGSASET, and cleared by writing a one to their bit locations in INT-FLAGSACLR. Both memory locations will provide the same result when read, and writing zero to any bit location has no effect. z Bit 7 – SOFIF: Start Of Frame Interrupt Flag This flag is set when a start of frame packet has been received. z Bit 6 – SUSPENDIF: Suspend Interrupt Flag This flag is set when the bus has been idle for 3ms. z Bit 5 – RESUMEIF: Resume Interrupt Flag This flag is set when a non-idle state has been detected on the bus while the USB module is in the suspend state. This interrupt is asynchronous, and is able to wake the CPU from sleep modes where the system clock is stopped, such as power-down and power-save sleep modes. z Bit 4 – RSTIF: Reset Interrupt Flag This flag is set when a reset condition has been detected on the bus. Bit 7 6 5 4 3 2 1 0 +0x07 – – – – – – TRNIE SETUPIE Read/Write R R R R R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0A/ +0x0B SOFIF SUSPENDIF RESUMEIF RESETIF CRCIF UNFIF OVFIF STALLIF Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 223 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 3 – CRCIF: Isochronous CRC Error Interrupt Flag This flag is set when a CRC error has been detected in an incoming data packet to an isochronous endpoint. z Bit 2 – UNFIF: Underflow Interrupt Flag This flag is set when the addressed endpoint in an IN transaction does not have data to send to the host. z Bit 1 – OVFIF: Overflow Interrupt Flag This flag is set when the addressed endpoint in an OUT transaction is not ready to accept data from the host. z Bit 0 – STALLIF: STALL Interrupt Flag This flag is set when the USB module has responded with a STALL handshake to either an IN or an OUT transaction. 18.13.12INTFLAGSBCLR/INTFLAGSBSET – Clear/Set Interrupt Flag register B This register is mapped into two I/O memory locations, one for clearing (INTFLAGSBCLR) and one for setting (INTFLAGSBSET) the flags. The individual flags can be set by writing a one to their bit locations in INFLAGSBSET, and cleared by writing a one to their bit locations in INTFLAGSBCLR. Both memory locations will provide the same result when read, and writing zero to any bit location has no effect. z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – TRNIF: Transaction Complete Interrupt Flag This flag is when there is a pending packet interrupt in the FIFO. z Bit 0 – SETUPIF: SETUP Transaction Complete Interrupt Flag This flag is set when a SETUP transaction has completed successfully. 18.13.13CALL – Calibration register Low CALL and CALH hold the 16-bit value, CAL. The USB PADs (D- and D+) are calibrated during production to enable operation without requiring external components on the USB lines. The calibration value is stored in the signature row of the device, and must be read from there and written to the CAL registers from software. z Bit 7:0 – CAL[7:0]: PAD Calibration low byte This byte holds the eight lsbs of CAL. Bit 7 6 5 4 3 2 1 0 +0x0C/ +0x0D – – – – – –- TRNIF SETUPIF Read/Write R R R R R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ++0x3A CAL[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 224 Atmel-8291C-AVR-XMEGA B -09/2014 18.13.14CALH – Calibration register High z Bit 7:0 – CAL[15:8]: PAD Calibration high byte This byte holds the eight msbs of CAL. Bit 7 6 5 4 3 2 1 0 +0x3B CAL[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 225 Atmel-8291C-AVR-XMEGA B -09/2014 18.14 Register Description – USB Endpoint Each of the 16 endpoint addresses have one input and one output endpoint. Each endpoint has eight bytes of configuration/status data located in internal SRAM. The address to the first configuration byte is (EPPTR[15:0] + 16 × endpoint address) for output endpoints and (EPPTR[15:0] + 16 × endpoint address + 8) for input endpoints. Some bit locations have different functions, depending on endpoint configuration type or direction, and this is reflected by using two different names for the bit locations. 18.14.1 STATUS – Status register Note: 1. For isochronous endpoints. z Bit 7 – STALL: STALL Flag This flag is set when an IN or OUT transaction has been responded to with a STALL handshake. This flag is cleared by writing a one to its bit location. z Bit 7 – CRC: CRC Error Flag This flag is set for isochronous output endpoints when a CRC error has been detected in an incoming data packet. This flag is cleared by writing a one to its bit location. z Bit 6 – UNF/OVF: Underflow/Overflow Flag UNF: For input endpoints, the UNF flag is set when an input endpoint is not ready to send data to the host in response of an IN token. OVF: For output endpoints, the OVF flag is set when an output endpoint is not ready to accept data from the host following an OUT token. z Bit 5 – TRNCOMPL0: Transaction Complete Flag This flag is set when an IN or OUT transaction has completed successfully. This flag is cleared by writing a one to its bit location. z Bit 4 – SETUP: SETUP Transaction Complete Flag This flag is set when a SETUP, IN, or OUT transaction has completed successfully. This flag is cleared by writing a one to its bit location. z Bit 4 – TRNCOMPL1: Transaction Complete Flag This flag is set when a SETUP, IN, or OUT transaction has completed successfully. This flag is cleared by writing a one to its bit location. z Bit 3 – BANK: Bank Select Flag When ping-pong mode is enabled, this bit indicates which bank will be used for the next transaction. BANK is toggled each time a transaction has completed successfully. This bit is not sed when ping-pong is disabled. This flag is cleared by writing a one to its bit location. z Bit 2 – BUSNACK1: Data Buffer 1 Not Acknowledge Flag When this flag is set, the USB module will discard incoming data to data buffer 1 in an OUT transaction, and will not return any data from data buffer 1 in an IN transaction. For control, bulk, and interrupt endpoints, a NAK handshake is returned. This flag is cleared by writing a one to its bit location. Bit 7 6 5 4 3 2 1 0 +0x00 STALL UNF/ OVF TRNCOMPL0 SETUP BANK BUSNACK1 BUSNACK0 TOGGLE CRC(1) TRNCOMPL1 Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 226 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 1 – BUSNACK0: Data Buffer 0 Not Acknowledge Flag When this flag is set, the USB module will discard incoming data to data buffer 0 in an OUT transaction, and will not return any data from data buffer 0 in an IN transaction. For control, bulk, and interrupt endpoints, a NAK handshake is returned. This flag is cleared by writing a one to its bit location. z Bit 0 – TOGGLE: Data Toggle Flag This indicates if a DATA0 or DATA1 PID is expected in the next data packet for an output endpoint, and if a DATA0 or DATA1 PID will be sent in the next transaction for an input endpoint. This bit has no effect for isochronous endpoints, where both DATA0 and DATA1 PIDs are accepted for output endpoint, and only DATA0 PIDs are sent for input endpoints. 18.14.2 CTRL – Control Note: 1. For isochronous endpoints. z Bit 7:6 – TYPE[1:0]: Endpoint Type These bits are used to enable and select the endpoint type. If the endpoint is disabled, the remaining seven endpoint configuration bytes are never read or written by the USB module, and their SRAM locations are free to use for other application data. Table 18-4. Endpoint type. z Bit 5 – MULTIPKT: Multipacket Transfer Enable Setting this bit enables multipacket transfers. Multipacket transfer enables a data payload exceeding the maximum packet size of an endpoint to be transferred as multiple packets without interrupts or software intervention. See “Multipacket Transfers” on page 213 for details on multipacket transfers. z Bit 4 – PINGPONG: Ping-pong Enable Setting this bit enables ping-pong operation. Ping-pong operation enables both endpoints (IN and OUT) with same address to be used in the same direction to allow double buffering and maximize throughput. The endpoint in the opposite direction must be disabled when ping-pong operation is enabled. Ping-pong operation is not possible for control endpoints. See “Ping-pong Operation” on page 212 for details. z Bit 3 – INTDSBL: Interrupt Disable Setting this bit disables all enabled interrupts from the endpoint. Hence, only the interrupt flags in the STATUS register are updated when interrupt conditions occur. The FIFO does not store this endpoint configuration table address upon transaction complete for the endpoint when interrupts are disabled for an endpoint. Clearing this bit enables all previously enables interrupts again. Bit 7 6 5 4 3 2 1 0 +0x01 TYPE[1:0] MULTIPKT PINGPONG INTDSBL STALL SIZE[1:0] SIZE[2:0](1) Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 TYPE[1:0] Group Configuration Description 00 DISABLE Endpoint enabled 01 CONTROL Control 10 BULK Bulk/interrupt 11 ISOCHRONOUS Isochronous XMEGA B [MANUAL] 227 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 2 – STALL: Endpoint STALL This bit controls the STALL behavior if the endpoint. z Bit 1:0 – BUFSIZE[1:0]: Data Size These bits configure the maximum data payload size for the endpoint. Incoming data bytes exceeding the maximum data payload size are discarded. z Bit 2:0 – BUFSIZE[2:0]: Data Size These bits configure the maximum data payload size for the endpoint when configured for isochronous operation. Table 18-5. BUFSIZE configuration Note: 1. Setting only available for isochronous endpoints. 18.14.3 CNTL – Counter Low register The CNTL and CNTH registers represent the 10-bit value, CNT, that contains the number of bytes received in the last OUT or SETUP transaction for an OUT endpoint, or the number of bytes to be sent in the next IN transaction for an IN endpoint. z Bit 7:0 – CNT[7:0]: Endpoint Byte Counter This byte contains the eight lsbs of the USB endpoint counter (CNT). BUFSIZE[2:0] Group Configuration Description 000 8 8-byte buffer size 001 16 16-byte buffer size 010 32 32-byte buffer size 011 64 64-byte buffer size 100(1) 128 128-byte buffer size 101(1) 256 256-byte buffer size 110(1) 512 512-byte buffer size 111(1) 1023 1023-byte buffer size Bit 7 6 5 4 3 2 1 0 +0x02 CNT[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value XXXXXXXX XMEGA B [MANUAL] 228 Atmel-8291C-AVR-XMEGA B -09/2014 18.14.4 CNTH – Counter High register z Bit 6 – AZLP: Automatic Zero Length Packet When this bit is set, the USB module will manage the ZLP handshake by hardware. This applies to IN endpoints only. When this bit is zero, the ZLP handshake must be managed by firmware. z Bit 6:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1:0 – CNT[9:8]: Endpoint Byte Counter These bits contain the two msbs of the USB endpoint counter (CNT). 18.14.5 DATAPTRL – Data Pointer Low register The DATAPTRL and DATAPTRH registers represent the 16-bit value, DATAPTR, that contains the SRAM address to the endpoint data buffer. z Bit 7:0 – DATAPTR[7:0]: Endpoint Data Pointer Low This byte contains the eight lsbs of the endpoint data pointer (DATAPTR). 18.14.6 DATAPTRH – Data Pointer High register z Bit 15:0 - DPTR[15:8]: Endpoint Data Pointer High This byte contains the eight msbs of the endpoint data pointer (DATAPTR). Bit 7 6 5 4 3 2 1 0 +0x03 AZLP – – – – – CNT[9:8] Read/Write R/W R R R R R R/W R/W Initial Value X X X X X X X X Bit 7 6 5 4 3 2 1 0 +0x04 DATAPTR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value X X X X X X X X Bit 7 6 5 4 3 2 1 0 +0x05 DATAPTR[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value X X X X X X X X XMEGA B [MANUAL] 229 Atmel-8291C-AVR-XMEGA B -09/2014 18.14.7 AUXDATAL – Auxiliary Data Low register The AUXDATAL and AUXDATAH registers represent the 16-bit value, AUXDATA, that is used for multipacket transfers. For IN endpoints, AUXDATA holds the total number of bytes sent. AUXDATA should be written to zero when setting up a new transfer. For OUT endpoints, AUXDATA holds the total data size for the complete transfer. This value must be a multiple of the maximum packet size, except for ISO 1023-byte endpoints. See “Multipacket Transfers” on page 213 for more details on setting up and using multipacket transfers. z Bit 7:0 – AUXDATA[7:0]: Auxiliary Data Low This byte contains the eight lsbs of the auxiliary data (AUXDATA). When multipacket transfer is not used, this SRAM location is free to use for other application data. 18.14.8 AUXDATAH – Auxiliary Data High register z Bit 7:0 – AUXDATA[15:8]: Auxiliary Data High This byte contains the eight msbs of the auxiliary data (AUXDATA). When multipacket transfer is not used, this SRAM location is free to use for other application data. Bit 7 6 5 4 3 2 1 0 +0x06 AUXDATA[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value X X X X X X X X Bit 7 6 5 4 3 2 1 0 +0x07 AUXDATA[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value X X X X X X X X XMEGA B [MANUAL] 230 Atmel-8291C-AVR-XMEGA B -09/2014 18.15 Register Description - Frame 18.15.1 FRAMENUML – Frame Number Low register The FRAMENUML and FRAMENUMH registers represent the 11-bit value, FRAMENUM, that holds the frame number from the most recently received start of frame packet. z Bit 7:0 – FRAMENUM[7:0]: Frame Number This byte contains the eight lsbs of the frame number (FRAMENUM). 18.15.2 FRAMENUMH – Frame Number High register z Bit 7 – FRAMEERR: Frame Error This flag is set if a CRC or bit-stuffing error was detected in the most recently received start of frame packet. z Bit 6:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2:0 – FRAMENUM[10:8]: Frame Number This byte contains the three msbs of the frame number (FRAMENUM). Bit 7 6 5 4 3 2 1 0 +0x00 FRAMENUM[7:0] Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x01 FRAMEERR – – – – FRAMENUM[10:8] Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 231 Atmel-8291C-AVR-XMEGA B -09/2014 18.16 Register Summary – USB Module 18.17 Register Summary – USB Endpoint The address to the first configuration byte is (EPPTR[15:0] + 16 × endpoint address) for OUT endpoints and (EPPTR[15:0] + 16 × endpoint address + 8) for IN endpoints. 18.18 Register Summary – Frame The address to the frame configuration byte is (MAXEP + 1) << 4. For instance with MAXEP = 3, the first address would be located at offset address 0x40. 18.19 USB Interrupt Vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRLA ENABLE SPEED FIFOEN STFRNUM MAXEP[3:0] 218 +0x01 CTRLB – – – PULLRST – RWAKEUP GNACK ATTACH 218 +0x02 STATUS – – – – UPRESUM RESUME SUSPEND BUSRST 219 +0x03 ADDR – ADDR[6:0] 219 +0x04 FIFOWP – – – FIFOWP[4:0] 220 +0x05 FIFORP – – – FIFORP[4:0] 220 +0x06 EPPTRL EPPTR[7:0] 220 +0x07 EPPTRH EPPTR[15:8] 221 +0x08 INTCTRLA SOFIE BUSEVIE BUSERRIE STALLIE – – INTLVL[1:0] 221 +0x09 INTCTRLB – – – – – – TRNIE SETUPIE 222 +0x0A INFLAGSACL SOFIF SUSPENDI RESUMEIF RSTIF CRCIF UNFIF OVFIF STALLIF 222 +0x0B INFLAGSASE SOFIF SUSPENDI RESUMEIF RSTIF CRCIF UNFIF OVFIF STALLIF 222 +0x0C INFLAGSBCL – – – – – – TRNIF SETUPIF 223 +0x0D INFLAGSBSE – – – – – – TRNIF SETUPIF 223 +0x0E Reserved – – – – – – – – +0x0F Reserved – – – – – – – – +0x10-0X39 Reserved – – – – – – – – +0x3A CALL CAL[7:0] 223 +0x3B CALH CAL[15:8] 224 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 STATUS STALL OVF/UNF TRNCOMP L0 SETUP BANK BUSNACK1 BUSNACK0 TOGGLE 225 CRC TRNCOMP Isochronous +0x01 CTRL TYPE[1:0] MULTIPKT PINGPONG INTDSB L STALL BUFSIZE[1:0] 226 BUFSIZE[2:0] Isochronous +0x02 CNTL CNT[7:0] 227 +0x03 CNTH AZLP – – – – – CNT[9:8] 228 +0x04 DATAPTR DATAPTR[7:0] 228 +0x05 DATAPTR DATAPTR[15:8] 228 +0x06 AUXDATA AUXDATA[7:0] 229 +0x07 AUXDATA AUXDATA[15:8] 229 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 FRAMENUM FRAMENUM[7:0] 230 +0x01 FRAMENUM FRAMEER – – – – FRAMENUM[10:8] 230 Offset Source Interrupt Description 0x00 BUSEVENT_vect SOF, suspend, resume, bus reset, CRC, underflow, overflow, and stall error interrupts 0x02 TRNCOMPL_vect Transaction complete interrupt XMEGA B [MANUAL] 232 Atmel-8291C-AVR-XMEGA B -09/2014 19. TWI – Two-Wire Interface 19.1 Features z Bidirectional, two-wire communication interface z Phillips I2 C compatible z System Management Bus (SMBus) compatible z Bus master and slave operation supported z Slave operation z Single bus master operation z Bus master in multi-master bus environment z Multi-master arbitration z Flexible slave address match functions z 7-bit and general call address recognition in hardware z 10-bit addressing supported z Address mask register for dual address match or address range masking z Optional software address recognition for unlimited number of addresses z Slave can operate in all sleep modes, including power-down z Slave address match can wake device from all sleep modes z 100kHz and 400kHz bus frequency support z Slew-rate limited output drivers z Input filter for bus noise and spike suppression z Support arbitration between start/repeated start and data bit (SMBus) z Slave arbitration allows support for address resolve protocol (ARP) (SMBus) 19.2 Overview The two-wire interface (TWI) is a bidirectional, two-wire communication interface. It is I2 C and System Management Bus (SMBus) compatible. The only external hardware needed to implement the bus is one pull-up resistor on each bus line. A device connected to the bus must act as a master or a slave. The master initiates a data transaction by addressing a slave on the bus and telling whether it wants to transmit or receive data. One bus can have many slaves and one or several masters that can take control of the bus. An arbitration process handles priority if more than one master tries to transmit data at the same time. Mechanisms for resolving bus contention are inherent in the protocol. The TWI module supports master and slave functionality. The master and slave functionality are separated from each other, and can be enabled and configured separately. The master module supports multi-master bus operation and arbitration. It contains the baud rate generator. Both 100kHz and 400kHz bus frequency is supported. Quick command and smart mode can be enabled to auto-trigger operations and reduce software complexity. The slave module implements 7-bit address match and general address call recognition in hardware. 10-bit addressing is also supported. A dedicated address mask register can act as a second address match register or as a register for address range masking. The slave continues to operate in all sleep modes, including power-down mode. This enables the slave to wake up the device from all sleep modes on TWI address match. It is possible to disable the address matching to let this be handled in software instead. The TWI module will detect START and STOP conditions, bus collisions, and bus errors. Arbitration lost, errors, collision, and clock hold on the bus are also detected and indicated in separate status flags available in both master and slave modes. It is possible to disable the TWI drivers in the device, and enable a four-wire digital interface for connecting to an external TWI bus driver. This can be used for applications where the device operates from a different VCC voltage than used by the TWI bus. XMEGA B [MANUAL] 233 Atmel-8291C-AVR-XMEGA B -09/2014 19.3 General TWI Bus Concepts The TWI provides a simple, bidirectional, two-wire communication bus consisting of a serial clock line (SCL) and a serial data line (SDA). The two lines are open-collector lines (wired-AND), and pull-up resistors (Rp) are the only external components needed to drive the bus. The pull-up resistors provide a high level on the lines when none of the connected devices are driving the bus The TWI bus is a simple and efficient method of interconnecting multiple devices on a serial bus. A device connected to the bus can be a master or slave, where the master controls the bus and all communication. Figure 19-1 on page 233 illustrates the TWI bus topology. Figure 19-1. TWI bus topology. A unique address is assigned to all slave devices connected to the bus, and the master will use this to address a slave and initiate a data transaction. Several masters can be connected to the same bus, called a multi-master environment. An arbitration mechanism is provided for resolving bus ownership among masters, since only one master device may own the bus at any given time. A device can contain both master and slave logic, and can emulate multiple slave devices by responding to more than one address. A master indicates the start of a transaction by issuing a START condition (S) on the bus. An address packet with a slave address (ADDRESS) and an indication whether the master wishes to read or write data (R/W) are then sent. After all data packets (DATA) are transferred, the master issues a STOP condition (P) on the bus to end the transaction. The receiver must acknowledge (A) or not-acknowledge (A) each byte received. Figure 19-2 on page 234 shows a TWI transaction. TWI DEVICE #1 RP RP RS RS SDA SCL VCC TWI DEVICE #2 RS RS TWI DEVICE #N RS RS Note: RS is optional XMEGA B [MANUAL] 234 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 19-2. Basic TWI transaction diagram topology for a 7-bit address bus. The master provides the clock signal for the transaction, but a device connected to the bus is allowed to stretch the lowlevel period of the clock to decrease the clock speed. 19.3.1 Electrical Characteristics The TWI module in XMEGA devices follows the electrical specifications and timing of I2 C bus and SMBus. These specifications are not 100% compliant, and so to ensure correct behavior, the inactive bus timeout period should be set in TWI master mode. Refer to “TWI Master Operation” on page 239 for more details. 19.3.2 START and STOP Conditions Two unique bus conditions are used for marking the beginning (START) and end (STOP) of a transaction. The master issues a START condition (S) by indicating a high-to-low transition on the SDA line while the SCL line is kept high. The master completes the transaction by issuing a STOP condition (P), indicated by a low-to-high transition on the SDA line while SCL line is kept high. Figure 19-3. START and STOP conditions. Multiple START conditions can be issued during a single transaction. A START condition that is not directly following a STOP condition is called a repeated START condition (Sr). 19.3.3 Bit Transfer As illustrated by Figure 19-4, a bit transferred on the SDA line must be stable for the entire high period of the SCL line. Consequently the SDA value can only be changed during the low period of the clock. This is ensured in hardware by the TWI module. S ADDRESS P 6 ... 0 R/W ACK ACK 7 ... 0 DATA ACK/NACK 7 ... 0 DATA SDA SCL S ADDRESS R/W A DATA A DATA A/A P Address Packet Data Packet #0 Transaction Data Packet #1 Direction The slave provides data on the bus The master provides data on the bus The master or slave can provide data on the bus SDA SCL START Condition STOP Condition S P XMEGA B [MANUAL] 235 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 19-4. Data validity. Combining bit transfers results in the formation of address and data packets. These packets consist of eight data bits (one byte) with the most-significant bit transferred first, plus a single-bit not-acknowledge (NACK) or acknowledge (ACK) response. The addressed device signals ACK by pulling the SCL line low during the ninth clock cycle, and signals NACK by leaving the line SCL high. 19.3.4 Address Packet After the START condition, a 7-bit address followed by a read/write (R/W) bit is sent. This is always transmitted by the master. A slave recognizing its address will ACK the address by pulling the data line low for the next SCL cycle, while all other slaves should keep the TWI lines released and wait for the next START and address. The address, R/W bit, and acknowledge bit combined is the address packet. Only one address packet for each START condition is allowed, also when 10-bit addressing is used. The R/W bit specifies the direction of the transaction. If the R/W bit is low, it indicates a master write transaction, and the master will transmit its data after the slave has acknowledged its address. If the R/W bit is high, it indicates a master read transaction, and the slave will transmit its data after acknowledging its address. 19.3.5 Data Packet An address packet is followed by one or more data packets. All data packets are nine bits long, consisting of one data byte and an acknowledge bit. The direction bit in the previous address packet determines the direction in which the data are transferred. 19.3.6 Transaction A transaction is the complete transfer from a START to a STOP condition, including any repeated START conditions in between. The TWI standard defines three fundamental transaction modes: Master write, master read, and a combined transaction. Figure 19-5 on page 235 illustrates the master write transaction. The master initiates the transaction by issuing a START condition (S) followed by an address packet with the direction bit set to zero (ADDRESS+W). Figure 19-5. Master write transaction. Assuming the slave acknowledges the address, the master can start transmitting data (DATA) and the slave will ACK or NACK (A/A) each byte. If no data packets are to be transmitted, the master terminates the transaction by issuing a STOP condition (P) directly after the address packet. There are no limitations to the number of data packets that can be SDA SCL DATA Valid Change Allowed S ADDRESS W A DATA A DATA A/A P Address Packet Data Packet Transaction N data packets XMEGA B [MANUAL] 236 Atmel-8291C-AVR-XMEGA B -09/2014 transferred. If the slave signals a NACK to the data, the master must assume that the slave cannot receive any more data and terminate the transaction. Figure 19-6 on page 236 illustrates the master read transaction. The master initiates the transaction by issuing a START condition followed by an address packet with the direction bit set to one (ADDRESS+R). The addressed slave must acknowledge the address for the master to be allowed to continue the transaction. Figure 19-6. Master read transaction. Assuming the slave acknowledges the address, the master can start receiving data from the slave. There are no limitations to the number of data packets that can be transferred. The slave transmits the data while the master signals ACK or NACK after each data byte. The master terminates the transfer with a NACK before issuing a STOP condition. Figure 19-7 illustrates a combined transaction. A combined transaction consists of several read and write transactions separated by repeated START conditions (Sr). Figure 19-7. Combined Transaction. 19.3.7 Clock and Clock Stretching All devices connected to the bus are allowed to stretch the low period of the clock to slow down the overall clock frequency or to insert wait states while processing data. A device that needs to stretch the clock can do this by holding/forcing the SCL line low after it detects a low level on the line. Three types of clock stretching can be defined, as shown in Figure 19-8. Figure 19-8. Clock stretching(1). Note: 1. Clock stretching is not supported by all I2 C slaves and masters. If a slave device is in sleep mode and a START condition is detected, the clock stretching normally works during the wake-up period. For AVR XMEGA devices, the clock stretching will be either directly before or after the ACK/NACK bit, as AVR XMEGA devices do not need to wake up for transactions that are not addressed to it. A slave device can slow down the bus frequency by stretching the clock periodically on a bit level. This allows the slave to run at a lower system clock frequency. However, the overall performance of the bus will be reduced accordingly. Both S ADDRESS R A DATA A DATA A P Transaction Address Packet Data Packet N data packets S ADDRESS R/W A DATA A/A Sr ADDRESS R/W DATA A/A P Transaction Address Packet #1 N Data Packets Address Packet #2 M Data Packets Direction Direction A SDA SCL S bit 7 bit 6 bit 0 ACK/NACK Periodic clock stretching Random clock stretching Wakeup clock stretching XMEGA B [MANUAL] 237 Atmel-8291C-AVR-XMEGA B -09/2014 the master and slave device can randomly stretch the clock on a byte level basis before and after the ACK/NACK bit. This provides time to process incoming or prepare outgoing data, or perform other time-critical tasks. In the case where the slave is stretching the clock, the master will be forced into a wait state until the slave is ready, and vice versa. 19.3.8 Arbitration A master can start a bus transaction only if it has detected that the bus is idle. As the TWI bus is a multi-master bus, it is possible that two devices may initiate a transaction at the same time. This results in multiple masters owning the bus simultaneously. This is solved using an arbitration scheme where the master loses control of the bus if it is not able to transmit a high level on the SDA line. The masters who lose arbitration must then wait until the bus becomes idle (i.e., wait for a STOP condition) before attempting to reacquire bus ownership. Slave devices are not involved in the arbitration procedure. Figure 19-9. TWI arbitration. Figure 19-9 shows an example where two TWI masters are contending for bus ownership. Both devices are able to issue a START condition, but DEVICE1 loses arbitration when attempting to transmit a high level (bit 5) while DEVICE2 is transmitting a low level. Arbitration between a repeated START condition and a data bit, a STOP condition and a data bit, or a repeated START condition and a STOP condition are not allowed and will require special handling by software. 19.3.9 Synchronization A clock synchronization algorithm is necessary for solving situations where more than one master is trying to control the SCL line at the same time. The algorithm is based on the same principles used for the clock stretching previously described. Figure 19-10 shows an example where two masters are competing for control over the bus clock. The SCL line is the wired-AND result of the two masters clock outputs. DEVICE1_SDA SDA (wired-AND) DEVICE2_SDA SCL S bit 7 bit 6 bit 5 bit 4 DEVICE1 Loses arbitration XMEGA B [MANUAL] 238 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 19-10.Clock synchronization. A high-to-low transition on the SCL line will force the line low for all masters on the bus, and they will start timing their low clock period. The timing length of the low clock period can vary among the masters. When a master (DEVICE1 in this case) has completed its low period, it releases the SCL line. However, the SCL line will not go high until all masters have released it. Consequently, the SCL line will be held low by the device with the longest low period (DEVICE2). Devices with shorter low periods must insert a wait state until the clock is released. All masters start their high period when the SCL line is released by all devices and has gone high. The device which first completes its high period (DEVICE1) forces the clock line low, and the procedure is then repeated. The result is that the device with the shortest clock period determines the high period, while the low period of the clock is determined by the device with the longest clock period. 19.4 TWI Bus State Logic The bus state logic continuously monitors the activity on the TWI bus lines when the master is enabled. It continues to operate in all sleep modes, including power-down. The bus state logic includes START and STOP condition detectors, collision detection, inactive bus timeout detection, and a bit counter. These are used to determine the bus state. Software can get the current bus state by reading the bus state bits in the master status register. The bus state can be unknown, idle, busy, or owner, and is determined according to the state diagram shown in Figure 19-11. The values of the bus state bits according to state are shown in binary in the figure. DEVICE1_SCL SCL (wired-AND) Wait State DEVICE2_SCL High Period Count Low Period Count XMEGA B [MANUAL] 239 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 19-11.Bus state, state diagram. After a system reset and/or TWI master enable, the bus state is unknown. The bus state machine can be forced to enter idle by writing to the bus state bits accordingly. If no state is set by application software, the bus state will become idle when the first STOP condition is detected. If the master inactive bus timeout is enabled, the bus state will change to idle on the occurrence of a timeout. After a known bus state is established, only a system reset or disabling of the TWI master will set the state to unknown. When the bus is idle, it is ready for a new transaction. If a START condition generated externally is detected, the bus becomes busy until a STOP condition is detected. The STOP condition will change the bus state to idle. If the master inactive bus timeout is enabled, the bus state will change from busy to idle on the occurrence of a timeout. If a START condition is generated internally while in idle state, the owner state is entered. If the complete transaction was performed without interference, i.e., no collisions are detected, the master will issue a STOP condition and the bus state will change back to idle. If a collision is detected, the arbitration is assumed lost and the bus state becomes busy until a STOP condition is detected. A repeated START condition will only change the bus state if arbitration is lost during the issuing of the repeated START. Arbitration during repeated START can be lost only if the arbitration has been ongoing since the first START condition. This happens if two masters send the exact same ADDRESS+DATA before one of the masters issues a repeated START (Sr). 19.5 TWI Master Operation The TWI master is byte-oriented, with an optional interrupt after each byte. There are separate interrupts for master write and master read. Interrupt flags can also be used for polled operation. There are dedicated status flags for indicating ACK/NACK received, bus error, arbitration lost, clock hold, and bus state. When an interrupt flag is set, the SCL line is forced low. This will give the master time to respond or handle any data, and will in most cases require software interaction. Figure 19-12 shows the TWI master operation. The diamond shaped symbols (SW) indicate where software interaction is required. Clearing the interrupt flags releases the SCL line. P + Timeout Write ADDRESS IDLE (0b01) S BUSY (0b11) UNKNOWN (0b00) OWNER (0b10) Arbitration Lost Command P Write ADDRESS(Sr) Sr (S) RESET P + Timeout XMEGA B [MANUAL] 240 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 19-12.TWI master operation. The number of interrupts generated is kept to a minimum by automatic handling of most conditions. Quick command and smart mode can be enabled to auto-trigger operations and reduce software complexity. 19.5.1 Transmitting Address Packets After issuing a START condition, the master starts performing a bus transaction when the master address register is written with the 7-bit slave address and direction bit. If the bus is busy, the TWI master will wait until the bus becomes idle before issuing the START condition. Depending on arbitration and the R/W direction bit, one of four distinct cases (M1 to M4) arises following the address packet. The different cases must be handled in software. 19.5.1.1 Case M1: Arbitration lost or bus error during address packet If arbitration is lost during the sending of the address packet, the master write interrupt flag and arbitration lost flag are both set. Serial data output to the SDA line is disabled, and the SCL line is released. The master is no longer allowed to perform any operation on the bus until the bus state has changed back to idle. A bus error will behave in the same way as an arbitration lost condition, but the error flag is set in addition to the write interrupt and arbitration lost flags. 19.5.1.2 Case M2: Address packet transmit complete - Address not acknowledged by slave If no slave device responds to the address, the master write interrupt flag and the master received acknowledge flag are set. The clock hold is active at this point, preventing further activity on the bus. 19.5.1.3 Case M3: Address packet transmit complete - Direction bit cleared If the master receives an ACK from the slave, the master write interrupt flag is set and the master received acknowledge flag is cleared. The clock hold is active at this point, preventing further activity on the bus. BUSY P IDLE S BUSY Sr P M3 M3 M2 M2 M1 M1 R DATA ADDRESS W DATA A/A Wait for IDLE APPLICATION SW SW Sr P M3 M2 SW A BUSY M4 A/A A/A A/A M4 A IDLE IDLE MASTER READ INTERRUPT + HOLD MASTER WRITE INTERRUPT + HOLD SW SW SW R/W BUSY SW Driver software The master provides data on the bus Slave provides data on the bus A A R/W BUSY M4 Bus state Mn Diagram connections XMEGA B [MANUAL] 241 Atmel-8291C-AVR-XMEGA B -09/2014 19.5.1.4 Case M4: Address packet transmit complete - Direction bit set If the master receives an ACK from the slave, the master proceeds to receive the next byte of data from the slave. When the first data byte is received, the master read interrupt flag is set and the master received acknowledge flag is cleared. The clock hold is active at this point, preventing further activity on the bus. 19.5.2 Transmitting Data Packets Assuming case M3 above, the master can start transmitting data by writing to the master data register. If the transfer was successful, the slave will signal with ACK. The master write interrupt flag is set, the master received acknowledge flag is cleared, and the master can prepare new data to send. During data transfer, the master is continuously monitoring the bus for collisions. The received acknowledge flag must be checked by software for each data packet transmitted before the next data packet can be transferred. The master is not allowed to continue transmitting data if the slave signals a NACK. If a collision is detected and the master loses arbitration during transfer, the arbitration lost flag is set. 19.5.3 Receiving Data Packets Assuming case M4 above, the master has already received one byte from the slave. The master read interrupt flag is set, and the master must prepare to receive new data. The master must respond to each byte with ACK or NACK. Indicating a NACK might not be successfully executed, as arbitration can be lost during the transmission. If a collision is detected, the master loses arbitration and the arbitration lost flag is set. 19.6 TWI Slave Operation The TWI slave is byte-oriented with optional interrupts after each byte. There are separate slave data and address/stop interrupts. Interrupt flags can also be used for polled operation. There are dedicated status flags for indicating ACK/NACK received, clock hold, collision, bus error, and read/write direction. When an interrupt flag is set, the SCL line is forced low. This will give the slave time to respond or handle data, and will in most cases require software interaction. Figure 19-13. shows the TWI slave operation. The diamond shapes symbols (SW) indicate where software interaction is required. Figure 19-13.TWI slave operation. The number of interrupts generated is kept to a minimum by automatic handling of most conditions. Quick command can be enabled to auto-trigger operations and reduce software complexity. Promiscuous mode can be enabled to allow the slave to respond to all received addresses. S S3 S2 ADDRESS A S1 R W DATA A/A DATA P S2 Sr S3 P S2 Sr S3 SLAVE ADDRESS INTERRUPT SLAVE DATA INTERRUPT A Collision (SMBus) SW SW SW SW A/A A/A SW Release Hold S1 A S1 SW Interrupt on STOP Condition Enabled S1 SW Driver software The master provides data on the bus Slave provides data on the bus Sn Diagram connections XMEGA B [MANUAL] 242 Atmel-8291C-AVR-XMEGA B -09/2014 19.6.1 Receiving Address Packets When the TWI slave is properly configured, it will wait for a START condition to be detected. When this happens, the successive address byte will be received and checked by the address match logic, and the slave will ACK a correct address and store the address in the DATA register. If the received address is not a match, the slave will not acknowledge and store address, and will wait for a new START condition. The slave address/stop interrupt flag is set when a START condition succeeded by a valid address byte is detected. A general call address will also set the interrupt flag. A START condition immediately followed by a STOP condition is an illegal operation, and the bus error flag is set. The R/W direction flag reflects the direction bit received with the address. This can be read by software to determine the type of operation currently in progress. Depending on the R/W direction bit and bus condition, one of four distinct cases (S1 to S4) arises following the address packet. The different cases must be handled in software. 19.6.1.1 Case S1: Address packet accepted - Direction bit set If the R/W direction flag is set, this indicates a master read operation. The SCL line is forced low by the slave, stretching the bus clock. If ACK is sent by the slave, the slave hardware will set the data interrupt flag indicating data is needed for transmit. Data, repeated START, or STOP can be received after this. If NACK is sent by the slave, the slave will wait for a new START condition and address match. 19.6.1.2 Case S2: Address packet accepted - Direction bit cleared If the R/W direction flag is cleared, this indicates a master write operation. The SCL line is forced low, stretching the bus clock. If ACK is sent by the slave, the slave will wait for data to be received. Data, repeated START, or STOP can be received after this. If NACK is sent, the slave will wait for a new START condition and address match. 19.6.1.3 Case S3: Collision If the slave is not able to send a high level or NACK, the collision flag is set, and it will disable the data and acknowledge output from the slave logic. The clock hold is released. A START or repeated START condition will be accepted. 19.6.1.4 Case S4: STOP condition received. When the STOP condition is received, the slave address/stop flag will be set, indicating that a STOP condition, and not an address match, occurred. 19.6.2 Receiving Data Packets The slave will know when an address packet with R/W direction bit cleared has been successfully received. After acknowledging this, the slave must be ready to receive data. When a data packet is received, the data interrupt flag is set and the slave must indicate ACK or NACK. After indicating a NACK, the slave must expect a STOP or repeated START condition. 19.6.3 Transmitting Data Packets The slave will know when an address packet with R/W direction bit set has been successfully received. It can then start sending data by writing to the slave data register. When a data packet transmission is completed, the data interrupt flag is set. If the master indicates NACK, the slave must stop transmitting data and expect a STOP or repeated START condition. 19.7 Enabling External Driver Interface An external driver interface can be enabled. When this is done, the internal TWI drivers with input filtering and slew rate control are bypassed. The normal I/O pin function is used, and the direction must be configured by the user software. When this mode is enabled, an external TWI compliant tri-state driver is needed for connecting to a TWI bus. By default, port pins 0 (Pn0) and 1 (Pn1) are used for SDA and SCL. The external driver interface uses port pins 0 to 3 for the SDA_IN, SCL_IN, SDA_OUT, and SCL_OUT signals. XMEGA B [MANUAL] 243 Atmel-8291C-AVR-XMEGA B -09/2014 19.8 Register Description – TWI 19.8.1 CTRL – Common Control Register z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2:1 – SDAHOLD[1:0]: SDA Hold Time Enable. Setting these bits to one enables an internal hold time on SDA with respect to the negative edge of SCL. Table 19-1. SDA hold time. z Bit 0 – EDIEN: External Driver Interface Enable Setting this bit enables the use of the external driver interface, and clearing this bit enables normal two-wire mode. See Table 19-2 for details. Table 19-2. External driver interface enable. Bit 7 6 5 4 3 2 1 0 +0x00 – – – – – SDAHOLD[1:0] EDIEN Read/Write R R R R R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 SDAHOLD[1:0] Group Configuration Description 00 OFF SDA hold time off 01 50NS Typical 50ns hold time 10 300NS Typical 100ns hold time 11 400NS Typical 400ns hold time EDIEN Mode Comment 0 Normal TWI Two-pin interface, slew rate control, and input filter. 1 External driver interface Four-pin interface, standard I/O, no slew rate control, and no input filter. XMEGA B [MANUAL] 244 Atmel-8291C-AVR-XMEGA B -09/2014 19.9 Register Description – TWI Master 19.9.1 CTRLA – Control register A z Bit 7:6 – INTLVL[1:0]: Interrupt Level These bits select the interrupt level for the TWI master interrupt, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. z Bit 5 – RIEN: Read Interrupt Enable Setting the read interrupt enable (RIEN) bit enables the read interrupt when the read interrupt flag (RIF) in the STATUS register is set. In addition the INTLVL bits must be nonzero for TWI master interrupts to be generated. z Bit 4 – WIEN: Write Interrupt Enable Setting the write interrupt enable (WIEN) bit enables the write interrupt when the write interrupt flag (WIF) in the STATUS register is set. In addition the INTLVL bits must be nonzero for TWI master interrupts to be generated. z Bit 3 – ENABLE: Enable TWI Master Setting the enable TWI master (ENABLE) bit enables the TWI master. z Bit 2:0 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. 19.9.2 CTRLB – Control register B z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:2 – TIMEOUT[1:0]: Inactive Bus Timeout Setting the inactive bus timeout (TIMEOUT) bits to a nonzero value will enable the inactive bus timeout supervisor. If the bus is inactive for longer than the TIMEOUT setting, the bus state logic will enter the idle state. Table 19-3 lists the timeout settings. Bit 7 6 5 4 3 2 1 0 +0x00 INTLVL[1:0] RIEN WIEN ENABLE – – – Read/Write R/W R/W R/W R/W R/W R R R Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x01 – – – – TIMEOUT[1:0] QCEN SMEN Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 245 Atmel-8291C-AVR-XMEGA B -09/2014 Table 19-3. TWI master inactive bus timeout settings. z Bit 1 – QCEN: Quick Command Enable When quick command is enabled, the corresponding interrupt flag is set immediately after the slave acknowledges the address (read or write interrupt). At this point, software can issue either a STOP or a repeated START condition. z Bit 0 – SMEN: Smart Mode Enable Setting this bit enables smart mode. When smart mode is enabled, the acknowledge action, as set by the ACKACT bit in the CTRLC register, is sent immediately after reading the DATA register. 19.9.3 CTRLC – Control register C z Bits 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2 – ACKACT: Acknowledge Action This bit defines the master's acknowledge behavior in master read mode. The acknowledge action is executed when a command is written to the CMD bits. If SMEN in the CTRLB register is set, the acknowledge action is performed when the DATA register is read. Table 19-4 lists the acknowledge actions. Table 19-4. ACKACT bit description. z Bit 1:0 – CMD[1:0]: Command Writing the command (CMD) bits triggers a master operation as defined by Table 19-5. The CMD bits are strobe bits, and always read as zero. The acknowledge action is only valid in master read mode (R). In master write mode (W), a command will only result in a repeated START or STOP condition. The ACKACT bit and the CMD bits can be written at the same time, and then the acknowledge action will be updated before the command is triggered. TIMEOUT[1:0] Group Configuration Description 00 DISABLED Disabled, normally used for I2 C 01 50US 50μs, normally used for SMBus at 100kHz 10 100US 100μs 11 200US 200μs Bit 7 6 5 4 3 2 1 0 +0x02 – – – – – ACKACT CMD[1:0] Read/Write R R R R R R/W R/W R/W Initial Value 00000000 ACKACT Action 0 Send ACK 1 Send NACK XMEGA B [MANUAL] 246 Atmel-8291C-AVR-XMEGA B -09/2014 Table 19-5. CMD bit description. Writing a command to the CMD bits will clear the master interrupt flags and the CLKHOLD flag. 19.9.4 STATUS – Status register z Bit 7 – RIF: Read Interrupt Flag This flag is set when a byte is successfully received in master read mode; i.e., no arbitration was lost or bus error occurred during the operation. Writing a one to this bit location will clear RIF. When this flag is set, the master forces the SCL line low, stretching the TWI clock period. Clearing the interrupt flags will release the SCL line. This flag is also cleared automatically when: z Writing to the ADDR register z Writing to the DATA register z Reading the DATA register z Writing a valid command to the CMD bits in the CTRLC register z Bit 6 – WIF: Write Interrupt Flag This flag is set when a byte is transmitted in master write mode. The flag is set regardless of the occurrence of a bus error or an arbitration lost condition. WIF is also set if arbitration is lost during sending of a NACK in master read mode, and if issuing a START condition when the bus state is unknown. Writing a one to this bit location will clear WIF. When this flag is set, the master forces the SCL line low, stretching the TWI clock period. Clearing the interrupt flags will release the SCL line. The flag is also cleared automatically for the same conditions as RIF. z Bit 5 – CLKHOLD: Clock Hold This flag is set when the master is holding the SCL line low. This is a status flag and a read-only flag that is set when RIF or WIF is set. Clearing the interrupt flags and releasing the SCL line will indirectly clear this flag. The flag is also cleared automatically for the same conditions as RIF. CMD[1:0] Group Configuration MODE Operation 00 NOACT X Reserved 01 START X Execute acknowledge action succeeded by repeated START condition 10 BYTEREC W No operation R Execute acknowledge action succeeded by a byte receive 11 STOP X Execute acknowledge action succeeded by issuing a STOP condition Bit 7 6 5 4 3 2 1 0 +0x03 RIF WIF CLKHOLD RXACK ARBLOST BUSERR BUSSTATE[1:0] Read/Write R/W R/W R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 247 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 4 – RXACK: Received Acknowledge This flag contains the most recently received acknowledge bit from the slave. This is a read-only flag. When read as zero, the most recent acknowledge bit from the slave was ACK, and when read as one the most recent acknowledge bit was NACK. z Bit 3 – ARBLOST: Arbitration Lost This flag is set if arbitration is lost while transmitting a high data bit or a NACK bit, or while issuing a START or repeated START condition on the bus. Writing a one to this bit location will clear ARBLOST. Writing the ADDR register will automatically clear ARBLOST. z Bit 2 – BUSERR: Bus Error This flag is set if an illegal bus condition has occurred. An illegal bus condition occurs if a repeated START or a STOP condition is detected, and the number of received or transmitted bits from the previous START condition is not a multiple of nine. Writing a one to this bit location will clear BUSERR. Writing the ADDR register will automatically clear BUSERR. z Bit 1:0 – BUSSTATE[1:0]: Bus State These bits indicate the current TWI bus state as defined in Table 19-6. The change of bus state is dependent on bus activity. Refer to the “TWI Bus State Logic” on page 238. Table 19-6. TWI master bus state. Writing 01 to the BUSSTATE bits forces the bus state logic into the idle state. The bus state logic cannot be forced into any other state. When the master is disabled, and after reset, the bus state logic is disabled and the bus state is unknown. 19.9.5 BAUD – Baud Rate register The baud rate (BAUD) register defines the relation between the system clock and the TWI bus clock (SCL) frequency. The frequency relation can be expressed by using the following equation: [1] The BAUD register must be set to a value that results in a TWI bus clock frequency (fTWI) equal or less than 100kHz or 400kHz, depending on which standard the application should comply with. The following equation [2] expresses equation [1] solved for the BAUD value: BUSSTATE[1:0] Group Configuration Description 00 UNKNOWN Unknown bus state 01 IDLE Idle bus state 10 OWNER Owner bus state 11 BUSY Busy bus state Bit 7 6 5 4 3 2 1 0 +0x04 BAUD[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 00000 f TWI f sys 2(5 + ( ) BAUD ) = ---------------------------------------[Hz] XMEGA B [MANUAL] 248 Atmel-8291C-AVR-XMEGA B -09/2014 [2] The BAUD register should be written only while the master is disabled. 19.9.6 ADDR – Address register When the address (ADDR) register is written with a slave address and the R/W bit while the bus is idle, a START condition is issued and the 7-bit slave address and the R/W bit are transmitted on the bus. If the bus is already owned when ADDR is written, a repeated START is issued. If the previous transaction was a master read and no acknowledge is sent yet, the acknowledge action is sent before the repeated START condition. After completing the operation and the acknowledge bit from the slave is received, the SCL line is forced low if arbitration was not lost. WIF is set. If the bus state is unknown when ADDR is written, WIF is set and BUSERR is set. All TWI master flags are automatically cleared when ADDR is written. This includes BUSERR, ARBLOST, RIF, and WIF. The master ADDR can be read at any time without interfering with ongoing bus activity. 19.9.7 DATA – Data register The data (DATA) register is used when transmitting and receiving data. During data transfer, data are shifted from/to the DATA register and to/from the bus. This implies that the DATA register cannot be accessed during byte transfers, and this is prevented by hardware. The DATA register can only be accessed when the SCL line is held low by the master; i.e., when CLKHOLD is set. In master write mode, writing the DATA register will trigger a data byte transfer followed by the master receiving the acknowledge bit from the slave. WIF and CLKHOLD are set. In master read mode, RIF and CLKHOLD are set when one byte is received in the DATA register. If smart mode is enabled, reading the DATA register will trigger the bus operation as set by the ACKACT bit. If a bus error occurs during reception, WIF and BUSERR are set instead of RIF. Accessing the DATA register will clear the master interrupt flags and CLKHOLD. BAUD f sys 2 f TWI = ---------------- – 5 Bit 7 6 5 4 3 2 1 0 +0x05 ADDR[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x06 DATA[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 249 Atmel-8291C-AVR-XMEGA B -09/2014 19.10 Register Description – TWI Slave 19.10.1 CTRLA – Control register A z Bit 7:6 – INTLVL[1:0]: Interrupt Level These bits select the interrupt level for the TWI master interrupt, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. z Bit 5 – DIEN: Data Interrupt Enable Setting the data interrupt enable (DIEN) bit enables the data interrupt when the data interrupt flag (DIF) in the STATUS register is set. The INTLVL bits must be nonzero for the interrupt to be generated. z Bit 4 – APIEN: Address/Stop Interrupt Enable Setting the address/stop interrupt enable (APIEN) bit enables the address/stop interrupt when the address/stop interrupt flag (APIF) in the STATUS register is set. The INTLVL bits must be nonzero for interrupt to be generated. z Bit 3 – ENABLE: Enable TWI Slave Setting this bit enables the TWI slave. z Bit 2 – PIEN: Stop Interrupt Enable Setting the this bit will cause APIF in the STATUS register to be set when a STOP condition is detected. z Bit 1 – PMEN: Promiscuous Mode Enable By setting the this bit, the slave address match logic responds to all received addresses. If this bit is cleared, the address match logic uses the ADDR register to determine which address to recognize as its own address. z Bit 0 – SMEN: Smart Mode Enable This bit enables smart mode. When Smart mode is enabled, the acknowledge action, as set by the ACKACT bit in the CTRLB register, is sent immediately after reading the DATA register. 19.10.2 CTRLB – Control register B z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2 – ACKACT: Acknowledge Action This bit defines the slave's acknowledge behavior after an address or data byte is received from the master. The acknowledge action is executed when a command is written to the CMD bits. If the SMEN bit in the CTRLA register is set, the acknowledge action is performed when the DATA register is read. Table 19-7 lists the acknowledge actions. Bit 7 6 5 4 3 2 1 0 +0x00 INTLVL[1:0] DIEN APIEN ENABLE PIEN PMEN SMEN Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0000 0 0 Bit 7 6 5 4 3 2 1 0 +0x01 – – – – – ACKACT CMD[1:0] Read/Write R R R R R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 250 Atmel-8291C-AVR-XMEGA B -09/2014 Table 19-7. TWI slave acknowledge actions. z Bit 1:0 – CMD[1:0]: Command Writing these bits trigger the slave operation as defined by Table 19-8. The CMD bits are strobe bits and always read as zero. The operation is dependent on the slave interrupt flags, DIF and APIF. The acknowledge action is only executed when the slave receives data bytes or address byte from the master. Table 19-8. TWI slave command. Writing the CMD bits will automatically clear the slave interrupt flags and CLKHOLD, and release the SCL line. The ACKACT bit and CMD bits can be written at the same time, and then the acknowledge action will be updated before the command is triggered. ACKACT Action 0 Send ACK 1 Send NACK CMD[1:0] Group Configuration DIR Operation 00 NOACT X No action 01 X Reserved 10 COMPLETE Used to complete transaction 0 Execute acknowledge action succeeded by waiting for any START (S/Sr) condition 1 Wait for any START (S/Sr) condition 11 RESPONSE Used in response to an address byte (APIF is set) 0 Execute acknowledge action succeeded by reception of next byte 1 Execute acknowledge action succeeded by DIF being set Used in response to a data byte (DIF is set) 0 Execute acknowledge action succeeded by waiting for the next byte 1 No operation XMEGA B [MANUAL] 251 Atmel-8291C-AVR-XMEGA B -09/2014 19.10.3 STATUS – Status register z Bit 7 – DIF: Data Interrupt Flag This flag is set when a data byte is successfully received; i.e., no bus error or collision occurred during the operation. Writing a one to this bit location will clear DIF. When this flag is set, the slave forces the SCL line low, stretching the TWI clock period. Clearing the interrupt flags will release the SCL line. This flag is also cleared automatically when writing a valid command to the CMD bits in the CTRLB register z Bit 6 – APIF: Address/Stop Interrupt Flag This flag is set when the slave detects that a valid address has been received, or when a transmit collision is detected. If the PIEN bit in the CTRLA register is set, a STOP condition on the bus will also set APIF. Writing a one to this bit location will clear APIF. When set for an address interrupt, the slave forces the SCL line low, stretching the TWI clock period. Clearing the interrupt flags will release the SCL line. The flag is also cleared automatically for the same condition as DIF. z Bit 5 – CLKHOLD: Clock Hold This flag is set when the slave is holding the SCL line low.This is a status flag and a read-only bit that is set when DIF or APIF is set. Clearing the interrupt flags and releasing the SCL line will indirectly clear this flag. z Bit 4 – RXACK: Received Acknowledge This flag contains the most recently received acknowledge bit from the master. This is a read-only flag. When read as zero, the most recent acknowledge bit from the maser was ACK, and when read as one, the most recent acknowledge bit was NACK. z Bit 3 – COLL: Collision This flag is set when a slave has not been able to transfer a high data bit or a NACK bit. If a collision is detected, the slave will commence its normal operation, disable data, and acknowledge output, and no low values will be shifted out onto the SDA line. Writing a one to this bit location will clear COLL. The flag is also cleared automatically when a START or repeated START condition is detected. z Bit 2 – BUSERR: TWI Slave Bus Error This flag is set when an illegal bus condition occurs during a transfer. An illegal bus condition occurs if a repeated START or a STOP condition is detected, and the number of bits from the previous START condition is not a multiple of nine. Writing a one to this bit location will clear BUSERR. For bus errors to be detected, the bus state logic must be enabled. This is done by enabling the TWI master. z Bit 1 – DIR: Read/Write Direction The R/W direction (DIR) flag reflects the direction bit from the last address packet received from a master. When this bit is read as one, a master read operation is in progress. When read as zero, a master write operation is in progress. z Bit 0 – AP: Slave Address or Stop This flag indicates whether a valid address or a STOP condition caused the last setting of APIF in the STATUS register. Table 19-9. TWI slave address or stop. Bit 7 6 5 4 3 2 1 0 +0x02 DIF APIF CLKHOLD RXACK COLL BUSERR DIR AP Read/Write R/W R/W R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 AP Description 0 A STOP condition generated the interrupt on APIF 1 Address detection generated the interrupt on APIF XMEGA B [MANUAL] 252 Atmel-8291C-AVR-XMEGA B -09/2014 19.10.4 ADDR – Address register The TWI slave address register should be loaded with the 7-bit slave address (in the seven most significant bits of ADDR) to which the TWI will respond. The lsb of ADDR is used to enable recognition of the general call address (0x00). z Bit 7:1 – ADDR[7:1]: TWI Slave Address This register contains the TWI slave address used by the slave address match logic to determine if a master has addressed the slave. The seven most-significant bits (ADDR[7:1]) represent the slave address. When using 10-bit addressing, the address match logic only supports hardware address recognition of the first byte of a 10-bit address. By setting ADDR[7:1] = 0b11110nn, ”nn” represents bits 9 and 8 of the slave address. The next byte received is bits 7 to 0 in the 10-bit address, and this must be handled by software. When the address match logic detects that a valid address byte is received, APIF is set and the DIR flag is updated. If the PMEN bit in CTRLA is set, the address match logic responds to all addresses transmitted on the TWI bus. The ADDR register is not used in this mode. z Bit 0 – ADDR: General Call Recognition Enable When ADDR[0] is set, this enables general call address recognition logic so the device can respond to a general address call that addresses all devices on the bus. 19.10.5 DATA – Data register The data (DATA) register is used when transmitting and received data. During data transfer, data are shifted from/to the DATA register and to/from the bus. This implies that the DATA register cannot be accessed during byte transfers, and this is prevented by hardware. The DATA register can be accessed only when the SCL line is held low by the slave; i.e., when CLKHOLD is set. When a master is reading data from the slave, data to send must be written to the DATA register. The byte transfer is started when the master starts to clock the data byte from the slave, followed by the slave receiving the acknowledge bit from the master. DIF and CLKHOLD are set. When a master writes data to the slave, DIF and CLKHOLD are set when one byte has been received in the DATA register. If smart mode is enabled, reading the DATA register will trigger the bus operation as set by the ACKACT bit. Accessing the DATA register will clear the slave interrupt flags and CLKHOLD. When an address match occurs, the received address will be stored in the DATA register. Bit 7 6 5 4 3 2 1 0 +0x03 ADDR[7:1] ADDR[0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 Bit 7 6 5 4 3 2 1 0 +0x04 DATA[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 253 Atmel-8291C-AVR-XMEGA B -09/2014 19.10.6 ADDRMASK – Address Mask register z Bit 7:1 – ADDRMASK[7:1]: Address Mask These bits can act as a second address match register or as an address mask register, depending on the ADDREN setting. If ADDREN is set to zero, ADDRMASK can be loaded with a 7-bit slave address mask. Each bit in ADDRMASK can mask (disable) the corresponding address bit in the ADDR register. If the mask bit is one, the address match between the incoming address bit and the corresponding bit in ADDR is ignored; i.e., masked bits will always match. If ADDREN is set to one, ADDRMASK can be loaded with a second slave address in addition to the ADDR register. In this mode, the slave will match on two unique addresses, one in ADDR and the other in ADDRMASK. z Bit 0 – ADDREN: Address Enable By default, this bit is zero, and the ADDRMASK bits acts as an address mask to the ADDR register. If this bit is set to one, the slave address match logic responds to the two unique addresses in ADDR and ADDRMASK. Bit 7 6 5 4 3 2 1 0 +0x05 ADDRMASK[7:1] ADDREN Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 254 Atmel-8291C-AVR-XMEGA B -09/2014 19.11 Register Summary - TWI 19.12 Register Summary - TWI Master 19.13 Register Summary - TWI Slave 19.14 Interrupt Vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL – – – – – SDAHOLD[1:0] EDIEN 243 +0x01 MASTER Offset address for TWI Master +0x08 SLAVE Offset address for TWI Slave Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRLA INTLVL[1:0] RIEN WIEN ENABLE – – – 244 +0x01 CTRLB – – – – TIMEOUT[1:0] QCEN SMEN 244 +0x02 CTRLC – – – – – ACKACT CMD[1:0] 245 +0x03 STATUS RIF WIF CLKHOLD RXACK ARBLOST BUSERR BUSSTATE[1:0] 246 +0x04 BAUD BAUD[7:0] 247 +0x05 ADDR ADDR[7:0] 248 +0x06 DATA DATA[7:0] 248 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRLA INTLVL[1:0] DIEN APIEN ENABLE PIEN TPMEN SMEN 249 +0x01 CTRLB – – – – – ACKACT CMD[1:0] 249 +0x02 STATUS DIF APIF CLKHOLD RXACK COLL BUSERR DIR AP 251 +0x03 ADDR ADDR[7:0] 252 +0x04 DATA DATA[7:0] 252 +0x05 ADDRMAS ADDRMASK[7:1] ADDREN 253 Offset Source Interrupt Description 0x00 SLAVE_vect TWI slave interrupt vector 0x02 MASTER_vect TWI master interrupt vector XMEGA B [MANUAL] 255 8291C–AVR–09/2014 20. SPI – Serial Peripheral Interface 20.1 Features z Full-duplex, three-wire synchronous data transfer z Master or slave operation z Lsb first or msb first data transfer z Eight programmable bit rates z Interrupt flag at the end of transmission z Write collision flag to indicate data collision z Wake up from idle sleep mode z Double speed master mode 20.2 Overview The Serial Peripheral Interface (SPI) is a high-speed synchronous data transfer interface using three or four pins. It allows fast communication between an XMEGA device and peripheral devices or between several microcontrollers. The SPI supports full-duplex communication. A device connected to the bus must act as a master or slave.The master initiates and controls all data transactions. The interconnection between master and slave devices with SPI is shown in Figure 20-1 on page 255. The system consists of two shift registers and a master clock generator. The SPI master initiates the communication cycle by pulling the slave select (SS) signal low for the desired slave. Master and slave prepare the data to be sent in their respective shift registers, and the master generates the required clock pulses on the SCK line to interchange data. Data are always shifted from master to slave on the master output, slave input (MOSI) line, and from slave to master on the master input, slave output (MISO) line. After each data packet, the master can synchronize the slave by pulling the SS line high. Figure 20-1. SPI master-slave interconnection. The SPI module is unbuffered in the transmit direction and single buffered in the receive direction. This means that bytes to be transmitted cannot be written to the SPI DATA register before the entire shift cycle is completed. When receiving data, a received character must be read from the DATA register before the next character has been completely shifted in. Otherwise, the first byte will be lost. In SPI slave mode, the control logic will sample the incoming signal on the SCK pin. To ensure correct sampling of this clock signal, the minimum low and high periods must each be longer than two CPU clock cycles. When the SPI module is enabled, the data direction of the MOSI, MISO, SCK, and SS pins is overridden according to Table 20-1. The pins with user-defined direction must be configured from software to have the correct direction according to the application. SHIFT ENABLE XMEGA B [MANUAL] 256 8291C–AVR–09/2014 Table 20-1. SPI pin override and directions. 20.3 Master Mode In master mode, the SPI interface has no automatic control of the SS line. If the SS pin is used, it must be configured as output and controlled by user software. If the bus consists of several SPI slaves and/or masters, a SPI master can use general purpose I/O pins to control the SS line to each of the slaves on the bus. Writing a byte to the DATA register starts the SPI clock generator and the hardware shifts the eight bits into the selected slave. After shifting one byte, the SPI clock generator stops and the SPI interrupt flag is set. The master may continue to shift the next byte by writing new data to the DATA register, or can signal the end of the transfer by pulling the SS line high. The last incoming byte will be kept in the buffer register. If the SS pin is not used and is configured as input, it must be held high to ensure master operation. If the SS pin is set as input and is being driven low, the SPI module will interpret this as another master trying to take control of the bus. To avoid bus contention, the master will take the following action: 1. The master enters slave mode. 2. The SPI interrupt flag is set. 20.4 Slave Mode In slave mode, the SPI module will remain sleeping with the MISO line tri-stated as long as the SS pin is driven high. In this state, software may update the contents of the DATA register, but the data will not be shifted out by incoming clock pulses on the SCK pin until the SS pin is driven low. If SS is driven low, the slave will start to shift out data on the first SCK clock pulse. When one byte has been completely shifted, the SPI interrupt flag is set. The slave may continue placing new data to be sent into the DATA register before reading the incoming data. The last incoming byte will be kept in the buffer register. When SS is driven high, the SPI logic is reset, and the SPI slave will not receive any new data. Any partially received packet in the shift register will be dropped. As the SS pin is used to signal the start and end of a transfer, it is also useful for doing packet/byte synchronization, keeping the slave bit counter synchronous with the master clock generator. 20.5 Data Modes There are four combinations of SCK phase and polarity with respect to serial data. The SPI data transfer formats are shown in Figure 20-2. Data bits are shifted out and latched in on opposite edges of the SCK signal, ensuring sufficient time for data signals to stabilize. The leading edge is the first clock edge of a clock cycle. The trailing edge is the last clock edge of a clock cycle. Pin Master Mode Slave Mode MOSI User defined Input MISO Input User defined SCK User defined Input SS User defined Input XMEGA B [MANUAL] 257 8291C–AVR–09/2014 Figure 20-2. SPI transfer modes. 20.6 DMA Support DMA support on the SPI module is available only in slave mode. The SPI slave can trigger a DMA transfer as one byte has been shifted into the DATA register. It is possible, however, to use the XMEGA USART in SPI mode and then have DMA support in master mode. For details, refer to “USART in Master SPI Mode” on page 273. Bit 1 Bit 6 LSB MSB Mode 0 SAMPLE I MOSI/MISO CHANGE 0 MOSI PIN CHANGE 0 MISO PIN Mode 2 SS MSB LSB Bit 6 Bit 1 Bit 5 Bit 2 Bit 4 Bit 3 Bit 3 Bit 4 Bit 2 Bit 5 MSB first (DORD = 0) LSB first (DORD = 1) Mode 1 SAMPLE I MOSI/MISO CHANGE 0 MOSI PIN CHANGE 0 MISO PIN Mode 3 SS MSB LSB Bit 6 Bit 1 Bit 5 Bit 2 Bit 4 Bit 3 Bit 3 Bit 4 Bit 2 Bit 5 Bit 1 Bit 6 LSB MSB MSB first (DORD = 0) LSB first (DORD = 1) XMEGA B [MANUAL] 258 8291C–AVR–09/2014 20.7 Register Description 20.7.1 CTRL – Control register z Bit 7 – CLK2X: Clock Double When this bit is set, the SPI speed (SCK frequency) will be doubled in master mode (see Table 20-3 on page 259). z Bit 6 – ENABLE: Enable Setting this bit enables the SPI module. This bit must be set to enable any SPI operations. z Bit 5 – DORD: Data Order DORD decides the data order when a byte is shifted out from the DATA register. When DORD is written to one, the leastsignificant bit (lsb) of the data byte is transmitted first, and when DORD is written to zero, the most-significant bit (msb) of the data byte is transmitted first. z Bit 4 – MASTER: Master Select This bit selects master mode when written to one, and slave mode when written to zero. If SS is configured as an input and driven low while master mode is set, master mode will be cleared. z Bit 3:2 – MODE[1:0]: Transfer Mode These bits select the transfer mode. The four combinations of SCK phase and polarity with respect to the serial data are shown in Table 20-2. These bits decide whether the first edge of a clock cycle (leading edge) is rising or falling, and whether data setup and sample occur on the leading or trailing edge. When the leading edge is rising, the SCK signal is low when idle, and when the leading edge is falling, the SCK signal is high when idle. Table 20-2. SPI transfer mode z Bits 1:0 – PRESCALER[1:0]: Clock Prescaler These two bits control the SPI clock rate configured in master mode. These bits have no effect in slave mode. The relationship between SCK and the peripheral clock frequency ( clkPER) is shown in Table 20-3. Bit 7 6 5 4 3 2 1 0 +0x00 CLK2X ENABLE DORD MASTER MODE[1:0] PRESCALER[1:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 MODE[1:0] Group Configuration Leading Edge Trailing Edge 00 0 Rising, sample Falling, setup 01 1 Rising, setup Falling, sample 10 2 Falling, sample Rising, setup 11 3 Falling, setup Rising, sample XMEGA B [MANUAL] 259 8291C–AVR–09/2014 Table 20-3. Relationship between SCK and the peripheral clock (ClkPER) frequency. 20.7.2 INTCTRL – Interrupt Control register z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1:0 – INTLVL[1:0]: Interrupt Level These bits enable the SPI interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will be triggered when IF in the STATUS register is set. 20.7.3 STATUS – Status register z Bit 7 – IF: Interrupt Flag This flag is set when a serial transfer is complete and one byte is completely shifted in/out of the DATA register. If SS is configured as input and is driven low when the SPI is in master mode, this will also set this flag. IF is cleared by hardware when executing the corresponding interrupt vector. Alternatively, the IF flag can be cleared by first reading the STATUS register when IF is set, and then accessing the DATA register. z Bit 6 – WRCOL: Write Collision Flag The WRCOL flag is set if the DATA register is written during a data transfer. This flag is cleared by first reading the STATUS register when WRCOL is set, and then accessing the DATA register. z Bit 5:0 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. CLK2X PRESCALER[1:0] SCK Frequency 0 00 ClkPER/4 0 01 ClkPER/16 0 10 ClkPER/64 0 11 ClkPER/128 1 00 ClkPER/2 1 01 ClkPER/8 1 10 ClkPER/32 1 11 ClkPER/64 Bit 7 6 5 4 3 2 1 0 +0x01 – – – – – – INTLVL[1:0] Read/Write R R R R R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x02 IF WRCOL – – – – – – Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 260 8291C–AVR–09/2014 20.7.4 DATA – Data register The DATA register is used for sending and receiving data. Writing to the register initiates the data transmission, and the byte written to the register will be shifted out on the SPI output line. Reading the register causes the shift register receive buffer to be read, returning the last byte successfully received. 20.8 Register Summary 20.9 Interrupt vector Summary Bit 7 6 5 4 3 2 1 0 +0x03 DATA[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL CLK2X ENABLE DORD MASTER MODE[1:0] PRESCALER[1:0] 258 +0x01 INTCTRL – – – – – – INTLVL[1:0] 259 +0x02 STATUS IF WRCOL – – – – – – 259 +0x03 DATA DATA[7:0] 260 Offset Source Interrupt Description 0x00 SPI_vect SPI interrupt vector XMEGA B [MANUAL] 261 8291C–AVR–09/2014 21. USART 21.1 Features z Full-duplex operation z Asynchronous or synchronous operation z Synchronous clock rates up to 1/2 of the device clock frequency z Asynchronous clock rates up to 1/8 of the device clock frequency z Supports serial frames with 5, 6, 7, 8, or 9 data bits and 1 or 2 stop bits z Fractional baud rate generator z Can generate desired baud rate from any system clock frequency z No need for external oscillator with certain frequencies z Built-in error detection and correction schemes z Odd or even parity generation and parity check z Data overrun and framing error detection z Noise filtering includes false start bit detection and digital low-pass filter z Separate interrupts for z Transmit complete z Transmit data register empty z Receive complete z Multiprocessor communication mode z Addressing scheme to address a specific devices on a multi-device bus z Enable unaddressed devices to automatically ignore all frames z Master SPI mode z Double buffered operation z Configurable data order z Operation up to 1/2 of the peripheral clock frequency z IRCOM module for IrDA compliant pulse modulation/demodulation 21.2 Overview The universal synchronous and asynchronous serial receiver and transmitter (USART) is a fast and flexible serial communication module. The USART supports full-duplex communication and asynchronous and synchronous operation. The USART can be configured to operate in SPI master mode and used for SPI communication. Communication is frame based, and the frame format can be customized to support a wide range of standards. The USART is buffered in both directions, enabling continued data transmission without any delay between frames. Separate interrupts for receive and transmit complete enable fully interrupt driven communication. Frame error and buffer overflow are detected in hardware and indicated with separate status flags. Even or odd parity generation and parity check can also be enabled. A block diagram of the USART is shown in Figure 21-1 on page 262. The main functional blocks are the clock generator, the transmitter, and the receiver, which are indicated in dashed boxes. XMEGA B [MANUAL] 262 8291C–AVR–09/2014 Figure 21-1. USART block diagram. The clock generator includes a fractional baud rate generator that is able to generate a wide range of USART baud rates from any system clock frequencies. This removes the need to use an external crystal oscillator with a specific frequency to achieve a required baud rate. It also supports external clock input in synchronous slave operation. The transmitter consists of a single write buffer (DATA), a shift register, and a parity generator. The write buffer allows continuous data transmission without any delay between frames. The receiver consists of a two-level receive buffer (DATA) and a shift register. Data and clock recovery units ensure robust synchronization and noise filtering during asynchronous data reception. It includes frame error, buffer overflow, and parity error detection. When the USART is set in master SPI mode, all USART-specific logic is disabled, leaving the transmit and receive buffers, shift registers, and baud rate generator enabled. Pin control and interrupt generation are identical in both modes. The registers are used in both modes, but their functionality differs for some control settings. An IRCOM module can be enabled for one USART to support IrDA 1.4 physical compliant pulse modulation and demodulation for baud rates up to 115.2kbps. For details, refer to “IRCOM - IR Communication Module” on page 282. 21.3 Clock Generation The clock used for baud rate generation and for shifting and sampling data bits is generated internally by the fractional baud rate generator or externally from the transfer clock (XCK) pin. Five modes of clock generation are supported: normal and double-speed asynchronous mode, master and slave synchronous mode, and master SPI mode. PARITY GENERATOR BSEL [H:L] DATA (Transmit) CTRLA CTRLB CTRLC BAUD RATE GENERATOR FRACTIONAL DIVIDE TRANSMIT SHIFT REGISTER RECEIVE SHIFT REGISTER RxD TxD PIN CONTROL DATA (Receive) PIN CONTROL XCK DATA RECOVERY CLOCK RECOVERY PIN CONTROL TX CONTROL RX CONTROL PARITY CHECKER DATA BUS OSC SYNC LOGIC Clock Generator Transmitter Receiver XMEGA B [MANUAL] 263 8291C–AVR–09/2014 Figure 21-2. Clock generation logic, block diagram. 21.3.1 Internal Clock Generation - The Fractional Baud Rate Generator The fractional baud rate generator is used for internal clock generation for asynchronous modes, synchronous master mode, and master SPI mode operation. The output frequency generated (fBAUD) is determined by the period setting (BSEL), an optional scale setting (BSCALE), and the peripheral clock frequency (fPER). Table 21-1 contains equations for calculating the baud rate (in bits per second) and for calculating the BSEL value for each mode of operation. It also shows the maximum baud rate versus peripheral clock frequency. BSEL can be set to any value between 0 and 4095. BSCALE can be set to any value between -7 and +7, and increases or decreases the baud rate slightly to provide the fractional baud rate scaling of the baud rate generator. When BSEL is 0, BSCALE must also be 0. Also, the value 2ABS(BSCALE) must at most be one half of the minimum number of clock cycles a frame requires. For more details, see “Fractional Baud Rate Generation” on page 271. Table 21-1. Equations for calculating baud rate register settings. Note: 1. The baud rate is defined to be the transfer rate in bits per second (bps) Baud Rate Generator /2 BSEL /4 /2 Sync Register fOSC XCK Pin txclk CLK2X UMSEL [1] DDR_XCK 0 1 0 1 xcki xcko DDR_XCK rxclk 0 1 1 0 Edge Detector PORT_INV fBAUD Operating Mode Conditions Baud Rate(1) Calculation BSEL Value Calculation Asynchronous normal speed mode (CLK2X = 0) BSCALE ≥ 0 BSCALE < 0 Asynchronous double speed mode (CLK2X = 1) BSCALE ≥ 0 BSCALE < 0 Synchronous and master SPI mode f BAUD f PER 16 ≤ ------------- f BAUD f PER 2 BSCALE ⋅ 16(BSEL + 1) = ------------------------------------------------------------ BSEL f PER 2 BSCALE ⋅ 16 f BAUD = -------------------------------------------------- – 1 f BAUD f PER 16 ≤ ------------- f BAUD f PER 16((2BSCALE ⋅ BSEL ) + 1) = ------------------------------------------------------------------ BSEL 1 2 BSCALE --------------------- f PER 16 f BAUD ----------------------- – 1 ⎝ ⎠ ⎛ ⎞ = f BAUD f PER 8 ≤ ------------- f BAUD f PER 2 BSCALE ⋅ ⋅ 8 ( ) BSEL + 1 = -------------------------------------------------------------- BSEL f PER 2 BSCALE ⋅ 8 f BAUD = ----------------------------------------------- – 1 f BAUD f PER 8 ≤ ------------- f BAUD f PER 8((2BSCALE ⋅ BSEL ) + 1) = --------------------------------------------------------------- BSEL 1 2 BSCALE --------------------- f PER 8 f BAUD -------------------- – 1 ⎝ ⎠ ⎛ ⎞ = f BAUD f PER 2 < ------------- f BAUD f PER 2 ⋅ ( ) BSEL + 1 = ------------------------------------ BSEL f PER 2 f BAUD = -------------------- – 1 XMEGA B [MANUAL] 264 8291C–AVR–09/2014 For BSEL=0, all baud rates must be achieved by changing BSEL instead of setting BSCALE: BSEL = (2 BSCALE-1) 21.3.2 External Clock External clock (XCK) is used in synchronous slave mode operation. The XCK clock input is sampled on the peripheral clock frequency (fPER), and the maximum XCK clock frequency (fXCK)is limited by the following: For each high and low period, XCK clock cycles must be sampled twice by the peripheral clock. If the XCK clock has jitter, or if the high/low period duty cycle is not 50/50, the maximum XCK clock speed must be reduced or the peripheral clock must be increased accordingly. 21.3.3 Double Speed Operation Double speed operation allows for higher baud rates under asynchronous operation with lower peripheral clock frequencies. When this is enabled, the baud rate for a given asynchronous baud rate setting shown in Table 21-1 on page 263 will be doubled. In this mode, the receiver will use half the number of samples (reduced from 16 to 8) for data sampling and clock recovery. Due to the reduced sampling, a more accurate baud rate setting and peripheral clock are required. See “Asynchronous Data Reception” on page 268 for more details. 21.3.4 Synchronous Clock Operation When synchronous mode is used, the XCK pin controls whether the transmission clock is input (slave mode) or output (master mode). The corresponding port pin must be set to output for master mode or to input for slave mode. The normal port operation of the XCK pin will be overridden. The dependency between the clock edges and data sampling or data change is the same. Data input (on RxD) is sampled at the XCK clock edge which is opposite the edge where data output (TxD) is changed. BSCALE BSEL BSCALE BSEL 1 0 → 0 1 2 0 → 0 3 3 0 → 0 7 4 0 → 0 15 5 0 → 0 31 6 0 → 0 63 7 0 → 0 127 f XCK f PER 4 < ------------- XMEGA B [MANUAL] 265 8291C–AVR–09/2014 Figure 21-3. Synchronous mode XCK timing. Using the inverted I/O (INVEN) setting for the corresponding XCK port pin, the XCK clock edges used for data sampling and data change can be selected. If inverted I/O is disabled (INVEN=0), data will be changed at the rising XCK clock edge and sampled at the falling XCK clock edge. If inverted I/O is enabled (INVEN=1), data will be changed at the falling XCK clock edge and sampled at the rising XCK clock edge. For more details, see “I/O Ports” on page 123. 21.3.5 Master SPI Mode Clock Generation For master SPI mode operation, only internal clock generation is supported. This is identical to the USART synchronous master mode, and the baud rate or BSEL setting is calculated using the same equations (see Table 21-1 on page 263). There are four combinations of the SPI clock (SCK) phase and polarity with respect to the serial data, and these are determined by the clock phase (UCPHA) control bit and the inverted I/O pin (INVEN) settings. The data transfer timing diagrams are shown in Figure 21-4 on page 266. Data bits are shifted out and latched in on opposite edges of the XCK signal, ensuring sufficient time for data signals to stabilize. The UCPHA and INVEN settings are summarized in Table 21- 2. Changing the setting of any of these bits during transmission will corrupt both the receiver and transmitter Table 21-2. INVEN and UCPHA functionality. The leading edge is the first clock edge of a clock cycle. The trailing edge is the last clock edge of a clock cycle. RxD / TxD XCK RxD / TxD UCPOL = 0 XCK UCPOL = 1 Sample Sample SPI Mode INVEN UCPHA Leading Edge Trailing Edge 0 0 0 Rising, sample Falling, setup 1 0 1 Rising, setup Falling, sample 2 1 0 Falling, sample Rising, setup 3 1 1 Falling, setup Rising, sample XMEGA B [MANUAL] 266 8291C–AVR–09/2014 Figure 21-4. UCPHA and INVEN data transfer timing diagrams. 21.4 Frame Formats Data transfer is frame based, where a serial frame consists of one character of data bits with synchronization bits (start and stop bits) and an optional parity bit for error checking. Note that this does not apply to master SPI operation (See “SPI Frame Formats” on page 267). The USART accepts all combinations of the following as valid frame formats: z 1 start bit z 5, 6, 7, 8, or 9 data bits z no, even, or odd parity bit z 1 or 2 stop bits A frame starts with the start bit, followed by all the data bits (least-significant bit first and most-significant bit last). If enabled, the parity bit is inserted after the data bits, before the first stop bit. One frame can be directly followed by a start bit and a new frame, or the communication line can return to the idle (high) state. Figure 21-5 on page 266 illustrates the possible combinations of frame formats. Bits inside brackets are optional. Figure 21-5. Frame formats. 21.4.1 Parity Bit Calculation Even or odd parity can be selected for error checking. If even parity is selected, the parity bit is set to one if the number of logical one data bits is odd (making the total number of ones even). If odd parity is selected, the parity bit is set to one if the number of logical one data bits is even (making the total number of ones odd). XCK Data setup (TXD) Data sample (RXD) XCK Data setup (TXD) Data sample (RXD) XCK Data setup (TXD) Data sample (RXD) XCK Data setup (TXD) Data sample (RXD) UCPOL=0 UCPOL=1 UCPHA=0 UCPHA=1 St Start bit, always low. (n) Data bits (0 to 8). P Parity bit, may be odd or even. Sp Stop bit, always high. IDLE No transfers on the communication line (RxD or TxD). The IDLE state is always high. (IDLE) St Sp1 [Sp2] 0 2 3 4 [5] [6] [7] [8] [P] 1 (St / IDLE) FRAME XMEGA B [MANUAL] 267 8291C–AVR–09/2014 21.4.2 SPI Frame Formats The serial frame in SPI mode is defined to be one character of eight data bits. The USART in master SPI mode has two selectable frame formats: z 8-bit data, msb first z 8-bit data, lsb first After a complete, 8-bit frame is transmitted, a new frame can directly follow it, or the communication line can return to the idle (high) state. 21.5 USART Initialization USART initialization should use the following sequence: 1. Set the TxD pin value high, and optionally set the XCK pin low. 2. Set the TxD and optionally the XCK pin as output. 3. Set the baud rate and frame format. 4. Set the mode of operation (enables XCK pin output in synchronous mode). 5. Enable the transmitter or the receiver, depending on the usage. For interrupt-driven USART operation, global interrupts should be disabled during the initialization. Before doing a re-initialization with a changed baud rate or frame format, be sure that there are no ongoing transmissions while the registers are changed. 21.6 Data Transmission - The USART Transmitter When the transmitter has been enabled, the normal port operation of the TxD pin is overridden by the USART and given the function as the transmitter's serial output. The direction of the pin must be set as output using the direction register for the corresponding port. For details on port pin control and output configuration, refer to “I/O Ports” on page 123. 21.6.1 Sending Frames A data transmission is initiated by loading the transmit buffer (DATA) with the data to be sent. The data in the transmit buffer are moved to the shift register when the shift register is empty and ready to send a new frame. The shift register is loaded if it is in idle state (no ongoing transmission) or immediately after the last stop bit of the previous frame is transmitted. When the shift register is loaded with data, it will transfer one complete frame. The transmit complete interrupt flag (TXCIF) is set and the optional interrupt is generated when the entire frame in the shift register has been shifted out and there are no new data present in the transmit buffer. The transmit data register (DATA) can only be written when the data register empty flag (DREIF) is set, indicating that the register is empty and ready for new data. When using frames with fewer than eight bits, the most-significant bits written to DATA are ignored. If 9-bit characters are used, the ninth bit must be written to the TXB8 bit before the low byte of the character is written to DATA. 21.6.2 Disabling the Transmitter A disabling of the transmitter will not become effective until ongoing and pending transmissions are completed; i.e., when the transmit shift register and transmit buffer register do not contain data to be transmitted. When the transmitter is disabled, it will no longer override the TxDn pin, and the pin direction is set as input automatically by hardware, even if it was configured as output by the user. 21.7 Data Reception - The USART Receiver When the receiver is enabled, the RxD pin functions as the receiver's serial input. The direction of the pin must be set as input, which is the default pin setting. XMEGA B [MANUAL] 268 8291C–AVR–09/2014 21.7.1 Receiving Frames The receiver starts data reception when it detects a valid start bit. Each bit that follows the start bit will be sampled at the baud rate or XCK clock and shifted into the receive shift register until the first stop bit of a frame is received. A second stop bit will be ignored by the receiver. When the first stop bit is received and a complete serial frame is present in the receive shift register, the contents of the shift register will be moved into the receive buffer. The receive complete interrupt flag (RXCIF) is set, and the optional interrupt is generated. The receiver buffer can be read by reading the data register (DATA) location. DATA should not be read unless the receive complete interrupt flag is set. When using frames with fewer than eight bits, the unused most-significant bits are read as zero. If 9-bit characters are used, the ninth bit must be read from the RXB8 bit before the low byte of the character is read from DATA. 21.7.2 Receiver Error Flags The USART receiver has three error flags. The frame error (FERR), buffer overflow (BUFOVF) and parity error (PERR) flags are accessible from the status register. The error flags are located in the receive FIFO buffer together with their corresponding frame. Due to the buffering of the error flags, the status register must be read before the receive buffer (DATA), since reading the DATA location changes the FIFO buffer. 21.7.3 Parity Checker When enabled, the parity checker calculates the parity of the data bits in incoming frames and compares the result with the parity bit of the corresponding frame. If a parity error is detected, the parity error flag is set. 21.7.4 Disabling the Receiver A disabling of the receiver will be immediate. The receiver buffer will be flushed, and data from ongoing receptions will be lost. 21.7.5 Flushing the Receive Buffer If the receive buffer has to be flushed during normal operation, read the DATA location until the receive complete interrupt flag is cleared. 21.8 Asynchronous Data Reception The USART includes a clock recovery and a data recovery unit for handling asynchronous data reception. The clock recovery unit is used for synchronizing the incoming asynchronous serial frames at the RxD pin to the internally generated baud rate clock. It samples and low-pass filters each incoming bit, thereby improving the noise immunity of the receiver. The asynchronous reception operational range depends on the accuracy of the internal baud rate clock, the rate of the incoming frames, and the frame size in number of bits. 21.8.1 Asynchronous Clock Recovery The clock recovery unit synchronizes the internal clock to the incoming serial frames. Figure 21-6 on page 269 illustrates the sampling process for the start bit of an incoming frame. The sample rate is 16 times the baud rate for normal mode, and eight times the baud rate for double speed mode. The horizontal arrows illustrate the synchronization variation due to the sampling process. Note the larger time variation when using the double speed mode of operation. Samples denoted as zero are samples done when the RxD line is idle; i.e., when there is no communication activity. XMEGA B [MANUAL] 269 8291C–AVR–09/2014 Figure 21-6. Start bit sampling. When the clock recovery logic detects a high (idle) to low (start) transition on the RxD line, the start bit detection sequence is initiated. Sample 1 denotes the first zero-sample, as shown in the figure. The clock recovery logic then uses samples 8, 9, and 10 for normal mode and samples 4, 5, and 6 for double speed mode to decide if a valid start bit is received. If two or three samples have a low level, the start bit is accepted. The clock recovery unit is synchronized, and the data recovery can begin. If two or three samples have a high level, the start bit is rejected as a noise spike, and the receiver looks for the next high-to-low transition. The process is repeated for each start bit. 21.8.2 Asynchronous Data Recovery The data recovery unit uses sixteen samples in normal mode and eight samples in double speed mode for each bit. Figure 21-7 on page 269 shows the sampling process of data and parity bits. Figure 21-7. Sampling of data and parity bits. As for start bit detection, an identical majority voting technique is used on the three center samples for deciding of the logic level of the received bit. The process is repeated for each bit until a complete frame is received. It includes the first stop bit, but excludes additional ones. If the sampled stop bit is a 0 value, the frame error (FERR) flag will be set. Figure 21-8 on page 269 shows the sampling of the stop bit in relation to the earliest possible beginning of the next frame's start bit. Figure 21-8. Stop bit and next start bit sampling. A new high-to-low transition indicating the start bit of a new frame can come right after the last of the bits used for majority voting. For normal speed mode, the first low level sample can be at the point marked (A) in Stop Bit Sampling and Next Start Bit Sampling. For double speed mode, the first low level must be delayed to point (B). Point (C) marks a stop bit of full length at nominal baud rate. The early start bit detection influences the operational range of the receiver. 1234567 8 9 10 11 12 13 14 15 16 1 2 IDLE START 0 0 BIT 0 3 0 123 4 5 678 1 2 RxD Sample (U2X = 0) Sample (U2X = 1) 1234567 8 9 10 11 12 13 14 15 16 1 BIT n 123 4 5 678 1 RxD Sample (CLK2X = 0) Sample (CLK2X = 1) 1234567 8 9 10 0/1 0/1 0/1 STOP 1 123 4 5 6 0/1 RxD Sample (CLK2X = 0) Sample (CLK2X = 1) (A) (B) (C) XMEGA B [MANUAL] 270 8291C–AVR–09/2014 21.8.3 Asynchronous Operational Range The operational range of the receiver is dependent on the mismatch between the received bit rate and the internally generated baud rate. If an external transmitter is sending using bit rates that are too fast or too slow, or if the internally generated baud rate of the receiver does not match the external source’s base frequency, the receiver will not be able to synchronize the frames to the start bit. The following equations can be used to calculate the ratio of the incoming data rate and internal receiver baud rate. Table 21-3 and Table 21-4 on page 270 list the maximum receiver baud rate error that can be tolerated. Normal speed mode has higher tolerance of baud rate variations. Table 21-3. Recommended maximum receiver baud rate error for normal speed mode. Table 21-4. Recommended maximum receiver baud rate error for double speed mode. D Sum of character size and parity size (D = 5 to 10 bits). S Samples per bit. S = 16 for normal speed mode and S = 8 for double speed mode. SF First sample number used for majority voting. SF = 8 for normal speed mode and SF = 4 for double speed mode. SM Middle sample number used for majority voting. SM = 9 for normal speed mode and SM = 5 for double speed mode. Rslow The ratio of the slowest incoming data rate that can be accepted in relation to the receiver baud rate. Rfast The ratio of the fastest incoming data rate that can be accepted in relation to the receiver baud rate. D #(Data + Parity Bit) Rslow [%] Rfast [%] Max Total Error [%] Recommended Max Receiver Error [%] 5 93.20 106.67 +6.67/-6.80 ± 3.0 6 94.12 105.79 +5.79/-5.88 ± 2.5 7 94.81 105.11 +5.11/-5.19 ± 2.0 8 95.36 104.58 +4.58/-4.54 ± 2.0 9 95.81 104.14 +4.14/-4.19 ± 1.5 10 96.17 103.78 +3.78/-3.83 ± 1.5 D #(Data + Parity Bit) Rslow [%] Rfast [%] Max Total Error [%] Recommended Max Receiver Error [%] 5 94.12 105.66 +5.66/-5.88 ± 2.5 6 94.92 104.92 +4.92/-5.08 ± 2.0 7 95.52 104.35 +4.35/-4.48 ± 1.5 Rslow ( ) D + 1 S S – 1 D S⋅ SF + + = ------------------------------------------- R fast ( ) D + 2 S ( ) D + 1 S SM + = ------------------------------------ XMEGA B [MANUAL] 271 8291C–AVR–09/2014 The recommendations for the maximum receiver baud rate error assume that the receiver and transmitter equally divide the maximum total error. 21.9 Fractional Baud Rate Generation Fractional baud rate generation is possible for asynchronous operation due to the relatively high number of clock cycles for each frame. Each bit is sampled sixteen times, but only the three middle samples are of importance. The total number of samples for one frame is also relatively high. Given a 1-start, 8-data, no-parity, and 1-stop-bit frame format, and assuming that normal speed mode is used, the total number of samples for a frame is (1+8+1)×16 or 160. As stated earlier, the UART can tolerate some variation in clock cycles for each sample. The critical factor is the time from the falling edge of the start bit (i.e., the clock synchronization) until the last bit's (i.e., the first stop bit’s) value is recovered. Standard baud rate generators have the unwanted property of having large frequency steps between high baud rate settings. The worst case is found between the BSEL values 0x000 and 0x001. Going from a BSEL value of 0x000, which has a 10-bit frame of 160 clock cycles, to a BSEL value of 0x001, with 320 clock cycles, gives a 50% change in frequency. Ideally, the step size should be small even between the fastest baud rates. This is where the advantage of the fractional baud rate generator emerges. In principle, the fractional baud rate generator works by doing uneven counting and then distributing the error evenly over the entire frame. A typical count sequence for an ordinary baud rate generator is: 2, 1, 0, 2, 1, 0, 2, 1, 0, 2, … which has an even period time. A baud rate clock ticks each time the counter reaches zero, and a sample of the signal received on RxD is taken for every 16th baud rate clock tick. For the fractional baud rate generator, the count sequence can have an uneven period: 2, 1, 0, 2, 1-1, 0, 2, 1, 0, 2, 1-1, 0,... In this example, an extra cycle is added to every second baud clock. This gives a baud rate clock tick jitter, but the average period has been increased by a fraction of 0.5 clock cycles. Figure 21-9 on page 272 shows an example of how BSEL and BSCALE can be used to achieve baud rates in between what is possible by just changing BSEL. The impact of fractional baud rate generation is that the step size between baud rate settings has been reduced. Given a scale factor of -1, the worst-case step then becomes from 160 to 240 clock cycles per 10-bit frame, compared to the previous step of from 160 to 320. A higher negative scale factor gives even finer granularity. There is a limit, however, to how high the scale factor can be. The value 2|BSCALE| must be at most half the minimum number of clock cycles of a frame. For instance, for 10-bit frames, the minimum number of clock cycles is 160. This means that the highest applicable scale factor is -6 (2I-6I = 64 < (160/2) = 80). For higher BSEL settings, the scale factor can be increased. Table 21-5 on page 272 shows BSEL and BSCALE settings when using the internal oscillators to generate the most commonly used baud rates for asynchronous operation and how reducing the BSCALE can be used to reduce the baud rate error even further. 8 96.00 103.90 +3.90/-4.00 ± 1.5 9 96.39 103.53 +3.53/-3.61 ± 1.5 10 96.70 103.23 +3.23/-3.30 ± 1.0 D #(Data + Parity Bit) Rslow [%] Rfast [%] Max Total Error [%] Recommended Max Receiver Error [%] XMEGA B [MANUAL] 272 8291C–AVR–09/2014 Figure 21-9. Fractional baud rate example. Table 21-5. USART baud rate. BSEL=0 BSCALE=0 fBAUD=fPER/8 clkBAUD8 clkBAUD8 BSEL=3 BSCALE=-6 fBAUD=fPER/8.375 clkBAUD8 BSEL=3 BSCALE=-4 fBAUD=fPER/9.5 Extra clock cycle added Baud fOSC = 32.0000MHz rate (bps) CLK2X = 0 CLK2X = 1 BSEL BSCALE Error [%] BSEL BSCALE Error [%] 2400 12 6 0.2 12 7 0.2 4800 12 5 0.2 12 6 0.2 9600 12 4 0.2 12 5 0.2 14.4k 34 2 0.8 34 3 0.8 138 0 -0.1 138 1 -0.1 19.2k 12 3 0.2 12 4 0.2 28.8k 34 1 -0.8 34 2 -0.8 137 -1 -0.1 138 0 -0.1 38.4k 12 2 0.2 12 3 0.2 57.6k 34 0 -0.8 34 1 -0.8 135 -2 -0.1 137 -1 -0.1 76.8k 12 1 0.2 12 2 0.2 115.2k 33 -1 -0.8 34 0 -0.8 131 -3 -0.1 135 -2 -0.1 230.4k 31 -2 -0.8 33 -1 -0.8 123 -4 -0.1 131 -3 -0.1 460.8k 27 -3 -0.8 31 -2 -0.8 107 -5 -0.1 123 -4 -0.1 XMEGA B [MANUAL] 273 8291C–AVR–09/2014 21.10 USART in Master SPI Mode Using the USART in master SPI mode requires the transmitter to be enabled. The receiver can optionally be enabled to serve as the serial input. The XCK pin will be used as the transfer clock. As for the USART, a data transfer is initiated by writing to the DATA register. This is the case for both sending and receiving data, since the transmitter controls the transfer clock. The data written to DATA are moved from the transmit buffer to the shift register when the shift register is ready to send a new frame. The transmitter and receiver interrupt flags and corresponding USART interrupts used in master SPI mode are identical in function to their use in normal USART operation. The receiver error status flags are not in use and are always read as zero. Disabling of the USART transmitter or receiver in master SPI mode is identical to their disabling in normal USART operation. 21.11 USART SPI vs. SPI The USART in master SPI mode is fully compatible with the standalone SPI module in that: z Timing diagrams are the same z UCPHA bit functionality is identical to that of the SPI CPHA bit z UDORD bit functionality is identical to that of the SPI DORD bit When the USART is set in master SPI mode, configuration and use are in some cases different from those of the standalone SPI module. In addition, the following differences exist: 921.6k 19 -4 -0.8 27 -3 -0.8 75 -6 -0.1 107 -5 -0.1 1.382M 7 -4 0.6 15 -3 0.6 57 -7 0.1 121 -6 0.1 1.843M 3 -5 -0.8 19 -4 -0.8 11 -7 -0.1 75 -6 -0.1 2.00M 0 0 0.0 1 0 0.0 2.304M – – – 3 -2 -0.8 47 -6 -0.1 2.5M – – – 19 -4 0.4 77 -7 -0.1 3.0M – – – 11 -5 -0.8 43 -7 -0.2 4.0M – – – 0 0 0.0 Max 2.0Mbps 4.0Mbps Baud fOSC = 32.0000MHz rate (bps) CLK2X = 0 CLK2X = 1 BSEL BSCALE Error [%] BSEL BSCALE Error [%] XMEGA B [MANUAL] 274 8291C–AVR–09/2014 z The USART transmitter in master SPI mode includes buffering, but the SPI module has no transmit buffer z The USART receiver in master SPI mode includes an additional buffer level z The USART in master SPI mode does not include the SPI write collision feature z The USART in master SPI mode does not include the SPI double speed mode feature, but this can be achieved by configuring the baud rate generator accordingly z Interrupt timing is not compatible z Pin control differs due to the master-only operation of the USART in SPI master mode A comparison of the USART in master SPI mode and the SPI pins is shown Table 21-6. Table 21-6. Comparison of USART in master SPI mode and SPI pins. 21.12 Multiprocessor Communication Mode The multiprocessor communication mode effectively reduces the number of incoming frames that have to be handled by the receiver in a system with multiple microcontrollers communicating via the same serial bus. In this mode, a dedicated bit in the frames is used to indicate whether the frame is an address or data frame type. If the receiver is set up to receive frames that contain five to eight data bits, the first stop bit is used to indicate the frame type. If the receiver is set up for frames with nine data bits, the ninth bit is used. When the frame type bit is one, the frame contains an address. When the frame type bit is zero, the frame is a data frame. If 5-bit to 8-bit character frames are used, the transmitter must be set to use two stop bits, since the first stop bit is used for indicating the frame type. If a particular slave MCU has been addressed, it will receive the following data frames as usual, while the other slave MCUs will ignore the frames until another address frame is received. 21.12.1 Using Multiprocessor Communication Mode The following procedure should be used to exchange data in multiprocessor communication mode (MPCM): 1. All slave MCUs are in multiprocessor communication mode. 2. The master MCU sends an address frame, and all slaves receive and read this frame. 3. Each slave MCU determines if it has been selected. 4. The addressed MCU will disable MPCM and receive all data frames. The other slave MCUs will ignore the data frames. 5. When the addressed MCU has received the last data frame, it must enable MPCM again and wait for a new address frame from the master. The process then repeats from step 2. Using any of the 5-bit to 8-bit character frame formats is impractical, as the receiver must change between using n and n+1 character frame formats. This makes full-duplex operation difficult, since the transmitter and receiver must use the same character size setting. USART SPI Comment TxD MOSI Master out only RxD MISO Master in only XCK SCK Functionally identical N/A SS Not supported by USART in master SPI mode XMEGA B [MANUAL] 275 8291C–AVR–09/2014 21.13 IRCOM Mode of Operation IRCOM mode can be enabled to use the IRCOM module with the USART. This enables IrDA 1.4 compliant modulation and demodulation for baud rates up to 115.2kbps. When IRCOM mode is enabled, double speed mode cannot be used for the USART. For devices with more than one USART, IRCOM mode can be enabled for only one USART at a time. For details, refer to “IRCOM - IR Communication Module” on page 282. 21.14 DMA Support DMA support is available on UART, USRT, and master SPI mode peripherals. For details on different USART DMA transfer triggers, refer to “Transfer Triggers” on page 49. XMEGA B [MANUAL] 276 8291C–AVR–09/2014 21.15 Register Description 21.15.1 DATA – Data register The USART transmit data buffer register (TXB) and USART receive data buffer register (RXB) share the same I/O address and is referred to as USART data register (DATA). The TXB register is the destination for data written to the DATA register location. Reading the DATA register location returns the contents of the RXB register. For 5-bit, 6-bit, or 7-bit characters, the upper unused bits will be ignored by the transmitter and set to zero by the receiver. The transmit buffer can be written only when DREIF in the STATUS register is set. Data written to the DATA register when DREIF is not set will be ignored by the USART transmitter. When data are written to the transmit buffer and the transmitter is enabled, the transmitter will load the data into the transmit shift register when the shift register is empty. The data are then transmitted on the TxD pin. The receive buffer consists of a two-level FIFO. Always read STATUS before DATA in order to get the correct status of the receive buffer. 21.15.2 STATUS – Status register z Bit 7 – RXCIF: Receive Complete Interrupt Flag This flag is set when there are unread data in the receive buffer and cleared when the receive buffer is empty (i.e., does not contain any unread data). When the receiver is disabled, the receive buffer will be flushed, and consequently RXCIF will become zero. When interrupt-driven data reception is used, the receive complete interrupt routine must read the received data from DATA in order to clear RXCIF. If not, a new interrupt will occur directly after the return from the current interrupt. This flag can also be cleared by writing a one to its bit location. z Bit 6 – TXCIF: Transmit Complete Interrupt Flag This flag is set when the entire frame in the transmit shift register has been shifted out and there are no new data in the transmit buffer (DATA). TXCIF is automatically cleared when the transmit complete interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. z Bit 5 – DREIF: Data Register Empty Flag This flag indicates whether the transmit buffer (DATA) is ready to receive new data. The flag is one when the transmit buffer is empty and zero when the transmit buffer contains data to be transmitted that has not yet been moved into the shift register. DREIF is set after a reset to indicate that the transmitter is ready. Always write this bit to zero when writing the STATUS register. DREIF is cleared by writing DATA. When interrupt-driven data transmission is used, the data register empty interrupt routine must either write new data to DATA in order to clear DREIF or disable the data register empty interrupt. If not, a new interrupt will occur directly after the return from the current interrupt. Bit 7 6 5 4 3 2 1 0 +0x00 RXB[[7:0] TXB[[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x01 RXCIF TXCIF DREIF FERR BUFOVF PERR – RXB8 Read/Write R R/W R R R R R R/W Initial Value 0 0 1 0 0 0 0 0 XMEGA B [MANUAL] 277 8291C–AVR–09/2014 z Bit 4 – FERR: Frame Error The FERR flag indicates the state of the first stop bit of the next readable frame stored in the receive buffer. The bit is set if the received character had a frame error, i.e., the first stop bit was zero, and cleared when the stop bit of the received data is one. This bit is valid until the receive buffer (DATA) is read. FERR is not affected by setting the number of stop bits used, as it always uses only the first stop bit. Always write this bit location to zero when writing the STATUS register. This flag is not used in master SPI mode operation. z Bit 3 – BUFOVF: Buffer Overflow This flag indicates data loss due to a receiver buffer full condition. This flag is set if a buffer overflow condition is detected. A buffer overflow occurs when the receive buffer is full (two characters) with a new character waiting in the receive shift register and a new start bit is detected. This flag is valid until the receive buffer (DATA) is read. Always write this bit location to zero when writing the STATUS register. This flag is not used in master SPI mode operation. z Bit 2 – PERR: Parity Error If parity checking is enabled and the next character in the receive buffer has a parity error, this flag is set. If parity check is not enabled, this flag will always be read as zero. This bit is valid until the receive buffer (DATA) is read. Always write this bit location to zero when writing the STATUS register. For details on parity calculation, refer to “Parity Bit Calculation” on page 266. This flag is not used in master SPI mode operation. z Bit 1 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 0 – RXB8: Receive Bit 8 RXB8 is the ninth data bit of the received character when operating with serial frames with nine data bits. When used, this bit must be read before reading the low bits from DATA. This bit is unused in master SPI mode operation. 21.15.3 CTRLA – Control register A z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5:4 – RXCINTLVL[1:0]: Receive Complete Interrupt Level These bits enable the receive complete interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will be triggered when the RXCIF flag in the STATUS register is set. z Bit 3:2 – TXCINTLVL[1:0]: Transmit Complete Interrupt Level These bits enable the transmit complete interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will be triggered when the TXCIF flag in the STATUS register is set. z Bit 1:0 – DREINTLVL[1:0]: Data Register Empty Interrupt Level These bits enable the data register empty interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will be triggered when the DREIF flag in the STATUS register is set. Bit 7 6 5 4 3 2 1 0 +0x03 – – RXCINTLVL[1:0] TXCINTLVL[1:0] DREINTLVL[1:0] Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 00000 XMEGA B [MANUAL] 278 8291C–AVR–09/2014 21.15.4 CTRLB – Control register B z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4 – RXEN: Receiver Enable Setting this bit enables the USART receiver. The receiver will override normal port operation for the RxD pin, when enabled. Disabling the receiver will flush the receive buffer, invalidating the FERR, BUFOVF, and PERR flags. z Bit 3 – TXEN: Transmitter Enable Setting this bit enables the USART transmitter. The transmitter will override normal port operation for the TxD pin, when enabled. Disabling the transmitter (writing TXEN to zero) will not become effective until ongoing and pending transmissions are completed; i.e., when the transmit shift register and transmit buffer register do not contain data to be transmitted. When disabled, the transmitter will no longer override the TxD port. z Bit 2 – CLK2X: Double Transmission Speed Setting this bit will reduce the divisor of the baud rate divider from16 to 8, effectively doubling the transfer rate for asynchronous communication modes. For synchronous operation, this bit has no effect and should always be written to zero. This bit must be zero when the USART communication mode is configured to IRCOM. This bit is unused in master SPI mode operation. z Bit 1 – MPCM: Multiprocessor Communication Mode This bit enables the multiprocessor communication mode. When the MPCM bit is written to one, the USART receiver ignores all the incoming frames that do not contain address information. The transmitter is unaffected by the MPCM setting. For more detailed information, see “Multiprocessor Communication Mode” on page 274. This bit is unused in master SPI mode operation. z Bit 0 – TXB8: Transmit Bit 8 TXB8 is the ninth data bit in the character to be transmitted when operating with serial frames with nine data bits. When used, this bit must be written before writing the low bits to DATA. This bit is unused in master SPI mode operation. 21.15.5 CTRLC – Control register C Note: 1. Master SPI mode. z Bits 7:6 – CMODE[1:0]: Communication Mode These bits select the mode of operation of the USART as shown in Table 21-7. Bit 7 6 5 4 3 2 1 0 +0x04 – – – RXEN TXEN CLK2X MPCM TXB8 Read/Write R R R R/W R/W R/W R/W R/W Initial Value 0 0 0 00000 Bit 7 6 5 4 3 2 1 0 +0x05 CMODE[1:0] PMODE[1:0] SBMODE CHSIZE[2:0] +0x05(1) CMODE[1:0] – – – UDORD UCPHA – Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0000110 XMEGA B [MANUAL] 279 8291C–AVR–09/2014 Table 21-7. CMODE bit settings. Notes: 1. See “IRCOM - IR Communication Module” on page 282 for full description on using IRCOM mode. 2. See “USART in Master SPI Mode” on page 273 for full description of the master SPI operation. z Bits 5:4 – PMODE[1:0]: Parity Mode These bits enable and set the type of parity generation according to Table 21-8. When enabled, the transmitter will automatically generate and send the parity of the transmitted data bits within each frame. The receiver will generate a parity value for the incoming data and compare it to the PMODE setting, and if a mismatch is detected, the PERR flag in STATUS will be set. These bits are unused in master SPI mode operation. Table 21-8. PMODE bit settings. z Bit 3 – SBMODE: Stop Bit Mode This bit selects the number of stop bits to be inserted by the transmitter according to Table 21-9. The receiver ignores this setting. This bit is unused in master SPI mode operation. Table 21-9. SBODE bit settings. z Bit 2:0 – CHSIZE[2:0]: Character Size The CHSIZE[2:0] bits set the number of data bits in a frame according to Table 21-10 on page 280. The receiver and transmitter use the same setting. CMODE[1:0] Group Configuration Mode 00 ASYNCHRONOUS Asynchronous USART 01 SYNCHRONOUS Synchronous USART 10 IRCOM IRCOM(1) 11 MSPI Master SPI(2) PMODE[1:0] Group Configuration Parity Mode 00 DISABLED Disabled 01 Reserved 10 EVEN Enabled, even parity 11 ODD Enabled, odd parity SBMODE Stop Bit(s) 0 1 1 2 XMEGA B [MANUAL] 280 8291C–AVR–09/2014 Table 21-10. CHSIZE bit settings. z Bit 2 – UDORD: Data Order This bit is only for master SPI mode, and this bit sets the frame format. When written to one, the lsb of the data word is transmitted first. When written to zero, the msb of the data word is transmitted first. The receiver and transmitter use the same setting. Changing the setting of UDORD will corrupt all ongoing communication for both receiver and transmitter. z Bit 1 – UCPHA: Clock Phase This bit is only for master SPI mode, and the bit determine whether data are sampled on the leading (first) edge or tailing (last) edge of XCKn. Refer to the “Master SPI Mode Clock Generation” on page 265 for details. 21.15.6 BAUDCTRLA – Baud Rate register A z Bit 7:0 – BSEL[7:0]: Baud Rate bits These are the lower 8 bits of the 12-bit BSEL value used for USART baud rate setting. BAUDCTRLB contains the four most-significant bits. Ongoing transmissions by the transmitter and receiver will be corrupted if the baud rate is changed. Writing BSEL will trigger an immediate update of the baud rate prescaler. See the equations in Table 21-1 on page 263. 21.15.7 BAUDCTRLB – Baud Rate register B z Bit 7:4 – BSCALE[3:0]: Baud Rate Scale factor These bits select the baud rate generator scale factor. The scale factor is given in two's complement form from -7 (0b1001) to +7 (0b0111). The -8 (0b1000) setting is reserved. See the equations in Table 21-1 on page 263. z Bit 3:0 – BSEL[11:8]: Baud Rate bits These are the upper 4 bits of the 12-bit value used for USART baud rate setting. BAUDCTRLA contains the eight leastsignificant bits. Ongoing transmissions by the transmitter and receiver will be corrupted if the baud rate is changed. Writing BAUDCTRLA will trigger an immediate update of the baud rate prescaler. CHSIZE[2:0] Group Configuration Character Size 000 5BIT 5-bit 001 6BIT 6-bit 010 7BIT 7-bit 011 8BIT 8-bit 100 Reserved 101 Reserved 110 Reserved 111 9BIT 9-bit Bit 7 6 5 4 3 2 1 0 +0x06 BSEL[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x07 BSCALE[3:0] BSEL[11:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 281 8291C–AVR–09/2014 21.16 Register Summary 21.16.1 Register Description - USART 21.16.2 Register Description - USART in SPI Master Mode 21.17 Interrupt Vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 DATA DATA[7:0] 276 +0x01 STATUS RXCIF TXCIF DREIF FERR BUFOVF PERR – RXB8 276 +0x02 Reserved – – – – – – – – +0x03 CTRLA – – RXCINTLVL[1:0] TXCINTLVL[1:0] DREINTLVL[1:0] 277 +0x04 CTRLB – – – RXEN TXEN CLK2X MPCM TXB8 278 +0x05 CTRLC CMODE[1:0] PMODE[1:0] SBMODE CHSIZE[2:0] 278 +0x06 BAUDCTRL BSEL[7:0] 280 +0x07 BAUDCTRL BSCALE[3:0] BSEL[11:8] 280 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 DATA DATA[7:0] 276 +0x01 STATUS RXCIF TXCIF DREIF – – – – – 276 +0x02 Reserved – – – – – – – – +0x03 CTRLA – – RXCINTLVL[1:0] TXCINTLVL[1:0] DREINTLVL[1:0] 277 +0x04 CTRLB – – – RXEN TXEN – – – 278 +0x05 CTRLC CMODE[1:0] – – – UDORD UCPHA – 278 +0x06 BAUDCTRL BSEL[7:0] 280 +0x07 BAUDCTRL BSCALE[3:0] BSEL[11:8] 280 Offset Source Interrupt Description 0x00 RXC_vect USART receive complete interrupt vector 0x02 DRE_vect USART data register empty interrupt vector 0x04 TXC_vect USART transmit complete interrupt vector XMEGA B [MANUAL] 282 8291C–AVR–09/2014 22. IRCOM - IR Communication Module 22.1 Features z Pulse modulation/demodulation for infrared communication z IrDA compatible for baud rates up to 115.2kbps z Selectable pulse modulation scheme z 3/16 of the baud rate period z Fixed pulse period, 8-bit programmable z Pulse modulation disabled z Built-in filtering z Can be connected to and used by any USART 22.2 Overview XMEGA devices contain an infrared communication module (IRCOM) that is IrDA compatible for baud rates up to 115.2kbps. It can be connected to any USART to enable infrared pulse encoding/decoding for that USART. Figure 22-1. IRCOM connection to USARTs and associated port pins. The IRCOM is automatically enabled when a USART is set in IRCOM mode. The signals between the USART and the RX/TX pins are then routed through the module as shown in Figure 22-1 on page 282. The data on the TX/RX pins are the inverted value of the transmitted/received infrared pulse. It is also possible to select an event channel from the event system as input for the IRCOM receiver. This will disable the RX input from the USART pin. For transmission, three pulse modulation schemes are available: z 3/16 of the baud rate period z Fixed programmable pulse time based on the peripheral clock frequency z Pulse modulation disabled IRCOM Pulse Decoding DIF Event System RXDxn TXDxn USARTxn .... USARTD0 USARTC0 RXDD0 TXDD0 RXDC0 TXDC0 Pulse Encoding decoded RXD encoded TXD encoded RXD RXD... TXD... decoded TXD events XMEGA B [MANUAL] 283 8291C–AVR–09/2014 For reception, a fixed programmable minimum high-level pulse width for the pulse to be decoded as a logical 0 is used. Shorter pulses will then be discarded, and the bit will be decoded to logical 1 as if no pulse was received. The module can only be used in combination with one USART at a time. Thus, IRCOM mode must not be set for more than one USART at a time. This must be ensured in the user software. 22.2.1 Event System Filtering The event system can be used as the receiver input. This enables IRCOM or USART input from I/O pins or sources other than the corresponding RX pin. If event system input is enabled, input from the USART's RX pin is automatically disabled. The event system has a digital input filter (DIF) on the event channels that can be used for filtering. Refer to “Event System” on page 63” for details on using the event system. XMEGA B [MANUAL] 284 8291C–AVR–09/2014 22.3 Registers Description 22.3.1 TXPLCTRL – Transmitter Pulse Length Control Register z Bit 7:0 – TXPLCTRL[7:0]: Transmitter Pulse Length Control This 8-bit value sets the pulse modulation scheme for the transmitter. Setting this register will have no effect if IRCOM mode is not selected by a USART. By leaving this register value to zero, 3/16 of the baud rate period pulse modulation is used. Setting this value from 1 to 254 will give a fixed pulse length coding. The 8-bit value sets the number of system clock periods for the pulse. The start of the pulse will be synchronized with the rising edge of the baud rate clock. Setting the value to 255 (0xFF) will disable pulse coding, letting the RX and TX signals pass through the IRCOM module unaltered. This enables other features through the IRCOM module, such as half-duplex USART, loop-back testing, and USART RX input from an event channel. TXPCTRL must be configured before the USART transmitter is enabled (TXEN). 22.3.2 RXPLCTRL – Receiver Pulse Length Control Register z Bit 7:0 – RXPLCTRL[7:0]: Receiver Pulse Length Control This 8-bit value sets the filter coefficient for the IRCOM transceiver. Setting this register will have no effect if IRCOM mode is not selected by a USART. By leaving this register value at zero, filtering is disabled. Setting this value between 1 and 255 will enable filtering, where x+1 equal samples are required for the pulse to be accepted. RXPCTRL must be configured before the USART receiver is enabled (RXEN). 22.3.3 CTRL – Control Register z Bit 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:0 – EVSEL [3:0]: Event Channel Selection These bits select the event channel source for the IRCOM receiver according to Table 22-1. If event input is selected for the IRCOM receiver, the input from the USART’s RX pin is automatically disabled. Bit 7 6 5 4 3 2 1 0 +0x01 TXPLCTRL[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x02 RXPLCTRL[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x00 – – – – EVSEL[3:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 285 8291C–AVR–09/2014 Table 22-1. Event channel selection. 22.4 Register Summary EVSEL[3:0] Group Configuration Event Source 0000 – None 0001 – (Reserved) 0010 – (Reserved) 0011 – (Reserved) 0100 – (Reserved) 0101 – (Reserved) 0110 – (Reserved) 0111 – (Reserved) 1nnn CHn Event system channel n; n = {0, …,7} Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL – – – – EVSEL[3:0] 284 +0x01 TXPLCTRL TXPLCTRL[7:0] 284 +0x02 RXPLCTRL RXPLCTRL[7:0] 284 XMEGA B [MANUAL] 286 8291C–AVR–09/2014 23. AES and DES Crypto Engines 23.1 Features z Data Encryption Standard (DES) CPU instruction z Advanced Encryption Standard (AES) crypto module z DES Instruction z Encryption and decryption z DES supported z Encryption/decryption in 16 CPU clock cycles per 8-byte block z AES crypto module z Encryption and decryption z Supports 128-bit keys z Supports XOR data load mode to the state memory z Encryption/decryption in 375 clock cycles per 16-byte block 23.2 Overview The Advanced Encryption Standard (AES) and Data Encryption Standard (DES) are two commonly used standards for cryptography. These are supported through an AES peripheral module and a DES CPU instruction, and the communication interfaces and the CPU can use these for fast, encrypted communication and secure data storage. DES is supported by an instruction in the AVR CPU. The 8-byte key and 8-byte data blocks must be loaded into the register file, and then the DES instruction must be executed 16 times to encrypt/decrypt the data block. The AES crypto module encrypts and decrypts 128-bit data blocks with the use of a 128-bit key. The key and data must be loaded into the key and state memory in the module before encryption/decryption is started. It takes 375 peripheral clock cycles before the encryption/decryption is done. The encrypted/encrypted data can then be read out, and an optional interrupt can be generated. The AES crypto module also has DMA support with transfer triggers when encryption/decryption is done and optional auto-start of encryption/decryption when the state memory is fully loaded. 23.3 DES Instruction The DES instruction is a single cycle instruction. In order to decrypt or encrypt a 64-bit (8-byte) data block, the instruction has to be executed 16 times. The data and key blocks must be loaded into the register file before encryption/decryption is started. The 64-bit data block (plaintext or ciphertext) is placed in registers R0-R7, where the LSB of data is placed in R0 and the MSB of data is placed in R7. The full 64-bit key (including parity bits) is placed in registers R8-R15, with the LSB of the key in R8 and the MSB of the key in R15. XMEGA B [MANUAL] 287 8291C–AVR–09/2014 Figure 23-1. Register file usage during DES encryption/decryption. Executing one DES instruction performs one round in the DES algorithm. Sixteen rounds must be executed in increasing order to form the correct DES ciphertext or plaintext. Intermediate results are stored in the register file (R0-R15) after each DES instruction. After sixteen rounds, the key is located in R8-R16 and the encrypted/decrypted ciphertext/plaintext is located in R0-R7. The instruction's operand (K) determines which round is executed, and the half carry flag (H) in the CPU status register determines whether encryption or decryption is performed. If the half carry flag is set, decryption is performed, and if the flag is cleared, encryption is performed. For more details on the DES instruction, refer to the AVR instruction set manual. 23.4 AES Crypto Module The AES crypto module performs encryption and decryption according to the Advanced Encryption Standard (FIPS-197). The 128-bit key block and 128-bit data block (plaintext or ciphertext) must be loaded into the key and state memories in the AES crypto module. This is done by writing the AES KEY register and STATE register sequentially with 16 bytes. It is software selectable whether the module should perform encryption or decryption. It is also possible to enable XOR mode, where all new data loaded to the state key is XORed with the current data in the state memory. The AES module uses 375 clock cycles before the encrypted/decrypted plaintext/ciphertext is available for readout in the state memory. The following setup and use procedure is recommended: 1. Enable the AES interrupt (optional). 2. Select the AES direction to encryption or decryption. 3. Load the key data block into the AES key memory. 4. Load the data block into the AES state memory. 5. Start the encryption/decryption operation. If more than one block is to be encrypted or decrypted, repeat the procedure from step 3. When the encryption/decryption procedure is complete, the AES interrupt flag is set and an optional interrupt is generated. Register File R0 R1 R2 R3 R4 R5 R6 R7 R8 R9 R10 R11 R12 R13 R14 R15 R16 ... R31 data0 data1 data2 data3 data4 data5 data6 data7 key0 key1 key2 key3 key4 key5 key6 key7 data key XMEGA B [MANUAL] 288 8291C–AVR–09/2014 23.4.1 Key and State Memory The AES key and state memory are both 16 x 8-bit memories that are accessible through the KEY and STATE registers, respectively. Each memory has two 4-bit address pointers used to address the memory for read and write, respectively. The initial value of the pointers is zero. After a read or write operation to the STATE or KEY register, the appropriate pointer is automatically incremented. Accessing (read or write) the control register (CTRL) will reset all pointers to zero. A pointer overflow (a sequential read or write done more than 16 times) will also set the affected pointer to zero. The pointers are not accessible from software. Read and write memory pointers are both incremented during write operations in XOR mode. Access to the KEY and STATE registers is possible only when encryption/decryption is not in progress. Figure 23-2. The state memory with pointers and register. The state memory contains the AES state throughout the encryption/decryption process. The initial value of the state is the initial data (i.e., plaintext in the encryption mode, and ciphertext in the decryption mode). The last value of the state is the encrypted/decrypted data. Figure 23-3. The key memory with pointers and register. In the AES crypto module, the following definition of the key is used: z In encryption mode, the key is the one defined in the AES standard. 4-bit state write address pointer 1 - 14 15 STATE 0 4-bit state read address pointer Reset pointer Reset pointer reset or access to AES Control reset or access to AES Control STATE[read pointer] xor XOR I/O Data Bus 4-bit key write address pointer 1 - 14 15 KEY 0 4-bit key read address pointer Reset pointer Reset pointer reset or access to CTRL reset or access to CTRL XMEGA B [MANUAL] 289 8291C–AVR–09/2014 z In decryption mode, the key is the last subkey of the expanded key defined in the AES standard. In decryption mode, the key expansion procedure must be executed by software before operation with the AES crypto module so that the last subkey is ready to be loaded through the KEY register. Alternatively, this procedure can be run in hardware by using the AES crypto module to process a dummy data block in encryption mode using the same key. After the end of the encryption, reading from the key memory allows the last subkey to be obtained; i.e., get the result of the key expansion procedure. Table 23-1 shows the results of reading the key, depending on the mode (encryption or decryption) and status of the AES crypto module. Table 23-1. The result of reading the key memory at different stages. 23.4.2 DMA Support The AES module can trigger a DMA transfer when the encryption/decryption procedure is complete. For more details on DMA transfer triggers, refer to “Transfer Triggers” on page 49. Encryption Decryption Before data processing After data processing Before data processing After Data Processing Same key as loaded The last subkey generated from the loaded key Same key as loaded The initial key generated from the last loaded subkey XMEGA B [MANUAL] 290 8291C–AVR–09/2014 23.5 Register Description – AES 23.5.1 CTRL – Control register z Bit 7 – START: Start/Run Setting this bit starts the encryption/decryption procedure, and this bit remains set while the encryption/decryption is ongoing. Writing this bit to zero will stop/abort any ongoing encryption/decryption process. This bit is automatically cleared if the SRIF or the ERROR flags in STATUS are set. z Bit 6 – AUTO: Auto Start Trigger Setting this bit enables the auto-start mode. In auto-start mode, the START bit will trigger automatically and start the encryption/decryption when all of the following conditions are met: z The AUTO bit is set before the state memory is loaded z All memory pointers (state read/write and key read/write) are zero z State memory is fully loaded If all of these conditions are not met, the encryption/decryption will be started with an incorrect key. z Bit 5 – RESET: Software Reset Setting this bit will reset the AES crypto module to its initial status on the next positive edge of the peripheral clock. All registers, pointers, and memories in the module are set to their initial value. When written to one, the bit stays high for one clock cycle before it is reset to zero by hardware. z Bit 4 – DECRYPT: Decryption / Direction This bit sets the direction for the AES crypto module. Writing this bit to zero will set the module in encryption mode. Writing one to this bit sets the module in decryption mode. z Bit 3 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 2 – XOR: State XOR Load Enable Setting this bit enables a XOR data load to the state memory. When this bit is set, the data loaded to the state memory are bitwise XORed with the data currently in the state memory. Writing this bit to zero disables XOR load mode, and new data written to the state memory will overwrite the current data. z Bit 1:0 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. Bit 7 6 5 4 3 2 1 0 +0x00 START AUTO RESET DECRYPT – XOR – – Read/Write R/W R/W R/W R/W R R/W R R Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 291 8291C–AVR–09/2014 23.5.2 STATUS – AES Status register z Bit 7 – ERROR: Error The ERROR flag indicates an illegal handling of the AES crypto module. The flag is set in the following cases: z Setting START in the control register while the state memory and/or key memory are not fully loaded or read. This error occurs when the total number of read/write operations from/to the STATE and KEY registers is not a multiple of 16 before an AES start. z Accessing (read or write) the control register while the START bit is one. This flag can be cleared by software by writing one to its bit location. z Bit 6:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – SRIF: State Ready Interrupt flag This flag is the interrupt/DMA request flag, and is set when the encryption/decryption procedure is completed and the state memory contains valid data. As long as the flag is zero, this indicates that there is no valid encrypted/decrypted data in the state memory. The flag is cleared by hardware when a read access is made to the state memory (the first byte is read). Alternatively, the bit can be cleared by writing a one to its bit location. 23.5.3 STATE – AES State register The STATE register is used to access the state memory. Before encryption/decryption can take place, the state memory must be written sequentially, byte-by-byte, through the STATE register. After encryption/decryption is done, the ciphertext/plaintext can be read sequentially, byte-by-byte, through the STATE register. Loading the initial data to the STATE register should be done after setting the appropriate AES mode and direction. This register can not be accessed during encryption/decryption. 23.5.4 KEY – Key register The KEY register is used to access the key memory. Before encryption/decryption can take place, the key memory must be written sequentially, byte-by-byte, through the KEY register. After encryption/decryption is done, the last subkey can be read sequentially, byte-by-byte, through the KEY register. Loading the initial data to the KEY register should be done after setting the appropriate AES mode and direction. Bit 7 6 5 4 3 2 1 0 +0x01 ERROR – – – – – – SRIF Read/Write R/W R R R R R R R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x02 STATE[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0000 Bit 7 6 5 4 3 2 1 0 +0x03 KEY[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 292 8291C–AVR–09/2014 23.5.5 INTCTRL – Interrupt Control register z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1:0 – INTLVL[1:0]: Interrupt priority and enable These bits enable the AES interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will be triggered when the SRIF in the STATUS register is set. 23.6 Register summary – AES 23.7 Interrupt vector summary Table 23-2. AES interrupt vector and its offset word address. Bit 7 6 5 4 3 2 1 0 +0x04 – – – – – – INTLVL[1:0] Read/Write R R R R R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 bit 0 Page +0x00 CTRL START AUTO RESET DECRYPT – XOR – – 290 +0x01 STATUS ERROR – – – – – – SRIF 291 +0x02 STATE STATE[7:0] 291 +0x03 KEY KEY[7:0] 291 +0x04 INTCTRL – – – – – – INTLVL[1:0] 292 +0x05 Reserved – – – – – – – – +0x06 Reserved – – – – – – – – +0x07 Reserved – – – – – – – – Offset Source Interrupt Description 0x00 AES_vect AES interrupt vector XMEGA B [MANUAL] 293 8291C–AVR–09/2014 24. CRC – Cyclic Redundancy Check Generator 24.1 Features z Cyclic redundancy check (CRC) generation and checking for z Communication data z Program or data in flash memory z Data in SRAM and I/O memory space z Integrated with flash memory, DMA controller and CPU z Continuous CRC on data going through a DMA channel z Automatic CRC of the complete or a selectable range of the flash memory z CPU can load data to the CRC generator through the I/O interface z CRC polynomial software selectable to z CRC-16 (CRC-CCITT) z CRC-32 (IEEE 802.3) z Zero remainder detection 24.2 Overview A cyclic redundancy check (CRC) is an error detection technique test algorithm used to find accidental errors in data, and it is commonly used to determine the correctness of a data transmission, and data present in the data and program memories. A CRC takes a data stream or a block of data as input and generates a 16- or 32-bit output that can be appended to the data and used as a checksum. When the same data are later received or read, the device or application repeats the calculation. If the new CRC result does not match the one calculated earlier, the block contains a data error. The application will then detect this and may take a corrective action, such as requesting the data to be sent again or simply not using the incorrect data. Typically, an n-bit CRC applied to a data block of arbitrary length will detect any single error burst not longer than n bits (any single alteration that spans no more than n bits of the data), and will detect the fraction 1-2-n of all longer error bursts. The CRC module in XMEGA devices supports two commonly used CRC polynomials; CRC-16 (CRC-CCITT) and CRC-32 (IEEE 802.3). z CRC-16: z CRC-32: Polynomial: x16+x12+x5 +1 Hex value: 0x1021 Polynomial: x32+x26+x23+x22+x16+x12+x11+x10+x8 +x7 +x5 +x4 +x2 +x+1 Hex value: 0x04C11DB7 XMEGA B [MANUAL] 294 8291C–AVR–09/2014 24.3 Operation The data source for the CRC module must be selected in software as either flash memory, the DMA channels, or the I/O interface. The CRC module then takes data input from the selected source and generates a checksum based on these data. The checksum is available in the CHECKSUM registers in the CRC module. When CRC-32 polynomial is used, the final checksum read is bit reversed and complemented (see Figure 24-1). For the I/O interface or DMA controller, which CRC polynomial is used is software selectable, but the default setting is CRC-16. CRC-32 is automatically used if Flash Memory is selected as the source. The CRC module operates on bytes only. Figure 24-1. CRC generator block diagram. 24.4 CRC on Flash memory A CRC-32 calculation can be performed on the entire flash memory, on only the application section, on only the boot section, or on a software selectable range of the flash memory. Other than selecting the flash as the source, all further control and setup are done from the NVM controller. This means that the NVM controller configures the memory range to perform the CRC on, and the CRC is started using NVM commands. Once completed, the result is available in the checksum registers in the CRC module. For further details on setting up and performing CRC on flash memory, refer to “Memory Programming” on page 375. 24.5 CRC on DMA Data CRC-16 or CRC-32 calculations can be performed on data passing through any DMA channel. Once a DMA channel is selected as the source, the CRC module will continuously generate the CRC on the data passing through the DMA channel. The checksum is available for readout once the DMA transaction is completed or aborted. A CRC can be DATAIN CTRL Flash Memory DMA Controller CRC-16 CRC-32 CHECKSUM bit-reverse + complement 8 16 8 32 Checksum read crc32 XMEGA B [MANUAL] 295 8291C–AVR–09/2014 performed not only on communication data, but also on data in SRAM or I/O memory by passing these data through a DMA channel. If the latter is done, the destination register for the DMA data can be the data input (DATAIN) register in the CRC module. 24.6 CRC using the I/O Interface CRC can be performed on any data by loading them into the CRC module using the CPU and writing the data to the DATAIN register. Using this method, an arbitrary number of bytes can be written to the register by the CPU, and CRC is done continuously for each byte. New data can be written for each cycle. The CRC complete is signaled by writing the BUSY bit in the STATUS register. XMEGA B [MANUAL] 296 8291C–AVR–09/2014 24.7 Register Description 24.7.1 CTRL – Control register z Bit 7:6 – RESET[1:0]: Reset These bits are used to reset the CRC module, and they will always be read as zero. The CRC registers will be reset one peripheral clock cycle after the RESET[1] bit is set Table 24-1. CRC reset. z Bit 5 – CRC32: CRC-32 Enable Setting this bit will enable CRC-32 instead of the default CRC-16. It cannot be changed while the BUSY flag is set. z Bit 4 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 3:0 – SOURCE[3:0]: Input Source These bits select the input source for generating the CRC. The selected source is locked until either the CRC generation is completed or the CRC module is reset. CRC generation complete is generated and signaled from the selected source when used with the DMA controller or flash memory. Table 24-2. CRC source select. Bit 7 6 5 4 3 2 1 0 +0x00 RESET[1:0] CRC32 – SOURCE[3:0] Read/Write R/W R/W R/W R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 RESET[1:0] Group configuration Description 00 NO No reset 01 – Reserved 10 RESET0 Reset CRC with CHECKSUM to all zeros 11 RESET1 Reset CRC with CHECKSUM to all ones SOURCE[3:0] Group configuration Description 0000 DISABLE CRC disabled 0001 IO I/O interface 0010 FLASH Flash 0011 – Reserved for future use 0100 DMACH0 DMA controller channel 0 0101 DMACH1 DMA controller channel 1 0110 DMACH2 DMA controller channel 2 0111 DMACH3 DMA controller channel 3 1xxx – Reserved for future use XMEGA B [MANUAL] 297 8291C–AVR–09/2014 24.7.2 STATUS – Status register z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – ZERO: Checksum Zero This flag is set if the CHECKSUM is zero when the CRC generation is complete. It is automatically cleared when a new CRC source is selected. When running CRC-32 and appending the checksum at the end of the packet (as little endian), the final checksum should be 0x2144df1c, and not zero. However, if the checksum is complemented before it is appended (as little endian) to the data, the final result in the checksum register will be zero. See the description of CHECKSUM to read out different versions of the CHECKSUM. z Bit 0 – BUSY: Busy This flag is read as one when a source configuration is selected and as long as the source is using the CRC module. If the I/O interface is selected as the source, the flag can be cleared by writing a one this location. If a DMA channel if selected as the source, the flag is cleared when the DMA channel transaction is completed or aborted. If flash memory is selected as the source, the flag is cleared when the CRC generation is completed. 24.7.3 DATAIN – Data Input register z Bit 7:0 – DATAIN[7:0]: Data Input This register is used to store the data for which the CRC checksum is computed. A new CHECKSUM is ready one clock cycle after the DATAIN register is written. 24.7.4 CHECKSUM0 – Checksum register 0 CHECKSUM0, CHECKSUM1, CHECKSUM2, and CHECKSUM3 represent the 16- or 32-bit CHECKSUM value and the generated CRC. The registers are reset to zero by default, but it is possible to write RESET to reset all bits to one. It is possible to write these registers only when the CRC module is disabled. If NVM is selected as the source, reading CHECKSUM will return a zero value until the BUSY flag is cleared. If CRC-32 is selected and the BUSY flag is cleared (i.e., CRC generation is completed or aborted), the bit reversed (bit 31 is swapped with bit 0, bit 30 with bit 1, etc.) and complemented result will be read from CHECKSUM. If CRC-16 is selected or the BUSY flag is set (i.e., CRC generation is ongoing), CHECKSUM will contain the actual content. z Bit 7:0 – CHECKSUM[7:0]: Checksum byte 0 These bits hold byte 0 of the generated CRC. Bit 7 6 5 4 3 2 1 0 +0x02 – – – – – – ZERO BUSY Read/Write R R R R R R R R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x03 DATAIN[7:0] Read/Write WWWWWWWW Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x04 CHECKSUM[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 298 8291C–AVR–09/2014 24.7.5 CHECKSUM1 – Checksum register 1 z Bit 7:0 – CHECKSUM[15:8]: Checksum byte 1 These bits hold byte 1 of the generated CRC. 24.7.6 CHECKSUM2 – Checksum register 2 z Bit 7:0 – CHECKSUM[23:16]: Checksum byte 2 These bits hold byte 2 of the generated CRC when CRC-32 is used. 24.7.7 CHECKSUM3 – CRC Checksum register 3 z Bit 7:0 – CHECKSUM[31:24]: Checksum byte 3 These bits hold byte 3 of the generated CRC when CRC-32 is used. 24.8 Register Summary Bit 7 6 5 4 3 2 1 0 +0x05 CHECKSUM[15:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x06 CHECKSUM[23:16] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x07 CHECKSUM[31:24] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL RESET[1:0] CRC32 – SOURCE[3:0] 296 +0x01 STATUS – – – – – – ZERO BUSY 297 +0x02 Reserved – – – – – – – – +0x03 DATAIN DATAIN[7:0] 297 +0x04 CHECKSU CHECKSUM[7:0] 298 +0x05 CHECKSU CHECKSUM[15:8] 298 +0x06 CHECKSU CHECKSUM[23:16] 298 +0x07 CHECKSU CHECKSUM[31:24] 298 XMEGA B [MANUAL] 299 8291C–AVR–09/2014 25. LCD – Liquid Crystal Display 25.1 Features z Display Capacity up to 40 Segment and up to 4 Common Terminals z Supports up to 16 GPIO's z Shadow Display Memory Gives Full Freedom in Segment Update z ASCII Character Mapping z Swap Capability Option on Common and/or Segment Terminal Buses z Supports from Static up to 1/4 Duty z Supports Static and 1/3 Bias z LCD Driver Active in Power Save Mode for Low Power Operation z Software Selectable Low Power Waveform z Flexible Selection of Frame Frequency z Programmable Blink Mode and Frequency z Blink on two Segment Terminals z Uses Only 32kHz RTC Clock Source z On-chip LCD Power Supply z Software Contrast Adjustment Control z Equal Source and Sink Capability to Increase LCD Life Time z Extended Interrupt Mode for Display Update or Wake-up from Sleep Mode 25.2 Overview An LCD display is made of several segments (pixels or complete symbols) which can be visible or invisible. A segment has two electrodes with liquid crystal between them. These electrodes are the common terminal (COM pin) and the segment terminal (SEG pin). When a voltage above a threshold voltage is applied across the liquid crystal, the segment becomes visible. The voltage must alternate to avoid an electrophoresis effect in the liquid crystal, this effect degrades the display. Hence the voltage waveform across a segment must not have a DC-component. The LCD controller is intended for monochrome passive liquid crystal display (LCD) with up to 4 Common terminals and up to 40 Segments terminals. If the application does not need all the LCD segments available on the XMEGA, up to 16 of the unused LCD pins can be used as general purpose I/O pins. The LCD controller can be clocked by an internal or an external asynchronous 32kHz clock source. This 32kHz oscillator source selection is the same as for the Real Time Counter (RTC). Dedicated Low Power Waveform, Contrast Control, Extended Interrupt Mode, Selectable Frame Frequency and Blink functionality are supported to offload the CPU, reduce interrupts and reduce power consumption. To reduce hardware design complexity, the LCD includes integrated LCD buffers, an integrated power supply voltage and an innovative SWAP mode. Using SWAP mode, the hardware designers have more flexibility during board layout as they can rearrange the pin sequence on Segment and/or Common Terminal Buses. XMEGA B [MANUAL] 300 8291C–AVR–09/2014 25.2.1 Definitions Several terms are used when describing LCD. The definitions in Table 25-1 are used throughout this document. Table 25-1. LCD definitions. Figure 25-1. LCD Typical Connections 25.2.2 LCD Clock Sources The LCD controller can be clocked by an internal or an external asynchronous 32kHz clock source. This 32kHz oscillator source selection is the same as for the Real Time Counter, RTCSRC bit-field in RTC control register (see Table 7-4 on page 87). The clock source must be stable to obtain accurate LCD timing and hence minimize DC voltage offset across LCD segments. 25.2.3 LCD Prescaler The prescaler consists of a 3-bit ripple counter and a 1 to 8-clock divider (see Figure 25-2 on page 301). The PRESC bit selects clk LCD divided by 8 or 16 from the ripple counter. If a finer resolution in frame rate is required, the CLKDIV bit-field can be used to divide the clock further by 1 to 8. Output from the clock divider clk LCD_PS is used as clock source for the LCD timing. 25.2.4 LCD Display Memory The Display Memory is available through I/O registers grouped for each common terminal. A start of new frame triggers an update of the Shadow Display Memory. The content of Display Memory is saved into the Shadow Display Memory. A Display Memory refresh is possible without affecting data that is sent to the panel. LCD A passive display panel with terminals leading directly to a segment Segment (or pixel) A LCD panel active area within the display which can be turned “ON or “OFF”. This can be a single segment of a 7-segment character or a specific symbol (icon). COM Common terminal SEG Segment terminal 1 / Duty 1 / Number of common terminals on an actual LCD display 1 / Bias 1 / Number of voltage levels used driving a LCD display -1 Frame Rate Number of times the LCD segments are energized per second Segment 0 Segment 1 Segment 2 Segment 4 Segment 5 Segment 6 SEG0 Segment 3 Segment 7 Common Terminal 0 COM0 Common Terminal 1 COM1 Segment Terminal 0 SEG1 Segment Terminal 1 SEG2 Segment Terminal 2 SEG3 Segment Terminal 3 XMEGA B [MANUAL] 301 8291C–AVR–09/2014 When a bit in the Display Memory is written to one, the corresponding segment will be energized (“ON”), and deenergized (“OFF”) when this bit is written to zero. To energize a segment, an absolute voltage above a certain threshold must be applied. This is done by setting the SEG pin to opposite phase when the corresponding COM pin is active. For a display with more than one common terminal, two (1/3 bias) additional voltage levels must be applied. Otherwise, non-energized segments on COM0 would be energized for all non-selected common terminals. Addressing COM0 starts a frame by driving an opposite phase with large amplitude on COM0 as against non addressed COM lines. Non-energized segments are in phase with the addressed COM0, and energized segments have opposite phase and large amplitude. For waveform figures refer to “Mode of Operation” on page 302. DATA4 - DATA0 from Shadow Display Memory is multiplexed into the decoder. The decoder is controlled from the LCD timing and sets up signals controlling the analog switches to produce an output waveform. Next, COM1 is addressed, and DATA9 - DATA5 from Shadow Display Memory is input to the decoder. Addressing continues until all COM lines are addressed according to the number of selected common terminals (duty). 25.2.5 Minimizing Power Consumption The power consumption of the LCD controller can be minimized by: 1. Using the lowest acceptable frame rate - Refer to the LCD glass technical characteristics. 2. Using the low power waveform - “Low Power Waveform” on page 303 3. Programming the lowest possible contrast value - “CTRLF – Control register F” on page 313. 25.3 Block Diagram Figure 25-2. LCD Controller Block Diagram COMy VLCD BIAS1 CTRLF BIAS2 Analog Switch Array Shadow Display Memory LCD Power Supply Timing Control & Swap CTRLD CTRLC CTRLB CTRLA Character Mapping CTRLH CTRLG CTRLE CAPH CAPL SEGx INT DATAn DATA1 : DATA0 Display Memory XMEGA B [MANUAL] 302 8291C–AVR–09/2014 25.4 Mode of Operation 25.4.1 Static Duty and Static Bias If all segments on an LCD have one common electrode, then, each segment must have a unique segment terminal. This kind of display is driven with the waveform shown in Figure 25-3 on page 302. SEG0-COM0 is the voltage across a segment that is “ON”, and SEG1-COM0 is the voltage across a segment that is “OFF”. Figure 25-3. Driving an LCD With One Common Terminal 25.4.2 1/2 Duty and 1/3 Bias For an LCD with two common terminals (1/2 duty) a more complex waveform must be used to individually control segments. The waveform is shown in Figure 25-4 on page 302. SEG0-COM0 is the voltage across a segment that is “ON”, and SEG0-COM1 is the voltage across a segment that is “OFF”. Figure 25-4. Driving an LCD With Two Common Terminals 25.4.3 1/3 Duty and 1/3 Bias 1/3 bias is usually recommended for an LCD with three common terminals (1/3 duty). The waveform is shown in Figure 25-5 on page 303. SEG0-COM0 is the voltage across a segment that is “ON” and SEG0-COM1 is the voltage across a segment that is “OFF”. XMEGA B [MANUAL] 303 8291C–AVR–09/2014 Figure 25-5. Driving an LCD With Three Common Terminals 25.4.4 1/4 Duty and 1/3 Bias 1/3 bias is optimal for an LCD displays with four common terminals (1/4 duty). The waveform is shown in Figure 25-6 on page 303. SEG0-COM0 is the voltage across a segment that is ON” and SEG0-COM1 is the voltage across a segment that is “OFF”. Figure 25-6. Driving an LCD With Four Common Terminals 25.4.5 Low Power Waveform To reduce toggle activity and hence power consumption, a low power waveform (LPWAV=1) can be selected. The low power waveform requires two subsequent frames with the same display data to obtain zero DC voltage. Consequently, the interrupt flag is only set every two frames. Default and the low power waveform is shown in Figure 25-7 on page 304 for 1/3 duty and 1/3 bias. For other selections of duty and bias, the effect is similar. SEG0-COM0 Frame Frame VLCD SEG0 COM0 2/3 VLCD GND 1/3 VLCD VLCD 2/3 VLCD GND 1/3 VLCD VLCD 2/3 VLCD GND 1/3 VLCD -1/3 VLCD -2/3 VLCD - VLCD Frame Frame VLCD SEG0 COM1 2/3 VLCD GND 1/3 VLCD VLCD 2/3 VLCD GND 1/3 VLCD VLCD 2/3 VLCD GND 1/3 VLCD -1/3 VLCD -2/3 VLCD - VLCD SEG0-COM1 XMEGA B [MANUAL] 304 8291C–AVR–09/2014 Figure 25-7. Low Power Waveform With Three Common Terminals 25.4.6 Operation in Sleep Modes The LCD will continue to operate in Idle mode, in Power-save mode and in Extended Standby mode (blinking included). 25.4.7 ASCII Character Mapping The LCD controller can automatically handle ASCII characters. Instead of setting and clearing segments of the digit, the user enters the ASCII code and the Digit Decoder updates itself the corresponding segment values in the Display Memory. Up to 4 types of character mapping are supported. Figure 25-8. ASCII Character Mapping Character mapping saves execution time and allows a fast return to Power-save or Extended Standby mode after display updates. 25.4.8 Display Blanking When BLANK is written to one, the LCD is blanked after the completion of the current frame. All segment and common pins are driven to GND, discharging the LCD. Data in the Display Memory is preserved. Display blanking should be used before disabling the LCD to avoid DC voltage across the segments, and a slowly fading image. This mode differs from the one enabled by SEGON = 0 (in CTRLA register) where the segment and common pins are always driven by the programmed waveform and where all the segments are “OFF”. 7-Segment - 4 COM term. - 2 SEG term. 7-Segment - 3 COM term. - 3 SEG term. 16-Segment - 3 COM term. - 6 SEG term. 14-Segment - 4 COM term. - 4 SEG term. XMEGA B [MANUAL] 305 8291C–AVR–09/2014 25.4.9 Display Blinking There are two ways to blink the display, controlled from software and controlled automatically by hardware. 25.4.9.1 Software Blinking Setting / clearing segment(s) in the Display Memory allows software blinking. To blink simultaneously all enabled segments, SEGON bit in CRTLA register can be used. The blink rate is software dependant. 25.4.9.2 Hardware Blinking Up to eight segments (pixels) can be configured to automatically blink. These segments must be connected to the segment terminal SEG1 and/or SEG0. This mode is enabled by setting the BLINKEN bit in the CTRLD register and defining the associated common terminal(s) in the CTRLE register.The blink rate frequency is configured by using the BLINKRATE bit-field in the CTRLD register. A segment will blink if its corresponding bit is set in the Display Memory, otherwise it will remain “OFF”. If all bits in the CTRLE register are set to zero, then blinking is applied to all enabled segments. The BLINK command will come into operation at the beginning of the next LCD frame. Table 25-2. Blinking modes. Notes: 1. SEGON bit in CTRLA register. 25.4.10 Extended Interrupt Mode In standard interrupt mode (XIME[4:0]=0), the LCD controller can provide an interrupt every frames. When the extended interrupt mode is enabled, the LCD controller can provide the interrupt every XIME[4:0]+1 frames. This mode provides an embedded time base for user. This time base can be used by the software in charge of display updates (i.e. scrolling text, progress bar, ...). The extended interrupt mode saves real time resources and allows the application to stay longer in Power-save or Extended Standby mode. 25.4.11 LCD Power Supply The LCD power supply manages all voltages for LCD buffers. The XBIAS bit in the CTRLA register defines the source of V LCD. If XBIAS is cleared, V LCD sources voltages from the Bandgap Reference. Otherwise, V LCD must be powered externally. Note that when using external V LCD, the fine contrast controlled by FCONT[5:0] bits of the CRTLG register is inoperative. SEGON(1) BLINKEN BPS1[3:0] | BPS0[3:0] Comment 0 x 0b xxxx xxxx All segments are “OFF” 1 0 0b xxxx xxxx All segments are driven by the corresponding data registers 1 1 0b 0000 0000 All segments are blinking at the blink frequency Not equal to zero Blinking only the selected segment(s) at the blink frequency XMEGA B [MANUAL] 306 8291C–AVR–09/2014 Table 25-3. LCD power supply pins behavior. Notes: 1. ENABLE and XBIAS bits of the CTRLA register. Figure 25-9. LCD Power Supply Block Diagram Different application schemes for bias generation are shown in Figure 25-10 on page 306. Figure 25-10.Analog Connections vs. Internal or External Bias Generation ENABLE(1) XBIAS(1) VLCD (pin) BIAS2 BIAS1 CAPH / CAPL 0 x H.Z. H.Z. H.Z. H.Z. 1 0 VLCD 2 /3 VLCD (also in static mode) 1 /3 VLCD (also in static mode) Pump voltage 1 Input for VLCD - Input for BIAS2 - H.Z. if static bias - Input for BIAS1 - H.Z. if static bias H.Z. BIAS1 BIAS2 VLCD CAPL CAPH COMy SEGx XBIAS x3 x2 x1 BANDGAP Reference Pump Contrast 100 nF (1) Internal Generation Static or 1/3 Bias ATxmegaB Device CAPH CAPL VCC VLCD BIAS2 BIAS1 GND VCC 100 nF (1) 100 nF (1) 100 nF (1) ATxmegaB Device CAPH CAPL VCC VLCD BIAS2 BIAS1 GND External Generation Static VCC ATxmegaB Device VCC External Generation (example) 1/3 Bias Notes : 1: These values are provided for design guidance only. They should be optimized for the application by the designer based on actual LCD specifications. 2: Bias generation can be provided by other sources of voltage than a division resistor. Ext.VLCD (2) (2) (2) (2) Decoupling Decoupling capacitors capacitors Decoupling Decoupling capacitor capacitor Ext.VLCD CAPH CAPL VCC VLCD BIAS2 BIAS1 GND XMEGA B [MANUAL] 307 8291C–AVR–09/2014 25.4.12 Segment and Common Buses Swapping(1) Segment and/or common buses can be swapped (mirrored) to give more flexibility for LCD interconnects. The first segment (or common) terminal pin becomes the last one, and so on. It is very useful in Chip on Glass (CoG), Chip on Film (CoF) or Chip on Board (CoB) technologies. SEGSWP bit and COMSWP bit in the CRTLA register control the order of the respective terminal buses. Note: 1. Refer to specific device datasheet for availability of this feature. 25.4.13 Port Mask For LCD panels that do not use all the available segment terminals of the device, it is possible to mask some of the unused pins. PMSK bit-field in the CTRLC register defines the number of segment terminals used in the application. Up to 16 unused segment terminal pins can be used as standard GPIO pins. They are always placed at the end of the segment terminal bus. The 8 last pins of this bus will become PG[0:7] - Port G - and the following 8 pins will become PM[0:7] - Port M. The GPIO functions on LCD pins are enabled if the corresponding segment terminal is masked or if the LCD controller is disabled. A pure segment terminal - not shared with GPIO - is grounded via a pull-down resistor if it is masked or if the LCD controller is disabled. Note: SEGSWP bit, which reverses the segment terminal indexing, will be active even if the LCD controller is disabled (ENABLE bit in the CRTLA register) and will thus also modify the GPIO pin mapping. Examples of a 40-segment LCD controller: z If 30 segments are used: Segment terminals [39:32] = PG[0:7] , Port G (GPIO functions) Segment terminals [31:30] = PM[0:1] , Port M (GPIO functions) Segment terminals [29:0] = SEG[29:0] , LCD (LCD functions) z If 20 segments are used: Segment terminals [39:32] = PG[0:7] , Port G (GPIO functions) Segment terminals [31:24] = PM[0:7] , Port M (GPIO functions) Segment terminals [23:20] = GND (pull down) Segment terminals [19:0] = SEG[19:0] , LCD (LCD functions) XMEGA B [MANUAL] 308 8291C–AVR–09/2014 25.5 Register Description – LCD 25.5.1 CTRLA – Control register A z Bit 7 – ENABLE: LCD Enable Writing this bit to one enables the LCD. By writing it to zero, the LCD is turned “OFF” immediately. Turning the LCD “OFF” while driving a display, drives the output to ground to discharge the display (apart from segment terminals which will be controlled by GPIO settings). z Bit 6 – XBIAS: External Bias Generation When this bit is set, the LCD buffers which drive the intermediate voltage levels are turned “OFF”. When XBIAS is “OFF”, an external source for V LCD is necessary. z Bit 5 – DATLCK: Data Register Lock Writing this bit to one freezes the Shadow Display Memory. If the Display Memory is modified, the Shadow Display Memory is locked and the display remains unchanged. When the bit is cleared, the Shadow Display Memory is updated when a new frame starts (see Figure 25-2 on page 301). z Bit 4 – COMSWP: Common Terminal Bus Swap(1) Writing this bit to one inverts the order of the common terminal bus (COM[3:0]). The common terminals disabled by DUTY[1:0] are also affected (see Table 25-4). Table 25-4. Common terminal bus reverse. Note: 1. Refer to specific device datasheet for availability of this feature. z Bit 3 – SEGSWP: Segment Terminal Bus Swap(1) Writing this bit to one inverts completely the order of the segment terminal bus (SEG[39:0]). The segment terminals unselected by PMSK[5:0] are also affected (see Table 25-5 on page 309). Bit 7 6 5 4 3 2 1 0 +0x00 ENABLE XBIAS DATLCK COMSWP SEGSWP CLRDT SEGON BLANK Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 DUTY[1:0] Number of COM COMSWP = 0 COMSWP = 1 00 4 COM3,COM2,COM1,COM0 COM0,COM1,COM2,COM3 01 1 –, –, –, COM0 COM0, –, –, – 10 2 –, –, COM1, COM0 COM0, COM1, –, – 11 3 –, COM2, COM1, COM0 COM0, COM1, COM2, – XMEGA B [MANUAL] 309 8291C–AVR–09/2014 Table 25-5. Segment terminal bus reverse (examples) Note: 1. Refer to specific device datasheet for availability of this feature. z Bit 2 – CLRDT: Clear Data Register Writing this bit to one clears immediately the Display Memory (but not the control registers). The display will be blanked after completion of a frame. This bit is automatically reset once the Display Memory is cleared. z Bit 1 – SEGON: Segments “ON”. Writing this bit to one enables all segments and the contents of the Display Memory is output on the LCD. Writing it to zero, turns “OFF” all LCD segments. This bit can be used to flash the LCD, leaving the LCD timing generator enabled. z Bit 0 – BLANK: Blanking Display Mode When this bit is written to one, the display will be blanked after completion of a frame. All segment and common terminals will be driven to ground. (For more details see “Display Blanking” on page 304). This function does not modify the Display Memory. 25.5.2 CTRLB – Control register B z Bit 7 – PRESC: LCD Prescaler Select The PRESC bit selects a tap point from a ripple counter. The ripple counter output can be further divided by setting the Clock Divider (CLKDIV[2:0]). The different selections are shown in Table 25-6. Together they define the prescaler LCD clock (clk LCD_PS), which is clocking the LCD controller. Table 25-6. LCD prescaler selection. PMSK[5:0] Number of SEG SEGSWP = 0 SEGSWP = 1 000100 4 (SEG [39:4] unused), SEG[3:0] SEG[0:3], (SEG[4:39] unused) 001000 8 (SEG[39:8] unused), SEG[7:0] SEG[0:7], (SEG[8:39] unused) 010000 16 (SEG[39:16] unused), SEG[15:0] SEG[0:15], (SEG[16:39] unused) 101000 40 SEG[39:0] SEG[0:39] Bit 7 6 5 4 3 2 1 0 +0x01 PRESC CLKDIV[2:0] LPWAV – DUTY[1:0] Read/Write R/W R/W R/W R/W R/W R R/W R/W Initial Value 0000 0 0 0 0 PRESC Output From Ripple Counter clk LCD / N Frame Rates (CLKDIV[2:0] = 0, DUTY = 1 /4 ) F(clk LCD) = 32kHz F(clk LCD) = 32768Hz 0 clk LCD / 8 500 Hz 512 Hz 1 clk LCD / 16 250 Hz 256 Hz XMEGA B [MANUAL] 310 8291C–AVR–09/2014 z Bit 6:4 – CLKDIV[2:0]: LCD Clock Division The CLKDIV bit-field defines the division ratio in the clock divider. The various selections are shown in Table 25-7. This Clock Divider gives extra flexibility in frame rate setting. Frame rate equation: Where: N = prescaler divider (8 or 16). K = 8 for 1/4, 1/2 and static duty. K = 6 for 1/3 duty. Table 25-7. LCD clock divider (1/4 dyty). Note that when using 1/3 duty, the frame rate is increased by 33% compared to the values listed above. Table 25-8. Example of frame rate calculation. z Bit 3 – LPWAV: Low Power Waveform When LPWAV is written to one, the low power waveform is outputted on LCD pins, otherwise the standard waveform is outputted. If this bit is modified during display operation the change takes place at the beginning of the next frame. (For more details see “Low Power Waveform” on page 303). z Bit 2 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. CLKDIV[2:0] Divided by Frame Rate (1/4 Duty) F(clk LCD) = 32 kHz F(clk LCD) = 32768 Hz N=8 N=16 N=8 N=16 000 1 500 Hz 250 Hz 512 Hz 256 Hz 001 2 250 Hz 125 Hz 256 Hz 128 Hz 010 3 166.667 Hz 83.333 Hz 170.667 Hz 85.333 Hz 011 4 125 Hz 62.5 Hz 128 Hz 64 Hz 100 5 100 Hz 50 Hz 102.4 Hz 51.2 Hz 101 6 83.333 Hz 41.667 Hz 85.333 Hz 42.667 Hz 110 7 71.429 Hz 35.714 Hz 73.143 Hz 36.671 Hz 111 8 62.5 Hz 31.25 Hz 64 Hz 32 Hz clk LCD Duty K PRESC N CLKDIV[2:0] Frame rate 32.768kHz Static 8 1 16 4 32768 / ( 8 x 16 x ( 1 + 4 ) ) = 51.2Hz 32.768kHz 1/2 8 1 16 4 32768 / ( 8 x 16 x ( 1 + 4 ) ) = 51.2Hz 32.768kHz 1/3 6 1 16 4 32768 / ( 6 x 16 x ( 1 + 4 ) ) = 68.267Hz 32.768kHz 1/4 8 1 16 4 32768 / ( 8 x 16 x ( 1 + 4 ) ) = 51.2Hz FrameRate F clkLCD ( ) (K N× × ( ) 1 + CLKDIV ) = ---------------------------------------------------------------- XMEGA B [MANUAL] 311 8291C–AVR–09/2014 z Bits 1:0 – DUTY[1:0]: Duty Select(1) The DUTY bit-field defines the duty cycle. Common pins that are not used will be driven to ground. The different duty selections are shown in Table 25-9. Table 25-9. Duty cycle. Note: 1. Refer to specific device datasheet for duty cycles availability (linked to the number of available common terminals). 25.5.3 CTRLC – Control register C z Bits 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bits 5:0 – PMSK[5:0]: LCD Port Mask The PMSK bit-field defines the number of port pins to be used as segment drivers. The unused pins will be driven to ground except the 16 highest pins which become GPIO's. 25.5.4 INTCTRL – Interrupt Control register z Bits 7:3 – XIME[4:0]: eXtended Interrupt Mode Enable XIME bit-field defines the number of frames to be completed for one interrupt period. Interrupt Period = ( ( XIME[4:0] + 1 ) x 2LPWAV ) frames z For default waveforms, the FCIF flag is generated every XIME[4:0] + 1 frames. The range is 1 up to 32 frames. z For low power waveforms requiring 2 subsequent frames, the FCIF flag is generated every 2 x ( XIME[4:0] + 1 ) frames. The range is 2 up to 64 frames. Note: This extended interrupt mode generates a stable time base from the frame rate. z Bit 2 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. DUTY[1:0] Duty Bias COM pins Used 0 0 1/4 1/3 COM[0:3] 0 1 Static Static COM0 1 0 1/2 1/3 COM[0:1] 1 1 1/3 1/3 COM[0:2] Bit 7 6 5 4 3 2 1 0 +0x02 – – PMSK[5:0] Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x03 XIME[4:0] – FCINTLVL[1:0] Read/Write R/W R/W R/W R/W R/W R R/W R/W Initial Value 0 0 000000 XMEGA B [MANUAL] 312 8291C–AVR–09/2014 z Bits 1:0 – FCINTLVL[1:0]: Interrupt Level This bit-field enables the LCD frame completed interrupt and selects the interrupt level as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 121. The enabled interrupt will be triggered when the FCIF flag in the INTFLAGS register is set. 25.5.5 INTFLAGS – Interrupt Flag register z Bits 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – FCIF: LCD Frames Completed Interrupt Flag The generation of this flag depends on the XIME value in the INTCTRL register. This bit is set by hardware at the beginning of a frame. FCIF is cleared by hardware when executing the corresponding interrupt handling routine. Alternatively, writing a logical one to the flag clears FCIF. 25.5.6 CTRLD – Control register D z Bits 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3 – BLINKEN: Blink Enable Writing this bit to one, the blink mode starts at the frequency specified by LCD blink rate (BLINKRATE). By writing it to zero, the LCD blink module stops. This BLINKEN bit takes effect at the beginning of the next LCD frame. (For more details see “Display Blinking” on page 305). z Bit 2 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bits 1:0 – BLINKRATE[1:0]: LCD Blink Rate The BLINKRATE bit-field defines the frequency of the hardware Display Blinking when the BLINKEN bit is set. Blink frequencies are shown in Table 25-10. Table 25-10. Blink frequencies. Bit 7 6 5 4 3 2 1 0 +0x04 – – – – – – – FCIF Read/Write R R R R R R R R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x05 – – – – BLINKEN – BLINKRATE[1:0] Read/Write R R R R R/W R R/W R/W Initial Value 0 0 0 0 0 0 0 0 BLINKRATE[1:0] Blink frequency 00 4Hz 01 2Hz 10 1Hz 11 0.5Hz XMEGA B [MANUAL] 313 8291C–AVR–09/2014 25.5.7 CTRLE – Control register E z Bits 7:4 – BPS1[3:0]: Blink Segment Selection 1 This bit-field defines the segment which is connected on SEG1 for blinking. Each bit of BPS1[3:0] corresponds to one of the common terminals. z Bits 3:0 – BPS0[3:0]: Blink Segment Selection 0 This bit-field defines the segment which is connected on SEG0 for blinking. Each bit of BPS0[3:0] corresponds to one of the common terminals. Note: If no segment to blink is selected (BPS1[3:0] = BPS1[3:0] = 0) and if the BLINKEN bit is set, then the full display is blinking. 25.5.8 CTRLF – Control register F z Bits 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bits 5:0 – FCONT[5:0]: Fine Contrast FCONT bit-field defines the maximum voltage clk LCD on segment and common pins. FCONT is a signed number (two's complement). New values take effect at the beginning of each frame. VLCD = 3.0 V + ( FCONT[5:0] x 0.016 V ) 25.5.9 CTRLG – Control register G z Bits 7:6 – TDG[1:0]: Type of Digit(1) This bit-field specifies the number of segments and segment/common connections used to display a digit. See Table 25- 11 and Figure 25-11 on page 314. Bit 7 6 5 4 3 2 1 0 +0x06 BPS1[3:0] BPS0[3:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x07 – – FCONT[5:0] Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x08 TDG[1:0] STSEG[5:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 314 8291C–AVR–09/2014 Table 25-11. Type of digits. Note: 1. Refer to specific device datasheet for “Type of Digit” availability. z Bits 5:0 – STSEG[5:0]: Start Segment STSEG bit-field defines the first segment terminal used to write the decoded display. This bit-field is automatically incremented or decremented (according to the DEC value of CTRLH register) by the number of segment terminals used in the digit. Figure 25-11.Segment and Common Terminal Connections for Digit 25.5.10 CTRLH – Control register H z Bit 7 – DEC: Decrement of Start Segment Writing this bit to one automatically decrements the STSEG bit-field of CTRLG register by the number of segment terminals used by the digit. If this bit is written to zero, the STSEG bit-field is incremented by the number of segment terminals used by the digit. This action takes place once the digit decoding is finished and prepares the next call to the Digit Decoder. z Bits 6:0 – DCODE[6:0]: Display Code DCODE bit-field will be computed by the Digit Decoder, and converted to display codes, and then automatically written into the Display Memory according to the STSEG value. This Digit Decoder can be used when the LCD panel is defined with one or more of the configurations above in Figure 25-11 on page 314. TDG[1:0] Digit Type 00 7-segment with 3 common terminals, COM[2:0] 01 7-segment with 4 common terminals, COM[3:0] 10 14-segment with 4 common terminals, COM[3:0] 11 16-segment with 3 common terminals, COM[2:0] a e f d g b c SEGn : a, b, c SEGn+1 : d, e, f, g COM0 : a, f COM1 : b, g COM2 : c, e COM3 : d a 7-segment with 4 COM e f d g b c SEGn : b, c SEGn+1 : a, d, g SEGn+2 : e, f COM0 : a, b, f COM1 : c, e, g COM2 : d 7-segment with 3 COM SEGn : h, i, k, n SEGn+1 : d, e, f SEGn+2 : a, b, c SEGn+3 : g, j, l, m COM0 : a, g, h COM1 : b, i, j, f COM2 : c, e, k, l COM3 : d, m, n a 14-segment with 4 COM e f d j b c k g i l n m h SEGn : h, g, n SEGn+1 : a, i, l SEGn+2 : b, k, m SEGn+3 : c, d, e SEGn+4 : j, o, p SEGn+5 : f COM0 : h, a, b, c, j COM1 : g, i, k, d, o COM2 : n, l, m, p, e, f 16-segment with 3 COM f e a b g h l c d m i k n p o j Bit 7 6 5 4 3 2 1 0 +0x09 DEC DCODE[6:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0000000 XMEGA B [MANUAL] 315 8291C–AVR–09/2014 The Table 25-12 on page 315, Table 25-13 on page 316 and Table 25-14 on page 317 show the DCODE[6:0] and display pattern. The table entry code, DCODE [6:0], is the 7-bit ASCII code of the digit. Table 25-12. 7-segments Character Table. XMEGA B [MANUAL] 316 8291C–AVR–09/2014 Table 25-13. 14-segments Character Table. XMEGA B [MANUAL] 317 8291C–AVR–09/2014 Table 25-14. 16-segments Character Table. XMEGA B [MANUAL] 318 8291C–AVR–09/2014 25.5.11 DATA – LCD Data Memory Mapping The Display Memory provides access to control the “ON/OFF” state for segments. Data Memory register offset versus segment (pixel) coordinates (pixel_COM, pixel_SEG): z LCD_offset = 0x10 + ( pixel_COM x ⎣(Max_SEG + 7 ) / 8⎦ ) + ⎣pixel_SEG / 8⎦ Where: . 0x10 is the hexadecimal offset of DATA0 register, . Max_SEG is the maximal number of SEG terminals of the device, .⎣xxx⎦ means the integer part of xxx. Bit position of the segment (pixel) in the Data Memory register (between 0 and 7): z bit_position = pixel_SEG % 8 Where: . % is the modulo operation. Bit 76543210 +0x23 PIX159 PIX158 PIX157 PIX156 PIX155 PIX154 PIX153 PIX152 DATA19 +0x22 PIX[151:144] DATA18 +0x21 PIX[143:136] DATA17 +0x20 PIX[135:128] DATA16 +0x1F PIX[127:120] DATA15 +0x1E PIX[119:112] DATA14 +0x1D PIX[111:104] DATA13 +0x1C PIX[103:96] DATA12 +0x1B PIX[95:88] DATA11 +0x1A PIX[87:80] DATA10 +0x19 PIX[79:72] DATA9 +0x18 PIX[71:64] DATA8 +0x17 PIX[63:56] DATA7 +0x16 PIX[55:48] DATA6 +0x15 PIX[47:40] DATA5 +0x14 PIX[39:32] DATA4 +0x13 PIX[31:24] DATA3 +0x12 PIX[23:16] DATA2 +0x11 PIX[15:8] DATA1 +0x10 PIX7 PIX6 PIX5 PIX4 PIX3 PIX2 PIX1 PIX0 DATA0 Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 XMEGA B [MANUAL] 319 8291C–AVR–09/2014 25.6 Register Summary – LCD 25.7 Interrupt Vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x24 to Reserved – – – – – – – – +0x23 DATA19 PIX[159:152] 318 +0x22 DATA18 PIX[151:144] 318 +0x21 DATA17 PIX[143:136] 318 +0x20 DATA16 PIX[135:128] 318 +0x1F DATA15 PIX[127:120] 318 +0x1E DATA14 PIX[119:112] 318 +0x1D DATA13 PIX[111:104] 318 +0x1C DATA12 PIX[103:96] 318 +0x1B DATA11 PIX[95:88] 318 +0x1A DATA10 PIX[87:80] 318 +0x19 DATA9 PIX[79:72] 318 +0x18 DATA8 PIX[71:64] 318 +0x17 DATA7 PIX[63:56] 318 +0x16 DATA6 PIX[55:48] 318 +0x15 DATA5 PIX[47:40] 318 +0x14 DATA4 PIX[39:32] 318 +0x13 DATA3 PIX[31:24] 318 +0x12 DATA2 PIX[23:16] 318 +0x11 DATA1 PIX[15:8] 318 +0x10 DATA0 PIX[7:0] 318 +0x0A to Reserved – – – – – – – – +0x09 CTRLH DEC DCODE[6:0] 314 +0x08 CTRLG TDG[1:0] STSEG[5:0] 313 +0x07 CTRLF – – FCONT[5:0] 313 +0x06 CTRLE BPS1[3:0] BPS0[3:0] 313 +0x05 CTRLD – – – – BLINKEN – BLINKRATE[1:0] 312 +0x04 INTFLAGS – – – – – – – FCIF 312 +0x03 INTCTRL XIME[4:0] – FCINTLVL[1:0] 311 +0x02 CTRLC – – PMSK[5:0] 311 +0x01 CTRLB PRESC CLKDIV[2:0] LPWAV – DUTY[1:0] 309 +0x00 CTRLA ENABLE XBIAS DATLCK COMSWP SEGSWP CLRDT SEGON BLANK 308 Offset Source Interrupt Description 0x00 LCD_vect LCD Interrupt vector XMEGA B [MANUAL] 320 Atmel-8291C-AVR-XMEGA B -09/2014 26. ADC – Analog-to-Digital Converter 26.1 Features z 12-bit resolution z Up to 300 thousand samples per second z Down to 2.3μs conversion time with 8-bit resolution z Down to 3.35μs conversion time with 12-bit resolution z Differential and single-ended input z Up to 16 single-ended inputs z Up to 16x4 differential inputs without gain z 8x4 differential input with gain z Built-in differential gain stage z 1/2x, 1x, 2x, 4x, 8x, 16x, 32x, and 64x gain options z Single, continuous and scan conversion options z Three internal inputs z Internal temperature sensor z AVCC voltage divided by 10 z 1.1V bandgap voltage z Internal and external reference options z Compare function for accurate monitoring of user defined thresholds z Optional DMA transfer of conversion results z Optional event triggered conversion for accurate timing z Optional interrupt/event on compare result 26.2 Overview The ADC converts analog signals to digital values. The ADC has 12-bit resolution and is capable of converting up to 300 thousand samples per second (ksps). The input selection is flexible, and both single-ended and differential measurements can be done. For differential measurements, an optional gain stage is available to increase the dynamic range. In addition, several internal signal inputs are available. The ADC can provide both signed and unsigned results. The ADC measurements can either be started by application software or an incoming event from another peripheral in the device. The ADC measurements can be started with predictable timing, and without software intervention. It is possible to use DMA to move ADC results directly to memory or peripherals when conversions are done. Both internal and external reference voltages can be used. An integrated temperature sensor is available for use with the ADC. The AVCC/10 and the bandgap voltage can also be measured by the ADC. The ADC has a compare function for accurate monitoring of user defined thresholds with minimum software intervention required. XMEGA B [MANUAL] 321 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 26-1. ADC overview. 26.3 Input Sources Input sources are the voltage inputs that the ADC can measure and convert. Four types of measurements can be selected: z Differential input z Differential input with gain z Single-ended input z Internal input The input pins are used for single-ended and differential input, while the internal inputs are directly available inside the device. In devices with two ADCs, PORTA pins can be input to ADCA and PORTB pins can be input to ADCB. For the devices with only one ADC, input pins may be available for ADCA on both PORTA and PORTB. The ADC is differential, and so for single-ended measurements the negative input is connected to a fixed internal value. The four types of measurements and their corresponding input options are shown in Figure 26-2 on page 322 to Figure 26-6 on page 324. 26.3.1 Differential Input When differential input is enabled, all input pins can be selected as positive input, and input pins 0 to 3 can be selected as negative input. The ADC must be in signed mode when differential input is used. CH0 Result Compare Register < > Threshold (Int Req) Internal 1.00V Internal AVCC/1.6V AREFA AREFB VINP VINN Internal signals S&H Σ ADC DAC 2x 2 bits VIN VOUT Internal AVCC/2 ADC0 ADC15 • • • ADC0 ADC7 • • • Reference Voltage Stage 1 Stage 2 Digital Correction Logic 2 2 clkADC CH0.CTRL REFCTRL CH0.MUXCTRL CTRLA EVCTRL CTRLB Enable Start Mode Resolution Action Select XMEGA B [MANUAL] 322 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 26-2. Differential measurement without gain. 26.3.2 Differential Input with Gain When differential input with gain is enabled, all input pins can be selected as positive input, and input pins 4 to 7 can be selected as negative input. When gain is enabled, the differential input is first sampled and amplified by the gain stage before the result is converted. The ADC must be in signed mode when differential input with gain is used. The gain is selectable to 1/2x, 1x, 2x, 4x, 8x, 16x, 32x, and 64x gain. Figure 26-3. Differential measurement with gain. 26.3.3 Single-ended Input For single-ended measurements, all input pins can be used as inputs. Single-ended measurements can be done in both signed and unsigned mode. The negative input is connected to internal ground in signed mode. + - ADC0 ADC3 ADC0 ADC15 • • • • • • GND INTGND + - ADC4 ADC7 ADC0 ADC7 • • • • • • GND INTGND ½x - 64x XMEGA B [MANUAL] 323 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 26-4. Single-ended measurement in signed mode. In unsigned mode, the negative input is connected to half of the voltage reference (VREF) voltage minus a fixed offset. The nominal value for the offset is: Since the ADC is differential, the input range is VREF to zero for the positive single-ended input. The offset enables the ADC to measure zero crossing in unsigned mode, and allows for calibration of any positive offset when the internal ground in the device is higher than the external ground. See Figure 26-11 on page 326 for details. Figure 26-5. Single-ended measurement in unsigned mode. 26.3.4 Internal Inputs These internal signals can be measured or used by the ADC. z Temperature sensor z Bandgap voltage z AVCC scaled z Pad and Internal Ground The temperature sensor gives an output voltage that increases linearly with the internal temperature of the device. One or more calibration points are needed to compute the temperature from a measurement of the temperature sensor. The temperature sensor is calibrated at one point in production test, and the result is stored to TEMPESENSE0 and TEMPSENSE1 in the production signature row. For more calibration condition details, refer to the device datasheet. The bandgap voltage is an accurate internal voltage reference. VCC can be measured directly by scaling it down by a factor of 10 before the ADC input. Thus, a VCC of 1.8V will be measured as 0.18V, and VCC of 3.6V will be measured as 0.36V. This enables easy measurement of the VCC voltage. The internal signals need to be enabled before they can be measured. Refer to their manual sections for Bandgap for details of how to enable these. The sample rate for the internal signals is lower than that of the ADC. Refer to the ADC characteristics in the device datasheets for details. For differential measurement Pad Ground (Gnd) and Internal Gnd can be selected as negative input. Pad Gnd is the gnd level on the pin and identical or very close to the external gnd. Internal Gnd is the internal device gnd level. Internal Gnd is used as the negative input when other internal signals are measured in single-ended signed mode. • + ADC - ADC0 ADC15 • • ΔV VREF = × 0.05 • • + ADC - ADC0 ADC15 −ΔV VREF ____ 2 • XMEGA B [MANUAL] 324 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 26-6. Internal measurements in single-ended signed mode. To measure the internal signals in unsigned mode, the negative input is connected to a fixed value given by the formula below, which is half of the voltage reference (VREF) minus a fixed offset, as it is for single-ended unsigned input. Refer to Figure 26-11 on page 326 for details. VINN = VREF/2 - ΔV Figure 26-7. Internal measurements in unsigned mode. 26.4 Sampling Time Control To support applications with high source output resistance, the sampling time can be increased by steps of one half ADC clock cycle up to 64 ADC clock cycles. 26.5 Voltage Reference Selection The following voltages can be used as the reference voltage (VREF) for the ADC: z Accurate internal 1.00V voltage generated from the bandgap z Internal AVCC/1.6V voltage z Internal AVCC/2V voltage z External voltage applied to AREF pin on PORTA z External voltage applied to AREF pin on PORTB Figure 26-8. ADC voltage reference selection + ADC - TEMP REF AVCC SCALED BANDGAP REF + ADC - TEMP REF AVCC SCALED BANDGAP REF −ΔV VREF ____ 2 Internal 1.00V AREFB AREFA Internal AVCC/1.6V Internal AVCC/2.0V VREF XMEGA B [MANUAL] 325 Atmel-8291C-AVR-XMEGA B -09/2014 26.6 Conversion Result The result of the analog-to-digital conversion is written to the channel result register. The ADC is either in signed or unsigned mode. This setting is global for the ADC and for the ADC channel. In signed mode, negative and positive results are generated. Signed mode must be used when the ADC channel is set up for differential measurements. In unsigned mode, only single-ended or internal signals can be measured. With 12-bit resolution, the TOP value of a signed result is 2047, and the results will be in the range -2048 to +2047 (0xF800 - 0x07FF). The ADC transfer function can be written as: VINP and VINN are the positive and negative inputs to the ADC. For differential measurements, GAIN is 1/2 to 64. For single-ended and internal measurements, GAIN is always 1 and VINP is the internal ground. In unsigned mode, only positive results are generated. The TOP value of an unsigned result is 4095, and the results will be in the range 0 to +4095 (0x0 - 0x0FFF). The ADC transfer functions can be written as: VINP is the single-ended or internal input. The ADC can be configured to generate either an 8-bit or a 12-bit result. A result with lower resolution will be available faster. See the “ADC Clock and Conversion Timing” on page 326 for a description on the propagation delay. The result register is 16 bits wide, and data are stored as right adjusted 16-bit values. Right adjusted means that the eight least-significant bits (lsb) are found in the low byte. A 12-bit result can be represented either left or right adjusted. Left adjusted means that the eight most-significant bits (msb) are found in the high byte. When the ADC is in signed mode, the msb represents the sign bit. In 12-bit right adjusted mode, the sign bit (bit 11) is padded to bits 12-15 to create a signed 16-bit number directly. In 8-bit mode, the sign bit (bit 7) is padded to the entire high byte. Figure 26-9 on page 325 to Figure 26-11 on page 326 show the different input options, the signal input range, and the result representation with 12-bit right adjusted mode. Figure 26-9. Signed differential input (with gain), input range, and result representation. RES VINP - VINN VREF = --------------------------------- GAIN TOP +1 ⋅ ⋅ ( ) RES VINP - (-ΔV ) VREF = ---------------------------------- ⋅ ( ) TOP +1 2047 2046 2045 ... 3 2 1 0 -1 ... -2045 -2046 -2047 -2048 7FF 7FE 7FD ... 3 2 1 0 FFF FFE ... 803 802 801 800 Dec Hex 0111 1111 1111 0111 1111 1110 0111 1111 1101 ... 0000 0000 0011 0000 0000 0010 0000 0000 0001 0000 0000 0000 1111 1111 1111 1111 1111 1110 ... 1000 0000 0011 1000 0000 0010 1000 0000 0001 1000 0000 0000 Binary 0000 0111 1111 1111 0000 0111 1111 1110 0000 0111 1111 1101 ... 0000 0000 0000 0011 0000 0000 0000 0010 0000 0000 0000 0001 0000 0000 0000 0000 1111 1111 1111 1111 1111 1111 1111 1110 ... 1111 1000 0000 0011 1111 1000 0000 0010 1111 1000 0000 0001 1111 1000 0000 0000 VREF 16-bit result register GAIN -VREF GAIN 0 V VINN RES VINP -2 XMEGA B [MANUAL] 326 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 26-10.Signed single-ended and internal input, input range, and result representation. Figure 26-11.Unsigned single-ended and internal input, input range, and result representation. 26.7 Compare Function The ADC has a built-in 12-bit compare function. The ADC compare register can hold a 12-bit value that represents a threshold voltage. The ADC channel can be configured to automatically compare its result with this compare value to give an interrupt or event only when the result is above or below the threshold. 26.8 Starting a Conversion Before a conversion is started, the input source must be selected. An ADC conversion can be started either by the application software writing to the start conversion bit or from any events in the event system. 26.8.1 Input Source Scan It is possible to select a range of consecutive input sources that is automatically scanned and measured when a conversion is started. This is done by setting the first (lowest) positive ADC channel input using the MUX control register, and a number of consecutive positive input sources. When a conversion is started, the first selected input source is measured and converted, then the positive input source selection is incremented after each conversion until it reaches the specified number of sources to scan. 26.9 ADC Clock and Conversion Timing The ADC is clocked from the peripheral clock. The ADC can prescale the peripheral clock to provide an ADC Clock (clkADC) that matches the application requirements and is within the operating range of the ADC. 2047 2046 2045 ... 3 2 1 0 -1 -2 ... -2045 -2046 -2047 -2048 7FF 7FE 7FD ... 3 2 1 0 FFF FFE ... 803 802 801 800 Dec Hex 0111 1111 1111 0111 1111 1110 0111 1111 1101 ... 0000 0000 0011 0000 0000 0010 0000 0000 0001 0000 0000 0000 1111 1111 1111 1111 1111 1110 ... 1000 0000 0011 1000 0000 0010 1000 0000 0001 1000 0000 0000 Binary 0000 0111 1111 1111 0000 0111 1111 1110 0000 0111 1111 1101 ... 0000 0000 0000 0011 0000 0000 0000 0010 0000 0000 0000 0001 0000 0000 0000 0000 1111 1111 1111 1111 1111 1111 1111 1110 ... 1111 1000 0000 0011 1111 1000 0000 0010 1111 1000 0000 0001 1111 1000 0000 0000 16-bit result register VREF -VREF 0 V VINP VINN = GND 4095 4094 4093 ... 203 202 201 200 FFF FFE FFD ... 0CB 0CA 0C9 0C8 Dec Hex 1111 1111 1111 1111 1111 1110 1111 1111 1101 ... 0000 1100 1011 0000 1100 1010 0000 1100 1001 0000 1100 1000 Binary 0000 1111 1111 1111 0000 1111 1111 1110 0000 1111 1111 1101 ... 0000 0000 1100 1011 0000 0000 1100 1010 0000 0000 1100 1001 0000 0000 1100 1000 16-bit result register V VREF VINN = − Δ 2 GND VREF − ΔV VINP ... 0 0 0000 0000 0000 0000 0000 0000 0000 XMEGA B [MANUAL] 327 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 26-12.ADC prescaler. The propagation delay of an ADC measurement is given by: RESOLUTION is the resolution, 8 or 12 bits. The propagation delay will increase by extra ADC clock cycles if the gain stage (GAIN) is used. A new ADC conversion can start as soon as the previous is completed. The most-significant bit (msb) of the result is converted first, and the rest of the bits are converted during the next three (for 8-bit results) or five (for 12-bit results) ADC clock cycles. Converting one bit takes a half ADC clock period. During the last cycle, the result is prepared before the interrupt flag is set and the result is available in the result register for readout. 26.9.1 Single Conversion without Gain Figure 26-13 on page 327 shows the ADC timing for a single conversion without gain. The writing of the start conversion bit, or the event triggering the conversion (START), must occur at least one peripheral clock cycle before the ADC clock cycle on which the conversion starts (indicated with the grey slope of the START trigger). The input source is sampled in the first half of the first cycle. Figure 26-13.ADC timing for one single conversion without gain. 9-bit ADC Prescaler ClkADC PRESCALER[2:0] CLK/4 CLK/8 CLK/16 CLK/32 CLK/64 CLK/128 ClkPER CLK/256 CLK/512 Propagation Delay = 1 RESOLUTION + 1 2 + + ------------------------------------------------ GAIN f ADC -------------------------------------------------------------------------------- clkADC START ADC SAMPLE IF CONVERTING BIT 10 9 8 7 6 5 4 3 2 1 lsb 12345678 msb 9 XMEGA B [MANUAL] 328 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 26-14.ADC timing for one single conversion with increased sampling time (SAMPVAL = 6). 26.9.2 Single Conversion with Gain Figure 26-15 on page 328 to Figure 26-17 on page 329 show the ADC timing for one single conversion with various gain settings. As seen in the “Overview” on page 320, the gain stage is built into the ADC. Gain is achieved by running the signal through a pipeline stage without converting. Compared to a conversion without gain, each gain multiplication of 2 adds one half ADC clock cycle propagation delay. Figure 26-15.ADC timing for one single conversion with 2x gain. Figure 26-16.ADC timing for one single conversion with 8x gain. CONVERTING BIT START IF ADC SAMPLE msb 10 9 8 7 6 5 4 3 2 1 lsb clkADC 123456789 CONVERTING BIT START IF ADC SAMPLE AMPLIFY msb 10 9 8 7 6 5 4 3 2 1 lsb clkADC 123456789 CONVERTING BIT START IF ADC SAMPLE AMPLIFY msb 10 9 8 7 6 5 4 3 2 1 lsb clkADC 123456789 XMEGA B [MANUAL] 329 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 26-17.ADC timing for one single conversion with 64x gain. 26.10 ADC Input Model The voltage input must charge the sample and hold (S/H) capacitor in the ADC in order to achieve maximum accuracy. Seen externally, the ADC input consists of an input resistance (Rin = Rchannel + Rswitch) and the S/H capacitor (Csample). Figure 26-18 on page 329 and Figure 26-19 on page 329 show the ADC input channel. Figure 26-18.ADC input for single-ended measurements. Figure 26-19.ADC input for differential measurements and differential measurements with gain. In order to achieve n bits of accuracy, the source output resistance, Rsource, must be less than the ADC input resistance on a pin: where the ADC sample time, TS is one-half the ADC clock cycle given by: For details on Rchannel, Rswitch, and Csample, refer to the ADC electrical characteristic in the device datasheet. CONVERTING BIT START IF ADC SAMPLE AMPLIFY msb 10 9 8 7 6 5 4 3 2 1 lsb clkADC 123456789 10 Rsource Ts Csample 2 n + 1 ⋅ ln( ) ---------------------------------------------- Rchannel – Rswitch ≤ – Ts 1 2 ⋅ f ADC ≤ --------------------- XMEGA B [MANUAL] 330 Atmel-8291C-AVR-XMEGA B -09/2014 26.11 DMA Transfer The DMA controller can be used to transfer ADC conversion results to memory or other peripherals. A new conversion result can trigger a DMA transaction. Refer to “DMAC - Direct Memory Access Controller” on page 47 for more details on DMA transfers. 26.12 Interrupts and Events The ADC can generate interrupt requests and events. The ADC channel has individual interrupt settings and interrupt vectors. Interrupt requests and events can be generated when an ADC conversion is complete or when an ADC measurement is above or below the ADC compare register value. 26.13 Calibration The ADC has built-in linearity calibration. The value from the production test calibration must be loaded from the signature row and into the ADC calibration register from software to achieve specified accuracy. User calibration of the linearity is not needed, hence not possible. Offset and gain calibration must be done in software. 26.14 Synchronous Sampling Starting an ADC conversion can cause an unknown delay between the start trigger or event and the actual conversion since the peripheral clock is faster than the ADC clock. To start an ADC conversion immediately on an incoming event, it is possible to flush the ADC of all measurements, reset the ADC clock, and start the conversion at the next peripheral clock cycle (which then will also be the next ADC clock cycle). If this is done, the ongoing conversions in the ADC will be lost. The ADC can be flushed from software, or an incoming event can do this automatically. When this function is used, the time between each conversion start trigger must be longer than the ADC propagation delay to ensure that one conversion is finished before the ADC is flushed and the next conversion is started. It is also important to clear pending events or start ADC conversion commands before doing a flush. If not, pending conversions will start immediately after the flush. XMEGA B [MANUAL] 331 Atmel-8291C-AVR-XMEGA B -09/2014 26.15 Register Description – ADC 26.15.1 CTRLA – Control register A TBD TPUBSXMEGA-116 z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2 – CH0START: Channel Start Single Conversion Setting this bit will start an ADC conversion. Bit is cleared by hardware when the conversion has started. Writing this bit is equivalent to writing the START bits inside the ADC channel register. z Bit 1 – FLUSH: Pipeline Flush Setting this bit will flush the ADC. When this is done, the ADC clock is restarted on the next peripheral clock edge, and the conversion in progress is aborted and lost. After the flush and the ADC clock restart, the ADC will resume where it left off; i.e., if any conversions were pending, these will enter the ADC and complete. z Bit 0 – ENABLE: Enable Setting this bit enables the ADC. 26.15.2 CTRLB – ADC Control register B z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 6:5 – CURRLIMIT[1:0]: Current Limitation These bits can be used to limit the current consumption of the ADC by reducing the maximum ADC sample rate. The available settings are shown in Table 26-1. The indicated current limitations are nominal values. Refer to the device datasheet for actual current limitation for each setting. Table 26-1. ADC current limitations. Bit 7 6 5 4 3 2 1 0 +0x00 – – – – – CH0START FLUSH ENABLE Read/Write R R R R R R/W R/W R/W Initial Value 0 0000 0 00 Bit 7 6 5 4 3 2 1 0 +0x01 – CURRLIMIT[1:0] CONVMODE FREERUN RESOLUTION[1:0] – Read/Write R R/W R/W R/W R/W R/W R/W R Initial Value 0 0 0 0 0 0 0 0 CURRLIMIT[1:0] Group Configuration Description 00 NO No limit 01 LOW Low current limit, max. sampling rate 225kSPS 10 MED Medium current limit, max. sampling rate 150kSPS 11 HIGH High current limit, max. sampling rate 75kSPS XMEGA B [MANUAL] 332 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 4 – CONVMODE: Conversion Mode This bit controls whether the ADC will work in signed or unsigned mode. By default, this bit is cleared and the ADC is configured for unsigned mode. When this bit is set, the ADC is configured for signed mode. z Bit 3 – FREERUN: Free Running Mode This bit controls the free running mode for the ADC. Once a conversion is finished, the next input will be sampled and converted. z Bit 2:1 – RESOLUTION[1:0]: Conversion Result Resolution These bits define whether the ADC completes the conversion at 12- or 8-bit result resolution. They also define whether the 12-bit result is left or right adjusted within the 16-bit result registers. See Table 26-2 for possible settings. Table 26-2. ADC conversion result resolution. z Bit 0 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. 26.15.3 REFCTRL – Reference Control register z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bits 6:4 – REFSEL[2:0]: Reference Selection These bits selects the reference for the ADC according to Table 26-3. Table 26-3. ADC reference selection. RESOLUTION[1:0] Group Configuration Description 00 12BIT 12-bit result, right adjusted 01 – Reserved 10 8BIT 8-bit result, right adjusted 11 LEFT12BIT 12-bit result, left adjusted Bit 7 6 5 4 3 2 1 0 +0x02 – REFSEL[2:0] – – BANDGAP TEMPREF Read/Write R R/W R/W R/W R R R/W R/W Initial Value 0 0 0 0 0 0 0 0 REFSEL[2:0] Group Configuration Description 000 INT1V 10/11 of bandgap (1.0V) 001 INTVCC VCC/1.6 010 AREFA External reference from AREF pin on PORT A 011 AREFB External reference from AREF pin on PORT B 100 INTVCC2 VCC/2 101 - 111 – Reserved XMEGA B [MANUAL] 333 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 3:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – BANDGAP: Bandgap Enable Setting this bit enables the bandgap for ADC measurement. Note that if any other functions are already using the bandgap, this bit does not need to be set when the internal 1.00V reference is used for another ADC or if the brownout detector is enabled. z Bit 0 – TEMPREF: Temperature Reference Enable Setting this bit enables the temperature sensor for ADC measurement. 26.15.4 EVCTRL – Event Control register z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4:3 – EVSEL[1:0]: Event Channel Input Select These bits select which event channel will trigger the ADC channel. Each setting defines a group of event channels, where the event channel with the lowest number will trigger ADC channel 0, the next event channel will trigger ADC channel 1, and so on. See Table 26-4. Table 26-4. ADC event channel select. z Bit 2:0 – EVACT[2:0]: Event Mode These bits select and limit how many of the selected event input channel are used, and also further limit the ADC channels triggers. They also define more special event triggers as defined in Table 26-5. Table 26-5. ADC event mode select. Bit 7 6 5 4 3 2 1 0 +0x03 – – – EVSEL[1:0] EVACT[2:0] Read/Write R R R R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 EVSEL[1:0] Group Configuration Selected Event Lines 00 0 Event channel 0 selected inputs 01 1 Event channel 1 selected inputs 10 2 Event channel 2 selected inputs 11 3 Event channel 3 selected inputs EVACT[2:0] Group Configuration Event Input Operation Mode 000 NONE No event inputs 001 CH0 Event channel with the lowest number defined by EVSEL triggers conversion on ADC channel 010 – Reserved 011 – Reserved 100 – Reserved XMEGA B [MANUAL] 334 Atmel-8291C-AVR-XMEGA B -09/2014 26.15.5 PRESCALER – Clock Prescaler register z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2:0 – PRESCALER[2:0]: Prescaler Configuration These bits define the ADC clock relative to the peripheral clock according to Table 26-6. Table 26-6. ADC prescaler settings. 26.15.6 INTFLAGS – Interrupt Flag register z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – CH0IF: Interrupt Flags This flag is set when the ADC conversion is complete. If the ADC is configured for compare mode, the interrupt flag will be set if the compare condition is met. CH0IF is automatically cleared when the ADC interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. 101 – Reserved 110 SYNCSWEEP The ADC is flushed and restarted for accurate timing 111 – Reserved EVACT[2:0] Group Configuration Event Input Operation Mode Bit 7 6 5 4 3 2 1 0 +0x04 – – – – – PRESCALER[2:0] Read/Write R R R R R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 PRESCALER[2:0] Group Configuration Peripheral Clock Division Factor 000 DIV4 4 001 DIV8 8 010 DIV16 16 011 DIV32 32 100 DIV64 64 101 DIV128 128 110 DIV256 256 111 DIV512 512 Bit 7 6 5 4 3 2 1 0 +0x06 – – – – – – – CH0IF Read/Write R R R R R R R R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 335 Atmel-8291C-AVR-XMEGA B -09/2014 26.15.7 TEMP – Temporary register z Bit 7:0 – TEMP[7:0]: Temporary bits This register is used when reading 16-bit registers in the ADC controller. The high byte of the 16-bit register is stored here when the low byte is read by the CPU. This register can also be read and written from the user software. For more details on 16-bit register access, refer to “Accessing 16-bit Registers” on page 13. 26.15.8 SAMPCTRL – Sampling time control register z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5:0 – SAMPVAL[5:0]: sampling time control register These bits control the ADC sampling time in number of half ADC prescaled clock cycles (depends of ADC_PRESCALER value), thus controlling the ADC input impedance. Sampling time is set according to the formula: Sampling time = (SAMPVAL + 1)*(ClkADC /2) 26.15.9 CALL – Calibration Value register Low The CALL and CALH register pair hold the 12-bit calibration value. The ADC is calibrated during production programming, and the calibration value must be read from the signature row and written to the CAL register from software. z Bit 7:0 – CAL[7:0]: ADC Calibration value These are the eight lsbs of the 12-bit CAL value. 26.15.10CALH – Calibration Value register High z Bit 3:0 – CAL[11:8]: Calibration value These are the four msbs of the 12-bit CAL value. Bit 7 6 5 4 3 2 1 0 +0x07 TEMP[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0000000 Bit 7 6 5 4 3 2 1 0 +0x08 – – SAMPVAL[5:0] Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x0C CAL[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x0D – – – – CAL[11:8] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 336 Atmel-8291C-AVR-XMEGA B -09/2014 26.15.11CH0RESH – Channel 0 Result register High The CH0RESL and CH0RESH register pair represents the 16-bit value, CH0RES. For details on reading 16-bit registers, refer to “Accessing 16-bit Registers” on page 13. 26.15.11.1 12-bit Mode, Left Adjusted z Bit 7:0 – CHRES[11:4]: Channel Result High byte These are the eight msbs of the 12-bit ADC result. 26.15.11.2 12-bit Mode, Right Adjusted z Bit 7:4 – Reserved These bits will in practice be the extension of the sign bit, CHRES11, when the ADC works in differential mode, and set to zero when the ADC works in signed mode. z Bit 3:0 – CHRES[11:8]: Channel Result High byte These are the four msbs of the 12-bit ADC result. 26.15.11.3 8-bit Mode z Bit 7:0 – Reserved These bits will in practice be the extension of the sign bit, CHRES7, when the ADC works in signed mode, and set to zero when the ADC works in single-ended mode. 26.15.12 CH0RESL – Channel 0 Result register Low 26.15.12.1 12-/8-bit Mode z Bit 7:0 – CHRES[7:0]: Channel Result Low byte These are the eight lsbs of the ADC result. 26.15.12.2 12-bit Mode, Left Adjusted z Bit 7:4 – CHRES[3:0]: Channel Result Low byte These are the four lsbs of the 12-bit ADC result. z Bit 3:0 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. Bit 7 6 5 4 3 2 1 0 12-bit, left CHRES[11:4] 12-bit, right – – – – CHRES[11:8] 8-bit – – – – – – – – Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 12-/8-bit, right CHRES[7:0] 12-bit, left CHRES[3:0] – – – – Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 337 Atmel-8291C-AVR-XMEGA B -09/2014 26.15.13 CMPH – Compare register High The CMPH and CMPL register pair represents the 16-bit value, CMP. For details on reading and writing 16-bit registers, refer to “Accessing 16-bit Registers” on page 13. z Bit 7:0 – CMP[15:0]: Compare Value High byte These are the eight msbs of the 16-bit ADC compare value. In signed mode, the number representation is 2's complement, and the msb is the sign bit. 26.15.14 CMPL – Compare register Low z Bit 7:0 – CMP[7:0]: Compare Value Low byte These are the eight lsbs of the 16-bit ADC compare value. In signed mode, the number representation is 2's complement. 26.16 Register Description - ADC Channel 26.16.1 CTRL – Control Register z Bit 7 – START: START Conversion on Channel Setting this bit will start a conversion on the channel. The bit is cleared by hardware when the conversion has started. Setting this bit when it already is set will have no effect. Writing or reading this bit is equivalent to writing the CH[3:0]START bits in “CTRLA – Control register A TBD TPUBSXMEGA-116” on page 331. z Bit 6:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4:2 – GAIN[2:0]: Gain Factor These bits define the gain factor for the ADC gain stage. See Table 26-7 on page 338. Gain is valid only with certain MUX settings. See “MUXCTRL – MUX Control registers” on page 338. Bit 7 6 5 4 3 2 1 0 +0x19 CMP[15:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 000000 Bit 7 6 5 4 3 2 1 0 +0x18 CMP[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x00 START – – GAIN[2:0] INPUTMODE[1:0] Read/Write R/W R R R/W R/W R/W R/W R/W Initial Value 0 0 000000 XMEGA B [MANUAL] 338 Atmel-8291C-AVR-XMEGA B -09/2014 Table 26-7. ADC gain factor z Bit 1:0 – INPUTMODE[1:0]: Channel Input Mode These bits define the channel mode. Table 26-8. Channel input modes, CONVMODE=0 (unsigned mode). Table 26-9. Channel input modes, CONVMODE=1 (singed mode). 26.16.2 MUXCTRL – MUX Control registers The MUXCTRL register defines the input source for the channel. z Bit 7 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. GAIN[2:0] Group Configuration Gain Factor 000 1X 1x 001 2X 2x 010 4X 4x 011 8X 8x 100 16X 16x 101 32X 32x 110 64X 64x 111 DIV2 ½x INPUTMODE[1:0] Group Configuration Description 00 INTERNAL Internal positive input signal 01 SINGLEENDED Single-ended positive input signal 10 – Reserved 11 – Reserved INPUTMODE[1:0] Group Configuration Description 00 INTERNAL Internal positive input signal 01 SINGLEENDED Single-ended positive input signal 10 DIFF Differential input signal 11 DIFFWGAIN Differential input signal with gain Bit 7 6 5 4 3 2 1 0 +0x01 – MUXPOS[3:0] MUXNEG[2:0] Read/Write R R/W R/W R/W R/W R R/W R/W Initial Value 0 0000000 XMEGA B [MANUAL] 339 Atmel-8291C-AVR-XMEGA B -09/2014 z Bit 6:3 – MUXPOS[3:0]: MUX Selection on Positive ADC Input These bits define the MUX selection for the positive ADC input. Table 26-10 and Table 26-11 show the possible input selection for the different input modes. Table 26-10. ADC MUXPOS configuration when INPUTMODE[1:0] = 00 (internal) is used. Table 26-11. ADC MUXPOS configuration when INPUTMODE[1:0] = 01 (single-ended) or INPUTMODE[1:0] = 10 (differential) is used. Table 26-12. ADC MUXPOS configuration when INPUTMODE[1:0] = 11 (differential with gain) is used. MUXPOS[3:0] Group Configuration Description 0000 TEMP Temperature reference 0001 BANDGAP Bandgap voltage 0010 SCALEDVCC 1/10 scaled VCC 0011 – Reserved 0100-1111 – Reserved MUXPOS[3:0] Group Configuration Description 0000 PIN0 ADC0 pin 0001 PIN1 ADC1 pin 0010 PIN2 ADC2 pin 0011 PIN3 ADC3 pin 0100 PIN4 ADC4 pin 0101 PIN5 ADC5 pin 0110 PIN6 ADC6 pin 0111 PIN7 ADC7 pin 1000 PIN8 ADC8 pin 1001 PIN9 ADC9 pin 1010 PIN10 ADC10 pin 1011 PIN11 ADC11 pin 1100 PIN12 ADC12 pin 1101 PIN13 ADC13 pin 1110 PIN14 ADC14 pin 1111 PIN15 ADC15 pin MUXPOS[3:0] Group Configuration Description 0000 PIN0 ADC0 pin 0001 PIN1 ADC1 pin 0010 PIN2 ADC2 pin XMEGA B [MANUAL] 340 Atmel-8291C-AVR-XMEGA B -09/2014 Depending on the device pin count and feature configuration, the actual number of analog input pins may be less than 16. Refer to the device datasheet and pin-out description for details. z Bit 2:0 – MUXNEG[2:0]: MUX Selection on Negative ADC Input These bits define the MUX selection for the negative ADC input when differential measurements are done. For internal or single-ended measurements, these bits are not used. Table 26-13 and Table 26-14 show the possible input sections. Table 26-13. ADC MUXNEG configuration, INPUTMODE[1:0] = 10, differential without gain. Table 26-14. ADC MUXNEG configuration, INPUTMODE[1:0] = 11, differential with gain. 0011 PIN3 ADC3 pin 0100 PIN4 ADC4 pin 0101 PIN5 ADC5 pin 0110 PIN6 ADC6 pin 0111 PIN7 ADC7 pin 1XXX – Reserved MUXNEG[2:0] Group Configuration Analog Input 000 PIN0 ADC0 pin 001 PIN1 ADC1 pin 010 PIN2 ADC2 pin 011 PIN3 ADC3 pin 100 – Reserved 101 GND PAD ground 110 – Reserved 111 INTGND Internal ground MUXNEG[2:0] Group Configuration Analog Input 000 PIN4 ADC4 pin 001 PIN5 ADC5 pin 010 PIN6 ADC6 pin 011 PIN7 ADC7 pin 100 INTGND Internal ground 101 – Reserved 110 – Reserved 111 GND PAD ground MUXPOS[3:0] Group Configuration Description XMEGA B [MANUAL] 341 Atmel-8291C-AVR-XMEGA B -09/2014 26.16.3 INTCTRL – Interrupt Control registers z Bits 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:2 – INTMODE: Interrupt Mode These bits select the interrupt mode for the channel according to Table 26-5. Table 26-15. ADC interrupt mode. z Bits 1:0 – INTLVL[1:0]: Interrupt Priority Level and Enable These bits enable the ADC channel interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will be triggered for conditions when the IF bit in the INTFLAGS register is set. 26.16.4 INTFLAGS – Interrupt Flag registers z Bit 7:1 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 0 – IF: Interrupt Flag The interrupt flag is set when the ADC conversion is complete. If the channel is configured for compare mode, the flag will be set if the compare condition is met. IF is automatically cleared when the ADC channel interrupt vector is executed. The bit can also be cleared by writing a one to the bit location. Bit 7 6 5 4 3 2 1 0 +0x02 – – – – INTMODE[1:0} INTLVL[1:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 INTMODE[1:0] Group Configuration Interrupt Mode 00 COMPLETE Conversion complete 01 BELOW Compare result below threshold 10 – Reserved 11 ABOVE Compare result above threshold Bit 7 6 5 4 3 2 1 0 +0x03 – – – – – – – IF Read/Write R R R R R R R R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 342 Atmel-8291C-AVR-XMEGA B -09/2014 26.16.5 RESH – Result register High For all result registers and with any ADC result resolution, a signed number is represented in 2’s complement form, and the msb represents the sign bit. The RESL and RESH register pair represents the 16-bit value, ADCRESULT. Reading and writing 16-bit values require special attention. Refer to “Accessing 16-bit Registers” on page 13 for details. 26.16.5.1 12-bit Mode, Left Adjusted z Bit 7:0 – RES[11:4]: Channel Result High byte These are the eight msbs of the 12-bit ADC result. 26.16.5.2 12-bit Mode, Right Adjusted z Bit 7:4 – Reserved These bits will in practice be the extension of the sign bit, CHRES11, when the ADC works in differential mode, and set to zero when the ADC works in signed mode. z Bits 3:0 – RES[11:8]: Channel Result High bits These are the four msbs of the 12-bit ADC result. 26.16.5.3 8-bit Mode z Bit 7:0 – Reserved These bits will in practice be the extension of the sign bit, CHRES7, when the ADC works in signed mode, and set to zero when the ADC works in single-ended mode. 26.16.6 RESL – Result register Low 26.16.6.1 12-/8-bit Mode z Bit 7:0 – RES[7:0]: Result Low byte These are the eight lsbs of the ADC result. 26.16.6.2 12-bit Mode, Left Adjusted z Bit 7:4 – RES[3:0]: Result Low bits These are the four lsbs of the 12-bit ADC result. z Bit 3:0 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. Bit 7 6 5 4 3 2 1 0 12-bit, left. +0x05 RES[11:4] 12-bit, right – – – – RES[11:8] 8-bit – – – – – – – – Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 12-/8-bit, right +0x04 RES[7:0] 12-bit, left. RES[3:0] – – – – Read/Write R R R R R R R R Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 343 Atmel-8291C-AVR-XMEGA B -09/2014 26.16.7 SCAN – Input Channel Scan register Scan is enabled when COUNT is set differently than 0. z Bit 7:4 – OFFSET[3:0]: Positive MUX Setting Offset The channel scan is enabled when COUNT != 0 and this register contains the offset for the next input source to be converted on ADC channel. The actual MUX setting for positive input equals MUXPOS + OFFSET. The value is incremented after each conversion until it reaches the maximum value given by COUNT. When OFFSET is equal to COUNT, OFFSET will be cleared on the next conversion. z Bit 3:0 – COUNT[3:0]: Number of Input Channels Included in Scan This register gives the number of input sources included in the channel scan. The number of input sources included is COUNT + 1. The input channels included are the range from MUXPOS to MUXPOS + COUNT. Bit 7 6 5 4 3 2 1 0 +0x06 OFFSET[3:0] COUNT[3:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 344 Atmel-8291C-AVR-XMEGA B -09/2014 26.17 Register Summary – ADC This is the register summary when the ADC is configured to give standard 12-bit results. The register summaries for 8-bit and 12- bit left adjusted will be similar, but with some changes in the result registers, CH0RESH and CH0RESL. 26.18 Register Summary – ADC Channel 26.19 Interrupt vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRLA – – – – – CH0STAR FLUSH ENABLE 331 +0x01 CTRLB – CURRLIMIT[1:0] CONVMO FREERUN RESOLUTION[1:0] – 331 +0x02 REFCTRL – REFSEL[2:0] – – BANDGAP TEMPREF 332 +0x03 EVCTRL – – – EVSEL[1:0] EVACT[2:0] 333 +0x04 PRESCALER – – – – – PRESCALER[2:0] 334 +0x05 Reserved – – – – – – – – +0x06 INTFLAGS – – – – – – – CH0IF 334 +0x07 TEMP TEMP[7:0] 335 +0x08 SAMPCTRL – – SAMPVAL[5:0] 335 +0x09 Reserved – – – – – – – – +0x0A Reserved – – – – – – – – +0x0B Reserved – – – – – – – – +0x0C CALL CAL[7:0] 335 +0x0D CALH – – – – CAL[11:8] +0x0E Reserved – – – – – – – – +0x0F Reserved – – – – – – – – +0x10 CH0RESL CH0RES[7:0] 336 +0x11 CH0RESH CH0RES[15:8] 336 +0x12 Reserved – – – – – – – – +0x13 Reserved – – – – – – – – +0x14 Reserved – – – – – – – – +0x15 Reserved – – – – – – – – +0x16 Reserved – – – – – – – – +0x17 Reserved – – – – – – – – +0x18 CMPL CMP[7:0] 337 +0x19 CMPH CMP[15:8] 337 +0x1A Reserved – – – – – – – – +0x1B Reserved – – – – – – – – +0x1C Reserved – – – – – – – – +0x1D Reserved – – – – – – – – +0x1E Reserved – – – – – – – – +0x1F Reserved – – – – – – – – +0x20 CH0 Offset Offset address for ADC channel +0x28 Reserved – – – – – – – – +0x30 Reserved – – – – – – – – +0x38 Reserved – – – – – – – – Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 CTRL START – – GAIN[2:0] INPUTMODE[1:0] 337 +0x01 MUXCTRL – MUXPOS[3:0] MUXNEG[2:0] 338 +0x02 INTCTRL – – – – INTMODE[1:0] INTLVL[1:0] 341 +0x03 INTFLAGS – – – – – – – IF 341 +0x04 RESL RES[7:0] 342 +0x05 RESH RES[15:8] 342 +0x06 SCAN OFFSET COUNT 342 +0x07 Reserved – – – – – – – – Offset Source Interrupt Description 0x00 CH0 Analog-to-digital converter channel 0 interrupt vector XMEGA B [MANUAL] 345 Atmel-8291C-AVR-XMEGA B -09/2014 27. AC – Analog Comparator 27.1 Features z Selectable hysteresis z None z Small z Large z Analog comparator output available on pin z Flexible input selection z All pins on the port z Bandgap reference voltage z A 64-level programmable voltage scaler of the internal AVCC voltage z Interrupt and event generation on: z Rising edge z Falling edge z Toggle z Window function interrupt and event generation on: z Signal above window z Signal inside window z Signal below window z Constant current source with configurable output pin selection 27.2 Overview The analog comparator (AC) compares the voltage levels on two inputs and gives a digital output based on this comparison. The analog comparator may be configured to generate interrupt requests and/or events upon several different combinations of input change. The analog comparator hysteresis can be adjusted in order to achieve the optimal operation for each application. The input selection includes analog port pins, several internal signals, and a 64-level programmable voltage scaler. The analog comparator output state can also be output on a pin for use by external devices. A constant current source can be enabled and output on a selectable pin. This can be used to replace, for example, external resistors used to charge capacitors in capacitive touch sensing applications. The analog comparators are always grouped in pairs on each port. These are called analog comparator 0 (AC0) and analog comparator 1 (AC1). They have identical behavior, but separate control registers. Used as pair, they can be set in window mode to compare a signal to a voltage range instead of a voltage level. XMEGA B [MANUAL] 346 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 27-1. Analog comparator overview. 27.3 Input Sources Each analog comparator has one positive and one negative input. Each input may be chosen from a selection of analog input pins and internal inputs such as a AVCC voltage scaler. The digital output from the analog comparator is one when the difference between the positive and the negative input voltage is positive, and zero otherwise. 27.3.1 Pin Inputs Any of analog input pins on the port can be selected as input to the analog comparator. 27.3.2 Internal Inputs Two internal inputs are available for the analog comparator: z Bandgap reference voltage z Voltage scaler, which provides a 64-level scaling of the internal AVCC voltage 27.4 Signal Compare In order to start a signal comparison, the analog comparator must be configured with the preferred properties and inputs before the module is enabled. The result of the comparison is continuously updated and available for application software and the event system. 27.5 Interrupts and Events The analog comparator can be configured to generate interrupts when the output toggles, when the output changes from zero to one (rising edge), or when the output changes from one to zero (falling edge). Events are generated at all times for the same condition as the interrupt, regardless of whether the interrupt is enabled or not. ACnMUXCTRL ACnCTRL Interrupt Mode Enable Enable Hysteresis Hysteresis AC1OUT WINCTRL Interrupt Sensititivity Control & Window Function Events Interrupts AC0OUT Pin Input Pin Input Pin Input Pin Input Voltage Scaler Bandgap + AC0 - + AC1 - XMEGA B [MANUAL] 347 Atmel-8291C-AVR-XMEGA B -09/2014 27.6 Window Mode Two analog comparators on the same port can be configured to work together in window mode. In this mode, a voltage range is defined, and the analog comparators give information about whether an input signal is within this range or not. Figure 27-2. The Analog comparators in window mode. 27.7 Input Hysteresis Application software can select between no-, low-, and high hysteresis for the comparison. Applying a hysteresis will help prevent constant toggling of the output that can be caused by noise when the input signals are close to each other. AC0 + - AC1 + - Input signal Upper limit of window Lower limit of window Interrupt sensitivity control Interrupts Events XMEGA B [MANUAL] 348 Atmel-8291C-AVR-XMEGA B -09/2014 27.8 Register Description 27.8.1 ACnCTRL – Analog Comparator n Control register z Bit 7:6 – INTMODE[1:0]: Interrupt Modes These bits configure the interrupt mode for analog comparator n according to Table 27-1. Table 27-1. Interrupt settings. z Bit 5:4 – INTLVL[1:0]: Interrupt Level These bits enable the analog comparator n interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will trigger according to the INTMODE setting. z Bit 3 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 2:1 – HYSMODE[1:0]: Hysteresis Mode Select These bits select the hysteresis mode according to Table 27-2. For details on actual hysteresis levels, refer to the device datasheet. Table 27-2. Hysteresis settings. z Bit 0 – ENABLE: Enable Setting this bit enables analog comparator n. Bit 7 6 5 4 3 2 1 0 +0x00 / +0x01 INTMODE[1:0] INTLVL[1:0] – HYSMODE[2:0] ENABLE Read/Write R/W R/W R/W R/W R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 INTMODE[1:0] Group Configuration Description 00 BOTHEDGES Comparator interrupt or event on output toggle 01 – Reserved 10 FALLING Comparator interrupt or event on falling output edge 11 RISING Comparator interrupt or event on rising output edge HYSMODE[1:0] Group Configuration Description 00 NO No hysteresis 01 SMALL Small hysteresis 10 LARGE Large hysteresis 11 – Reserved XMEGA B [MANUAL] 349 Atmel-8291C-AVR-XMEGA B -09/2014 27.8.2 ACnMUXCTRL – Analog Comparator n Mux Control register z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5:3 – MUXPOS[2:0]: Positive Input MUX Selection These bits select which input will be connected to the positive input of analog comparator n according to Table 27-3. Table 27-3. Positive input MUX selection. z Bit 2:0 – MUXNEG[2:0]: Negative Input MUX Selection These bits select which input will be connected to the negative input of analog comparator n according to Table 27-4. Table 27-4. Negative input MUX selection. Bit 7 6 5 4 3 2 1 0 +0x02 / +0x03 – – MUXPOS[2:0] MUXNEG[2:0] Read/Write R R R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 MUXPOS[2:0] Group Configuration Description 000 PIN0 Pin 0 001 PIN1 Pin 1 010 PIN2 Pin 2 011 PIN3 Pin 3 100 PIN4 Pin 4 101 PIN5 Pin 5 110 PIN6 Pin 6 111 – Reserved MUXNEG[2:0] Group Configuration Negative Input MUX Selection 000 PIN0 Pin 0 001 PIN1 Pin 1 010 PIN3 Pin 3 011 PIN5 Pin 5 100 PIN7 Pin 7 101 – Reserved 110 BANDGAP Internal bandgap voltage 111 SCALER AVCC voltage scaler XMEGA B [MANUAL] 350 Atmel-8291C-AVR-XMEGA B -09/2014 27.8.3 CTRLA – Control register A z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – AC1OUT: Analog Comparator 1 Output Setting this bit makes the output of AC1 available on pin 6 of the port. z Bit 0 – AC0OUT: Analog Comparator 0 Output Setting this bit makes the output of AC0 available on pin 7 of the port. 27.8.4 CTRLB – Control register B z Bit 7:6 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 5:0 – SCALEFAC[5:0]: Voltage Scaling Factor These bits define the scaling factor for the AVcc voltage scaler. The input to the analog comparator, VSCALE, is: 27.8.5 WINCTRL – Window Function Control register z Bit 7:5 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 4 – WEN: Window Mode Enable Setting this bit enables the analog comparator window mode. z Bits 3:2 – WINTMODE[1:0]: Window Interrupt Mode Settings These bits configure the interrupt mode for the analog comparator window mode according to Table 27-5. Bit 7 6 5 4 3 2 1 0 +0x04 – – – – – – AC1OUT AC0OUT Read/Write R R R R R R R/W R/W Initial Value 0 0 000000 Bit 7 6 5 4 3 2 1 0 +0x05 – – SCALEFAC[5:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 00000000 VSCALE V CC ⋅ ( ) SCALEFAC + 1 64 = ------------------------------------------------------------- Bit 7 6 5 4 3 2 1 0 +0x06 – – – WEN WINTMODE[1:0] WINTLVL[1:0] Read/Write R R R R/W R/W R/W R/W R/W Initial Value 0 0 000000 XMEGA B [MANUAL] 351 Atmel-8291C-AVR-XMEGA B -09/2014 Table 27-5. Window mode interrupt settings. z Bits 1:0 – WINTLVL[1:0]: Window Interrupt Enable These bits enable the analog comparator window mode interrupt and select the interrupt level, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. The enabled interrupt will trigger according to the WINTMODE setting. 27.8.6 STATUS – Status register z Bits 7:6 – WSTATE[1:0]: Window Mode Current State These bits show the current state of the signal if window mode is enabled according to Table 27-6. Table 27-6. Window mode current state. z Bit 5 – AC1STATE: Analog Comparator 1 Current State This bit shows the current state of the output signal from AC1. z Bit 4 – AC0STATE: Analog Comparator 0 Current State This bit shows the current state of the output signal fromAC0. z Bit 3 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. z Bit 2 – WIF: Analog Comparator Window Interrupt Flag This is the interrupt flag for the window mode. WIF is set according to the WINTMODE setting in the “WINCTRL – Window Function Control register” on page 350. This flag is automatically cleared when the analog comparator window interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. z Bit 1 – AC1IF: Analog Comparator 1 Interrupt Flag This is the interrupt flag for AC1. AC1IF is set according to the INTMODE setting in the corresponding “ACnCTRL – Analog Comparator n Control register” on page 348. WINTMODE[1:0] Group Configuration Description 00 ABOVE Interrupt on signal above window 01 INSIDE Interrupt on signal inside window 10 BELOW Interrupt on signal below window 11 OUTSIDE Interrupt on signal outside window Bit 7 6 5 4 3 2 1 0 +0x07 WSTATE[1:0] AC1STATE AC0STATE – WIF AC1IF AC0IF Read/Write R/W R/W R/W R/W R R/W R/W R/W Initial Value 0 0 000000 WSTATE[1:0] Group Configuration Description 00 ABOVE Signal is above window 01 INSIDE Signal is inside window 10 BELOW Signal is below window 11 OUTSIDE Signa is outside window XMEGA B [MANUAL] 352 Atmel-8291C-AVR-XMEGA B -09/2014 This flag is automatically cleared when the analog comparator 1 interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. z Bit 0 – AC0IF: Analog Comparator 0 Interrupt Flag This is the interrupt flag for AC0. AC0IF is set according to the INTMODE setting in the corresponding “ACnCTRL – Analog Comparator n Control register” on page 348. This flag is automatically cleared when the analog comparator 0 interrupt vector is executed. The flag can also be cleared by writing a one to its bit location. 27.8.7 CURRCTRL – Current Source Control register z Bit 7 – CURRENT: Current Source Enable Setting this bit to one will enable the constant current source. z Bit 6:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – AC1CURR: AC1 Current Source Output Enable Setting this bit to one will enable the constant current source output on the pin selected by MUXNEG in AC1MUXTRL. z Bit 0 – AC0CURR: AC0 Current Source Output Enable Setting this bit to one will enable the constant current source output on the pin selected by MUXNEG in AC0MUXTRL. 27.8.8 CURRCALIB – Current Source Calibration register z Bits 7:4 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 3:0 – CALIB[3:0]: Current Source Calibration The constant current source is calibrated during production. A calibration value can be read from the signature row and written to the CURRCALIB register from software. Refer to device data sheet for default calibration values and user calibration range. Bit 7 6 5 4 3 2 1 0 +0x08 CURRENT – – – – – AC1CURR AC0CURR Read/Write R/W R R R R R R/W R/W Initial Value 0 0 0000 0 0 Bit 7 6 5 4 3 2 1 0 +0x09 – – – – CALIB[3:0] Read/Write R R R R R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 XMEGA B [MANUAL] 353 Atmel-8291C-AVR-XMEGA B -09/2014 27.9 Register Summary 27.10 Interrupt vector Summary Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 AC0CTRL INTMODE[1:0] INTLVL[1:0] – HYSMODE[1:0] ENABLE 348 +0x01 AC1CTRL INTMODE[1:0] INTLVL[1:0] – HYSMODE[1:0] ENABLE 348 +0x02 AC0MUXCTR – – MUXPOS[2:0] MUXNEG[2:0] 349 +0x03 AC1MUXCTR – – MUXPOS[2:0] MUXNEG[2:0] 349 +0x04 CTRLA – – – – – – AC1OUT ACOOUT 350 +0x05 CTRLB – – SCALEFAC5:0] 350 +0x06 WINCTRL – – – WEN WINTMODE[1:0] WINTLVL[1:0] 350 +0x07 STATUS WSTATE[1:0] AC1STATE AC0STATE – WIF AC1IF AC0IF 351 +0x08 CURRCTRL CURRENT – – – – – AC1CURR AC0CURR 352 +0x09 CURRCALIB – – – – CALIB[3:0] 352 Offset Source Interrupt Description 0x00 COMP0_vect Analog comparator 0 interrupt vector 0x02 COMP1_vect Analog comparator 1 interrupt vector 0x04 WINDOW_vect Analog comparator window interrupt vector XMEGA B [MANUAL] 354 Atmel-8291C-AVR-XMEGA B -09/2014 28. IEEE 1149.1 JTAG Boundary Scan Interface 28.1 Features • JTAG (IEEE Std. 1149.1-2001 compliant) interface • Boundary scan capabilities according to the JTAG standard • Full scan of all I/O pins • Supports the mandatory SAMPLE, IDCODE, PRELOAD, EXTEST, and BYPASS instructions • Supports the optional HIGHZ and CLAMP instructions • Supports the AVR-specific PDICOM instruction for accessing the PDI 28.2 Overview The JTAG interface is mainly intended for testing PCBs by using the JTAG boundary scan capability. Secondarily, the JTAG interface is used to access the Program and Debug Interface (PDI) in its optional JTAG mode. The boundary scan chain has the capability of driving and observing the logic levels on I/O pins. At the system level, all microcontroller or board components having JTAG capabilities are connected serially by the TDI/TDO signals to form a long shift register. An external controller sets up the devices to drive values at their output pins, and observes the input values received from other devices. The controller compares the received data with the expected result. In this way, boundary scan method provides a mechanism for testing the interconnections and integrity of components on printed circuit boards by using only the four test access port (TAP) signals. The IEEE Std. 1149.1-2001 defined mandatory JTAG instructions, IDCODE, BYPASS, SAMPLE/ PRELOAD, and EXTEST, together with the optional CLAMP and HIGHZ instructions can be used for testing the printed circuit board. Alternatively, the HIGHZ instruction can be used to place all I/O pins in an inactive drive state, while bypassing the boundary scan register chain of the chip. The AVR-specific PDICOM instruction makes it possible to use the PDI data register as an interface for accessing the PDI for programming and debugging. This provides an alternative way to access internal programming and debugging resources by using the JTAG interface. For more details on PDI, programming, and on-chip debugging, refer to “Program and Debug Interface” on page 393. The JTAGEN fuse must be programmed and the JTAGD bit in the MCUCR register must be cleared to enable the JTAG interface and TAP. See “FUSEBYTE4 – Fuse Byte4” on page 31, and “MCUCR – Control register” on page 45 for more details. When using the JTAG interface for boundary scan, the JTAG TCK clock frequency can be higher than the internal device frequency. A system clock in the device is not required for boundary scan. 28.3 TAP - Test Access Port The JTAG interface requires and uses four device I/O pins. In JTAG terminology, these pins constitute the test access port, or TAP. These pins are: z TMS: Test mode select. The pin is used for navigating through the TAP-controller state machine z TCK: Test clock. This is the JTAG clock signal, and all operation is synchronous to TCK z TDI: Test data in. Serial input data to be shifted in to the instruction register or data register (scan chains) z TDO: Test data out. Serial output data from the instruction register or data register The IEEE Std. 1149.1-2001 also specifies an optional test reset signal, TRST. This signal is not available. When the JTAGEN fuse is unprogrammed or the JTAG disable bit is set, the JTAG interface is disabled. The four TAP pins are normal port pins, and the TAP controller is in reset. When enabled, the input TAP signals are internally pulled high and JTAG is enabled for boundary scan operations. XMEGA B [MANUAL] 355 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 28-1. TAP controller state diagram. The TAP controller is a 16-state, finite state machine that controls the operation of the boundary scan circuitry. The state transitions shown in Figure 28-1 depend on the signal present on TMS (shown adjacent to each state transition) at the time of the rising edge on TCK. The initial state after a power-on reset is the test logic reset state. Assuming the present state is run test/idle, a typical scenario for using the JTAG interface is: z At the TMS input, apply the sequence 1, 1, 0, 0 at the rising edges of TCK to enter the shift instruction register, or shift IR, state. While in this state, shift the four bits of the JTAG instruction into the JTAG instruction register from the TDI input at the rising edge of TCK. The TMS input must be held low during input of the 3 lsbs in order to remain in the shift IR state. The msb of the instruction is shifted in when this state is left by setting TMS high. While the instruction is shifted in from the TDI pin, the captured IR state, 0x01, is shifted out on the TDO pin. The JTAG instruction selects a particular data register as the path between TDI and TDO and controls the circuitry surrounding the selected data register z Apply the TMS sequence 1, 1, 0 to reenter the run test/idle state. The instruction is latched onto the parallel output from the shift register path in the update IR state. The exit IR, pause IR, and exit2 IR states are used only for navigating the state machine z At the TMS input, apply the sequence 1, 0, 0 at the rising edges of TCK to enter the shift data register, or shift DR, state. While in this state, upload the selected data register (selected by the present JTAG instruction in the JTAG instruction register) from the TDI input at the rising edge of TCK. In order to remain in the shift DR state, the TMS input must be held low during the input of all bits except the msb. The msb of the data is shifted in when this state is left by setting TMS high. While the data register is shifted in from the TDI pin, the parallel inputs to the data register captured in the capture DR state are shifted out on the TDO pin z Apply the TMS sequence 1, 1, 0 to reenter the run test/idle state. If the selected data register has a latched parallel output, the latching takes place in the update DR state. The exit DR, pause DR, and exit2 DR states are used only for navigating the state machine. XMEGA B [MANUAL] 356 Atmel-8291C-AVR-XMEGA B -09/2014 As shown in the state diagram, the run test/idle state need not be entered between selecting JTAG instructions and using data registers. Note: Independently of the initial state of the TAP controller, the test logic reset state can always be entered by holding TMS high for five TCK clock periods. 28.4 JTAG Instructions The instruction register is four bits wide. Listed below are the JTAG instructions for boundary scan operation and the PDICOM instruction used for accessing the PDI in JTAG mode. The lsb is shifted in and out first for all shift registers. The opcode for each instruction is shown beside the instruction name in hex format. The text describes which data register is selected as the path between TDI and TDO for each instruction. 28.4.1 EXTEST; 0x1 EXTEST is the instruction for selecting the boundary scan chain as the data register for testing circuitry external to the AVR XMEGA device package. The instruction is used for sampling external pins and loading output pins with data. For the I/O port pins, both output control (DIR) and output data (OUT) are controllable via the scan chain, while the output control and actual pin value are observable. The contents of the latched outputs of the boundary scan chain are driven out as soon as the JTAG instruction register is loaded with the EXTEST instruction. The active states are: z Capture DR: Data on the external pins are sampled into the boundary scan chain z Shift DR: Data in the Boundary-scan Chain are shifted by the TCK input z Update DR: Data from the scan chain are applied to output pins 28.4.2 IDCODE; 0x3 IDCODE is the instruction for selecting the 32-bit ID register as the data register. The ID register consists of a version number, a device number, and the manufacturer code chosen by the Joint Electron Devices Engineering Council (JEDEC). This is the default instruction after power up. The active states are: z Capture DR: Data in the IDCODE register are sampled into the device identification register z Shift DR: The IDCODE scan chain is shifted by the TCK input 28.4.3 SAMPLE/PRELOAD; 0x2 SAMPLE/PRELOAD is the instruction for preloading the output latches and taking a snapshot of the input/output pins without affecting system operation. However, the output latches are not connected to the pins. The boundary scan chain is selected as the data register. Since each of the SAMPLE and PRELOAD instructions implements the functionality of the other, they share a common binary value, and can be treated as a single, merged instruction. The active states are: z Capture DR: Data on the external pins are sampled into the boundary scan chain z Shift DR: The boundary scan chain is shifted by the TCK input z Update DR: Data from the boundary scan chain are applied to the output latches, but the output latches are not connected to the pins 28.4.4 BYPASS; 0xf BYPASS is the instruction for selecting the bypass register for the data register. This instruction can be issued to make the shortest possible scan chain through the device. XMEGA B [MANUAL] 357 Atmel-8291C-AVR-XMEGA B -09/2014 The active states are: z Capture DR: Loads a zero into the bypass register z Shift DR: The bypass register cell between TDI and TDO is shifted 28.4.5 CLAMP; 0x4 CLAMP is an optional instruction that allows the state of the input/output pins to be determined from the preloaded output latches. The instruction allows static pin values to be applied via the boundary scan registers while bypassing these registers in the scan path, efficiently shortening the total length of the serial test path. The bypass register is selected as the data register. The active states are: z Capture DR: Loads a zero into the bypass register z Shift DR: The bypass register cell between TDI and TDO is shifted 28.4.6 HIGHZ; 0x5 HIGHZ is an optional instruction for putting all outputs in an inactive drive state (e.g., high impedance). The bypass register is selected as the data register. The active states are: z Capture DR: Loads a zero into the bypass register z Shift DR: The bypass register cell between TDI and TDO is shifted 28.4.7 PDICOM; 0x7 PDICOM is an AVR XMEGA specific instruction for using the JTAG TAP as an alternative interface to the PDI. The active states are: z Capture DR: Parallel data from the PDI are sampled into the PDICOM data register z Shift DR: The PDICOM data register is shifted by the TCK input z Update DR: Commands or operands are parallel-latched from the PDICOM data register into the PDI 28.5 Boundary Scan Chain The boundary scan chain has the capability of driving and observing the logic levels on the I/O pins. To ensure a predictable device behavior during and after the EXTEST, CLAMP, and HIGHZ instructions, the device is automatically put in reset. During active reset, the external oscillators, analog modules, and non-default port pin settings (like pullup/down, bus-keeper, wired-AND/OR) are disabled. It should be noted that the current device and port pin state are unaffected by the SAMPLE and PRELOAD instructions. 28.5.1 Scanning the Port Pins Figure 28-2 on page 358 shows the boundary scan cell used for all the bidirectional port pins. This cell is able to control and observe both pin direction and pin value via a two-stage shift register. When no alternate port function is present, output control corresponds to the DIR register value, output data corresponds to the OUT register value, and input data corresponds to the IN register value (tapped before the input inverter and input synchronizer). Mode represents either an active CLAMP or EXTEST instruction, while shift DR is set when the TAP controller is in its shift DR state. XMEGA B [MANUAL] 358 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 28-2. Boundary scan cell for bi-directional port pin. 28.5.2 Scanning the PDI Pins Two observe-only cells are inserted to make the combined RESET and PDI_CLK pin and the PDI_DATA pin observable. Even though the PDI_DATA pin is bidirectional, it is only made observable in order to avoid any extra logic on the PDI_DATA output path. Figure 28-3. An observe-only input cell. Q D D Q D Q D Q Input Data (IN) Output Data (IN) Output Control (DIR) Mode Pn Shift DR To next cell From last cell Clock DR Update DR 0 1 0 1 0 0 1 1 En D Q From last cell Clock DR To next cell To system logic From system pin Shift DR 1 0 XMEGA B [MANUAL] 359 Atmel-8291C-AVR-XMEGA B -09/2014 28.6 Data Registers The supported data registers that can be connected between TDI and TDO are: z Bypass register (Ref: register A in Figure 28-4 on page 359). z Device identification register (Ref: register C in Figure 28-4 on page 359). z Boundary scan chain (Ref: register D in Figure 28-4 on page 359). z PDICOM data register (Ref: register B in Figure 28-4 on page 359) Figure 28-4. JTAG data register overview. 28.6.1 Bypass Register The bypass register consists of a single shift register stage. When the bypass register is selected as the path between TDI and TDO, the register is reset to 0 when leaving the capture DR controller state. The bypass register can be used to shorten the scan chain on a system when the other devices are to be tested. 28.6.2 Device Identification Register 28.6.2.1 Version Version is a 4-bit number identifying the revision of the device. The JTAG version number follows the revision of the device. Revision A is 0x0, revision B is 0x1, and so on. 28.6.2.2 Part Number The part number is a 16-bit code identifying the device. Refer to the device data sheets to find the correct number. 28.6.2.3 Manufacturer ID The manufacturer ID is an 11-bit code identifying the manufacturer. For Atmel, this code is 0x01F. D D TDI A B B B C C C C TDO TMS D D D D D D D D D I/O PORTS PDI JTAG TCK to all TCK registers Internal registers JTAG Boundary-scan chain TAP CTRL MSB LSB Bit 31 28 27 12 11 1 0 Device ID Version Part Number Manufacturer ID 1 4 bits 16 bits 11 bits 1 bit XMEGA B [MANUAL] 360 Atmel-8291C-AVR-XMEGA B -09/2014 28.6.3 Boundary Scan Chain The boundary scan chain has the capability of driving and observing the logic levels on all I/O pins. Refer to “Boundary Scan Chain” on page 357 for a complete description. 28.6.4 PDICOM Data Register The PDICOM data register is a 9-bit wide register used for serial-to-parallel and parallel-to-serial conversions of data between the JTAG TAP and the PDI. For details, refer to “Program and Debug Interface” on page 393. Document Footer Title [PRELIMINARY DATASHEET] 361 Atmel-8291C-AVR-XMEGA B -09/2014 29. Program and Debug Interface 29.1 Features z Programming ̶ External programming through PDI or JTAG interfaces z Minimal protocol overhead for fast operation z Built-in error detection and handling for reliable operation ̶ Boot loader support for programming through any communication interface z Debugging ̶ Nonintrusive, real-time, on-chip debug system ̶ No software or hardware resources required from device except pin connection ̶ Program flow control z Go, Stop, Reset, Step Into, Step Over, Step Out, Run-to-Cursor ̶ Unlimited number of user program breakpoints ̶ Unlimited number of user data breakpoints, break on: z Data location read, write, or both read and write z Data location content equal or not equal to a value z Data location content is greater or smaller than a value z Data location content is within or outside a range ̶ No limitation on device clock frequency z Program and Debug Interface (PDI) ̶ Two-pin interface for external programming and debugging ̶ Uses the Reset pin and a dedicated pin ̶ No I/O pins required during programming or debugging z JTAG interface ̶ Four-pin, IEEE Std. 1149.1 compliant interface for programming and debugging ̶ Boundary scan capabilities according to IEEE Std. 1149.1 (JTAG) 29.2 Overview The Program and Debug Interface (PDI) is an Atmel proprietary interface for external programming and on-chip debugging of a device. The PDI supports fast programming of nonvolatile memory (NVM) spaces; flash, EEPOM, fuses, lock bits, and the user signature row. This is done by accessing the NVM controller and executing NVM controller commands, as described in “Memory Programming” on page 407. Debug is supported through an on-chip debug system that offers nonintrusive, real-time debug. It does not require any software or hardware resources except for the device pin connection. Using the Atmel tool chain, it offers complete program flow control and support for an unlimited number of program and complex data breakpoints. Application debug can be done from a C or other high-level language source code level, as well as from an assembler and disassembler level. Programming and debugging can be done through two physical interfaces. The primary one is the PDI physical layer, which is available on all devices. This is a two-pin interface that uses the Reset pin for the clock input (PDI_CLK) and one other dedicated pin for data input and output (PDI_DATA). A JTAG interface is also available on most devices, and this can be used for programming and debugging through the four-pin JTAG interface. The JTAG interface is IEEE Std. 1149.1 compliant, and supports boundary scan. Any external programmer or on-chip debugger/emulator can be directly connected to either of these interfaces. Unless otherwise stated, all references to the PDI assume access through the PDI physical layer. Document Footer Title [PRELIMINARY DATASHEET] 362 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 29-1. The PDI with JTAG and PDI physical layers and closely related modules (grey). 29.3 PDI Physical The PDI physical layer handles the low-level serial communication. It uses a bidirectional, half-duplex, synchronous serial receiver and transmitter (just as a USART in USRT mode). The physical layer includes start-of-frame detection, frame error detection, parity generation, parity error detection, and collision detection. In addition to PDI_CLK and PDI_DATA, the PDI_DATA pin has an internal pull resistor, VCC and GND must be connected between the External Programmer/debugger and the device. Figure 29-2 on page 362 shows a typical connection. Figure 29-2. PDI connection. The remainder of this section is intended for use only by third parties developing programmers or programming support for Atmel AVR XMEGA devices. 29.3.1 Enabling The PDI physical layer must be enabled before use. This is done by first forcing the PDI_DATA line high for a period longer than the equivalent external reset minimum pulse width (refer to device datasheet for external reset pulse width data). This will disable the RESET functionality of the Reset pin, if not already disabled by the fuse settings. Next, continue to keep the PDI_DATA line high for 16 PDI_CLK cycles. The first PDI_CLK cycle must start no later than 100μs after the RESET functionality of the Reset pin is disabled. If this does not occur in time, the enabling procedure must start over again. The enable sequence is shown in Figure 29-3 on page 363. PDI Controller JTAG Physical (physical layer) PDI Physical (physical layer) OCD NVM Controller Program and Debug Interface (PDI) PDI_CLK PDI_DATA TDO TCK TMI TDI NVM Memories PDIBUS Internal Interfaces PDI Connector GND VCC PDI_CLK PDI_DATA Document Footer Title [PRELIMINARY DATASHEET] 363 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 29-3. PDI physical layer enable sequence. The Reset pin is sampled when the PDI interface is enabled. The reset register is then set according to the state of the Reset pin, preventing the device from running code after the reset functionality of this pin is disabled. 29.3.2 Disabling If the clock frequency on PDI_CLK is lower than approximately 10kHz, this is regarded as inactivity on the clock line. This will automatically disable the PDI. If not disabled by a fuse, the reset function of the Reset (PDI_CLK) pin is enabled again. This also means that the minimum programming frequency is approximately 10kHz. 29.3.3 Frame Format and Characters The PDI physical layer uses a frame format defined as one character of eight data bits, with a start bit, a parity bit, and two stop bits. Figure 29-4. PDI serial frame format. Three different characters are used, DATA, BREAK, and IDLE. The BREAK character is equal to a 12-bit length of low level. The IDLE character is equal to a 12- bit length of high level. The BREAK and IDLE characters can be extended beyond the 12-bit length. Figure 29-5. Characters and timing for the PDI physical layer. Disable RESET function on Reset (PDI_CLK) pin Activate PDI PDI_DATA PDI_CLK St Start bit, always low (0-7) Data bits (0 to 7) P Parity bit, even parity used Sp1 Stop bit 1, always high Sp2 Stop bit 2, always high St 012 3 4567P Sp1 FRAME (IDLE) Sp2 (St/IDLE) START 012 3 4567P STOP 1 IDLE character BREAK IDLE 1 DATA character 1 BREAK character Document Footer Title [PRELIMINARY DATASHEET] 364 Atmel-8291C-AVR-XMEGA B -09/2014 29.3.4 Serial Transmission and Reception The PDI physical layer is either in transmit (TX) or receive (RX) mode. By default, it is in RX mode, waiting for a start bit. The programmer and the PDI operate synchronously on the PDI_CLK provided by the programmer. The dependency between the clock edges and data sampling or data change is fixed. As illustrated in Figure 29-6 on page 364, output data (either from the programmer or the PDI) is always set up (changed) on the falling edge of PDI_CLK and sampled on the rising edge of PDI_CLK. Figure 29-6. Changing and sampling of data. 29.3.5 Serial Transmission When a data transmission is initiated, by the PDI controller, the transmitter simply shifts out the start bit, data bits, parity bit, and the two stop bits on the PDI_DATA line. The transmission speed is dictated by the PDI_CLK signal. While in transmission mode, IDLE bits (high bits) are automatically transmitted to fill possible gaps between successive DATA characters. If a collision is detected during transmission, the output driver is disabled, and the interface is put into RX mode waiting for a BREAK character. 29.3.6 Serial Reception When a start bit is detected, the receiver starts to collect the eight data bits. If the parity bit does not correspond to the parity of the data bits, a parity error has occurred. If one or both of the stop bits are low, a frame error has occurred. If the parity bit is correct, and no frame error is detected, the received data bits are available for the PDI controller. When the PDI is in TX mode, a BREAK character signaled by the programmer will not be interpreted as a BREAK, but will instead cause a generic data collision. When the PDI is in RX mode, a BREAK character will be recognized as a BREAK. By transmitting two successive BREAK characters (which must be separated by one or more high bits), the last BREAK character will always be recognized as a BREAK, regardless of whether the PDI was in TX or RX mode initially. This is because in TX mode the first BREAK is seen as a collision. The PDI then shifts to RX mode and sees the second BREAK as break. 29.3.7 Direction Change In order to ensure correct timing for half-duplex operation, a guard time mechanism is used. When the PDI changes from RX mode to TX mode, a configurable number of IDLE bits are inserted before the start bit is transmitted. The minimum transition time between RX and TX mode is two IDLE cycles, and these are always inserted. The default guard time value is 128 bits. Figure 29-7. PDI direction change by inserting IDLE bits. PDI_CLK PDI_DATA Sample Sample Sample St P Sp1 1 DATA character Sp2 IDLE bits St P 1 DATA character Sp1 Sp2 Dir. change PDI DATA Receive (RX) PDI DATA Transmit (TX) Data from PDI interface to Programmer Data from Programmer to PDI interface Guard time # IDLE bits inserted Document Footer Title [PRELIMINARY DATASHEET] 365 Atmel-8291C-AVR-XMEGA B -09/2014 The external programmer will loose control of the PDI_DATA line at the point where the PDI changes from RX to TX mode. The guard time relaxes this critical phase of the communication. When the programmer changes from RX mode to TX mode, a single IDLE bit, at minimum, should be inserted before the start bit is transmitted. 29.3.8 Drive Contention and Collision Detection In order to reduce the effect of drive contention (the PDI and the programmer driving the PDI_DATA line at the same time), a mechanism for collision detection is used. The mechanism is based on the way the PDI drives data out on the PDI_DATA line. As shown in Figure 29-8 on page 365, the PDI output driver is active only when the output value changes (from 0-1 or 1-0). Hence, if two or more successive bit values are the same, the value is actively driven only on the first clock cycle. After this point, the PDI output driver is automatically tri-stated, and the PDI_DATA pin has a bus keeper responsible for keeping the pin value unchanged until the output driver is reenabled due to a change in the bit value. Figure 29-8. Driving data out on the PDI_DATA using a bus keeper. If the programmer and the PDI both drive the PDI_DATA line at the same time, drive contention will occur, as illustrated in Figure 29-9 on page 365. Every time a bit value is kept for two or more clock cycles, the PDI is able to verify that the correct bit value is driven on the PDI_DATA line. If the programmer is driving the PDI_DATA line to the opposite bit value to what the PDI expects, a collision is detected. Figure 29-9. Drive contention and collision detection on the PDI_DATA line. As long as the PDI transmits alternating ones and zeros, collisions cannot be detected, because the PDI output driver will be active all the time, preventing polling of the PDI_DATA line. However, the two stop bits should always be transmitted as ones within a single frame, enabling collision detection at least once per frame. 1011 0 Output enable PDI_CLK PDI Output 0 1 PDI_DATA PDI_CLK PDI Output PDI_DATA 1 0 X 1 1 Programmer output X 1 Collision detect = Collision Document Footer Title [PRELIMINARY DATASHEET] 366 Atmel-8291C-AVR-XMEGA B -09/2014 29.4 JTAG Physical The JTAG physical layer handles the basic low-level serial communication over four I/O lines, TMS, TCK, TDI, and TDO. The JTAG physical layer includes BREAK detection, parity error detection, and parity generation. For all generic JTAG details, refer to “IEEE 1149.1 JTAG Boundary Scan Interface” on page 386. 29.4.1 Enabling The JTAGEN fuse must be programmed and the JTAG disable bit in the MCU control register must be cleared to enable the JTAG interface. This is done by default. When the JTAG PDICOM instruction is shifted into the JTAG instruction register, the JTAG interface can be used to access the PDI for external programming and on-chip debugging. 29.4.2 Disabling The JTAG interface can be disabled by unprogramming the JTAGEN fuse or by setting the JTAG disable bit in the MCU control register from the application code. 29.4.3 JTAG Instruction Set The Atmel XMEGA specific JTAG instruction set consist of eight instructions related to boundary scan and PDI access for programming. For more details on JTAG and the general JTAG instruction set, refer to “JTAG Instructions” on page 388. 29.4.3.1 The PDICOM Instruction When the PDICOM instruction is shifted into the JTAG instruction register, the 9-bit PDI communication register is selected as the data register. Commands are shifted into the register as results from previous commands are shifted out from the register. The active TAP controller states are (see “TAP - Test Access Port” on page 386): ̶ Capture DR: Parallel data from the PDI controller is sampled into the PDI communication register ̶ Shift DR: The PDI communication register is shifted by the TCK input ̶ Update DR: Commands or operands are parallel-latched into registers in the PDI controller 29.4.4 Frame Format and Characters The JTAG physical layer supports a fixed frame format. A serial frame is defined to be one character of eight data bits followed by one parity bit. Figure 29-10. JTAG serial frame format Three special data characters are used. Common among these is that the parity bit is inverted in order to force a parity error upon reception. The BREAK character (0xBB+P1) is used by the external programmer to force the PDI to abort any ongoing operation and bring the PDI controller into a known state. The DELAY character (0xDB+P1) is used by the PDI to tell the programmer that it has no data ready. The EMPTY character (0xEB+P1) is used by the PDI to tell the programmer that it has no transmission pending (i.e., the PDI is in RX-mode). (0-7) Data/command bits, least-significant bit sent first (0 to 7) P Parity bit, even parity used Document Footer Title [PRELIMINARY DATASHEET] 367 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 29-11. Special data characters. 29.4.5 Serial transmission and reception The JTAG interface supports full-duplex communication. At the same time as input data is shifted in on the TDI pin, output data is shifted out on the TDO pin. However, PDI communication relies on half-duplex data transfer. Due to this, the JTAG physical layer operates only in either transmit (TX) or receive (RX) mode. The available JTAG bit channel is used for control and status signalling. The programmer and the JTAG interface operate synchronously on the TCK clock provided by the programmer. The dependency between the clock edges and data sampling or data change is fixed. As illustrated in Figure 29-12 on page 367, TDI and TDO is always set up (change) on the falling edge of TCK, while data always should be sampled on the rising edge of TCK. Figure 29-12. Changing and sampling data. 29.4.6 Serial Transmission When data transmission is initiated, a data byte is loaded into the shift register and then out on TDO. The parity bit is generated and appended to the data byte during transmission. The transmission speed is given by the TCK signal. If the PDI is in TX mode (as a response to an LD instruction), and a transmission request from the PDI controller is pending when the TAP controller enters the capture DR state, valid data will be parallel-loaded into the shift register, and a correct parity bit will be generated and transmitted along with the data byte in the shift DR state. If the PDI is in RX mode when the TAP controller enters the capture DR state, an EMPTY byte will be loaded into the shift register, and the parity bit will be set (forcing a parity error) when data is shifted out in the shift DR state. This situation occurs during normal PDI command and operand reception. If the PDI is in TX- mode (as a response to an LD instruction), but no transmission request from the PDI controller is pending when the TAP controller enters the capture DR state, a DELAY byte (0xDB) will be loaded into the shift register, and the parity bit will be set (forcing a parity error) when data is shifted out in the shift DR state. This situation occurs during data transmission if the data to be transmitted is not yet available. Figure 29-13 on page 368 shows an uninterrupted flow of data frames from the PDI as a response to the repeated indirect LD instruction. In this example, the device is not able to return data bytes faster than one valid byte per two transmitted frames. Thus, intermediate DELAY characters are inserted. Document Footer Title [PRELIMINARY DATASHEET] 368 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 29-13. Data not ready marking. If a DELAY data frame is transmitted as a response to an LD instruction, the programmer should interpret this as if the JTAG interface had no data ready for transmission in the previous capture DR state. The programmer must initiate repeated transfers until a valid data byte is received. The LD instruction is defined to return a specified number of valid frames, not just a number of frames. Hence, if the programmer detects a DELAY character after transmitting an LD instruction, the LD instruction should not be retransmitted, because the first LD response would still be pending. 29.4.7 Serial Reception During reception, the PDI collects the eight data bits and the parity bit from TDI and shifts them into the shift register. Every time a valid frame is received, the data is latched in to the update DR state. The parity checker calculates the parity (even mode) of the data bits in incoming frames and compares the result with the parity bit from the serial frame. In case of a parity error, the PDI controller is signaled. The parity checker is active in both TX and RX modes. If a parity error is detected, the received data byte is evaluated and compared with the BREAK character (which will always generate a parity error). In case the BREAK character is recognized, the PDI controller is signaled. 29.5 PDI Controller The PDI controller performs data transmission/reception on a byte level, command decoding, high-level direction control, control and status register access, exception handling, and clock switching (PDI_CLK or TCK). The interaction between an external programmer and the PDI controller is based on a scheme where the programmer transmits various types of requests to the PDI controller, which in turn responds according to the specific request. A programmer request comes in the form of an instruction, which may be followed by one or more byte operands. The PDI controller response may be silent (e.g., a data byte is stored to a location within the device), or it may involve data being returned to the programmer (e.g., a data byte is read from a location within the device). 29.5.1 Switching between PDI and JTAG modes The PDI controller uses either the JTAG or PDI physical layer for establishing a connection to the programmer. Based on this, the PDI is in either JTAG or PDI mode. When one of the modes is entered, the PDI controller registers will be initialized, and the correct clock source will be selected. The PDI mode has higher priority than the JTAG mode. Hence, if the PDI mode is enabled while the PDI controller is already in JTAG mode, the access layer will automatically switch over to PDI mode. If switching physical layer without powering on/off the device, the active layer should be disabled before the alternative physical layer is enabled. 29.5.2 Accessing Internal Interfaces After an external programmer has established communication with the PDI, the internal interfaces are not accessible, by default. To get access to the NVM controller and the nonvolatile memories for programming, a unique key must be signaled by using the KEY instruction. The internal interfaces are accessed as one linear address space using a dedicated bus (PDIBUS) between the PDI and the internal interfaces. The PDIBUS address space is shown in Table 33-3 on page 421. The NVM controller must be enabled for the PDI controller to have any access to the NVM interface. The PDI controller can access the NVM and NVM controller in programming mode only. The PDI controller does not need to access the NVM controller's data or address registers when reading or writing NVM. Document Footer Title [PRELIMINARY DATASHEET] 369 Atmel-8291C-AVR-XMEGA B -09/2014 29.5.3 NVM Programming Key The key that must be sent using the KEY instruction is 64 bits long. The key that will enable NVM programming is: 0x1289AB45CDD888FF 29.5.4 Exception Handling There are several situations that are considered exceptions from normal operation. The exceptions depend on whether the PDI is in RX or TX mode and whether PDI or JTAG mode is used. While the PDI is in RX mode, the exceptions are: z PDI: ̶ The physical layer detects a parity error ̶ The physical layer detects a frame error ̶ The physical layer recognizes a BREAK character (also detected as a frame error) z JTAG: ̶ The physical layer detects a parity error ̶ The physical layer recognizes a BREAK character (also detected as a parity error) While the PDI is in TX mode, the exceptions are: z PDI: ̶ The physical layer detects a data collision z JTAG: ̶ The physical layer detects a parity error (on the dummy data shifted in on TDI) ̶ The physical layer recognizes a BREAK character Exceptions are signaled to the PDI controller. All ongoing operations are then aborted, and the PDI is put in ERROR state. The PDI will remain in ERROR state until a BREAK is sent from the external programmer, and this will bring the PDI back to its default RX state. Due to this mechanism, the programmer can always synchronize the protocol by transmitting two successive BREAK characters. 29.5.5 Reset Signalling Through the reset register, the programmer can issue a reset and force the device into reset. After clearing the reset register, reset is released, unless some other reset source is active. 29.5.6 Instruction Set The PDI has a small instruction set used for accessing both the PDI itself and the internal interfaces. All instructions are byte instructions. The instructions allow an external programmer to access the PDI controller, the NVM controller and the nonvolatile memories. 29.5.6.1 LDS - Load Data from PDIBUS Data Space using Direct Addressing The LDS instruction is used to load data from the PDIBUS data space for read out. The LDS instruction is based on direct addressing, which means that the address must be given as an argument to the instruction. Even though the protocol is based on byte-wise communication, the LDS instruction supports multiple-byte addresses and data access. Four different address/data sizes are supported: single-byte, word (two bytes), three-byte, and long (four bytes). Multiple-byte access is broken down internally into repeated single-byte accesses, but this reduces protocol overhead. When using the LDS instruction, the address byte(s) must be transmitted before the data transfer. 29.5.6.2 STS - Store Data to PDIBUS Data Space using Direct Addressing The STS instruction is used to store data that are serially shifted into the physical layer shift register to locations within the PDIBUS data space. The STS instruction is based on direct addressing, which means that the address must be given as an argument to the instruction. Even though the protocol is based on byte-wise communication, the ST Document Footer Title [PRELIMINARY DATASHEET] 370 Atmel-8291C-AVR-XMEGA B -09/2014 instruction supports multiple-bytes addresses and data access. Four different address/data sizes are supported: single-byte, word (two bytes), three-byte, and long (four bytes). Multiple-byte access is broken down internally into repeated single-byte accesses, but this reduces protocol overhead. When using the STS instruction, the address byte(s) must be transmitted before the data transfer. 29.5.6.3 LD - Load Data from PDIBUS Data Space using Indirect Addressing The LD instruction is used to load data from the PDIBUS data space into the physical layer shift register for serial read out. The LD instruction is based on indirect addressing (pointer access), which means that the address must be stored in the pointer register prior to the data access. Indirect addressing can be combined with pointer increment. In addition to reading data from the PDIBUS data space, the LD instruction can read the pointer register. Even though the protocol is based on byte-wise communication, the LD instruction supports multiple-byte addresses and data access. Four different address/data sizes are supported: single-byte, word (two bytes), three-byte, and long (four bytes). Multiple-byte access is broken down internally into repeated single-byte accesses, but this reduces the protocol overhead. 29.5.6.4 ST - Store Data to PDIBUS Data Space using Indirect Addressing The ST instruction is used to store data that is serially shifted into the physical layer shift register to locations within the PDIBUS data space. The ST instruction is based on indirect addressing (pointer access), which means that the address must be stored in the pointer register prior to the data access. Indirect addressing can be combined with pointer increment. In addition to writing data to the PDIBUS data space, the ST instruction can write the pointer register. Even though the protocol is based on byte-wise communication, the ST instruction supports multiple-bytes address - and data access. Four different address/data sizes are supported; byte, word, 3 bytes, and long (4 bytes). Multiple-bytes access is internally broken down to repeated single-byte accesses, but it reduces the protocol overhead. 29.5.6.5 LDCS - Load Data from PDI Control and Status Register Space The LDCS instruction is used to load data from the PDI control and status registers into the physical layer shift register for serial read out. The LDCS instruction supports only direct addressing and single-byte access. 29.5.6.6 STCS - Store Data to PDI Control and Status Register Space The STCS instruction is used to store data that are serially shifted into the physical layer shift register to locations within the PDI control and status registers. The STCS instruction supports only direct addressing and single-byte access. 29.5.6.7 KEY - Set Activation Key The KEY instruction is used to communicate the activation key bytes required for activating the NVM interfaces. 29.5.6.8 REPEAT - Set Instruction Repeat Counter The REPEAT instruction is used to store count values that are serially shifted into the physical layer shift register to the repeat counter register. The instruction that is loaded directly after the REPEAT instruction operand(s) will be repeated a number of times according to the specified repeat counter register value. Hence, the initial repeat counter value plus one gives the total number of times the instruction will be executed. Setting the repeat counter register to zero makes the following instruction run once without being repeated. The REPEAT instruction cannot be repeated. The KEY instruction cannot be repeated, and will override the current value of the repeat counter register. 29.5.7 Instruction Set Summary The PDI instruction set summary is shown in Figure 29-14 on page 371. Document Footer Title [PRELIMINARY DATASHEET] 371 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 29-14. PDI instruction set summary. 29.6 Register Description – PDI Instruction and Addressing Registers The PDI instruction and addressing registers are internal registers utilized for instruction decoding and PDIBUS addressing. None of these registers are accessible as registers in a register space. 29.6.1 Instruction Register When an instruction is successfully shifted into the physical layer shift register, it is copied into the instruction register. The instruction is retained until another instruction is loaded. The reason for this is that the REPEAT command may force the same instruction to be run repeatedly, requiring command decoding to be performed several times on the same instruction. 29.6.2 Pointer Register The pointer register is used to store an address value that specifies locations within the PDIBUS address space. During direct data access, the pointer register is updated by the specified number of address bytes given as operand bytes to an instruction. During indirect data access, addressing is based on an address already stored in the pointer register prior to the access itself. Indirect data access can be optionally combined with pointer register post-increment. LDS 0 0 0 Cmd Size A Size B STS 0 1 0 LDCS 1 0 0 CS Address STCS 1 1 0 KEY 1 1 1 0 0 0 REPEAT 1 0 1 0 0 0 Size B LDS STS ST 0 0 1 0 0 1 1 1 LD 0 0 0 0 Cmd LDCS (LDS Control/Status) STCS (STS Control/Status) KEY 0 1 1 0 1 1 REPEAT 1 1 1 1 0 0 Size B - Data size Byte 3 Bytes Long (4 Bytes) 0 0 1 0 0 1 1 1 Word (2 Bytes) CS Address (CS - Control/Status reg.) 0 0 0 Register 0 Register 2 Reserved Register 1 0 0 0 0 1 0 0 1 0 0 0 1 1 1 1 1 1 Reserved ...... 0 0 Size A - Address size (direct access) Byte 3 Bytes Long (4 Bytes) 0 0 1 0 0 1 1 1 Word (2 Bytes) LD 0 0 1 Cmd Ptr Size A/B ST 0 1 1 0 0 0 0 Ptr - Pointer access (indirect access) *(ptr) ptr ptr++ - Reserved 0 0 1 0 0 1 1 1 *(ptr++) 0 0 Document Footer Title [PRELIMINARY DATASHEET] 372 Atmel-8291C-AVR-XMEGA B -09/2014 The indirect access mode has an option that makes it possible to load or read the pointer register without accessing any other registers. Any register update is performed in a little-endian fashion. Hence, loading a single byte of the address register will always update the LSB while the most-significant bytes are left unchanged. The pointer register is not involved in addressing registers in the PDI control and status register space (CSRS space). 29.6.3 Repeat Counter Register The REPEAT instruction is always accompanied by one or more operand bytes that define the number of times the next instruction should be repeated. These operand bytes are copied into the repeat counter register upon reception. During the repeated executions of the instruction immediately following the REPEAT instruction and its operands, the repeat counter register is decremented until it reaches zero, indicating that all repetitions have completed. The repeat counter is also involved in key reception. 29.6.4 Operand Count Register Immediately after an instruction (except the LDCS and STCS instructions) a specified number of operands or data bytes (given by the size parts of the instruction) are expected. The operand count register is used to keep track of how many bytes have been transferred. Document Footer Title [PRELIMINARY DATASHEET] 373 Atmel-8291C-AVR-XMEGA B -09/2014 29.7 Register Description – PDI Control and Status Registers The PDI control and status registers are accessible in the PDI control and status register space (CSRS) using the LDCS and STCS instructions. The CSRS contains registers directly involved in configuration and status monitoring of the PDI itself. 29.7.1 STATUS – Status register z Bit 7:2 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 1 – NVMEN: Nonvolatile Memory Enable This status bit is set when the key signalling enables the NVM programming interface. The external programmer can poll this bit to verify successful enabling. Writing the NVMEN bit disables the NVM interface. z Bit 0 – Reserved This bit is unused and reserved for future use. For compatibility with future devices, always write this bit to zero when this register is written. 29.7.2 RESET – Reset register z Bit 7:0 – RESET[7:0]: Reset Signature When the reset signature, 0x59, is written to RESET, the device is forced into reset. The device is kept in reset until RESET is written with a data value different from the reset signature. Reading the lsb will return the status of the reset. The seven msbs will always return the value 0x00, regardless of whether the device is in reset or not. 29.7.3 CTRL – Control register z Bit 7:3 – Reserved These bits are unused and reserved for future use. For compatibility with future devices, always write these bits to zero when this register is written. z Bit 2:0 – GUARDTIME[2:0]: Guard Time These bits specify the number of IDLE bits of guard time that are inserted in between PDI reception and transmission direction changes. The default guard time is 128 IDLE bits, and the available settings are shown in Table 29-1 on page 374. In order to speed up the communication, the guard time should be set to the lowest safe configuration accepted. No guard time is inserted when switching from TX to RX mode. Bit 7 6 5 4 3 2 1 0 +0x00 – – – – – – NVMEN – Read/Write R R R R R R R/W R Initial Value 00000000 Bit 7 6 5 4 3 2 1 0 +0x01 RESET[7:0] Read/Write R/W R/W R/W R/W R/W R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 +0x02 – – – – – GUARDTIME[2:0] Read/Write R R R R R R/W R/W R/W Initial Value 0 0 0 0 0 0 0 0 Document Footer Title [PRELIMINARY DATASHEET] 374 Atmel-8291C-AVR-XMEGA B -09/2014 Table 29-1. Guard time settings. 29.8 Register Summary GUARDTIME Number of IDLE Bits 000 128 001 64 010 32 011 16 100 8 101 4 110 2 111 2 Address Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Page +0x00 STATUS – – – – – – NVMEN – 373 +0x01 RESET RESET[7:0] 373 +0x02 CTRL – – – – – GUARDTIME[2:0] 373 +0x03 Reserved – – – – – – – – XMEGA B [MANUAL] 375 Atmel-8291C-AVR-XMEGA B -09/2014 30. Memory Programming 30.1 Features z Read and write access to all memory spaces from z External programmers z Application software self-programming z Self-programming and boot loader support z Read-while-write self-programming z CPU can run and execute code while flash is being programmed z Any communication interface can be used for program upload/download z External programming z Support for in-system and production programming z Programming through serial PDI or JTAG interface z High security with separate boot lock bits for: z External programming access z Boot loader section access z Application section access z Application table access z Reset fuse to select reset vector address to the start of the z Application section, or z Boot loader section 30.2 Overview This section describes how to program the nonvolatile memory (NVM) in Atmel AVR XMEGA devices, and covers both self-programming and external programming. The NVM consists of the flash program memory, user signature and production signature rows, fuses and lock bits, and EEPROM data memory. For details on the actual memories, how they are organized, and the register description for the NVM controller used to access the memories, refer to “Memories” on page 20. The NVM can be accessed for read and write from application software through self-programming and from an external programmer. Accessing the NVM is done through the NVM controller, and the two methods of programming are similar. Memory access is done by loading address and/or data to the selected memory or NVM controller and using a set of commands and triggers that make the NVM controller perform specific tasks on the nonvolatile memory. From external programming, all memory spaces can be read and written, except for the production signature row, which can only be read. The device can be programmed in-system and is accessed through the PDI using the PDI or JTAG physical interfaces. “External Programming” on page 388 describes PDI and JTAG in detail. Self-programming and boot loader support allows application software in the device to read and write the flash, user signature row and EEPROM, write the lock bits to a more secure setting, and read the production signature row and fuses. The flash allows read-while-write self-programming, meaning that the CPU can continue to operate and execute code while the flash is being programmed. “Self-programming and Boot Loader Support” on page 379 describes this in detail. For both self-programming and external programming, it is possible to run a CRC check on the flash or a section of the flash to verify its content after programming. The device can be locked to prevent reading and/or writing of the NVM. There are separate lock bits for external programming access and self-programming access to the boot loader section, application section, and application table section. XMEGA B [MANUAL] 376 Atmel-8291C-AVR-XMEGA B -09/2014 30.3 NVM Controller Access to the nonvolatile memories is done through the NVM controller. It controls NVM timing and access privileges, and holds the status of the NVM, and is the common NVM interface for both external programming and selfprogramming. For more details, refer to “Register Description” on page 393. 30.4 NVM Commands The NVM controller has a set of commands used to perform tasks on the NVM. This is done by writing the selected command to the NVM command register. In addition, data and addresses must be read/written from/to the NVM data and address registers for memory read/write operations. When a selected command is loaded and address and data are set up for the operation, each command has a trigger that will start the operation. Based on these triggers, there are three main types of commands. 30.4.1 Action-triggered Commands Action-triggered commands are triggered when the command execute (CMDEX) bit in the NVM control register A (CTRLA) is written. Action-triggered commands typically are used for operations which do not read or write the NVM, such as the CRC check. 30.4.2 NVM Read-triggered Commands NVM read-triggered commands are triggered when the NVM is read, and this is typically used for NVM read operations. 30.4.3 NVM Write-triggered Commands NVM write-triggered commands are triggered when the NVM is written, and this is typically used for NVM write operations. 30.4.4 Write/Execute Protection Most command triggers are protected from accidental modification/execution during self-programming. This is done using the configuration change protection (CCP) feature, which requires a special write or execute sequence in order to change a bit or execute an instruction. For details on the CCP, refer to “Configuration Change Protection” on page 13. 30.5 NVM Controller Busy Status When the NVM controller is busy performing an operation, the busy flag in the NVM status register is set and the following registers are blocked for write access: z NVM command register z NVM control A register z NVM control B register z NVM address registers z NVM data registers This ensures that the given command is executed and the operations finished before the start of a new operation. The external programmer or application software must ensure that the NVM is not addressed when it is busy with a programming operation. Programming any part of the NVM will automatically block: z All programming to other parts of the NVM z All loading/erasing of the flash and EEPROM page buffers z All NVM reads from external programmers z All NVM reads from the application section During self-programming, interrupts must be disabled or the interrupt vector table must be moved to the boot loader sections, as described in “Interrupts and Programmable Multilevel Interrupt Controller” on page 115. XMEGA B [MANUAL] 377 Atmel-8291C-AVR-XMEGA B -09/2014 30.6 Flash and EEPROM Page Buffers The flash memory is updated page by page. The EEPROM can be updated on a byte-by-byte and page-by-page basis. flash and EEPROM page programming is done by first filling the associated page buffer, and then writing the entire page buffer to a selected page in flash or EEPROM. The size of the page and page buffers depends on the flash and EEPROM size in each device, and details are described in the device datasheet. 30.6.1 Flash Page Buffer The flash page buffer is filled one word at a time, and it must be erased before it can be loaded. When loading the page buffer with new content, the result is a binary AND between the existing content of the page buffer location and the new value. If the page buffer is already loaded once after erase the location will most likely be corrupted. Page buffer locations that are not loaded will have the value 0xFFFF, and this value will then be programmed into the corresponding flash page locations. The page buffer is automatically erased after: z A device reset z Executing the write flash page command z Executing the erase and write flash page command z Executing the signature row write command z Executing the write lock bit command 30.6.2 EEPROM Page Buffer The EEPROM page buffer is filled one byte at a time, and it must be erased before it can be loaded. When loading the page buffer with new content, the result is a binary AND between the existing content of the page buffer location and the new value. If the EEPROM page buffer is already loaded once after erase the location will most likely be corrupted. EEPROM page buffer locations that are loaded will get tagged by the NVM controller. During a page write or page erase, only targed locations will be written or erased. Locations that are not targed will not be written or erased, and the corresponding EEPROM location will remain unchanged. This means that before an EEPROM page erase, data must be loaded to the selected page buffer location to tag them. When performing an EEPROM page erase, the actual value of the tagged location does not matter. The EEPROM page buffer is automatically erased after: z A system reset z Executing the write EEPROM page command z Executing the erase and write EEPROM page command z Executing the write lock bit and write fuse commands 30.7 Flash and EEPROM Programming Sequences For page programming, filling the page buffers and writing the page buffer into flash or EEPROM are two separate operations. The sequence is same for both self-programming and external programming. 30.7.1 Flash Programming Sequence Before programming a flash page with the data in the flash page buffer, the flash page must be erased. Programming an un-erased flash page will corrupt its content. The flash page buffer can be filled either before the erase flash Page operation or between a erase flash page and a write flash page operation: XMEGA B [MANUAL] 378 Atmel-8291C-AVR-XMEGA B -09/2014 Alternative 1: z Fill the flash page buffer z Perform a flash page erase z Perform a flash page write Alternative 2: z Fill the flash page buffer z Perform an atomic page erase and write Alternative 3, fill the buffer after a page erase: z Perform a flash page erase z Fill the flash page buffer z Perform a flash page write The NVM command set supports both atomic erase and write operations, and split page erase and page write commands. This split commands enable shorter programming time for each command, and the erase operations can be done during non-time-critical programming execution. When using alternative 1 or 2 above for self-programming, the boot loader provides an effective read-modify-write feature, which allows the software to first read the page, do the necessary changes, and then write back the modified data. If alternative 3 is used, it is not possible to read the old data while loading, since the page is already erased. The page address must be the same for both page erase and page write operations when using alternative 1 or 3. 30.7.2 EEPROM Programming Sequence Before programming an EEPROM page with the tagged data bytes stored in the EEPROM page buffer, the selected locations in the EEPROM page must be erased. Programming an unerased EEPROM page will corrupt its content. The EEPROM page buffer must be loaded before any page erase or page write operations: Alternative 1: z Fill the EEPROM page buffer with the selected number of bytes z Perform a EEPROM page erase z Perform a EEPROM page write Alternative 2: z Fill the EEPROM page buffer with the selected number of bytes z Perform an atomic EEPROM page erase and write 30.8 Protection of NVM To protect the flash and EEPROM memories from write and/or read, lock bits can be set to restrict access from external programmers and the application software. Refer to “LOCKBITS – Lock Bit register” on page 29 for details on the available lock bit settings and how to use them. 30.9 Preventing NVM Corruption During periods when the VCC voltage is below the minimum operating voltage for the device, the result from a flash memory write can be corrupt, as supply voltage is too low for the CPU and the flash to operate properly.To ensure that the voltage is sufficient enough during a complete programming sequence of the flash memory, a voltage detector using the POR threshold (VPOT+) level is enabled. During chip erase and when the PDI is enabled the brownout detector (BOD) is automatically enabled at its configured level. XMEGA B [MANUAL] 379 Atmel-8291C-AVR-XMEGA B -09/2014 Depending on the programming operation, if any of these VCC voltage levels are reached, the programming sequence will be aborted immediately. If this happens, the NVM programming should be restarted when the power is sufficient again, in case the write sequence failed or only partly succeeded. 30.10 CRC Functionality It is possible to run an automatic cyclic redundancy check (CRC) on the flash program memory. When NVM is used to control the CRC module, an even number of bytes are read, at least in the flash range mode. If the user selects a range with an odd number of bytes, an extra byte will be read, and the checksum will not correspond to the selected range. Refer to “CRC – Cyclic Redundancy Check Generator” on page 293 for more details. 30.11 Self-programming and Boot Loader Support Reading and writing the EEPROM and flash memory from the application software in the device is referred to as selfprogramming. A boot loader (application code located in the boot loader section of the flash) can both read and write the flash program memory, user signature row, and EEPROM, and write the lock bits to a more secure setting. Application code in the application section can read from the flash, user signature row, production signature row, and fuses, and read and write the EEPROM. 30.11.1 Flash Programming The boot loader support provides a real read-while-write self-programming mechanism for uploading new program code by the device itself. This feature allows flexible application software updates controlled by the device using a boot loader application that reside in the boot loader section in the flash. The boot loader can use any available communication interface and associated protocol to read code and write (program) that code into the flash memory, or read out the program memory code. It has the capability to write into the entire flash, including the boot loader section. The boot loader can thus modify itself, and it can also erase itself from the flash if the feature is not needed anymore. 30.11.1.1 Application and Boot Loader Sections The application and boot loader sections in the flash are different when it comes to self-programming. z When erasing or writing a page located inside the application section, the boot loader section can be read during the operation, and thus the CPU can run and execute code from the boot loader section z When erasing or writing a page located inside the boot loader section, the CPU is halted during the entire operation, and code cannot execute The user signature row section has the same properties as the boot loader section. Table 30-1. Summary of self-programming functionality. 30.11.1.2 Addressing the Flash The Z-pointer is used to hold the flash memory address for read and write access. For more details on the Z-pointer, refer to “The X-, Y-, and Z- Registers” on page 11. Since the flash is word accessed and organized in pages, the Z-pointer can be treated as having two sections. The leastsignificant bits address the words within a page, while the most-significant bits address the page within the flash. This is shown in Figure 30-1 on page 380. The word address in the page (FWORD) is held by the bits [WORDMSB:1] in the Zpointer. The remaining bits [PAGEMSB:WORDMSB+1] in the Z-pointer hold the flash page address (FPAGE). Together FWORD and FPAGE holds an absolute address to a word in the flash. Section being Addressed during Programming Section that can be Read during Programming CPU halted? Application section Boot loader section No Boot loader section None Yes User signature row section None Yes XMEGA B [MANUAL] 380 Atmel-8291C-AVR-XMEGA B -09/2014 For flash read operations (ELPM and LPM), one byte is read at a time. For this, the least-significant bit (bit 0) in the Zpointer is used to select the low byte or high byte in the word address. If this bit is 0, the low byte is read, and if this bit is 1 the high byte is read. The size of FWORD and FPAGE will depend on the page and flash size in the device. Refer to each device’s datasheet for details. Once a programming operation is initiated, the address is latched and the Z-pointer can be updated and used for other operations. Figure 30-1. Flash addressing for self-programming. 30.11.2 NVM Flash Commands The NVM commands that can be used for accessing the flash program memory, signature row and production signature row are listed in Table 30-2. For self-programming of the flash, the trigger for action-triggered commands is to set the CMDEX bit in the NVM CTRLA register (CMDEX). The read-triggered commands are triggered by executing the (E)LPM instruction (LPM). The writetriggered commands are triggered by executing the SPM instruction (SPM). The Change Protected column indicates whether the trigger is protected by the configuration change protection (CCP) or not. This is a special sequence to write/execute the trigger during self-programming. For more details, refer to “Configuration Change Protection” on page 13. CCP is not required for external programming. The two last columns show the address pointer used for addressing and the source/destination data register. Section 30.11.1.1 on page 379 through Section 30.11.2.14 on page 384 explain in detail the algorithm for each NVM operation. FPAGE FWORD 0/1 BIT Z-Pointer P 1 AGEMSB WORDMSB 0 PAGE INSTRUCTION WORD PROGRAM MEMORY PAGE WORD ADDRESS WITHIN A PAGE PAGE ADDRESS WITHIN THE FLASH FWORD 00 01 02 PAGEEND 00 01 02 FLASHEND FPAGE Low/High Byte select for (E)LPM XMEGA B [MANUAL] 381 Atmel-8291C-AVR-XMEGA B -09/2014 Table 30-2. Flash self-programming commands. Notes: 1. The flash range CRC command used byte addressing of the flash. 2. Will depend on the flash section (application or boot loader) that is actually addressed. 3. This command is qualified with the lock bits, and requires that the boot lock bits are unprogrammed. 4. When using a command that changes the normal behavior of the LPM command; READ_USER_SIG_ROW and READ_CALIB_ROW; it is recommended to disable interrupts to ensure correct execution of the LPM instruction. 5. For consistency the name Calibration Row has been renamed to Production Signature Row throughout the document. 30.11.2.1 Read Flash The (E)LPM instruction is used to read one byte from the flash memory. 1. Load the Z-pointer with the byte address to read. 2. Load the NVM command register (NVM CMD) with the no operation command. 3. Execute the LPM instruction. The destination register will be loaded during the execution of the LPM instruction. CMD[6:0] Group Configuration Description Trigger CPU Halted NVM Busy Change Protected Address Pointer Data Register 0x00 NO_OPERATION No operation / read flash -/(E)LPM -/N N -/N -/ Z-pointer -/Rd Flash Page Buffer 0x23 LOAD_FLASH_BUFFER Load flash page buffer SPM N N N Z-pointer R1:R0 0x26 ERASE_FLASH_BUFFER Erase flash page buffer CMDEX N Y Y Z-pointer - Flash 0x2B ERASE_FLASH_PAGE Erase flash page SPM N/Y(2) Y Y Z-pointer - 0x02E WRITE_FLASH_PAGE Write flash page SPM N/Y(2) Y Y Z-pointer - 0x2F ERASE_WRITE_FLASH_PAGE Erase and write flash page SPM N/Y(2) Y Y Z-pointer - 0x3A FLASH_RANGE_CRC(3) Flash range CRC CMDEX Y Y Y DATA/ADDR(1) DATA Application Section 0x20 ERASE_APP Erase application section SPM Y Y Y Z-pointer - 0x22 ERASE_APP_PAGE Erase application section page SPM N Y Y Z-pointer - 0x24 WRITE_APP_PAGE Write application section page SPM N Y Y Z-pointer - 0x25 ERASE_WRITE_APP_PAGE Erase and write application section page SPM N Y Y Z-pointer - 0x38 APP_CRC Application section CRC CMDEX Y Y Y - DATA Boot Loader Section 0x2A ERASE_BOOT_PAGE Erase boot loader section page SPM Y Y Y Z-pointer - 0x2C WRITE_BOOT_PAGE Write boot loader section page SPM Y Y Y Z-pointer - 0x2D ERASE_WRITE_BOOT_PAGE Erase and write boot loader section page SPM Y Y Y Z-pointer - 0x39 BOOT_CRC Boot loader section CRC CMDEX Y Y Y - DATA User Signature Row 0x01(4) READ_USER_SIG_ROW Read user signature row LPM N N N Z-pointer Rd 0x18 ERASE_USER_SIG_ROW Erase user signature row SPM Y Y Y - - 0x1A WRITE_USER_SIG_ROW Write user signature row SPM Y Y Y - - Production Signature (Calibration) Row(5) 0x02(4) READ_CALIB_ROW Read calibration row LPM N N N Z-pointer Rd XMEGA B [MANUAL] 382 Atmel-8291C-AVR-XMEGA B -09/2014 30.11.2.2 Erase Flash Page Buffer The erase flash page buffer command is used to erase the flash page buffer. 1. Load the NVM CMD with the erase flash page buffer command. 2. Set the command execute bit (NVMEX) in the NVM control register A (NVM CTRLA). This requires the timed CCP sequence during self-programming. The NVM busy (BUSY) flag in the NVM status register (NVM STATUS) will be set until the page buffer is erased. 30.11.2.3 Load Flash Page Buffer The load flash page buffer command is used to load one word of data into the flash page buffer. 1. Load the NVM CMD register with the load flash page buffer command. 2. Load the Z-pointer with the word address to write. 3. Load the data word to be written into the R1:R0 registers. 4. Execute the SPM instruction. The SPM instruction is not protected when performing a flash page buffer load. Repeat step 2-4 until the complete flash page buffer is loaded. Unloaded locations will have the value 0xFFFF. 30.11.2.4 Erase Flash Page The erase flash page command is used to erase one page in the flash. 1. Load the Z-pointer with the flash page address to erase. The page address must be written to FPAGE. Other bits in the Z-pointer will be ignored during this operation. 2. Load the NVM CMD register with the erase flash page command. 3. Execute the SPM instruction. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the erase operation is finished. The flash section busy (FBUSY) flag is set as long the flash is busy, and the application section cannot be accessed. 30.11.2.5 Write Flash Page The write flash page command is used to write the flash page buffer into one flash page in the flash. 1. Load the Z-pointer with the flash page to write. The page address must be written to FPAGE. Other bits in the Zpointer will be ignored during this operation. 2. Load the NVM CMD register with the write flash page command. 3. Execute the SPM instruction. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the write operation is finished. The FBUSY flag is set as long the flash is busy, and the application section cannot be accessed. 30.11.2.6 Flash Range CRC The flash range CRC command can be used to verify the content in an address range in flash after a self-programming. 1. Load the NVM CMD register with the flash range CRC command. 2. Load the start byte address in the NVM address register (NVM ADDR). 3. Load the end byte address in NVM data register (NVM DATA). 4. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set, and the CPU is halted during the execution of the command. The CRC checksum will be available in the NVM DATA register. In order to use the flash range CRC command, all the boot lock bits must be unprogrammed (no locks). The command execution will be aborted if the boot lock bits for an accessed location are set. 30.11.2.7 Erase Application Section The erase application command is used to erase the complete application section. 1. Load the Z-pointer to point anywhere in the application section. 2. Load the NVM CMD register with the erase application section command XMEGA B [MANUAL] 383 Atmel-8291C-AVR-XMEGA B -09/2014 3. Execute the SPM instruction. This requires the timed CCP sequence during self-programming. The BUSY flag in the STATUS register will be set until the operation is finished. The CPU will be halted during the complete execution of the command. 30.11.2.8 Erase Application Section / Boot Loader Section Page The erase application section page erase and erase boot loader section page commands are used to erase one page in the application section or boot loader section. 1. Load the Z-pointer with the flash page address to erase. The page address must be written to ZPAGE. Other bits in the Z-pointer will be ignored during this operation. 2. Load the NVM CMD register with the erase application/boot section page command. 3. Execute the SPM instruction. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the erase operation is finished. The FBUSY flag is set as long the flash is busy, and the application section cannot be accessed. 30.11.2.9 Application Section / Boot Loader Section Page Write The write application section page and write boot loader section page commands are used to write the flash page buffer into one flash page in the application section or boot loader section. 1. Load the Z-pointer with the flash page to write. The page address must be written to FPAGE. Other bits in the Zpointer will be ignored during this operation. 2. Load the NVM CMD register with the write application section/boot loader section page command. 3. Execute the SPM instruction. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the write operation is finished. The FBUSY flag is set as long the flash is busy, and the application section cannot be accessed. An invalid page address in the Z-pointer will abort the NVM command. The erase application section page command requires that the Z-pointer addresses the application section, and the erase boot section page command requires that the Z-pointer addresses the boot loader section. 30.11.2.10 Erase and Write Application Section / Boot Loader Section Page The erase and write application section page and erase and write boot loader section page commands are used to erase one flash page and then write the flash page buffer into that flash page in the application section or boot loader section in one atomic operation. 1. Load the Z-pointer with the flash page to write. The page address must be written to FPAGE. Other bits in the Zpointer will be ignored during this operation. 2. Load the NVM CMD register with the erase and write application section/boot loader section page command. 3. Execute the SPM instruction. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the operation is finished. The FBUSY flag is set as long as the flash is busy, and the application section cannot be accessed. An invalid page address in the Z-pointer will abort the NVM command. The erase and write application section command requires that the Z-pointer addresses the application section, and the erase and write boot section page command requires that the Z-pointer addresses the boot loader section. 30.11.2.11 Application Section / Boot Loader Section CRC The application section CRC and boot loader section CRC commands can be used to verify the application section and boot loader section content after self-programming. 1. Load the NVM CMD register with the application section/ boot load section CRC command. 2. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set, and the CPU is halted during the execution of the CRC command. The CRC checksum will be available in the NVM data registers. XMEGA B [MANUAL] 384 Atmel-8291C-AVR-XMEGA B -09/2014 30.11.2.12 Erase User Signature Row The erase user signature row command is used to erase the user signature row. 1. Load the NVM CMD register with the erase user signature row command. 2. Execute the SPM instruction. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set, and the CPU will be halted until the erase operation is finished. The user signature row is NRWW. 30.11.2.13 Write User Signature Row The write signature row command is used to write the flash page buffer into the user signature row. 1. Set up the NVM CMD register to write user signature row command. 2. Execute the SPM instruction. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the operation is finished, and the CPU will be halted during the write operation. The flash page buffer will be cleared during the command execution after the write operation, but the CPU is not halted during this stage. 30.11.2.14 Read User Signature Row / Production Signature Row The read user signature row and read calibration row commands are used to read one byte from the user signature row or production signature (calibration) row. 1. Load the Z-pointer with the byte address to read. 2. Load the NVM CMD register with the read user signature row / production signature (calibration) row command 3. Execute the LPM instruction. The destination register will be loaded during the execution of the LPM instruction. To ensure that LPM for reading flash will be executed correctly it is advised to disable interrupt while using either of these commands. 30.11.3 NVM Fuse and Lock Bit Commands The NVM flash commands that can be used for accessing the fuses and lock bits are listed in Table 30-3. For self-programming of the fuses and lock bits, the trigger for action-triggered commands is to set the CMDEX bit in the NVM CTRLA register (CMDEX). The read-triggered commands are triggered by executing the (E)LPM instruction (LPM). The write-triggered commands are triggered by a executing the SPM instruction (SPM). The Change Protected column indicates whether the trigger is protected by the configuration change protection (CCP) during self-programming or not. The last two columns show the address pointer used for addressing and the source/destination data register. Section 30.11.3.1 on page 385 through Section 30.11.3.2 on page 385 explain in detail the algorithm for each NVM operation. Table 30-3. Fuse and lock bit commands. CMD[6:0] Group Configuration Description Trigger CPU Halted Change Protected NVM Busy Address Pointer Data Register 0x00 NO_OPERATION No operation - - - - - - Fuses and Lock Bits 0x07 READ_FUSES Read fuses CMDEX Y N Y ADDR DATA 0x08 WRITE_LOCK_BITS Write lock bits CMDEX N Y Y ADDR - XMEGA B [MANUAL] 385 Atmel-8291C-AVR-XMEGA B -09/2014 30.11.3.1 Write Lock Bits The write lock bits command is used to program the boot lock bits to a more secure settings from software. 1. Load the NVM DATA0 register with the new lock bit value. 2. Load the NVM CMD register with the write lock bit command. 3. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the command is finished. The CPU is halted during the complete execution of the command. This command can be executed from both the boot loader section and the application section. The EEPROM and flash page buffers are automatically erased when the lock bits are written. 30.11.3.2 Read Fuses The read fuses command is used to read the fuses from software. 1. Load the NVM ADDR register with the address of the fuse byte to read. 2. Load the NVM CMD register with the read fuses command. 3. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The result will be available in the NVM DATA0 register. The CPU is halted during the complete execution of the command. 30.11.4 EEPROM Programming The EEPROM can be read and written from application code in any part of the flash. Its is both byte and page accessible. This means that either one byte or one page can be written to the EEPROM at once. One byte is read from the EEPROM during a read. 30.11.4.1 Addressing the EEPROM The EEPROM can be accessed through the NVM controller (I/O mapped), similar to accessing the flash program memory, or it can be memory mapped into the data memory space to be accessed similar to SRAM. When accessing the EEPROM through the NVM controller, the NVM address (ADDR) register is used to address the EEPROM, while the NVM data (DATA) register is used to store or load EEPROM data. For EEPROM page programming, the ADDR register can be treated as having two sections. The least-significant bits address the bytes within a page, while the most-significant bits address the page within the EEPROM. This is shown in Figure 30-2 on page 386. The byte address in the page (E2BYTE) is held by the bits [BYTEMSB:0] in the ADDR register. The remaining bits [PAGEMSB:BYTEMSB+1] in the ADDR register hold the EEPROM page address (E2PAGE). Together E2BYTE and E2PAGE hold an absolute address to a byte in the EEPROM. The size of E2WORD and E2PAGE will depend on the page and flash size in the device. Refer to the device datasheet for details on this. XMEGA B [MANUAL] 386 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 30-2. I/O mapped EEPROM addressing. When EEPROM memory mapping is enabled, loading a data byte into the EEPROM page buffer can be performed through direct or indirect store instructions. Only the least-significant bits of the EEPROM address are used to determine locations within the page buffer, but the complete memory mapped EEPROM address is always required to ensure correct address mapping. Reading from the EEPROM can be done directly using direct or indirect load instructions. When a memory mapped EEPROM page buffer load operation is performed, the CPU is halted for two cycles before the next instruction is executed. When the EEPROM is memory mapped, the EEPROM page buffer load and EEPROM read functionality from the NVM controller are disabled. 30.11.5 NVM EEPROM Commands The NVM flash commands that can be used for accessing the EEPROM through the NVM controller are listed in Table 30-4. For self-programming of the EEPROM, the trigger for action-triggered commands is to set the CMDEX bit in the NVM CTRLA register (CMDEX). The read-triggered command is triggered by reading the NVM DATA0 register (DATA0). The Change Protected column indicates whether the trigger is protected by the configuration change protection (CCP) during self-programming or not. CCP is not required for external programming. The last two columns show the address pointer used for addressing and the source/destination data register. Section 30.11.5.1 on page 387 through Section 30.11.5.7 on page 388 explain in detail the algorithm for each EEPROM operation. Table 30-4. EEPROM self-programming commands. E2PAGE E2BYTE BIT NVM ADDR PAGEMSB BYTEMSB 0 PAGE DATA BYTE EEPROM MEMORY PAGE BYTE ADDRESS WITHIN A PAGE PAGE ADDRESS WITHIN THE EEPROM E2BYTE 00 01 02 E2PAGEEND E2PAGE 00 01 02 E2END CMD[6:0] Group Configuration Description Trigger CPU Halted Change Protected NVM Busy Address Pointer Data Register 0x00 NO_OPERATION No operation - - - - - - EEPROM Page Buffer 0x33 LOAD_EEPROM_BUFFER Load EEPROM page buffer DATA0 N Y N ADDR DATA0 0x36 ERASE_EEPROM _BUFFER Erase EEPROM page buffer CMDEX N Y Y - - XMEGA B [MANUAL] 387 Atmel-8291C-AVR-XMEGA B -09/2014 30.11.5.1 Load EEPROM Page Buffer The load EEPROM page buffer command is used to load one byte into the EEPROM page buffer. 1. Load the NVM CMD register with the load EEPROM page buffer command. 2. Load the NVM ADDR0 register with the address to write. 3. Load the NVM DATA0 register with the data to write. This will trigger the command. Repeat steps 2-3 until the arbitrary number of bytes are loaded into the page buffer. 30.11.5.2 Erase EEPROM Page Buffer The erase EEPROM page buffer command is used to erase the EEPROM page buffer. 1. Load the NVM CMD register with the erase EEPROM buffer command. 2. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the operation is finished. 30.11.5.3 Erase EEPROM Page The erase EEPROM page command is used to erase one EEPROM page. 1. Set up the NVM CMD register to the erase EEPROM page command. 2. Load the NVM ADDR register with the address of the EEPROM page to erase. 3. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the operation is finished. The page erase commands will only erase the locations that are loaded and tagged in the EEPROM page buffer. 30.11.5.4 Write EEPROM Page The write EEPROM page command is used to write all locations loaded in the EEPROM page buffer into one page in EEPROM. Only the locations that are loaded and tagged in the EEPROM page buffer will be written. 1. Load the NVM CMD register with the write EEPROM page command. 2. Load the NVM ADDR register with the address of the EEPROM page to write. 3. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the operation is finished. 30.11.5.5 Erase and Write EEPROM Page The erase and write EEPROM page command is used to first erase an EEPROM page and then write the EEPROM page buffer into that page in EEPROM in one atomic operation. 1. Load the NVM CMD register with the erase and write EEPROM page command. 2. Load the NVM ADDR register with the address of the EEPROM page to write. 3. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the operation is finished. EEPROM 0x32 ERASE_EEPROM_PAGE Erase EEPROM page CMDEX N Y Y ADDR - 0x34 WRITE_EEPROM_PAGE Write EEPROM page CMDEX N Y Y ADDR - 0x35 ERASE_WRITE_EEPROM_PAGE Erase and write EEPROM page CMDEX N Y Y ADDR - 0x30 ERASE_EEPROM Erase EEPROM CMDEX N Y Y - - 0x06 READ_EEPROM Read EEPROM CMDEX N Y N ADDR DATA0 CMD[6:0] Group Configuration Description Trigger CPU Halted Change Protected NVM Busy Address Pointer Data Register XMEGA B [MANUAL] 388 Atmel-8291C-AVR-XMEGA B -09/2014 30.11.5.6 Erase EEPROM The erase EEPROM command is used to erase all locations in all EEPROM pages that are loaded and tagged in the EEPROM page buffer. 1. Set up the NVM CMD register to the erase EPPROM command. 2. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the operation is finished. 30.11.5.7 Read EEPROM The read EEPROM command is used to read one byte from the EEPROM. 1. Load the NVM CMD register with the read EEPROM command. 2. Load the NVM ADDR register with the address to read. 3. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The data byte read will be available in the NVM DATA0 register. 30.12 External Programming External programming is the method for programming code and nonvolatile data into the device from an external programmer or debugger. This can be done by both in-system or in mass production programming. For external programming, the device is accessed through the PDI and PDI controller, and using either the JTAG or PDI physical connection. For details on PDI and JTAG and how to enable and use the physical interface, refer to “Program and Debug Interface” on page 361. The remainder of this section assumes that the correct physical connection to the PDI is enabled. Doing this all data and program memory spaces are mapped into the linear PDI memory space. Figure 30-3 on page 389 shows the PDI memory space and the base address for each memory space in the device. XMEGA B [MANUAL] 389 Atmel-8291C-AVR-XMEGA B -09/2014 Figure 30-3. Memory map for PDI accessing the data and program memories. 30.12.1 Enabling External Programming Interface NVM programming from the PDI requires enabling using the following steps: 1. Load the RESET register in the PDI with 0x59. 2. Load the NVM key in the PDI. 3. Poll NVMEN in the PDI status register (PDI STATUS) until NVMEN is set. When the NVMEN bit in the PDI STATUS register is set, the NVM interface is enabled and active from the PDI. 30.12.2 NVM Programming When the PDI NVM interface is enabled, all memories in the device are memory mapped in the PDI address space. The PDI controller does not need to access the NVM controller's address or data registers, but the NVM controller must be loaded with the correct command (i.e., to read from any NVM, the controller must be loaded with the NVM read command FLASH_BASE = 0x0800000 EPPROM_BASE = 0x08C0000 FUSE_BASE = 0x08F0020 DATAMEM_BASE = 0x1000000 APP_BASE = FLASH_BASE BOOT_BASE = FLASH_BASE + SIZE_APPL PROD_SIGNATURE_BASE = 0x008E0200 USER_SIGNATURE_BASE = 0x008E0400 0x0000000 FUSES APPLICATION SECTION 16 MB BOOT SECTION 0x0800000 0x08F0020 TOP=0x1FFFFFF EEPROM 0x08E0200 SIGNATURE ROW 0x08C0000 0x08C1000 DATAMEM (mapped IO/SRAM) 16 MB 0x1000000 1 BYTE XMEGA B [MANUAL] 390 Atmel-8291C-AVR-XMEGA B -09/2014 before loading data from the PDIBUS address space). For the reminder of this section, all references to reading and writing data or program memory addresses from the PDI refer to the memory map shown in Figure 30-3 on page 389. The PDI uses byte addressing, and hence all memory addresses must be byte addresses. When filling the flash or EEPROM page buffers, only the least-significant bits of the address are used to determine locations within the page buffer. Still, the complete memory mapped address for the flash or EEPROM page is required to ensure correct address mapping. During programming (page erase and page write) when the NVM is busy, the NVM is blocked for reading. 30.12.3 NVM Commands The NVM commands that can be used for accessing the NVM memories from external programming are listed in Table 30-5 on page 390. This is a superset of the commands available for self-programming. For external programming, the trigger for action-triggered commands is to set the CMDEX bit in the NVM CTRLA register (CMDEX). The read-triggered commands are triggered by a direct or indirect load instruction (LDS or LD) from the PDI (PDI read). The write-triggered commands are triggered by a direct or indirect store instruction (STS or ST) from the PDI (PDI write). “ Chip Erase” on page 391 through “ Write Fuse/ Lock Bit” on page 393 explain in detail the algorithm for each NVM operation. The commands are protected by the lock bits, and if read and write lock is set, only the chip erase and flash CRC commands are available. Table 30-5. NVM commands available for external programming. CMD[6:0] Commands / Operation Trigger Change Protected NVM Busy 0x00 No operation - - - 0x40 Chip erase(1) CMDEX Y Y 0x43 Read NVM PDI Read N N Flash Page Buffer 0x23 Load flash page buffer PDI Write N N 0x26 Erase flash page buffer CMDEX Y Y Flash 0x2B Erase flash page PDI write N Y 0x2E Write flash page PDI write N Y 0x2F Erase and write flash page PDI write N Y 0x78 Flash CRC CMDEX Y Y Application Section 0x20 Erase application section PDI write N Y 0x22 Erase application section page PDI write N Y 0x24 Write application section page PDI write N Y 0x25 Erase and write application section page PDI write N Y 0x38 Application section CRC CMDEX Y Y Boot Loader Section 0x68 Erase boot section PDI write N Y 0x2A Erase boot loader section page PDI write N Y 0x2C Write boot loader section page PDI write N Y XMEGA B [MANUAL] 391 Atmel-8291C-AVR-XMEGA B -09/2014 Notes: 1. If the EESAVE fuse is programmed, the EEPROM is preserved during chip erase. 2. For consistency the name Calibration Row has been renamed to Production Signature Row throughout the document. 30.12.3.1 Chip Erase The chip erase command is used to erase the flash program memory, EEPROM and lock bits. Erasing of the EEPROM depends on EESAVE fuse setting. Refer to “FUSEBYTE5 – Fuse Byte 5” on page 32 for details. The user signature row, production signature (calibration) row, and fuses are not affected. 1. Load the NVM CMD register with the chip erase command. 2. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. Once this operation starts, the PDI bus between the PDI controller and the NVM is disabled, and the NVMEN bit in the PDI STATUS register is cleared until the operation is finished. Poll the NVMEN bit until this is set, indicating that the PDI bus is enabled. The BUSY flag in the NVM STATUS register will be set until the operation is finished. 30.12.3.2 Read NVM The read NVM command is used to read the flash, EEPROM, fuses, and signature and production signature (calibration) row sections. 1. Load the NVM CMD register with the read NVM command. 2. Read the selected memory address by executing a PDI read operation. 0x2D Erase and write boot loader section page PDI write N Y 0x39 Boot loader section CRC NVMAA Y Y Production Signature (Calibration)(2) and User Signature Sections 0x01 Read user signature row PDI read N N 0x18 Erase user signature row PDI write N Y 0x1A Write user signature row PDI write N Y 0x02 Read calibration row PDI read N N Fuses and Lock Bits 0x07 Read fuse PDI read N N 0x4C Write fuse PDI write N Y 0x08 Write lock bits CMDEX Y Y EEPROM Page Buffer 0x33 Load EEPROM page buffer PDI write N N 0x36 Erase EEPROM page buffer CMDEX Y Y EEPROM 0x30 Erase EEPROM CMDEX Y Y 0x32 Erase EEPROM page PDI write N Y 0x34 Write EEPROM page PDI write N Y 0x35 Erase and write EEPROM page PDI write N Y 0x06 Read EEPROM PDI read N N CMD[6:0] Commands / Operation Trigger Change Protected NVM Busy XMEGA B [MANUAL] 392 Atmel-8291C-AVR-XMEGA B -09/2014 Dedicated read EEPROM, read fuse, read signature row, and read production signature (calibration) row commands are also available for the various memory sections. The algorithm for these commands are the same as for the read NVM command. 30.12.3.3 Erase Page Buffer The erase flash page buffer and erase EEPROM page buffer commands are used to erase the flash and EEPROM page buffers. 1. Load the NVM CMD register with the erase flash/EEPROM page buffer command. 2. Set the CMDEX bit in the NVM CTRLA register. The BUSY flag in the NVM STATUS register will be set until the operation is completed. 30.12.3.4 Load Page Buffer The load flash page buffer and load EEPROM page buffer commands are used to load one byte of data into the flash and EEPROM page buffers. 1. Load the NVM CMD register with the load flash/EEPROM page buffer command. 2. Write the selected memory address by doing a PDI write operation. Since the flash page buffer is word accessed and the PDI uses byte addressing, the PDI must write the flash page buffer in the correct order. For the write operation, the low byte of the word location must be written before the high byte. The low byte is then written into the temporary register. The PDI then writes the high byte of the word location, and the low byte is then written into the word location page buffer in the same clock cycle. The PDI interface is automatically halted before the next PDI instruction can be executed. 30.12.3.5 Erase Page The erase application section page, erase boot loader section page, erase user signature row, and erase EEPROM page commands are used to erase one page in the selected memory space. 1. Load the NVM CMD register with erase application section/boot loader section/user signature row/EEPROM page command. 2. Set the CMDEX bit in the NVM CTRLA register. The BUSY flag in the NVM STATUS register will be set until the operation is finished. 30.12.3.6 Write Page The write application section page, write boot loader section page, write user signature row, and write EEPROM page commands are used to write a loaded flash/EEPROM page buffer into the selected memory space. 1. Load the NVM CMD register with write application section/boot loader section/user signature row/EEPROM page command. 2. Write the selected page by doing a PDI write. The page is written by addressing any byte location within the page. The BUSY flag in the NVM STATUS register will be set until the operation is finished. 30.12.3.7 Erase and Write Page The erase and write application section page, erase and write boot loader section page, and erase and write EEPROM page commands are used to erase one page and then write a loaded flash/EEPROM page buffer into that page in the selected memory space in one atomic operation. 1. Load the NVM CMD register with erase and write application section/boot loader section/user signature row/EEPROM page command. 2. Write the selected page by doing a PDI write. The page is written by addressing any byte location within the page. The BUSY flag in the NVM STATUS register will be set until the operation is finished. 30.12.3.8 Erase Application/ Boot Loader/ EEPROM Section The erase application section, erase boot loader section, and erase EEPROM section commands are used to erase the complete selected section. XMEGA B [MANUAL] 393 Atmel-8291C-AVR-XMEGA B -09/2014 1. Load the NVM CMD register with Erase Application/ Boot/ EEPROM Section command 2. Set the CMDEX bit in the NVM CTRLA register. The BUSY flag in the NVM STATUS register will be set until the operation is finished. 30.12.3.9 Application / Boot Section CRC The application section CRC and boot loader section CRC commands can be used to verify the content of the selected section after programming. 1. Load the NVM CMD register with application/ boot loader section CRC command. 2. Set the CMDEX bit in the NVM CTRLA register. This requires the timed CCP sequence during self-programming. The BUSY flag in the NVM STATUS register will be set until the operation is finished. The CRC checksum will be available in the NVM DATA register. 30.12.3.10 Flash CRC The flash CRC command can be used to verify the content of the flash program memory after programming. The command can be executed independently of the lock bit state. 1. Load the NVM CMD register with flash CRC command. 2. Set the CMDEX bit in the NVM CTRLA register. Once this operation starts, the PDI bus between the PDI controller and the NVM is disabled, and the NVMEN bit in the PDI STATUS register is cleared until the operation is finished. Poll the NVMEN bit until this is set again, indicting the PDI bus is enabled. The BUSY flag in the NVM STATUS register will be set until the operation is finished. The CRC checksum will be available in the NVM DATA register. 30.12.3.11 Write Fuse/ Lock Bit The write fuse and write lock bit commands are used to write the fuses and the lock bits to a more secure setting. 1. Load the NVM CMD register with the write fuse/ lock bit command. 2. Write the selected fuse or lock bits by doing a PDI write operation. The BUSY flag in the NVM STATUS register will be set until the command is finished. For lock bit write, the lock bit write command can also be used. 30.13 Register Description Refer to “Register Description – NVM Controller” on page 26 for a complete register description of the NVM controller. Refer to “Register Description – PDI Control and Status Registers” on page 373 for a complete register description of the PDI. 30.14 Register Summary Refer to “Register Description – NVM Controller” on page 26 for a complete register summary of the NVM controller. Refer to “Register Summary” on page 374 for a complete register summary of the PDI. XMEGA B [MANUAL] 394 Atmel-8291C-AVR-XMEGA B -09/2014 31. Peripheral Module Address Map The address maps show the base address for each peripheral and module in XMEGA. All peripherals and modules are not present in all XMEGA devices, refer to device data sheet for the peripherals module address map for a specific device. Base Address Name Description Page 0x0000 GPIO General Purpose IO Registers page 42 0x0010 VPORT0 Virtual Port 0 page 132 0x0014 VPORT1 Virtual Port 1 0x0018 VPORT2 Virtual Port 2 0x001C VPORT3 Virtual Port 3 0x0030 CPU CPU page 19 0x0040 CLK Clock Control page 96 0x0048 SLEEP Sleep Controller page 101 0x0050 OSC Oscillator Control page 96 0x0060 DFLLRC32M DFLL for the 32 MHz Internal RC Oscillator page 96 0x0068 DFLLRC2M DFLL for the 2 MHz RC Oscillator 0x0070 PR Power Reduction page 98 0x0078 RST Reset Controller page 109 0x0080 WDT Watch-Dog Timer page 114 0x0090 MCU MCU Control page 42 0x00A0 PMIC Programmable Multilevel Interrupt Controller page 122 0x00B0 PORTCFG Port Configuration page 146 0x00C0 AES AES Module page 292 0x0100 DMA DMA Controller page 62 0x0180 EVSYS Event System page 74 0x01C0 NVM Non Volatile Memory (NVM) Controller page 46 0x0200 ADCA Analog to Digital Converter on port A page 344 0x0240 ADCB Analog to Digital Converter on port B 0x0380 ACA Analog Comparator pair on port A page 353 0x0390 ACB Analog Comparator pair on port B 0x0400 RTC Real Time Counter page 205 0x0480 TWIC Two Wire Interface on port C page 254 0x04C0 USB Universal Serial Bus Interface page 281 0x0600 PORTA Port A page 146 0x0620 PORTB Port B 0x0640 PORTC Port C 0x0660 PORTD Port D 0x0680 PORTE Port E 0x06C0 PORTG Port G 0x0760 PORTM Port M 0x07E0 PORTR Port R 0x0800 TCC0 Timer/Counter 0 on port C page 172 0x0840 TCC1 Timer/Counter 1 on port C 0x0880 AWEXC Advanced Waveform Extension on port C page 195 0x0890 HIRESC High Resolution Extension on port C page 197 0x08A0 USARTC0 USART 0 on port C page 281 0x08C0 SPIC Serial Peripheral Interface on port C page 260 0x08F0 IRCOM Infrared Communication Module page 285 0x0A00 TCE0 Timer/Counter 0 on port E page 172 0x0AA0 USARTE0 USART 0 on port E page 281 0x0D00 LCD LCD - Liquid Crystal Display page 319 Atmel-8291C-AVR-XMEGA B -09/2014 395 32. Instruction Set Summary Mnemonics Operands Description Operation Flags #Clocks Arithmetic and Logic Instructions ADD Rd, Rr Add without Carry Rd ← Rd + Rr Z,C,N,V,S,H 1 ADC Rd, Rr Add with Carry Rd ← Rd + Rr + C Z,C,N,V,S,H 1 ADIW Rd, K Add Immediate to Word Rd ← Rd + 1:Rd + K Z,C,N,V,S 2 SUB Rd, Rr Subtract without Carry Rd ← Rd - Rr Z,C,N,V,S,H 1 SUBI Rd, K Subtract Immediate Rd ← Rd - K Z,C,N,V,S,H 1 SBC Rd, Rr Subtract with Carry Rd ← Rd - Rr - C Z,C,N,V,S,H 1 SBCI Rd, K Subtract Immediate with Carry Rd ← Rd - K - C Z,C,N,V,S,H 1 SBIW Rd, K Subtract Immediate from Word Rd + 1:Rd ← Rd + 1:Rd - K Z,C,N,V,S 2 AND Rd, Rr Logical AND Rd ← Rd • Rr Z,N,V,S 1 ANDI Rd, K Logical AND with Immediate Rd ← Rd • K Z,N,V,S 1 OR Rd, Rr Logical OR Rd ← Rd v Rr Z,N,V,S 1 ORI Rd, K Logical OR with Immediate Rd ← Rd v K Z,N,V,S 1 EOR Rd, Rr Exclusive OR Rd ← Rd ⊕ Rr Z,N,V,S 1 COM Rd One’s Complement Rd ← $FF - Rd Z,C,N,V,S 1 NEG Rd Two’s Complement Rd ← $00 - Rd Z,C,N,V,S,H 1 SBR Rd,K Set Bit(s) in Register Rd ← Rd v K Z,N,V,S 1 CBR Rd,K Clear Bit(s) in Register Rd ← Rd • ($FFh - K) Z,N,V,S 1 INC Rd Increment Rd ← Rd + 1 Z,N,V,S 1 DEC Rd Decrement Rd ← Rd - 1 Z,N,V,S 1 TST Rd Test for Zero or Minus Rd ← Rd • Rd Z,N,V,S 1 CLR Rd Clear Register Rd ← Rd ⊕ Rd Z,N,V,S 1 SER Rd Set Register Rd ← $FF None 1 MUL Rd,Rr Multiply Unsigned R1:R0 ← Rd x Rr (UU) Z,C 2 MULS Rd,Rr Multiply Signed R1:R0 ← Rd x Rr (SS) Z,C 2 MULSU Rd,Rr Multiply Signed with Unsigned R1:R0 ← Rd x Rr (SU) Z,C 2 FMUL Rd,Rr Fractional Multiply Unsigned R1:R0 ← Rd x Rr<<1 (UU) Z,C 2 FMULS Rd,Rr Fractional Multiply Signed R1:R0 ← Rd x Rr<<1 (SS) Z,C 2 FMULSU Rd,Rr Fractional Multiply Signed with Unsigned R1:R0 ← Rd x Rr<<1 (SU) Z,C 2 DES K Data Encryption if (H = 0) then R15:R0 else if (H = 1) then R15:R0 ← ← Encrypt(R15:R0, K) Decrypt(R15:R0, K) 1/2 Branch instructions RJMP k Relative Jump PC ← PC + k + 1 None 2 IJMP Indirect Jump to (Z) PC(15:0) PC(21:16) ← ← Z, 0 None 2 EIJMP Extended Indirect Jump to (Z) PC(15:0) PC(21:16) ← ← Z, EIND None 2 JMP k Jump PC ← k None 3 Atmel-8291C-AVR-XMEGA B -09/2014 396 RCALL k Relative Call Subroutine PC ← PC + k + 1 None 2 / 3(1) ICALL Indirect Call to (Z) PC(15:0) PC(21:16) ← ← Z, 0 None 2 / 3(1) EICALL Extended Indirect Call to (Z) PC(15:0) PC(21:16) ← ← Z, EIND None 3(1) CALL k call Subroutine PC ← k None 3 / 4(1) RET Subroutine Return PC ← STACK None 4 / 5(1) RETI Interrupt Return PC ← STACK I 4 / 5(1) CPSE Rd,Rr Compare, Skip if Equal if (Rd = Rr) PC ← PC + 2 or 3 None 1 / 2 / 3 CP Rd,Rr Compare Rd - Rr Z,C,N,V,S,H 1 CPC Rd,Rr Compare with Carry Rd - Rr - C Z,C,N,V,S,H 1 CPI Rd,K Compare with Immediate Rd - K Z,C,N,V,S,H 1 SBRC Rr, b Skip if Bit in Register Cleared if (Rr(b) = 0) PC ← PC + 2 or 3 None 1 / 2 / 3 SBRS Rr, b Skip if Bit in Register Set if (Rr(b) = 1) PC ← PC + 2 or 3 None 1 / 2 / 3 SBIC A, b Skip if Bit in I/O Register Cleared if (I/O(A,b) = 0) PC ← PC + 2 or 3 None 2 / 3 / 4 SBIS A, b Skip if Bit in I/O Register Set If (I/O(A,b) =1) PC ← PC + 2 or 3 None 2 / 3 / 4 BRBS s, k Branch if Status Flag Set if (SREG(s) = 1) then PC ← PC + k + 1 None 1 / 2 BRBC s, k Branch if Status Flag Cleared if (SREG(s) = 0) then PC ← PC + k + 1 None 1 / 2 BREQ k Branch if Equal if (Z = 1) then PC ← PC + k + 1 None 1 / 2 BRNE k Branch if Not Equal if (Z = 0) then PC ← PC + k + 1 None 1 / 2 BRCS k Branch if Carry Set if (C = 1) then PC ← PC + k + 1 None 1 / 2 BRCC k Branch if Carry Cleared if (C = 0) then PC ← PC + k + 1 None 1 / 2 BRSH k Branch if Same or Higher if (C = 0) then PC ← PC + k + 1 None 1 / 2 BRLO k Branch if Lower if (C = 1) then PC ← PC + k + 1 None 1 / 2 BRMI k Branch if Minus if (N = 1) then PC ← PC + k + 1 None 1 / 2 BRPL k Branch if Plus if (N = 0) then PC ← PC + k + 1 None 1 / 2 BRGE k Branch if Greater or Equal, Signed if (N ⊕ V= 0) then PC ← PC + k + 1 None 1 / 2 BRLT k Branch if Less Than, Signed if (N ⊕ V= 1) then PC ← PC + k + 1 None 1 / 2 BRHS k Branch if Half Carry Flag Set if (H = 1) then PC ← PC + k + 1 None 1 / 2 BRHC k Branch if Half Carry Flag Cleared if (H = 0) then PC ← PC + k + 1 None 1 / 2 BRTS k Branch if T Flag Set if (T = 1) then PC ← PC + k + 1 None 1 / 2 BRTC k Branch if T Flag Cleared if (T = 0) then PC ← PC + k + 1 None 1 / 2 BRVS k Branch if Overflow Flag is Set if (V = 1) then PC ← PC + k + 1 None 1 / 2 BRVC k Branch if Overflow Flag is Cleared if (V = 0) then PC ← PC + k + 1 None 1 / 2 BRIE k Branch if Interrupt Enabled if (I = 1) then PC ← PC + k + 1 None 1 / 2 BRID k Branch if Interrupt Disabled if (I = 0) then PC ← PC + k + 1 None 1 / 2 Data transfer instructions MOV Rd, Rr Copy Register Rd ← Rr None 1 MOVW Rd, Rr Copy Register Pair Rd+1:Rd ← Rr+1:Rr None 1 Mnemonics Operands Description Operation Flags #Clocks Atmel-8291C-AVR-XMEGA B -09/2014 397 LDI Rd, K Load Immediate Rd ← K None 1 LDS Rd, k Load Direct from data space Rd ← (k) None 2(1)(2) LD Rd, X Load Indirect Rd ← (X) None 1(1)(2) LD Rd, X+ Load Indirect and Post-Increment Rd X ← ← (X) X + 1 None 1(1)(2) LD Rd, -X Load Indirect and Pre-Decrement X ← X - 1, Rd ← (X) ← ← X - 1 (X) None 2(1)(2) LD Rd, Y Load Indirect Rd ← (Y) ← (Y) None 1(1)(2) LD Rd, Y+ Load Indirect and Post-Increment Rd Y ← ← (Y) Y + 1 None 1(1)(2) LD Rd, -Y Load Indirect and Pre-Decrement Y Rd ← ← Y - 1 (Y) None 2(1)(2) LDD Rd, Y+q Load Indirect with Displacement Rd ← (Y + q) None 2(1)(2) LD Rd, Z Load Indirect Rd ← (Z) None 1(1)(2) LD Rd, Z+ Load Indirect and Post-Increment Rd Z ← ← (Z), Z+1 None 1(1)(2) LD Rd, -Z Load Indirect and Pre-Decrement Z Rd ← ← Z - 1, (Z) None 2(1)(2) LDD Rd, Z+q Load Indirect with Displacement Rd ← (Z + q) None 2(1)(2) STS k, Rr Store Direct to Data Space (k) ← Rd None 2(1) ST X, Rr Store Indirect (X) ← Rr None 1(1) ST X+, Rr Store Indirect and Post-Increment (X) X ← ← Rr, X + 1 None 1(1) ST -X, Rr Store Indirect and Pre-Decrement X (X) ← ← X - 1, Rr None 2(1) ST Y, Rr Store Indirect (Y) ← Rr None 1(1) ST Y+, Rr Store Indirect and Post-Increment (Y) Y ← ← Rr, Y + 1 None 1(1) ST -Y, Rr Store Indirect and Pre-Decrement Y (Y) ← ← Y - 1, Rr None 2(1) STD Y+q, Rr Store Indirect with Displacement (Y + q) ← Rr None 2(1) ST Z, Rr Store Indirect (Z) ← Rr None 1(1) ST Z+, Rr Store Indirect and Post-Increment (Z) Z ← ← Rr Z + 1 None 1(1) ST -Z, Rr Store Indirect and Pre-Decrement Z ← Z - 1 None 2(1) STD Z+q,Rr Store Indirect with Displacement (Z + q) ← Rr None 2(1) LPM Load Program Memory R0 ← (Z) None 3 LPM Rd, Z Load Program Memory Rd ← (Z) None 3 LPM Rd, Z+ Load Program Memory and PostIncrement Rd Z ← ← (Z), Z + 1 None 3 ELPM Extended Load Program Memory R0 ← (RAMPZ:Z) None 3 ELPM Rd, Z Extended Load Program Memory Rd ← (RAMPZ:Z) None 3 ELPM Rd, Z+ Extended Load Program Memory and Post-Increment Rd Z ← ← (RAMPZ:Z), Z + 1 None 3 SPM Store Program Memory (RAMPZ:Z) ← R1:R0 None - Mnemonics Operands Description Operation Flags #Clocks Atmel-8291C-AVR-XMEGA B -09/2014 398 SPM Z+ Store Program Memory and PostIncrement by 2 (RAMPZ:Z) Z ← ← R1:R0, Z + 2 None - IN Rd, A In From I/O Location Rd ← I/O(A) None 1 OUT A, Rr Out To I/O Location I/O(A) ← Rr None 1 PUSH Rr Push Register on Stack STACK ← Rr None 1(1) POP Rd Pop Register from Stack Rd ← STACK None 2(1) XCH Z, Rd Exchange RAM location Temp Rd (Z) ← ← ← Rd, (Z), Temp None 2 LAS Z, Rd Load and Set RAM location Temp Rd (Z) ← ← ← Rd, (Z), Temp v (Z) None 2 LAC Z, Rd Load and Clear RAM location Temp Rd (Z) ← ← ← Rd, (Z), ($FFh – Rd) • (Z) None 2 LAT Z, Rd Load and Toggle RAM location Temp Rd (Z) ← ← ← Rd, (Z), Temp ⊕ (Z) None 2 Bit and bit-test instructions LSL Rd Logical Shift Left Rd(n+1) Rd(0) C ← ← ← Rd(n), 0, Rd(7) Z,C,N,V,H 1 LSR Rd Logical Shift Right Rd(n) Rd(7) C ← ← ← Rd(n+1), 0, Rd(0) Z,C,N,V 1 ROL Rd Rotate Left Through Carry Rd(0) Rd(n+1) C ← ← ← C, Rd(n), Rd(7) Z,C,N,V,H 1 ROR Rd Rotate Right Through Carry Rd(7) Rd(n) C ← ← ← C, Rd(n+1), Rd(0) Z,C,N,V 1 ASR Rd Arithmetic Shift Right Rd(n) ← Rd(n+1), n=0..6 Z,C,N,V 1 SWAP Rd Swap Nibbles Rd(3..0) ↔ Rd(7..4) None 1 BSET s Flag Set SREG(s) ← 1 SREG(s) 1 BCLR s Flag Clear SREG(s) ← 0 SREG(s) 1 SBI A, b Set Bit in I/O Register I/O(A, b) ← 1 None 1 CBI A, b Clear Bit in I/O Register I/O(A, b) ← 0 None 1 BST Rr, b Bit Store from Register to T T ← Rr(b) T 1 BLD Rd, b Bit load from T to Register Rd(b) ← T None 1 SEC Set Carry C ← 1 C 1 CLC Clear Carry C ← 0 C 1 SEN Set Negative Flag N ← 1 N 1 CLN Clear Negative Flag N ← 0 N 1 SEZ Set Zero Flag Z ← 1 Z 1 CLZ Clear Zero Flag Z ← 0 Z 1 SEI Global Interrupt Enable I ← 1 I 1 CLI Global Interrupt Disable I ← 0 I 1 Mnemonics Operands Description Operation Flags #Clocks Atmel-8291C-AVR-XMEGA B -09/2014 399 Notes: 1. Cycle times for data memory accesses assume internal memory accesses, and are not valid for accesses via the external RAM interface. 2. One extra cycle must be added when accessing Internal SRAM. SES Set Signed Test Flag S ← 1 S 1 CLS Clear Signed Test Flag S ← 0 S 1 SEV Set Two’s Complement Overflow V ← 1 V 1 CLV Clear Two’s Complement Overflow V ← 0 V 1 SET Set T in SREG T ← 1 T 1 CLT Clear T in SREG T ← 0 T 1 SEH Set Half Carry Flag in SREG H ← 1 H 1 CLH Clear Half Carry Flag in SREG H ← 0 H 1 MCU control instructions BREAK Break (See specific descr. for BREAK) None 1 NOP No Operation None 1 SLEEP Sleep (see specific descr. for Sleep) None 1 WDR Watchdog Reset (see specific descr. for WDR) None 1 Mnemonics Operands Description Operation Flags #Clocks XMEGA B [MANUAL] 400 Atmel-8291C-AVR-XMEGA B -09/2014 33. Datasheet Revision History Please note that the referring page numbers in this section are referring to this document. The referring revision in this section are referring to the document revision. 33.1 8291C – 06/2014 33.2 8291B – 01/2013 1. Replaced RCOSC48M with USBRCOSC in Section 4.15.19 on page 40 and in Section 4.20 on page 45. 2. Changed VCC to AVCC in the section “AC – Analog Comparator” on page 345 and onwards, and in “Voltage Reference Selection” on page 324. 3. Updated last page and footers from template of May 5 2014. 1. Added XMEGA B feature overview inTable 2-1 on page 5. 2. References to Calibration Row updated to Production Signature Row for consistency. 3. Added reference to “NVM Flash Commands” on page 380 in “Production Signature Row” on page 22. 4. Updated “LOCKBITS – Lock Bits register” on page 30. Description of Bit[1:0] updated and added a table note. 5. Title of Table 4-12 on page 35 changed to “Lock bit protection mode.” 6. Updated “TRIGSRC – Trigger Source” on page 57. The description Bit[7:0] updated. 7 Updated description of “CHnCTRL – Event Channel n Control register” on page 72. 8. Updated the formula of COMP register in “DFLL 2MHz and DFLL 32MHz” on page 82. 9. Updated Table 9-2 on page 105, the “Programmable BODLEVEL setting.” 10. Table note added to the Table 10-1 on page 112. 11. Table note added to the Table 10-2 on page 113. 12. Updated “Port Interrupt” on page 129. 13. Updated Table 12-3 on page 130. “Both edge” replaced by “Any edge”. 14. Updated “Port Event” on page 130. 15. Updated Table 12-10 on page 142, and Table 12-11 on page 143. 16. Updated “Event Action Controlled Operation” on page 153. 17. Updated Figure 13-10 on page 155. CH7MUX changed to CHnMUX. 18 Updated Table 13-2 in “DMA Support” on page 160. 19. Updated Table 14-3 on page 179. CMD changed to BYTEM[1:0] 20. Updated “Clock Domains” on page 199. 21. Updated description in “For Output Endpoints” on page 213. 22. Updated both formula of “BAUD – Baud Rate register” on page 247 23. Updated “DATA – Data register” on page 248. Added the description of ADDR[7:1] and ADDR[0] XMEGA B [MANUAL] 401 Atmel-8291C-AVR-XMEGA B -09/2014 33.3 8291A – 07/2011 24. Updated the formula in “Fractional Baud Rate Generation” on page 271. 25. Updated Figure 21-9 on page 272, the “Fractional baud rate example.” 26. Added Table 21-5 on page 272, the “USART baud rate.” 27. Updated “ADC Input Model” on page 329. 26. Updated “Synchronous Sampling” on page 330. 27 Updated description of “Bit 3:0 – COUNT[3:0]: Number of Input Channels Included in Scan” in “SCAN – Input Channel Scan register” on page 343 28. Updated Analog Comparator overview block diagram in Figure 27-1 on page 346. 1. Initial revision edited from XMEGA AU Manual rev A 07/11 XMEGA B [MANUAL] 402 Atmel-8291C-AVR-XMEGA B -09/2014 Table of Contents 1. About the Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1 Reading the Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2 Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.3 Recommended Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Atmel AVR CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.3 Architectural Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.4 ALU - Arithmetic Logic Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.5 Program Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.6 Instruction Execution Timing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.7 Status Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.8 Stack and Stack Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.9 Register File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.10 RAMP and Extended Indirect Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.11 Accessing 16-bit Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.12 Configuration Change Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.13 Fuse Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.14 Register Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.15 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4. Memories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.3 Flash Program Memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.4 Fuses and Lockbits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 4.5 Data Memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 4.6 Internal SRAM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.7 EEPROM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.8 I/O Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.9 Data Memory and Bus Arbitration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.10 Memory Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.11 Device ID and Revision. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.12 I/O Memory Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.13 Register Description – NVM Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.14 Register Descriptions – Fuses and Lock Bits . . . . . . . . . . . . . . . . . . . . . . . . . 30 4.15 Register Description – Production Signature Row . . . . . . . . . . . . . . . . . . . . . 36 4.16 Register Description – General Purpose I/O Memory. . . . . . . . . . . . . . . . . . . 42 4.17 Register Descriptions – MCU Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 4.18 Register Summary - NVM Controller. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 4.19 Register Summary - Fuses and Lock Bits. . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 4.20 Register Summary - Production Signature Row . . . . . . . . . . . . . . . . . . . . . . . 45 4.21 Register Summary – General Purpose I/O Registers . . . . . . . . . . . . . . . . . . . 46 4.22 Register Summary – MCU Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 4.23 Interrupt Vector Summary – NVM Controller . . . . . . . . . . . . . . . . . . . . . . . . . 46 XMEGA B [MANUAL] 403 Atmel-8291C-AVR-XMEGA B -09/2014 5. DMAC - Direct Memory Access Controller . . . . . . . . . . . . . . . . . . . . . . . . . 47 5.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 5.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 5.3 DMA Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.4 Transfer Triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.5 Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.6 Priority Between Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.7 Double Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.8 Transfer Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.9 Error detection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.10 Software Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.11 Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.12 Interrupts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.13 Register Description – DMA Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 5.14 Register Description – DMA Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 5.15 Register Summary – DMA Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 5.16 Register Summary – DMA Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 5.17 DMA Interrupt Vector Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 6. Event System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 6.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 6.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 6.3 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 6.4 Event Routing Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 6.5 Event Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 6.6 Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 6.7 Quadrature Decoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 6.8 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 6.9 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 7. System Clock and Clock Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 7.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 7.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 7.3 Clock Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 7.4 Clock Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 7.5 System Clock Selection and Prescalers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 7.6 PLL with 1x-31x Multiplication Factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 7.7 DFLL 2MHz and DFLL 32MHz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 7.8 PLL and External Clock Source Failure Monitor . . . . . . . . . . . . . . . . . . . . . . . 82 7.9 Register Description – Clock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 7.10 Register Description – Oscillator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 7.11 Register Description – DFLL32M/DFLL2M . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 7.12 Register Summary - Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 7.13 Register Summary - Oscillator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 7.14 Register Summary - DFLL32M/DFLL2M. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 7.15 Oscillator Failure Interrupt Vector Summary . . . . . . . . . . . . . . . . . . . . . . . . . . 94 8. Power Management and Sleep Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 8.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 8.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 8.3 Sleep Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 XMEGA B [MANUAL] 404 Atmel-8291C-AVR-XMEGA B -09/2014 8.4 Power Reduction Registers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 8.5 Minimizing Power Consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 8.6 Register Description – Sleep. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 8.7 Register Description – Power Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 8.8 Register Summary - Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 8.9 Register Summary - Power Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 9. Reset System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 9.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 9.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 9.3 Reset Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 9.4 Reset Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 9.5 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 9.6 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 10. WDT – Watchdog Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 10.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 10.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 10.3 Normal Mode Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 10.4 Window Mode Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 10.5 Watchdog Timer Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 10.6 Configuration Protection and Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 10.7 Registers Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 10.8 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 11. Interrupts and Programmable Multilevel Interrupt Controller . . . . . . . 115 11.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 11.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 11.3 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 11.4 Interrupts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 11.5 Interrupt level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 11.6 Interrupt priority. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 11.7 Interrupt vector locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 11.8 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 11.9 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 12. I/O Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 12.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 12.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 12.3 I/O Pin Use and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 12.4 Reading the Pin Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 12.5 Input Sense Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 12.6 Port Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 12.7 Port Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 12.8 Alternate Port Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 12.9 Clock and Event Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 12.10 Multi-pin configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 12.11 Virtual Ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 12.12 Register Descriptions – Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 12.13 Register Descriptions – Port Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 140 12.14 Register Descriptions – Virtual Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 12.15 Register Summary – Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 XMEGA B [MANUAL] 405 Atmel-8291C-AVR-XMEGA B -09/2014 12.16 Register Summary – Port Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 12.17 Register Summary – Virtual Ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 12.18 Interrupt Vector Summary – Ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 13. TC0/1 – 16-bit Timer/Counter Type 0 and 1 . . . . . . . . . . . . . . . . . . . . . . 148 13.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 13.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 13.3 Block Diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 13.4 Clock and Event Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 13.5 Double Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 13.6 Counter Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 13.7 Capture Channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 13.8 Compare Channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 13.9 Interrupts and events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 13.10 DMA Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 13.11 Timer/Counter Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 13.12 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 13.13 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 13.14 Interrupt Vector Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 14. TC2 – 16-bit Timer/Counter Type 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 14.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 14.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 14.3 Block Diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 14.4 Clock Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 14.5 Counter Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 14.6 Compare Channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 14.7 Interrupts and Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 14.8 DMA Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 14.9 Timer/Counter Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 14.10 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 14.11 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 14.12 Interrupt Vector Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 15. AWeX – Advanced Waveform Extension . . . . . . . . . . . . . . . . . . . . . . . . . 185 15.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 15.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 15.3 Port Override. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 15.4 Dead-time Insertion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 15.5 Pattern Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 15.6 Fault Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 15.7 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 15.8 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 16. Hi-Res – High-Resolution Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 16.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 16.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 16.3 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 16.4 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 17. RTC – Real-Time Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 17.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 XMEGA B [MANUAL] 406 Atmel-8291C-AVR-XMEGA B -09/2014 17.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 17.3 Register Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 17.4 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 17.5 Interrupt Vector Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 18. USB – Universal Serial Bus Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 18.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 18.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 18.3 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 18.4 SRAM Memory Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 18.5 Clock Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 18.6 Ping-pong Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 18.7 Multipacket Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 18.8 Auto Zero Length Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 18.9 Transaction Complete FIFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 18.10 Interrupts and Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 18.11 VBUS Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 18.12 On-chip Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 18.13 Register Description – USB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 18.14 Register Description – USB Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 18.15 Register Description - Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 18.16 Register Summary – USB Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 18.17 Register Summary – USB Endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 18.18 Register Summary – Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 18.19 USB Interrupt Vector Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 19. TWI – Two-Wire Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 19.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 19.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 19.3 General TWI Bus Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 19.4 TWI Bus State Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 19.5 TWI Master Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 19.6 TWI Slave Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 19.7 Enabling External Driver Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 19.8 Register Description – TWI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 19.9 Register Description – TWI Master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 19.10 Register Description – TWI Slave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 19.11 Register Summary - TWI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 19.12 Register Summary - TWI Master. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 19.13 Register Summary - TWI Slave. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 19.14 Interrupt Vector Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 20. SPI – Serial Peripheral Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 20.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 20.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 20.3 Master Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 20.4 Slave Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 20.5 Data Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 20.6 DMA Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 20.7 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 20.8 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 20.9 Interrupt vector Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 XMEGA B [MANUAL] 407 Atmel-8291C-AVR-XMEGA B -09/2014 21. USART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 21.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 21.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 21.3 Clock Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 21.4 Frame Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 21.5 USART Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 21.6 Data Transmission - The USART Transmitter . . . . . . . . . . . . . . . . . . . . . . . 267 21.7 Data Reception - The USART Receiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 21.8 Asynchronous Data Reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 21.9 Fractional Baud Rate Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 21.10 USART in Master SPI Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 21.11 USART SPI vs. SPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 21.12 Multiprocessor Communication Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 21.13 IRCOM Mode of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 21.14 DMA Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 21.15 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 21.16 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 21.17 Interrupt Vector Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 22. IRCOM - IR Communication Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 22.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 22.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 22.3 Registers Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 22.4 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 23. AES and DES Crypto Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 23.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 23.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 23.3 DES Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 23.4 AES Crypto Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 23.5 Register Description – AES. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 23.6 Register summary – AES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 23.7 Interrupt vector summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 24. CRC – Cyclic Redundancy Check Generator . . . . . . . . . . . . . . . . . . . . . 293 24.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 24.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 24.3 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 24.4 CRC on Flash memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 24.5 CRC on DMA Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 24.6 CRC using the I/O Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 24.7 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 24.8 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 25. LCD – Liquid Crystal Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 25.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 25.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 25.3 Block Diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 25.4 Mode of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 25.5 Register Description – LCD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 25.6 Register Summary – LCD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 25.7 Interrupt Vector Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 XMEGA B [MANUAL] 408 Atmel-8291C-AVR-XMEGA B -09/2014 26. ADC – Analog-to-Digital Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 26.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 26.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 26.3 Input Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 26.4 Sampling Time Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 26.5 Voltage Reference Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 26.6 Conversion Result. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 26.7 Compare Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 26.8 Starting a Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 26.9 ADC Clock and Conversion Timing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 26.10 ADC Input Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 26.11 DMA Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 26.12 Interrupts and Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 26.13 Calibration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 26.14 Synchronous Sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 26.15 Register Description – ADC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 26.16 Register Description - ADC Channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 26.17 Register Summary – ADC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 26.18 Register Summary – ADC Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 26.19 Interrupt vector Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 27. AC – Analog Comparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 27.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 27.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 27.3 Input Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 27.4 Signal Compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 27.5 Interrupts and Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 27.6 Window Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 27.7 Input Hysteresis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 27.8 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 27.9 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 27.10 Interrupt vector Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 28. IEEE 1149.1 JTAG Boundary Scan Interface . . . . . . . . . . . . . . . . . . . . . 354 28.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 28.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 28.3 TAP - Test Access Port. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 28.4 JTAG Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 28.5 Boundary Scan Chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 28.6 Data Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 29. Program and Debug Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 29.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 29.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 29.3 PDI Physical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 29.4 JTAG Physical. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 29.5 PDI Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 29.6 Register Description – PDI Instruction and Addressing Registers . . . . . . . . 371 29.7 Register Description – PDI Control and Status Registers. . . . . . . . . . . . . . . 373 29.8 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 XMEGA B [MANUAL] 409 Atmel-8291C-AVR-XMEGA B -09/2014 30. Memory Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 30.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 30.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 30.3 NVM Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 30.4 NVM Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 30.5 NVM Controller Busy Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 30.6 Flash and EEPROM Page Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 30.7 Flash and EEPROM Programming Sequences . . . . . . . . . . . . . . . . . . . . . . 377 30.8 Protection of NVM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 30.9 Preventing NVM Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 30.10 CRC Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 30.11 Self-programming and Boot Loader Support . . . . . . . . . . . . . . . . . . . . . . . . 379 30.12 External Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 30.13 Register Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 30.14 Register Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 31. Peripheral Module Address Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 32. Instruction Set Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 33. Datasheet Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 33.1 8291C – 06/2014. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 33.2 8291B – 01/2013. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 33.3 8291A – 07/2011. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 | www.atmel.com © 2014 Atmel Corporation. All rights reserved. / Rev.: 8291C–AVR–XMEGA B –Manual–09/2014 Atmel®, Atmel logo and combinations thereof, Enabling Unlimited Possibilities®, and others are registered trademarks or trademarks of Atmel Corporation or its subsidiaries. Other terms and product names may be trademarks of others. DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life. SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments unless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specifically designated by Atmel as automotive-grade.

Features • High-performance, Low-power 32-bit Atmel® AVR® Microcontroller – Compact Single-cycle RISC Instruction Set Including DSP Instructions – Read-modify-write Instructions and Atomic Bit Manipulation – Performance • Up to 64DMIPS Running at 50MHz from Flash (1 Flash Wait State) • Up to 36DMIPS Running at 25MHz from Flash (0 Flash Wait State) – Memory Protection Unit (MPU) • Secure Access Unit (SAU) providing User-defined Peripheral Protection • picoPower® Technology for Ultra-low Power Consumption • Multi-hierarchy Bus System – High-performance Data Transfers on Separate Buses for Increased Performance – 12 Peripheral DMA Channels improve Speed for Peripheral Communication • Internal High-speed Flash – 256Kbytes, 128Kbytes, and 64Kbytes Versions – Single-cycle Access up to 25MHz – FlashVault Technology Allows Pre-programmed Secure Library Support for End User Applications – Prefetch Buffer Optimizing Instruction Execution at Maximum Speed – 100,000 Write Cycles, 15-year Data Retention Capability – Flash Security Locks and User-defined Configuration Area • Internal High-speed SRAM, Single-cycle Access at Full Speed – 32Kbytes (256Kbytes and 128Kbytes Flash) and 16Kbytes (64Kbytes Flash) • Interrupt Controller (INTC) – Autovectored Low-latency Interrupt Service with Programmable Priority • External Interrupt Controller (EIC) • Peripheral Event System for Direct Peripheral to Peripheral Communication • System Functions – Power and Clock Manager – SleepWalking Power Saving Control – Internal System RC Oscillator (RCSYS) – 32 KHz Oscillator – Multipurpose Oscillator, Phase Locked Loop (PLL), and Digital Frequency Locked Loop (DFLL) • Windowed Watchdog Timer (WDT) • Asynchronous Timer (AST) with Real-time Clock Capability – Counter or Calendar Mode Supported • Frequency Meter (FREQM) for Accurate Measuring of Clock Frequency • Universal Serial Bus (USBC) – Full Speed and Low Speed USB Device Support – Multi-packet Ping-pong Mode • Six 16-bit Timer/Counter (TC) Channels – External Clock Inputs, PWM, Capture, and Various Counting Capabilities • 36 PWM Channels (PWMA) – 12-bit PWM with a Source Clock up to 150MHz • Four Universal Synchronous/Asynchronous Receiver/Transmitters (USART) – Independent Baudrate Generator, Support for SPI – Support for Hardware Handshaking 32142D–06/2013 32-bit Atmel AVR Microcontroller ATUC256L3U ATUC128L3U ATUC64L3U ATUC256L4U ATUC128L4U ATUC64L4U 2 32142D–06/2013 ATUC64/128/256L3/4U • One Master/Slave Serial Peripheral Interface (SPI) with Chip Select Signals – Up to 15 SPI Slaves can be Addressed • Two Master and Two Slave Two-wire Interfaces (TWI), 400kbit/s I2 C-compatible • One 8-channel Analog-to-digital Converter (ADC) with up to 12 Bits Resolution – Internal Temperature Sensor • Eight Analog Comparators (AC) with Optional Window Detection • Capacitive Touch (CAT) Module – Hardware-assisted Atmel® AVR® QTouch® and Atmel® AVR® QMatrix Touch Acquisition – Supports QTouch and QMatrix Capture from Capacitive Touch Sensors • QTouch Library Support – Capacitive Touch Buttons, Sliders, and Wheels – QTouch and QMatrix Acquisition • Audio Bitstream DAC (ABDACB) Suitable for Stereo Audio • Inter-IC Sound (IISC) Controller – Compliant with Inter-IC Sound (I2 S) Specification • On-chip Non-intrusive Debug System – Nexus Class 2+, Runtime Control, Non-intrusive Data and Program Trace – aWire Single-pin Programming Trace and Debug Interface, Muxed with Reset Pin – NanoTrace Provides Trace Capabilities through JTAG or aWire Interface • 64-pin TQFP/QFN (51 GPIO Pins), 48-pin TQFP/QFN/TLLGA (36 GPIO Pins) • Six High-drive I/O Pins (64-pin Packages), Four High-drive I/O Pins (48-pin Packages) • Single 1.62-3.6V Power Supply 3 32142D–06/2013 ATUC64/128/256L3/4U 1. Description The Atmel® AVR® ATUC64/128/256L3/4U is a complete system-on-chip microcontroller based on the AVR32 UC RISC processor running at frequencies up to 50MHz. AVR32 UC is a highperformance 32-bit RISC microprocessor core, designed for cost-sensitive embedded applications, with particular emphasis on low power consumption, high code density, and high performance. The processor implements a Memory Protection Unit (MPU) and a fast and flexible interrupt controller for supporting modern and real-time operating systems. The Secure Access Unit (SAU) is used together with the MPU to provide the required security and integrity. Higher computation capability is achieved using a rich set of DSP instructions. The ATUC64/128/256L3/4U embeds state-of-the-art picoPower technology for ultra-low power consumption. Combined power control techniques are used to bring active current consumption down to 174µA/MHz, and leakage down to 220nA while still retaining a bank of backup registers. The device allows a wide range of trade-offs between functionality and power consumption, giving the user the ability to reach the lowest possible power consumption with the feature set required for the application. The Peripheral Direct Memory Access (DMA) controller enables data transfers between peripherals and memories without processor involvement. The Peripheral DMA controller drastically reduces processing overhead when transferring continuous and large data streams. The ATUC64/128/256L3/4U incorporates on-chip Flash and SRAM memories for secure and fast access. The FlashVault technology allows secure libraries to be programmed into the device. The secure libraries can be executed while the CPU is in Secure State, but not read by non-secure software in the device. The device can thus be shipped to end customers, who will be able to program their own code into the device to access the secure libraries, but without risk of compromising the proprietary secure code. The External Interrupt Controller (EIC) allows pins to be configured as external interrupts. Each external interrupt has its own interrupt request and can be individually masked. The Peripheral Event System allows peripherals to receive, react to, and send peripheral events without CPU intervention. Asynchronous interrupts allow advanced peripheral operation in low power sleep modes. The Power Manager (PM) improves design flexibility and security. The Power Manager supports SleepWalking functionality, by which a module can be selectively activated based on peripheral events, even in sleep modes where the module clock is stopped. Power monitoring is supported by on-chip Power-on Reset (POR), Brown-out Detector (BOD), and Supply Monitor (SM). The device features several oscillators, such as Phase Locked Loop (PLL), Digital Frequency Locked Loop (DFLL), Oscillator 0 (OSC0), and system RC oscillator (RCSYS). Either of these oscillators can be used as source for the system clock. The DFLL is a programmable internal oscillator from 20 to 150MHz. It can be tuned to a high accuracy if an accurate reference clock is running, e.g. the 32KHz crystal oscillator. The Watchdog Timer (WDT) will reset the device unless it is periodically serviced by the software. This allows the device to recover from a condition that has caused the system to be unstable. The Asynchronous Timer (AST) combined with the 32KHz crystal oscillator supports powerful real-time clock capabilities, with a maximum timeout of up to 136 years. The AST can operate in counter or calendar mode. 4 32142D–06/2013 ATUC64/128/256L3/4U The Frequency Meter (FREQM) allows accurate measuring of a clock frequency by comparing it to a known reference clock. The Full-speed USB 2.0 device interface (USBC) supports several USB classes at the same time, thanks to the rich end-point configuration. The device includes six identical 16-bit Timer/Counter (TC) channels. Each channel can be independently programmed to perform frequency measurement, event counting, interval measurement, pulse generation, delay timing, and pulse width modulation. The Pulse Width Modulation controller (PWMA) provides 12-bit PWM channels which can be synchronized and controlled from a common timer. 36 PWM channels are available, enabling applications that require multiple PWM outputs, such as LCD backlight control. The PWM channels can operate independently, with duty cycles set individually, or in interlinked mode, with multiple channels changed at the same time. The ATUC64/128/256L3/4U also features many communication interfaces, like USART, SPI, and TWI, for communication intensive applications. The USART supports different communication modes, like SPI Mode and LIN Mode. A general purpose 8-channel ADC is provided, as well as eight analog comparators (AC). The ADC can operate in 10-bit mode at full speed or in enhanced mode at reduced speed, offering up to 12-bit resolution. The ADC also provides an internal temperature sensor input channel. The analog comparators can be paired to detect when the sensing voltage is within or outside the defined reference window. The Capacitive Touch (CAT) module senses touch on external capacitive touch sensors, using the QTouch technology. Capacitive touch sensors use no external mechanical components, unlike normal push buttons, and therefore demand less maintenance in the user application. The CAT module allows up to 17 touch sensors, or up to 16 by 8 matrix sensors to be interfaced. All touch sensors can be configured to operate autonomously without software interaction, allowing wakeup from sleep modes when activated. Atmel offers the QTouch library for embedding capacitive touch buttons, sliders, and wheels functionality into AVR microcontrollers. The patented charge-transfer signal acquisition offers robust sensing and includes fully debounced reporting of touch keys as well as Adjacent Key Suppression® (AKS®) technology for unambiguous detection of key events. The easy-to-use QTouch Suite toolchain allows you to explore, develop, and debug your own touch applications. The Audio Bitstream DAC (ABDACB) converts a 16-bit sample value to a digital bitstream with an average value proportional to the sample value. Two channels are supported, making the ABDAC particularly suitable for stereo audio. The Inter-IC Sound Controller (IISC) provides a 5-bit wide, bidirectional, synchronous, digital audio link with external audio devices. The controller is compliant with the Inter-IC Sound (I2S) bus specification. The ATUC64/128/256L3/4U integrates a class 2+ Nexus 2.0 On-chip Debug (OCD) System, with non-intrusive real-time trace and full-speed read/write memory access, in addition to basic runtime control. The NanoTrace interface enables trace feature for aWire- or JTAG-based debuggers. The single-pin aWire interface allows all features available through the JTAG interface to be accessed through the RESET pin, allowing the JTAG pins to be used for GPIO or peripherals. 5 32142D–06/2013 ATUC64/128/256L3/4U 2. Overview 2.1 Block Diagram Figure 2-1. Block Diagram INTERRUPT CONTROLLER ASYNCHRONOUS TIMER PERIPHERAL DMA CONTROLLER HSB-PB BRIDGE B HSB-PB BRIDGE A S MM M S S M EXTERNAL INTERRUPT CONTROLLER HIGH SPEED BUS MATRIX GENERALPURPOSE I/Os GENERAL PURPOSE I/Os PA PB EXTINT[5..1] NMI PA PB SPI DMA MISO, MOSI NPCS[3..0] USART0 USART1 USART2 USART3 DMA RXD TXD CLK RTS, CTS WATCHDOG TIMER SCK JTAG INTERFACE MCKO MDO[5..0] MSEO[1..0] EVTI_N TDO TDI TMS CONFIGURATION REGISTERS BUS 256/128/64 KB S FLASH FLASH CONTROLLER EVTO_N AVR32UC CPU NEXUS CLASS 2+ OCD INSTR INTERFACE DATA INTERFACE MEMORY INTERFACE LOCAL BUS 32/16 KB SRAM MEMORY PROTECTION UNIT LOCAL BUS INTERFACE FREQUENCY METER PWMA[35..0] PWM CONTROLLER TWI MASTER 0 DMA TWI MASTER 1 TWI SLAVE 0 DMA TWI SLAVE 1 8-CHANNEL ADC DMA INTERFACE POWER MANAGER RESET CONTROLLER SLEEP CONTROLLER CLOCK CONTROLLER TCK RESET_N aWire CAPACITIVE TOUCH DMA MODULE AC INTERFACE ACREFN ACAN[3..0] ACBN[3..0] ACBP[3..0] ACAP[3..0] TWCK TWD TWALM TWCK TWD TWALM GLUE LOGIC CONTROLLER IN[7..0] OUT[1..0] USB 2.0 Interface 8EP DMA INTER-IC SOUND CONTROLLER TIMER/COUNTER 0 TIMER/COUNTER 1 A[2..0] B[2..0] AUDIO BITSTREAM DMA DAC DAC0, DAC1 DACN0, DACN1 ISCK IWS ISDI ISDO IMCK CLK SAU S/M S DM DP SYSTEM CONTROL INTERFACE GCLK[9..0] XIN32 XOUT32 OSC32K RCSYS XIN0 XOUT0 OSC0 DFLL RC32K RC120M RC32OUT PLL GCLK_IN[2..0] CSB[16:0] SMP CSA[16:0] SYNC VDIVEN DIS TRIGGER ADP[1..0] AD[8..0] DATAOUT ADVREFP CLK[2..0] 6 32142D–06/2013 ATUC64/128/256L3/4U 2.2 Configuration Summary Table 2-1. Configuration Summary Feature ATUC256L3U ATUC128L3U ATUC64L3U ATUC256L4U ATUC128L4U ATUC64L4U Flash 256KB 128KB 64KB 256KB 128KB 64KB SRAM 32KB 16KB 32KB 16KB GPIO 51 36 High-drive pins 6 4 External Interrupts 6 TWI 2 USART 4 Peripheral DMA Channels 12 Peripheral Event System 1 SPI 1 Asynchronous Timers 1 Timer/Counter Channels 6 PWM channels 36 Frequency Meter 1 Watchdog Timer 1 Power Manager 1 Secure Access Unit 1 Glue Logic Controller 1 Oscillators Digital Frequency Locked Loop 20-150MHz (DFLL) Phase Locked Loop 40-240MHz (PLL) Crystal Oscillator 0.45-16MHz (OSC0) Crystal Oscillator 32KHz (OSC32K) RC Oscillator 120MHz (RC120M) RC Oscillator 115kHz (RCSYS) RC Oscillator 32kHz (RC32K) ADC 8-channel 12-bit Temperature Sensor 1 Analog Comparators 8 Capacitive Touch Module 1 JTAG 1 aWire 1 USB 1 Audio Bitstream DAC 1 0 IIS Controller 1 0 Max Frequency 50MHz Packages TQFP64/QFN64 TQFP48/QFN48/TLLGA48 7 32142D–06/2013 ATUC64/128/256L3/4U 3. Package and Pinout 3.1 Package The device pins are multiplexed with peripheral functions as described in Section . Figure 3-1. ATUC64/128/256L4U TQFP48/QFN48 Pinout GND 1 PA09 2 PA08 3 PA03 4 PB12 5 PB00 6 PB02 7 PB03 8 PA22 9 PA06 10 PA00 11 PA05 12 13 PA02 14 PA01 15 PB13 16 PB14 17 VDDIN 18 VDDCORE 19 GND 20 PB05 21 PB04 22 RESET_N 23 PB10 24 PA21 PA14 36 VDDANA 35 ADVREFP 34 GNDANA 33 PB08 32 PB07 31 PB06 30 PB09 29 PA04 28 PA11 27 PA13 26 PA20 25 PA15 37 PA16 38 PA17 39 PA19 40 PA18 41 VDDIO 42 GND 43 PB11 44 GND 45 PA10 46 PA12 47 VDDIO 48 8 32142D–06/2013 ATUC64/128/256L3/4U Figure 3-2. ATUC64/128/256L4U TLLGA48 Pinout GND 1 PA09 2 PA08 3 PA03 4 PB12 5 PB00 6 PB02 7 PB03 8 PA22 9 PA06 10 PA00 11 PA05 12 PA02 13 14 PA01 15 PB13 16 PB14 17 VDDIN 18 VDDCORE 19 GND 20 PB05 21 PB04 22 RESET_N 23 PB10 24 PA21 PA14 36 VDDANA 35 ADVREFP 34 GNDANA 33 PB08 32 PB07 31 PB06 30 PB09 29 PA04 28 PA11 27 PA13 26 PA20 25 PA15 37 PA16 38 PA17 39 PA19 40 PA18 41 VDDIO 42 GND 43 PB11 44 GND 45 PA10 46 PA12 47 VDDIO 48 9 32142D–06/2013 ATUC64/128/256L3/4U Figure 3-3. ATUC64/128/256L3U TQFP64/QFN64 Pinout GND 1 PA09 2 PA08 3 PB19 4 PB20 5 PA03 6 PB12 7 PB00 8 PB02 9 PB03 10 VDDIO 11 GND 12 PA22 13 PA06 14 PA00 15 PA05 16 17 PA02 18 PA01 19 PA07 20 PB01 21 PB26 22 PB13 23 PB14 24 PB27 PB08 44 PB07 43 PB06 42 PB22 41 PB21 40 PB09 39 PA04 38 VDDIO 37 GND 36 PA11 35 PA13 34 PA20 33 PA15 49 PA16 50 PA17 51 PA19 52 PA18 53 PB23 54 PB24 55 PB11 56 PB15 57 PB16 58 PB17 59 PB18 60 25 VDDIN 26 27 GND 28 PB05 29 PB04 30 31 PB10 32 PA21 PA14 48 VDDANA 47 ADVREFP 46 GNDANA 45 PB25 61 PA10 62 PA12 63 VDDIO 64 VDDCORE RESET_N 10 32142D–06/2013 ATUC64/128/256L3/4U Peripheral Multiplexing on I/O lines 3.1.1 Multiplexed Signals Each GPIO line can be assigned to one of the peripheral functions. The following table describes the peripheral signals multiplexed to the GPIO lines. Table 3-1. GPIO Controller Function Multiplexing 48- pin 64- pin Pin Name G PI O Supply Pad Type GPIO Function ABCDE F GH 11 15 PA00 0 VDDIO Normal I/O USART0- TXD USART1- RTS SPINPCS[2] PWMAPWMA[0] SCIFGCLK[0] CATCSA[2] 14 18 PA01 1 VDDIO Normal I/O USART0- RXD USART1- CTS SPINPCS[3] USART1- CLK PWMAPWMA[1] ACIFBACAP[0] TWIMS0- TWALM CATCSA[1] 13 17 PA02 2 VDDIO Highdrive I/O USART0- RTS ADCIFBTRIGGER USART2- TXD TC0-A0 PWMAPWMA[2] ACIFBACBP[0] USART0- CLK CATCSA[3] 4 6 PA03 3 VDDIO Normal I/O USART0- CTS SPINPCS[1] USART2- TXD TC0-B0 PWMAPWMA[3] ACIFBACBN[3] USART0- CLK CATCSB[3] 28 38 PA04 4 VDDIO Normal I/O SPI-MISO TWIMS0- TWCK USART1- RXD TC0-B1 PWMAPWMA[4] ACIFBACBP[1] CATCSA[7] 12 16 PA05 5 VDDIO Normal I/O (TWI) SPI-MOSI TWIMS1- TWCK USART1- TXD TC0-A1 PWMAPWMA[5] ACIFBACBN[0] TWIMS0- TWD CATCSB[7] 10 14 PA06 6 VDDIO Highdrive I/O, 5V tolerant SPI-SCK USART2- TXD USART1- CLK TC0-B0 PWMAPWMA[6] EICEXTINT[2] SCIFGCLK[1] CATCSB[1] 19 PA07 7 VDDIO Normal I/O (TWI) SPINPCS[0] USART2- RXD TWIMS1- TWALM TWIMS0- TWCK PWMAPWMA[7] ACIFBACAN[0] EICNMI (EXTINT[0]) CATCSB[2] 3 3 PA08 8 VDDIO Highdrive I/O USART1- TXD SPINPCS[2] TC0-A2 ADCIFBADP[0] PWMAPWMA[8] CATCSA[4] 2 2 PA09 9 VDDIO Highdrive I/O USART1- RXD SPINPCS[3] TC0-B2 ADCIFBADP[1] PWMAPWMA[9] SCIFGCLK[2] EICEXTINT[1] CATCSB[4] 46 62 PA10 10 VDDIO Normal I/O TWIMS0- TWD TC0-A0 PWMAPWMA[10] ACIFBACAP[1] SCIFGCLK[2] CATCSA[5] 27 35 PA11 11 VDDIN Normal I/O PWMAPWMA[11] 47 63 PA12 12 VDDIO Normal I/O USART2- CLK TC0-CLK1 CAT-SMP PWMAPWMA[12] ACIFBACAN[1] SCIFGCLK[3] CATCSB[5] 26 34 PA13 13 VDDIN Normal I/O GLOCOUT[0] GLOCIN[7] TC0-A0 SCIFGCLK[2] PWMAPWMA[13] CAT-SMP EICEXTINT[2] CATCSA[0] 36 48 PA14 14 VDDIO Normal I/O ADCIFBAD[0] TC0-CLK2 USART2- RTS CAT-SMP PWMAPWMA[14] SCIFGCLK[4] CATCSA[6] 37 49 PA15 15 VDDIO Normal I/O ADCIFBAD[1] TC0-CLK1 GLOCIN[6] PWMAPWMA[15] CATSYNC EICEXTINT[3] CATCSB[6] 38 50 PA16 16 VDDIO Normal I/O ADCIFBAD[2] TC0-CLK0 GLOCIN[5] PWMAPWMA[16] ACIFBACREFN EICEXTINT[4] CATCSA[8] 11 32142D–06/2013 ATUC64/128/256L3/4U 39 51 PA17 17 VDDIO Normal I/O (TWI) TC0-A1 USART2- CTS TWIMS1- TWD PWMAPWMA[17] CAT-SMP CAT-DIS CATCSB[8] 41 53 PA18 18 VDDIO Normal I/O ADCIFBAD[4] TC0-B1 GLOCIN[4] PWMAPWMA[18] CATSYNC EICEXTINT[5] CATCSB[0] 40 52 PA19 19 VDDIO Normal I/O ADCIFBAD[5] TC0-A2 TWIMS1- TWALM PWMAPWMA[19] SCIFGCLK_IN[ 0] CAT-SYNC CATCSA[10] 25 33 PA20 20 VDDIN Normal I/O USART2- TXD TC0-A1 GLOCIN[3] PWMAPWMA[20] SCIFRC32OUT CATCSA[12] 24 32 PA21 21 VDDIN Normal I/O (TWI, 5V tolerant, SMBus) USART2- RXD TWIMS0- TWD TC0-B1 ADCIFBTRIGGER PWMAPWMA[21] PWMAPWMAOD [21] SCIFGCLK[0] CATSMP 9 13 PA22 22 VDDIO Normal I/O USART0- CTS USART2- CLK TC0-B2 CAT-SMP PWMAPWMA[22] ACIFBACBN[2] CATCSB[10] 6 8 PB00 32 VDDIO Normal I/O USART3- TXD ADCIFBADP[0] SPINPCS[0] TC0-A1 PWMAPWMA[23] ACIFBACAP[2] TC1-A0 CATCSA[9] 20 PB01 33 VDDIO Highdrive I/O USART3- RXD ADCIFBADP[1] SPI-SCK TC0-B1 PWMAPWMA[24] TC1-A1 CATCSB[9] 7 9 PB02 34 VDDIO Normal I/O USART3- RTS USART3- CLK SPI-MISO TC0-A2 PWMAPWMA[25] ACIFBACAN[2] SCIFGCLK[1] CATCSB[11] 8 10 PB03 35 VDDIO Normal I/O USART3- CTS USART3- CLK SPI-MOSI TC0-B2 PWMAPWMA[26] ACIFBACBP[2] TC1-A2 CATCSA[11] 21 29 PB04 36 VDDIN Normal I/O (TWI, 5V tolerant, SMBus) TC1-A0 USART1- RTS USART1- CLK TWIMS0- TWALM PWMAPWMA[27] PWMAPWMAOD [27] TWIMS1- TWCK CATCSA[14] 20 28 PB05 37 VDDIN Normal I/O (TWI, 5V tolerant, SMBus) TC1-B0 USART1- CTS USART1- CLK TWIMS0- TWCK PWMAPWMA[28] PWMAPWMAOD [28] SCIFGCLK[3] CATCSB[14] 30 42 PB06 38 VDDIO Normal I/O TC1-A1 USART3- TXD ADCIFBAD[6] GLOCIN[2] PWMAPWMA[29] ACIFBACAN[3] EICNMI (EXTINT[0]) CATCSB[13] 31 43 PB07 39 VDDIO Normal I/O TC1-B1 USART3- RXD ADCIFBAD[7] GLOCIN[1] PWMAPWMA[30] ACIFBACAP[3] EICEXTINT[1] CATCSA[13] 32 44 PB08 40 VDDIO Normal I/O TC1-A2 USART3- RTS ADCIFBAD[8] GLOCIN[0] PWMAPWMA[31] CATSYNC EICEXTINT[2] CATCSB[12] 29 39 PB09 41 VDDIO Normal I/O TC1-B2 USART3- CTS USART3- CLK PWMAPWMA[32] ACIFBACBN[1] EICEXTINT[3] CATCSB[15] 23 31 PB10 42 VDDIN Normal I/O TC1-CLK0 USART1- TXD USART3- CLK GLOCOUT[1] PWMAPWMA[33] SCIFGCLK_IN[ 1] EICEXTINT[4] CATCSB[16] 44 56 PB11 43 VDDIO Normal I/O TC1-CLK1 USART1- RXD ADCIFBTRIGGER PWMAPWMA[34] CATVDIVEN EICEXTINT[5] CATCSA[16] 5 7 PB12 44 VDDIO Normal I/O TC1-CLK2 TWIMS1- TWALM CATSYNC PWMAPWMA[35] ACIFBACBP[3] SCIFGCLK[4] CATCSA[15] 15 22 PB13 45 VDDIN USB I/O USBC-DM USART3- TXD TC1-A1 PWMAPWMA[7] ADCIFBADP[1] SCIFGCLK[5] CATCSB[2] 16 23 PB14 46 VDDIN USB I/O USBC-DP USART3- RXD TC1-B1 PWMAPWMA[24] SCIFGCLK[5] CATCSB[9] Table 3-1. GPIO Controller Function Multiplexing 12 32142D–06/2013 ATUC64/128/256L3/4U 3.2 See Section 3.3 for a description of the various peripheral signals. Refer to ”Electrical Characteristics” on page 897 for a description of the electrical properties of the pin types used. 3.2.1 TWI, 5V Tolerant, and SMBUS Pins Some normal I/O pins offer TWI, 5V tolerance, and SMBUS features. These features are only available when either of the TWI functions or the PWMAOD function in the PWMA are selected for these pins. Refer to the ”Electrical Characteristics” on page 897 for a description of the electrical properties of the TWI, 5V tolerance, and SMBUS pins. 57 PB15 47 VDDIO Highdrive I/O ABDACBCLK IISCIMCK SPI-SCK TC0-CLK2 PWMAPWMA[8] SCIFGCLK[3] CATCSB[4] 58 PB16 48 VDDIO Normal I/O ABDACBDAC[0] IISC-ISCK USART0- TXD PWMAPWMA[9] SCIFGCLK[2] CATCSA[5] 59 PB17 49 VDDIO Normal I/O ABDACBDAC[1] IISC-IWS USART0- RXD PWMAPWMA[10] CATCSB[5] 60 PB18 50 VDDIO Normal I/O ABDACBDACN[0] IISC-ISDI USART0- RTS PWMAPWMA[12] CATCSA[0] 4 PB19 51 VDDIO Normal I/O ABDACBDACN[1] IISC-ISDO USART0- CTS PWMAPWMA[20] EICEXTINT[1] CATCSA[12] 5 PB20 52 VDDIO Normal I/O TWIMS1- TWD USART2- RXD SPINPCS[1] TC0-A0 PWMAPWMA[21] USART1- RTS USART1- CLK CATCSA[14] 40 PB21 53 VDDIO Normal I/O TWIMS1- TWCK USART2- TXD SPINPCS[2] TC0-B0 PWMAPWMA[28] USART1- CTS USART1- CLK CATCSB[14] 41 PB22 54 VDDIO Normal I/O TWIMS1- TWALM SPINPCS[3] TC0-CLK0 PWMAPWMA[27] ADCIFBTRIGGER SCIFGCLK[0] CATCSA[8] 54 PB23 55 VDDIO Normal I/O SPI-MISO USART2- RTS USART2- CLK TC0-A2 PWMAPWMA[0] CAT-SMP SCIFGCLK[6] CATCSA[4] 55 PB24 56 VDDIO Normal I/O SPI-MOSI USART2- CTS USART2- CLK TC0-B2 PWMAPWMA[1] ADCIFBADP[1] SCIFGCLK[7] CATCSA[2] 61 PB25 57 VDDIO Normal I/O SPINPCS[0] USART1- RXD TC0-A1 PWMAPWMA[2] SCIFGCLK_IN[ 2] SCIFGCLK[8] CATCSA[3] 21 PB26 58 VDDIO Normal I/O SPI-SCK USART1- TXD TC0-B1 PWMAPWMA[3] ADCIFBADP[0] SCIFGCLK[9] CATCSB[3] 24 PB27 59 VDDIN Normal I/O USART1- RXD TC0-CLK1 PWMAPWMA[4] ADCIFBADP[1] EICNMI (EXTINT[0]) CATCSA[9] Table 3-1. GPIO Controller Function Multiplexing 13 32142D–06/2013 ATUC64/128/256L3/4U 3.2.2 Peripheral Functions Each GPIO line can be assigned to one of several peripheral functions. The following table describes how the various peripheral functions are selected. The last listed function has priority in case multiple functions are enabled on the same pin. 3.2.3 JTAG Port Connections If the JTAG is enabled, the JTAG will take control over a number of pins, irrespectively of the I/O Controller configuration. 3.2.4 Nexus OCD AUX Port Connections If the OCD trace system is enabled, the trace system will take control over a number of pins, irrespectively of the I/O Controller configuration. Two different OCD trace pin mappings are possible, depending on the configuration of the OCD AXS register. For details, see the AVR32 UC Technical Reference Manual. Table 3-2. Peripheral Functions Function Description GPIO Controller Function multiplexing GPIO and GPIO peripheral selection A to H Nexus OCD AUX port connections OCD trace system aWire DATAOUT aWire output in two-pin mode JTAG port connections JTAG debug port Oscillators OSC0, OSC32 Table 3-3. JTAG Pinout 48-pin 64-pin Pin name JTAG pin 11 15 PA00 TCK 14 18 PA01 TMS 13 17 PA02 TDO 4 6 PA03 TDI Table 3-4. Nexus OCD AUX Port Connections Pin AXS=1 AXS=0 EVTI_N PA05 PB08 MDO[5] PA10 PB00 MDO[4] PA18 PB04 MDO[3] PA17 PB05 MDO[2] PA16 PB03 MDO[1] PA15 PB02 MDO[0] PA14 PB09 14 32142D–06/2013 ATUC64/128/256L3/4U 3.2.5 Oscillator Pinout The oscillators are not mapped to the normal GPIO functions and their muxings are controlled by registers in the System Control Interface (SCIF). Please refer to the SCIF chapter for more information about this. 3.2.6 Other Functions The functions listed in Table 3-6 are not mapped to the normal GPIO functions. The aWire DATA pin will only be active after the aWire is enabled. The aWire DATAOUT pin will only be active after the aWire is enabled and the 2_PIN_MODE command has been sent. The WAKE_N pin is always enabled. Please refer to Section 6.1.4.2 on page 44 for constraints on the WAKE_N pin. EVTO_N PA04 PA04 MCKO PA06 PB01 MSEO[1] PA07 PB11 MSEO[0] PA11 PB12 Table 3-4. Nexus OCD AUX Port Connections Pin AXS=1 AXS=0 Table 3-5. Oscillator Pinout 48-pin 64-pin Pin Name Oscillator Pin 3 3 PA08 XIN0 46 62 PA10 XIN32 26 34 PA13 XIN32_2 2 2 PA09 XOUT0 47 63 PA12 XOUT32 25 33 PA20 XOUT32_2 Table 3-6. Other Functions 48-pin 64-pin Pin Name Function 27 35 PA11 WAKE_N 22 30 RESET_N aWire DATA 11 15 PA00 aWire DATAOUT 15 32142D–06/2013 ATUC64/128/256L3/4U 3.3 Signal Descriptions The following table gives details on signal name classified by peripheral. Table 3-7. Signal Descriptions List Signal Name Function Type Active Level Comments Audio Bitstream DAC - ABDACB CLK D/A Clock out Output DAC1 - DAC0 D/A Bitstream out Output DACN1 - DACN0 D/A Inverted bitstream out Output Analog Comparator Interface - ACIFB ACAN3 - ACAN0 Negative inputs for comparators "A" Analog ACAP3 - ACAP0 Positive inputs for comparators "A" Analog ACBN3 - ACBN0 Negative inputs for comparators "B" Analog ACBP3 - ACBP0 Positive inputs for comparators "B" Analog ACREFN Common negative reference Analog ADC Interface - ADCIFB AD8 - AD0 Analog Signal Analog ADP1 - ADP0 Drive Pin for resistive touch screen Output TRIGGER External trigger Input aWire - AW DATA aWire data I/O DATAOUT aWire data output for 2-pin mode I/O Capacitive Touch Module - CAT CSA16 - CSA0 Capacitive Sense A I/O CSB16 - CSB0 Capacitive Sense B I/O DIS Discharge current control Analog SMP SMP signal Output SYNC Synchronize signal Input VDIVEN Voltage divider enable Output External Interrupt Controller - EIC NMI (EXTINT0) Non-Maskable Interrupt Input EXTINT5 - EXTINT1 External interrupt Input Glue Logic Controller - GLOC IN7 - IN0 Inputs to lookup tables Input OUT1 - OUT0 Outputs from lookup tables Output Inter-IC Sound (I2S) Controller - IISC 16 32142D–06/2013 ATUC64/128/256L3/4U IMCK I2S Master Clock Output ISCK I2S Serial Clock I/O ISDI I2S Serial Data In Input ISDO I2S Serial Data Out Output IWS I2S Word Select I/O JTAG module - JTAG TCK Test Clock Input TDI Test Data In Input TDO Test Data Out Output TMS Test Mode Select Input Power Manager - PM RESET_N Reset Input Low Pulse Width Modulation Controller - PWMA PWMA35 - PWMA0 PWMA channel waveforms Output PWMAOD35 - PWMAOD0 PWMA channel waveforms, open drain mode Output Not all channels support open drain mode System Control Interface - SCIF GCLK9 - GCLK0 Generic Clock Output Output GCLK_IN2 - GCLK_IN0 Generic Clock Input Input RC32OUT RC32K output at startup Output XIN0 Crystal 0 Input Analog/ Digital XIN32 Crystal 32 Input (primary location) Analog/ Digital XIN32_2 Crystal 32 Input (secondary location) Analog/ Digital XOUT0 Crystal 0 Output Analog XOUT32 Crystal 32 Output (primary location) Analog XOUT32_2 Crystal 32 Output (secondary location) Analog Serial Peripheral Interface - SPI MISO Master In Slave Out I/O MOSI Master Out Slave In I/O NPCS3 - NPCS0 SPI Peripheral Chip Select I/O Low SCK Clock I/O Timer/Counter - TC0, TC1 A0 Channel 0 Line A I/O A1 Channel 1 Line A I/O A2 Channel 2 Line A I/O Table 3-7. Signal Descriptions List 17 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. ADCIFB: AD3 does not exist. B0 Channel 0 Line B I/O B1 Channel 1 Line B I/O B2 Channel 2 Line B I/O CLK0 Channel 0 External Clock Input Input CLK1 Channel 1 External Clock Input Input CLK2 Channel 2 External Clock Input Input Two-wire Interface - TWIMS0, TWIMS1 TWALM SMBus SMBALERT I/O Low TWCK Two-wire Serial Clock I/O TWD Two-wire Serial Data I/O Universal Synchronous Asynchronous Receiver Transmitter - USART0, USART1, USART2, USART3 CLK Clock I/O CTS Clear To Send Input Low RTS Request To Send Output Low RXD Receive Data Input TXD Transmit Data Output Table 3-7. Signal Descriptions List Table 3-8. Signal Description List, Continued Signal Name Function Type Active Level Comments Power VDDCORE Core Power Supply / Voltage Regulator Output Power Input/Output 1.62V to 1.98V VDDIO I/O Power Supply Power Input 1.62V to 3.6V. VDDIO should always be equal to or lower than VDDIN. VDDANA Analog Power Supply Power Input 1.62V to 1.98V ADVREFP Analog Reference Voltage Power Input 1.62V to 1.98V VDDIN Voltage Regulator Input Power Input 1.62V to 3.6V(1) GNDANA Analog Ground Ground GND Ground Ground Auxiliary Port - AUX MCKO Trace Data Output Clock Output MDO5 - MDO0 Trace Data Output Output 18 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. See Section 6. on page 39 3.4 I/O Line Considerations 3.4.1 JTAG Pins The JTAG is enabled if TCK is low while the RESET_N pin is released. The TCK, TMS, and TDI pins have pull-up resistors when JTAG is enabled. The TCK pin always has pull-up enabled during reset. The TDO pin is an output, driven at VDDIO, and has no pull-up resistor. The JTAG pins can be used as GPIO pins and multiplexed with peripherals when the JTAG is disabled. Please refer to Section 3.2.3 on page 13 for the JTAG port connections. 3.4.2 PA00 Note that PA00 is multiplexed with TCK. PA00 GPIO function must only be used as output in the application. 3.4.3 RESET_N Pin The RESET_N pin is a schmitt input and integrates a permanent pull-up resistor to VDDIN. As the product integrates a power-on reset detector, the RESET_N pin can be left unconnected in case no reset from the system needs to be applied to the product. The RESET_N pin is also used for the aWire debug protocol. When the pin is used for debugging, it must not be driven by external circuitry. 3.4.4 TWI Pins PA21/PB04/PB05 When these pins are used for TWI, the pins are open-drain outputs with slew-rate limitation and inputs with spike filtering. When used as GPIO pins or used for other peripherals, the pins have the same characteristics as other GPIO pins. Selected pins are also SMBus compliant (refer to Section on page 10). As required by the SMBus specification, these pins provide no leakage path to ground when the ATUC64/128/256L3/4U is powered down. This allows other devices on the SMBus to continue communicating even though the ATUC64/128/256L3/4U is not powered. After reset a TWI function is selected on these pins instead of the GPIO. Please refer to the GPIO Module Configuration chapter for details. MSEO1 - MSEO0 Trace Frame Control Output EVTI_N Event In Input Low EVTO_N Event Out Output Low General Purpose I/O pin PA22 - PA00 Parallel I/O Controller I/O Port 0 I/O PB27 - PB00 Parallel I/O Controller I/O Port 1 I/O Table 3-8. Signal Description List, Continued Signal Name Function Type Active Level Comments 19 32142D–06/2013 ATUC64/128/256L3/4U 3.4.5 TWI Pins PA05/PA07/PA17 When these pins are used for TWI, the pins are open-drain outputs with slew-rate limitation and inputs with spike filtering. When used as GPIO pins or used for other peripherals, the pins have the same characteristics as other GPIO pins. After reset a TWI function is selected on these pins instead of the GPIO. Please refer to the GPIO Module Configuration chapter for details. 3.4.6 GPIO Pins All the I/O lines integrate a pull-up resistor Programming of this pull-up resistor is performed independently for each I/O line through the GPIO Controllers. After reset, I/O lines default as inputs with pull-up resistors disabled, except PA00 which has the pull-up resistor enabled. PA20 selects SCIF-RC32OUT (GPIO Function F) as default enabled after reset. 3.4.7 High-drive Pins The six pins PA02, PA06, PA08, PA09, PB01, and PB15 have high-drive output capabilities. Refer to Section 35. on page 897 for electrical characteristics. 3.4.8 USB Pins PB13/PB14 When these pins are used for USB, the pins are behaving according to the USB specification. When used as GPIO pins or used for other peripherals, the pins have the same behaviour as other normal I/O pins, but the characteristics are different. Refer to Section 35. on page 897 for electrical characteristics. To be able to use the USB I/O the VDDIN power supply must be 3.3V nominal. 3.4.9 RC32OUT Pin 3.4.9.1 Clock output at startup After power-up, the clock generated by the 32kHz RC oscillator (RC32K) will be output on PA20, even when the device is still reset by the Power-On Reset Circuitry. This clock can be used by the system to start other devices or to clock a switching regulator to rise the power supply voltage up to an acceptable value. The clock will be available on PA20, but will be disabled if one of the following conditions are true: • PA20 is configured to use a GPIO function other than F (SCIF-RC32OUT) • PA20 is configured as a General Purpose Input/Output (GPIO) • The bit FRC32 in the Power Manager PPCR register is written to zero (refer to the Power Manager chapter) The maximum amplitude of the clock signal will be defined by VDDIN. Once the RC32K output on PA20 is disabled it can never be enabled again. 3.4.9.2 XOUT32_2 function PA20 selects RC32OUT as default enabled after reset. This function is not automatically disabled when the user enables the XOUT32_2 function on PA20. This disturbs the oscillator and may result in the wrong frequency. To avoid this, RC32OUT must be disabled when XOUT32_2 is enabled. 20 32142D–06/2013 ATUC64/128/256L3/4U 3.4.10 ADC Input Pins These pins are regular I/O pins powered from the VDDIO. However, when these pins are used for ADC inputs, the voltage applied to the pin must not exceed 1.98V. Internal circuitry ensures that the pin cannot be used as an analog input pin when the I/O drives to VDD. When the pins are not used for ADC inputs, the pins may be driven to the full I/O voltage range. 21 32142D–06/2013 ATUC64/128/256L3/4U 4. Processor and Architecture Rev: 2.1.2.0 This chapter gives an overview of the AVR32UC CPU. AVR32UC is an implementation of the AVR32 architecture. A summary of the programming model, instruction set, and MPU is presented. For further details, see the AVR32 Architecture Manual and the AVR32UC Technical Reference Manual. 4.1 Features • 32-bit load/store AVR32A RISC architecture – 15 general-purpose 32-bit registers – 32-bit Stack Pointer, Program Counter and Link Register reside in register file – Fully orthogonal instruction set – Privileged and unprivileged modes enabling efficient and secure operating systems – Innovative instruction set together with variable instruction length ensuring industry leading code density – DSP extension with saturating arithmetic, and a wide variety of multiply instructions • 3-stage pipeline allowing one instruction per clock cycle for most instructions – Byte, halfword, word, and double word memory access – Multiple interrupt priority levels • MPU allows for operating systems with memory protection • Secure State for supporting FlashVault technology 4.2 AVR32 Architecture AVR32 is a new, high-performance 32-bit RISC microprocessor architecture, designed for costsensitive embedded applications, with particular emphasis on low power consumption and high code density. In addition, the instruction set architecture has been tuned to allow a variety of microarchitectures, enabling the AVR32 to be implemented as low-, mid-, or high-performance processors. AVR32 extends the AVR family into the world of 32- and 64-bit applications. Through a quantitative approach, a large set of industry recognized benchmarks has been compiled and analyzed to achieve the best code density in its class. In addition to lowering the memory requirements, a compact code size also contributes to the core’s low power characteristics. The processor supports byte and halfword data types without penalty in code size and performance. Memory load and store operations are provided for byte, halfword, word, and double word data with automatic sign- or zero extension of halfword and byte data. The C-compiler is closely linked to the architecture and is able to exploit code optimization features, both for size and speed. In order to reduce code size to a minimum, some instructions have multiple addressing modes. As an example, instructions with immediates often have a compact format with a smaller immediate, and an extended format with a larger immediate. In this way, the compiler is able to use the format giving the smallest code size. Another feature of the instruction set is that frequently used instructions, like add, have a compact format with two operands as well as an extended format with three operands. The larger format increases performance, allowing an addition and a data move in the same instruction in a 22 32142D–06/2013 ATUC64/128/256L3/4U single cycle. Load and store instructions have several different formats in order to reduce code size and speed up execution. The register file is organized as sixteen 32-bit registers and includes the Program Counter, the Link Register, and the Stack Pointer. In addition, register R12 is designed to hold return values from function calls and is used implicitly by some instructions. 4.3 The AVR32UC CPU The AVR32UC CPU targets low- and medium-performance applications, and provides an advanced On-Chip Debug (OCD) system, no caches, and a Memory Protection Unit (MPU). Java acceleration hardware is not implemented. AVR32UC provides three memory interfaces, one High Speed Bus master for instruction fetch, one High Speed Bus master for data access, and one High Speed Bus slave interface allowing other bus masters to access data RAMs internal to the CPU. Keeping data RAMs internal to the CPU allows fast access to the RAMs, reduces latency, and guarantees deterministic timing. Also, power consumption is reduced by not needing a full High Speed Bus access for memory accesses. A dedicated data RAM interface is provided for communicating with the internal data RAMs. A local bus interface is provided for connecting the CPU to device-specific high-speed systems, such as floating-point units and I/O controller ports. This local bus has to be enabled by writing a one to the LOCEN bit in the CPUCR system register. The local bus is able to transfer data between the CPU and the local bus slave in a single clock cycle. The local bus has a dedicated memory range allocated to it, and data transfers are performed using regular load and store instructions. Details on which devices that are mapped into the local bus space is given in the CPU Local Bus section in the Memories chapter. Figure 4-1 on page 23 displays the contents of AVR32UC. 23 32142D–06/2013 ATUC64/128/256L3/4U Figure 4-1. Overview of the AVR32UC CPU 4.3.1 Pipeline Overview AVR32UC has three pipeline stages, Instruction Fetch (IF), Instruction Decode (ID), and Instruction Execute (EX). The EX stage is split into three parallel subsections, one arithmetic/logic (ALU) section, one multiply (MUL) section, and one load/store (LS) section. Instructions are issued and complete in order. Certain operations require several clock cycles to complete, and in this case, the instruction resides in the ID and EX stages for the required number of clock cycles. Since there is only three pipeline stages, no internal data forwarding is required, and no data dependencies can arise in the pipeline. Figure 4-2 on page 24 shows an overview of the AVR32UC pipeline stages. AVR32UC CPU pipeline Instruction memory controller MPU High Speed Bus High Speed Bus OCD systemOCD interface Interrupt controller interface High Speed Bus slave High Speed Bus High Speed Bus master Power/ Reset control Reset interface CPU Local Bus master CPU Local Bus Data memory controller CPU RAM High Speed Bus master 24 32142D–06/2013 ATUC64/128/256L3/4U Figure 4-2. The AVR32UC Pipeline 4.3.2 AVR32A Microarchitecture Compliance AVR32UC implements an AVR32A microarchitecture. The AVR32A microarchitecture is targeted at cost-sensitive, lower-end applications like smaller microcontrollers. This microarchitecture does not provide dedicated hardware registers for shadowing of register file registers in interrupt contexts. Additionally, it does not provide hardware registers for the return address registers and return status registers. Instead, all this information is stored on the system stack. This saves chip area at the expense of slower interrupt handling. 4.3.2.1 Interrupt Handling Upon interrupt initiation, registers R8-R12 are automatically pushed to the system stack. These registers are pushed regardless of the priority level of the pending interrupt. The return address and status register are also automatically pushed to stack. The interrupt handler can therefore use R8-R12 freely. Upon interrupt completion, the old R8-R12 registers and status register are restored, and execution continues at the return address stored popped from stack. The stack is also used to store the status register and return address for exceptions and scall. Executing the rete or rets instruction at the completion of an exception or system call will pop this status register and continue execution at the popped return address. 4.3.2.2 Java Support AVR32UC does not provide Java hardware acceleration. 4.3.2.3 Memory Protection The MPU allows the user to check all memory accesses for privilege violations. If an access is attempted to an illegal memory address, the access is aborted and an exception is taken. The MPU in AVR32UC is specified in the AVR32UC Technical Reference manual. 4.3.2.4 Unaligned Reference Handling AVR32UC does not support unaligned accesses, except for doubleword accesses. AVR32UC is able to perform word-aligned st.d and ld.d. Any other unaligned memory access will cause an IF ID ALU MUL Regfile write Prefetch unit Decode unit ALU unit Multiply unit Load-store unit LS Regfile Read 25 32142D–06/2013 ATUC64/128/256L3/4U address exception. Doubleword-sized accesses with word-aligned pointers will automatically be performed as two word-sized accesses. The following table shows the instructions with support for unaligned addresses. All other instructions require aligned addresses. 4.3.2.5 Unimplemented Instructions The following instructions are unimplemented in AVR32UC, and will cause an Unimplemented Instruction Exception if executed: • All SIMD instructions • All coprocessor instructions if no coprocessors are present • retj, incjosp, popjc, pushjc • tlbr, tlbs, tlbw • cache 4.3.2.6 CPU and Architecture Revision Three major revisions of the AVR32UC CPU currently exist. The device described in this datasheet uses CPU revision 3. The Architecture Revision field in the CONFIG0 system register identifies which architecture revision is implemented in a specific device. AVR32UC CPU revision 3 is fully backward-compatible with revisions 1 and 2, ie. code compiled for revision 1 or 2 is binary-compatible with revision 3 CPUs. Table 4-1. Instructions with Unaligned Reference Support Instruction Supported Alignment ld.d Word st.d Word 26 32142D–06/2013 ATUC64/128/256L3/4U 4.4 Programming Model 4.4.1 Register File Configuration The AVR32UC register file is shown below. Figure 4-3. The AVR32UC Register File 4.4.2 Status Register Configuration The Status Register (SR) is split into two halfwords, one upper and one lower, see Figure 4-4 and Figure 4-5. The lower word contains the C, Z, N, V, and Q condition code flags and the R, T, and L bits, while the upper halfword contains information about the mode and state the processor executes in. Refer to the AVR32 Architecture Manual for details. Figure 4-4. The Status Register High Halfword Application Bit 0 Supervisor Bit 31 PC SR INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R3 R1 R2 R0 Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 INT0 SP_APP SP_SYS R12 R11 R9 R10 R8 INT1 INT2 INT3 Exception NMI LR LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Secure Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SEC LR SS_STATUS SS_ADRF SS_ADRR SS_ADR0 SS_ADR1 SS_SP_SYS SS_SP_APP SS_RAR SS_RSR Bit 31 0 0 0 Bit 16 Interrupt Level 0 Mask Interrupt Level 1 Mask Interrupt Level 3 Mask Interrupt Level 2 Mask 0 0 0 0 0 0 1 1 0 0 0 0 1 - DM D - M2 M1 M0 EM I2MFE I0M GM LC 1 SS Initial value I1M Bit name Mode Bit 0 Mode Bit 1 - Mode Bit 2 Reserved Debug State - I3M Reserved Exception Mask Global Interrupt Mask Debug State Mask Secure State 27 32142D–06/2013 ATUC64/128/256L3/4U Figure 4-5. The Status Register Low Halfword 4.4.3 Processor States 4.4.3.1 Normal RISC State The AVR32 processor supports several different execution contexts as shown in Table 4-2. Mode changes can be made under software control, or can be caused by external interrupts or exception processing. A mode can be interrupted by a higher priority mode, but never by one with lower priority. Nested exceptions can be supported with a minimal software overhead. When running an operating system on the AVR32, user processes will typically execute in the application mode. The programs executed in this mode are restricted from executing certain instructions. Furthermore, most system registers together with the upper halfword of the status register cannot be accessed. Protected memory areas are also not available. All other operating modes are privileged and are collectively called System Modes. They have full access to all privileged and unprivileged resources. After a reset, the processor will be in supervisor mode. 4.4.3.2 Debug State The AVR32 can be set in a debug state, which allows implementation of software monitor routines that can read out and alter system information for use during application development. This implies that all system and application registers, including the status registers and program counters, are accessible in debug state. The privileged instructions are also available. All interrupt levels are by default disabled when debug state is entered, but they can individually be switched on by the monitor routine by clearing the respective mask bit in the status register. Bit 15 Bit 0 Reserved Carry Zero Sign 0 0 0 0 0 0 0 0 0 0 0 0 0 0 - T - - - - Bit name 0 0 Initial value - L Q V N Z C Overflow Saturation - - - Lock Reserved Scratch Table 4-2. Overview of Execution Modes, their Priorities and Privilege Levels. Priority Mode Security Description 1 Non Maskable Interrupt Privileged Non Maskable high priority interrupt mode 2 Exception Privileged Execute exceptions 3 Interrupt 3 Privileged General purpose interrupt mode 4 Interrupt 2 Privileged General purpose interrupt mode 5 Interrupt 1 Privileged General purpose interrupt mode 6 Interrupt 0 Privileged General purpose interrupt mode N/A Supervisor Privileged Runs supervisor calls N/A Application Unprivileged Normal program execution mode 28 32142D–06/2013 ATUC64/128/256L3/4U Debug state can be entered as described in the AVR32UC Technical Reference Manual. Debug state is exited by the retd instruction. 4.4.3.3 Secure State The AVR32 can be set in a secure state, that allows a part of the code to execute in a state with higher security levels. The rest of the code can not access resources reserved for this secure code. Secure State is used to implement FlashVault technology. Refer to the AVR32UC Technical Reference Manual for details. 4.4.4 System Registers The system registers are placed outside of the virtual memory space, and are only accessible using the privileged mfsr and mtsr instructions. The table below lists the system registers specified in the AVR32 architecture, some of which are unused in AVR32UC. The programmer is responsible for maintaining correct sequencing of any instructions following a mtsr instruction. For detail on the system registers, refer to the AVR32UC Technical Reference Manual. Table 4-3. System Registers Reg # Address Name Function 0 0 SR Status Register 1 4 EVBA Exception Vector Base Address 2 8 ACBA Application Call Base Address 3 12 CPUCR CPU Control Register 4 16 ECR Exception Cause Register 5 20 RSR_SUP Unused in AVR32UC 6 24 RSR_INT0 Unused in AVR32UC 7 28 RSR_INT1 Unused in AVR32UC 8 32 RSR_INT2 Unused in AVR32UC 9 36 RSR_INT3 Unused in AVR32UC 10 40 RSR_EX Unused in AVR32UC 11 44 RSR_NMI Unused in AVR32UC 12 48 RSR_DBG Return Status Register for Debug mode 13 52 RAR_SUP Unused in AVR32UC 14 56 RAR_INT0 Unused in AVR32UC 15 60 RAR_INT1 Unused in AVR32UC 16 64 RAR_INT2 Unused in AVR32UC 17 68 RAR_INT3 Unused in AVR32UC 18 72 RAR_EX Unused in AVR32UC 19 76 RAR_NMI Unused in AVR32UC 20 80 RAR_DBG Return Address Register for Debug mode 21 84 JECR Unused in AVR32UC 22 88 JOSP Unused in AVR32UC 23 92 JAVA_LV0 Unused in AVR32UC 29 32142D–06/2013 ATUC64/128/256L3/4U 24 96 JAVA_LV1 Unused in AVR32UC 25 100 JAVA_LV2 Unused in AVR32UC 26 104 JAVA_LV3 Unused in AVR32UC 27 108 JAVA_LV4 Unused in AVR32UC 28 112 JAVA_LV5 Unused in AVR32UC 29 116 JAVA_LV6 Unused in AVR32UC 30 120 JAVA_LV7 Unused in AVR32UC 31 124 JTBA Unused in AVR32UC 32 128 JBCR Unused in AVR32UC 33-63 132-252 Reserved Reserved for future use 64 256 CONFIG0 Configuration register 0 65 260 CONFIG1 Configuration register 1 66 264 COUNT Cycle Counter register 67 268 COMPARE Compare register 68 272 TLBEHI Unused in AVR32UC 69 276 TLBELO Unused in AVR32UC 70 280 PTBR Unused in AVR32UC 71 284 TLBEAR Unused in AVR32UC 72 288 MMUCR Unused in AVR32UC 73 292 TLBARLO Unused in AVR32UC 74 296 TLBARHI Unused in AVR32UC 75 300 PCCNT Unused in AVR32UC 76 304 PCNT0 Unused in AVR32UC 77 308 PCNT1 Unused in AVR32UC 78 312 PCCR Unused in AVR32UC 79 316 BEAR Bus Error Address Register 80 320 MPUAR0 MPU Address Register region 0 81 324 MPUAR1 MPU Address Register region 1 82 328 MPUAR2 MPU Address Register region 2 83 332 MPUAR3 MPU Address Register region 3 84 336 MPUAR4 MPU Address Register region 4 85 340 MPUAR5 MPU Address Register region 5 86 344 MPUAR6 MPU Address Register region 6 87 348 MPUAR7 MPU Address Register region 7 88 352 MPUPSR0 MPU Privilege Select Register region 0 89 356 MPUPSR1 MPU Privilege Select Register region 1 Table 4-3. System Registers (Continued) Reg # Address Name Function 30 32142D–06/2013 ATUC64/128/256L3/4U 4.5 Exceptions and Interrupts In the AVR32 architecture, events are used as a common term for exceptions and interrupts. AVR32UC incorporates a powerful event handling scheme. The different event sources, like Illegal Op-code and interrupt requests, have different priority levels, ensuring a well-defined behavior when multiple events are received simultaneously. Additionally, pending events of a higher priority class may preempt handling of ongoing events of a lower priority class. When an event occurs, the execution of the instruction stream is halted, and execution is passed to an event handler at an address specified in Table 4-4 on page 34. Most of the handlers are placed sequentially in the code space starting at the address specified by EVBA, with four bytes between each handler. This gives ample space for a jump instruction to be placed there, jumping to the event routine itself. A few critical handlers have larger spacing between them, allowing the entire event routine to be placed directly at the address specified by the EVBA-relative offset generated by hardware. All interrupt sources have autovectored interrupt service routine (ISR) addresses. This allows the interrupt controller to directly specify the ISR address as an address 90 360 MPUPSR2 MPU Privilege Select Register region 2 91 364 MPUPSR3 MPU Privilege Select Register region 3 92 368 MPUPSR4 MPU Privilege Select Register region 4 93 372 MPUPSR5 MPU Privilege Select Register region 5 94 376 MPUPSR6 MPU Privilege Select Register region 6 95 380 MPUPSR7 MPU Privilege Select Register region 7 96 384 MPUCRA Unused in this version of AVR32UC 97 388 MPUCRB Unused in this version of AVR32UC 98 392 MPUBRA Unused in this version of AVR32UC 99 396 MPUBRB Unused in this version of AVR32UC 100 400 MPUAPRA MPU Access Permission Register A 101 404 MPUAPRB MPU Access Permission Register B 102 408 MPUCR MPU Control Register 103 412 SS_STATUS Secure State Status Register 104 416 SS_ADRF Secure State Address Flash Register 105 420 SS_ADRR Secure State Address RAM Register 106 424 SS_ADR0 Secure State Address 0 Register 107 428 SS_ADR1 Secure State Address 1 Register 108 432 SS_SP_SYS Secure State Stack Pointer System Register 109 436 SS_SP_APP Secure State Stack Pointer Application Register 110 440 SS_RAR Secure State Return Address Register 111 444 SS_RSR Secure State Return Status Register 112-191 448-764 Reserved Reserved for future use 192-255 768-1020 IMPL IMPLEMENTATION DEFINED Table 4-3. System Registers (Continued) Reg # Address Name Function 31 32142D–06/2013 ATUC64/128/256L3/4U relative to EVBA. The autovector offset has 14 address bits, giving an offset of maximum 16384 bytes. The target address of the event handler is calculated as (EVBA | event_handler_offset), not (EVBA + event_handler_offset), so EVBA and exception code segments must be set up appropriately. The same mechanisms are used to service all different types of events, including interrupt requests, yielding a uniform event handling scheme. An interrupt controller does the priority handling of the interrupts and provides the autovector offset to the CPU. 4.5.1 System Stack Issues Event handling in AVR32UC uses the system stack pointed to by the system stack pointer, SP_SYS, for pushing and popping R8-R12, LR, status register, and return address. Since event code may be timing-critical, SP_SYS should point to memory addresses in the IRAM section, since the timing of accesses to this memory section is both fast and deterministic. The user must also make sure that the system stack is large enough so that any event is able to push the required registers to stack. If the system stack is full, and an event occurs, the system will enter an UNDEFINED state. 4.5.2 Exceptions and Interrupt Requests When an event other than scall or debug request is received by the core, the following actions are performed atomically: 1. The pending event will not be accepted if it is masked. The I3M, I2M, I1M, I0M, EM, and GM bits in the Status Register are used to mask different events. Not all events can be masked. A few critical events (NMI, Unrecoverable Exception, TLB Multiple Hit, and Bus Error) can not be masked. When an event is accepted, hardware automatically sets the mask bits corresponding to all sources with equal or lower priority. This inhibits acceptance of other events of the same or lower priority, except for the critical events listed above. Software may choose to clear some or all of these bits after saving the necessary state if other priority schemes are desired. It is the event source’s responsability to ensure that their events are left pending until accepted by the CPU. 2. When a request is accepted, the Status Register and Program Counter of the current context is stored to the system stack. If the event is an INT0, INT1, INT2, or INT3, registers R8-R12 and LR are also automatically stored to stack. Storing the Status Register ensures that the core is returned to the previous execution mode when the current event handling is completed. When exceptions occur, both the EM and GM bits are set, and the application may manually enable nested exceptions if desired by clearing the appropriate bit. Each exception handler has a dedicated handler address, and this address uniquely identifies the exception source. 3. The Mode bits are set to reflect the priority of the accepted event, and the correct register file bank is selected. The address of the event handler, as shown in Table 4-4 on page 34, is loaded into the Program Counter. The execution of the event handler routine then continues from the effective address calculated. The rete instruction signals the end of the event. When encountered, the Return Status Register and Return Address Register are popped from the system stack and restored to the Status Register and Program Counter. If the rete instruction returns from INT0, INT1, INT2, or INT3, registers R8-R12 and LR are also popped from the system stack. The restored Status Register contains information allowing the core to resume operation in the previous execution mode. This concludes the event handling. 32 32142D–06/2013 ATUC64/128/256L3/4U 4.5.3 Supervisor Calls The AVR32 instruction set provides a supervisor mode call instruction. The scall instruction is designed so that privileged routines can be called from any context. This facilitates sharing of code between different execution modes. The scall mechanism is designed so that a minimal execution cycle overhead is experienced when performing supervisor routine calls from timecritical event handlers. The scall instruction behaves differently depending on which mode it is called from. The behaviour is detailed in the instruction set reference. In order to allow the scall routine to return to the correct context, a return from supervisor call instruction, rets, is implemented. In the AVR32UC CPU, scall and rets uses the system stack to store the return address and the status register. 4.5.4 Debug Requests The AVR32 architecture defines a dedicated Debug mode. When a debug request is received by the core, Debug mode is entered. Entry into Debug mode can be masked by the DM bit in the status register. Upon entry into Debug mode, hardware sets the SR.D bit and jumps to the Debug Exception handler. By default, Debug mode executes in the exception context, but with dedicated Return Address Register and Return Status Register. These dedicated registers remove the need for storing this data to the system stack, thereby improving debuggability. The Mode bits in the Status Register can freely be manipulated in Debug mode, to observe registers in all contexts, while retaining full privileges. Debug mode is exited by executing the retd instruction. This returns to the previous context. 4.5.5 Entry Points for Events Several different event handler entry points exist. In AVR32UC, the reset address is 0x80000000. This places the reset address in the boot flash memory area. TLB miss exceptions and scall have a dedicated space relative to EVBA where their event handler can be placed. This speeds up execution by removing the need for a jump instruction placed at the program address jumped to by the event hardware. All other exceptions have a dedicated event routine entry point located relative to EVBA. The handler routine address identifies the exception source directly. AVR32UC uses the ITLB and DTLB protection exceptions to signal a MPU protection violation. ITLB and DTLB miss exceptions are used to signal that an access address did not map to any of the entries in the MPU. TLB multiple hit exception indicates that an access address did map to multiple TLB entries, signalling an error. All interrupt requests have entry points located at an offset relative to EVBA. This autovector offset is specified by an interrupt controller. The programmer must make sure that none of the autovector offsets interfere with the placement of other code. The autovector offset has 14 address bits, giving an offset of maximum 16384 bytes. Special considerations should be made when loading EVBA with a pointer. Due to security considerations, the event handlers should be located in non-writeable flash memory, or optionally in a privileged memory protection region if an MPU is present. If several events occur on the same instruction, they are handled in a prioritized way. The priority ordering is presented in Table 4-4 on page 34. If events occur on several instructions at different locations in the pipeline, the events on the oldest instruction are always handled before any events on any younger instruction, even if the younger instruction has events of higher priority 33 32142D–06/2013 ATUC64/128/256L3/4U than the oldest instruction. An instruction B is younger than an instruction A if it was sent down the pipeline later than A. The addresses and priority of simultaneous events are shown in Table 4-4 on page 34. Some of the exceptions are unused in AVR32UC since it has no MMU, coprocessor interface, or floatingpoint unit. 34 32142D–06/2013 ATUC64/128/256L3/4U Table 4-4. Priority and Handler Addresses for Events Priority Handler Address Name Event source Stored Return Address 1 0x80000000 Reset External input Undefined 2 Provided by OCD system OCD Stop CPU OCD system First non-completed instruction 3 EVBA+0x00 Unrecoverable exception Internal PC of offending instruction 4 EVBA+0x04 TLB multiple hit MPU PC of offending instruction 5 EVBA+0x08 Bus error data fetch Data bus First non-completed instruction 6 EVBA+0x0C Bus error instruction fetch Data bus First non-completed instruction 7 EVBA+0x10 NMI External input First non-completed instruction 8 Autovectored Interrupt 3 request External input First non-completed instruction 9 Autovectored Interrupt 2 request External input First non-completed instruction 10 Autovectored Interrupt 1 request External input First non-completed instruction 11 Autovectored Interrupt 0 request External input First non-completed instruction 12 EVBA+0x14 Instruction Address CPU PC of offending instruction 13 EVBA+0x50 ITLB Miss MPU PC of offending instruction 14 EVBA+0x18 ITLB Protection MPU PC of offending instruction 15 EVBA+0x1C Breakpoint OCD system First non-completed instruction 16 EVBA+0x20 Illegal Opcode Instruction PC of offending instruction 17 EVBA+0x24 Unimplemented instruction Instruction PC of offending instruction 18 EVBA+0x28 Privilege violation Instruction PC of offending instruction 19 EVBA+0x2C Floating-point UNUSED 20 EVBA+0x30 Coprocessor absent Instruction PC of offending instruction 21 EVBA+0x100 Supervisor call Instruction PC(Supervisor Call) +2 22 EVBA+0x34 Data Address (Read) CPU PC of offending instruction 23 EVBA+0x38 Data Address (Write) CPU PC of offending instruction 24 EVBA+0x60 DTLB Miss (Read) MPU PC of offending instruction 25 EVBA+0x70 DTLB Miss (Write) MPU PC of offending instruction 26 EVBA+0x3C DTLB Protection (Read) MPU PC of offending instruction 27 EVBA+0x40 DTLB Protection (Write) MPU PC of offending instruction 28 EVBA+0x44 DTLB Modified UNUSED 35 32142D–06/2013 ATUC64/128/256L3/4U 5. Memories 5.1 Embedded Memories • Internal high-speed flash – 256Kbytes (ATUC256L3U, ATUC256L4U) – 128Kbytes (ATUC128L3U, ATUC128L4U) – 64Kbytes (ATUC64L3U, ATUC64L4U) • 0 wait state access at up to 25MHz in worst case conditions • 1 wait state access at up to 50MHz in worst case conditions • Pipelined flash architecture, allowing burst reads from sequential flash locations, hiding penalty of 1 wait state access • Pipelined flash architecture typically reduces the cycle penalty of 1 wait state operation to only 8% compared to 0 wait state operation • 100 000 write cycles, 15-year data retention capability • Sector lock capabilities, bootloader protection, security bit • 32 fuses, erased during chip erase • User page for data to be preserved during chip erase • Internal high-speed SRAM, single-cycle access at full speed – 32Kbytes (ATUC256L3U, ATUC256L4U, ATUC128L3U, ATUC128L4U) – 16Kbytes (ATUC64L3U, ATUC64L4U) 5.2 Physical Memory Map The system bus is implemented as a bus matrix. All system bus addresses are fixed, and they are never remapped in any way, not even during boot. Note that AVR32 UC CPU uses unsegmented translation, as described in the AVR32 Architecture Manual. The 32-bit physical address space is mapped as follows: Table 5-1. ATUC64/128/256L3/4U Physical Memory Map Memory Start Address Size ATUC256L3U, ATUC256L4U ATUC128L3U, ATUC128L4U ATUC64L3U, ATUC64L4U Embedded SRAM 0x00000000 32Kbytes 32Kbytes 16Kbytes Embedded Flash 0x80000000 256Kbytes 128Kbytes 64Kbytes SAU Channels 0x90000000 256 bytes 256 bytes 256 bytes HSB-PB Bridge B 0xFFFE0000 64Kbytes 64Kbytes 64Kbytes HSB-PB Bridge A 0xFFFF0000 64Kbytes 64Kbytes 64Kbytes Table 5-2. Flash Memory Parameters Device Flash Size (FLASH_PW) Number of Pages (FLASH_P) Page Size (FLASH_W) ATUC256L3U, ATUC256L4U 256Kbytes 512 512 bytes ATUC128L3U, ATUC128L4U 128Kbytes 256 512 bytes ATUC64L3U, ATUC64L4U 64Kbytes 128 512 bytes 36 32142D–06/2013 ATUC64/128/256L3/4U 5.3 Peripheral Address Map Table 5-3. Peripheral Address Mapping Address Peripheral Name 0xFFFE0000 FLASHCDW Flash Controller - FLASHCDW 0xFFFE0400 HMATRIX HSB Matrix - HMATRIX 0xFFFE0800 SAU Secure Access Unit - SAU 0xFFFE1000 USBC USB 2.0 Interface - USBC 0xFFFF0000 PDCA Peripheral DMA Controller - PDCA 0xFFFF1000 INTC Interrupt controller - INTC 0xFFFF1400 PM Power Manager - PM 0xFFFF1800 SCIF System Control Interface - SCIF 0xFFFF1C00 AST Asynchronous Timer - AST 0xFFFF2000 WDT Watchdog Timer - WDT 0xFFFF2400 EIC External Interrupt Controller - EIC 0xFFFF2800 FREQM Frequency Meter - FREQM 0xFFFF2C00 GPIO General-Purpose Input/Output Controller - GPIO 0xFFFF3000 USART0 Universal Synchronous Asynchronous Receiver Transmitter - USART0 0xFFFF3400 USART1 Universal Synchronous Asynchronous Receiver Transmitter - USART1 0xFFFF3800 USART2 Universal Synchronous Asynchronous Receiver Transmitter - USART2 0xFFFF3C00 USART3 Universal Synchronous Asynchronous Receiver Transmitter - USART3 0xFFFF4000 SPI Serial Peripheral Interface - SPI 37 32142D–06/2013 ATUC64/128/256L3/4U 5.4 CPU Local Bus Mapping Some of the registers in the GPIO module are mapped onto the CPU local bus, in addition to being mapped on the Peripheral Bus. These registers can therefore be reached both by accesses on the Peripheral Bus, and by accesses on the local bus. Mapping these registers on the local bus allows cycle-deterministic toggling of GPIO pins since the CPU and GPIO are the only modules connected to this bus. Also, since the local bus runs at CPU speed, one write or read operation can be performed per clock cycle to the local busmapped GPIO registers. 0xFFFF4400 TWIM0 Two-wire Master Interface - TWIM0 0xFFFF4800 TWIM1 Two-wire Master Interface - TWIM1 0xFFFF4C00 TWIS0 Two-wire Slave Interface - TWIS0 0xFFFF5000 TWIS1 Two-wire Slave Interface - TWIS1 0xFFFF5400 PWMA Pulse Width Modulation Controller - PWMA 0xFFFF5800 TC0 Timer/Counter - TC0 0xFFFF5C00 TC1 Timer/Counter - TC1 0xFFFF6000 ADCIFB ADC Interface - ADCIFB 0xFFFF6400 ACIFB Analog Comparator Interface - ACIFB 0xFFFF6800 CAT Capacitive Touch Module - CAT 0xFFFF6C00 GLOC Glue Logic Controller - GLOC 0xFFFF7000 AW aWire - AW 0xFFFF7400 ABDACB Audio Bitstream DAC - ABDACB 0xFFFF7800 IISC Inter-IC Sound (I2S) Controller - IISC Table 5-3. Peripheral Address Mapping 38 32142D–06/2013 ATUC64/128/256L3/4U The following GPIO registers are mapped on the local bus: Table 5-4. Local Bus Mapped GPIO Registers Port Register Mode Local Bus Address Access 0 Output Driver Enable Register (ODER) WRITE 0x40000040 Write-only SET 0x40000044 Write-only CLEAR 0x40000048 Write-only TOGGLE 0x4000004C Write-only Output Value Register (OVR) WRITE 0x40000050 Write-only SET 0x40000054 Write-only CLEAR 0x40000058 Write-only TOGGLE 0x4000005C Write-only Pin Value Register (PVR) - 0x40000060 Read-only 1 Output Driver Enable Register (ODER) WRITE 0x40000140 Write-only SET 0x40000144 Write-only CLEAR 0x40000148 Write-only TOGGLE 0x4000014C Write-only Output Value Register (OVR) WRITE 0x40000150 Write-only SET 0x40000154 Write-only CLEAR 0x40000158 Write-only TOGGLE 0x4000015C Write-only Pin Value Register (PVR) - 0x40000160 Read-only 39 32142D–06/2013 ATUC64/128/256L3/4U 6. Supply and Startup Considerations 6.1 Supply Considerations 6.1.1 Power Supplies The ATUC64/128/256L3/4U has several types of power supply pins: • VDDIO: Powers I/O lines. Voltage is 1.8 to 3.3V nominal. • VDDIN: Powers I/O lines, the USB pins, and the internal regulator. Voltage is 1.8 to 3.3V nominal if USB is not used, and 3.3V nominal when USB is used. • VDDANA: Powers the ADC. Voltage is 1.8V nominal. • VDDCORE: Powers the core, memories, and peripherals. Voltage is 1.8V nominal. The ground pins GND are common to VDDCORE, VDDIO, and VDDIN. The ground pin for VDDANA is GNDANA. When VDDCORE is not connected to VDDIN, the VDDIN voltage must be higher than 1.98V. Refer to Section 35. on page 897 for power consumption on the various supply pins. For decoupling recommendations for the different power supplies, please refer to the schematic checklist. Refer to Section on page 10 for power supply connections for I/O pins. 6.1.2 Voltage Regulator The ATUC64/128/256L3/4U embeds a voltage regulator that converts from 3.3V nominal to 1.8V with a load of up to 60 mA. The regulator supplies the output voltage on VDDCORE. The regulator may only be used to drive internal circuitry in the device. VDDCORE should be externally connected to the 1.8V domains. See Section 6.1.3 for regulator connection figures. Adequate output supply decoupling is mandatory for VDDCORE to reduce ripple and avoid oscillations. The best way to achieve this is to use two capacitors in parallel between VDDCORE and GND as close to the device as possible. Please refer to Section 35.8 on page 911 for decoupling capacitors values and regulator characteristics. Figure 6-1. Supply Decoupling. The voltage regulator can be turned off in the shutdown mode to power down the core logic and keep a small part of the system powered in order to reduce power consumption. To enter this mode the 3.3V supply mode, with 1.8V regulated I/O lines power supply configuration must be used. 3.3V 1.8V VDDIN VDDCORE 1.8V Regulator CIN1 COUT1 COUT2 C IN3 IN2 C 40 32142D–06/2013 ATUC64/128/256L3/4U 6.1.3 Regulator Connection The ATUC64/128/256L3/4U supports three power supply configurations: • 3.3V single supply mode – Shutdown mode is not available • 1.8V single supply mode – Shutdown mode is not available • 3.3V supply mode, with 1.8V regulated I/O lines – Shutdown mode is available 41 32142D–06/2013 ATUC64/128/256L3/4U 6.1.3.1 3.3V Single Supply Mode In 3.3V single supply mode the internal regulator is connected to the 3.3V source (VDDIN pin) and its output feeds VDDCORE. Figure 6-2 shows the power schematics to be used for 3.3V single supply mode. All I/O lines will be powered by the same power (VDDIN=VDDIO). Figure 6-2. 3.3V Single Supply Mode VDDIO VDDCORE + - 1.98-3.6V VDDANA ADC VDDIN GND GNDANA CPU, Peripherals, Memories, SCIF, BOD, RCSYS, DFLL, PLL OSC32K, RC32K, POR33, SM33 I/O Pins I/O Pins OSC32K_2, AST, Wake, Regulator control Linear regulator 42 32142D–06/2013 ATUC64/128/256L3/4U 6.1.3.2 1.8V Single Supply Mode In 1.8V single supply mode the internal regulator is not used, and VDDIO and VDDCORE are powered by a single 1.8V supply as shown in Figure 6-3. All I/O lines will be powered by the same power (VDDIN = VDDIO = VDDCORE). Figure 6-3. 1.8V Single Supply Mode VDDIO VDDCORE + - 1.62-1.98V VDDANA ADC VDDIN GND GNDANA CPU, Peripherals, Memories, SCIF, BOD, RCSYS, DFLL, PLL OSC32K, RC32K, POR33, SM33 I/O Pins I/O Pins OSC32K_2, AST, Wake, Regulator control 43 32142D–06/2013 ATUC64/128/256L3/4U 6.1.3.3 3.3V Supply Mode with 1.8V Regulated I/O Lines In this mode, the internal regulator is connected to the 3.3V source and its output is connected to both VDDCORE and VDDIO as shown in Figure 6-4. This configuration is required in order to use Shutdown mode. Figure 6-4. 3.3V Supply Mode with 1.8V Regulated I/O Lines In this mode, some I/O lines are powered by VDDIN while other I/O lines are powered by VDDIO. Refer to Section on page 10 for description of power supply for each I/O line. Refer to the Power Manager chapter for a description of what parts of the system are powered in Shutdown mode. Important note: As the regulator has a maximum output current of 60 mA, this mode can only be used in applications where the maximum I/O current is known and compatible with the core and peripheral power consumption. Typically, great care must be used to ensure that only a few I/O lines are toggling at the same time and drive very small loads. VDDIO VDDCORE + - 1.98-3.6V VDDANA ADC VDDIN GND GNDANA CPU, Peripherals, Memories, SCIF, BOD, RCSYS, DFLL, PLL OSC32K, RC32K, POR33, SM33 I/O Pins I/O Pins OSC32K_2, AST, Wake, Regulator control Linear regulator 44 32142D–06/2013 ATUC64/128/256L3/4U 6.1.4 Power-up Sequence 6.1.4.1 Maximum Rise Rate To avoid risk of latch-up, the rise rate of the power supplies must not exceed the values described in Table 35-3 on page 898. Recommended order for power supplies is also described in this chapter. 6.1.4.2 Minimum Rise Rate The integrated Power-on Reset (POR33) circuitry monitoring the VDDIN powering supply requires a minimum rise rate for the VDDIN power supply. See Table 35-3 on page 898 for the minimum rise rate value. If the application can not ensure that the minimum rise rate condition for the VDDIN power supply is met, one of the following configurations can be used: • A logic “0” value is applied during power-up on pin PA11 (WAKE_N) until VDDIN rises above 1.2V. • A logic “0” value is applied during power-up on pin RESET_N until VDDIN rises above 1.2V. 6.2 Startup Considerations This chapter summarizes the boot sequence of the ATUC64/128/256L3/4U. The behavior after power-up is controlled by the Power Manager. For specific details, refer to the Power Manager chapter. 6.2.1 Starting of Clocks After power-up, the device will be held in a reset state by the Power-on Reset (POR18 and POR33) circuitry for a short time to allow the power to stabilize throughout the device. After reset, the device will use the System RC Oscillator (RCSYS) as clock source. Please refer to Table 35-17 on page 910 for the frequency for this oscillator. On system start-up, all high-speed clocks are disabled. All clocks to all modules are running. No clocks have a divided frequency; all parts of the system receive a clock with the same frequency as the System RC Oscillator. When powering up the device, there may be a delay before the voltage has stabilized, depending on the rise time of the supply used. The CPU can start executing code as soon as the supply is above the POR18 and POR33 thresholds, and before the supply is stable. Before switching to a high-speed clock source, the user should use the BOD to make sure the VDDCORE is above the minimum level (1.62V). 6.2.2 Fetching of Initial Instructions After reset has been released, the AVR32 UC CPU starts fetching instructions from the reset address, which is 0x80000000. This address points to the first address in the internal Flash. The code read from the internal flash is free to configure the clock system and clock sources. Please refer to the PM and SCIF chapters for more details. 45 32142D–06/2013 ATUC64/128/256L3/4U 7. Peripheral DMA Controller (PDCA) Rev: 1.2.3.1 7.1 Features • Multiple channels • Generates transfers between memories and peripherals such as USART and SPI • Two address pointers/counters per channel allowing double buffering • Performance monitors to measure average and maximum transfer latency • Optional synchronizing of data transfers with extenal peripheral events • Ring buffer functionality 7.2 Overview The Peripheral DMA Controller (PDCA) transfers data between on-chip peripheral modules such as USART, SPI and memories (those memories may be on- and off-chip memories). Using the PDCA avoids CPU intervention for data transfers, improving the performance of the microcontroller. The PDCA can transfer data from memory to a peripheral or from a peripheral to memory. The PDCA consists of multiple DMA channels. Each channel has: • A Peripheral Select Register • A 32-bit memory pointer • A 16-bit transfer counter • A 32-bit memory pointer reload value • A 16-bit transfer counter reload value The PDCA communicates with the peripheral modules over a set of handshake interfaces. The peripheral signals the PDCA when it is ready to receive or transmit data. The PDCA acknowledges the request when the transmission has started. When a transmit buffer is empty or a receive buffer is full, an optional interrupt request can be generated. 46 32142D–06/2013 ATUC64/128/256L3/4U 7.3 Block Diagram Figure 7-1. PDCA Block Diagram 7.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 7.4.1 Power Management If the CPU enters a sleep mode that disables the PDCA clocks, the PDCA will stop functioning and resume operation after the system wakes up from sleep mode. 7.4.2 Clocks The PDCA has two bus clocks connected: One High Speed Bus clock (CLK_PDCA_HSB) and one Peripheral Bus clock (CLK_PDCA_PB). These clocks are generated by the Power Manager. Both clocks are enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the PDCA before disabling the clocks, to avoid freezing the PDCA in an undefined state. 7.4.3 Interrupts The PDCA interrupt request lines are connected to the interrupt controller. Using the PDCA interrupts requires the interrupt controller to be programmed first. HSB to PB Bridge Peripheral DMA Controller (PDCA) Peripheral 0 High Speed Bus Matrix Handshake Interfaces Peripheral Bus IRQ HSB HSB Interrupt Controller Peripheral 1 Peripheral 2 Peripheral (n-1) ... Memory HSB 47 32142D–06/2013 ATUC64/128/256L3/4U 7.4.4 Peripheral Events The PDCA peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 7.5 Functional Description 7.5.1 Basic Operation The PDCA consists of multiple independent PDCA channels, each capable of handling DMA requests in parallel. Each PDCA channels contains a set of configuration registers which must be configured to start a DMA transfer. In this section the steps necessary to configure one PDCA channel is outlined. The peripheral to transfer data to or from must be configured correctly in the Peripheral Select Register (PSR). This is performed by writing the Peripheral Identity (PID) value for the corresponding peripheral to the PID field in the PSR register. The PID also encodes the transfer direction, i.e. memory to peripheral or peripheral to memory. See Section 7.5.6. The transfer size must be written to the Transfer Size field in the Mode Register (MR.SIZE). The size must match the data size produced or consumed by the selected peripheral. See Section 7.5.7. The memory address to transfer to or from, depending on the PSR, must be written to the Memory Address Register (MAR). For each transfer the memory address is increased by either a one, two or four, depending on the size set in MR. See Section 7.5.2. The number of data items to transfer is written to the TCR register. If the PDCA channel is enabled, a transfer will start immediately after writing a non-zero value to TCR or the reload version of TCR, TCRR. After each transfer the TCR value is decreased by one. Both MAR and TCR can be read while the PDCA channel is active to monitor the DMA progress. See Section 7.5.3. The channel must be enabled for a transfer to start. A channel is enable by writing a one to the EN bit in the Control Register (CR). 7.5.2 Memory Pointer Each channel has a 32-bit Memory Address Register (MAR). This register holds the memory address for the next transfer to be performed. The register is automatically updated after each transfer. The address will be increased by either one, two or four depending on the size of the DMA transfer (byte, halfword or word). The MAR can be read at any time during transfer. 7.5.3 Transfer Counter Each channel has a 16-bit Transfer Counter Register (TCR). This register must be written with the number of transfers to be performed. The TCR register should contain the number of data items to be transferred independently of the transfer size. The TCR can be read at any time during transfer to see the number of remaining transfers. 7.5.4 Reload Registers Both the MAR and the TCR have a reload register, respectively Memory Address Reload Register (MARR) and Transfer Counter Reload Register (TCRR). These registers provide the possibility for the PDCA to work on two memory buffers for each channel. When one buffer has completed, MAR and TCR will be reloaded with the values in MARR and TCRR. The reload logic is always enabled and will trigger if the TCR reaches zero while TCRR holds a non-zero value. After reload, the MARR and TCRR registers are cleared. 48 32142D–06/2013 ATUC64/128/256L3/4U If TCR is zero when writing to TCRR, the TCR and MAR are automatically updated with the value written in TCRR and MARR. 7.5.5 Ring Buffer When Ring Buffer mode is enabled the TCRR and MARR registers will not be cleared when TCR and MAR registers reload. This allows the PDCA to read or write to the same memory region over and over again until the transfer is actively stopped by the user. Ring Buffer mode is enabled by writing a one to the Ring Buffer bit in the Mode Register (MR.RING). 7.5.6 Peripheral Selection The Peripheral Select Register (PSR) decides which peripheral should be connected to the PDCA channel. A peripheral is selected by writing the corresponding Peripheral Identity (PID) to the PID field in the PSR register. Writing the PID will both select the direction of the transfer (memory to peripheral or peripheral to memory), which handshake interface to use, and the address of the peripheral holding register. Refer to the Peripheral Identity (PID) table in the Module Configuration section for the peripheral PID values. 7.5.7 Transfer Size The transfer size can be set individually for each channel to be either byte, halfword or word (8- bit, 16-bit or 32-bit respectively). Transfer size is set by writing the desired value to the Transfer Size field in the Mode Register (MR.SIZE). When the PDCA moves data between peripherals and memory, data is automatically sized and aligned. When memory is accessed, the size specified in MR.SIZE and system alignment is used. When a peripheral register is accessed the data to be transferred is converted to a word where bit n in the data corresponds to bit n in the peripheral register. If the transfer size is byte or halfword, bits greater than 8 and16 respectively are set to zero. Refer to the Module Configuration section for information regarding what peripheral registers are used for the different peripherals and then to the peripheral specific chapter for information about the size option available for the different registers. 7.5.8 Enabling and Disabling Each DMA channel is enabled by writing a one to the Transfer Enable bit in the Control Register (CR.TEN) and disabled by writing a one to the Transfer Disable bit (CR.TDIS). The current status can be read from the Status Register (SR). While the PDCA channel is enabled all DMA request will be handled as long the TCR and TCRR is not zero. 7.5.9 Interrupts Interrupts can be enabled by writing a one to the corresponding bit in the Interrupt Enable Register (IER) and disabled by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The Interrupt Mask Register (IMR) can be read to see whether an interrupt is enabled or not. The current status of an interrupt source can be read through the Interrupt Status Register (ISR). The PDCA has three interrupt sources: • Reload Counter Zero - The TCRR register is zero. • Transfer Finished - Both the TCR and TCRR registers are zero. • Transfer Error - An error has occurred in accessing memory. 49 32142D–06/2013 ATUC64/128/256L3/4U 7.5.10 Priority If more than one PDCA channel is requesting transfer at a given time, the PDCA channels are prioritized by their channel number. Channels with lower numbers have priority over channels with higher numbers, giving channel zero the highest priority. 7.5.11 Error Handling If the Memory Address Register (MAR) is set to point to an invalid location in memory, an error will occur when the PDCA tries to perform a transfer. When an error occurs, the Transfer Error bit in the Interrupt Status Register (ISR.TERR) will be set and the DMA channel that caused the error will be stopped. In order to restart the channel, the user must program the Memory Address Register to a valid address and then write a one to the Error Clear bit in the Control Register (CR.ECLR). If the Transfer Error interrupt is enabled, an interrupt request will be generated when a transfer error occurs. 7.5.12 Peripheral Event Trigger Peripheral events can be used to trigger PDCA channel transfers. Peripheral Event synchronizations are enabled by writing a one to the Event Trigger bit in the Mode Register (MR.ETRIG). When set, all DMA requests will be blocked until a peripheral event is received. For each peripheral event received, only one data item is transferred. If no DMA requests are pending when a peripheral event is received, the PDCA will start a transfer as soon as a peripheral event is detected. If multiple events are received while the PDCA channel is busy transferring data, an overflow condition will be signaled in the Peripheral Event System. Refer to the Peripheral Event System chapter for more information. 7.6 Performance Monitors Up to two performance monitors allow the user to measure the activity and stall cycles for PDCA transfers. To monitor a PDCA channel, the corresponding channel number must be written to one of the MON0/1CH fields in the Performance Control Register (PCONTROL) and a one must be written to the corresponding CH0/1EN bit in the same register. Due to performance monitor hardware resource sharing, the two monitor channels should NOT be programmed to monitor the same PDCA channel. This may result in UNDEFINED performance monitor behavior. 7.6.1 Measuring mechanisms Three different parameters can be measured by each channel: • The number of data transfer cycles since last channel reset, both for read and write • The number of stall cycles since last channel reset, both for read and write • The maximum latency since last channel reset, both for read and write These measurements can be extracted by software and used to generate indicators for bus latency, bus load, and maximum bus latency. Each of the counters has a fixed width, and may therefore overflow. When an overflow is encountered in either the Performance Channel Data Read/Write Cycle registers (PRDATA0/1 and PWDATA0/1) or the Performance Channel Read/Write Stall Cycles registers (PRSTALL0/1 and PWSTALL0/1) of a channel, all registers in the channel are reset. This behavior is altered if the Channel Overflow Freeze bit is one in the Performance Control register (PCONTROL.CH0/1OVF). If this bit is one, the channel registers are frozen when either DATA or STALL reaches its maximum value. This simplifies one-shot readout of the counter values. 50 32142D–06/2013 ATUC64/128/256L3/4U The registers can also be manually reset by writing a one to the Channel Reset bit in the PCONTROL register (PCONTROL.CH0/1RES). The Performance Channel Read/Write Latency registers (PRLAT0/1 and PWLAT0/1) are saturating when their maximum count value is reached. The PRLAT0/1 and PWLAT0/1 registers can only be reset by writing a one to the corresponding reset bit in PCONTROL (PCONTROL.CH0/1RES). A counter is enabled by writing a one to the Channel Enable bit in the Performance Control Register (PCONTROL.CH0/1EN). 51 32142D–06/2013 ATUC64/128/256L3/4U 7.7 User Interface 7.7.1 Memory Map Overview The channels are mapped as shown in Table 7-1. Each channel has a set of configuration registers, shown in Table 7-2, where n is the channel number. 7.7.2 Channel Memory Map Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 7-1. PDCA Register Memory Map Address Range Contents 0x000 - 0x03F DMA channel 0 configuration registers 0x040 - 0x07F DMA channel 1 configuration registers ... ... (0x000 - 0x03F)+m*0x040 DMA channel m configuration registers 0x800-0x830 Performance Monitor registers 0x834 Version register Table 7-2. PDCA Channel Configuration Registers Offset Register Register Name Access Reset 0x000 + n*0x040 Memory Address Register MAR Read/Write 0x00000000 0x004 + n*0x040 Peripheral Select Register PSR Read/Write - (1) 0x008 + n*0x040 Transfer Counter Register TCR Read/Write 0x00000000 0x00C + n*0x040 Memory Address Reload Register MARR Read/Write 0x00000000 0x010 + n*0x040 Transfer Counter Reload Register TCRR Read/Write 0x00000000 0x014 + n*0x040 Control Register CR Write-only 0x00000000 0x018 + n*0x040 Mode Register MR Read/Write 0x00000000 0x01C + n*0x040 Status Register SR Read-only 0x00000000 0x020 + n*0x040 Interrupt Enable Register IER Write-only 0x00000000 0x024 + n*0x040 Interrupt Disable Register IDR Write-only 0x00000000 0x028 + n*0x040 Interrupt Mask Register IMR Read-only 0x00000000 0x02C + n*0x040 Interrupt Status Register ISR Read-only 0x00000000 52 32142D–06/2013 ATUC64/128/256L3/4U 7.7.3 Performance Monitor Memory Map Note: 1. The number of performance monitors is device specific. If the device has only one performance monitor, the Channel1 registers are not available. Please refer to the Module Configuration section at the end of this chapter for the number of performance monitors on this device. 7.7.4 Version Register Memory Map Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 7-3. PDCA Performance Monitor Registers(1) Offset Register Register Name Access Reset 0x800 Performance Control Register PCONTROL Read/Write 0x00000000 0x804 Channel0 Read Data Cycles PRDATA0 Read-only 0x00000000 0x808 Channel0 Read Stall Cycles PRSTALL0 Read-only 0x00000000 0x80C Channel0 Read Max Latency PRLAT0 Read-only 0x00000000 0x810 Channel0 Write Data Cycles PWDATA0 Read-only 0x00000000 0x814 Channel0 Write Stall Cycles PWSTALL0 Read-only 0x00000000 0x818 Channel0 Write Max Latency PWLAT0 Read-only 0x00000000 0x81C Channel1 Read Data Cycles PRDATA1 Read-only 0x00000000 0x820 Channel1 Read Stall Cycles PRSTALL1 Read-only 0x00000000 0x824 Channel1 Read Max Latency PRLAT1 Read-only 0x00000000 0x828 Channel1 Write Data Cycles PWDATA1 Read-only 0x00000000 0x82C Channel1 Write Stall Cycles PWSTALL1 Read-only 0x00000000 0x830 Channel1 Write Max Latency PWLAT1 Read-only 0x00000000 Table 7-4. PDCA Version Register Memory Map Offset Register Register Name Access Reset 0x834 Version Register VERSION Read-only - (1) 53 32142D–06/2013 ATUC64/128/256L3/4U 7.7.5 Memory Address Register Name: MAR Access Type: Read/Write Offset: 0x000 + n*0x040 Reset Value: 0x00000000 • MADDR: Memory Address Address of memory buffer. MADDR should be programmed to point to the start of the memory buffer when configuring the PDCA. During transfer, MADDR will point to the next memory location to be read/written. 31 30 29 28 27 26 25 24 MADDR[31:24] 23 22 21 20 19 18 17 16 MADDR[23:16] 15 14 13 12 11 10 9 8 MADDR[15:8] 76543210 MADDR[7:0] 54 32142D–06/2013 ATUC64/128/256L3/4U 7.7.6 Peripheral Select Register Name: PSR Access Type: Read/Write Offset: 0x004 + n*0x040 Reset Value: - • PID: Peripheral Identifier The Peripheral Identifier selects which peripheral should be connected to the DMA channel. Writing a PID will select both which handshake interface to use, the direction of the transfer and also the address of the Receive/Transfer Holding Register for the peripheral. See the Module Configuration section of PDCA for details. The width of the PID field is device specific and dependent on the number of peripheral modules in the device. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 PID 55 32142D–06/2013 ATUC64/128/256L3/4U 7.7.7 Transfer Counter Register Name: TCR Access Type: Read/Write Offset: 0x008 + n*0x040 Reset Value: 0x00000000 • TCV: Transfer Counter Value Number of data items to be transferred by the PDCA. TCV must be programmed with the total number of transfers to be made. During transfer, TCV contains the number of remaining transfers to be done. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 TCV[15:8] 76543210 TCV[7:0] 56 32142D–06/2013 ATUC64/128/256L3/4U 7.7.8 Memory Address Reload Register Name: MARR Access Type: Read/Write Offset: 0x00C + n*0x040 Reset Value: 0x00000000 • MARV: Memory Address Reload Value Reload Value for the MAR register. This value will be loaded into MAR when TCR reaches zero if the TCRR register has a nonzero value. 31 30 29 28 27 26 25 24 MARV[31:24] 23 22 21 20 19 18 17 16 MARV[23:16] 15 14 13 12 11 10 9 8 MARV[15:8] 76543210 MARV[7:0] 57 32142D–06/2013 ATUC64/128/256L3/4U 7.7.9 Transfer Counter Reload Register Name: TCRR Access Type: Read/Write Offset: 0x010 + n*0x040 Reset Value: 0x00000000 • TCRV: Transfer Counter Reload Value Reload value for the TCR register. When TCR reaches zero, it will be reloaded with TCRV if TCRV has a positive value. If TCRV is zero, no more transfers will be performed for the channel. When TCR is reloaded, the TCRR register is cleared. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 TCRV[15:8] 76543210 TCRV[7:0] 58 32142D–06/2013 ATUC64/128/256L3/4U 7.7.10 Control Register Name: CR Access Type: Write-only Offset: 0x014 + n*0x040 Reset Value: 0x00000000 • ECLR: Transfer Error Clear Writing a zero to this bit has no effect. Writing a one to this bit will clear the Transfer Error bit in the Status Register (SR.TERR). Clearing the SR.TERR bit will allow the channel to transmit data. The memory address must first be set to point to a valid location. • TDIS: Transfer Disable Writing a zero to this bit has no effect. Writing a one to this bit will disable transfer for the DMA channel. • TEN: Transfer Enable Writing a zero to this bit has no effect. Writing a one to this bit will enable transfer for the DMA channel. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - ECLR 76543210 - - - - - - TDIS TEN 59 32142D–06/2013 ATUC64/128/256L3/4U 7.7.11 Mode Register Name: MR Access Type: Read/Write Offset: 0x018 + n*0x040 Reset Value: 0x00000000 • RING: Ring Buffer 0:The Ring buffer functionality is disabled. 1:The Ring buffer functionality is enabled. When enabled, the reload registers, MARR and TCRR will not be cleared after reload. • ETRIG: Event Trigger 0:Start transfer when the peripheral selected in Peripheral Select Register (PSR) requests a transfer. 1:Start transfer only when or after a peripheral event is received. • SIZE: Size of Transfer 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - RING ETRIG SIZE Table 7-5. Size of Transfer SIZE Size of Transfer 0 Byte 1 Halfword 2 Word 3 Reserved 60 32142D–06/2013 ATUC64/128/256L3/4U 7.7.12 Status Register Name: SR Access Type: Read-only Offset: 0x01C + n*0x040 Reset Value: 0x00000000 • TEN: Transfer Enabled This bit is cleared when the TDIS bit in CR is written to one. This bit is set when the TEN bit in CR is written to one. 0: Transfer is disabled for the DMA channel. 1: Transfer is enabled for the DMA channel. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - TEN 61 32142D–06/2013 ATUC64/128/256L3/4U 7.7.13 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x020 + n*0x040 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TERR TRC RCZ 62 32142D–06/2013 ATUC64/128/256L3/4U 7.7.14 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x024 + n*0x040 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TERR TRC RCZ 63 32142D–06/2013 ATUC64/128/256L3/4U 7.7.15 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x028 + n*0x040 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TERR TRC RCZ 64 32142D–06/2013 ATUC64/128/256L3/4U 7.7.16 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x02C + n*0x040 Reset Value: 0x00000000 • TERR: Transfer Error This bit is cleared when no transfer errors have occurred since the last write to CR.ECLR. This bit is set when one or more transfer errors has occurred since reset or the last write to CR.ECLR. • TRC: Transfer Complete This bit is cleared when the TCR and/or the TCRR holds a non-zero value. This bit is set when both the TCR and the TCRR are zero. • RCZ: Reload Counter Zero This bit is cleared when the TCRR holds a non-zero value. This bit is set when TCRR is zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TERR TRC RCZ 65 32142D–06/2013 ATUC64/128/256L3/4U 7.7.17 Performance Control Register Name: PCONTROL Access Type: Read/Write Offset: 0x800 Reset Value: 0x00000000 • MON1CH: Performance Monitor Channel 1 • MON0CH: Performance Monitor Channel 0 The PDCA channel number to monitor with counter n Due to performance monitor hardware resource sharing, the two performance monitor channels should NOT be programmed to monitor the same PDCA channel. This may result in UNDEFINED monitor behavior. • CH1RES: Performance Channel 1 Counter Reset Writing a zero to this bit has no effect. Writing a one to this bit will reset the counter in the channel specified in MON1CH. This bit always reads as zero. • CH0RES: Performance Channel 0 Counter Reset Writing a zero to this bit has no effect. Writing a one to this bit will reset the counter in the channel specified in MON0CH. This bit always reads as zero. • CH1OF: Channel 1 Overflow Freeze 0: The performance channel registers are reset if DATA or STALL overflows. 1: All performance channel registers are frozen just before DATA or STALL overflows. • CH1OF: Channel 0 Overflow Freeze 0: The performance channel registers are reset if DATA or STALL overflows. 1: All performance channel registers are frozen just before DATA or STALL overflows. • CH1EN: Performance Channel 1 Enable 0: Performance channel 1 is disabled. 1: Performance channel 1 is enabled. • CH0EN: Performance Channel 0 Enable 0: Performance channel 0 is disabled. 1: Performance channel 0 is enabled. 31 30 29 28 27 26 25 24 - - MON1CH 23 22 21 20 19 18 17 16 - - MON0CH 15 14 13 12 11 10 9 8 - - - - - - CH1RES CH0RES 76543210 - - CH1OF CH0OF - - CH1EN CH0EN 66 32142D–06/2013 ATUC64/128/256L3/4U 7.7.18 Performance Channel 0 Read Data Cycles Name: PRDATA0 Access Type: Read-only Offset: 0x804 Reset Value: 0x00000000 • DATA: Data Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 67 32142D–06/2013 ATUC64/128/256L3/4U 7.7.19 Performance Channel 0 Read Stall Cycles Name: PRSTALL0 Access Type: Read-only Offset: 0x808 Reset Value: 0x00000000 • STALL: Stall Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 STALL[31:24] 23 22 21 20 19 18 17 16 STALL[23:16] 15 14 13 12 11 10 9 8 STALL[15:8] 76543210 STALL[7:0] 68 32142D–06/2013 ATUC64/128/256L3/4U 7.7.20 Performance Channel 0 Read Max Latency Name: PRLAT0 Access Type: Read/Write Offset: 0x80C Reset Value: 0x00000000 • LAT: Maximum Transfer Initiation Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock This counter is saturating. The register is reset only when PCONTROL.CH0RES is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 LAT[15:8] 76543210 LAT[7:0] 69 32142D–06/2013 ATUC64/128/256L3/4U 7.7.21 Performance Channel 0 Write Data Cycles Name: PWDATA0 Access Type: Read-only Offset: 0x810 Reset Value: 0x00000000 • DATA: Data Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 70 32142D–06/2013 ATUC64/128/256L3/4U 7.7.22 Performance Channel 0 Write Stall Cycles Name: PWSTALL0 Access Type: Read-only Offset: 0x814 Reset Value: 0x00000000 • STALL: Stall Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 STALL[31:24] 23 22 21 20 19 18 17 16 STALL[23:16] 15 14 13 12 11 10 9 8 STALL[15:8] 76543210 STALL[7:0] 71 32142D–06/2013 ATUC64/128/256L3/4U 7.7.23 Performance Channel 0 Write Max Latency Name: PWLAT0 Access Type: Read/Write Offset: 0x818 Reset Value: 0x00000000 • LAT: Maximum Transfer Initiation Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock This counter is saturating. The register is reset only when PCONTROL.CH0RES is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 LAT[15:8] 76543210 LAT[7:0] 72 32142D–06/2013 ATUC64/128/256L3/4U 7.7.24 Performance Channel 1 Read Data Cycles Name: PRDATA1 Access Type: Read-only Offset: 0x81C Reset Value: 0x00000000 • DATA: Data Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 73 32142D–06/2013 ATUC64/128/256L3/4U 7.7.25 Performance Channel 1 Read Stall Cycles Name: PRSTALL1 Access Type: Read-only Offset: 0x820 Reset Value: 0x00000000 • STALL: Stall Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 STALL[31:24] 23 22 21 20 19 18 17 16 STALL[23:16] 15 14 13 12 11 10 9 8 STALL[15:8] 76543210 STALL[7:0] 74 32142D–06/2013 ATUC64/128/256L3/4U 7.7.26 Performance Channel 1 Read Max Latency Name: PRLAT1 Access Type: Read/Write Offset: 0x824 Reset Value: 0x00000000 • LAT: Maximum Transfer Initiation Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock This counter is saturating. The register is reset only when PCONTROL.CH1RES is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 LAT[15:8] 76543210 LAT[7:0] 75 32142D–06/2013 ATUC64/128/256L3/4U 7.7.27 Performance Channel 1 Write Data Cycles Name: PWDATA1 Access Type: Read-only Offset: 0x828 Reset Value: 0x00000000 • DATA: Data Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 76 32142D–06/2013 ATUC64/128/256L3/4U 7.7.28 Performance Channel 1 Write Stall Cycles Name: PWSTALL1 Access Type: Read-only Offset: 0x82C Reset Value: 0x00000000 • STALL: Stall Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 STALL[31:24] 23 22 21 20 19 18 17 16 STALL[23:16] 15 14 13 12 11 10 9 8 STALL[15:8] 76543210 STALL[7:0] 77 32142D–06/2013 ATUC64/128/256L3/4U 7.7.29 Performance Channel 1 Write Max Latency Name: PWLAT1 Access Type: Read/Write Offset: 0x830 Reset Value: 0x00000000 • LAT: Maximum Transfer Initiation Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock This counter is saturating. The register is reset only when PCONTROL.CH1RES is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 LAT[15:8] 76543210 LAT[7:0] 78 32142D–06/2013 ATUC64/128/256L3/4U 7.7.30 PDCA Version Register Name: VERSION Access Type: Read-only Offset: 0x834 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 79 32142D–06/2013 ATUC64/128/256L3/4U 7.8 Module Configuration The specific configuration for each PDCA instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. The PDCA and the peripheral modules communicate through a set of handshake signals. The following table defines the valid settings for the Peripheral Identifier (PID) in the PDCA Peripheral Select Register (PSR). The direction is specified as observed from the memory, so RX means transfers from peripheral to memory, and TX means from memory to peripheral. Table 7-6. PDCA Configuration Feature PDCA Number of channels 12 Number of performance monitors 1 Table 7-7. PDCA Clocks Clock Name Description CLK_PDCA_HSB Clock for the PDCA HSB interface CLK_PDCA_PB Clock for the PDCA PB interface Table 7-8. Register Reset Values Register Reset Value PSR CH 0 0 PSR CH 1 1 PSR CH 2 2 PSR CH 3 3 PSR CH 4 4 PSR CH 5 5 PSR CH 6 6 PSR CH 7 7 PSR CH 8 8 PSR CH 9 9 PSR CH 10 10 PSR CH 11 11 VERSION 123 Table 7-9. Peripheral Identity Values PID Direction Peripheral Instance Peripheral Register 0 RX USART0 RHR 1 RX USART1 RHR 2 RX USART2 RHR 80 32142D–06/2013 ATUC64/128/256L3/4U 3 RX USART3 RHR 4 RX SPI RDR 5 RX TWIM0 RHR 6 RX TWIM1 RHR 7 RX TWIS0 RHR 8 RX TWIS1 RHR 9 RX ADCIFB LCDR 10 RX AW RHR 11 RX CAT ACOUNT 12 TX USART0 THR 13 TX USART1 THR 14 TX USART2 THR 15 TX USART3 THR 16 TX SPI TDR 17 TX TWIM0 THR 18 TX TWIM1 THR 19 TX TWIS0 THR 20 TX TWIS1 THR 21 TX AW THR 22 TX CAT MBLEN 23 TX ABDACB SDR0 24 TX ABDACB SDR1 25 RX IISC RHR (CH0) 26 RX IISC RHR (CH1) 27 TX IISC THR (CH0) 28 TX IISC THR (CH1) 29 RX CAT DMATSR 30 TX CAT DMATSW Table 7-9. Peripheral Identity Values PID Direction Peripheral Instance Peripheral Register 81 32142D–06/2013 ATUC64/128/256L3/4U 8. USB Interface (USBC) Rev: 2.0.0.15 8.1 Features • Compatible with the USB 2.0 specification • Supports full (12Mbit/s) and low (1.5Mbit/s) speed communication • Seven physical pipes/endpoints in ping-pong mode • Flexible pipe/endpoint configuration and reallocation of data buffers in embedded RAM • Up to two memory banks per pipe/endpoint • Built-in DMA with multi-packet support through ping-pong mode • On-chip transceivers with built-in pull-ups and pull-downs 8.2 Overview The Universal Serial Bus interface (USBC) module complies with the Universal Serial Bus (USB) 2.0 specification. Each pipe/endpoint can be configured into one of several transfer types. It can be associated with one or more memory banks (located inside the embedded system or CPU RAM) used to store the current data payload. If two banks are used (“ping-pong” mode), then one bank is read or written by the CPU (or any other HSB master) while the other is read or written by the USBC core. Table 8-1 describes the hardware configuration of the USBC module. 8.3 Block Diagram The USBC interfaces a USB link with a data flow stored in the embedded ram (CPU or HSB). The USBC requires a 48MHz ± 0.25% reference clock, which is the USB generic clock. For more details see ”Clocks” on page 84. The 48MHz clock is used to generate either a 12MHz fullspeed or a 1.5MHz low-speed bit clock from the received USB differential data, and to transmit data according to full- or low-speed USB device tolerances. Clock recovery is achieved by a digital phase-locked loop (a DPLL, not represented) in the USBC module, which complies with the USB jitter specifications. The USBC module consists of: • HSB master interface Table 8-1. Description of USB pipes/endpoints pipe/endpoint Mnemonic Max. size Number of available banks Type 0 PEP0 1023 bytes 1 Control/Isochronous/Bulk/Interrupt 1 PEP1 1023 bytes 2 Control/Isochronous/Bulk/Interrupt 2 PEP2 1023 bytes 2 Control/Isochronous/Bulk/Interrupt ... ... ... ... ... 6 PEP6 1023 bytes 2 Control/Isochronous/Bulk/Interrupt 82 32142D–06/2013 ATUC64/128/256L3/4U • User interface • USB Core • Transceiver pads Figure 8-1. USBC Block Diagram Note: in the block diagram is symbolic, it is mapped to a GPIO pin (See Section “8.5.1” on page 84.). The VBUS detection (rising edge detection on the GPIO pin) should be handled by software. Interrupt Controller USB interrupts DM USB_VBUS (1) USB DP User interface SCIF GCLK_USBC @ 48 MHz PB USB 2.0 Core USB clock domain System clock domain HSB HSB Master 83 32142D–06/2013 ATUC64/128/256L3/4U 8.4 I/O Lines Description Table 8-2. I/O Lines Description PIn Name Pin Description Type Active Level DM Data -: Differential Data Line - Port Input/Output DP Data +: Differential Data Line + Port Input/Output 84 32142D–06/2013 ATUC64/128/256L3/4U 8.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 8.5.1 I/O Lines The USBC pins may be multiplexed with the I/O Controller lines. The user must first configure the I/O Controller to assign the desired USBC pins to their peripheral functions. The USB VBUS line should be connected to a GPIO pin and the user should monitor this with software. 8.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the USBC, the USBC will stop functioning and resume operation after the system wakes up from sleep mode. 8.5.3 Clocks The USBC has two bus clocks connected: One High Speed Bus clock (CLK_USBC_HSB) and one Peripheral Bus clock (CLK_USBC_PB). These clocks are generated by the Power Manager. Both clocks are enabled at reset, and can be disabled by the Power Manager. It is recommended to disable the USBC before disabling the clocks, to avoid freezing the USBC in an undefined state. The 48MHz USB clock is generated by a dedicated generic clock from the SCIF module. Before using the USB, the user must ensure that the USB generic clock (GCLK_USBC) is enabled at 48MHz in the SCIF module. 8.5.4 Interrupts The USBC interrupt request line is connected to the interrupt controller. Using the USBC interrupt requires the interrupt controller to be programmed first. The USBC asynchronous interrupt can wake the CPU from any sleep mode: • The Wakeup Interrupt (WAKEUP) 85 32142D–06/2013 ATUC64/128/256L3/4U 8.6 Functional Description 8.6.1 USB General Operation 8.6.1.1 Initialization After a hardware reset, the USBC is in the Reset state. In this state: • The module is disabled. The USBC Enable bit in the General Control register (USBCON.USBE) is reset. • The module clock is stopped in order to minimize power consumption. The Freeze USB Clock bit in USBCON (USBCON.FRZCLK) is set. • The USB pad is in suspend mode. • The internal states and registers of the device are reset. • The Freeze USB Clock (FRZCLK), USBC Enable (USBE), in USBCON and the Low-Speed mode bit in the Device General Control register (UDCON.LS) can be written to by software, so that the user can configure pads and speed before enabling the module. These values are only taken into account once the module has been enabled and unfrozen. After writing a one to USBCON.USBE, the USBC enters device mode in idle state. Refer to Section 8.6.2 for the basic operation of the device mode. The USBC can be disabled at any time by writing a zero to USBCON.USBE, this acts as a hardware reset, except that the FRZCLK,bit in USBCON, and the LS bits in UDCON are not reset. 8.6.1.2 Interrupts One interrupt vector is assigned to the USBC. See Section 8.6.2.18 for further details about device interrupts. See Section 8.5.4 for asynchronous interrupts. 8.6.1.3 Frozen clock When the USB clock is frozen, it is still possible to access the following bits: FRZCLK, and USBE in the USBCON register, and LS in the UDCON register. When FRZCLK is set, only the asynchronous interrupt can trigger a USB interrupt (see Section 8.5.4). 8.6.1.4 Speed control • Device mode When the USBC interface is in device mode, the speed selection is done by the UDCON.LS bit, connecting an internal pull-up resistor to either DP (full-speed mode) or DM (low-speed mode). The LS bit shall be written before attaching the device, which can be simulated by clearing the UDCON.DETACH bit. 86 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-2. Speed Selection in device mode 8.6.1.5 Data management Endpoints and pipe buffers can be allocated anywhere in the embedded memory (CPU RAM or HSB RAM). See ”RAM management” on page 90. 8.6.1.6 Pad Suspend Figure 8-3 illustrates the behavior of the USB pad in device mode. Figure 8-3. Pad Behavior • In Idle state, the pad is in low power consumption mode. • In Active state, the pad is working. Figure 8-4 illustrates the pad events leading to a PAD state change. RPU UDCON.DETACH DP DM UDCON.LS VBUS Idle Active USBE = 1 & DETACH = 0 & Suspend USBE = 0 | DETACH = 1 | Suspend 87 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-4. Pad events The Suspend Interrupt bit in the Device Global Interrupt register (UDINT.SUSP) is set and the Wakeup Interrupt (UDINT.WAKEUP) bit is cleared when a USB Suspend state has been detected on the USB bus. This event automatically puts the USB pad in the Idle state. The detection of a non-idle event sets WAKEUP, clears SUSP, and wakes the USB pad. The pad goes to the Idle state if the module is disabled or if UDCON.DETACH is written to one. It returns to the Active state when USBCON.USBE is written to one and DETACH is written to zero. SUSP Suspend detected Cleared on Wakeup WAKEUP Wakeup detected Cleared by software to acknowledge the interrupt PAD state Active Idle Active 88 32142D–06/2013 ATUC64/128/256L3/4U 8.6.2 USBC Device Mode Operation 8.6.2.1 Device Enabling In device mode, the USBC supports full- and low-speed data transfers. Including the default control endpoint, a total of seven endpoints are provided. They can be configured as isochronous, bulk or interrupt types, as described in Table 8-1 on page 81 After a hardware reset, the USBC device mode is in the reset state (see Section 8.6.1.1). In this state, the endpoint banks are disabled and neither DP nor DM are pulled up (DETACH is one). DP or DM will be pulled up according to the selected speed as soon as the DETACH bit is written to zero. See “Device mode” for further details. When the USBC is enabled (USBE is one) in device mode, it enters the Idle state, minimizing power consumption. Being in Idle state does not require the USB clocks to be activated. The USBC device mode can be disabled or reset at any time by disabling the USBC (by writing a zero to USBE). 8.6.2.2 USB reset The USB bus reset is initiated by a connected host and managed by hardware. When a USB reset state is detected on the USB bus, the following operations are performed by the controller: • UDCON register is reset except for the DETACH and SPDCONF bits. • Device Frame Number Register (UDFNUM), Endpoint n Configuration Register (UECFGn), and Endpoint n Control Register (UECONn) registers are cleared. • The data toggle sequencing in all the endpoints are cleared. • At the end of the reset process, the End of Reset (EORST) bit in the UDINT register is set. 8.6.2.3 Endpoint activation When an endpoint is disabled (UERST.EPENn = 0) the data toggle sequence, Endpoint n Status Set (UESTAn), and UECONn registers will be reset. The controller ignores all transactions to this endpoint as long as it is inactive. To complete an endpoint activation, the user should fill out the endpoint descriptor: see Figure 8- 5 on page 91. 8.6.2.4 Data toggle sequence In order to respond to a CLEAR_FEATURE USB request without disabling the endpoint, the user can clear the data toggle sequence by writing a one to the Reset Data Toggle Set bit in the Endpoint n Control Set register (UECONnSET.RSTDTS) 8.6.2.5 Busy bank enable In order to make an endpoint bank look busy regardless of its actual state, the user can write a one to the Busy Bank Enable bit in the Endpoint n Control Register (UECONnSET.BUSY0/1ES). If a BUSYnE bit is set, any transaction to this bank will be rejected with a NAK reply. 8.6.2.6 Address setup The USB device address is set up according to the USB protocol. 89 32142D–06/2013 ATUC64/128/256L3/4U • After all kinds of resets, the USB device address is 0. • The host starts a SETUP transaction with a SET_ADDRESS(addr) request. • The user writes this address to the USB Address field (UDCON.UADD), and writes a zero to the Address Enable bit (UDCON.ADDEN), resulting in the address remaining zero. • The user sends a zero-length IN packet from the control endpoint. • The user enables the stored USB device address by writing a one to ADDEN. Once the USB device address is configured, the controller filters the packets to only accept those targeting the address stored in UADD. UADD and ADDEN should not be written to simultaneously. They should be written sequentially, UADD field first. If UADD or ADDEN is cleared, the default device address 0 is used. UADD and ADDEN are cleared: • On a hardware reset. • When the USBC is disabled (USBE written to zero). • When a USB reset is detected. 8.6.2.7 Suspend and Wakeup When an idle USB bus state has been detected for 3 ms, the controller sets the Suspend (SUSP) interrupt bit in UDINT. In this case, the transceiver is suspended, reducing power consumption. To further reduce power consumption it is recommended to freeze the USB clock by writing a one to the Freeze USB Clock (FRZCLK) bit in USBCON when the USB bus is in suspend mode. The MCU can also enter the idle or frozen sleep mode to further lower power consumption. To recover from the suspend mode, the user shall wait for the Wakeup (WAKEUP) interrupt bit, which is set when a non-idle event is detected, and then write a zero to FRZCLK. As the WAKEUP interrupt bit in UDINT is set when a non-idle event is detected, it can occur regardless of whether the controller is in the suspend mode or not. The SUSP and WAKEUP interrupts are thus independent of each other except for that one bit is cleared when the other is set. 8.6.2.8 Detach The reset value of the DETACH bit located in the UDCON register, is one. It is possible to initiate a device re-enumeration simply by writing a one and then a zero to DETACH. DETACH acts on the pull-up connections of the DP and DM pads. See “Device mode” for further details. 8.6.2.9 Remote wakeup The remote wakeup request (also known as upstream resume) is the only request the device may send on its own initiative. This should be preceded by a DEVICE_REMOTE_WAKEUP request from the host. • First, the USBC must have detected a “Suspend” state on the bus, i.e. the remote wakeup request can only be sent after a SUSP interrupt has been set. 90 32142D–06/2013 ATUC64/128/256L3/4U • The user may then write a one to the remote wakeup (RMWKUP) bit in UDCON to send an Upstream Resume to the host initiating the wakeup. This will automatically be done by the controller after 5ms of inactivity on the USB bus. • When the controller sends the Upstream Resume, the Upstream Resume (UPRSM) interrupt is set and SUSP is cleared. • RMWKUP is cleared at the end of the transmitting Upstream Resume. • In case of a rebroadcast resume initiated by the host, the End of Resume (EORSM) interrupt is set when the rebroadcast resume is completed. 8.6.2.10 RAM management Endpoint data can be physically allocated anywhere in the embedded RAM. The USBC controller accesses these endpoints directly through the HSB master (built-in DMA). The USBC controller reads the USBC descriptors to know where each endpoint is located. The base address of the USBC descriptor (UDESC.UDESCA) needs to be written by the user. The descriptors can also be allocated anywhere in the embedded RAM. Before using an endpoint, the user should setup the endpoint address for each bank. Depending on the direction, the type, and the packet-mode (single or multi-packet), the user should also initialize the endpoint packet size, and the endpoint control and status fields, so that the USBC controller does not compute random values from the RAM. When using an endpoint the user should read the UESTAX.CURRBK field to know which bank is currently being processed. 91 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-5. Memory organization Each descriptor of an endpoint n consists of four words. • The address of the endpoint and the bank used (EPn_ADDR_BK0/1). • The packet size information for the endpoint and bank (EPn_PCKSIZE_BK0/1): Table 8-3. EPn_PCKSIZE_BK0/1 structure – AUTO_ZLP: Auto zero length packet, see ”Multi packet mode for IN endpoints” on page 96. – MULTI_PACKET_SIZE: see ”Multi packet mode and single packet mode.” on page 93. – BYTE_COUNT: see ”Multi packet mode and single packet mode.” on page 93. 31 30:16 15 14:0 AUTO_ZLP MULTI_PACKET_SIZE - BYTE_COUNT EPn BK0 EP0_CTR_STA_BK0 E P 0 _ P C K S IZ E _ B K 0 EP0_ADDR_BK0 UDESCA Growing Memory Addresses Descriptor EP0 R e se rve d EP0_CTR _STA_BK1 E P 0 _ P C K S IZ E _ B K 1 EP0_ADDR_BK1 R e se rve d Bank0 Bank1 +0x000 +0x004 +0x008 +0x00C +0x010 +0x014 +0x018 +0x01C EP1_CTR_STA_BK0 E P 1 _ P C K S IZ E _ B K 0 EP1_ADDR_BK0 Descriptor EP1 R e se rve d EP1_CTR _STA_BK1 E P 1 _ P C K S IZ E _ B K 1 EP1_ADDR_BK1 R e se rve d Bank0 Bank1 +0x020 +0x024 +0x028 +0x02C +0x030 +0x034 +0x038 +0x03C EPn_CTR_STA_BK0 E P n _ P C K S IZ E _ B K 0 EPn_ADDR_BK0 R e se rve d EPn_CTR _STA_BK1 E P n _ P C K S IZ E _ B K 1 EPn_ADDR_BK1 R e se rve d Bank0 Bank1 Descriptor EPn EPn BK1 U S B d e s c rip to rs U S B B u ffe rs 92 32142D–06/2013 ATUC64/128/256L3/4U • The control and status fields for the endpoint and bank (EPn_CTR_STA_BK0/1): Table 8-4. EPn_CTR_STA_BK0/1 structure – UNDERF: Underflow status for isochronous IN transfer. See ”Data flow error” on page 99. – OVERF: Overflow status for isochronous OUT transfer. See ”Data flow error” on page 99. – CRCERR: CRC error status for isochronous OUT transfer. See ”CRC error” on page 99. – STALLRQ_NEXT: Stall request for the next transfer. See ”STALL request” on page 92. 8.6.2.11 STALL request For each endpoint, the STALL management is performed using: • The STALL Request (STALLRQ) bit in UECONn is set to initiate a STALL request. • The STALLed Interrupt (STALLEDI) bit in UESTAn is set when a STALL handshake has been sent. To answer requests with a STALL handshake, STALLRQ has to be set by writing a one to the STALL Request Set (STALLRQS) bit. All following requests will be discarded (RXOUTI, etc. will not be set) and handshaked with a STALL until the STALLRQ bit is cleared, by receiving a new SETUP packet (for control endpoints) or by writing a one to the STALL Request Clear (STALLRQC) bit. Each time a STALL handshake is sent, the STALLEDI bit is set by the USBC and the EPnINT interrupt is set. The user can use the descriptor to manage STALL requests. The USBC controller reads the EPn_CTR_STA_BK0/1.STALLRQ_NEXT bit after successful transactions and if it is one the USBC controller will set UECON.STALLRQ. The STALL_NEXT bit will be cleared upon receiving a SETUP transaction and the USBC controller will then clear the STALLRQ bit. • Special considerations for control endpoints If a SETUP packet is received at a control endpoint where a STALL request is active, the Received SETUP Interrupt (RXSTPI) bit in UESTAn is set, and the STALLRQ and STALLEDI bits are cleared. It allows the SETUP to be always ACKed as required by the USB standard. This management simplifies the enumeration process management. If a command is not supported or contains an error, the user requests a STALL and can return to the main task, waiting for the next SETUP request. • STALL handshake and retry mechanism The retry mechanism has priority over the STALL handshake. A STALL handshake is sent if the STALLRQ bit is set and if there is no retry required. 31:19 18 17 16 15:1 0 Status elements Control elements - UNDERF OVERF CRCERR - STALLRQ_NEXT 93 32142D–06/2013 ATUC64/128/256L3/4U 8.6.2.12 Multi packet mode and single packet mode. Single packet mode is the default mode where one USB packet is managed per bank. The multi-packet mode allows the user to manage data exceeding the maximum endpoint size (UECFGn.EPSIZE) for an endpoint bank across multiple packets without software intervention. This mode can also be coupled with the ping-pong mode. • For an OUT endpoint, the EPn_PCKSIZE_BK0/1.MULTI_PACKET_SIZE field should be configured correctly to enable the multi-packet mode. See ”Multi packet mode for OUT endpoints” on page 98. For single packet mode, the MULTI_PACKET_SIZE should be initialized to 0. • For an IN endpoint, the EPn_PCKSIZE_BK0/1.BYTE_COUNT field should be configured correctly to enable the multi-packet mode. See”Multi packet mode for IN endpoints” on page 96. For single packet mode, the BYTE_COUNT should be less than EPSIZE. 8.6.2.13 Management of control endpoints • Overview A SETUP request is always ACKed. When a new SETUP packet is received, the RXSTPI is set, but not the Received OUT Data Interrupt (RXOUTI) bit. The FIFO Control (FIFOCON) bit in UECONn is irrelevant for control endpoints. The user should therefore never use it for these endpoints. When read, this value is always zero. Control endpoints are managed using: • The RXSTPI bit: is set when a new SETUP packet is received. This has to be cleared by firmware in order to acknowledge the packet and to free the bank. • The RXOUTI bit: is set when a new OUT packet is received. This has to be cleared by firmware in order to acknowledge the packet and to free the bank. • The Transmitted IN Data Interrupt (TXINI) bit: is set when the current bank is ready to accept a new IN packet. This has to be cleared by firmware in order to send the packet. • Control write Figure 8-6 on page 94 shows a control write transaction. During the status stage, the controller will not necessarily send a NAK on the first IN token: • If the user knows the exact number of descriptor bytes that will be read, the status stage can be predicted, and a zero-length packet can be sent after the next IN token. • Alternatively the bytes can be read until the NAKed IN Interrupt (NAKINI) is triggered, notifying that all bytes are sent by the host and that the transaction is now in the status stage. 94 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-6. Control Write • Control read Figure 8-7 on page 94 shows a control read transaction. The USBC has to manage the simultaneous write requests from the CPU and USB host. Figure 8-7. Control Read A NAK handshake is always generated as the first status stage command. The UESTAn.NAKINI bit is set. It allows the user to know that the host aborts the IN data stage. As a consequence, the user should stop processing the IN data stage and should prepare to receive the OUT status stage by checking the UESTAn.RXOUTI bit. The OUT retry is always ACKed. This OUT reception sets RXOUTI. Handle this with the following software algorithm: // process the IN data stage set TXINI wait for RXOUTI (rising) OR TXINI (falling) if RXOUTI is high, then process the OUT status stage if TXINI is low, then return to process the IN data stage Once the OUT status stage has been received, the USBC waits for a SETUP request. The SETUP request has priority over all other requests and will be ACKed. SETUP RXSTPI RXOUTI TXINI USB Bus HW SW OUT HW SW OUT HW SW IN IN NAK SW SETUP STATUS DATA SETUP RXSTPI RXOUTI TXINI USB Bus HW SW IN HW SW IN OUT OUT NAK SW SW HW Wr Enable HOST Wr Enable CPU SETUP STATUS DATA 95 32142D–06/2013 ATUC64/128/256L3/4U 8.6.2.14 Management of IN endpoints • Overview IN packets are sent by the USBC device controller upon IN requests from the host. The endpoint and its descriptor in RAM must be pre configured (see section ”RAM management” on page 90 for more details). When the current bank is clear, the TXINI and FIFO Control (UECONn.FIFOCON) bits will be set simultaneously. This triggers an EPnINT interrupt if the Transmitted IN Data Interrupt Enable (TXINE) bit in UECONn is one. TXINI shall be cleared by software (by writing a one to the Transmitted IN Data Interrupt Enable Clear bit in the Endpoint n Control Clear register (UECONnCLR.TXINIC)) to acknowledge the interrupt. This has no effect on the endpoint FIFO. The user writes the IN data to the bank referenced by the EPn descriptor and allows the USBC to send the data by writing a one to the FIFO Control Clear (UECONnCLR.FIFOCONC) bit. This will also cause a switch to the next bank if the IN endpoint is composed of multiple banks. The TXINI and FIFOCON bits will be updated accordingly. TXINI should always be cleared before clearing FIFOCON to avoid missing an TXINI event. Figure 8-8. Example of an IN endpoint with one data bank Figure 8-9. Example of an IN endpoint with two data banks IN DATA (bank 0) ACK TXINI FIFOCON HW write data to CPU BANK 0 SW SW SW SW IN NAK write data to CPU BANK 0 IN DATA (bank 0) ACK TXINI FIFOCON write data to CPU BANK 0 SW SW SW SW IN DATA (bank 1) ACK write data to CPU BANK 1 SW HW write data to CPU BANK0 96 32142D–06/2013 ATUC64/128/256L3/4U • Detailed description The data is written according to this sequence: • When the bank is empty, TXINI and FIFOCON are set, which triggers an EPnINT interrupt if TXINE is one. • The user acknowledges the interrupt by clearing TXINI. • The user reads the UESTAX.CURRBK field to see which the current bank is. • The user writes the data to the current bank, located in RAM as described by its descriptor: EPn_ADDR_BK0/1. • The user should write the size of the IN packet into the USB descriptor: EPn_PCKSIZE_BK0/1.BYTE_COUNT. • The user allows the controller to send the bank contents and switches to the next bank (if any) by clearing FIFOCON. If the endpoint uses several banks, the current one can be written while the previous one is being read by the host. When the user clears FIFOCON, the next current bank may already be clear and TXINI is set immediately. An “Abort” stage can be produced when a zero-length OUT packet is received during an IN stage of a control or isochronous IN transaction. The Kill IN Bank (KILLBK) bit in UECONn is used to kill the last written bank. The best way to manage this abort is to apply the algorithm represented on Figure 8-10 on page 96. See ”Endpoint n Control Register” on page 130 for more details about the KILLBK bit. Figure 8-10. Abort Algorithm • Multi packet mode for IN endpoints In multi packet mode, the user can prepare n USB packets in the bank to be sent on a multiple IN transaction. The packet sizes will equal UECFGn.EPSIZE unless the AUTO_ZLP option is Endpoint Abort Abort Done Abort is based on the fact that no bank is busy, i.e., that nothing has to be sent Disable the TXINI interrupt. EPRSTn = 1 NBUSYBK == 0? Yes TXINEC = 1 No KILLBKS = 1 KILLBK Yes == 1? Kill the last written bank. Wait for the end of the procedure No 97 32142D–06/2013 ATUC64/128/256L3/4U set, or if the total byte count is not an integral multiple of EPSIZE, whereby the last packet should be short. To enable the multi packet mode, the user should configure the endpoint descriptor (EPn_PCKSIZE_BK0/1.BYTE_COUNT) to the total size of the multi packet, which should be larger than the endpoint size (EPSIZE). Since the EPn_PCKSIZE_BK0/1.MULTI_PACKET_SIZE is incremented (by the transmitted packet size) after each successful transaction, it should be set to zero when setting up a new multi packet transfer. The EPn_PCKSIZE_BK0/1.MULTI_PACKET_SIZE is cleared by hardware when all the bank contents have been sent. The bank is considered as ready and the TX_IN flag is set when: • A short packet (smaller than EPSIZE) has been transmitted. • A packet has been successfully transmitted, the updated MULTI_PACKET_SIZE equals the BYTE_COUNT, and the AUTO_ZLP field is not set. • An extra zero length packet has been automatically sent for the last transfer of the current bank, if BYTE_COUNT is a multiple of EPSIZE and AUTO_ZLP is set. 8.6.2.15 Management of OUT endpoints • Overview The endpoint and its descriptor in RAM must be pre configured, see section ”RAM management” on page 90 for more details. When the current bank is full, the RXOUTI and FIFO Control (UECONn.FIFOCON) bits will be set simultaneously. This triggers an EPnINT interrupt if the Received OUT Data Interrupt Enable (RXOUTE) bit in UECONn is one. RXOUTI shall be cleared by software (by writing a one to the Received OUT Data Interrupt Clear (RXOUTIC) bit) to acknowledge the interrupt. This has no effect on the endpoint FIFO. The user reads the OUT data from the RAM and clears the FIFOCON bit to free the bank. This will also cause a switch to the next bank if the OUT endpoint is composed of multiple banks. RXOUTI should always be cleared before clearing FIFOCON to avoid missing an RXOUTI event. Figure 8-11. Example of an OUT endpoint with one data bank OUT DATA (bank 0) ACK RXOUTI FIFOCON HW OUT DATA (bank 0) ACK HW SW SW SW read data from CPU BANK 0 read data from CPU BANK 0 NAK 98 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-12. Example of an OUT endpoint with two data banks • Detailed description Before using the OUT endpoint, one should properly initialize its descriptor for each bank. See Figure 8-5 on page 91. The data is read, according to this sequence: • When the bank is full, RXOUTI and FIFOCON are set, which triggers an EPnINT interrupt if RXOUTE is one. • The user acknowledges the interrupt by writing a one to RXOUTIC in order to clear RXOUTI. • The user reads the UESTAX.CURRBK field to know the current bank number. • The user reads the byte count of the current bank from the descriptor in RAM (EPn_PCKSIZE_BK0/1.BYTE_COUNT) to know how many bytes to read. • The user reads the data in the current bank, located in RAM as described by its descriptor: EPn_ADDR_BK0/1. • The user frees the bank and switches to the next bank (if any) by clearing FIFOCON. If the endpoint uses several banks, the current one can be read while the next is being written by the host. When the user clears FIFOCON, the following bank may already be ready and RXOUTI will be immediately set. • Multi packet mode for OUT endpoints In multi packet mode, the user can extend the size of the bank allowing the storage of n USB packets in the bank. To enable the multi packet mode, the user should configure the endpoint descriptor (EPn_PCKSIZE_BK0/1.MULTI_PACKET_SIZE) to match the size of the multi packet.This value should be a multiple of the endpoint size (UECFGn.EPSIZE). Since the EPn_PCKSIZE_BK0/1.BYTE_COUNT is incremented (by the received packet size) after each successful transaction, it should be set to zero when setting up a new multi packet transfer. As for single packet mode, the number of received data bytes is stored in the BYTE_CNT field. The bank is considered as “valid” and the RX_OUT flag is set when: OUT DATA (bank 0) ACK RXOUTI FIFOCON HW OUT DATA (bank 1) ACK SW read data from CPU SW BANK 0 HW SW read data from CPU BANK 1 99 32142D–06/2013 ATUC64/128/256L3/4U • A packet has been successfully received and the updated BYTE_COUNT equals the MULTI_PACKET_SIZE. • A short packet (smaller than EPSIZE) has been received. 8.6.2.16 Data flow error This error exists only for isochronous IN/OUT endpoints. It sets the Errorflow Interrupt (ERRORFI) bit in UESTAn, which triggers an EPnINT interrupt if the Errorflow Interrupt Enable (ERRORFE) bit is one. The user can check the EPn_CTR_STA_BK0/1.UNDERF and OVERF bits in the endpoint descriptor to see which current bank has been affected. • An underflow can occur during IN stage if the host attempts to read from an empty bank. A zero-length packet is then automatically sent by the USBC. The endpoint descriptor EPn_CTR_STA_BK0/1.UNDERF points out the bank from which the IN data should have originated. If a new successful transaction occurs, the UNDERF bit is overwritten to 0 only if the UESTAn.ERRORFI is cleared. • An overflow can occur during the OUT stage if the host tries to send a packet while the bank is full. Typically this occurs when a CPU is not fast enough. The packet data is not written to the bank and is lost. The endpoint descriptor EPn_CTR_STA_BK0/1.OVERF points out which bank the OUT data was destined to. If the UESTAn.ERRORFI bit is cleared and a new transaction is successful, the OVERF bit will be overwritten to zero. 8.6.2.17 CRC error This error exists only for isochronous OUT endpoints. It sets the CRC Error Interrupt (CRCERRI) bit in UESTAn, which triggers an EPnINT interrupt if the CRC Error Interrupt Enable (CRCERRE) bit is one. A CRC error can occur during an isochronous OUT stage if the USBC detects a corrupted received packet. The OUT packet is stored in the bank as if no CRC error had occurred (RXOUTI is set). The user can also check the endpoint descriptor to see which current bank is impacted by the CRC error by reading EPn_CTR_STA_BK0/1.CRCERR. 8.6.2.18 Interrupts There are two kinds of device interrupts: processing, i.e. their generation is part of the normal processing, and exception, i.e. errors not related to CPU exceptions. • Global interrupts The processing device global interrupts are: • The Suspend (SUSP) interrupt • The Start of Frame (SOF) interrupt with no frame number CRC error (the Frame Number CRC Error (FNCERR) bit in the Device Frame Number (UDFNUM) register is zero) • The End of Reset (EORST) interrupt • The Wakeup (WAKEUP) interrupt • The End of Resume (EORSM) interrupt • The Upstream Resume (UPRSM) interrupt • The Endpoint n (EPnINT) interrupt The exception device global interrupts are: 100 32142D–06/2013 ATUC64/128/256L3/4U • The Start of Frame (SOF) interrupt with a frame number CRC error (FNCERR is one) • Endpoint interrupts The processing device endpoint interrupts are: • The Transmitted IN Data Interrupt (TXINI) • The Received OUT Data Interrupt (RXOUTI) • The Received SETUP Interrupt (RXSTPI) • The Number of Busy Banks (NBUSYBK) interrupt The exception device endpoint interrupts are: • The Errorflow Interrupt (ERRORFI) • The NAKed OUT Interrupt (NAKOUTI) • The NAKed IN Interrupt (NAKINI) • The STALLed Interrupt (STALLEDI) • The CRC Error Interrupt (CRCERRI) 101 32142D–06/2013 ATUC64/128/256L3/4U 8.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 8-5. USBC Register Memory Map Offset Register Name Access Reset Value 0x0000 Device General Control Register UDCON Read/Write 0x00000100 0x0004 Device Global Interrupt Register UDINT Read-Only 0x00000000 0x0008 Device Global Interrupt Clear Register UDINTCLR Write-Only 0x00000000 0x000C Device Global Interrupt Set Register UDINTSET Write-Only 0x00000000 0x0010 Device Global Interrupt Enable Register UDINTE Read-Only 0x00000000 0x0014 Device Global Interrupt Enable Clear Register UDINTECLR Write-Only 0x00000000 0x0018 Device Global Interrupt Enable Set Register UDINTESET Write-Only 0x00000000 0x001C Endpoint Enable/Reset Register UERST Read/Write 0x00000000 0x0020 Device Frame Number Register UDFNUM Read-Only 0x00000000 0x0100 + n*4 Endpoint n Configuration Register UECFGn Read/Write 0x00000000 0x0130 + n*4 Endpoint n Status Register UESTAn Read-Only 0x00000100 0x0160 + n*4 Endpoint n Status Clear Register UESTAnCLR Write-Only 0x00000000 0x0190 + n*4 Endpoint n Status Set Register UESTAnSET Write-Only 0x00000000 0x01C0 + n*4 Endpoint n Control Register UECONn Read-Only 0x00000000 0x01F0 + n*4 Endpoint n Control Set Register UECONnSET Write-Only 0x00000000 0x0220 + n*4 Endpoint n Control Clear Register UECONnCLR Write-Only 0x00000000 0x0800 General Control Register USBCON Read/Write 0x00004000 0x0804 General Status Register USBSTA Read-Only 0x00000000 0x0808 General Status Clear Register USBSTACLR Write-Only 0x00000000 0x080C General Status Set Register USBSTASET Write-Only 0x00000000 0x0818 IP Version Register UVERS Read-Only -(1) 0x081C IP Features Register UFEATURES Read-Only -(1) 0x0820 IP PB Address Size Register UADDRSIZE Read-Only -(1) 0x0824 IP Name Register 1 UNAME1 Read-Only -(1) 0x0828 IP Name Register 2 UNAME2 Read-Only -(1) 0x082C USB Finite State Machine Status Register USBFSM Read-Only 0x00000009 0x0830 USB Descriptor address UDESC Read/Write 0x00000000 102 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1 USB General Registers 8.7.1.1 General Control Register Name: USBCON Access Type: Read/Write Offset: 0x0800 Reset Value: 0x00004000 • USBE: USBC Enable Writing a zero to this bit will disable the USBC, USB transceiver, and USB clock inputs. This will over-ride FRZCLK settings but not affect the value. Unless explicitly stated, all registers will become reset and read-only. Writing a one to this bit will enable the USBC. 0: The USBC is disabled. 1: The USBC is enabled. This bit can be written to even if FRZCLK is one. • FRZCLK: Freeze USB Clock Writing a zero to this bit will enable USB clock inputs. Writing a one to this bit will disable USB clock inputs. The resume detection will remain active. Unless explicitly stated, all registers will become read-only. 0: The clock inputs are enabled. 1: The clock inputs are disabled. This bit can be written to even if USBE is zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -- - -- - 15 14 13 12 11 10 9 8 USBE FRZCLK - - - - - - 76543210 -------- 103 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.2 General Status Register Register Name: USBSTA Access Type: Read-Only Offset: 0x0804 Reset Value: 0x00000000 • CLKUSABLE: Generic Clock Usable This bit is cleared when the USB generic clock is not usable. This bit is set when the USB generic clock (that should be 48 Mhz) is usable. • SPEED: Speed Status This field is set according to the controller speed mode. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CLKUSABLE SPEED - - - - 76543210 -------- SPEED Speed Status 00 full-speed mode 01 Reserved 10 low-speed mode 11 Reserved 104 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.3 General Status Clear Register Register Name: USBSTACLR Access Type: Write-Only Offset: 0x0808 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in USBSTA. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 105 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.4 General Status Set Register Register Name: USBSTASET Access Type: Write-Only Offset: 0x080C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in USBSTA. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 106 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.5 Version Register Register Name: UVERS Access Type: Read-Only Offset: 0x0818 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 107 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.6 Features Register Register Name: UFEATURES Access Type: Read-Only Offset: 0x081C Reset Value: - • EPTNBRMAX: Maximal Number of pipes/endpoints This field indicates the number of hardware-implemented pipes/endpoints: 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - EPTNBRMAX 108 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.7 Address Size Register Register Name: UADDRSIZE Access Type: Read-Only Offset: 0x0820 Reset Value: - • UADDRSIZE: IP PB Address Size This field indicates the size of the PB address space reserved for the USBC IP interface. 31 30 29 28 27 26 25 24 UADDRSIZE[31:24] 23 22 21 20 19 18 17 16 UADDRSIZE[23:16] 15 14 13 12 11 10 9 8 UADDRSIZE[15:8] 76543210 UADDRSIZE[7:0] 109 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.8 IP Name Register 1 Register Name: UNAME1 Access Type: Read-Only Offset: 0x0824 Reset Value: - • UNAME1: IP Name Part One This field indicates the first part of the ASCII-encoded name of the USBC IP. 31 30 29 28 27 26 25 24 UNAME1[31:24] 23 22 21 20 19 18 17 16 UNAME1[23:16] 15 14 13 12 11 10 9 8 UNAME1[15:8] 76543210 UNAME1[7:0] 110 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.9 IP Name Register 2 Register Name: UNAME2 Access Type: Read-Only Offset: 0x0828 Reset Value: • UNAME2: IP Name Part Two This field indicates the second part of the ASCII-encoded name of the USBC IP. 31 30 29 28 27 26 25 24 UNAME2[31:24] 23 22 21 20 19 18 17 16 UNAME2[23:16] 15 14 13 12 11 10 9 8 UNAME2[15:8] 76543210 UNAME2[7:0] 111 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.10 Finite State Machine Status Register Register Name: USBFSM Access Type: Read-Only Offset: 0x082C Reset Value: 0x00000009 • DRDSTATE: Dual Role Device State This field indicates the state of the USBC. For Device mode it should always read 9. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - DRDSTATE 112 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.11 USB Descriptor Address Register Name: UDESC Access Type: Read-Write Offset: 0x0830 Reset Value: - • UDESCA: USB Descriptor Address This field contains the address of the USB descriptor. The three least significant bits are always zero. 31 30 29 28 27 26 25 24 UDESCA[31:24] 23 22 21 20 19 18 17 16 UDESCA[23:16] 15 14 13 12 11 10 9 8 UDESCA[15:8] 76543210 UDESCA[7:0] 113 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2 USB Device Registers 8.7.2.1 Device General Control Register Register Name: UDCON Access Type: Read/Write Offset: 0x0000 Reset Value: 0x00000100 • GNAK: Global NAK 0: Normal mode. 1: A NAK handshake is answered for each USB transaction regardless of the current endpoint memory bank status. • LS: low-speed mode force 0: The full-speed mode is active. 1: The low-speed mode is active. This bit can be written to even if USBE is zero or FRZCLK is one. Disabling the USBC (by writing a zero to the USBE bit) does not reset this bit. • RMWKUP: Remote wakeup Writing a zero to this bit has no effect. Writing a one to this bit will send an upstream resume to the host for a remote wakeup. This bit is cleared when the USBC receives a USB reset or once the upstream resume has been sent. • DETACH: Detach Writing a zero to this bit will reconnect the device. Writing a one to this bit will physically detach the device (disconnect internal pull-up resistor from DP and DM). • ADDEN: Address Enable Writing a zero to this bit has no effect. Writing a one to this bit will activate the UADD field (USB address). This bit is cleared when a USB reset is received. • UADD: USB Address This field contains the device address. This field is cleared when a USB reset is received. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - GNAK - 15 14 13 12 11 10 9 8 - - - LS - - RMWKUP DETACH 76543210 ADDEN UADD 114 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.2 Device Global Interrupt Register Register Name: UDINT Access Type: Read-Only Offset: 0x0004 Reset Value: 0x00000000 Note: 1. EPnINT bits are within the range from EP0INT to EP6INT. • EPnINT: Endpoint n Interrupt This bit is cleared when the interrupt source is serviced. This bit is set when an interrupt is triggered by the endpoint n (UESTAn, UECONn). This triggers a USB interrupt if EPnINTE is one. • UPRSM: Upstream Resume Interrupt This bit is cleared when the UDINTCLR.UPRSMC bit is written to one to acknowledge the interrupt (USB clock inputs must be enabled before). This bit is set when the USBC sends a resume signal called “Upstream Resume”. This triggers a USB interrupt if UPRSME is one. • EORSM: End of Resume Interrupt This bit is cleared when the UDINTCLR.EORSMC bit is written to one to acknowledge the interrupt. This bit is set when the USBC detects a valid “End of Resume” signal initiated by the host. This triggers a USB interrupt if EORSME is one. • WAKEUP: Wakeup Interrupt This bit is cleared when the UDINTCLR.WAKEUPC bit is written to one to acknowledge the interrupt (USB clock inputs must be enabled before) or when the Suspend (SUSP) interrupt bit is set. This bit is set when the USBC is reactivated by a filtered non-idle signal from the lines (not by an upstream resume). This triggers an interrupt if WAKEUPE is one. This interrupt is generated even if the clock is frozen by the FRZCLK bit. • EORST: End of Reset Interrupt This bit is cleared when the UDINTCLR.EORSTC bit is written to one to acknowledge the interrupt. This bit is set when a USB “End of Reset” has been detected. This triggers a USB interrupt if EORSTE is one. • SOF: Start of Frame Interrupt This bit is cleared when the UDINTCLR.SOFC bit is written to one to acknowledge the interrupt. This bit is set when a USB “Start of Frame” PID (SOF) has been detected (every 1 ms). This triggers a USB interrupt if SOFE is one. The FNUM field is updated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - EP8INT(1) EP7INT(1) EP6INT(1) EP5INT(1) EP4INT(1) 15 14 13 12 11 10 9 8 EP3INT(1) EP2INT(1) EP1INT(1) EP0INT - - - - 76543210 - UPRSM EORSM WAKEUP EORST SOF - SUSP 115 32142D–06/2013 ATUC64/128/256L3/4U • SUSP: Suspend Interrupt This bit is cleared when the UDINTCLR.SUSPC bit is written to one to acknowledge the interrupt or when the Wakeup (WAKEUP) interrupt bit is set. This bit is set when a USB “Suspend” idle bus state has been detected for 3 frame periods (J state for 3 ms). This triggers a USB interrupt if SUSPE is one. 116 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.3 Device Global Interrupt Clear Register Register Name: UDINTCLR Access Type: Write-Only Offset: 0x0008 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in UDINT. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - UPRSMC EORSMC WAKEUPC EORSTC SOFC - SUSPC 117 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.4 Device Global Interrupt Set Register Register Name: UDINTSET Access Type: Write-Only Offset: 0x000C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in UDINT, which may be useful for test or debug purposes. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - UPRSMS EORSMS WAKEUPS EORSTS SOFS - SUSPS 118 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.5 Device Global Interrupt Enable Register Register Name: UDINTE Access Type: Read-Only Offset: 0x0010 Reset Value: 0x00000000 Note: 1. EPnINTE bits are within the range from EP0INTE to EP6INTE. 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in UDINTECLR is written to one. A bit in this register is set when the corresponding bit in UDINTESET is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - EP8INTE(1) EP7INTE(1) EP6INTE(1) EP5INTE(1) EP4INTE(1) 15 14 13 12 11 10 9 8 EP3INTE(1) EP2INTE(1) EP1INTE(1) EP0INTE - - - - 76543210 - UPRSME EORSME WAKEUPE EORSTE SOFE - SUSPE 119 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.6 Device Global Interrupt Enable Clear Register Register Name: UDINTECLR Access Type: Write-Only Offset: 0x0014 Reset Value: 0x00000000 Note: 1. EPnINTEC bits are within the range from EP0INTEC to EP6INTEC. Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in UDINTE. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - EP8INTEC(1) EP7INTEC(1) EP6INTEC(1) EP5INTEC(1) EP4INTEC(1) 15 14 13 12 11 10 9 8 EP3INTEC(1) EP2INTEC(1) EP1INTEC(1) EP0INTEC - - - - 76543210 - UPRSMEC EORSMEC WAKEUPEC EORSTEC SOFEC - SUSPEC 120 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.7 Device Global Interrupt Enable Set Register Register Name: UDINTESET Access Type: Write-Only Offset: 0x0018 Reset Value: 0x00000000 Note: 1. EPnINTES bits are within the range from EP0INTES to EP6INTES. Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in UDINTE. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - EP8INTES(1) EP7INTES(1) EP6INTES(1) EP5INTES(1) EP4INTES(1) 15 14 13 12 11 10 9 8 EP3INTES(1) EP2INTES(1) EP1INTES(1) EP0INTES - - - - 76543210 - UPRSMES EORSMES WAKEUPES EORSTES SOFES - SUSPES 121 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.8 Endpoint Enable/Reset Register Register Name: UERST Access Type: Read/Write Offset: 0x001C Reset Value: 0x00000000 • EPENn: Endpoint n Enable Note: 1. EPENn bits are within the range from EPEN0 to EPEN6. Writing a zero to this bit will disable the endpoint n (USB requests will be ignored), and resets the endpoints registers (UECFGn, UESTAn, UECONn), but not the endpoint configuration (EPBK, EPSIZE, EPDIR, EPTYPE). Writing a one to this bit will enable the endpoint n. 0: The endpoint n is disabled. 1: The endpoint n is enabled. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - EPEN8(1) 76543210 EPEN7(1) EPEN6(1) EPEN5(1) EPEN4(1) EPEN3(1) EPEN2(1) EPEN1(1) EPEN0 122 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.9 Device Frame Number Register Register Name: UDFNUM Access Type: Read-Only Offset: 0x0020 Reset Value: 0x00000000 • FNCERR: Frame Number CRC Error This bit is cleared upon receiving a USB reset. This bit is set when a corrupted frame number is received. This bit and the SOF interrupt bit are updated at the same time. • FNUM: Frame Number This field is cleared upon receiving a USB reset. This field contains the 11-bit frame number information, as provided from the last SOF packet. FNUM is updated even if a corrupted SOF is received. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 FNCERR - FNUM[10:5] 76543210 FNUM[4:0] - - - 123 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.10 Endpoint n Configuration Register Register Name: UECFGn, n in [0..6] Access Type: Read/Write Offset: 0x0100 + (n * 0x04) Reset Value: 0x00000000 • EPTYPE: Endpoint Type This field selects the endpoint type: This field is cleared upon receiving a USB reset. • EPDIR: Endpoint Direction 0: The endpoint direction is OUT. 1: The endpoint direction is IN (nor for control endpoints). This bit is cleared upon receiving a USB reset. • EPSIZE: Endpoint Size This field determines the size of each endpoint bank: 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - EPTYPE - - EPDIR 76543210 - EPSIZE - EPBK - - EPTYPE Endpoint Type 0 0 Control 0 1 Isochronous 1 0 Bulk 1 1 Interrupt EPSIZE Endpoint Size 0 0 0 8 bytes 0 0 1 16 bytes 0 1 0 32 bytes 0 1 1 64 bytes 1 0 0 128 bytes 124 32142D–06/2013 ATUC64/128/256L3/4U This field is cleared upon receiving a USB reset (except for the endpoint 0). • EPBK: Endpoint Banks This bit selects the number of banks for the endpoint: 0: single-bank endpoint 1: double-bank endpoint For control endpoints, a single-bank endpoint shall be selected. This field is cleared upon receiving a USB reset (except for the endpoint 0). 1 0 1 256 bytes 1 1 0 512 bytes 1 1 1 1024 bytes EPSIZE Endpoint Size 125 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.11 Endpoint n Status Register Register Name: UESTAn, n in [0..6] Access Type: Read-Only 0x0100 Offset: 0x0130 + (n * 0x04) Reset Value: 0x00000000 • CTRLDIR: Control Direction Writing a zero or a one to this bit has no effect. This bit is cleared after a SETUP packet to indicate that the following packet is an OUT packet. This bit is set after a SETUP packet to indicate that the following packet is an IN packet. • CURRBK: Current Bank This bit is set for non-control endpoints, indicating the current bank: This field may be updated one clock cycle after the RWALL bit changes, so the user should not poll this field as an interrupt bit. • NBUSYBK: Number of Busy Banks This field is set to indicate the number of busy banks: 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - CTRLDIR - 15 14 13 12 11 10 9 8 CURRBK NBUSYBK RAMACERI - DTSEQ 76543210 - STALLEDI/ CRCERRI - NAKINI NAKOUTI RXSTPI/ ERRORFI RXOUTI TXINI CURRBK Current Bank 0 0 Bank0 0 1 Bank1 1 0 Reserved 1 1 Reserved NBUSYBK Number of Busy Banks 0 0 0 (all banks free) 0 11 1 02 1 1 Reserved 126 32142D–06/2013 ATUC64/128/256L3/4U For IN endpoints, this indicates the number of banks filled by the user and ready for IN transfers. When all banks are free an EPnINT interrupt will be triggered if NBUSYBKE is one. For OUT endpoints, this indicates the number of banks filled by OUT transactions from the host. When all banks are busy an EPnINT interrupt will be triggered if NBUSYBKE is one. • RAMACERI: Ram Access Error Interrupt This bit is cleared when the RAMACERIC bit is written to one, acknowledging the interrupt. This bit is set when a RAM access underflow error occurs during an IN data stage. • DTSEQ: Data Toggle Sequence This field is set to indicate the PID of the current bank: For IN transfers, this indicates the data toggle sequence that will be used for the next packet to be sent. For OUT transfers, this value indicates the data toggle sequence of the data received in the current bank. • STALLEDI: STALLed Interrupt This bit is cleared when the STALLEDIC bit is written to one, acknowledging the interrupt. This bit is set when a STALL handshake has been sent and triggers an EPnINT interrupt if STALLEDE is one. • CRCERRI: CRC Error Interrupt This bit is cleared when the CRCERRIC bit is written to one, acknowledging the interrupt. This bit is set when a CRC error has been detected in an isochronous OUT endpoint bank, and triggers an EPnINT interrupt if CRCERRE is one. • NAKINI: NAKed IN Interrupt This bit is cleared when the NAKINIC bit is written to one, acknowledging the interrupt. This bit is set when a NAK handshake has been sent in response to an IN request from the host, and triggers an EPnINT interrupt if NAKINE is one. • NAKOUTI: NAKed OUT Interrupt This bit is cleared when the NAKOUTIC bit is written to one, acknowledging the interrupt. This bit is set when a NAK handshake has been sent in response to an OUT request from the host, and triggers an EPnINT interrupt if NAKOUTE is one. • ERRORFI: Isochronous Error flow Interrupt This bit is cleared when the ERRORFIC bit is written to one, acknowledging the interrupt. This bit is set, for isochronous IN/OUT endpoints, when an errorflow (underflow or overflow) error occurs, and triggers an EPnINT interrupt if ERRORFE is one. An underflow can occur during IN stage if the host attempts to read from an empty bank. A zero-length packet is then automatically sent by the USBC. An overflow can also occur during OUT stage if the host sends a packet while the bank is already full, resulting in the packet being lost. This is typically due to a CPU not being fast enough. This bit is inactive (cleared) for bulk and interrupt IN/OUT endpoints and it means RXSTPI for control endpoints. • RXSTPI: Received SETUP Interrupt This bit is cleared when the RXSTPIC bit is written to one, acknowledging the interrupt and freeing the bank. This bit is set, for control endpoints, to signal that the current bank contains a new valid SETUP packet, and triggers an EPnINT interrupt if RXSTPE is one. This bit is inactive (cleared) for bulk and interrupt IN/OUT endpoints and it means UNDERFI for isochronous IN/OUT endpoints. • RXOUTI: Received OUT Data Interrupt This bit is cleared when the RXOUTIC bit is written to one, acknowledging the interrupt. For control endpoints, it releases the bank. For other endpoint types, the user should clear the FIFOCON bit to free the bank. RXOUTI shall always be cleared before clearing FIFOCON to avoid missing an interrupt. DTSEQ Data Toggle Sequence 0 0 Data0 0 1 Data1 1 X Reserved 127 32142D–06/2013 ATUC64/128/256L3/4U This bit is set, for control endpoints, when the current bank contains a bulk OUT packet (data or status stage). This triggers an EPnINT interrupt if RXOUTE is one. This bit is set for isochronous, bulk and, interrupt OUT endpoints, at the same time as FIFOCON when the current bank is full. This triggers an EPnINT interrupt if RXOUTE is one. This bit is inactive (cleared) for isochronous, bulk and interrupt IN endpoints. • TXINI: Transmitted IN Data Interrupt This bit is cleared when the TXINIC bit is written to one, acknowledging the interrupt. For control endpoints, this will send the packet. For other endpoint types, the user should clear the FIFOCON to allow the USBC to send the data. TXINI shall always be cleared before clearing FIFOCON to avoid missing an interrupt. This bit is set for control endpoints, when the current bank is ready to accept a new IN packet. This triggers an EPnINT interrupt if TXINE is one. This bit is set for isochronous, bulk and interrupt IN endpoints, at the same time as FIFOCON when the current bank is free. This triggers an EPnINT interrupt if TXINE is one. This bit is inactive (cleared) for isochronous, bulk and interrupt OUT endpoints. 128 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.12 Endpoint n Status Clear Register Register Name: UESTAnCLR, n in [0..6] Access Type: Write-Only Offset: 0x0160 + (n * 0x04) Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in UESTA. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - RAMACERIC - - - 76543210 - STALLEDIC/ CRCERRIC - NAKINIC NAKOUTIC RXSTPIC/ ERRORFIC RXOUTIC TXINIC 129 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.13 Endpoint n Status Set Register Register Name: UESTAnSET, n in [0..6] Access Type: Write-Only Offset: 0x0190 + (n * 0x04) Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in UESTA. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - NBUSYBKS RAMACERIS - - 76543210 - STALLEDIS/ CRCERRIS - NAKINIS NAKOUTIS RXSTPIS/ ERRORFIS RXOUTIS TXINIS 130 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.14 Endpoint n Control Register Register Name: UECONn, n in [0..6] Access Type: Read-Only Offset: 0x01C0 + (n * 0x04) Reset Value: 0x00000000 • BUSY0E: Busy Bank0 Enable This bit is cleared when the BUSY0C bit is written to one. This bit is set when the BUSY0ES bit is written to one. This will set the bank 0 as “busy”. All transactions, except SETUP, destined to this bank will be rejected (i.e: NAK token will be answered). • BUSY1E: Busy Bank1 Enable This bit is cleared when the BUSY1C bit is written to one. This bit is set when the BUSY1ES bit is written to one. This will set the bank 1 as “busy”. All transactions, except SETUP, destined to this bank will be rejected (i.e: NAK token will be answered). • STALLRQ: STALL Request This bit is cleared when a new SETUP packet is received or when the STALLRQC bit is written to zero. This bit is set when the STALLRQS bit is written to one, requesting a STALL handshake to be sent to the host. • RSTDT: Reset Data Toggle The data toggle sequence is cleared when the RSTDTS bit is written to one (i.e., Data0 data toggle sequence will be selected for the next sent (IN endpoints) or received (OUT endpoints) packet. This bit is always read as zero. • FIFOCON: FIFO Control For control endpoints: The FIFOCON and RWALL bits are irrelevant. The software shall therefore never use them for these endpoints. When read, their value is always 0. For IN endpoints: This bit is cleared when the FIFOCONC bit is written to one, sending the FIFO data and switching to the next bank. This bit is set simultaneously to TXINI, when the current bank is free. For OUT endpoints: This bit is cleared when the FIFOCONC bit is written to one, freeing the current bank and switching to the next. This bit is set simultaneously to RXINI, when the current bank is full. 31 30 29 28 27 26 25 24 - - - - - - BUSY1E BUSY0E 23 22 21 20 19 18 17 16 - - - - STALLRQ RSTDT - - 15 14 13 12 11 10 9 8 - FIFOCON KILLBK NBUSYBKE RAMACERE - - 76543210 - STALLEDE/ CRCERRE - NAKINE NAKOUTE RXSTPE/ ERRORFE RXOUTE TXINE 131 32142D–06/2013 ATUC64/128/256L3/4U • KILLBK: Kill IN Bank This bit is cleared by hardware after the completion of the “kill packet procedure”. This bit is set when the KILLBKS bit is written to one, killing the last written bank. The user shall wait for this bit to be cleared before trying to process another IN packet. Caution: The bank is cleared when the “kill packet” procedure is completed by the USBC core: If the bank is really killed, the NBUSYBK field is decremented. If the bank sent instead of killed (IN transfer), the NBUSYBK field is decremented and the TXINI flag is set. This specific case can occur if an IN token comes while the user tries to kill the bank. Note: If two banks are ready to be sent, the above specific case will not occur, since the first bank is sent (IN transfer) while the last bank is killed. • NBUSYBKE: Number of Busy Banks Interrupt Enable This bit is cleared when the NBUSYBKEC bit is written to zero, disabling the Number of Busy Banks interrupt (NBUSYBK). This bit is set when the NBUSYBKES bit is written to one, enabling the Number of Busy Banks interrupt (NBUSYBK). • RAMACERE: RAMACER Interrupt Enable This bit is cleared when the RAMACEREC bit is written to one, disabling the RAMACER interrupt (RAMACERI). This bit is set when the RAMACERES bit is written to one, enabling the RAMACER interrupt (RAMACERI). • STALLEDE: STALLed Interrupt Enable This bit is cleared when the STALLEDEC bit is written to one, disabling the STALLed interrupt (STALLEDI). This bit is set when the STALLEDES bit is written to one, enabling the STALLed interrupt (STALLEDI). • CRCERRE: CRC Error Interrupt Enable This bit is cleared when the CRCERREC bit is written to one, disabling the CRC Error interrupt (CRCERRI). This bit is set when the CRCERRES bit is written to one, enabling the CRC Error interrupt (CRCERRI). • NAKINE: NAKed IN Interrupt Enable This bit is cleared when the NAKINEC bit is written to one, disabling the NAKed IN interrupt (NAKINI). This bit is set when the NAKINES bit is written to one, enabling the NAKed IN interrupt (NAKINI). • NAKOUTE: NAKed OUT Interrupt Enable This bit is cleared when the NAKOUTEC bit is written to one, disabling the NAKed OUT interrupt (NAKOUTI). This bit is set when the NAKOUTES bit is written to one, enabling the NAKed OUT interrupt (NAKOUTI). • RXSTPE: Received SETUP Interrupt Enable This bit is cleared when the RXSTPEC bit is written to one, disabling the Received SETUP interrupt (RXSTPI). This bit is set when the RXSTPES bit is written to one, enabling the Received SETUP interrupt (RXSTPI). • ERRORFE: Errorflow Interrupt Enable This bit is cleared when the ERRORFEC bit is written to one, disabling the Underflow interrupt (ERRORFI). This bit is set when the ERRORFES bit is written to one, enabling the Underflow interrupt (ERRORFI). • RXOUTE: Received OUT Data Interrupt Enable This bit is cleared when the RXOUTEC bit is written to one, disabling the Received OUT Data interrupt (RXOUT). This bit is set when the RXOUTES bit is written to one, enabling the Received OUT Data interrupt (RXOUT). • TXINE: Transmitted IN Data Interrupt Enable This bit is cleared when the TXINEC bit is written to one, disabling the Transmitted IN Data interrupt (TXINI). This bit is set when the TXINES bit is written to one, enabling the Transmitted IN Data interrupt (TXINI). 132 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.15 Endpoint n Control Clear Register Register Name: UECONnCLR, n in [0..6] Access Type: Write-Only Offset: 0x0220 + (n * 0x04) Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in UECONn. These bits always read as zero. 31 30 29 28 27 26 25 24 - - - - - - BUSY1EC BUSY0EC 23 22 21 20 19 18 17 16 - - - - STALLRQC - - - 15 14 13 12 11 10 9 8 - FIFOCONC - NBUSYBKEC RAMACEREC - - - 76543210 - STALLEDEC/ CRCERREC - NAKINEC NAKOUTEC RXSTPEC/ ERRORFEC RXOUTEC TXINEC 133 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.16 Endpoint n Control Set Register Register Name: UECONnSET, n in [0..6] Access Type: Write-Only Offset: 0x01F0 + (n * 0x04) Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in UECONn. These bits always read as zero. • • 31 30 29 28 27 26 25 24 - - - - - - BUSY1ES BUSY0ES 23 22 21 20 19 18 17 16 - - - - STALLRQS RSTDTS - - 15 14 13 12 11 10 9 8 - - KILLBKS NBUSYBKES RAMACERES --- 76543210 - STALLEDES/ CRCERRES - NAKINES NAKOUTES RXSTPES/ ERRORFES RXOUTES TXINES 134 32142D–06/2013 ATUC64/128/256L3/4U 8.8 Module Configuration The specific configuration for each USBC instance is listed in the following tables. The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 8-6. USBC Clocks Clock Name Description CLK_USBC_PB Clock for the USBC PB interface CLK_USBC_HSB Clock for the USBC HSB interface GCLK_USBC The generic clock used for the USBC is GCLK7 Table 8-7. Register Reset Values Register Reset Value UVERS 0x00000200 UFEATURES 0x00000007 UADDRSIZE 0x00001000 UNAME1 0x48555342 UNAME2 0x00000000 135 32142D–06/2013 ATUC64/128/256L3/4U 9. Flash Controller (FLASHCDW) Rev: 1.2.0.0 9.1 Features • Controls on-chip flash memory • Supports 0 and 1 wait state bus access • Buffers reducing penalty of wait state in sequential code or loops • Allows interleaved burst reads for systems with one wait state, outputting one 32-bit word per clock cycle for sequential reads • Secure State for supporting FlashVault technology • 32-bit HSB interface for reads from flash and writes to page buffer • 32-bit PB interface for issuing commands to and configuration of the controller • Flash memory is divided into 16 regions can be individually protected or unprotected • Additional protection of the Boot Loader pages • Supports reads and writes of general-purpose Non Volatile Memory (NVM) bits • Supports reads and writes of additional NVM pages • Supports device protection through a security bit • Dedicated command for chip-erase, first erasing all on-chip volatile memories before erasing flash and clearing security bit 9.2 Overview The Flash Controller (FLASHCDW) interfaces the on-chip flash memory with the 32-bit internal HSB bus. The controller manages the reading, writing, erasing, locking, and unlocking sequences. 9.3 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 9.3.1 Power Management If the CPU enters a sleep mode that disables clocks used by the FLASHCDW, the FLASHCDW will stop functioning and resume operation after the system wakes up from sleep mode. 9.3.2 Clocks The FLASHCDW has two bus clocks connected: One High Speed Bus clock (CLK_FLASHCDW_HSB) and one Peripheral Bus clock (CLK_FLASHCDW_PB). These clocks are generated by the Power Manager. Both clocks are enabled at reset, and can be disabled by writing to the Power Manager. The user has to ensure that CLK_FLASHCDW_HSB is not turned off before reading the flash or writing the pagebuffer and that CLK_FLASHCDW_PB is not turned off before accessing the FLASHCDW configuration and control registers. Failing to do so may deadlock the bus. 9.3.3 Interrupts The FLASHCDW interrupt request lines are connected to the interrupt controller. Using the FLASHCDW interrupts requires the interrupt controller to be programmed first. 136 32142D–06/2013 ATUC64/128/256L3/4U 9.3.4 Debug Operation When an external debugger forces the CPU into debug mode, the FLASHCDW continues normal operation. If the FLASHCDW is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 9.4 Functional Description 9.4.1 Bus Interfaces The FLASHCDW has two bus interfaces, one High Speed Bus (HSB) interface for reads from the flash memory and writes to the page buffer, and one Peripheral Bus (PB) interface for issuing commands and reading status from the controller. 9.4.2 Memory Organization The flash memory is divided into a set of pages. A page is the basic unit addressed when programming the flash. A page consists of several words. The pages are grouped into 16 regions of equal size. Each of these regions can be locked by a dedicated fuse bit, protecting it from accidental modification. • p pages (FLASH_P) • w bytes in each page and in the page buffer (FLASH_W) • pw bytes in total (FLASH_PW) • f general-purpose fuse bits (FLASH_F), used as region lock bits and for other device-specific purposes • 1 security fuse bit • 1 User page 9.4.3 User Page The User page is an additional page, outside the regular flash array, that can be used to store various data, such as calibration data and serial numbers. This page is not erased by regular chip erase. The User page can only be written and erased by a special set of commands. Read accesses to the User page are performed just as any other read accesses to the flash. The address map of the User page is given in Figure 9-1 on page 138. 9.4.4 Read Operations The on-chip flash memory is typically used for storing instructions to be executed by the CPU. The CPU will address instructions using the HSB bus, and the FLASHCDW will access the flash memory and return the addressed 32-bit word. In systems where the HSB clock period is slower than the access time of the flash memory, the FLASHCDW can operate in 0 wait state mode, and output one 32-bit word on the bus per clock cycle. If the clock frequency allows, the user should use 0 wait state mode, because this gives the highest performance as no stall cycles are encountered. The FLASHCDW can also operate in systems where the HSB bus clock period is faster than the access speed of the flash memory. Wait state support and a read granularity of 64 bits ensure efficiency in such systems. Performance for systems with high clock frequency is increased since the internal read word width of the flash memory is 64 bits. When a 32-bit word is to be addressed, the word itself and 137 32142D–06/2013 ATUC64/128/256L3/4U also the other word in the same 64-bit location is read. The first word is output on the bus, and the other word is put into an internal buffer. If a read to a sequential address is to be performed in the next cycle, the buffered word is output on the bus, while the next 64-bit location is read from the flash memory. Thus, latency in 1 wait state mode is hidden for sequential fetches. The programmer can select the wait states required by writing to the FWS field in the Flash Control Register (FCR). It is the responsibility of the programmer to select a number of wait states compatible with the clock frequency and timing characteristics of the flash memory. In 0ws mode, no wait states are encountered on any flash read operations. In 1 ws mode, one stall cycle is encountered on the first access in a single or burst transfer. In 1 ws mode, if the first access in a burst access is to an address that is not 64-bit aligned, an additional stall cycle is also encountered when reading the second word in the burst. All subsequent words in the burst are accessed without any stall cycles. The Flash Controller provides two sets of buffers that can be enabled in order to speed up instruction fetching. These buffers can be enabled by writing a one to the FCR.SEQBUF and FCR.BRBUF bits. The SEQBUF bit enables buffering hardware optimizing sequential instruction fetches. The BRBUF bit enables buffering hardware optimizing tight inner loops. These buffers are never used when the flash is in 0 wait state mode. Usually, both these buffers should be enabled when operating in 1 wait state mode. Some users requiring absolute cycle determinism may want to keep the buffers disabled. The Flash Controller address space is displayed in Figure 9-1. The memory space between address pw and the User page is reserved, and reading addresses in this space returns an undefined result. The User page is permanently mapped to an offset of 0x00800000 from the start address of the flash memory. Table 9-1. User Page Addresses Memory type Start address, byte sized Size Main array 0 pw bytes User 0x00800000 w bytes 138 32142D–06/2013 ATUC64/128/256L3/4U Figure 9-1. Memory Map for the Flash Memories 9.4.5 High Speed Read Mode The flash provides a High Speed Read Mode, offering slightly higher flash read speed at the cost of higher power consumption. Two dedicated commands, High Speed Read Mode Enable (HSEN) and High Speed Read Mode Disable (HSDIS) control the speed mode. The High Speed Mode (HSMODE) bit in the Flash Status Register (FSR) shows which mode the flash is in. After reset, the High Speed Mode is disabled, and must be manually enabled if the user wants to. Refer to the Electrical Characteristics chapter at the end of this datasheet for details on the maximum clock frequencies in Normal and High Speed Read Mode. 0 pw Reserved Flash data array Reserved User Page Flash with User Page 0x0080 0000 All addresses are byte addresses Flash base address Offset from base address 139 32142D–06/2013 ATUC64/128/256L3/4U Figure 9-2. High Speed Mode 9.4.6 Quick Page Read A dedicated command, Quick Page Read (QPR), is provided to read all words in an addressed page. All bits in all words in this page are AND’ed together, returning a 1-bit result. This result is placed in the Quick Page Read Result (QPRR) bit in Flash Status Register (FSR). The QPR command is useful to check that a page is in an erased state. The QPR instruction is much faster than performing the erased-page check using a regular software subroutine. 9.4.7 Quick User Page Read A dedicated command, Quick User Page Read (QPRUP), is provided to read all words in the user page. All bits in all words in this page are AND’ed together, returning a 1-bit result. This result is placed in the Quick Page Read Result (QPRR) bit in Flash Status Register (FSR). The QPRUP command is useful to check that a page is in an erased state. The QPRUP instruction is much faster than performing the erased-page check using a regular software subroutine. 9.4.8 Page Buffer Operations The flash memory has a write and erase granularity of one page; data is written and erased in chunks of one page. When programming a page, the user must first write the new data into the Page Buffer. The contents of the entire Page Buffer is copied into the desired page in flash memory when the user issues the Write Page command, Refer to Section 9.5.1 on page 141. In order to program data into flash page Y, write the desired data to locations Y0 to Y31 in the regular flash memory map. Writing to an address A in the flash memory map will not update the flash memory, but will instead update location A%32 in the page buffer. The PAGEN field in the Flash Command (FCMD) register will at the same time be updated with the value A/32. Frequency Frequency limit for 0 wait state operation Normal High Speed mode 1 wait state 0 wait state 140 32142D–06/2013 ATUC64/128/256L3/4U Figure 9-3. Mapping from Page Buffer to Flash Internally, the flash memory stores data in 64-bit doublewords. Therefore, the native data size of the Page Buffer is also a 64-bit doubleword. All locations shown in Figure 9-3 are therefore doubleword locations. Since the HSB bus only has a 32-bit data width, two 32-bit HSB transfers must be performed to write a 64-bit doubleword into the Page Buffer. The FLASHCDW has logic to combine two 32-bit HSB transfers into a 64-bit data before writing this 64-bit data into the Page Buffer. This logic requires the word with the low address to be written to the HSB bus before the word with the high address. To exemplify, to write a 64-bit value to doubleword X0 residing in page X, first write a 32-bit word to the byte address pointing to address X0, thereafter write a word to the byte address pointing to address (X0+4). The page buffer is word-addressable and should only be written with aligned word transfers, never with byte or halfword transfers. The page buffer can not be read. The page buffer is also used for writes to the User page. Page buffer write operations are performed with 4 wait states. Any accesses attempted to the FLASHCDW on the HSB bus during these cycles will be automatically stalled. Writing to the page buffer can only change page buffer bits from one to zero, i.e. writing 0xAAAAAAAA to a page buffer location that has the value 0x00000000 will not change the page buffer value. The only way to change a bit from zero to one is to erase the entire page buffer with the Clear Page Buffer command. Z3 Z2 Z1 Z0 Z7 Z6 Z5 Z4 Z11 Z10 Z9 Z8 Z15 Z14 Z13 Z12 Z19 Z18 Z17 Z16 Z23 Z22 Z21 Z20 Z27 Z26 Z25 Z24 Z31 Z30 Z29 Z28 Y3 Y2 Y1 Y0 Y7 Y6 Y5 Y4 Y11 Y10 Y9 Y8 Y15 Y14 Y13 Y12 Y19 Y18 Y17 Y16 Y23 Y22 Y21 Y20 Y27 Y26 Y25 Y24 Y31 Y30 Y29 Y28 X3 X2 X1 X0 X7 X6 X5 X4 X11 X10 X9 X8 X15 X14 X13 X12 X19 X18 X17 X16 X23 X22 X21 X20 X27 X26 X25 X24 X31 X30 X29 X28 3 2 1 0 7 6 5 4 11 10 9 8 15 14 13 12 19 18 17 16 23 22 21 20 27 26 25 24 31 30 29 28 Page X Page Y Page Z Page Buffer 64-bit data Flash All locations are doubleword locations 141 32142D–06/2013 ATUC64/128/256L3/4U The page buffer is not automatically reset after a page write. The programmer should do this manually by issuing the Clear Page Buffer flash command. This can be done after a page write, or before the page buffer is loaded with data to be stored to the flash page. 9.5 Flash Commands The FLASHCDW offers a command set to manage programming of the flash memory, locking and unlocking of regions, and full flash erasing. See Section 9.8.2 for a complete list of commands. To run a command, the CMD field in the Flash Command Register (FCMD) has to be written with the command number. As soon as the FCMD register is written, the FRDY bit in the Flash Status Register (FSR) is automatically cleared. Once the current command is complete, the FSR.FRDY bit is automatically set. If an interrupt has been enabled by writing a one to FCR.FRDY, the interrupt request line of the Flash Controller is activated. All flash commands except for Quick Page Read (QPR) and Quick User Page Read (QPRUP) will generate an interrupt request upon completion if FCR.FRDY is one. Any HSB bus transfers attempting to read flash memory when the FLASHCDW is busy executing a flash command will be stalled, and allowed to continue when the flash command is complete. After a command has been written to FCMD, the programming algorithm should wait until the command has been executed before attempting to read instructions or data from the flash or writing to the page buffer, as the flash will be busy. The waiting can be performed either by polling the Flash Status Register (FSR) or by waiting for the flash ready interrupt. The command written to FCMD is initiated on the first clock cycle where the HSB bus interface in FLASHCDW is IDLE. The user must make sure that the access pattern to the FLASHCDW HSB interface contains an IDLE cycle so that the command is allowed to start. Make sure that no bus masters such as DMA controllers are performing endless burst transfers from the flash. Also, make sure that the CPU does not perform endless burst transfers from flash. This is done by letting the CPU enter sleep mode after writing to FCMD, or by polling FSR for command completion. This polling will result in an access pattern with IDLE HSB cycles. All the commands are protected by the same keyword, which has to be written in the eight highest bits of the FCMD register. Writing FCMD with data that does not contain the correct key and/or with an invalid command has no effect on the flash memory; however, the PROGE bit is set in the Flash Status Register (FSR). This bit is automatically cleared by a read access to the FSR register. Writing a command to FCMD while another command is being executed has no effect on the flash memory; however, the PROGE bit is set in the Flash Status Register (FSR). This bit is automatically cleared by a read access to the FSR register. If the current command writes or erases a page in a locked region, or a page protected by the BOOTPROT fuses, the command has no effect on the flash memory; however, the LOCKE bit is set in the FSR register. This bit is automatically cleared by a read access to the FSR register. 9.5.1 Write/Erase Page Operation Flash technology requires that an erase must be done before programming. The entire flash can be erased by an Erase All command. Alternatively, pages can be individually erased by the Erase Page command. The User page can be written and erased using the mechanisms described in this chapter. 142 32142D–06/2013 ATUC64/128/256L3/4U After programming, the page can be locked to prevent miscellaneous write or erase sequences. Locking is performed on a per-region basis, so locking a region locks all pages inside the region. Additional protection is provided for the lowermost address space of the flash. This address space is allocated for the Boot Loader, and is protected both by the lock bit(s) corresponding to this address space, and the BOOTPROT[2:0] fuses. Data to be written is stored in an internal buffer called the page buffer. The page buffer contains w words. The page buffer wraps around within the internal memory area address space and appears to be repeated by the number of pages in it. Writing of 8-bit and 16-bit data to the page buffer is not allowed and may lead to unpredictable data corruption. Data must be written to the page buffer before the programming command is written to the Flash Command Register (FCMD). The sequence is as follows: • Reset the page buffer with the Clear Page Buffer command. • Fill the page buffer with the desired contents as described in Section 9.4.8 on page 139. • Programming starts as soon as the programming key and the programming command are written to the Flash Command Register. The PAGEN field in the Flash Command Register (FCMD) must contain the address of the page to write. PAGEN is automatically updated when writing to the page buffer, but can also be written to directly. The FRDY bit in the Flash Status Register (FSR) is automatically cleared when the page write operation starts. • When programming is completed, the FRDY bit in the Flash Status Register (FSR) is set. If an interrupt was enabled by writing FCR.FRDY to one, an interrupt request is generated. Two errors can be detected in the FSR register after a programming sequence: • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. • Lock Error: Can have two different causes: – The page to be programmed belongs to a locked region. A command must be executed to unlock the corresponding region before programming can start. – A bus master without secure status attempted to program a page requiring secure privileges. 9.5.2 Erase All Operation The entire memory is erased if the Erase All command (EA) is written to the Flash Command Register (FCMD). Erase All erases all bits in the flash array. The User page is not erased. All flash memory locations, the general-purpose fuse bits, and the security bit are erased (reset to 0xFF) after an Erase All. The EA command also ensures that all volatile memories, such as register file and RAMs, are erased before the security bit is erased. Erase All operation is allowed only if no regions are locked, and the BOOTPROT fuses are configured with a BOOTPROT region size of 0. Thus, if at least one region is locked, the bit LOCKE in FSR is set and the command is cancelled. If the LOCKE bit in FCR is one, an interrupt request is set generated. When the command is complete, the FRDY bit in the Flash Status Register (FSR) is set. If an interrupt has been enabled by writing FCR.FRDY to one, an interrupt request is generated. Two errors can be detected in the FSR register after issuing the command: 143 32142D–06/2013 ATUC64/128/256L3/4U • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. • Lock Error: At least one lock region is protected, or BOOTPROT is different from 0. The erase command has been aborted and no page has been erased. A “Unlock region containing given page” (UP) command must be executed to unlock any locked regions. 9.5.3 Region Lock Bits The flash memory has p pages, and these pages are grouped into 16 lock regions, each region containing p/16 pages. Each region has a dedicated lock bit preventing writing and erasing pages in the region. After production, the device may have some regions locked. These locked regions are reserved for a boot or default application. Locked regions can be unlocked to be erased and then programmed with another application or other data. To lock or unlock a region, the commands Lock Region Containing Page (LP) and Unlock Region Containing Page (UP) are provided. Writing one of these commands, together with the number of the page whose region should be locked/unlocked, performs the desired operation. One error can be detected in the FSR register after issuing the command: • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. The lock bits are implemented using the lowest 16 general-purpose fuse bits. This means that lock bits can also be set/cleared using the commands for writing/erasing general-purpose fuse bits, see Section 9.6. The general-purpose bit being in an erased (1) state means that the region is unlocked. The lowermost pages in the flash can additionally be protected by the BOOTPROT fuses, see Section 9.6. 9.6 General-purpose Fuse Bits The flash memory has a number of general-purpose fuse bits that the application programmer can use freely. The fuse bits can be written and erased using dedicated commands, and read 144 32142D–06/2013 ATUC64/128/256L3/4U through a dedicated Peripheral Bus address. Some of the general-purpose fuse bits are reserved for special purposes, and should not be used for other functions: The BOOTPROT fuses protects the following address space for the Boot Loader: Table 9-2. General-purpose Fuses with Special Functions GeneralPurpose fuse number Name Usage 15:0 LOCK Region lock bits. 16 EPFL External Privileged Fetch Lock. Used to prevent the CPU from fetching instructions from external memories when in privileged mode. This bit can only be changed when the security bit is cleared. The address range corresponding to external memories is device-specific, and not known to the Flash Controller. This fuse bit is simply routed out of the CPU or bus system, the Flash Controller does not treat this fuse in any special way, except that it can not be altered when the security bit is set. If the security bit is set, only an external JTAG or aWire Chip Erase can clear EPFL. No internal commands can alter EPFL if the security bit is set. When the fuse is erased (i.e. "1"), the CPU can execute instructions fetched from external memories. When the fuse is programmed (i.e. "0"), instructions can not be executed from external memories. This fuse has no effect in devices with no External Memory Interface (EBI). 19:17 BOOTPROT Used to select one of eight different bootloader sizes. Pages included in the bootloader area can not be erased or programmed except by a JTAG or aWire chip erase. BOOTPROT can only be changed when the security bit is cleared. If the security bit is set, only an external JTAG or aWire Chip Erase can clear BOOTPROT, and thereby allow the pages protected by BOOTPROT to be programmed. No internal commands can alter BOOTPROT or the pages protected by BOOTPROT if the security bit is set. 21:20 SECURE Used to configure secure state and secure state debug capabilities. Decoded into SSE and SSDE signals as shown in Table 9-5. Refer to the AVR32 Architecture Manual and the AVR32UC Technical Reference Manual for more details on SSE and SSDE. 22 UPROT If programmed (i.e. “0”), the JTAG USER PROTECTION feature is enabled. If this fuse is programmed some HSB addresses will be accessible by JTAG access even if the flash security fuse is programmed. Refer to the JTAG documentation for more information on this functionality. This bit can only be changed when the security bit is cleared. 145 32142D–06/2013 ATUC64/128/256L3/4U The SECURE fuses have the following functionality: To erase or write a general-purpose fuse bit, the commands Write General-Purpose Fuse Bit (WGPB) and Erase General-Purpose Fuse Bit (EGPB) are provided. Writing one of these commands, together with the number of the fuse to write/erase, performs the desired operation. An entire General-Purpose Fuse byte can be written at a time by using the Program GP Fuse Byte (PGPFB) instruction. A PGPFB to GP fuse byte 2 is not allowed if the flash is locked by the security bit. The PFB command is issued with a parameter in the PAGEN field: • PAGEN[2:0] - byte to write • PAGEN[10:3] - Fuse value to write All general-purpose fuses can be erased by the Erase All General-Purpose fuses (EAGP) command. An EAGP command is not allowed if the flash is locked by the security bit. Two errors can be detected in the FSR register after issuing these commands: • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. • Lock Error: – A write or erase of the BOOTPROT or EPFL or UPROT fuse bits was attempted while the flash is locked by the security bit. – A write or erase of the SECURE fuse bits was attempted when SECURE mode was enabled. The lock bits are implemented using the lowest 16 general-purpose fuse bits. This means that the 16 lowest general-purpose fuse bits can also be written/erased using the commands for locking/unlocking regions, see Section 9.5.3. Table 9-3. Boot Loader Area Specified by BOOTPROT BOOTPROT Pages protected by BOOTPROT Size of protected memory 7 None 0 6 0-1 1Kbyte 5 0-3 2Kbyte 4 0-7 4Kbyte 3 0-15 8Kbyte 2 0-31 16Kbyte 1 0-63 32Kbyte 0 0-127 64Kbyte Table 9-5. Secure State Configuration SECURE Functionality SSE SSDE 00 Secure state disabled 0 0 01 Secure enabled, secure state debug enabled 1 1 10 Secure enabled, secure state debug disabled 1 0 11 Secure state disabled 0 0 146 32142D–06/2013 ATUC64/128/256L3/4U 9.7 Security Bit The security bit allows the entire device to be locked from external JTAG, aWire, or other debug access for code security. The security bit can be written by a dedicated command, Set Security Bit (SSB). Once set, the only way to clear the security bit is through the JTAG or aWire Chip Erase command. Once the security bit is set, the following Flash Controller commands will be unavailable and return a lock error if attempted: • Write General-Purpose Fuse Bit (WGPB) to BOOTPROT or EPFL fuses • Erase General-Purpose Fuse Bit (EGPB) to BOOTPROT or EPFL fuses • Program General-Purpose Fuse Byte (PGPFB) of fuse byte 2 • Erase All General-Purpose Fuses (EAGPF) One error can be detected in the FSR register after issuing the command: • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. 147 32142D–06/2013 ATUC64/128/256L3/4U 9.8 User Interface Note: 1. The value of the Lock bits depend on their programmed state. All other bits in FSR are 0. 2. All bits in FGPRHI/LO are dependent on the programmed state of the fuses they map to. Any bits in these registers not mapped to a fuse read as 0. 3. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 9-6. FLASHCDW Register Memory Map Offset Register Register Name Access Reset 0x00 Flash Control Register FCR Read/Write 0x00000000 0x04 Flash Command Register FCMD Read/Write 0x00000000 0x08 Flash Status Register FSR Read-only -(1) 0x0C Flash Parameter Register FPR Read-only -(3) 0x10 Flash Version Register FVR Read-only -(3) 0x14 Flash General Purpose Fuse Register Hi FGPFRHI Read-only -(2) 0x18 Flash General Purpose Fuse Register Lo FGPFRLO Read-only -(2) 148 32142D–06/2013 ATUC64/128/256L3/4U 9.8.1 Flash Control Register Name: FCR Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • BRBUF: Branch Target Instruction Buffer Enable 0: The Branch Target Instruction Buffer is disabled. 1: The Branch Target Instruction Buffer is enabled. • SEQBUF: Sequential Instruction Fetch Buffer Enable 0: The Sequential Instruction Fetch Buffer is disabled. 1: The Sequential Instruction Fetch Buffer is enabled. • FWS: Flash Wait State 0: The flash is read with 0 wait states. 1: The flash is read with 1 wait state. • PROGE: Programming Error Interrupt Enable 0: Programming Error does not generate an interrupt request. 1: Programming Error generates an interrupt request. • LOCKE: Lock Error Interrupt Enable 0: Lock Error does not generate an interrupt request. 1: Lock Error generates an interrupt request. • FRDY: Flash Ready Interrupt Enable 0: Flash Ready does not generate an interrupt request. 1: Flash Ready generates an interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - BRBUF SEQBUF - 76543210 - FWS - - PROGE LOCKE - FRDY 149 32142D–06/2013 ATUC64/128/256L3/4U 9.8.2 Flash Command Register Name: FCMD Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 The FCMD can not be written if the flash is in the process of performing a flash command. Doing so will cause the FCR write to be ignored, and the PROGE bit in FSR to be set. • KEY: Write protection key This field should be written with the value 0xA5 to enable the command defined by the bits of the register. If the field is written with a different value, the write is not performed and no action is started. This field always reads as 0. • PAGEN: Page number The PAGEN field is used to address a page or fuse bit for certain operations. In order to simplify programming, the PAGEN field is automatically updated every time the page buffer is written to. For every page buffer write, the PAGEN field is updated with the page number of the address being written to. Hardware automatically masks writes to the PAGEN field so that only bits representing valid page numbers can be written, all other bits in PAGEN are always 0. As an example, in a flash with 1024 pages (page 0 - page 1023), bits 15:10 will always be 0. 31 30 29 28 27 26 25 24 KEY 23 22 21 20 19 18 17 16 PAGEN [15:8] 15 14 13 12 11 10 9 8 PAGEN [7:0] 76543210 - - CMD Table 9-7. Semantic of PAGEN field in different commands Command PAGEN description No operation Not used Write Page The number of the page to write Clear Page Buffer Not used Lock region containing given Page Page number whose region should be locked Unlock region containing given Page Page number whose region should be unlocked Erase All Not used Write General-Purpose Fuse Bit GPFUSE # Erase General-Purpose Fuse Bit GPFUSE # Set Security Bit Not used 150 32142D–06/2013 ATUC64/128/256L3/4U • CMD: Command This field defines the flash command. Issuing any unused command will cause the Programming Error bit in FSR to be set, and the corresponding interrupt to be requested if the PROGE bit in FCR is one. Program GP Fuse Byte WriteData[7:0], ByteAddress[2:0] Erase All GP Fuses Not used Quick Page Read Page number Write User Page Not used Erase User Page Not used Quick Page Read User Page Not used High Speed Mode Enable Not used High Speed Mode Disable Not used Table 9-8. Set of commands Command Value Mnemonic No operation 0 NOP Write Page 1 WP Erase Page 2 EP Clear Page Buffer 3 CPB Lock region containing given Page 4 LP Unlock region containing given Page 5 UP Erase All 6 EA Write General-Purpose Fuse Bit 7 WGPB Erase General-Purpose Fuse Bit 8 EGPB Set Security Bit 9 SSB Program GP Fuse Byte 10 PGPFB Erase All GPFuses 11 EAGPF Quick Page Read 12 QPR Write User Page 13 WUP Erase User Page 14 EUP Quick Page Read User Page 15 QPRUP High Speed Mode Enable 16 HSEN High Speed Mode Disable 17 HSDIS RESERVED 16-31 Table 9-7. Semantic of PAGEN field in different commands Command PAGEN description 151 32142D–06/2013 ATUC64/128/256L3/4U 9.8.3 Flash Status Register Name: FSR Access Type: Read-only Offset: 0x08 Reset Value: 0x00000000 • LOCKx: Lock Region x Lock Status 0: The corresponding lock region is not locked. 1: The corresponding lock region is locked. • HSMODE: High-Speed Mode 0: High-speed mode disabled. 1: High-speed mode enabled. • QPRR: Quick Page Read Result 0: The result is zero, i.e. the page is not erased. 1: The result is one, i.e. the page is erased. • SECURITY: Security Bit Status 0: The security bit is inactive. 1: The security bit is active. • PROGE: Programming Error Status Automatically cleared when FSR is read. 0: No invalid commands and no bad keywords were written in the Flash Command Register FCMD. 1: An invalid command and/or a bad keyword was/were written in the Flash Command Register FCMD. • LOCKE: Lock Error Status Automatically cleared when FSR is read. 0: No programming of at least one locked lock region has happened since the last read of FSR. 1: Programming of at least one locked lock region has happened since the last read of FSR. • FRDY: Flash Ready Status 0: The Flash Controller is busy and the application must wait before running a new command. 1: The Flash Controller is ready to run a new command. 31 30 29 28 27 26 25 24 LOCK15 LOCK14 LOCK13 LOCK12 LOCK11 LOCK10 LOCK9 LOCK8 23 22 21 20 19 18 17 16 LOCK7 LOCK6 LOCK5 LOCK4 LOCK3 LOCK2 LOCK1 LOCK0 15 14 13 12 11 10 9 8 -------- 76543210 - HSMODE QPRR SECURITY PROGE LOCKE - FRDY 152 32142D–06/2013 ATUC64/128/256L3/4U 9.8.4 Flash Parameter Register Name: FPR Access Type: Read-only Offset: 0x0C Reset Value: - • PSZ: Page Size The size of each flash page. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - PSZ 76543210 - - - - FSZ Table 9-9. Flash Page Size PSZ Page Size 0 32 Byte 1 64 Byte 2 128 Byte 3 256 Byte 4 512 Byte 5 1024 Byte 6 2048 Byte 7 4096 Byte 153 32142D–06/2013 ATUC64/128/256L3/4U • FSZ: Flash Size The size of the flash. Not all device families will provide all flash sizes indicated in the table. Table 9-10. Flash Size FSZ Flash Size FSZ Flash Size 0 4 Kbyte 8 192 Kbyte 1 8 Kbyte 9 256 Kbyte 2 16 Kbyte 10 384 Kbyte 3 32 Kbyte 11 512 Kbyte 4 48 Kbyte 12 768 Kbyte 5 64 Kbyte 13 1024 Kbyte 6 96 Kbyte 14 2048 Kbyte 7 128 Kbyte 15 Reserved 154 32142D–06/2013 ATUC64/128/256L3/4U 9.8.5 Flash Version Register Name: FVR Access Type: Read-only Offset: 0x10 Reset Value: 0x00000000 • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 155 32142D–06/2013 ATUC64/128/256L3/4U 9.8.6 Flash General Purpose Fuse Register High Name: FGPFRHI Access Type: Read-only Offset: 0x14 Reset Value: - This register is only used in systems with more than 32 GP fuses. • GPFxx: General Purpose Fuse xx 0: The fuse has a written/programmed state. 1: The fuse has an erased state. 31 30 29 28 27 26 25 24 GPF63 GPF62 GPF61 GPF60 GPF59 GPF58 GPF57 GPF56 23 22 21 20 19 18 17 16 GPF55 GPF54 GPF53 GPF52 GPF51 GPF50 GPF49 GPF48 15 14 13 12 11 10 9 8 GPF47 GPF46 GPF45 GPF44 GPF43 GPF42 GPF41 GPF40 76543210 GPF39 GPF38 GPF37 GPF36 GPF35 GPF34 GPF33 GPF32 156 32142D–06/2013 ATUC64/128/256L3/4U 9.8.7 Flash General Purpose Fuse Register Low Name: FGPFRLO Access Type: Read-only Offset: 0x18 Reset Value: - • GPFxx: General Purpose Fuse xx 0: The fuse has a written/programmed state. 1: The fuse has an erased state. 31 30 29 28 27 26 25 24 GPF31 GPF30 GPF29 GPF28 GPF27 GPF26 GPF25 GPF24 23 22 21 20 19 18 17 16 GPF23 GPF22 GPF21 GPF20 GPF19 GPF18 GPF17 GPF16 15 14 13 12 11 10 9 8 GPF15 GPF14 GPF13 GPF12 GPF11 GPF10 GPF09 GPF08 76543210 GPF07 GPF06 GPF05 GPF04 GPF03 GPF02 GPF01 GPF00 157 32142D–06/2013 ATUC64/128/256L3/4U 9.9 Fuse Settings The flash contains 32 general purpose fuses. These 32 fuses can be found in the Flash General Purpose Fuse Register Low (FGPFRLO). The Flash General Purpose Fuse Register High (FGPFRHI) is not used. In addition to the general purpose fuses, parts of the flash user page can have a defined meaning outside of the flash controller and will also be described in this section. Note that when writing to the user page the values do not get loaded by the other modules on the device until a chip reset occurs. The general purpose fuses are erased by a JTAG or aWire chip erase. 158 32142D–06/2013 ATUC64/128/256L3/4U 9.9.1 Flash General Purpose Fuse Register Low (FGPFRLO) • BODEN: Brown Out Detector Enable • BODHYST: Brown Out Detector Hysteresis 0: The Brown out detector hysteresis is disabled 1: The Brown out detector hysteresis is enabled • BODLEVEL: Brown Out Detector Trigger Level This controls the voltage trigger level for the Brown out detector. Refer to ”Electrical Characteristics” on page 897. • UPROT, SECURE, BOOTPROT, EPFL, LOCK These are Flash Controller fuses and are described in the FLASHCDW section. 9.9.1.1 Default Fuse Value The devices are shipped with the FGPFRLO register value:0xE07FFFFF: • BODEN fuses set to 11. BOD is disabled. • BODHYST fuse set to 1. The BOD hysteresis is enabled. • BODLEVEL fuses set to 000000. This is the minimum voltage trigger level for BOD. This level is lower than the POR level, so when BOD is enabled, it will never trigger with this default value. • UPROT fuse set to 1. • SECURE fuse set to 11. • BOOTPROT fuses set to 111. The bootloader protection is disabled. • EPFL fuse set to 1. External privileged fetch is not locked. • LOCK fuses set to 1111111111111111. No region locked. After the JTAG or aWire chip erase command, the FGPFR register value is 0xFFFFFFFF. 31 30 29 28 27 26 25 24 BODEN BODHYST BODLEVEL[5:1] 23 22 21 20 19 18 17 16 BODLEVEL[0] UPROT SECURE BOOTPROT EPFL 15 14 13 12 11 10 9 8 LOCK[15:8] 7 6543210 LOCK[7:0] BODEN Description 00 BOD disabled 01 BOD enabled, BOD reset enabled 10 BOD enabled, BOD reset disabled 11 BOD disabled 159 32142D–06/2013 ATUC64/128/256L3/4U 9.9.2 First Word of the User Page (Address 0x80800000) • WDTAUTO: WatchDog Timer Auto Enable at Startup 0: The WDT is automatically enabled at startup. 1: The WDT is not automatically enabled at startup. Please refer to the WDT chapter for detail about timeout settings when the WDT is automatically enabled. 9.9.2.1 Default user page first word value The devices are shipped with the user page erased (all bits 1): • WDTAUTO set to 1, WDT disabled. 31 30 29 28 27 26 25 24 - ------- 23 22 21 20 19 18 17 16 - ------- 15 14 13 12 11 10 9 8 - ------- 7 6543210 - - - - - - - WDTAUTO 160 32142D–06/2013 ATUC64/128/256L3/4U 9.9.3 Second Word of the User Page (Address 0x80800004) • SSADRR: Secure State End Address for the RAM • SSADRF: Secure State End Address for the Flash 9.9.3.1 Default user page second word value The devices are shipped with the User page erased (all bits 1). 9.10 Serial Number Each device has a unique 120 bits serial number readable from address 0x8080020C to 0x8080021A. 9.11 Module Configuration The specific configuration for each FLASHCDW instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 31 30 29 28 27 26 25 24 SSADRR[15:8] 23 22 21 20 19 18 17 16 SSADRR[7:0] 15 14 13 12 11 10 9 8 SSADRF[15:8] 7 6543210 SSADRF[7:0] Table 9-11. Module Configuration Feature ATUC256L3U, ATUC256L4U ATUC128L3U, ATUC128L4U ATUC64L3U, ATUC64L4U Flash size 256Kbytes 128Kbytes 64Kbytes Number of pages 512 256 128 Page size 512 bytes 512 bytes 512 bytes Table 9-12. Module Clock Name Module Name Clock Name Description FLASHCDW CLK_FLASHCDW_HSB Clock for the FLASHCDW HSB interface CLK_FLASHCDW_PB Clock for the FLASHCDW PB interface 161 32142D–06/2013 ATUC64/128/256L3/4U Table 9-13. Register Reset Values Register ATUC256L3U, ATUC256L4U ATUC128L3U, ATUC128L4U ATUC64L3U, ATUC64L4U FVR 0x00000120 0x00000120 0x00000120 FPR 0x00000409 0x00000407 0x00000405 162 32142D–06/2013 ATUC64/128/256L3/4U 10. Secure Access Unit (SAU) Rev: 1.1.1.3 10.1 Features • Remaps registers in memory regions protected by the MPU to regions not protected by the MPU • Programmable physical address for each channel • Two modes of operation: Locked and Open – In Locked Mode, access to a channel must be preceded by an unlock action • An unlocked channel remains open only for a specific amount of time, if no access is performed during this time, the channel is relocked • Only one channel can be open at a time, opening a channel while another one is open locks the first one • Access to a locked channel is denied, a bus error and optionally an interrupt is returned • If a channel is relocked due to an unlock timeout, an interrupt can optionally be generated – In Open Mode, all channels are permanently unlocked 10.2 Overview In many systems, erroneous access to peripherals can lead to catastrophic failure. An example of such a peripheral is the Pulse Width Modulator (PWM) used to control electric motors. The PWM outputs a pulse train that controls the motor. If the control registers of the PWM module are inadvertently updated with wrong values, the motor can start operating out of control, possibly causing damage to the application and the surrounding environment. However, sometimes the PWM control registers must be updated with new values, for example when modifying the pulse train to accelerate the motor. A mechanism must be used to protect the PWM control registers from inadvertent access caused by for example: • Errors in the software code • Transient errors in the CPU caused by for example electrical noise altering the execution path of the program To improve the security in a computer system, the AVR32UC implements a Memory Protection Unit (MPU). The MPU can be set up to limit the accesses that can be performed to specific memory addresses. The MPU divides the memory space into regions, and assigns a set of access restrictions on each region. Access restrictions can for example be read/write if the CPU is in supervisor mode, and read-only if the CPU is in application mode. The regions can be of different size, but each region is usually quite large, e.g. protecting 1 kilobyte of address space or more. Furthermore, access to each region is often controlled by the execution state of the CPU, i.e. supervisor or application mode. Such a simple control mechanism is often too inflexible (too coarse-grained chunks) and with too much overhead (often requiring system calls to access protected memory locations) for simple or real-time systems such as embedded microcontrollers. Usually, the Secure Access Unit (SAU) is used together with the MPU to provide the required security and integrity. The MPU is set up to protect regions of memory, while the SAU is set up to provide a secure channel into specific memory locations that are protected by the MPU. These specific locations can be thought of as fine-grained overrides of the general coarsegrained protection provided by the MPU. 163 32142D–06/2013 ATUC64/128/256L3/4U 10.3 Block Diagram Figure 10-1 presents the SAU integrated in an example system with a CPU, some memories, some peripherals, and a bus system. The SAU is connected to both the Peripheral Bus (PB) and the High Speed Bus (HSB). Configuration of the SAU is done via the PB, while memory accesses are done via the HSB. The SAU receives an access on its HSB slave interface, remaps it, checks that the channel is unlocked, and if so, initiates a transfer on its HSB master interface to the remapped address. The thin arrows in Figure 10-1 exemplifies control flow when using the SAU. The CPU wants to read the RX Buffer in the USART. The MPU has been configured to protect all registers in the USART from user mode access, while the SAU has been configured to remap the RX Buffer into a memory space that is not protected by the MPU. This unprotected memory space is mapped into the SAU HSB slave space. When the CPU reads the appropriate address in the SAU, the SAU will perform an access to the desired RX buffer register in the USART, and thereafter return the read results to the CPU. The return data flow will follow the opposite direction of the control flow arrows in Figure 10-1. Figure 10-1. SAU Block Diagram SAU Channel Bus master MPU CPU Bus slave USART PWM Bus slave Bus master Bus slave Flash Bus slave RAM Bus bridge SAU Configuration Interrupt request High Speed Bus SAU Peripheral Bus 164 32142D–06/2013 ATUC64/128/256L3/4U 10.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 10.4.1 Power Management If the CPU enters a sleep mode that disables clocks used by the SAU, the SAU will stop functioning and resume operation after the system wakes up from sleep mode. 10.4.2 Clocks The SAU has two bus clocks connected: One High Speed Bus clock (CLK_SAU_HSB) and one Peripheral Bus clock (CLK_SAU_PB). These clocks are generated by the Power Manager. Both clocks are enabled at reset, and can be disabled by writing to the Power Manager. The user has to ensure that CLK_SAU_HSB is not turned off before accessing the SAU. Likewise, the user must ensure that no bus access is pending in the SAU before disabling CLK_SAU_HSB. Failing to do so may deadlock the High Speed Bus. 10.4.3 Interrupt The SAU interrupt request line is connected to the interrupt controller. Using the SAU interrupt requires the interrupt controller to be programmed first. 10.4.4 Debug Operation When an external debugger forces the CPU into debug mode, the SAU continues normal operation. If the SAU is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 10.5 Functional Description 10.5.1 Enabling the SAU The SAU is enabled by writing a one to the Enable (EN) bit in the Control Register (CR). This will set the SAU Enabled (EN) bit in the Status Register (SR). 10.5.2 Configuring the SAU Channels The SAU has a set of channels, mapped in the HSB memory space. These channels can be configured by a Remap Target Register (RTR), located at the same memory address. When the SAU is in normal mode, the SAU channel is addressed, and when the SAU is in setup mode, the RTR can be addressed. Before the SAU can be used, the channels must be configured and enabled. To configure a channel, the corresponding RTR must be programmed with the Remap Target Address. To do this, make sure the SAU is in setup mode by writing a one to the Setup Mode Enable (SEN) bit in CR. This makes sure that a write to the RTR address accesses the RTR, not the SAU channel. Thereafter, the RTR is written with the address to remap to, typically the address of a specific PB register. When all channels have been configured, return to normal mode by writing a one to the Setup Mode Disable (SDIS) in CR. The channels can now be enabled by writing ones to the corresponding bits in the Channel Enable Registers (CERH/L). The SAU is only able to remap addresses above 0xFFFC0000. 165 32142D–06/2013 ATUC64/128/256L3/4U 10.5.2.1 Protecting SAU configuration registers In order to prevent the SAU configuration registers to be changed by malicious or runaway code, they should be protected by the MPU as soon as they have been configured. Maximum security is provided in the system if program memory does not contain any code to unprotect the configuration registers in the MPU. This guarantees that runaway code can not accidentally unprotect and thereafter change the SAU configuration registers. 10.5.3 Lock Mechanism The SAU can be configured to use two different access mechanisms: Open and Locked. In Open Mode, SAU channels can be accessed freely after they have been configured and enabled. In order to prevent accidental accesses to remapped addresses, it is possible to configure the SAU in Locked Mode. Writing a one to the Open Mode bit in the CONFIG register (CONFIG.OPEN) will enable Open Mode. Writing a zero to CONFIG.OPEN will enable Locked Mode. When using Locked Mode, the lock mechanism must be configured by writing a user defined key value to the Unlock Key (UKEY) field in the Configuration Register (CONFIG). The number of CLK_SAU_HSB cycles the channel remains unlocked must be written to the Unlock Number of Clock Cycles (UCYC) field in CONFIG. Access control to the SAU channels is enabled by means of the Unlock Register (UR), which resides in the same address space as the SAU channels. Before a channel can be accessed, the unlock register must be written with th correct key and channel number (single write access). Access to the channel is then permitted for the next CONFIG.UCYC clock cycles, or until a successful access to the unlocked channel has been made. Only one channel can be unlocked at a time. If any other channel is unlocked at the time of writing UR, this channel will be automatically locked before the channel addressed by the UR write is unlocked. An attempted access to a locked channel will be aborted, and the Channel Access Unsuccessful bit (SR.CAU) will be set. Any pending errors bits in SR must be cleared before it is possible to access UR. The following SR bits are defined as error bits: EXP, CAU, URREAD, URKEY, URES, MBERROR, RTRADR. If any of these bits are set while writing to UR, the write is aborted and the Unlock Register Error Status (URES) bit in SR is set. 10.5.4 Normal Operation The following sequence must be used in order to access a SAU channel in normal operation (CR.SEN=0): 1. If not in Open Mode, write the unlock key to UR.KEY and the channel number to UR.CHANNEL. 2. Perform the read or write operation to the SAU channel. If not in Open Mode, this must be done within CONFIG.UCYC clock cycles of unlocking the channel. The SAU will use its HSB master interface to remap the access to the target address pointed to by the corresponding RTR. 3. To confirm that the access was successful, wait for the IDLE transfer status bit (SR.IDLE) to indicate the operation is completed. Then check SR for possible error conditions. The SAU can be configured to generate interrupt requests or a Bus Error Exception if the access failed. 166 32142D–06/2013 ATUC64/128/256L3/4U 10.5.4.1 Operation example Figure 10-2 shows a typical memory map, consisting of some memories, some simple peripherals, and a SAU with multiple channels and an Unlock Register (UR). Imagine that the MPU has been set up to disallow all accesses from the CPU to the grey modules. Thus the CPU has no way of accessing for example the Transmit Holding register in the UART, present on address X on the bus. Note that the SAU RTRs are not protected by the MPU, thus the RTRs can be accessed. If for example RTR0 is configured to point to address X, an access to RTR0 will be remapped by the SAU to address X according to the algorithm presented above. By programming the SAU RTRs, specific addresses in modules that have generally been protected by the MPU can be performed. Figure 10-2. Example Memory Map for a System with SAU 10.5.5 Interrupts The SAU can generate an interrupt request to signal different events. All events that can generate an interrupt request have dedicated bits in the Status Register (SR). An interrupt request will be generated if the corresponding bit in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in SR is cleared by writing a one to the corresponding bit in the Interrupt Clear Register (ICR). The following SR bits are used for signalling the result of SAU accesses: • RTR Address Error (RTRADR) is set if an illegal address is written to the RTRs. Only addresses in the range 0xFFFC0000-0xFFFFFFFF are allowed. • Master Interface Bus Error (MBERROR) is set if any of the conditions listed in Section 10.5.7 occurred. Transmit Holding Baudrate Control Receive Holding Channel 1 RTR0 RTR1 Address X Address Z UART SAU CONFIG SAU CHANNEL UR RTR62 ... 167 32142D–06/2013 ATUC64/128/256L3/4U • Unlock Register Error Status (URES) is set if an attempt was made to unlock a channel by writing to the Unlock Register while one or more error bits in SR were set (see Section 10.5.6). The unlock operation was aborted. • Unlock Register Key Error (URKEY) is set if the Unlock Register was attempted written with an invalid key. • Unlock Register Read (URREAD) is set if the Unlock Register was attempted read. • Channel Access Unsuccessful (CAU) is set if the channel access was unsuccessful. • Channel Access Successful (CAS) is set if the channel access was successful. • Channel Unlock Expired (EXP) is set if the channel lock expired, with no channel being accessed after the channel was unlocked. 10.5.6 Error bits If error bits are set when attempting to unlock a channel, SR.URES will be set. The following SR bits are considered error bits: • EXP • CAU • URREAD • URKEY • URES • MBERROR • RTRADR 10.5.7 Bus Error Responses By writing a one to the Bus Error Response Enable bit (CR.BERREN), serious access errors will be configured to return a bus error to the CPU. This will cause the CPU to execute its Bus Error Data Fetch exception routine. The conditions that can generate a bus error response are: • Reading the Unlock Register • Trying to access a locked channel • The SAU HSB master receiving a bus error response from its addressed slave 10.5.8 Disabling the SAU To disable the SAU, the user must first ensure that no SAU bus operations are pending. This can be done by checking that the SR.IDLE bit is set. The SAU may then be disabled by writing a one to the Disable (DIS) bit in CR. 168 32142D–06/2013 ATUC64/128/256L3/4U 10.6 User Interface The following addresses are used by SAU channel configuration registers. All offsets are relative to the SAU’s PB base address. Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. The following addresses are used by SAU channel registers. All offsets are relative to the SAU’s HSB base address. The number of channels implemented is device specific, refer to the Module Configuration section at the end of this chapter. Table 10-1. SAU Configuration Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Write-only 0x00000000 0x04 Configuration Register CONFIG Write-only 0x00000000 0x08 Channel Enable Register High CERH Read/Write 0x00000000 0x0C Channel Enable Register Low CERL Read/Write 0x00000000 0x10 Status Register SR Read-only 0x00000400 0x14 Interrupt Enable Register IER Write-only 0x00000000 0x18 Interrupt Disable Register IDR Write-only 0x00000000 0x1C Interrupt Mask Register IMR Read-only 0x00000000 0x20 Interrupt Clear Register ICR Write-only 0x00000000 0x24 Parameter Register PARAMETER Read-only -(1) 0x28 Version Register VERSION Read-only -(1) Table 10-2. SAU Channel Register Memory Map Offset Register Register Name Access Reset 0x00 Remap Target Register 0 RTR0 Read/Write N/A 0x04 Remap Target Register 1 RTR1 Read/Write N/A 0x08 Remap Target Register 2 RTR2 Read/Write N/A ... ... ... ... ... 0x04*n Remap Target Register n RTRn Read/Write N/A 0xFC Unlock Register UR Write-only N/A 169 32142D–06/2013 ATUC64/128/256L3/4U 10.6.1 Control Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 • BERRDIS: Bus Error Response Disable Writing a zero to this bit has no effect. Writing a one to this bit disables Bus Error Response from the SAU. • BERREN: Bus Error Response Enable Writing a zero to this bit has no effect. Writing a one to this bit enables Bus Error Response from the SAU. • SDIS: Setup Mode Disable Writing a zero to this bit has no effect. Writing a one to this bit exits setup mode. • SEN: Setup Mode Enable Writing a zero to this bit has no effect. Writing a one to this bit enters setup mode. • DIS: SAU Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the SAU. • EN: SAU Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the SAU. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - BERRDIS BERREN SDIS SEN DIS EN 170 32142D–06/2013 ATUC64/128/256L3/4U 10.6.2 Configuration Register Name: CONFIG Access Type: Write-only Offset: 0x04 Reset Value: 0x00000000 • OPEN: Open Mode Enable Writing a zero to this bit disables open mode. Writing a one to this bit enables open mode. • UCYC: Unlock Number of Clock Cycles Once a channel has been unlocked, it remains unlocked for this amount of CLK_SAU_HSB clock cycles or until one access to a channel has been made. • UKEY: Unlock Key The value in this field must be written to UR.KEY to unlock a channel. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - OPEN 15 14 13 12 11 10 9 8 UCYC 76543210 UKEY 171 32142D–06/2013 ATUC64/128/256L3/4U 10.6.3 Channel Enable Register High Name: CERH Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • CERH[n]: Channel Enable Register High 0: Channel (n+32) is not enabled. 1: Channel (n+32) is enabled. 31 30 29 28 27 26 25 24 - CERH[30:24] 23 22 21 20 19 18 17 16 CERH[23:16] 15 14 13 12 11 10 9 8 CERH[15:8] 76543210 CERH[7:0] 172 32142D–06/2013 ATUC64/128/256L3/4U 10.6.4 Channel Enable Register Low Name: CERL Access Type: Read/Write Offset: 0x0C Reset Value: 0x00000000 • CERL[n]: Channel Enable Register Low 0: Channel n is not enabled. 1: Channel n is enabled. 31 30 29 28 27 26 25 24 CERL[31:24] 23 22 21 20 19 18 17 16 CERL[23:16] 15 14 13 12 11 10 9 8 CERL[15:8] 76543210 CERL[7:0] 173 32142D–06/2013 ATUC64/128/256L3/4U 10.6.5 Status Register Name: SR Access Type: Read-only Offset: 0x10 Reset Value: 0x00000400 • IDLE This bit is cleared when a read or write operation to the SAU channel is started. This bit is set when the operation is completed and no SAU bus operations are pending. • SEN: SAU Setup Mode Enable This bit is cleared when the SAU exits setup mode. This bit is set when the SAU enters setup mode. • EN: SAU Enabled This bit is cleared when the SAU is disabled. This bit is set when the SAU is enabled. • RTRADR: RTR Address Error This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if, in the configuration phase, an RTR was written with an illegal address, i.e. the upper 16 bits in the address were different from 0xFFFC, 0xFFFD, 0xFFFE or 0xFFFF. • MBERROR: Master Interface Bus Error This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if a channel access generated a transfer on the master interface that received a bus error response from the addressed slave. • URES: Unlock Register Error Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if an attempt was made to unlock a channel by writing to the Unlock Register while one or more error bits were set in SR. The unlock operation was aborted. • URKEY: Unlock Register Key Error This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if the Unlock Register was attempted written with an invalid key. • URREAD: Unlock Register Read This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if the Unlock Register was read. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - IDLE SEN EN 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 174 32142D–06/2013 ATUC64/128/256L3/4U • CAU: Channel Access Unsuccessful This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if channel access was unsuccessful, i.e. an access was attempted to a locked or disabled channel. • CAS: Channel Access Successful This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if channel access successful, i.e. one access was made after the channel was unlocked. • EXP: Channel Unlock Expired This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if channel unlock has expired, i.e. no access being made after the channel was unlocked. 175 32142D–06/2013 ATUC64/128/256L3/4U 10.6.6 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 176 32142D–06/2013 ATUC64/128/256L3/4U 10.6.7 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 177 32142D–06/2013 ATUC64/128/256L3/4U 10.6.8 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 178 32142D–06/2013 ATUC64/128/256L3/4U 10.6.9 Interrupt Clear Register Name: ICR Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and any corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 179 32142D–06/2013 ATUC64/128/256L3/4U 10.6.10 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x24 Reset Value: - • CHANNELS: Number of channels implemented. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CHANNELS 180 32142D–06/2013 ATUC64/128/256L3/4U 10.6.11 Version Register Name: VERSION Access Type: Write-only Offset: 0x28 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 181 32142D–06/2013 ATUC64/128/256L3/4U 10.6.12 Remap Target Register n Name: RTRn Access Type: Read/Write Offset: n*4 Reset Value: 0x00000000 • RTR: Remap Target Address for Channel n RTR[31:16] must have one of the following values, any other value will result in UNDEFINED behavior: 0xFFFC 0xFFFD 0xFFFE 0xFFFF RTR[1:0] must be written to 00, any other value will result in UNDEFINED behavior. 31 30 29 28 27 26 25 24 RTR[31:24] 23 22 21 20 19 18 17 16 RTR[23:16] 15 14 13 12 11 10 9 8 RTR[15:8] 76543210 RTR[7:0] 182 32142D–06/2013 ATUC64/128/256L3/4U 10.6.13 Unlock Register Name: UR Access Type : Write-only Offset: 0xFC Reset Value: 0x00000000 • KEY: Unlock Key The correct key must be written in order to unlock a channel. The key value written must correspond to the key value defined in CONFIG.UKEY. • CHANNEL: Channel Number Number of the channel to unlock. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 KEY 76543210 - - CHANNEL 183 32142D–06/2013 ATUC64/128/256L3/4U 10.7 Module Configuration The specific configuration for each SAU instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 10-3. SAU configuration Feature SAU SAU Channels 16 Table 10-4. SAU clock name Module name Clock name Description SAU CLK_SAU_HSB Clock for the SAU HSB interface SAU CLK_SAU_PB Clock for the SAU PB interface Table 10-5. Register Reset Values Register Reset Value VERSION 0x00000111 PARAMETER 0x00000010 184 32142D–06/2013 ATUC64/128/256L3/4U 11. HSB Bus Matrix (HMATRIXB) Rev: 1.3.0.3 11.1 Features • User Interface on peripheral bus • Configurable number of masters (up to 16) • Configurable number of slaves (up to 16) • One decoder for each master • Programmable arbitration for each slave – Round-Robin – Fixed priority • Programmable default master for each slave – No default master – Last accessed default master – Fixed default master • One cycle latency for the first access of a burst • Zero cycle latency for default master • One special function register for each slave (not dedicated) 11.2 Overview The Bus Matrix implements a multi-layer bus structure, that enables parallel access paths between multiple High Speed Bus (HSB) masters and slaves in a system, thus increasing the overall bandwidth. The Bus Matrix interconnects up to 16 HSB Masters to up to 16 HSB Slaves. The normal latency to connect a master to a slave is one cycle except for the default master of the accessed slave which is connected directly (zero cycle latency). The Bus Matrix provides 16 Special Function Registers (SFR) that allow the Bus Matrix to support application specific features. 11.3 Product Dependencies In order to configure this module by accessing the user registers, other parts of the system must be configured correctly, as described below. 11.3.1 Clocks The clock for the HMATRIX bus interface (CLK_HMATRIX) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. 11.4 Functional Description 11.4.1 Special Bus Granting Mechanism The Bus Matrix provides some speculative bus granting techniques in order to anticipate access requests from some masters. This mechanism reduces latency at first access of a burst or single transfer. This bus granting mechanism sets a different default master for every slave. At the end of the current access, if no other request is pending, the slave remains connected to its associated default master. A slave can be associated with three kinds of default masters: no default master, last access master, and fixed default master. 185 32142D–06/2013 ATUC64/128/256L3/4U To change from one kind of default master to another, the Bus Matrix user interface provides the Slave Configuration Registers, one for each slave, that set a default master for each slave. The Slave Configuration Register contains two fields: DEFMSTR_TYPE and FIXED_DEFMSTR. The 2-bit DEFMSTR_TYPE field selects the default master type (no default, last access master, fixed default master), whereas the 4-bit FIXED_DEFMSTR field selects a fixed default master provided that DEFMSTR_TYPE is set to fixed default master. Please refer to the Bus Matrix user interface description. 11.4.1.1 No Default Master At the end of the current access, if no other request is pending, the slave is disconnected from all masters. No Default Master suits low-power mode. 11.4.1.2 Last Access Master At the end of the current access, if no other request is pending, the slave remains connected to the last master that performed an access request. 11.4.1.3 Fixed Default Master At the end of the current access, if no other request is pending, the slave connects to its fixed default master. Unlike last access master, the fixed master does not change unless the user modifies it by a software action (field FIXED_DEFMSTR of the related SCFG). 11.4.2 Arbitration The Bus Matrix provides an arbitration mechanism that reduces latency when conflict cases occur, i.e. when two or more masters try to access the same slave at the same time. One arbiter per HSB slave is provided, thus arbitrating each slave differently. The Bus Matrix provides the user with the possibility of choosing between 2 arbitration types for each slave: 1. Round-Robin Arbitration (default) 2. Fixed Priority Arbitration This is selected by the ARBT field in the Slave Configuration Registers (SCFG). Each algorithm may be complemented by selecting a default master configuration for each slave. When a re-arbitration must be done, specific conditions apply. This is described in “Arbitration Rules” . 11.4.2.1 Arbitration Rules Each arbiter has the ability to arbitrate between two or more different master requests. In order to avoid burst breaking and also to provide the maximum throughput for slave interfaces, arbitration may only take place during the following cycles: 1. Idle Cycles: When a slave is not connected to any master or is connected to a master which is not currently accessing it. 2. Single Cycles: When a slave is currently doing a single access. 3. End of Burst Cycles: When the current cycle is the last cycle of a burst transfer. For defined length burst, predicted end of burst matches the size of the transfer but is managed differently for undefined length burst. This is described below. 4. Slot Cycle Limit: When the slot cycle counter has reached the limit value indicating that the current master access is too long and must be broken. This is described below. 186 32142D–06/2013 ATUC64/128/256L3/4U • Undefined Length Burst Arbitration In order to avoid long slave handling during undefined length bursts (INCR), the Bus Matrix provides specific logic in order to re-arbitrate before the end of the INCR transfer. A predicted end of burst is used as a defined length burst transfer and can be selected among the following five possibilities: 1. Infinite: No predicted end of burst is generated and therefore INCR burst transfer will never be broken. 2. One beat bursts: Predicted end of burst is generated at each single transfer inside the INCP transfer. 3. Four beat bursts: Predicted end of burst is generated at the end of each four beat boundary inside INCR transfer. 4. Eight beat bursts: Predicted end of burst is generated at the end of each eight beat boundary inside INCR transfer. 5. Sixteen beat bursts: Predicted end of burst is generated at the end of each sixteen beat boundary inside INCR transfer. This selection can be done through the ULBT field in the Master Configuration Registers (MCFG). • Slot Cycle Limit Arbitration The Bus Matrix contains specific logic to break long accesses, such as very long bursts on a very slow slave (e.g., an external low speed memory). At the beginning of the burst access, a counter is loaded with the value previously written in the SLOT_CYCLE field of the related Slave Configuration Register (SCFG) and decreased at each clock cycle. When the counter reaches zero, the arbiter has the ability to re-arbitrate at the end of the current byte, halfword, or word transfer. 11.4.2.2 Round-Robin Arbitration This algorithm allows the Bus Matrix arbiters to dispatch the requests from different masters to the same slave in a round-robin manner. If two or more master requests arise at the same time, the master with the lowest number is first serviced, then the others are serviced in a round-robin manner. There are three round-robin algorithms implemented: 1. Round-Robin arbitration without default master 2. Round-Robin arbitration with last default master 3. Round-Robin arbitration with fixed default master • Round-Robin Arbitration without Default Master This is the main algorithm used by Bus Matrix arbiters. It allows the Bus Matrix to dispatch requests from different masters to the same slave in a pure round-robin manner. At the end of the current access, if no other request is pending, the slave is disconnected from all masters. This configuration incurs one latency cycle for the first access of a burst. Arbitration without default master can be used for masters that perform significant bursts. • Round-Robin Arbitration with Last Default Master This is a biased round-robin algorithm used by Bus Matrix arbiters. It allows the Bus Matrix to remove the one latency cycle for the last master that accessed the slave. At the end of the cur- 187 32142D–06/2013 ATUC64/128/256L3/4U rent transfer, if no other master request is pending, the slave remains connected to the last master that performed the access. Other non privileged masters still get one latency cycle if they want to access the same slave. This technique can be used for masters that mainly perform single accesses. • Round-Robin Arbitration with Fixed Default Master This is another biased round-robin algorithm. It allows the Bus Matrix arbiters to remove the one latency cycle for the fixed default master per slave. At the end of the current access, the slave remains connected to its fixed default master. Every request attempted by this fixed default master will not cause any latency whereas other non privileged masters will still get one latency cycle. This technique can be used for masters that mainly perform single accesses. 11.4.2.3 Fixed Priority Arbitration This algorithm allows the Bus Matrix arbiters to dispatch the requests from different masters to the same slave by using the fixed priority defined by the user. If two or more master requests are active at the same time, the master with the highest priority number is serviced first. If two or more master requests with the same priority are active at the same time, the master with the highest number is serviced first. For each slave, the priority of each master may be defined through the Priority Registers for Slaves (PRAS and PRBS). 11.4.3 Slave and Master assignation The index number assigned to Bus Matrix slaves and masters are described in the Module Configuration section at the end of this chapter. 188 32142D–06/2013 ATUC64/128/256L3/4U 11.5 User Interface Table 11-1. HMATRIX Register Memory Map Offset Register Name Access Reset Value 0x0000 Master Configuration Register 0 MCFG0 Read/Write 0x00000002 0x0004 Master Configuration Register 1 MCFG1 Read/Write 0x00000002 0x0008 Master Configuration Register 2 MCFG2 Read/Write 0x00000002 0x000C Master Configuration Register 3 MCFG3 Read/Write 0x00000002 0x0010 Master Configuration Register 4 MCFG4 Read/Write 0x00000002 0x0014 Master Configuration Register 5 MCFG5 Read/Write 0x00000002 0x0018 Master Configuration Register 6 MCFG6 Read/Write 0x00000002 0x001C Master Configuration Register 7 MCFG7 Read/Write 0x00000002 0x0020 Master Configuration Register 8 MCFG8 Read/Write 0x00000002 0x0024 Master Configuration Register 9 MCFG9 Read/Write 0x00000002 0x0028 Master Configuration Register 10 MCFG10 Read/Write 0x00000002 0x002C Master Configuration Register 11 MCFG11 Read/Write 0x00000002 0x0030 Master Configuration Register 12 MCFG12 Read/Write 0x00000002 0x0034 Master Configuration Register 13 MCFG13 Read/Write 0x00000002 0x0038 Master Configuration Register 14 MCFG14 Read/Write 0x00000002 0x003C Master Configuration Register 15 MCFG15 Read/Write 0x00000002 0x0040 Slave Configuration Register 0 SCFG0 Read/Write 0x00000010 0x0044 Slave Configuration Register 1 SCFG1 Read/Write 0x00000010 0x0048 Slave Configuration Register 2 SCFG2 Read/Write 0x00000010 0x004C Slave Configuration Register 3 SCFG3 Read/Write 0x00000010 0x0050 Slave Configuration Register 4 SCFG4 Read/Write 0x00000010 0x0054 Slave Configuration Register 5 SCFG5 Read/Write 0x00000010 0x0058 Slave Configuration Register 6 SCFG6 Read/Write 0x00000010 0x005C Slave Configuration Register 7 SCFG7 Read/Write 0x00000010 0x0060 Slave Configuration Register 8 SCFG8 Read/Write 0x00000010 0x0064 Slave Configuration Register 9 SCFG9 Read/Write 0x00000010 0x0068 Slave Configuration Register 10 SCFG10 Read/Write 0x00000010 0x006C Slave Configuration Register 11 SCFG11 Read/Write 0x00000010 0x0070 Slave Configuration Register 12 SCFG12 Read/Write 0x00000010 0x0074 Slave Configuration Register 13 SCFG13 Read/Write 0x00000010 0x0078 Slave Configuration Register 14 SCFG14 Read/Write 0x00000010 0x007C Slave Configuration Register 15 SCFG15 Read/Write 0x00000010 0x0080 Priority Register A for Slave 0 PRAS0 Read/Write 0x00000000 0x0084 Priority Register B for Slave 0 PRBS0 Read/Write 0x00000000 0x0088 Priority Register A for Slave 1 PRAS1 Read/Write 0x00000000 189 32142D–06/2013 ATUC64/128/256L3/4U 0x008C Priority Register B for Slave 1 PRBS1 Read/Write 0x00000000 0x0090 Priority Register A for Slave 2 PRAS2 Read/Write 0x00000000 0x0094 Priority Register B for Slave 2 PRBS2 Read/Write 0x00000000 0x0098 Priority Register A for Slave 3 PRAS3 Read/Write 0x00000000 0x009C Priority Register B for Slave 3 PRBS3 Read/Write 0x00000000 0x00A0 Priority Register A for Slave 4 PRAS4 Read/Write 0x00000000 0x00A4 Priority Register B for Slave 4 PRBS4 Read/Write 0x00000000 0x00A8 Priority Register A for Slave 5 PRAS5 Read/Write 0x00000000 0x00AC Priority Register B for Slave 5 PRBS5 Read/Write 0x00000000 0x00B0 Priority Register A for Slave 6 PRAS6 Read/Write 0x00000000 0x00B4 Priority Register B for Slave 6 PRBS6 Read/Write 0x00000000 0x00B8 Priority Register A for Slave 7 PRAS7 Read/Write 0x00000000 0x00BC Priority Register B for Slave 7 PRBS7 Read/Write 0x00000000 0x00C0 Priority Register A for Slave 8 PRAS8 Read/Write 0x00000000 0x00C4 Priority Register B for Slave 8 PRBS8 Read/Write 0x00000000 0x00C8 Priority Register A for Slave 9 PRAS9 Read/Write 0x00000000 0x00CC Priority Register B for Slave 9 PRBS9 Read/Write 0x00000000 0x00D0 Priority Register A for Slave 10 PRAS10 Read/Write 0x00000000 0x00D4 Priority Register B for Slave 10 PRBS10 Read/Write 0x00000000 0x00D8 Priority Register A for Slave 11 PRAS11 Read/Write 0x00000000 0x00DC Priority Register B for Slave 11 PRBS11 Read/Write 0x00000000 0x00E0 Priority Register A for Slave 12 PRAS12 Read/Write 0x00000000 0x00E4 Priority Register B for Slave 12 PRBS12 Read/Write 0x00000000 0x00E8 Priority Register A for Slave 13 PRAS13 Read/Write 0x00000000 0x00EC Priority Register B for Slave 13 PRBS13 Read/Write 0x00000000 0x00F0 Priority Register A for Slave 14 PRAS14 Read/Write 0x00000000 0x00F4 Priority Register B for Slave 14 PRBS14 Read/Write 0x00000000 0x00F8 Priority Register A for Slave 15 PRAS15 Read/Write 0x00000000 0x00FC Priority Register B for Slave 15 PRBS15 Read/Write 0x00000000 0x0110 Special Function Register 0 SFR0 Read/Write – 0x0114 Special Function Register 1 SFR1 Read/Write – 0x0118 Special Function Register 2 SFR2 Read/Write – 0x011C Special Function Register 3 SFR3 Read/Write – 0x0120 Special Function Register 4 SFR4 Read/Write – 0x0124 Special Function Register 5 SFR5 Read/Write – 0x0128 Special Function Register 6 SFR6 Read/Write – Table 11-1. HMATRIX Register Memory Map (Continued) Offset Register Name Access Reset Value 190 32142D–06/2013 ATUC64/128/256L3/4U 0x012C Special Function Register 7 SFR7 Read/Write – 0x0130 Special Function Register 8 SFR8 Read/Write – 0x0134 Special Function Register 9 SFR9 Read/Write – 0x0138 Special Function Register 10 SFR10 Read/Write – 0x013C Special Function Register 11 SFR11 Read/Write – 0x0140 Special Function Register 12 SFR12 Read/Write – 0x0144 Special Function Register 13 SFR13 Read/Write – 0x0148 Special Function Register 14 SFR14 Read/Write – 0x014C Special Function Register 15 SFR15 Read/Write – Table 11-1. HMATRIX Register Memory Map (Continued) Offset Register Name Access Reset Value 191 32142D–06/2013 ATUC64/128/256L3/4U 11.5.1 Master Configuration Registers Name: MCFG0...MCFG15 Access Type: Read/Write Offset: 0x00 - 0x3C Reset Value: 0x00000002 • ULBT: Undefined Length Burst Type 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 –––––––– 76543210 – – – – – ULBT Table 11-2. Undefined Length Burst Type ULBT Undefined Length Burst Type Description 000 Inifinite Length Burst No predicted end of burst is generated and therefore INCR bursts coming from this master cannot be broken. 001 Single-Access The undefined length burst is treated as a succession of single accesses, allowing rearbitration at each beat of the INCR burst. 010 4 Beat Burst The undefined length burst is split into a four-beat burst, allowing re-arbitration at each four-beat burst end. 011 8 Beat Burst The undefined length burst is split into an eight-beat burst, allowing re-arbitration at each eight-beat burst end. 100 16 Beat Burst The undefined length burst is split into a sixteen-beat burst, allowing re-arbitration at each sixteen-beat burst end. 192 32142D–06/2013 ATUC64/128/256L3/4U 11.5.2 Slave Configuration Registers Name: SCFG0...SCFG15 Access Type: Read/Write Offset: 0x40 - 0x7C Reset Value: 0x00000010 • ARBT: Arbitration Type 0: Round-Robin Arbitration 1: Fixed Priority Arbitration • FIXED_DEFMSTR: Fixed Default Master This is the number of the Default Master for this slave. Only used if DEFMSTR_TYPE is 2. Specifying the number of a master which is not connected to the selected slave is equivalent to setting DEFMSTR_TYPE to 0. • DEFMSTR_TYPE: Default Master Type 0: No Default Master At the end of the current slave access, if no other master request is pending, the slave is disconnected from all masters. This results in a one cycle latency for the first access of a burst transfer or for a single access. 1: Last Default Master At the end of the current slave access, if no other master request is pending, the slave stays connected to the last master having accessed it. This results in not having one cycle latency when the last master tries to access the slave again. 2: Fixed Default Master At the end of the current slave access, if no other master request is pending, the slave connects to the fixed master the number that has been written in the FIXED_DEFMSTR field. This results in not having one cycle latency when the fixed master tries to access the slave again. • SLOT_CYCLE: Maximum Number of Allowed Cycles for a Burst When the SLOT_CYCLE limit is reached for a burst, it may be broken by another master trying to access this slave. This limit has been placed to avoid locking a very slow slave when very long bursts are used. This limit must not be very small. Unreasonably small values break every burst and the Bus Matrix arbitrates without performing any data transfer. 16 cycles is a reasonable value for SLOT_CYCLE. 31 30 29 28 27 26 25 24 – – – – – – – ARBT 23 22 21 20 19 18 17 16 – – FIXED_DEFMSTR DEFMSTR_TYPE 15 14 13 12 11 10 9 8 –––––––– 76543210 SLOT_CYCLE 193 32142D–06/2013 ATUC64/128/256L3/4U 11.5.3 Bus Matrix Priority Registers A For Slaves Register Name: PRAS0...PRAS15 Access Type: Read/Write Offset: - Reset Value: 0x00000000 • MxPR: Master x Priority Fixed priority of Master x for accessing the selected slave. The higher the number, the higher the priority. 31 30 29 28 27 26 25 24 - - M7PR - - M6PR 23 22 21 20 19 18 17 16 - - M5PR - - M4PR 15 14 13 12 11 10 9 8 - - M3PR - - M2PR 76543210 - - M1PR - - M0PR 194 32142D–06/2013 ATUC64/128/256L3/4U 11.5.4 Priority Registers B For Slaves Name: PRBS0...PRBS15 Access Type: Read/Write Offset: - Reset Value: 0x00000000 • MxPR: Master x Priority Fixed priority of Master x for accessing the selected slave. The higher the number, the higher the priority. 31 30 29 28 27 26 25 24 - - M15PR - - M14PR 23 22 21 20 19 18 17 16 - - M13PR - - M12PR 15 14 13 12 11 10 9 8 - - M11PR - - M10PR 76543210 - - M9PR - - M8PR 195 32142D–06/2013 ATUC64/128/256L3/4U 11.5.5 Special Function Registers Name: SFR0...SFR15 Access Type: Read/Write Offset: 0x110 - 0x14C Reset Value: - • SFR: Special Function Register Fields Those registers are not a HMATRIX specific register. The field of those will be defined where they are used. 31 30 29 28 27 26 25 24 SFR 23 22 21 20 19 18 17 16 SFR 15 14 13 12 11 10 9 8 SFR 76543210 SFR 196 32142D–06/2013 ATUC64/128/256L3/4U 11.6 Module Configuration The specific configuration for each HMATRIX instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 11.6.1 Bus Matrix Connections The bus matrix has the several masters and slaves. Each master has its own bus and its own decoder, thus allowing a different memory mapping per master. The master number in the table below can be used to index the HMATRIX control registers. For example, HMATRIX MCFG0 register is associated with the CPU Data master interface. Each slave has its own arbiter, thus allowing a different arbitration per slave. The slave number in the table below can be used to index the HMATRIX control registers. For example, SCFG3 is associated with the Internal SRAM Slave Interface. Accesses to unused areas returns an error result to the master requesting such an access. Table 11-3. HMATRIX Clocks Clock Name Description CLK_HMATRIX Clock for the HMATRIX bus interface Table 11-4. High Speed Bus Masters Master 0 CPU Data Master 1 CPU Instruction Master 2 CPU SAB Master 3 SAU Master 4 PDCA Master 5 USBC Table 11-5. High Speed Bus Slaves Slave 0 Internal Flash Slave 1 HSB-PB Bridge A Slave 2 HSB-PB Bridge B Slave 3 Internal SRAM Slave 4 SAU 197 32142D–06/2013 ATUC64/128/256L3/4U Figure 11-1. HMatrix Master / Slave Connections CPU Data 0 CPU Instruction 1 CPU SAB 2 SAU 3 Internal Flash 0 HSB-PB Bridge 0 1 HSB-PB Bridge 1 2 Internal SRAM 3 HMATRIX SLAVES HMATRIX MASTERS SAU 4 PDCA 4 USBC 5 198 32142D–06/2013 ATUC64/128/256L3/4U 12. Interrupt Controller (INTC) Rev: 1.0.2.5 12.1 Features • Autovectored low latency interrupt service with programmable priority – 4 priority levels for regular, maskable interrupts – One Non-Maskable Interrupt • Up to 64 groups of interrupts with up to 32 interrupt requests in each group 12.2 Overview The INTC collects interrupt requests from the peripherals, prioritizes them, and delivers an interrupt request and an autovector to the CPU. The AVR32 architecture supports 4 priority levels for regular, maskable interrupts, and a Non-Maskable Interrupt (NMI). The INTC supports up to 64 groups of interrupts. Each group can have up to 32 interrupt request lines, these lines are connected to the peripherals. Each group has an Interrupt Priority Register (IPR) and an Interrupt Request Register (IRR). The IPRs are used to assign a priority level and an autovector to each group, and the IRRs are used to identify the active interrupt request within each group. If a group has only one interrupt request line, an active interrupt group uniquely identifies the active interrupt request line, and the corresponding IRR is not needed. The INTC also provides one Interrupt Cause Register (ICR) per priority level. These registers identify the group that has a pending interrupt of the corresponding priority level. If several groups have a pending interrupt of the same level, the group with the lowest number takes priority. 12.3 Block Diagram Figure 12-1 gives an overview of the INTC. The grey boxes represent registers that can be accessed via the user interface. The interrupt requests from the peripherals (IREQn) and the NMI are input on the left side of the figure. Signals to and from the CPU are on the right side of the figure. 199 32142D–06/2013 ATUC64/128/256L3/4U Figure 12-1. INTC Block Diagram 12.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 12.4.1 Power Management If the CPU enters a sleep mode that disables CLK_SYNC, the INTC will stop functioning and resume operation after the system wakes up from sleep mode. 12.4.2 Clocks The clock for the INTC bus interface (CLK_INTC) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. The INTC sampling logic runs on a clock which is stopped in any of the sleep modes where the system RC oscillator is not running. This clock is referred to as CLK_SYNC. This clock is enabled at reset, and only turned off in sleep modes where the system RC oscillator is stopped. 12.4.3 Debug Operation When an external debugger forces the CPU into debug mode, the INTC continues normal operation. 12.5 Functional Description All of the incoming interrupt requests (IREQs) are sampled into the corresponding Interrupt Request Register (IRR). The IRRs must be accessed to identify which IREQ within a group that is active. If several IREQs within the same group are active, the interrupt service routine must prioritize between them. All of the input lines in each group are logically ORed together to form the GrpReqN lines, indicating if there is a pending interrupt in the corresponding group. The Request Masking hardware maps each of the GrpReq lines to a priority level from INT0 to INT3 by associating each group with the Interrupt Level (INTLEVEL) field in the corresponding Request Masking OR IREQ0 IREQ1 IREQ2 IREQ31 GrpReq0 Masks SREG Masks I[3-0]M GM INTLEVEL AUTOVECTOR Prioritizer Interrupt Controller CPU OR GrpReqN NMIREQ OR IREQ32 IREQ33 IREQ34 IREQ63 GrpReq1 IRR Registers IPR Registers ICR Registers INT_level, offset INT_level, offset INT_level, offset IPR0 IPR1 IPRn IRR0 IRR1 IRRn ValReq0 ValReq1 ValReqN . . . . . . . . . 200 32142D–06/2013 ATUC64/128/256L3/4U Interrupt Priority Register (IPR). The GrpReq inputs are then masked by the mask bits from the CPU status register. Any interrupt group that has a pending interrupt of a priority level that is not masked by the CPU status register, gets its corresponding ValReq line asserted. Masking of the interrupt requests is done based on five interrupt mask bits of the CPU status register, namely Interrupt Level 3 Mask (I3M) to Interrupt Level 0 Mask (I0M), and Global Interrupt Mask (GM). An interrupt request is masked if either the GM or the corresponding interrupt level mask bit is set. The Prioritizer hardware uses the ValReq lines and the INTLEVEL field in the IPRs to select the pending interrupt of the highest priority. If an NMI interrupt request is pending, it automatically gets the highest priority of any pending interrupt. If several interrupt groups of the highest pending interrupt level have pending interrupts, the interrupt group with the lowest number is selected. The INTLEVEL and handler autovector offset (AUTOVECTOR) of the selected interrupt are transmitted to the CPU for interrupt handling and context switching. The CPU does not need to know which interrupt is requesting handling, but only the level and the offset of the handler address. The IRR registers contain the interrupt request lines of the groups and can be read via user interface registers for checking which interrupts of the group are actually active. The delay through the INTC from the peripheral interrupt request is set until the interrupt request to the CPU is set is three cycles of CLK_SYNC. 12.5.1 Non-Maskable Interrupts A NMI request has priority over all other interrupt requests. NMI has a dedicated exception vector address defined by the AVR32 architecture, so AUTOVECTOR is undefined when INTLEVEL indicates that an NMI is pending. 12.5.2 CPU Response When the CPU receives an interrupt request it checks if any other exceptions are pending. If no exceptions of higher priority are pending, interrupt handling is initiated. When initiating interrupt handling, the corresponding interrupt mask bit is set automatically for this and lower levels in status register. E.g, if an interrupt of level 3 is approved for handling, the interrupt mask bits I3M, I2M, I1M, and I0M are set in status register. If an interrupt of level 1 is approved, the masking bits I1M and I0M are set in status register. The handler address is calculated by logical OR of the AUTOVECTOR to the CPU system register Exception Vector Base Address (EVBA). The CPU will then jump to the calculated address and start executing the interrupt handler. Setting the interrupt mask bits prevents the interrupts from the same and lower levels to be passed through the interrupt controller. Setting of the same level mask bit prevents also multiple requests of the same interrupt to happen. It is the responsibility of the handler software to clear the interrupt request that caused the interrupt before returning from the interrupt handler. If the conditions that caused the interrupt are not cleared, the interrupt request remains active. 12.5.3 Clearing an Interrupt Request Clearing of the interrupt request is done by writing to registers in the corresponding peripheral module, which then clears the corresponding NMIREQ/IREQ signal. The recommended way of clearing an interrupt request is a store operation to the controlling peripheral register, followed by a dummy load operation from the same register. This causes a 201 32142D–06/2013 ATUC64/128/256L3/4U pipeline stall, which prevents the interrupt from accidentally re-triggering in case the handler is exited and the interrupt mask is cleared before the interrupt request is cleared. 202 32142D–06/2013 ATUC64/128/256L3/4U 12.6 User Interface Table 12-1. INTC Register Memory Map Offset Register Register Name Access Reset 0x000 Interrupt Priority Register 0 IPR0 Read/Write 0x00000000 0x004 Interrupt Priority Register 1 IPR1 Read/Write 0x00000000 ... ... ... ... ... 0x0FC Interrupt Priority Register 63 IPR63 Read/Write 0x00000000 0x100 Interrupt Request Register 0 IRR0 Read-only N/A 0x104 Interrupt Request Register 1 IRR1 Read-only N/A ... ... ... ... ... 0x1FC Interrupt Request Register 63 IRR63 Read-only N/A 0x200 Interrupt Cause Register 3 ICR3 Read-only N/A 0x204 Interrupt Cause Register 2 ICR2 Read-only N/A 0x208 Interrupt Cause Register 1 ICR1 Read-only N/A 0x20C Interrupt Cause Register 0 ICR0 Read-only N/A 203 32142D–06/2013 ATUC64/128/256L3/4U 12.6.1 Interrupt Priority Registers Name: IPR0...IPR63 Access Type: Read/Write Offset: 0x000 - 0x0FC Reset Value: 0x00000000 • INTLEVEL: Interrupt Level Indicates the EVBA-relative offset of the interrupt handler of the corresponding group: 00: INT0: Lowest priority 01: INT1 10: INT2 11: INT3: Highest priority • AUTOVECTOR: Autovector Address Handler offset is used to give the address of the interrupt handler. The least significant bit should be written to zero to give halfword alignment. 31 30 29 28 27 26 25 24 INTLEVEL - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - AUTOVECTOR[13:8] 76543210 AUTOVECTOR[7:0] 204 32142D–06/2013 ATUC64/128/256L3/4U 12.6.2 Interrupt Request Registers Name: IRR0...IRR63 Access Type: Read-only Offset: 0x0FF - 0x1FC Reset Value: N/A • IRR: Interrupt Request line This bit is cleared when no interrupt request is pending on this input request line. This bit is set when an interrupt request is pending on this input request line. The are 64 IRRs, one for each group. Each IRR has 32 bits, one for each possible interrupt request, for a total of 2048 possible input lines. The IRRs are read by the software interrupt handler in order to determine which interrupt request is pending. The IRRs are sampled continuously, and are read-only. 31 30 29 28 27 26 25 24 IRR[32*x+31] IRR[32*x+30] IRR[32*x+29] IRR[32*x+28] IRR[32*x+27] IRR[32*x+26] IRR[32*x+25] IRR[32*x+24] 23 22 21 20 19 18 17 16 IRR[32*x+23] IRR[32*x+22] IRR[32*x+21] IRR[32*x+20] IRR[32*x+19] IRR[32*x+18] IRR[32*x+17] IRR[32*x+16] 15 14 13 12 11 10 9 8 IRR[32*x+15] IRR[32*x+14] IRR[32*x+13] IRR[32*x+12] IRR[32*x+11] IRR[32*x+10] IRR[32*x+9] IRR[32*x+8] 76543210 IRR[32*x+7] IRR[32*x+6] IRR[32*x+5] IRR[32*x+4] IRR[32*x+3] IRR[32*x+2] IRR[32*x+1] IRR[32*x+0] 205 32142D–06/2013 ATUC64/128/256L3/4U 12.6.3 Interrupt Cause Registers Name: ICR0...ICR3 Access Type: Read-only Offset: 0x200 - 0x20C Reset Value: N/A • CAUSE: Interrupt Group Causing Interrupt of Priority n ICRn identifies the group with the highest priority that has a pending interrupt of level n. This value is only defined when at least one interrupt of level n is pending. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CAUSE 206 32142D–06/2013 ATUC64/128/256L3/4U 12.7 Module Configuration The specific configuration for each INTC instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 12.7.1 Interrupt Request Signal Map 12.8 Interrupt Request Signal Map The various modules may output Interrupt request signals. These signals are routed to the Interrupt Controller (INTC), described in a later chapter. The Interrupt Controller supports up to 64 groups of interrupt requests. Each group can have up to 32 interrupt request signals. All interrupt signals in the same group share the same autovector address and priority level. Refer to the documentation for the individual submodules for a description of the semantics of the different interrupt requests. The interrupt request signals are connected to the INTC as follows. Table 12-2. INTC Clock Name Module Name Clock Name Description INTC CLK_INTC Clock for the INTC bus interface Table 12-3. Interrupt Request Signal Map Group Line Module Signal 0 0 AVR32UC3 CPU SYSREG COMPARE 1 0 AVR32UC3 CPU OCD DCEMU_DIRTY 1 AVR32UC3 CPU OCD DCCPU_READ 2 0 Flash Controller FLASHCDW 3 0 Secure Access Unit SAU 4 0 Peripheral DMA Controller PDCA 0 1 Peripheral DMA Controller PDCA 1 2 Peripheral DMA Controller PDCA 2 3 Peripheral DMA Controller PDCA 3 5 0 Peripheral DMA Controller PDCA 4 1 Peripheral DMA Controller PDCA 5 2 Peripheral DMA Controller PDCA 6 3 Peripheral DMA Controller PDCA 7 6 0 Peripheral DMA Controller PDCA 8 1 Peripheral DMA Controller PDCA 9 2 Peripheral DMA Controller PDCA 10 3 Peripheral DMA Controller PDCA 11 7 0 Power Manager PM 207 32142D–06/2013 ATUC64/128/256L3/4U 8 0 System Control Interface SCIF 9 0 Asynchronous Timer AST ALARM 10 0 Asynchronous Timer AST PER 1 Asynchronous Timer AST OVF 2 Asynchronous Timer AST READY 3 Asynchronous Timer AST CLKREADY 11 0 External Interrupt Controller EIC 1 1 External Interrupt Controller EIC 2 2 External Interrupt Controller EIC 3 3 External Interrupt Controller EIC 4 12 0 External Interrupt Controller EIC 5 13 0 Frequency Meter FREQM 14 0 General-Purpose Input/Output Controller GPIO 0 1 General-Purpose Input/Output Controller GPIO 1 2 General-Purpose Input/Output Controller GPIO 2 3 General-Purpose Input/Output Controller GPIO 3 4 General-Purpose Input/Output Controller GPIO 4 5 General-Purpose Input/Output Controller GPIO 5 6 General-Purpose Input/Output Controller GPIO 6 7 General-Purpose Input/Output Controller GPIO 7 15 0 Universal Synchronous Asynchronous Receiver Transmitter USART0 16 0 Universal Synchronous Asynchronous Receiver Transmitter USART1 17 0 Universal Synchronous Asynchronous Receiver Transmitter USART2 18 0 Universal Synchronous Asynchronous Receiver Transmitter USART3 19 0 Serial Peripheral Interface SPI 20 0 Two-wire Master Interface TWIM0 21 0 Two-wire Master Interface TWIM1 22 0 Two-wire Slave Interface TWIS0 23 0 Two-wire Slave Interface TWIS1 24 0 Pulse Width Modulation Controller PWMA 25 0 Timer/Counter TC00 1 Timer/Counter TC01 2 Timer/Counter TC02 Table 12-3. Interrupt Request Signal Map 208 32142D–06/2013 ATUC64/128/256L3/4U 26 0 Timer/Counter TC10 1 Timer/Counter TC11 2 Timer/Counter TC12 27 0 ADC Interface ADCIFB 28 0 Analog Comparator Interface ACIFB 29 0 Capacitive Touch Module CAT 30 0 aWire AW 31 0 Audio Bitstream DAC ABDACB 32 0 USB 2.0 Interface USBC 33 0 Inter-IC Sound (I2S) Controller IISC Table 12-3. Interrupt Request Signal Map 209 32142D–06/2013 ATUC64/128/256L3/4U 13. Power Manager (PM) Rev: 4.2.0.4 13.1 Features • Generates clocks and resets for digital logic • On-the-fly frequency change of CPU, HSB and PBx clocks • Sleep modes allow simple disabling of logic clocks and clock sources • Module-level clock gating through maskable peripheral clocks • Wake-up from internal or external interrupts • Automatic identification of reset sources • Supports advanced Shutdown sleep mode 13.2 Overview The Power Manager (PM) provides synchronous clocks used to clock the main digital logic in the device, namely the CPU, and the modules and peripherals connected to the High Speed Bus (HSB) and the Peripheral Buses (PBx). The PM contains advanced power-saving features, allowing the user to optimize the power consumption for an application. The synchronous clocks are divided into a number of clock domains, one for the CPU and HSB, and one for each PBx. The clocks can run at different speeds, allowing the user to save power by running peripherals relatively slow, whilst maintaining high CPU performance. The clocks can be independently changed on-the-fly, without halting any peripherals. The user may adjust CPU and memory speeds according to the dynamic application load, without disturbing or re-configuring active peripherals. Each module has a separate clock, enabling the user to save power by switching off clocks to inactive modules. Clocks and oscillators can be automatically switched off during idle periods by the CPU sleep instruction. The system will return to normal operation when interrupts occur. To achieve minimal power usage, a special sleep mode, called Shutdown is available, where power on all internal logic (CPU, peripherals) and most of the I/O lines is removed, reducing current leakage. Only a small amount of logic, including the 32KHz crystal oscillator (OSC32K) and the AST remain powered. The Power Manager also contains a Reset Controller, which collects all possible reset sources, generates hard and soft resets, and allows the reset source to be identified by software. 210 32142D–06/2013 ATUC64/128/256L3/4U 13.3 Block Diagram Figure 13-1. PM Block Diagram 13.4 I/O Lines Description 13.5 Product Dependencies 13.5.1 Interrupt The PM interrupt line is connected to one of the interrupt controllers internal sources. Using the PM interrupt requires the interrupt controller to be configured first. 13.5.2 Clock Implementation In ATUC64/128/256L3/4U, the HSB shares source clock with the CPU. Write attempts to the HSB Clock Select register (HSBSEL) will be ignored, and it will always read the same as the CPU Clock Select register (CPUSEL). The PM bus interface clock (CLK_PM) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. If disabled it can only be reenabled by a reset. 13.5.3 Power Considerations The Shutdown mode is only available for the “3.3V supply mode, with 1.8V regulated I/O lines“ power configuration. Table 13-1. I/O Lines Description Name Description Type Active Level RESET_N Reset Input Low Sleep Controller Synchronous Clock Generator Reset Controller Main Clock Sources Sleep Instruction Power-on Reset Detector(s) Resets Synchronous clocks CPU, HSB, PBx Interrupts External Reset Pin Reset Sources 211 32142D–06/2013 ATUC64/128/256L3/4U 13.6 Functional Description 13.6.1 Synchronous Clocks The System RC Oscillator (RCSYS) and a selection of other clock sources can provide the source for the main clock, which is the origin for the synchronous CPU/HSB and PBx module clocks. For details about the other main clock sources, please refer to the Main Clock Control (MCCTRL) register description. The synchronous clocks can run of the main clock and all the 8- bit prescaler settings as long as fCPU  fPBx,. The synchronous clock source can be changed onthe fly, according to variations in application load. The clock domains can be shut down in sleep mode, as described in Section 13.6.3. The module clocks in every synchronous clock domain can be individually masked to minimize power consumption in inactive modules. Figure 13-2. Synchronous Clock Generation 13.6.1.1 Selecting the main clock source The common main clock can be connected to RCSYS or a selection of other clock sources. For details about the other main clock sources, please refer to the MCCTRL register description. By default, the main clock will be connected to RCSYS. The user can connect the main clock to another source by writing to the Main Clock Select (MCCTRL.MCSEL) field. The user must first assure that the source is enabled and ready in order to avoid a deadlock. Care should also be taken so that the new synchronous clock frequencies do not exceed the maximum frequency for each clock domain. 13.6.1.2 Selecting synchronous clock division ratio The main clock feeds an 8-bit prescaler, which can be used to generate the synchronous clocks. By default, the synchronous clocks run on the undivided main clock. The user can select a prescaler division for the CPU clock by writing a one to the CPU Division bit in the CPU Clock Select register (CPUSEL.CPUDIV), and a value to the CPU Clock Select field (CPUSEL.CPUSEL), resulting in a CPU clock frequency: fCPU = fmain / 2(CPUSEL+1) Mask Prescaler Main Clock Sources MCSEL 0 1 CPUSEL CPUDIV Main Clock Sleep Controller CPUMASK CPU Clocks HSB Clocks PBx Clocks Sleep Instruction 212 32142D–06/2013 ATUC64/128/256L3/4U Similarly, the PBx clocks can be divided by writing their respective Clock Select (PBxSEL) registers to get the divided PBx frequency: fPBx = fmain / 2(PBSEL+1) The PBx clock frequency can not exceed the CPU clock frequency. The user must select a PBxSEL.PBSEL value greater than or equal to the CPUSEL.CPUSEL value, so that fCPU  fPBx. If the user selects division factors that will result in fCPU< fPBx, the Power Manager will automatically change the PBxSEL.PBSEL/PBDIV values to ensure correct operation (fCPU  fPBx). The HSB clock will always be forced to the same division as the CPU clock. To ensure correct operation, the frequencies must never exceed the specified maximum frequency for each clock domain. For modules connected to the HSB bus, the PB clock frequency must be the same as the CPU clock frequency. 13.6.1.3 Clock Ready flag There is a slight delay from CPUSEL and PBxSEL being written to the new clock setting taking effect. During this interval, the Clock Ready bit in the Status Register (SR.CKRDY) will read as zero. When the clock settings change is completed, the bit will read as one. The Clock Select registers (CPUSEL, PBxSEL) must not be written to while SR.CKRDY is zero, or the system may become unstable or hang. The Clock Ready bit in the Interrupt Status Register (ISR.CKRDY) is set on a SR.CKRDY zeroto-one transition. If the Clock Ready bit in the Interrupt Mask Register (IMR.CKRDY) is set, an interrupt request is generated. IMR.CKRDY is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.CKRDY). 13.6.2 Peripheral Clock Masking By default, the clocks for all modules are enabled, regardless of which modules are actually being used. It is possible to disable the clock for a module in the CPU, HSB, or PBx clock domain by writing a zero to the corresponding bit in the corresponding Clock Mask (CPUMASK/HSBMASK/PBxMASK) register. When a module is not clocked, it will cease operation, and its registers cannot be read nor written. The module can be re-enabled later by writing a one to the corresponding mask bit. A module may be connected to several clock domains, in which case it will have several mask bits. The Maskable Module Clocks table in the Clock Mask register description contains a list of implemented maskable clocks. 13.6.2.1 Cautionary note Note that clocks should only be switched off if it is certain that the module will not be used. Switching off the clock for the Flash Controller will cause a problem if the CPU needs to read from the flash. Switching off the clock to the Power Manager, which contains the mask registers, or the corresponding PBx bridge, will make it impossible to write to the mask registers again. In this case, they can only be re-enabled by a system reset. 13.6.3 Sleep Modes In normal operation, all clock domains are active, allowing software execution and peripheral operation. When the CPU is idle, it is possible to switch it and other (optional) clock domains off to save power. This is done by the sleep instruction, which takes the sleep mode index number from Table 13-2 on page 213 as argument. 213 32142D–06/2013 ATUC64/128/256L3/4U 13.6.3.1 Entering and exiting sleep modes The sleep instruction will halt the CPU and all modules belonging to the stopped clock domains. The modules will be halted regardless of the bit settings in the mask registers. Clock sources can also be switched off to save power. Some of these have a relatively long start-up time, and are only switched off when very low power consumption is required. The CPU and affected modules are restarted when the sleep mode is exited. This occurs when an interrupt triggers. Note that even if an interrupt is enabled in sleep mode, it may not trigger if the source module is not clocked. 13.6.3.2 Supported sleep modes The following sleep modes are supported. These are detailed in Table 13-2 on page 213. • Idle: The CPU is stopped, the rest of the device is operational. • Frozen: The CPU and HSB modules are stopped, peripherals are operational. • Standby: All synchronous clocks are stopped, and the clock sources are running, allowing for a quick wake-up to normal mode. • Stop: As Standby, but oscillators, and other clock sources are also stopped. 32KHz Oscillator OSC32K(2), RCSYS, AST, and WDT will remain operational. • DeepStop: All synchronous clocks and clock sources are stopped. Bandgap voltage reference and BOD are turned off. OSC32K(2) and RCSYS remain operational. • Static: All clock sources, including RCSYS are stopped. Bandgap voltage reference and BOD are turned off. OSC32K(2) remains operational. • Shutdown: All clock sources, including RCSYS are stopped. Bandgap voltage reference, BOD detector, and Voltage regulator are turned off. OSC32K(2) remains operational. This mode can only be used in the “3.3V supply mode, with 1.8V regulated I/O lines“ configuration (described in Power Considerations chapter). Refer to Section 13.6.4 for more details. Notes: 1. The sleep mode index is used as argument for the sleep instruction. 2. OSC32K will only remain operational if pre-enabled. 3. Clock sources other than those specifically listed in the table. 4. SYSTIMER is the clock for the CPU COUNT and COMPARE registers. The internal voltage regulator is also adjusted according to the sleep mode in order to reduce its power consumption. Table 13-2. Sleep Modes Index(1) Sleep Mode CPU HSB PBx, GCLK Clock Sources(3), SYSTIMER(4) OSC32K(2) RCSYS BOD & Bandgap Voltage Regulator 0 Idle Stop Run Run Run Run Run On Normal mode 1 Frozen Stop Stop Run Run Run Run On Normal mode 2 Standby Stop Stop Stop Run Run Run On Normal mode 3 Stop Stop Stop Stop Stop Run Run On Low power mode 4 DeepStop Stop Stop Stop Stop Run Run Off Low power mode 5 Static Stop Stop Stop Stop Run Stop Off Low power mode 6 Shutdown Stop Stop Stop Stop Run Stop Off Off 214 32142D–06/2013 ATUC64/128/256L3/4U 13.6.3.3 Waking from sleep modes There are two types of wake-up sources from sleep mode, synchronous and asynchronous. Synchronous wake-up sources are all non-masked interrupts. Asynchronous wake-up sources are AST, WDT, external interrupts from EIC, external reset, external wake pin (WAKE_N), and all asynchronous wake-ups enabled in the Asynchronous Wake Up Enable (AWEN) register. The valid wake-up sources for each sleep mode are detailed in Table 13-3 on page 214. In Shutdown the only wake-up sources are external reset, external wake-up pin or AST. See Section 13.6.4.3 on page 216. Notes: 1. The sleep mode index is used as argument for the sleep instruction. 2. Only PB modules operational, as HSB module clocks are stopped. 3. WDT only available if clocked from pre-enabled OSC32K. 13.6.3.4 SleepWalking In all sleep modes where the PBx clocks are stopped, except for Shutdown mode, the device can partially wake up if a PBx module asynchronously discovers that it needs its clock. Only the requested clocks and clock sources needed will be started, all other clocks will remain masked to zero. E.g. if the main clock source is OSC0, only OSC0 will be started even if other clock sources were enabled in normal mode. Generic clocks can also be started in a similar way. The state where only requested clocks are running is referred to as SleepWalking. The time spent to start the requested clock is mostly limited by the startup time of the given clock source. This allows PBx modules to handle incoming requests, while still keeping the power consumption at a minimum. When the device is SleepWalking any asynchronous wake-up can wake the device up at any time without stopping the requested PBx clock. All requests to start clocks can be masked by writing to the Peripheral Power Control Register (PPCR), all requests are enabled at reset. During SleepWalking the interrupt controller clock will be running. If an interrupt is pending when entering SleepWalking, it will wake the whole device up. 13.6.3.5 Precautions when entering sleep mode Modules communicating with external circuits should normally be disabled before entering a sleep mode that will stop the module operation. This will prevent erratic behavior caused by entering or exiting sleep modes. Please refer to the relevant module documentation for recommended actions. Table 13-3. Wake-up Sources Index(1) Sleep Mode Wake-up Sources 0 Idle Synchronous, Asynchronous 1 Frozen Synchronous(2), Asynchronous 2 Standby Asynchronous 3 Stop Asynchronous 4 DeepStop Asynchronous 5 Static Asynchronous(3) 6 Shutdown External reset, External wake-up pin 215 32142D–06/2013 ATUC64/128/256L3/4U Communication between the synchronous clock domains is disturbed when entering and exiting sleep modes. Bus transactions over clock domains affected by the sleep mode are therefore not recommended. The system may hang if the bus clocks are stopped during a bus transaction. The CPU is automatically stopped in a safe state to ensure that all CPU bus operations are complete when the sleep mode goes into effect. Thus, when entering Idle mode, no further action is necessary. When entering a sleep mode (except Idle mode), all HSB masters must be stopped before entering the sleep mode. In order to let potential PBx write operations complete, the user should let the CPU perform a PBx register read operation before issuing the sleep instruction. This will stall the CPU until pending PBx operations have completed. The Shutdown sleep mode requires extra care. Please refer to Section 13.6.4. 13.6.4 Shutdown Sleep Mode 13.6.4.1 Description The Shutdown sleep mode is available only when the device is used in the “3.3V supply mode, with 1.8V regulated I/O lines“ configuration (refer to the Power Considerations chapter). In this configuration, the voltage regulator supplies both VDDCORE and VDDIO power supplies. When the device enters Shutdown mode, the regulator is turned off and only the following logic is kept powered by VDDIN: – OSC32K using alternate pinout PA13/PA20 – AST core logic (internal counter and alarm detection logic) – Backup Registers – I/O lines PA11, PA13, PA20, PA21, PB04, PB05, and PB10 – RESET_N line The table below lists I/O line functionality that remains operational during Shutdown sleep mode. If no special function is used the I/O line will keep its setting when entering the sleep mode 13.6.4.2 Entering Shutdown sleep mode Before entering the Shutdown sleep mode, a few actions are required: – All modules should normally be disabled before entering Shutdown sleep mode (see Section 13.6.3.5) Table 13-4. I/O Lines Usage During Shutdown Mode Pin Possible Usage During Shutdown Sleep Mode PA11 WAKE_N signal (active low wake-up) PA13 XIN32_2 (OSC32K using alternate pinout) PA20 XOUT32_2 (OSC32K using alternate pinout) PA21 PB04 PB05 PB10 RESET_N Reset pin 216 32142D–06/2013 ATUC64/128/256L3/4U – The POR33 must be masked to avoid spurious resets when the power is back. This must also be done when POR33 is disabled, as POR33 will be enabled automatically when the device wakes up from Shutdown mode. Disable the POR33 by writing a one to the POR33MASK bit in the SCIF.VREGCR register. Due to internal synchronisation, this bit must be read as a one before the sleep instruction is executed by the CPU. Refer to the System Control Interface (SCIF) chapter for more details. – The 32KHz RC oscillator (RC32K) must be running and stable. This is done by writing a one to the EN bit in the SCIF.RC32KCR register. Due to internal synchronisation, this bit must be read as a one to ensure that the oscillator is stable before the sleep instruction is executed by the CPU. As soon as the Shutdown sleep mode is entered, all CPU and peripherals are reset to ensure a consistent state. POR33 and RC32K are automatically disabled to save extra power. 13.6.4.3 Leaving Shutdown sleep mode Exiting Shutdown sleep mode can be done by the events described in Table 13-5. When a wake-up event occurs, the regulator is turned on and the device will wait for VDDCORE to be valid before starting. The Sleep Reset bit in the Reset Cause register (RCAUSE.SLEEP) is then set, allowing software running on the device to distinguish between the first power-up and a wake-up from Shutdown mode. 13.6.4.4 Special consideration regarding waking up from Shutdown sleep mode using the WAKE_N pin By default, the WAKE_N pin will only wake the device up if it is pulled low after entering Shutdown mode. If the WAKE_N is pulled low before the Shutdown mode is entered, it will not wake the device from the Shutdown sleep mode. In order to wake the device by pulling WAKE_N low before entering Shutdown mode, the user has to write a one to the bit corresponding to the WAKEN wake-up source in the AWEN register. In this scenario, the CPU execution will proceed with the next instruction, and the RCAUSE register content will not be altered. 13.6.5 Divided PB Clocks The clock generator in the Power Manager provides divided PBx clocks for use by peripherals that require a prescaled PBx clock. This is described in the documentation for the relevant modules. The divided clocks are directly maskable, and are stopped in sleep modes where the PBx clocks are stopped. Table 13-5. Events That Can Wake up the Device from Shutdown Mode Source How PA11 (WAKE_N) Pulling-down PA11 will wake up the device RESET_N Pulling-down RESET_N pin will wake up the device The device is kept under reset until RESET_N is tied high again AST OSC32K must be set-up to use alternate pinout (XIN32_2 and XOUT32_2) Refer to the SCIF Chapter AST must be configured to use the clock from OSC32K AST must be configured to allow alarm, periodic, or overflow wake-up 217 32142D–06/2013 ATUC64/128/256L3/4U 13.6.6 Reset Controller The Reset Controller collects the various reset sources in the system and generates hard and soft resets for the digital logic. The device contains a Power-on Reset (POR) detector, which keeps the system reset until power is stable. This eliminates the need for external reset circuitry to guarantee stable operation when powering up the device. It is also possible to reset the device by pulling the RESET_N pin low. This pin has an internal pull-up, and does not need to be driven externally during normal operation. Table 13-6 on page 217 lists these and other reset sources supported by the Reset Controller. Figure 13-3. Reset Controller Block Diagram In addition to the listed reset types, the JTAG & aWire can keep parts of the device statically reset. See JTAG and aWire documentation for details. Table 13-6. Reset Description Reset Source Description Power-on Reset Supply voltage below the Power-on Reset detector threshold voltage VPOT External Reset RESET_N pin asserted Brown-out Reset VDDCORE supply voltage below the Brown-out detector threshold voltage JTAG Reset Controller RESET_N Power-on Reset Detector(s) OCD Watchdog Reset RCAUSE CPU, HSB, PBx OCD, AST, WDT, Clock Generator Brown-out Detector AWIRE SM33 Detector 218 32142D–06/2013 ATUC64/128/256L3/4U Depending on the reset source, when a reset occurs, some parts of the device are not always reset. Only the Power-on Reset (POR) will force a whole device reset. Refer to the table in the Module Configuration section at the end of this chapter for further details. The latest reset cause can be read in the RCAUSE register, and can be read during the applications boot sequence in order to determine proper action. 13.6.6.1 Power-on Reset Detector The Power-on Reset 1.8V (POR18) detector monitors the VDDCORE supply pin and generates a Power-on Reset (POR) when the device is powered on. The POR is active until the VDDCORE voltage is above the power-on threshold level (VPOT). The POR will be re-generated if the voltage drops below the power-on threshold level. See Electrical Characteristics for parametric details. The Power-on Reset 3.3V (POR33) detector monitors the internal regulator supply pin and generates a Power-on Reset (POR) when the device is powered on. The POR is active until the internal regulator supply voltage is above the regulator power-on threshold level (VPOT). The POR will be re-generated if the voltage drops below the regulator power-on threshold level. See Electrical Characteristics for parametric details. 13.6.6.2 External Reset The external reset detector monitors the RESET_N pin state. By default, a low level on this pin will generate a reset. 13.6.7 Clock Failure Detector This mechanism automatically switches the main clock source to the safe RCSYS clock when the main clock source fails. This may happen when an external crystal is selected as a source for the main clock and the crystal is not mounted on the board. The main clock is compared with RCSYS, and if no rising edge of the main clock is detected during one RCSYS period, the clock is considered to have failed. The detector is enabled by writing a one to the Clock Failure Detection Enable bit in the Clock Failure Detector Control Register (CFDCTRL.CFDEN). As soon as the detector is enabled, the clock failure detector will monitor the divided main clock. Note that the detector does not monitor the main clock if RCSYS is the source of the main clock, or if the main clock is temporarily not available (startup-time after a wake-up, switching timing etc.), or in sleep mode where the main clock is driven by the RCSYS (Stop and DeepStop mode). When a clock failure is detected, the main clock automatically switches to the RCSYS clock and the Clock Failure Detected (CFD) interrupt is generated if enabled. The MCCTRL register is also changed by hardware to indicate that the main clock comes from RCSYS. 13.6.8 Interrupts The PM has a number of interrupt sources: • AE - Access Error, SM33 Reset Internal regulator supply voltage below the SM33 threshold voltage. This generates a Power-on Reset. Watchdog Timer See Watchdog Timer documentation OCD See On-Chip Debug documentation Reset Source Description 219 32142D–06/2013 ATUC64/128/256L3/4U – A lock protected register is written to without first being unlocked. • CKRDY - Clock Ready: – New Clock Select settings in the CPUSEL/PBxSEL registers have taken effect. (A zero-to-one transition on SR.CKRDY is detected). • CFD - Clock Failure Detected: – The system detects that the main clock is not running. The Interrupt Status Register contains one bit for each interrupt source. A bit in this register is set on a zero-to-one transition of the corresponding bit in the Status Register (SR), and cleared by writing a one to the corresponding bit in the Interrupt Clear Register (ICR). The interrupt sources will generate an interrupt request if the corresponding bit in the Interrupt Mask Register is set. The interrupt sources are ORed together to form one interrupt request. The Power Manager will generate an interrupt request if at least one of the bits in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in the Interrupt Status Register (ISR) is cleared by writing a one to the corresponding bit in the Interrupt Clear Register (ICR). Because all the interrupt sources are ORed together, the interrupt request from the Power Manager will remain active until all the bits in ISR are cleared. 220 32142D–06/2013 ATUC64/128/256L3/4U 13.7 User Interface Note: 1. The reset value is device specific. Please refer to the Module Configuration section at the end of this chapter. 2. Latest Reset Source. 3. Latest Wake Source. Table 13-7. PM Register Memory Map Offset Register Register Name Access Reset 0x000 Main Clock Control MCCTRL Read/Write 0x00000000 0x004 CPU Clock Select CPUSEL Read/Write 0x00000000 0x008 HSB Clock Select HSBSEL Read-only 0x00000000 0x00C PBA Clock Select PBASEL Read/Write 0x00000000 0x010 PBB Clock Select PBBSEL Read/Write 0x00000000 0x014 - 0x01C Reserved 0x020 CPU Mask CPUMASK Read/Write 0x00010001 0x024 HSB Mask HSBMASK Read/Write 0x0000007F 0x028 PBA Mask PBAMASK Read/Write 0x0FFFFFFF 0x02C PBB Mask PBBMASK Read/Write 0x0000000F 0x030- 0x03C Reserved 0x040 PBA Divided Mask PBADIVMASK Read/Write 0x0000007F 0x044 - 0x050 Reserved 0x054 Clock Failure Detector Control CFDCTRL Read/Write 0x00000000 0x058 Unlock Register UNLOCK Write-only 0x00000000 0x05C - 0x0BC Reserved 0x0C0 Interrupt Enable Register IER Write-only 0x00000000 0x0C4 Interrupt Disable Register IDR Write-only 0x00000000 0x0C8 Interrupt Mask Register IMR Read-only 0x00000000 0x0CC Interrupt Status Register ISR Read-only 0x00000000 0x0D0 Interrupt Clear Register ICR Write-only 0x00000000 0x0D4 Status Register SR Read-only 0x00000020 0x0D8 - 0x15C Reserved 0x160 Peripheral Power Control Register PPCR Read/Write 0x000001FA 0x164 - 0x17C Reserved 0x180 Reset Cause Register RCAUSE Read-only -(2) 0x184 Wake Cause Register WCAUSE Read-only -(3) 0x188 Asynchronous Wake Up Enable Register AWEN Read/Write 0x00000000 0x18C - 0x3F4 Reserved 0x3F8 Configuration Register CONFIG Read-only 0x00000043 0x3FC Version Register VERSION Read-only -(1) 221 32142D–06/2013 ATUC64/128/256L3/4U 13.7.1 Main Clock Control Name: MCCTRL Access Type: Read/Write Offset: 0x000 Reset Value: 0x00000000 • MCSEL: Main Clock Select Note: 1. If the 120MHz RC oscillator is selected as main clock source, it must be divided by at least 4 before being used as clock source for the CPU. This division is selected by writing to the CPUSEL and CPUDIV bits in the CPUSEL register, before switching to RC120M as main clock source. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - MCSEL Table 13-8. Main clocks in ATUC64/128/256L3/4U. MCSEL[2:0] Main clock source 0 System RC oscillator (RCSYS) 1 Oscillator0 (OSC0) 2 DFLL 3 120MHz RC oscillator (RC120M)(1) 222 32142D–06/2013 ATUC64/128/256L3/4U 13.7.2 CPU Clock Select Name: CPUSEL Access Type: Read/Write Offset: 0x004 Reset Value: 0x00000000 • CPUDIV, CPUSEL: CPU Division and Clock Select CPUDIV = 0: CPU clock equals main clock. CPUDIV = 1: CPU clock equals main clock divided by 2(CPUSEL+1). Note that if CPUDIV is written to 0, CPUSEL should also be written to 0 to ensure correct operation. Also note that writing this register clears POSCSR.CKRDY. The register must not be re-written until CKRDY goes high. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 CPUDIV - - - - CPUSEL 223 32142D–06/2013 ATUC64/128/256L3/4U 13.7.3 HSB Clock Select Name: HSBSEL Access Type: Read Offset: 0x008 Reset Value: 0x00000000 This register is read-only and its content is always equal to CPUSEL. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 HSBDIV - - - - HSBSEL 224 32142D–06/2013 ATUC64/128/256L3/4U 13.7.4 PBx Clock Select Name: PBxSEL Access Type: Read/Write Offset: 0x00C-0x010 Reset Value: 0x00000000 • PBDIV, PBSEL: PBx Division and Clock Select PBDIV = 0: PBx clock equals main clock. PBDIV = 1: PBx clock equals main clock divided by 2(PBSEL+1). Note that if PBDIV is written to 0, PBSEL should also be written to 0 to ensure correct operation. Also note that writing this register clears SR.CKRDY. The register must not be re-written until SR.CKRDY is set. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 PBDIV - - - - PBSEL 225 32142D–06/2013 ATUC64/128/256L3/4U 13.7.5 Clock Mask Name: CPUMASK/HSBMASK/PBAMASK/PBBMASK Access Type: Read/Write Offset: 0x020-0x02C Reset Value: - • MASK: Clock Mask If bit n is cleared, the clock for module n is stopped. If bit n is set, the clock for module n is enabled according to the current power mode. The number of implemented bits in each mask register, as well as which module clock is controlled by each bit, is shown in Table 13-9. 31 30 29 28 27 26 25 24 MASK[31:24] 23 22 21 20 19 18 17 16 MASK[23:16] 15 14 13 12 11 10 9 8 MASK[15:8] 76543210 MASK[7:0] Table 13-9. Maskable Module Clocks in ATUC64/128/256L3/4U. Bit CPUMASK HSBMASK PBAMASK PBBMASK 0 OCD PDCA PDCA FLASHCDW 1 - FLASHCDW INTC HMATRIX 2 - SAU PM SAU 3 - PBB bridge SCIF USBC 4 - PBA bridge AST - 5 - Peripheral Event System WDT - 6 - USBC EIC - 7 - - FREQM - 8 - - GPIO - 9 - - USART0 - 10 - - USART1 - 11 - - USART2 - 226 32142D–06/2013 ATUC64/128/256L3/4U Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 12 - - USART3 - 13 - - SPI - 14 - - TWIM0 - 15 - - TWIM1 - 16 SYSTIMER - TWIS0 - 17 - - TWIS1 - 18 - - PWMA - 19 - - TC0 - 20 - - TC1 - 21 - - ADCIFB - 22 - - ACIFB - 23 - - CAT - 24 - - GLOC - 25 - - AW - 26 - - ABDACB - 27 - - IISC - 31:28 - - - - Table 13-9. Maskable Module Clocks in ATUC64/128/256L3/4U. Bit CPUMASK HSBMASK PBAMASK PBBMASK 227 32142D–06/2013 ATUC64/128/256L3/4U 13.7.6 PBA Divided Mask Name: PBADIVMASK Access Type: Read/Write Offset: 0x040 Reset Value: 0x0000007F • MASK: Clock Mask If bit n is written to zero, the clock divided by 2(n+1) is stopped. If bit n is written to one, the clock divided by 2(n+1) is enabled according to the current power mode. Table 13-10 shows what clocks are affected by the different MASK bits. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - ------ 15 14 13 12 11 10 9 8 -------- 76543210 - MASK[6:0] Table 13-10. Divided Clock Mask Bit USART0 USART1 USART2 USART3 TC0 TC1 0 - - - - TIMER_CLOCK2 TIMER_CLOCK2 1- - - - - - 2 CLK_USART/ DIV CLK_USART/ DIV CLK_USART/ DIV CLK_USART/ DIV TIMER_CLOCK3 TIMER_CLOCK3 3- - - - - - 4 - - - - TIMER_CLOCK4 TIMER_CLOCK4 5- - - - - - 6 - - - - TIMER_CLOCK5 TIMER_CLOCK5 228 32142D–06/2013 ATUC64/128/256L3/4U 13.7.7 Clock Failure Detector Control Register Name: CFDCTRL Access Type: Read/Write Offset: 0x054 Reset Value: 0x00000000 • SFV: Store Final Value 0: The register is read/write 1: The register is read-only, to protect against further accidental writes. • CFDEN: Clock Failure Detection Enable 0: Clock Failure Detector is disabled 1: Clock Failure Detector is enabled Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 SFV - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - CFDEN 229 32142D–06/2013 ATUC64/128/256L3/4U 13.7.8 Unlock Register Name: UNLOCK Access Type: Write-only Offset: 0x058 Reset Value: 0x00000000 To unlock a write protected register, first write to the UNLOCK register with the address of the register to unlock in the ADDR field and 0xAA in the KEY field. Then, in the next PB access write to the register specified in the ADDR field. • KEY: Unlock Key Write this bit field to 0xAA to enable unlock. • ADDR: Unlock Address Write the address of the register to unlock to this field. 31 30 29 28 27 26 25 24 KEY 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - ADDR[9:8] 76543210 ADDR[7:0] 230 32142D–06/2013 ATUC64/128/256L3/4U 13.7.9 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x0C0 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 231 32142D–06/2013 ATUC64/128/256L3/4U 13.7.10 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x0C4 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 232 32142D–06/2013 ATUC64/128/256L3/4U 13.7.11 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x0C8 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 233 32142D–06/2013 ATUC64/128/256L3/4U 13.7.12 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x0CC Reset Value: 0x00000000 0: The corresponding interrupt is cleared. 1: The corresponding interrupt is pending. This bit is cleared when the corresponding bit in ICR is written to one. This bit is set on a zero-to-one transition of the corresponding bit in the Status Register (SR). 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 234 32142D–06/2013 ATUC64/128/256L3/4U 13.7.13 Interrupt Clear Register Name: ICR Access Type: Write-only Offset: 0x0D0 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in ISR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 235 32142D–06/2013 ATUC64/128/256L3/4U 13.7.14 Status Register Name: SR Access Type: Read-only Offset: 0x0D4 Reset Value: 0x00000020 • AE: Access Error 0: No access error has occurred. 1: A write to lock protected register without unlocking it has occurred. • CKRDY: Clock Ready 0: One of the CPUSEL/PBxSEL registers has been written, and the new clock setting is not yet effective. 1: The synchronous clocks have frequencies as indicated in the CPUSEL/PBxSEL registers. • CFD: Clock Failure Detected 0: Main clock is running correctly. 1: Failure on main clock detected. Main clock is now running on RCSYS. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 236 32142D–06/2013 ATUC64/128/256L3/4U 13.7.15 Peripheral Power Control Register Name: PPCR Access Type: Read/Write Offset: 0x004 Reset Value: 0x000001FA • RSTTM: Reset test mode 0: External reset not in test mode 1: External reset in test mode • FRC32: Force RC32 out 0: RC32 signal is not forced as output 1: RC32 signal is forced as output • RSTPUN: Reset Pull-up, active low 0: Pull-up for external reset on 1: Pull-up for external reset off 31 30 29 28 27 26 25 24 PPC[31:24] 23 22 21 20 19 18 17 16 PPC[23:16] 15 14 13 12 11 10 9 8 PPC[15:8] 76543210 PPC[7:0] Table 13-11. Peripheral Power Control Bit Name 0 RSTPUN 1 FRC32 2 RSTTM 3 CATRCMASK 4 ACIFBCRCMASK 5 ADCIFBRCMASK 6 ASTRCMASK 7 TWIS0RCMASK 8 TWIS1RCMASK 31:9 - 237 32142D–06/2013 ATUC64/128/256L3/4U • CATRCMASK: CAT Request Clock Mask 0: CAT Request Clock is disabled 1: CAT Request Clock is enabled • ACIFBRCMASK: ACIFB Request Clock Mask 0: ACIFB Request Clock is disabled 1: ACIFB Request Clock is enabled • ADCIFBRCMASK: ADCIFB Request Clock Mask 0: ADCIFB Request Clock is disabled 1: ADCIFB Request Clock is enabled • ASTRCMASK: AST Request Clock Mask 0: AST Request Clock is disabled 1: AST Request Clock is enabled • TWIS0RCMASK: TWIS0 Request Clock Mask 0: TWIS0 Request Clock is disabled 1: TWIS0 Request Clock is enabled • TWIS1RCMASK: TWIS1 Request Clock Mask 0: TWIS1 Request Clock is disabled 1: TWIS1 Request Clock is enabled Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 238 32142D–06/2013 ATUC64/128/256L3/4U 13.7.16 Reset Cause Register Name: RCAUSE Access Type: Read-only Offset: 0x180 Reset Value: Latest Reset Source • AWIRE: aWire Reset This bit is set when the last reset was caused by the aWire. • JTAG: JTAG Reset This bit is set when the last reset was caused by the JTAG. • OCDRST: OCD Reset This bit is set when the last reset was due to the RES bit in the OCD Development Control register having been written to one. • SLEEP: Sleep Reset This bit is set when the last reset was due to the device waking up from the Shutdown sleep mode. • WDT: Watchdog Reset This bit is set when the last reset was due to a watchdog time-out. • EXT: External Reset Pin This bit is set when the last reset was due to the RESET_N pin being pulled low. • BOD: Brown-out Reset This bit is set when the last reset was due to the core supply voltage being lower than the brown-out threshold level. • POR: Power-on Reset This bit is set when the last reset was due to the core supply voltage VDDCORE being lower than the power-on threshold level (the reset is generated by the POR18 detector), or the internal regulator supply voltage being lower than the regulator power-on threshold level (generated by the POR33 detector), or the internal regulator supply voltage being lower than the minimum required input voltage (generated by the 3.3V supply monitor SM33). 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - AWIRE - JTAG OCDRST 76543210 - SLEEP - - WDT EXT BOD POR 239 32142D–06/2013 ATUC64/128/256L3/4U 13.7.17 Wake Cause Register Name: WCAUSE Access Type: Read-only Offset: 0x184 Reset Value: Latest Wake Source A bit in this register is set on wake up caused by the peripheral referred to in Table 13-12 on page 239. 31 30 29 28 27 26 25 24 WCAUSE[31:24] 23 22 21 20 19 18 17 16 WCAUSE[23:16] 15 14 13 12 11 10 9 8 WCAUSE[15:8] 76543210 WCAUSE[7:0] Table 13-12. Wake Cause Bit Wake Cause 0 CAT 1 ACIFB 2 ADCIFB 3 TWI Slave 0 4 TWI Slave 1 5 WAKE_N 6 ADCIFB Pen Detect 7 USBC 15:8 - 16 EIC 17 AST 31:18 - 240 32142D–06/2013 ATUC64/128/256L3/4U 13.7.18 Asynchronous Wake Up Enable Register Name: AWEN Access Type: Read/Write Offset: 0x188 Reset Value: 0x00000000 Each bit in this register corresponds to an asynchronous wake-up source, according to Table 13-13 on page 240. 0: The corresponding wake up is disabled. 1: The corresponding wake up is enabled 31 30 29 28 27 26 25 24 AWEN[31:24] 23 22 21 20 19 18 17 16 AWEN[23:16] 15 14 13 12 11 10 9 8 AWEN[15:8] 76543210 AWEN[7:0] Table 13-13. Asynchronous Wake-up Sources Bit Asynchronous Wake-up Source 0 CAT 1 ACIFB 2 ADCIFB 3 TWIS0 4 TWIS1 5 WAKEN 6 ADCIFBPD 7 USBC 31:8 - 241 32142D–06/2013 ATUC64/128/256L3/4U 13.7.19 Configuration Register Name: CONFIG Access Type: Read-Only Offset: 0x3F8 Reset Value: - This register shows the configuration of the PM. • HSBPEVC:HSB PEVC Clock Implemented 0: HSBPEVC not implemented. 1: HSBPEVC implemented. • PBD: PBD Implemented 0: PBD not implemented. 1: PBD implemented. • PBC: PBC Implemented 0: PBC not implemented. 1: PBC implemented. • PBB: PBB Implemented 0: PBB not implemented. 1: PBB implemented. • PBA: PBA Implemented 0: PBA not implemented. 1: PBA implemented. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 HSBPEVC - - - PBD PBC PBB PBA 242 32142D–06/2013 ATUC64/128/256L3/4U 13.7.20 Version Register Name: VERSION Access Type: Read-Only Offset: 0x3FC Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 243 32142D–06/2013 ATUC64/128/256L3/4U 13.8 Module Configuration The specific configuration for each PM instance is listed in the following tables. The module bus clocks listed here are connected to the system bus clocks. Please refer to the “Synchronous Clocks”, “Peripheral Clock Masking” and “Sleep Modes” sections for details. Table 13-14. Power Manager Clocks Clock Name Description CLK_PM Clock for the PM bus interface Table 13-15. Register Reset Values Register Reset Value VERSION 0x00000420 Table 13-16. Effect of the Different Reset Events Power-on Reset External Reset Watchdog Reset BOD Reset SM33 Reset CPU Error Reset OCD Reset JTAG Reset CPU/HSB/PBx (excluding Power Manager) Y Y Y YY Y YY 32KHz oscillator Y N N N N N N N RC Oscillator Calibration register Y N N N N N N N Other oscillator control registers Y Y Y Y Y Y Y Y AST registers, except interrupt registers Y N N NN N NN Watchdog control register Y Y N Y Y Y Y Y Voltage Calibration register Y N N N N N N N SM33 control register Y Y Y Y Y Y Y Y BOD control register Y Y Y N Y Y Y Y Clock control registers Y Y Y Y Y Y Y Y OCD system and OCD registers Y Y N Y Y Y N Y 244 32142D–06/2013 ATUC64/128/256L3/4U 14. System Control Interface (SCIF) Rev: 1.1.0.0 14.1 Features • Supports crystal oscillator 0.45-16MHz (OSC0) • Supports Digital Frequency Locked Loop 20-150MHz (DFLL) • Supports Phase Locked Loop 80-240MHz (PLL) • Supports 32KHz ultra-low-power oscillator (OSC32K) • Supports 32kHz RC oscillator (RC32K) • Integrated low-power RC oscillator (RCSYS) • Generic clocks (GCLK) with wide frequency range provided • Generic Clock Prescaler • Controls Bandgap • Controls Brown-out detectors (BOD) and supply monitors • Controls Voltage Regulator (VREG) behavior and calibration • Controls Temperature Sensor • Controls Supply Monitor 33 (SM33) operating modes and calibration • Controls 120MHz integrated RC Oscillator (RC120M) • Four 32-bit general-purpose backup registers 14.2 Overview The System Control Interface (SCIF) controls the oscillators, Generic Clocks, BODs, Bandgap, VREG, Temperature Sensor, and Backup Registers. 14.3 I/O Lines Description 14.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. Table 14-1. I/O Lines Description Pin Name Pin Description Type RC32OUT RC32 output at startup Output XIN0 Crystal 0 Input Analog/Digital XIN32 Crystal 32 Input (primary location) Analog/Digital XIN32_2 Crystal 32 Input (secondary location) Analog/Digital XOUT0 Crystal 0 Output Analog XOUT32 Crystal 32 Output (primary location) Analog XOUT32_2 Crystal 32 Output (secondary location) Analog GCLK9-GCLK0 Generic Clock Output Output GCLK_IN2-GCLK_IN0 Generic Clock Input Input 245 32142D–06/2013 ATUC64/128/256L3/4U 14.4.1 I/O Lines The SCIF provides a number of generic clock outputs, which can be connected to output pins, multiplexed with GPIO lines. The programmer must first program the GPIO controller to assign these pins to their peripheral function. If the I/O pins of the SCIF are not used by the application, they can be used for other purposes by the GPIO controller. Oscillator pins are also multiplexed with GPIO. When oscillators are used, the related pins are controlled directly by the SCIF, overriding GPIO settings. RC32OUT will be output after reset, and the GPIO controller can assign this pin to other peripheral function after start-up. 14.4.2 Power Management The BODs and all the oscillators, except the 32KHz oscillator (OSC32K) are turned off in some sleep modes and turned automatically on when the device wakes up. The Voltage Regulator is set in low power mode in some sleep modes and automatically set back in normal mode when the device wakes up. Please refer to the Power Manager chapter for details. The BOD control registers will not be reset by the Power Manager on a BOD reset. 14.4.3 Clocks The SCIF controls all oscillators in the device. The oscillators can be used as source for the CPU and peripherals. Selection of source is done in the Power Manager. The oscillators can also be used as source for generic clocks. 14.4.4 Interrupts The SCIF interrupt request line is connected to the interrupt controller. Using the SCIF interrupt requires the interrupt controller to be programmed first. 14.4.5 Debug Operation The SCIF does not interact with debug operations. 14.5 Functional Description 14.5.1 Oscillator (OSC) Operation Rev: 1.1.1.0 The main oscillator (OSCn) is designed to be used with an external 0.450 to 16MHz crystal and two biasing capacitors, as shown in the Electrical Characteristics chapter, or with an external clock connected to the XIN. The oscillator can be used as source for the main clock in the device, as described in the Power Manager chapter. The oscillator can be used as source for the generic clocks, as described in the Generic Clocks section. The oscillator is disabled by default after reset. When the oscillator is disabled, the XIN and XOUT pins can be used as general purpose I/Os. When the oscillator is enabled, the XIN and XOUT pins are controlled directly by the SCIF, overriding GPIO settings. When the oscillator is configured to use an external clock, the clock must be applied to the XIN pin while the XOUT pin can be used as general purpose I/O. The oscillator is enabled by writing a one to the Oscillator Enable bit in the Oscillator Control register (OSCCTRLn.OSCEN). Operation mode (external clock or crystal) is selected by writing to the Oscillator Mode bit in OSCCTRLn (OSCCTRLn.MODE). The oscillator is automatically dis- 246 32142D–06/2013 ATUC64/128/256L3/4U abled in certain sleep modes to reduce power consumption, as described in the Power Manager chapter. After a hard reset, or when waking up from a sleep mode where the oscillators were disabled, the oscillator will need a certain amount of time to stabilize on the correct frequency. This startup time can be set in the OSCCTRLn register. The SCIF masks the oscillator outputs during the start-up time, to ensure that no unstable clocks propagate to the digital logic. The OSCn Ready bit in the Power and Clock Status Register (PCLKSR.OSCnRDY) is set when the oscillator is stable and ready to be used as clock source. An interrupt can be generated on a zero-to-one transition on OSCnRDY if the OSCnRDY bit in the Interrupt Mask Register (IMR.OSCnRDY) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.OSCnRDY). 14.5.2 32KHz Oscillator (OSC32K) Operation Rev: 1.1.0.1 The 32KHz oscillator operates as described for the oscillator above. The 32KHz oscillator can be used as source clock for the Asynchronous Timer (AST) and the Watchdog Timer (WDT). The 32KHz oscillator can also be used as source for the generic clocks. The oscillator is disabled by default after reset. When the oscillator is disabled, the XIN32 and XOUT32 pins can be used as general-purpose I/Os. When the oscillator is enabled, the XIN32 and XOUT32 pins are controlled directly by the SCIF, overriding GPIO settings. When the oscillator is configured to use an external clock, the clock must be applied to the XIN32 pin while the XOUT32 pin can be used as general-purpose I/O. The oscillator is enabled writing a one to the OSC32 Enable bit in the 32KHz Oscillator Control Register (OSCCTRL32OSC32EN). The oscillator is disabled by writing a zero to the OSC32EN bit, while keeping the other bits unchanged. Writing to OSC32EN while also writing to other bits may result in unpredictable behavior. Operation mode (external clock or crystal) is selected by writing to the Oscillator Mode bit in OSCCTRL32 (OSCCTRL32.MODE). The oscillator is an ultra-low-power design and remains enabled in all sleep modes. The start-up time of the 32KHz oscillator is selected by writing to the Oscillator Start-up Time field in the OSCCTRL32 register (OSCCTRL32.STARTUP). The SCIF masks the oscillator output during the start-up time, to ensure that no unstable clock cycles propagate to the digital logic. The OSC32 Ready bit in the Power and Clock Status Register (PCLKSR.OSC32RDY) is set when the oscillator is stable and ready to be used as clock source. An interrupt can be generated on a zero-to-one transition on PCLKSR.OSC32RDY if the OSC32RDY bit in the Interrupt Mask Register (IMR.OSC32RDY) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.OSC32RDY). .As a crystal oscillator usually requires a very long start-up time (up to 1 second), the 32KHz oscillator will keep running across resets, except a Power-on Reset (POR). The 32KHz oscillator also has a 1KHz output. This is enabled by writing a one to the Enable 1KHz output bit in OSCCTRL32 register (OSCCTRL32.EN1K). If the 32KHz output clock is not needed when 1K is enabled, this can be disabled by writing a zero to the Enable 32KHz output bit in the OSCCTRL32 register (OSCCTRL32.EN32K). OSCCTRL32.EN32K is set after a POR. The 32KHz oscillator has two possible sets of pins. To select between them write to the Pin Select bit in the OSCCTRL32 register (OSCCTRL32.PINSEL). If the 32KHz oscillator is to be 247 32142D–06/2013 ATUC64/128/256L3/4U used in Shutdown mode, PINSEL must be written to one, and XIN32_2 and XOUT32_2 must be used. 14.5.3 PLL Operation Rev: 1.1.0.0 The device contains one Phase Locked Loop (PLL), which is controlled by the Phase Locked Loop Interface (PLLIF). The PLL is disabled by default, but can be enabled to provide high frequency source clocks for synchronous or generic clocks. The PLL can use different clock sources as reference clock, please refer to the “PLL Clock Sources” table in the SCIF Module Configuration section for details. The PLL output is divided by a multiplication factor, and the PLL compares the phase of the resulting clock to the reference clock. The PLL will adjust its output frequency until the two compared clocks phases are equal, thus locking the output frequency to a multiple of the reference clock frequency. When the PLL is switched on, or when changing the clock source or multiplication factor for the PLL, the PLL is unlocked and the output frequency is undefined. The PLL clock for the digital logic is automatically masked when the PLL is unlocked, to prevent the connected digital logic from receiving a too high frequency and thus become unstable. The PLL can be configured by writing the PLL Control Register (PLLn). To prevent unexpected writes due to software bugs, write access to the PLLn register is protected by a locking mechanism, for details please refer to the UNLOCK register description. Figure 14-1. PLL with Control Logic and Filters 14.5.3.1 Enabling the PLL Before the PLL is enabled it must be set up correctly. The PLL Oscillator Select field (PLLOSC) selects a source for the reference clock. The PLL Multiply Factor (PLLMUL) and PLL Division Phase Detector Output Divider Source clocks PLLOSC PLLOPT[0] PLLMUL Lock bit Mask PLL clock Input Divider PLLDIV 1/2 PLLOPT[1] 0 1 VCO fvco fPLL Lock Counter fREF 248 32142D–06/2013 ATUC64/128/256L3/4U Factor (PLLDIV) fields must be written with the multiplication and division factors, respectively. The PLLMUL must always be greater than 1, creating the PLL frequency: fvco = (PLLMUL+1)/PLLDIV • fREF, if PLLDIV >0 fvco = 2•(PLLMUL+1) • fREF, if PLLDIV = 0 The PLL Options (PLLOPT) field should be configured to proper values according to the PLL operating frequency. The PLLOPT field can also be configured to divide the output frequency of the PLL by 2 and Wide-Bandwidth mode, which allows faster startup time and out-of-lock time. It is not possible to change any of the PLL configuration bits when the PLL is enabled, Any write to PLLn while the PLL is enabled will be discarded. After setting up the PLL, the PLL is enabled by writing a one to the PLL Enable (PLLEN) bit in the PLLn register. 14.5.3.2 Disabling the PLL The PLL is disabled by writing a zero to the PLL Enable (PLLEN) bit in the PLLn register. After disabling the PLL, the PLL configuration fields becomes writable. 14.5.3.3 PLL Lock The lock signal for each PLL is available as a PLLLOCKn flag in the PCLKSR register. If the lock for some reason is lost, the PLLLOCKLOSTn flag in PCLKSR register will be set. An interrupt can be generated on a 0 to 1 transition of these bits. 14.5.4 Digital Frequency Locked Loop (DFLL) Operation Rev: 2.1.0.1 The DFLL is controlled by the Digital Frequency Locked Loop Interface (DFLLIF). The DFLL is disabled by default, but can be enabled to provide a high-frequency source clock for synchronous and generic clocks. Features: • Internal oscillator with no external components • 20-150MHz frequency in closed loop mode • Can operate standalone as a high-frequency programmable oscillator in open loop mode • Can operate as an accurate frequency multiplier against a known frequency in closed loop mode • Optional spread-spectrum clock generation • Very high-frequency multiplication supported - can generate all frequencies from a 32KHz clock The DFLL can operate in both open loop mode and closed loop mode. In closed loop mode a low frequency clock with high accuracy can be used as reference clock to get high accuracy on the output clock (CLK_DFLL). To prevent unexpected writes due to software bugs, write access to the configuration registers is protected by a locking mechanism. For details please refer to the UNLOCK register description. 249 32142D–06/2013 ATUC64/128/256L3/4U Figure 14-2. DFLLIF Block Diagram 14.5.4.1 Enabling the DFLL The DFLL is enabled by writing a one to the Enable bit (EN) in the DFLLn Configuration Register (DFLLnCONF). No other bits or fields in DFLLnCONF must be changed simultaneously, or before the DFLL is enabled. 14.5.4.2 Internal synchronization Due to multiple clock domains in the DFLLIF, values in the DFLLIF configuration registers need to be synchronized to other clock domains. The status of this synchronization can be read from the Power and Clocks Status Register (PCLKSR). Before writing to a DFLLIF configuration register, the user must check that the DFLLn Synchronization Ready bit (DFLLnRDY) in PCLKSR is set. When this bit is set, the DFLL can be configured, and CLK_DFLL is ready to be used. Any write to a DFLLIF configuration register while DFLLnRDY is cleared will be ignored. Before reading the value in any of the DFLL configuration registers a one must be written to the Synchronization bit (SYNC) in the DFLLn Synchronization Register (DFLLnSYNC). The DFLL configuration registers are ready to be read when PCLKSR.DFLLnRDY is set. 14.5.4.3 Disabling the DFLL The DFLL is disabled by writing a zero to DFLLnCONF.EN. No other bits or fields in DFLLnCONF must be changed simultaneously. After disabling the DFLL, PCLKSR.DFLLnRDY will not be set. It is not required to wait for PCLKSR.DFLLnRDY to be set before re-enabling the DFLL. 14.5.4.4 Open loop operation After enabling the DFLL, open loop mode is selected by writing a zero to the Mode Selection bit (MODE) in DFLLnCONF. When operating in open loop mode the output frequency of the DFLL will be determined by the values written to the Coarse Calibration Value field (COARSE) and the Fine Calibration Value field (FINE) in the DFLLnCONF register. When writing to COARSE and DFLL COARSE FINE 8 9 CLK_DFLL IMUL FMUL 32 CLK_DFLLIF_REF FREQUENCY TUNER DFLLLOCKC DFLLLOCKLOSTC DFLLLOCKF DFLLLOCKLOSTF DFLLLOCKA DFLLLOCKLOSTA CSTEP FSTEP 8+9 CLK_DFLLIF_DITHER 250 32142D–06/2013 ATUC64/128/256L3/4U FINE, be aware that the output frequency must not exceed the maximum frequency of the device after the division in the clock generator. It is possible to change the value of COARSE and FINE, and thereby the output frequency of the DFLL, while the DFLL is enabled and in use. The DFLL clock is ready to be used when PCLKSR.DFLLnRDY is cleared after enabling the DFLL. The frequency range in open loop mode is 20-150MHz, but maximum frequency can be higher, and the minimum frequency can be lower. The best way to start the DFLL at a specific frequency in open loop mode is to first configure it for closed loop mode, see Section 14.5.4.5. When a lock is achieved, read back the COARSE and FINE values and switch to open loop mode using these values. An alternative approach is to use the Frequency Meter (FREQM) to monitor the DFLL frequency and adjust the COARSE and FINE values based on measurement results form the FREQM. Please refer to the FREQM chapter for more information on how to use it. Note that the output frequency of the DFLL will drift when in open loop mode due to temperature and voltage changes. Please refer to the Electrical Characteristics chapter for details. 14.5.4.5 Closed loop operation The DFLL must be correctly configured before closed loop operation can be enabled. After enabling the DFLL, enable and select a reference clock (CLK_DFLLIF_REF). CLK_DFLLIF_REF is a generic clock, please refer to Generic Clocks section for details. Then set the maximum step size allowed in finding the COARSE and FINE values by setting the Coarse Maximum Step field (CSTEP) and Fine Maximum Step field (FSTEP) in the DFLLn Maximum Step Register (DFLLnSTEP). A small step size will ensure low overshoot on the output frequency, but can typically result in longer lock times. A high value might give a big overshoot, but can typically give faster locking. DFLLnSTEP.CSTEP and DFLLnSTEP.FSTEP must be lower than 50% of the maximum value of DFLLnCONF.COARSE and DFLLnCONF.FINE respectively. Then select the multiplication factor in the Integer Multiply Factor field (IMUL) and the Fractional Multiply field (FMUL) in the DFLLn Multiplier Register (DFLLnMUL). Care must be taken when choosing IMUL and FMUL so the output frequency does not exceed the maximum frequency of the device. Start the closed loop mode by writing a one to DFLLnCONF.MODE bit. The frequency of CLK_DFLL (fDFLL) is given by: where fREF is the frequency of CLK_DFLLIF_REF. COARSE and FINE in DFLLnCONF are readonly in closed loop mode, and are controlled by the DFLLIF to meet user specified frequency. The values in COARSE when the closed loop mode is enabled is used by the frequency tuner as a starting point for COARSE. Setting COARSE to a value close to the final value will reduce the time needed to get a lock on COARSE. Frequency locking The locking of the frequency in closed loop mode is divided into three stages. In the COARSE stage the control logic quickly finds the correct value for DFLLnCONF.COARSE and thereby sets the output frequency to a value close to the correct frequency. The DFLLn Locked on Coarse Value bit (DFLLnLOCKC) in PCLKSR will be set when this is done. In the FINE stage the control logic tunes the value in DFLLnCONF.FINE so the output frequency will be very close to the desired frequency. DFLLn Locked on Fine Value bit (DFLLnLOCKF) in PCLKSR will be set when this is done. In the ACCURATE stage the DFLL frequency tuning mechanism uses dithering on the FINE bits to obtain an accurate average output frequency. DFLLn Locked on Accurate Value bit (DFLLnLOCKA) in PCLKSR will be set when this is done. The ACCURATE stage will f DFLL IMUL FMUL 216 + -----------------    f REF = 251 32142D–06/2013 ATUC64/128/256L3/4U only be executed if the Dithering Enable bit (DITHER) in DFLLnCONF has been written to a one. If DITHER is written to a zero DFLLnLOCKA will never occur. If dithering is enabled, the frequency of the dithering is decided by a generic clock (CLK_DFLLIF_DITHER). This clock has to be set up correctly before enabling dithering. Please refer to the Generic Clocks section for details. Figure 14-3. DFLL Closed loop State Diagram When dithering is enabled the accuracy of the average output frequency of the DFLL will be higher. However, the actual frequency will be alternating between two frequencies. If a fixed frequency is required, the dithering should not be enabled. Figure 14-4. DFLL Locking in Closed loop CLK_DFLL is ready to be used when the DFLLn Synchronization Ready bit (DFLLnRDY) in PCLKSR is set after enabling the DFLL. However, the accuracy of the output frequency depends on which locks are set. For lock times, please refer to the Electrical Characteristics chapter. Measure fDFLLn Calculate new COARSE value DFLLnLOCKC 0 Calculate new FINE value DFLLnLOCKF 0 1 1 DFLLnLOCKA Calculate new dithering dutycycle 0 Compensate for drift 1 DITHER 1 Compensate for drift 0 Initial frequency Target frequency DFLLnLOCKC DFLLnLOCKF DFLLnLOCKA 252 32142D–06/2013 ATUC64/128/256L3/4U Drift compensation The frequency tuner will automatically compensate for drift in the fDFLL without losing either of the locks. If the FINE value overflows or underflows, which should normally not happen, but could occur due to large drift in temperature and voltage, all locks will be lost, and the COARSE and FINE values will be recalibrated as described earlier. If any lock is lost the corresponding bit in PCLKSR will be set, DFLLn Lock Lost on Coarse Value bit (DFLLnLOCKLOSTC) for lock lost on COARSE value, DFLLn Lock Lost on Fine Value bit (DFLLnLOCKLOSTF) for lock lost on FINE value and DFLLn Lock Lost on Accurate Value bit (DFLLnLOCKLOSTA) for lock lost on ACCURATE value. The corresponding lock status bit will be cleared when the lock lost bit is set, and vice versa. Reference clock stop detection If CLK_DFLLIF_REF stops or is running at a very slow frequency, the DFLLn Reference Clock Stopped bit (DFLLnRCS) in PCLKSR will be set. Note that the detection of the clock stop will take a long time. The DFLLIF operate as if it was in open loop mode if it detects that the reference clock has stopped. This means that the COARSE and FINE values will be kept constant while PCLKSR.DFLLnRCS is set. Closed loop mode operation will automatically resume if the CLK_DFLLIF_REF is restarted, and compensate for any drift during the time CLK_DFLLIF_REF was stopped. No locks will be lost. Frequency error measurement The ratio between CLK_DFLLIF_REF and CLK_DFLL is measured automatically by the DFLLIF. The difference between this ratio and DFLLnMUL is stored in the Multiplication Ratio Difference field (RATIODIFF) in the DFLLn Ratio Register (DFLLnRATIO). The relative error on CLK_DFLL compared to the target frequency can be calculated as follows: where is the number of reference clock cycles the DFLLIF is using for calculating the ratio. 14.5.4.6 Dealing with delay in the DFLL The time from selecting a new frequency until this frequency is output by the DFLL, can be up to several micro seconds. If the difference between the desired output frequency (CLK_DFLL) and the frequency of CLK_DFLLIF_REF is small this can lead to an instability in the DFLLIF locking mechanism, which can prevent the DFLLIF from achieving locks. To avoid this, a chill cycle where the CLK_DFLL frequency is not measured can be enabled. The chill cycle is enabled by writing a one to the Chill Cycle Enable (CCEN) bit in the DFLLnCONF register. Enabling chill cycles might double the lock time, Another solution to the same problem can be to use less strict lock requirements. This is called Quick Lock (QL), which is enabled by writing a one to the Quick Lock Enable (QLEN) bit in the DFLLnCONF register. The QL might lead to bigger spread in the outputted frequency than chill cycles, but the average output frequency is the same. If the target frequency is below 40MHz, one of these methods should always be used. 14.5.4.7 Spread Spectrum Generator (SSG) When the DFLL is used as the main clock source for the device, the EMI radiated from the device will be synchronous to fDFLL. To provide better Electromagnetic Compatibility (EMC) the error RATIODIFF fREF  2NUMREF f DFLL  = ------------------------------------------------ 2NUMREF 253 32142D–06/2013 ATUC64/128/256L3/4U DFLLIF can provide a clock with the energy spread in the frequency domain. This is done by adding or subtracting values from the FINE value. SSG is enabled by writing a one to the Enable bit (EN) in the DFLLn Spread Spectrum Generator Control Register (DFLLnSSG). A generic clock sets the rate at which the SSG changes the frequency of the DFLL clock to generate a spread spectrum (CLK_DFLLIF_DITHER). This is the same clock used by the dithering mechanism. The frequency of this clock should be higher than fREF to ensure that the DFLLIF can lock. Please refer to the Generic clocks section for details. Optionally, the clock ticks can be qualified by a Pseudo Random Binary Sequence (PRBS) if the PRBS bit in DFLLnSSG is one. This reduces the modulation effect of CLK_DFLLIF_DITHER frequency onto fDFLL. The amplitude of the frequency variation can be selected by setting the SSG Amplitude field (AMPLITUDE) in DFLLnSSG. If AMPLITUDE is zero the SSG will toggle on the LSB of the FINE value. If AMPLITUDE is one the SSG will add the sequence {1,-1, 0} to FINE. The step size of the SSG is selected by writing to the SSG Step Size field (STEPSIZE) in DFLLnSSG. STEPSIZE equal to zero or one will result in a step size equal to one. If the step size is set to n, the output value from the SSG will be incremented/decremented by n on every tick of the source clock. The Spread Spectrum Generator is available in both open and closed loop mode. When spread spectrum is enabled in closed loop mode, and the AMPLITUDE is high, an overflow/underflow in FINE is more likely to occur. Figure 14-5. Spread Spectrum Generator Block Diagram. 14.5.4.8 Wake from sleep modes The DFLLIF may optionally reset its lock bits when waking from a sleep mode which disables the DFLL. This is configured by the Lose Lock After Wake (LLAW) bit in DFLLnCONF register. If DFLLnCONF.LLAW is written to zero the DFLL will be re-enabled and start running with the same configuration as before going to sleep even if the reference clock is not available. The locks will not be lost. When the reference clock has restarted, the FINE tracking will quickly compensate for any frequency drift during sleep. If a one is written to DFLLnCONF.LLAW before going to a sleep mode where the DFLL is turned off, the DFLLIF will lose all its locks when waking up, and needs to regain these through the full lock sequence. 14.5.4.9 Accuracy There are mainly three factors that decide the accuracy of the fDFLL. These can be tuned to obtain maximum accuracy when fine lock is achieved. Pseudorandom Binary Sequence Spread Spectrum Generator FINE 9 To DFLL CLK_DFLLIF_DITHER AMPLITUDE, STEPSIZE PRBS 1 0 254 32142D–06/2013 ATUC64/128/256L3/4U • FINE resolution: The frequency step between two FINE values. This is relatively smaller for high output frequencies. • Resolution of the measurement: If the resolution of the measured fDFLL is low, i.e. the ratio between CLK_DFLL frequency and CLK_DFLLIF_REF is small, then the DFLLIF might lock at a frequency that is lower than the targeted frequency. It is recommended to use a reference clock frequency of 32 KHz or lower to avoid this issue for low target frequencies. • The accuracy of the reference clock. 14.5.4.10 Interrupts A interrupt can be generated on a zero-to-one transaction on DFLLnLOCKC, DFLLnLOCKF, DFLLnLOCKA, DFLLnLOCKLOSTC, DFLLnLOCKLOSTF, DFLLnLOCKLOSTA, DFLLnRDY or DFLLnRCS. 14.5.5 Brown-Out Detection (BOD) Rev: 1.2.0.0 The Brown-Out Detector monitors the VDDCORE supply pin and compares the supply voltage to the brown-out detection level. The BOD is disabled by default, and is enabled by writing to the BOD Control field in the BOD Control Register (BOD.CTRL). This field can also be updated by flash fuses. The BOD is powered by VDDIO and will not be powered during Shutdown sleep mode. To prevent unexpected writes to the BOD register due to software bugs, write access to this register is protected by a locking mechanism. For details please refer to the UNLOCK register description. To prevent further modifications by software, the content of the BOD register can be set as readonly by writing a one to the Store Final Value bit (BOD.SFV). When this bit is one, software can not change the BOD register content. This bit is cleared after flash calibration and after a reset except after a BOD reset. The brown-out detection level is selected by writing to the BOD Level field in BOD (BOD.LEVEL). Please refer to the Electrical Characteristics chapter for parametric details. If the BOD is enabled (BOD.CTRL is one or two) and the supply voltage goes below the detection level, the Brown-Out Detection bit in the Power and Clocks Status Register (PCLKSR.BODDET) is set. This bit is cleared when the supply voltage goes above the detection level. An interrupt request will be generated on a zero-to-one transition on PCLKSR.BODDET if the Brown-Out Detection bit in the Interrupt Mask Register (IMR.BODDET) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.BODDET). If BOD.CTRL is one, a BOD reset will be generated when the supply voltage goes below the detection level. If BOD.CTRL is two, the device will not be reset. Writing a one to the BOD Hysteresis bit in BOD (BOD.HYST) will add a hysteresis on the BOD detection level. Note that the BOD must be disabled before changing BOD.LEVEL, to avoid spurious reset or interrupt. After enabling the BOD, the BOD output will be masked during one half of a RCSYS clock cycle and two main clocks cycles to avoid false results. When the JTAG or aWire is enabled, the BOD reset and interrupt are masked. 255 32142D–06/2013 ATUC64/128/256L3/4U The CTRL, HYST, and LEVEL fields in the BOD Control Register are loaded factory defined calibration values from flash fuses after a reset. If the Flash Calibration Done bit in the BOD Control Register (BOD.FCD) is zero, the flash calibration will be redone after any reset, and the BOD.FCD bit will be set before program execution starts in the CPU. If BOD.FCD is one, the flash calibration is redone after any reset except for a BOD reset. The BOD.FCD bit is cleared after a reset, except for a BOD reset. BOD.FCD is set when these fields have been updated after a flash calibration. It is possible to override the values in the BOD.CTRL, BOD.HYST, and BOD.LEVEL fields after reset by writing to the BOD Control Register. Please refer to the Fuse Settings chapter for more details about BOD fuses and how to program the fuses. Figure 14-6. BOD Block Diagram 14.5.6 Bandgap Rev: 1.2.0.0 The flash memory, the BOD, and the Temperature Sensor need a stable voltage reference to operate. This reference voltage is provided by an internal Bandgap voltage reference. This reference is automatically turned on at start-up and turned off during some sleep modes to save power. The Bandgap reference is powered by the internal regulator supply voltage and will not be powered during Shutdown sleep mode. Please refer to the Power Manager chapter for details. VDDCORE POR18 BOD SCIF POWER MANAGER(PM) INTC Reset Bod Detected Enable BO D Hyst BOD Level Reset In et rrupt 256 32142D–06/2013 ATUC64/128/256L3/4U 14.5.7 System RC Oscillator (RCSYS) Rev: 1.1.1.0 The system RC oscillator has a startup time of three cycles, and is always available except in some sleep modes. Please refer to the Power Manager chapter for details. The system RC oscillator operates at a nominal frequency of 115kHz, and is calibrated using the Calibration Value field (CALIB) in the RC Oscillator Calibration Register (RCCR). After a Power-on Reset (POR), the RCCR.CALIB field is loaded with a factory defined value stored in the Flash fuses. Please refer to the Fuse setting chapter for more details about RCCR fuses and how to program the fuses. If the Flash Calibration Done (FCD) bit in the RCCR is zero at any reset, the flash calibration will be redone and the RCCR.FCD bit will be set before program execution starts in the CPU. If the RCCR.FCD is one, the flash calibration will only be redone after a Power-on Reset. To prevent unexpected writes to RCCR due to software bugs, write access to this register is protected by a locking mechanism. For details please refer to the UNLOCK register description. Although it is not recommended to override default factory settings, it is still possible to override the default values by writing to RCCR.CALIB. 14.5.8 Voltage Regulator (VREG) Rev: 1.1.0.0 The embedded voltage regulator can be used to provide the VDDCORE voltage from the internal regulator supply voltage. It is controlled by the Voltage Regulator Calibration Register (VREGCR). The voltage regulator is enabled by default at start-up but can be disabled by software if an external voltage is provided on the VDDCORE pin. The VREGCR also contains bits to control the POR18 detector and the POR33 detector. 14.5.8.1 Register protection To prevent unexpected writes to VREGCR due to software bugs, write access to this register is protected by a locking mechanism. For details please refer to the UNLOCK register description. To prevent further modifications by software, the content of the VREGCR register can be set as read-only by writing a one to the Store Final Value bit (VREGCR.SFV). Once this bit is set, software can not change the VREGCR content until a Power-on Reset (POR) is applied. 14.5.8.2 Controlling voltage regulator output The voltage regulator is always enabled at start-up, i.e. after a POR or when waking up from Shutdown mode. It can be disabled by software by writing a zero to the Enable bit (VREGCR.EN). This bit is set after a POR. Because of internal synchronization, the voltage regulator is not immediately enabled or disabled. The actual state of the voltage regulator can be read from the ON bit (VREGCR.ON). The voltage regulator output level is controlled by the Select VDD field (SELVDD) in VREGCR. The default value of this field corresponds to a regulator output voltage of 1.8V. Other values of this field are not defined, and it is not recommended to change the value of this field. The Voltage Regulator OK bit (VREGCR.VREGOK) bit indicates when the voltage regulator output has reached the voltage threshold level. 257 32142D–06/2013 ATUC64/128/256L3/4U 14.5.8.3 Factory calibration After a Power-on Reset (POR) the VREGCR.CALIB field is loaded with a factory defined calibration value. This value is chosen so that the normal output voltage of the regulator after a powerup is 1.8V. Although it is not recommended to override default factory settings, it is still possible to override these default values by writing to VREGCR.CALIB. If the Flash Calibration Done bit in VREGCR (VREGCR.FCD) is zero, the flash calibration will be redone after any reset, and the VREGCR.FCD bit will be set before program execution starts in the CPU. If VREGCR.FCD is one, the flash calibration will only be redone after a POR. 14.5.8.4 POR33 control VREGCR includes control bits for the Power-on Reset 3.3V (POR33) detector that monitors the internal regulator supply voltage. The POR33 detector is enabled by default but can be disabled by software to reduce power consumption. The 3.3V Supply Monitor (SM33) can then be used to monitor the regulator power supply. The POR33 detector is disabled by writing a zero to the POR33 Enable bit (VREGCR.POR33EN). Because of internal synchronisation, the POR33 detector is not immediately enabled or disabled. The actual state of the POR33 detector can be read from the POR33 Status bit (VREGCR.POR33STATUS). The 32kHz RC oscillator (RC32K) must be enabled before disabling the POR33 detector. Once the POR33 detector has been disabled, the RC32K oscillator can be disabled again. To avoid spurious resets, it is mandatory to mask the Power-on Reset when enabling or disabling the POR33 detector. The Power-on Reset generated by the POR33 detector can be ignored by writing a one to the POR33 Mask bit (VREGCR.POR33MASK). Because of internal synchronization, the masking is not immediately effective, so software should wait for the VREGCR.POR33MASK to read as a one before assuming the masking is effective. The output of the POR33 detector is zero if the internal regulator supply voltage is below the POR33 power-on threshold level, and one if the internal regulator supply voltage is above the POR33 power-on threshold level. This output (before masking) can be read from the POR33 Value bit (VREGCR.POR33VALUE). 14.5.8.5 POR18 control VREGCR includes control bits for the Power-on Reset 1.8V (POR18) detector that monitors the VDDCORE voltage. The POR18 detector is enabled by default but can be disabled by software to reduce power consumption. The POR18 detector is disabled by writing a zero to the POR18 Enable bit (VREGCR.POR18EN). Because of internal synchronization, the POR18 detector is not immediately enabled or disabled. The actual state of the POR18 detector can be read from the POR18 Status bit (VREGCR.POR18STATUS). Please note that the POR18 detector cannot be disabled while the JTAG or aWire debug interface is used. Writing a zero to VREGCR.POR18EN bit will have no effect. To avoid spurious resets, it is mandatory to mask the Power-on Reset when enabling or disabling the POR18 detector. The Power-on Reset generated by the POR18 detector can be ignored by writing a one to the POR18 Mask bit (VREGCR.POR18MASK). Because of internal 258 32142D–06/2013 ATUC64/128/256L3/4U synchronisation, the masking is not immediately effective, so software should wait for the VREGCR.POR18MASK to read as one before assuming the masking is effective. The output of the POR18 detector is zero if the VDDCORE voltage is below the POR18 poweron threshold level, and one if the VDDCORE voltage is above the POR18 power-on threshold level. The output of the POR18 detector (before masking) can be read from the POR18 Value bit (VREGCR.POR18VALUE). 14.5.9 3.3 V Supply Monitor (SM33) Rev: 1.1.0.0 The 3.3V supply monitor is a specific voltage detector for the internal regulator supply voltage. It will indicate if the internal regulator supply voltage is above the minimum required input voltage threshold. The user can choose to generate either a Power-on Reset (POR) and an interrupt request, or only an interrupt request, when the internal regulator supply voltage drops below this threshold. Please refer to the Electrical Characteristics chapter for parametric details. 14.5.9.1 Register protection To prevent unexpected writes to SM33 register due to software bugs, write access to this register is protected by a locking mechanism. For details please refer to the UNLOCK register description. To prevent further modifications by software, the content of the register can be set as read-only by writing a one to the Store Final Value bit (SM33.SFV). When this bit is one, software can not change the SM33 register content until the device is reset. 14.5.9.2 Operating modes The SM33 is disabled by default and is enabled by writing to the Supply Monitor Control field in the SM33 control register (SM33.CTRL). The current state of the SM33 can be read from the Supply Monitor On Indicator bit in SM33 (SM33.ONSM). Enabling the SM33 will disable the POR33 detector. The SM33 can operate in continuous mode or in sampling mode. In sampling mode, the SM33 is periodically enabled for a short period of time, just enough to make a a measurement, and then disabled for a longer time to reduce power consumption. By default, the SM33 operates in sampling mode during DeepStop and Static mode and in continuous mode for other sleep modes. Sampling mode can also be forced during sleep modes other than DeepStop and Static, and during normal operation, by writing a one to the Force Sampling Mode bit in the SM33 register (SM33.FS). The user can select the sampling frequency by writing to the Sampling Frequency field in SM33 (SM33.SAMPFREQ). The sampling mode uses the 32kHz RC oscillator (RC32K) as clock source. The 32kHz RC oscillator is automatically enabled when the SM33 operates in sampling mode. 14.5.9.3 Interrupt and reset generation If the SM33 is enabled (SM33.CTRL is one or two) and the regulator supply voltage drops below the SM33 threshold, the SM33DET bit in the Power and Clocks Status Register (PCLKSR.SM33DET) is set. This bit is cleared when the supply voltage goes above the threshold. An interrupt request is generated on a zer-to-one transition of PCLKSR.SM33DET if the 259 32142D–06/2013 ATUC64/128/256L3/4U Supply Monitor 3.3V Detection bit in the Interrupt Mask Register (IMR.SM33DET) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.SM33DET). If SM33.CTRL is one, a POR will be generated when the voltage drops below the threshold. If SM33.CTRL is two, the device will not be reset. 14.5.9.4 Factory calibration After a reset the SM33.CALIB field is loaded with a factory defined value. This value is chosen so that the nominal threshold value is 1.75V. The flash calibration is redone after any reset, and the Flash Calibration Done bit in SM33 (SM33.FCD) is set before program execution starts in the CPU. Although it is not recommended to override default factory settings, it is still possible to override the default value by writing to SM33.CALIB 14.5.10 Temperature Sensor Rev: 1.0.0.0 The Temperature Sensor is connected to an ADC channel, please refer to the ADC chapter for details. It is enabled by writing one to the Enable bit (EN) in the Temperature Sensor Configuration Register (TSENS). The Temperature Sensor can not be calibrated. Please refer to the Electrical Characteristics chapter for more details. 14.5.11 120MHz RC Oscillator (RC120M) Rev: 1.1.0.0 The 120MHz RC Oscillator can be used as source for the main clock in the device, as described in the Power Manager chapter. The oscillator can also be used as source for the generic clocks, as described in Generic Clock section. The RC120M must be enabled before it is used as a source clock. To enable the clock, the user must write a one to the Enable bit in the 120MHz RC Oscillator Control Register (RC120MCR.EN), and read back the RC120MCR register until the EN bit reads one. The clock is disabled by writing a zero to RC120MCR.EN. The EN bit must be read back as zero before the RC120M is re-enabled. If not, undefined behavior may occur. The oscillator is automatically disabled in certain sleep modes to reduce power consumption, as described in the Power Manager chapter. 14.5.12 Backup Registers (BR) Rev: 1.0.0.1 Four 32-bit backup registers are available to store values when the device is in Shutdown mode. These registers will keep their content even when the VDDCORE supply and the internal regulator supply voltage supplies are removed. The backup registers can be accessed by reading from and writing to the BR0, BR1, BR2, and BR3 registers. After writing to one of the backup registers the user must wait until the Backup Register Interface Ready bit in tne Power and Clocks Status Register (PCLKSR.BRIFARDY) is set before writing to another backup register. Writes to the backup register while PCLKSR.BRIFARDY is zero will be discarded. An interrupt can be generated on a zero-to-one transition on PCLKSR.BRIFARDY if 260 32142D–06/2013 ATUC64/128/256L3/4U the BRIFARDY bit in the Interrupt Mask Register (IMR.BRIFARDY) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.BRIFARDY). After powering up the device the Backup Register Interface Valid bit in PCLKSR (PCLKSR.BRIFAVALID) is cleared, indicating that the content of the backup registers has not been written and contains the reset value. After writing to one of the backup registers the PCLKSR.BRIFAVALID bit is set. During writes to the backup registers (when BRIFARDY is zero) BRIFAVALID will be zero. If a reset occurs when BRIFARDY is zero, BRIFAVALID will be cleared after the reset, indicating that the content of the backup registers is not valid. If BRIFARDY is one when a reset occurs, BRIFAVALID will be one and the content is the same as before the reset. The user must ensure that BRIFAVALID and BRIFARDY are both set before reading the backup register values. 14.5.13 32kHz RC Oscillator (RC32K) Rev: 1.1.0.0 The RC32K can be used as source for the generic clocks, as described in The Generic Clocks section. The 32kHz RC oscillator (RC32K) is forced on after reset, and output on PA20. The clock is available on the pad until the PPCR.FRC32 bit in the Power Manager has been cleared or a different peripheral function has been chosen on PA20 (PA20 will start with peripheral function F by default). Note that the forcing will only enable the clock output. To be able to use the RC32K normally the oscillator must be enabled as described below. The oscillator is enabled by writing a one to the Enable bit in the 32kHz RC Oscillator Configuration Register (RC32KCR.EN) and disabled by writing a zero to RC32KCR.EN. The oscillator is also automatically enabled when the sampling mode is requested for the SM33. In this case, writing a zero to RC32KCR.EN will not disable the RC32K until the sampling mode is no longer requested. 14.5.14 Generic Clock Prescalers Rev: 1.0.0.0 The generic clocks can be sourced by two special prescalers to increase the generic clock frequency precision. These prescalers are named the High Resolution Prescaler (HRP) and the Fractional Prescaler (FP). 14.5.14.1 High resolution prescaler The HRP is a 24-bit counter that can generate a very accurate clock waveform. The clock obtained has 50% duty cycle. 261 32142D–06/2013 ATUC64/128/256L3/4U Figure 14-7. High Resolution Prescaler Generation The HRP is enabled by writing a one to the High Resolution Prescaler Enable (HRPEN) bit in the High Resolution Prescaler Control Register (HRPCR). The user can select a clock source for the HRP by writing to the Clock Selection (CKSEL) field of the HRPCR register. The user must configure the High Resolution Prescaler Clock (HRPCLK) frequency by writing to the High Resolution Count (HRCOUNT) field of the High Resolution Counter (HRPCR) register. This results in the output frequency: fHRPCLK = fSRC / (2*(HRCOUNT+1)) The CKSEL field can not be changed dynamically but the HRCOUNT field can be changed onthe-fly. 14.5.14.2 Fractional prescaler The FP generates a clock whose average frequency is more precise than the HRP. However, this clock frequency is subject to jitter around the target clock frequency. This jitter influence can be decreased by dividing this clock with the GCLK divider. Moreover the duty cycle of this clock is not precisely 50%. Figure 14-8. Fractional Prescaler Generation The FP is enabled by writing a one to the FPEN bit in the Fractional Prescaler Control Register (FPCR). The user can select a clock source for the FP by writing to the CKSEL field of the FPCR register. Divider CKSEL HRPCLK HRCOUNT Mask HRPEN Divider CKSEL FPCLK FPDIV Mask FPMUL FPEN 262 32142D–06/2013 ATUC64/128/256L3/4U The user must configure the FP frequency by writing to the FPMUL and FPDIV fields of the FPMUL and FPDIV registers. FPMUL and FPDIV must not be equal to zero and FPDIV must be greater or equal to FPMUL. This results in the output frequency: fFPCLK = fSRC * FPMUL/ (2*FPDIV) The CKSEL field can not be changed dynamically but the FPMUL and FPDIV fields can be changed on-the-fly. • Jitter description As described in Figure 14-9, the CLKFP half period lengths are integer multiples of the source clock period but are not always equals. However the difference between the low level half period length and the high level half period length is at the most one source clock period. This induces when FPDIV is not an integer multiple of FPMUL a jitter on the FPCLK. The more the FPCLK frequency is low, the more the jitter incidence is reduced. Figure 14-9. Fractional Prescaler Jitter Examples 14.5.15 Generic Clocks Rev: 1.1.0.0 Timers, communication modules, and other modules connected to external circuitry may require specific clock frequencies to operate correctly. The SCIF defines a number of generic clocks that can provide a wide range of accurate clock frequencies. Each generic clock runs from either clock source listed in the “Generic Clock Sources” table in the SCIF Module Configuration section. The selected source can optionally be divided by any even integer up to 512. Each clock can be independently enabled and disabled, and is also automatically disabled along with peripheral clocks by the Sleep Controller in the Power Manager. SRC clock FPCLK FMUL= 5 FDIV=5 FMUL=3 FDIV=10 FMUL=7 FDIV=9 263 32142D–06/2013 ATUC64/128/256L3/4U Figure 14-10. Generic Clock Generation 14.5.15.1 Enabling a generic clock A generic clock is enabled by writing a one to the Clock Enable bit (CEN) in the Generic Clock Control Register (GCCTRL). Each generic clock can individually select a clock source by writing to the Oscillator Select field (OSCSEL). The source clock can optionally be divided by writing a one to the Divide Enable bit (DIVEN) and the Division Factor field (DIV), resulting in the output frequency: where fSRC is the frequency of the selected source clock, and fGCLK is the output frequency of the generic clock. 14.5.15.2 Disabling a generic clock A generic clock is disabled by writing a zero to CEN or entering a sleep mode that disables the PB clocks. In either case, the generic clock will be switched off on the first falling edge after the disabling event, to ensure that no glitches occur. After CEN has been written to zero, the bit will still read as one until the next falling edge occurs, and the clock is actually switched off. When writing a zero to CEN the other bits in GCCTRL should not be changed until CEN reads as zero, to avoid glitches on the generic clock. The generic clocks will be automatically re-enabled when waking from sleep. 14.5.15.3 Changing clock frequency When changing the generic clock frequency by changing OSCSEL or DIV, the clock should be disabled before being re-enabled with the new clock source or division setting. This prevents glitches during the transition. 14.5.15.4 Generic clock allocation The generic clocks are allocated to different functions as shown in the “Generic Clock Allocation” table in the SCIF Module Configuration section. 14.5.16 Interrupts The SCIF has the following interrupt sources: • AE - Access Error: – A protected SCIF register was accessed without first being correctly unlocked. Divider OSCSEL Generic Clock DIV 0 1 DIVEN Mask CEN Sleep Controller fSRC fGCLK Generic Clock Sources f GCLK f SRC 2  DIV + 1 = ---------------------------- 264 32142D–06/2013 ATUC64/128/256L3/4U • PLLLOCK - PLL Lock – A 0 to 1 transition on the PCLKSR.PLLLOCK bit is detected. • PLLLOCKLOST - PLL Lock Lost – A to 1 transition on the PCLKSR.PLLLOCKLOST bit is detected. • BRIFARDY - Backup Register Interface Ready. – A 0 to 1 transition on the PCLKSR.BRIFARDY bit is detected. • DFLL0RCS - DFLL Reference Clock Stopped: – A 0 to 1 transition on the PCLKSR.DFLLRCS bit is detected. • DFLL0RDY - DFLL Ready: – A 0 to 1 transition on the PCLKSR.DFLLRDY bit is detected. • DFLL0LOCKLOSTA - DFLL lock lost on Accurate value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKLOSTA bit is detected. • DFLL0LOCKLOSTF - DFLL lock lost on Fine value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKLOSTF bit is detected. • DFLL0LOCKLOSTC - DFLL lock lost on Coarse value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKLOSTC bit is detected. • DFLL0LOCKA - DFLL Locked on Accurate value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKA bit is detected. • DFLL0LOCKF - DFLL Locked on Fine value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKF bit is detected. • DFLL0LOCKC - DFLL Locked on Coarse value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKC bit is detected. • BODDET - Brown out detection: – A 0 to 1 transition on the PCLKSR.BODDET bit is detected. • SM33DET - Supply Monitor 3.3V Detector: – A 0 to 1 transition on the PCLKSR.SM33DET bit is detected. • VREGOK - Voltage Regulator OK: – A 0 to 1 transition on the PCLKSR.VREGOK bit is detected. • OSC0RDY - Oscillator Ready: – A 0 to 1 transition on the PCLKSR.OSC0RDY bit is detected. • OSC32RDY - 32KHz Oscillator Ready: – A 0 to 1 transition on the PCLKSR.OSC32RDY bit is detected. The interrupt sources will generate an interrupt request if the corresponding bit in the Interrupt Mask Register is set. The interrupt sources are ORed together to form one interrupt request. The SCIF will generate an interrupt request if at least one of the bits in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in the Interrupt Status Register (ISR) is cleared by writing a one to the corresponding bit in the Interrupt Clear Register (ICR). Because all the interrupt sources are ORed together, the interrupt request from the SCIF will remain active until all the bits in ISR are cleared. 265 32142D–06/2013 ATUC64/128/256L3/4U 14.6 User Interface Table 14-2. SCIF Register Memory Map Offset Register Register Name Access Reset 0x0000 Interrupt Enable Register IER Write-only 0x00000000 0x0004 Interrupt Disable Register IDR Write-only 0x00000000 0x0008 Interrupt Mask Register IMR Read-only 0x00000000 0x000C Interrupt Status Register ISR Read-only 0x00000000 0x0010 Interrupt Clear Register ICR Write-only 0x00000000 0x0014 Power and Clocks Status Register PCLKSR Read-only 0x00000000 0x0018 Unlock Register UNLOCK Write-only 0x00000000 0x001C Oscillator 0 Control Register OSCCTRL0 Read/Write 0x00000000 0x0020 Oscillator 32 Control Register OSCCTRL32 Read/Write 0x00000004 0x0024 DFLL Config Register DFLL0CONF Read/Write 0x00000000 0x0028 DFLL Multiplier Register DFLL0MUL Write-only 0x00000000 0x002C DFLL Step Register DFLL0STEP Write-only 0x00000000 0x0030 DFLL Spread Spectrum Generator Control Register DFLL0SSG Write-only 0x00000000 0x0034 DFLL Ratio Register DFLL0RATIO Read-only 0x00000000 0x0038 DFLL Synchronization Register DFLL0SYNC Write-only 0x00000000 0x003C BOD Level Register BOD Read/Write -(2) 0x0044 Voltage Regulator Calibration Register VREGCR Read/Write -(2) 0x0048 System RC Oscillator Calibration Register RCCR Read/Write -(2) 0x004C Supply Monitor 33 Calibration Register SM33 Read/Write -(2) 0x0050 Temperature Sensor Calibration Register TSENS Read/Write 0x00000000 0x0058 120MHz RC Oscillator Control Register RC120MCR Read/Write 0x00000000 0x005C-0x0068 Backup Registers BR Read/Write 0x00000000 0x006C 32kHz RC Oscillator Control Register RC32KCR Read/Write 0x00000000 0x0070 Generic Clock Control0 GCCTRL0 Read/Write 0x00000000 0x0074 Generic Clock Control1 GCCTRL1 Read/Write 0x00000000 0x0078 Generic Clock Control2 GCCTRL2 Read/Write 0x00000000 0x007C Generic Clock Control3 GCCTRL3 Read/Write 0x00000000 0x0080 Generic Clock Control4 GCCTRL4 Read/Write 0x00000000 0x0084 Generic Clock Control5 GCCTRL5 Read/Write 0x00000000 0x0088 Generic Clock Control6 GCCTRL6 Read/Write 0x00000000 0x008C Generic Clock Control7 GCCTRL7 Read/Write 0x00000000 0x0090 Generic Clock Control8 GCCTRL8 Read/Write 0x00000000 0x0094 Generic Clock Control9 GCCTRL9 Read/Write 0x00000000 266 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. The reset value is device specific. Please refer to the Module Configuration section at the end of this chapter. 2. The reset value of this register depends on factory calibration. 0x0098 PLL0 Control Register PLL0 Read/Write 0x00000000 0x009C High Resolution Prescaler Control Register HRPCR Read/Write 0x00000000 0x00A0 Fractional Prescaler Control Register FPCR Read/Write 0x00000000 0x00A4 Fractional Prescaler Multiplier Register FPMUL Read/Write 0x00000000 0x00A8 Fractional Prescaler DIVIDER Register FPDIV Read/Write 0x00000000 0x03BC Commonly used Modules Version Register CMVERSION Read-only -(1) 0x03C0 Generic Clock Prescaler Version Register GCLKPRESCVERSION Read-only -(1) 0x03C4 PLL Version Register PLLVERSION Read-only -(1) 0x03C8 Oscillator0 Version Register OSC0VERSION Read-only -(1) 0x03CC 32 KHz Oscillator Version Register OSC32VERSION Read-only -(1) 0x03D0 DFLL Version Register DFLLIFVERSION Read-only -(1) 0x03D4 BOD Version Register BODIFAVERSION Read-only -(1) 0x03D8 Voltage Regulator Version Register VREGIFBVERSION Read-only -(1) 0x03DC System RC Oscillator Version Register RCOSCIFAVERSION Read-only -(1) 0x03E0 3.3V Supply Monitor Version Register SM33IFAVERSION Read-only -(1) 0x03E4 Temperature Sensor Version Register TSENSIFAVERSION Read-only -(1) 0x03EC 120MHz RC Oscillator Version Register RC120MIFAVERSION Read-only -(1) 0x03F0 Backup Register Interface Version Register BRIFAVERSION Read-only -(1) 0x03F4 32kHz RC Oscillator Version Register RC32KIFAVERSION Read-only -(1) 0x03F8 Generic Clock Version Register GCLKVERSION Read-only -(1) 0x03FC SCIF Version Register VERSION Read-only -(1) Table 14-2. SCIF Register Memory Map Offset Register Register Name Access Reset 267 32142D–06/2013 ATUC64/128/256L3/4U 14.6.1 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x0000 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 268 32142D–06/2013 ATUC64/128/256L3/4U 14.6.2 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x0004 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 269 32142D–06/2013 ATUC64/128/256L3/4U 14.6.3 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x0008 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 270 32142D–06/2013 ATUC64/128/256L3/4U 14.6.4 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x000C Reset Value: 0x00000000 0: The corresponding interrupt is cleared. 1: The corresponding interrupt is pending. A bit in this register is cleared when the corresponding bit in ICR is written to one. A bit in this register is set when the corresponding interrupt occurs. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 271 32142D–06/2013 ATUC64/128/256L3/4U 14.6.5 Interrupt Clear Register Name: ICR Access Type: Write-only Offset: 0x0010 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in ISR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 272 32142D–06/2013 ATUC64/128/256L3/4U 14.6.6 Power and Clocks Status Register Name: PCLKSR Access Type: Read-only Offset: 0x0014 Reset Value: 0x00000000 • BRIFAVALID: Backup Register Interface Valid 0: The values in the backup registers are not valid. 1: The values in the backup registers are valid. • PLLL0LOCKLOST: PLL0 lock lost value 0: PLL0 has not lost it’s lock or has never been enabled. 1: PLL0 has lost it’s lock, either by disabling the PLL0 or due to faulty operation. • PLL0LOCK: PLL0 Locked on Accurate value 0: PLL0 is unlocked on accurate value. 1: PLL0 is locked on accurate value, and is ready to be selected as clock source with an accurate output clock. • BRIFARDY: Backup Register Interface Ready 0: The backup register interface is busy updating the backup registers. Writes to BRn will be discarded. 1: The backup register interface is ready to accept new writes to the backup registers. • DFLL0RCS: DFLL0 Reference Clock Stopped 0: The DFLL reference clock is running, or has never been enabled. 1: The DFLL reference clock has stopped or is too slow. • DFLL0RDY: DFLL0 Synchronization Ready 0: Read or write to DFLL registers is invalid 1: Read or write to DFLL registers is valid • DFLL0LOCKLOSTA: DFLL0 Lock Lost on Accurate Value 0: DFLL has not lost its Accurate lock or has never been enabled. 1: DFLL has lost its Accurate lock, either by disabling the DFLL or due to faulty operation. • DFLL0LOCKLOSTF: DFLL0 Lock Lost on Fine Value 0: DFLL has not lost its Fine lock or has never been enabled. 1: DFLL has lost its Fine lock, either by disabling the DFLL or due to faulty operation. 31 30 29 28 27 26 25 24 - BRIFAVALID - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 273 32142D–06/2013 ATUC64/128/256L3/4U • DFLL0LOCKLOSTC: DFLL0 Lock Lost on Coarse Value 0: DFLL has not lost its Coarse lock or has never been enabled. 1: DFLL has lost its Coarse lock, either by disabling the DFLL or due to faulty operation. • DFLL0LOCKA: DFLL0 Locked on Accurate Value 0: DFLL is unlocked on Accurate value. 1: DFLL is locked on Accurate value, and is ready to be selected as clock source with an accurate output clock. • DFLL0LOCKF: DFLL0 Locked on Fine Value 0: DFLL is unlocked on Fine value. 1: DFLL is locked on Fine value, and is ready to be selected as clock source with a high accuracy on the output clock. • DFLL0LOCKC: DFLL0 Locked on Coarse Value 0: DFLL is unlocked on Coarse value. 1: DFLL is locked on Coarse value, and is ready to be selected as clock source with medium accuracy on the output clock. • BODDET: Brown-Out Detection 0: No BOD Event. 1: BOD has detected that the supply voltage is below the BOD reference value. • SM33DET: Supply Monitor 3.3V Detector 0: SM33 not enabled or the supply voltage is above the SM33 threshold. 1: SM33 enabled and the supply voltage is below the SM33 threshold. • VREGOK: Voltage Regulator OK 0: Voltage regulator not enabled or not ready. 1: Voltage regulator has reached its output threshold value after being enabled. • OSC0RDY: OSC0 Ready 0: Oscillator not enabled or not ready. 1: Oscillator is stable and ready to be used as clock source. • OSC32RDY: 32 KHz oscillator Ready 0: OSC32K not enabled or not ready. 1: OSC32K is stable and ready to be used as clock source. 274 32142D–06/2013 ATUC64/128/256L3/4U 14.6.7 Unlock Register Name: UNLOCK Access Type: Write-only Offset: 0x0018 Reset Value: 0x00000000 To unlock a write protected register, first write to the UNLOCK register with the address of the register to unlock in the ADDR field and 0xAA in the KEY field. Then, in the next PB access write to the register specified in the ADDR field. The LOCK is by default off. To turn on the LOCK, first write 0xAA to the KEY field and UNLOCK address offset to the ADDR field in the UNLOCK register, followed by writing 0x5A5A5A5A to the UNLOCK register. To turn off the LOCK, first write 0xAA to the KEY field and UNLOCK address offset to the ADDR field in the UNLOCK register, followed by writing 0xA5AA5A55 to the UNLOCK register. • KEY: Unlock Key Write this bit field to 0xAA to enable unlock. • ADDR: Unlock Address Write the address offset of the register to unlock to this field. 31 30 29 28 27 26 25 24 KEY 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - ADDR[9:8] 76543210 ADDR[7:0] 275 32142D–06/2013 ATUC64/128/256L3/4U 14.6.8 Oscillator Control Register Name: OSCCTRLn Access Type: Read/Write Reset Value: 0x00000000 • OSCEN: Oscillator Enable 0: The oscillator is disabled. 1: The oscillator is enabled. • STARTUP: Oscillator Start-up Time Select start-up time for the oscillator. Please refer to the “Oscillator Startup Time” table in the SCIF Module Configuration section for details. • AGC: Automatic Gain Control For test purposes. • GAIN: Gain Selects the gain for the oscillator. Please refer to the “Oscillator Gain Settings” table in the SCIF Module Configuration section for details. • MODE: Oscillator Mode 0: External clock connected on XIN. XOUT can be used as general-purpose I/O (no crystal). 1: Crystal is connected to XIN/XOUT. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - OSCEN 15 14 13 12 11 10 9 8 - - - - STARTUP[3:0] 76543210 - - - - AGC GAIN[1:0] MODE 276 32142D–06/2013 ATUC64/128/256L3/4U 14.6.9 32KHz Oscillator Control Register Name: OSCCTRL32 Access Type: Read/Write Reset Value: 0x00000004 Note: This register is only reset by Power-On Reset • RESERVED This bit must always be written to zero. • STARTUP: Oscillator Start-up Time Select start-up time for 32 KHz oscillator 31 30 29 28 27 26 25 24 RESERVED ------- 23 22 21 20 19 18 17 16 - - - - - STARTUP[2:0] 15 14 13 12 11 10 9 8 - - - - - MODE[2:0] 76543210 - - - - EN1K EN32K PINSEL OSC32EN Table 14-3. Start-up Time for 32 KHz Oscillator STARTUP Number of RCSYS Clock Cycle Approximative Equivalent Time (RCOSC = 115 kHz) 00 0 1 128 1.1 ms 2 8192 72.3 ms 3 16384 143 ms 4 65536 570 ms 5 131072 1.1 s 6 262144 2.3 s 7 524288 4.6 s 277 32142D–06/2013 ATUC64/128/256L3/4U • MODE: Oscillator Mode • EN1K: 1 KHz output Enable 0: The 1 KHz output is disabled. 1: The 1 KHz output is enabled. • EN32K: 32 KHz output Enable 0: The 32 KHz output is disabled. 1: The 32 KHz output is enabled. • PINSEL: Pins Select 0: Default pins used. 1: Alternate pins: XIN32_2 pin is used instead of XIN32 pin, XOUT32_2 pin is used instead of XOUT32. • OSC32EN: 32 KHz Oscillator Enable 0: The 32 KHz Oscillator is disabled 1: The 32 KHz Oscillator is enabled Table 14-4. Operation Mode for 32 KHz Oscillator MODE Description 0 External clock connected to XIN32, XOUT32 can be used as general-purpose I/O (no crystal) 1 Crystal mode. Crystal is connected to XIN32/XOUT32. 2 Reserved 3 Reserved 4 Crystal and high current mode. Crystal is connected to XIN32/XOUT32. 5 Reserved 6 Reserved 7 Reserved 278 32142D–06/2013 ATUC64/128/256L3/4U 14.6.10 DFLLn Configuration Register Name: DFLLnCONF Access Type: Read/Write Reset Value: 0x00000000 • COARSE: Coarse Calibration Value Set the value of the coarse calibration register. If in closed loop mode, this field is Read-only. • FINE: FINE Calibration Value Set the value of the fine calibration register. If in closed loop mode, this field is Read-only. • QLEN: Quick Lock Enable 0: Quick Lock is disabled. 1: Quick Lock is enabled. • CCEN: Chill Cycle Enable 0: Chill Cycle is disabled. 1: Chill Cycle is enabled. • LLAW: Lose Lock After Wake 0: Locks will not be lost after waking up from sleep modes. 1: Locks will be lost after waking up from sleep modes where the DFLL clock has been stopped. • DITHER: Enable Dithering 0: The fine LSB input to the VCO is constant. 1: The fine LSB input to the VCO is dithered to achieve sub-LSB approximation to the correct multiplication ratio. • MODE: Mode Selection 0: The DFLL is in open loop operation. 1: The DFLL is in closed loop operation. • EN: Enable 0: The DFLL is disabled. 1: The DFLL is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 COARSE[7:0] 23 22 21 20 19 18 17 16 - - - - - - - FINE[8] 15 14 13 12 11 10 9 8 FINE[7:0] 76543210 - QLEN CCEN - LLAW DITHER MODE EN 279 32142D–06/2013 ATUC64/128/256L3/4U 14.6.11 DFLLn Multiplier Register Name: DFLLnMUL Access Type: Read/Write Reset Value: 0x00000000 • IMUL: Integer Multiply Factor This field, together with FMUL, determines the ratio between fDFLL and fREFthe DFLL. IMUL is the integer part, while the FMUL is the fractional part. In open loop mode, writing to this register has no effect. • FMUL: Fractional Multiply Factor This field, together with IMUL, determines the ratio between fDFLL and fREFthe DFLL. IMUL is the integer part, while the FMUL is the fractional part. In open loop mode, writing to this register has no effect. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 IMUL[15:8] 23 22 21 20 19 18 17 16 IMUL[7:0] 15 14 13 12 11 10 9 8 FMUL[15:8] 76543210 FMUL[7:0] 280 32142D–06/2013 ATUC64/128/256L3/4U 14.6.12 DFLLn Maximum Step Register Name: DFLLnSTEP Access Type: Read/Write Reset Value: 0x00000000 • FSTEP: Fine Maximum Step This indicates the maximum step size during fine adjustment in closed-loop mode. When adjusting to a new frequency, the expected overshoot of that frequency depends on this step size. • CSTEP: Coarse Maximum Step This indicates the maximum step size during coarse adjustment in closed-loop mode. When adjusting to a new frequency, the expected overshoot of that frequency depends on this step size. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 - - - - - - - FSTEP[8] 23 22 21 20 19 18 17 16 FSTEP[7:0] 15 14 13 12 11 10 9 8 -------- 76543210 CSTEP[7:0] 281 32142D–06/2013 ATUC64/128/256L3/4U 14.6.13 DFLLn Spread Spectrum Generator Control Register Name: DFLLnSSG Access Type: Read/Write Reset Value: 0x00000000 • STEPSIZE: SSG Step Size Sets the step size of the spread spectrum. • AMPLITUDE: SSG Amplitude Sets the amplitude of the spread spectrum. • PRBS: Pseudo Random Bit Sequence 0: Each spread spectrum frequency is applied at constant intervals 1: Each spread spectrum frequency is applied at pseudo-random intervals • EN: Enable 0: SSG is disabled. 1: SSG is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 - ------- 23 22 21 20 19 18 17 16 - - - STEPSIZE[4:0] 15 14 13 12 11 10 9 8 - - - AMPLITUDE[4:0] 76543210 - - - - - - PRBS EN 282 32142D–06/2013 ATUC64/128/256L3/4U 14.6.14 DFLLn Ratio Register Name: DFLLnRATIO Access Type: Read-only Reset Value: 0x00000000 • RATIODIFF: Multiplication Ratio Difference In closed-loop mode, this field indicates the error in the ratio between the VCO frequency and the target frequency. • NUMREF: Numerical Reference The number of reference clock cycles used to measure the VCO frequency equals 2^NUMREF. 31 30 29 28 27 26 25 24 RATIODIFF[15:8] 23 22 21 20 19 18 17 16 RATIODIFF[7:0] 15 14 13 12 11 10 9 8 - ------- 76543210 - - - NUMREF[4:0] 283 32142D–06/2013 ATUC64/128/256L3/4U 14.6.15 DFLLn Synchronization Register Name: DFLLnSYNC Access Type: Write-only Reset Value: 0x00000000 • SYNC: Synchronization To be able to read the current value of DFLLnCONF or DFLLnRATIO in closed-loop mode, this bit should be written to one. The updated value is available in DFLLnCONF and DFLLnRATIO when PCLKSR.DFLLnRDY is set. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - SYNC 284 32142D–06/2013 ATUC64/128/256L3/4U 14.6.16 BOD Control Register Name: BOD Access Type: Read/Write Reset Value: - • SFV: Store Final Value 0: The register is read/write 1: The register is read-only, to protect against further accidental writes. This bit is cleared after any reset except for a BOD reset, and during flash calibration. • FCD: Fuse Calibration Done 0: The flash calibration will be redone after any reset. 1: The flash calibration will be redone after any reset except for a BOD reset. This bit is cleared after any reset, except for a BOD reset. This bit is set when the CTRL, HYST and LEVEL fields have been updated by the flash fuses after a reset. • CTRL: BOD Control • HYST: BOD Hysteresis 0: No hysteresis. 1: Hysteresis on. • LEVEL: BOD Level This field sets the triggering threshold of the BOD. See Electrical Characteristics for actual voltage levels. Note that any change to the LEVEL field of the BOD register should be done with the BOD deactivated to avoid spurious reset or interrupt. 31 30 29 28 27 26 25 24 SFV - - - - - - - 23 22 21 20 19 18 17 16 - - - - - - - FCD 15 14 13 12 11 10 9 8 - - - - - - CTRL 76543210 - HYST LEVEL Table 14-5. Operation Mode for BOD CTRL Description 0 BOD is disabled. 1 BOD is enabled and can reset the device. An interrupt request will be generated, if enabled in the IMR register. 2 BOD is enabled but cannot reset the device. An interrupt request will be generated, if enabled in the IMR register. 3 Reserved. 285 32142D–06/2013 ATUC64/128/256L3/4U Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 286 32142D–06/2013 ATUC64/128/256L3/4U 14.6.17 Voltage Regulator Calibration Register Name: VREGCR Access Type: Read/Write Reset Value: - • SFV: Store Final Value 0: The register is read/write. 1: The register is read-only, to protect against further accidental writes. This bit is cleared by a Power-on Reset. • INTPD: Internal Pull-down This bit is used for test purposes only. 0: The voltage regulator output is not pulled to ground. 1: The voltage regulator output has a pull-down to ground. • POR18VALUE: Power-on Reset 1.8V Output Value 0: VDDCORE voltage is below the POR18 power-on threshold level. 1: VDDCORE voltage is above the POR18 power-on threshold level. This bit is read-only. Writing to this bit has no effect. • POR33VALUE: Power-on Reset 3.3V Output Value 0: Internal regulator supply voltage is below the POR33 power-on threshold level. 1: Internal regulator supply voltage is above the POR33 power-on threshold level. This bit is read-only. Writing to this bit has no effect. • POR18MASK: Power-on Reset 1.8V Output Mask 0: Power-on Reset is not masked. 1: Power-on Reset is masked. • POR18STATUS: Power-on Reset 1.8V Status 0: Power-on Reset is disabled. 1: Power-on Reset is enabled. This bit is read-only. Writing to this bit has no effect. • POR18EN: Power-on Reset 1.8V Enable Writing a zero to this bit disables the POR18 detector. Writing a one to this bit enables the POR18 detector. • POR33MASK: Power-on Reset 3.3V Output Mask 0: Power-on Reset 3.3V is not masked. 31 30 29 28 27 26 25 24 SFV INTPD - - - DBG- POR18VALUE POR33VALUE 23 22 21 20 19 18 17 16 POR18MASK POR18STAT US POR18EN POR33MASK POR33STAT US POR33EN DEEPDIS FCD 15 14 13 12 11 10 9 8 - - - - CALIB 76543210 ON VREGOK EN - - SELVDD 287 32142D–06/2013 ATUC64/128/256L3/4U 1: Power-on Reset 3.3V is masked. • POR33STATUS: Power-on Reset 3.3V Status 0: Power-on Reset is disabled. 1: Power-on Reset is enabled. This bit is read-only. Writing to this bit has no effect. • POR33EN: Power-on Reset 3.3V Enable 0: Writing a zero to this bit disables the POR33 detector. 1: Writing a one to this bit enables the POR33 detector. • DEEPDIS: Disable Regulator Deep Mode 0: Regulator will enter deep mode in low-power sleep modes for lower power consumption. 1: Regulator will stay in full-power mode in all sleep modes for shorter start-up time. • FCD: Flash Calibration Done 0: The flash calibration will be redone after any reset. 1: The flash calibration will only be redone after a Power-on Reset. This bit is cleared after a Power-on Reset. This bit is set when the CALIB field has been updated by flash calibration after a reset. • CALIB: Calibration Value Calibration value for Voltage Regulator. This is calibrated during production and should not be changed. • ON: Voltage Regulator On Status 0: The voltage regulator is currently disabled. 1: The voltage regulator is currently enabled. This bit is read-only. Writing to this bit has no effect. • VREGOK: Voltage Regulator OK Status 0: The voltage regulator is disabled or has not yet reached a stable output voltage. 1: The voltage regulator has reached the output voltage threshold level after being enabled. This bit is read-only. Writing to this bit has no effect. • EN: Enable 0: The voltage regulator is disabled. 1: The voltage regulator is enabled. Note: This bit is set after a Power-on Reset (POR). • SELVDD: Select VDD Output voltage of the Voltage Regulator. The default value of this bit corresponds to an output voltage of 1.8V. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 288 32142D–06/2013 ATUC64/128/256L3/4U 14.6.18 System RC Oscillator Calibration Register Name: RCCR Access Type: Read/Write Reset Value: - • FCD: Flash Calibration Done 0: The flash calibration will be redone after any reset. 1: The flash calibration will only be redone after a Power-on Reset. This bit is cleared after a POR. This bit is set when the CALIB field has been updated by the flash fuses after a reset. • CALIB: Calibration Value Calibration Value for the System RC oscillator (RCSYS). Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - FCD 15 14 13 12 11 10 9 8 - - - - - - CALIB[9:8] 76543210 CALIB[7:0] 289 32142D–06/2013 ATUC64/128/256L3/4U 14.6.19 Supply Monitor 33 Calibration Register Name: SM33 Access Type: Read/Write Reset Value: - • SAMPFREQ: Sampling Frequency Selects the sampling mode frequency of the 3.3V supply monitor. In sampling mode, the SM33 performs a measurement every 2(SAMPFREQ+5) cycles of the internal 32kHz RC oscillator. • ONSM: Supply Monitor On Indicator 0: The supply monitor is disabled. 1: The supply monitor is enabled. This bit is read-only. Writing to this bit has no effect. • SFV: Store Final Value 0: The register is read/write 1: The register is read-only, to protect against further accidental writes. This bit is cleared after a reset. • FCD: Flash Calibration Done This bit is cleared after a reset. This bit is set when CALIB field has been updated after a reset. • CALIB: Calibration Value Calibration Value for the SM33. • FS: Force Sampling Mode 0: Sampling mode is enabled in DeepStop and Static mode only. 1: Sampling mode is always enabled. • CTRL: Supply Monitor Control 31 30 29 28 27 26 25 24 - - - - SAMPFREQ 23 22 21 20 19 18 17 16 - - - - - ONSM SFV FCD 15 14 13 12 11 10 9 8 - - - - CALIB 76543210 FS - - - CTRL 290 32142D–06/2013 ATUC64/128/256L3/4U Selects the operating mode for the SM33. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. Table 14-6. Operation Mode for SM33 CTRL Description 0 SM33 is disabled. 1 SM33 is enabled and can reset the device. An interrupt request will be generated if the corresponding interrupt is enabled in the IMR register. 2 SM33 is enabled and cannot reset the device. An interrupt request will be generated if the corresponding interrupt is enabled in the IMR register. 3 SM33 is disabled 4-7 Reserved 291 32142D–06/2013 ATUC64/128/256L3/4U 14.6.20 Temperature Sensor Configuration Register Name: TSENS Access Type: Read/Write Reset Value: 0x00000000 • EN: Temperature Sensor Enable 0: The Temperature Sensor is disabled. 1: The Temperature Sensor is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - EN 292 32142D–06/2013 ATUC64/128/256L3/4U 14.6.21 120MHz RC Oscillator Configuration Register Name: RC120MCR Access Type: Read/Write Reset Value: 0x00000000 • EN: RC120M Enable 0: The 120 MHz RC oscillator is disabled. 1: The 120 MHz RC oscillator is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - EN 293 32142D–06/2013 ATUC64/128/256L3/4U 14.6.22 Backup Register n Name: BRn Access Type: Read/Write Reset Value: 0x00000000 This is a set of general-purpose read/write registers. Data stored in these registers is retained when the device is in Shutdown. Before writing to these registers the user must ensure that PCLKSR.BRIFARDY is not set. Note that this registers are protected by a lock. To write to these registers the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 294 32142D–06/2013 ATUC64/128/256L3/4U 14.6.23 32kHz RC Oscillator Configuration Register Name: RC32KCR Access Type: Read/Write Reset Value: 0x00000000 • EN: RC32K Enable 0: The 32 kHz RC oscillator is disabled. 1: The 32 kHz RC oscillator is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - EN 295 32142D–06/2013 ATUC64/128/256L3/4U 14.6.24 Generic Clock Control Name: GCCTRL Access Type: Read/Write Reset Value: 0x00000000 There is one GCCTRL register per generic clock in the design. • DIV: Division Factor The number of DIV bits for each generic clock is as shown in the “Generic Clock number of DIV bits” table in the SCIF Module Configuration section. • OSCSEL: Oscillator Select Selects the source clock for the generic clock. Please refer to the “Generic Clock Sources” table in the SCIF Module Configuration section. • DIVEN: Divide Enable 0: The generic clock equals the undivided source clock. 1: The generic clock equals the source clock divided by 2*(DIV+1). • CEN: Clock Enable 0: The generic clock is disabled. 1: The generic clock is enabled. 31 30 29 28 27 26 25 24 DIV[15:8] 23 22 21 20 19 18 17 16 DIV[7:0] 15 14 13 12 11 10 9 8 - - - OSCSEL[4:0] 76543210 - - - - - - DIVEN CEN 296 32142D–06/2013 ATUC64/128/256L3/4U 14.6.25 PLL Control Register Name: PLLn Access Type: Read/Write Reset Value: 0x00000000 • PLLCOUNT: PLL Count Specifies the number of RCSYS clock cycles before ISR.PLLLOCKn will be set after PLLn has been written, or after PLLn has been automatically re-enabled after exiting a sleep mode. • PLLMUL: PLL Multiply Factor • PLLDIV: PLL Division Factor These fields determine the ratio of the PLL output frequency to the source oscillator frequency: fvco = (PLLMUL+1)/PLLDIV • fREF if PLLDIV >0 fvco = 2•(PLLMUL+1) • fREF if PLLDIV = 0 Note that the PLLMUL field should always be greater than 1 or the behavior of the PLL will be undefined. • PLLOPT: PLL Option PLLOPT[0]: Selects the VCO frequency range (fvco). 0: 80MHz1 1 1 0 0 BaudRate SelectedClock   8 2  – OVER CD = ----------------------------------------------- 438 32142D–06/2013 ATUC64/128/256L3/4U The baud rate is calculated with the following formula (OVER=0): The baud rate error is calculated with the following formula. It is not recommended to work with an error higher than 5%. 20.6.1.3 Fractional Baud Rate in Asynchronous Mode The baud rate generator has a limitation: the source frequency is always a multiple of the baud rate. An approach to this problem is to integrate a high resolution fractional N clock generator, outputting fractional multiples of the reference source clock. This fractional part is selected with the Fractional Part field (BRGR.FP), and is activated by giving it a non-zero value. The resolution is one eighth of CD. The resulting baud rate is calculated using the following formula: The modified architecture is presented below: Table 20-3. Baud Rate Example (OVER=0) Source Clock (Hz) Expected Baud Rate (bit/s) Calculation Result CD Actual Baud Rate (bit/s) Error 3 686 400 38 400 6.00 6 38 400.00 0.00% 4 915 200 38 400 8.00 8 38 400.00 0.00% 5 000 000 38 400 8.14 8 39 062.50 1.70% 7 372 800 38 400 12.00 12 38 400.00 0.00% 8 000 000 38 400 13.02 13 38 461.54 0.16% 12 000 000 38 400 19.53 20 37 500.00 2.40% 12 288 000 38 400 20.00 20 38 400.00 0.00% 14 318 180 38 400 23.30 23 38 908.10 1.31% 14 745 600 38 400 24.00 24 38 400.00 0.00% 18 432 000 38 400 30.00 30 38 400.00 0.00% 24 000 000 38 400 39.06 39 38 461.54 0.16% 24 576 000 38 400 40.00 40 38 400.00 0.00% 25 000 000 38 400 40.69 40 38 109.76 0.76% 32 000 000 38 400 52.08 52 38 461.54 0.16% 32 768 000 38 400 53.33 53 38 641.51 0.63% 33 000 000 38 400 53.71 54 38 194.44 0.54% 40 000 000 38 400 65.10 65 38 461.54 0.16% 50 000 000 38 400 81.38 81 38 580.25 0.47% 60 000 000 38 400 97.66 98 38 265.31 0.35% BaudRate CLKUSART =      CD  16 Error 1 ExpectedBaudRate ActualBaudRate --------------------------------------------------     = – BaudRate SelectedClock 8 2  – OVER CD FP 8 + -------         = -------------------------------------------------------------------- 439 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-3. Fractional Baud Rate Generator 20.6.1.4 Baud Rate in Synchronous and SPI Mode If the USART is configured to operate in synchronous mode, the selected clock is divided by the BRGR.CD field. This does not apply when CLK is selected. When CLK is selected the external frequency must be at least 4.5 times lower than the system clock, and when either CLK or CLK_USART/DIV are selected, CD must be even to ensure a 50/50 duty cycle. If CLK_USART is selected, the generator ensures this regardless of value. 20.6.2 Receiver and Transmitter Control After a reset, the transceiver is disabled. The receiver/transmitter is enabled by writing a one to either the Receiver Enable, or Transmitter Enable bit in the Control Register (CR.RXEN, or CR.TXEN). They may be enabled together and can be configured both before and after they have been enabled. The user can reset the USART receiver/transmitter at any time by writing a one to either the Reset Receiver (CR.RSTRX), or Reset Transmitter (CR.RSTTX) bit. This software reset clears status bits and resets internal state machines, immediately halting any communication. The user interface configuration registers will retain their values. The user can disable the receiver/transmitter by writing a one to either the Receiver Disable, or Transmitter Disable bit (CR.RXDIS, or CR.TXDIS). If the receiver is disabled during a character reception, the USART will wait for the current character to be received before disabling. If the transmitter is disabled during transmission, the USART will wait until both the current character and the character stored in the Transmitter Holding Register (THR) are transmitted before disabling. If a timeguard has been implemented it will remain functional during the transaction. USCLKS CD Modulus Control FP FP CD glitch-free logic 16-bit Counter OVER FIDI SYNC Sampling Divider CLK_USART CLK_USART/DIV Reserved CLK CLK BaudRate Clock Sampling Clock SYNC USCLKS = 3 >1 1 2 3 0 0 1 0 1 1 0 0 BaudRate SelectedClock CD = ------------------------------------- 440 32142D–06/2013 ATUC64/128/256L3/4U 20.6.3 Synchronous and Asynchronous Modes 20.6.3.1 Transmitter Operations The transmitter performs equally in both synchronous and asynchronous operating modes (MR.SYNC). One start bit, up to 9 data bits, an optional parity bit, and up to two stop bits are successively shifted out on the TXD pin at each falling edge of the serial clock. The number of data bits is selected by the Character Length field (MR.CHRL) and the MR.MODE9 bit. Nine bits are selected by writing a one to MODE9, overriding any value in CHRL. The parity bit configuration is selected in the MR.PAR field. The Most Significant Bit First bit (MR.MSBF) selects which data bit to send first. The number of stop bits is selected by the MR.NBSTOP field. The 1.5 stop bit configuration is only supported in asynchronous mode. Figure 20-4. Character Transmit The characters are sent by writing to the Character to be Transmitted field (THR.TXCHR). The transmitter reports status with the Transmitter Ready (TXRDY) and Transmitter Empty (TXEMPTY) bits in the Channel Status Register (CSR). TXRDY is set when THR is empty. TXEMPTY is set when both THR and the transmit shift register are empty (transmission complete). Both TXRDY and TXEMPTY are cleared when the transmitter is disabled. Writing a character to THR while TXRDY is zero has no effect and the written character will be lost. Figure 20-5. Transmitter Status 20.6.3.2 Asynchronous Receiver If the USART is configured in an asynchronous operating mode (MR.SYNC = 0), the receiver will oversample the RXD input line by either 8 or 16 times the baud rate clock, as selected by the Oversampling Mode bit (MR.OVER). If the line is zero for half a bit period (four or eight consecutive samples, respectively), a start bit will be assumed, and the following 8th or 16th sample will determine the logical value on the line, in effect resulting in bit values being determined at the middle of the bit period. D0 D1 D2 D3 D4 D5 D6 D7 TXD Start Bit Parity Bit Stop Bit Example: 8-bit, Parity Enabled One Stop Baud Rate Clock D0 D1 D2 D3 D4 D5 D6 D7 TXD Start Bit Parity Bit Stop Bit Baud Rate Clock Start Bit Write THR D0 D1 D2 D3 D4 D5 D6 D7 Parity Bit Stop Bit TXRDY TXEMPTY 441 32142D–06/2013 ATUC64/128/256L3/4U The number of data bits, endianess, parity mode, and stop bits are selected by the same bits and fields as for the transmitter (MR.CHRL, MODE9, MSBF, PAR, and NBSTOP). The synchronization mechanism will only consider one stop bit, regardless of the used protocol, and when the first stop bit has been sampled, the receiver will automatically begin looking for a new start bit, enabling resynchronization even if there is a protocol miss-match. Figure 20-6 and Figure 20-7 illustrate start bit detection and character reception in asynchronous mode. Figure 20-6. Asynchronous Start Bit Detection Figure 20-7. Asynchronous Character Reception 20.6.3.3 Synchronous Receiver In synchronous mode (SYNC=1), the receiver samples the RXD signal on each rising edge of the Baud Rate Clock. If a low level is detected, it is considered as a start bit. Configuration bits and fields are the same as in asynchronous mode. Sampling Clock (x16) RXD Start Detection Sampling Baud Rate Clock RXD Start Rejection Sampling 12345678 12345670 1234 12345678 9 10 11 12 13 14 15 16 D0 Sampling D0 D1 D2 D3 D4 D5 D6 D7 RXD Parity Bit Stop Bit Example: 8-bit, Parity Enabled Baud Rate Clock Start Detection 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 442 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-8. Synchronous Mode Character Reception 20.6.3.4 Receiver Operations When a character reception is completed, it is transferred to the Received Character field in the Receive Holding Register (RHR.RXCHR), and the Receiver Ready bit in the Channel Status Register (CSR.RXRDY) is set. If RXRDY is already set, RHR will be overwritten and the Overrun Error bit (CSR.OVRE) is set. Reading RHR will clear RXRDY, and writing a one to the Reset Status bit in the Control Register (CR.RSTSTA) will clear OVRE. Figure 20-9. Receiver Status 20.6.3.5 Parity The USART supports five parity modes selected by MR.PAR. The PAR field also enables the Multidrop mode, see ”Multidrop Mode” on page 443. If even parity is selected, the parity bit will be a zero if there is an even number of ones in the data character, and if there is an odd number it will be a one. For odd parity the reverse applies. If space or mark parity is chosen, the parity bit will always be a zero or one, respectively. See Table 20-4. D0 D1 D2 D3 D4 D5 D6 D7 RXD Start Sampling Parity Bit Stop Bit Example: 8-bit, Parity Enabled 1 Stop Baud Rate Clock D0 D1 D2 D3 D4 D5 D6 D7 RXD Start Bit Parity Bit Stop Bit Baud Rate Clock Write CR RXRDY OVRE D0 D1 D2 D3 D4 D5 D6 D7 Start Bit Parity Bit Stop Bit RSTSTA = 1 Read RHR Table 20-4. Parity Bit Examples Alphanum Character Hex Bin Parity Mode Odd Even Mark Space None A 0x41 0100 0001 1 0 1 0 - V 0x56 0101 0110 1 0 1 0 - R 0x52 0101 0010 0 1 1 0 - 443 32142D–06/2013 ATUC64/128/256L3/4U The receiver will report parity errors in CSR.PARE, unless parity is disabled. Writing a one to CR.RSTSTA will clear PARE. See Figure 20-10 Figure 20-10. Parity Error 20.6.3.6 Multidrop Mode If PAR is either 0x6 or 0x7, the USART runs in Multidrop mode. This mode differentiates data and address characters. Data has the parity bit zero and addresses have a one. By writing a one to the Send Address bit (CR.SENDA) the user will cause the next character written to THR to be transmitted as an address. Receiving a character with a one as parity bit will set PARE. 20.6.3.7 Transmitter Timeguard The timeguard feature enables the USART to interface slow devices by inserting an idle state on the TXD line in between two characters. This idle state corresponds to a long stop bit, whose duration is selected by the Timeguard Value field in the Transmitter Timeguard Register (TTGR.TG). The transmitter will hold the TXD line high for TG bit periods, in addition to the number of stop bits. As illustrated in Figure 20-11, the behavior of TXRDY and TXEMPTY is modified when TG has a non-zero value. If a pending character has been written to THR, the TXRDY bit will not be set until this characters start bit has been sent. TXEMPTY will remain low until the timeguard transmission has completed. Figure 20-11. Timeguard Operation D0 D1 D2 D3 D4 D5 D6 D7 RXD Start Bit Bad Parity Bit Stop Bit Baud Rate Clock Write CR PARE RXRDY RSTSTA = 1 D0 D1 D2 D3 D4 D5 D6 D7 TXD Start Bit Parity Bit Stop Bit Baud Rate Clock Start Bit TG = 4 Write THR D0 D1 D2 D3 D4 D5 D6 D7 Parity Bit Stop Bit TXRDY TXEMPTY TG = 4 444 32142D–06/2013 ATUC64/128/256L3/4U Table 20-5. Maximum Baud Rate Dependent Timeguard Durations 20.6.3.8 Receiver Time-out The Time-out Value field in the Receiver Time-out Register (RTOR.TO) enables handling of variable-length frames by detection of selectable idle durations on the RXD line. The value written to TO is loaded to a decremental counter, and unless it is zero, a time-out will occur when the amount of inactive bit periods match the initial counter value. If a time-out has not occurred, the counter will reload and restart every time a new character arrives. A time-out sets the TIMEOUT bit in CSR. Clearing TIMEOUT can be done in two ways: • Writing a one to the Start Time-out bit (CR.STTTO). This also aborts count down until the next character has been received. • Writing a one to the Reload and Start Time-out bit (CR.RETTO). This also reloads the counter and restarts count down immediately. Figure 20-12. Receiver Time-out Block Diagram Table 20-6. Maximum Time-out Period Baud Rate (bit/sec) Bit time (µs) Timeguard (ms) 1 200 833 212.50 9 600 104 26.56 14400 69.4 17.71 19200 52.1 13.28 28800 34.7 8.85 33400 29.9 7.63 56000 17.9 4.55 57600 17.4 4.43 115200 8.7 2.21 Baud Rate (bit/sec) Bit Time (µs) Time-out (ms) 600 1 667 109 225 1 200 833 54 613 2 400 417 27 306 4 800 208 13 653 16-bit Time-out Counter 0 TO TIMEOUT Baud Rate Clock = Character Received RETTO Load Clock 16-bit Value STTTO 1 D Q Clear 445 32142D–06/2013 ATUC64/128/256L3/4U 20.6.3.9 Framing Error The receiver is capable of detecting framing errors. A framing error has occurred if a stop bit reads as zero. This can occur if the transmitter and receiver are not synchronized. A framing error is reported by CSR.FRAME as soon as the error is detected, at the middle of the stop bit. Figure 20-13. Framing Error Status 20.6.3.10 Transmit Break When TXRDY is set, the user can request the transmitter to generate a break condition on the TXD line by writing a one to The Start Break bit (CR.STTBRK). The break is treated as a normal 0x00 character transmission, clearing TXRDY and TXEMPTY, but with zeroes for preambles, start, parity, stop, and time guard bits. Writing a one to the Stop Break bit (CR.STBRK) will stop the generation of new break characters, and send ones for TG duration or at least 12 bit periods, ensuring that the receiver detects end of break, before resuming normal operation. Figure 20-14 illustrates STTBRK and STPBRK effect on the TXD line. Writing to STTBRK and STPBRK simultaneously can lead to unpredictable results. Writes to THR before a pending break has started will be ignored. 9 600 104 6 827 14400 69 4 551 19200 52 3 413 28800 35 2 276 33400 30 1 962 56000 18 1 170 57600 17 1 138 200000 5 328 Baud Rate (bit/sec) Bit Time (µs) Time-out (ms) D0 D1 D2 D3 D4 D5 D6 D7 RXD Start Bit Parity Bit Stop Bit Baud Rate Clock Write CR FRAME RXRDY RSTSTA = 1 446 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-14. Break Transmission 20.6.3.11 Receive Break A break condition is assumed when incoming data, parity, and stop bits are zero. This corresponds to a framing error, but FRAME will remain zero while the Break Received/End Of Break bit (CSR.RXBRK) is set. Writing a one to CR.RSTSTA will clear RXBRK. An end of break will also set RXBRK, and is assumed when TX is high for at least 2/16 of a bit period in asynchronous mode, or when a high level is sampled in synchronous mode. 20.6.3.12 Hardware Handshaking The USART features an out-of-band hardware handshaking flow control mechanism, implementable by connecting the RTS and CTS pins with the remote device, as shown in Figure 20- 15. Figure 20-15. Connection with a Remote Device for Hardware Handshaking Writing 0x2 to the MR.MODE field configures the USART to operate in this mode. The receiver will drive its RTS pin high when disabled or when the Reception Buffer Full bit (CSR.RXBUFF) is set by the Buffer Full signal from the Peripheral DMA controller. If the receivers RTS pin is high, the transmitters CTS pin will also be high and only the active character transactions will be completed. Allocating a new buffer to the DMA controller by clearing RXBUFF, will drive the RTS pin low, allowing the transmitter to resume transmission. Detected level changes on the CTS pin can trigger interrupts, and are reported by the CTS Input Change bit in the Channel Status Register (CSR.CTSIC). Figure 20-16 illustrates receiver functionality, and Figure 20-17 illustrates transmitter functionality. D0 D1 D2 D3 D4 D5 D6 D7 TXD Start Bit Parity Bit Stop Bit Baud Rate Clock Write CR TXRDY TXEMPTY STTBRK = 1 STPBRK = 1 Break Transmission End of Break USART TXD CTS Remote Device RXD RXD TXD RTS RTS CTS 447 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-16. Receiver Behavior when Operating with Hardware Handshaking Figure 20-17. Transmitter Behavior when Operating with Hardware Handshaking Figure 20-18. 20.6.4 SPI Mode The USART features a Serial Peripheral Interface (SPI) link compliant mode, supporting synchronous, full-duplex communication, in both master and slave mode. Writing 0xE (master) or 0xF (slave) to MR.MODE will enable this mode. A SPI in master mode controls the data flow to and from the other SPI devices, who are in slave mode. It is possible to let devices take turns being masters (aka multi-master protocol), and one master may shift data simultaneously into several slaves, but only one slave may respond at a time. A slave is selected when its slave select (NSS) signal has been raised by the master. The USART can only generate one NSS signal, and it is possible to use standard I/O lines to address more than one slave. 20.6.4.1 Modes of Operation The SPI system consists of two data lines and two control lines: • Master Out Slave In (MOSI): This line supplies the data shifted from master to slave. In master mode this is connected to TXD, and in slave mode to RXD. • Master In Slave Out (MISO): This line supplies the data shifted from slave to master. In master mode this is connected to RXD, and in slave mode to TXD. • Serial Clock (CLK): This is controlled by the master. One period per bit transmission. In both modes this is connected to CLK. • Slave Select (NSS): This control line allows the master to select or deselect a slave. In master mode this is connected to RTS, and in slave mode to CTS. Changing SPI mode after initial configuration has to be followed by a transceiver software reset in order to avoid unpredictable behavior. 20.6.4.2 Baud Rate The baud rate generator operates as described in ”Baud Rate in Synchronous and SPI Mode” on page 439, with the following requirements: In SPI Master Mode: RTS RXBUFF Write CR RXEN = 1 RXD RXDIS = 1 CTS TXD 448 32142D–06/2013 ATUC64/128/256L3/4U • The Clock Selection field (MR.USCLKS) must not equal 0x3 (external clock, CLK). • The Clock Output Select bit (MR.CLKO) must be one. • The BRGR.CD field must be at least 0x4. • If USCLKS is one (internal divided clock, CLK_USART/DIV), the value in CD has to be even, ensuring a 50:50 duty cycle. CD can be odd if USCLKS is zero (internal clock, CLK_USART). In SPI Slave Mode: • CLK frequency must be at least four times lower than the system clock. 20.6.4.3 Data Transfer • Up to nine data bits are successively shifted out on the TXD pin at each edge. There are no start, parity, or stop bits, and MSB is always sent first. The SPI Clock Polarity (MR.CPOL), and SPI Clock Phase (MR.CPHA) bits configure CLK by selecting the edges upon which bits are shifted and sampled, resulting in four non-interoperable protocol modes see Table 20-7. A master/slave pair must use the same configuration, and the master must be reconfigured if it is to communicate with slaves using different configurations. See Figures 20-19 and 20-20. Figure 20-19. SPI Transfer Format (CPHA=1, 8 bits per transfer) Table 20-7. SPI Bus Protocol Modes SPI Bus Protocol Mode CPOL CPHA 0 01 1 00 2 11 3 10 CLK cycle (for reference) CLK (CPOL= 1) MOSI SPI Master ->TXD SPI Slave ->RXD MISO SPI Master ->RXD SPI Slave ->TXD NSS SPI Master ->RTS SPI Slave ->CTS MSB MSB 1 CLK (CPOL= 0) 3 5 6 7 8 4 3 2 1 LSB 6 6 5 5 4 3 2 1 LSB 2 4 449 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-20. SPI Transfer Format (CPHA=0, 8 bits per transfer) 20.6.4.4 Receiver and Transmitter Control See ”Transmitter Operations” on page 440, and ”Receiver Operations” on page 442. 20.6.4.5 Character Transmission and Reception In SPI master mode, the slave select line (NSS) is asserted low one bit period before the start of transmission, and released high one bit period after every character transmission. A delay for at least three bit periods is always inserted in between characters. In order to address slave devices supporting the Chip Select Active After Transfer (CSAAT) mode, NSS can be forced low by writing a one to the Force SPI Chip Select bit (CR.RTSEN/FCS). Releasing NSS when FCS is one, is only possible by writing a one to the Release SPI Chip Select bit (CR.RTSDIS/RCS). In SPI slave mode, a low level on NSS for at least one bit period will allow the slave to initiate a transmission or reception. The Underrun Error bit (CSR.UNRE) is set if a character must be sent while THR is empty, and TXD will be high during character transmission, as if 0xFF was being sent. If a new character is written to THR it will be sent correctly during the next transmission slot. Writing a one to CR.RSTSTA will clear UNRE. To ensure correct behavior of the receiver in SPI slave mode, the master device sending the frame must ensure a minimum delay of one bit period in between each character transmission. 20.6.4.6 Receiver Time-out Receiver Time-out’s are not possible in SPI mode as the baud rate clock is only active during data transfers. 20.6.5 LIN Mode The USART features a LIN (Local Interconnect Network) 1.3 and 2.0 compliant mode, embedding full error checking and reporting, automatic frame processing with up to 256 data bytes, CLK cycle (for reference) CLK (CPOL= 0) CLK (CPOL= 1) MOSI SPI Master -> TXD SPI Slave -> RXD MISO SPI Master -> RXD SPI Slave -> TXD NSS SPI Master -> RTS SPI Slave -> CTS MSB 6 5 MSB 6 5 4 4 3 3 2 2 1 1 LSB LSB 1 2 3 4 5 6 7 8 450 32142D–06/2013 ATUC64/128/256L3/4U customizable response data lengths, and requires minimal CPU resources. Writing 0xA (master) or 0xB (slave) to MR.MODE enables this mode. 20.6.5.1 Modes of operation Changing LIN mode after initial configuration has to be followed by a transceiver software reset in order to avoid unpredictable behavior. 20.6.5.2 Receiver and Transmitter Control See Section “20.6.2” on page 439. 20.6.5.3 Baud Rate Configuration The LIN nodes baud rate is configured in the Baud Rate Generator Register (BRGR), See Section “20.6.1.1” on page 437. 20.6.5.4 Character Transmission and Reception See ”Transmitter Operations” on page 440, and ”Receiver Operations” on page 442. 20.6.5.5 Header Transmission (Master Node Configuration) All LIN frames start with a header sent by the master. As soon as the identifier has been written to the Identifier Character field in the LIN Identifier Register (LINIR.IDCHR), TXRDY is cleared and the header is sent. The header consists of a Break, Sync, and Identifier field. TXRDY is set when the identifier has been transferred into the transmitters shift register. The Break field consists of 13 dominant bits, the break, and one recessive bit, the break delimiter. The Sync field is the character 0x55. The Identifier field contains the Identifier as written to IDCHR. The identifier parity bits can be generated automatically (see Section 20.6.5.8). Figure 20-21. Header Transmission 20.6.5.6 Header Reception (Slave Node Configuration) The USART stays idle until it detects a break field, consisting of at least 11 consecutive dominant bits (zeroes) on the bus. A received break will set the Lin Break bit (CSR.LINBK). The Sync field is used to synchronize the baud rate (see Section 20.6.5.7). IDCHR is updated and the LIN Identifier bit (CSR.LINID) is set when the Identifier has been received. The Identifier parity bits can be automatically checked (see Section 20.6.5.8). Writing a one to RSTSTA will clear LINBK and LINID. TXD Baud Rate Clock Start Bit Write LINIR 10101010 TXRDY Stop Bit Start Bit Break Field ID0 ID1 ID2 ID3 ID4 ID5 ID6 ID7 13 dominant bits (at 0) Stop Bit Break Delimiter 1 recessive bit (at 1) Synch Byte = 0x55 LINIR ID 451 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-22. Header Reception 20.6.5.7 Slave Node Synchronization Synchronization is only done by the slave. If the Sync field is not 0x55, an Inconsistent Sync Field error (CSR.LINISFE) is generated. The time between falling edges is measured by a 19-bit counter, driven by the sampling clock (see Section 20.6.1). Figure 20-23. Sync Field The counter starts when the Sync field start bit is detected, and continues for eight bit periods. The 16 most significant bits (counter value divided by 8) becomes the new clock divider (BRGR.CD), and the three least significant bits (the remainder) becomes the new fractional part (BRGR.FP). Figure 20-24. Slave Node Synchronization The synchronization accuracy depends on: • The theoretical slave node clock frequency; nominal clock frequency (FNom) • The baud rate Break Field 13 dominant bits (at 0) Break Delimiter 1 recessive bit (at 1) Start Bit 10101010 Stop Bit Start Bit ID0 ID1 ID2 ID4 ID3 ID6 ID5 ID7 Stop Bit Synch Byte = 0x55 Baud Rate Clock RXD Write US_CR With RSTSTA=1 US_LINIR LINID Start bit Stop bit Synch Field 8 Tbit 2 Tbit 2 Tbit 2 Tbit 2 Tbit RXD Baud Rate Clock LINIDRX Synchro Counter 000_0011_0001_0110_1101 BRGR Clcok Divider (CD) 0000_0110_0010_1101 BRGR Fractional Part (FP) 101 Initial CD Initial FP Reset Start Bit 10101010 Stop Bit Start Bit Break Field ID0 ID1 ID2 ID3 ID4 ID5 ID6 ID7 13 dominant bits (at 0) Stop Bit Break Delimiter 1 recessive bit (at 1) Synch Byte = 0x55 452 32142D–06/2013 ATUC64/128/256L3/4U • The oversampling mode (OVER=0 => 16x, or OVER=1 => 8x) The following formula is used to calculate synchronization deviation, where FSLAVE is the real slave node clock frequency, and FTOL_UNSYNC is the difference between FNom and FSLAVE According to the LIN specification, FTOL_UNSYNCH may not exceed ±15%, and the bit rates between two nodes must be within ±2% of each other, resulting in a maximal BaudRate_deviation of ±1%. Minimum nominal clock frequency with a fractional part: Examples: • Baud rate = 20 kbit/s, OVER=0 (Oversampling 16x) => FNom(min) = 2.64 MHz • Baud rate = 20 kbit/s, OVER=1 (Oversampling 8x) => FNom(min) = 1.47 MHz • Baud rate = 1 kbit/s, OVER=0 (Oversampling 16x) => FNom(min) = 132 kHz • Baud rate = 1 kbit/s, OVER=1 (Oversampling 8x) => FNom(min) = 74 kHz If the fractional part is not used, the synchronization accuracy is much lower. The 16 most significant bits, added with the first least significant bit, becomes the new clock divider (CD). The equation of the baud rate deviation is the same as above, but the constants are: Minimum nominal clock frequency without a fractional part: Examples: • Baud rate = 20 kbit/s, OVER=0 (Oversampling 16x) => FNom(min) = 19.12 MHz • Baud rate = 20 kbit/s, OVER=1 (Oversampling 8x) => FNom(min) = 9.71 MHz • Baud rate = 1 kbit/s, OVER=0 (Oversampling 16x) => FNom(min) = 956 kHz • Baud rate = 1 kbit/s, OVER=1 (Oversampling 8x) => FNom(min) = 485 kHz 20.6.5.8 Identifier Parity An identifier field consists of two sub-fields; the identifier and its parity. Bits 0 to 5 are assigned to the identifier, while bits 6 and 7 are assigned to parity. Automatic parity management is disabled by writing a one to the Parity Disable bit in the LIN Mode register (LINMR.PARDIS). BaudRate_deviation 100   8 2 OVER    – +   BaudRate 8 FSLAVE   --------------------------------------------------------------------------------------------------   =   % BaudRate_deviation 100   8 2 OVER    – +   BaudRate 8 FTOL_UNSYNC 100 -----------------------------------     xFNom   --------------------------------------------------------------------------------------------------       = % –0.5    +0.5 -1    +1 FNom  min 100   0.5 8 2 OVER     – + 1  BaudRate 8 –15 100 --------- + 1       1%  ------------------------------------------------------------------------------------------------------       = Hz –4    +4 -1    +1 FNom  min 100   4 8 2 OVER     – + 1  Baudrate 8 –15 100 --------- + 1       1%  -----------------------------------------------------------------------------------------------       = Hz 453 32142D–06/2013 ATUC64/128/256L3/4U • PARDIS=0: During header transmission, the parity bits are computed and in the shift register they replace bits six and seven from IDCHR. During header reception, the parity bits are checked and can generate a LIN Identifier Parity Error (see Section 20.6.6). Bits six and seven in IDCHR read as zero when receiving. • PARDIS=1: During header transmission, all the bits in IDCHR are sent on the bus. During header reception, all the bits in IDCHR are updated with the received Identifier. 20.6.5.9 Node Action After an identifier transaction, a LIN response mode has to be selected. This is done in the Node Action field (LINMR.NACT). Below are some response modes exemplified in a small LIN cluster: • Response, from master to slave1: Master: NACT=PUBLISH Slave1: NACT=SUBSCRIBE Slave2: NACT=IGNORE • Response, from slave1 to master: Master: NACT=SUBSCRIBE Slave1: NACT=PUBLISH Slave2: NACT=IGNORE • Response, from slave1 to slave2: Master: NACT=IGNORE Slave1: NACT=PUBLISH Slave2: NACT=SUBSCRIBE 20.6.5.10 LIN Response Data Length The response data length is the number of data fields (bytes), excluding the checksum. Figure 20-25. Response Data Length The response data length can be configured, either by the user, or automatically by bits 4 and 5 in the Identifier (IDCHR), in accordance to LIN 1.1. The user selects mode by writing to the Data Length Mode bit (LINMR.DML): • DLM=0: the response data length is configured by the user by writing to the 8-bit Data Length Control field (LINMR.DLC). The response data length equals DLC + 1 bytes. User configuration: 1 - 256 data fields (DLC+1) Identifier configuration: 2/4/8 data fields Sync Break Sync Field Identifier Field Checksum Field Data Field Data Field Data Field Data Field 454 32142D–06/2013 ATUC64/128/256L3/4U • DLM=1: the response data length is defined by the Identifier bits according to the table below. 20.6.5.11 Checksum The last frame field is the checksum. It is configured by the Checksum Type (LINMR.CHKTYP), and the Checksum Disable (LINMR.CHKDIS) bits. TXRDY will not be set after the last THR data write if enabled. Writing a one to CHKDIS will disable the automatic checksum generation/checking, and the user may send/check this last byte manually, disguised as a normal data. The checksum is an inverted 8-bit sum with carry, either: • over all data bytes, called a classic checksum. This is used for LIN 1.3 compliant slaves, and automatically managed when CHKDIS=0, and CHKTYP=1. • over all data bytes and the protected identifier, called an enhanced checksum. This is used for LIN 2.0 compliant slaves, and automatically managed when CHKDIS=0, and CHKTYP=0. 20.6.5.12 Frame Slot Mode A LIN master can be configured to use frame slots with a pre-defined minimum length. Writing a one to the Frame Slot Mode Disable bit (LINMR.FSDIS) disables this mode. This mode will not allow TXRDY to be set after a frame transfer until the entire frame slot duration has elapsed, in effect preventing the master from sending a new header. The LIN Transfer Complete bit (CSR.LINTC) will still be set after the checksum has been sent. Writing a one to CR.RSTST clears LINTC. Figure 20-26. Frame Slot Mode with Automatic Checksum The minimum frame slot size is determined by TFrame_Maximum, and calculated below (all values in bit periods): • THeader_Nominal = 34 Table 20-8. Response Data Length if DLM = 1 IDCHR[5] IDCHR[4] Response Data Length [bytes] 00 2 01 2 10 4 11 8 Break Synch Protected Identifier Data N Checksum Header Interframe space Response space Frame Frame slot = TFrame_Maximum Response TXRDY Write THR Write LINID Data 1 Data 2 Data 3 Data3 Data N-1 Data N Frame Slot Mode Disabled Frame Slot Mode Enabled LINTC Data 1 455 32142D–06/2013 ATUC64/128/256L3/4U • TFrame_Maximum = 1.4 x (THeader_Nominal + TResponse_Nominal + 1)(Note:) Note: The term “+1” leads to an integer result for TFrame_Max (LIN Specification 1.3) If the Checksum is sent (CHKDIS=0): • TResponse_Nominal = 10 x (NData + 1) • TFrame_Maximum = 1.4 x (34 + 10 x (DLC + 1 + 1) + 1) • TFrame_Maximum = 77 + 14 x DLC If the Checksum is not sent (CHKDIS=1): • TResponse_Nominal = 10 x NData • TFrame_Maximum = 1.4 x (34 + 10 x (DLC + 1) + 1) • TFrame_Maximum = 63 + 14 x DLC 20.6.6 LIN Errors These error bits are cleared by writing a one to CSR.RSTSTA. 20.6.6.1 Slave Not Responding Error (CSR.LINSNRE) This error is generated if no valid message appears within the TFrame_Maximum time frame slot, while the USART is expecting a response from another node (NACT=SUBSCRIBE). 20.6.6.2 Checksum Error (CSR.LINCE) This error is generated if the received checksum is wrong. This error can only be generated if the checksum feature is enabled (CHKDIS=0). 20.6.6.3 Identifier Parity Error (CSR.LINIPE) This error is generated if the identifier parity is wrong. This error can only be generated if parity is enabled (PARDIS=0). 20.6.6.4 Inconsistent Sync Field Error (CSR.LINISFE) This error is generated in slave mode if the Sync Field character received is not 0x55. Synchronization procedure is aborted. 20.6.6.5 Bit Error (CSR.LINBE) This error is generated if the value transmitted by the USART on Tx differs from the value sampled on Rx. If a bit error is detected, the transmission is aborted at the next byte border. 20.6.7 LIN Frame Handling 20.6.7.1 Master Node Configuration • Write a one to CR.TXEN and CR.RXEN to enable both transmitter and receiver • Select LIN mode and master node by writing to MR.MODE • Configure the baud rate by writing to CD and FP in BRGR • Configure the frame transfer by writing to NACT, PARDIS, CHKDIS, CHKTYPE, DLCM, FSDIS, and DLC in LINMR • Check that CSR.TXRDY is one • Send the header by writing to LINIR.IDCHR The following procedure depends on the NACT setting: 456 32142D–06/2013 ATUC64/128/256L3/4U • Case 1: NACT=PUBLISH, the USART sends a response – Wait until TXRDY is a one – Send a byte by writing to THR.TXCHR – Repeat the two previous steps until there is no more data to send – Wait until CSR.LINTC is a one – Check for LIN errors • Case 2: NACT=SUBSCRIBE, the USART receives a response – Wait until RXRDY is a one – Read RHR.RXCHR – Repeat the two previous steps until there is no more data to read – Wait until LINTC is a one – Check for LIN errors • Case 3: NACT=IGNORE, the USART is not concerned by a response – Wait until LINTC is a one – Check for LIN errors Figure 20-27. Master Node Configuration, NACT=PUBLISH Frame Break Synch Protected Identifier Data 1 Data N Checksum TXRDY Write THR Write LINIR Data 1 Data 2 Data 3 Data N-1 Data N RXRDY Header Interframe space Response space Frame slot = TFrame_Maximum Data3 Response LINTC FSDIS=1 FSDIS=0 457 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-28. Master Node Configuration, NACT=SUBSCRIBE Figure 20-29. Master Node Configuration, NACT=IGNORE 20.6.7.2 Slave Node Configuration This is identical to the master node configuration above, except for: • LIN mode selected in MR.MODE is slave • When the baud rate is configured, wait until CSR.LINID is a one, then; • Check for LINISFE and LINPE errors, clear errors and LINIDby writing a one to RSTSTA • Read IDCHR • Configure the frame transfer by writing to NACT, PARDIS, CHKDIS, CHKTYPE, DLCM, and DLC in LINMR IMPORTANT: if NACT=PUBLISH, and this field is already correct, the LINMR register must still be written with this value in order to set TXRDY, and to request the corresponding Peripheral DMA Controller write transfer. The different NACT settings result in the same procedure as for the master node, see page 455. Break Synch Protected Identifier Data 1 Data N Checksum TXRDY Read RHR Write LINIR Data 1 Data N-1 Data N-1 RXRDY Data N-2 Data N Header Interframe Response space space Frame Frame slot = TFrame_Maximum Data3 Response LINTC FSDIS=1 FSDIS=0 TXRDY Write LINIR RXRDY LINTC Break Synch Protected Identifier Data 1 Data N-1 Data N Checksum Header Interframe Response space space Frame Frame slot = TFrame_Maximum Data3 Response FSDIS=1 FSDIS=0 458 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-30. Slave Node Configuration, NACT=PUBLISH Figure 20-31. Slave Node Configuration, NACT=SUBSCRIBE Figure 20-32. Slave Node Configuration, NACT=IGNORE 20.6.8 LIN Frame Handling With The Peripheral DMA Controller The USART can be used together with the Peripheral DMA Controller in order to transfer data without processor intervention. The DMA Controller uses the TXRDY and RXRDY bits, to trigger one byte writes or reads. It always writes to THR, and it always reads RHR. Break Synch Protected Identifier Data 1 Data N Checksum TXRDY Write THR Read LINID Data 1 Data 3 Data N-1 Data N RXRDY LINIDRX Data 2 LINTC TXRDY Read RHR Read LINID RXRDY LINIDRX LINTC Break Synch Protected Identifier Data 1 Data N Checksum Data 1 Data N-1 Data N-2 Data N-1 Data N TXRDY Read RHR Read LINID RXRDY LINIDRX LINTC Break Synch Protected Identifier Data 1 Data N Checksum Data N-1 459 32142D–06/2013 ATUC64/128/256L3/4U 20.6.8.1 Master Node Configuration The Peripheral DMA Controller Mode bit (LINMR.PDCM) allows the user to select configuration: • PDCM=0: LIN configuration must be written to LINMR, it is not stored in the write buffer. • PDCM=1: LIN configuration is written by the DMA Controller to THR, and is stored in the write buffer. Since data transfer size is a byte, the transfer is split into two accesses. The first writes the NACT, PARDIS, CHKDIS, CHKTYP, DLM and FSDIS bits, while the second writes the DLC field. If NACT=PUBLISH, the write buffer will also contain the Identifier. When NACT=SUBSCRIBE, the read buffer contains the data. Figure 20-33. Master Node with Peripheral DMA Controller (PDCM=0) Figure 20-34. Master Node with Peripheral DMA Controller (PDCM=1) | | | | RXRDY TXRDY Peripheral bus USART LIN CONTROLLER DATA 0 DATA N | | | | READ BUFFER NODE ACTION = PUBLISH NODE ACTION = SUBSCRIBE Peripheral DMA Controller RXRDY Peripheral bus DATA 0 DATA 1 DATA N WRITE BUFFER Peripheral DMA Controller USART LIN CONTROLLER | | | | | | | | NACT PARDIS CHKDIS CHKTYP DLM FSDIS DLC IDENTIFIER DATA 0 DATA N WRITE BUFFER RXRDY Peripheral bus DLC IDENTIFIER DATA 0 DATA N WRITE BUFFER RXRDY READ BUFFER NODE ACTION = PUBLISH NODE ACTION = SUBSCRIBE Peripheral DMA Controller Peripheral DMA Controller USART LIN CONTROLLER NACT PARDIS CHKDIS CHKTYP DLM FSDIS USART LIN CONTROLLER TXRDY Peripheral bus 460 32142D–06/2013 ATUC64/128/256L3/4U 20.6.8.2 Slave Node Configuration In this mode, the Peripheral DMA Controller transfers only data. The user reads the Identifier from LINIR, and selects LIN mode by writing to LINMR. When NACT=PUBLISH the data is in the write buffer, while the read buffer contains the data when NACT=SUBSCRIBE. IMPORTANT: if in slave mode, NACT is already configured correctly as PUBLISH, the LINMR register must still be written with this value in order to set TXRDY, and to request the corresponding Peripheral DMA Controller write transfer. Figure 20-35. Slave Node with Peripheral DMA Controller 20.6.9 Wake-up Request Any node in a sleeping LIN cluster may request a wake-up. By writing to the Wakeup Signal Type bit (LINMR.WKUPTYP), the user can choose to send either a LIN 1.3 (WKUPTYP=1), or a LIN 2.0 (WKUPTYP=0) compliant wakeup request. Writing a one to the Send LIN Wakeup Signal bit (CR.LINWKUP), transmits a wakeup, and when completed sets LINTC. According to LIN 1.3, the wakeup request should be generated with the character 0x80 in order to impose eight successive dominant bits. According to LIN 2.0, the wakeup request is issued by forcing the bus into the dominant state for 250µs to 5ms. Sending the character 0xF0 does this, regardless of baud rate. • Baud rate max = 20 kbit/s -> one bit period = 50µs -> five bit periods = 250µs • Baud rate min = 1 kbit/s -> one bit period = 1ms -> five bit periods = 5ms 20.6.10 Bus Idle Time-out LIN bus inactivity should eventually cause slaves to time-out and enter sleep mode. LIN 1.3 specifies this to 25000 bit periods, whilst LIN 2.0 specifies 4seconds. For the time-out counter operation see Section 20.6.3.8 ”Receiver Time-out” on page 444. | | | | | | | | DATA 0 DATA N RXRDY Peripheral Bus READ BUFFER NACT = SUBSCRIBE DATA 0 DATA N TXRDY Peripheral bus WRITE BUFFER USART LIN CONTROLLER USART LIN CONTROLLER Peripheral DMA Controller Peripheral DMA Controller Table 20-9. Receiver Time-out Values (RTOR.TO) LIN Specification Baud Rate Time-out period TO 2.0 1 000 bit/s 4s 4 000 2 400 bit/s 9 600 9 600 bit/s 38 400 19 200 bit/s 76 800 20 000 bit/s 80 000 1.3 - 25 000 bit periods 25 000 461 32142D–06/2013 ATUC64/128/256L3/4U 20.6.11 Test Modes The internal loopback feature enables on-board diagnostics, and allows the USART to operate in three different test modes, with reconfigured pin functionality, as shown below. 20.6.11.1 Normal Mode During normal operation, a receivers RXD pin is connected to a transmitters TXD pin. Figure 20-36. Normal Mode Configuration 20.6.11.2 Automatic Echo Mode Automatic echo mode allows bit-by-bit retransmission. When a bit is received on the RXD pin, it is also sent to the TXD pin, as shown in Figure 20-37. Transmitter configuration has no effect. Figure 20-37. Automatic Echo Mode Configuration 20.6.11.3 Local Loopback Mode Local loopback mode connects the output of the transmitter directly to the input of the receiver, as shown in Figure 20-38. The TXD and RXD pins are not used. The RXD pin has no effect on the receiver and the TXD pin is continuously driven high, as in idle state. Figure 20-38. Local Loopback Mode Configuration 20.6.11.4 Remote Loopback Mode Remote loopback mode connects the RXD pin to the TXD pin, as shown in Figure 20-39. The transmitter and the receiver are disabled and have no effect. This mode allows bit-by-bit retransmission. Receiver Transmitter RXD TXD Receiver Transmitter RXD TXD Receiver Transmitter RXD TXD 1 462 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-39. Remote Loopback Mode Configuration 20.6.12 Write Protection Registers To prevent single software errors from corrupting USART behavior, certain address spaces can be write-protected by writing the correct Write Protect KEY and a one to the Write Protect Enable bit in the Write Protect Mode Register (WPMR.WPKEY, and WPMR.WPEN). Disabling the write protection is done by writing the correct key, and a zero to WPEN. Write attempts to a write protected register are detected and the Write Protect Violation Status bit in the Write Protect Status Register (WPSR.WPVS) is set, while the Write Protect Violation Source field (WPSR.WPVSRC) indicates the targeted register. Writing the correct key to the Write Protect KEY bit (WPMR.WPKEY) clears WPVSRC and WPVS. The protected registers are: • ”Mode Register” on page 466 • ”Baud Rate Generator Register” on page 476 • ”Receiver Time-out Register” on page 477 • ”Transmitter Timeguard Register” on page 478 Receiver Transmitter RXD TXD 1 463 32142D–06/2013 ATUC64/128/256L3/4U 20.7 User Interface Note: 1. Values in the Version Register vary with the version of the IP block implementation. Table 20-10. USART Register Memory Map Offset Register Name Access Reset 0x0000 Control Register CR Write-only 0x00000000 0x0004 Mode Register MR Read-write 0x00000000 0x0008 Interrupt Enable Register IER Write-only 0x00000000 0x000C Interrupt Disable Register IDR Write-only 0x00000000 0x0010 Interrupt Mask Register IMR Read-only 0x00000000 0x0014 Channel Status Register CSR Read-only 0x00000000 0x0018 Receiver Holding Register RHR Read-only 0x00000000 0x001C Transmitter Holding Register THR Write-only 0x00000000 0x0020 Baud Rate Generator Register BRGR Read-write 0x00000000 0x0024 Receiver Time-out Register RTOR Read-write 0x00000000 0x0028 Transmitter Timeguard Register TTGR Read-write 0x00000000 0x0054 LIN Mode Register LINMR Read-write 0x00000000 0x0058 LIN Identifier Register LINIR Read-write 0x00000000 0x00E4 Write Protect Mode Register WPMR Read-write 0x00000000 0x00E8 Write Protect Status Register WPSR Read-only 0x00000000 0x00FC Version Register VERSION Read-only 0x–(1) 464 32142D–06/2013 ATUC64/128/256L3/4U 20.7.1 Control Register Name: CR Access Type: Write-only Offset: 0x0 Reset Value: 0x00000000 • LINWKUP: Send LIN Wakeup Signal Writing a zero to this bit has no effect. Writing a one to this bit will sends a wakeup signal on the LIN bus. • LINABT: Abort LIN Transmission Writing a zero to this bit has no effect. Writing a one to this bit will abort the current LIN transmission. • RTSDIS/RCS: Request to Send Disable/Release SPI Chip Select Writing a zero to this bit has no effect. Writing a one to this bit when USART is not in SPI master mode drives RTS pin high. Writing a one to this bit when USART is in SPI master mode releases NSS (RTS pin). • RTSEN/FCS: Request to Send Enable/Force SPI Chip Select Writing a zero to this bit has no effect. Writing a one to this bit when USART is not in SPI master mode drives RTS low. Writing a one to this bit when USART is in SPI master mode when; FCS=0: has no effect. FCS=1: forces NSS (RTS pin) low, even if USART is not transmitting, in order to address SPI slave devices supporting the CSAAT Mode (Chip Select Active After Transfer). • RETTO: Rearm Time-out Writing a zero to this bit has no effect. Writing a one to this bit reloads the time-out counter and clears CSR.TIMEOUT. • RSTNACK: Reset Non Acknowledge Writing a zero to this bit has no effect. Writing a one to this bit clears CSR.NACK. • SENDA: Send Address Writing a zero to this bit has no effect. Writing a one to this bit will in multidrop mode send the next character written to THR as an address. • STTTO: Start Time-out Writing a zero to this bit has no effect. Writing a one to this bit will abort any current time-out count down, and trigger a new count down when the next character has been received. CSR.TIMEOUT is also cleared. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – LINWKUP LINABT RTSDIS/RCS RTSEN/FCS – – 15 14 13 12 11 10 9 8 RETTO RSTNACK – SENDA STTTO STPBRK STTBRK RSTSTA 76543210 TXDIS TXEN RXDIS RXEN RSTTX RSTRX – – 465 32142D–06/2013 ATUC64/128/256L3/4U • STPBRK: Stop Break Writing a zero to this bit has no effect. Writing a one to this bit will stop the generation of break signal characters, and then send ones for TTGR.TG duration, or at least 12 bit periods. No effect if no break is being transmitted. • STTBRK: Start Break Writing a zero to this bit has no effect. Writing a one to this bit will start transmission of break characters when current characters present in THR and the transmit shift register have been sent. No effect if a break signal is already being generated. • RSTSTA: Reset Status Bits Writing a zero to this bit has no effect. Writing a one to this bit will clear the following bits in CSR: PARE, FRAME, OVRE, LINBE, LINSFE, LINIPE, LINCE, LINSNRE, and RXBRK. • TXDIS: Transmitter Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the transmitter. • TXEN: Transmitter Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the transmitter if TXDIS is zero. • RXDIS: Receiver Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the receiver. • RXEN: Receiver Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the receiver if RXDIS is zero. • RSTTX: Reset Transmitter Writing a zero to this bit has no effect. Writing a one to this bit will reset the transmitter. • RSTRX: Reset Receiver Writing a zero to this bit has no effect. Writing a one to this bit will reset the receiver. 466 32142D–06/2013 ATUC64/128/256L3/4U 20.7.2 Mode Register Name: MR Access Type: Read-write Offset: 0x4 Reset Value: 0x00000000 This register can only be written if the WPEN bit is cleared in the Write Protect Mode Register. • INACK: Inhibit Non Acknowledge 0: The NACK is generated. 1: The NACK is not generated. • OVER: Oversampling Mode 0: Oversampling at 16 times the baud rate. 1: Oversampling at 8 times the baud rate. • CLKO: Clock Output Select 0: The USART does not drive the CLK pin. 1: The USART drives the CLK pin unless USCLKS selects the external clock. • MODE9: 9-bit Character Length 0: CHRL defines character length. 1: 9-bit character length. • MSBF/CPOL: Bit Order or SPI Clock Polarity If USART does not operate in SPI Mode: MSBF=0: Least Significant Bit is sent/received first. MSBF=1: Most Significant Bit is sent/received first. If USART operates in SPI Mode, CPOL is used with CPHA to produce the required clock/data relationship between devices. CPOL=0: The inactive state value of CLK is logic level zero. CPOL=1: The inactive state value of CLK is logic level one. 31 30 29 28 27 26 25 24 ––––– – 23 22 21 20 19 18 17 16 – – – INACK OVER CLKO MODE9 MSBF/CPOL 15 14 13 12 11 10 9 8 CHMODE NBSTOP PAR SYNC/CPHA 76543210 CHRL USCLKS MODE 467 32142D–06/2013 ATUC64/128/256L3/4U • CHMODE: Channel Mode • NBSTOP: Number of Stop Bits • PAR: Parity Type • SYNC/CPHA: Synchronous Mode Select or SPI Clock Phase If USART does not operate in SPI Mode (MODE is  0xE and 0xF): SYNC = 0: USART operates in Asynchronous Mode. SYNC = 1: USART operates in Synchronous Mode. If USART operates in SPI Mode, CPHA determines which edge of CLK causes data to change and which edge causes data to be captured. CPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. CPHA = 0: Data is changed on the leading edge of CLK and captured on the following edge of CLK. CPHA = 1: Data is captured on the leading edge of CLK and changed on the following edge of CLK. Table 20-11. CHMODE Mode Description 0 0 Normal Mode 0 1 Automatic Echo. Receiver input is connected to the TXD pin. 1 0 Local Loopback. Transmitter output is connected to the Receiver input. 1 1 Remote Loopback. RXD pin is internally connected to the TXD pin. Table 20-12. NBSTOP Asynchronous (SYNC=0) Synchronous (SYNC=1) 0 0 1 stop bit 1 stop bit 0 1 1.5 stop bits Reserved 1 0 2 stop bits 2 stop bits 1 1 Reserved Reserved Table 20-13. PAR Parity Type 0 0 0 Even parity 0 0 1 Odd parity 0 1 0 Parity forced to 0 (Space) 0 1 1 Parity forced to 1 (Mark) 1 0 x No parity 1 1 x Multidrop mode 468 32142D–06/2013 ATUC64/128/256L3/4U • CHRL: Character Length. • USCLKS: Clock Selection Note: 1. The value of DIV is device dependent. Please refer to the Module Configuration section at the end of this chapter. • MODE Table 20-14. CHRL Character Length 0 0 5 bits 0 1 6 bits 1 0 7 bits 1 1 8 bits Table 20-15. USCLKS Selected Clock 0 0 CLK_USART 0 1 CLK_USART/DIV(1) 1 0 Reserved 1 1 CLK Table 20-16. MODE Mode of the USART 0 0 0 0 Normal 0 0 1 0 Hardware Handshaking 1 0 1 0 LIN Master 1 0 1 1 LIN Slave 1 1 1 0 SPI Master 1 1 1 1 SPI Slave Others Reserved 469 32142D–06/2013 ATUC64/128/256L3/4U 20.7.3 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x8 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 – – LINSNRE LINCE LINIPE LINISFE LINBE – 23 22 21 20 19 18 17 16 – – – – CTSIC – – – 15 14 13 12 11 10 9 8 LINTC LINID NACK/LINBK RXBUFF – ITER/UNRE TXEMPTY TIMEOUT 76543210 PARE FRAME OVRE – – RXBRK TXRDY RXRDY 470 32142D–06/2013 ATUC64/128/256L3/4U 20.7.4 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0xC Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 – – LINSNRE LINCE LINIPE LINISFE LINBE – 23 22 21 20 19 18 17 16 – – – – CTSIC – – – 15 14 13 12 11 10 9 8 LINTC LINID NACK/LINBK RXBUFF – ITER/UNRE TXEMPTY TIMEOUT 76543210 PARE FRAME OVRE – – RXBRK TXRDY RXRDY 471 32142D–06/2013 ATUC64/128/256L3/4U 20.7.5 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x10 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 – – LINSNRE LINCE LINIPE LINISFE LINBE – 23 22 21 20 19 18 17 16 – – – – CTSIC – – – 15 14 13 12 11 10 9 8 LINTC LINID NACK/LINBK RXBUFF – ITER/UNRE TXEMPTY TIMEOUT 76543210 PARE FRAME OVRE – – RXBRK TXRDY RXRDY 472 32142D–06/2013 ATUC64/128/256L3/4U 20.7.6 Channel Status Register Name: CSR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 • LINSNRE: LIN Slave Not Responding Error 0: No LIN Slave Not Responding Error has been detected since the last RSTSTA. 1: A LIN Slave Not Responding Error has been detected since the last RSTSTA. • LINCE: LIN Checksum Error 0: No LIN Checksum Error has been detected since the last RSTSTA. 1: A LIN Checksum Error has been detected since the last RSTSTA. • LINIPE: LIN Identifier Parity Error 0: No LIN Identifier Parity Error has been detected since the last RSTSTA. 1: A LIN Identifier Parity Error has been detected since the last RSTSTA. • LINISFE: LIN Inconsistent Sync Field Error 0: No LIN Inconsistent Sync Field Error has been detected since the last RSTSTA 1: The USART is configured as a Slave node and a LIN Inconsistent Sync Field Error has been detected since the last RSTSTA. • LINBE: LIN Bit Error 0: No Bit Error has been detected since the last RSTSTA. 1: A Bit Error has been detected since the last RSTSTA. • CTS: Image of CTS Input 0: CTS is low. 1: CTS is high. • CTSIC: Clear to Send Input Change Flag 0: No change has been detected on the CTS pin since the last CSR read. 1: At least one change has been detected on the CTS pin since the last CSR read. • LINTC: LIN Transfer Completed 0: The USART is either idle or a LIN transfer is ongoing. 1: A LIN transfer has been completed since the last RSTSTA. • LINID: LIN Identifier 0: No LIN Identifier has been sent or received. 1: A LIN Identifier has been sent (master) or received (slave), since the last RSTSTA. • NACK: Non Acknowledge 0: No Non Acknowledge has been detected since the last RSTNACK. 1: At least one Non Acknowledge has been detected since the last RSTNACK. • RXBUFF: Reception Buffer Full 0: The Buffer Full signal from the Peripheral DMA Controller channel is inactive. 31 30 29 28 27 26 25 24 – – LINSNRE LINCE LINIPE LINISFE LINBE – 23 22 21 20 19 18 17 16 CTS – – – CTSIC – – – 15 14 13 12 11 10 9 8 LINTC LINID NACK/LINBK RXBUFF – ITER/UNRE TXEMPTY TIMEOUT 76543210 PARE FRAME OVRE – – RXBRK TXRDY RXRDY 473 32142D–06/2013 ATUC64/128/256L3/4U 1: The Buffer Full signal from the Peripheral DMA Controller channel is active. • ITER/UNRE: Max number of Repetitions Reached or SPI Underrun Error If USART does not operate in SPI Slave Mode: ITER=0: Maximum number of repetitions has not been reached since the last RSTSTA. ITER=1: Maximum number of repetitions has been reached since the last RSTSTA. If USART operates in SPI Slave Mode: UNRE=0: No SPI underrun error has occurred since the last RSTSTA. UNRE=1: At least one SPI underrun error has occurred since the last RSTSTA. • TXEMPTY: Transmitter Empty 0: The transmitter is either disabled or there are characters in THR, or in the transmit shift register. 1: There are no characters in neither THR, nor in the transmit shift register. • TIMEOUT: Receiver Time-out 0: There has not been a time-out since the last Start Time-out command (CR.STTTO), or RTOR.TO is zero. 1: There has been a time-out since the last Start Time-out command. • PARE: Parity Error 0: Either no parity error has been detected, or the parity bit is a zero in multidrop mode, since the last RSTSTA. 1: Either at least one parity error has been detected, or the parity bit is a one in multidrop mode, since the last RSTSTA. • FRAME: Framing Error 0: No stop bit has been found as low since the last RSTSTA. 1: At least one stop bit has been found as low since the last RSTSTA. • OVRE: Overrun Error 0: No overrun error has occurred since the last RSTSTA. 1: At least one overrun error has occurred since the last RSTSTA. • RXBRK: Break Received/End of Break 0: No Break received or End of Break detected since the last RSTSTA. 1: Break received or End of Break detected since the last RSTSTA. • TXRDY: Transmitter Ready 0: The transmitter is either disabled, or a character in THR is waiting to be transferred to the transmit shift register, or an STTBRK command has been requested. As soon as the transmitter is enabled, TXRDY becomes one. 1: There is no character in the THR. • RXRDY: Receiver Ready 0: The receiver is either disabled, or no complete character has been received since the last read of RHR. If characters were being received when the receiver was disabled, RXRDY changes to 1 when the receiver is enabled. 1: At least one complete character has been received and RHR has not yet been read. 474 32142D–06/2013 ATUC64/128/256L3/4U 20.7.7 Receiver Holding Register Name: RHR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 • RXCHR: Received Character Last received character. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 – – – – – – – RXCHR[8] 76543210 RXCHR[7:0] 475 32142D–06/2013 ATUC64/128/256L3/4U 20.7.8 Transmitter Holding Register Name: THR Access Type: Write-only Offset: 0x1C Reset Value: 0x00000000 • TXCHR: Character to be Transmitted If TXRDY is zero this field contains the next character to be transmitted. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 – – – – – – – TXCHR[8] 76543210 TXCHR[7:0] 476 32142D–06/2013 ATUC64/128/256L3/4U 20.7.9 Baud Rate Generator Register Name: BRGR Access Type: Read-write Offset: 0x20 Reset Value: 0x00000000 This register can only be written to if write protection is disabled, see ”Write Protect Mode Register” on page 482. • FP: Fractional Part 0: Fractional divider is disabled. 1 - 7: Baud rate resolution, defined by FP x 1/8. • CD: Clock Divider 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – – – – FP 15 14 13 12 11 10 9 8 CD[15:8] 76543210 CD[7:0] Table 20-17. CD SYNC = 0 SYNC = 1 or MODE = SPI (Master or Slave) OVER = 0 OVER = 1 0 Baud Rate Clock Disabled 1 to 65535 Baud Rate = Selected Clock/16/CD Baud Rate = Selected Clock/8/CD Baud Rate = Selected Clock /CD 477 32142D–06/2013 ATUC64/128/256L3/4U 20.7.10 Receiver Time-out Register Name: RTOR Access Type: Read-write Offset: 0x24 Reset Value: 0x00000000 This register can only be written to if write protection is disabled, see ”Write Protect Mode Register” on page 482. • TO: Time-out Value 0: The receiver Time-out is disabled. 1 - 131071: The receiver Time-out is enabled and the time-out delay is TO x bit period. Note that the size of the TO counter is device dependent, see the Module Configuration section. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – – – – – – TO[16] 15 14 13 12 11 10 9 8 TO[15:8] 76543210 TO[7:0] 478 32142D–06/2013 ATUC64/128/256L3/4U 20.7.11 Transmitter Timeguard Register Name: TTGR Access Type: Read-write Offset: 0x28 Reset Value: 0x00000000 This register can only be written to if write protection is disabled, see ”Write Protect Mode Register” on page 482. • TG: Timeguard Value 0: The transmitter Timeguard is disabled. 1 - 255: The transmitter timeguard is enabled and the timeguard delay is TG x bit period. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 –––––––– 76543210 TG 479 32142D–06/2013 ATUC64/128/256L3/4U 20.7.12 LIN Mode Register Name: LINMR Access Type: Read-write Offset: 0x54 Reset Value: 0x00000000 • PDCM: Peripheral DMA Controller Mode 0: The LIN mode register is not written by the Peripheral DMA Controller. 1: The LIN mode register is, except for this bit, written by the Peripheral DMA Controller. • DLC: Data Length Control 0 - 255: If DLM=0 this field defines the response data length to DLC+1 bytes. • WKUPTYP: Wakeup Signal Type 0: Writing a one to CR.LINWKUP will send a LIN 2.0 wakeup signal. 1: Writing a one to CR.LINWKUP will send a LIN 1.3 wakeup signal. • FSDIS: Frame Slot Mode Disable 0: The Frame Slot mode is enabled. 1: The Frame Slot mode is disabled. • DLM: Data Length Mode 0: The response data length is defined by DLC. 1: The response data length is defined by bits 4 and 5 of the Identifier (LINIR.IDCHR). • CHKTYP: Checksum Type 0: LIN 2.0 “Enhanced” checksum 1: LIN 1.3 “Classic” checksum • CHKDIS: Checksum Disable 0: Checksum is automatically computed and sent when master, and checked when slave. 1: Checksum is not computed and sent, nor checked. • PARDIS: Parity Disable 0: Identifier parity is automatically computed and sent when master, and checked when slave. 1: Identifier parity is not computed and sent, nor checked. • NACT: LIN Node Action 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – – – – – – PDCM 15 14 13 12 11 10 9 8 DLC 76543210 WKUPTYP FSDIS DLM CHKTYP CHKDIS PARDIS NACT Table 20-18. NACT Mode Description 0 0 PUBLISH: The USART transmits the response. 480 32142D–06/2013 ATUC64/128/256L3/4U 0 1 SUBSCRIBE: The USART receives the response. 1 0 IGNORE: The USART does not transmit and does not receive the response. 1 1 Reserved Table 20-18. 481 32142D–06/2013 ATUC64/128/256L3/4U 20.7.13 LIN Identifier Register Name: LINIR Access Type: Read-write or Read-only Offset: 0x58 Reset Value: 0x00000000 • IDCHR: Identifier Character If USART is in LIN master mode, the IDCHR field is read-write, and its value is the Identifier character to be transmitted. If USART is in LIN slave mode, the IDCHR field is read-only, and its value is the last received Identifier character. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 –––––––– 76543210 IDCHR 482 32142D–06/2013 ATUC64/128/256L3/4U 20.7.14 Write Protect Mode Register Register Name: WPMR Access Type: Read-write Offset: 0xE4 Reset Value: See Table 20-10 • WPKEY: Write Protect KEY Has to be written to 0x555341 (“USA” in ASCII) in order to successfully write WPEN. Always reads as zero. • WPEN: Write Protect Enable 0 = Write protection disabled. 1 = Write protection enabled. Protects the registers: • ”Mode Register” on page 466 • ”Baud Rate Generator Register” on page 476 • ”Receiver Time-out Register” on page 477 • ”Transmitter Timeguard Register” on page 478 31 30 29 28 27 26 25 24 WPKEY[23:16] 23 22 21 20 19 18 17 16 WPKEY[15:8] 15 14 13 12 11 10 9 8 WPKEY[7:0] 76543210 — — — — — — — WPEN 483 32142D–06/2013 ATUC64/128/256L3/4U 20.7.15 Write Protect Status Register Register Name: WPSR Access Type: Read-only Offset: 0xE8 Reset Value: See Table 20-10 • WPVSRC: Write Protect Violation Source If WPVS=1 this field indicates which write-protected register was unsuccessfully written to, either by address offset or code. • WPVS: Write Protect Violation Status 0= No write protect violation has occurred since the last WPSR read. 1= A write protect violation has occurred since the last WPSR read. Note: Reading WPSR automatically clears all fields. 31 30 29 28 27 26 25 24 ———————— 23 22 21 20 19 18 17 16 WPVSRC[15:8] 15 14 13 12 11 10 9 8 WPVSRC[7:0] 76543210 — — — — — — — WPVS 484 32142D–06/2013 ATUC64/128/256L3/4U 20.7.16 Version Register Name: VERSION Access Type: Read-only Offset: 0xFC Reset Value: - • MFN Reserved. No functionality associated. • VERSION Version of the module. No functionality associated. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – – – MFN 15 14 13 12 11 10 9 8 – – – – VERSION[11:8] 76543210 VERSION[7:0] 485 32142D–06/2013 ATUC64/128/256L3/4U 20.8 Module Configuration The specific configuration for each USART instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 20-19. USART Configuration Feature USART0 USART1 USART2 USART3 Receiver Time-out Counter Size (Size of the RTOR.TO field) 17 bit 17 bit 17 bit 17 bit DIV Value for divided CLK_USART 8 8 8 8 Table 20-20. USART Clocks Module Name Clock Name Description USART0 CLK_USART0 Clock for the USART0 bus interface USART1 CLK_USART1 Clock for the USART1 bus interface USART2 CLK_USART2 Clock for the USART2 bus interface USART3 CLK_USART3 Clock for the USART3 bus interface Table 20-21. Register Reset Values Register Reset Value VERSION 0x00000440 486 32142D–06/2013 ATUC64/128/256L3/4U 21. Serial Peripheral Interface (SPI) Rev: 2.1.1.3 21.1 Features • Compatible with an embedded 32-bit microcontroller • Supports communication with serial external devices – Four chip selects with external decoder support allow communication with up to 15 peripherals – Serial memories, such as DataFlash and 3-wire EEPROMs – Serial peripherals, such as ADCs, DACs, LCD controllers, CAN controllers and Sensors – External co-processors • Master or Slave Serial Peripheral Bus Interface – 4 - to 16-bit programmable data length per chip select – Programmable phase and polarity per chip select – Programmable transfer delays between consecutive transfers and between clock and data per chip select – Programmable delay between consecutive transfers – Selectable mode fault detection • Connection to Peripheral DMA Controller channel capabilities optimizes data transfers – One channel for the receiver, one channel for the transmitter – Next buffer support – Four character FIFO in reception 21.2 Overview The Serial Peripheral Interface (SPI) circuit is a synchronous serial data link that provides communication with external devices in Master or Slave mode. It also enables communication between processors if an external processor is connected to the system. The Serial Peripheral Interface is essentially a shift register that serially transmits data bits to other SPIs. During a data transfer, one SPI system acts as the “master”' which controls the data flow, while the other devices act as “slaves'' which have data shifted into and out by the master. Different CPUs can take turn being masters (Multiple Master Protocol opposite to Single Master Protocol where one CPU is always the master while all of the others are always slaves) and one master may simultaneously shift data into multiple slaves. However, only one slave may drive its output to write data back to the master at any given time. A slave device is selected when the master asserts its NSS signal. If multiple slave devices exist, the master generates a separate slave select signal for each slave (NPCS). The SPI system consists of two data lines and two control lines: • Master Out Slave In (MOSI): this data line supplies the output data from the master shifted into the input(s) of the slave(s). • Master In Slave Out (MISO): this data line supplies the output data from a slave to the input of the master. There may be no more than one slave transmitting data during any particular transfer. • Serial Clock (SPCK): this control line is driven by the master and regulates the flow of the data bits. The master may transmit data at a variety of baud rates; the SPCK line cycles once for each bit that is transmitted. • Slave Select (NSS): this control line allows slaves to be turned on and off by hardware. 487 32142D–06/2013 ATUC64/128/256L3/4U 21.3 Block Diagram Figure 21-1. SPI Block Diagram 21.4 Application Block Diagram Figure 21-2. Application Block Diagram: Single Master/Multiple Slave Implementation Spi Interface Interrupt Control Peripheral DMA Controller I/O Controller CLK_SPI Peripheral Bus SPI Interrupt SPCK NPCS3 NPCS2 NPCS1 NPCS0/NSS MOSI MISO Slave 0 Slave 2 Slave 1 SPCK NPCS3 NPCS2 NPCS1 NPCS0 MOSI MISO Spi Master SPCK NSS MOSI MISO SPCK NSS MOSI MISO SPCK NSS MOSI MISO NC 488 32142D–06/2013 ATUC64/128/256L3/4U 21.5 I/O Lines Description 21.6 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 21.6.1 I/O Lines The pins used for interfacing the compliant external devices may be multiplexed with I/O lines. The user must first configure the I/O Controller to assign the SPI pins to their peripheral functions. 21.6.2 Clocks The clock for the SPI bus interface (CLK_SPI) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the SPI before disabling the clock, to avoid freezing the SPI in an undefined state. 21.6.3 Interrupts The SPI interrupt request line is connected to the interrupt controller. Using the SPI interrupt requires the interrupt controller to be programmed first. 21.7 Functional Description 21.7.1 Modes of Operation The SPI operates in master mode or in slave mode. Operation in master mode is configured by writing a one to the Master/Slave Mode bit in the Mode Register (MR.MSTR). The pins NPCS0 to NPCS3 are all configured as outputs, the SPCK pin is driven, the MISO line is wired on the receiver input and the MOSI line driven as an output by the transmitter. If the MR.MSTR bit is written to zero, the SPI operates in slave mode. The MISO line is driven by the transmitter output, the MOSI line is wired on the receiver input, the SPCK pin is driven by the transmitter to synchronize the receiver. The NPCS0 pin becomes an input, and is used as a Slave Select signal (NSS). The pins NPCS1 to NPCS3 are not driven and can be used for other purposes. The data transfers are identically programmable for both modes of operations. The baud rate generator is activated only in master mode. Table 21-1. I/O Lines Description Pin Name Pin Description Type Master Slave MISO Master In Slave Out Input Output MOSI Master Out Slave In Output Input SPCK Serial Clock Output Input NPCS1-NPCS3 Peripheral Chip Selects Output Unused NPCS0/NSS Peripheral Chip Select/Slave Select Output Input 489 32142D–06/2013 ATUC64/128/256L3/4U 21.7.2 Data Transfer Four combinations of polarity and phase are available for data transfers. The clock polarity is configured with the Clock Polarity bit in the Chip Select Registers (CSRn.CPOL). The clock phase is configured with the Clock Phase bit in the CSRn registers (CSRn.NCPHA). These two bits determine the edges of the clock signal on which data is driven and sampled. Each of the two bits has two possible states, resulting in four possible combinations that are incompatible with one another. Thus, a master/slave pair must use the same parameter pair values to communicate. If multiple slaves are used and fixed in different configurations, the master must reconfigure itself each time it needs to communicate with a different slave. Table 21-2 on page 489 shows the four modes and corresponding parameter settings. Figure 21-3 on page 489 and Figure 21-4 on page 490 show examples of data transfers. Figure 21-3. SPI Transfer Format (NCPHA = 1, 8 bits per transfer) Table 21-2. SPI modes SPI Mode CPOL NCPHA 0 01 1 00 2 11 3 10 SPCK cycle (for reference) 1 4 2 3 5 8 6 7 SPCK (CPOL = 0) NSS (to slave) MISO (from slave) MOSI (from master) SPCK (CPOL = 1) MSB 6 4 5 LSB 3 2 1 MSB 6 5 4 3 2 1 LSB *** *** Not Defined, but normaly MSB of previous character received 490 32142D–06/2013 ATUC64/128/256L3/4U Figure 21-4. SPI Transfer Format (NCPHA = 0, 8 bits per transfer) 21.7.3 Master Mode Operations When configured in master mode, the SPI uses the internal programmable baud rate generator as clock source. It fully controls the data transfers to and from the slave(s) connected to the SPI bus. The SPI drives the chip select line to the slave and the serial clock signal (SPCK). The SPI features two holding registers, the Transmit Data Register (TDR) and the Receive Data Register (RDR), and a single Shift Register. The holding registers maintain the data flow at a constant rate. After enabling the SPI, a data transfer begins when the processor writes to the TDR register. The written data is immediately transferred in the Shift Register and transfer on the SPI bus starts. While the data in the Shift Register is shifted on the MOSI line, the MISO line is sampled and shifted in the Shift Register. Transmission cannot occur without reception. Before writing to the TDR, the Peripheral Chip Select field in TDR (TDR.PCS) must be written in order to select a slave. If new data is written to TDR during the transfer, it stays in it until the current transfer is completed. Then, the received data is transferred from the Shift Register to RDR, the data in TDR is loaded in the Shift Register and a new transfer starts. The transfer of a data written in TDR in the Shift Register is indicated by the Transmit Data Register Empty bit in the Status Register (SR.TDRE). When new data is written in TDR, this bit is cleared. The SR.TDRE bit is used to trigger the Transmit Peripheral DMA Controller channel. The end of transfer is indicated by the Transmission Registers Empty bit in the SR register (SR.TXEMPTY). If a transfer delay (CSRn.DLYBCT) is greater than zero for the last transfer, SR.TXEMPTY is set after the completion of said delay. The CLK_SPI can be switched off at this time. During reception, received data are transferred from the Shift Register to the reception FIFO. The FIFO can contain up to 4 characters (both Receive Data and Peripheral Chip Select fields). While a character of the FIFO is unread, the Receive Data Register Full bit in SR remains high (SR.RDRF). Characters are read through the RDR register. If the four characters stored in the FIFO are not read and if a new character is stored, this sets the Overrun Error Status bit in the SR register (SR.OVRES). The procedure to follow in such a case is described in Section 21.7.3.8. SPCK cycle (for reference) 1 4 2 3 5 8 6 7 SPCK (CPOL = 0) NSS (to slave) MISO (from slave) MOSI (from master) SPCK (CPOL = 1) MSB 6 4 5 LSB 3 2 1 6 5 4 3 2 1 LSB *** Not Defined, but normaly LSB of previous character transmitted *** MSB 491 32142D–06/2013 ATUC64/128/256L3/4U Figure 21-5 on page 491shows a block diagram of the SPI when operating in master mode. Figure 21-6 on page 492 shows a flow chart describing how transfers are handled. 21.7.3.1 Master mode block diagram Figure 21-5. Master Mode Block Diagram Baud Rate Generator RXFIFOEN 4 – Character FIFO Shift Register TDRE RXFIFOEN 4 – Character FIFO PS PCSDEC Current Peripheral MODF MODFDIS MSTR SCBR CSR0..3 CSR0..3 CPOL NCPHA BITS RDR RD RDRF OVRES TD TDR RDR CSAAT CSNAAT CSR0..3 PCS MR PCS TDR SPCK CLK_SPI MISO MOSI LSB MSB NPCS1 NPCS2 NPCS3 NPCS0 SPI Clock 0 1 0 1 0 1 NPCS0 492 32142D–06/2013 ATUC64/128/256L3/4U 21.7.3.2 Master mode flow diagram Figure 21-6. Master Mode Flow Diagram SPI Enable CSAAT ? PS ? 1 0 0 1 1 NPCS = TDR(PCS) NPCS = MR(PCS) Delay DLYBS Serializer = TDR(TD) TDRE = 1 Data Transfer RDR(RD) = Serializer RDRF = 1 TDRE ? NPCS = 0xF Delay DLYBCS Fixed peripheral Variable peripheral Delay DLYBCT 0 1 CSAAT ? 0 TDRE ? 1 0 PS ? 0 1 TDR(PCS) = NPCS ? no yes MR(PCS) = NPCS ? no NPCS = 0xF Delay DLYBCS NPCS = TDR(PCS) NPCS = 0xF Delay DLYBCS NPCS = MR(PCS), TDR(PCS) Fixed peripheral Variable peripheral - NPCS defines the current Chip Select - CSAAT, DLYBS, DLYBCT refer to the fields of the Chip Select Register corresponding to the Current Chip Select - When NPCS is 0xF, CSAAT is 0. 493 32142D–06/2013 ATUC64/128/256L3/4U 21.7.3.3 Clock generation The SPI Baud rate clock is generated by dividing the CLK_SPI , by a value between 1 and 255. This allows a maximum operating baud rate at up to CLK_SPI and a minimum operating baud rate of CLK_SPI divided by 255. Writing the Serial Clock Baud Rate field in the CSRn registers (CSRn.SCBR) to zero is forbidden. Triggering a transfer while CSRn.SCBR is zero can lead to unpredictable results. At reset, CSRn.SCBR is zero and the user has to configure it at a valid value before performing the first transfer. The divisor can be defined independently for each chip select, as it has to be configured in the CSRn.SCBR field. This allows the SPI to automatically adapt the baud rate for each interfaced peripheral without reprogramming. 21.7.3.4 Transfer delays Figure 21-7 on page 493 shows a chip select transfer change and consecutive transfers on the same chip select. Three delays can be configured to modify the transfer waveforms: • The delay between chip selects, programmable only once for all the chip selects by writing to the Delay Between Chip Selects field in the MR register (MR.DLYBCS). Allows insertion of a delay between release of one chip select and before assertion of a new one. • The delay before SPCK, independently programmable for each chip select by writing the Delay Before SPCK field in the CSRn registers (CSRn.DLYBS). Allows the start of SPCK to be delayed after the chip select has been asserted. • The delay between consecutive transfers, independently programmable for each chip select by writing the Delay Between Consecutive Transfers field in the CSRn registers (CSRn.DLYBCT). Allows insertion of a delay between two transfers occurring on the same chip select These delays allow the SPI to be adapted to the interfaced peripherals and their speed and bus release time. Figure 21-7. Programmable Delays DLYBCS DLYBS DLYBCT DLYBCT Chip Select 1 Chip Select 2 SPCK 494 32142D–06/2013 ATUC64/128/256L3/4U 21.7.3.5 Peripheral selection The serial peripherals are selected through the assertion of the NPCS0 to NPCS3 signals. By default, all the NPCS signals are high before and after each transfer. The peripheral selection can be performed in two different ways: • Fixed Peripheral Select: SPI exchanges data with only one peripheral • Variable Peripheral Select: Data can be exchanged with more than one peripheral Fixed Peripheral Select is activated by writing a zero to the Peripheral Select bit in MR (MR.PS). In this case, the current peripheral is defined by the MR.PCS field and the TDR.PCS field has no effect. Variable Peripheral Select is activated by writing a one to the MR.PS bit . The TDR.PCS field is used to select the current peripheral. This means that the peripheral selection can be defined for each new data. The Fixed Peripheral Selection allows buffer transfers with a single peripheral. Using the Peripheral DMA Controller is an optimal means, as the size of the data transfer between the memory and the SPI is either 4 bits or 16 bits. However, changing the peripheral selection requires the Mode Register to be reprogrammed. The Variable Peripheral Selection allows buffer transfers with multiple peripherals without reprogramming the MR register. Data written to TDR is 32-bits wide and defines the real data to be transmitted and the peripheral it is destined to. Using the Peripheral DMA Controller in this mode requires 32-bit wide buffers, with the data in the LSBs and the PCS and LASTXFER fields in the MSBs, however the SPI still controls the number of bits (8 to16) to be transferred through MISO and MOSI lines with the CSRn registers. This is not the optimal means in term of memory size for the buffers, but it provides a very effective means to exchange data with several peripherals without any intervention of the processor. 21.7.3.6 Peripheral chip select decoding The user can configure the SPI to operate with up to 15 peripherals by decoding the four Chip Select lines, NPCS0 to NPCS3 with an external logic. This can be enabled by writing a one to the Chip Select Decode bit in the MR register (MR.PCSDEC). When operating without decoding, the SPI makes sure that in any case only one chip select line is activated, i.e. driven low at a time. If two bits are defined low in a PCS field, only the lowest numbered chip select is driven low. When operating with decoding, the SPI directly outputs the value defined by the PCS field of either the MR register or the TDR register (depending on PS). As the SPI sets a default value of 0xF on the chip select lines (i.e. all chip select lines at one) when not processing any transfer, only 15 peripherals can be decoded. The SPI has only four Chip Select Registers, not 15. As a result, when decoding is activated, each chip select defines the characteristics of up to four peripherals. As an example, the CRS0 register defines the characteristics of the externally decoded peripherals 0 to 3, corresponding to the PCS values 0x0 to 0x3. Thus, the user has to make sure to connect compatible peripherals on the decoded chip select lines 0 to 3, 4 to 7, 8 to 11 and 12 to 14. 21.7.3.7 Peripheral deselection When operating normally, as soon as the transfer of the last data written in TDR is completed, the NPCS lines all rise. This might lead to runtime error if the processor is too long in responding 495 32142D–06/2013 ATUC64/128/256L3/4U to an interrupt, and thus might lead to difficulties for interfacing with some serial peripherals requiring the chip select line to remain active during a full set of transfers. To facilitate interfacing with such devices, the CSRn registers can be configured with the Chip Select Active After Transfer bit written to one (CSRn.CSAAT) . This allows the chip select lines to remain in their current state (low = active) until transfer to another peripheral is required. When the CSRn.CSAAT bit is written to qero, the NPCS does not rise in all cases between two transfers on the same peripheral. During a transfer on a Chip Select, the SR.TDRE bit rises as soon as the content of the TDR is transferred into the internal shifter. When this bit is detected the TDR can be reloaded. If this reload occurs before the end of the current transfer and if the next transfer is performed on the same chip select as the current transfer, the Chip Select is not de-asserted between the two transfers. This might lead to difficulties for interfacing with some serial peripherals requiring the chip select to be de-asserted after each transfer. To facilitate interfacing with such devices, the CSRn registers can be configured with the Chip Select Not Active After Transfer bit (CSRn.CSNAAT) written to one. This allows to de-assert systematically the chip select lines during a time DLYBCS. (The value of the CSRn.CSNAAT bit is taken into account only if the CSRn.CSAAT bit is written to zero for the same Chip Select). Figure 21-8 on page 496 shows different peripheral deselection cases and the effect of the CSRn.CSAAT and CSRn.CSNAAT bits. 21.7.3.8 FIFO management A FIFO has been implemented in Reception FIFO (both in master and in slave mode), in order to be able to store up to 4 characters without causing an overrun error. If an attempt is made to store a fifth character, an overrun error rises. If such an event occurs, the FIFO must be flushed. There are two ways to Flush the FIFO: • By performing four read accesses of the RDR (the data read must be ignored) • By writing a one to the Flush Fifo Command bit in the CR register (CR.FLUSHFIFO). After that, the SPI is able to receive new data. 496 32142D–06/2013 ATUC64/128/256L3/4U Figure 21-8. Peripheral Deselection Figure 21-8 on page 496 shows different peripheral deselection cases and the effect of the CSRn.CSAAT and CSRn.CSNAAT bits. 21.7.3.9 Mode fault detection The SPI is capable of detecting a mode fault when it is configured in master mode and NPCS0, MOSI, MISO, and SPCK are configured as open drain through the I/O Controller with either internal or external pullup resistors. If the I/O Controller does not have open-drain capability, mode fault detection must be disabled by writing a one to the Mode Fault Detection bit in the MR A NPCS[0..3] Write TDR TDRE NPCS[0..3] Write TDR TDRE NPCS[0..3] Write TDR TDRE DLYBCS PCS = A DLYBCS DLYBCT A PCS = B B DLYBCS PCS = A DLYBCS DLYBCT A PCS = B B DLYBCS DLYBCT PCS=A A DLYBCS DLYBCT A PCS = A A A DLYBCT A A CSAAT = 0 and CSNAAT = 0 DLYBCT A A CSAAT = 1 and CSNAAT= 0 / 1 A DLYBCS PCS = A DLYBCT A A CSAAT = 0 and CSNAAT = 1 NPCS[0..3] Write TDR TDRE PCS = A DLYBCT A A CSAAT = 0 and CSNAAT = 0 497 32142D–06/2013 ATUC64/128/256L3/4U register (MR.MODFDIS). In systems with open-drain I/O lines, a mode fault is detected when a low level is driven by an external master on the NPCS0/NSS signal. When a mode fault is detected, the Mode Fault Error bit in the SR (SR.MODF) is set until the SR is read and the SPI is automatically disabled until re-enabled by writing a one to the SPI Enable bit in the CR register (CR.SPIEN). By default, the mode fault detection circuitry is enabled. The user can disable mode fault detection by writing a one to the Mode Fault Detection bit in the MR register (MR.MODFDIS). 21.7.4 SPI Slave Mode When operating in slave mode, the SPI processes data bits on the clock provided on the SPI clock pin (SPCK). The SPI waits for NSS to go active before receiving the serial clock from an external master. When NSS falls, the clock is validated on the serializer, which processes the number of bits defined by the Bits Per Transfer field of the Chip Select Register 0 (CSR0.BITS). These bits are processed following a phase and a polarity defined respectively by the CSR0.NCPHA and CSR0.CPOL bits. Note that the BITS, CPOL, and NCPHA bits of the other Chip Select Registers have no effect when the SPI is configured in Slave Mode. The bits are shifted out on the MISO line and sampled on the MOSI line. When all the bits are processed, the received data is transferred in the Receive Data Register and the SR.RDRF bit rises. If the RDR register has not been read before new data is received, the SR.OVRES bit is set. Data is loaded in RDR even if this flag is set. The user has to read the SR register to clear the SR.OVRES bit. When a transfer starts, the data shifted out is the data present in the Shift Register. If no data has been written in the TDR register, the last data received is transferred. If no data has been received since the last reset, all bits are transmitted low, as the Shift Register resets to zero. When a first data is written in TDR, it is transferred immediately in the Shift Register and the SR.TDRE bit rises. If new data is written, it remains in TDR until a transfer occurs, i.e. NSS falls and there is a valid clock on the SPCK pin. When the transfer occurs, the last data written in TDR is transferred in the Shift Register and the SR.TDRE bit rises. This enables frequent updates of critical variables with single transfers. Then, a new data is loaded in the Shift Register from the TDR. In case no character is ready to be transmitted, i.e. no character has been written in TDR since the last load from TDR to the Shift Register, the Shift Register is not modified and the last received character is retransmitted. In this case the Underrun Error Status bit is set in SR (SR.UNDES). Figure 21-9 on page 498 shows a block diagram of the SPI when operating in slave mode. 498 32142D–06/2013 ATUC64/128/256L3/4U Figure 21-9. Slave Mode Functional Block Diagram Shift Register SPCK SPIENS LSB MSB NSS MOSI SPI Clock TDRE TDR TD RDRF OVRES CSR0 CPOL NCPHA BITS SPIEN SPIDIS MISO UNDES RDR RD 4 - Character FIFO 0 1 RXFIFOEN 499 32142D–06/2013 ATUC64/128/256L3/4U 21.8 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 21-3. SPI Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Write-only 0x00000000 0x04 Mode Register MR Read/Write 0x00000000 0x08 Receive Data Register RDR Read-only 0x00000000 0x0C Transmit Data Register TDR Write-only 0x00000000 0x10 Status Register SR Read-only 0x00000000 0x14 Interrupt Enable Register IER Write-only 0x00000000 0x18 Interrupt Disable Register IDR Write-only 0x00000000 0x1C Interrupt Mask Register IMR Read-only 0x00000000 0x30 Chip Select Register 0 CSR0 Read/Write 0x00000000 0x34 Chip Select Register 1 CSR1 Read/Write 0x00000000 0x38 Chip Select Register 2 CSR2 Read/Write 0x00000000 0x3C Chip Select Register 3 CSR3 Read/Write 0x00000000 0x E4 Write Protection Control Register WPCR Read/Write 0X00000000 0xE8 Write Protection Status Register WPSR Read-only 0x00000000 0xF8 Features Register FEATURES Read-only - (1) 0xFC Version Register VERSION Read-only - (1) 500 32142D–06/2013 ATUC64/128/256L3/4U 21.8.1 Control Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 • LASTXFER: Last Transfer 1: The current NPCS will be deasserted after the character written in TD has been transferred. When CSRn.CSAAT is one, this allows to close the communication with the current serial peripheral by raising the corresponding NPCS line as soon as TD transfer has completed. 0: Writing a zero to this bit has no effect. • FLUSHFIFO: Flush Fifo Command 1: If The FIFO Mode is enabled (MR.FIFOEN written to one) and if an overrun error has been detected, this command allows to empty the FIFO. 0: Writing a zero to this bit has no effect. • SWRST: SPI Software Reset 1: Writing a one to this bit will reset the SPI. A software-triggered hardware reset of the SPI interface is performed. The SPI is in slave mode after software reset. Peripheral DMA Controller channels are not affected by software reset. 0: Writing a zero to this bit has no effect. • SPIDIS: SPI Disable 1: Writing a one to this bit will disable the SPI. As soon as SPIDIS is written to one, the SPI finishes its transfer, all pins are set in input mode and no data is received or transmitted. If a transfer is in progress, the transfer is finished before the SPI is disabled. If both SPIEN and SPIDIS are equal to one when the CR register is written, the SPI is disabled. 0: Writing a zero to this bit has no effect. • SPIEN: SPI Enable 1: Writing a one to this bit will enable the SPI to transfer and receive data. 0: Writing a zero to this bit has no effect. 31 30 29 28 27 26 25 24 - - - - - - - LASTXFER 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - FLUSHFIFO 76543210 SWRST - - - - - SPIDIS SPIEN 501 32142D–06/2013 ATUC64/128/256L3/4U 21.8.2 Mode Register Name: MR Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • DLYBCS: Delay Between Chip Selects This field defines the delay from NPCS inactive to the activation of another NPCS. The DLYBCS time guarantees nonoverlapping chip selects and solves bus contentions in case of peripherals having long data float times. If DLYBCS is less than or equal to six, six CLK_SPI periods will be inserted by default. Otherwise, the following equation determines the delay: • PCS: Peripheral Chip Select This field is only used if Fixed Peripheral Select is active (PS = 0). If PCSDEC = 0: PCS = xxx0NPCS[3:0] = 1110 PCS = xx01NPCS[3:0] = 1101 PCS = x011NPCS[3:0] = 1011 PCS = 0111NPCS[3:0] = 0111 PCS = 1111forbidden (no peripheral is selected) (x = don’t care) If PCSDEC = 1: NPCS[3:0] output signals = PCS. • LLB: Local Loopback Enable 1: Local loopback path enabled. LLB controls the local loopback on the data serializer for testing in master mode only (MISO is internally connected on MOSI). 0: Local loopback path disabled. • RXFIFOEN: FIFO in Reception Enable 1: The FIFO is used in reception (four characters can be stored in the SPI). 31 30 29 28 27 26 25 24 DLYBCS 23 22 21 20 19 18 17 16 - - - - PCS 15 14 13 12 11 10 9 8 -------- 76543210 LLB RXFIFOEN - MODFDIS - PCSDEC PS MSTR Delay Between Chip Selects DLYBCS CLKSPI = ----------------------- 502 32142D–06/2013 ATUC64/128/256L3/4U 0: The FIFO is not used in reception (only one character can be stored in the SPI). • MODFDIS: Mode Fault Detection 1: Mode fault detection is disabled. If the I/O controller does not have open-drain capability, mode fault detection must be disabled for proper operation of the SPI. 0: Mode fault detection is enabled. • PCSDEC: Chip Select Decode 0: The chip selects are directly connected to a peripheral device. 1: The four chip select lines are connected to a 4- to 16-bit decoder. When PCSDEC equals one, up to 15 Chip Select signals can be generated with the four lines using an external 4- to 16-bit decoder. The CSRn registers define the characteristics of the 15 chip selects according to the following rules: CSR0 defines peripheral chip select signals 0 to 3. CSR1 defines peripheral chip select signals 4 to 7. CSR2 defines peripheral chip select signals 8 to 11. CSR3 defines peripheral chip select signals 12 to 14. • PS: Peripheral Select 1: Variable Peripheral Select. 0: Fixed Peripheral Select. • MSTR: Master/Slave Mode 1: SPI is in master mode. 0: SPI is in slave mode. 503 32142D–06/2013 ATUC64/128/256L3/4U 21.8.3 Receive Data Register Name: RDR Access Type: Read-only Offset: 0x08 Reset Value: 0x00000000 • RD: Receive Data Data received by the SPI Interface is stored in this register right-justified. Unused bits read zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 RD[15:8] 76543210 RD[7:0] 504 32142D–06/2013 ATUC64/128/256L3/4U 21.8.4 Transmit Data Register Name: TDR Access Type: Write-only Offset: 0x0C Reset Value: 0x00000000 • LASTXFER: Last Transfer 1: The current NPCS will be deasserted after the character written in TD has been transferred. When CSRn.CSAAT is one, this allows to close the communication with the current serial peripheral by raising the corresponding NPCS line as soon as TD transfer has completed. 0: Writing a zero to this bit has no effect. This field is only used if Variable Peripheral Select is active (MR.PS = 1). • PCS: Peripheral Chip Select If PCSDEC = 0: PCS = xxx0NPCS[3:0] = 1110 PCS = xx01NPCS[3:0] = 1101 PCS = x011NPCS[3:0] = 1011 PCS = 0111NPCS[3:0] = 0111 PCS = 1111forbidden (no peripheral is selected) (x = don’t care) If PCSDEC = 1: NPCS[3:0] output signals = PCS This field is only used if Variable Peripheral Select is active (MR.PS = 1). • TD: Transmit Data Data to be transmitted by the SPI Interface is stored in this register. Information to be transmitted must be written to the TDR register in a right-justified format. 31 30 29 28 27 26 25 24 - - - - - - - LASTXFER 23 22 21 20 19 18 17 16 - - - - PCS 15 14 13 12 11 10 9 8 TD[15:8] 76543210 TD[7:0] 505 32142D–06/2013 ATUC64/128/256L3/4U 21.8.5 Status Register Name: SR Access Type: Read-only Offset: 0x10 Reset Value: 0x00000000 • SPIENS: SPI Enable Status 1: This bit is set when the SPI is enabled. 0: This bit is cleared when the SPI is disabled. • UNDES: Underrun Error Status (Slave Mode Only) 1: This bit is set when a transfer begins whereas no data has been loaded in the TDR register. 0: This bit is cleared when the SR register is read. • TXEMPTY: Transmission Registers Empty 1: This bit is set when TDR and internal shifter are empty. If a transfer delay has been defined, TXEMPTY is set after the completion of such delay. 0: This bit is cleared as soon as data is written in TDR. • NSSR: NSS Rising 1: A rising edge occurred on NSS pin since last read. 0: This bit is cleared when the SR register is read. • OVRES: Overrun Error Status 1: This bit is set when an overrun has occurred. An overrun occurs when RDR is loaded at least twice from the serializer since the last read of the RDR. 0: This bit is cleared when the SR register is read. • MODF: Mode Fault Error 1: This bit is set when a Mode Fault occurred. 0: This bit is cleared when the SR register is read. • TDRE: Transmit Data Register Empty 1: This bit is set when the last data written in the TDR register has been transferred to the serializer. 0: This bit is cleared when data has been written to TDR and not yet transferred to the serializer. TDRE equals zero when the SPI is disabled or at reset. The SPI enable command sets this bit to one. • RDRF: Receive Data Register Full 1: Data has been received and the received data has been transferred from the serializer to RDR since the last read of RDR. 0: No data has been received since the last read of RDR 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - SPIENS 15 14 13 12 11 10 9 8 - - - - - UNDES TXEMPTY NSSR 76543210 - - - - OVRES MODF TDRE RDRF 506 32142D–06/2013 ATUC64/128/256L3/4U 21.8.6 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - UNDES TXEMPTY NSSR 76543210 - - - - OVRES MODF TDRE RDRF 507 32142D–06/2013 ATUC64/128/256L3/4U 21.8.7 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - UNDES TXEMPTY NSSR 76543210 - - - - OVRES MODF TDRE RDRF 508 32142D–06/2013 ATUC64/128/256L3/4U 21.8.8 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - UNDES TXEMPTY NSSR 76543210 - - - - OVRES MODF TDRE RDRF 509 32142D–06/2013 ATUC64/128/256L3/4U 21.8.9 Chip Select Register 0 Name: CSR0 Access Type: Read/Write Offset: 0x30 Reset Value: 0x00000000 • DLYBCT: Delay Between Consecutive Transfers This field defines the delay between two consecutive transfers with the same peripheral without removing the chip select. The delay is always inserted after each transfer and before removing the chip select if needed. When DLYBCT equals zero, no delay between consecutive transfers is inserted and the clock keeps its duty cycle over the character transfers. Otherwise, the following equation determines the delay: • DLYBS: Delay Before SPCK This field defines the delay from NPCS valid to the first valid SPCK transition. When DLYBS equals zero, the NPCS valid to SPCK transition is 1/2 the SPCK clock period. Otherwise, the following equations determine the delay: • SCBR: Serial Clock Baud Rate In Master Mode, the SPI Interface uses a modulus counter to derive the SPCK baud rate from the CLK_SPI. The Baud rate is selected by writing a value from 1 to 255 in the SCBR field. The following equations determine the SPCK baud rate: Writing the SCBR field to zero is forbidden. Triggering a transfer while SCBR is zero can lead to unpredictable results. At reset, SCBR is zero and the user has to write it to a valid value before performing the first transfer. If a clock divider (SCBRn) field is set to one and the other SCBR fields differ from one, access on CSn is correct but no correct access will be possible on other CS. 31 30 29 28 27 26 25 24 DLYBCT 23 22 21 20 19 18 17 16 DLYBS 15 14 13 12 11 10 9 8 SCBR 76543210 BITS CSAAT CSNAAT NCPHA CPOL Delay Between Consecutive Transfers 32  DLYBCT CLKSPI = ------------------------------------ Delay Before SPCK DLYBS CLKSPI = --------------------- SPCK Baudrate CLKSPI SCBR = --------------------- 510 32142D–06/2013 ATUC64/128/256L3/4U • BITS: Bits Per Transfer The BITS field determines the number of data bits transferred. Reserved values should not be used. • CSAAT: Chip Select Active After Transfer 1: The Peripheral Chip Select does not rise after the last transfer is achieved. It remains active until a new transfer is requested on a different chip select. 0: The Peripheral Chip Select Line rises as soon as the last transfer is achieved. • CSNAAT: Chip Select Not Active After Transfer (Ignored if CSAAT = 1) 0: The Peripheral Chip Select does not rise between two transfers if the TDR is reloaded before the end of the first transfer and if the two transfers occur on the same Chip Select. 1: The Peripheral Chip Select rises systematically between each transfer performed on the same slave for a minimal duration of: (if DLYBCT field is different from 0) (if DLYBCT field equals 0) • NCPHA: Clock Phase 1: Data is captured after the leading (inactive-to-active) edge of SPCK and changed on the trailing (active-to-inactive) edge of SPCK. 0: Data is changed on the leading (inactive-to-active) edge of SPCK and captured after the trailing (active-to-inactive) edge of SPCK. NCPHA determines which edge of SPCK causes data to change and which edge causes data to be captured. NCPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. • CPOL: Clock Polarity 1: The inactive state value of SPCK is logic level one. 0: The inactive state value of SPCK is logic level zero. BITS Bits Per Transfer 0000 8 0001 9 0010 10 0011 11 0100 12 0101 13 0110 14 0111 15 1000 16 1001 4 1010 5 1011 6 1100 7 1101 Reserved 1110 Reserved 1111 Reserved DLYBCS CLKSPI ----------------------- DLYBCS + 1 CLKSPI -------------------------------- 511 32142D–06/2013 ATUC64/128/256L3/4U CPOL is used to determine the inactive state value of the serial clock (SPCK). It is used with NCPHA to produce the required clock/data relationship between master and slave devices. 512 32142D–06/2013 ATUC64/128/256L3/4U 21.8.10 Chip Select Register 1 Name: CSR1 Access Type: Read/Write Offset: 0x34 Reset Value: 0x00000000 • DLYBCT: Delay Between Consecutive Transfers This field defines the delay between two consecutive transfers with the same peripheral without removing the chip select. The delay is always inserted after each transfer and before removing the chip select if needed. When DLYBCT equals zero, no delay between consecutive transfers is inserted and the clock keeps its duty cycle over the character transfers. Otherwise, the following equation determines the delay: • DLYBS: Delay Before SPCK This field defines the delay from NPCS valid to the first valid SPCK transition. When DLYBS equals zero, the NPCS valid to SPCK transition is 1/2 the SPCK clock period. Otherwise, the following equations determine the delay: • SCBR: Serial Clock Baud Rate In Master Mode, the SPI Interface uses a modulus counter to derive the SPCK baud rate from the CLK_SPI. The Baud rate is selected by writing a value from 1 to 255 in the SCBR field. The following equations determine the SPCK baud rate: Writing the SCBR field to zero is forbidden. Triggering a transfer while SCBR is zero can lead to unpredictable results. At reset, SCBR is zero and the user has to write it to a valid value before performing the first transfer. If a clock divider (SCBRn) field is set to one and the other SCBR fields differ from one, access on CSn is correct but no correct access will be possible on other CS. 31 30 29 28 27 26 25 24 DLYBCT 23 22 21 20 19 18 17 16 DLYBS 15 14 13 12 11 10 9 8 SCBR 76543210 BITS CSAAT CSNAAT NCPHA CPOL Delay Between Consecutive Transfers 32  DLYBCT CLKSPI = ------------------------------------ Delay Before SPCK DLYBS CLKSPI = --------------------- SPCK Baudrate CLKSPI SCBR = --------------------- 513 32142D–06/2013 ATUC64/128/256L3/4U • BITS: Bits Per Transfer The BITS field determines the number of data bits transferred. Reserved values should not be used. • CSAAT: Chip Select Active After Transfer 1: The Peripheral Chip Select does not rise after the last transfer is achieved. It remains active until a new transfer is requested on a different chip select. 0: The Peripheral Chip Select Line rises as soon as the last transfer is achieved. • CSNAAT: Chip Select Not Active After Transfer (Ignored if CSAAT = 1) 0: The Peripheral Chip Select does not rise between two transfers if the TDR is reloaded before the end of the first transfer and if the two transfers occur on the same Chip Select. 1: The Peripheral Chip Select rises systematically between each transfer performed on the same slave for a minimal duration of: (if DLYBCT field is different from 0) (if DLYBCT field equals 0) • NCPHA: Clock Phase 1: Data is captured after the leading (inactive-to-active) edge of SPCK and changed on the trailing (active-to-inactive) edge of SPCK. 0: Data is changed on the leading (inactive-to-active) edge of SPCK and captured after the trailing (active-to-inactive) edge of SPCK. NCPHA determines which edge of SPCK causes data to change and which edge causes data to be captured. NCPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. • CPOL: Clock Polarity 1: The inactive state value of SPCK is logic level one. 0: The inactive state value of SPCK is logic level zero. BITS Bits Per Transfer 0000 8 0001 9 0010 10 0011 11 0100 12 0101 13 0110 14 0111 15 1000 16 1001 4 1010 5 1011 6 1100 7 1101 Reserved 1110 Reserved 1111 Reserved DLYBCS CLKSPI ----------------------- DLYBCS + 1 CLKSPI -------------------------------- 514 32142D–06/2013 ATUC64/128/256L3/4U CPOL is used to determine the inactive state value of the serial clock (SPCK). It is used with NCPHA to produce the required clock/data relationship between master and slave devices. 515 32142D–06/2013 ATUC64/128/256L3/4U 21.8.11 Chip Select Register 2 Name: CSR2 Access Type: Read/Write Offset: 0x38 Reset Value: 0x00000000 • DLYBCT: Delay Between Consecutive Transfers This field defines the delay between two consecutive transfers with the same peripheral without removing the chip select. The delay is always inserted after each transfer and before removing the chip select if needed. When DLYBCT equals zero, no delay between consecutive transfers is inserted and the clock keeps its duty cycle over the character transfers. Otherwise, the following equation determines the delay: • DLYBS: Delay Before SPCK This field defines the delay from NPCS valid to the first valid SPCK transition. When DLYBS equals zero, the NPCS valid to SPCK transition is 1/2 the SPCK clock period. Otherwise, the following equations determine the delay: • SCBR: Serial Clock Baud Rate In Master Mode, the SPI Interface uses a modulus counter to derive the SPCK baud rate from the CLK_SPI. The Baud rate is selected by writing a value from 1 to 255 in the SCBR field. The following equations determine the SPCK baud rate: Writing the SCBR field to zero is forbidden. Triggering a transfer while SCBR is zero can lead to unpredictable results. At reset, SCBR is zero and the user has to write it to a valid value before performing the first transfer. If a clock divider (SCBRn) field is set to one and the other SCBR fields differ from one, access on CSn is correct but no correct access will be possible on other CS. 31 30 29 28 27 26 25 24 DLYBCT 23 22 21 20 19 18 17 16 DLYBS 15 14 13 12 11 10 9 8 SCBR 76543210 BITS CSAAT CSNAAT NCPHA CPOL Delay Between Consecutive Transfers 32  DLYBCT CLKSPI = ------------------------------------ Delay Before SPCK DLYBS CLKSPI = --------------------- SPCK Baudrate CLKSPI SCBR = --------------------- 516 32142D–06/2013 ATUC64/128/256L3/4U • BITS: Bits Per Transfer The BITS field determines the number of data bits transferred. Reserved values should not be used. • CSAAT: Chip Select Active After Transfer 1: The Peripheral Chip Select does not rise after the last transfer is achieved. It remains active until a new transfer is requested on a different chip select. 0: The Peripheral Chip Select Line rises as soon as the last transfer is achieved. • CSNAAT: Chip Select Not Active After Transfer (Ignored if CSAAT = 1) 0: The Peripheral Chip Select does not rise between two transfers if the TDR is reloaded before the end of the first transfer and if the two transfers occur on the same Chip Select. 1: The Peripheral Chip Select rises systematically between each transfer performed on the same slave for a minimal duration of: (if DLYBCT field is different from 0) (if DLYBCT field equals 0) • NCPHA: Clock Phase 1: Data is captured after the leading (inactive-to-active) edge of SPCK and changed on the trailing (active-to-inactive) edge of SPCK. 0: Data is changed on the leading (inactive-to-active) edge of SPCK and captured after the trailing (active-to-inactive) edge of SPCK. NCPHA determines which edge of SPCK causes data to change and which edge causes data to be captured. NCPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. • CPOL: Clock Polarity 1: The inactive state value of SPCK is logic level one. 0: The inactive state value of SPCK is logic level zero. BITS Bits Per Transfer 0000 8 0001 9 0010 10 0011 11 0100 12 0101 13 0110 14 0111 15 1000 16 1001 4 1010 5 1011 6 1100 7 1101 Reserved 1110 Reserved 1111 Reserved DLYBCS CLKSPI ----------------------- DLYBCS + 1 CLKSPI -------------------------------- 517 32142D–06/2013 ATUC64/128/256L3/4U CPOL is used to determine the inactive state value of the serial clock (SPCK). It is used with NCPHA to produce the required clock/data relationship between master and slave devices. 518 32142D–06/2013 ATUC64/128/256L3/4U 21.8.12 Chip Select Register 3 Name: CSR3 Access Type: Read/Write Offset: 0x3C Reset Value: 0x00000000 • DLYBCT: Delay Between Consecutive Transfers This field defines the delay between two consecutive transfers with the same peripheral without removing the chip select. The delay is always inserted after each transfer and before removing the chip select if needed. When DLYBCT equals zero, no delay between consecutive transfers is inserted and the clock keeps its duty cycle over the character transfers. Otherwise, the following equation determines the delay: • DLYBS: Delay Before SPCK This field defines the delay from NPCS valid to the first valid SPCK transition. When DLYBS equals zero, the NPCS valid to SPCK transition is 1/2 the SPCK clock period. Otherwise, the following equations determine the delay: • SCBR: Serial Clock Baud Rate In Master Mode, the SPI Interface uses a modulus counter to derive the SPCK baud rate from the CLK_SPI. The Baud rate is selected by writing a value from 1 to 255 in the SCBR field. The following equations determine the SPCK baud rate: Writing the SCBR field to zero is forbidden. Triggering a transfer while SCBR is zero can lead to unpredictable results. At reset, SCBR is zero and the user has to write it to a valid value before performing the first transfer. If a clock divider (SCBRn) field is set to one and the other SCBR fields differ from one, access on CSn is correct but no correct access will be possible on other CS. 31 30 29 28 27 26 25 24 DLYBCT 23 22 21 20 19 18 17 16 DLYBS 15 14 13 12 11 10 9 8 SCBR 76543210 BITS CSAAT CSNAAT NCPHA CPOL Delay Between Consecutive Transfers 32  DLYBCT CLKSPI = ------------------------------------ Delay Before SPCK DLYBS CLKSPI = --------------------- SPCK Baudrate CLKSPI SCBR = --------------------- 519 32142D–06/2013 ATUC64/128/256L3/4U • BITS: Bits Per Transfer The BITS field determines the number of data bits transferred. Reserved values should not be used. • CSAAT: Chip Select Active After Transfer 1: The Peripheral Chip Select does not rise after the last transfer is achieved. It remains active until a new transfer is requested on a different chip select. 0: The Peripheral Chip Select Line rises as soon as the last transfer is achieved. • CSNAAT: Chip Select Not Active After Transfer (Ignored if CSAAT = 1) 0: The Peripheral Chip Select does not rise between two transfers if the TDR is reloaded before the end of the first transfer and if the two transfers occur on the same Chip Select. 1: The Peripheral Chip Select rises systematically between each transfer performed on the same slave for a minimal duration of: (if DLYBCT field is different from 0) (if DLYBCT field equals 0) • NCPHA: Clock Phase 1: Data is captured after the leading (inactive-to-active) edge of SPCK and changed on the trailing (active-to-inactive) edge of SPCK. 0: Data is changed on the leading (inactive-to-active) edge of SPCK and captured after the trailing (active-to-inactive) edge of SPCK. NCPHA determines which edge of SPCK causes data to change and which edge causes data to be captured. NCPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. • CPOL: Clock Polarity 1: The inactive state value of SPCK is logic level one. 0: The inactive state value of SPCK is logic level zero. BITS Bits Per Transfer 0000 8 0001 9 0010 10 0011 11 0100 12 0101 13 0110 14 0111 15 1000 16 1001 4 1010 5 1011 6 1100 7 1101 Reserved 1110 Reserved 1111 Reserved DLYBCS CLKSPI ----------------------- DLYBCS + 1 CLKSPI -------------------------------- 520 32142D–06/2013 ATUC64/128/256L3/4U CPOL is used to determine the inactive state value of the serial clock (SPCK). It is used with NCPHA to produce the required clock/data relationship between master and slave devices. 521 32142D–06/2013 ATUC64/128/256L3/4U 21.8.13 Write Protection Control Register Register Name: WPCR Access Type: Read-write Offset: 0xE4 Reset Value: 0x00000000 • SPIWPKEY: SPI Write Protection Key Password If a value is written in SPIWPEN, the value is taken into account only if SPIWPKEY is written with “SPI” (SPI written in ASCII Code, i.e. 0x535049 in hexadecimal). • SPIWPEN: SPI Write Protection Enable 1: The Write Protection is Enabled 0: The Write Protection is Disabled 31 30 29 28 27 26 25 24 SPIWPKEY[23:16] 23 22 21 20 19 18 17 16 SPIWPKEY[15:8] 15 14 13 12 11 10 9 8 SPIWPKEY[7:0] 76543210 - - - - - - - SPIWPEN 522 32142D–06/2013 ATUC64/128/256L3/4U 21.8.14 Write Protection Status Register Register Name: WPSR Access Type: Read-only Offset: 0xE8 Reset Value: 0x00000000 • SPIWPVSRC: SPI Write Protection Violation Source This Field indicates the Peripheral Bus Offset of the register concerned by the violation (MR or CSRx) • SPIWPVS: SPI Write Protection Violation Status 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SPIWPVSRC 76543210 - - - - - SPIWPVS SPIWPVS value Violation Type 1 The Write Protection has blocked a Write access to a protected register (since the last read). 2 Software Reset has been performed while Write Protection was enabled (since the last read or since the last write access on MR, IER, IDR or CSRx). 3 Both Write Protection violation and software reset with Write Protection enabled have occurred since the last read. 4 Write accesses have been detected on MR (while a chip select was active) or on CSRi (while the Chip Select “i” was active) since the last read. 5 The Write Protection has blocked a Write access to a protected register and write accesses have been detected on MR (while a chip select was active) or on CSRi (while the Chip Select “i” was active) since the last read. 6 Software Reset has been performed while Write Protection was enabled (since the last read or since the last write access on MR, IER, IDR or CSRx) and some write accesses have been detected on MR (while a chip select was active) or on CSRi (while the Chip Select “i” was active) since the last read. 7 - The Write Protection has blocked a Write access to a protected register. and - Software Reset has been performed while Write Protection was enabled. and - Write accesses have been detected on MR (while a chip select was active) or on CSRi (while the Chip Select “i” was active) since the last read. 523 32142D–06/2013 ATUC64/128/256L3/4U 21.8.15 Features Register Register Name: FEATURES Access Type: Read-only Offset: 0xF8 Reset Value: – • SWIMPL: Spurious Write Protection Implemented 0: Spurious write protection is not implemented. 1: Spurious write protection is implemented. • FIFORIMPL: FIFO in Reception Implemented 0: FIFO in reception is not implemented. 1: FIFO in reception is implemented. • BRPBHSB: Bridge Type is PB to HSB 0: Bridge type is not PB to HSB. 1: Bridge type is PB to HSB. • CSNAATIMPL: CSNAAT Features Implemented 0: CSNAAT (Chip select not active after transfer) features are not implemented. 1: CSNAAT features are implemented. • EXTDEC: External Decoder True 0: External decoder capability is not implemented. 1: External decoder capability is implemented. • LENNCONF: Character Length if not Configurable If the character length is not configurable, this field specifies the fixed character length. • LENCONF: Character Length Configurable 0: The character length is not configurable. 1: The character length is configurable. • PHZNCONF: Phase is Zero if Phase not Configurable 0: If phase is not configurable, phase is non-zero. 1: If phase is not configurable, phase is zero. • PHCONF: Phase Configurable 0: Phase is not configurable. 1: Phase is configurable. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - SWIMPL FIFORIMPL BRPBHSB CSNAATIMPL EXTDEC 15 14 13 12 11 10 9 8 LENNCONF LENCONF 76543210 PHZNCONF PHCONF PPNCONF PCONF NCS 524 32142D–06/2013 ATUC64/128/256L3/4U • PPNCONF: Polarity Positive if Polarity not Configurable 0: If polarity is not configurable, polarity is negative. 1: If polarity is not configurable, polarity is positive. • PCONF: Polarity Configurable 0: Polarity is not configurable. 1: Polarity is configurable. • NCS: Number of Chip Selects This field indicates the number of chip selects implemented. 525 32142D–06/2013 ATUC64/128/256L3/4U 21.8.16 Version Register Register Name: VERSION Access Type: Read-only Offset: 0xFC Reset Value: – • MFN Reserved. No functionality associated. • VERSION Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - MFN 15 14 13 12 11 10 9 8 VERSION[11:8] 76543210 VERSION[7:0] 526 32142D–06/2013 ATUC64/128/256L3/4U 21.9 Module Configuration The specific configuration for each SPI instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 21-4. SPI Clock Name Module Name Clock Name Description SPI CLK_SPI Clock for the SPI bus interface Table 21-5. Register Reset Value FEATURES 0x001F0154 VERSION 0x00000211 527 32142D–06/2013 ATUC64/128/256L3/4U 22. Two-wire Master Interface (TWIM) Rev.: 1.1.0.1 22.1 Features • Compatible with I²C standard – Multi-master support – Transfer speeds of 100 and 400 kbit/s – 7- and 10-bit and General Call addressing • Compatible with SMBus standard – Hardware Packet Error Checking (CRC) generation and verification with ACK control – SMBus ALERT interface – 25 ms clock low timeout delay – 10 ms master cumulative clock low extend time – 25 ms slave cumulative clock low extend time • Compatible with PMBus • Compatible with Atmel Two-wire Interface Serial Memories • DMA interface for reducing CPU load • Arbitrary transfer lengths, including 0 data bytes • Optional clock stretching if transmit or receive buffers not ready for data transfer 22.2 Overview The Atmel Two-wire Master Interface (TWIM) interconnects components on a unique two-wire bus, made up of one clock line and one data line with speeds of up to 400 kbit/s, based on a byte-oriented transfer format. It can be used with any Atmel Two-wire Interface bus serial EEPROM and I²C compatible device such as a real time clock (RTC), dot matrix/graphic LCD controller, and temperature sensor, to name a few. The TWIM is always a bus master and can transfer sequential or single bytes. Multiple master capability is supported. Arbitration of the bus is performed internally and relinquishes the bus automatically if the bus arbitration is lost. A configurable baud rate generator permits the output data rate to be adapted to a wide range of core clock frequencies.Table 22-1 lists the compatibility level of the Atmel Two-wire Interface in Master Mode and a full I²C compatible device. Note: 1. START + b000000001 + Ack + Sr Table 22-1. Atmel TWIM Compatibility with I²C Standard I²C Standard Atmel TWIM Standard-mode (100 kbit/s) Supported Fast-mode (400 kbit/s) Supported Fast-mode Plus (1 Mbit/s) Supported 7- or 10-bits Slave Addressing Supported START BYTE(1) Not Supported Repeated Start (Sr) Condition Supported ACK and NACK Management Supported Slope Control and Input Filtering (Fast mode) Supported Clock Stretching Supported 528 32142D–06/2013 ATUC64/128/256L3/4U Table 22-2 lists the compatibility level of the Atmel Two-wire Master Interface and a full SMBus compatible master. 22.3 List of Abbreviations 22.4 Block Diagram Figure 22-1. Block Diagram Table 22-2. Atmel TWIM Compatibility with SMBus Standard SMBus Standard Atmel TWIM Bus Timeouts Supported Address Resolution Protocol Supported Alert Supported Host Functionality Supported Packet Error Checking Supported Table 22-3. Abbreviations Abbreviation Description TWI Two-wire Interface A Acknowledge NA Non Acknowledge P Stop S Start Sr Repeated Start SADR Slave Address ADR Any address except SADR R Read W Write Peripheral Bus Bridge Two-wire Interface I/O Controller TWCK TWD INTC TWI Interrupt Power Manager CLK_TWIM TWALM 529 32142D–06/2013 ATUC64/128/256L3/4U 22.5 Application Block Diagram Figure 22-2. Application Block Diagram 22.6 I/O Lines Description 22.7 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 22.7.1 I/O Lines TWD and TWCK are bidirectional lines, connected to a positive supply voltage via a current source or pull-up resistor (see Figure 22-4 on page 531). When the bus is free, both lines are high. The output stages of devices connected to the bus must have an open-drain or open-collector to perform the wired-AND function. TWALM is used to implement the optional SMBus SMBALERT signal. The TWALM, TWD, and TWCK pins may be multiplexed with I/O Controller lines. To enable the TWIM, the user must perform the following steps: • Program the I/O Controller to: – Dedicate TWD, TWCK, and optionally TWALM as peripheral lines. – Define TWD, TWCK, and optionally TWALM as open-drain. 22.7.2 Power Management If the CPU enters a sleep mode that disables clocks used by the TWIM, the TWIM will stop functioning and resume operation after the system wakes up from sleep mode. TWI Master TWD TWCK Atmel TWI serial EEPROM I 2 C RTC I 2 C LCD controller I 2 C temp sensor Slave 2 Slave 3 Slave 4 VDD Rp: pull-up value as given by the I2C Standard TWALM Slave 1 Rp Rp Rp Table 22-4. I/O Lines Description Pin Name Pin Description Type TWD Two-wire Serial Data Input/Output TWCK Two-wire Serial Clock Input/Output TWALM SMBus SMBALERT Input/Output 530 32142D–06/2013 ATUC64/128/256L3/4U 22.7.3 Clocks The clock for the TWIM bus interface (CLK_TWIM) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the TWIM before disabling the clock, to avoid freezing the TWIM in an undefined state. 22.7.4 DMA The TWIM DMA handshake interface is connected to the Peripheral DMA Controller. Using the TWIM DMA functionality requires the Peripheral DMA Controller to be programmed after setting up the TWIM. 22.7.5 Interrupts The TWIM interrupt request lines are connected to the interrupt controller. Using the TWIM interrupts requires the interrupt controller to be programmed first. 22.7.6 Debug Operation When an external debugger forces the CPU into debug mode, the TWIM continues normal operation. If the TWIM is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 531 32142D–06/2013 ATUC64/128/256L3/4U 22.8 Functional Description 22.8.1 Transfer Format The data put on the TWD line must be 8 bits long. Data is transferred MSB first; each byte must be followed by an acknowledgement. The number of bytes per transfer is unlimited (see Figure 22-4). Each transfer begins with a START condition and terminates with a STOP condition (see Figure 22-4). • A high-to-low transition on the TWD line while TWCK is high defines the START condition. • A low-to-high transition on the TWD line while TWCK is high defines a STOP condition. Figure 22-3. START and STOP Conditions Figure 22-4. Transfer Format 22.8.2 Operation The TWIM has two modes of operation: • Master transmitter mode • Master receiver mode The master is the device which starts and stops a transfer and generates the TWCK clock. These modes are described in the following chapters. TWD TWCK Start Stop TWD TWCK Start Address R/W Ack Data Ack Data Ack Stop 532 32142D–06/2013 ATUC64/128/256L3/4U 22.8.2.1 Clock Generation The Clock Waveform Generator Register (CWGR) is used to control the waveform of the TWCK clock. CWGR must be written so that the desired TWI bus timings are generated. CWGR describes bus timings as a function of cycles of a prescaled clock. The clock prescaling can be selected through the Clock Prescaler field in CWGR (CWGR.EXP). CWGR has the following fields: LOW: Prescaled clock cycles in clock low count. Used to time TLOW and TBUF. HIGH: Prescaled clock cycles in clock high count. Used to time THIGH. STASTO: Prescaled clock cycles in clock high count. Used to time THD_STA, TSU_STA, TSU_STO. DATA: Prescaled clock cycles for data setup and hold count. Used to time THD_DAT, TSU_DAT. EXP: Specifies the clock prescaler setting. Note that the total clock low time generated is the sum of THD_DAT + TSU_DAT + TLOW. Any slave or other bus master taking part in the transfer may extend the TWCK low period at any time. The TWIM hardware monitors the state of the TWCK line as required by the I²C specification. The clock generation counters are started when a high/low level is detected on the TWCK line, not when the TWIM hardware releases/drives the TWCK line. This means that the CWGR settings alone do not determine the TWCK frequency. The CWGR settings determine the clock low time and the clock high time, but the TWCK rise and fall times are determined by the external circuitry (capacitive load, etc.). Figure 22-5. Bus Timing Diagram f PRESCALER f CLK_TWIM 2  EXP 1 + = ------------------------- S t HD:STA t LOW t SU:DAT t HIGH t HD:DAT t LOW P t SU:STO Sr t SU:STA t SU:DAT 533 32142D–06/2013 ATUC64/128/256L3/4U 22.8.2.2 Setting up and Performing a Transfer Operation of the TWIM is mainly controlled by the Control Register (CR) and the Command Register (CMDR). TWIM status is provided in the Status Register (SR). The following list presents the main steps in a typical communication: 1. Before any transfers can be performed, bus timings must be configured by writing to the Clock Waveform Generator Register (CWGR). If operating in SMBus mode, the SMBus Timing Register (SMBTR) register must also be configured. 2. If the Peripheral DMA Controller is to be used for the transfers, it must be set up. 3. CMDR or NCMDR must be written with a value describing the transfer to be performed. The interrupt system can be set up to give interrupt requests on specific events or error conditions in the SR, for example when the transfer is complete or if arbitration is lost. The Interrupt Enable Register (IER) and Interrupt Disable Register (IDR) can be written to specify which bits in the SR will generate interrupt requests. The SR.BUSFREE bit is set when activity is completed on the two-wire bus. The SR.CRDY bit is set when CMDR and/or NCMDR is ready to receive one or more commands. The controller will refuse to start a new transfer while ANAK, DNAK, or ARBLST in the Status Register (SR) is one. This is necessary to avoid a race when the software issues a continuation of the current transfer at the same time as one of these errors happen. Also, if ANAK or DNAK occurs, a STOP condition is sent automatically. The user will have to restart the transmission by clearing the error bits in SR after resolving the cause for the NACK. After a data or address NACK from the slave, a STOP will be transmitted automatically. Note that the VALID bit in CMDR is NOT cleared in this case. If this transfer is to be discarded, the VALID bit can be cleared manually allowing any command in NCMDR to be copied into CMDR. When a data or address NACK is returned by the slave while the master is transmitting, it is possible that new data has already been written to the THR register. This data will be transferred out as the first data byte of the next transfer. If this behavior is to be avoided, the safest approach is to perform a software reset of the TWIM. 22.8.3 Master Transmitter Mode A START condition is transmitted and master transmitter mode is initiated when the bus is free and CMDR has been written with START=1 and READ=0. START and SADR+W will then be transmitted. During the address acknowledge clock pulse (9th pulse), the master releases the data line (HIGH), enabling the slave to pull it down in order to acknowledge the address. The master polls the data line during this clock pulse and sets the Address Not Acknowledged bit (ANAK) in the Status Register if no slave acknowledges the address. After the address phase, the following is repeated: while (NBYTES>0) 1. Wait until THR contains a valid data byte, stretching low period of TWCK. SR.TXRDY indicates the state of THR. Software or the Peripheral DMA Controller must write the data byte to THR. 2. Transmit this data byte 3. Decrement NBYTES 4. If (NBYTES==0) and STOP=1, transmit STOP condition Writing CMDR with START=STOP=1 and NBYTES=0 will generate a transmission with no data bytes, ie START, SADR+W, STOP. 534 32142D–06/2013 ATUC64/128/256L3/4U TWI transfers require the slave to acknowledge each received data byte. During the acknowledge clock pulse (9th pulse), the master releases the data line (HIGH), enabling the slave to pull it down in order to generate the acknowledge. The master polls the data line during this clock pulse and sets the Data Acknowledge bit (DNACK) in the Status Register if the slave does not acknowledge the data byte. As with the other status bits, an interrupt can be generated if enabled in the Interrupt Enable Register (IER). TXRDY is used as Transmit Ready for the Peripheral DMA Controller transmit channel. The end of a command is marked when the TWIM sets the SR.CCOMP bit. See Figure 22-6 and Figure 22-7. Figure 22-6. Master Write with One Data Byte Figure 22-7. Master Write with Multiple Data Bytes 22.8.4 Master Receiver Mode A START condition is transmitted and master receiver mode is initiated when the bus is free and CMDR has been written with START=1 and READ=1. START and SADR+R will then be transmitted. During the address acknowledge clock pulse (9th pulse), the master releases the data line (HIGH), enabling the slave to pull it down in order to acknowledge the address. The master polls the data line during this clock pulse and sets the Address Not Acknowledged bit (ANAK) in the Status Register if no slave acknowledges the address. After the address phase, the following is repeated: while (NBYTES>0) TWD SR.IDLE TXRDY Write THR (DATA) NBYTES set to 1 STOP sent automatically (ACK received and NBYTES=0) S DADR W A DATA A P TWD SR.IDLE TXRDY Write THR (DATAn) NBYTES set to n STOP sent automatically (ACK received and NBYTES=0) S DADR W A DATAn A DATAn+5 A A DATAn+m P Write THR (DATAn+1) Write THR (DATAn+m) Last data sent 535 32142D–06/2013 ATUC64/128/256L3/4U 1. Wait until RHR is empty, stretching low period of TWCK. SR.RXRDY indicates the state of RHR. Software or the Peripheral DMA Controller must read any data byte present in RHR. 2. Release TWCK generating a clock that the slave uses to transmit a data byte. 3. Place the received data byte in RHR, set RXRDY. 4. If NBYTES=0, generate a NAK after the data byte, otherwise generate an ACK. 5. Decrement NBYTES 6. If (NBYTES==0) and STOP=1, transmit STOP condition. Writing CMDR with START=STOP=1 and NBYTES=0 will generate a transmission with no data bytes, ie START, DADR+R, STOP The TWI transfers require the master to acknowledge each received data byte. During the acknowledge clock pulse (9th pulse), the slave releases the data line (HIGH), enabling the master to pull it down in order to generate the acknowledge. All data bytes except the last are acknowledged by the master. Not acknowledging the last byte informs the slave that the transfer is finished. RXRDY is used as Receive Ready for the Peripheral DMA Controller receive channel. Figure 22-8. Master Read with One Data Byte Figure 22-9. Master Read with Multiple Data Bytes TWD SR.IDLE RXRDY Write START & STOP bit NBYTES set to 1 Read RHR S DADR R A DATA N P TWD SR.IDLE RXRDY Write START + STOP bit NBYTES set to m S DADR R A DATAn A DATAn+m-1 A N DATAn+m P Read RHR DATAn DATAn+1 Read RHR DATAn+m-2 Read RHR DATAn+m-1 Read RHR DATAn+m Send STOP When NBYTES=0 536 32142D–06/2013 ATUC64/128/256L3/4U 22.8.5 Using the Peripheral DMA Controller The use of the Peripheral DMA Controller significantly reduces the CPU load. The user can set up ring buffers for the Peripheral DMA Controller, containing data to transmit or free buffer space to place received data. To assure correct behavior, respect the following programming sequences: 22.8.5.1 Data Transmit with the Peripheral DMA Controller 1. Initialize the transmit Peripheral DMA Controller (memory pointers, size, etc.). 2. Configure the TWIM (ADR, NBYTES, etc.). 3. Start the transfer by enabling the Peripheral DMA Controller to transmit. 4. Wait for the Peripheral DMA Controller end-of-transmit flag. 5. Disable the Peripheral DMA Controller. 22.8.5.2 Data Receive with the Peripheral DMA Controller 1. Initialize the receive Peripheral DMA Controller (memory pointers, size, etc.). 2. Configure the TWIM (ADR, NBYTES, etc.). 3. Start the transfer by enabling the Peripheral DMA Controller to receive. 4. Wait for the Peripheral DMA Controller end-of-receive flag. 5. Disable the Peripheral DMA Controller. 22.8.6 Multi-master Mode More than one master may access the bus at the same time without data corruption by using arbitration. Arbitration starts as soon as two or more masters place information on the bus at the same time, and stops (arbitration is lost) for the master that intends to send a logical one while the other master sends a logical zero. As soon as arbitration is lost by a master, it stops sending data and listens to the bus in order to detect a STOP. The SR.ARBLST flag will be set. When the STOP is detected, the master who lost arbitration may reinitiate the data transfer. Arbitration is illustrated in Figure 22-11. If the user starts a transfer and if the bus is busy, the TWIM automatically waits for a STOP condition on the bus before initiating the transfer (see Figure 22-10). Note: The state of the bus (busy or free) is not indicated in the user interface. 537 32142D–06/2013 ATUC64/128/256L3/4U Figure 22-10. User Sends Data While the Bus is Busy Figure 22-11. Arbitration Cases 22.8.7 Combined Transfers CMDR and NCMDR may be used to generate longer sequences of connected transfers, since generation of START and/or STOP conditions is programmable on a per-command basis. Writing NCMDR with START=1 when the previous transfer was written with STOP=0 will cause a REPEATED START on the bus. The ability to generate such connected transfers allows arbitrary transfer lengths, since it is legal to write CMDR with both START=0 and STOP=0. If this is done in master receiver mode, the CMDR.ACKLAST bit must also be controlled. TWCK TWD DATA sent by a master STOP sent by the master START sent by the TWI DATA sent by the TWI Bus is busy Bus is free A transfer is programmed (DADR + W + START + Write THR) Transfer is initiated TWI DATA transfer Transfer is kept Bus is considered as free TWCK Bus is busy Bus is free A transfer is programmed (DADR + W + START + Write THR) Transfer is initiated TWI DATA transfer Transfer is kept Bus is considered as free Data from a Master Data from TWI S 0 S 0 0 1 1 1 ARBLST S 0 S 0 0 1 1 1 TWD S 1 0 0 1 1 1 1 Arbitration is lost TWI stops sending data P P S 1 0 0 1 1 Data from the master 1 1 Data from the TWI Arbitration is lost The master stops sending data Transfer is stopped Transfer is programmed again (DADR + W + START + Write THR) TWCK TWD 538 32142D–06/2013 ATUC64/128/256L3/4U As for single data transfers, the TXRDY and RXRDY bits in the Status Register indicates when data to transmit can be written to THR, or when received data can be read from RHR. Transfer of data to THR and from RHR can also be done automatically by DMA, see Section 22.8.5 22.8.7.1 Write Followed by Write Consider the following transfer: START, DADR+W, DATA+A, DATA+A, REPSTART, DADR+W, DATA+A, DATA+A, STOP. To generate this transfer: 1. Write CMDR with START=1, STOP=0, DADR, NBYTES=2 and READ=0. 2. Write NCMDR with START=1, STOP=1, DADR, NBYTES=2 and READ=0. 3. Wait until SR.TXRDY==1, then write first data byte to transfer to THR. 4. Wait until SR.TXRDY==1, then write second data byte to transfer to THR. 5. Wait until SR.TXRDY==1, then write third data byte to transfer to THR. 6. Wait until SR.TXRDY==1, then write fourth data byte to transfer to THR. 22.8.7.2 Read Followed by Read Consider the following transfer: START, DADR+R, DATA+A, DATA+NA, REPSTART, DADR+R, DATA+A, DATA+NA, STOP. To generate this transfer: 1. Write CMDR with START=1, STOP=0, DADR, NBYTES=2 and READ=1. 2. Write NCMDR with START=1, STOP=1, DADR, NBYTES=2 and READ=1. 3. Wait until SR.RXRDY==1, then read first data byte received from RHR. 4. Wait until SR.RXRDY==1, then read second data byte received from RHR. 5. Wait until SR.RXRDY==1, then read third data byte received from RHR. 6. Wait until SR.RXRDY==1, then read fourth data byte received from RHR. If combining several transfers, without any STOP or REPEATED START between them, remember to write a one to the ACKLAST bit in CMDR to keep from ending each of the partial transfers with a NACK. 22.8.7.3 Write Followed by Read Consider the following transfer: START, DADR+W, DATA+A, DATA+A, REPSTART, DADR+R, DATA+A, DATA+NA, STOP. 539 32142D–06/2013 ATUC64/128/256L3/4U Figure 22-12. Combining a Write and Read Transfer To generate this transfer: 1. Write CMDR with START=1, STOP=0, DADR, NBYTES=2 and READ=0. 2. Write NCMDR with START=1, STOP=1, DADR, NBYTES=2 and READ=1. 3. Wait until SR.TXRDY==1, then write first data byte to transfer to THR. 4. Wait until SR.TXRDY==1, then write second data byte to transfer to THR. 5. Wait until SR.RXRDY==1, then read first data byte received from RHR. 6. Wait until SR.RXRDY==1, then read second data byte received from RHR. 22.8.7.4 Read Followed by Write Consider the following transfer: START, DADR+R, DATA+A, DATA+NA, REPSTART, DADR+W, DATA+A, DATA+A, STOP. Figure 22-13. Combining a Read and Write Transfer To generate this transfer: 1. Write CMDR with START=1, STOP=0, DADR, NBYTES=2 and READ=1. 2. Write NCMDR with START=1, STOP=1, DADR, NBYTES=2 and READ=0. 3. Wait until SR.RXRDY==1, then read first data byte received from RHR. 4. Wait until SR.RXRDY==1, then read second data byte received from RHR. 5. Wait until SR.TXRDY==1, then write first data byte to transfer to THR. 6. Wait until SR.TXRDY==1, then write second data byte to transfer to THR. TWD SR.IDLE TXRDY S DADR W A DATA0 A DATA1 NA Sr DADR R A DATA2 A DATA3 A P THR DATA0 DATA1 RXRDY 1 RHR DATA2 DATA3 TWD SR.IDLE TXRDY S SADR R A DATA0 A DATA1 Sr DADR W A DATA2 A DATA3 NA P THR DATA2 RXRDY RHR DATA0 DATA3 A 1 2 DATA3 Read TWI_RHR 540 32142D–06/2013 ATUC64/128/256L3/4U 22.8.8 Ten Bit Addressing Writing a one to CMDR.TENBIT enables 10-bit addressing in hardware. Performing transfers with 10-bit addressing is similar to transfers with 7-bit addresses, except that bits 9:7 of CMDR.SADR must be written appropriately. In Figure 22-14 and Figure 22-15, the grey boxes represent signals driven by the master, the white boxes are driven by the slave. 22.8.8.1 Master Transmitter To perform a master transmitter transfer: 1. Write CMDR with TENBIT=1, REPSAME=0, READ=0, START=1, STOP=1 and the desired address and NBYTES value. Figure 22-14. A Write Transfer with 10-bit Addressing 22.8.8.2 Master Receiver When using master receiver mode with 10-bit addressing, CMDR.REPSAME must also be controlled. CMDR.REPSAME must be written to one when the address phase of the transfer should consist of only 1 address byte (the 11110xx byte) and not 2 address bytes. The I²C standard specifies that such addressing is required when addressing a slave for reads using 10-bit addressing. To perform a master receiver transfer: 1. Write CMDR with TENBIT=1, REPSAME=0, READ=0, START=1, STOP=0, NBYTES=0 and the desired address. 2. Write NCMDR with TENBIT=1, REPSAME=1, READ=1, START=1, STOP=1 and the desired address and NBYTES value. Figure 22-15. A Read Transfer with 10-bit Addressing 22.8.9 SMBus Mode SMBus mode is enabled and disabled by writing to the SMEN and SMDIS bits in CR. SMBus mode operation is similar to I²C operation with the following exceptions: • Only 7-bit addressing can be used. • The SMBus standard describes a set of timeout values to ensure progress and throughput on the bus. These timeout values must be written into SMBTR. • Transmissions can optionally include a CRC byte, called Packet Error Check (PEC). • A dedicated bus line, SMBALERT, allows a slave to get a master’s attention. • A set of addresses have been reserved for protocol handling, such as Alert Response Address (ARA) and Host Header (HH) Address. S SLAVE ADDRESS 1st 7 bits RW A1 A2 DATA A P SLAVE ADDRESS 2nd byte DATA AA 11110XX0 S SLAVE ADDRESS 1st 7 bits RW A1 A2 DATA A P SLAVE ADDRESS 2nd byte DATA A 11110XX0 Sr SLAVE ADDRESS 1st 7 bits RW A3 11110XX1 541 32142D–06/2013 ATUC64/128/256L3/4U 22.8.9.1 Packet Error Checking Each SMBus transfer can optionally end with a CRC byte, called the PEC byte. Writing a one to CMDR.PECEN enables automatic PEC handling in the current transfer. Transfers with and without PEC can freely be intermixed in the same system, since some slaves may not support PEC. The PEC LFSR is always updated on every bit transmitted or received, so that PEC handling on combined transfers will be correct. In master transmitter mode, the master calculates a PEC value and transmits it to the slave after all data bytes have been transmitted. Upon reception of this PEC byte, the slave will compare it to the PEC value it has computed itself. If the values match, the data was received correctly, and the slave will return an ACK to the master. If the PEC values differ, data was corrupted, and the slave will return a NACK value. The DNAK bit in SR reflects the state of the last received ACK/NACK value. Some slaves may not be able to check the received PEC in time to return a NACK if an error occurred. In this case, the slave should always return an ACK after the PEC byte, and some other mechanism must be implemented to verify that the transmission was received correctly. In master receiver mode, the slave calculates a PEC value and transmits it to the master after all data bytes have been transmitted. Upon reception of this PEC byte, the master will compare it to the PEC value it has computed itself. If the values match, the data was received correctly. If the PEC values differ, data was corrupted, and SR.PECERR is set. In master receiver mode, the PEC byte is always followed by a NACK transmitted by the master, since it is the last byte in the transfer. The PEC byte is automatically inserted in a master transmitter transmission if PEC is enabled when NBYTES reaches zero. The PEC byte is identified in a master receiver transmission if PEC is enabled when NBYTES reaches zero. NBYTES must therefore be written with the total number of data bytes in the transmission, including the PEC byte. In combined transfers, the PECEN bit should only be written to one in the last of the combined transfers. Consider the following transfer: S, ADR+W, COMMAND_BYTE, ACK, SR, ADR+R, DATA_BYTE, ACK, PEC_BYTE, NACK, P This transfer is generated by writing two commands to the command registers. The first command is a write with NBYTES=1 and PECEN=0, and the second is a read with NBYTES=2 and PECEN=1. Writing a one to the STOP bit in CR will place a STOP condition on the bus after the current byte. No PEC byte will be sent in this case. 22.8.9.2 Timeouts The TLOWS and TLOWM fields in SMBTR configure the SMBus timeout values. If a timeout occurs, the master will transmit a STOP condition and leave the bus. The SR.TOUT bit is set. 22.8.9.3 SMBus ALERT Signal A slave can get the master’s attention by pulling the TWALM line low. The TWIM will then set the SR.SMBALERT bit. This can be set up to trigger an interrupt, and software can then take the appropriate action, as defined in the SMBus standard. 542 32142D–06/2013 ATUC64/128/256L3/4U 22.8.10 Identifying Bus Events This chapter lists the different bus events, and how they affect bits in the TWIM registers. This is intended to help writing drivers for the TWIM. Table 22-5. Bus Events Event Effect Master transmitter has sent a data byte SR.THR is cleared. Master receiver has received a data byte SR.RHR is set. Start+Sadr sent, no ack received from slave SR.ANAK is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. Data byte sent to slave, no ack received from slave SR.DNAK is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. Arbitration lost SR.ARBLST is set. SR.CCOMP not set. CMDR.VALID remains set. TWCK and TWD immediately released to a pulled-up state. SMBus Alert received SR.SMBALERT is set. SMBus timeout received SR.SMBTOUT is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. Master transmitter receives SMBus PEC Error SR.DNAK is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. Master receiver discovers SMBus PEC Error SR.PECERR is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. CR.STOP is written by user SR.STOP is set. SR.CCOMP set. CMDR.VALID remains set. STOP transmitted on bus after current byte transfer has finished. 543 32142D–06/2013 ATUC64/128/256L3/4U 22.9 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 22-6. TWIM Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Write-only 0x00000000 0x04 Clock Waveform Generator Register CWGR Read/Write 0x00000000 0x08 SMBus Timing Register SMBTR Read/Write 0x00000000 0x0C Command Register CMDR Read/Write 0x00000000 0x10 Next Command Register NCMDR Read/Write 0x00000000 0x14 Receive Holding Register RHR Read-only 0x00000000 0x18 Transmit Holding Register THR Write-only 0x00000000 0x1C Status Register SR Read-only 0x00000002 0x20 Interrupt Enable Register IER Write-only 0x00000000 0x24 Interrupt Disable Register IDR Write-only 0x00000000 0x28 Interrupt Mask Register IMR Read-only 0x00000000 0x2C Status Clear Register SCR Write-only 0x00000000 0x30 Parameter Register PR Read-only -(1) 0x34 Version Register VR Read-only -(1) 544 32142D–06/2013 ATUC64/128/256L3/4U 22.9.1 Control Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 • STOP: Stop the Current Transfer Writing a one to this bit terminates the current transfer, sending a STOP condition after the shifter has become idle. If there are additional pending transfers, they will have to be explicitly restarted by software after the STOP condition has been successfully sent. Writing a zero to this bit has no effect. • SWRST: Software Reset If the TWIM master interface is enabled, writing a one to this bit resets the TWIM. All transfers are halted immediately, possibly violating the bus semantics. If the TWIM master interface is not enabled, it must first be enabled before writing a one to this bit. Writing a zero to this bit has no effect. • SMDIS: SMBus Disable Writing a one to this bit disables SMBus mode. Writing a zero to this bit has no effect. • SMEN: SMBus Enable Writing a one to this bit enables SMBus mode. Writing a zero to this bit has no effect. • MDIS: Master Disable Writing a one to this bit disables the master interface. Writing a zero to this bit has no effect. • MEN: Master Enable Writing a one to this bit enables the master interface. Writing a zero to this bit has no effect. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - STOP 76543210 SWRST - SMDIS SMEN - - MDIS MEN 545 32142D–06/2013 ATUC64/128/256L3/4U 22.9.2 Clock Waveform Generator Register Name: CWGR Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • EXP: Clock Prescaler Used to specify how to prescale the TWCK clock. Counters are prescaled according to the following formula • DATA: Data Setup and Hold Cycles Clock cycles for data setup and hold count. Prescaled by CWGR.EXP. Used to time THD_DAT, TSU_DAT. • STASTO: START and STOP Cycles Clock cycles in clock high count. Prescaled by CWGR.EXP. Used to time THD_STA, TSU_STA, TSU_STO • HIGH: Clock High Cycles Clock cycles in clock high count. Prescaled by CWGR.EXP. Used to time THIGH. • LOW: Clock Low Cycles Clock cycles in clock low count. Prescaled by CWGR.EXP. Used to time TLOW, TBUF. 31 30 29 28 27 26 25 24 - EXP DATA 23 22 21 20 19 18 17 16 STASTO 15 14 13 12 11 10 9 8 HIGH 76543210 LOW f PRESCALER f CLK_TWIM 2  EXP 1 + = ------------------------- 546 32142D–06/2013 ATUC64/128/256L3/4U 22.9.3 SMBus Timing Register Name: SMBTR Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • EXP: SMBus Timeout Clock Prescaler Used to specify how to prescale the TIM and TLOWM counters in SMBTR. Counters are prescaled according to the following formula • THMAX: Clock High Maximum Cycles Clock cycles in clock high maximum count. Prescaled by SMBTR.EXP. Used for bus free detection. Used to time THIGH:MAX. NOTE: Uses the prescaler specified by CWGR, NOT the prescaler specified by SMBTR. • TLOWM: Master Clock Stretch Maximum Cycles Clock cycles in master maximum clock stretch count. Prescaled by SMBTR.EXP. Used to time TLOW:MEXT • TLOWS: Slave Clock Stretch Maximum Cycles Clock cycles in slave maximum clock stretch count. Prescaled by SMBTR.EXP. Used to time TLOW:SEXT. 31 30 29 28 27 26 25 24 EXP - - - - 23 22 21 20 19 18 17 16 THMAX 15 14 13 12 11 10 9 8 TLOWM 76543210 TLOWS f prescaled SMBus  f CLKTWIM 2  EXP + 1 = ------------------------ 547 32142D–06/2013 ATUC64/128/256L3/4U 22.9.4 Command Register Name: CMDR Access Type: Read/Write Offset: 0x0C Reset Value: 0x00000000 • ACKLAST: ACK Last Master RX Byte 0: Causes the last byte in master receive mode (when NBYTES has reached 0) to be NACKed. This is the standard way of ending a master receiver transfer. 1: Causes the last byte in master receive mode (when NBYTES has reached 0) to be ACKed. Used for performing linked transfers in master receiver mode with no STOP or REPEATED START between the subtransfers. This is needed when more than 255 bytes are to be received in one single transmission. • PECEN: Packet Error Checking Enable 0: Causes the transfer not to use PEC byte verification. The PEC LFSR is still updated for every bit transmitted or received. Must be used if SMBus mode is disabled. 1: Causes the transfer to use PEC. PEC byte generation (if master transmitter) or PEC byte verification (if master receiver) will be performed. • NBYTES: Number of Data Bytes in Transfer The number of data bytes in the transfer. After the specified number of bytes have been transferred, a STOP condition is transmitted if CMDR.STOP is one. In SMBus mode, if PEC is used, NBYTES includes the PEC byte, i.e. there are NBYTES-1 data bytes and a PEC byte. • VALID: CMDR Valid 0: Indicates that CMDR does not contain a valid command. 1: Indicates that CMDR contains a valid command. This bit is cleared when the command is finished. • STOP: Send STOP Condition 0: Do not transmit a STOP condition after the data bytes have been transmitted. 1: Transmit a STOP condition after the data bytes have been transmitted. • START: Send START Condition 0: The transfer in CMDR should not commence with a START or REPEATED START condition. 1: The transfer in CMDR should commence with a START or REPEATED START condition. If the bus is free when the command is executed, a START condition is used. If the bus is busy, a REPEATED START is used. • REPSAME: Transfer is to Same Address as Previous Address Only used in 10-bit addressing mode, always write to 0 in 7-bit addressing mode. 31 30 29 28 27 26 25 24 - - - - ACKLAST PECEN 23 22 21 20 19 18 17 16 NBYTES 15 14 13 12 11 10 9 8 VALID STOP START REPSAME TENBIT SADR[9:7] 76543210 SADR[6:0] READ 548 32142D–06/2013 ATUC64/128/256L3/4U Write this bit to one if the command in CMDR performs a repeated start to the same slave address as addressed in the previous transfer in order to enter master receiver mode. Write this bit to zero otherwise. • TENBIT: Ten Bit Addressing Mode 0: Use 7-bit addressing mode. 1: Use 10-bit addressing mode. Must not be used when the TWIM is in SMBus mode. • SADR: Slave Address Address of the slave involved in the transfer. Bits 9-7 are don’t care if 7-bit addressing is used. • READ: Transfer Direction 0: Allow the master to transmit data. 1: Allow the master to receive data. 549 32142D–06/2013 ATUC64/128/256L3/4U 22.9.5 Next Command Register Name: NCMDR Access Type: Read/Write Offset: 0x10 Reset Value: 0x00000000 This register is identical to CMDR. When the VALID bit in CMDR becomes 0, the content of NCMDR is copied into CMDR, clearing the VALID bit in NCMDR. If the VALID bit in CMDR is cleared when NCMDR is written, the content is copied immediately. 31 30 29 28 27 26 25 24 - - - - ACKLAST PECEN 23 22 21 20 19 18 17 16 NBYTES 15 14 13 12 11 10 9 8 VALID STOP START REPSAME TENBIT SADR[9:7] 76543210 SADR[6:0] READ 550 32142D–06/2013 ATUC64/128/256L3/4U 22.9.6 Receive Holding Register Name: RHR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 • RXDATA: Received Data When the RXRDY bit in the Status Register (SR) is one, this field contains a byte received from the TWI bus. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RXDATA 551 32142D–06/2013 ATUC64/128/256L3/4U 22.9.7 Transmit Holding Register Name: THR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 • TXDATA: Data to Transmit Write data to be transferred on the TWI bus here. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 TXDATA 552 32142D–06/2013 ATUC64/128/256L3/4U 22.9.8 Status Register Name: SR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000002 • MENB: Master Interface Enable 0: Master interface is disabled. 1: Master interface is enabled. • STOP: Stop Request Accepted This bit is one when a STOP request caused by writing a one to CR.STOP has been accepted, and transfer has stopped. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • PECERR: PEC Error This bit is one when a SMBus PEC error occurred. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • TOUT: Timeout This bit is one when a SMBus timeout occurred. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • SMBALERT: SMBus Alert This bit is one when an SMBus Alert was received. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • ARBLST: Arbitration Lost This bit is one when the actual state of the SDA line did not correspond to the data driven onto it, indicating a higher-priority transmission in progress by a different master. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • DNAK: NAK in Data Phase Received This bit is one when no ACK was received form slave during data transmission. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • ANAK: NAK in Address Phase Received This bit is one when no ACK was received from slave during address phase This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • BUSFREE: Two-wire Bus is Free This bit is one when activity has completed on the two-wire bus. Otherwise, this bit is cleared. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - MENB 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - BUSFREE IDLE CCOMP CRDY TXRDY RXRDY 553 32142D–06/2013 ATUC64/128/256L3/4U • IDLE: Master Interface is Idle This bit is one when no command is in progress, and no command waiting to be issued. Otherwise, this bit is cleared. • CCOMP: Command Complete This bit is one when the current command has completed successfully. This bit is zero if the command failed due to conditions such as a NAK receved from slave. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • CRDY: Ready for More Commands This bit is one when CMDR and/or NCMDR is ready to receive one or more commands. This bit is cleared when this is no longer true. • TXRDY: THR Data Ready This bit is one when THR is ready for one or more data bytes. This bit is cleared when this is no longer true (i.e. THR is full or transmission has stopped). • RXRDY: RHR Data Ready This bit is one when RX data are ready to be read from RHR. This bit is cleared when this is no longer true. 554 32142D–06/2013 ATUC64/128/256L3/4U 22.9.9 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - BUSFREE IDLE CCOMP CRDY TXRDY RXRDY 555 32142D–06/2013 ATUC64/128/256L3/4U 22.9.10 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x24 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - BUSFREE IDLE CCOMP CRDY TXRDY RXRDY 556 32142D–06/2013 ATUC64/128/256L3/4U 22.9.11 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x28 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - BUSFREE IDLE CCOMP CRDY TXRDY RXRDY 557 32142D–06/2013 ATUC64/128/256L3/4U 22.9.12 Status Clear Register Name: SCR Access Type : Write-only Offset: 0x2C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - - - CCOMP - - - 558 32142D–06/2013 ATUC64/128/256L3/4U 22.9.13 Parameter Register (PR) Name: PR Access Type: Read-only Offset: 0x30 Reset Value: - 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 559 32142D–06/2013 ATUC64/128/256L3/4U 22.9.14 Version Register (VR) Name: VR Access Type: Read-only Offset: 0x34 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION [11:8] 76543210 VERSION [7:0] 560 32142D–06/2013 ATUC64/128/256L3/4U 22.10 Module Configuration The specific configuration for each TWIM instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 22-7. Module Clock Name Module Name Clock Name Description TWIM0 CLK_TWIM0 Clock for the TWIM0 bus interface TWIM1 CLK_TWIM1 Clock for the TWIM1 bus interface Table 22-8. Register Reset Values Register Reset Value VERSION 0x00000110 PARAMETER 0x00000000 561 32142D–06/2013 ATUC64/128/256L3/4U 23. Two-wire Slave Interface (TWIS) Rev.: 1.2.0.1 23.1 Features • Compatible with I²C standard – Transfer speeds of 100 and 400 kbit/s – 7 and 10-bit and General Call addressing • Compatible with SMBus standard – Hardware Packet Error Checking (CRC) generation and verification with ACK response – SMBALERT interface – 25 ms clock low timeout delay – 25 ms slave cumulative clock low extend time • Compatible with PMBus • DMA interface for reducing CPU load • Arbitrary transfer lengths, including 0 data bytes • Optional clock stretching if transmit or receive buffers not ready for data transfer • 32-bit Peripheral Bus interface for configuration of the interface 23.2 Overview The Atmel Two-wire Slave Interface (TWIS) interconnects components on a unique two-wire bus, made up of one clock line and one data line with speeds of up to 400 kbit/s, based on a byte-oriented transfer format. It can be used with any Atmel Two-wire Interface bus, I²C, or SMBus-compatible master. The TWIS is always a bus slave and can transfer sequential or single bytes. Below, Table 23-1 lists the compatibility level of the Atmel Two-wire Slave Interface and a full I²C compatible device. Note: 1. START + b000000001 + Ack + Sr Table 23-1. Atmel TWIS Compatibility with I²C Standard I²C Standard Atmel TWIS Standard-mode (100 kbit/s) Supported Fast-mode (400 kbit/s) Supported 7 or 10 bits Slave Addressing Supported START BYTE(1) Not Supported Repeated Start (Sr) Condition Supported ACK and NAK Management Supported Slope control and input filtering (Fast mode) Supported Clock stretching Supported 562 32142D–06/2013 ATUC64/128/256L3/4U Below, Table 23-2 lists the compatibility level of the Atmel Two-wire Slave Interface and a full SMBus compatible device. 23.3 List of Abbreviations 23.4 Block Diagram Figure 23-1. Block Diagram Table 23-2. Atmel TWIS Compatibility with SMBus Standard SMBus Standard Atmel TWIS Bus Timeouts Supported Address Resolution Protocol Supported Alert Supported Packet Error Checking Supported Table 23-3. Abbreviations Abbreviation Description TWI Two-wire Interface A Acknowledge NA Non Acknowledge P Stop S Start Sr Repeated Start SADR Slave Address ADR Any address except SADR R Read W Write Peripheral Bus Bridge Two-wire Interface I/O Controller TWCK TWD Interrupt Controller TWI Interrupt Power Manager CLK_TWIS TWALM 563 32142D–06/2013 ATUC64/128/256L3/4U 23.5 Application Block Diagram Figure 23-2. Application Block Diagram 23.6 I/O Lines Description 23.7 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 23.7.1 I/O Lines TWDand TWCK are bidirectional lines, connected to a positive supply voltage via a current source or pull-up resistor (see Figure 23-5 on page 565). When the bus is free, both lines are high. The output stages of devices connected to the bus must have an open-drain or open-collector to perform the wired-AND function. TWALM is used to implement the optional SMBus SMBALERT signal. TWALM, TWD, and TWCK pins may be multiplexed with I/O Controller lines. To enable the TWIS, the user must perform the following steps: • Program the I/O Controller to: – Dedicate TWD, TWCK, and optionally TWALM as peripheral lines. – Define TWD, TWCK, and optionally TWALM as open-drain. Host with TWI Interface TWD TWCK Atmel TWI serial EEPROM I²C RTC I²C LCD controller Slave 1 Slave 2 Slave 3 VDD I²C temp. sensor Slave 4 Rp: Pull up value as given by the I²C Standard Rp Rp Table 23-4. I/O Lines Description Pin Name Pin Description Type TWD Two-wire Serial Data Input/Output TWCK Two-wire Serial Clock Input/Output TWALM SMBus SMBALERT Input/Output 564 32142D–06/2013 ATUC64/128/256L3/4U 23.7.2 Power Management If the CPU enters a sleep mode that disables clocks used by the TWIS, the TWIS will stop functioning and resume operation after the system wakes up from sleep mode. The TWIS is able to wake the system from sleep mode upon address match, see Section 23.8.8 on page 572. 23.7.3 Clocks The clock for the TWIS bus interface (CLK_TWIS) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the TWIS before disabling the clock, to avoid freezing the TWIS in an undefined state. 23.7.4 DMA The TWIS DMA handshake interface is connected to the Peripheral DMA Controller. Using the TWIS DMA functionality requires the Peripheral DMA Controller to be programmed after setting up the TWIS. 23.7.5 Interrupts The TWIS interrupt request lines are connected to the interrupt controller. Using the TWIS interrupts requires the interrupt controller to be programmed first. 23.7.6 Debug Operation When an external debugger forces the CPU into debug mode, the TWIS continues normal operation. If the TWIS is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 23.8 Functional Description 23.8.1 Transfer Format The data put on the TWD line must be 8 bits long. Data is transferred MSB first; each byte must be followed by an acknowledgement. The number of bytes per transfer is unlimited (see Figure 23-4 on page 565). Each transfer begins with a START condition and terminates with a STOP condition (see Figure 23-3). • A high-to-low transition on the TWD line while TWCK is high defines the START condition. • A low-to-high transition on the TWD line while TWCK is high defines a STOP condition. Figure 23-3. START and STOP Conditions TWD TWCK Start Stop 565 32142D–06/2013 ATUC64/128/256L3/4U Figure 23-4. Transfer Format 23.8.2 Operation The TWIS has two modes of operation: • Slave transmitter mode • Slave receiver mode A master is a device which starts and stops a transfer and generates the TWCK clock. A slave is assigned an address and responds to requests from the master. These modes are described in the following chapters. Figure 23-5. Typical Application Block Diagram 23.8.2.1 Bus Timing The Timing Register (TR) is used to control the timing of bus signals driven by the TWIS. TR describes bus timings as a function of cycles of the prescaled CLK_TWIS. The clock prescaling can be selected through TR.EXP. TR has the following fields: TLOWS: Prescaled clock cycles used to time SMBUS timeout TLOW:SEXT. TWD TWCK Start Address R/W Ack Data Ack Data Ack Stop Host with TWI Interface TWD TWCK Atmel TWI Serial EEPROM I²C RTC I²C LCD Controller Slave 1 Slave 2 Slave 3 VDD I²C Temp. Sensor Slave 4 Rp: Pull up value as given by the I²C Standard Rp Rp fPRESCALED f CLK_TWIS 2  EXP 1 + = ------------------------ 566 32142D–06/2013 ATUC64/128/256L3/4U TTOUT: Prescaled clock cycles used to time SMBUS timeout TTIMEOUT. SUDAT: Non-prescaled clock cycles for data setup and hold count. Used to time TSU_DAT. EXP: Specifies the clock prescaler setting used for the SMBUS timeouts. Figure 23-6. Bus Timing Diagram 23.8.2.2 Setting Up and Performing a Transfer Operation of the TWIS is mainly controlled by the Control Register (CR). The following list presents the main steps in a typical communication: 3. Before any transfers can be performed, bus timings must be configured by writing to the Timing Register (TR).If the Peripheral DMA Controller is to be used for the transfers, it must be set up. 4. The Control Register (CR) must be configured with information such as the slave address, SMBus mode, Packet Error Checking (PEC), number of bytes to transfer, and which addresses to match. The interrupt system can be set up to generate interrupt request on specific events or error conditions, for example when a byte has been received. The NBYTES register is only used in SMBus mode, when PEC is enabled. In I²C mode or in SMBus mode when PEC is disabled, the NBYTES register is not used, and should be written to zero. NBYTES is updated by hardware, so in order to avoid hazards, software updates of NBYTES can only be done through writes to the NBYTES register. 23.8.2.3 Address Matching The TWIS can be set up to match several different addresses. More than one address match may be enabled simultaneously, allowing the TWIS to be assigned to several addresses. The address matching phase is initiated after a START or REPEATED START condition. When the TWIS receives an address that generates an address match, an ACK is automatically returned to the master. S t HD:STA t LOW t SU:DAT t HIGH t HD:DAT t LOW P t SU:STO Sr t SU:STA t SU:DAT 567 32142D–06/2013 ATUC64/128/256L3/4U In I²C mode: • The address in CR.ADR is checked for address match if CR.SMATCH is one. • The General Call address is checked for address match if CR.GCMATCH is one. In SMBus mode: • The address in CR.ADR is checked for address match if CR.SMATCH is one. • The Alert Response Address is checked for address match if CR.SMAL is one. • The Default Address is checked for address match if CR.SMDA is one. • The Host Header Address is checked for address match if CR.SMHH is one. 23.8.2.4 Clock Stretching Any slave or bus master taking part in a transfer may extend the TWCK low period at any time. The TWIS may extend the TWCK low period after each byte transfer if CR.STREN is one and: • Module is in slave transmitter mode, data should be transmitted, but THR is empty, or • Module is in slave receiver mode, a byte has been received and placed into the internal shifter, but the Receive Holding Register (RHR) is full, or • Stretch-on-address-match bit CR.SOAM=1 and slave was addressed. Bus clock remains stretched until all address match bits in the Status Register (SR) have been cleared. If CR.STREN is zero and: • Module is in slave transmitter mode, data should be transmitted but THR is empty: Transmit the value present in THR (the last transmitted byte or reset value), and set SR.URUN. • Module is in slave receiver mode, a byte has been received and placed into the internal shifter, but RHR is full: Discard the received byte and set SR.ORUN. 23.8.2.5 Bus Errors If a bus error (misplaced START or STOP) condition is detected, the SR.BUSERR bit is set and the TWIS waits for a new START condition. 23.8.3 Slave Transmitter Mode If the TWIS matches an address in which the R/W bit in the TWI address phase transfer is set, it will enter slave transmitter mode and set the SR.TRA bit (note that SR.TRA is set one CLK_TWIS cycle after the relevant address match bit in the same register is set). After the address phase, the following actions are performed: 1. If SMBus mode and PEC is used, NBYTES must be set up with the number of bytes to transmit. This is necessary in order to know when to transmit the PEC byte. NBYTES can also be used to count the number of bytes received if using DMA. 2. Byte to transmit depends on I²C/SMBus mode and CR.PEC: – If in I²C mode or CR.PEC is zero or NBYTES is non-zero: The TWIS waits until THR contains a valid data byte, possibly stretching the low period of TWCK. After THR contains a valid data byte, the data byte is transferred to a shifter, and then SR.TXRDY is changed to one because the THR is empty again. – SMBus mode and CR.PEC is one: If NBYTES is zero, the generated PEC byte is automatically transmitted instead of a data byte from THR. TWCK will not be stretched by the TWIS. 3. The data byte in the shifter is transmitted. 568 32142D–06/2013 ATUC64/128/256L3/4U 4. NBYTES is updated. If CR.CUP is one, NBYTES is incremented, otherwise NBYTES is decremented. 5. After each data byte has been transmitted, the master transmits an ACK (Acknowledge) or NAK (Not Acknowledge) bit. If a NAK bit is received by the TWIS, the SR.NAK bit is set. Note that this is done two CLK_TWIS cycles after TWCK has been sampled by the TWIS to be HIGH (see Figure 23-9). The NAK indicates that the transfer is finished, and the TWIS will wait for a STOP or REPEATED START. If an ACK bit is received, the SR.NAK bit remains LOW. The ACK indicates that more data should be transmitted, jump to step 2. At the end of the ACK/NAK clock cycle, the Byte Transfer Finished (SR.BTF) bit is set. Note that this is done two CLK_TWIS cycles after TWCK has been sampled by the TWIS to be LOW (see Figure 23-9). Also note that in the event that SR.NAK bit is set, it must not be cleared before the SR.BTF bit is set to ensure correct TWIS behavior. 6. If STOP is received, SR.TCOMP and SR.STO will be set. 7. If REPEATED START is received, SR.REP will be set. The TWI transfers require the receiver to acknowledge each received data byte. During the acknowledge clock pulse (9th pulse), the slave releases the data line (HIGH), enabling the master to pull it down in order to generate the acknowledge. The slave polls the data line during this clock pulse and sets the NAK bit in SR if the master does not acknowledge the data byte. A NAK means that the master does not wish to receive additional data bytes. As with the other status bits, an interrupt can be generated if enabled in the Interrupt Enable Register (IER). SR.TXRDY is used as Transmit Ready for the Peripheral DMA Controller transmit channel. The end of the complete transfer is marked by the SR.TCOMP bit changing from zero to one. See Figure 23-7 and Figure 23-8. Figure 23-7. Slave Transmitter with One Data Byte TCOMP TXRDY Write THR (DATA) STOP sent by master TWD S DADR R P A DATA N NBYTES set to 1 569 32142D–06/2013 ATUC64/128/256L3/4U Figure 23-8. Slave Transmitter with Multiple Data Bytes Figure 23-9. Timing Relationship between TWCK, SR.NAK, and SR.BTF 23.8.4 Slave Receiver Mode If the TWIS matches an address in which the R/W bit in the TWI address phase transfer is cleared, it will enter slave receiver mode and clear SR.TRA (note that SR.TRA is cleared one CLK_TWIS cycle after the relevant address match bit in the same register is set). After the address phase, the following is repeated: 1. If SMBus mode and PEC is used, NBYTES must be set up with the number of bytes to receive. This is necessary in order to know which of the received bytes is the PEC byte. NBYTES can also be used to count the number of bytes received if using DMA. 2. Receive a byte. Set SR.BTF when done. 3. Update NBYTES. If CR.CUP is written to one, NBYTES is incremented, otherwise NBYTES is decremented. NBYTES is usually configured to count downwards if PEC is used. 4. After a data byte has been received, the slave transmits an ACK or NAK bit. For ordinary data bytes, the CR.ACK field controls if an ACK or NAK should be returned. If PEC is enabled and the last byte received was a PEC byte (indicated by NBYTES equal to zero), The TWIS will automatically return an ACK if the PEC value was correct, otherwise a NAK will be returned. 5. If STOP is received, SR.TCOMP will be set. 6. If REPEATED START is received, SR.REP will be set. The TWI transfers require the receiver to acknowledge each received data byte. During the acknowledge clock pulse (9th pulse), the master releases the data line (HIGH), enabling the S DADR R DATA n+5 A P A DATA n A DATA n+m N TCOMP TXRDY Write THR (Data n) NBYTES set to m STOP sent by master TWD Write THR (Data n+1) Write THR (Data n+m) Last data sent DATA (LSB) N P TWCK SR.NAK SR.BTF t1 t1 t1: (CLK_TWIS period) x 2 TWD 570 32142D–06/2013 ATUC64/128/256L3/4U slave to pull it down in order to generate the acknowledge. The master polls the data line during this clock pulse. The SR.RXRDY bit indicates that a data byte is available in the RHR. The RXRDY bit is also used as Receive Ready for the Peripheral DMA Controller receive channel. Figure 23-10. Slave Receiver with One Data Byte Figure 23-11. Slave Receiver with Multiple Data Bytes 23.8.5 Interactive ACKing Received Data Bytes When implementing a register interface over TWI, it may sometimes be necessary or just useful to report reads and writes to invalid register addresses by sending a NAK to the host. To be able to do this, one must first receive the register address from the TWI bus, and then tell the TWIS whether to ACK or NAK it. In normal operation of the TWIS, this is not possible because the controller will automatically ACK the byte at about the same time as the RXRDY bit changes from zero to one. Writing a one to the Stretch on Data Byte Received bit (CR.SODR) will stretch the clock allowing the user to update CR.ACK bit before returning the desired value. After the last bit in the data byte is received, the TWI bus clock is stretched, the received data byte is transferred to the RHR register, and SR.BTF is set. At this time, the user can examine the received byte and write the desired ACK or NACK value to CR.ACK. When the user clears SR.BTF, the desired ACK value is transferred on the TWI bus. This makes it possible to look at the byte received, determine if it is valid, and then decide to ACK or NAK it. 23.8.6 Using the Peripheral DMA Controller The use of the Peripheral DMA Controller significantly reduces the CPU load. The user can set up ring buffers for the Peripheral DMA Controller, containing data to transmit or free buffer space to place received data. By initializing NBYTES to zero before a transfer, and writing a one to CR.CUP, NBYTES is incremented by one each time a data has been transmitted or received. This allows the user to detect how much data was actually transferred by the DMA system. S DADR W DATA A P A TCOMP RXRDY Read RHR TWD TWD S DADR W DATA n A A A DATA (n+1) A DATA (n+m) DATA (n+m)-1 P A TCOMP RXRDY Read RHR DATA n Read RHR DATA (n+1) Read RHR DATA (n+m)-1 Read RHR DATA (n+m) 571 32142D–06/2013 ATUC64/128/256L3/4U To assure correct behavior, respect the following programming sequences: 23.8.6.1 Data Transmit with the Peripheral DMA Controller 1. Initialize the transmit Peripheral DMA Controller (memory pointers, size, etc.). 2. Configure the TWIS (ADR, NBYTES, etc.). 3. Start the transfer by enabling the Peripheral DMA Controller to transmit. 4. Wait for the Peripheral DMA Controller end-of-transmit flag. 5. Disable the Peripheral DMA Controller. 23.8.6.2 Data Receive with the Peripheral DMA Controller 1. Initialize the receive Peripheral DMA Controller (memory pointers, size - 1, etc.). 2. Configure the TWIS (ADR, NBYTES, etc.). 3. Start the transfer by enabling the Peripheral DMA Controller to receive. 4. Wait for the Peripheral DMA Controller end-of-receive flag. 5. Disable the Peripheral DMA Controller. 23.8.7 SMBus Mode SMBus mode is enabled by writing a one to the SMBus Mode Enable (SMEN) bit in CR. SMBus mode operation is similar to I²C operation with the following exceptions: • Only 7-bit addressing can be used. • The SMBus standard describes a set of timeout values to ensure progress and throughput on the bus. These timeout values must be written to TR. • Transmissions can optionally include a CRC byte, called Packet Error Check (PEC). • A dedicated bus line, SMBALERT, allows a slave to get a master’s attention. • A set of addresses have been reserved for protocol handling, such as Alert Response Address (ARA) and Host Header (HH) Address. Address matching on these addresses can be enabled by configuring CR appropriately. 23.8.7.1 Packet Error Checking (PEC) Each SMBus transfer can optionally end with a CRC byte, called the PEC byte. Writing a one to the Packet Error Checking Enable (PECEN) bit in CR enables automatic PEC handling in the current transfer. The PEC generator is always updated on every bit transmitted or received, so that PEC handling on following linked transfers will be correct. In slave receiver mode, the master calculates a PEC value and transmits it to the slave after all data bytes have been transmitted. Upon reception of this PEC byte, the slave will compare it to the PEC value it has computed itself. If the values match, the data was received correctly, and the slave will return an ACK to the master. If the PEC values differ, data was corrupted, and the slave will return a NAK value. The SR.SMBPECERR bit is set automatically if a PEC error occurred. In slave transmitter mode, the slave calculates a PEC value and transmits it to the master after all data bytes have been transmitted. Upon reception of this PEC byte, the master will compare it to the PEC value it has computed itself. If the values match, the data was received correctly. If the PEC values differ, data was corrupted, and the master must take appropriate action. The PEC byte is automatically inserted in a slave transmitter transmission if PEC enabled when NBYTES reaches zero. The PEC byte is identified in a slave receiver transmission if PEC 572 32142D–06/2013 ATUC64/128/256L3/4U enabled when NBYTES reaches zero. NBYTES must therefore be set to the total number of data bytes in the transmission, including the PEC byte. 23.8.7.2 Timeouts The Timing Register (TR) configures the SMBus timeout values. If a timeout occurs, the slave will leave the bus. The SR.SMBTOUT bit is also set. 23.8.7.3 SMBALERT A slave can get the master’s attention by pulling the SMBALERT line low. This is done by writing a one to the SMBus Alert (SMBALERT) bit in CR. This will also enable address match on the Alert Response Address (ARA). 23.8.8 Wakeup from Sleep Modes by TWI Address Match The TWIS is able to wake the device up from a sleep mode upon an address match, including sleep modes where CLK_TWIS is stopped. After detecting the START condition on the bus, The TWIS will stretch TWCK until CLK_TWIS has started. The time required for starting CLK_TWIS depends on which sleep mode the device is in. After CLK_TWIS has started, the TWIS releases its TWCK stretching and receives one byte of data on the bus. At this time, only a limited part of the device, including the TWIS, receives a clock, thus saving power. The TWIS goes on to receive the slave address. If the address phase causes a TWIS address match, the entire device is wakened and normal TWIS address matching actions are performed. Normal TWI transfer then follows. If the TWIS is not addressed, CLK_TWIS is automatically stopped and the device returns to its original sleep mode. 23.8.9 Identifying Bus Events This chapter lists the different bus events, and how these affects the bits in the TWIS registers. This is intended to help writing drivers for the TWIS. Table 23-5. Bus Events Event Effect Slave transmitter has sent a data byte SR.THR is cleared. SR.BTF is set. The value of the ACK bit sent immediately after the data byte is given by CR.ACK. Slave receiver has received a data byte SR.RHR is set. SR.BTF is set. SR.NAK updated according to value of ACK bit received from master. Start+Sadr on bus, but address is to another slave None. Start+Sadr on bus, current slave is addressed, but address match enable bit in CR is not set None. Start+Sadr on bus, current slave is addressed, corresponding address match enable bit in CR set Correct address match bit in SR is set. SR.TRA updated according to transfer direction (updating is done one CLK_TWIS cycle after address match bit is set) Slave enters appropriate transfer direction mode and data transfer can commence. 573 32142D–06/2013 ATUC64/128/256L3/4U Start+Sadr on bus, current slave is addressed, corresponding address match enable bit in CR set, SR.STREN and SR.SOAM are set. Correct address match bit in SR is set. SR.TRA updated according to transfer direction (updating is done one CLK_TWIS cycle after address match bit is set). Slave stretches TWCK immediately after transmitting the address ACK bit. TWCK remains stretched until all address match bits in SR have been cleared. Slave enters appropriate transfer direction mode and data transfer can commence. Repeated Start received after being addressed SR.REP set. SR.TCOMP unchanged. Stop received after being addressed SR.STO set. SR.TCOMP set. Start, Repeated Start, or Stop received in illegal position on bus SR.BUSERR set. SR.STO and SR.TCOMP may or may not be set depending on the exact position of an illegal stop. Data is to be received in slave receiver mode, SR.STREN is set, and RHR is full TWCK is stretched until RHR has been read. Data is to be transmitted in slave receiver mode, SR.STREN is set, and THR is empty TWCK is stretched until THR has been written. Data is to be received in slave receiver mode, SR.STREN is cleared, and RHR is full TWCK is not stretched, read data is discarded. SR.ORUN is set. Data is to be transmitted in slave receiver mode, SR.STREN is cleared, and THR is empty TWCK is not stretched, previous contents of THR is written to bus. SR.URUN is set. SMBus timeout received SR.SMBTOUT is set. TWCK and TWD are immediately released. Slave transmitter in SMBus PEC mode has transmitted a PEC byte, that was not identical to the PEC calculated by the master receiver. Master receiver will transmit a NAK as usual after the last byte of a master receiver transfer. Master receiver will retry the transfer at a later time. Slave receiver discovers SMBus PEC Error SR.SMBPECERR is set. NAK returned after the data byte. Table 23-5. Bus Events Event Effect 574 32142D–06/2013 ATUC64/128/256L3/4U 23.9 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 23-6. TWIS Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Read/Write 0x00000000 0x04 NBYTES Register NBYTES Read/Write 0x00000000 0x08 Timing Register TR Read/Write 0x00000000 0x0C Receive Holding Register RHR Read-only 0x00000000 0x10 Transmit Holding Register THR Write-only 0x00000000 0x14 Packet Error Check Register PECR Read-only 0x00000000 0x18 Status Register SR Read-only 0x00000002 0x1C Interrupt Enable Register IER Write-only 0x00000000 0x20 Interrupt Disable Register IDR Write-only 0x00000000 0x24 Interrupt Mask Register IMR Read-only 0x00000000 0x28 Status Clear Register SCR Write-only 0x00000000 0x2C Parameter Register PR Read-only -(1) 0x30 Version Register VR Read-only -(1) 575 32142D–06/2013 ATUC64/128/256L3/4U 23.9.1 Control Register Name: CR Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • TENBIT: Ten Bit Address Match 0: Disables Ten Bit Address Match. 1: Enables Ten Bit Address Match. • ADR: Slave Address Slave address used in slave address match. Bits 9:0 are used if in 10-bit mode, bits 6:0 otherwise. • SODR: Stretch Clock on Data Byte Reception 0: Does not stretch bus clock immediately before ACKing a received data byte. 1: Stretches bus clock immediately before ACKing a received data byte. • SOAM: Stretch Clock on Address Match 0: Does not stretch bus clock after address match. 1: Stretches bus clock after address match. • CUP: NBYTES Count Up 0: Causes NBYTES to count down (decrement) per byte transferred. 1: Causes NBYTES to count up (increment) per byte transferred. • ACK: Slave Receiver Data Phase ACK Value 0: Causes a low value to be returned in the ACK cycle of the data phase in slave receiver mode. 1: Causes a high value to be returned in the ACK cycle of the data phase in slave receiver mode. • PECEN: Packet Error Checking Enable 0: Disables SMBus PEC (CRC) generation and check. 1: Enables SMBus PEC (CRC) generation and check. • SMHH: SMBus Host Header 0: Causes the TWIS not to acknowledge the SMBus Host Header. 1: Causes the TWIS to acknowledge the SMBus Host Header. • SMDA: SMBus Default Address 0: Causes the TWIS not to acknowledge the SMBus Default Address. 1: Causes the TWIS to acknowledge the SMBus Default Address. • SMBALERT: SMBus Alert 0: Causes the TWIS to release the SMBALERT line and not to acknowledge the SMBus Alert Response Address (ARA). 1: Causes the TWIS to pull down the SMBALERT line and to acknowledge the SMBus Alert Response Address (ARA). 31 30 29 28 27 26 25 24 - - - - - TENBIT ADR[9:8] 23 22 21 20 19 18 17 16 ADR[7:0] 15 14 13 12 11 10 9 8 SODR SOAM CUP ACK PECEN SMHH SMDA SMBALERT 76543210 SWRST - - STREN GCMATCH SMATCH SMEN SEN 576 32142D–06/2013 ATUC64/128/256L3/4U • SWRST: Software Reset This bit will always read as 0. Writing a zero to this bit has no effect. Writing a one to this bit resets the TWIS. • STREN: Clock Stretch Enable 0: Disables clock stretching if RHR/THR buffer full/empty. May cause over/underrun. 1: Enables clock stretching if RHR/THR buffer full/empty. • GCMATCH: General Call Address Match 0: Causes the TWIS not to acknowledge the General Call Address. 1: Causes the TWIS to acknowledge the General Call Address. • SMATCH: Slave Address Match 0: Causes the TWIS not to acknowledge the Slave Address. 1: Causes the TWIS to acknowledge the Slave Address. • SMEN: SMBus Mode Enable 0: Disables SMBus mode. 1: Enables SMBus mode. • SEN: Slave Enable 0: Disables the slave interface. 1: Enables the slave interface. 577 32142D–06/2013 ATUC64/128/256L3/4U 23.9.2 NBYTES Register Name: NBYTES Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • NBYTES: Number of Bytes to Transfer Writing to this field updates the NBYTES counter. The field can also be read to learn the progress of the transfer. NBYTES can be incremented or decremented automatically by hardware. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 NBYTES 578 32142D–06/2013 ATUC64/128/256L3/4U 23.9.3 Timing Register Name: TR Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • EXP: Clock Prescaler Used to specify how to prescale the SMBus TLOWS counter. The counter is prescaled according to the following formula: • SUDAT: Data Setup Cycles Non-prescaled clock cycles for data setup count. Used to time TSU_DAT. Data is driven SUDAT cycles after TWCK low detected. This timing is used for timing the ACK/NAK bits, and any data bits driven in slave transmitter mode. • TTOUT: SMBus TTIMEOUT Cycles Prescaled clock cycles used to time SMBus TTIMEOUT. • TLOWS: SMBus TLOW:SEXT Cycles Prescaled clock cycles used to time SMBus TLOW:SEXT. 31 30 29 28 27 26 25 24 EXP - - - - 23 22 21 20 19 18 17 16 SUDAT 15 14 13 12 11 10 9 8 TTOUT 76543210 TLOWS f PRESCALED f CLK_TWIS 2  EXP 1 + = ------------------------ 579 32142D–06/2013 ATUC64/128/256L3/4U 23.9.4 Receive Holding Register Name: RHR Access Type: Read-only Offset: 0x0C Reset Value: 0x00000000 • RXDATA: Received Data Byte When the RXRDY bit in the Status Register (SR) is one, this field contains a byte received from the TWI bus. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RXDATA 580 32142D–06/2013 ATUC64/128/256L3/4U 23.9.5 Transmit Holding Register Name: THR Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 • TXDATA: Data Byte to Transmit Write data to be transferred on the TWI bus here. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 TXDATA 581 32142D–06/2013 ATUC64/128/256L3/4U 23.9.6 Packet Error Check Register Name: PECR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 • PEC: Calculated PEC Value The calculated PEC value. Updated automatically by hardware after each byte has been transferred. Reset by hardware after a STOP condition. Provided if the user manually wishes to control when the PEC byte is transmitted, or wishes to access the PEC value for other reasons. In ordinary operation, the PEC handling is done automatically by hardware. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 PEC 582 32142D–06/2013 ATUC64/128/256L3/4U 23.9.7 Status Register Name: SR Access Type: Read-only Offset: 0x18 Reset Value: 0x000000002 • BTF: Byte Transfer Finished This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when byte transfer has completed. • REP: Repeated Start Received This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a REPEATED START condition is received. • STO: Stop Received This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the STOP condition is received. • SMBDAM: SMBus Default Address Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the SMBus Default Address. • SMBHHM: SMBus Host Header Address Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the SMBus Host Header Address. • SMBALERTM: SMBus Alert Response Address Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the SMBus Alert Response Address. • GCM: General Call Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the General Call Address. • SAM: Slave Address Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the Slave Address. • BUSERR: Bus Error This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a misplaced START or STOP condition has occurred. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN TRA - TCOMP SEN TXRDY RXRDY 583 32142D–06/2013 ATUC64/128/256L3/4U • SMBPECERR: SMBus PEC Error This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a SMBus PEC error has occurred. • SMBTOUT: SMBus Timeout This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a SMBus timeout has occurred. • NAK: NAK Received This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a NAK was received from the master during slave transmitter operation. • ORUN: Overrun This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when an overrun has occurred in slave receiver mode. Can only occur if CR.STREN is zero. • URUN: Underrun This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when an underrun has occurred in slave transmitter mode. Can only occur if CR.STREN is zero. • TRA: Transmitter Mode 0: The slave is in slave receiver mode. 1: The slave is in slave transmitter mode. • TCOMP: Transmission Complete This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when transmission is complete. Set after receiving a STOP after being addressed. • SEN: Slave Enabled 0: The slave interface is disabled. 1: The slave interface is enabled. • TXRDY: TX Buffer Ready 0: The TX buffer is full and should not be written to. 1: The TX buffer is empty, and can accept new data. • RXRDY: RX Buffer Ready 0: No RX data ready in RHR. 1: RX data is ready to be read from RHR. 584 32142D–06/2013 ATUC64/128/256L3/4U 23.9.8 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x1C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will write a one to the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN - - TCOMP - TXRDY RXRDY 585 32142D–06/2013 ATUC64/128/256L3/4U 23.9.9 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN - - TCOMP - TXRDY RXRDY 586 32142D–06/2013 ATUC64/128/256L3/4U 23.9.10 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x24 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN - - TCOMP - TXRDY RXRDY 587 32142D–06/2013 ATUC64/128/256L3/4U 23.9.11 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x28 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN - - TCOMP - - - 588 32142D–06/2013 ATUC64/128/256L3/4U 23.9.12 Parameter Register Name: PR Access Type: Read-only Offset: 0x2C Reset Value: - 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 589 32142D–06/2013 ATUC64/128/256L3/4U 23.9.13 Version Register (VR) Name: VR Access Type: Read-only Offset: 0x30 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION [11:8] 76543210 VERSION [7:0] 590 32142D–06/2013 ATUC64/128/256L3/4U 23.10 Module Configuration The specific configuration for each TWIS instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 23-7. Module Clock Name Module Name Clock Name Description TWIS0 CLK_TWIS0 Clock for the TWIS0 bus interface TWIS1 CLK_TWIS1 Clock for the TWIS1 bus interface Table 23-8. Register Reset Values Register Reset Value VERSION 0x00000120 PARAMETER 0x00000000 591 32142D–06/2013 ATUC64/128/256L3/4U 24. Inter-IC Sound Controller (IISC) Rev: 1.0.0.0 24.1 Features • Compliant with Inter-IC Sound (I2 S) bus specification • Master, slave, and controller modes: – Slave: data received/transmitted – Master: data received/transmitted and clocks generated – Controller: clocks generated • Individual enable and disable of receiver, transmitter, and clocks • Configurable clock generator common to receiver and transmitter: – Suitable for a wide range of sample frequencies (fs), including 32kHz, 44.1kHz, 48kHz, 88.2kHz, 96kHz, and 192kHz – 16fs to 1024fs Master Clock generated for external oversampling ADCs • Several data formats supported: – 32-, 24-, 20-, 18-, 16-, and 8-bit mono or stereo format – 16- and 8-bit compact stereo format, with left and right samples packed in the same word to reduce data transfers • DMA interfaces for receiver and transmitter to reduce processor overhead: – Either one DMA channel for both audio channels, or – One DMA channel per audio channel • Smart holding registers management to avoid audio channels mix after overrun or underrun 24.2 Overview The Inter-IC Sound Controller (IISC) provides a 5-wire, bidirectional, synchronous, digital audio link with external audio devices: ISDI, ISDO, IWS, ISCK, and IMCK pins. This controller is compliant with the Inter-IC Sound (I2 S) bus specification. The IISC consists of a Receiver, a Transmitter, and a common Clock Generator, that can be enabled separately, to provide Master, Slave, or Controller modes with Receiver, Transmitter, or both active. Peripheral DMA channels, separate for the Receiver and for the Transmitter, allow a continuous high bitrate data transfer without processor intervention to the following: • Audio CODECs in Master, Slave, or Controller mode • Stereo DAC or ADC through dedicated I2 S serial interface The IISC can use either a single DMA channel for both audio channels or one DMA channel per audio channel. The 8- and 16-bit compact stereo format allows reducing the required DMA bandwidth by transferring the left and right samples within the same data word. In Master Mode, the IISC allows outputting a 16 fs to 1024fs Master Clock, in order to provide an oversampling clock to an external audio codec or digital signal processor (DSP). 592 32142D–06/2013 ATUC64/128/256L3/4U 24.3 Block Diagram Figure 24-1. IISC Block Diagram 24.4 I/O Lines Description 24.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 24.5.1 I/O lines The IISC pins may be multiplexed with I/O Controller lines. The user must first program the I/O Controller to assign the desired IISC pins to their peripheral function. If the IISC I/O lines are not used by the application, they can be used for other purposes by the I/O Controller. It is required to enable only the IISC inputs and outputs actually in use. 24.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the IISC, the IISC will stop functioning and resume operation after the system wakes up from sleep mode.I/O Controller ISCK IWS ISDI ISDO IMCK Receiver Clocks Transmitter Peripheral Bus interface Generic clock PB Peripheral Bus Bridge Interrupt Controller SCIF Power Manager PB clock IRQ Peripheral DMA Controller Rx Tx IISC Table 24-1. I/O Lines Description Pin Name Pin Description Type IMCK Master Clock Output ISCK Serial Clock Input/Output IWS I2 S Word Select Input/Output ISDI Serial Data Input Input ISDO Serial Data Output Output 593 32142D–06/2013 ATUC64/128/256L3/4U 24.5.3 Clocks The clock for the IISC bus interface (CLK_IISC) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the IISC before disabling the clock, to avoid freezing the IISC in an undefined state. One of the generic clocks is connected to the IISC. The generic clock (GCLK_IISC) can be set to a wide range of frequencies and clock sources. The GCLK_IISC must be enabled and configured before use. Refer to the module configuration section for details on the GCLK_IISC used for the IISC. The frequency for this clock has to be set as described in Table. 24.5.4 DMA The IISC DMA handshake interfaces are connected to the Peripheral DMA Controller. Using the IISC DMA functionality requires the Peripheral DMA Controller to be programmed first. 24.5.5 Interrupts The IISC interrupt line is connected to the Interrupt Controller. Using the IISC interrupt requires the Interrupt Controller to be programmed first. 24.5.6 Debug Operation When an external debugger forces the CPU into debug mode, the IISC continues normal operation. If this module is configured in a way that requires it to be periodically serviced by the CPU through interrupt requests or similar, improper operation or data loss may result during debugging. 24.6 Functional Description 24.6.1 Initialization The IISC features a Receiver, a Transmitter, and, for Master and Controller modes, a Clock Generator. Receiver and Transmitter share the same Serial Clock and Word Select. Before enabling the IISC, the chosen configuration must be written to the Mode Register (MR). The IMCKMODE, MODE, and DATALENGTH fields in the MR register must be written. If the IMCKMODE field is written as one, then the IMCKFS field should be written with the chosen ratio, as described in Section 24.6.5 ”Serial Clock and Word Select Generation” on page 595. Once the Mode Register has been written, the IISC Clock Generator, Receiver, and Transmitter can be enabled by writing a one to the CKEN, RXEN, and TXEN bits in the Control Register (CR). The Clock Generator can be enabled alone, in Controller Mode, to output clocks to the IMCK, ISCK, and IWS pins. The Clock Generator must also be enabled if the Receiver or the Transmitter is enabled. The Clock Generator, Receiver, and Transmitter can be disabled independently by writing a one to CR.CXDIS, CR.RXDIS and/or CR.TXDIS respectively. Once requested to stop, they will only stop when the transmission of the pending frame transmission will be completed. 24.6.2 Basic Operation The Receiver can be operated by reading the Receiver Holding Register (RHR), whenever the Receive Ready (RXRDY) bit in the Status Register (SR) is set. Successive values read from RHR will correspond to the samples from the left and right audio channels for the successive frames. 594 32142D–06/2013 ATUC64/128/256L3/4U The Transmitter can be operated by writing to the Transmitter Holding Register (RHR), whenever the Transmit Ready (TXRDY) bit in the Status Register (SR) is set. Successive values written to THR should correspond to the samples from the left and right audio channels for the successive frames. The Receive Ready and Transmit Ready bits can be polled by reading the Status Register. The IISC processor load can be reduced by enabling interrupt-driven operation. The RXRDY and/or TXRDY interrupt requests can be enabled by writing a one to the corresponding bit in the Interrupt Enable Register (IER). The interrupt service routine associated to the IISC interrupt request will then be executed whenever the Receive Ready or the Transmit Ready status bit is set. 24.6.3 Master, Controller, and Slave Modes In Master and Controller modes, the IISC provides the Master Clock, the Serial Clock and the Word Select. IMCK, ISCK, and IWS pins are outputs. In Controller mode, the IISC Receiver and Transmitter are disabled. Only the clocks are enabled and used by an external receiver and/or transmitter. In Slave mode, the IISC receives the Serial Clock and the Word Select from an external master. ISCK and IWS pins are inputs. The mode is selected by writing the MODE field of the Mode Register (MR). Since the MODE field changes the direction of the IWS and ISCK pins, the Mode Register should only be written when the IISC is stopped, in order to avoid unwanted glitches on the IWS and ISCK pins. 24.6.4 I2 S Reception and Transmission Sequence As specified in the I2 S protocol, data bits are left-adjusted in the Word Select time slot, with the MSB transmitted first, starting one clock period after the transition on the Word Select line. Figure 24-2. I 2 S Reception and Transmission Sequence Data bits are sent on the falling edge of the Serial Clock and sampled on the rising edge of the Serial Clock. The Word Select line indicates the channel in transmission, a low level for the left channel and a high level for the right channel. The length of transmitted words can be chosen among 8, 16, 18, 20, 24, and 32 bits by writing the MR.DATALENGTH field. If the time slot allows for more data bits than written in the MR.DATALENGTH field, zeroes are appended to the transmitted data word or extra received bits are discarded. If the time slot allows for less data bits than written, the extra bits to be transmitted are not sent or the missing bits are set to zero in the received data word. Serial Clock ISCK Word Select IWS Data ISDI/ISDO MSB Left Channel LSB MSB Right Channel 595 32142D–06/2013 ATUC64/128/256L3/4U 24.6.5 Serial Clock and Word Select Generation The generation of clocks in the IISC is described in Figure 24-3 on page 596. In Slave mode, the Serial Clock and Word Select Clock are driven by an external master. ISCK and IWS pins are inputs and no generic clock is required by the IISC. In Master mode, the user can configure the Master Clock, Serial Clock, and Word Select Clock through the Mode Register (MR). IMCK, ISCK, and IWS pins are outputs and a generic clock is used to derive the IISC clocks. Audio codecs connected to the IISC pins may require a Master Clock signal with a frequency multiple of the audio sample frequency (fs), such as 256fs. When the IISC is in Master mode, writing a one to MR.IMCKMODE will output GCLK_IISC as Master Clock to the IMCK pin, and will divide GCLK_IISC to create the internal bit clock, output on the ISCK pin. The clock division factor is defined by writing to MR.IMCKFS and MR.DATALENGTH, as described ”IMCKFS: Master Clock to fs Ratio” on page 602. The Master Clock (IMCK) frequency is 16*(IMCKFS+1) times the sample frequency (fs), i.e. IWS frequency. The Serial Clock (ISCK) frequency is 2*Slot Length times the sample frequency (fs), where Slot Length is defined in Table 24-2 on page 595. Warning: MR.IMCKMODE should only be written as one if the Master Clock frequency is strictly higher than the Serial Clock. If a Master Clock output is not required, the GCLK_IISC generic clock is used as ISCK, by writing a zero to MR.IMCKMODE. Alternatively, if the frequency of the generic clock used is a multiple of the required ISCK frequency, the IMCK to ISCK divider can be used with the ratio defined by writing the MR.IMCKFS field. The IWS pin is used as Word Select as described in Section 24.6.4. Table 24-2. Slot Length MR.DATALENGTH Word Length Slot Length 0 32 bits 32 1 24 bits 32 if MR.IWS24 is zero 24 if MR.IWS24 is one 2 20 bits 3 18 bits 4 16 bits 16 5 16 bits compact stereo 6 8 bits 8 7 8 bits compact stereo 596 32142D–06/2013 ATUC64/128/256L3/4U Figure 24-3. IISC Clocks Generation 24.6.6 Mono When the Transmit Mono (TXMONO) in the Mode Register is set, data written to the left channel is duplicated to the right output channel. When the Receive Mono (RXMONO) in the Mode Register is set, data received from the left channel is duplicated to the right channel. 24.6.7 Holding Registers The IISC user interface includes a Receive Holding Register (RHR) and a Transmit Holding Register (THR). RHR and THR are used to access audio samples for both audio channels. When a new data word is available in the RHR register, the Receive Ready bit (RXRDY) in the Status Register (SR) is set. Reading the RHR register will clear this bit. A receive overrun condition occurs if a new data word becomes available before the previous data word has been read from the RHR register. Then, the Receive Overrun bit in the Status Register will be set and bit i of the RXORCH field in the Status Register is set, where i is the current receive channel number. When the THR register is empty, the Transmit Ready bit (TXRDY) in the Status Register (SR) is set. Writing into the THR register will clear this bit. A transmit underrun condition occurs if a new data word needs to be transmitted before it has been written to the THR register. Then, the Transmit Underrun bit in the Status Register will be set and bit i of the TXORCH field in the Status Register is set, where i is the current transmit channel number. If the TXSAME bit in the Mode Register is zero, then a zero data word is transmitted in case of underrun. If MR.TXSAME is one, then the previous data word for the current transmit channel number is transmitted. MR.MODE = SLAVE Clock divider MR.DATALENGTH GCLK_IISC Clock enable Clock divider CR.CKEN/CKDIS MR.IMCKMODE MR.DATALENGTH MR.IMCKFS MR.IMCKMODE 0 1 IMCK pin output Clock enable CR.CKEN/CKDIS Internal bit clock ISCK pin input 1 0 ISCK pin output Internal word clock IWS pin input 1 0 IWS pin output 597 32142D–06/2013 ATUC64/128/256L3/4U Data words are right-justified in the RHR and THR registers. For 16-bit compact stereo, the left sample uses bits 15 through 0 and the right sample uses bits 31 through 16 of the same data word. For 8-bit compact stereo, the left sample uses bits 7 through 0 and the right sample uses bits 15 through 8 of the same data word. 24.6.8 DMA Operation The Receiver and the Transmitter can each be connected either to one single Peripheral DMA channel or to one Peripheral DMA channel per data channel. This is selected by writing to the MR.RXDMA and MR.TXDMA bits. If a single Peripheral DMA channel is selected, all data samples use IISC Receiver or Transmitter DMA channel 0. The Peripheral DMA reads from the RHR register and writes to the RHR register for both audio channels, successively. The Peripheral DMA transfers may use 32-bit word, 16-bit halfword, or 8-bit byte according to the value of the MR.DATALENGTH field. 24.6.9 Loop-back Mode For debugging purposes, the IISC can be configured to loop back the Transmitter to the Receiver. Writing a one to the MR.LOOP bit will internally connect ISDO to ISDI, so that the transmitted data is also received. Writing a zero to MR.LOOP will restore the normal behavior with independent Receiver and Transmitter. As for other changes to the Receiver or Transmitter configuration, the IISC Receiver and Transmitter must be disabled before writing to the MR register to update MR.LOOP. 24.6.10 Interrupts An IISC interrupt request can be triggered whenever one or several of the following bits are set in the Status Register (SR): Receive Ready (RXRDY), Receive Overrun (RXOR), Transmit Ready (TXRDY), or Transmit Underrun (TXOR). The interrupt request will be generated if the corresponding bit in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in SR is cleared by writing a one the corresponding bit in the Status Clear Register (SCR). For debugging purposes, interrupt requests can be simulated by writing a one to the corresponding bit in the Status Set Register (SSR). 598 32142D–06/2013 ATUC64/128/256L3/4U Figure 24-4. Interrupt Block Diagram 24.7 IISC Application Examples The IISC can support several serial communication modes used in audio or high-speed serial links. Some standard applications are shown in the following figures. All serial link applications supported by the IISC are not listed here. Figure 24-5. Audio Application Block Diagram IER IDR IMR Set Clear Interrupt Control IISC Interrupt Request TXRDY TXUR Transmitter Receiver RXRDY RXOR Serial Clock Word Select Serial Data Out MSB LSB MSB Serial Data Out Word Select Serial Clock IISC ISCK IWS ISDO ISDI EXTERNAL I 2 S RECEIVER 599 32142D–06/2013 ATUC64/128/256L3/4U Figure 24-6. Codec Application Block Diagram Figure 24-7. Time Slot Application Block Diagram IISC Word Select Serial Data Out Serial Data In EXTERNAL AUDIO CODEC IMCK IWS ISDO ISDI Serial Clock Master Clock ISCK Right Time Slot Serial Clock Word Select Serial Data Out Serial Data In Dstart Dend Left Time Slot EXTERNAL AUDIO CODEC for Left Time Slot EXTERNAL AUDIO CODEC for Right Time Slot Serial Data In Serial Data Out Word Select Serial Clock Serial Clock Word Select Serial Data Out Serial Data In Dstart Left Time Slot Right Time Slot Dend IISC ISCK IWS ISDO ISDI Master Clock IMCK 600 32142D–06/2013 ATUC64/128/256L3/4U 24.8 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 24-3. IISC Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Write-only 0x00000000 0x04 Mode Register MR Read/Write 0x00000000 0x08 Status Register SR Read-only 0x00000000 0x0C Status Clear Register SCR Write-only 0x00000000 0x10 Status Set Register SSR Write-only 0x00000000 0x14 Interrupt Enable Register IER Write-only 0x00000000 0x18 Interrupt Disable Register IDR Write-only 0x00000000 0x1C Interrupt Mask Register IMR Read-only 0x00000000 0x20 Receiver Holding Register RHR Read-only 0x00000000 0x24 Transmitter Holding Register THR Write-only 0x00000000 0x28 Version Register VERSION Read-only - (1) 0x2C Parameter Register PARAMETER Read-only - (1) 601 32142D–06/2013 ATUC64/128/256L3/4U 24.8.1 Control Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 The Control Register should only be written to enable the IISC after the chosen configuration has been written to the Mode Register, in order to avoid unwanted glitches on the IWS, ISCK, and ISDO outputs. The proper sequence is to write the MR register, then write the CR register to enable the IISC, or to disable the IISC before writing a new value into MR. • SWRST: Software Reset Writing a zero to this bit has no effect. Writing a one to this bit resets all the registers in the module. The module will be disabled after the reset. This bit always reads as zero. • TXDIS: Transmitter Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the IISC Transmitter. SR.TXEN will be cleared when the Transmitter is effectively stopped. • TXEN: Transmitter Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the IISC Transmitter, if TXDIS is not one. SR.TXEN will be set when the Transmitter is effectively started. • CKDIS: Clocks Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the IISC clocks generation. • CKEN: Clocks Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the IISC clocks generation, if CKDIS is not one. • RXDIS: Receiver Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the IISC Receiver. SR.TXEN will be cleared when the Transmitter is effectively stopped. • RXEN: Receiver Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the IISC Receiver, if RXDIS is not one. SR.RXEN will be set when the Receiver is effectively started. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 SWRST - TXDIS TXEN CKDIS CKEN RXDIS RXEN 602 32142D–06/2013 ATUC64/128/256L3/4U 24.8.2 Mode Register Name: MR Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 The Mode Register should only be written when the IISC is stopped, in order to avoid unwanted glitches on the IWS, ISCK, and ISDO outputs. The proper sequence is to write the MR register, then write the CR register to enable the IISC, or to disable the IISC before writing a new value into MR. • IWS24: IWS TDM Slot Width 0: IWS slot is 32-bit wide for DATALENGTH=18/20/24-bit 1: IWS slot is 24-bit wide for DATALENGTH=18/20/24-bit Refer to Table 24-2, “Slot Length,” on page 595. • IMCKMODE: Master Clock Mode 0: No Master Clock generated (generic clock is used as ISCK output) 1: Master Clock generated (generic clock is used as IMCK output) Warning: if IMCK frequency is the same as ISCK, IMCKMODE should not be written as one. Refer to Section 24.6.5 ”Serial Clock and Word Select Generation” on page 595 and Table 24-2, “Slot Length,” on page 595. • IMCKFS: Master Clock to fs Ratio Master Clock frequency is 16*(IMCKFS+1) times the sample rate, i.e. IWS frequency: 31 30 29 28 27 26 25 24 IWS24 IMCKMODE IMCKFS 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - TXSAME TXDMA TXMONO RXLOOP RXDMA RXMONO 76543210 - - - DATALENGTH - MODE Table 24-4. Master Clock to Sample Frequency (fs) Ratio fs Ratio IMCKFS 16 fs 0 32 fs 1 48fs 2 64 fs 3 96fs 5 128 fs 7 192fs 11 256 fs 15 603 32142D–06/2013 ATUC64/128/256L3/4U • TXSAME: Transmit Data when Underrun 0: Zero sample transmitted when underrun 1: Previous sample transmitted when underrun • TXDMA: Single or multiple DMA Channels for Transmitter 0: Transmitter uses a single DMA channel for both audio channels 1: Transmitter uses one DMA channel per audio channel • TXMONO: Transmit Mono 0: Stereo 1: Mono, with left audio samples duplicated to right audio channel by the IISC • RXLOOP: Loop-back Test Mode 0: Normal mode 1: ISDO output of IISC is internally connected to ISDI input • RXMONO: Receive Mono 0: Stereo 1: Mono, with left audio samples duplicated to right audio channel by the IISC • RXDMA: Single or multiple DMA Channels for Receiver 0: Receiver uses a single DMA channel for both audio channels 1: Receiver uses one DMA channel per audio channel- • DATALENGTH: Data Word Length • MODE: Mode 384 fs 23 512 fs 31 768 fs 47 1024 fs 63 Table 24-5. Data Word Length DATALENGTH Word Length Comments 0 32 bits 1 24 bits 2 20 bits 3 18 bits 4 16 bits 5 16 bits compact stereo Left sample in bits 15 through 0 and right sample in bits 31 through 16 of the same word 6 8 bits 7 8 bits compact stereo Left sample in bits 7 through 0 and right sample in bits 15 through 8 of the same word Table 24-6. Mode MODE Comments 0 SLAVE ISCK and IWS pin inputs used as Bit Clock and Word Select/Frame Sync. 1 MASTER Bit Clock and Word Select/Frame Sync generated by IISC from GCLK_IISC and output to ISCK and IWS pins. GCLK_IISC is output as Master Clock on IMCK if MR.IMCKMODE is one. Table 24-4. Master Clock to Sample Frequency (fs) Ratio fs Ratio IMCKFS 604 32142D–06/2013 ATUC64/128/256L3/4U 24.8.3 Status Register Name: SR Access Type: Read-only Offset: 0x08 Reset Value: 0x00000000 • TXURCH: Transmit Underrun Channel This field is cleared when SCR.TXUR is written to one Bit i of this field is set when a transmit underrun error occurred in channel i (i=0 for first channel of the frame) • RXORCH: Receive Overrun Channel This field is cleared when SCR.RXOR is written to one Bit i of this field is set when a receive overrun error occurred in channel i (i=0 for first channel of the frame) • TXUR: Transmit Underrun This bit is cleared when the corresponding bit in SCR is written to one This bit is set when an underrun error occurs on the THR register or when the corresponding bit in SSR is written to one • TXRDY: Transmit Ready This bit is cleared when data is written to THR This bit is set when the THR register is empty and can be written with new data to be transmitted • TXEN: Transmitter Enabled This bit is cleared when the Transmitter is effectively disabled, following a CR.TXDIS or CR.SWRST request This bit is set when the Transmitter is effectively enabled, following a CR.TXEN request • RXOR: Receive Overrun This bit is cleared when the corresponding bit in SCR is written to one This bit is set when an overrun error occurs on the RHR register or when the corresponding bit in SSR is written to one • RXRDY: Receive Ready This bit is cleared when the RHR register is read This bit is set when received data is present in the RHR register • RXEN: Receiver Enabled This bit is cleared when the Receiver is effectively disabled, following a CR.RXDIS or CR.SWRST request This bit is set when the Receiver is effectively enabled, following a CR.RXEN request 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - TXURCH - - - - 15 14 13 12 11 10 9 8 - - - - - - RXORCH 76543210 - TXUR TXRDY TXEN - RXOR RXRDY RXEN 605 32142D–06/2013 ATUC64/128/256L3/4U 24.8.4 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x0C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - TXURCH - - - - 15 14 13 12 11 10 9 8 - - - - - - RXORCH 76543210 - TXUR - - - RXOR - - 606 32142D–06/2013 ATUC64/128/256L3/4U 24.8.5 Status Set Register Name: SSR Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in SR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - TXURCH - - - - 15 14 13 12 11 10 9 8 - - - - - - RXORCH 76543210 - TXUR - - - RXOR - - 607 32142D–06/2013 ATUC64/128/256L3/4U 24.8.6 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - TXUR TXRDY - - RXOR RXRDY - 608 32142D–06/2013 ATUC64/128/256L3/4U 24.8.7 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - TXUR TXRDY - - RXOR RXRDY - 609 32142D–06/2013 ATUC64/128/256L3/4U 24.8.8 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - TXUR TXRDY - - RXOR RXRDY - 610 32142D–06/2013 ATUC64/128/256L3/4U 24.8.9 Receive Holding Register Name: RHR Access Type: Read-only Offset: 0x20 Reset Value: 0x00000000 • RHR: Received Word This field is set by hardware to the last received data word. If MR.DATALENGTH specifies less than 32 bits, data shall be rightjustified into the RHR field. 31 30 29 28 27 26 25 24 RHR[31:24] 23 22 21 20 19 18 17 16 RHR[23:16] 15 14 13 12 11 10 9 8 RHR[15:8] 76543210 RHR[7:0] 611 32142D–06/2013 ATUC64/128/256L3/4U 24.8.10 Transmit Holding Register Name: THR Access Type: Write-only Offset: 0x24 Reset Value: 0x00000000 • THR: Data Word to Be Transmitted Next data word to be transmitted after the current word if TXRDY is not set. If MR.DATALENGTH specifies less than 32 bits, data shall be right-justified into the THR field. 31 30 29 28 27 26 25 24 THR[31:24] 23 22 21 20 19 18 17 16 THR[23:16] 15 14 13 12 11 10 9 8 THR[15:8] 76543210 THR[7:0] 612 32142D–06/2013 ATUC64/128/256L3/4U 24.8.11 Module Version Name: VERSION Access Type: Read-only Offset: 0x28 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 613 32142D–06/2013 ATUC64/128/256L3/4U 24.8.12 Module Parameters Name: PARAMETER Access Type: Read-only Offset: 0x2C Reset Value: - Reserved. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 614 32142D–06/2013 ATUC64/128/256L3/4U 24.9 Module configuration The specific configuration for each IISC instance is listed in the following tables. The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 24-7. IISC Clocks Clock Name Description CLK_IISC Clock for the IISC bus interface GCLK The generic clock used for the IISC is GCLK6 Table 24-8. Register Reset Values Register Reset Value VERSION 0x00000100 615 32142D–06/2013 ATUC64/128/256L3/4U 25. Pulse Width Modulation Controller (PWMA) Rev: 2.0.1.0 25.1 Features • Left-aligned non-inverted 12-bit PWM • Common 12-bit timebase counter – Asynchronous clock source supported – Spread-spectrum counter to allow a constantly varying duty cycle • Separate 12-bit duty cycle register per channel • Synchronized channel updates – No glitches when changing the duty cycles • Interlinked operation supported – Up to 32 channels can be updated with the same duty cycle value at a time – Up to 4 channels can be updated with different duty cycle values at a time • Interrupt on PWM timebase overflow • Incoming peripheral events supported – Pre-defined channels support incoming (increase/decrease) peripheral events from the Peripheral Event System – Incoming increase/decrease event can either increase or decrease the duty cycle by one • One output peripheral event supported – Connected to channel 0 and asserted when the common timebase counter is equal to the programmed duty cycle for channel 0 • Output PWM waveforms – Support normal waveform output for each channel – Support composite waveform generation (XOR’ed) for each pair channels • Open drain driving on selected pins for 5V PWM operation 25.2 Overview The Pulse Width Modulation Controller (PWMA) controls several pulse width modulation (PWM) channels. The number of channels is specific to the device. Each channel controls one square output PWM waveform. Characteristics of the output PWM waveforms such as period and duty cycle are configured through the user interface. All user interface registers are mapped on the peripheral bus. The duty cycle value for each channel can be set independently, while the period is determined by a common timebase counter (TC). The timebase for the counter is selected by using the allocated asynchronous Generic Clock (GCLK). The user interface for the PWMA contains handshake and synchronizing logic to ensure that no glitches occur on the output PWM waveforms while changing the duty cycle values. PWMA duty cycle values can be changed using two approaches, either an interlinked singlevalue mode or an interlinked multi-value mode. In the interlinked single-value mode, any set of channels, up to 32 channels, can be updated simultaneously with the same value while the other channels remain unchanged. There is also an interlinked multi-value mode, where the 8 least significant bits of up to 4 channels can be updated with 4 different values while the other channels remain unchanged. Some pins can be driven in open drain mode, allowing the PWMA to generate a 5V waveform using an external pullup resistor. 616 32142D–06/2013 ATUC64/128/256L3/4U 25.3 Block Diagram Figure 25-1. PWMA Block Diagram 25.4 I/O Lines Description Each channel outputs one PWM waveform on one external I/O line. 25.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. PWM Blocks Channel m Channel 1 Channel 0 Duty Cycle Register COMP PWMA[m:0] Interrupt Handling IRQ PB TOP Timebase Counter SPREAD Adjust TOFL READY Channel_0 CLK_PWMA GCLK Domain PB Clock Domain Spread Spectrum Counter Sync GCLK ETV Control Duty Cycle Channel Select WAVEXOR CWG TCLR CHERR Table 25-1. I/O Line Description Pin Name Pin Description Type PWMA[n] Output PWM waveform for one channel n Output PWMMOD[n] Output PWM waveform for one channel n, open drain mode Output 617 32142D–06/2013 ATUC64/128/256L3/4U 25.5.1 I/O Lines The pins used for interfacing the PWMA may be multiplexed with I/O Controller lines. The programmer must first program the I/O Controller to assign the desired PWMA pins to their peripheral function. It is only required to enable the PWMA outputs actually in use. 25.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the PWMA, the PWMA will stop functioning and resume operation after the system wakes up from sleep mode. 25.5.3 Clocks The clock for the PWMA bus interface (CLK_PWMA) is controlled by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the PWMA before disabling the clock, to avoid freezing the PWMA in an undefined state. Additionally, the PWMA depends on a dedicated Generic Clock (GCLK). The GCLK can be set to a wide range of frequencies and clock sources and must be enabled in the System Control Interface (SCIF) before the PWMA can be used. 25.5.4 Interrupts The PWMA interrupt request lines are connected to the interrupt controller. Using the PWMA interrupts requires the interrupt controller to be programmed first. 25.5.5 Peripheral Events The PWMA peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 25.5.6 Debug Operation When an external debugger forces the CPU into debug mode, the PWMA continues normal operation. If the PWMA is configured in a way that requires it to be periodically serviced by the CPU through interrupts, improper operation or data loss may result during debugging. 25.6 Functional Description The PWMA embeds a number of PWM channel submodules, each providing an output PWM waveform. Each PWM channel contains a duty cycle register and a comparator. A common timebase counter for all channels determines the frequency and the period for all the PWM waveforms. 25.6.1 Enabling the PWMA Once the GCLK has been enabled, the PWMA is enabled by writing a one to the EN bit in the Control Register (CR). 25.6.2 Timebase Counter The top value of the timebase counter defines the period of the PWMA output waveform. The timebase counter starts at zero when the PWMA is enabled and counts upwards until it reaches its effective top value (ETV). The effective top value is defined by specifying the desired number of GCLK clock cycles in the TOP field of Top Value Register (TVR.TOP) in normal operation (the 618 32142D–06/2013 ATUC64/128/256L3/4U SPREAD field of CR (CR.SPREAD) is zero). When the timebase counter reaches its effective top value, it restarts counting from zero. The period of the PWMA output waveform is then: The timebase counter can be reset by writing a one to the Timebase Clear bit in CR (CR.TCLR). Note that this can cause a glitch to the output PWM waveforms in use. 25.6.3 Spread Spectrum Counter The spread spectrum counter allows the generation of constantly varying duty cycles on the output PWM waveforms. This is achieved by varying the effective top value of the timebase counter in a range defined by the spread spectrum counter value. When CR.SPREAD is not zero, the spread spectrum counter is enabled. Its range is defined by CR.SPREAD. It starts to count from -CR.SPREAD when the PWMA is enabled or after reset and counts upwards. When it reaches CR.SPREAD, it restarts to count from -CR.SPREAD again. The spread spectrum counter will cause the effective top value to vary from TOPSPREAD to TOP+SPREAD. Figure 25-2 on page 618 illustrates this. This leads to a constantly varying duty cycle on the PWM output waveforms though the duty cycle values stored are unchanged. Figure 25-2. PWMA Adjusting Top Value for Timebase Counter 25.6.3.1 Special considerations The maximum value of the timebase counter is 0x0FFF. If SPREAD is written to a value that will cause the ETV to exceed this value, the spread spectrum counter’s range will be limited to prevent the timebase counter to exceed its maximum value. If SPREAD is written to a value causing (TOP-SPREAD) to be below zero, the spread spectrum counter’s range will be limited to prevent the timebase counter to count below zero. In both cases, the SPREAD value read from the Control Register will be the same value as written to the SPREAD field. TPWMA   ETV + 1 TGCLK =  0x0 0x0FFF Duty Cycle -SPREAD SPREAD TOP Adjusting top value range for the timerbase counter 619 32142D–06/2013 ATUC64/128/256L3/4U When writing a one to CR.TCLR, the timebase counter and the spread spectrum counter are reset at their lower limit values and the effective top value of the timebase counter will also be reset. 25.6.4 Duty Cycle and Waveform Properties Each PWM channel has its own duty cycle value (DCV) which is write-only and cannot be read out. The duty cycle value can be changed in two approaches as described in Section25.6.6. When the duty cycle value is zero, the PWM output is zero. Otherwise, the PWM output is set when the timebase counter is zero, and cleared when the timebase counter reaches the duty cycle value. This is summarized as: Note that when increasing the duty cycle value for one channel from 0 to 1, the number of GCLK cycles when the PWM waveform is high will jump from 0 to 2. When incrementing the duty cycle value by one for any other values, the number of GCLK cycle when the waveform is high will increase by one. This is summarized in Table 25-2. 25.6.5 Waveform Output PWMA waveforms are output to I/O lines. The output waveform properties are controlled by Composite Waveform Generation (CWG) register(s). If this register is cleared (by default), the channel waveforms are out directly to the I/O lines. To avoid too many I/O toggling simultaneously on the output I/O lines, every other output PWM waveform toggles on the negative edge of the GCLK instead of the positive edge. In CWG mode, all channels are paired and their outputs are XOR’ed together if the corresponding bit of CWG register is set. The even number of output is the XOR’ed output and the odd number of output is the inverse of its. Each bit of CWG register controls one pair channels and the least significant bit refers to the lowest number of pair channels. 25.6.6 Updating Duty Cycle Values 25.6.6.1 Interlinked Single Value PWM Operation The PWM channels can be interlinked to allow multiple channels to be updated simultaneously with the same duty cycle value. This value must be written to the Interlinked Single Value Duty Table 25-2. PMW Waveform Duty Cycles Duty Cycle Value #Clock Cycles When Waveform is High #Clock Cycles When Waveform is Low 0 0 ETV+1 1 2 ETV-1 2 3 ETV-2 ... ... ... ETV-1 ETV 1 ETV ETV+1 0 PWM Waveform = low when DCV = 0 or TC DCV  high when TC DCV  and DCV  0   620 32142D–06/2013 ATUC64/128/256L3/4U (ISDUTY) register. Each channel has a corresponding enabling bit in the Interlinked Single Value Channel Set (ISCHSET) register(s). When a bit is written to one in the ISCHSET register, the duty cycle register for the corresponding channel will be updated with the value stored in the ISDUTY register. It can only be updated when the READY bit in the Status Register (SR.READY) is one, indicating that the PWMA is ready for writing. Figure 25-3 on page 620 shows the writing procedure. It is thus possible to update the duty cycle values for up to 32 PWM channels within one ISCHSET register at a time. Figure 25-3. Interlinked Single Value PWM Operation Flow 25.6.6.2 Interlinked Multiple Value PWM Operation The interlinked multiple value PWM operation allows up to four channels to be updated simultaneously with different duty cycle values. The four duty cycle values are required to be written to the four registers, DUTY3, DUTY2, DUTY1 and DUTY0 , respectively. The index number of the four channels to be updated is written to the four SEL fields in the Interlinked Multiple Value Channel Select (IMCHSEL) register (IMCHSEL.SEL). When the IMCHSEL register is written, the values stored in the DUTY0/1/2/3 registers are synchronized to the duty cycle registers for the channels selected by the SEL fields. Figure 25-4 on page 620 shows the writing procedure. Note that only writes to the implemented channels will be effective. If one of the IMCHSEL.SEL fields points to a non-existing channel, the corresponding value in the DUTYx register will not be written. If the same channel is specified multiple times in the IMCHSEL.SEL fields, the channel will be updated with the value referred by the upper IMCHSEL.SEL field. When only the least significant 8-bits duty cycle value are considered for updating, the four duty cycle values can be written to the IMDUTY register once. This is equivalent to writing the four duty cycle values to the four DUTY registers one by one. Figure 25-4. Interlinked Multiple Value PWM Operation Flow ISCHSETm ... Write Enable Channeln DUTY Channel1 DUTY Channel0 DUTY ISDUTY Channel2 DUTY DUTY3/2/1/0 IMDUTY IMCHSEL Channeln DUTY ... MUX Channel1 DUTY Channel0 DUTY 621 32142D–06/2013 ATUC64/128/256L3/4U 25.6.7 Open Drain Mode Some pins can be used in open drain mode, allowing the PWMA waveform to toggle between 0V and up to 5V on these pins. In this mode the PWMA will drive the pin to zero or leave the output open. An external pullup can be used to pull the pin up to the desired voltage. To enable open drain mode on a pin the PWMAOD function must be selected instead of the PWMA function in the I/O Controller. Please refer to the Module Configuration chapter for information about which pins are available in open drain mode. 25.6.8 Synchronization Both the timebase counter and the spread spectrum counter can be reset and the duty cycle registers can be written through the user interface of the module. This requires a synchronization between the PB and GCLK clock domains, which takes a few clock cycles of each clock domain. The BUSY bit in SR indicates when the synchronization is ongoing. Writing to the module while the BUSY bit is set will result in discarding the new value. Note that the duty cycle registers will not be updated with the new values until the timebase counter reaches its top value, in order to avoid glitches. The BUSY bit in SR will always be set during this updating and synchronization period. 25.6.9 Interrupts When the timebase counter overflows, the Timebase Overflow bit in the Status Register (SR.TOFL) is set. If the corresponding bit in the Interrupt Mask Register (IMR) is set, an interrupt request will be generated. Since the user needs to wait until the user interface is available between each write due to synchronization, a READY bit is provided in SR, which can be used to generate an interrupt request. The interrupt request will be generated if the corresponding bit in IMR is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in SR is cleared by writing a one to the corresponding bit in the Status Clear Register (SCR). 25.6.10 Peripheral Events 25.6.10.1 Input Peripheral Events The pre-defined channels support input peripheral events from the Peripheral Event System. Input peripheral events must be enabled by writing a one to the corresponding bit in the Channel Event Enable Registers (CHEERs) before peripheral events can be used to control the duty cycle value. Each bit in the register corresponds to one channel, where bit 0 corresponds to channel 0 and so on. Both the increase and decrease events are enabled for the corresponding channel when a bit in the CHEER register is set. An increase or decrease event (event_incr/event_decr) can either increase or decrease the duty cycle value by one in a PWM period. The events are taken into account when the common timebase counter reaches its top. The behavior is defined by the Channel Event Response Register (CHERR). Each bit in the register corresponds to one channel, where bit 0 corresponds to channel 0 and so on. If the bit in CHERR is set to 0 (default) for a channel, the increase event will increase the duty cycle value and the decrease event will decrease the duty cycle value for that channel. If the bit is set to 1, the increase and decrease event will have reverse function so that 622 32142D–06/2013 ATUC64/128/256L3/4U the increase event will decrease the duty cycle value and decrease event will increase the duty cycle value. If both the increase event and the decrease event occur at the same time for a channel, the duty cycle value will not be changed. The number of channels supporting input peripheral events is device specific. Please refer to the Module Configuration section at the end of this chapter for details. 25.6.10.2 Output Peripheral Event The PWMA also supports one output peripheral event (event_ch0) to the Peripheral Event System. This output peripheral event is connected to channel 0 and will be asserted when the timebase counter reaches the duty cycle value for channel 0. This output event is always enabled. 623 32142D–06/2013 ATUC64/128/256L3/4U 25.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 25-3. PWMA Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Read/Write 0x00000000 0x04 Interlinked Single Value Duty Register ISDUTY Write-only 0x00000000 0x08 Interlinked Multiple Value Duty Register IMDUTY Write-only 0x00000000 0x0C Interlinked Multiple Value Channel Select IMCHSEL Write-only 0x00000000 0x10 Interrupt Enable Register IER Write-only 0x00000000 0x14 Interrupt Disable Register IDR Write-only 0x00000000 0x18 Interrupt Mask Register IMR Read-only 0x00000000 0x1C Status Register SR Read-only 0x00000000 0x20 Status Clear Register SCR Write-only 0x00000000 0x24 Parameter Register PARAMETER Read-only - (1) 0x28 Version Register VERSION Read-only - (1) 0x2C Top Value Register TVR Read/Write 0x00000000 0x30+m*0x10 Interlinked Single Value Channel Set m ISCHSETm Write-only 0x00000000 0x34+m*0x10 Channel Event Response Register m CHERRm Read/Write 0x00000000 0x38+m*0x10 Channel Event Enable Register m CHEERm Read/Write 0x00000000 0x3C+k*0x10 CWG Register CWGk Read/Write 0x00000000 0x80 Interlinked Multiple Value Duty0 Register DUTY0 Write-only 0x00000000 0x84 Interlinked Multiple Value Duty1 Register DUTY1 Write-only 0x00000000 0x88 Interlinked Multiple Value Duty2 Register DUTY2 Write-only 0x00000000 0x8C Interlinked Multiple Value Duty3 Register DUTY3 Write-only 0x00000000 624 32142D–06/2013 ATUC64/128/256L3/4U 25.7.1 Control Register Name: CR Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • SPREAD: Spread Spectrum Limit Value The spread spectrum limit value, together with the TOP field, defines the range for the spread spectrum counter. It is introduced in order to achieve constant varying duty cycles on the output PWM waveforms. Refer to Section25.6.3 for more information. • TOP: Timebase Counter Top Value The top value for the timebase counter. The value written to this field will update the least significant 8 bits of the TVR.TOP field in case only 8-bits resolution is required. The 4 most significant bits of TVR.TOP will be written to 0. When the TVR.TOP field is written, this CR.TOP field will also be updated with only the least significant 8 bits of TVR.TOP field. • TCLR: Timebase Clear Writing a zero to this bit has no effect. Writing a one to this bit will clear the timebase counter. This bit is always read as zero. • EN: Module Enable 0: The PWMA is disabled 1: The PWMA is enabled 31 30 29 28 27 26 25 24 - - - - - - - SPREAD[8] 23 22 21 20 19 18 17 16 SPREAD[7:0] 15 14 13 12 11 10 9 8 TOP 76543210 - - - - - - TCLR EN 625 32142D–06/2013 ATUC64/128/256L3/4U 25.7.2 Interlinked Single Value Duty Register Name: ISDUTY Access Type: Write-only Offset: 0x04 Reset Value: 0x00000000 • DUTY: Duty Cycle Value The duty cycle value written to this field is written simultaneously to all channels selected in the ISCHSETm register. If the value zero is written to DUTY all affected channels will be disabled. In this state the output waveform will be zero all the time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - DUTY[11:8] 76543210 DUTY[7:0] 626 32142D–06/2013 ATUC64/128/256L3/4U 25.7.3 Interlinked Multiple Value Duty Register Name: IMDUTY Access Type: Write-only Offset: 0x08 Reset Value: 0x00000000 • DUTYn: Duty Cycle The value written to DUTY field n will be automatically written to the least significant 8 bits of the DUTYn register for a PWMA channel while the most significant 4bits of the DUTYn register are unchanged. Which channel is selected for updating is defined by the corresponding SEL field in the IMCHSEL register. To write mulitple channels at a time with more than 8 bits of the duty cycle value, refer to DUTY3/2/1/0 registers. If the value zero is written to DUTY all affected channels will be disabled. In this state the output waveform will be zero all the time. 31 30 29 28 27 26 25 24 DUTY3 23 22 21 20 19 18 17 16 DUTY2 15 14 13 12 11 10 9 8 DUTY1 76543210 DUTY0 627 32142D–06/2013 ATUC64/128/256L3/4U 25.7.4 Interlinked Multiple Value Channel Select Name: IMCHSEL Access Type: Write-only Offset: 0x0C Reset Value: 0x00000000 • SELn: Channel Select The duty cycle of the PWMA channel SELn will be updated with the value stored in the DUTYn register when IMCHSEL is written. If SELn points to a non-implemented channel, the write will be discarded. Note: The duty registers will be updated with the value stored in the DUTY3, DUTY2, DUTY1 and DUTY0 registers when the IMCHSEL register is written. Synchronization takes place immediately when an IMCHSEL register is written. The duty cycle registers will, however, not be updated until the synchronization is completed and the timebase counter reaches its top value in order to avoid glitches. When only 8 bits duty cycle value are considered for updating, the four duty cycle values can be written to the IMDUTY register once. This is equivalent to writing the 8 bits four duty cycle values to the four DUTY registers one by one while the upper 4 bits remain unchanged. 31 30 29 28 27 26 25 24 SEL3 23 22 21 20 19 18 17 16 SEL2 15 14 13 12 11 10 9 8 SEL1 76543210 SEL0 628 32142D–06/2013 ATUC64/128/256L3/4U 25.7.5 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - READY - TOFL 629 32142D–06/2013 ATUC64/128/256L3/4U 25.7.6 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - READY - TOFL 630 32142D–06/2013 ATUC64/128/256L3/4U 25.7.7 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - READY - TOFL 631 32142D–06/2013 ATUC64/128/256L3/4U 25.7.8 Status Register Name: SR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 • BUSY: Interface Busy This bit is automatically cleared when the interface is no longer busy. This bit is set when the user interface is busy and will not respond to new write operations. • READY: Interface Ready This bit is cleared by writing a one to the corresponding bit in the SCR register. This bit is set when the BUSY bit has a 1-to-0 transition. • TOFL: Timebase Overflow This bit is cleared by writing a one to corresponding bit in the SCR register. This bit is set when the timebase counter has wrapped at its top value. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - BUSY READY - TOFL 632 32142D–06/2013 ATUC64/128/256L3/4U 25.7.9 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. This register always reads as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 1 10 9 8 -------- 76543210 - - - - - READY - TOFL 633 32142D–06/2013 ATUC64/128/256L3/4U 25.7.10 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x24 Reset Value: - • CHANNELS: Channels Implemented This field contains the number of channels implemented on the device. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 CHANNELS 634 32142D–06/2013 ATUC64/128/256L3/4U 25.7.11 Version Register Name: VERSION Access Type: Read-only Offset: 0x28 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 635 32142D–06/2013 ATUC64/128/256L3/4U 25.7.12 Top Value Register Name: TVR Access Type: Read/Write Offset: 0x2C Reset Value: 0x00000000 • TOP: Timebase Counter Top Value The top value for the timebase counter. The value written to the CR.TOP field will automatically be written to the 8 least significant bits of this field while the 4 most significant bits will be 0. When this register is written, it will also automatically update the CR.TOP field with the 8 least significant bits. The effective top value of the timebase counter is defined by both TVR.TOP and the CR.SPREAD. Refer to Section25.6.2 for more information. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - TOP[11:8] 76543210 TOP[7:0] 636 32142D–06/2013 ATUC64/128/256L3/4U 25.7.13 Interlinked Single Value Channel Set Name: ISCHSETm Access Type: Write-only Offset: 0x30+m*0x10 Reset Value: 0x00000000 • SET: Single Value Channel Set If the bit n in SET is one, the duty cycle of PWMA channel n will be updated with the value written to ISDUTY. If more than one ISCHSET register is present, ISCHSET0 controls channels 31 to 0 and ISCHSET1 controls channels 63 to 32. Note: The duty registers will be updated with the value stored in the ISDUTY register when any ISCHSETm register is written. Synchronization takes place immediately when an ISCHSET register is written. The duty cycle registers will, however, not be updated until the synchronization is completed and the timebase counter reaches its top value in order to avoid glitches. 31 30 29 28 27 26 25 24 SET 23 22 21 20 19 18 17 16 SET 15 14 13 12 11 10 9 8 SET 76543210 SET 637 32142D–06/2013 ATUC64/128/256L3/4U 25.7.14 Channel Event Response Register Name: CHERRm Access Type: Read/Write Offset: 0x34+m*0x10 Reset Value: 0x00000000 • CHER: Channel Event Response 0: The increase event will increase the duty cycle value by one in a PWM period for the corresponding channel and the decrease event will decrease the duty cycle value by one. 1: The increase event will decrease the duty cycle value by one in a PWM period for the corresponding channel and the decrease event will increase the duty cycle value by one. The events are taken into account when the common timebase counter reaches its top. If more than one CHERR register is present, CHERR0 controls channels 31-0 and CHERR1 controls channels 64-32 and so on. 31 30 29 28 27 26 25 24 CHER 23 22 21 20 19 18 17 16 CHER 15 14 13 12 11 10 9 8 CHER 76543210 CHER 638 32142D–06/2013 ATUC64/128/256L3/4U 25.7.15 Channel Event Enable Register Name: CHEERm Access Type: Read/Write Offset: 0x38+m*0x10 Reset Value: 0x00000000 • CHEE: Channel Event Enable 0: The input peripheral event for the corresponding channel is disabled. 1: The input peripheral event for the corresponding channel is enabled. Both increase and decrease events for channel n are enabled if bit n is one. If more than one CHEER register is present, CHEER0 controls channels 31-0 and CHEER1 controls channels 64-32 and so on. 31 30 29 28 27 26 25 24 CHEE 23 22 21 20 19 18 17 16 CHEE 15 14 13 12 11 10 9 8 CHEE 76543210 CHEE 639 32142D–06/2013 ATUC64/128/256L3/4U 25.7.16 Composite Waveform Generation Name: CWG Access Type: Read/Write Offset: 0x3C+k*0x10 Reset Value: 0x00000000 • XOR: Pair Waveform XOR’ed If the bit n in XOR field is one, the pair of PWMA output waveforms will be XORed before output. The even number output will be the XOR’ed output and the odd number output will be reverse of it. For example, if bit 0 in XOR is one, the pair of PWMA output waveforms for channel 0 and 1 will be XORed together. If bit n in XOR is zero, normal waveforms are output for that pair. Note that If more than one CWG register is present, CWG0 controls the first 32 pairs, corresponding to channels 63 downto 0, and CWG1 controls the second 32 pairs, corresponding to channels 127 downto 64. 31 30 29 28 27 26 25 24 XOR 23 22 21 20 19 18 17 16 XOR 15 14 13 12 11 10 9 8 XOR 76543210 XOR 640 32142D–06/2013 ATUC64/128/256L3/4U 25.7.17 Interlinked Multiple Value Duty0/1/2/3 Register Name: DUTY0/1/2/3 Access Type: Write-only Offset: 0x80-0x8C Reset Value: 0x00000000 These registers allows up to 4 channels to be updated with a common 12-bits duty cycle value at a time. They are the extension of the IMDUTY register which only supports updating the least significant 8 bits of the duty registers for up to 4 channels. • DUTY: Duty Cycle Value The duty cycle value written to this field will be updated to the channel specified by IMCHSEL. DUTY0 is specified by IMCHSEL.SEL0, DUTY1 is specified by IMCHSEL.SEL1, and so on. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - DUTY[11:8] 76543210 DUTY[7:0] 641 32142D–06/2013 ATUC64/128/256L3/4U 25.8 Module Configuration The specific configuration for each PWMA instance is listed in the following tables. The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 25-4. PWMA Configuration Feature PWMA Number of PWM channels 36 Channels supporting incoming peripheral events 0, 6, 8, 9, 11, 14, 19, and 20 PWMA channels with Open Drain mode 21, 27, and 28 Table 25-5. PWMA Clocks Clock Name Descripton CLK_PWMA Clock for the PWMA bus interface GCLK The generic clock used for the PWMA is GCLK3 Table 25-6. Register Reset Values Register Reset Value VERSION 0x00000201 PARAMETER 0x00000024 642 32142D–06/2013 ATUC64/128/256L3/4U 26. Timer/Counter (TC) Rev: 2.2.3.1.3 26.1 Features • Three 16-bit Timer Counter channels • A wide range of functions including: – Frequency measurement – Event counting – Interval measurement – Pulse generation – Delay timing – Pulse width modulation – Up/down capabilities • Each channel is user-configurable and contains: – Three external clock inputs – Five internal clock inputs – Two multi-purpose input/output signals • Internal interrupt signal • Two global registers that act on all three TC channels • Peripheral event input on all A lines in capture mode 26.2 Overview The Timer Counter (TC) includes three identical 16-bit Timer Counter channels. Each channel can be independently programmed to perform a wide range of functions including frequency measurement, event counting, interval measurement, pulse generation, delay timing, and pulse width modulation. Each channel has three external clock inputs, five internal clock inputs, and two multi-purpose input/output signals which can be configured by the user. Each channel drives an internal interrupt signal which can be programmed to generate processor interrupts. The TC block has two global registers which act upon all three TC channels. The Block Control Register (BCR) allows the three channels to be started simultaneously with the same instruction. The Block Mode Register (BMR) defines the external clock inputs for each channel, allowing them to be chained. 643 32142D–06/2013 ATUC64/128/256L3/4U 26.3 Block Diagram Figure 26-1. TC Block Diagram 26.4 I/O Lines Description 26.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 26.5.1 I/O Lines The pins used for interfacing the compliant external devices may be multiplexed with I/O lines. The user must first program the I/O Controller to assign the TC pins to their peripheral functions. I/O Controller TC2XC2S INT0 INT1 INT2 TIOA0 TIOA1 TIOA2 TIOB0 TIOB1 TIOB2 XC2 TCLK0 TCLK1 TCLK2 TCLK0 TCLK1 TCLK2 TCLK0 TCLK1 TCLK2 TIOA1 TIOA2 TIOA0 TIOA2 TIOA1 Interrupt Controller CLK0 CLK1 CLK2 A0 B0 A1 B1 A2 B2 Timer Count er TIOB TIOA TIOB SYNC TIMER_CLOCK1 TIOA SYNC SYNC TIOA TIOB TIMER_CLOCK2 TIMER_CLOCK3 TIMER_CLOCK4 TIMER_CLOCK5 XC1 XC0 XC0 XC2 XC1 XC0 XC1 XC2 Timer/Counter Channel 2 Timer/Counter Channel 1 Timer/Counter Channel 0 TC1XC1S TC0XC0S TIOA0 Table 26-1. I/O Lines Description Pin Name Description Type CLK0-CLK2 External Clock Input Input A0-A2 I/O Line A Input/Output B0-B2 I/O Line B Input/Output 644 32142D–06/2013 ATUC64/128/256L3/4U When using the TIOA lines as inputs the user must make sure that no peripheral events are generated on the line. Refer to the Peripheral Event System chapter for details. 26.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the TC, the TC will stop functioning and resume operation after the system wakes up from sleep mode. 26.5.3 Clocks The clock for the TC bus interface (CLK_TC) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the TC before disabling the clock, to avoid freezing the TC in an undefined state. 26.5.4 Interrupts The TC interrupt request line is connected to the interrupt controller. Using the TC interrupt requires the interrupt controller to be programmed first. 26.5.5 Peripheral Events The TC peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 26.5.6 Debug Operation The Timer Counter clocks are frozen during debug operation, unless the OCD system keeps peripherals running in debug operation. 26.6 Functional Description 26.6.1 TC Description The three channels of the Timer Counter are independent and identical in operation. The registers for channel programming are listed in Figure 26-3 on page 659. 26.6.1.1 Channel I/O Signals As described in Figure 26-1 on page 643, each Channel has the following I/O signals. 26.6.1.2 16-bit counter Each channel is organized around a 16-bit counter. The value of the counter is incremented at each positive edge of the selected clock. When the counter has reached the value 0xFFFF and passes to 0x0000, an overflow occurs and the Counter Overflow Status bit in the Channel n Status Register (SRn.COVFS) is set. Table 26-2. Channel I/O Signals Description Block/Channel Signal Name Description Channel Signal XC0, XC1, XC2 External Clock Inputs TIOA Capture mode: Timer Counter Input Waveform mode: Timer Counter Output TIOB Capture mode: Timer Counter Input Waveform mode: Timer Counter Input/Output INT Interrupt Signal Output SYNC Synchronization Input Signal 645 32142D–06/2013 ATUC64/128/256L3/4U The current value of the counter is accessible in real time by reading the Channel n Counter Value Register (CVn). The counter can be reset by a trigger. In this case, the counter value passes to 0x0000 on the next valid edge of the selected clock. 26.6.1.3 Clock selection At block level, input clock signals of each channel can either be connected to the external inputs TCLK0, TCLK1 or TCLK2, or be connected to the configurable I/O signals A0, A1 or A2 for chaining by writing to the BMR register. See Figure 26-2 on page 645. Each channel can independently select an internal or external clock source for its counter: • Internal clock signals: TIMER_CLOCK1, TIMER_CLOCK2, TIMER_CLOCK3, TIMER_CLOCK4, TIMER_CLOCK5. See the Module Configuration Chapter for details about the connection of these clock sources. • External clock signals: XC0, XC1 or XC2. See the Module Configuration Chapter for details about the connection of these clock sources. This selection is made by the Clock Selection field in the Channel n Mode Register (CMRn.TCCLKS). The selected clock can be inverted with the Clock Invert bit in CMRn (CMRn.CLKI). This allows counting on the opposite edges of the clock. The burst function allows the clock to be validated when an external signal is high. The Burst Signal Selection field in the CMRn register (CMRn.BURST) defines this signal. Note: In all cases, if an external clock is used, the duration of each of its levels must be longer than the CLK_TC period. The external clock frequency must be at least 2.5 times lower than the CLK_TC. Figure 26-2. Clock Selection TIMER_CLOCK5 XC2 TCCLKS CLKI BURST 1 Selected Clock XC1 XC0 TIMER_CLOCK4 TIMER_CLOCK3 TIMER_CLOCK2 TIMER_CLOCK1 646 32142D–06/2013 ATUC64/128/256L3/4U 26.6.1.4 Clock control The clock of each counter can be controlled in two different ways: it can be enabled/disabled and started/stopped. See Figure 26-3 on page 646. • The clock can be enabled or disabled by the user by writing to the Counter Clock Enable/Disable Command bits in the Channel n Clock Control Register (CCRn.CLKEN and CCRn.CLKDIS). In Capture mode it can be disabled by an RB load event if the Counter Clock Disable with RB Loading bit in CMRn is written to one (CMRn.LDBDIS). In Waveform mode, it can be disabled by an RC Compare event if the Counter Clock Disable with RC Compare bit in CMRn is written to one (CMRn.CPCDIS). When disabled, the start or the stop actions have no effect: only a CLKEN command in CCRn can re-enable the clock. When the clock is enabled, the Clock Enabling Status bit is set in SRn (SRn.CLKSTA). • The clock can also be started or stopped: a trigger (software, synchro, external or compare) always starts the clock. In Capture mode the clock can be stopped by an RB load event if the Counter Clock Stopped with RB Loading bit in CMRn is written to one (CMRn.LDBSTOP). In Waveform mode it can be stopped by an RC compare event if the Counter Clock Stopped with RC Compare bit in CMRn is written to one (CMRn.CPCSTOP). The start and the stop commands have effect only if the clock is enabled. Figure 26-3. Clock Control 26.6.1.5 TC operating modes Each channel can independently operate in two different modes: • Capture mode provides measurement on signals. • Waveform mode provides wave generation. The TC operating mode selection is done by writing to the Wave bit in the CCRn register (CCRn.WAVE). In Capture mode, TIOA and TIOB are configured as inputs. Q S R S R Q CLKSTA CLKEN CLKDIS Stop Event Disable Counter Clock Selected Clock Trigger Event 647 32142D–06/2013 ATUC64/128/256L3/4U In Waveform mode, TIOA is always configured to be an output and TIOB is an output if it is not selected to be the external trigger. 26.6.1.6 Trigger A trigger resets the counter and starts the counter clock. Three types of triggers are common to both modes, and a fourth external trigger is available to each mode. The following triggers are common to both modes: • Software Trigger: each channel has a software trigger, available by writing a one to the Software Trigger Command bit in CCRn (CCRn.SWTRG). • SYNC: each channel has a synchronization signal SYNC. When asserted, this signal has the same effect as a software trigger. The SYNC signals of all channels are asserted simultaneously by writing a one to the Synchro Command bit in the BCR register (BCR.SYNC). • Compare RC Trigger: RC is implemented in each channel and can provide a trigger when the counter value matches the RC value if the RC Compare Trigger Enable bit in CMRn (CMRn.CPCTRG) is written to one. The channel can also be configured to have an external trigger. In Capture mode, the external trigger signal can be selected between TIOA and TIOB. In Waveform mode, an external event can be programmed to be one of the following signals: TIOB, XC0, XC1, or XC2. This external event can then be programmed to perform a trigger by writing a one to the External Event Trigger Enable bit in CMRn (CMRn.ENETRG). If an external trigger is used, the duration of the pulses must be longer than the CLK_TC period in order to be detected. Regardless of the trigger used, it will be taken into account at the following active edge of the selected clock. This means that the counter value can be read differently from zero just after a trigger, especially when a low frequency signal is selected as the clock. 26.6.1.7 Peripheral events on TIOA inputs The TIOA input lines are ored internally with peripheral events from the Peripheral Event System. To capture using events the user must ensure that the corresponding pin functions for the TIOA line are disabled. When capturing on the external TIOA pin the user must ensure that no peripheral events are generated on this pin. 26.6.2 Capture Operating Mode This mode is entered by writing a zero to the CMRn.WAVE bit. Capture mode allows the TC channel to perform measurements such as pulse timing, frequency, period, duty cycle and phase on TIOA and TIOB signals which are considered as inputs. Figure 26-4 on page 649 shows the configuration of the TC channel when programmed in Capture mode. 26.6.2.1 Capture registers A and B Registers A and B (RA and RB) are used as capture registers. This means that they can be loaded with the counter value when a programmable event occurs on the signal TIOA. 648 32142D–06/2013 ATUC64/128/256L3/4U The RA Loading Selection field in CMRn (CMRn.LDRA) defines the TIOA edge for the loading of the RA register, and the RB Loading Selection field in CMRn (CMRn.LDRB) defines the TIOA edge for the loading of the RB register. RA is loaded only if it has not been loaded since the last trigger or if RB has been loaded since the last loading of RA. RB is loaded only if RA has been loaded since the last trigger or the last loading of RB. Loading RA or RB before the read of the last value loaded sets the Load Overrun Status bit in SRn (SRn.LOVRS). In this case, the old value is overwritten. 26.6.2.2 Trigger conditions In addition to the SYNC signal, the software trigger and the RC compare trigger, an external trigger can be defined. The TIOA or TIOB External Trigger Selection bit in CMRn (CMRn.ABETRG) selects TIOA or TIOB input signal as an external trigger. The External Trigger Edge Selection bit in CMRn (CMRn.ETREDG) defines the edge (rising, falling or both) detected to generate an external trigger. If CMRn.ETRGEDG is zero (none), the external trigger is disabled. 649 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-4. Capture Mode TIMER_CLOCK1 XC0 XC1 XC2 TCCLKS CLKI Q S R S R Q CLKSTA CLKEN CLKDIS BURST TIOB Capture Register A Compare RC = 16-bit Counter ABETRG SWTRG ETRGEDG CPCTRG IMR Trig LDRBS LDRAS ETRGS SR LOVRS COVFS SYNC 1 MTIOB TIOA MTIOA LDRA LDBSTOP If RA is not Loaded or RB is Loaded If RA is Loaded LDBDIS CPCS INT Edge Detector LDRB CLK OVF RESET Timer/Counter Channel Edge Detector Edge Detector Capture Register B Register C TIMER_CLOCK2 TIMER_CLOCK3 TIMER_CLOCK4 TIMER_CLOCK5 650 32142D–06/2013 ATUC64/128/256L3/4U 26.6.3 Waveform Operating Mode Waveform operating mode is entered by writing a one to the CMRn.WAVE bit. In Waveform operating mode the TC channel generates one or two PWM signals with the same frequency and independently programmable duty cycles, or generates different types of oneshot or repetitive pulses. In this mode, TIOA is configured as an output and TIOB is defined as an output if it is not used as an external event. Figure 26-5 on page 651 shows the configuration of the TC channel when programmed in Waveform operating mode. 26.6.3.1 Waveform selection Depending on the Waveform Selection field in CMRn (CMRn.WAVSEL), the behavior of CVn varies. With any selection, RA, RB and RC can all be used as compare registers. RA Compare is used to control the TIOA output, RB Compare is used to control the TIOB output (if correctly configured) and RC Compare is used to control TIOA and/or TIOB outputs. 651 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-5. Waveform Mode TCCLKS CLKI Q S R S R Q CLKSTA CLKEN CLKDIS CPCDIS BURST TIOB Register A Compare RC = CPCSTOP 16-bit Counter EEVT EEVTEDG SYNC SWTRG ENETRG WAVSEL IMR Trig ACPC ACPA AEEVT ASWTRG BCPC BCPB BEEVT BSWTRG TIOA MTIOA TIOB MTIOB CPAS COVFS ETRGS SR CPCS CPBS CLK OVF RESET Output Contr oller O utput Cont r oller INT 1 Edge Detector Timer/Counter Channel TIMER_CLOCK1 XC0 XC1 XC2 WAVSEL Register B Register C Compare RB = Compare RA = TIMER_CLOCK2 TIMER_CLOCK3 TIMER_CLOCK4 TIMER_CLOCK5 652 32142D–06/2013 ATUC64/128/256L3/4U 26.6.3.2 WAVSEL = 0 When CMRn.WAVSEL is zero, the value of CVn is incremented from 0 to 0xFFFF. Once 0xFFFF has been reached, the value of CVn is reset. Incrementation of CVn starts again and the cycle continues. See Figure 26-6 on page 652. An external event trigger or a software trigger can reset the value of CVn. It is important to note that the trigger may occur at any time. See Figure 26-7 on page 653. RC Compare cannot be programmed to generate a trigger in this configuration. At the same time, RC Compare can stop the counter clock (CMRn.CPCSTOP = 1) and/or disable the counter clock (CMRn.CPCDIS = 1). Figure 26-6. WAVSEL= 0 Without Trigger Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with 0xFFFF 0xFFFF Waveform Examples 653 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-7. WAVSEL= 0 With Trigger 26.6.3.3 WAVSEL = 2 When CMRn.WAVSEL is two, the value of CVn is incremented from zero to the value of RC, then automatically reset on a RC Compare. Once the value of CVn has been reset, it is then incremented and so on. See Figure 26-8 on page 654. It is important to note that CVn can be reset at any time by an external event or a software trigger if both are programmed correctly. See Figure 26-9 on page 654. In addition, RC Compare can stop the counter clock (CMRn.CPCSTOP) and/or disable the counter clock (CMRn.CPCDIS = 1). Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with 0xFFFF 0xFFFF Waveform Examples Counter cleared by trigger 654 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-8. WAVSEL = 2 Without Trigger Figure 26-9. WAVSEL = 2 With Trigger 26.6.3.4 WAVSEL = 1 When CMRn.WAVSEL is one, the value of CVn is incremented from 0 to 0xFFFF. Once 0xFFFF is reached, the value of CVn is decremented to 0, then re-incremented to 0xFFFF and so on. See Figure 26-10 on page 655. Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with RC 0xFFFF Waveform Examples Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with RC 0xFFFF Waveform Examples Counter cleared by trigger 655 32142D–06/2013 ATUC64/128/256L3/4U A trigger such as an external event or a software trigger can modify CVn at any time. If a trigger occurs while CVn is incrementing, CVn then decrements. If a trigger is received while CVn is decrementing, CVn then increments. See Figure 26-11 on page 655. RC Compare cannot be programmed to generate a trigger in this configuration. At the same time, RC Compare can stop the counter clock (CMRn.CPCSTOP = 1) and/or disable the counter clock (CMRn.CPCDIS = 1). Figure 26-10. WAVSEL = 1 Without Trigger Figure 26-11. WAVSEL = 1 With Trigger Time Counter Value RC RB RA TIOB TIOA Counter decremented by compare match with 0xFFFF 0xFFFF Waveform Examples Time Counter Value TIOB TIOA Counter decremented by compare match with 0xFFFF 0xFFFF Waveform Examples Counter decremented by trigger RC RB RA Counter incremented by trigger 656 32142D–06/2013 ATUC64/128/256L3/4U 26.6.3.5 WAVSEL = 3 When CMRn.WAVSEL is three, the value of CVn is incremented from zero to RC. Once RC is reached, the value of CVn is decremented to zero, then re-incremented to RC and so on. See Figure 26-12 on page 656. A trigger such as an external event or a software trigger can modify CVn at any time. If a trigger occurs while CVn is incrementing, CVn then decrements. If a trigger is received while CVn is decrementing, CVn then increments. See Figure 26-13 on page 657. RC Compare can stop the counter clock (CMRn.CPCSTOP = 1) and/or disable the counter clock (CMRn.CPCDIS = 1). Figure 26-12. WAVSEL = 3 Without Trigger Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with RC 0xFFFF Waveform Examples 657 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-13. WAVSEL = 3 With Trigger 26.6.3.6 External event/trigger conditions An external event can be programmed to be detected on one of the clock sources (XC0, XC1, XC2) or TIOB. The external event selected can then be used as a trigger. The External Event Selection field in CMRn (CMRn.EEVT) selects the external trigger. The External Event Edge Selection field in CMRn (CMRn.EEVTEDG) defines the trigger edge for each of the possible external triggers (rising, falling or both). If CMRn.EEVTEDG is written to zero, no external event is defined. If TIOB is defined as an external event signal (CMRn.EEVT = 0), TIOB is no longer used as an output and the compare register B is not used to generate waveforms and subsequently no IRQs. In this case the TC channel can only generate a waveform on TIOA. When an external event is defined, it can be used as a trigger by writing a one to the CMRn.ENETRG bit. As in Capture mode, the SYNC signal and the software trigger are also available as triggers. RC Compare can also be used as a trigger depending on the CMRn.WAVSEL field. 26.6.3.7 Output controller The output controller defines the output level changes on TIOA and TIOB following an event. TIOB control is used only if TIOB is defined as output (not as an external event). The following events control TIOA and TIOB: • software trigger • external event • RC compare RA compare controls TIOA and RB compare controls TIOB. Each of these events can be programmed to set, clear or toggle the output as defined in the following fields in CMRn: • RC Compare Effect on TIOB (CMRn.BCPC) Time Counter Value TIOB TIOA Counter decremented by compare match with RC 0xFFFF Waveform Examples RC RB RA Counter decremented by trigger Counter incremented by trigger 658 32142D–06/2013 ATUC64/128/256L3/4U • RB Compare Effect on TIOB (CMRn.BCPB) • RC Compare Effect on TIOA (CMRn.ACPC) • RA Compare Effect on TIOA (CMRn.ACPA) 659 32142D–06/2013 ATUC64/128/256L3/4U 26.7 User Interface Table 26-3. TC Register Memory Map Offset Register Register Name Access Reset 0x00 Channel 0 Control Register CCR0 Write-only 0x00000000 0x04 Channel 0 Mode Register CMR0 Read/Write 0x00000000 0x10 Channel 0 Counter Value CV0 Read-only 0x00000000 0x14 Channel 0 Register A RA0 Read/Write(1) 0x00000000 0x18 Channel 0 Register B RB0 Read/Write(1) 0x00000000 0x1C Channel 0 Register C RC0 Read/Write 0x00000000 0x20 Channel 0 Status Register SR0 Read-only 0x00000000 0x24 Interrupt Enable Register IER0 Write-only 0x00000000 0x28 Channel 0 Interrupt Disable Register IDR0 Write-only 0x00000000 0x2C Channel 0 Interrupt Mask Register IMR0 Read-only 0x00000000 0x40 Channel 1 Control Register CCR1 Write-only 0x00000000 0x44 Channel 1 Mode Register CMR1 Read/Write 0x00000000 0x50 Channel 1 Counter Value CV1 Read-only 0x00000000 0x54 Channel 1 Register A RA1 Read/Write(1) 0x00000000 0x58 Channel 1 Register B RB1 Read/Write(1) 0x00000000 0x5C Channel 1 Register C RC1 Read/Write 0x00000000 0x60 Channel 1 Status Register SR1 Read-only 0x00000000 0x64 Channel 1 Interrupt Enable Register IER1 Write-only 0x00000000 0x68 Channel 1 Interrupt Disable Register IDR1 Write-only 0x00000000 0x6C Channel 1 Interrupt Mask Register IMR1 Read-only 0x00000000 0x80 Channel 2 Control Register CCR2 Write-only 0x00000000 0x84 Channel 2 Mode Register CMR2 Read/Write 0x00000000 0x90 Channel 2 Counter Value CV2 Read-only 0x00000000 0x94 Channel 2 Register A RA2 Read/Write(1) 0x00000000 0x98 Channel 2 Register B RB2 Read/Write(1) 0x00000000 0x9C Channel 2 Register C RC2 Read/Write 0x00000000 0xA0 Channel 2 Status Register SR2 Read-only 0x00000000 0xA4 Channel 2 Interrupt Enable Register IER2 Write-only 0x00000000 0xA8 Channel 2 Interrupt Disable Register IDR2 Write-only 0x00000000 0xAC Channel 2 Interrupt Mask Register IMR2 Read-only 0x00000000 0xC0 Block Control Register BCR Write-only 0x00000000 0xC4 Block Mode Register BMR Read/Write 0x00000000 0xF8 Features Register FEATURES Read-only -(2) 0xFC Version Register VERSION Read-only -(2) 660 32142D–06/2013 ATUC64/128/256L3/4U Notes: 1. Read-only if CMRn.WAVE is zero. 2. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. 661 32142D–06/2013 ATUC64/128/256L3/4U 26.7.1 Channel Control Register Name: CCR Access Type: Write-only Offset: 0x00 + n * 0x40 Reset Value: 0x00000000 • SWTRG: Software Trigger Command 1: Writing a one to this bit will perform a software trigger: the counter is reset and the clock is started. 0: Writing a zero to this bit has no effect. • CLKDIS: Counter Clock Disable Command 1: Writing a one to this bit will disable the clock. 0: Writing a zero to this bit has no effect. • CLKEN: Counter Clock Enable Command 1: Writing a one to this bit will enable the clock if CLKDIS is not one. 0: Writing a zero to this bit has no effect. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - SWTRG CLKDIS CLKEN 662 32142D–06/2013 ATUC64/128/256L3/4U 26.7.2 Channel Mode Register: Capture Mode Name: CMR Access Type: Read/Write Offset: 0x04 + n * 0x40 Reset Value: 0x00000000 • LDRB: RB Loading Selection • LDRA: RA Loading Selection • WAVE 1: Capture mode is disabled (Waveform mode is enabled). 0: Capture mode is enabled. • CPCTRG: RC Compare Trigger Enable 1: RC Compare resets the counter and starts the counter clock. 0: RC Compare has no effect on the counter and its clock. • ABETRG: TIOA or TIOB External Trigger Selection 1: TIOA is used as an external trigger. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - LDRB LDRA 15 14 13 12 11 10 9 8 WAVE CPCTRG - - - ABETRG ETRGEDG 76543210 LDBDIS LDBSTOP BURST CLKI TCCLKS LDRB Edge 0 none 1 rising edge of TIOA 2 falling edge of TIOA 3 each edge of TIOA LDRA Edge 0 none 1 rising edge of TIOA 2 falling edge of TIOA 3 each edge of TIOA 663 32142D–06/2013 ATUC64/128/256L3/4U 0: TIOB is used as an external trigger. • ETRGEDG: External Trigger Edge Selection • LDBDIS: Counter Clock Disable with RB Loading 1: Counter clock is disabled when RB loading occurs. 0: Counter clock is not disabled when RB loading occurs. • LDBSTOP: Counter Clock Stopped with RB Loading 1: Counter clock is stopped when RB loading occurs. 0: Counter clock is not stopped when RB loading occurs. • BURST: Burst Signal Selection • CLKI: Clock Invert 1: The counter is incremented on falling edge of the clock. 0: The counter is incremented on rising edge of the clock. • TCCLKS: Clock Selection ETRGEDG Edge 0 none 1 rising edge 2 falling edge 3 each edge BURST Burst Signal Selection 0 The clock is not gated by an external signal 1 XC0 is ANDed with the selected clock 2 XC1 is ANDed with the selected clock 3 XC2 is ANDed with the selected clock TCCLKS Clock Selected 0 TIMER_CLOCK1 1 TIMER_CLOCK2 2 TIMER_CLOCK3 3 TIMER_CLOCK4 4 TIMER_CLOCK5 5 XC0 6 XC1 7 XC2 664 32142D–06/2013 ATUC64/128/256L3/4U 26.7.3 Channel Mode Register: Waveform Mode Name: CMR Access Type: Read/Write Offset: 0x04 + n * 0x40 Reset Value: 0x00000000 • BSWTRG: Software Trigger Effect on TIOB • BEEVT: External Event Effect on TIOB 31 30 29 28 27 26 25 24 BSWTRG BEEVT BCPC BCPB 23 22 21 20 19 18 17 16 ASWTRG AEEVT ACPC ACPA 15 14 13 12 11 10 9 8 WAVE WAVSEL ENETRG EEVT EEVTEDG 76543210 CPCDIS CPCSTOP BURST CLKI TCCLKS BSWTRG Effect 0 none 1 set 2 clear 3 toggle BEEVT Effect 0 none 1 set 2 clear 3 toggle 665 32142D–06/2013 ATUC64/128/256L3/4U • BCPC: RC Compare Effect on TIOB • BCPB: RB Compare Effect on TIOB • ASWTRG: Software Trigger Effect on TIOA • AEEVT: External Event Effect on TIOA • ACPC: RC Compare Effect on TIOA BCPC Effect 0 none 1 set 2 clear 3 toggle BCPB Effect 0 none 1 set 2 clear 3 toggle ASWTRG Effect 0 none 1 set 2 clear 3 toggle AEEVT Effect 0 none 1 set 2 clear 3 toggle ACPC Effect 0 none 1 set 2 clear 3 toggle 666 32142D–06/2013 ATUC64/128/256L3/4U • ACPA: RA Compare Effect on TIOA • WAVE 1: Waveform mode is enabled. 0: Waveform mode is disabled (Capture mode is enabled). • WAVSEL: Waveform Selection • ENETRG: External Event Trigger Enable 1: The external event resets the counter and starts the counter clock. 0: The external event has no effect on the counter and its clock. In this case, the selected external event only controls the TIOA output. • EEVT: External Event Selection Note: 1. If TIOB is chosen as the external event signal, it is configured as an input and no longer generates waveforms and subsequently no IRQs. • EEVTEDG: External Event Edge Selection • CPCDIS: Counter Clock Disable with RC Compare 1: Counter clock is disabled when counter reaches RC. 0: Counter clock is not disabled when counter reaches RC. ACPA Effect 0 none 1 set 2 clear 3 toggle WAVSEL Effect 0 UP mode without automatic trigger on RC Compare 1 UPDOWN mode without automatic trigger on RC Compare 2 UP mode with automatic trigger on RC Compare 3 UPDOWN mode with automatic trigger on RC Compare EEVT Signal selected as external event TIOB Direction 0 TIOB input(1) 1 XC0 output 2 XC1 output 3 XC2 output EEVTEDG Edge 0 none 1 rising edge 2 falling edge 3 each edge 667 32142D–06/2013 ATUC64/128/256L3/4U • CPCSTOP: Counter Clock Stopped with RC Compare 1: Counter clock is stopped when counter reaches RC. 0: Counter clock is not stopped when counter reaches RC. • BURST: Burst Signal Selection • CLKI: Clock Invert 1: Counter is incremented on falling edge of the clock. 0: Counter is incremented on rising edge of the clock. • TCCLKS: Clock Selection BURST Burst Signal Selection 0 The clock is not gated by an external signal. 1 XC0 is ANDed with the selected clock. 2 XC1 is ANDed with the selected clock. 3 XC2 is ANDed with the selected clock. TCCLKS Clock Selected 0 TIMER_CLOCK1 1 TIMER_CLOCK2 2 TIMER_CLOCK3 3 TIMER_CLOCK4 4 TIMER_CLOCK5 5 XC0 6 XC1 7 XC2 668 32142D–06/2013 ATUC64/128/256L3/4U 26.7.4 Channel Counter Value Register Name: CV Access Type: Read-only Offset: 0x10 + n * 0x40 Reset Value: 0x00000000 • CV: Counter Value CV contains the counter value in real time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 CV[15:8] 76543210 CV[7:0] 669 32142D–06/2013 ATUC64/128/256L3/4U 26.7.5 Channel Register A Name: RA Access Type: Read-only if CMRn.WAVE = 0, Read/Write if CMRn.WAVE = 1 Offset: 0x14 + n * 0X40 Reset Value: 0x00000000 • RA: Register A RA contains the Register A value in real time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 RA[15:8] 76543210 RA[7:0] 670 32142D–06/2013 ATUC64/128/256L3/4U 26.7.6 Channel Register B Name: RB Access Type: Read-only if CMRn.WAVE = 0, Read/Write if CMRn.WAVE = 1 Offset: 0x18 + n * 0x40 Reset Value: 0x00000000 • RB: Register B RB contains the Register B value in real time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 RB[15:8] 76543210 RB[7:0] 671 32142D–06/2013 ATUC64/128/256L3/4U 26.7.7 Channel Register C Name: RC Access Type: Read/Write Offset: 0x1C + n * 0x40 Reset Value: 0x00000000 • RC: Register C RC contains the Register C value in real time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 RC[15:8] 76543210 RC[7:0] 672 32142D–06/2013 ATUC64/128/256L3/4U 26.7.8 Channel Status Register Name: SR Access Type: Read-only Offset: 0x20 + n * 0x40 Reset Value: 0x00000000 Note: Reading the Status Register will also clear the interrupt bit for the corresponding interrupts. • MTIOB: TIOB Mirror 1: TIOB is high. If CMRn.WAVE is zero, this means that TIOB pin is high. If CMRn.WAVE is one, this means that TIOB is driven high. 0: TIOB is low. If CMRn.WAVE is zero, this means that TIOB pin is low. If CMRn.WAVE is one, this means that TIOB is driven low. • MTIOA: TIOA Mirror 1: TIOA is high. If CMRn.WAVE is zero, this means that TIOA pin is high. If CMRn.WAVE is one, this means that TIOA is driven high. 0: TIOA is low. If CMRn.WAVE is zero, this means that TIOA pin is low. If CMRn.WAVE is one, this means that TIOA is driven low. • CLKSTA: Clock Enabling Status 1: This bit is set when the clock is enabled. 0: This bit is cleared when the clock is disabled. • ETRGS: External Trigger Status 1: This bit is set when an external trigger has occurred. 0: This bit is cleared when the SR register is read. • LDRBS: RB Loading Status 1: This bit is set when an RB Load has occurred and CMRn.WAVE is zero. 0: This bit is cleared when the SR register is read. • LDRAS: RA Loading Status 1: This bit is set when an RA Load has occurred and CMRn.WAVE is zero. 0: This bit is cleared when the SR register is read. • CPCS: RC Compare Status 1: This bit is set when an RC Compare has occurred. 0: This bit is cleared when the SR register is read. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - MTIOB MTIOA CLKSTA 15 14 13 12 11 10 9 8 -------- 76543210 ETRGS LDRBS LDRAS CPCS CPBS CPAS LOVRS COVFS 673 32142D–06/2013 ATUC64/128/256L3/4U • CPBS: RB Compare Status 1: This bit is set when an RB Compare has occurred and CMRn.WAVE is one. 0: This bit is cleared when the SR register is read. • CPAS: RA Compare Status 1: This bit is set when an RA Compare has occurred and CMRn.WAVE is one. 0: This bit is cleared when the SR register is read. • LOVRS: Load Overrun Status 1: This bit is set when RA or RB have been loaded at least twice without any read of the corresponding register and CMRn.WAVE is zero. 0: This bit is cleared when the SR register is read. • COVFS: Counter Overflow Status 1: This bit is set when a counter overflow has occurred. 0: This bit is cleared when the SR register is read. 674 32142D–06/2013 ATUC64/128/256L3/4U 26.7.9 Channel Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x24 + n * 0x40 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 ETRGS LDRBS LDRAS CPCS CPBS CPAS LOVRS COVFS 675 32142D–06/2013 ATUC64/128/256L3/4U 26.7.10 Channel Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x28 + n * 0x40 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 ETRGS LDRBS LDRAS CPCS CPBS CPAS LOVRS COVFS 676 32142D–06/2013 ATUC64/128/256L3/4U 26.7.11 Channel Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x2C + n * 0x40 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 ETRGS LDRBS LDRAS CPCS CPBS CPAS LOVRS COVFS 677 32142D–06/2013 ATUC64/128/256L3/4U 26.7.12 Block Control Register Name: BCR Access Type: Write-only Offset: 0xC0 Reset Value: 0x00000000 • SYNC: Synchro Command 1: Writing a one to this bit asserts the SYNC signal which generates a software trigger simultaneously for each of the channels. 0: Writing a zero to this bit has no effect. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - SYNC 678 32142D–06/2013 ATUC64/128/256L3/4U 26.7.13 Block Mode Register Name: BMR Access Type: Read/Write Offset: 0xC4 Reset Value: 0x00000000 • TC2XC2S: External Clock Signal 2 Selection • TC1XC1S: External Clock Signal 1 Selection 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - TC2XC2S TC1XC1S TC0XC0S TC2XC2S Signal Connected to XC2 0 TCLK2 1 none 2 TIOA0 3 TIOA1 TC1XC1S Signal Connected to XC1 0 TCLK1 1 none 2 TIOA0 3 TIOA2 679 32142D–06/2013 ATUC64/128/256L3/4U • TC0XC0S: External Clock Signal 0 Selection TC0XC0S Signal Connected to XC0 0 TCLK0 1 none 2 TIOA1 3 TIOA2 680 32142D–06/2013 ATUC64/128/256L3/4U 26.7.14 Features Register Name: FEATURES Access Type: Read-only Offset: 0xF8 Reset Value: - • BRPBHSB: Bridge type is PB to HSB 1: Bridge type is PB to HSB. 0: Bridge type is not PB to HSB. • UPDNIMPL: Up/down is implemented 1: Up/down counter capability is implemented. 0: Up/down counter capability is not implemented. • CTRSIZE: Counter size This field indicates the size of the counter in bits. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 ------- 15 14 13 12 11 10 9 8 - - - - - - BRPBHSB UPDNIMPL 76543210 CTRSIZE 681 32142D–06/2013 ATUC64/128/256L3/4U 26.7.15 Version Register Name: VERSION Access Type: Read-only Offset: 0xFC Reset Value: - • VARIANT: Variant number Reserved. No functionality associated. • VERSION: Version number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 682 32142D–06/2013 ATUC64/128/256L3/4U 26.8 Module Configuration The specific configuration for each Timer/Counter instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 26.8.1 Clock Connections There are two Timer/Counter modules, TC0 and TC1, with three channels each, giving a total of six Timer/Counter channels. Each Timer/Counter channel can independently select an internal or external clock source for its counter: Table 26-4. TC Bus Interface Clocks Module name Clock Name Description TC0 CLK_TC0 Clock for the TC0 bus interface TC1 CLK_TC1 Clock for the TC1 bus interface Table 26-5. Timer/Counter Clock Connections Module Source Name Connection TC0 Internal TIMER_CLOCK1 32 KHz oscillator clock (CLK_32K) TIMER_CLOCK2 PBA Clock / 2 TIMER_CLOCK3 PBA Clock / 8 TIMER_CLOCK4 PBA Clock / 32 TIMER_CLOCK5 PBA Clock / 128 External XC0 See Section on page 10 XC1 XC2 TC1 Internal TIMER_CLOCK1 32 KHz oscillator clock (CLK_32K) TIMER_CLOCK2 PBA Clock / 2 TIMER_CLOCK3 PBA Clock / 8 TIMER_CLOCK4 PBA Clock / 32 TIMER_CLOCK5 PBA Clock / 128 External XC0 See Section on page 10 XC1 XC2 683 32142D–06/2013 ATUC64/128/256L3/4U 27. Peripheral Event System Rev: 1.0.0.1 27.1 Features • Direct peripheral to peripheral communication system • Allows peripherals to receive, react to, and send peripheral events without CPU intervention • Cycle deterministic event communication • Asynchronous interrupts allow advanced peripheral operation in low power sleep modes 27.2 Overview Several peripheral modules can be configured to emit or respond to signals known as peripheral events. The exact condition to trigger a peripheral event, or the action taken upon receiving a peripheral event, is specific to each module. Peripherals that respond to peripheral events are called peripheral event users and peripherals that emit peripheral events are called peripheral event generators. A single module can be both a peripheral event generator and user. The peripheral event generators and users are interconnected by a network known as the Peripheral Event System. This allows low latency peripheral-to-peripheral signaling without CPU intervention, and without consuming system resources such as bus or RAM bandwidth. This offloads the CPU and system resources compared to a traditional interrupt-based software driven system. 27.3 Peripheral Event System Block Diagram Figure 27-1. Peripheral Event System Block Diagram 27.4 Functional Description 27.4.1 Configuration The Peripheral Event System in the ATUC64/128/256L3/4U has a fixed mapping of peripheral events between generators and users, as described in Table 27-1 to Table 27-4. Thus, the user does not need to configure the interconnection between the modules, although each peripheral event can be enabled or disabled at the generator or user side as described in the peripheral chapter for each module. Peripheral Event System Generator Generator User Generator/ User 684 32142D–06/2013 ATUC64/128/256L3/4U Table 27-1. Peripheral Event Mapping from ACIFB to PWMA Generator Generated Event User Effect Asynchronous ACIFB channel 0 AC0 VINP > AC0 VINN PWMA channel 0 PWMA duty cycle value increased by one No AC0 VINN > AC0 VINP PWMA duty cycle value decreased by one ACIFB channel 1 AC1 VINP > AC1 VINN PWMA channel 6 PWMA duty cycle value increased by one AC1 VINN > AC1 VINP PWMA duty cycle value decreased by one ACIFB channel 2 AC2 VINP > AC2 VINN PWMA channel 8 PWMA duty cycle value increased by one AC2 VINN > AC2 VINP PWMA duty cycle value decreased by one ACIFB channel 3 AC3 VINP > AC3 VINN PWMA channel 9 PWMA duty cycle value increased by one AC3 VINN > AC3 VINP PWMA duty cycle value decreased by one ACIFB channel 4 AC4 VINP > AC4 VINN PWMA channel 11 PWMA duty cycle value increased by one AC4 VINN > AC4 VINP PWMA duty cycle value decreased by one ACIFB channel 5 AC5 VINP > AC5 VINN PWMA channel 14 PWMA duty cycle value increased by one AC5 VINN > AC5 VINP PWMA duty cycle value decreased by one ACIFB channel 6 AC6 VINP > AC6 VINN PWMA channel 19 PWMA duty cycle value increased by one AC6 VINN > AC6 VINP PWMA duty cycle value decreased by one ACIFB channel 7 AC7 VINP > AC7 VINN PWMA channel 20 PWMA duty cycle value increased by one AC7 VINN > AC7 VINP PWMA duty cycle value decreased by one ACIFB channel n ACn VINN > ACn VINP CAT Automatically used by the CAT when performing QMatrix acquisition. No Table 27-2. Peripheral Event Mapping from GPIO to TC Generator Generated Event User Effect Asynchronous GPIO Pin change on PA00-PA07 TC0 A0 capture No Pin change on PA08-PA15 A1 capture Pin change on PA16-PA23 A2 capture Pin change on PB00-PB07 TC1 A1 capture Pin change on PB08-PB15 A2 capture 685 32142D–06/2013 ATUC64/128/256L3/4U 27.4.2 Peripheral Event Connections Each generated peripheral event is connected to one or more users. If a peripheral event is connected to multiple users, the peripheral event can trigger actions in multiple modules. A peripheral event user can likewise be connected to one or more peripheral event generators. If a peripheral event user is connected to multiple generators, the peripheral events are OR’ed together to a single peripheral event. This means that peripheral events from either one of the generators will result in a peripheral event to the user. To configure a peripheral event, the peripheral event must be enabled at both the generator and user side. Even if a generator is connected to multiple users, only the users with the peripheral event enabled will trigger on the peripheral event. 27.4.3 Low Power Operation As the peripheral events do not require CPU intervention, they are available in Idle mode. They are also available in deeper sleep modes if both the generator and user remain clocked in that mode. Certain events are known as asynchronous peripheral events, as identified in Table 27-1 to Table 27-4. These can be issued even when the system clock is stopped, and revive unclocked user peripherals. The clock will be restarted for this module only, without waking the system from sleep mode. The clock remains active only as long as required by the triggered function, before being switched off again, and the system remains in the original sleep mode. The CPU and sysTable 27-3. Peripheral Event Mapping from AST Generator Generated Event User Effect Asynchronous AST Overflow event ACIFB Comparison is triggered if the ACIFB.CONFn register is written to 11 (Event Triggered Single Measurement Mode) and the EVENTEN bit in the ACIFB.CTRL register is written to 1. Yes Periodic event Alarm event Overflow event ADCIFB Conversion is triggered if the TRGMOD bit in the ADCIFB.TRGR register is written to 111 (Peripheral Event Trigger). Periodic event Alarm event Overflow event CAT Trigger one iteration of autonomous touch detection. Periodic event Alarm event Table 27-4. Peripheral Event Mapping from PWMA Generator Generated Event User Effect Asynchronous PWMA channel 0 Timebase counter reaches the duty cycle value. ACIFB Comparison is triggered if the ACIFB.CONFn register is written to 11 (Event Triggered Single Measurement Mode) and the EVENTEN bit in the ACIFB.CTRL register is written to 1. No ADCIFB Conversion is triggered if the TRGMOD bit in the ADCIFB.TRGR register is written to 111 (Peripheral Event Trigger). 686 32142D–06/2013 ATUC64/128/256L3/4U tem will only be woken up if the user peripheral generates an interrupt as a result of the operation. This concept is known as SleepWalking and is described in further detail in the Power Manager chapter. Note that asynchronous peripheral events may be associated with a delay due to the need to restart the system clock source if this has been stopped in the sleep mode. 27.5 Application Example This application example shows how the Peripheral Event System can be used to program the ADC Interface to perform ADC conversions at selected intervals. Conversions of the active analog channels are started with a software or a hardware trigger. One of the possible hardware triggers is a peripheral event trigger, allowing the Peripheral Event System to synchronize conversion with some configured peripheral event source. From Table 27-3 and Table 27-4, it can be read that this peripheral event source can be either an AST peripheral event, or an event from the PWM Controller. The AST can generate periodic peripheral events at selected intervals, among other types of peripheral events. The Peripheral Event System can then be used to set up the ADC Interface to sample an analog signal at regular intervals. The user must enable peripheral events in the AST and in the ADC Interface to accomplish this. The periodic peripheral event in the AST is enabled by writing a one to the corresponding bit in the AST Event Enable Register (EVE). To select the peripheral event trigger for the ADC Interface, the user must write the value 0x7 to the Trigger Mode (TRGMOD) field in the ADC Interface Trigger Register (TRGR). When the peripheral events are enabled, the AST will generate peripheral events at the selected intervals, and the Peripheral Event System will route the peripheral events to the ADC Interface, which will perform ADC conversions at the selected intervals. Figure 27-2. Application Example Since the AST peripheral event is asynchronous, the description above will also work in sleep modes where the ADC clock is stopped. In this case, the ADC clock (and clock source, if needed) will be restarted during the ADC conversion. After the conversion, the ADC clock and clock source will return to the sleep state, unless the ADC generates an interrupt, which in turn will wake up the system. Using asynchronous interrupts thus allows ADC operation in much lower power states than would otherwise be possible. Peripheral Event System AST ADC Interface Trigger conversion Periodic peripheral event 687 32142D–06/2013 ATUC64/128/256L3/4U 28. Audio Bit Stream DAC (ABDACB) Rev.: 1.0.0.0 28.1 Features • 16 bit digital stereo DAC • Oversampling D/A conversion architecture – Adjustable oversampling ratio – 3rd order Sigma-Delta D/A converters • Digital bitstream output • Parallel interface • Connects to DMA for background transfer without CPU intervention • Supported sampling frequencies – 8000Hz, 11025Hz, 12000Hz, 16000Hz, 22050Hz, 24000Hz, 32000Hz, 44100Hz, and 48000Hz • Supported data formats – 32-, 24-, 20-, 18-, 16-, and 8-bit stereo format – 16- and 8-bit compact stereo format, with left and right sample packed in the same word to reduce data transfers • Common mode offset control • Volume control 28.2 Overview The Audio Bitstream DAC (ABDACB) converts a 16-bit sample value to a digital bitstream with an average value proportional to the sample value. Two channels are supported making the Audio Bitstream DAC particularly suitable for stereo audio. Each channel has a pair of complementary digital outputs, DAC and DACN, which can be connected to an external high input impedance amplifier. The Audio Bitstream DAC is made up of several signal processing blocks and a 3rd order Sigma Delta D/A converter for each channel. The Sigma Delta modulator converts the parallel data to a bitstream, while the signal processing blocks perform volume control, offset control, upsampling, and filtering to compensate for the upsampling process. The upsampling is performed by a Cascaded Integrator-Comb (CIC) filter, and the compensation filter is a Finite Impulse Response (FIR) CIC compensation filter. 28.3 Block Diagram Figure 28-1. ABDACB Block Diagram User Inter af ce Synchronizer Volume control Offset control CIC Compensation filter (FIR) CIC Comb Section CIC Integrator section Clock divider Sigma Delta Modulator Sigma Delta Modulator clk_abdacb gclk Signal processing (before up-sampling) CLK DAC[0] DACN[0] DAC[1] DACN[1] PB 688 32142D–06/2013 ATUC64/128/256L3/4U 28.4 I/O Lines Description 28.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 28.5.1 I/O lines The output pins used for the output bitstream from the Audio Bitstream DAC may be multiplexed with I/O Controller lines. Before using the Audio Bitstream DAC, the I/O Controller must be configured in order for the Audio Bitstream DAC I/O lines to be in Audio Bitstream DAC peripheral mode. 28.5.2 Clocks The clock for the ABDACB bus interface (CLK_ABDACB) is generated by the Power Manager. This clock is turned on by default, and can be enabled and disabled in the Power Manager. It is recommended to disable the ABDACB before disabling the clock, to avoid freezing the ABDACB in an undefined state. Before using the Audio Bitstream DAC, the user must ensure that the Audio Bitstream DAC clock is enabled in the Power Manager. The Audio Bitstream DAC requires a separate clock for the D/A conversion. This clock is provided by a generic clock which has to be set up in the System Control Interface (SCIF). The frequency for this clock has to be set as described in Table 28-3 on page 697. It is important that this clock is accurate and has low jitter. Incorrect frequency will result in too fast or too slow playback (frequency shift), and too high jitter will add noise to the D/A conversion. For best performance one should trade frequency accuracy (within some limits) for low jitter to obtain the best performance as jitter will have large impact on the quality of the converted signal. 28.5.3 DMA The ABDACB is connected to the Peripheral DMA controller. Using DMA to transfer data samples requires the Peripheral DMA controller to be programmed before enabling the ABDACB. 28.5.4 Interrupts The ABDACB interrupt request line is connected to the interrupt controller. Using the ABDACB interrupt requires the interrupt controller to be programmed first. Table 28-1. I/O Lines Description Pin Name Pin Description Type DAC[0] Output for channel 0 Output DACN[0] Inverted output for channel 0 Output DAC[1] Output for channel 1 Output DACN[1] Inverted output for channel 1 Output CLK Clock output for DAC Output 689 32142D–06/2013 ATUC64/128/256L3/4U 28.6 Functional Description 28.6.1 Construction The Audio Bitstream DAC is divided into several parts, the user interface, the signal processing blocks, and the Sigma Delta modulator blocks. See Figure 28-1 on page 687. The user interface is used to configure the signal processing blocks and to input new data samples to the converter.The signal processing blocks manages volume control, offset control, and upsampling. The Sigma Delta blocks converts the parallel data to1-bit bitstreams. 28.6.1.1 CIC Interpolation Filter The interpolation filter in the system is a Cascaded Integrator-Comb (CIC) interpolation filter which interpolates from Fs to {125, 128, 136}xFs depending on the control settings. This filter is a 4th order CIC filter, and the basic building blocks of the filter is a comb part and an integrator part. Since the CIC interpolator has a sinc-function frequency response it is compensated by a linear phase CIC compensation filter to make the passband response more flat in the range 0- 20kHz, see figure Figure 28-4 on page 693. The frequency response of this type of interpolator has the first zero at the input sampling frequency. This means that the first repeated specters created by the upsampling process will not be fully rejected and the output signal will contain signals from these repeated specters. See Figure 28-6 on page 694. Since the human ear can not hear frequencies above 20kHz, we should not be affected by this when the sample rate is above 40kHz, but digital measurement equipment will be affected. This need to be accounted for when doing measurements on the system to prevent aliasing and incorrect measurement results. 28.6.1.2 Sigma Delta Modulator The Sigma Delta modulator is a 3rd order modulator consisting of three differentiators (delta blocks), three integrators (sigma blocks), and a one bit quantizer. The purpose of the integrators is to shape the noise, so that the noise is reduced in the audio passband and increased at the higher frequencies, where it can be filtered out by an analog low-pass filter. To be able to filter out all the noise at high frequencies the analog low-pass filter must be one order larger than the Sigma Delta modulator. 28.6.1.3 Recreating the Analog Signal Since the DAC and DACN outputs from the ABDAC are digital square wave signals, they have to be passed through a low pass filter to recreate the analog signal. This also means that noise on the IO voltage will couple through to the analog signal. To remove some of the IO noise the ABDAC can output a clock signal, CLK, which can be used to resample the DAC and DACN signals on external Flip-Flops powered by a clean supply. 28.6.2 Initialization Before enabling the ABDACB the correct configuration must be applied to the Control Register (CR). Configuring the Alternative Upsampling Ratio bit (CR.ALTUPR), Common Mode Offset Control bit (CR.CMOC), and the Sampling Frequency field (CR.FS) according to the sampling rate of the data that is converted and the type of amplifier the outputs are connected to is required to get the correct behavior of the system. When the correct configuration is applied the ABDACB can be enabled by writing a one to the Enable bit in the Control Register (CR.EN). The module is disabled by writing a zero to the Enable bit. The module should be disabled before entering sleep modes to ensure that the outputs are not left in an undesired state. 690 32142D–06/2013 ATUC64/128/256L3/4U 28.6.3 Basic operation To convert audio data to a digital bitstream the user must first initialize the ABDACB as described in Section 28.6.2. When the ABDACB is initialized and enabled it will indicate that it is ready to receive new data by setting the Transmit Ready bit in the Status Register (SR.TXRDY). When the TXRDY bit is set in the Status Register the user has to write new samples to Sample Data Register 0 (SDR0) and Sample Data Register 1 (SDR1). If the Mono Mode (MONO) bit in the Control Register (CR) is set, or one of the compact stereo formats are used by configuring the Data Word Format (DATAFORMAT) in the Control Register, only SDR0 has to be written. Failing to write to the sample data registers will result in an underrun indicated by the Transmit Underrun (TXUR) bit in the Status Register (SR.TXUR). When new samples are written to the sample data registers the TXRDY bit will be cleared. To increase performance of the system an interrupt handler or DMA transfer can be used to write new samples to the sample data registers. See Section 28.6.10 for details on DMA, and Section 28.6.11 for details on interrupt. 28.6.4 Data Format The input data type is two’s complement. The Audio Bitstream DAC can be configured to accept different audio formats. The format must be configured in the Data Word Format field in the Control Register. In regular operation data for the two channels are written to the sample data registers SDR0 and SDR1. If the data format field specifies a format using less than 32 bits, data must be written right-justified in SDR0 and SDR1. Sign extension into the unused bits is not necessary. Only the 16 most significant bits in the data will be used by the ABDACB. For data formats larger than 16 bits the least significant bits are ignored. For 8-bit data formats the 8 bits will be used as the most significant bits in the 16-bit samples, the additional bits will be zeros. The ABDACB also supports compact data formats for 16- and 8-bit samples. For 16-bit samples the sample for channel 0 must be written to bits 15 through 0 and the sample for channel 1 must be written to bits 31 through 16 in SDR0. For 8-bit samples the sample for channel 0 must be written to bits 7 through 0 and the sample for channel 1 must be written to bits 15 through 8 in SDR0. SDR1 is not used in this mode. See Table 28-5 on page 699. 28.6.5 Data Swapping When the Swap Channels (SWAP) bit in the Control Register (CR.SWAP) is one, writing to the Sample Data Register 0 (SDR0) will put the data in Sample Data Register 1 (SDR1). Writing SDR1 will put the data in SDR0. If one of the two compact stereo formats is used the lower and upper halfword of SDR0 will be swapped when writing to SDR0. 28.6.6 Common Mode Offset Control When the Common Mode Offset Control (CMOC) bit in the Control Register is one the input data will get a DC value applied to it and the amplitude will be scaled. This will make the common mode offset of the two corresponding outputs, DAC and DACN, to move away from each other so that the output signals are not overlapping. The result is that the two signals can be applied to a differential analog filter, and the difference will always be a positive value, removing the need for a negative voltage supply for the filter. The cost of doing this a 3dB loss in dynamic range. On the left side of Figure 28-2 one can see the filtered output from the DAC and DACN pins when a sine wave is played when CR.CMOC is zero. The waveform on the right side shows the output of the differential filter when the two outputs on the left side are used as inputs to the differential filter. Figure 28-3 show the corresponding outputs when CR.CMOC is one. 691 32142D–06/2013 ATUC64/128/256L3/4U Figure 28-2. Output signals with CMOC=0 Figure 28-3. Output signals with CMOC=1 28.6.7 Volume Control The Audio Bitstream DAC have two volume control registers, Volume Control Register 0 (VCR0) and Volume Control Register 1 (VCR1), that can be used to adjust the volume for the corresponding channel. The volume control is linear and will only scale each sample according to the value in the Volume Control (VOLUME) field in the volume control registers. The register also has a Mute bit (MUTE) which can be used to mute the corresponding channel. The filtered out- 692 32142D–06/2013 ATUC64/128/256L3/4U put of the DAC pins will have a voltage given by the following equation, given that it is configured to run at the default upsampling ratio of 128: If one want to get coherence between the sign of the input data and the output voltage one can use the DATAN outputs or invert the sign of the input data by software. 28.6.8 Mono When the Mono bit (MONO) in the Control Register is set, data written to SDR0 will be used for both output channels. If one of the compact stereo formats are used only the data written to the part of SDR0 that corresponds with channel 0 is used. 28.6.9 Alternative Upsampling Ratio The digital filters and Sigma Delta modulators requires its own clock to perform the conversion at the correct speed, and this clock is provided by a generic clock in the SCIF. The frequency of this clock depends on the input sample rate and the upsampling ratio which is controlled by the Alternative Upsampling Ratio bit (ALTUPR) in the Control Register. The ABDACB supports three upsampling ratios, 125, 128, and 136. The default setting is a ratio of 128, and is used when CR.ALTUPR is zero. Using this ratio gives a clock frequency requirement that is common for audio products. In some cases one may want to use other clock frequencies that already are available in the system. By writing a one to CR.ALTUPR a upsampling ratio of 125 or 136 is used depending on the configuration of the Sampling Frequency field in the Control Register. Refer to Table 28-3 for required clock frequency and settings. The required clock frequency of the generic clock can be calculated from the following equation: R is the upsampling ratio of the converter. If CR.ALTUPR is zero the upsampling ratio is 128. If CR.ALTUPR is one, R will change to 125 when CR.FS is configured for 8kHz, 12kHz, 16kHz, 24kHz, 32kHz, and 48kHz. For the other configurations of CR.FS, 11.025kHz, 22.050kHz, and 44.100kHz, it will change to 136. 28.6.10 DMA operation The Audio Bitstream DAC is connected to the Peripheral DMA Controller. The Peripheral DMA Controller can be programmed to automatically transfer samples to the Sample Data Registers (SDR0 and SDR1) when the Audio Bitstream DAC is ready for new samples. Two DMA channels are used, one for each sample data register. If the Mono Mode bit in the Control Register (CR.MONO) is one, or one of the compact stereo formats is used, only the DMA channel connected to SDR0 will be used. When using DMA only the Control Register needs to be written in the Audio Bitstream DAC. This enables the Audio Bitstream DAC to operate without any CPU intervention such as polling the Status Register (SR) or using interrupts. See the Peripheral DMA Controller documentation for details on how to setup Peripheral DMA transfers. 28.6.11 Interrupts The ABDACB requires new data samples at a rate of FS. The interrupt status bits are used to indicate when the system is ready to receive new samples. The Transmit Ready Interrupt Status bit in the Status Register (SR.TXRDY) will be set whenever the ABDACB is ready to receive a new sample. A new sample value must be written to the sample data registers (SDR0 and VOUT 1 2 -- 33 128 – --------- SDR 215 ------------ VOLUME 215 – 1   ------------------------     VVDDIO =  GCLK[Hz] F = S   R 8 693 32142D–06/2013 ATUC64/128/256L3/4U SDR1) before 1/FS second, or an underrun will occur, as indicated by the Underrun Interrupt bit in SR (SR.TXUR). The interrupt bits in SR are cleared by writing a one to the corresponding bit in the Status Clear Register (SCR). 28.6.12 Frequency Response Figure Figure 28-4 to Figure 28-7 show the frequency response for the system. The sampling frequency used is 48kHz, but the response will be the same for other sampling frequencies, always having the first zero at FS. Figure 28-4. Passband Frequency Response 694 32142D–06/2013 ATUC64/128/256L3/4U Figure 28-5. Frequency Response up to Sampling Frequency Figure 28-6. Frequency Response up to 3x Sampling Frequency 695 32142D–06/2013 ATUC64/128/256L3/4U Figure 28-7. Frequency Response up to 128x Sampling Frequency 696 32142D–06/2013 ATUC64/128/256L3/4U 28.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 28-2. ABDACB Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Read/Write 0x00000000 0x04 Sample Data Register 0 SDR0 Read/Write 0x00000000 0x08 Sample Data Register 1 SDR1 Read/Write 0x00000000 0x0C Volume Control Register 0 VCR0 Read/Write 0x00000000 0x10 Volume Control Register 1 VCR1 Read/Write 0x00000000 0x14 Interrupt Enable Register IER Write-only 0x00000000 0x18 Interrupt Disable Register IDR Write-only 0x00000000 0x1C Interrupt Mask Register IMR Read-only 0x00000000 0x20 Status Register SR Read-only 0x00000000 0x24 Status Clear Register SCR Write-only 0x00000000 0x28 Parameter Register PARAMETER Read-only - (1) 0x2C Version Register VERSION Read-only - (1) 697 32142D–06/2013 ATUC64/128/256L3/4U 28.7.1 Control Register Name: CR Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • FS: Sampling Frequency Must be set to the matching data sampling frequency, see Table 28-3. Note: 1. The actual clock requirement are 11.9952MHz, 23.9904MHz, and 47.9808MHz, but this is very close to the suggested clock frequencies, and will only result in a very small frequency shift. This need to be accounted for during testing if comparing to a reference signal. Notes: 1. 31 30 29 28 27 26 25 24 - - - - FS 23 22 21 20 19 18 17 16 - - - - - DATAFORMAT 15 14 13 12 11 10 9 8 -------- 76543210 SWRST - MONO CMOC ALTUPR - SWAP EN Table 28-3. Generic Clock Requirements CR.FS Description GCLK (CR.ALTUPR=1) GCLK (CR.ALTUPR=0) 0 8000Hz sampling frequency 8.0MHz 8.1920MHz 1 11025Hz sampling frequency 12.0MHz(1) 11.2896MHz 2 12000Hz sampling frequency 12.0MHz 12.2880MHz 3 16000Hz sampling frequency 16.0MHz 16.3840MHz 4 22050Hz sampling frequency 24.0MHz(1) 22.5792MHz 5 24000Hz sampling frequency 24.0MHz 24.5760MHz 6 32000Hz sampling frequency 32.0MHz 32.7680MHz 7 44100Hz sampling frequency 48.0MHz(1) 45.1584MHz 8 48000Hz sampling frequency 48.0MHz 49.1520MHz Other Reserved - - 698 32142D–06/2013 ATUC64/128/256L3/4U • DATAFORMAT: Data Word Format • SWRST: Software Reset Writing a zero to this bit does not have any effect. Writing a one to this bit will reset the ABDACB as if a hardware reset was done. • MONO: Mono Mode 0: Mono mode is disabled. 1: Mono mode is enabled. • CMOC: Common Mode Offset Control 0: Common mode adjustment is disabled. 1: Common mode adjustment is enabled. • ALTUPR: Alternative Upsampling Ratio 0: Alternative upsampling is disabled. 1: Alternative upsampling is enabled. • SWAP: Swap Channels 0: Channel swap is disabled. 1: Channel swap is enabled. • EN: Enable 0: The ABDACB is disabled. 1: The ABDACB is enabled. Table 28-4. Data Word Format DATAFORMAT Word length Comment 0 32 bits 1 24 bits 2 20 bits 3 18 bits 4 16 bits 5 16 bits compact stereo Channel 1 sample in bits 31 through 16, channel 0 sample in bits 15 through 0 in SDR0 6 8 bits 7 8 bits compact stereo Channel 1 sample in bits 15 through 8, channel 0 sample in bits 7through 0 in SDR0 699 32142D–06/2013 ATUC64/128/256L3/4U 28.7.2 Sample Data Register 0 Name: SDR0 Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • DATA: Sample Data Sample Data for channel 0 in two’s complement format. Data must be right-justified, see Table 28-5. 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] Table 28-5. Sample Data Register Formats Data Format SDR0 SDR1 Comment 32 bits CH0 sample in DATA[31:0] CH1 sample in DATA[31:0] 24 bits CH0 sample in DATA[23:0] CH1 sample in DATA[23:0] Remaining bits are ignored. 20 bits CH0 sample in DATA[19:0] CH1 sample in DATA[19:0] Remaining bits are ignored. 18 bits CH0 sample in DATA[17:0] CH1 sample in DATA[17:0] Remaining bits are ignored. 16 bits CH0 sample in DATA[15:0] CH1 sample in DATA[15:0] Remaining bits are ignored. 16 bits compact stereo CH0 sample in DATA[15:0] CH1 sample in DATA[31:16] Not used 8 bits CH0 sample in DATA[7:0] CH1 sample in DATA[7:0] Remaining bits are ignored. 8 bits compact stereo CH0 sample in DATA[7:0] CH1 sample in DATA[15:8] Not used Remaining bits are ignored. 700 32142D–06/2013 ATUC64/128/256L3/4U 28.7.3 Sample Data Register 1 Name: SDR1 Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • DATA: Sample Data Sample Data for channel 1 in two’s complement format. Data must be right-justified, see Table 28-5 on page 699. 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 701 32142D–06/2013 ATUC64/128/256L3/4U 28.7.4 Volume Control Register 0 Name: VCR0 Access Type: Read/Write Offset: 0x0C Reset Value: 0x00000000 • MUTE: Mute 0: Channel 0 is not muted. 1: Channel 0 is muted. • VOLUME: Volume Control 15-bit value adjusting the volume for channel 0. 31 30 29 28 27 26 25 24 MUTE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - VOLUME[14:8] 76543210 VOLUME[7:0] 702 32142D–06/2013 ATUC64/128/256L3/4U 28.7.5 Volume Control Register 1 Name: VCR1 Access Type: Read/Write Offset: 0x10 Reset Value: 0x00000000 • MUTE: Mute 0: Channel 1 is not muted. 1: Channel 1 is muted. • VOLUME: Volume Control 15-bit value adjusting the volume for channel 1. 31 30 29 28 27 26 25 24 MUTE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - VOLUME[14:8] 76543210 VOLUME[7:0] 703 32142D–06/2013 ATUC64/128/256L3/4U 28.7.6 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY - 704 32142D–06/2013 ATUC64/128/256L3/4U 28.7.7 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY - 705 32142D–06/2013 ATUC64/128/256L3/4U 28.7.8 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY - 706 32142D–06/2013 ATUC64/128/256L3/4U 28.7.9 Status Register Name: SR Access Type: Read-only Offset: 0x20 Reset Value: 0x00000000 • TXUR: Transmit Underrun This bit is cleared when no underrun has occurred since the last time this bit was cleared (by reset or by writing to SCR). This bit is set when at least one underrun has occurred since the last time this bit was cleared (by reset or by writing to SCR). • TXRDY: Transmit Ready This bit is cleared when the ABDACB is not ready to receive a new data in SDR. This bit is set when the ABDACB is ready to receive a new data in SDR. • BUSY: ABDACB Busy This bit is set when the ABDACB is busy doing a data transfer between clock domains. CR, SDR0, and SDR1 can not be written during this time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY BUSY 707 32142D–06/2013 ATUC64/128/256L3/4U 28.7.10 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x24 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY - 708 32142D–06/2013 ATUC64/128/256L3/4U 28.7.11 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x28 Reset Value: 0x00000000 Reserved. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 709 32142D–06/2013 ATUC64/128/256L3/4U 28.7.12 Version Register Name: VERSION Access Type: Read-only Offset: 0x2C Reset Value: 0x00000000 • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 710 32142D–06/2013 ATUC64/128/256L3/4U 28.8 Module Configuration The specific configuration for each ABDACB instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 28-6. ABDACB Clocks Clock Name Description CLK_ABDACB Clock for the ABDACB bus interface GCLK The generic clock used for the ABDACB is GCLK6 Table 28-7. Register Reset Values Register Reset Value VERSION 0x00000100 PARAMETER 0x00000000 711 32142D–06/2013 ATUC64/128/256L3/4U 29. ADC Interface (ADCIFB) Rev:1.0.1.1 29.1 Features • Multi-channel Analog-to-Digital Converter with up to 12-bit resolution • Enhanced Resolution Mode – 11-bit resolution obtained by interpolating 4 samples – 12-bit resolution obtained by interpolating 16 samples • Glueless interface with resistive touch screen panel, allowing – Resistive Touch Screen position measurement – Pen detection and pen loss detection • Integrated enhanced sequencer – ADC Mode – Resistive Touch Screen Mode • Numerous trigger sources – Software – Embedded 16-bit timer for periodic trigger – Pen detect trigger – Continuous trigger – External trigger, rising, falling, or any-edge trigger – Peripheral event trigger • ADC Sleep Mode for low power ADC applications • Programmable ADC timings – Programmable ADC clock – Programmable startup time 29.2 Overview The ADC Interface (ADCIFB) converts analog input voltages to digital values. The ADCIFB is based on a Successive Approximation Register (SAR) 10-bit Analog-to-Digital Converter (ADC). The conversions extend from 0V to ADVREFP. The ADCIFB supports 8-bit and 10-bit resolution mode, in addition to enhanced resolution mode with 11-bit and 12-bit resolution. Conversion results are reported in a common register for all channels. The 11-bit and 12-bit resolution modes are obtained by interpolating multiple samples to acquire better accuracy. For 11-bit mode 4 samples are used, which gives an effective sample rate of 1/4 of the actual sample frequency. For 12-bit mode 16 samples are used, giving a effective sample rate of 1/16 of actual. This arrangement allows conversion speed to be traded for better accuracy. Conversions can be started for all enabled channels, either by a software trigger, by detection of a level change on the external trigger pin (TRIGGER), or by an integrated programmable timer. When the Resistive Touch Screen Mode is enabled, an integrated sequencer automatically configures the pad control signals and performs resistive touch screen conversions. The ADCIFB also integrates an ADC Sleep Mode, a Pen-Detect Mode, and an Analog Compare Mode, and connects with one Peripheral DMA Controller channel. These features reduce both power consumption and processor intervention. 712 32142D–06/2013 ATUC64/128/256L3/4U 29.3 Block Diagram Figure 29-1. ADCIFB Block Diagram ADVREFP Analog Multiplexer Successive Approximation Register Analog-to-Digital Converter Trigger ADC Control Logic Timer User Interface AD0 AD1 AD3 ADn AD2 Resisitve Touch Screen Sequencer CLK_ADCIFB .... ADCIFB ADP0 ADP1 I/O Controller TRIGGER Peripheral Bus DMA Request Interrupt Request CLK_ADC 713 32142D–06/2013 ATUC64/128/256L3/4U 29.4 I/O Lines Description 29.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 29.5.1 I/O Lines The analog input pins can be multiplexed with I/O Controller lines. The user must make sure the I/O Controller is configured correctly to allow the ADCIFB access to the AD pins before the ADCIFB is instructed to start converting data. If the user fails to do this the converted data may be wrong. The number of analog inputs is device dependent, please refer to the ADCIFB Module Configuration chapter for the number of available AD inputs on the current device. The ADVREFP pin must be connected correctly prior to using the ADCIFB. Failing to do so will result in invalid ADC operation. See the Electrical Characteristics chapter for details. If the TRIGGER, ADP0, and ADP1 pins are to be used in the application, the user must configure the I/O Controller to assign the needed pins to the ADCIFB function. 29.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the ADCIFB, the ADCIFB will stop functioning and resume operation after the system wakes up from sleep mode. If the Peripheral Event System is configured to send asynchronous peripheral events to the ADCIFB and the clock used by the ADCIFB is stopped, a local and temporary clock will automatically be requested so the event can be processed. Refer to Section 29.6.13, Section 29.6.12, and the Peripheral Event System chapter for details. Before entering a sleep mode where the clock to the ADCIFB is stopped, make sure the Analogto-Digital Converter cell is put in an inactive state. Refer to Section 29.6.13 for more information. 29.5.3 Clocks The clock for the ADCIFB bus interface (CLK_ADCIFB) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the ADCIFB before disabling the clock, to avoid freezing the ADCIFB in an undefined state. Table 29-1. I/O Lines Description Pin Name Description Type ADVREFP Reference voltage Analog TRIGGER External trigger Digital ADP0 Drive Pin 0 for Resistive Touch Screen top channel (Xp) Digital ADP1 Drive Pin 1 for Resistive Touch Screen right channel (Yp) Digital AD0-ADn Analog input channels 0 to n Analog 714 32142D–06/2013 ATUC64/128/256L3/4U 29.5.4 DMA The ADCIFB DMA handshake interface is connected to the Peripheral DMA Controller. Using the ADCIFB DMA functionality requires the Peripheral DMA Controller to be programmed first. 29.5.5 Interrupts The ADCIFB interrupt request line is connected to the interrupt controller. Using the ADCIFB interrupt request functionality requires the interrupt controller to be programmed first. 29.5.6 Peripheral Events The ADCIFB peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details 29.5.7 Debug Operation When an external debugger forces the CPU into debug mode, this module continues normal operation. If this module is configured in a way that requires it to be periodically serviced by the CPU through interrupt requests or similar, improper operation or data loss may result during debugging. 29.6 Functional Description The ADCIFB embeds a Successive Approximation Register (SAR) Analog-to-Digital Converter (ADC). The ADC supports 8-bit or 10-bit resolution, which can be extended to 11 or 12 bits by the Enhanced Resolution Mode. The conversion is performed on a full range between 0V and the reference voltage pin ADVREFP. Analog inputs between these voltages converts to digital values (codes) based on a linear conversion. This linear conversion is described in the expression below where M is the number of bits used to represent the analog value, Vin is the voltage of the analog value to convert, Vref is the maximum voltage, and Code is the converted digital value. 29.6.1 Initializing the ADCIFB The ADC Interface is enabled by writing a one to the Enable bit in the Control Register (CR.EN). After the ADC Interface is enabled, the ADC timings needs to be configured by writing the correct values to the RES, PRESCAL, and STARTUP fields in the ADC Configuration Register (ACR). See Section 29.6.5, and Section 29.6.7 for details. Before the ADCIFB can be used, the I/O Controller must be configured correctly and the Reference Voltage (ADVREFP) signal must be connected. Refer to Section 29.5.1 for details. 29.6.2 Basic Operation To convert analog values to digital values the user must first initialize the ADCIFB as described in Section 29.6.1. When the ADCIFB is initialized the channels to convert must be enabled by writing a one the corresponding bits in the Channel Enable Register (CHER). Enabling channel N instructs the ADCIFB to convert the analog voltage applied to AD pin N at each conversion sequence. Multiple channels can be enabled resulting in multiple AD pins being converted at each conversion sequence. Code 2M Vin  Vref = ------------------- 715 32142D–06/2013 ATUC64/128/256L3/4U To start converting data the user can either manually start a conversion sequence by writing a one to the START bit in the Control Register (CR.START) or configure an automatic trigger to initiate the conversions. The automatic trigger can be configured to trig on many different conditions. Refer to Section 29.8.1 for details. The result of the conversion is stored in the Last Converted Data Register (LCDR) as they become available, overwriting the result from the previous conversion. To avoid data loss if more than one channel is enabled, the user must read the conversion results as they become available either by using an interrupt handler or by using a Peripheral DMA channel to copy the results to memory. Failing to do so will result in an Overrun Error condition, indicated by the OVRE bit in the Status Register (SR). To use an interrupt handler the user must enable the Data Ready (DRDY) interrupt request by writing a one to the corresponding bit in the Interrupt Enable Register (IER). To clear the interrupt after the conversion result is read, the user must write a one to the corresponding bit in the Interrupt Clear Register (ICR). See Section 29.6.11 for details. To use a Peripheral DMA Controller channel the user must configure the Peripheral DMA Controller appropriately. The Peripheral DMA Controller will, when configured, automatically read converted data as they become available. There is no need to manually clear any bits in the Interrupt Status Register as this is performed by the hardware. If an Overrun Error condition happens during DMA operation, the OVRE bit in the SR will be set. 29.6.3 ADC Resolution The Analog-to-Digital Converter cell supports 8-bit or 10-bit resolution, which can be extended to 11-bit and 12-bit with the Enhanced Resolution Mode. The resolution is selected by writing the selected resolution value to the RES field in the ADC Configuration Register (ACR). See Section 29.9.3. By writing a zero to the RES field, the ADC switches to the lowest resolution and the conversion results can be read in the eight lowest significant bits of the Last Converted Data Register (LCDR). The four highest bits of the Last Converted Data (LDATA) field in the LCDR register reads as zero. Writing a one to the RES field enables 10-bit resolution, the optimal resolution for both sampling speed and accuracy. Writing two or three automatically enables Enhanced Resolution Mode with 11-bit or 12-bit resolution, see Section 29.6.4 for details. When a Peripheral DMA Controller channel is connected to the ADCIFB in 10-bit, 11-bit, or 12- bit resolution mode, a transfer size of 16 bits must be used. By writing a zero to the RES field, the destination buffers can be optimized for 8-bit transfers. 29.6.4 Enhanced Resolution Mode The Enhanced Resolution Mode is automatically enabled when 11-bit or 12-bit mode is selected in the ADC Configuration Register (ACR). In this mode the ADCIFB will trade conversion performance for accuracy by averaging multiple samples. To be able to increase the accuracy by averaging multiple samples it is important that some noise is present in the input signal. The noise level should be between one and two LSB peakto-peak to get good averaging performance. The performance cost of enabling 11-bit mode is 4 ADC samples, which reduces the effective ADC performance by a factor 4. For 12-bit mode this factor is 16. For 12-bit mode the effective sample rate is maximum ADC sample rate divided by 16. 716 32142D–06/2013 ATUC64/128/256L3/4U 29.6.5 ADC Clock The ADCIFB generates an internal clock named CLK_ADC that is used by the Analog-to-Digital Converter cell to perform conversions. The CLK_ADC frequency is selected by writing to the PRESCAL field in the ADC Configuration Register (ACR). The CLK_ADC range is between CLK_ADCIFB/2, if PRESCAL is 0, and CLK_ADCIFB/128, if PRESCAL is 63 (0x3F). A sensible PRESCAL value must be used in order to provide an ADC clock frequency according to the maximum sampling rate parameter given in the Electrical Characteristics section. Failing to do so may result in incorrect Analog-to-Digital Converter operation. 29.6.6 ADC Sleep Mode The ADC Sleep Mode maximizes power saving by automatically deactivating the Analog-to-Digital Converter cell when it is not being used for conversions. The ADC Sleep Mode is enabled by writing a one to the SLEEP bit in the ADC Configuration Register (ACR). When a trigger occurs while the ADC Sleep Mode is enabled, the Analog-to-Digital Converter cell is automatically activated. As the analog cell requires a startup time, the logic waits during this time and then starts the conversion of the enabled channels. When conversions of all enabled channels are complete, the ADC is deactivated until the next trigger. 29.6.7 Startup Time The Analog-to-Digital Converter cell has a minimal startup time when the cell is activated. This startup time is given in the Electrical Characteristics chapter and must be written to the STARTUP field in the ADC Configuration Register (ACR) to get correct conversion results. The STARTUP field expects the startup time to be represented as the number of CLK_ADC cycles between 8 and 1024 and in steps of 8 that is needed to cover the ADC startup time as specified in the Electrical Characteristics chapter. The Analog-to-Digital Converter cell is activated at the first conversion after reset and remains active if ACR.SLEEP is zero. If ACR.SLEEP is one, the Analog-to-Digital Converter cell is automatically deactivated when idle and thus each conversion sequence will have a initial startup time delay. 29.6.8 Sample and Hold Time A minimal Sample and Hold Time is necessary for the ADCIFB to guarantee the best converted final value when switching between ADC channels. This time depends on the input impedance of the analog input, but also on the output impedance of the driver providing the signal to the analog input, as there is no input buffer amplifier. The Sample and Hold time has to be programmed through the SHTIM field in the ADC Configuration Register (ACR). This field can define a Sample and Hold time between 1 and 16 CLK_ADC cycles. 29.6.9 ADC Conversion ADC conversions are performed on all enabled channels when a trigger condition is detected. For details regarding trigger conditions see Section 29.8.1. The term channel is used to identify a specific analog input pin so it can be included or excluded in an Analog-to-Digital conversion sequence and to identify which AD pin was used to convert the current value in the Last Converted Data Register (LCDR). Channel number N corresponding to AD pin number N. 717 32142D–06/2013 ATUC64/128/256L3/4U Channels are enabled by writing a one to the corresponding bit in the Channel Enable Register (CHER), and disabled by writing a one to the corresponding bit in the Channel Disable Register (CHDR). Active channels are listed in the Channel Status Register (CHSR). When a conversion sequence is started, all enabled channels will be converted in one sequence and the result will be placed in the Last Converted Data Register (LCDR) with the channel number used to produce the result. It is important to read out the results while the conversion sequence is ongoing, as new values will automatically overwrite any old value and the old value will be lost if not previously read by the user. If the Analog-to-Digital Converter cell is inactive when starting a conversion sequence, the conversion logic will wait a configurable number of CLK_ADC cycles as defined in the startup time field in the ADC Configuration Register (ACR). After the cell is activated all enabled channels is converted one by one until no more enabled channels exist. The conversion sequence converts each enabled channel in order starting with the channel with the lowest channel number. If the ACR.SLEEP bit is one, the Analog-to-Digital Converter cell is deactivated after the conversion sequence has finished. For each channel converted, the ADCIFB waits a Sample and Hold number of CLK_ADC cycles as defined in the SHTIM field in ACR, and then instructs the Analog-to-Digital Converter cell to start converting the analog voltage. The ADC cell requires 10 CLK_ADC cycles to actually convert the value, so the total time to convert a channel is Sample and Hold + 10 CLK_ADC cycles. 29.6.10 Analog Compare Mode The ADCIFB can test if the converted values, as they become available, are below, above, or inside a specified range and generate interrupt requests based on this information. This is useful for applications where the user wants to monitor some external analog signal and only initiate actions if the value is above, below, or inside some specified range. The Analog Compare mode is enabled by writing a one to the Analog Compare Enable (ACE) bit in the Mode Register (MR). The values to compare must be written to the Low Value (LV) field and the High Value (HV) field in the Compare Value Register (CVR). The Analog Compare mode will, when enabled, check all enabled channels against the pre-programmed high and low values and set status bits. To generate an interrupt request if a converted value is below a limit, write the limit to the CVR.LV field and enable interrupt request on the Compare Lesser Than (CLT) bit by writing a one to the corresponding bit in the Interrupt Enable Register (IER). To generate an interrupt request if a converted value is above a limit, write the limit to the CVR.HV field and enable interrupt for Compare Greater Than (CGT) bit. To generate an interrupt request if a converted value is inside a range, write the low and high limit to the LV and HV fields and enable the Compare Else (CELSE) interrupt. To generate an interrupt request if a value is outside a range, write the LV and HV fields to the low and high limits of the range and enable CGT and CLT interrupts. Note that the values written to LV and HV must match the resolution selected in the ADC Configuration Register (ACR). 29.6.11 Interrupt Operation Interrupt requests are enabled by writing a one to the corresponding bit in the Interrupt Enable Register (IER) and disabled by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). Enabled interrupts can be read from the Interrupt Mask Register (IMR). Active interrupt requests, but potentially masked, are visible in the Interrupt Status Register (ISR). To 718 32142D–06/2013 ATUC64/128/256L3/4U clear an active interrupt request, write a one to the corresponding bit in the Interrupt Clear Register (ICR). The source for the interrupt requests are the status bits in the Status Register (SR). The SR shows the ADCIFB status at the time the register is read. The Interrupt Status Register (ISR) shows the status since the last write to the Interrupt Clear Register. The combination of ISR and SR allows the user to react to status change conditions but also allows the user to read the current status at any time. 29.6.12 Peripheral Events The Peripheral Event System can be used together with the ADCIFB to allow any peripheral event generator to be used as a trigger source. To enable peripheral events to trigger a conversion sequence the user must write the Peripheral Event Trigger value (0x7) to the Trigger Mode (TRGMOD) field in the Trigger Register (TRGR). Refer to Table 29-4 on page 730. The user must also configure a peripheral event generator to emit peripheral events for the ADCIFB to trigger on. Refer to the Peripheral Event System chapter for details. 29.6.13 Sleep Mode Before entering sleep modes the user must make sure the ADCIFB is idle and that the Analogto-Digital Converter cell is inactive. To deactivate the Analog-to-Digital Converter cell the SLEEP bit in the ADC Configuration Register (ACR) must be written to one and the ADCIFB must be idle. To make sure the ADCIFB is idle, write a zero the Trigger Mode (TRGMOD) field in the Trigger Register (TRGR) and wait for the READY bit in the Status Register (SR) to be set. Note that by deactivating the Analog-to-Digital Converter cell, a startup time penalty as defined in the STARTUP field in the ADC Configuration Register (ACR) will apply on the next conversion. 29.6.14 Conversion Performances For performance and electrical characteristics of the ADCIFB, refer to the Electrical Characteristics chapter. 29.7 Resistive Touch Screen The ADCIFB embeds an integrated Resistive Touch Screen Sequencer that can be used to calculate contact coordinates on a resistive touch screen film. When instructed to start, the integrated Resistive Touch Screen Sequencer automatically applies a sequence of voltage patterns to the resistive touch screen films and the Analog-to-Digital Conversion cell is used to measure the effects. The resulting measurements can be used to calculate the horizontal and vertical contact coordinates. It is recommended to use a high resistance touch screen for optimal resolution. The resistive touch screen film is connected to the ADCIFB using the AD and ADP pins. See Section 29.7.3 for details. Resistive Touch Screen Mode is enabled by writing a one to the Touch Screen ADC Mode field in the Mode Register (MR.TSAMOD). In this mode, channels TSPO+0 though TSPO+3 are automatically enabled where TSPO refers to the Touch Screen Pin Offset field in the Mode Register (MR.TSPO). For each conversion sequence, all enabled channels before TSPO+0 and after TSPO+3 are converted as ordinary ADC channels, producing 1 conversion result each. When the sequencer enters the TSPO+0 channel the Resistive Touch Screen Sequencer will take over control and convert the next 4 channels as described in Section 29.7.4. 719 32142D–06/2013 ATUC64/128/256L3/4U 29.7.1 Resistive Touch Screen Principles A resistive touch screen is based on two resistive films, each one fitted with a pair of electrodes, placed at the top and bottom on one film, and on the right and left on the other. Between the two, there is a layer that acts as an insulator, but makes a connection when pressure is applied to the screen. This is illustrated in Figure 29-2 on page 719. Figure 29-2. Resistive Touch Screen Position Measurement 29.7.2 Position Measurement Method As shown in Figure 29-2 on page 719, to detect the position of a contact, voltage is first applied to XP (top) and Xm (bottom) leaving Yp and Ym tristated. Due to the linear resistance of the film, there is a voltage gradient from top to bottom on the first film. When a contact is performed on the screen, the voltage at the contact point propagates to the second film. If the input impedance on the YP (right) and Ym (left) electrodes are high enough, no current will flow, allowing the voltage at the contact point to be measured at Yp. The value measured represents the vertical position component of the contact point. For the horizontal direction, the same method is used, but by applying voltage from YP (right) to Ym (left) and measuring at XP. In an ideal world (linear, with no loss), the vertical position is equal to: VYP / VDD To compensate for some of the real world imperfections, VXP and VXm can be measured and used to improve accuracy at the cost of two more conversions per axes. The new expression for the vertical position then becomes: (VYP - VXM) / (VXP - VXM) XM XP YM YP XP XM YP VDD GND Volt Horizontal Position Detection YP YM XP VDD GND Volt Vertical Position Detection Pen Contact 720 32142D–06/2013 ATUC64/128/256L3/4U 29.7.3 Resistive Touch Screen Pin Connections The resistive touch screen film signals connects to the ADCIFB using the AD and ADP pins. The XP (top) and XM (bottom) film signals are connected to ADtspo+0 and ADtspo+1 pins, and the YP (right) and YM (left) signals are connected to ADtspo+2 and ADtspo+3 pins. The tspo index is configurable through the Touch Screen Pin Offset (TSPO) field in the Mode Register (MR) and allows the user to configure which AD pins to use for resistive touch screen applications. Writing a zero to the TSPO field instructs the ADCIFB to use AD0 through AD3, where AD0 is connected to XP, AD1 is connected to XM and so on. Writing a one to the TSPO field instructs the ADCIFB to use AD1 through AD4 for resistive touch screen sequencing, where AD1 is connected to XP and AD0 is free to be used as an ordinary ADC channel. When the Analog Pin Output Enable (APOE) bit in the Mode Register (MR) is zero, the AD pins are used to measure input voltage and drive the GND sequences, while the ADP pins are used to drive the VDD sequences. This arrangement allows the user to reduce the voltage seen at the AD input pins by inserting external resistors between ADP0 and XP and ADP1 and YP signals which are again directly connected to the AD pins. It is important that the voltages observed at the AD pins are not higher than the maximum allowed ADC input voltage. See Figure 29-3 on page 721 for details regarding how to connect the resistive touch screen films to the AD and ADP pins. By adding a resistor between ADP0 and XP, and ADP1 and YP, the maximum voltage observed at the AD pins can be controlled by the following voltage divider expressions: The Rfilmx parameter is the film resistance observed when measuring between XP and XM. The Rresistorx parameter is the resistor size inserted between ADP0 and XP. The definition of Rfilmy and Rresistory is the same but for ADP1, YP, and YM instead. Table 29-2. Resistive Touch Screen Pin Connections ADCIFB Pin TS Signal, APOE == 0 TS Signal, APOE == 1 ADP0 Xp through a resistor No Connect ADP1 Yp through a resistor No Connect ADtspo+0 Xp Xp ADtspo+1 Xm Xm ADtspo+2 Yp Yp ADtspo+3 Ym Ym V ADtspo + 0   Rfilmx Rfilmx Rresistorx + -------------------------------------------- V DP0 =    721 32142D–06/2013 ATUC64/128/256L3/4U The ADP pins are used by default, as the APOE bit is zero after reset. Writing a one to the APOE bit instructs the ADCIFB Resistive Touch Screen Sequencer to use the already connected ADtspo+0 and ADtspo+2 pins to drive VDD to XP and YP signals directly. In this mode the ADP pins can be used as general purpose I/O pins. Before writing a one to the APOE bit the user must make sure that the I/O voltage is compatible with the ADC input voltage. If the I/O voltage is higher than the maximum input voltage of the ADC, permanent damage may occur. Refer to the Electrical Characteristics chapter for details. Figure 29-3. Resistive Touch Screen Pin Connections V ADtspo + 2   Rfilmy Rfilmy Rresistory + -------------------------------------------- V DP1 =    ADtspo+1 XM XP YM YP ADtspo+0 DP1 DP0 ADtspo+3 ADtspo+2 Analog Pin Output Enable (MR.APOE) == 0 ADtspo+1 XM XP YM YP ADtspo+0 DP1 DP0 ADtspo+3 ADtspo+2 Analog Pin Output Enable (MR.APOE) == 1 NC NC 722 32142D–06/2013 ATUC64/128/256L3/4U 29.7.4 Resistive Touch Screen Sequencer The Resistive Touch Screen Sequencer is responsible for applying voltage to the resistive touch screen films as described in Section 29.7.2. This is done by controlling the output enable and the output value of the ADP and AD pins. This allows the Resistive Touch Screen Sequencer to add a voltage gradient on one film while keeping the other film floating so a touch can be measured. The Resistive Touch Screen Sequencer will when measuring the vertical position, apply VDD and GND to the pins connected to XP and XM. The YP and YM pins are put in tristate mode so the measurement of YP can proceed without interference. To compensate for ADC offset errors and non ideal pad drivers, the actual voltage of XP and XM is measured as well, so the real values for VDD and GND can be used in the contact point calculation to increase accuracy. See second formula in Section 29.7.2. When the vertical values are converted the same setup is applies for the second axes, by setting XP and XM in tristate mode and applying VDD and GND to YP and YM. Refer to Section 29.8.3 for details. 29.7.5 Pen Detect If no contact is applied to the resistive touch screen films, any resistive touch screen conversion result will be undefined as the film being measured is floating. This can be avoided by enabling Pen Detect and only trigger resistive touch screen conversions when the Pen Contact (PENCNT) status bit in the Status Register (SR) is one. Pen Detect is enabled by writing a one to the Pen Detect (PENDET) bit in the Mode Register (MR). When Pen Detect is enabled, the ADCIFB grounds the vertical panel by applying GND to XP and XM and polarizes the horizontal panel by enabling pull-up on the pin connected to YP. The YM pin will in this mode be tristated. Since there is no contact, no current is flowing and there is no related power consumption. As soon as a contact occurs, GND will propagate to YM by pulling down YP, allowing the contact to be registered by the ADCIFB. A programmable debouncing filter can be used to filter out false pen detects because of noise. The debouncing filter is programmable from one CLK_ADC period and up to 215 CLK_ADC periods. The debouncer length is set by writing to the PENDBC field in MR. 723 32142D–06/2013 ATUC64/128/256L3/4U Figure 29-4. Resistive Touch Screen Pen Detect The Resistive Touch Screen Pen Detect can be used to generate an ADCIFB interrupt request or it can be used to trig a conversion, so that a position can be measured as soon as a contact is detected. The Pen Detect Mode generates two types of status signals, reported in the Status Register (SR): • The bit PENCNT is set when current flows and remains set until current stops. • The bit NOCNT is set when no current flows and remains set until current flows. Before a current change is reflected in the SR, the new status must be stable for the duration of the debouncing time. Both status conditions can generate an interrupt request if the corresponding bit in the Interrupt Mask Register (IMR) is one. Refer to Section 29.6.11 on page 717. XP XM YM YP Tristate GND Pullup T o the ADC Debouncer Pen Interrupt PENDBC GND Resistive Touch Screen Sequencer 724 32142D–06/2013 ATUC64/128/256L3/4U 29.8 Operating Modes The ADCIFB features two operating modes, each defining a separate conversion sequence: • ADC Mode: At each trigger, all the enabled channels are converted. • Resistive Touch Screen Mode: At each trigger, all enabled channels plus the resistive touch screen channels are converted as described in Section 29.8.3. If channels except the dedicated resistive touch screen channels are enabled, they are converted normally before and after the resistive touch screen channels are converted. The operating mode is selected by the TSAMOD field in the Mode Register (MR). 29.8.1 Conversion Triggers A conversion sequence is started either by a software or by a hardware trigger. When a conversion sequence is started, all enabled channels will be converted and made available in the shared Last Converted Register (LCDR). The software trigger is asserted by writing a one to the START field in the Control Register (CR). The hardware trigger can be selected by the TRGMOD field in the Trigger Register (TRGR). Different hardware triggers exist: • External trigger, either rising or falling or any, detected on the external trigger pin TRIGGER • Pen detect trigger, depending the PENDET bit in the Mode Register (MR) • Continuous trigger, meaning the ADCIFB restarts the next sequence as soon as it finishes the current one • Periodic trigger, which is defined by the TRGR.TRGPER field • Peripheral event trigger, allowing the Peripheral Event System to synchronize conversion with some configured peripheral event source. Enabling a hardware trigger does not disable the software trigger functionality. Thus, if a hardware trigger is selected, the start of a conversion can still be initiated by the software trigger. 29.8.2 ADC Mode In the ADC Mode, the active channels are defined by the Channel Status Register (CHSR). A channel is enabled by writing a one to the corresponding bit in the Channel Enable Register (CHER), and disabled by writing a one to the corresponding bit in the Channel Disable Register (CHDR). The conversion results are stored in the Last Converted Data Register (LCDR) as they become available, overwriting old conversions. At each trigger, the following sequence is performed: 1. If ACR.SLEEP is one, wake up the ADC and wait for the startup time. 2. If Channel 0 is enabled, convert Channel 0 and store result in LCDR. 3. If Channel 1 is enabled, convert Channel 1 and store result in LCDR. 4. If Channel N is enabled, convert Channel N and store result in LCDR. 5. If ACR.SLEEP is one, place the ADC cell in a low-power state. If the Peripheral DMA Controller is enabled, all converted values are transferred continuously into the memory buffer. 29.8.3 Resistive Touch Screen Mode Writing a one to the TSAMOD field in the Mode Register (MR) enables Resistive Touch Screen Mode. In this mode the channels TSPO+0 to TSPO+3, corresponding to the resistive touch 725 32142D–06/2013 ATUC64/128/256L3/4U screen inputs, are automatically activated. In addition, if any other channels are enabled, they will be converted before and after the resistive touch screen conversion. At each trigger, the following sequence is performed: 1. If ACR.SLEEP is one, wake up the ADC cell and wait for the startup time. 2. Convert all enabled channels before TSPO and store the results in the LCDR. 3. Apply supply on the inputs XP and XM during the Sample and Hold Time. 4. Convert Channel XM and store the result in TMP. 5. Apply supply on the inputs XP and XM during the Sample and Hold Time. 6. Convert Channel XP, subtract TMP from the result and store the subtracted result in LCDR. 7. Apply supply on the inputs XP and XM during the Sample and Hold Time. 8. Convert Channel YP, subtract TMP from the result and store the subtracted result in LCDR. 9. Apply supply on the inputs YP and YM during the Sample and Hold Time. 10. Convert Channel YM and store the result in TMP. 11. Apply supply on the inputs YP and YM during the Sample and Hold Time. 12. Convert Channel YP, subtract TMP from the result and store the subtracted result in LCDR. 13. Apply supply on the inputs YP and YM during the Sample and Hold Time. 14. Convert Channel XP, subtract TMP from the result and store the subtracted result in LCDR. 15. Convert all enabled channels after TSPO + 3 and store results in the LCDR. 16. If ACR.SLEEP is one, place the ADC cell in a low-power state. The resulting buffer structure stored in memory is: 1. XP - XM 2. YP - XM 3. YP - YM 4. XP - YM. The vertical position can be easily calculated by dividing the data at offset 1(XP - XM) by the data at offset 2(YP - XM). The horizontal position can be easily calculated by dividing the data at offset 3(YP - YM) by the data at offset 4(XP - YM). 726 32142D–06/2013 ATUC64/128/256L3/4U 29.9 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 29-3. ADCIFB Register Memory Map Offset Register Name Access Reset 0x00 Control Register CR Write-only - 0x04 Mode Register MR Read/Write 0x00000000 0x08 ADC Configuration Register ACR Read/Write 0x00000000 0x0C Trigger Register TRGR Read/Write 0x00000000 0x10 Compare Value Register CVR Read/Write 0x00000000 0x14 Status Register SR Read-only 0x00000000 0x18 Interrupt Status Register ISR Read-only 0x00000000 0x1C Interrupt Clear Register ICR Write-only - 0x20 Interrupt Enable Register IER Write-only - 0x24 Interrupt Disable Register IDR Write-only - 0x28 Interrupt Mask Register IMR Read-only 0x00000000 0x2C Last Converted Data Register LCDR Read-only 0x00000000 0x30 Parameter Register PARAMETER Read-only -(1) 0x34 Version Register VERSION Read-only -(1) 0x40 Channel Enable Register CHER Write-only - 0x44 Channel Disable Register CHDR Write-only - 0x48 Channel Status Register CHSR Read-only 0x00000000 727 32142D–06/2013 ATUC64/128/256L3/4U 29.9.1 Control Register Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 • DIS: ADCDIFB Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the ADCIFB. Note: Disabling the ADCIFB effectively stops all clocks in the module so the user must make sure the ADCIFB is idle before disabling the ADCIFB. • EN: ADCIFB Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the ADCIFB. Note: The ADCIFB must be enabled before use. • START: Start Conversion Writing a zero to this bit has no effect. Writing a one to this bit starts an Analog-to-Digital conversion. • SWRST: Software Reset Writing a zero to this bit has no effect. Writing a one to this bit resets the ADCIFB, simulating a hardware reset. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - DIS EN 76543210 - - - - - - START SWRST 728 32142D–06/2013 ATUC64/128/256L3/4U 29.9.2 Mode Register Name: MR Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • PENDBC: Pen Detect Debouncing Period Period = 2PENDBC*TCLK_ADC • TSPO: Touch Screen Pin Offset The Touch Screen Pin Offset field is used to indicate which AD pins are connected to the resistive touch screen film edges. Only an offset is specified and it is assumed that the resistive touch screen films are connected sequentially from the specified offset pin and up to and including offset + 3 (4 pins). • APOE: Analog Pin Output Enable 0: AD pins are not used to drive VDD in resistive touch screen sequence. 1: AD pins are used to drive VDD in resistive touch screen sequence. Note: If the selected I/O voltage configuration is incompatible with the Analog-to-Digital converter cell voltage specification, this bit must stay cleared to avoid damaging the ADC. In this case the ADP pins must be used to drive VDD instead, as described in Section 29.7.3. If the I/O and ADC voltages are compatible, the AD pins can be used directly by writing a one to this bit. In this case the ADP pins can be ignored. • ACE: Analog Compare Enable 0: The analog compare functionality is disabled. 1: The analog compare functionality is enabled. • PENDET: Pen Detect 0: The pen detect functionality is disabled. 1: The pen detect functionality is enabled. Note: Touch detection logic can only be enabled when the ADC sequencer is idle. For successful pen detection the user must make sure there is enough idle time between consecutive scans for the touch detection logic to settle. • TSAMOD: Touch Screen ADC Mode 0: Touch Screen Mode is disabled. 1: Touch Screen Mode is enabled. 31 30 29 28 27 26 25 24 PENDBC - - - - 23 22 21 20 19 18 17 16 TSPO 15 14 13 12 11 10 9 8 -------- 76543210 - APOE ACE PENDET - - - TSAMOD 729 32142D–06/2013 ATUC64/128/256L3/4U 29.9.3 ADC Configuration Register Name: ACR Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • SHTIM: Sample & Hold Time for ADC Channels • STARTUP: Startup Time • PRESCAL: Prescaler Rate Selection • RES: Resolution Selection 0: 8-bit resolution. 1: 10-bit resolution. 2: 11-bit resolution, interpolated. 3: 12-bit resolution, interpolated. • SLEEP: ADC Sleep Mode 0: ADC Sleep Mode is disabled. 1: ADC Sleep Mode is enabled. 31 30 29 28 27 26 25 24 - - - - SHTIM 23 22 21 20 19 18 17 16 - STARTUP 15 14 13 12 11 10 9 8 - - PRESCAL 76543210 - - RES - - - SLEEP TSAMPLE&HOLD   SHTIM + 2 TCLK_ADC =  TARTUP   STARTUP + 1  8 TCLK_AD =  TCLK_ADC =   PRESCAL + 1  2 TCLK_ADCIFB  730 32142D–06/2013 ATUC64/128/256L3/4U 29.9.4 Trigger Register Name: TRGR Access Type: Read/Write Offset: 0x0C Reset Value: 0x00000000 • TRGPER: Trigger Period Effective only if TRGMOD defines a Periodic Trigger. Defines the periodic trigger period, with the following equations: Trigger Period = TRGPER *TCLK_ADC • TRGMOD: Trigger Mode 31 30 29 28 27 26 25 24 TRGPER[15:8] 23 22 21 20 19 18 17 16 TRGPER[7:0] 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TRGMOD Table 29-4. Trigger Modes TRGMOD Selected Trigger Mode 0 0 0 No trigger, only software trigger can start conversions 0 0 1 External Trigger Rising Edge 0 1 0 External Trigger Falling Edge 0 1 1 External Trigger Any Edge 100 Pen Detect Trigger (shall be selected only if PENDET is set and TSAMOD = Touch Screen mode) 1 0 1 Periodic Trigger (TRGPER shall be initiated appropriately) 1 1 0 Continuous Mode 1 1 1 Peripheral Event Trigger 731 32142D–06/2013 ATUC64/128/256L3/4U 29.9.5 Compare Value Register Name: CVR Access Type: Read/Write Offset: 0x10 Reset Value: 0x00000000 • HV: High Value Defines the high value used when comparing analog input. • LV: Low Value Defines the low value used when comparing analog input. 31 30 29 28 27 26 25 24 - - - - HV[11:8] 23 22 21 20 19 18 17 16 HV[7:0] 15 14 13 12 11 10 9 8 - - - - LV[11:8] 76543210 LV[7:0] 732 32142D–06/2013 ATUC64/128/256L3/4U 29.9.6 Status Register Name: SR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 • EN: Enable Status 0: The ADCIFB is disabled. 1: The ADCIFB is enabled. This bit is cleared when CR.DIS is written to one. This bit is set when CR.EN is written to one. • CELSE: Compare Else Status This bit is cleared when either CLT or CGT are detected or when analog compare is disabled. This bit is set when no CLT or CGT are detected on the last converted data and analog compare is enabled. • CGT: Compare Greater Than Status This bit is cleared when no compare greater than CVR.HV is detected on the last converted data or when analog compare is disabled. This bit is set when compare greater than CVR.HV is detected on the last converted data and analog compare is enabled. • CLT: Compare Lesser Than Status This bit is cleared when no compare lesser than CVR.LV is detected on the last converted data or when analog compare is disabled. This bit is set when compare lesser than CVR.LV is detected on the last converted data and analog compare is enabled. • BUSY: Busy Status This bit is cleared when the ADCIFB is ready to perform a conversion sequence. This bit is set when the ADCIFB is busy performing a convention sequence. • READY: Ready Status This bit is cleared when the ADCIFB is busy performing a conversion sequence This bit is set when the ADCIFB is ready to perform a conversion sequence. • NOCNT: No Contact Status This bit is cleared when no contact loss is detected or pen detect is disabled This bit is set when contact loss is detected and pen detect is enabled. • PENCNT: Pen Contact Status This bit is cleared when no contact is detected or pen detect is disabled. 31 30 29 28 27 26 25 24 - - - - - - - EN 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 733 32142D–06/2013 ATUC64/128/256L3/4U This bit is set when pen contact is detected and pen detect is enabled. • OVRE: Overrun Error Status This bit is cleared when no Overrun Error has occurred since the start of a conversion sequence. This bit is set when one or more Overrun Error has occurred since the start of a conversion sequence. • DRDY: Data Ready Status 0: No data has been converted since the last reset. 1: One or more conversions have completed since the last reset and data is available in LCDR. This bit is cleared when CR.SWRST is written to one. This bit is set when one or more conversions have completed and data is available in LCDR. 734 32142D–06/2013 ATUC64/128/256L3/4U 29.9.7 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 • CELSE: Compare Else Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • CGT: Compare Greater Than Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • CLT: Compare Lesser Than Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • BUSY: Busy Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • READY: Ready Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • NOCNT: No Contact Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • PENCNT: Pen Contact Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • OVRE: Overrun Error Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • DRDY: Data Ready Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when a conversion has completed and new data is available in LCDR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 735 32142D–06/2013 ATUC64/128/256L3/4U 29.9.8 Interrupt Clear Register Name: ICR Access Type: Write-only Offset: 0x1C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in ISR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 736 32142D–06/2013 ATUC64/128/256L3/4U 29.9.9 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 737 32142D–06/2013 ATUC64/128/256L3/4U 29.9.10 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x24 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 738 32142D–06/2013 ATUC64/128/256L3/4U 29.9.11 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x28 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared by writing a one to the corresponding bit in Interrupt Disable Register (IDR). A bit in this register is set by writing a one to the corresponding bit in Interrupt Enable Register (IER). 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 739 32142D–06/2013 ATUC64/128/256L3/4U 29.9.12 Last Converted Data Register Name: LCDR Access Type: Read-only Offset: 0x2C Reset Value: 0x00000000 • LCCH: Last Converted Channel This field indicates what channel was last converted, i.e. what channel the LDATA represents. • LDATA: Last Data Converted The analog-to-digital conversion data is placed in this register at the end of a conversion on any analog channel and remains until a new conversion on any analog channel is completed. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 LCCH 15 14 13 12 11 10 9 8 - - - - LDATA[11:8] 76543210 LDATA[7:0] 740 32142D–06/2013 ATUC64/128/256L3/4U 29.9.13 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x30 Reset Value: 0x00000000 • CHn: Channel n Implemented 0: The corresponding channel is not implemented. 1: The corresponding channel is implemented. 31 30 29 28 27 26 25 24 CH31 CH30 CH29 CH28 CH27 CH26 CH25 CH24 23 22 21 20 19 18 17 16 CH23 CH22 CH21 CH20 CH19 CH18 CH17 CH16 15 14 13 12 11 10 9 8 CH15 CH14 CH13 CH12 CH11 CH10 CH9 CH8 76543210 CH7 CH6 CH5 CH4 CH3 CH2 CH1 CH0 741 32142D–06/2013 ATUC64/128/256L3/4U 29.9.14 Version Register Name: VERSION Access Type: Read-only Offset: 0x34 Reset Value: 0x00000000 • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the Module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 742 32142D–06/2013 ATUC64/128/256L3/4U 29.9.15 Channel Enable Register Name: CHER Access Type: Write-only Offset: 0x40 Reset Value: 0x00000000 • CHn: Channel n Enable Writing a zero to a bit in this register has no effect Writing a one to a bit in this register enables the corresponding channel The number of available channels is device dependent. Please refer to the Module Configuration section at the end of this chapter for information regarding which channels are implemented. 31 30 29 28 27 26 25 24 CH31 CH30 CH29 CH28 CH27 CH26 CH25 CH24 23 22 21 20 19 18 17 16 CH23 CH22 CH21 CH20 CH19 CH18 CH17 CH16 15 14 13 12 11 10 9 8 CH15 CH14 CH13 CH12 CH11 CH10 CH9 CH8 76543210 CH7 CH6 CH5 CH4 CH3 CH2 CH1 CH0 743 32142D–06/2013 ATUC64/128/256L3/4U 29.9.16 Channel Disable Register Name: CHDR Access Type: Write-only Offset: 0x44 Reset Value: 0x00000000 • CHn: Channel N Disable Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register disables the corresponding channel. Warning: If the corresponding channel is disabled during a conversion, or if it is disabled and then re-enabled during a conversion, its associated data and its corresponding DRDY and OVRE bits in SR are unpredictable. The number of available channels is device dependent. Please refer to the Module Configuration section at the end of this chapter for information regarding how many channels are implemented. 31 30 29 28 27 26 25 24 CH31 CH30 CH29 CH28 CH27 CH26 CH25 CH24 23 22 21 20 19 18 17 16 CH23 CH22 CH21 CH20 CH19 CH18 CH17 CH16 15 14 13 12 11 10 9 8 CH15 CH14 CH13 CH12 CH11 CH10 CH9 CH8 76543210 CH7 CH6 CH5 CH4 CH3 CH2 CH1 CH0 744 32142D–06/2013 ATUC64/128/256L3/4U 29.9.17 Channel Status Register Name: CHSR Access Type: Read-only Offset: 0x48 Reset Value: 0x00000000 • CHn: Channel N Status 0: The corresponding channel is disabled. 1: The corresponding channel is enabled. A bit in this register is cleared by writing a one to the corresponding bit in Channel Disable Register (CHDR). A bit in this register is set by writing a one to the corresponding bit in Channel Enable Register (CHER). The number of available channels is device dependent. Please refer to the Module Configuration section at the end of this chapter for information regarding how many channels are implemented. 31 30 29 28 27 26 25 24 CH31 CH30 CH29 CH28 CH27 CH26 CH25 CH24 23 22 21 20 19 18 17 16 CH23 CH22 CH21 CH20 CH19 CH18 CH17 CH16 15 14 13 12 11 10 9 8 CH15 CH14 CH13 CH12 CH11 CH10 CH9 CH8 76543210 CH7 CH6 CH5 CH4 CH3 CH2 CH1 CH0 745 32142D–06/2013 ATUC64/128/256L3/4U 29.10 Module Configuration The specific configuration for each ADCIFB instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Note: 1. AD3 does not exist Table 29-5. Module Configuration Feature ADCIFB Number of ADC channels 9 (8 + 1 internal temperature sensor channel) Table 29-6. ADCIFB Clocks Clock Name Description CLK_ADCIFB Clock for the ADCIFB bus interface Table 29-7. Register Reset Values Register Reset Value VERSION 0x00000110 PARAMETER 0x000003FF Table 29-8. ADC Input Channels(1) Channel Input CH0 AD0 CH1 AD1 CH2 AD2 CH4 AD4 CH5 AD5 CH6 AD6 CH7 AD7 CH8 AD8 CH9 Temperature sensor 746 32142D–06/2013 ATUC64/128/256L3/4U 30. Analog Comparator Interface (ACIFB) Rev: 2.0.2.2 30.1 Features • Controls an array of Analog Comparators • Low power option – Single shot mode support • Selectable settings for filter option – Filter length and hysteresis • Window Mode – Detect inside/outside window – Detect above/below window • Interrupt – On comparator result rising edge, falling edge, toggle – Inside window, outside window, toggle – When startup time has passed • Can generate events to the peripheral event system 30.2 Overview The Analog Comparator Interface (ACIFB) is able to control a number of Analog Comparators (AC) with identical behavior. An Analog Comparator compares two voltages and gives a compare output depending on this comparison. The ACIFB can be configured in normal mode using each comparator independently or in window mode using defined comparator pairs to observe a window. The number of channels implemented is device specific. Refer to the Module Configuration section at the end of this chapter for details. 747 32142D–06/2013 ATUC64/128/256L3/4U 30.3 Block Diagram Figure 30-1. ACIFB Block Diagram 30.4 I/O Lines Description There are two groups of analog comparators, A and B, as shown in Table 30-1. In normal mode, this grouping does not have any meaning. In window mode, two analog comparators, one from group A and the corresponding comparator from group B, are paired. ……………... TRIGGER EVENTS IRQ GCLK Peripheral Bus ACIFB Analog Comparators PERIPHERAL EVENT GENERATION - + AC INN INP CONF0.INSELN - + AC INN INP CONFn.INSELN FILTER FILTER INTERRUPT GENERATION CLK_ACIFB CTRL.ACTEST TR.ACTESTn TR.ACTEST0 ACOUT0 ACOUTn ACP0 ACN0 ACREFN ACPn ACNn Table 30-1. Analog Comparator Groups for Window Mode Group A Group B Pair Number AC0 AC1 0 AC2 AC3 1 AC4 AC5 2 AC6 AC7 3 Table 30-2. I/O Line Description Pin Name Pin Description Type ACAPn Positive reference pin for Analog Comparator A n Analog ACANn Negative reference pin for Analog Comparator A n Analog 748 32142D–06/2013 ATUC64/128/256L3/4U The signal names corresponds to the groups A and B of analog comparators. For normal mode, the mapping from input signal names in the block diagram to the signal names is given in Table 30-3. 30.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 30.5.1 I/O Lines The ACIFB pins are multiplexed with other peripherals. The user must first program the I/O Controller to give control of the pins to the ACIFB. 30.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the ACIFB, the ACIFB will stop functioning and resume operation after the system wakes up from sleep mode. 30.5.3 Clocks The clock for the ACIFB bus interface (CLK_ACIFB) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the ACIFB before disabling the clock, to avoid freezing the ACIFB in an undefined state. The ACIFB uses a GCLK as clock source for the Analog Comparators. The user must set up this GCLK at the right frequency. The CLK_ACIFB clock of the interface must be at least 4x the GCLK frequency used in the comparators. The GCLK is used both for measuring the startup time of a comparator, and to give a frequency for the comparisons done in Continuous Measurement Mode, see Section 30.6. Refer to the Electrical Characteristics chapter for GCLK frequency limitations. ACBPn Positive reference pin for Analog Comparator B n Analog ACBNn Negative reference pin for Analog Comparator B n Analog ACREFN Reference Voltage for all comparators selectable for INN Analog Table 30-3. Signal Name Mapping Pin Name Channel Number Normal Mode ACAP0/ACAN0 0 ACP0/ACN0 ACBP0/ACBN0 1 ACP1/ACN1 ACAP1/ACAN1 2 ACP2/ACN2 ACBP1/ACBN1 3 ACP3/ACN3 ACAP2/ACAN2 4 ACP4/ACN4 ACBP2/ACBN2 5 ACP5/ACN5 ACAP3/ACAN3 6 ACP6/ACN6 ACBP3/ACBN3 7 ACP7/ACN7 Table 30-2. I/O Line Description Pin Name Pin Description Type 749 32142D–06/2013 ATUC64/128/256L3/4U 30.5.4 Interrupts The ACIFB interrupt request line is connected to the interrupt controller. Using the ACIFB interrupt requires the interrupt controller to be programmed first. 30.5.5 Peripheral Events The ACIFB peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 30.5.6 Debug Operation When an external debugger forces the CPU into debug mode, the ACIFB continues normal operation. If the ACIFB is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 30.6 Functional Description The ACIFB is enabled by writing a one to the Control Register Enable bit (CTRL.EN). Additionally, the comparators must be individually enabled by programming the MODE field in the AC Configuration Register (CONFn.MODE). The results from the individual comparators can either be used directly (normal mode), or the results from two comparators can be grouped to generate a comparison window (window mode). All comparators need not be in the same mode, some comparators may be in normal mode, while others are in window mode. There are restrictions on which AC channels that can be grouped together in a window pair, see Section 30.6.5. 30.6.1 Analog Comparator Operation Each AC channel can be in one of four different modes, determined by CONFn.MODE: • Off • Continuous Measurement Mode (CM) • User Triggered Single Measurement Mode (UT) • Event Triggered Single Measurement Mode (ET) After being enabled, a startup time defined in CTRL.SUT is required before the result of the comparison is ready. The GCLK is used for measuring the startup time of a comparator, During the startup time the AC output is not available. When the ACn Ready bit in the Status Register (SR.ACRDYn) is one, the output of ACn is ready. In window mode the result is available when both the comparator outputs are ready (SR.ACRDYn=1 and SR.ACRDYn+1=1). 30.6.1.1 Continuous Measurement Mode In CM, the Analog Comparator is continuously enabled and performing comparisons. This ensures that the result of the latest comparison is always available in the ACn Current Comparison Status bit in the Status Register (SR.ACCSn). Comparisons are done on every positive edge of GCLK. CM is enabled by writing CONFn.MODE to 1. After the startup time has passed, a comparison is done and SR is updated. Appropriate peripheral events and interrupts are also generated. New comparisons are performed continuously until the CONFn.MODE field is written to 0. 750 32142D–06/2013 ATUC64/128/256L3/4U 30.6.1.2 User Triggered Single Measurement Mode In the UT mode, the user starts a single comparison by writing a one to the User Start Single Comparison bit (CTRL.USTART). This mode is enabled by writing CONFn.MODE to 2. After the startup time has passed, a single comparison is done and SR is updated. Appropriate peripheral events and interrupts are also generated. No new comparisons will be performed. CTRL.USTART is cleared automatically by hardware when the single comparison has been done. 30.6.1.3 Event Triggered Single Measurement Mode This mode is enabled by writing CONFn.MODE to 3 and Peripheral Event Trigger Enable (CTRL.EVENTEN) to one. The ET mode is similar to the UT mode, the difference is that a peripheral event from another hardware module causes the hardware to automatically set the Peripheral Event Start Single Comparison bit (CTRL.ESTART). After the startup time has passed, a single comparison is done and SR is updated. Appropriate peripheral events and interrupts are also generated. No new comparisons will be performed. CTRL.ESTART is cleared automatically by hardware when the single comparison has been done. 30.6.1.4 Selecting Comparator Inputs Each Analog Comparator has one positive (INP) and one negative (INN) input. The positive input is fed from an external input pin (ACPn). The negative input can either be fed from an external input pin (ACNn) or from a reference voltage common to all ACs (ACREFN). The user selects the input source as follows: • In normal mode with the Negative Input Select and Positive Input Select fields (CONFn.INSELN and CONFn.INSELP). • In window mode with CONFn.INSELN, CONFn.INSELP and CONFn+1.INSELN, CONFn+1,INSELP. The user must configure CONFn.INSELN and CONFn+1.INSELP to the same source. 30.6.2 Interrupt Generation The interrupt request will be generated if the corresponding bit in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in ISR is cleared by writing a one to the corresponding bit in the Interrupt Status Clear Register (ICR). 30.6.3 Peripheral Event Generation The ACIFB can be set up so that certain comparison results notify other parts of the device via the Peripheral Event system. Refer to Section 30.6.4.3 and Section 30.6.5.3 for information on which comparison results can generate events, and how to configure the ACIFB to achieve this. Zero or one event will be generated per comparison. 30.6.4 Normal Mode In normal mode all Analog Comparators are operating independently. 30.6.4.1 Normal Mode Output Each Analog Comparator generates one output ACOUT according to the input voltages on INP (AC positive input) and INN (AC negative input): 751 32142D–06/2013 ATUC64/128/256L3/4U • ACOUT = 1 if VINP > VINN • ACOUT = 0 if VINP < VINN • ACOUT = 0 if the AC output is not available (SR.ACRDY = 0) The output can optionally be filtered, as described in Section 30.6.6. 30.6.4.2 Normal Mode Interrupt The AC channels can generate interrupts. The Interrupt Settings field in the Configuration Register (CONFn.IS) can be configured to select when the AC will generate an interrupt: • When VINP > VINN • When VINP < VINN • On toggle of the AC output (ACOUT) • When comparison has been done 30.6.4.3 Normal Mode Peripheral Events The ACIFB can generate peripheral events according to the configuration of CONFn.EVENN and CONFn.EVENP. • When VINP > VINN or • When VINP < VINN or • On toggle of the AC output (ACOUT) 30.6.5 Window Mode In window mode, two ACs (an even and the following odd build up a pair) are grouped. The negative input of ACn (even) and the positive input of ACn+1 (odd) has to be connected together externally to the device and are controlled by the Input Select fields in the AC Configuration Registers (CONFn.INSELN and CONFn+1.INSELP). The positive input of ACn (even) and the negative input of ACn+1 (odd) can still be configured independently by CONFn.INSELP and CONFn+1.INSELN, respectively. 752 32142D–06/2013 ATUC64/128/256L3/4U Figure 30-2. Analog Comparator Interface in Window Mode 30.6.5.1 Window Mode Output When operating in window mode, each channel generates the same ACOUT outputs as in normal mode, see Section 30.6.4.1. Additionally, the ACIFB generates a window mode signal (acwout) according to the common input voltage to be compared: • ACWOUT = 1 if the common input voltage is inside the window, VACN(N+1) < Vcommon < VACP(N) • ACWOUT = 0 if the common input voltage is outside the window, Vcommon < VACN(N+1) or Vcommon > VACP(N) • ACWOUT = 0 if the window mode output is not available (SR.ACRDYn=0 or SR.ACRDYn+1=0) 30.6.5.2 Window Mode Interrupts When operating in window mode, each channel can generate the same interrupts as in normal mode, see Section 30.6.4.2. Additionally, when channels operate in window mode, programming Window Mode Interrupt Settings in the Window Mode Configuration Register (CONFWn.WIS) can cause interrupts to be generated when: • As soon as the common input voltage is inside the window. • As soon as the common input voltage is outside the window. • On toggle of the window compare output (ACWOUT). • When the comparison in both channels in the window pair is ready. Comparator pair 0 - + AC0 Interrupt Generator Window Module ACOUT0 Peripheral Event Generator Window window event - + AC1 Filter Filter SR.ACCS0 SR.WFCS0 ACAP0 ACAN0 ACBP0 COMMON ACWOUT ACBN0 IRQ ACOUT1 753 32142D–06/2013 ATUC64/128/256L3/4U 30.6.5.3 Window Mode Peripheral Events When operating in window mode, each channel can generate the same peripheral events as in normal mode, see Section 30.6.4.3. Additionally, when channels operate in window mode, programming Window Mode Event Selection Source (CONFWn.WEVSRC) can cause peripheral events to be generated when: • As soon as the common input voltage is inside the window. • As soon as the common input voltage is outside the window. • On toggle of the window compare output (ACWOUT) • Whenever a comparison is ready and the common input voltage is inside the window. • Whenever a comparison is ready and the common input voltage is outside the window. • When the comparison in both channels in the window pair is ready. 30.6.6 Filtering The output of the comparator can be filtered to reduce noise. The filter length is determined by the Filter Length field in the CONFn register (CONFn.FLEN). The filter samples the Analog Comparator output at the GCLK frequency for 2CONFn.FLEN samples. A separate counter (CNT) counts the number of cycles the AC output was one. This filter is deactivated if CONFn.FLEN equals 0. If the filter is enabled, the Hysteresis Value field HYS in the CONFn register (CONFn.HYS) can be used to define a hysteresis value. The hysteresis value should be chosen so that: The filter function is defined by: The filtering algorithm is explained in Figure 30-3. 2FLEN measurements are sampled. If the number of measurements that are zero is less than (2FLEN/2 - HYS), the filtered result is zero. If the number of measurements that are one is more than (2FLEN/2 + HYS), the filtered result is one. Otherwise, the result is unchanged. 2FLEN 2 ----------------  HYS CNT 2FLEN 2 ---------------- + HYS       comp = 1 2FLEN 2 ---------------- + HYS     CNT 2FLEN 2 ----------------–HYS        comp unchanged CNT 2FLEN 2 ----------------–HYS       comp = 0 754 32142D–06/2013 ATUC64/128/256L3/4U Figure 30-3. The Filtering Algorithm 30.7 Peripheral Event Triggers Peripheral events from other modules can trigger comparisons in the ACIFB. All channels that are set up in Event Triggered Single Measurement Mode will be started simultaneously when a peripheral event is received. Channels that are operating in Continuous Measurement Mode or User Triggered Single Measurement Mode will be unaffected by the received event. The software can still operate these channels independently of channels in Event Triggered Single Measurement Mode. A peripheral event will trigger one or more comparisons, in normal or window mode. 30.8 AC Test mode By writing the Analog Comparator Test Mode (CR.ACTEST) bit to one, the outputs from the ACs are overridden by the value in the Test Register (TR), see Figure 30-1. This is useful for software development. 2 FLEN 2 FLEN 2 HYS HYS ”Result=0" ”Result=1" Result = UNCHANGED 0 755 32142D–06/2013 ATUC64/128/256L3/4U 30.9 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 30-4. ACIFB Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CTRL Read/Write 0x00000000 0x04 Status Register SR Read-only 0x00000000 0x10 Interrupt Enable Register IER Write-only 0x00000000 0x14 Interrupt Disable Register IDR Write-only 0x00000000 0x18 Interrupt Mask Register IMR Read-only 0x00000000 0x1C Interrupt Status Register ISR Read-only 0x00000000 0x20 Interrupt Status Clear Register ICR Write-only 0x00000000 0x24 Test Register TR Read/Write 0x00000000 0x30 Parameter Register PARAMETER Read-only -(1) 0x34 Version Register VERSION Read-only -(1) 0x80 Window0 Configuration Register CONFW0 Read/Write 0x00000000 0x84 Window1 Configuration Register CONFW1 Read/Write 0x00000000 0x88 Window2 Configuration Register CONFW2 Read/Write 0x00000000 0x8C Window3 Configuration Register CONFW3 Read/Write 0x00000000 0xD0 AC0 Configuration Register CONF0 Read/Write 0x00000000 0xD4 AC1 Configuration Register CONF1 Read/Write 0x00000000 0xD8 AC2 Configuration Register CONF2 Read/Write 0x00000000 0xDC AC3 Configuration Register CONF3 Read/Write 0x00000000 0xE0 AC4 Configuration Register CONF4 Read/Write 0x00000000 0xE4 AC5 Configuration Register CONF5 Read/Write 0x00000000 0xE8 AC6 Configuration Register CONF6 Read/Write 0x00000000 0xEC AC7 Configuration Register CONF7 Read/Write 0x00000000 756 32142D–06/2013 ATUC64/128/256L3/4U 30.9.1 Control Register Name: CTRL Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • SUT: Startup Time Analog Comparator startup time = . Each time an AC is enabled, the AC comparison will be enabled after the startup time of the AC. • ACTEST: Analog Comparator Test Mode 0: The Analog Comparator outputs feeds the channel logic in ACIFB. 1: The Analog Comparator outputs are bypassed with the AC Test Register. • ESTART: Peripheral Event Start Single Comparison Writing a zero to this bit has no effect. Writing a one to this bit starts a comparison and can be used for test purposes. This bit is cleared when comparison is done. This bit is set when an enabled peripheral event is received. • USTART: User Start Single Comparison Writing a zero to this bit has no effect. Writing a one to this bit starts a Single Measurement Mode comparison. This bit is cleared when comparison is done. • EVENTEN: Peripheral Event Trigger Enable 0: A peripheral event will not trigger a comparison. 1: Enable comparison triggered by a peripheral event. • EN: ACIFB Enable 0: The ACIFB is disabled. 1: The ACIFB is enabled. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - SUT[9:8] 15 14 13 12 11 10 9 8 SUT[7:0] 76543210 ACTEST - ESTART USTART - - -EVENTEN EN SUT FGCLK ---------------- 757 32142D–06/2013 ATUC64/128/256L3/4U 30.9.2 Status Register Name: SR Access Type: Read-only Offset: 0x04 Reset Value: 0x00000000 • WFCSn: Window Mode Current Status This bit is cleared when the common input voltage is outside the window. This bit is set when the common input voltage is inside the window. • ACRDYn: ACn Ready This bit is cleared when the AC output (ACOUT) is not ready. This bit is set when the AC output (ACOUT) is ready, AC is enabled and its startup time is over. • ACCSn: ACn Current Comparison Status This bit is cleared when VINP is currently lower than VINN This bit is set when VINP is currently greater than VINN. 31 30 29 28 27 26 25 24 - - - - WFCS3 WFCS2 WFCS1 WFCS0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 ACRDY7 ACCS7 ACRDY6 ACCS6 ACRDY5 ACCS5 ACRDY4 ACCS4 76543210 ACRDY3 ACCS3 ACRDY2 ACCS2 ACRDY1 ACCS1 ACRDY0 ACCS0 758 32142D–06/2013 ATUC64/128/256L3/4U 30.9.3 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 759 32142D–06/2013 ATUC64/128/256L3/4U 30.9.4 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 760 32142D–06/2013 ATUC64/128/256L3/4U 30.9.5 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 • WFINTn: Window Mode Interrupt Mask 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. • SUTINTn: ACn Startup Time Interrupt Mask 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. • ACINTn: ACn Interrupt Mask 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 761 32142D–06/2013 ATUC64/128/256L3/4U 30.9.6 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 • WFINTn: Window Mode Interrupt Status 0: No Window Mode Interrupt is pending. 1: Window Mode Interrupt is pending. This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding channel pair operating in window mode generated an interrupt. • SUTINTn: ACn Startup Time Interrupt Status 0: No Startup Time Interrupt is pending. 1: Startup Time Interrupt is pending. This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the startup time of the corresponding AC has passed. • ACINTn: ACn Interrupt Status 0: No Normal Mode Interrupt is pending. 1: Normal Mode Interrupt is pending. This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding channel generated an interrupt. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 762 32142D–06/2013 ATUC64/128/256L3/4U 30.9.7 Interrupt Status Clear Register Name: ICR Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in ISR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 763 32142D–06/2013 ATUC64/128/256L3/4U 30.9.8 Test Register Name: TR Access Type: Read/Write Offset: 0x24 Reset Value: 0x00000000 • ACTESTn: AC Output Override Value If CTRL.ACTEST is set, the ACn output is overridden with the value of ACTESTn. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 ACTEST7 ACTEST6 ACTEST5 ACTEST4 ACTEST3 ACTEST2 ACTEST1 ACTEST0 764 32142D–06/2013 ATUC64/128/256L3/4U 30.9.9 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x30 Reset Value: - • WIMPLn: Window Pair n Implemented 0: Window Pair not implemented. 1: Window Pair implemented. • ACIMPLn: Analog Comparator n Implemented 0: Analog Comparator not implemented. 1: Analog Comparator implemented. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - WIMPL3 WIMPL2 WIMPL1 WIMPL0 15 14 13 12 11 10 9 8 -------- 76543210 ACIMPL7 ACIMPL6 ACIMPL5 ACIMPL4 ACIMPL3 ACIMPL2 ACIMPL1 ACIMPL0 765 32142D–06/2013 ATUC64/128/256L3/4U 30.9.10 Version Register Name: VERSION Access Type: Read-only Offset: 0x34 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 766 32142D–06/2013 ATUC64/128/256L3/4U 30.9.11 Window Configuration Register Name: CONFWn Access Type: Read/Write Offset: 0x80,0x84,0x88,0x8C Reset Value: 0x00000000 • WFEN: Window Mode Enable 0: The window mode is disabled. 1: The window mode is enabled. • WEVEN: Window Event Enable 0: Event from awout is disabled. 1: Event from awout is enabled. • WEVSRC: Event Source Selection for Window Mode 000: Event on acwout rising edge. 001: Event on acwout falling edge. 010: Event on awout rising or falling edge. 011: Inside window. 100: Outside window. 101: Measure done. 110-111: Reserved. • WIS: Window Mode Interrupt Settings 00: Window interrupt as soon as the input voltage is inside the window. 01: Window interrupt as soon as the input voltage is outside the window. 10: Window interrupt on toggle of window compare output. 11: Window interrupt when evaluation of input voltage is done. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - WFEN 15 14 13 12 11 10 9 8 - - - - WEVEN WEVSRC 7654321 0 - - - - - - WIS 767 32142D–06/2013 ATUC64/128/256L3/4U 30.9.12 AC Configuration Register Name: CONFn Access Type: Read/Write Offset: 0xD0,0xD4,0xD8,0xDC,0xE0,0xE4,0xE8,0xEC Reset Value: 0x00000000 • FLEN: Filter Length 000: Filter off. n: Number of samples to be averaged =2n . • HYS: Hysteresis Value 0000: No hysteresis. 1111: Max hysteresis. • EVENN: Event Enable Negative 0: Do not output event when ACOUT is zero. 1: Output event when ACOUT is zero. • EVENP: Event Enable Positive 0: Do not output event when ACOUT is one. 1: Output event when ACOUT is one. • INSELP: Positive Input Select 00: ACPn pin selected. 01: Reserved. 10: Reserved. 11: Reserved. • INSELN: Negative Input Select 00: ACNn pin selected. 01: ACREFN pin selected. 10: Reserved. 11: Reserved. • MODE: Mode 00: Off. 01: Continuous Measurement Mode. 10: User Triggered Single Measurement Mode. 11: Event Triggered Single Measurement Mode. 31 30 29 28 27 26 25 24 - FLEN HYS 23 22 21 20 19 18 17 16 - - - - - - EVENP EVENN 15 14 13 12 11 10 9 8 - - - - INSELP INSELN 7654321 0 - - MODE - - IS 768 32142D–06/2013 ATUC64/128/256L3/4U • IS: Interrupt Settings 00: Comparator interrupt when as VINP > VINN. 01: Comparator interrupt when as VINP < VINN. 10: Comparator interrupt on toggle of Analog Comparator output. 11: Comparator interrupt when comparison of VINP and VINN is done. 769 32142D–06/2013 ATUC64/128/256L3/4U 30.10 Module Configuration The specific configuration for each ACIFB instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Refer to the Power Manager chapter for details. Table 30-5. ACIFB Configuration Feature ACIFB Number of channels 8 Table 30-6. ACIFB Clocks Clock Name Description CLK_ACIFB Clock for the ACIFB bus interface GCLK The generic clock used for the ACIFB is GCLK4 Table 30-7. Register Reset Values Register Reset Value VERSION 0x00000202 PARAMETER 0x000F00FF 770 32142D–06/2013 ATUC64/128/256L3/4U 31. Capacitive Touch Module (CAT) Rev: 4.0.0.0 31.1 Features • QTouch® method allows N touch sensors to be implemented using 2N physical pins • QMatrix method allows X by Y matrix of sensors to be implemented using (X+2Y) physical pins • One autonomous QTouch sensor operates without DMA or CPU intervention • All QTouch sensors can operate in DMA-driven mode without CPU intervention • External synchronization to reduce 50 or 60 Hz mains interference • Spread spectrum sensor drive capability 31.2 Overview The Capacitive Touch Module (CAT) senses touch on external capacitive touch sensors. Capacitive touch sensors use no external mechanical components, and therefore demand less maintenance in the user application. The module implements the QTouch method of capturing signals from capacitive touch sensors. The QTouch method is generally suitable for small numbers of sensors since it requires 2 physical pins per sensor. The module also implements the QMatrix method, which is more appropriate for large numbers of sensors since it allows an X by Y matrix of sensors to be implemented using only (X+2Y) physical pins. The module allows methods to function together, so N touch sensors and an X by Y matrix of sensors can be implemented using (2N+X+2Y) physical pins. In addition, the module allows sensors using the QTouch method to be divided into two groups. Each QTouch group can be configured with different properties. This eases the implementation of multiple kinds of controls such as push buttons, wheels, and sliders. All of the QTouch sensors can operate in a DMA-driven mode, known as DMATouch, that allows detection of touch without CPU intervention. The module also implements one autonomous QTouch sensor that is capable of detecting touch without DMA or CPU intervention. This allows proximity or activation detection in low-power sleep modes. 771 32142D–06/2013 ATUC64/128/256L3/4U 31.3 Block Diagram Figure 31-1. CAT Block Diagram 31.4 I/O Lines Description Interface Registers Peripheral Bus Finite State Machine Capacitor Charge and Discharge Sequence Generator Counters CSAn SMP I/O Controller Pins Discharge Current Sources DIS Yn Analog Comparators Peripheral Event System CLK_CAT Analog Comparator Interface SYNC Capacitive Touch Module (CAT) CSBn GCLK_CAT VDIVEN NOTE: Italicized signals and blocks are used only for QMatrix operation Table 31-1. I/O Lines Description Name Description Type CSAn Capacitive sense A line n I/O CSBn Capacitive sense B line n I/O DIS Discharge current control (only used for QMatrix) Analog 772 32142D–06/2013 ATUC64/128/256L3/4U 31.5 Product Dependencies In order to use the CAT module, other parts of the system must be configured correctly, as described below. 31.5.1 I/O Lines The CAT pins may be multiplexed with other peripherals. The user must first program the I/O Controller to give control of the pins to the CAT module. In QMatrix mode, the Y lines must be driven by the CAT and analog comparators sense the voltage on the Y lines. Thus, the CAT (not the Analog Comparator Interface) must be the selected function for the Y lines in the I/O Controller. By writing ones and zeros to bits in the Pin Mode Registers (PINMODEx), most of the CAT pins can be individually selected to implement the QTouch method or the QMatrix method. Each pin has a different name and function depending on whether it is implementing the QTouch method or the QMatrix method. The following table shows the pin names for each method and the bits in the PINMODEx registers which control the selection of the QTouch or QMatrix method. SMP SMP line (only used for QMatrix) Output SYNC Synchronize signal Input VDIVEN Voltage divider enable (only used for QMatrix) Output Table 31-1. I/O Lines Description Name Description Type Table 31-2. Pin Selection Guide CAT Module Pin Name QTouch Method Pin Name QMatrix Method Pin Name Selection Bit in PINMODEx Register CSA0 SNS0 X0 SP0 CSB0 SNSK0 X1 SP0 CSA1 SNS1 Y0 SP1 CSB1 SNSK1 YK0 SP1 CSA2 SNS2 X2 SP2 CSB2 SNSK2 X3 SP2 CSA3 SNS3 Y1 SP3 CSB3 SNSK3 YK1 SP3 CSA4 SNS4 X4 SP4 CSB4 SNSK4 X5 SP4 CSA5 SNS5 Y2 SP5 CSB5 SNSK5 YK2 SP5 CSA6 SNS6 X6 SP6 CSB6 SNSK6 X7 SP6 CSA7 SNS7 Y3 SP7 CSB7 SNSK7 YK3 SP7 CSA8 SNS8 X8 SP8 773 32142D–06/2013 ATUC64/128/256L3/4U 31.5.2 Clocks The clock for the CAT module, CLK_CAT, is generated by the Power Manager (PM). This clock is turned on by default, and can be enabled and disabled in the PM. The user must ensure that CLK_CAT is enabled before using the CAT module. QMatrix operations also require the CAT generic clock, GCLK_CAT. This generic clock is generated by the System Control Interface (SCIF), and is shared between the CAT and the Analog Comparator Interface. The user must ensure that the GCLK_CAT is enabled in the SCIF before using QMatrix functionality in the CAT module. For proper QMatrix operation, the frequency of GCLK_CAT must be less than half the frequency of CLK_CAT. If only QTouch functionality is used, then GCLK_CAT is unnecessary. 31.5.3 Interrupts The CAT interrupt request line is connected to the interrupt controller. Using CAT interrupts requires the interrupt controller to be programmed first. 31.5.4 Peripheral Events The CAT peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 31.5.5 Peripheral Direct Memory Access The CAT module provides handshake capability for a Peripheral DMA Controller. One handshake controls transfers from the Acquired Count Register (ACOUNT) to memory. A second handshake requests burst lengths for each (X,Y) pair to the Matrix Burst Length Register CSB8 SNSK8 X9 SP8 CSA9 SNS9 Y4 SP9 CSB9 SNSK9 YK4 SP9 CSA10 SNS10 X10 SP10 CSB10 SNSK10 X11 SP10 CSA11 SNS11 Y5 SP11 CSB11 SNSK11 YK5 SP11 CSA12 SNS12 X12 SP12 CSB12 SNSK12 X13 SP12 CSA13 SNS13 Y6 SP13 CSB13 SNSK13 YK6 SP13 CSA14 SNS14 X14 SP14 CSB14 SNSK14 X15 SP14 CSA15 SNS15 Y7 SP15 CSB15 SNSK15 YK7 SP15 CSA16 SNS16 X16 SP16 CSB16 SNSK16 X17 SP16 Table 31-2. Pin Selection Guide CAT Module Pin Name QTouch Method Pin Name QMatrix Method Pin Name Selection Bit in PINMODEx Register 774 32142D–06/2013 ATUC64/128/256L3/4U (MBLEN) when using the QMatrix acquisition method. Two additional handshakes support DMATouch by regulating transfers from memory to the DMATouch State Write Register (DMATSW) and from the DMATouch State Read Register (DMATSR) to memory. The Peripheral DMA Controller must be configured properly and enabled in order to perform direct memory access transfers to/from the CAT module. 31.5.6 Analog Comparators When the CAT module is performing QMatrix acquisition, it requires that on-chip analog comparators be used as part of the process. These analog comparators are not controlled directly by the CAT module, but by a separate Analog Comparator (AC) Interface. This interface must be configured properly and enabled before the CAT module is used. This includes configuring the generic clock input for the analog comparators to the proper sampling frequency. The CAT will automatically use the negative peripheral events from the AC Interface on every Y pin in QMatrix mode. When QMatrix acquisition is used the analog comparator corresponding to the selected Y pins must be enabled and converting continuously, using the Y pin as the positive reference and the ACREFN as negative reference. 31.5.7 Debug Operation When an external debugger forces the CPU into debug mode, the CAT continues normal operation. If the CAT is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 31.6 Functional Description 31.6.1 Acquisition Types The CAT module can perform several types of QTouch acquisition from capacitive touch sensors: autonomous QTouch (one sensor only), DMATouch, QTouch group A, and QTouch group B. The CAT module can also perform QMatrix acquisition. Each type of acquisition has an associated set of pin selection and configuration registers that allow a large degree of flexibility. The following schematic diagrams show typical hardware connections for QTouch and QMatrix sensors, respectively: Figure 31-2. CAT Touch Connections AVR32 Chip QTouch Sensor Cs (Sense Capacitor) SNSKn SNSn 775 32142D–06/2013 ATUC64/128/256L3/4U Figure 31-3. CAT Matrix Connections In order to use the autonomous QTouch detection capability, the user must first set up the Autonomous Touch Pin Select Register (ATPINS) and Autonomous/DMA Touch Configuration Registers (ATCFG0 through 3) with appropriate values. The module can then be enabled using the Control Register (CTRL). After the module is enabled, the module will acquire data from the autonomous QTouch sensor and use it to determine whether the sensor is activated. The active/inactive status of the autonomous QTouch sensor is reported in the Status Register (SR), and it is also possible to configure the CAT to generate an interrupt whenever the status changes. The module will continue acquiring autonomous QTouch sensor data and updating autonomous QTouch status until the module is disabled or reset. In order to use the DMATouch capability, it is first necessary to set up the pin mode registers (PINMODE0, PINMODE1, and PINMODE2) so that the desired pins are specified as DMATouch. The Autonomous/DMA Touch Configuration Registers (ATCFG0 through 3) must also be configured with appropriate values. One channel of the Peripheral DMA Controller must be set up to transfer state words from a block of memory to the DMATSW register, and another channel must be set up to transfer state words from the DMATSR register back to the same block of memory. The module can then be enabled using the CTRL register. After the module is enabled, the module will acquire count values from each DMATouch sensor. Once the module has acquired a count value for a sensor, it will use a handshake interface to signal the Peripheral DMA controller to transfer a state word to the DMATSW register. The module will use the count value to update the state word, and then the updated state word will be transferred to the DMATSR register. Another handshake interface will signal the Peripheral DMA controller to transfer the contents of the DMATSR register back to memory. The status of the DMATouch sensors can be determined at any time by reading the DMATouch Sensor Status Register (DMATSS). AVR32 Chip Cs0 (Sense Capacitor) X3 YK0 X6 QMatrix Sensor Array X7 X2 Y0 YK1 Y1 Cs1 (Sense Capacitor) SMP Rsmp1 Rsmp0 VDIVEN DIS Rdis ACREFN Ra Rb NOTE: If the CAT internal current sources will be enabled, the SMP signal and Rsmp resistors should NOT be included in the design. If the CAT internal current sources will NOT be enabled, the DIS signal and Rdis resistor should NOT be included in the design. 776 32142D–06/2013 ATUC64/128/256L3/4U In order to use the QMatrix, QTouch group A, or QTouch group B acquisition capabilities, it is first necessary to set up the pin mode registers (PINMODE0, PINMODE1, and PINMODE2) and configuration registers (MGCFG0, MGCFG1, TGACFG0, TGACFG1, TGBCFG0, and TGBCFG1). The module must then be enabled using the CTRL register. In order to initiate acquisition, it is necessary to perform a write to the Acquisition Initiation and Selection Register (AISR). The specific value written to AISR determines which type of acquisition will be performed: QMatrix, QTouch group A, or QTouch group B. The CPU can initiate acquisition by writing to the AISR. While QMatrix, QTouch group A, or QTouch group B acquisition is in progress, the module collects count values from the sensors and buffers them. Availability of acquired count data is indicated by the Acquisition Ready (ACREADY) bit in the Status Register (SR). The CPU or the Peripheral DMA Controller can then read the acquired counts from the ACOUNT register. Because the CAT module is configured with Peripheral DMA Controller capability that can transfer data from memory to MBLEN and from ACOUNT to memory, the Peripheral DMA Controller can perform long acquisition sequences and store results in memory without CPU intervention. 31.6.2 Prescaler and Charge Length Each QTouch acquisition type (autonomous QTouch, QTouch group A, and QTouch group B) has its own prescaler. Each QTouch prescaler divides down the CLK_CAT clock to an appropriate sampling frequency for its particular acquisition type. Typical frequencies are 1MHz for QTouch acquisition and 4MHz for QMatrix burst timing control. Each QTouch prescaler is controlled by the DIV field in the appropriate Configuration Register 0 (ATCFG0, TGACFG0, or TGBCFG0). The QMatrix burst timing prescaler is controlled by the DIV field in MGCFG0. Each prescaler uses the following formula to generate the sampling clock: Sampling clock = CLK_CAT / (2(DIV+1)) The capacitive sensor charge length, discharge length, and settle length can be determined for each acquisition type using the CHLEN, DILEN, and SELEN fields in Configuration Registers 0 and 1. The lengths are specified in terms of prescaler clocks. In addition, the QMatrix Cx discharge length can be determined using the CXDILEN field in MGCFG2. For QMatrix acquisition, the duration of CHLEN should not be set to the same value as the period of any periodic signal on any other pin. If the duration of CHLEN is the same as the period of a signal on another pin, it is likely that the other signal will significantly affect measurements due to stray capacitive coupling. For example, if a 1 MHz signal is generated on another pin of the chip, then CHLEN should not be 1 microsecond. For the QMatrix method, burst and capture lengths are set for each (X,Y) pair by writing the desired length values to the MBLEN register. The write must be done before each X line can start its acquisition and is indicated by the status bit MBLREQ in the Status Register (SR). A DMA handshake interface is also connected to this status bit to reduce CPU overhead during QMatrix acquisitions. Four burst lengths (BURST0..3) can be written at one time into the MBLEN register. If the current configuration uses Y lines larger than Y3 the register has to be written a second time. The first write to MBLEN specifies the burst length for Y lines 0 to 3 in the BURST0 to BURST3 fields, respectively. The second write specifies the burst length for Y lines 4 to 7 in fields BURST0 to BURST3, respectively, and so on. 777 32142D–06/2013 ATUC64/128/256L3/4U The Y and YK pins remain clamped to ground apart from the specified number of burst pulses, when charge is transferred and captured into the sampling capacitor. 31.6.3 Capacitive Count Acquisition For the QMatrix, QTouch group A, and QTouch group B types of acquisition, the module acquires count values from the sensors, buffers them, and makes them available for reading in the ACOUNT register. Further processing of the count values must be performed by the CPU. When the module performs QMatrix acquisition using multiple Y lines, it starts the capture for each Y line at the appropriate time in the burst sequence so that all captures finish simultaneously. For example, suppose that an acquisition is performed on Y0 and Y1 with BURST0=53 and BURST1=60. The module will first toggle the X line 7 times while capturing on Y1 while Y0 and YK0 are clamped to ground. The module will then toggle the X line 53 times while capturing on both Y1 and Y0. 31.6.4 Autonomous QTouch and DMATouch For autonomous QTouch and DMATouch, a complete detection algorithm is implemented within the CAT module. The additional parameters needed to control the detection algorithm must be specified by the user in the ATCFG2 and ATCFG3 registers. Autonomous QTouch and DMATouch sensitivity and out-of-touch sensitivity can be adjusted with the SENSE and OUTSENS fields, respectively, in ATCFG2. Each field accepts values from one to 255 where 255 is the least sensitive setting. The value in the OUTSENS field should be smaller than the value in the SENSE field. To avoid false positives a detect integration filtering technique can be used. The number of successive detects required is specified in the FILTER field of the ATCFG2 register. To compensate for changes in capacitance the CAT can recalibrate the autonomous QTouch sensor periodically. The timing of this calibration is done with the NDRIFT and PDRIFT fields in the Configuration register, ATCFG3. It is recommended that the PDRIFT value is smaller than the NDRIFT value. The autonomous QTouch sensor and DMATouch sensors will also recalibrate if the count value goes too far positive beyond a threshold. This positive recalibration threshold is specified by the PTHR field in the ATCFG3 register. The following block diagram shows the sequence of acquisition and processing operations used by the CAT module. The AISR written bit is internal and not visible in the user interface. 778 32142D–06/2013 ATUC64/128/256L3/4U Figure 31-4. CAT Acquisition and Processing Sequence 31.6.5 Spread Spectrum Sensor Drive To reduce electromagnetic compatibility issues, the capacitive sensors can be driven with a spread spectrum signal. To enable spread spectrum drive for a specific acquisition type, the user must write a one to the SPREAD bit in the appropriate Configuration Register 1 (MGCFG1, ATCFG1, TGACFG1, or TGBCFG1). During spread spectrum operation, the length of each pulse within a burst is varied in a deterministic pattern, so that the exact same burst pattern is used for a specific burst length. The maximum spread is determined by the MAXDEV field in the Spread Spectrum Configuration Register (SSCFG) register. The prescaler divisor is varied in a sawtooth pattern from (2(DIV+1))-MAXDEV to (2(DIV+1))+MAXDEV and then back to (2(DIV+1))-MAXDEV. For example, if DIV is 2 and MAXDEV is 3, the prescaler divisor will have the following sequence: 6, 7, 8, Idle Acquire autonomous touch count Acquire counts Update autonomous touch detection algorithm Wait for all acquired counts to be transferred AISR written flag set? No Yes Clear AISR written flag No Yes Autonomous touch enabled (ATEN)? 779 32142D–06/2013 ATUC64/128/256L3/4U 9, 3, 4, 5, 6, 7, 8, 9, 3, 4, etc. MAXDEV must not exceed the value of (2(DIV+1)), or undefined behavior will occur. 31.6.6 Synchronization To prevent interference from the 50 or 60 Hz mains line the CAT can trigger acquisition on the SYNC signal. The SYNC signal should be derived from the mains line. The acquisition will trigger on a falling edge of this signal. To enable synchronization for a specific acquisition type, the user must write a one to the SYNC bit in the appropriate Configuration Register 1 (MGCFG1, ATCFG1, TGACFG1, or TGBCFG1). For QMatrix acquisition, all X lines must be sampled at a specific phase of the noise signal for the synchronization to be effective. This can be accomplished by the synchronization timer, which is enabled by writing a non-zero value to the SYNCTIM field in the MGCFG2 register. This ensures that the start of the acquisition of each X line is spaced at regular intervals, defined by the SYNCTIM field. 31.6.7 Resistive Drive By default, the CAT pins are driven with normal I/O drive properties. Some of the CSA and CSB pins can optionally drive with a 1k output resistance for improved EMC. The pins that have this capability are listed in the Module Configuration section. 31.6.8 Discharge Current Sources The device integrates discharge current sources, which can be used to discharge the sampling capacitors during the QMatrix measurement phase. The discharge current sources are enabled by writing the GLEN bit in the Discharge Current Source (DICS) register to one. This enables an internal reference voltage, which can be either the internal 1.1V band gap voltage or VDDIO/3, as selected by the INTVREFSEL bit in the DICS register. If the DICS.INTREFSEL bit is one, the reference voltage is applied across an internal resistor, Rint. Otherwise, the voltage is applied to the DIS pin, and an external reference resistor must be connected between DIS and ground. The nominal discharge current is given by the following formula, where Vref is the reference voltage, Rref is the value of the reference resistor, trim is the value written to the DICS.TRIM field, and k is a constant of proportionality: I = (Vref/Rref)*(1+(k*trim)) The values for the internal reference resistor, Rint, and the constant, k, may be found in the Electrical Characteristics section. The nominal discharge current may be programmed between 2 and 20 µA. The reference current can be fine-tuned by adjusting the trim value in the DICS.TRIM field. The reference current is mirrored to each Y-pin if the corresponding bit is written to one in the DICS.SOURCES field. 31.6.9 Voltage Divider Enable (VDIVEN) Capability In many QMatrix applications, the sense capacitors will be charged to 50 mV or more and the negative reference pin (ACREFN) of the analog comparators can be tied directly to ground. In that case, the relatively small input offset voltage of the comparators will not cause acquisition problems. However, in certain specialized QMatrix applications such as interpolated touch screens, it may be desirable for the sense capacitors to be charged to less than 25 mV. When such small voltages are used on the sense capacitors, the input offset voltage of the comparators becomes an issue and can cause QMatrix acquisition problems. 780 32142D–06/2013 ATUC64/128/256L3/4U Problems with QMatrix acquisition of small sense capacitor voltages can be solved by connecting the negative reference pin (ACREFN) to a voltage divider that produces a small positive voltage (20 mV, typically) to cancel any negative input offset voltage. With a 3.3V supply, recommended values for the voltage divider are Ra (resistor from positive supply to ACREFN) of 8200 ohm and Rb (resistor from ACREFN to ground) of 50 ohm. These recommended values will produce 20 mV on the ACREFN pin, which should generally be enough to compensate for the worst-case negative input offset of the analog comparators. Unfortunately, such a voltage divider constantly draws a small current from the power supply, reducing battery life in portable applications. In order to prevent this constant power drain, the CAT module provides a voltage divider enable pin (VDIVEN) that can be used for driving the voltage divider. The VDIVEN pin provides power to the voltage divider only when the comparators are actually performing QMatrix comparisons. When the comparators are inactive, the VDIVEN output is zero. This minimizes the power consumed by the voltage divider. 781 32142D–06/2013 ATUC64/128/256L3/4U 31.7 User Interface Table 31-3. CAT Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CTRL Read/Write 0x00000000 0x04 Autonomous Touch Pin Selection Register ATPINS Read/Write 0x00000000 0x08 Pin Mode Register 0 PINMODE0 Read/Write 0x00000000 0x0C Pin Mode Register 1 PINMODE1 Read/Write 0x00000000 0x10 Autonomous/DMA Touch Configuration Register 0 ATCFG0 Read/Write 0x00000000 0x14 Autonomous/DMA Touch Configuration Register 1 ATCFG1 Read/Write 0x00000000 0x18 Autonomous/DMA Touch Configuration Register 2 ATCFG2 Read/Write 0x00000000 0x1C Autonomous/DMA Touch Configuration Register 3 ATCFG3 Read/Write 0x00000000 0x20 Touch Group A Configuration Register 0 TGACFG0 Read/Write 0x00000000 0x24 Touch Group A Configuration Register 1 TGACFG1 Read/Write 0x00000000 0x28 Touch Group B Configuration Register 0 TGBCFG0 Read/Write 0x00000000 0x2C Touch Group B Configuration Register 1 TGBCFG1 Read/Write 0x00000000 0x30 Matrix Group Configuration Register 0 MGCFG0 Read/Write 0x00000000 0x34 Matrix Group Configuration Register 1 MGCFG1 Read/Write 0x00000000 0x38 Matrix Group Configuration Register 2 MGCFG2 Read/Write 0x00000000 0x3C Status Register SR Read-only 0x00000000 0x40 Status Clear Register SCR Write-only - 0x44 Interrupt Enable Register IER Write-only - 0x48 Interrupt Disable Register IDR Write-only - 0x4C Interrupt Mask Register IMR Read-only 0x00000000 0x50 Acquisition Initiation and Selection Register AISR Read/Write 0x00000000 0x54 Acquired Count Register ACOUNT Read-only 0x00000000 0x58 Matrix Burst Length Register MBLEN Write-only - 0x5C Discharge Current Source Register DICS Read/Write 0x00000000 0x60 Spread Spectrum Configuration Register SSCFG Read/Write 0x00000000 0x64 CSA Resistor Control Register CSARES Read/Write 0x00000000 0x68 CSB Resistor Control Register CSBRES Read/Write 0x00000000 0x6C Autonomous Touch Base Count Register ATBASE Read-only 0x00000000 0x70 Autonomous Touch Current Count Register ATCURR Read-only 0x00000000 0x74 Pin Mode Register 2 PINMODE2 Read/Write 0x00000000 0x78 DMATouch State Write Register DMATSW Write-only 0x00000000 0x7C DMATouch State Read Register DMATSR Read-only 0x00000000 0x80 Analog Comparator Shift Offset Register 0 ACSHI0 Read/Write 0x00000000 0x84 Analog Comparator Shift Offset Register 1 ACSHI1 Read/Write 0x00000000 0x88 Analog Comparator Shift Offset Register 2 ACSHI2 Read/Write 0x00000000 782 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. The reset value for this register is device specific. Please refer to the Module Configuration section at the end of this chapter. 0x8C Analog Comparator Shift Offset Register 3 ACSHI3 Read/Write 0x00000000 0x90 Analog Comparator Shift Offset Register 4 ACSHI4 Read/Write 0x00000000 0x94 Analog Comparator Shift Offset Register 5 ACSHI5 Read/Write 0x00000000 0x98 Analog Comparator Shift Offset Register 6 ACSHI6 Read/Write 0x00000000 0x9C Analog Comparator Shift Offset Register 7 ACSHI7 Read/Write 0x00000000 0xA0 DMATouch Sensor Status Register DMATSS Read-only 0x00000000 0xF8 Parameter Register PARAMETER Read-only -(1) 0xFC Version Register VERSION Read-only -(1) Table 31-3. CAT Register Memory Map Offset Register Register Name Access Reset 783 32142D–06/2013 ATUC64/128/256L3/4U 31.7.1 Control Register Name: CTRL Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • SWRST: Software reset Writing a zero to this bit has no effect. Writing a one to this bit resets the module. The module will be disabled after the reset. This bit always reads as zero. • EN: Module enable 0: Module is disabled. 1: Module is enabled. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 SWRST - - - - - - EN 784 32142D–06/2013 ATUC64/128/256L3/4U 31.7.2 Autonomous Touch Pin Selection Register Name: ATPINS Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • ATEN: Autonomous Touch Enable 0: Autonomous QTouch acquisition and detection is disabled. 1: Autonomous QTouch acquisition and detection is enabled using the sense pair specified in ATSP. • ATSP: Autonomous Touch Sense Pair Selects the sense pair that will be used by the autonomous QTouch sensor. A value of n will select sense pair n (CSAn and CSBn pins). 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - ATEN 76543210 - - - ATSP 785 32142D–06/2013 ATUC64/128/256L3/4U 31.7.3 Pin Mode Registers 0, 1, and 2 Name: PINMODE0, PINMODE1, and PINMODE2 Access Type: Read/Write Offset: 0x08, 0x0C, 0x74 Reset Value: 0x00000000 • SP: Sense Pair Mode Selection Each SP[n] bit determines the operation mode of sense pair n (CSAn and CSBn pins). The (PINMODE2.SP[n] PINMODE1.SP[n] PINMODE0.SP[n]) bits have the following definitions: 000: Sense pair n disabled. 001: Sense pair n is assigned to QTouch Group A. 010: Sense pair n is assigned to QTouch Group B. 011: Sense pair n is assigned to the QMatrix Group. 100: Sense pair n is assigned to the DMATouch Group. 101: Reserved. 110: Reserved. 111: Reserved. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - SP[16] 15 14 13 12 11 10 9 8 SP[15:8] 76543210 SP[7:0] 786 32142D–06/2013 ATUC64/128/256L3/4U 31.7.4 Autonomous/DMA Touch Configuration Register 0 Name: ATCFG0 Access Type: Read/Write Offset: 0x10 Reset Value: 0x00000000 • DIV: Clock Divider The prescaler is used to ensure that the CLK_CAT clock is divided to around 1 MHz to produce the sampling clock.The prescaler uses the following formula to generate the sampling clock: Sampling clock = CLK_CAT / (2(DIV+1)) • CHLEN: Charge Length For the autonomous QTouch sensor and DMATouch sensors, specifies how many sample clock cycles should be used for transferring charge to the sense capacitor. • SELEN: Settle Length For the autonomous QTouch sensor and DMATouch sensors, specifies how many sample clock cycles should be used for settling after charge transfer. 31 30 29 28 27 26 25 24 DIV[15:8] 23 22 21 20 19 18 17 16 DIV[7:0] 15 14 13 12 11 10 9 8 CHLEN 76543210 SELEN 787 32142D–06/2013 ATUC64/128/256L3/4U 31.7.5 Autonomous/DMA Touch Configuration Register 1 Name: ATCFG1 Access Type: Read/Write Offset: 0x14 Reset Value: 0x00000000 • DISHIFT: Discharge Shift For the autonomous QTouch sensor and DMATouch sensors, specifies how many bits the DILEN field should be shifted before using it to determine the discharge time. • SYNC: Sync Pin For the autonomous QTouch sensor and DMATouch sensors, specifies that acquisition shall begin when a falling edge is received on the SYNC line. • SPREAD: Spread Spectrum Sensor Drive For the autonomous QTouch sensor and DMATouch sensors, specifies that spread spectrum sensor drive shall be used. • DILEN: Discharge Length For the autonomous QTouch sensor and DMATouch sensors, specifies how many sample clock cycles the CAT should use to discharge the capacitors before charging them. • MAX: Maximum Count For the autonomous QTouch sensor and DMATouch sensors, specifies how many counts the maximum acquisition should be. 31 30 29 28 27 26 25 24 - DISHIFT - SYNC SPREAD 23 22 21 20 19 18 17 16 DILEN 15 14 13 12 11 10 9 8 MAX[15:8] 76543210 MAX[7:0] 788 32142D–06/2013 ATUC64/128/256L3/4U 31.7.6 Autonomous/DMA Touch Configuration Register 2 Name: ATCFG2 Access Type: Read/Write Offset: 0x18 Reset Value: 0x00000000 • FILTER: Autonomous Touch Filter Setting For the autonomous QTouch sensor and DMATouch sensors, specifies how many positive detects in a row the CAT needs to have on the sensor before reporting it as a touch. A FILTER value of 0 is not allowed and will result in undefined behavior. • OUTSENS: Out-of-Touch Sensitivity For the autonomous QTouch sensor and DMATouch sensors, specifies how sensitive the out-of-touch detector should be. • SENSE: Sensitivity For the autonomous QTouch sensor and DMATouch sensors, specifies how sensitive the touch detector should be. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - FILTER 15 14 13 12 11 10 9 8 OUTSENS 76543210 SENSE 789 32142D–06/2013 ATUC64/128/256L3/4U 31.7.7 Autonomous/DMA Touch Configuration Register 3 Name: ATCFG3 Access Type: Read/Write Offset: 0x1C Reset Value: 0x00000000 • PTHR: Positive Recalibration Threshold For the autonomous QTouch sensor and DMATouch sensors, specifies how far a sensor’s signal must move in a positive direction from the reference in order to cause a recalibration. • PDRIFT: Positive Drift Compensation For the autonomous QTouch sensor and DMATouch sensors, specifies how often a positive drift compensation should be performed. When this field is zero, positive drift compensation will never be performed. When this field is non-zero, the positive drift compensation time interval is given by the following formula: Tpdrift = PDRIFT * 65536 * (sample clock period) • NDRIFT: Negative Drift Compensation For the autonomous QTouch sensor and DMATouch sensors, specifies how often a negative drift compensation should be performed. When this field is zero, negative drift compensation will never be performed. When this field is non-zero, the negative drift compensation time interval is given by the following formula: Tndrift = NDRIFT * 65536 * (sample clock period) With the typical sample clock frequency of 1 MHz, PDRIFT and NDRIFT can be set from 0.066 seconds to 16.7 seconds with 0.066 second resolution. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 PTHR 15 14 13 12 11 10 9 8 PDRIFT 76543210 NDRIFT 790 32142D–06/2013 ATUC64/128/256L3/4U 31.7.8 Touch Group x Configuration Register 0 Name: TGxCFG0 Access Type: Read/Write Offset: 0x20, 0x28 Reset Value: 0x00000000 • DIV: Clock Divider The prescaler is used to ensure that the CLK_CAT clock is divided to around 1 MHz to produce the sampling clock.The prescaler uses the following formula to generate the sampling clock: Sampling clock = CLK_CAT / (2(DIV+1)) • CHLEN: Charge Length For the QTouch method, specifies how many sample clock cycles should be used for transferring charge to the sense capacitor. • SELEN: Settle Length For the QTouch method, specifies how many sample clock cycles should be used for settling after charge transfer. 31 30 29 28 27 26 25 24 DIV[15:8] 23 22 21 20 19 18 17 16 DIV[7:0] 15 14 13 12 11 10 9 8 CHLEN 76543210 SELEN 791 32142D–06/2013 ATUC64/128/256L3/4U 31.7.9 Touch Group x Configuration Register 1 Name: TGxCFG1 Access Type: Read/Write Offset: 0x24, 0x2C Reset Value: 0x00000000 • DISHIFT: Discharge Shift For the sensors in QTouch group x, specifies how many bits the DILEN field should be shifted before using it to determine the discharge time. • SYNC: Sync Pin For sensors in QTouch group x, specifies that acquisition shall begin when a falling edge is received on the SYNC line. • SPREAD: Spread Spectrum Sensor Drive For sensors in QTouch group x, specifies that spread spectrum sensor drive shall be used. • DILEN: Discharge Length For sensors in QTouch group x, specifies how many clock cycles the CAT should use to discharge the capacitors before charging them. • MAX: Touch Maximum Count For sensors in QTouch group x, specifies how many counts the maximum acquisition should be. 31 30 29 28 27 26 25 24 - - DISHIFT - - SYNC SPREAD 23 22 21 20 19 18 17 16 DILEN 15 14 13 12 11 10 9 8 MAX[15:8] 76543210 MAX[7:0] 792 32142D–06/2013 ATUC64/128/256L3/4U 31.7.10 Matrix Group Configuration Register 0 Name: MGCFG0 Access Type: Read/Write Offset: 0x30 Reset Value: 0x00000000 • DIV: Clock Divider The prescaler is used to ensure that the CLK_CAT clock is divided to around 4 MHz to produce the burst timing clock.The prescaler uses the following formula to generate the burst timing clock: Burst timing clock = CLK_CAT / (2(DIV+1)) • CHLEN: Charge Length For QMatrix sensors, specifies how many burst prescaler clock cycles should be used for transferring charge to the sense capacitor. • SELEN: Settle Length For QMatrix sensors, specifies how many burst prescaler clock cycles should be used for settling after charge transfer. 31 30 29 28 27 26 25 24 DIV[15:8] 23 22 21 20 19 18 17 16 DIV[7:0] 15 14 13 12 11 10 9 8 CHLEN 76543210 SELEN 793 32142D–06/2013 ATUC64/128/256L3/4U 31.7.11 Matrix Group Configuration Register 1 Name: MGCFG1 Access Type: Read/Write Offset: 0x34 Reset Value: 0x00000000 • DISHIFT: Discharge Shift For QMatrix sensors, specifies how many bits the DILEN field should be shifted before using it to determine the discharge time. • SYNC: Sync Pin For QMatrix sensors, specifies that acquisition shall begin when a falling edge is received on the SYNC line. • SPREAD: Spread Spectrum Sensor Drive For QMatrix sensors, specifies that spread spectrum sensor drive shall be used. • DILEN: Discharge Length For QMatrix sensors, specifies how many burst prescaler clock cycles the CAT should use to discharge the capacitors at the beginning of a burst sequence. • MAX: Maximum Count For QMatrix sensors, specifies how many counts the maximum acquisition should be. 31 30 29 28 27 26 25 24 - DISHIFT - SYNC SPREAD 23 22 21 20 19 18 17 16 DILEN 15 14 13 12 11 10 9 8 MAX[15:8] 76543210 MAX[7:0] 794 32142D–06/2013 ATUC64/128/256L3/4U 31.7.12 Matrix Group Configuration Register 2 Name: MGCFG2 Access Type: Read/Write Offset: 0x38 Reset Value: 0x00000000 • ACCTRL: Analog Comparator Control When written to one, allows the CAT to disable the analog comparators when they are not needed. When written to zero, the analog comparators are always enabled. • CONSEN: Consensus Filter Length For QMatrix sensors, specifies that discharge will be terminated when CONSEN out of the most recent 5 comparator samples are positive. For example, a value of 3 in the CONSEN field will terminate discharge when 3 out of the most recent 5 comparator samples are positive. When CONSEN has the default value of 0, discharge will be terminated immediately when the comparator output goes positive. • CXDILEN: Cx Capacitor Discharge Length For QMatrix sensors, specifies how many burst prescaler clock cycles the CAT should use to discharge the Cx capacitor at the end of each burst cycle. • SYNCTIM: Sync Time Interval When non-zero, determines the number of prescaled clock cycles between the start of the acquisition on each X line for QMatrix acquisition. 31 30 29 28 27 26 25 24 ACCTRL CONSEN - 23 22 21 20 19 18 17 16 CXDILEN 15 14 13 12 11 10 9 8 - SYNCTIM[11:8] 76543210 SYNCTIM[7:0] 795 32142D–06/2013 ATUC64/128/256L3/4U 31.7.13 Status Register Name: SR Access Type: Read-only Offset: 0x3C Reset Value: 0x00000000 • DMATSC: DMATouch Sensor State Change 0: No change in the DMATSS register. 1: One or more bits have changed in the DMATSS register. • DMATSR: DMATouch State Read Register Ready 0: A new state word is not available in the DMATSR register. 1: A new state word is available in the DMATSR register. • DMATSW: DMATouch State Write Register Request 0: The DMATouch algorithm is not requesting that a state word be written to the DMATSW register. 1: The DMATouch algorithm is requesting that a state word be written to the DMATSW register. • ACQDONE: Acquisition Done 0: Acquisition is not done (still in progress). 1: Acquisition is complete. • ACREADY: Acquired Count Data is Ready 0: Acquired count data is not available in the ACOUNT register. 1: Acquired count data is available in the ACOUNT register. • MBLREQ: Matrix Burst Length Required 0: The QMatrix acquisition does not require any burst lengths. 1: The QMatrix acquisition requires burst lengths for the current X line. • ATSTATE: Autonomous Touch Sensor State 0: The autonomous QTouch sensor is not active. 1: The autonomous QTouch sensor is active. • ATSC: Autonomous Touch Sensor Status Interrupt 0: No status change in the autonomous QTouch sensor. 1: Status change in the autonomous QTouch sensor. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - DMATSR DMATSW 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - MBLREQ ATSTATE ATSC ATCAL ENABLED 796 32142D–06/2013 ATUC64/128/256L3/4U • ATCAL: Autonomous Touch Calibration Ongoing 0: The autonomous QTouch sensor is not calibrating. 1: The autonomous QTouch sensor is calibrating. • ENABLED: Module Enabled 0: The module is disabled. 1: The module is enabled. 797 32142D–06/2013 ATUC64/128/256L3/4U 31.7.14 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x40 Reset Value: - Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - - - 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - - - ATSC ATCAL - 798 32142D–06/2013 ATUC64/128/256L3/4U 31.7.15 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x44 Reset Value: - Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - - - 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - - - ATSC ATCAL - 799 32142D–06/2013 ATUC64/128/256L3/4U 31.7.16 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x48 Reset Value: - Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - - - 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - - - ATSC ATCAL - 800 32142D–06/2013 ATUC64/128/256L3/4U 31.7.17 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x4C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - - - 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - - - ATSC ATCAL - 801 32142D–06/2013 ATUC64/128/256L3/4U 31.7.18 Acquisition Initiation and Selection Register Name: AISR Access Type: Read/Write Offset: 0x50 Reset Value: 0x00000000 • ACQSEL: Acquisition Type Selection A write to this register initiates an acquisition of the following type: 00: QTouch Group A. 01: QTouch Group B. 10: QMatrix Group. 11: Undefined behavior. A read of this register will return the value that was previously written. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - 15 14 13 12 11 10 9 8 - 76543210 - ACQSEL 802 32142D–06/2013 ATUC64/128/256L3/4U 31.7.19 Acquired Count Register Name: ACOUNT Access Type: Read-only Offset: 0x54 Reset Value: 0x00000000 • Y: Y index The Y index (for QMatrix method) associated with this count value. • SPORX: Sensor pair or X index The sensor pair index (for QTouch method) or X index (for QMatrix method) associated with this count value. • COUNT: Count value The signal (number of counts) acquired on the channel specified in the SPORX and Y fields. When multiple acquired count values are read from a QTouch acquisition, the Y field will always be 0 and the SPORX value will increase monotonically. For example, suppose a QTouch acquisition is performed using sensor pairs SP1, SP4, and SP9. The first count read will have SPORX=1, the second read will have SPORX=4, and the third read will have SPORX=9. When multiple acquired count values are read from a QMatrix acquisition, the SPORX value will stay the same while Y increases monotonically through all Y values in the group. Then SPORX will increase to the next X value in the group. For example, a QMatrix acquisition with X=2,3 and Y=4,7 would provide count values in the following order: X=2 and Y=4, then X=2 and Y=7, then X=3 and Y=4, and finally X=3 and Y=7. 31 30 29 28 27 26 25 24 Y 23 22 21 20 19 18 17 16 SPORX 15 14 13 12 11 10 9 8 COUNT[15:8] 76543210 COUNT[7:0] 803 32142D–06/2013 ATUC64/128/256L3/4U 31.7.20 Matrix Burst Length Register Name: MBLEN Access Type: Write-only Offset: 0x58 Reset Value: - • BURSTx: Burst Length x For QMatrix sensors, specifies how many times the switching sequence should be repeated before acquisition begins for each channel. Each count in the BURSTx field specifies 1 repeat of the switching sequence, so the actual burst length will be BURST. Before doing a QMatrix acquisition on one X line this register has to be written with the burst values for the current XY pairs. For each X line this register needs to be programmed with all the Y values. If Y values larger than 3 are used the register has to be written several times in order to specify all burst lengths. The Status Register bit MBLREQ is set to 1 when the CAT is waiting for values to be written into this register. 31 30 29 28 27 26 25 24 BURST0 23 22 21 20 19 18 17 16 BURST1 15 14 13 12 11 10 9 8 BURST2 76543210 BURST3 804 32142D–06/2013 ATUC64/128/256L3/4U 31.7.21 Discharge Current Source Register Name: DICS Access Type: Read/Write Offset: 0x5C Reset Value: 0x00000000 • FSOURCES: Force Discharge Current Sources When FSOURCES[n] is 0, the corresponding discharge current source behavior depends on SOURCES[n]. When FSOURCES[n] is 1, the corresponding discharge current source is forced to be enabled continuously. This is useful for testing or debugging but should not be done during normal acquisition. • GLEN: Global Enable 0: The current source module is globally disabled. 1: The current source module is globally enabled. • INTVREFSEL: Internal Voltage Reference Select 0: The voltage for the reference resistor is generated from the internal band gap circuit. 1: The voltage for the reference resistor is VDDIO/3. • INTREFSEL: Internal Reference Select 0: The reference current flows through an external resistor on the DIS pin. 1: The reference current flows through the internal reference resistor. • TRIM: Reference Current Trimming This field is used to trim the discharge current. 0x00 corresponds to the minimum current value, and 0x1F corresponds to the maximum current value. • SOURCES: Enable Discharge Current Sources When SOURCES[n] is 0, the corresponding discharge current source is disabled. When SOURCES[n] is 1, the corresponding discharge current source is enabled at appropriate times during acquisition. 31 30 29 28 27 26 25 24 FSOURCES[7:0] 23 22 21 20 19 18 17 16 GLEN - - - - - INTVREFSEL INTREFSEL 15 14 13 12 11 10 9 8 - - - TRIM 76543210 SOURCES[7:0] 805 32142D–06/2013 ATUC64/128/256L3/4U 31.7.22 Spread Spectrum Configuration Register Name: SSCFG Access Type: Read/Write Offset: 0x60 Reset Value: 0x00000000 • MAXDEV: Maximum Deviation When spread spectrum burst is enabled, MAXDEV indicates the maximum number of prescaled clock cycles the burst pulse will be extended or shortened. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 MAXDEV 806 32142D–06/2013 ATUC64/128/256L3/4U 31.7.23 CSA Resistor Control Register Name: CSARES Access Type: Read/Write Offset: 0x64 Reset Value: 0x00000000 • RES: Resistive Drive Enable When RES[n] is 0, CSA[n] has the same drive properties as normal I/O pads. When RES[n] is 1, CSA[n] has a nominal output resistance of 1kOhm during the burst phase. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - RES[16] 15 14 13 12 11 10 9 8 RES[15:8] 76543210 RES[7:0] 807 32142D–06/2013 ATUC64/128/256L3/4U 31.7.24 CSB Resistor Control Register Name: CSBRES Access Type: Read/Write Offset: 0x68 Reset Value: 0x00000000 • RES: Resistive Drive Enable When RES[n] is 0, CSB[n] has the same drive properties as normal I/O pads. When RES[n] is 1, CSB[n] has a nominal output resistance of 1kOhm during the burst phase. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - RES[16] 15 14 13 12 11 10 9 8 RES[15:8] 76543210 RES[7:0] 808 32142D–06/2013 ATUC64/128/256L3/4U 31.7.25 Autonomous Touch Base Count Register Name: ATBASE Access Type: Read-only Offset: 0x6C Reset Value: 0x00000000 • COUNT: Count value The base count currently stored by the autonomous touch sensor. This is useful for autonomous touch debugging purposes. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - 15 14 13 12 11 10 9 8 COUNT[15:8] 76543210 COUNT[7:0] 809 32142D–06/2013 ATUC64/128/256L3/4U 31.7.26 Autonomous Touch Current Count Register Name: ATCURR Access Type: Read-only Offset: 0x70 Reset Value: 0x00000000 • COUNT: Count value The current count acquired by the autonomous touch sensor. This is useful for autonomous touch debugging purposes. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - 15 14 13 12 11 10 9 8 COUNT[15:8] 76543210 COUNT[7:0] 810 32142D–06/2013 ATUC64/128/256L3/4U 31.7.27 DMATouch State Write Register Name: DMATSW Access Type: Write-only Offset: 0x78 Reset Value: 0x00000000 • NOTINCAL: Not in Calibration Mode 0: Calibration should be performed on the next iteration of the DMATouch algorithm. 1: Calibration should not be performed on the next iteration of the DMATouch algorithm. • DETCNT: Detection Count This count value is updated and used by the DMATouch algorithm in order to detect when a button has been pushed. • BASECNT: Base Count This count value represents the average expected acquired count when the sensor/button is not pushed. 31 30 29 28 27 26 25 24 - - - - - - - NOTINCAL 23 22 21 20 19 18 17 16 DETCNT[23:16] 15 14 13 12 11 10 9 8 BASECNT[15:8] 76543210 BASECNT[7:0] 811 32142D–06/2013 ATUC64/128/256L3/4U 31.7.28 DMA Touch State Read Register Name: DMATSR Access Type: Read/Write Offset: 0x7C Reset Value: 0x00000000 • NOTINCAL: Not in Calibration Mode 0: Calibration should be performed on the next iteration of the DMATouch algorithm. 1: Calibration should not be performed on the next iteration of the DMATouch algorithm. • DETCNT: Detection Count This count value is updated and used by the DMATouch algorithm in order to detect when a button has been pushed. • BASECNT: Base Count This count value represents the average expected acquired count when the sensor/button is not pushed. 31 30 29 28 27 26 25 24 - - - - - - - NOTINCAL 23 22 21 20 19 18 17 16 DETCNT[23:16] 15 14 13 12 11 10 9 8 BASECNT[15:8] 76543210 BASECNT[7:0] 812 32142D–06/2013 ATUC64/128/256L3/4U 31.7.29 Analog Comparator Shift Offset Register x Name: ACSHIx Access Type: Read/Write Offset: 0x80, 0x84, 0x88, 0x8C, 0x90, 0x94, 0x98, and 0x9C Reset Value: 0x00000000 • SHIVAL: Shift Offset Value Specifies the amount to shift the count value from each comparator. This allows the offset of each comparator to be compensated. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - 15 14 13 12 11 10 9 8 - SHIVAL[11:8] 76543210 SHIVAL[7:0] 813 32142D–06/2013 ATUC64/128/256L3/4U 31.7.30 DMATouch Sensor Status Register Name: DMATSS Access Type: Read-only Offset: 0xA0 Reset Value: 0x00000000 • SS: Sensor Status 0: The DMATouch sensor is not active, i.e. the button is currently not pushed. 1: The DMATouch sensor is active, i.e. the button is currently pushed. 31 30 29 28 27 26 25 24 SS[31:24] 23 22 21 20 19 18 17 16 SS[23:16] 15 14 13 12 11 10 9 8 SS[15:8] 76543210 SS[7:0] 814 32142D–06/2013 ATUC64/128/256L3/4U 31.7.31 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0xF8 Reset Value: - • SP[n]: Sensor pair implemented 0: The corresponding sensor pair is not implemented 1: The corresponding sensor pair is implemented. 31 30 29 28 27 26 25 24 SP[31:24] 23 22 21 20 19 18 17 16 SP[23:16] 15 14 13 12 11 10 9 8 SP[15:8] 76543210 SP[7:0] 815 32142D–06/2013 ATUC64/128/256L3/4U 31.7.32 Version Register Name: VERSION Access Type: Read-only Offset: 0xFC Reset Value: - • VARIANT: Variant number Reserved. No functionality associated. • VERSION: Version number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 816 32142D–06/2013 ATUC64/128/256L3/4U 31.8 Module Configuration The specific configuration the CAT module is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 31.8.1 Resistive Drive By default, the CAT pins are driven with normal I/O drive properties. Some of the CSA and CSB pins can optionally drive with a 1k output resistance for improved EMC. To enable resistive drive on a pin, the user must write a one to the corresponding bit in the CSA Resistor Control Register (CSARES) or CSB Resistor Control Register (CSBRES) register. Table 31-4. CAT Configuration Feature CAT Number of touch sensors/Size of matrix Allows up to 17 touch sensors, or up to 16 by 8 matrix sensors to be interfaced. Table 31-5. CAT Clocks Clock Name Description CLK_CAT Clock for the CAT bus interface GCLK The generic clock used for the CAT is GCLK4 Table 31-6. Register Reset Values Register Reset Value VERSION 0x00000400 PARAMETER 0x0001FFFF 817 32142D–06/2013 ATUC64/128/256L3/4U 32. Glue Logic Controller (GLOC) Rev: 1.0.0.0 32.1 Features • Glue logic for general purpose PCB design • Programmable lookup table • Up to four inputs supported per lookup table • Optional filtering of output 32.2 Overview The Glue Logic Controller (GLOC) contains programmable logic which can be connected to the device pins. This allows the user to eliminate logic gates for simple glue logic functions on the PCB. The GLOC consists of a number of lookup table (LUT) units. Each LUT can generate an output as a user programmable logic expression with four inputs. Inputs can be individually masked. The output can be combinatorially generated from the inputs, or filtered to remove spikes. 32.3 Block Diagram Figure 32-1. GLOC Block Diagram PERIPHERAL BUS TRUTH FILTER OUT[0] ... OUT[n] FILTEN IN[3:0] … IN[(4n+3):4n] AEN CLK_GLOC GCLK 818 32142D–06/2013 ATUC64/128/256L3/4U 32.4 I/O Lines Description Each LUT have 4 inputs and one output. The inputs and outputs for the LUTs are mapped sequentially to the inputs and outputs. This means that LUT0 is connected to IN0 to IN3 and OUT0. LUT1 is connected to IN4 to IN7 and OUT1. In general, LUTn is connected to IN[4n] to IN[4n+3] and OUTn. 32.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 32.5.1 I/O Lines The pins used for interfacing the GLOC may be multiplexed with I/O Controller lines. The programmer must first program the I/O Controller to assign the desired GLOC pins to their peripheral function. If I/O lines of the GLOC are not used by the application, they can be used for other purposes by the I/O Controller. It is only required to enable the GLOC inputs and outputs actually in use. Pullups for pins configured to be used by the GLOC will be disabled. 32.5.2 Clocks The clock for the GLOC bus interface (CLK_GLOC) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the GLOC before disabling the clock, to avoid freezing the module in an undefined state. Additionally, the GLOC depends on a dedicated Generic Clock (GCLK). The GCLK can be set to a wide range of frequencies and clock sources, and must be enabled by the System Control Interface (SCIF) before the GLOC filter can be used. 32.5.3 Debug Operation When an external debugger forces the CPU into debug mode, the GLOC continues normal operation. 32.6 Functional Description 32.6.1 Enabling the Lookup Table Inputs Since the inputs to each lookup table (LUT) unit can be multiplexed with other peripherals, each input must be explicitly enabled by writing a one to the corresponding enable bit (AEN) in the corresponding Control Register (CR). If no inputs are enabled, the output OUTn will be the least significant bit in the TRUTHn register. Table 32-1. I/O Lines Description Pin Name Pin Description Type IN0-INm Inputs to lookup tables Input OUT0-OUTn Output from lookup tables Output 819 32142D–06/2013 ATUC64/128/256L3/4U 32.6.2 Configuring the Lookup Table The lookup table in each LUT unit can generate any logic expression OUT as a function of up to four inputs, IN[3:0]. The truth table for the expression is written to the TRUTH register for the LUT. Table 32-2 shows the truth table for LUT0. The truth table for LUTn is written to TRUTHn, and the corresponding input and outputs will be IN[4n] to IN[4n+3] and OUTn. 32.6.3 Output Filter By default, the output OUTn is a combinatorial function of the inputs IN[4n] to IN[4n+3]. This may cause some short glitches to occur when the inputs change value. It is also possible to clock the output through a filter to remove glitches. This requires that the corresponding generic clock (GCLK) has been enabled before use. The filter can then be enabled by writing a one to the Filter Enable (FILTEN) bit in CRn. The OUTn output will be delayed by three to four GCLK cycles when the filter is enabled. Table 32-2. Truth Table for the Lookup Table in LUT0 IN[3] IN[2] IN[1] IN[0] OUT[0] 0 0 0 0 TRUTH0[0] 0 0 0 1 TRUTH0[1] 0 0 1 0 TRUTH0[2] 0 0 1 1 TRUTH0[3] 0 1 0 0 TRUTH0[4] 0 1 0 1 TRUTH0[5] 0 1 1 0 TRUTH0[6] 0 1 1 1 TRUTH0[7] 1 0 0 0 TRUTH0[8] 1 0 0 1 TRUTH0[9] 1 0 1 0 TRUTH0[10] 1 0 1 1 TRUTH0[11] 1 1 0 0 TRUTH0[12] 1 1 0 1 TRUTH0[13] 1 1 1 0 TRUTH0[14] 1 1 1 1 TRUTH0[15] 820 32142D–06/2013 ATUC64/128/256L3/4U 32.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 32-3. GLOC Register Memory Map Offset Register Register Name Access Reset 0x00+n*0x08 Control Register n CRn Read/Write 0x00000000 0x04+n*0x08 Truth Table Register n TRUTHn Read/Write 0x00000000 0x38 Parameter Register PARAMETER Read-only - (1) 0x3C Version Register VERSION Read-only - (1) 821 32142D–06/2013 ATUC64/128/256L3/4U 32.7.1 Control Register n Name: CRn Access Type: Read/Write Offset: 0x00+n*0x08 Reset Value: 0x00000000 • FILTEN: Filter Enable 1: The output is glitch filtered 0: The output is not glitch filtered • AEN: Enable IN Inputs Input IN[n] is enabled when AEN[n] is one. Input IN[n] is disabled when AEN[n] is zero, and will not affect the OUT value. 31 30 29 28 27 26 25 24 FILTEN - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - AEN 822 32142D–06/2013 ATUC64/128/256L3/4U 32.7.2 Truth Table Register n Name: TRUTHn Access Type: Read/Write Offset: 0x04+n*0x08 Reset Value: 0x00000000 • TRUTH: Truth Table Value This value defines the output OUT as a function of inputs IN: OUT = TRUTH[IN] 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 TRUTH[15:8] 76543210 TRUTH[7:0] 823 32142D–06/2013 ATUC64/128/256L3/4U 32.7.3 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x38 Reset Value: - • LUTS: Lookup Table Units Implemented This field contains the number of lookup table units implemented in this device. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 LUTS 824 32142D–06/2013 ATUC64/128/256L3/4U 32.7.4 VERSION Register Name: VERSION Access Type: Read-only Offset: 0x3C Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 825 32142D–06/2013 ATUC64/128/256L3/4U 32.8 Module Configuration The specific configuration for each GLOC instance is listed in the following tables.The GLOC bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 32-4. GLOC Configuration Feature GLOC Number of LUT units 2 Table 32-5. GLOC Clocks Clock Name Description CLK_GLOC Clock for the GLOC bus interface GCLK The generic clock used for the GLOC is GCLK5 Table 32-6. Register Reset Values Register Reset Value VERSION 0x00000100 PARAMETER 0x00000002 826 32142D–06/2013 ATUC64/128/256L3/4U 33. aWire UART (AW) Rev: 2.3.0.0 33.1 Features • Asynchronous receiver or transmitter when the aWire system is not used for debugging. • One- or two-pin operation supported. 33.2 Overview If the AW is not used for debugging, the aWire UART can be used by the user to send or receive data with one start bit, eight data bits, no parity bits, and one stop bit. This can be controlled through the aWire UART user interface. This chapter only describes the aWire UART user interface. For a description of the aWire Debug Interface, please see the Programming and Debugging chapter. 33.3 Block Diagram Figure 33-1. aWire Debug Interface Block Diagram UART Reset filter External reset AW_ENABLE RESET_N Baudrate Detector RW SZ ADDR DATA CRC AW CONTROL AW User Interface SAB interface RESET command Power Manager HALT command CPU Flash Controller CHIP_ERASE command aWire Debug Interface PB SAB 827 32142D–06/2013 ATUC64/128/256L3/4U 33.4 I/O Lines Description 33.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 33.5.1 I/O Lines The pin used by AW is multiplexed with the RESET_N pin. The reset functionality is the default function of this pin. To enable the aWire functionality on the RESET_N pin the user must enable the aWire UART user interface. 33.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the aWire UART user interface, the aWire UART user interface will stop functioning and resume operation after the system wakes up from sleep mode. 33.5.3 Clocks The aWire UART uses the internal 120 MHz RC oscillator (RC120M) as clock source for its operation. When using the aWire UART user interface RC120M must enabled using the Clock Request Register (see Section 33.6.1). The clock for the aWire UART user interface (CLK_AW) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the aWire UART user interface before disabling the clock, to avoid freezing the aWire UART user interface in an undefined state. 33.5.4 Interrupts The aWire UART user interface interrupt request line is connected to the interrupt controller. Using the aWire UART user interface interrupt requires the interrupt controller to be programmed first. 33.5.5 Debug Operation If the AW is used for debugging the aWire UART user interface will not be usable. When an external debugger forces the CPU into debug mode, the aWire UART user interface continues normal operation. If the aWire UART user interface is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 33.5.6 External Components The AW needs an external pullup on the RESET_N pin to ensure that the pin is pulled up when the bus is not driven. 33.6 Functional Description The aWire UART user interface can be used as a spare Asynchronous Receiver or Transmitter when AW is not used for debugging. Table 33-1. I/O Lines Description Name Description Type DATA aWire data multiplexed with the RESET_N pin. Input/Output 828 32142D–06/2013 ATUC64/128/256L3/4U 33.6.1 How to Initialize The Module To initialize the aWire UART user interface the user must first enable the clock by writing a one to the Clock Enable bit in the Clock Request Register (CLKR.CLKEN) and wait for the Clock Enable bit in the Status Register (SR.CENABLED) to be set. After doing this either receive, transmit or receive with resync must be selected by writing the corresponding value into the Mode field of the Control (CTRL.MODE) Register. Due to the RC120M being asynchronous with the system clock values must be allowed to propagate in the system. During this time the aWire master will set the Busy bit in the Status Register (SR.BUSY). After the SR.BUSY bit is cleared the Baud Rate field in the Baud Rate Register (BRR.BR) can be written with the wanted baudrate ( ) according to the following formula ( is the RC120M clock frequency): After this operation the user must wait until the SR.BUSY is cleared. The interface is now ready to be used. 33.6.2 Basic Asynchronous Receiver Operation The aWire UART user interface must be initialized according to the sequence above, but the CTRL.MODE field must be written to one (Receive mode). When a data byte arrives the aWire UART user interface will indicate this by setting the Data Ready Interrupt bit in the Status Register (SR.DREADYINT). The user must read the Data in the Receive Holding Register (RHR.RXDATA) and clear the Interrupt bit by writing a one to the Data Ready Interrupt Clear bit in the Status Clear Register (SCR.DREADYINT). The interface is now ready to receive another byte. 33.6.3 Basic Asynchronous Transmitter Operation The aWire UART user interface must be initialized according to the sequence above, but the CTRL.MODE field must be written to two (Transmit mode). To transmit a data byte the user must write the data to the Transmit Holding Register (THE.TXDATA). Before the next byte can be written the SR.BUSY must be cleared. 33.6.4 Basic Asynchronous Receiver with Resynchronization By writing three into CTRL.MODE the aWire UART user interface will assume that the first byte it receives is a sync byte (0x55) and set BRR.BR according to this. All subsequent transfers will assume this baudrate, unless BRR.BR is rewritten by the user. To make the aWire UART user interface accept a new sync resynchronization the aWire UART user interface must be disabled by writing zero to CTRL.MODE and then reenable the interface. 33.6.5 Overrun In Receive mode an overrun can occur if the user has not read the previous received data from the RHR.RXDATA when the newest data should be placed there. Such a condition is flagged by setting the Overrun bit in the Status Register (SR.OVERRUN). If SR.OVERRUN is set the newest data received is placed in RHR.RXDATA and the data that was there before is overwritten. f br f aw f br 8f aw BR = ----------- 829 32142D–06/2013 ATUC64/128/256L3/4U 33.6.6 Interrupts To make the CPU able to do other things while waiting for the aWire UART user interface to finish its operations the aWire UART user interface supports generating interrupts. All status bits in the Status Register can be used as interrupt sources, except the SR.BUSY and SR.CENABLED bits. To enable an interrupt the user must write a one to the corresponding bit in the Interrupt Enable Register (IER). Upon the next zero to one transition of this SR bit the aWire UART user interface will flag this interrupt to the CPU. To clear the interrupt the user must write a one to the corresponding bit in the Status Clear Register (SCR). Interrupts can be disabled by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt Mask Register (IMR) can be read to check if an interrupt is enabled or disabled. 33.6.7 Using the Peripheral DMA Controller To relieve the CPU of data transfers the aWire UART user interface support using the Peripheral DMA controller. To transmit using the Peripheral DMA Controller do the following: 1. Setup the aWire UART user interface in transmit mode. 2. Setup the Peripheral DMA Controller with buffer address and length, use byte as transfer size. 3. Enable the Peripheral DMA Controller. 4. Wait until the Peripheral DMA Controller is done. To receive using the Peripheral DMA Controller do the following: 1. Setup the aWire UART user interface in receive mode 2. Setup the Peripheral DMA Controller with buffer address and length, use byte as transfer size. 3. Enable the Peripheral DMA Controller. 4. Wait until the Peripheral DMA Controller is ready. 830 32142D–06/2013 ATUC64/128/256L3/4U 33.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 33-2. aWire UART user interface Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CTRL Read/Write 0x00000000 0x04 Status Register SR Read-only 0x00000000 0x08 Status Clear Register SCR Write-only - 0x0C Interrupt Enable Register IER Write-only - 0x10 Interrupt Disable Register IDR Write-only - 0x14 Interrupt Mask Register IMR Read-only 0x00000000 0x18 Receive Holding Register RHR Read-only 0x00000000 0x1C Transmit Holding Register THR Read/Write 0x00000000 0x20 Baud Rate Register BRR Read/Write 0x00000000 0x24 Version Register VERSION Read-only -(1) 0x28 Clock Request Register CLKR Read/Write 0x00000000 831 32142D–06/2013 ATUC64/128/256L3/4U 33.7.1 Control Register Name: CTRL Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • MODE: aWire UART user interface mode 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - MODE Table 33-3. aWire UART user interface Modes MODE Mode Description 0 Disabled 1 Receive 2 Transmit 3 Receive with resync. 832 32142D–06/2013 ATUC64/128/256L3/4U 33.7.2 Status Register Name: SR Access Type: Read-only Offset: 0x04 Reset Value: 0x00000000 • TRMIS: Transmit Mismatch 0: No transfers mismatches. 1: The transceiver was active when receiving. This bit is set when the transceiver is active when receiving. This bit is cleared when corresponding bit in SCR is written to one. • OVERRUN: Data Overrun 0: No data overwritten in RHR. 1: Data in RHR has been overwritten before it has been read. This bit is set when data in RHR is overwritten before it has been read. This bit is cleared when corresponding bit in SCR is written to one. • DREADYINT: Data Ready Interrupt 0: No new data in the RHR. 1: New data received and placed in the RHR. This bit is set when new data is received and placed in the RHR. This bit is cleared when corresponding bit in SCR is written to one. • READYINT: Ready Interrupt 0: The interface has not generated an ready interrupt. 1: The interface has had a transition from busy to not busy. This bit is set when the interface has transition from busy to not busy. This bit is cleared when corresponding bit in SCR is written to one. • CENABLED: Clock Enabled 0: The aWire clock is not enabled. 1: The aWire clock is enabled. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 - - - - - CENABLED - BUSY 833 32142D–06/2013 ATUC64/128/256L3/4U This bit is set when the clock is disabled. This bit is cleared when the clock is enabled. • BUSY: Synchronizer Busy 0: The asynchronous interface is ready to accept more data. 1: The asynchronous interface is busy and will block writes to CTRL, BRR, and THR. This bit is set when the asynchronous interface becomes busy. This bit is cleared when the asynchronous interface becomes ready. 834 32142D–06/2013 ATUC64/128/256L3/4U 33.7.3 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x08 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 -------- 835 32142D–06/2013 ATUC64/128/256L3/4U 33.7.4 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x0C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 -------- 836 32142D–06/2013 ATUC64/128/256L3/4U 33.7.5 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 -------- 837 32142D–06/2013 ATUC64/128/256L3/4U 33.7.6 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 -------- 838 32142D–06/2013 ATUC64/128/256L3/4U 33.7.7 Receive Holding Register Name: RHR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 • RXDATA: Received Data The last byte received. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RXDATA 839 32142D–06/2013 ATUC64/128/256L3/4U 33.7.8 Transmit Holding Register Name: THR Access Type: Read/Write Offset: 0x1C Reset Value: 0x00000000 • TXDATA: Transmit Data The data to send. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 TXDATA 840 32142D–06/2013 ATUC64/128/256L3/4U 33.7.9 Baud Rate Register Name: BRR Access Type: Read/Write Offset: 0x20 Reset Value: 0x00000000 • BR: Baud Rate The baud rate ( ) of the transmission, calculated using the following formula ( is the RC120M frequency): BR should not be set to a value smaller than 32. Writing a value to this field will update the baud rate of the transmission. Reading this field will give the current baud rate of the transmission. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 BR[15:8] 76543210 BR[7:0] f br f aw f br 8f aw BR = ----------- 841 32142D–06/2013 ATUC64/128/256L3/4U 33.7.10 Version Register Name: VERSION Access Type: Read-only Offset: 0x24 Reset Value: 0x00000200 • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 842 32142D–06/2013 ATUC64/128/256L3/4U 33.7.11 Clock Request Register Name: CLKR Access Type: Read/Write Offset: 0x28 Reset Value: 0x00000000 • CLKEN: Clock Enable 0: The aWire clock is disabled. 1: The aWire clock is enabled. Writing a zero to this bit will disable the aWire clock. Writing a one to this bit will enable the aWire clock. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - CLKEN 843 32142D–06/2013 ATUC64/128/256L3/4U 33.8 Module Configuration The specific configuration for each aWire instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 33-4. AW Clocks Clock Name Description CLK_AW Clock for the AW bus interface Table 33-5. Register Reset Values Register Reset Value VERSION 0x00000230 844 32142D–06/2013 ATUC64/128/256L3/4U 34. Programming and Debugging 34.1 Overview The ATUC64/128/256L3/4U supports programming and debugging through two interfaces, JTAG or aWire. JTAG is an industry standard interface and allows boundary scan for PCB testing, as well as daisy-chaining of multiple devices on the PCB. aWire is an Atmel proprietary protocol which offers higher throughput and robust communication, and does not require application pins to be reserved. Either interface provides access to the internal Service Access Bus (SAB), which offers a bridge to the High Speed Bus, giving access to memories and peripherals in the device. By using this bridge to the bus system, the flash and fuses can thus be programmed by accessing the Flash Controller in the same manner as the CPU. The SAB also provides access to the Nexus-compliant On-chip Debug (OCD) system in the device, which gives the user non-intrusive run-time control of the program execution. Additionally, trace information can be output on the Auxiliary (AUX) debug port or buffered in internal RAM for later retrieval by JTAG or aWire. 34.2 Service Access Bus The AVR32 architecture offers a common interface for access to On-chip Debug, programming, and test functions. These are mapped on a common bus called the Service Access Bus (SAB), which is linked to the JTAG and aWire port through a bus master module, which also handles synchronization between the debugger and SAB clocks. When accessing the SAB through the debugger there are no limitations on debugger frequency compared to chip frequency, although there must be an active system clock in order for the SAB accesses to complete. If the system clock is switched off in sleep mode, activity on the debugger will restart the system clock automatically, without waking the device from sleep. Debuggers may optimize the transfer rate by adjusting the frequency in relation to the system clock. This ratio can be measured with debug protocol specific instructions. The Service Access Bus uses 36 address bits to address memory or registers in any of the slaves on the bus. The bus supports sized accesses of bytes (8 bits), halfwords (16 bits), or words (32 bits). All accesses must be aligned to the size of the access, i.e. halfword accesses must have the lowest address bit cleared, and word accesses must have the two lowest address bits cleared. 34.2.1 SAB Address Map The SAB gives the user access to the internal address space and other features through a 36 bits address space. The 4 MSBs identify the slave number, while the 32 LSBs are decoded within the slave’s address space. The SAB slaves are shown in Table 34-1. Table 34-1. SAB Slaves, Addresses and Descriptions Slave Address [35:32] Description Unallocated 0x0 Intentionally unallocated OCD 0x1 OCD registers HSB 0x4 HSB memory space, as seen by the CPU 845 32142D–06/2013 ATUC64/128/256L3/4U 34.2.2 SAB Security Restrictions The Service Access bus can be restricted by internal security measures. A short description of the security measures are found in the table below. 34.2.2.1 Security measure and control location A security measure is a mechanism to either block or allow SAB access to a certain address or address range. A security measure is enabled or disabled by one or several control signals. This is called the control location for the security measure. These security measures can be used to prevent an end user from reading out the code programmed in the flash, for instance. Below follows a more in depth description of what locations are accessible when the security measures are active. Note: 1. Second Word of the User Page, refer to the Fuses Settings section for details. HSB 0x5 Alternative mapping for HSB space, for compatibility with other 32-bit AVR devices. Memory Service Unit 0x6 Memory Service Unit registers Reserved Other Unused Table 34-1. SAB Slaves, Addresses and Descriptions Slave Address [35:32] Description Table 34-2. SAB Security Measures Security Measure Control Location Description Secure mode FLASHCDW SECURE bits set Allocates a portion of the flash for secure code. This code cannot be read or debugged. The User page is also locked. Security bit FLASHCDW security bit set Programming and debugging not possible, very restricted access. User code programming FLASHCDW UPROT + security bit set Restricts all access except parts of the flash and the flash controller for programming user code. Debugging is not possible unless an OS running from the secure part of the flash supports it. Table 34-3. Secure Mode SAB Restrictions Name Address Start Address End Access Secure flash area 0x580000000 0x580000000 + (USERPAGE[15:0] << 10) Blocked Secure RAM area 0x500000000 0x500000000 + (USERPAGE[31:16] << 10) Blocked User page 0x580800000 0x581000000 Read Other accesses - - As normal 846 32142D–06/2013 ATUC64/128/256L3/4U Table 34-4. Security Bit SAB Restrictions Name Address start Address end Access OCD DCCPU, OCD DCEMU, OCD DCSR 0x100000110 0x100000118 Read/Write User page 0x580800000 0x581000000 Read Other accesses - - Blocked Table 34-5. User Code Programming SAB Restrictions Name Address start Address end Access OCD DCCPU, OCD DCEMU, OCD DCSR 0x100000110 0x100000118 Read/Write User page 0x580800000 0x581000000 Read FLASHCDW PB interface 0x5FFFE0000 0x5FFFE0400 Read/Write FLASH pages outside BOOTPROT 0x580000000 + BOOTPROT size 0x580000000 + Flash size Read/Write Other accesses - - Blocked 847 32142D–06/2013 ATUC64/128/256L3/4U 34.3 On-Chip Debug Rev: 2.1.2.0 34.3.1 Features • Debug interface in compliance with IEEE-ISTO 5001-2003 (Nexus 2.0) Class 2+ • JTAG or aWire access to all on-chip debug functions • Advanced Program, Data, Ownership, and Watchpoint trace supported • NanoTrace aWire- or JTAG-based trace access • Auxiliary port for high-speed trace information • Hardware support for 6 Program and 2 Data breakpoints • Unlimited number of software breakpoints supported • Automatic CRC check of memory regions 34.3.2 Overview Debugging on the ATUC64/128/256L3/4U is facilitated by a powerful On-Chip Debug (OCD) system. The user accesses this through an external debug tool which connects to the JTAG or aWire port and the Auxiliary (AUX) port if implemented. The AUX port is primarily used for trace functions, and an aWire- or JTAG-based debugger is sufficient for basic debugging. The debug system is based on the Nexus 2.0 standard, class 2+, which includes: • Basic run-time control • Program breakpoints • Data breakpoints • Program trace • Ownership trace • Data trace In addition to the mandatory Nexus debug features, the ATUC64/128/256L3/4U implements several useful OCD features, such as: • Debug Communication Channel between CPU and debugger • Run-time PC monitoring • CRC checking • NanoTrace • Software Quality Assurance (SQA) support The OCD features are controlled by OCD registers, which can be accessed by the debugger, for instance when the NEXUS_ACCESS JTAG instruction is loaded. The CPU can also access OCD registers directly using mtdr/mfdr instructions in any privileged mode. The OCD registers are implemented based on the recommendations in the Nexus 2.0 standard, and are detailed in the AVR32UC Technical Reference Manual. 34.3.3 I/O Lines Description The OCD AUX trace port contains a number of pins, as shown in Table 34-6 on page 848. These are multiplexed with I/O Controller lines, and must explicitly be enabled by writing OCD registers before the debug session starts. The AUX port is mapped to two different locations, 848 32142D–06/2013 ATUC64/128/256L3/4U selectable by OCD Registers, minimizing the chance that the AUX port will need to be shared with an application. 34.3.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 34.3.4.1 Power Management The OCD clock operates independently of the CPU clock. If enabled in the Power Manager, the OCD clock (CLK_OCD) will continue running even if the CPU enters a sleep mode that disables the CPU clock. 34.3.4.2 Clocks The OCD has a clock (CLK_OCD) running synchronously with the CPU clock. This clock is generated by the Power Manager. The clock is enabled at reset, and can be disabled by writing to the Power Manager. 34.3.4.3 Interrupt The OCD system interrupt request lines are connected to the interrupt controller. Using the OCD interrupts requires the interrupt controller to be programmed first. Table 34-6. Auxiliary Port Signals Pin Name Pin Description Direction Active Level Type MCKO Trace data output clock Output Digital MDO[5:0] Trace data output Output Digital MSEO[1:0] Trace frame control Output Digital EVTI_N Event In Input Low Digital EVTO_N Event Out Output Low Digital 849 32142D–06/2013 ATUC64/128/256L3/4U 34.3.5 Block Diagram Figure 34-1. On-Chip Debug Block Diagram 34.3.6 SAB-based Debug Features A debugger can control all OCD features by writing OCD registers over the SAB interface. Many of these do not depend on output on the AUX port, allowing an aWire- or JTAG-based debugger to be used. A JTAG-based debugger should connect to the device through a standard 10-pin IDC connector as described in the AVR32UC Technical Reference Manual. An aWire-based debugger should connect to the device through the RESET_N pin. On-Chip Debug JTAG Debug PC Debug Instruction CPU Breakpoints Program Trace Data Trace Ownership Trace Transmit Queue Watchpoints AUX JTAG Internal SRAM Service Access Bus Memory Service Unit HSB Bus Matrix Memories and peripherals aWire aWire 850 32142D–06/2013 ATUC64/128/256L3/4U Figure 34-2. JTAG-based Debugger Figure 34-3. aWire-based Debugger 34.3.6.1 Debug Communication Channel The Debug Communication Channel (DCC) consists of a pair OCD registers with associated handshake logic, accessible to both CPU and debugger. The registers can be used to exchange data between the CPU and the debugmaster, both runtime as well as in debug mode. 32-bit AVR JTAG-based debug tool PC JTAG 10-pin IDC 32-bit AVR aWire-based debug tool PC aWire 851 32142D–06/2013 ATUC64/128/256L3/4U The OCD system can generate an interrupt to the CPU when DCCPU is read and when DCEMU is written. This enables the user to build a custum debug protocol using only these registers. The DCCPU and DCEMU registers are available even when the security bit in the flash is active. For more information refer to the AVR32UC Technical Reference Manual. 34.3.6.2 Breakpoints One of the most fundamental debug features is the ability to halt the CPU, to examine registers and the state of the system. This is accomplished by breakpoints, of which many types are available: • Unconditional breakpoints are set by writing OCD registers by the debugger, halting the CPU immediately. • Program breakpoints halt the CPU when a specific address in the program is executed. • Data breakpoints halt the CPU when a specific memory address is read or written, allowing variables to be watched. • Software breakpoints halt the CPU when the breakpoint instruction is executed. When a breakpoint triggers, the CPU enters debug mode, and the D bit in the status register is set. This is a privileged mode with dedicated return address and return status registers. All privileged instructions are permitted. Debug mode can be entered as either OCD Mode, running instructions from the debugger, or Monitor Mode, running instructions from program memory. 34.3.6.3 OCD Mode When a breakpoint triggers, the CPU enters OCD mode, and instructions are fetched from the Debug Instruction OCD register. Each time this register is written by the debugger, the instruction is executed, allowing the debugger to execute CPU instructions directly. The debug master can e.g. read out the register file by issuing mtdr instructions to the CPU, writing each register to the Debug Communication Channel OCD registers. 34.3.6.4 Monitor Mode Since the OCD registers are directly accessible by the CPU, it is possible to build a softwarebased debugger that runs on the CPU itself. Setting the Monitor Mode bit in the Development Control register causes the CPU to enter Monitor Mode instead of OCD mode when a breakpoint triggers. Monitor Mode is similar to OCD mode, except that instructions are fetched from the debug exception vector in regular program memory, instead of issued by the debug master. 34.3.6.5 Program Counter Monitoring Normally, the CPU would need to be halted for a debugger to examine the current PC value. However, the ATUC64/128/256L3/4U also proves a Debug Program Counter OCD register, where the debugger can continuously read the current PC without affecting the CPU. This allows the debugger to generate a simple statistic of the time spent in various areas of the code, easing code optimization. 34.3.7 Memory Service Unit The Memory Service Unit (MSU) is a block dedicated to test and debug functionality. It is controlled through a dedicated set of registers addressed through the Service Access Bus. 852 32142D–06/2013 ATUC64/128/256L3/4U 34.3.7.1 Cyclic Redundancy Check (CRC) The MSU can be used to automatically calculate the CRC of a block of data in memory. The MSU will then read out each word in the specified memory block and report the CRC32-value in an MSU register. 34.3.7.2 NanoTrace The MSU additionally supports NanoTrace. This is a 32-bit AVR-specific feature, in which trace data is output to memory instead of the AUX port. This allows the trace data to be extracted by the debugger through the SAB, enabling trace features for aWire- or JTAG-based debuggers. The user must write MSU registers to configure the address and size of the memory block to be used for NanoTrace. The NanoTrace buffer can be anywhere in the physical address range, including internal and external RAM, through an EBI, if present. This area may not be used by the application running on the CPU. 34.3.8 AUX-based Debug Features Utilizing the Auxiliary (AUX) port gives access to a wide range of advanced debug features. Of prime importance are the trace features, which allow an external debugger to receive continuous information on the program execution in the CPU. Additionally, Event In and Event Out pins allow external events to be correlated with the program flow. Debug tools utilizing the AUX port should connect to the device through a Nexus-compliant Mictor-38 connector, as described in the AVR32UC Technical Reference manual. This connector includes the JTAG signals and the RESET_N pin, giving full access to the programming and debug features in the device. 853 32142D–06/2013 ATUC64/128/256L3/4U Figure 34-4. AUX+JTAG Based Debugger 34.3.8.1 Trace Operation Trace features are enabled by writing OCD registers by the debugger. The OCD extracts the trace information from the CPU, compresses this information and formats it into variable-length messages according to the Nexus standard. The messages are buffered in a 16-frame transmit queue, and are output on the AUX port one frame at a time. The trace features can be configured to be very selective, to reduce the bandwidth on the AUX port. In case the transmit queue overflows, error messages are produced to indicate loss of data. The transmit queue module can optionally be configured to halt the CPU when an overflow occurs, to prevent the loss of messages, at the expense of longer run-time for the program. 34.3.8.2 Program Trace Program trace allows the debugger to continuously monitor the program execution in the CPU. Program trace messages are generated for every branch in the program, and contains compressed information, which allows the debugger to correlate the message with the source code to identify the branch instruction and target address. 34.3.8.3 Data Trace Data trace outputs a message every time a specific location is read or written. The message contains information about the type (read/write) and size of the access, as well as the address and data of the accessed location. The ATUC64/128/256L3/4U contains two data trace chanAVR32 AUX+JTAG debu g tool JTAG AUX h ig h s p e e d M ic to r3 8 T ra ce b u ffe r P C 854 32142D–06/2013 ATUC64/128/256L3/4U nels, each of which are controlled by a pair of OCD registers which determine the range of addresses (or single address) which should produce data trace messages. 34.3.8.4 Ownership Trace Program and data trace operate on virtual addresses. In cases where an operating system runs several processes in overlapping virtual memory segments, the Ownership Trace feature can be used to identify the process switch. When the O/S activates a process, it will write the process ID number to an OCD register, which produces an Ownership Trace Message, allowing the debugger to switch context for the subsequent program and data trace messages. As the use of this feature depends on the software running on the CPU, it can also be used to extract other types of information from the system. 34.3.8.5 Watchpoint Messages The breakpoint modules normally used to generate program and data breakpoints can also be used to generate Watchpoint messages, allowing a debugger to monitor program and data events without halting the CPU. Watchpoints can be enabled independently of breakpoints, so a breakpoint module can optionally halt the CPU when the trigger condition occurs. Data trace modules can also be configured to produce watchpoint messages instead of regular data trace messages. 34.3.8.6 Event In and Event Out Pins The AUX port also contains an Event In pin (EVTI_N) and an Event Out pin (EVTO_N). EVTI_N can be used to trigger a breakpoint when an external event occurs. It can also be used to trigger specific program and data trace synchronization messages, allowing an external event to be correlated to the program flow. When the CPU enters debug mode, a Debug Status message is transmitted on the trace port. All trace messages can be timestamped when they are received by the debug tool. However, due to the latency of the transmit queue buffering, the timestamp will not be 100% accurate. To improve this, EVTO_N can toggle every time a message is inserted into the transmit queue, allowing trace messages to be timestamped precisely. EVTO_N can also toggle when a breakpoint module triggers, or when the CPU enters debug mode, for any reason. This can be used to measure precisely when the respective internal event occurs. 34.3.8.7 Software Quality Analysis (SQA) Software Quality Analysis (SQA) deals with two important issues regarding embedded software development. Code coverage involves identifying untested parts of the embedded code, to improve test procedures and thus the quality of the released software. Performance analysis allows the developer to precisely quantify the time spent in various parts of the code, allowing bottlenecks to be identified and optimized. Program trace must be used to accomplish these tasks without instrumenting (altering) the code to be examined. However, traditional program trace cannot reconstruct the current PC value without correlating the trace information with the source code, which cannot be done on-the-fly. This limits program trace to a relatively short time segment, determined by the size of the trace buffer in the debug tool. The OCD system in ATUC64/128/256L3/4U extends program trace with SQA capabilities, allowing the debug tool to reconstruct the PC value on-the-fly. Code coverage and performance analysis can thus be reported for an unlimited execution sequence. 855 32142D–06/2013 ATUC64/128/256L3/4U 34.4 JTAG and Boundary-scan (JTAG) Rev: 2.2.2.4 34.4.1 Features • IEEE1149.1 compliant JTAG Interface • Boundary-scan Chain for board-level testing • Direct memory access and programming capabilities through JTAG Interface 34.4.2 Overview The JTAG Interface offers a four pin programming and debug solution, including boundary-scan support for board-level testing. Figure 34-5 on page 856 shows how the JTAG is connected in an 32-bit AVR device. The TAP Controller is a state machine controlled by the TCK and TMS signals. The TAP Controller selects either the JTAG Instruction Register or one of several Data Registers as the scan chain (shift register) between the TDI-input and TDO-output. The Instruction Register holds JTAG instructions controlling the behavior of a Data Register. The Device Identification Register, Bypass Register, and the boundary-scan chain are the Data Registers used for board-level testing. The Reset Register can be used to keep the device reset during test or programming. The Service Access Bus (SAB) interface contains address and data registers for the Service Access Bus, which gives access to On-Chip Debug, programming, and other functions in the device. The SAB offers several modes of access to the address and data registers, as described in Section 34.4.11. Section 34.5 lists the supported JTAG instructions, with references to the description in this document. 856 32142D–06/2013 ATUC64/128/256L3/4U 34.4.3 Block Diagram Figure 34-5. JTAG and Boundary-scan Access 34.4.4 I/O Lines Description 34.4.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. Table 34-7. I/O Line Description Pin Name Pin Description Type Active Level RESET_N External reset pin. Used when enabling and disabling the JTAG. Input Low TCK Test Clock Input. Fully asynchronous to system clock frequency. Input TMS Test Mode Select, sampled on rising TCK. Input TDI Test Data In, sampled on rising TCK. Input TDO Test Data Out, driven on falling TCK. Output 32-bit AVR device JTAG data registers TAP Controller Instruction Register Device Identification Register By-pass Register Reset Register Service Access Bus interface Boundary Scan Chain Pins and analog blocks Data register scan enable JTAG Pins Boundary scan enable 2nd JTAG device JTAG master TDO TDI Part specific registers ... TMS TDO TDI TMS TCK TCK Instruction register scan enable SAB Internal I/O lines JTAG TMS TDI TDO TCK 857 32142D–06/2013 ATUC64/128/256L3/4U 34.4.5.1 I/O Lines The TMS, TDI, TDO, and TCK pins are multiplexed with I/O lines. When the JTAG is used the associated pins must be enabled. To enable the JTAG pins, refer to Section 34.4.7. While using the multiplexed JTAG lines all normal peripheral activity on these lines is disabled. The user must make sure that no external peripheral is blocking the JTAG lines while debugging. 34.4.5.2 Power Management When an instruction that accesses the SAB is loaded in the instruction register, before entering a sleep mode, the system clocks are not switched off to allow debugging in sleep modes. This can lead to a program behaving differently when debugging. 34.4.5.3 Clocks The JTAG Interface uses the external TCK pin as clock source. This clock must be provided by the JTAG master. Instructions that use the SAB bus requires the internal main clock to be running. 34.4.6 JTAG Interface The JTAG Interface is accessed through the dedicated JTAG pins shown in Table 34-7 on page 856. The TMS control line navigates the TAP controller, as shown in Figure 34-6 on page 858. The TAP controller manages the serial access to the JTAG Instruction and Data registers. Data is scanned into the selected instruction or data register on TDI, and out of the register on TDO, in the Shift-IR and Shift-DR states, respectively. The LSB is shifted in and out first. TDO is highZ in other states than Shift-IR and Shift-DR. The device implements a 5-bit Instruction Register (IR). A number of public JTAG instructions defined by the JTAG standard are supported, as described in Section 34.5.2, as well as a number of 32-bit AVR-specific private JTAG instructions described in Section 34.5.3. Each instruction selects a specific data register for the Shift-DR path, as described for each instruction. 858 32142D–06/2013 ATUC64/128/256L3/4U Figure 34-6. TAP Controller State Diagram Test-LogicReset Run-Test/ Idle Select-DR Scan Select-IR Scan Capture-DR Capture-IR Shift-DR Shift-IR Exit1-DR Exit1-IR Pause-DR Pause-IR Exit2-DR Exit2-IR Update-DR Update-IR 0 1 1 1 0 0 1 0 1 1 0 0 1 0 1 1 1 0 1 1 0 0 1 1 0 1 0 0 0 0 0 1 859 32142D–06/2013 ATUC64/128/256L3/4U 34.4.7 How to Initialize the Module To enable the JTAG pins the TCK pin must be held low while the RESET_N pin is released. After enabling the JTAG interface the halt bit is set automatically to prevent the system from running code after the interface is enabled. To make the CPU run again set halt to zero using the HALT command.. JTAG operation when RESET_N is pulled low is not possible. Independent of the initial state of the TAP Controller, the Test-Logic-Reset state can always be entered by holding TMS high for 5 TCK clock periods. This sequence should always be applied at the start of a JTAG session and after enabling the JTAG pins to bring the TAP Controller into a defined state before applying JTAG commands. Applying a 0 on TMS for 1 TCK period brings the TAP Controller to the Run-Test/Idle state, which is the starting point for JTAG operations. 34.4.8 How to disable the module To disable the JTAG pins the TCK pin must be held high while RESET_N pin is released. 34.4.9 Typical Sequence Assuming Run-Test/Idle is the present state, a typical scenario for using the JTAG Interface follows. 34.4.9.1 Scanning in JTAG Instruction At the TMS input, apply the sequence 1, 1, 0, 0 at the rising edges of TCK to enter the Shift Instruction Register (Shift-IR) state. While in this state, shift the 5 bits of the JTAG instructions into the JTAG instruction register from the TDI input at the rising edge of TCK. During shifting, the JTAG outputs status bits on TDO, refer to Section 34.5 for a description of these. The TMS input must be held low during input of the 4 LSBs in order to remain in the Shift-IR state. The JTAG Instruction selects a particular Data Register as path between TDI and TDO and controls the circuitry surrounding the selected Data Register. Apply the TMS sequence 1, 1, 0 to re-enter the Run-Test/Idle state. The instruction is latched onto the parallel output from the shift register path in the Update-IR state. The Exit-IR, Pause-IR, and Exit2-IR states are only used for navigating the state machine. Figure 34-7. Scanning in JTAG Instruction 34.4.9.2 Scanning in/out Data At the TMS input, apply the sequence 1, 0, 0 at the rising edges of TCK to enter the Shift Data Register (Shift-DR) state. While in this state, upload the selected Data Register (selected by the present JTAG instruction in the JTAG Instruction Register) from the TDI input at the rising edge TCK TAP State TLR RTI SelDR SelIR CapIR ShIR Ex1IR UpdIR RTI TMS TDI Instruction TDO ImplDefined 860 32142D–06/2013 ATUC64/128/256L3/4U of TCK. In order to remain in the Shift-DR state, the TMS input must be held low. While the Data Register is shifted in from the TDI pin, the parallel inputs to the Data Register captured in the Capture-DR state is shifted out on the TDO pin. Apply the TMS sequence 1, 1, 0 to re-enter the Run-Test/Idle state. If the selected Data Register has a latched parallel-output, the latching takes place in the Update-DR state. The Exit-DR, Pause-DR, and Exit2-DR states are only used for navigating the state machine. As shown in the state diagram, the Run-Test/Idle state need not be entered between selecting JTAG instruction and using Data Registers. 34.4.10 Boundary-scan The boundary-scan chain has the capability of driving and observing the logic levels on the digital I/O pins, as well as the boundary between digital and analog logic for analog circuitry having off-chip connections. At system level, all ICs having JTAG capabilities are connected serially by the TDI/TDO signals to form a long shift register. An external controller sets up the devices to drive values at their output pins, and observe the input values received from other devices. The controller compares the received data with the expected result. In this way, boundary-scan provides a mechanism for testing interconnections and integrity of components on Printed Circuits Boards by using the 4 TAP signals only. The four IEEE 1149.1 defined mandatory JTAG instructions IDCODE, BYPASS, SAMPLE/PRELOAD, and EXTEST can be used for testing the Printed Circuit Board. Initial scanning of the data register path will show the ID-code of the device, since IDCODE is the default JTAG instruction. It may be desirable to have the 32-bit AVR device in reset during test mode. If not reset, inputs to the device may be determined by the scan operations, and the internal software may be in an undetermined state when exiting the test mode. If needed, the BYPASS instruction can be issued to make the shortest possible scan chain through the device. The device can be set in the reset state either by pulling the external RESETn pin low, or issuing the AVR_RESET instruction with appropriate setting of the Reset Data Register. The EXTEST instruction is used for sampling external pins and loading output pins with data. The data from the output latch will be driven out on the pins as soon as the EXTEST instruction is loaded into the JTAG IR-register. Therefore, the SAMPLE/PRELOAD should also be used for setting initial values to the scan ring, to avoid damaging the board when issuing the EXTEST instruction for the first time. SAMPLE/PRELOAD can also be used for taking a snapshot of the external pins during normal operation of the part. When using the JTAG Interface for boundary-scan, the JTAG TCK clock is independent of the internal chip clock. The internal chip clock is not required to run during boundary-scan operations. NOTE: For pins connected to 5V lines care should be taken to not drive the pins to a logic one using boundary-scan, as this will create a current flowing from the 3,3V driver to the 5V pull-up on the line. Optionally a series resistor can be added between the line and the pin to reduce the current. Details about the boundary-scan chain can be found in the BSDL file for the device. This can be found on the Atmel website. 34.4.11 Service Access Bus The AVR32 architecture offers a common interface for access to On-Chip Debug, programming, and test functions. These are mapped on a common bus called the Service Access Bus (SAB), 861 32142D–06/2013 ATUC64/128/256L3/4U which is linked to the JTAG through a bus master module, which also handles synchronization between the TCK and SAB clocks. For more information about the SAB and a list of SAB slaves see the Service Access Bus chapter. 34.4.11.1 SAB Address Mode The MEMORY_SIZED_ACCESS instruction allows a sized read or write to any 36-bit address on the bus. MEMORY_WORD_ACCESS is a shorthand instruction for 32-bit accesses to any 36-bit address, while the NEXUS_ACCESS instruction is a Nexus-compliant shorthand instruction for accessing the 32-bit OCD registers in the 7-bit address space reserved for these. These instructions require two passes through the Shift-DR TAP state: one for the address and control information, and one for data. 34.4.11.2 Block Transfer To increase the transfer rate, consecutive memory accesses can be accomplished by the MEMORY_BLOCK_ACCESS instruction, which only requires a single pass through Shift-DR for data transfer only. The address is automatically incremented according to the size of the last SAB transfer. 34.4.11.3 Canceling a SAB Access It is possible to abort an ongoing SAB access by the CANCEL_ACCESS instruction, to avoid hanging the bus due to an extremely slow slave. 34.4.11.4 Busy Reporting As the time taken to perform an access may vary depending on system activity and current chip frequency, all the SAB access JTAG instructions can return a busy indicator. This indicates whether a delay needs to be inserted, or an operation needs to be repeated in order to be successful. If a new access is requested while the SAB is busy, the request is ignored. The SAB becomes busy when: • Entering Update-DR in the address phase of any read operation, e.g., after scanning in a NEXUS_ACCESS address with the read bit set. • Entering Update-DR in the data phase of any write operation, e.g., after scanning in data for a NEXUS_ACCESS write. • Entering Update-DR during a MEMORY_BLOCK_ACCESS. • Entering Update-DR after scanning in a counter value for SYNC. • Entering Update-IR after scanning in a MEMORY_BLOCK_ACCESS if the previous access was a read and data was scanned after scanning the address. The SAB becomes ready again when: • A read or write operation completes. • A SYNC countdown completed. • A operation is cancelled by the CANCEL_ACCESS instruction. What to do if the busy bit is set: • During Shift-IR: The new instruction is selected, but the previous operation has not yet completed and will continue (unless the new instruction is CANCEL_ACCESS). You may 862 32142D–06/2013 ATUC64/128/256L3/4U continue shifting the same instruction until the busy bit clears, or start shifting data. If shifting data, you must be prepared that the data shift may also report busy. • During Shift-DR of an address: The new address is ignored. The SAB stays in address mode, so no data must be shifted. Repeat the address until the busy bit clears. • During Shift-DR of read data: The read data is invalid. The SAB stays in data mode. Repeat scanning until the busy bit clears. • During Shift-DR of write data: The write data is ignored. The SAB stays in data mode. Repeat scanning until the busy bit clears. 34.4.11.5 Error Reporting The Service Access Bus may not be able to complete all accesses as requested. This may be because the address is invalid, the addressed area is read-only or cannot handle byte/halfword accesses, or because the chip is set in a protected mode where only limited accesses are allowed. The error bit is updated when an access completes, and is cleared when a new access starts. What to do if the error bit is set: • During Shift-IR: The new instruction is selected. The last operation performed using the old instruction did not complete successfully. • During Shift-DR of an address: The previous operation failed. The new address is accepted. If the read bit is set, a read operation is started. • During Shift-DR of read data: The read operation failed, and the read data is invalid. • During Shift-DR of write data: The previous write operation failed. The new data is accepted and a write operation started. This should only occur during block writes or stream writes. No error can occur between scanning a write address and the following write data. • While polling with CANCEL_ACCESS: The previous access was cancelled. It may or may not have actually completed. • After power-up: The error bit is set after power up, but there has been no previous SAB instruction so this error can be discarded. 34.4.11.6 Protected Reporting A protected status may be reported during Shift-IR or Shift-DR. This indicates that the security bit in the Flash Controller is set and that the chip is locked for access, according to Section 34.5.1. The protected state is reported when: • The Flash Controller is under reset. This can be due to the AVR_RESET command or the RESET_N line. • The Flash Controller has not read the security bit from the flash yet (This will take a a few ms). Happens after the Flash Controller reset has been released. • The security bit in the Flash Controller is set. What to do if the protected bit is set: • Release all active AVR_RESET domains, if any. • Release the RESET_N line. • Wait a few ms for the security bit to clear. It can be set temporarily due to a reset. 863 32142D–06/2013 ATUC64/128/256L3/4U • Perform a CHIP_ERASE to clear the security bit. NOTE: This will erase all the contents of the non-volatile memory. 34.5 JTAG Instruction Summary The implemented JTAG instructions in the 32-bit AVR are shown in the table below. 34.5.1 Security Restrictions When the security fuse in the Flash is programmed, the following JTAG instructions are restricted: • NEXUS_ACCESS • MEMORY_WORD_ACCESS • MEMORY_BLOCK_ACCESS • MEMORY_SIZED_ACCESS For description of what memory locations remain accessible, please refer to the SAB address map. Full access to these instructions is re-enabled when the security fuse is erased by the CHIP_ERASE JTAG instruction. Table 34-8. JTAG Instruction Summary Instruction OPCODE Instruction Description 0x01 IDCODE Select the 32-bit Device Identification register as data register. 0x02 SAMPLE_PRELOAD Take a snapshot of external pin values without affecting system operation. 0x03 EXTEST Select boundary-scan chain as data register for testing circuitry external to the device. 0x04 INTEST Select boundary-scan chain for internal testing of the device. 0x06 CLAMP Bypass device through Bypass register, while driving outputs from boundaryscan register. 0x0C AVR_RESET Apply or remove a static reset to the device 0x0F CHIP_ERASE Erase the device 0x10 NEXUS_ACCESS Select the SAB Address and Data registers as data register for the TAP. The registers are accessed in Nexus mode. 0x11 MEMORY_WORD_ACCESS Select the SAB Address and Data registers as data register for the TAP. 0x12 MEMORY_BLOCK_ACCESS Select the SAB Data register as data register for the TAP. The address is auto-incremented. 0x13 CANCEL_ACCESS Cancel an ongoing Nexus or Memory access. 0x14 MEMORY_SERVICE Select the SAB Address and Data registers as data register for the TAP. The registers are accessed in Memory Service mode. 0x15 MEMORY_SIZED_ACCESS Select the SAB Address and Data registers as data register for the TAP. 0x17 SYNC Synchronization counter 0x1C HALT Halt the CPU for safe programming. 0x1F BYPASS Bypass this device through the bypass register. Others N/A Acts as BYPASS 864 32142D–06/2013 ATUC64/128/256L3/4U Note that the security bit will read as programmed and block these instructions also if the Flash Controller is statically reset. Other security mechanisms can also restrict these functions. If such mechanisms are present they are listed in the SAB address map section. 34.5.1.1 Notation Table 34-10 on page 864 shows bit patterns to be shifted in a format like "peb01". Each character corresponds to one bit, and eight bits are grouped together for readability. The least significantbit is always shifted first, and the most significant bit shifted last. The symbols used are shown in Table 34-9. In many cases, it is not required to shift all bits through the data register. Bit patterns are shown using the full width of the shift register, but the suggested or required bits are emphasized using bold text. I.e. given the pattern "aaaaaaar xxxxxxxx xxxxxxxx xxxxxxxx xx", the shift register is 34 bits, but the test or debug unit may choose to shift only 8 bits "aaaaaaar". The following describes how to interpret the fields in the instruction description tables: Table 34-9. Symbol Description Symbol Description 0 Constant low value - always reads as zero. 1 Constant high value - always reads as one. a An address bit - always scanned with the least significant bit first b A busy bit. Reads as one if the SAB was busy, or zero if it was not. See Section 34.4.11.4 for details on how the busy reporting works. d A data bit - always scanned with the least significant bit first. e An error bit. Reads as one if an error occurred, or zero if not. See Section 34.4.11.5 for details on how the error reporting works. p The chip protected bit. Some devices may be set in a protected state where access to chip internals are severely restricted. See the documentation for the specific device for details. On devices without this possibility, this bit always reads as zero. r A direction bit. Set to one to request a read, set to zero to request a write. s A size bit. The size encoding is described where used. x A don’t care bit. Any value can be shifted in, and output data should be ignored. Table 34-10. Instruction Description Instruction Description IR input value Shows the bit pattern to shift into IR in the Shift-IR state in order to select this instruction. The pattern is show both in binary and in hexadecimal form for convenience. Example: 10000 (0x10) IR output value Shows the bit pattern shifted out of IR in the Shift-IR state when this instruction is active. Example: peb01 865 32142D–06/2013 ATUC64/128/256L3/4U 34.5.2 Public JTAG Instructions The JTAG standard defines a number of public JTAG instructions. These instructions are described in the sections below. 34.5.2.1 IDCODE This instruction selects the 32 bit Device Identification register (DID) as Data Register. The DID register consists of a version number, a device number, and the manufacturer code chosen by JEDEC. This is the default instruction after a JTAG reset. Details about the DID register can be found in the module configuration section at the end of this chapter. Starting in Run-Test/Idle, the Device Identification register is accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Capture-DR: The IDCODE value is latched into the shift register. 7. In Shift-DR: The IDCODE scan chain is shifted by the TCK input. 8. Return to Run-Test/Idle. 34.5.2.2 SAMPLE_PRELOAD This instruction takes a snap-shot of the input/output pins without affecting the system operation, and pre-loading the scan chain without updating the DR-latch. The boundary-scan chain is selected as Data Register. Starting in Run-Test/Idle, the Device Identification register is accessed in the following way: DR Size Shows the number of bits in the data register chain when this instruction is active. Example: 34 bits DR input value Shows which bit pattern to shift into the data register in the Shift-DR state when this instruction is active. Multiple such lines may exist, e.g., to distinguish between reads and writes. Example: aaaaaaar xxxxxxxx xxxxxxxx xxxxxxxx xx DR output value Shows the bit pattern shifted out of the data register in the Shift-DR state when this instruction is active. Multiple such lines may exist, e.g., to distinguish between reads and writes. Example: xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb Table 34-10. Instruction Description (Continued) Instruction Description Table 34-11. IDCODE Details Instructions Details IR input value 00001 (0x01) IR output value p0001 DR Size 32 DR input value xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx DR output value Device Identification Register 866 32142D–06/2013 ATUC64/128/256L3/4U 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Capture-DR: The Data on the external pins are sampled into the boundary-scan chain. 7. In Shift-DR: The boundary-scan chain is shifted by the TCK input. 8. Return to Run-Test/Idle. 34.5.2.3 EXTEST This instruction selects the boundary-scan chain as Data Register for testing circuitry external to the 32-bit AVR package. The contents of the latched outputs of the boundary-scan chain is driven out as soon as the JTAG IR-register is loaded with the EXTEST instruction. Starting in Run-Test/Idle, the EXTEST instruction is accessed the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. In Update-IR: The data from the boundary-scan chain is applied to the output pins. 5. Return to Run-Test/Idle. 6. Select the DR Scan path. 7. In Capture-DR: The data on the external pins is sampled into the boundary-scan chain. 8. In Shift-DR: The boundary-scan chain is shifted by the TCK input. 9. In Update-DR: The data from the scan chain is applied to the output pins. 10. Return to Run-Test/Idle. Table 34-12. SAMPLE_PRELOAD Details Instructions Details IR input value 00010 (0x02) IR output value p0001 DR Size Depending on boundary-scan chain, see BSDL-file. DR input value Depending on boundary-scan chain, see BSDL-file. DR output value Depending on boundary-scan chain, see BSDL-file. Table 34-13. EXTEST Details Instructions Details IR input value 00011 (0x03) IR output value p0001 DR Size Depending on boundary-scan chain, see BSDL-file. DR input value Depending on boundary-scan chain, see BSDL-file. DR output value Depending on boundary-scan chain, see BSDL-file. 867 32142D–06/2013 ATUC64/128/256L3/4U 34.5.2.4 INTEST This instruction selects the boundary-scan chain as Data Register for testing internal logic in the device. The logic inputs are determined by the boundary-scan chain, and the logic outputs are captured by the boundary-scan chain. The device output pins are driven from the boundary-scan chain. Starting in Run-Test/Idle, the INTEST instruction is accessed the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. In Update-IR: The data from the boundary-scan chain is applied to the internal logic inputs. 5. Return to Run-Test/Idle. 6. Select the DR Scan path. 7. In Capture-DR: The data on the internal logic is sampled into the boundary-scan chain. 8. In Shift-DR: The boundary-scan chain is shifted by the TCK input. 9. In Update-DR: The data from the boundary-scan chain is applied to internal logic inputs. 10. Return to Run-Test/Idle. 34.5.2.5 CLAMP This instruction selects the Bypass register as Data Register. The device output pins are driven from the boundary-scan chain. Starting in Run-Test/Idle, the CLAMP instruction is accessed the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. In Update-IR: The data from the boundary-scan chain is applied to the output pins. 5. Return to Run-Test/Idle. 6. Select the DR Scan path. 7. In Capture-DR: A logic ‘0’ is loaded into the Bypass Register. 8. In Shift-DR: Data is scanned from TDI to TDO through the Bypass register. Table 34-14. INTEST Details Instructions Details IR input value 00100 (0x04) IR output value p0001 DR Size Depending on boundary-scan chain, see BSDL-file. DR input value Depending on boundary-scan chain, see BSDL-file. DR output value Depending on boundary-scan chain, see BSDL-file. 868 32142D–06/2013 ATUC64/128/256L3/4U 9. Return to Run-Test/Idle. 34.5.2.6 BYPASS This instruction selects the 1-bit Bypass Register as Data Register. Starting in Run-Test/Idle, the CLAMP instruction is accessed the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Capture-DR: A logic ‘0’ is loaded into the Bypass Register. 7. In Shift-DR: Data is scanned from TDI to TDO through the Bypass register. 8. Return to Run-Test/Idle. 34.5.3 Private JTAG Instructions The 32-bit AVR defines a number of private JTAG instructions, not defined by the JTAG standard. Each instruction is briefly described in text, with details following in table form. 34.5.3.1 NEXUS_ACCESS This instruction allows Nexus-compliant access to the On-Chip Debug registers through the SAB. The 7-bit register index, a read/write control bit, and the 32-bit data is accessed through the JTAG port. The data register is alternately interpreted by the SAB as an address register and a data register. The SAB starts in address mode after the NEXUS_ACCESS instruction is selected, and toggles between address and data mode each time a data scan completes with the busy bit cleared. NOTE: The polarity of the direction bit is inverse of the Nexus standard. Table 34-15. CLAMP Details Instructions Details IR input value 00110 (0x06) IR output value p0001 DR Size 1 DR input value x DR output value x Table 34-16. BYPASS Details Instructions Details IR input value 11111 (0x1F) IR output value p0001 DR Size 1 DR input value x DR output value x 869 32142D–06/2013 ATUC64/128/256L3/4U Starting in Run-Test/Idle, OCD registers are accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the direction bit (1=read, 0=write) and the 7-bit address for the OCD register. 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: For a read operation, scan out the contents of the addressed register. For a write operation, scan in the new contents of the register. 9. Return to Run-Test/Idle. For any operation, the full 7 bits of the address must be provided. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. 34.5.3.2 MEMORY_SERVICE This instruction allows access to registers in an optional Memory Service Unit. The 7-bit register index, a read/write control bit, and the 32-bit data is accessed through the JTAG port. The data register is alternately interpreted by the SAB as an address register and a data register. The SAB starts in address mode after the MEMORY_SERVICE instruction is selected, and toggles between address and data mode each time a data scan completes with the busy bit cleared. Starting in Run-Test/Idle, Memory Service registers are accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the direction bit (1=read, 0=write) and the 7-bit address for the Memory Service register. Table 34-17. NEXUS_ACCESS Details Instructions Details IR input value 10000 (0x10) IR output value peb01 DR Size 34 bits DR input value (Address phase) aaaaaaar xxxxxxxx xxxxxxxx xxxxxxxx xx DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xx DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xx DR output value (Address phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb DR output value (Data read phase) eb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb 870 32142D–06/2013 ATUC64/128/256L3/4U 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: For a read operation, scan out the contents of the addressed register. For a write operation, scan in the new contents of the register. 9. Return to Run-Test/Idle. For any operation, the full 7 bits of the address must be provided. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. 34.5.3.3 MEMORY_SIZED_ACCESS This instruction allows access to the entire Service Access Bus data area. Data is accessed through a 36-bit byte index, a 2-bit size, a direction bit, and 8, 16, or 32 bits of data. Not all units mapped on the SAB bus may support all sizes of accesses, e.g., some may only support word accesses. The data register is alternately interpreted by the SAB as an address register and a data register. The SAB starts in address mode after the MEMORY_SIZED_ACCESS instruction is selected, and toggles between address and data mode each time a data scan completes with the busy bit cleared. Table 34-18. MEMORY_SERVICE Details Instructions Details IR input value 10100 (0x14) IR output value peb01 DR Size 34 bits DR input value (Address phase) aaaaaaar xxxxxxxx xxxxxxxx xxxxxxxx xx DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xx DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xx DR output value (Address phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb DR output value (Data read phase) eb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb 871 32142D–06/2013 ATUC64/128/256L3/4U The size field is encoded as i Table 34-19. Starting in Run-Test/Idle, SAB data is accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the direction bit (1=read, 0=write), 2-bit access size, and the 36-bit address of the data to access. 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: For a read operation, scan out the contents of the addressed area. For a write operation, scan in the new contents of the area. 9. Return to Run-Test/Idle. For any operation, the full 36 bits of the address must be provided. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. Table 34-19. Size Field Semantics Size field value Access size Data alignment 00 Byte (8 bits) Address modulo 4 : data alignment 0: dddddddd xxxxxxxx xxxxxxxx xxxxxxxx 1: xxxxxxxx dddddddd xxxxxxxx xxxxxxxx 2: xxxxxxxx xxxxxxxx dddddddd xxxxxxxx 3: xxxxxxxx xxxxxxxx xxxxxxxx dddddddd 01 Halfword (16 bits) Address modulo 4 : data alignment 0: dddddddd dddddddd xxxxxxxx xxxxxxxx 1: Not allowed 2: xxxxxxxx xxxxxxxx dddddddd dddddddd 3: Not allowed 10 Word (32 bits) Address modulo 4 : data alignment 0: dddddddd dddddddd dddddddd dddddddd 1: Not allowed 2: Not allowed 3: Not allowed 11 Reserved N/A Table 34-20. MEMORY_SIZED_ACCESS Details Instructions Details IR input value 10101 (0x15) IR output value peb01 DR Size 39 bits DR input value (Address phase) aaaaaaaa aaaaaaaa aaaaaaaa aaaaaaaa aaaassr DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxx DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xxxxxxx 872 32142D–06/2013 ATUC64/128/256L3/4U 34.5.3.4 MEMORY_WORD_ACCESS This instruction allows access to the entire Service Access Bus data area. Data is accessed through the 34 MSB of the SAB address, a direction bit, and 32 bits of data. This instruction is identical to MEMORY_SIZED_ACCESS except that it always does word sized accesses. The size field is implied, and the two lowest address bits are removed and not scanned in. Note: This instruction was previously known as MEMORY_ACCESS, and is provided for backwards compatibility. The data register is alternately interpreted by the SAB as an address register and a data register. The SAB starts in address mode after the MEMORY_WORD_ACCESS instruction is selected, and toggles between address and data mode each time a data scan completes with the busy bit cleared. Starting in Run-Test/Idle, SAB data is accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the direction bit (1=read, 0=write) and the 34-bit address of the data to access. 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: For a read operation, scan out the contents of the addressed area. For a write operation, scan in the new contents of the area. 9. Return to Run-Test/Idle. For any operation, the full 34 bits of the address must be provided. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. DR output value (Address phase) xxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb DR output value (Data read phase) xxxxxeb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb Table 34-20. MEMORY_SIZED_ACCESS Details (Continued) Instructions Details Table 34-21. MEMORY_WORD_ACCESS Details Instructions Details IR input value 10001 (0x11) IR output value peb01 DR Size 35 bits DR input value (Address phase) aaaaaaaa aaaaaaaa aaaaaaaa aaaaaaaa aar DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxx DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xxx 873 32142D–06/2013 ATUC64/128/256L3/4U 34.5.3.5 MEMORY_BLOCK_ACCESS This instruction allows access to the entire SAB data area. Up to 32 bits of data is accessed at a time, while the address is sequentially incremented from the previously used address. In this mode, the SAB address, size, and access direction is not provided with each access. Instead, the previous address is auto-incremented depending on the specified size and the previous operation repeated. The address must be set up in advance with MEMORY_SIZE_ACCESS or MEMORY_WORD_ACCESS. It is allowed, but not required, to shift data after shifting the address. This instruction is primarily intended to speed up large quantities of sequential word accesses. It is possible to use it also for byte and halfword accesses, but the overhead in this is case much larger as 32 bits must still be shifted for each access. The following sequence should be used: 1. Use the MEMORY_SIZE_ACCESS or MEMORY_WORD_ACCESS to read or write the first location. 2. Return to Run-Test/Idle. 3. Select the IR Scan path. 4. In Capture-IR: The IR output value is latched into the shift register. 5. In Shift-IR: The instruction register is shifted by the TCK input. 6. Return to Run-Test/Idle. 7. Select the DR Scan path. The address will now have incremented by 1, 2, or 4 (corresponding to the next byte, halfword, or word location). 8. In Shift-DR: For a read operation, scan out the contents of the next addressed location. For a write operation, scan in the new contents of the next addressed location. 9. Go to Update-DR. 10. If the block access is not complete, return to Select-DR Scan and repeat the access. 11. If the block access is complete, return to Run-Test/Idle. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. DR output value (Address phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xeb DR output value (Data read phase) xeb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb Table 34-21. MEMORY_WORD_ACCESS Details (Continued) Instructions Details Table 34-22. MEMORY_BLOCK_ACCESS Details Instructions Details IR input value 10010 (0x12) IR output value peb01 DR Size 34 bits DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xx 874 32142D–06/2013 ATUC64/128/256L3/4U The overhead using block word access is 4 cycles per 32 bits of data, resulting in an 88% transfer efficiency, or 2.1 MBytes per second with a 20 MHz TCK frequency. 34.5.3.6 CANCEL_ACCESS If a very slow memory location is accessed during a SAB memory access, it could take a very long time until the busy bit is cleared, and the SAB becomes ready for the next operation. The CANCEL_ACCESS instruction provides a possibility to abort an ongoing transfer and report a timeout to the JTAG master. When the CANCEL_ACCESS instruction is selected, the current access will be terminated as soon as possible. There are no guarantees about how long this will take, as the hardware may not always be able to cancel the access immediately. The SAB is ready to respond to a new command when the busy bit clears. Starting in Run-Test/Idle, CANCEL_ACCESS is accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 34.5.3.7 SYNC This instruction allows external debuggers and testers to measure the ratio between the external JTAG clock and the internal system clock. The SYNC data register is a 16-bit counter that counts down to zero using the internal system clock. The busy bit stays high until the counter reaches zero. Starting in Run-Test/Idle, SYNC instruction is used in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xx DR output value (Data read phase) eb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb Table 34-22. MEMORY_BLOCK_ACCESS Details (Continued) Instructions Details Table 34-23. CANCEL_ACCESS Details Instructions Details IR input value 10011 (0x13) IR output value peb01 DR Size 1 DR input value x DR output value 0 875 32142D–06/2013 ATUC64/128/256L3/4U 6. Scan in an 16-bit counter value. 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: Scan out the busy bit, and until the busy bit clears goto 7. 9. Calculate an approximation to the internal clock speed using the elapsed time and the counter value. 10. Return to Run-Test/Idle. The full 16-bit counter value must be provided when starting the synch operation, or the result will be undefined. When reading status, shifting may be terminated once the required number of bits have been acquired. 34.5.3.8 AVR_RESET This instruction allows a debugger or tester to directly control separate reset domains inside the chip. The shift register contains one bit for each controllable reset domain. Setting a bit to one resets that domain and holds it in reset. Setting a bit to zero releases the reset for that domain. The AVR_RESET instruction can be used in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the value corresponding to the reset domains the JTAG master wants to reset into the data register. 7. Return to Run-Test/Idle. 8. Stay in run test idle for at least 10 TCK clock cycles to let the reset propagate to the system. See the device specific documentation for the number of reset domains, and what these domains are. For any operation, all bits must be provided or the result will be undefined. Table 34-24. SYNC_ACCESS Details Instructions Details IR input value 10111 (0x17) IR output value peb01 DR Size 16 bits DR input value dddddddd dddddddd DR output value xxxxxxxx xxxxxxeb Table 34-25. AVR_RESET Details Instructions Details IR input value 01100 (0x0C) IR output value p0001 876 32142D–06/2013 ATUC64/128/256L3/4U 34.5.3.9 CHIP_ERASE This instruction allows a programmer to completely erase all nonvolatile memories in a chip. This will also clear any security bits that are set, so the device can be accessed normally. In devices without non-volatile memories this instruction does nothing, and appears to complete immediately. The erasing of non-volatile memories starts as soon as the CHIP_ERASE instruction is selected. The CHIP_ERASE instruction selects a 1 bit bypass data register. A chip erase operation should be performed as: 1. Reset the system and stop the CPU from executing. 2. Select the IR Scan path. 3. In Capture-IR: The IR output value is latched into the shift register. 4. In Shift-IR: The instruction register is shifted by the TCK input. 5. Check the busy bit that was scanned out during Shift-IR. If the busy bit was set goto 2. 6. Return to Run-Test/Idle. 34.5.3.10 HALT This instruction allows a programmer to easily stop the CPU to ensure that it does not execute invalid code during programming. This instruction selects a 1-bit halt register. Setting this bit to one halts the CPU. Setting this bit to zero releases the CPU to run normally. The value shifted out from the data register is one if the CPU is halted. Before releasing the halt command the CPU needs to be reset to ensure that it will start at the reset startup address. The HALT instruction can be used in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. DR Size Device specific. DR input value Device specific. DR output value Device specific. Table 34-25. AVR_RESET Details (Continued) Instructions Details Table 34-26. CHIP_ERASE Details Instructions Details IR input value 01111 (0x0F) IR output value p0b01 Where b is the busy bit. DR Size 1 bit DR input value x DR output value 0 877 32142D–06/2013 ATUC64/128/256L3/4U 6. In Shift-DR: Scan in the value 1 to halt the CPU, 0 to start CPU execution. 7. Return to Run-Test/Idle. Table 34-27. HALT Details Instructions Details IR input value 11100 (0x1C) IR output value p0001 DR Size 1 bit DR input value d DR output value d 878 32142D–06/2013 ATUC64/128/256L3/4U 34.5.4 JTAG Data Registers The following device specific registers can be selected as JTAG scan chain depending on the instruction loaded in the JTAG Instruction Register. Additional registers exist, but are implicitly described in the functional description of the relevant instructions. 34.5.4.1 Device Identification Register The Device Identification Register contains a unique identifier for each product. The register is selected by the IDCODE instruction, which is the default instruction after a JTAG reset. Device specific ID codes The different device configurations have different JTAG ID codes, as shown in Table 34-28. Note that if the flash controller is statically reset, the ID code will be undefined. 34.5.4.2 Reset Register The reset register is selected by the AVR_RESET instruction and contains one bit for each reset domain in the device. Setting each bit to one will keep that domain reset until the bit is cleared. MSB LSB Bit 31 28 27 12 11 1 0 Device ID Revision Part Number Manufacturer ID 1 4 bits 16 bits 11 bits 1 bit Revision This is a 4 bit number identifying the revision of the component. Rev A = 0x0, B = 0x1, etc. Part Number The part number is a 16 bit code identifying the component. Manufacturer ID The Manufacturer ID is a 11 bit code identifying the manufacturer. The JTAG manufacturer ID for ATMEL is 0x01F. Table 34-28. Device and JTAG ID Device Name JTAG ID Code (R is the revision number) ATUC256L3U 0xr21C303F ATUC128L3U 0xr21C403F ATUC64L3U 0xr21C503F ATUC256L4U 0xr21C603F ATUC128L4U 0xr21C703F ATUC64L4U 0xr21C803F Bit 0 Reset domain System 879 32142D–06/2013 ATUC64/128/256L3/4U 34.5.4.3 Boundary--scan Chain The boundary-scan chain has the capability of driving and observing the logic levels on the digital I/O pins, as well as driving and observing the logic levels between the digital I/O pins and the internal logic. Typically, output value, output enable, and input data are all available in the boundary-scan chain. The boundary-scan chain is described in the BSDL (Boundary Scan Description Language) file available at the Atmel web site. System Resets the whole chip, except the JTAG itself. 880 32142D–06/2013 ATUC64/128/256L3/4U 34.6 aWire Debug Interface (AW) Rev.: 2.3.0.1 34.6.1 Features • Single pin debug system. • Half Duplex asynchronous communication (UART compatible). • Full duplex mode for direct UART connection. • Compatible with JTAG functionality, except boundary scan. • Failsafe packet-oriented protocol. • Read and write on-chip memory and program on-chip flash and fuses through SAB interface. • On-Chip Debug access through SAB interface. • Asynchronous receiver or transmitter when the aWire system is not used for debugging. 34.6.2 Overview The aWire Debug Interface (AW) offers a single pin debug solution that is fully compatible with the functionality offered by the JTAG interface, except boundary scan. This functionality includes memory access, programming capabilities, and On-Chip Debug access. Figure 34-8 on page 881 shows how the AW is connected in a 32-bit AVR device. The RESET_N pin is used both as reset and debug pin. A special sequence on RESET_N is needed to block the normal reset functionality and enable the AW. The Service Access Bus (SAB) interface contains address and data registers for the Service Access Bus, which gives access to On-Chip Debug, programming, and other functions in the device. The SAB offers several modes of access to the address and data registers, as discussed in Section 34.6.6.8. Section 34.6.7 lists the supported aWire commands and responses, with references to the description in this document. If the AW is not used for debugging, the aWire UART can be used by the user to send or receive data with one stop bit, eight data bits, no parity bits, and one stop bit. This can be controlled through the aWire user interface. 881 32142D–06/2013 ATUC64/128/256L3/4U 34.6.3 Block Diagram Figure 34-8. aWire Debug Interface Block Diagram 34.6.4 I/O Lines Description 34.6.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. Table 34-29. I/O Lines Description Name Description Type DATA aWire data multiplexed with the RESET_N pin. Input/Output DATAOUT aWire data output in 2-pin mode. Output UART Reset filter External reset AW_ENABLE RESET_N Baudrate Detector RW SZ ADDR DATA CRC AW CONTROL AW User Interface SAB interface RESET command Power Manager HALT command CPU Flash Controller CHIP_ERASE command aWire Debug Interface PB SAB 882 32142D–06/2013 ATUC64/128/256L3/4U 34.6.5.1 I/O Lines The pin used by AW is multiplexed with the RESET_N pin. The reset functionality is the default function of this pin. To enable the aWire functionality on the RESET_N pin the user must enable the AW either by sending the enable sequence over the RESET_N pin from an external aWire master or by enabling the aWire user interface. In 2-pin mode data is received on the RESET_N line, but transmitted on the DATAOUT line. After sending the 2_PIN_MODE command the DATAOUT line is automatically enabled. All other peripheral functions on this pin is disabled. 34.6.5.2 Power Management When debugging through AW the system clocks are automatically turned on to allow debugging in sleep modes. 34.6.5.3 Clocks The aWire UART uses the internal 120 MHz RC oscillator (RC120M) as clock source for its operation. When enabling the AW the RC120M is automatically started. 34.6.5.4 External Components The AW needs an external pullup on the RESET_N pin to ensure that the pin is pulled up when the bus is not driven. 34.6.6 Functional Description 34.6.6.1 aWire Communication Protocol The AW is accessed through the RESET_N pin shown in Table 34-29 on page 881. The AW communicates through a UART operating at variable baud rate (depending on a sync pattern) with one start bit, 8 data bits (LSB first), one stop bit, and no parity bits. The aWire protocol is based upon command packets from an externalmaster and response packets from the slave (AW). The master always initiates communication and decides the baud rate. The packet contains a sync byte (0x55), a command/response byte, two length bytes (optional), a number of data bytes as defined in the length field (optional), and two CRC bytes. If the command/response has the most significant bit set, the command/response also carries the optional length and data fields. The CRC field is not checked if the CRC value transmitted is 0x0000. Table 34-30. aWire Packet Format Field Number of bytes Description Comment Optional SYNC 1 Sync pattern (0x55). Used by the receiver to set the baud rate clock. No COMMAND/ RESPONSE 1 Command from the master or response from the slave. When the most significant bit is set the command/response has a length field. A response has the next most significant bit set. A command does not have this bit set. No 883 32142D–06/2013 ATUC64/128/256L3/4U CRC calculation The CRC is calculated from the command/response, length, and data fields. The polynomial used is the FCS16 (or CRC-16-CCIT) in reverse mode (0x8408) and the starting value is 0x0000. Example command Below is an example command from the master with additional data. Figure 34-9. Example Command Example response Below is an example response from the slave with additional data. Figure 34-10. Example Response LENGTH 2 The number of bytes in the DATA field. Yes DATA LENGTH Data according to command/ response. Yes CRC 2 CRC calculated with the FCS16 polynomial. CRC value of 0x0000 makes the aWire disregard the CRC if the master does not support it. No Table 34-30. aWire Packet Format Field Number of bytes Description Comment Optional baud_rate_clk data_pin ... field sync(0x55) command(0x81) length(MSB) length(lsb) ... data(MSB) data(LSB) CRC(MSB) CRC(lsb) baud_rate_clk data_pin ... field sync(0x55) response(0xC1) length(MSB) length(lsb) ... data(MSB) data(LSB) CRC(MSB) CRC(lsb) 884 32142D–06/2013 ATUC64/128/256L3/4U Avoiding drive contention when changing direction The aWire debug protocol uses one dataline in both directions. To avoid both the master and the slave to drive this line when changing direction the AW has a built in guard time before it starts to drive the line. At reset this guard time is set to maximum (128 bit cycles), but can be lowered by the master upon command. The AW will release the line immediately after the stop character has been transmitted. During the direction change there can be a period when the line is not driven. An external pullup has to be added to RESET_N to keep the signal stable when neither master or slave is actively driving the line. 34.6.6.2 The RESET_N pin Normal reset functionality on the RESET_N pin is disabled when using aWire. However, the user can reset the system through the RESET aWire command. During aWire operation the RESET_N pin should not be connected to an external reset circuitry, but disconnected via a switch or a jumper to avoid drive contention and speed problems. Figure 34-11. Reset Circuitry and aWire. 34.6.6.3 Initializing the AW To enable AW, the user has to send a 0x55 pattern with a baudrate of 1 kHz on the RESET_N pin. The AW is enabled after transmitting this pattern and the user can start transmitting commands. This pattern is not the sync pattern for the first command. After enabling the aWire debug interface the halt bit is set automatically to prevent the system from running code after the interface is enabled. To make the CPU run again set halt to zero using the HALT command. 34.6.6.4 Disabling the AW To disable AW, the user can keep the RESET_N pin low for 100 ms. This will disable the AW, return RESET_N to its normal function, and reset the device. An aWire master can also disable aWire by sending the DISABLE command. After acking the command the AW will be disabled and RESET_N returns to its normal function. RESET_N AW Debug Interface Jumper MCU Power Manager aWire master connector Board Reset Circuitry 885 32142D–06/2013 ATUC64/128/256L3/4U 34.6.6.5 Resetting the AW The aWire master can reset the AW slave by pulling the RESET_N pin low for 20 ms. This is equivalent to disabling and then enabling AW. 34.6.6.6 2-pin Mode To avoid using special hardware when using a normal UART device as aWire master, the aWire slave has a 2-pin mode where one pin is used as input and on pin is used as output. To enable this mode the 2_PIN_MODE command must be sent. After sending the command, all responses will be sent on the DATAOUT pin instead of the RESET_N pin. Commands are still received on the RESET_N pin. 34.6.6.7 Baud Rate Clock The communication speed is set by the master in the sync field of the command. The AW will use this to resynchronize its baud rate clock and reply on this frequency. The minimum frequency of the communication is 1 kHz. The maximum frequency depends on the internal clock source for the AW (RC120M). The baud rate clock is generated by AW with the following formula: Where is the baud rate frequency and is the frequency of the internal RC120M. TUNE is the value returned by the BAUD_RATE response. To find the max frequency the user can issue the TUNE command to the AW to make it return the TUNE value. This value can be used to compute the . The maximum operational frequency ( ) is then: 34.6.6.8 Service Access Bus The AVR32 architecture offers a common interface for access to On-Chip Debug, programming, and test functions. These are mapped on a common bus called the Service Access Bus (SAB), which is linked to the aWire through a bus master module, which also handles synchronization between the aWire and SAB clocks. For more information about the SAB and a list of SAB slaves see the Service Access Bus chapter. SAB Clock When accessing the SAB through the aWire there are no limitations on baud rate frequency compared to chip frequency, although there must be an active system clock in order for the SAB accesses to complete. If the system clock (CLK_SYS) is switched off in sleep mode, activity on the aWire pin will restart the CLK_SYS automatically, without waking the device from sleep. aWire masters may optimize the transfer rate by adjusting the baud rate frequency in relation to the CLK_SYS. This ratio can be measured with the MEMORY_SPEED_REQUEST command. When issuing the MEMORY_SPEED_REQUEST command a counter value CV is returned. CV can be used to calculate the SAB speed ( ) using this formula: f aw TUNE f  br 8 = ---------------------------- f br f aw f aw f brmax f brmax f aw 4 = ------- f sab 886 32142D–06/2013 ATUC64/128/256L3/4U SAB Address Mode The Service Access Bus uses 36 address bits to address memory or registers in any of the slaves on the bus. The bus supports sized accesses of bytes (8 bits), halfwords (16 bits), or words (32 bits). All accesses must be aligned to the size of the access, i.e. halfword accesses must have the lowest address bit cleared, and word accesses must have the two lowest address bits cleared. Two instructions exist to access the SAB: MEMORY_WRITE and MEMORY_READ. These two instructions write and read words, halfwords, and bytes from the SAB. Busy Reporting If the aWire master, during a MEMORY_WRITE or a MEMORY_READ command, transmit another byte when the aWire is still busy sending the previous byte to the SAB, the AW will respond with a MEMORY_READ_WRITE_STATUS error. See chapter Section 34.6.8.5 for more details. The aWire master should adjust its baudrate or delay between bytes when doing SAB accesses to ensure that the SAB is not overwhelmed with data. Error Reporting If a write is performed on a non-existing memory location the SAB interface will respond with an error. If this happens, all further writes in this command will not be performed and the error and number of bytes written is reported in the MEMORY_READWRITE_STATUS message from the AW after the write. If a read is performed on a non-existing memory location, the SAB interface will respond with an error. If this happens, the data bytes read after this event are not valid. The AW will include three extra bytes at the end of the transfer to indicate if the transfer was successful, or in the case of an error, how many valid bytes were received. 34.6.6.9 CRC Errors/NACK Response The AW will calculate a CRC value when receiving the command, length, and data fields of the command packets. If this value differs from the value from the CRC field of the packet, the AW will reply with a NACK response. Otherwise the command is carried out normally. An unknown command will be replied with a NACK response. In worst case a transmission error can happen in the length or command field of the packet. This can lead to the aWire slave trying to receive a command with or without length (opposite of what the master intended) or receive an incorrect number of bytes. The aWire slave will then either wait for more data when the master has finished or already have transmitted the NACK response in congestion with the master. The master can implement a timeout on every command and reset the slave if no response is returned after the timeout period has ended. f sab 3f aw CV – 3 = ---------------- 887 32142D–06/2013 ATUC64/128/256L3/4U 34.6.7 aWire Command Summary The implemented aWire commands are shown in the table below. The responses from the AW are listed in Section 34.6.8. All aWire commands are described below, with a summary in table form. 34.6.7.1 AYA This command asks the AW: “Are you alive”, where the AW should respond with an acknowledge. Table 34-31. aWire Command Summary COMMAND Instruction Description 0x01 AYA “Are you alive”. 0x02 JTAG_ID Asks AW to return the JTAG IDCODE. 0x03 STATUS_REQUEST Request a status message from the AW. 0x04 TUNE Tell the AW to report the current baud rate. 0x05 MEMORY_SPEED_REQUEST Reports the speed difference between the aWire control and the SAB clock domains. 0x06 CHIP_ERASE Erases the flash and all volatile memories. 0x07 DISABLE Disables the AW. 0x08 2_PIN_MODE Enables the DATAOUT pin and puts the aWire in 2-pin mode, where all responses are sent on the DATAOUT pin. 0x80 MEMORY_WRITE Writes words, halfwords, or bytes to the SAB. 0x81 MEMORY_READ Reads words, halfwords, or bytes from the SAB. 0x82 HALT Issues a halt command to the device. 0x83 RESET Issues a reset to the Reset Controller. 0x84 SET_GUARD_TIME Sets the guard time for the AW. Table 34-32. Command/Response Description Notation Command/Response Description Command/Response value Shows the command/response value to put into the command/response field of the packet. Additional data Shows the format of the optional data field if applicable. Possible responses Shows the possible responses for this command. Table 34-33. AYA Details Command Details Command value 0x01 Additional data N/A Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) 888 32142D–06/2013 ATUC64/128/256L3/4U 34.6.7.2 JTAG_ID This command instructs the AW to output the JTAG idcode in the following response. 34.6.7.3 STATUS_REQUEST Asks the AW for a status message. 34.6.7.4 TUNE Asks the AW for the current baud rate counter value. 34.6.7.5 MEMORY_SPEED_REQUEST Asks the AW for the relative speed between the aWire clock (RC120M) and the SAB interface. 34.6.7.6 CHIP_ERASE This instruction allows a programmer to completely erase all nonvolatile memories in the chip. This will also clear any security bits that are set, so the device can be accessed normally. The command is acked immediately, but the status of the command can be monitored by checking Table 34-34. JTAG_ID Details Command Details Command value 0x02 Additional data N/A Possible responses 0xC0: IDCODE (Section 34.6.8.3) 0x41: NACK (Section 34.6.8.2) Table 34-35. STATUS_REQUEST Details Command Details Command value 0x03 Additional data N/A Possible responses 0xC4: STATUS_INFO (Section 34.6.8.7) 0x41: NACK (Section 34.6.8.2) Table 34-36. TUNE Details Command Details Command value 0x04 Additional data N/A Possible responses 0xC3: BAUD_RATE (Section 34.6.8.6) 0x41: NACK (Section 34.6.8.2) Table 34-37. MEMORY_SPEED_REQUEST Details Command Details Command value 0x05 Additional data N/A Possible responses 0xC5: MEMORY_SPEED (Section 34.6.8.8) 0x41: NACK (Section 34.6.8.2) 889 32142D–06/2013 ATUC64/128/256L3/4U the Chip Erase ongoing bit in the status bytes received after the STATUS_REQUEST command. 34.6.7.7 DISABLE Disables the AW. The AW will respond with an ACK response and then disable itself. 34.6.7.8 2_PIN_MODE Enables the DATAOUT pin as an output pin. All responses sent from the aWire slave will be sent on this pin, instead of the RESET_N pin, starting with the ACK for the 2_PIN_MODE command. 34.6.7.9 MEMORY_WRITE This command enables programming of memory/writing to registers on the SAB. The MEMORY_WRITE command allows words, halfwords, and bytes to be programmed to a continuous sequence of addresses in one operation. Before transferring the data, the user must supply: 1. The number of data bytes to write + 5 (size and starting address) in the length field. 2. The size of the transfer: words, halfwords, or bytes. 3. The starting address of the transfer. Table 34-38. CHIP_ERASE Details Command Details Command value 0x06 Additional data N/A Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) Table 34-39. DISABLE Details Command Details Command value 0x07 Additional data N/A Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) Table 34-40. DISABLE Details Command Details Command value 0x07 Additional data N/A Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) 890 32142D–06/2013 ATUC64/128/256L3/4U The 4 MSB of the 36 bit SAB address are submitted together with the size field (2 bits). Then follows the 4 remaining address bytes and finally the data bytes. The size of the transfer is specified using the values from the following table: Below is an example write command: 1. 0x55 (sync) 2. 0x80 (command) 3. 0x00 (length MSB) 4. 0x09 (length LSB) 5. 0x25 (size and address MSB, the two MSB of this byte are unused and set to zero) 6. 0x00 7. 0x00 8. 0x00 9. 0x04 (address LSB) 10. 0xCA 11. 0xFE 12. 0xBA 13. 0xBE 14. 0xXX (CRC MSB) 15. 0xXX (CRC LSB) The length field is set to 0x0009 because there are 9 bytes of additional data: 5 address and size bytes and 4 bytes of data. The address and size field indicates that words should be written to address 0x500000004. The data written to 0x500000004 is 0xCAFEBABE. 34.6.7.10 MEMORY_READ This command enables reading of memory/registers on the Service Access Bus (SAB). The MEMORY_READ command allows words, halfwords, and bytes to be read from a continuous sequence of addresses in one operation. The user must supply: Table 34-41. Size Field Decoding Size field Description 00 Byte transfer 01 Halfword transfer 10 Word transfer 11 Reserved Table 34-42. MEMORY_WRITE Details Command Details Command value 0x80 Additional data Size, Address and Data Possible responses 0xC2: MEMORY_READWRITE_STATUS (Section 34.6.8.5) 0x41: NACK (Section 34.6.8.2) 891 32142D–06/2013 ATUC64/128/256L3/4U 1. The size of the data field: 7 (size and starting address + read length indicator) in the length field. 2. The size of the transfer: Words, halfwords, or bytes. 3. The starting address of the transfer. 4. The number of bytes to read (max 65532). The 4 MSB of the 36 bit SAB address are submitted together with the size field (2 bits). The 4 remaining address bytes are submitted before the number of bytes to read. The size of the transfer is specified using the values from the following table: Below is an example read command: 1. 0x55 (sync) 2. 0x81 (command) 3. 0x00 (length MSB) 4. 0x07 (length LSB) 5. 0x25 (size and address MSB, the two MSB of this byte are unused and set to zero) 6. 0x00 7. 0x00 8. 0x00 9. 0x04 (address LSB) 10. 0x00 11. 0x04 12. 0xXX (CRC MSB) 13. 0xXX (CRC LSB) The length field is set to 0x0007 because there are 7 bytes of additional data: 5 bytes of address and size and 2 bytes with the number of bytes to read. The address and size field indicates one word (four bytes) should be read from address 0x500000004. Table 34-43. Size Field Decoding Size field Description 00 Byte transfer 01 Halfword transfer 10 Word transfer 11 Reserved Table 34-44. MEMORY_READ Details Command Details Command value 0x81 Additional data Size, Address and Length Possible responses 0xC1: MEMDATA (Section 34.6.8.4) 0xC2: MEMORY_READWRITE_STATUS (Section 34.6.8.5) 0x41: NACK (Section 34.6.8.2) 892 32142D–06/2013 ATUC64/128/256L3/4U 34.6.7.11 HALT This command tells the CPU to halt code execution for safe programming. If the CPU is not halted during programming it can start executing partially loaded programs. To halt the processor, the aWire master should send 0x01 in the data field of the command. After programming the halting can be released by sending 0x00 in the data field of the command. 34.6.7.12 RESET This command resets different domains in the part. The aWire master sends a byte with the reset value. Each bit in the reset value byte corresponds to a reset domain in the chip. If a bit is set the reset is activated and if a bit is not set the reset is released. The number of reset domains and their destinations are identical to the resets described in the JTAG data registers chapter under reset register. 34.6.7.13 SET_GUARD_TIME Sets the guard time value in the AW, i.e. how long the AW will wait before starting its transfer after the master has finished. The guard time can be either 0x00 (128 bit lengths), 0x01 (16 bit lengths), 0x2 (4 bit lengths) or 0x3 (1 bit length). Table 34-45. HALT Details Command Details Command value 0x82 Additional data 0x01 to halt the CPU 0x00 to release the halt and reset the device. Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) Table 34-46. RESET Details Command Details Command value 0x83 Additional data Reset value for each reset domain. The number of reset domains is part specific. Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) Table 34-47. SET_GUARD_TIME Details Command Details Command value 0x84 Additional data Guard time Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) 893 32142D–06/2013 ATUC64/128/256L3/4U 34.6.8 aWire Response Summary The implemented aWire responses are shown in the table below. 34.6.8.1 ACK The AW has received the command successfully and performed the operation. 34.6.8.2 NACK The AW has received the command, but got a CRC mismatch. 34.6.8.3 IDCODE The JTAG idcode for this device. 34.6.8.4 MEMDATA The data read from the address specified by the MEMORY_READ command. The last 3 bytes are status bytes from the read. The first status byte is the status of the command described in the table below. The last 2 bytes are the number of remaining data bytes to be sent in the data field of the packet when the error occurred. If the read was not successful all data bytes after the failure are undefined. A successful word read (4 bytes) will look like this: Table 34-48. aWire Response Summary RESPONSE Instruction Description 0x40 ACK Acknowledge. 0x41 NACK Not acknowledge. Sent after CRC errors and after unknown commands. 0xC0 IDCODE The JTAG idcode. 0xC1 MEMDATA Values read from memory. 0xC2 MEMORY_READWRITE_STATUS Status after a MEMORY_WRITE or a MEMORY_READ command. OK, busy, error. 0xC3 BAUD_RATE The current baudrate. 0xC4 STATUS_INFO Status information. 0xC5 MEMORY_SPEED SAB to aWire speed information. Table 34-49. ACK Details Response Details Response value 0x40 Additional data N/A Table 34-50. NACK Details Response Details Response value 0x41 Additional data N/A Table 34-51. IDCODE Details Response Details Response value 0xC0 Additional data JTAG idcode 894 32142D–06/2013 ATUC64/128/256L3/4U 1. 0x55 (sync) 2. 0xC1 (command) 3. 0x00 (length MSB) 4. 0x07 (length LSB) 5. 0xCA (Data MSB) 6. 0xFE 7. 0xBA 8. 0xBE (Data LSB) 9. 0x00 (Status byte) 10. 0x00 (Bytes remaining MSB) 11. 0x00 (Bytes remaining LSB) 12. 0xXX (CRC MSB) 13. 0xXX (CRC LSB) The status is 0x00 and all data read are valid. An unsuccessful four byte read can look like this: 1. 0x55 (sync) 2. 0xC1 (command) 3. 0x00 (length MSB) 4. 0x07 (length LSB) 5. 0xCA (Data MSB) 6. 0xFE 7. 0xXX (An error has occurred. Data read is undefined. 5 bytes remaining of the Data field) 8. 0xXX (More undefined data) 9. 0x02 (Status byte) 10. 0x00 (Bytes remaining MSB) 11. 0x05 (Bytes remaining LSB) 12. 0xXX (CRC MSB) 13. 0xXX (CRC LSB) The error occurred after reading 2 bytes on the SAB. The rest of the bytes read are undefined. The status byte indicates the error and the bytes remaining indicates how many bytes were remaining to be sent of the data field of the packet when the error occurred. Table 34-52. MEMDATA Status Byte status byte Description 0x00 Read successful 0x01 SAB busy 0x02 Bus error (wrong address) Other Reserved Table 34-53. MEMDATA Details Response Details Response value 0xC1 Additional data Data read, status byte, and byte count (2 bytes) 895 32142D–06/2013 ATUC64/128/256L3/4U 34.6.8.5 MEMORY_READWRITE_STATUS After a MEMORY_WRITE command this response is sent by AW. The response can also be sent after a MEMORY_READ command if AW encountered an error when receiving the address. The response contains 3 bytes, where the first is the status of the command and the 2 next contains the byte count when the first error occurred. The first byte is encoded this way: 34.6.8.6 BAUD_RATE The current baud rate in the AW. See Section 34.6.6.7 for more details. 34.6.8.7 STATUS_INFO A status message from AW. Table 34-54. MEMORY_READWRITE_STATUS Status Byte status byte Description 0x00 Write successful 0x01 SAB busy 0x02 Bus error (wrong address) Other Reserved Table 34-55. MEMORY_READWRITE_STATUS Details Response Details Response value 0xC2 Additional data Status byte and byte count (2 bytes) Table 34-56. BAUD_RATE Details Response Details Response value 0xC3 Additional data Baud rate Table 34-57. STATUS_INFO Contents Bit number Name Description 15-9 Reserved 8 Protected The protection bit in the internal flash is set. SAB access is restricted. This bit will read as one during reset. 7 SAB busy The SAB bus is busy with a previous transfer. This could indicate that the CPU is running on a very slow clock, the CPU clock has stopped for some reason or that the part is in constant reset. 6 Chip erase ongoing The Chip erase operation has not finished. 5 CPU halted This bit will be set if the CPU is halted. This bit will read as zero during reset. 4-1 Reserved 0 Reset status This bit will be set if AW has reset the CPU using the RESET command. 896 32142D–06/2013 ATUC64/128/256L3/4U 34.6.8.8 MEMORY_SPEED Counts the number of RC120M clock cycles it takes to sync one message to the SAB interface and back again. The SAB clock speed ( ) can be calculated using the following formula: 34.6.9 Security Restrictions When the security fuse in the Flash is programmed, the following aWire commands are limited: • MEMORY_WRITE • MEMORY_READ Unlimited access to these instructions is restored when the security fuse is erased by the CHIP_ERASE aWire command. Note that the security bit will read as programmed and block these instructions also if the Flash Controller is statically reset. Table 34-58. STATUS_INFO Details Response Details Response value 0xC4 Additional data 2 status bytes Table 34-59. MEMORY_SPEED Details Response Details Response value 0xC5 Additional data Clock cycle count (MS) f sab f sab 3f aw CV – 3 = ---------------- 897 32142D–06/2013 ATUC64/128/256L3/4U 35. Electrical Characteristics 35.1 Absolute Maximum Ratings* Notes: 1. 5V tolerant pins, see Section ”Peripheral Multiplexing on I/O lines” on page 10 2. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. 35.2 Supply Characteristics The following characteristics are applicable to the operating temperature range: TA = -40°C to 85°C, unless otherwise specified and are valid for a junction temperature up to TJ = 100°C. Please refer to Section 6. ”Supply and Startup Considerations” on page 39. Table 35-1. Absolute Maximum Ratings Operating temperature..................................... -40C to +85C *NOTICE: Stresses beyond those listed under “Absolute Maximum Ratings” may cause permanent damage to the device. This is a stress rating only and functional operation of the device at these or other conditions beyond those indicated in the operational sections of this specification is not implied. Exposure to absolute maximum rating conditions for extended periods may affect device reliability. Storage temperature...................................... -60°C to +150°C Voltage on input pins (except for 5V pins) with respect to ground .................................................................-0.3V to VVDD(2)+0.3V Voltage on 5V tolerant(1) pins with respect to ground ............... .............................................................................-0.3V to 5.5V Total DC output current on all I/O pins - VDDIO, 64-pin package ............... ......................................................................141 mA Total DC output current on all I/O pins - VDDIN, 64-pin package ....................................................................................... 42 mA Total DC output current on all I/O pins - VDDIO, 48-pin package ........... ...........................................................................120mA Total DC output current on all I/O pins - VDDIN, 48-pin package ....................................................................................... 39 mA Maximum operating voltage VDDCORE......................... 1.98V Maximum operating voltage VDDIO, VDDIN .................... 3.6V Table 35-2. Supply Characteristics Symbol Parameter Voltage Min Max Unit VVDDIO DC supply peripheral I/Os 1.62 3.6 V VVDDIN DC supply peripheral I/Os, 1.8V single supply mode 1.62 1.98 V DC supply peripheral I/Os and internal regulator, 3.3V supply mode 1.98 3.6 V VVDDCORE DC supply core 1.62 1.98 V VVDDANA Analog supply voltage 1.62 1.98 V 898 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.3 Maximum Clock Frequencies These parameters are given in the following conditions: • VVDDCORE = 1.62V to 1.98V • Temperature = -40°C to 85°C 35.4 Power Consumption The values in Table 35-5 are measured values of power consumption under the following conditions, except where noted: • Operating conditions, internal core supply (Figure 35-1) - this is the default configuration – VVDDIN = 3.0V Table 35-3. Supply Rise Rates and Order(1) Symbol Parameter Rise Rate Min Max Unit Comment VVDDIO DC supply peripheral I/Os 0 2.5 V/µs VVDDIN DC supply peripheral I/Os and internal regulator 0.002 2.5 V/µs Slower rise time requires external power-on reset circuit. VVDDCORE DC supply core 0 2.5 V/µs Rise before or at the same time as VDDIO VVDDANA Analog supply voltage 0 2.5 V/µs Rise together with VDDCORE Table 35-4. Clock Frequencies Symbol Parameter Description Min Max Units fCPU CPU clock frequency 50 MHz fPBA PBA clock frequency 50 fPBB PBB clock frequency 50 fGCLK0 GCLK0 clock frequency DFLLIF main reference, GCLK0 pin 50 fGCLK1 GCLK1 clock frequency DFLLIF dithering and SSG reference, GCLK1 pin 50 fGCLK2 GCLK2 clock frequency AST, GCLK2 pin 20 fGCLK3 GCLK3 clock frequency PWMA, GCLK3 pin 140 fGCLK4 GCLK4 clock frequency CAT, ACIFB, GCLK4 pin 50 fGCLK5 GCLK5 clock frequency GLOC and GCLK5 pin 80 fGCLK6 GCLK6 clock frequency ABDACB, IISC, and GCLK6 pin 50 fGCLK7 GCLK7 clock frequency USBC and GCLK7 pin 50 fGCLK8 GCLK8 clock frequency PLL0 source clock and GCLK8 pin 50 fGCLK9 GCLK9 clock frequency FREQM, GCLK0-8, GCLK9 pin 150 899 32142D–06/2013 ATUC64/128/256L3/4U – VVDDCORE = 1.62V, supplied by the internal regulator – Corresponds to the 3.3V supply mode with 1.8V regulated I/O lines, please refer to the Supply and Startup Considerations section for more details • Equivalent to the 3.3V single supply mode • Consumption in 1.8V single supply mode can be estimated by subtracting the regulator static current • Operating conditions, external core supply (Figure 35-2) - used only when noted – VVDDIN = VVDDCORE = 1.8V – Corresponds to the 1.8V single supply mode, please refer to the Supply and Startup Considerations section for more details • TA = 25C • Oscillators – OSC0 (crystal oscillator) stopped – OSC32K (32KHz crystal oscillator) running with external 32KHz crystal – DFLL running at 50MHz with OSC32K as reference • Clocks – DFLL used as main clock source – CPU, HSB, and PBB clocks undivided – PBA clock divided by 4 – The following peripheral clocks running • PM, SCIF, AST, FLASHCDW, PBA bridge – All other peripheral clocks stopped • I/Os are inactive with internal pull-up • Flash enabled in high speed mode • POR18 enabled • POR33 disabled 900 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. These numbers are valid for the measured condition only and must not be extrapolated to other frequencies. Figure 35-1. Measurement Schematic, Internal Core Supply Table 35-5. Power Consumption for Different Operating Modes Mode Conditions Measured on Consumption Typ Unit Active(1) CPU running a recursive Fibonacci algorithm Amp0 300 µA/MHz CPU running a division algorithm 174 Idle(1) 96 Frozen(1) 57 Standby(1) 46 Stop 38 µA DeepStop 25 Static -OSC32K and AST stopped -Internal core supply 14 -OSC32K running -AST running at 1KHz -External core supply (Figure 35-2) 7.3 -OSC32K and AST stopped -External core supply (Figure 35-2) 6.7 Shutdown -OSC32K running -AST running at 1KHz 800 nA AST and OSC32K stopped 220 Amp0 VDDIN VDDCORE VDDANA VDDIO 901 32142D–06/2013 ATUC64/128/256L3/4U Figure 35-2. Measurement Schematic, External Core Supply Amp0 VDDIN VDDCORE VDDANA VDDIO 902 32142D–06/2013 ATUC64/128/256L3/4U 35.5 I/O Pin Characteristics Notes: 1. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Table 35-6. Normal I/O Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units RPULLUP Pull-up resistance 75 100 145 kOhm VIL Input low-level voltage VVDD = 3.0V -0.3 0.3 * VVDD V VVDD = 1.62V -0.3 0.3 * VVDD VIH Input high-level voltage VVDD = 3.6V 0.7 * VVDD VVDD + 0.3 V VVDD = 1.98V 0.7 * VVDD VVDD + 0.3 VOL Output low-level voltage VVDD = 3.0V, IOL = 3mA 0.4 V VVDD = 1.62V, IOL = 2mA 0.4 VOH Output high-level voltage VVDD = 3.0V, IOH = 3mA VVDD - 0.4 V VVDD = 1.62V, IOH = 2mA VVDD - 0.4 fMAX Output frequency(2) VVDD = 3.0V, load = 10pF 45 MHz VVDD = 3.0V, load = 30pF 23 tRISE Rise time(2) VVDD = 3.0V, load = 10pF 4.7 ns VVDD = 3.0V, load = 30pF 11.5 tFALL Fall time(2) VVDD = 3.0V, load = 10pF 4.8 VVDD = 3.0V, load = 30pF 12 ILEAK Input leakage current Pull-up resistors disabled 1 µA CIN Input capacitance, all normal I/O pins except PA05, PA07, PA17, PA20, PA21, PB04, PB05 TQFP48 package 1.4 pF QFN48 package 1.1 TLLGA48 package 1.1 TQFP64 package 1.5 QFN64 package 1.1 CIN Input capacitance, PA20 TQFP48 package 2.7 QFN48 package 2.4 TLLGA48 package 2.4 TQFP64 package 2.8 QFN64 package 2.4 CIN Input capacitance, PA05, PA07, PA17, PA21, PB04, PB05 TQFP48 package 3.8 QFN48 package 3.5 TLLGA48 package 3.5 TQFP64 package 3.9 QFN64 package 3.5 903 32142D–06/2013 ATUC64/128/256L3/4U Notes: 1. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. Table 35-7. High-drive I/O Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units RPULLUP Pull-up resistance PA06 30 50 110 PA02, PB01, RESET 75 100 145 kOhm PA08, PA09 10 20 45 VIL Input low-level voltage VVDD = 3.0V -0.3 0.3 * VVDD V VVDD = 1.62V -0.3 0.3 * VVDD VIH Input high-level voltage VVDD = 3.6V 0.7 * VVDD VVDD + 0.3 V VVDD = 1.98V 0.7 * VVDD VVDD + 0.3 VOL Output low-level voltage VVDD = 3.0V, IOL = 6mA 0.4 V VVDD = 1.62V, IOL = 4mA 0.4 VOH Output high-level voltage VVDD = 3.0V, IOH = 6mA VVDD - 0.4 V VVDD = 1.62V, IOH = 4mA VVDD - 0.4 fMAX Output frequency, all High-drive I/O pins, except PA08 and PA09(2) VVDD = 3.0V, load = 10pF 45 MHz VVDD = 3.0V, load = 30pF 23 tRISE Rise time, all High-drive I/O pins, except PA08 and PA09(2) VVDD = 3.0V, load = 10pF 4.7 ns VVDD = 3.0V, load = 30pF 11.5 tFALL Fall time, all High-drive I/O pins, except PA08 and PA09(2) VVDD = 3.0V, load = 10pF 4.8 VVDD = 3.0V, load = 30pF 12 fMAX Output frequency, PA08 and PA09(2) VVDD = 3.0V, load = 10pF 54 MHz VVDD = 3.0V, load = 30pF 40 tRISE Rise time, PA08 and PA09(2) VVDD = 3.0V, load = 10pF 2.8 ns VVDD = 3.0V, load = 30pF 4.9 tFALL Fall time, PA08 and PA09(2) VVDD = 3.0V, load = 10pF 2.4 VVDD = 3.0V, load = 30pF 4.6 ILEAK Input leakage current Pull-up resistors disabled 1 µA CIN Input capacitance, all High-drive I/O pins, except PA08 and PA09 TQFP48 package 2.2 pF QFN48 package 2.0 TLLGA48 package 2.0 TQFP64 package 2.3 QFN64 package 2.0 CIN Input capacitance, PA08 and PA09 TQFP48 package 7.0 QFN48 package 6.7 TLLGA48 package 6.7 TQFP64 package 7.1 QFN64 package 6.7 904 32142D–06/2013 ATUC64/128/256L3/4U 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Notes: 1. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Table 35-8. High-drive I/O, 5V Tolerant, Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units RPULLUP Pull-up resistance 30 50 110 kOhm VIL Input low-level voltage VVDD = 3.0V -0.3 0.3 * VVDD V VVDD = 1.62V -0.3 0.3 * VVDD VIH Input high-level voltage VVDD = 3.6V 0.7 * VVDD 5.5 V VVDD = 1.98V 0.7 * VVDD 5.5 VOL Output low-level voltage VVDD = 3.0V, IOL = 6mA 0.4 V VVDD = 1.62V, IOL = 4mA 0.4 VOH Output high-level voltage VVDD = 3.0V, IOH = 6mA VVDD - 0.4 V VVDD = 1.62V, IOH = 4mA VVDD - 0.4 fMAX Output frequency(2) VVDD = 3.0V, load = 10pF 87 MHz VVDD = 3.0V, load = 30pF 58 tRISE Rise time(2) VVDD = 3.0V, load = 10pF 2.3 ns VVDD = 3.0V, load = 30pF 4.3 tFALL Fall time(2) VVDD = 3.0V, load = 10pF 1.9 VVDD = 3.0V, load = 30pF 3.7 ILEAK Input leakage current 5.5V, pull-up resistors disabled 10 µA CIN Input capacitance TQFP48 package 4.5 pF QFN48 package 4.2 TLLGA48 package 4.2 TQFP64 package 4.6 QFN64 package 4.2 Table 35-9. TWI Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units RPULLUP Pull-up resistance 25 35 60 kOhm VIL Input low-level voltage VVDD = 3.0V -0.3 0.3 * VVDD V VVDD = 1.62V -0.3 0.3 * VVDD VIH Input high-level voltage VVDD = 3.6V 0.7 * VVDD VVDD + 0.3 V VVDD = 1.98V 0.7 * VVDD VVDD + 0.3 Input high-level voltage, 5V tolerant SMBUS compliant pins VVDD = 3.6V 0.7 * VVDD 5.5 V VVDD = 1.98V 0.7 * VVDD 5.5 905 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. 35.6 Oscillator Characteristics 35.6.1 Oscillator 0 (OSC0) Characteristics 35.6.1.1 Digital Clock Characteristics The following table describes the characteristics for the oscillator when a digital clock is applied on XIN. Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.6.1.2 Crystal Oscillator Characteristics The following table describes the characteristics for the oscillator when a crystal is connected between XIN and XOUT as shown in Figure 35-3. The user must choose a crystal oscillator where the crystal load capacitance CL is within the range given in the table. The exact value of CL VOL Output low-level voltage IOL = 3mA 0.4 V ILEAK Input leakage current Pull-up resistors disabled 1 IIL Input low leakage 1 µA IIH Input high leakage 1 CIN Input capacitance TQFP48 package 3.8 pF QFN48 package 3.5 TLLGA48 package 3.5 TQFP64 package 3.9 QFN64 package 3.5 tFALL Fall time Cbus = 400pF, VVDD > 2.0V 250 ns Cbus = 400pF, VVDD > 1.62V 470 fMAX Max frequency Cbus = 400pF, VVDD > 2.0V 400 kHz Table 35-9. TWI Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units Table 35-10. Digital Clock Characteristics Symbol Parameter Conditions Min Typ Max Units fCPXIN XIN clock frequency 50 MHz tCPXIN XIN clock duty cycle(1) 40 60 % tSTARTUP Startup time 0 cycles CIN XIN input capacitance TQFP48 package 7.0 pF QFN48 package 6.7 TLLGA48 package 6.7 TQFP64 package 7.1 QFN64 package 6.7 906 32142D–06/2013 ATUC64/128/256L3/4U can be found in the crystal datasheet. The capacitance of the external capacitors (CLEXT) can then be computed as follows: where CPCB is the capacitance of the PCB and Ci is the internal equivalent load capacitance. Notes: 1. Please refer to the SCIF chapter for details. 2. Nominal crystal cycles. 3. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Figure 35-3. Oscillator Connection CLEXT 2 CL Ci   – CPCB = – Table 35-11. Crystal Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Crystal oscillator frequency(3) 0.45 10 16 MHz CL Crystal load capacitance(3) 6 18 pF Ci Internal equivalent load capacitance 2 tSTARTUP Startup time SCIF.OSCCTRL.GAIN = 2(1) 30 000(2) cycles IOSC Current consumption Active mode, f = 0.45MHz, SCIF.OSCCTRL.GAIN = 0 30 µA Active mode, f = 10MHz, SCIF.OSCCTRL.GAIN = 2 220 XIN XOUT CLEXT CLEXT CL Ci UC3L 907 32142D–06/2013 ATUC64/128/256L3/4U 35.6.2 32KHz Crystal Oscillator (OSC32K) Characteristics Figure 35-3 and the equation above also applies to the 32KHz oscillator connection. The user must choose a crystal oscillator where the crystal load capacitance CL is within the range given in the table. The exact value of CL can then be found in the crystal datasheet. Notes: 1. Nominal crystal cycles. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.6.3 Phase Locked Loop (PLL) Characteristics Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Table 35-12. 32 KHz Crystal Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Crystal oscillator frequency 32 768 Hz tSTARTUP Startup time RS = 60kOhm, CL = 9pF 30 000(1) cycles CL Crystal load capacitance(2) 6 12.5 pF Ci Internal equivalent load capacitance 2 IOSC32 Current consumption 0.6 µA RS Equivalent series resistance(2) 32 768Hz 35 85 kOhm Table 35-13. Phase Locked Loop Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency(1) 40 240 MHz fIN Input frequency(1) 4 16 IPLL Current consumption 8 µA/MHz tSTARTUP Startup time, from enabling the PLL until the PLL is locked fIN= 4MHz 200 µs fIN= 16MHz 155 908 32142D–06/2013 ATUC64/128/256L3/4U 35.6.4 Digital Frequency Locked Loop (DFLL) Characteristics Notes: 1. Spread Spectrum Generator (SSG) is disabled by writing a zero to the EN bit in the DFLL0SSG register. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 3. The FINE and COARSE values are selected by wrirting to the DFLL0VAL.FINE and DFLL0VAL.COARSE field respectively. Table 35-14. Digital Frequency Locked Loop Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency(2) 20 150 MHz fREF Reference frequency(2) 8 150 kHz FINE resolution step FINE > 100, all COARSE values (3) 0.38 % Frequency drift over voltage and temperature Open loop mode See Figure 35-4 Accuracy(2) FINE lock, fREF = 32kHz, SSG disabled 0.1 0.5 % ACCURATE lock, fREF = 32kHz, dither clk RCSYS/2, SSG disabled 0.06 0.5 FINE lock, fREF = 8-150kHz, SSG disabled 0.2 1 ACCURATE lock, fREF = 8-150kHz, dither clk RCSYS/2, SSG disabled 0.1 1 IDFLL Power consumption 25 µA/MHz tSTARTUP Startup time(2) Within 90% of final values 100 µs tLOCK Lock time fREF = 32kHz, FINE lock, SSG disabled 8 ms fREF = 32kHz, ACCURATE lock, dithering clock = RCSYS/2, SSG disabled 28 909 32142D–06/2013 ATUC64/128/256L3/4U Figure 35-4. DFLL Open Loop Frequency Variation(1)(2) Notes: 1. The plot shows a typical open loop mode behavior with COARSE= 99 and FINE= 255. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.6.5 120MHz RC Oscillator (RC120M) Characteristics Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. DFLL Open Loop Frequency variation 80 90 100 110 120 130 140 150 160 -40 -20 0 20 40 60 80 Temperature Frequencies (MHz) 1,98V 1,8V 1.62V Table 35-15. Internal 120MHz RC Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency(1) 88 120 152 MHz IRC120M Current consumption 1.2 mA tSTARTUP Startup time(1) VVDDCORE = 1.8V 3 µs 910 32142D–06/2013 ATUC64/128/256L3/4U 35.6.6 32kHz RC Oscillator (RC32K) Characteristics Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.6.7 System RC Oscillator (RCSYS) Characteristics 35.7 Flash Characteristics Table 35-18 gives the device maximum operating frequency depending on the number of flash wait states and the flash read mode. The FSW bit in the FLASHCDW FSR register controls the number of wait states used when accessing the flash memory. Table 35-16. 32kHz RC Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency(1) 20 32 44 kHz IRC32K Current consumption 0.7 µA tSTARTUP Startup time(1) 100 µs Table 35-17. System RC Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency Calibrated at 85C 111.6 115 118.4 kHz Table 35-18. Maximum Operating Frequency Flash Wait States Read Mode Maximum Operating Frequency 1 High speed read mode 50MHz 0 25MHz 1 Normal read mode 30MHz 0 15MHz Table 35-19. Flash Characteristics Symbol Parameter Conditions Min Typ Max Unit tFPP Page programming time fCLK_HSB = 50MHz 5 ms tFPE Page erase time 5 tFFP Fuse programming time 1 tFEA Full chip erase time (EA) 6 tFCE JTAG chip erase time (CHIP_ERASE) fCLK_HSB = 115kHz 310 911 32142D–06/2013 ATUC64/128/256L3/4U 35.8 ABDACB Electrical Characteristics. Notes: 1. Test Condition: Common Mode Offset Control disabled (CR.CMOC = 0). Alternative Upsampling Ratio disabled (CR.ALTUPR = 0). Volume at maximum level (VCR0.VOLUME = 0x7FFF and VCR1.VOLUME = 0x7FFF). Device is battery powered (9V) through an LDO, VDDIO at 3.3V. Analog low pass filter as shown in Figure 35-5(1. order differential low pass filter followed by a 4. order low-pass), +VCC at +9V and -VCC at -9V. Test signal stored on a SD card and read by the SPI Interface. 2. Performance numbers for dynamic range, SNR, and THD performance are very dependent on the application and circuit board design. Since the design has 0dB Power Supply Rejection Ratio (PSRR), noise on the IO power supply will couple directly through to the output and be present in the audio signal. To get the best performance one should reduce toggling of other IO pins as much as possible and make sure the device has sufficient decoupling on the IO supply pins. 3. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Figure 35-5. Differential Analog Low-pass Filter Table 35-20. Flash Endurance and Data Retention Symbol Parameter Conditions Min Typ Max Unit NFARRAY Array endurance (write/page) 100k cycles NFFUSE General Purpose fuses endurance (write/bit) 10k tRET Data retention 15 years Table 35-21. ABDACB Electrical Characteristics Symbol Parameter Conditions MIN TYP MAX Unit Resolution 16 Bits Dynamic range(1)(2)(3) FS = 48.000kHz > 76 dB SNR(1)(2)(3) FS = 48.000kHz > 46 dB THD(1)(2)(3) FS = 48.000kHz < 0.02 % PSRR 0 dB VOut maximum CR.CMOC = 0 97/128 * VDDIO V VOut minimum CR.CMOC = 0 31/128 * VDDIO V Common mode CR.CMOC = 0 CR.CMOC = 1, DAC_0 and DAC_1 pins CR.CMOC = 1, DACN_0 and DACN_1 pins 64/128 * VDDIO 80/128 * VDDIO 48/128 * VDDIO V R1, 22K C2 140p R2, 22K R4, 22K C1, 140p R3, 22K R6, 22K R5, 22K R7, 22K C4 270p C3 310p -Vcc +Vcc -Vcc +Vcc DAC DACN R8, 22K R9, 22K C6 110p C5 750p -Vcc +Vcc GND GND GND GND GND Out 912 32142D–06/2013 ATUC64/128/256L3/4U 35.9 Analog Characteristics 35.9.1 Voltage Regulator Characteristics Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Note: 1. Refer to Section 6.1.2 on page 39. Table 35-22. VREG Electrical Characteristics Symbol Parameter Condition Min Typ Max Units VVDDIN Input voltage range 1.98 3.3 3.6 V VVDDCORE Output voltage, calibrated value VVDDIN >= 1.98V 1.8 Output voltage accuracy(1) IOUT = 0.1mA to 60mA, VVDDIN > 1.98V 2 % IOUT = 0.1mA to 60mA, VVDDIN <1.98V 4 IOUT DC output current(1) Normal mode 60 mA Low power mode 1 IVREG Static current of internal regulator Normal mode 13 µA Low power mode 4 Table 35-23. Decoupling Requirements Symbol Parameter Condition Typ Techno. Units CIN1 Input regulator capacitor 1 33 nF CIN2 Input regulator capacitor 2 100 CIN3 Input regulator capacitor 3 10 µF COUT1 Output regulator capacitor 1 100 nF COUT2 Output regulator capacitor 2 2.2 Tantalum 0.5 3.0V, fADC = 6MHz, 12-bit resolution mode, low impedance source 28 kSPS VVDD > 3.0V, fADC = 6MHz, 10-bit resolution mode, low impedance source 460 VVDD > 3.0V, fADC = 6MHz, 8-bit resolution mode, low impedance source 460 VADVREFP Reference voltage range VADVREFP = VVDDANA 1.62 1.98 V IADC Current consumption on VVDDANA ADC Clock = 6MHz 350 µA IADVREFP Current consumption on ADVREFP pin fADC = 6MHz 150 Table 35-30. Analog Inputs Symbol Parameter Conditions Min Typ Max Units VADn Input Voltage Range 12-bit mode 10-bit mode 0 VADVREFP V 8-bit mode CONCHIP Internal Capacitance(1) 22.5 pF RONCHIP Internal Resistance(1) VVDDIO = 3.0V to 3.6V, VVDDCORE = 1.8V 3.15 kOhm VVDDIO = VVDDCORE = 1.62V to 1.98V 55.9 RONCHIP CONCHIP RSOURCE 917 32142D–06/2013 ATUC64/128/256L3/4U ( ) of the PCB and source must be taken into account when calculating the required sample and hold time. Figure 35-8 shows the ADC input channel equivalent circuit. Figure 35-8. ADC Input The minimum sample and hold time (in ns) can be found using this formula: Where n is the number of bits in the conversion. is defined by the SHTIM field in the ADCIFB ACR register. Please refer to the ADCIFB chapter for more information. 35.9.6.2 Applicable Conditions and Derating Data Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. CSOURCE ADCVREFP/2 CONCHIP RONCHIP R Positive Input SOURCE CSOURCE VIN t SAMPLEHOLD RONCHIP + RSOURCE   CONCHIP CSOURCE    + 2n + 1   ln  t SAMPLEHOLD Table 35-31. Transfer Characteristics 12-bit Resolution Mode(1) Parameter Conditions Min Typ Max Units Resolution 12 Bit Integral non-linearity ADC clock frequency = 6MHz, Input Voltage Range = 0 - VADVREFP +/-4 LSB ADC clock frequency = 6MHz, Input Voltage Range = (10% VADVREFP) - (90% VADVREFP) +/-2 Differential non-linearity ADC clock frequency = 6MHz -1.5 1.5 Offset error +/-3 Gain error +/-5 Table 35-32. Transfer Characteristics, 10-bit Resolution Mode(1) Parameter Conditions Min Typ Max Units Resolution 10 Bit Integral non-linearity ADC clock frequency = 6MHz +/-1 LSB Differential non-linearity -1.0 1.0 Offset error +/-1 Gain error +/-2 918 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.9.7 Temperature Sensor Characteristics Note: 1. The Temperature Sensor is not calibrated. The accuracy of the Temperature Sensor is governed by the ADC accuracy. Table 35-33. Transfer Characteristics, 8-bit Resolution Mode(1) Parameter Conditions Min Typ Max Units Resolution 8 Bit Integral non-linearity ADC clock frequency = 6MHz +/-0.5 LSB Differential non-linearity -0.3 0.3 Offset error +/-1 Gain error +/-1 Table 35-34. Temperature Sensor Characteristics(1) Symbol Parameter Condition Min Typ Max Units Gradient 1 mV/°C ITS Current consumption 1 µA tSTARTUP Startup time 0 µs 919 32142D–06/2013 ATUC64/128/256L3/4U 35.9.8 Analog Comparator Characteristics Notes: 1. AC.CONFn.FLEN and AC.CONFn.HYS fields, refer to the Analog Comparator Interface chapter. 2. Referring to fAC. 3. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.9.9 Capacitive Touch Characteristics 35.9.9.1 Discharge Current Source Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Table 35-35. Analog Comparator Characteristics Symbol Parameter Condition Min Typ Max Units Positive input voltage range(3) -0.2 VVDDIO + 0.3 V Negative input voltage range(3) -0.2 VVDDIO - 0.6 Statistical offset(3) VACREFN = 1.0V, fAC = 12MHz, filter length = 2, hysteresis = 0(1) 20 mV fAC Clock frequency for GCLK4(3) 12 MHz Throughput rate(3) fAC = 12MHz 12 000 000 Comparisons per second Propagation delay Delay from input change to Interrupt Status Register Changes ns IAC Current consumption(3) All channels, VDDIO = 3.3V, fA = 3MHz 420 µA tSTARTUP Startup time 3 cycles Input current per pin(3) 0.2 µA/MHz(2) Table 35-36. DICS Characteristics Symbol Parameter Min Typ Max Unit RREF Internal resistor 170 kOhm k Trim step size(1) 0.7 % 1 t CLKACIFB f AC  ---------------------------------------- + 3     t CLKACIFB  920 32142D–06/2013 ATUC64/128/256L3/4U 35.9.9.2 Strong Pull-up Pull-down 35.9.10 USB Transceiver Characteristics The USB on-chip buffers comply with the Universal Serial Bus (USB) v2.0 standard. All AC parameters related to these buffers can be found within the USB 2.0 electrical specifications. 35.9.10.1 Electrical Characteristics Table 35-37. Strong Pull-up Pull-down Parameter Min Typ Max Unit Pull-down resistor 1 kOhm Pull-up resistor 1 Table 35-38. Electrical Parameters Symbol Parameter Conditions Min Typ Max Unit REXT Recommended external USB series resistor In series with each USB pin with ±5% 39 Ohm 921 32142D–06/2013 ATUC64/128/256L3/4U 35.10 Timing Characteristics 35.10.1 Startup, Reset, and Wake-up Timing The startup, reset, and wake-up timings are calculated using the following formula: Where and are found in Table 35-39. is the period of the CPU clock. If a clock source other than RCSYS is selected as the CPU clock, the oscillator startup time, , must be added to the wake-up time from the stop, deepstop, and static sleep modes. Please refer to the source for the CPU clock in the ”Oscillator Characteristics” on page 905 for more details about oscillator startup times. Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.10.2 RESET_N Timing Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. t tCONST NCPU t CPU = +  t CONST NCPU t CPU t OSCSTART Table 35-39. Maximum Reset and Wake-up Timing(1) Parameter Measuring Max (in µs) Max Startup time from power-up, using regulator Time from VDDIN crossing the VPOT+ threshold of POR33 to the first instruction entering the decode stage of CPU. VDDCORE is supplied by the internal regulator. 2210 0 Startup time from power-up, no regulator Time from VDDIN crossing the VPOT+ threshold of POR33 to the first instruction entering the decode stage of CPU. VDDCORE is connected to VDDIN. 1810 0 Startup time from reset release Time from releasing a reset source (except POR18, POR33, and SM33) to the first instruction entering the decode stage of CPU. 170 0 Wake-up Idle From wake-up event to the first instruction of an interrupt routine entering the decode stage of the CPU. 0 19 Frozen 0 110 Standby 0 110 Stop 27 + 116 Deepstop 27 + 116 Static 97 + 116 Wake-up from shutdown From wake-up event to the first instruction entering the decode stage of the CPU. 1180 0 t CONST NCPU t OSCSTART t OSCSTART t OSCSTART Table 35-40. RESET_N Waveform Parameters(1) Symbol Parameter Conditions Min Max Units tRESET RESET_N minimum pulse length 10 ns 922 32142D–06/2013 ATUC64/128/256L3/4U 35.10.3 USART in SPI Mode Timing 35.10.3.1 Master mode Figure 35-9. USART in SPI Master Mode with (CPOL= CPHA= 0) or (CPOL= CPHA= 1) Figure 35-10. USART in SPI Master Mode with (CPOL= 0 and CPHA= 1) or (CPOL= 1 and CPHA= 0) Notes: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 2. Where: USPI0 USPI1 MISO SPCK MOSI USPI2 USPI3 USPI4 MISO SPCK MOSI USPI5 Table 35-41. USART in SPI Mode Timing, Master Mode(1) Symbol Parameter Conditions Min Max Units USPI0 MISO setup time before SPCK rises VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 28.7 + tSAMPLE(2) ns USPI1 MISO hold time after SPCK rises 0 USPI2 SPCK rising to MOSI delay 16.5 USPI3 MISO setup time before SPCK falls 25.8 + tSAMPLE(2) USPI4 MISO hold time after SPCK falls 0 USPI5 SPCK falling to MOSI delay 21.19 t SAMPLE t SPCK t SPCK 2 t CLKUSART  ------------------------------------ 1 2 --     t CLKUSART = –  923 32142D–06/2013 ATUC64/128/256L3/4U Maximum SPI Frequency, Master Output The maximum SPI master output frequency is given by the following formula: Where is the MOSI delay, USPI2 or USPI5 depending on CPOL and NCPHA. is the maximum frequency of the SPI pins. Please refer to the I/O Pin Characteristics section for the maximum frequency of the pins. is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. Maximum SPI Frequency, Master Input The maximum SPI master input frequency is given by the following formula: Where is the MISO setup and hold time, USPI0 + USPI1 or USPI3 + USPI4 depending on CPOL and NCPHA. is the SPI slave response time. Please refer to the SPI slave datasheet for . is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. 35.10.3.2 Slave mode Figure 35-11. USART in SPI Slave Mode with (CPOL= 0 and CPHA= 1) or (CPOL= 1 and CPHA= 0) f SPCKMAX MIN fPINMAX 1 SPIn ------------ f CLKSPI  2 9 = (, )  ---------------------------- SPIn fPINMAX f CLKSPI f SPCKMAX MIN 1 SPIn tVALID + ----------------------------------- f CLKSPI  2 9 = ( ,) ----------------------------- SPIn TVALID TVALID f CLKSPI USPI7 USPI8 MISO SPCK MOSI USPI6 924 32142D–06/2013 ATUC64/128/256L3/4U Figure 35-12. USART in SPI Slave Mode with (CPOL= CPHA= 0) or (CPOL= CPHA= 1) Figure 35-13. USART in SPI Slave Mode, NPCS Timing Notes: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 2. Where: USPI10 USPI11 MISO SPCK MOSI USPI9 USPI14 USPI12 USPI15 USPI13 NSS SPCK, CPOL=0 SPCK, CPOL=1 Table 35-42. USART in SPI mode Timing, Slave Mode(1) Symbol Parameter Conditions Min Max Units USPI6 SPCK falling to MISO delay VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 37.3 ns USPI7 MOSI setup time before SPCK rises 2.6 + tSAMPLE(2) + tCLK_USART USPI8 MOSI hold time after SPCK rises 0 USPI9 SPCK rising to MISO delay 37.0 USPI10 MOSI setup time before SPCK falls 2.6 + tSAMPLE(2) + tCLK_USART USPI11 MOSI hold time after SPCK falls 0 USPI12 NSS setup time before SPCK rises 27.2 USPI13 NSS hold time after SPCK falls 0 USPI14 NSS setup time before SPCK falls 27.2 USPI15 NSS hold time after SPCK rises 0 t SAMPLE t SPCK t SPCK 2 tCLKUSART  ------------------------------------ 1 2 + --     t CLKUSART = –  925 32142D–06/2013 ATUC64/128/256L3/4U Maximum SPI Frequency, Slave Input Mode The maximum SPI slave input frequency is given by the following formula: Where is the MOSI setup and hold time, USPI7 + USPI8 or USPI10 + USPI11 depending on CPOL and NCPHA. is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. Maximum SPI Frequency, Slave Output Mode The maximum SPI slave output frequency is given by the following formula: Where is the MISO delay, USPI6 or USPI9 depending on CPOL and NCPHA. is the SPI master setup time. Please refer to the SPI master datasheet for . is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. is the maximum frequency of the SPI pins. Please refer to the I/O Pin Characteristics section for the maximum frequency of the pins. 35.10.4 SPI Timing 35.10.4.1 Master mode Figure 35-14. SPI Master Mode with (CPOL= NCPHA= 0) or (CPOL= NCPHA= 1) f SPCKMAX MIN f CLKSPI  2 9 ----------------------------- 1 SPIn = ( ,) ------------ SPIn f CLKSPI f SPCKMAX MIN f CLKSPI  2 9 ---------------------------- f PINMAX  1 SPIn tSETUP + = ( ,) ------------------------------------ SPIn TSETUP TSETUP f CLKSPI f PINMAX SPI0 SPI1 MISO SPCK MOSI SPI2 926 32142D–06/2013 ATUC64/128/256L3/4U Figure 35-15. SPI Master Mode with (CPOL= 0 and NCPHA= 1) or (CPOL= 1 and NCPHA= 0) Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Maximum SPI Frequency, Master Output The maximum SPI master output frequency is given by the following formula: Where is the MOSI delay, SPI2 or SPI5 depending on CPOL and NCPHA. is the maximum frequency of the SPI pins. Please refer to the I/O Pin Characteristics section for the maximum frequency of the pins. Maximum SPI Frequency, Master Input The maximum SPI master input frequency is given by the following formula: Where is the MISO setup and hold time, SPI0 + SPI1 or SPI3 + SPI4 depending on CPOL and NCPHA. is the SPI slave response time. Please refer to the SPI slave datasheet for . SPI3 SPI4 MISO SPCK MOSI SPI5 Table 35-43. SPI Timing, Master Mode(1) Symbol Parameter Conditions Min Max Units SPI0 MISO setup time before SPCK rises VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 33.4 + (tCLK_SPI)/2 ns SPI1 MISO hold time after SPCK rises 0 SPI2 SPCK rising to MOSI delay 7.1 SPI3 MISO setup time before SPCK falls 29.2 + (tCLK_SPI)/2 SPI4 MISO hold time after SPCK falls 0 SPI5 SPCK falling to MOSI delay 8.63 f SPCKMAX MIN fPINMAX 1 SPIn = ( ,) ------------ SPIn f PINMAX f SPCKMAX 1 SPIn tVALID + = ----------------------------------- SPIn t VALID tVALID 927 32142D–06/2013 ATUC64/128/256L3/4U 35.10.4.2 Slave mode Figure 35-16. SPI Slave Mode with (CPOL= 0 and NCPHA= 1) or (CPOL= 1 and NCPHA= 0) Figure 35-17. SPI Slave Mode with (CPOL= NCPHA= 0) or (CPOL= NCPHA= 1) Figure 35-18. SPI Slave Mode, NPCS Timing SPI7 SPI8 MISO SPCK MOSI SPI6 SPI10 SPI11 MISO SPCK MOSI SPI9 SPI14 SPI12 SPI15 SPI13 NPCS SPCK, CPOL=0 SPCK, CPOL=1 928 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Maximum SPI Frequency, Slave Input Mode The maximum SPI slave input frequency is given by the following formula: Where is the MOSI setup and hold time, SPI7 + SPI8 or SPI10 + SPI11 depending on CPOL and NCPHA. is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. Maximum SPI Frequency, Slave Output Mode The maximum SPI slave output frequency is given by the following formula: Where is the MISO delay, SPI6 or SPI9 depending on CPOL and NCPHA. is the SPI master setup time. Please refer to the SPI master datasheet for . is the maximum frequency of the SPI pins. Please refer to the I/O Pin Characteristics section for the maximum frequency of the pins. 35.10.5 TWIM/TWIS Timing Figure 35-45 shows the TWI-bus timing requirements and the compliance of the device with them. Some of these requirements (tr and tf ) are met by the device without requiring user intervention. Compliance with the other requirements (tHD-STA, tSU-STA, tSU-STO, tHD-DAT, tSU-DAT-TWI, tLOWTWI, tHIGH, and fTWCK) requires user intervention through appropriate programming of the relevant Table 35-44. SPI Timing, Slave Mode(1) Symbol Parameter Conditions Min Max Units SPI6 SPCK falling to MISO delay VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 29.4 ns SPI7 MOSI setup time before SPCK rises 0 SPI8 MOSI hold time after SPCK rises 6.0 SPI9 SPCK rising to MISO delay 29.0 SPI10 MOSI setup time before SPCK falls 0 SPI11 MOSI hold time after SPCK falls 5.5 SPI12 NPCS setup time before SPCK rises 3.4 SPI13 NPCS hold time after SPCK falls 1.1 SPI14 NPCS setup time before SPCK falls 3.3 SPI15 NPCS hold time after SPCK rises 0.7 f SPCKMAX MIN fCLKSPI 1 SPIn = ( ,) ------------ SPIn f CLKSPI f SPCKMAX MIN fPINMAX 1 SPIn tSETUP + = (, ) ------------------------------------ SPIn t SETUP t SETUP fPINMAX 929 32142D–06/2013 ATUC64/128/256L3/4U TWIM and TWIS user interface registers. Please refer to the TWIM and TWIS sections for more information. Notes: 1. Standard mode: ; fast mode: . 2. A device must internally provide a hold time of at least 300 ns for TWD with reference to the falling edge of TWCK. Notations: Cb = total capacitance of one bus line in pF tclkpb = period of TWI peripheral bus clock tprescaled = period of TWI internal prescaled clock (see chapters on TWIM and TWIS) The maximum tHD;DAT has only to be met if the device does not stretch the LOW period (tLOW-TWI) of TWCK. Table 35-45. TWI-Bus Timing Requirements Symbol Parameter Mode Minimum Maximum Uni Requirement Device Requirement Device t tr TWCK and TWD rise time Standard( 1) - 1000 ns Fast(1) 20 + 0.1Cb 300 tf TWCK and TWD fall time Standard - 300 ns Fast 20 + 0.1Cb 300 tHD-STA (Repeated) START hold time Standard 4 tclkpb - s Fast 0.6 tSU-STA (Repeated) START set-up time Standard 4.7 tclkpb - s Fast 0.6 tSU-STO STOP set-up time Standard 4.0 4tclkpb - s Fast 0.6 tHD-DAT Data hold time Standard 0.3(2) 2tclkpb 3.45() 15tprescaled + tclkpb s Fast 0.9() tSU-DATTWI Data set-up time Standard 250 2tclkpb - ns Fast 100 tSU-DAT - -tclkpb - - tLOW-TWI TWCK LOW period Standard 4.7 4tclkpb - s Fast 1.3 tLOW - -tclkpb - - tHIGH TWCK HIGH period Standard 4.0 8tclkpb - s Fast 0.6 fTWCK TWCK frequency Standard - 100 kHz Fast 400 1 12tclkpb ----------------------- fTWCK  100 kHz f TWCK  100 kHz 930 32142D–06/2013 ATUC64/128/256L3/4U 35.10.6 JTAG Timing Figure 35-19. JTAG Interface Signals Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. JTAG2 JTAG3 JTAG1 JTAG4 JTAG0 TMS/TDI TCK TDO JTAG5 JTAG6 JTAG7 JTAG8 JTAG9 JTAG10 Boundary Scan Inputs Boundary Scan Outputs Table 35-46. JTAG Timings(1) Symbol Parameter Conditions Min Max Units JTAG0 TCK Low Half-period VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 21.8 ns JTAG1 TCK High Half-period 8.6 JTAG2 TCK Period 30.3 JTAG3 TDI, TMS Setup before TCK High 2.0 JTAG4 TDI, TMS Hold after TCK High 2.3 JTAG5 TDO Hold Time 9.5 JTAG6 TCK Low to TDO Valid 21.8 JTAG7 Boundary Scan Inputs Setup Time 0.6 JTAG8 Boundary Scan Inputs Hold Time 6.9 JTAG9 Boundary Scan Outputs Hold Time 9.3 JTAG10 TCK to Boundary Scan Outputs Valid 32.2 931 32142D–06/2013 ATUC64/128/256L3/4U 36. Mechanical Characteristics 36.1 Thermal Considerations 36.1.1 Thermal Data Table 36-1 summarizes the thermal resistance data depending on the package. 36.1.2 Junction Temperature The average chip-junction temperature, TJ, in °C can be obtained from the following: 1. 2. where: • JA = package thermal resistance, Junction-to-ambient (°C/W), provided in Table 36-1. • JC = package thermal resistance, Junction-to-case thermal resistance (°C/W), provided in Table 36-1. • HEAT SINK = cooling device thermal resistance (°C/W), provided in the device datasheet. • PD = device power consumption (W) estimated from data provided in Section 35.4 on page 898. • TA = ambient temperature (°C). From the first equation, the user can derive the estimated lifetime of the chip and decide if a cooling device is necessary or not. If a cooling device is to be fitted on the chip, the second equation should be used to compute the resulting average chip-junction temperature TJ in °C. Table 36-1. Thermal Resistance Data Symbol Parameter Condition Package Typ Unit JA Junction-to-ambient thermal resistance Still Air TQFP48 54.4 C/W JC Junction-to-case thermal resistance TQFP48 15.7 JA Junction-to-ambient thermal resistance Still Air QFN48 26.0 C/W JC Junction-to-case thermal resistance QFN48 1.6 JA Junction-to-ambient thermal resistance Still Air TLLGA48 25.4 C/W JC Junction-to-case thermal resistance TLLGA48 12.7 JA Junction-to-ambient thermal resistance Still Air TQFP64 52.9 C/W JC Junction-to-case thermal resistance TQFP64 15.5 JA Junction-to-ambient thermal resistance Still Air QFN64 22.9 C/W JC Junction-to-case thermal resistance QFN64 1.6 TJ TA PD JA = +    TJ TA PD  HEATSINK  JC = + +   932 32142D–06/2013 ATUC64/128/256L3/4U 36.2 Package Drawings Figure 36-1. TQFP-48 Package Drawing Table 36-2. Device and Package Maximum Weight 140 mg Table 36-3. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-4. Package Reference JEDEC Drawing Reference MS-026 JESD97 Classification E3 933 32142D–06/2013 ATUC64/128/256L3/4U Figure 36-2. QFN-48 Package Drawing Note: The exposed pad is not connected to anything internally, but should be soldered to ground to increase board level reliability. Table 36-5. Device and Package Maximum Weight 140 mg Table 36-6. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-7. Package Reference JEDEC Drawing Reference M0-220 JESD97 Classification E3 934 32142D–06/2013 ATUC64/128/256L3/4U Figure 36-3. TLLGA-48 Package Drawing Table 36-8. Device and Package Maximum Weight 39.3 mg Table 36-9. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-10. Package Reference JEDEC Drawing Reference N/A JESD97 Classification E4 935 32142D–06/2013 ATUC64/128/256L3/4U Figure 36-4. TQFP-64 Package Drawing Table 36-11. Device and Package Maximum Weight 300 mg Table 36-12. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-13. Package Reference JEDEC Drawing Reference MS-026 JESD97 Classification E3 936 32142D–06/2013 ATUC64/128/256L3/4U Figure 36-5. QFN-64 Package Drawing Note: The exposed pad is not connected to anything internally, but should be soldered to ground to increase board level reliability. Table 36-14. Device and Package Maximum Weight 200 mg Table 36-15. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-16. Package Reference JEDEC Drawing Reference M0-220 JESD97 Classification E3 937 32142D–06/2013 ATUC64/128/256L3/4U 36.3 Soldering Profile Table 36-17 gives the recommended soldering profile from J-STD-20. A maximum of three reflow passes is allowed per component. Table 36-17. Soldering Profile Profile Feature Green Package Average Ramp-up Rate (217°C to Peak) 3°C/s max Preheat Temperature 175°C ±25°C 150-200°C Time Maintained Above 217°C 60-150 s Time within 5C of Actual Peak Temperature 30 s Peak Temperature Range 260°C Ramp-down Rate 6°C/s max Time 25C to Peak Temperature 8 minutes max 938 32142D–06/2013 ATUC64/128/256L3/4U 37. Ordering Information Table 37-1. Ordering Information Device Ordering Code Carrier Type Package Package Type Temperature Operating Range ATUC256L3U ATUC256L3U-AUTES ES TQFP 64 JESD97 Classification E3 N/A ATUC256L3U-AUT Tray Industrial (-40C to 85C) ATUC256L3U-AUR Tape & Reel ATUC256L3U-Z3UTES ES QFN 64 N/A ATUC256L3U-Z3UT Tray Industrial (-40C to 85C) ATUC256L3U-Z3UR Tape & Reel ATUC128L3U ATUC128L3U-AUT Tray TQFP 64 JESD97 Classification E3 Industrial (-40C to 85C) ATUC128L3U-AUR Tape & Reel ATUC128L3U-Z3UT Tray QFN 64 ATUC128L3U-Z3UR Tape & Reel ATUC64L3U ATUC64L3U-AUT Tray TQFP 64 JESD97 Classification E3 Industrial (-40C to 85C) ATUC64L3U-AUR Tape & Reel ATUC64L3U-Z3UT Tray QFN 64 ATUC64L3U-Z3UR Tape & Reel 939 32142D–06/2013 ATUC64/128/256L3/4U ATUC256L4U ATUC256L4U-AUTES ES TQFP 48 JESD97 Classification E3 N/A ATUC256L4U-AUT Tray Industrial (-40C to 85C) ATUC256L4U-AUR Tape & Reel ATUC256L4U-ZAUTES ES QFN 48 N/A ATUC256L4U-ZAUT Tray Industrial (-40C to 85C) ATUC256L4U-ZAUR Tape & Reel ATUC256L4U-D3HES ES TLLGA 48 JESD97 Classification E4 N/A ATUC256L4U-D3HT Tray Industrial (-40C to 85C) ATUC256L4U-D3HR Tape & Reel ATUC128L4U ATUC128L4U-AUT Tray TQFP 48 JESD97 Classification E3 ATUC128L4U-AUR Tape & Reel ATUC128L4U-ZAUT Tray QFN 48 ATUC128L4U-ZAUR Tape & Reel ATUC128L4U-D3HT Tray TLLGA 48 JESD97 Classification E4 ATUC128L4U-D3HR Tape & Reel ATUC64L4U ATUC64L4U-AUT Tray TQFP 48 JESD97 Classification E3 ATUC64L4U-AUR Tape & Reel ATUC64L4U-ZAUT Tray QFN 48 ATUC64L4U-ZAUR Tape & Reel ATUC64L4U-D3HT Tray TLLGA 48 JESD97 Classification E4 ATUC64L4U-D3HR Tape & Reel Table 37-1. Ordering Information Device Ordering Code Carrier Type Package Package Type Temperature Operating Range 940 32142D–06/2013 ATUC64/128/256L3/4U 38. Errata 38.1 Rev. C 38.1.1 SCIF 1. The RC32K output on PA20 is not always permanently disabled The RC32K output on PA20 may sometimes re-appear. Fix/Workaround Before using RC32K for other purposes, the following procedure has to be followed in order to properly disable it: - Run the CPU on RCSYS - Disable the output to PA20 by writing a zero to PM.PPCR.RC32OUT - Enable RC32K by writing a one to SCIF.RC32KCR.EN, and wait for this bit to be read as one - Disable RC32K by writing a zero to SCIF.RC32KCR.EN, and wait for this bit to be read as zero. 2. PLLCOUNT value larger than zero can cause PLLEN glitch Initializing the PLLCOUNT with a value greater than zero creates a glitch on the PLLEN signal during asynchronous wake up. Fix/Workaround The lock-masking mechanism for the PLL should not be used. The PLLCOUNT field of the PLL Control Register should always be written to zero. 3. Writing 0x5A5A5A5A to the SCIF memory range will enable the SCIF UNLOCK feature The SCIF UNLOCK feature will be enabled if the value 0x5A5A5A5A is written to any location in the SCIF memory range. Fix/Workaround None. 38.1.2 SPI 1. SPI data transfer hangs with CSR0.CSAAT==1 and MR.MODFDIS==0 When CSR0.CSAAT==1 and mode fault detection is enabled (MR.MODFDIS==0), the SPI module will not start a data transfer. Fix/Workaround Disable mode fault detection by writing a one to MR.MODFDIS. 2. Disabling SPI has no effect on the SR.TDRE bit Disabling SPI has no effect on the SR.TDRE bit whereas the write data command is filtered when SPI is disabled. Writing to TDR when SPI is disabled will not clear SR.TDRE. If SPI is disabled during a PDCA transfer, the PDCA will continue to write data to TDR until its buffer is empty, and this data will be lost. Fix/Workaround Disable the PDCA, add two NOPs, and disable the SPI. To continue the transfer, enable the SPI and PDCA. 3. SPI disable does not work in SLAVE mode SPI disable does not work in SLAVE mode. Fix/Workaround Read the last received data, then perform a software reset by writing a one to the Software Reset bit in the Control Register (CR.SWRST). 941 32142D–06/2013 ATUC64/128/256L3/4U 4. SPI bad serial clock generation on 2nd chip_select when SCBR=1, CPOL=1, and NCPHA=0 When multiple chip selects (CS) are in use, if one of the baudrates equal 1 while one (CSRn.SCBR=1) of the others do not equal 1, and CSRn.CPOL=1 and CSRn.NCPHA=0, then an additional pulse will be generated on SCK. Fix/Workaround When multiple CS are in use, if one of the baudrates equals 1, the others must also equal 1 if CSRn.CPOL=1 and CSRn.NCPHA=0. 5. SPI mode fault detection enable causes incorrect behavior When mode fault detection is enabled (MR.MODFDIS==0), the SPI module may not operate properly. Fix/Workaround Always disable mode fault detection before using the SPI by writing a one to MR.MODFDIS. 6. SPI RDR.PCS is not correct The PCS (Peripheral Chip Select) field in the SPI RDR (Receive Data Register) does not correctly indicate the value on the NPCS pins at the end of a transfer. Fix/Workaround Do not use the PCS field of the SPI RDR. 38.1.3 TWI 1. SMBALERT bit may be set after reset The SMBus Alert (SMBALERT) bit in the Status Register (SR) might be erroneously set after system reset. Fix/Workaround After system reset, clear the SR.SMBALERT bit before commencing any TWI transfer. 2. Clearing the NAK bit before the BTF bit is set locks up the TWI bus When the TWIS is in transmit mode, clearing the NAK Received (NAK) bit of the Status Register (SR) before the end of the Acknowledge/Not Acknowledge cycle will cause the TWIS to attempt to continue transmitting data, thus locking up the bus. Fix/Workaround Clear SR.NAK only after the Byte Transfer Finished (BTF) bit of the same register has been set. 38.1.4 TC 1. Channel chaining skips first pulse for upper channel When chaining two channels using the Block Mode Register, the first pulse of the clock between the channels is skipped. Fix/Workaround Configure the lower channel with RA = 0x1 and RC = 0x2 to produce a dummy clock cycle for the upper channel. After the dummy cycle has been generated, indicated by the SR.CPCS bit, reconfigure the RA and RC registers for the lower channel with the real values. 38.1.5 CAT 1. CAT QMatrix sense capacitors discharged prematurely At the end of a QMatrix burst charging sequence that uses different burst count values for different Y lines, the Y lines may be incorrectly grounded for up to n-1 periods of the periph- 942 32142D–06/2013 ATUC64/128/256L3/4U eral bus clock, where n is the ratio of the PB clock frequency to the GCLK_CAT frequency. This results in premature loss of charge from the sense capacitors and thus increased variability of the acquired count values. Fix/Workaround Enable the 1kOhm drive resistors on all implemented QMatrix Y lines (CSA 1, 3, 5, 7, 9, 11, 13, and/or 15) by writing ones to the corresponding odd bits of the CSARES register. 2. Autonomous CAT acquisition must be longer than AST source clock period When using the AST to trigger CAT autonomous touch acquisition in sleep modes where the CAT bus clock is turned off, the CAT will start several acquisitions if the period of the AST source clock is larger than one CAT acquisition. One AST clock period after the AST trigger, the CAT clock will automatically stop and the CAT acquisition can be stopped prematurely, ruining the result. Fix/Workaround Always ensure that the ATCFG1.max field is set so that the duration of the autonomous touch acquisition is greater than one clock period of the AST source clock. 38.1.6 aWire 1. aWire MEMORY_SPEED_REQUEST command does not return correct CV The aWire MEMORY_SPEED_REQUEST command does not return a CV corresponding to the formula in the aWire Debug Interface chapter. Fix/Workaround Issue a dummy read to address 0x100000000 before issuing the MEMORY_SPEED_REQUEST command and use this formula instead: 38.2 Flash 1. Corrupted data in flash may happen after flash page write operations After a flash page write operation from an external programmer, reading (data read or code fetch) in flash may fail. This may lead to an exception or to others errors derived from this corrupted read access. Fix/Workaround Before any flash page write operation, each write in the page buffer must preceded by a write in the page buffer with 0xFFFF_FFFF content at any address in the page. 38.3 Rev. B 38.3.1 SCIF 1. The RC32K output on PA20 is not always permanently disabled The RC32K output on PA20 may sometimes re-appear. Fix/Workaround Before using RC32K for other purposes, the following procedure has to be followed in order to properly disable it: - Run the CPU on RCSYS - Disable the output to PA20 by writing a zero to PM.PPCR.RC32OUT - Enable RC32K by writing a one to SCIF.RC32KCR.EN, and wait for this bit to be read as one f sab 7f aw CV – 3 = ---------------- 943 32142D–06/2013 ATUC64/128/256L3/4U - Disable RC32K by writing a zero to SCIF.RC32KCR.EN, and wait for this bit to be read as zero. 2. PLLCOUNT value larger than zero can cause PLLEN glitch Initializing the PLLCOUNT with a value greater than zero creates a glitch on the PLLEN signal during asynchronous wake up. Fix/Workaround The lock-masking mechanism for the PLL should not be used. The PLLCOUNT field of the PLL Control Register should always be written to zero. 3. Writing 0x5A5A5A5A to the SCIF memory range will enable the SCIF UNLOCK feature The SCIF UNLOCK feature will be enabled if the value 0x5A5A5A5A is written to any location in the SCIF memory range. Fix/Workaround None. 38.3.2 WDT 1. WDT Control Register does not have synchronization feedback When writing to the Timeout Prescale Select (PSEL), Time Ban Prescale Select (TBAN), Enable (EN), or WDT Mode (MODE) fieldss of the WDT Control Register (CTRL), a synchronizer is started to propagate the values to the WDT clcok domain. This synchronization takes a finite amount of time, but only the status of the synchronization of the EN bit is reflected back to the user. Writing to the synchronized fields during synchronization can lead to undefined behavior. Fix/Workaround -When writing to the affected fields, the user must ensure a wait corresponding to 2 clock cycles of both the WDT peripheral bus clock and the selected WDT clock source. -When doing writes that changes the EN bit, the EN bit can be read back until it reflects the written value. 38.3.3 SPI 1. SPI data transfer hangs with CSR0.CSAAT==1 and MR.MODFDIS==0 When CSR0.CSAAT==1 and mode fault detection is enabled (MR.MODFDIS==0), the SPI module will not start a data transfer. Fix/Workaround Disable mode fault detection by writing a one to MR.MODFDIS. 2. Disabling SPI has no effect on the SR.TDRE bit Disabling SPI has no effect on the SR.TDRE bit whereas the write data command is filtered when SPI is disabled. Writing to TDR when SPI is disabled will not clear SR.TDRE. If SPI is disabled during a PDCA transfer, the PDCA will continue to write data to TDR until its buffer is empty, and this data will be lost. Fix/Workaround Disable the PDCA, add two NOPs, and disable the SPI. To continue the transfer, enable the SPI and PDCA. 3. SPI disable does not work in SLAVE mode SPI disable does not work in SLAVE mode. Fix/Workaround Read the last received data, then perform a software reset by writing a one to the Software Reset bit in the Control Register (CR.SWRST). 944 32142D–06/2013 ATUC64/128/256L3/4U 4. SPI bad serial clock generation on 2nd chip_select when SCBR=1, CPOL=1, and NCPHA=0 When multiple chip selects (CS) are in use, if one of the baudrates equal 1 while one (CSRn.SCBR=1) of the others do not equal 1, and CSRn.CPOL=1 and CSRn.NCPHA=0, then an additional pulse will be generated on SCK. Fix/Workaround When multiple CS are in use, if one of the baudrates equals 1, the others must also equal 1 if CSRn.CPOL=1 and CSRn.NCPHA=0. 5. SPI mode fault detection enable causes incorrect behavior When mode fault detection is enabled (MR.MODFDIS==0), the SPI module may not operate properly. Fix/Workaround Always disable mode fault detection before using the SPI by writing a one to MR.MODFDIS. 6. SPI RDR.PCS is not correct The PCS (Peripheral Chip Select) field in the SPI RDR (Receive Data Register) does not correctly indicate the value on the NPCS pins at the end of a transfer. Fix/Workaround Do not use the PCS field of the SPI RDR. 38.3.4 TWI 1. TWIS may not wake the device from sleep mode If the CPU is put to a sleep mode (except Idle and Frozen) directly after a TWI Start condition, the CPU may not wake upon a TWIS address match. The request is NACKed. Fix/Workaround When using the TWI address match to wake the device from sleep, do not switch to sleep modes deeper than Frozen. Another solution is to enable asynchronous EIC wake on the TWIS clock (TWCK) or TWIS data (TWD) pins, in order to wake the system up on bus events. 2. SMBALERT bit may be set after reset The SMBus Alert (SMBALERT) bit in the Status Register (SR) might be erroneously set after system reset. Fix/Workaround After system reset, clear the SR.SMBALERT bit before commencing any TWI transfer. 3. Clearing the NAK bit before the BTF bit is set locks up the TWI bus When the TWIS is in transmit mode, clearing the NAK Received (NAK) bit of the Status Register (SR) before the end of the Acknowledge/Not Acknowledge cycle will cause the TWIS to attempt to continue transmitting data, thus locking up the bus. Fix/Workaround Clear SR.NAK only after the Byte Transfer Finished (BTF) bit of the same register has been set. 38.3.5 PWMA 1. The SR.READY bit cannot be cleared by writing to SCR.READY The Ready bit in the Status Register will not be cleared when writing a one to the corresponding bit in the Status Clear register. The Ready bit will be cleared when the Busy bit is set. Fix/Workaround 945 32142D–06/2013 ATUC64/128/256L3/4U Disable the Ready interrupt in the interrupt handler when receiving the interrupt. When an operation that triggers the Busy/Ready bit is started, wait until the ready bit is low in the Status Register before enabling the interrupt. 38.3.6 TC 1. Channel chaining skips first pulse for upper channel When chaining two channels using the Block Mode Register, the first pulse of the clock between the channels is skipped. Fix/Workaround Configure the lower channel with RA = 0x1 and RC = 0x2 to produce a dummy clock cycle for the upper channel. After the dummy cycle has been generated, indicated by the SR.CPCS bit, reconfigure the RA and RC registers for the lower channel with the real values. 38.3.7 CAT 1. CAT QMatrix sense capacitors discharged prematurely At the end of a QMatrix burst charging sequence that uses different burst count values for different Y lines, the Y lines may be incorrectly grounded for up to n-1 periods of the peripheral bus clock, where n is the ratio of the PB clock frequency to the GCLK_CAT frequency. This results in premature loss of charge from the sense capacitors and thus increased variability of the acquired count values. Fix/Workaround Enable the 1kOhm drive resistors on all implemented QMatrix Y lines (CSA 1, 3, 5, 7, 9, 11, 13, and/or 15) by writing ones to the corresponding odd bits of the CSARES register. 2. Autonomous CAT acquisition must be longer than AST source clock period When using the AST to trigger CAT autonomous touch acquisition in sleep modes where the CAT bus clock is turned off, the CAT will start several acquisitions if the period of the AST source clock is larger than one CAT acquisition. One AST clock period after the AST trigger, the CAT clock will automatically stop and the CAT acquisition can be stopped prematurely, ruining the result. Fix/Workaround Always ensure that the ATCFG1.max field is set so that the duration of the autonomous touch acquisition is greater than one clock period of the AST source clock. 3. CAT consumes unnecessary power when disabled or when autonomous touch not used A CAT prescaler controlled by the ATCFG0.DIV field will be active even when the CAT module is disabled or when the autonomous touch feature is not used, thereby causing unnecessary power consumption. Fix/Workaround If the CAT module is not used, disable the CLK_CAT clock in the PM module. If the CAT module is used but the autonomous touch feature is not used, the power consumption of the CAT module may be reduced by writing 0xFFFF to the ATCFG0.DIV field. 38.3.8 aWire 1. aWire MEMORY_SPEED_REQUEST command does not return correct CV The aWire MEMORY_SPEED_REQUEST command does not return a CV corresponding to the formula in the aWire Debug Interface chapter. Fix/Workaround 946 32142D–06/2013 ATUC64/128/256L3/4U Issue a dummy read to address 0x100000000 before issuing the MEMORY_SPEED_REQUEST command and use this formula instead: 38.4 Flash 2. Corrupted data in flash may happen after flash page write operations After a flash page write operation from an external programmer, reading (data read or code fetch) in flash may fail. This may lead to an exception or to others errors derived from this corrupted read access. Fix/Workaround Before any flash page write operation, each write in the page buffer must preceded by a write in the page buffer with 0xFFFF_FFFF content at any address in the page. 38.5 Rev. A 38.5.1 Device 3. JTAGID is wrong The JTAGID reads 0x021DF03F for all devices. Fix/Workaround None. 38.5.2 FLASHCDW 1. General-purpose fuse programming does not work The general-purpose fuses cannot be programmed and are stuck at 1. Please refer to the Fuse Settings chapter in the FLASHCDW for more information about what functions are affected. Fix/Workaround None. 2. Set Security Bit command does not work The Set Security Bit (SSB) command of the FLASHCDW does not work. The device cannot be locked from external JTAG, aWire, or other debug accesses. Fix/Workaround None. 3. Flash programming time is longer than specified f sab 7f aw CV – 3 = ---------------- 947 32142D–06/2013 ATUC64/128/256L3/4U The flash programming time is now: Fix/Workaround None. 4. Power Manager 5. Clock Failure Detector (CFD) can be issued while turning off the CFD While turning off the CFD, the CFD bit in the Status Register (SR) can be set. This will change the main clock source to RCSYS. Fix/Workaround Solution 1: Enable CFD interrupt. If CFD interrupt is issues after turning off the CFD, switch back to original main clock source. Solution 2: Only turn off the CFD while running the main clock on RCSYS. 6. Sleepwalking in idle and frozen sleep mode will mask all other PB clocks If the CPU is in idle or frozen sleep mode and a module is in a state that triggers sleep walking, all PB clocks will be masked except the PB clock to the sleepwalking module. Fix/Workaround Mask all clock requests in the PM.PPCR register before going into idle or frozen mode. 4. Unused PB clocks are running Three unused PBA clocks are enabled by default and will cause increased active power consumption. Fix/Workaround Disable the clocks by writing zeroes to bits [27:25] in the PBA clock mask register. 38.5.3 SCIF 1. The RC32K output on PA20 is not always permanently disabled The RC32K output on PA20 may sometimes re-appear. Fix/Workaround Before using RC32K for other purposes, the following procedure has to be followed in order to properly disable it: - Run the CPU on RCSYS - Disable the output to PA20 by writing a zero to PM.PPCR.RC32OUT - Enable RC32K by writing a one to SCIF.RC32KCR.EN, and wait for this bit to be read as one - Disable RC32K by writing a zero to SCIF.RC32KCR.EN, and wait for this bit to be read as zero. 2. PLL lock might not clear after disable Table 38-1. Flash Characteristics Symbol Parameter Conditions Min Typ Max Unit TFPP Page programming time fCLK_HSB= 50MHz 7.5 ms TFPE Page erase time 7.5 TFFP Fuse programming time 1 TFEA Full chip erase time (EA) 9 TFCE JTAG chip erase time (CHIP_ERASE) fCLK_HSB= 115kHz 250 948 32142D–06/2013 ATUC64/128/256L3/4U Under certain circumstances, the lock signal from the Phase Locked Loop (PLL) oscillator may not go back to zero after the PLL oscillator has been disabled. This can cause the propagation of clock signals with the wrong frequency to parts of the system that use the PLL clock. Fix/Workaround PLL must be turned off before entering STOP, DEEPSTOP or STATIC sleep modes. If PLL has been turned off, a delay of 30us must be observed after the PLL has been enabled again before the SCIF.PLL0LOCK bit can be used as a valid indication that the PLL is locked. 3. PLLCOUNT value larger than zero can cause PLLEN glitch Initializing the PLLCOUNT with a value greater than zero creates a glitch on the PLLEN signal during asynchronous wake up. Fix/Workaround The lock-masking mechanism for the PLL should not be used. The PLLCOUNT field of the PLL Control Register should always be written to zero. 4. RCSYS is not calibrated The RCSYS is not calibrated and will run faster than 115.2kHz. Frequencies around 150kHz can be expected. Fix/Workaround If a known clock source is available the RCSYS can be runtime calibrated by using the frequency meter (FREQM) and tuning the RCSYS by writing to the RCCR register in SCIF. 5. Writing 0x5A5A5A5A to the SCIF memory range will enable the SCIF UNLOCK feature The SCIF UNLOCK feature will be enabled if the value 0x5A5A5A5A is written to any location in the SCIF memory range. Fix/Workaround None. 38.5.4 WDT 1. Clearing the Watchdog Timer (WDT) counter in second half of timeout period will issue a Watchdog reset If the WDT counter is cleared in the second half of the timeout period, the WDT will immediately issue a Watchdog reset. Fix/Workaround Use twice as long timeout period as needed and clear the WDT counter within the first half of the timeout period. If the WDT counter is cleared after the first half of the timeout period, you will get a Watchdog reset immediately. If the WDT counter is not cleared at all, the time before the reset will be twice as long as needed. 2. WDT Control Register does not have synchronization feedback When writing to the Timeout Prescale Select (PSEL), Time Ban Prescale Select (TBAN), Enable (EN), or WDT Mode (MODE) fieldss of the WDT Control Register (CTRL), a synchronizer is started to propagate the values to the WDT clcok domain. This synchronization takes a finite amount of time, but only the status of the synchronization of the EN bit is reflected back to the user. Writing to the synchronized fields during synchronization can lead to undefined behavior. Fix/Workaround -When writing to the affected fields, the user must ensure a wait corresponding to 2 clock cycles of both the WDT peripheral bus clock and the selected WDT clock source. -When doing writes that changes the EN bit, the EN bit can be read back until it reflects the written value. 949 32142D–06/2013 ATUC64/128/256L3/4U 38.5.5 GPIO 1. Clearing Interrupt flags can mask other interrupts When clearing interrupt flags in a GPIO port, interrupts on other pins of that port, happening in the same clock cycle will not be registered. Fix/Workaround Read the PVR register of the port before and after clearing the interrupt to see if any pin change has happened while clearing the interrupt. If any change occurred in the PVR between the reads, they must be treated as an interrupt. 38.5.6 SPI 1. SPI data transfer hangs with CSR0.CSAAT==1 and MR.MODFDIS==0 When CSR0.CSAAT==1 and mode fault detection is enabled (MR.MODFDIS==0), the SPI module will not start a data transfer. Fix/Workaround Disable mode fault detection by writing a one to MR.MODFDIS. 2. Disabling SPI has no effect on the SR.TDRE bit Disabling SPI has no effect on the SR.TDRE bit whereas the write data command is filtered when SPI is disabled. Writing to TDR when SPI is disabled will not clear SR.TDRE. If SPI is disabled during a PDCA transfer, the PDCA will continue to write data to TDR until its buffer is empty, and this data will be lost. Fix/Workaround Disable the PDCA, add two NOPs, and disable the SPI. To continue the transfer, enable the SPI and PDCA. 3. SPI disable does not work in SLAVE mode SPI disable does not work in SLAVE mode. Fix/Workaround Read the last received data, then perform a software reset by writing a one to the Software Reset bit in the Control Register (CR.SWRST). 4. SPI bad serial clock generation on 2nd chip_select when SCBR=1, CPOL=1, and NCPHA=0 When multiple chip selects (CS) are in use, if one of the baudrates equal 1 while one (CSRn.SCBR=1) of the others do not equal 1, and CSRn.CPOL=1 and CSRn.NCPHA=0, then an additional pulse will be generated on SCK. Fix/Workaround When multiple CS are in use, if one of the baudrates equals 1, the others must also equal 1 if CSRn.CPOL=1 and CSRn.NCPHA=0. 5. SPI mode fault detection enable causes incorrect behavior When mode fault detection is enabled (MR.MODFDIS==0), the SPI module may not operate properly. Fix/Workaround Always disable mode fault detection before using the SPI by writing a one to MR.MODFDIS. 6. SPI RDR.PCS is not correct The PCS (Peripheral Chip Select) field in the SPI RDR (Receive Data Register) does not correctly indicate the value on the NPCS pins at the end of a transfer. Fix/Workaround Do not use the PCS field of the SPI RDR. 950 32142D–06/2013 ATUC64/128/256L3/4U 38.5.7 TWI 1. TWIS may not wake the device from sleep mode If the CPU is put to a sleep mode (except Idle and Frozen) directly after a TWI Start condition, the CPU may not wake upon a TWIS address match. The request is NACKed. Fix/Workaround When using the TWI address match to wake the device from sleep, do not switch to sleep modes deeper than Frozen. Another solution is to enable asynchronous EIC wake on the TWIS clock (TWCK) or TWIS data (TWD) pins, in order to wake the system up on bus events. 2. SMBALERT bit may be set after reset The SMBus Alert (SMBALERT) bit in the Status Register (SR) might be erroneously set after system reset. Fix/Workaround After system reset, clear the SR.SMBALERT bit before commencing any TWI transfer. 3. Clearing the NAK bit before the BTF bit is set locks up the TWI bus When the TWIS is in transmit mode, clearing the NAK Received (NAK) bit of the Status Register (SR) before the end of the Acknowledge/Not Acknowledge cycle will cause the TWIS to attempt to continue transmitting data, thus locking up the bus. Fix/Workaround Clear SR.NAK only after the Byte Transfer Finished (BTF) bit of the same register has been set. 4. TWIS stretch on Address match error When the TWIS stretches TWCK due to a slave address match, it also holds TWD low for the same duration if it is to be receiving data. When TWIS releases TWCK, it releases TWD at the same time. This can cause a TWI timing violation. Fix/Workaround None. 5. TWIM TWALM polarity is wrong The TWALM signal in the TWIM is active high instead of active low. Fix/Workaround Use an external inverter to invert the signal going into the TWIM. When using both TWIM and TWIS on the same pins, the TWALM cannot be used. 38.5.8 PWMA 1. The SR.READY bit cannot be cleared by writing to SCR.READY The Ready bit in the Status Register will not be cleared when writing a one to the corresponding bit in the Status Clear register. The Ready bit will be cleared when the Busy bit is set. Fix/Workaround Disable the Ready interrupt in the interrupt handler when receiving the interrupt. When an operation that triggers the Busy/Ready bit is started, wait until the ready bit is low in the Status Register before enabling the interrupt. 38.5.9 TC 1. Channel chaining skips first pulse for upper channel When chaining two channels using the Block Mode Register, the first pulse of the clock between the channels is skipped. 951 32142D–06/2013 ATUC64/128/256L3/4U Fix/Workaround Configure the lower channel with RA = 0x1 and RC = 0x2 to produce a dummy clock cycle for the upper channel. After the dummy cycle has been generated, indicated by the SR.CPCS bit, reconfigure the RA and RC registers for the lower channel with the real values. 38.5.10 ADCIFB 1. ADCIFB DMA transfer does not work with divided PBA clock DMA requests from the ADCIFB will not be performed when the PBA clock is slower than the HSB clock. Fix/Workaround Do not use divided PBA clock when the PDCA transfers from the ADCIFB. 38.5.11 CAT 1. CAT QMatrix sense capacitors discharged prematurely At the end of a QMatrix burst charging sequence that uses different burst count values for different Y lines, the Y lines may be incorrectly grounded for up to n-1 periods of the peripheral bus clock, where n is the ratio of the PB clock frequency to the GCLK_CAT frequency. This results in premature loss of charge from the sense capacitors and thus increased variability of the acquired count values. Fix/Workaround Enable the 1kOhm drive resistors on all implemented QMatrix Y lines (CSA 1, 3, 5, 7, 9, 11, 13, and/or 15) by writing ones to the corresponding odd bits of the CSARES register. 2. Autonomous CAT acquisition must be longer than AST source clock period When using the AST to trigger CAT autonomous touch acquisition in sleep modes where the CAT bus clock is turned off, the CAT will start several acquisitions if the period of the AST source clock is larger than one CAT acquisition. One AST clock period after the AST trigger, the CAT clock will automatically stop and the CAT acquisition can be stopped prematurely, ruining the result. Fix/Workaround Always ensure that the ATCFG1.max field is set so that the duration of the autonomous touch acquisition is greater than one clock period of the AST source clock. 3. CAT consumes unnecessary power when disabled or when autonomous touch not used A CAT prescaler controlled by the ATCFG0.DIV field will be active even when the CAT module is disabled or when the autonomous touch feature is not used, thereby causing unnecessary power consumption. Fix/Workaround If the CAT module is not used, disable the CLK_CAT clock in the PM module. If the CAT module is used but the autonomous touch feature is not used, the power consumption of the CAT module may be reduced by writing 0xFFFF to the ATCFG0.DIV field. 4. CAT module does not terminate QTouch burst on detect The CAT module does not terminate a QTouch burst when the detection voltage is reached on the sense capacitor. This can cause the sense capacitor to be charged more than necessary. Depending on the dielectric absorption characteristics of the capacitor, this can lead to unstable measurements. Fix/Workaround Use the minimum possible value for the MAX field in the ATCFG1, TG0CFG1, and TG1CFG1 registers. 952 32142D–06/2013 ATUC64/128/256L3/4U 38.5.12 aWire 1. aWire MEMORY_SPEED_REQUEST command does not return correct CV The aWire MEMORY_SPEED_REQUEST command does not return a CV corresponding to the formula in the aWire Debug Interface chapter. Fix/Workaround Issue a dummy read to address 0x100000000 before issuing the MEMORY_SPEED_REQUEST command and use this formula instead: 38.5.13 Flash 5. Corrupted data in flash may happen after flash page write operations After a flash page write operation from an external programmer, reading (data read or code fetch) in flash may fail. This may lead to an exception or to others errors derived from this corrupted read access. Fix/Workaround Before any flash page write operation, each write in the page buffer must preceded by a write in the page buffer with 0xFFFF_FFFF content at any address in the page. 38.5.14 I/O Pins 1. PA05 is not 3.3V tolerant. PA05 should be grounded on the PCB and left unused if VDDIO is above 1.8V. Fix/Workaround None. 2. No pull-up on pins that are not bonded PB13 to PB27 are not bonded on UC3L0256/128, but has no pull-up and can cause current consumption on VDDIO/VDDIN if left undriven. Fix/Workaround Enable pull-ups on PB13 to PB27 by writing 0x0FFFE000 to the PUERS1 register in the GPIO. 3. PA17 has low ESD tolerance PA17 only tolerates 500V ESD pulses (Human Body Model). Fix/Workaround Care must be taken during manufacturing and PCB design. f sab 7f aw CV – 3 = ---------------- 953 32142D–06/2013 ATUC64/128/256L3/4U 39. Datasheet Revision History Please note that the referring page numbers in this section are referred to this document. The referring revision in this section are referring to the document revision. 39.1 Rev. D – 06/2013 39.2 Rev. C – 01/2012 39.3 Rev. B – 12/2011 39.4 Rev. A – 12/2011 1. Updated the datasheet with a new ATmel blue logo and the last page. 2. Added Flash errata. 1. Description: DFLL frequency is 20 to 150MHz, not 40 to 150MHz. 2. Block Diagram: GCLK_IN is input, not output. CAT SMP corrected from I/O to output. SPI NPCS corrected from output to I/O. 3, Package and Pinout: EXTINT0 in Signal Descriptions table is NMI. 4, Supply and Startup Considerations: In 1.8V single supply mode figure, the input voltage is 1.62-1.98V, not 1.98-3.6V. “On system start-up, the DFLL is disabled” is replaced by “On system start-up, all high-speed clocks are disabled”. 5, ADCIFB: PRND signal removed from block diagram. 6, Electrical Charateristics: Added 64-pin package information to I/O Pin Characteristics tables and Digital Clock Characteristics table. 7, Mechanical Characteristics: QFN48 Package Drawing updated. Note that the package drawing for QFN48 is correct in datasheet rev A, but wrong in rev B. Added notes to package drawings. 8. Summary: Removed Programming and Debugging chapter, added Processor and Architecture chapter. 1. JTAG Data Registers subchapter added in the Programming and Debugging chapter, containing JTAG IDs. 1. Initial revision. i 32142D–06/2013 ATUC64/128/256L3/4U Table of Contents Features ..................................................................................................... 1 1 Description ............................................................................................... 3 2 Overview ................................................................................................... 5 2.1 Block Diagram ...................................................................................................5 2.2 Configuration Summary .....................................................................................6 3 Package and Pinout ................................................................................. 7 3.1 Package .............................................................................................................7 3.2 See Section 3.3 for a description of the various peripheral signals. ................12 3.3 Signal Descriptions ..........................................................................................15 3.4 I/O Line Considerations ...................................................................................18 4 Processor and Architecture .................................................................. 21 4.1 Features ..........................................................................................................21 4.2 AVR32 Architecture .........................................................................................21 4.3 The AVR32UC CPU ........................................................................................22 4.4 Programming Model ........................................................................................26 4.5 Exceptions and Interrupts ................................................................................30 5 Memories ................................................................................................ 35 5.1 Embedded Memories ......................................................................................35 5.2 Physical Memory Map .....................................................................................35 5.3 Peripheral Address Map ..................................................................................36 5.4 CPU Local Bus Mapping .................................................................................37 6 Supply and Startup Considerations ..................................................... 39 6.1 Supply Considerations .....................................................................................39 6.2 Startup Considerations ....................................................................................44 7 Peripheral DMA Controller (PDCA) ...................................................... 45 7.1 Features ..........................................................................................................45 7.2 Overview ..........................................................................................................45 7.3 Block Diagram .................................................................................................46 7.4 Product Dependencies ....................................................................................46 7.5 Functional Description .....................................................................................47 7.6 Performance Monitors .....................................................................................49 7.7 User Interface ..................................................................................................51 ii 32142D–06/2013 ATUC64/128/256L3/4U 7.8 Module Configuration ......................................................................................79 8 USB Interface (USBC) ............................................................................ 81 8.1 Features ..........................................................................................................81 8.2 Overview ..........................................................................................................81 8.3 Block Diagram .................................................................................................81 8.4 I/O Lines Description .......................................................................................83 8.5 Product Dependencies ....................................................................................84 8.6 Functional Description .....................................................................................85 8.7 User Interface ...............................................................................................101 8.8 Module Configuration ....................................................................................134 9 Flash Controller (FLASHCDW) ........................................................... 135 9.1 Features ........................................................................................................135 9.2 Overview ........................................................................................................135 9.3 Product Dependencies ..................................................................................135 9.4 Functional Description ...................................................................................136 9.5 Flash Commands ..........................................................................................141 9.6 General-purpose Fuse Bits ............................................................................143 9.7 Security Bit ....................................................................................................146 9.8 User Interface ................................................................................................147 9.9 Fuse Settings .................................................................................................157 9.10 Serial Number ................................................................................................160 9.11 Module Configuration ....................................................................................160 10 Secure Access Unit (SAU) .................................................................. 162 10.1 Features ........................................................................................................162 10.2 Overview ........................................................................................................162 10.3 Block Diagram ...............................................................................................163 10.4 Product Dependencies ..................................................................................164 10.5 Functional Description ...................................................................................164 10.6 User Interface ................................................................................................168 10.7 Module Configuration ....................................................................................183 11 HSB Bus Matrix (HMATRIXB) .............................................................. 184 11.1 Features ........................................................................................................184 11.2 Overview ........................................................................................................184 11.3 Product Dependencies ..................................................................................184 11.4 Functional Description ...................................................................................184 iii 32142D–06/2013 ATUC64/128/256L3/4U 11.5 User Interface ................................................................................................188 11.6 Module Configuration ....................................................................................196 12 Interrupt Controller (INTC) .................................................................. 198 12.1 Features ........................................................................................................198 12.2 Overview ........................................................................................................198 12.3 Block Diagram ...............................................................................................198 12.4 Product Dependencies ..................................................................................199 12.5 Functional Description ...................................................................................199 12.6 User Interface ................................................................................................202 12.7 Module Configuration ....................................................................................206 12.8 Interrupt Request Signal Map ........................................................................206 13 Power Manager (PM) ............................................................................ 209 13.1 Features ........................................................................................................209 13.2 Overview ........................................................................................................209 13.3 Block Diagram ...............................................................................................210 13.4 I/O Lines Description .....................................................................................210 13.5 Product Dependencies ..................................................................................210 13.6 Functional Description ...................................................................................211 13.7 User Interface ................................................................................................220 13.8 Module Configuration ....................................................................................243 14 System Control Interface (SCIF) ......................................................... 244 14.1 Features ........................................................................................................244 14.2 Overview ........................................................................................................244 14.3 I/O Lines Description .....................................................................................244 14.4 Product Dependencies ..................................................................................244 14.5 Functional Description ...................................................................................245 14.6 User Interface ................................................................................................265 14.7 Module Configuration ....................................................................................318 15 Asynchronous Timer (AST) ................................................................ 322 15.1 Features ........................................................................................................322 15.2 Overview ........................................................................................................322 15.3 Block Diagram ...............................................................................................323 15.4 Product Dependencies ..................................................................................323 15.5 Functional Description ...................................................................................324 15.6 User Interface ................................................................................................330 iv 32142D–06/2013 ATUC64/128/256L3/4U 15.7 Module Configuration ....................................................................................351 16 Watchdog Timer (WDT) ....................................................................... 352 16.1 Features ........................................................................................................352 16.2 Overview ........................................................................................................352 16.3 Block Diagram ...............................................................................................352 16.4 Product Dependencies ..................................................................................352 16.5 Functional Description ...................................................................................353 16.6 User Interface ................................................................................................358 16.7 Module Configuration ....................................................................................364 17 External Interrupt Controller (EIC) ..................................................... 365 17.1 Features ........................................................................................................365 17.2 Overview ........................................................................................................365 17.3 Block Diagram ...............................................................................................365 17.4 I/O Lines Description .....................................................................................366 17.5 Product Dependencies ..................................................................................366 17.6 Functional Description ...................................................................................366 17.7 User Interface ................................................................................................370 17.8 Module Configuration ....................................................................................386 18 Frequency Meter (FREQM) .................................................................. 387 18.1 Features ........................................................................................................387 18.2 Overview ........................................................................................................387 18.3 Block Diagram ...............................................................................................387 18.4 Product Dependencies ..................................................................................387 18.5 Functional Description ...................................................................................388 18.6 User Interface ................................................................................................390 18.7 Module Configuration ....................................................................................401 19 General-Purpose Input/Output Controller (GPIO) ............................. 403 19.1 Features ........................................................................................................403 19.2 Overview ........................................................................................................403 19.3 Block Diagram ...............................................................................................403 19.4 I/O Lines Description .....................................................................................404 19.5 Product Dependencies ..................................................................................404 19.6 Functional Description ...................................................................................405 19.7 User Interface ................................................................................................410 19.8 Module Configuration ....................................................................................433 v 32142D–06/2013 ATUC64/128/256L3/4U 20 Universal Synchronous Asynchronous Receiver Transmitter (USART) 434 20.1 Features ........................................................................................................434 20.2 Overview ........................................................................................................434 20.3 Block Diagram ...............................................................................................435 20.4 I/O Lines Description ....................................................................................436 20.5 Product Dependencies ..................................................................................436 20.6 Functional Description ...................................................................................437 20.7 User Interface ................................................................................................463 20.8 Module Configuration ....................................................................................485 21 Serial Peripheral Interface (SPI) ......................................................... 486 21.1 Features ........................................................................................................486 21.2 Overview ........................................................................................................486 21.3 Block Diagram ...............................................................................................487 21.4 Application Block Diagram .............................................................................487 21.5 I/O Lines Description .....................................................................................488 21.6 Product Dependencies ..................................................................................488 21.7 Functional Description ...................................................................................488 21.8 User Interface ................................................................................................499 21.9 Module Configuration ....................................................................................526 22 Two-wire Master Interface (TWIM) ...................................................... 527 22.1 Features ........................................................................................................527 22.2 Overview ........................................................................................................527 22.3 List of Abbreviations ......................................................................................528 22.4 Block Diagram ...............................................................................................528 22.5 Application Block Diagram .............................................................................529 22.6 I/O Lines Description .....................................................................................529 22.7 Product Dependencies ..................................................................................529 22.8 Functional Description ...................................................................................531 22.9 User Interface ................................................................................................543 22.10 Module Configuration ....................................................................................560 23 Two-wire Slave Interface (TWIS) ......................................................... 561 23.1 Features ........................................................................................................561 23.2 Overview ........................................................................................................561 23.3 List of Abbreviations ......................................................................................562 vi 32142D–06/2013 ATUC64/128/256L3/4U 23.4 Block Diagram ...............................................................................................562 23.5 Application Block Diagram .............................................................................563 23.6 I/O Lines Description .....................................................................................563 23.7 Product Dependencies ..................................................................................563 23.8 Functional Description ...................................................................................564 23.9 User Interface ................................................................................................574 23.10 Module Configuration ....................................................................................590 24 Inter-IC Sound Controller (IISC) .......................................................... 591 24.1 Features ........................................................................................................591 24.2 Overview ........................................................................................................591 24.3 Block Diagram ...............................................................................................592 24.4 I/O Lines Description .....................................................................................592 24.5 Product Dependencies ..................................................................................592 24.6 Functional Description ...................................................................................593 24.7 IISC Application Examples ............................................................................598 24.8 User Interface ................................................................................................600 24.9 Module configuration .....................................................................................614 25 Pulse Width Modulation Controller (PWMA) ..................................... 615 25.1 Features ........................................................................................................615 25.2 Overview ........................................................................................................615 25.3 Block Diagram ...............................................................................................616 25.4 I/O Lines Description .....................................................................................616 25.5 Product Dependencies ..................................................................................616 25.6 Functional Description ...................................................................................617 25.7 User Interface ................................................................................................623 25.8 Module Configuration ....................................................................................641 26 Timer/Counter (TC) .............................................................................. 642 26.1 Features ........................................................................................................642 26.2 Overview ........................................................................................................642 26.3 Block Diagram ...............................................................................................643 26.4 I/O Lines Description .....................................................................................643 26.5 Product Dependencies ..................................................................................643 26.6 Functional Description ...................................................................................644 26.7 User Interface ................................................................................................659 26.8 Module Configuration ....................................................................................682 vii 32142D–06/2013 ATUC64/128/256L3/4U 27 Peripheral Event System ..................................................................... 683 27.1 Features ........................................................................................................683 27.2 Overview ........................................................................................................683 27.3 Peripheral Event System Block Diagram .......................................................683 27.4 Functional Description ...................................................................................683 27.5 Application Example ......................................................................................686 28 Audio Bit Stream DAC (ABDACB) ...................................................... 687 28.1 Features ........................................................................................................687 28.2 Overview ........................................................................................................687 28.3 Block Diagram ...............................................................................................687 28.4 I/O Lines Description .....................................................................................688 28.5 Product Dependencies ..................................................................................688 28.6 Functional Description ...................................................................................689 28.7 User Interface ................................................................................................696 28.8 Module Configuration ....................................................................................710 29 ADC Interface (ADCIFB) ...................................................................... 711 29.1 Features ........................................................................................................711 29.2 Overview ........................................................................................................711 29.3 Block Diagram ...............................................................................................712 29.4 I/O Lines Description .....................................................................................713 29.5 Product Dependencies ..................................................................................713 29.6 Functional Description ...................................................................................714 29.7 Resistive Touch Screen .................................................................................718 29.8 Operating Modes ...........................................................................................724 29.9 User Interface ................................................................................................726 29.10 Module Configuration ....................................................................................745 30 Analog Comparator Interface (ACIFB) ............................................... 746 30.1 Features ........................................................................................................746 30.2 Overview ........................................................................................................746 30.3 Block Diagram ...............................................................................................747 30.4 I/O Lines Description .....................................................................................747 30.5 Product Dependencies ..................................................................................748 30.6 Functional Description ...................................................................................749 30.7 Peripheral Event Triggers ..............................................................................754 30.8 AC Test mode ................................................................................................754 viii 32142D–06/2013 ATUC64/128/256L3/4U 30.9 User Interface ................................................................................................755 30.10 Module Configuration ....................................................................................769 31 Capacitive Touch Module (CAT) ......................................................... 770 31.1 Features ........................................................................................................770 31.2 Overview ........................................................................................................770 31.3 Block Diagram ...............................................................................................771 31.4 I/O Lines Description .....................................................................................771 31.5 Product Dependencies ..................................................................................772 31.6 Functional Description ...................................................................................774 31.7 User Interface ................................................................................................781 31.8 Module Configuration ....................................................................................816 32 Glue Logic Controller (GLOC) ............................................................ 817 32.1 Features ........................................................................................................817 32.2 Overview ........................................................................................................817 32.3 Block Diagram ...............................................................................................817 32.4 I/O Lines Description .....................................................................................818 32.5 Product Dependencies ..................................................................................818 32.6 Functional Description ...................................................................................818 32.7 User Interface ................................................................................................820 32.8 Module Configuration ....................................................................................825 33 aWire UART (AW) ................................................................................. 826 33.1 Features ........................................................................................................826 33.2 Overview ........................................................................................................826 33.3 Block Diagram ...............................................................................................826 33.4 I/O Lines Description .....................................................................................827 33.5 Product Dependencies ..................................................................................827 33.6 Functional Description ...................................................................................827 33.7 User Interface ................................................................................................830 33.8 Module Configuration ....................................................................................843 34 Programming and Debugging ............................................................ 844 34.1 Overview ........................................................................................................844 34.2 Service Access Bus .......................................................................................844 34.3 On-Chip Debug ..............................................................................................847 34.4 JTAG and Boundary-scan (JTAG) .................................................................855 34.5 JTAG Instruction Summary ...........................................................................863 ix 32142D–06/2013 ATUC64/128/256L3/4U 34.6 aWire Debug Interface (AW) .........................................................................880 35 Electrical Characteristics .................................................................... 897 35.1 Absolute Maximum Ratings* .........................................................................897 35.2 Supply Characteristics ...................................................................................897 35.3 Maximum Clock Frequencies ........................................................................898 35.4 Power Consumption ......................................................................................898 35.5 I/O Pin Characteristics ...................................................................................902 35.6 Oscillator Characteristics ...............................................................................905 35.7 Flash Characteristics .....................................................................................910 35.8 ABDACB Electrical Characteristics. .............................................................911 35.9 Analog Characteristics ...................................................................................912 35.10 Timing Characteristics ...................................................................................921 36 Mechanical Characteristics ................................................................. 931 36.1 Thermal Considerations ................................................................................931 36.2 Package Drawings .........................................................................................932 36.3 Soldering Profile ............................................................................................937 37 Ordering Information ........................................................................... 938 38 Errata ..................................................................................................... 940 38.1 Rev. C ............................................................................................................940 38.2 Flash ..............................................................................................................942 38.3 Rev. B ............................................................................................................942 38.4 Flash .............................................................................................................946 38.5 Rev. A ............................................................................................................946 39 Datasheet Revision History ................................................................ 953 39.1 Rev. D – 06/2013 ...........................................................................................953 39.2 Rev. C – 01/2012 ...........................................................................................953 39.3 Rev. B – 12/2011 ...........................................................................................953 39.4 Rev. A – 12/2011 ...........................................................................................953 Table of Contents....................................................................................... i Atmel Corporation 1600 Technology Drive San Jose, CA 95110 USA Tel: (+1) (408) 441-0311 Fax: (+1) (408) 487-2600 www.atmel.com Atmel Asia Limited Unit 01-5 & 16, 19F BEA Tower, Millennium City 5 418 Kwun Tong Roa Kwun Tong, Kowloon HONG KONG Tel: (+852) 2245-6100 Fax: (+852) 2722-1369 Atmel Munich GmbH Business Campus Parkring 4 D-85748 Garching b. Munich GERMANY Tel: (+49) 89-31970-0 Fax: (+49) 89-3194621 Atmel Japan G.K. 16F Shin-Osaki Kangyo Bldg 1-6-4 Osaki, Shinagawa-ku Tokyo 141-0032 JAPAN Tel: (+81) (3) 6417-0300 Fax: (+81) (3) 6417-0370 © 2013 Atmel Corporation. All rights reserved. / Rev.: 32142D–AVR32–06/2013 Atmel®, logo and combinations thereof, AVR®, picoPower®, QTouch®, AKS® and others are registered trademarks or trademarks of Atmel Corporation or its subsidiaries. Other terms and product names may be trademarks of others. Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.

USB Demonstrations Help MPLAB Harmony Integrated Software Framework © 2013-2018 Microchip Technology Inc. All rights reserved. Volume I: Getting Started With MPLAB Harmony Libraries and Applications This volume introduces the MPLAB® Harmony Integrated Software Framework. Description MPLAB Harmony is a layered framework of modular libraries that provide flexible and interoperable software "building blocks" for developing embedded PIC32 applications. MPLAB Harmony is also part of a broad and expandable ecosystem, providing demonstration applications, third-party offerings, and convenient development tools, such as the MPLAB Harmony Configurator (MHC), which integrate with the MPLAB X IDE and MPLAB XC32 language tools. Legal Notices Please review the Software License Agreement prior to using MPLAB Harmony. It is the responsibility of the end-user to know and understand the software license agreement terms regarding the Microchip and third-party software that is provided in this installation. A copy of the agreement is available in the /doc folder of your MPLAB Harmony installation. The OPENRTOS® demonstrations provided in MPLAB Harmony use the OPENRTOS evaluation license, which is meant for demonstration purposes only. Customers desiring development and production on OPENRTOS must procure a suitable license. Please refer to one of the following documents, which are located in the /third_party/rtos/OPENRTOS/Documents folder of your MPLAB Harmony installation, for information on obtaining an evaluation license for your device: • OpenRTOS Click Thru Eval License PIC32MXxx.pdf • OpenRTOS Click Thru Eval License PIC32MZxx.pdf TIP! Throughout this documentation, occurrences of refer to the default MPLAB Harmony installation path: • Windows: C:/microchip/harmony/ • Mac OS/Linux: ~/microchip/harmony/ Volume I: Getting Started With MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 2 Applications Help This section provides information on the various application demonstrations that are included in MPLAB Harmony. Description Applications determine how MPLAB Harmony libraries (device drivers, middleware, and system services) are used to do something useful. In a MPLAB Harmony system, there may be one main application, there may be multiple independent applications or there may be one or more Operating System (OS) specific applications. Applications interact with MPLAB Harmony libraries through well defined interfaces. Applications may operate in a strictly polling environment, they may be interrupt driven, they may be executed in OS-specific threads, or they may be written so as to be flexible and easily configured for any of these environments. Applications generally fit into one of the following categories. Demonstration Applications Demonstration applications are provided (with MPLAB Harmony or in separate installations) to demonstrate typical or interesting usage models of one or more MPLAB Harmony libraries. Demonstration applications can demonstrate realistic solutions to real-life problems. Sample Applications Sample applications are extremely simple applications provided with MPLAB Harmony as examples of how to use individual features of a library. They will not normally accomplish anything useful on their own. They are provided primarily as documentation to show how to use a library. USB Demonstrations This section provides descriptions of the USB demonstrations. MPLAB Harmony is available for download from the Microchip website by visiting: http://www.microchip.com/mplabharmony. Once you are on the site, click the Downloads tab to access the appropriate download for your operating system. For additional information on this demonstration, refer to the “Applications Help” section in the MPLAB Harmony Help. Introduction USB Library Demonstration Applications Help Description This distribution package contains a variety of USB-related firmware projects that demonstrate the capabilities of the MPLAB Harmony USB stack. This section describes the hardware requirement and procedures to run these firmware projects on Microchip demonstration and development boards. To know more about the MPLAB Harmony USB stack and configuring the USB stack and the APIs provided by the USB stack, refer to the USB Library documentation. Program, Data Memory, and Stack Component Memory Refer to USB Device Stack Demonstration Application Program and Data Memory Requirements and USB Device Stack Component Memory Requirements for important memory information. Pen Drive Tests Refer to USB MSD Host USB Pen Drive Tests for information on the tests conducted on USB Flash devices. USB Device Stack Demonstration Application Program and Data Memory Requirements Provides information on program and data memory requirements, as well as pen drive test specifications. Description Program Memory and Data Memory Requirements with -O1 Optimization The following table shows the program memory and data memory requirements of the USB Device Stack demonstration applications. All size figures are in bytes. Demonstration applications were compiled with the MPLAB XC32 C/C++ Compiler, v1.40, with –O1 optimization. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 3 Note: The msd_basic, cdc_msd_basic, and the hid_msd_basic demonstrations use the PIC32 program Flash memory as the MSD storage media. The difference in Data Memory requirements between the PIC32MX and PIC32MZ microcontrollers for these demonstration examples, is due to an application demonstration buffer whose size is equal to the erase page size of the PIC32 microcontroller. On the PIC32MX795F512L, this size is 4096 bytes. On the PIC32MZ2048ECH144, the erase page size is 16 KB. Program Memory and Data Memory Requirements with -Os Optimization The following table shows the program memory and data memory requirements of the USB Device Stack demonstration applications. All size figures are in bytes. Demonstration applications were compiled with the MPLAB XC32 C/C++ Compiler, v1.40, with –Os optimization. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 4 USB Device Stack Component Memory Requirements Provides memory requirements. Description The following table shows the Program and Data Memory requirements for individual components in the MPLAB Harmony USB Device Stack. Device Stack Component Program Memory Data Memory Device Layer 5688 184 CDC Function Driver 2420 64 + (36 * Queue Size) MSD Function Driver 5352 217 HID Function Driver 2376 40 + (36 * Queue Size) Vendor 912 8 + (36 * Queue Size) PIC32MX USB Driver 5636 144 + (32 * Number of Endpoints) PIC32MZ USB Driver 10244 192 + (32 * Number of Endpoints) Notes: 1. Memory requirements (in bytes) for a single instance. 2. Size measured for USB Device Stack Components in MPLAB Harmony. 3. Data Memory does not include function call stack memory size. USB MSD Host USB Pen Drive Tests Provides pen drive test specifications. Description USB MSD Host USB Pen Drive Tests The following table lists the commercially available USB pen drives, which have been tested to successfully enumerate with the MSD Host Driver Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 5 in the MPLAB Harmony USB Host. Note that if the USB pen drive you are using in not included in the table, this indicates that this USB pen drive has not been tested with the MSD Host Driver. However, the USB pen drive could still potentially work with MSD Host Driver. Some USB pen drives in this table did not have their manufacturer or model data available. The USB Pen drives were tested with the msd_basic USB Host demonstration in the latest version of the MPLAB Harmony USB Host Stack. VID PID Manufacturer Model/Drive Capacity 0x1B1C 0x1A0F Corsair Components Flash Voyager Go 8 GB 0x03F0 0x0AB7 Hewlett-Packard 64 GB 0xABCD 0x1234 Microchip Technology Inc. 4 GB 0x125F 0xCB10 Adata Dashdrive UV100 8 GB 0x8644 0x8003 Verico T Series 16 GB 0x8564 0x1000 Transcend USB 3.0 32 GB 0x0951 0x16A7 Dell Kingston Technology 16 GB 0x0718 0x0704 Imation 16 GB Pen Drive 0x048D 0x1168 iBall Jaldi 16 GB Pen Drive 0x058F 0x6366 Alcor Micro AXL 32 GB 0x154B 0x005B PNY Cube 16 GB 0x0930 0x6544 Toshiba Hatabusa Pen Drive 8 GB 0x058F 0x6387 Alcor ZipMem 16 GB 0x090C 0x1000 Silicon Motion Inc. Axl 8GB 0x18A5 0x0245 Verbatim Store N Go Audio USB 8 GB 0x05DC 0xC75C Lexar USB Pen Drive 8 GB 0x1005 0xb113 Apacer 8 GB (AH233) 0x054C 0x06B0 Sony 8 GB 0x054C 0x0862 Sony Micro Vault USM-V 8 GB 0x0781 0x557c SanDisk 8 GB 0x1E4E 0x3257 Etron iBall 16 GB 0x1EC9 0x0101 Moserbaer Swivel 16 GB Pen Drive 0x0BDA 0x0109 SanDisk Standard A and Mini-B connector 16 GB 0x1908 0x1320 ZBEL Wrist Band Flash Drive 4 GB 0x0951 0x1665 Kingston Data Traveler SE9 16 GB USB HID Host Keyboard and Mouse Tests Provides information on tested USB keyboard and mouse devices. Description The following table lists the commercially available USB keyboard and mouse devices, which have been tested to successfully enumerate with the HID Host Driver in the MPLAB Harmony USB Host. Note that if the USB HID device you are using in not included in the table, this indicates that this USB HID device has not been tested, but could still potentially work with the HID Host Driver. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 6 Note: The above tests have been performed only on the PIC32M family of devices. Demonstration Application Configurations This topic provides information on the available USB demonstration project configurations. Description The available USB Demonstration application MPLAB X IDE projects feature support for multiple configurations. Selecting these configurations allow for the demonstration projects to run across different PIC32 microcontrollers and development boards. The following project configurations are available: Configuration name Description pic32mx_usb_sk2_int_dyn Selecting this configuration will set up the demonstration application to run on the PIC32 USB Starter Kit II development board, with the PIC32MX795F512L microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mx_usb_sk2_poll_dyn Selecting this configuration will set up the demonstration application to run on the PIC32 USB Starter Kit II development board, with the PIC32MX795F512L microcontroller. The USB Stack will be configured for Polled mode operation and the USB driver will be configured for Dynamic operation mode. pic32mx_usb_sk3_int_dyn Selecting this configuration will set up the demonstration application to run on the PIC32 USB Starter Kit III development board, with the PIC32MX470F512L microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mx_bt_sk_int_dyn Selecting this configuration will set up the demonstration application to run on the PIC32 Bluetooth Starter Kit development board, with the PIC32MX270F256D microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for dynamic operation mode. pic32mz_da_sk_intddr_int_dyn Selecting this configuration will set up the demonstration application to run on the PIC32MZ Embedded Graphics with Internal DRAM (DA) Starter Kit development board, with the PIC32MZ2064DAH169 microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mz_ec_sk_int_dyn Selecting this configuration will set up the demonstration application to run on the PIC32MZ EC Starter Kit development board, with the PIC32MZ2048ECH144 microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mz_ec_sk_poll_dyn Selecting this configuration will set up the demonstration application to run on the PIC32MZ EC Starter Kit development board, with the PIC32MC2048ECH144 microcontroller. The USB Stack will be configured for Polled mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mz_ec_sk_meb2_int_dyn Selecting this configuration will set up the demonstration application to run on the PIC32MZ EC Starter Kit, with the PIC32MZ2048ECH144 microcontroller board attached to the MEB II. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mz_ef_sk_int_dyn Selecting this configuration will set up the demonstration application to run on the PIC32MZ EF Starter Kit, with the PIC32MZ2048EFM144 microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 7 pic32mz_ef_sk_poll_dyn Selecting this configuration will set up the demonstration application to run on the PIC32MZ EF Starter Kit development board, with the PIC32MZ2048EFM144 microcontroller. The USB Stack will be configured for Polled mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mx795_pim_e16_int_dyn Selecting this configuration will set up the demonstration application to run on the Explorer 16 Development Board along with the PIC32MX795F512L microcontroller Plug In Module and USB PICtail Plus Daughter Board. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mx460_pim_e16_int_dyn Selecting this configuration will set up the demonstration application to run on the Explorer 16 Development Board along with the PIC32MX460F512L microcontroller Plug In Module and USB PICtail Plus Daughter Board. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mx470_curiosity Selecting this configuration will set up the demonstration application to run on the PIC32MX470 Curiosity Development Board, with the PIC32MX470F512H microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mz_ef_curiosity Selecting this configuration will set up the demonstration application to run on the PIC32MZ EF Curiosity Development Board, with the PIC32MZ2048EFM100 microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mk_evk_int_dyn Selecting this configuration will set up the demonstration application to run on the PIC32MK GP Development Board, with the PIC32MK1024GPE100 microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mx_xlp_sk_int_dyn Selecting this configuration will set up the demonstration application to run on the PIC32MX XLP Starter Kit, with the PIC32MX274F256D microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. chipkit_wf32 Selecting this configuration will set up the demonstration application to run on the chipKIT WF32 Wi-Fi Development Board, with the PIC32MZ2048EFG100 microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. chipkit_wifire Selecting this configuration will set up the demonstration application to run on the chipKIT Wi-FIRE Development Board, with the PIC32MX275F256D microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. The following figure shows how a configuration can be selected in MPLAB X IDE. Alternatively, the active configuration can be selected in the Project Properties. USB Device Demonstrations Matrix The following table shows the availability of a configuration across available USB Device demonstration applications. Green indicates support. Red indicates no support. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 8 USB Host Demonstration Matrix The following table shows the availability of a configuration across available USB Host demonstration applications. Green indicates support. Red indicates no support. USB Multiple Controller Demonstration Matrix The following table shows the availability of a configuration across available USB Multiple Controller Demonstration applications. Green indicates support. Red indicates no support. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 9 Demonstrations The USB Demonstrations are grouped into USB Device Stack, USB Host Stack, USB Dual Role, and USB demonstrations that make use of multiple USB controllers on certain PIC32 family devices. Device This section describes the USB Device demonstrations. Description The MPLAB Harmony USB Device Stack demonstration applications uses LEDs on the development board to indicate the USB state of the device. The following table provides details on the development board specific LEDs and the USB Device State these indicate when active. This indication scheme is implemented by all USB Device Stack Demonstration applications. USB Device State and LED Indication Demonstration Board Reset State Configured State Suspended State Explorer 16 Development Board and PIM D3, D4 D5 D4, D5 PIC32 USB Starter Kit II LED1, LED2 LED3 LED2, LED3 PIC32MZ Embedded Connectivity (EC) Starter Kit LED1, LED2 LED3 LED2, LED3 PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit LED1, LED2 LED3 LED2, LED3 PIC32 USB Starter Kit III LED1, LED2 LED3 LED2, LED3 PIC32 Bluetooth Starter Kit Red LED, Green LED Blue LED Green LED, Blue LED PIC32MX470 Curiosity Development Board LED1, LED2 LED3 LED2, LED3 PIC32MZ EF Curiosity Development Board LED1, LED2 LED3 LED2, LED3 cdc_com_port_dual Demonstrates a USB CDC device, emulating dual serial COM ports - one looping back into the other. Description This demonstration application creates a USB CDC Device that enumerates as two serial ports on the USB Host personal computer. This application demonstrates the ability of the MPLAB Harmony USB Device Stack to support multiple instances of the same Device class. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB CDC Device Dual COM Port Demonstration. Description To build this project, you must open the cdc_com_port_dual.X project in MPLAB X IDE, and then select the desired configuration. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 10 The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/cdc_com_port_dual. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location cdc_com_port_dual.X /apps/usb/device/cdc_com_port_dual/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx460_pim_e16_int_dyn pic32mx460_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration on the Explorer 16 Development Board configured for Interrupt mode and dynamic operation. This configuration also requires PIC32MX460F512L Plug-In Module (PIM) and the USB PICtail Plus Daughter Board. pic32mx_bt_sk_int_dyn pic32mx_bt_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 Bluetooth Starter Kit configured for Interrupt mode and dynamic operation. pic32mx_usb_sk3_int_dyn pic32mx_usb_sk3 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit III configured for Interrupt mode and dynamic operation. pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mx_xlp_sk_int_dyn pic32mx_xlp_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MX XLP Starter Kit configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. pic32mx470_curiosity pic32mx470_curiosity Select this MPLAB X IDE project configuration to run the demonstration application to run on the PIC32MX470 Curiosity Development Board, with the PIC32MX470F512H microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mz_ef_curiosity pic32mz_ef_curiosity Select this MPLAB X IDE project configuration to run the demonstration application to run on the PIC32MZ EF Curiosity Development Board, with the PIC32MZ2048EFM100 microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II Remove jumper JP2. PIC32MZ EC Starter Kit Remove jumper JP1. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32MX XLP Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32 USB Starter Kit III Remove jumper JP1. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 11 PIC32 Bluetooth Starter Kit Jumper J8 should either be shorted between pins 2 and 3 or should be completely open. PIC32MX460F512L PIM Jumper J10 should be removed. This plug-in module should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be connected to the edge connector J9. On the Explorer 16 Development Board: • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place • Jumper JP2 and JP4 should be removed On the PIC32MX460F512L PIM: • Keep jumper J10 open • Keep all jumpers in J9 open PIC32MX470 Curiosity Development Board • Ensure that a jumper is placed at 4-3 on J8, to select supply from debug USB connector. • Power the PIC32MX470 Curiosity Development Board from a Host PC through a Type-A male to mini-B USB cable connected to Mini-B port (J3). • Ensure that jumper is not present in the J13 header to use the Curiosity board in device mode. • Plug in a USB cable with a micro-B type connector to Micro-B port (J12), and plug the other end into your computer. PIC32MZ EF Curiosity Development Board • Ensure that a jumper is placed at 4-3 on J8, to select supply from debug USB connector. • Power the PIC32MZ EF Curiosity Development Board from a Host PC through a Type-A male to micro-B USB cable connected to Micro-B port (J3). Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 12 • Ensure that jumper is not present in the J13 header to use the Curiosity board in device mode. • Plug in a USB cable with a micro-B type connector to Micro-B port (J12), and plug the other end into your computer. Running the Demonstration Provides instructions on how to build and run the CDC Dual COM Port demonstration. Description This demonstration allows the device to appear like dual serial (COM) ports to the host. Do the following to run this demonstration: 1. First compile and program the target device. While compiling, select the appropriate MPLAB X IDE project configuration based on the demonstration board. Refer to Building the Application for details. 2. Attach the device to the host. If the host is a personal computer and this is the first time you have plugged this device into the computer you may be prompted for a .inf file. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 13 3. Select the "Install from a list or specific location (Advanced)" option. Specify the /apps/usb/device/cdc_com_port_dual/inf directory. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 14 Note: As an option, to specify the driver, you may open the device manager and expand the Ports (COM & LPT) tab, and right click on “Update Driver Software…” Verify that the enumerated USB device is seen as a virtual USB serial comport in Device Manager. 4. Once the device is successfully installed, open up two instances of a terminal program, such as HyperTerminal. Select the appropriate COM port for each of these terminal instances. The following screen shot shows the COM port selection for the Tera Term terminal program. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 15 5. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. 6. To run the demonstration, turn on local echo on both the terminals. For Tera Term terminal application, navigate to Setup->Terminal to turn on local echo. Type a character or string in one terminal window. The same character or string appears on the second terminal window. Similarly, any character typed in the second window appears in the first window. The following screen shot shows two instances of Tera Term. Note: Some terminal programs, like HyperTerminal, require users to click the disconnect button before removing the device from the computer. Failing to do so may result in having to close and open the program again to reconnect to the device. cdc_com_port_single Demonstrates a USB CDC device, emulating a serial COM port. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 16 Description This demonstration application creates a USB CDC Device that enumerates as a single COM port on the host personal computer. The application demonstrates two-way communication between the USB device and the personal computer host. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB CDC Device Single COM Port Demonstration. Description To build this project, you must open the cdc_com_port_single.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/cdc_com_port_single. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location cdc_com_port_single.X /apps/usb/device/cdc_com_port_single/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx460_pim_e16_int_dyn pic32mx460_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration on the Explorer 16 Development Board configured for Interrupt mode and dynamic operation. This configuration also requires PIC32MX460F512L Plug-In Module (PIM) and the USB PICtail Plus Daughter Board. pic32mx_usb_sk2_poll_dyn pic32mx_bt_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II with the USB Device Stack configured for Polled mode and dynamic operation. pic32mx_usb_sk3_int_dyn pic32mx_usb_sk3 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit III configured for Interrupt mode and dynamic operation. pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_da_sk_intddr_int_dyn pic32mz_da_sk_intddr Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Graphics with Internal DRAM (DA) Starter Kit configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn_micromips pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured in microMIPS mode for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_poll_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit with the USB Device Stack configured for Polled mode and dynamic operation. pic32mx_125_sk_int_dyn pic32mx_125_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MX1/2/5 Starter Kit with the USB Device Stack configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II Remove jumper JP2. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 17 PIC32MZ Embedded Graphics with Internal DRAM (DA) Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32 USB Starter Kit III Remove jumper JP1. PIC32MX460F512L PIM Jumper J10 should be removed. This plug-in module should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be connected to the edge connector J9. On the Explorer 16 Development Board: • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place • Jumper JP2 and JP4 should be removed On the PIC32MX460F512L PIM: • Keep jumper J10 open • Keep all jumpers in J9 open PIC32WK Wi-Fi Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions on how to build and run the CDC Single COM Port demonstration. Description This demonstration allows the device to appear like a serial (COM) port to the host. Do the following to run this demonstration: 1. First compile and program the target device. While compiling, select the appropriate MPLAB X IDE project configuration based on the demonstration board. Refer to Building the Application for details. 2. Attach the device to the host. If the host is a personal computer and this is the first time you have plugged this device into the computer, you may be prompted for a .inf file. 3. Select the "Install from a list or specific location (Advanced)" option. Specify the /apps/usb/device/cdc_com_port_single/inf directory. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 18 4. Once the device is successfully installed, open up a terminal program, such as HyperTerminal and select the appropriate COM port. On most machines this will be COM5 or higher. Set the communication properties to 9600 baud, 1 Stop bit and No parity, with Flow Control set to None. 5. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. 6. Once connected to the device, there are two ways to run this example project: • a) Typing a key in the terminal window will result in the attached device echoing the next letter. Therefore, if the letter 'b' is pressed, the device will echo 'c'. • b) If the push button is pressed, the device will echo "PUSH BUTTON PRESSED" to the terminal window. The following table shows the switch buttons to be pressed for different demonstration boards. Demonstration Board Button PIC32 USB Starter Kit II PIC32 USB Starter Kit III PIC32MZ Embedded Graphics with Internal DRAM (DA) Starter Kit PIC32MZ Embedded Connectivity (EC) Starter Kit PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit PIC32WK Wi-Fi Starter Kit SW1 Explorer 16 Development Board S3 Note: Some terminal programs, like HyperTerminal, require users to click the disconnect button before removing the device from the computer. Failing to do so may result in having to close and open the program again to reconnect to the device. cdc_msd_basic Demonstrates a composite USB device emulating a COM port and Flash drive. Description This demonstration application creates a composite USB Device that enumerates as a COM port and as Flash drive simultaneously. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB CDC MSD Composite Device Demonstration. Description To build this project, you must open the cdc_msd_basic.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/cdc_msd_basic. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 19 Project Name Location cdc_msd_basic.X /apps/usb/device/cdc_msd_basic/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Description PIC32 USB Starter Kit II Remove jumper JP2. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions on how to build and run the USB CDC MSD Composite Device demonstration. Description This demonstration application creates a composite USB Device that works simultaneously as a CDC and as a MSD device. This application combines the functionality of the cdc_com_port_single and msd_basic demonstration applications into one device. Refer to Running the Demonstration section of the cdc_com_port_single demonstration and the Running the Demonstration section of the msd_basic demonstration for details on exercising the CDC and MSD device features, respectively. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. cdc_serial_emulator This application demonstrates the use of the CDC device class in implementing a USB-to-Serial Dongle. Description This application demonstrates the use of the CDC device class in implementing a USB-to-Serial Dongle. The application enumerates a COM port on the personal computer. Data received through the CDC USB interface is forwarded to a UART. Data received on the UART is forwarded to the CDC USB interface. This emulates a USB-to-Serial Dongle. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB CDC Device USB-to-Serial Demonstration. Description To build this project, you must open the cdc_serial_emulator.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/cdc_serial_emulator. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 20 Project Name Location cdc_serial_emulator.X /apps/usb/device/cdc_serial_emulator/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx795_pim_e16_int_dyn pic32mx795_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration on the Explorer 16 Development Board configured for Interrupt mode and dynamic operation. This configuration also requires the PIC32MX795F512L Plug-In Module (PIM) and the USB PICtail Plus Daughter Board. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ EF Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32MX795F512L CAN-USB PIM Jumper J10 should be removed. Jumper J1 and J2 should_connect_to positions 1 and 2. This PIM should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be connected to the edge connector J9. On the Explorer 16 Development Board: • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place • Jumper JP2 and JP4 should be removed On the PIC32MX795F512L PIM: • Keep jumper J10 open • Keep all jumpers in J9 open • Jumper J1 should be shorted between positions 1 and 2. This configuration is only applicable for the PIC32MX795F512L USB CAN PIM (MA320003), and not the PIC32MX795F512L USB PIM (MA320002). • Jumper J2 should be shorted between positions 1 and 2. This configuration is only applicable for the PIC32MX795F512L USB CAN PIM (MA320003) and not the PIC32MX795F512L USB PIM (MA320002). Running the Demonstration Provides instructions on how to build and run the CDC Serial Emulator Demonstration. Prior to using this demonstration, it is recommended to review the MPLAB Harmony Release Notes for any known issues. A PDF copy of the release notes is provided in the /doc folder of your installation. Description This application demonstrates the use of the CDC Device class in implementing a USB-to-Serial Dongle. The application enumerates a COM port on the personal computer. Data received through the CDC USB interface is forwarded to a UART. Data received on the UART is forwarded to the CDC USB interface. This emulates a USB-to-Serial Dongle. 1. Open_the project in MPLAB X IDE and select the desired configuration. 2. Build the code and program the device. 3. Depending on the hardware in use, do one of the following: • If you are using the Explorer 16 board, connect the mini-B device connector on the USB PICtail Plus Daughter Board to the personal computer • If you a are using the PIC32MZ EF starter kit, connect the micro-USB device connector to the personal computer Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 21 7. Select the "Install from a list or specific location (Advanced)" option. Specify the /apps/usb/device/cdc_serial_emulator/inf directory. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. 8. Open_a terminal emulation program of your choice and select the enumerated USB COM port. 9. Connect the USB-to-Serial Dongle to the same personal computer. 10. Open_another instance of the terminal emulation program and select the USB-to-Serial Dongle. 11. Connect the serial connector of the USB-to-Serial Dongle to the UART connector (P1) on the Explorer 16 Development Board. 12. Choose a baud rate of 9600, 1 Stop bit and no parity while opening both of the terminal emulation programs. The setup should be similar to the following diagram. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 22 Any text entered into the terminal 1 program will be echoed on terminal 2 and vice versa. cdc_serial_emulator_msd Demonstrates a USB to Serial Dongle combined with a MSD class. Description This demonstration application creates a USB Device that combines the functionality of the cdc_serial_emulator and msd_basic demonstration applications. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the this demonstration application. Description To build this project, you must open the cdc_serial_emulator_msd.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/cdc_serial_emulator_msd. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location cdc_serial_emulator_msd.X /apps/usb/device/cdc_serial_emulator_msd/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx795_pim_e16_int_dyn pic32mx795_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration on the Explorer 16 Development Board configured for Interrupt mode and dynamic operation. This configuration also requires the PIC32MX795F512L Plug-In Module (PIM) and the USB PICtail Plus Daughter Board. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MX795F512L CAN-USB PIM Jumper J10 should be removed. Jumper J1 and J2 should_connect_to positions 1 and 2. This PIM should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be connected to the edge connector J9. On the Explorer 16 Development Board: Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 23 • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place • Jumper JP2 and JP4 should be removed On the PIC32MX795F512L PIM: • Keep jumper J10 open. • Keep all jumpers in J9 open • Jumper J1 should be shorted between positions 1 and 2 • Jumper J2 should be shorted between positions 1 and 2 Running the Demonstration Provides instructions on how to build and run the demonstration. Description This demonstration functions as a composite USB Device that combines the features of the devices created by the cdc_serial_emulator and the msd_basic demonstration applications. Refer to Running the Demonstration section of the cdc_serial_emulator demonstration and Running the Demonstration section of the msd_basic demonstration for details on exercising the CDC and MSD functions, respectively. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. hid_basic This demonstration application creates a custom HID device that can be controlled by a personal computer-based utility. Description This application creates a custom HID device that can be controlled by a personal computer-based utility. The device allows the USB Host utility to control the LEDs on the board and query the status of a switch. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB HID Basic Demonstration. Description To build this project, you must open the hid_basic.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/hid_basic. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location hid_basic.X /apps/usb/device/hid_basic/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx460_pim_e16_int_dyn pic32mx460_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration on the Explorer 16 Development Board configured for Interrupt mode and dynamic operation. This configuration also requires the PIC32MX460F512L Plug-In Module (PIM) and the USB PICtail Plus Daughter Board. pic32mx_usb_sk3_int_dyn pic32mx_usb_sk3 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit III configured for Interrupt mode and dynamic operation. pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 24 pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II Remove jumper JP2. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32 USB Starter Kit III Remove jumper JP1. PIC32MX460F512L PIM Jumper J10 should be removed. This plug-in module should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be connected to the edge connector J9. On the Explorer 16 Development Board: • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place • Jumper JP2 and JP4 should be removed On the PIC32MX460F512L PIM: • Keep jumper J10 open • Keep all jumpers in J9 open Running the Demonstration Provides instructions on how to build and run the HID Basic demonstration. Description This demonstration uses the selected hardware platform as a HID class USB device, but uses the HID class for general purpose I/O operations. While compiling, select the appropriate MPLAB X IDE project configuration based on the demonstration board. Refer to Building the Application for details. Typically, the HID class is used to implement human interface products, such as mice and keyboards. The HID protocol, is however, quite flexible, and can be adapted and used to send/receive general purpose data to/from a USB device. Using the HID class for general purpose I/O operations is quite advantageous, in that it does not require any kind of custom driver installation process. HID class drivers are already provided by and are distributed with common operating systems. Therefore, upon plugging in a HID class device into a typical computer system, no user installation of drivers is required, the installation is fully automatic. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. HID devices primarily communicate through one interrupt IN endpoint and one interrupt OUT endpoint. In most applications, this effectively limits the maximum achievable bandwidth for full speed HID devices to 64 kBytes/s of IN traffic, and 64 kBytes/s of OUT traffic (64 kB/s, but effectively "full duplex"). The GenericHIDSimpleDemo.exe program, and the associated firmware demonstrate how to use the HID protocol for basic general purpose USB data transfer. Before you can run the GenericHIDSimpleDemo.exe executable, you will need to have the Microsoft® .NET Framework Version 2.0 Redistributable Package (later versions are probably acceptable, but have not been tested) installed on your computer. Programs that were built in the Visual Studio® .NET languages require the .NET redistributable package. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® operating systems will not need to install the .NET framework, as it comes preinstalled as part of the operating system. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 25 Launching the Application To launch the application, simply double click the executable GenericHIDSimpleDemo.exe in the \apps\usb\device\hid_basic\bin directory. A property sheet similar to the following should appear: Note: If instead of this window, an error message appears while trying to launch the application, it is likely the Microsoft .NET Framework Version 2.0 Redistributable Package has not yet been installed. Please install it and try again. Send/Receive Packets To begin sending/receiving packets to the device, you must first find and_connect_ to the device. As configured by default, the application is looking for HID class USB devices with VID = 0x04D8 and PID = 0x003F. The device descriptor in the firmware project meant to be used with this demonstration uses the same VID/PID. If you plug in a USB device programmed with the correct precompiled .hex file, and click Connect, the other push buttons should become enabled. If clicking Connect has no effect, it is likely the USB device is either not connected, or has not been programmed with the correct firmware. Clicking Toggle LED(s) should send a single packet of general purpose generic data to the HID class USB peripheral device. The data will arrive on the interrupt OUT endpoint. The firmware has been configured to receive this generic data packet, parse the packet looking for the Toggle LED(s) command, and should respond appropriately by controlling the LED(s) on the demonstration board. The Get Pushbutton State option will send one packet of data over the USB to the peripheral device (to the interrupt OUT endpoint) requesting the current push button state. The firmware will process the received Get Pushbutton State command, and will prepare an appropriate response packet depending upon the pushbutton state. The following table shows the button that has to be pressed on the demonstration board to see the change in the push button state. Demonstration Board Button PIC32 USB Starter Kit II PIC32 USB Starter Kit III PIC32MZ Embedded Connectivity (EC) Starter Kit PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit SW1 Explorer 16 Development Board S3 hid_joystick Demonstrates a USB HID device emulating a joystick. Description This demonstration application creates a custom HID joystick. This application is only intended to demonstrate creation of Joystick HID Report descriptors and may not be a definite end solution. The end application requirements may need the report descriptor to be modified. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB HID Joystick Demonstration. Description To build this project, you must open the hid_joystick.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/hid_joystick. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location hid_joystick.X /apps/usb/device/hid_joystick/firmware Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 26 MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx460_pim_e16_int_dyn pic32mx460_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration on the Explorer 16 Development Board configured for Interrupt mode and dynamic operation. This configuration also requires the PIC32MX460F512L Plug-In Module (PIM) and the USB PICtail Plus Daughter Board. pic32mx_usb_sk3_int_dyn pic32mx_usb_sk3 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit III configured for Interrupt mode and dynamic operation. pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II Remove jumper JP2. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32 USB Starter Kit III Remove jumper JP1. PIC32MX460F512L PIM Jumper J10 should be removed. This plug-in module should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be connected to the edge connector J9. On the Explorer 16 Development Board: • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place • Jumper JP2 and JP4 should be removed On the PIC32MX460F512L PIM: • Keep jumper J10 open • Keep all jumpers in J9 open Running the Demonstration Provides instructions on how to build and run the USB HID Joystick demonstration. Description This demonstration uses the selected hardware platform as a USB Joystick. Select the appropriate MPLAB X IDE project configuration based on the demonstration board. Refer to Building the Application for details. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. To test the joystick feature, navigate to the /apps/usb/device/hid_joystick/bin directory and open JoystickTester.exe: Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 27 Pressing the button will cause the device to: • Indicate that the "x" button is pressed, but no others • Move the hat switch to the "east" position • Move the X and Y coordinates to their extreme values The Following table shows the button that has to be pressed on the demonstration board to emulate the joystick. Demonstration Board Button PIC32 USB Starter Kit II PIC32 USB Starter Kit III PIC32MZ Embedded Connectivity (EC) Starter Kit PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit SW1 Explorer 16 Development Board S3 Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 28 hid_keyboard Demonstrates a USB HID device, emulating a keyboard. Description This demonstration application creates a Generic HID keyboard. Pressing a key on the board emulates a keyboard key press. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB HID Keyboard Demonstration. Description To build this project, you must open the hid_keyboard.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/hid_keyboard. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location hid_keyboard.X /apps/usb/device/hid_keyboard/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx460_pim_e16_int_dyn pic32mx460_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration on the Explorer 16 Development Board configured for Interrupt mode and dynamic operation. This configuration also requires the PIC32MX460F512L Plug-In Module (PIM) and the USB PICtail Plus Daughter Board. pic32mx_usb_sk3_int_dyn pic32mx_usb_sk3 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit III configured for Interrupt mode and dynamic operation. pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II Remove jumper JP2. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32 USB Starter Kit III Remove jumper JP1. PIC32MX460F512L PIM Jumper J10 should be removed. This plug-in module should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 29 connected to the edge connector J9. On the Explorer 16 Development Board: • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place • Jumper JP2 and JP4 should be removed On the PIC32MX460F512L PIM: • Keep jumper J10 open • Keep all jumpers in J9 open Running the Demonstration Provides instructions on how to build and run the USB HID Keyboard demonstration. Description This demonstration uses the selected hardware platform as a USB keyboard. While compiling, select the appropriate MPLAB X IDE project configuration based on the demonstration board. Refer to Building the Application for details. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. Before pressing the button, select a window in which it is safe to type text freely. Pressing the button on the demonstration board will cause the device to print a character on the screen. The following table shows the button that has to be pressed on the demonstration board to print a character. Demonstration Board Button PIC32 USB Starter Kit II PIC32 USB Starter Kit III PIC32MZ Embedded Connectivity (EC) Starter Kit PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit SW1 Explorer 16 Development Board S3 hid_mouse Demonstrates a USB HID device, emulating a mouse pointing device. Description This demonstration application creates a USB HID based two-button mouse device. When connected, the device emulates mouse operation by moving the cursor in a circular pattern. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB HID Mouse Demonstration. Description To build this project, you must open the hid_mouse.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/hid_mouse. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location hid_mouse.X /apps/usb/device/hid_mouse/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 30 Project Configuration Name BSP Used Description pic32mx460_pim_e16_int_dyn pic32mx460_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration on the Explorer 16 Development Board configured for Interrupt mode and dynamic operation. This configuration also requires the PIC32MX460F512L Plug-In Module (PIM) and the USB PICtail Plus Daughter Board. pic32mx_usb_sk3_int_dyn pic32mx_usb_sk3 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit III configured for Interrupt mode and dynamic operation. pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II Remove jumper JP2. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32 USB Starter Kit III Remove jumper JP1. PIC32MX460F512L PIM Jumper J10 should be removed. This plug-in module should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be connected to the edge connector J9. On the Explorer 16 Development Board: • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place • Jumper JP2 and JP4 should be removed On the PIC32MX460F512L PIM: • Keep jumper J10 open • Keep all jumpers in J9 open Running the Demonstration Provides instructions on how to build and run the HID Mouse Demonstration. Description This demonstration uses the selected hardware platform as a USB mouse. While compiling, select the appropriate MPLAB X IDE project configuration based on the demonstration board. Refer to Building the Application for details. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. Before connecting the board to the computer through the USB cable please be aware that the device will begin moving the mouse cursor on the computer. There are two ways to stop the device from allowing the cursor to continue to move. The first way is to disconnect the device from the computer. The second is to press the correct button on the hardware platform. Pressing the button again will cause the mouse cursor to start moving in a circle again. The following table shows the button that has to be pressed on the demonstration board to stop the circular motion: Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 31 Demonstration Board Button PIC32 USB Starter Kit II PIC32 USB Starter Kit III PIC32MZ Embedded Connectivity (EC) Starter Kit PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit SW1 Explorer 16 Development Board S3 hid_msd_basic Demonstrates a HID Device Class and MSD class composite USB Device. Description This demonstration application creates a USB Device that combines the functionality of the hid_basic and msd_basic demonstration applications. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the this demonstration application. Description To build this project, you must open the hid_msd_basic.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/hid_msd_basic. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location hid_msd_basic.X /apps/usb/device/hid_msd_basic/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this configuration to run the demonstration application on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this configuration to run the demonstration application on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II Remove jumper JP2. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions on how to build and run the demonstration. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 32 Description This demonstration functions as composite USB Device that combines the features of the devices created by the hid_basic and the msd_basic demonstration applications. Refer to Running the Demonstration section of the hid_basic demonstration and Running the Demonstration section of the msd_basic demonstration for details on exercising the HID and MSD functions, respectively. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. msd_basic Demonstrates a USB MSD Device emulating a Flash Drive. Description This demonstration application creates a Flash drive using the Mass Storage Device Class. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB MSD Basic Demonstration. Description To build this project, you must open the msd_basic.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/msd_basic. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location msd_basic.X /apps/usb/device/msd_basic/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx_bt_sk_int_dyn pic32mx_bt_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 Bluetooth Starter Kit configured for Interrupt mode and dynamic operation. pic32mx_usb_sk2_poll_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II with the USB Device Stack configured for Polled mode and dynamic operation.. pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mx_usb_sk3_int_dyn pic32mx_usb_sk3 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit III configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_poll_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Polled mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II Remove jumper JP2. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 33 PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32 USB Starter Kit III Remove jumper JP1. PIC32 Bluetooth Starter Kit No hardware related configuration or jumper settings required. PIC32MX460F512L PIM Jumper J10 should be removed. This plug-in module should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be connected to the edge connector J9. On the Explorer 16 Development Board: • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place • Jumper JP2 and JP4 should be removed Running the Demonstration Provides instructions on how to build and run the USB MSD Basic demonstration. Description This demonstration uses the selected hardware platform as a logical drive on the computer using the internal Flash of the device as the drive storage media. Connect the hardware platform to a computer through a USB cable. The device should appear as a new drive on the computer named "Drive Name". The drive can used to store files. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. Note: Reprogramming the development board will cause any stored files to be erased. msd_fs_spiflash This application demonstrates accessing the SPI Flash connected to the PIC32 device as a media by multiple clients. Description This application demonstrates accessing the SPI Flash connected to the PIC32 device as a media by multiple clients. When connected via USB to the Host Computer, the SPI Flash is shown as the storage media. The Host writes files to the media, which is later accessed by the application running on the PIC32 device using the File System. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB MSD File System SPI Flash Demonstration. Description To build this project, you must open the msd_fs_spiflash.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/msd_fs_spiflash. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location msd_fs_spiflash.X /apps/usb/device/msd_fs_spiflash/firmware Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 34 MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description bt_audio_dk_int_dyn bt_audio_dk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 Bluetooth Audio Development Kit. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 Bluetooth Audio Develoment Kit Ensure that switch S1 is set to PIC32_MCLR. Running the Demonstration Provides instructions on how to build and run the USB MSD File System SPI Flash demonstration. Description This demonstration shows an example of: • Accessing the media attached to PIC32 by multiple clients • Application running on the PIC32 firmware accesses the media using the MPLAB Harmony File System When connected to the USB Host the very first time, the user is expected to format the media and create a file named FILE.TXT in the root directory of the media. The user can update the file to provide input for the application to glow the LEDs present on the development kit. The application running on the PIC32 reads and interprets the data present in the file and accordingly turns ON or OFF the LEDs LED8 and LED9 of the development kit. The format of input in the file FILE.TXT should be as follows: • For turning ON an LED: • LED8:1 • LED9:1 • For turning OFF an LED: • LED8:0 • LED9:0 After having set the appropriate values in the file, the user can then press and release the wwitch SW1 located on the development kit for the MPLAB Harmony File System running on the PIC32 to act upon the contents of the file. The FS state machine of the demonstration is only triggered by the switch SW1. When the user presses and releases SW1 the following occurs: • LED5 is turned ON to indicate that the FS state machine is running • The USB is detached • The file system on the SPI Flash is mounted • The contents of FILE.TXT is read and acted upon. Depending on the values set in the file, the LEDs are either turned ON or OFF. • Next, the file system is unmounted and the USB is reattached • LED5 is turned OFF to indicate that FS state machine is no longer running • If LED6 is turned ON during any part of the demonstration, this indicates the demonstration has failed msd_multiple_luns This topic demonstrates data transfer between two storage media - SD card and non-volatile memory (NVM) - and a computer through USB Mass Storage Device (MSD). Description This application demonstrates the creation of a USB device with multiple logical units. The storage media, SD Card, acts as one logical unit, and the NVM acts as the second logical unit. Data transfer between a computer and the logical units (SD Card / NVM) takes place through USB MSD. Building the Application This section identifies the MPLAB X IDE project name and location, and then lists and describes the available configurations for the USB MSD multiple LUNs demonstration. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 35 Description To build this project, you must open the msd_multiple_luns.X project in MPLAB X IDE, and then select the desired configuration. The following tables lists and describes the project and the supported configurations. The parent folder for these files is /apps/usb/device/msd_multiple_luns MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location msd_multiple_luns.X /apps/usb/device/msd_multiple_luns/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx470_curiosity pic32mx470_curiosity Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MX470 Curiosity board with the USB device stack configured for Interrupt mode and full speed operation. The LUN0 media type is configured as SD Card and LUN1 media type is configured as NVM. pic32mz_ef_curiosity pic32mz_ef_curiosity Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ EF Curiosity board with the USB device stack configured for Interrupt mode and high speed operation. The LUN0 media type is configured as SD Card and LUN1 media type is configured as NVM. Configuring the Hardware This section describes how to configure the supported hardware. Description PIC32MX470 Curiosity Development Board 1. Ensure that a jumper is placed at 4-3 on J8, to select supply from debug USB connector. 2. Mount the SD Click board, "microSD click" from MikroElektronika (http://www.mikroe.com/click/microsd/) on the mikro bus interface J10. 3. Plug a micro SD card into the microSD click board card slot. 4. Power the PIC32MX470 Curiosity Development Board from a Host PC through a Type-A male to mini-B USB cable connected to Mini-B port (J3). 5. Connect a Type-A male to micro USB cable to the micro USB port (J12) on PIC32MX470 Curiosity Development Board. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 36 PIC32MZ EF Curiosity Development Board 1. Ensure that a jumper is placed at 4-3 on J8, to select supply from debug USB connector. 2. Mount the SD Click board, "microSD click" from MikroElektronika (http://www.mikroe.com/click/microsd/) on the mikro bus interface J10. 3. Plug a micro SD card into the microSD click board card slot. 4. Power the PIC32MZ EF Curiosity Development Board from a Host PC through a Type-A male to micro USB cable connected to micro USB port (J3). 5. Connect a Type-A male to micro USB cable to the micro USB port (J12) on PIC32MZ EF Curiosity Development Board. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 37 Running the Demonstration This section provides instructions about how to build and run the USB MSD Multiple LUNs demonstration. Description This demonstration uses SD card and NVM as drive storage media and shows them as two logical drives on the computer. • Connect the hardware platform to a computer through a USB cable. • The device should appear as two new drives on the computer. • The NVM media should appear as "Drive Name" and should have a sample “FILE.txt” file. The drive name for the SD card media depends on the micro SD card vendor. The drives can then be used to store files. • The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. Note: Reprogramming the development board will cause any stored files in the NVM media to be erased. msd_sdcard Demonstrates data transfer from a SD card and a computer through USB MSD. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 38 Description This application demonstrates the usage of a SD card reader through the USB Mass Storage Device (MSD) class to transfer data between a computer and SD card. High-Speed USB is used for communication between the Host computer and the PIC32 device, while a SD card is used as the storage medium. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB MSD SD Card Demonstration. Description To build this project, you must open the msd_sdcard.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/msd_sdcard. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location msd_sdcard.X /apps/usb/device/msd_sdcard/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mz_ec_sk_int_dyn pic32mz_ec_sk+meb2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ EC Starter Kit connected to the MEB II. The media drivers are configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MZ Embedded Connectivity (EC) Starter Kit and Multimedia Expansion Board II (MEB II) No hardware related configuration or jumper settings required. Running the Demonstration Provides instructions on how to build and run the USB MSD SD Card demonstration. Description This demonstration uses the selected hardware platform as a logical drive on the computer using the SD card as the drive storage media. Connect the hardware platform to a computer through a USB cable. The device should appear as a new drive on the computer named "Drive Name". The drive can then be used to store files. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. vendor Demonstrates a custom USB Device created by using the USB Device Layer Endpoint functions. Description This demonstration application creates a custom USB device using the USB Device Layer Endpoint functions. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 39 Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the Vendor USB Device Demonstration. Description To build this project, you must open the vendor.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/device/vendor. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location vendor.X /apps/usb/device/vendor/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx460_pim_e16_int_dyn pic32mx460_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration on the Explorer 16 Development Board configured for Interrupt mode and dynamic operation. This configuration also requires the PIC32MX460F512L Plug-In Module (PIM) and the USB PICtail Plus Daughter Board. pic32mx_usb_sk3_int_dyn pic32mx_usb_sk3 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit III configured for Interrupt mode and dynamic operation. pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II Remove jumper JP2. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32 USB Starter Kit III Remove jumper JP1. PIC32MX460F512L PIM Jumper J10 should be removed. This plug-in module should be used along with the Explorer 16 Development Board and the USB PICtail Plus daughter board. The microcontroller PIM should be plugged into the PIM_socket_on the board. The USB PICtail Plus daughter board should be connected to the edge connector J9. On the Explorer 16 Development Board: • Switch S2 should be set to PIM • Jumper JP2 should be in place On the USB PICtail Plus Daughter Board: • Jumper JP1 should be in place Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 40 • Jumper JP2 and JP4 should be removed On the PIC32MX460F512L PIM: • Keep jumper J10 open • Keep all jumpers in J9 open Running the Demonstration Provides instructions on how to build and run the Vendor USB Device demonstration. Description The Vendor device can be exercised by using the WinUSB PnP Demonstration application, which is provided in your installation of MPLAB Harmony. The LEDs on the demonstration board will indicate the USB state of the device, as described in the USB Device State and LED Indication Table in the Device section. This application allows the state of the LEDs on the board to be toggled and indicates the state of a switch (pressed/released) on the board. To launch the application, double click WinUSB PnP Demo.exe located in /apps/usb/device/vendor/bin. A dialog box similar to the following should appear: The appropriate device family that is under testing should be selected in the utility. Pressing the Toggle LED button will cause the LED on the board to toggle. The Pushbutton State field in the application indicates the state of a button on connected USB Device. Pressing the switch on the development board will update the Pressed/Not Pressed status of the Pushbutton State field. Demonstration Board Button PIC32 USB Starter Kit II PIC32 USB Starter Kit III PIC32MZ Embedded Connectivity (EC) Starter Kit PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit SW1 Explorer 16 Development Board S3 Note: The device family under test should be selected appropriately. An incorrect selection will result in an invalid push button status. Host This section describes the USB Host demonstrations. audio_speaker This application demonstrates the use of the Audio v1.0 Host Class Driver to enumerate and operate an audio speaker device. Description This application demonstrates the use of the Audio v1.0 Host Class Driver to enumerate and an audio speaker device. The application uses the USB Host Layer and Audio 1.0 class driver to enumerate an Audio v1.0 USB device. The demonstration host application then operates and uses the functionality of the attached audio speaker device. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 41 Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB Host Audio Speaker Demonstration. Description To build this project, you must open the audio_speaker.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/host/audio_speaker. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location audio_speaker.X /apps/usb/host/audio_speaker/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II JP2 should be in place. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions on how to build and run the USB Host Audio v1.0 Basic Demo. Description This application demonstrates the use of the Audio v1.0 Host Class Driver to enumerate and operate an Audio v1.0 Device. The application uses the USB Host layer and Audio v1.0 class driver to enumerate a Audio v1.0 USB device. The demonstration host application then operates and uses the functionality of the attached Audio v1.0 Device. Prior to using this demonstration, it is recommended to review the MPLAB Harmony Release Notes for any known issues. A PDF copy of the release notes is provided in the /doc folder of your installation. 1. Open the project in MPLAB X IDE and select the desired project configuration. 2. Build the code and program the device. 3. Attach a commercially available USB speaker to the board. 4. LED1 is turned ON if the attached device is accepted by the Audio 1.0 class driver. 5. The speaker should produce a 1 kHz sine wave. 6. LED2 will continue blinking if the demonstration application cannot accept the device. 7. Press switch SW1 to mute the audio. 8. Press switch SW2 to unmute the audio Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 42 cdc_basic This application demonstrates the use of the CDC Host Class Driver to enumerate and operate a CDC Device. Description This application demonstrates the use of the CDC Host Class Driver to enumerate and operate a CDC Device. The application uses the USB Host_layer and CDC class driver to enumerate a CDC USB device. The demonstration host application then operates and uses the functionality of the attached CDC Device. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB CDC Host Basic Demonstration. Description To build this project, you must open the cdc_basic.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/host/cdc_basic. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location cdc_basic.X /apps/usb/host/cdc_basic/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mx_usb_sk2_poll_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Polled mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II JP2 should be in place. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions on how to build and run the USB Host CDC Basic Demo. Description This application demonstrates the use of the CDC Host Class Driver to enumerate and operate a CDC Device. The application uses the USB Host_layer and CDC class driver to enumerate a CDC USB device. The demonstration host application then operates and uses the functionality of the attached CDC Device. Prior to using this demonstration, it is recommended to review the MPLAB Harmony Release Notes for any known issues. A PDF copy of the Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 43 release notes is provided in the /doc folder of your installation. 1. Open_the project in MPLAB X IDE and select the desired project configuration. 2. Build the code and program the device. 3. Follow the directions for setting up and running the cdc_serial_emulator USB device demonstration. 4. Connect the UART (P1) port on the Explorer 16 Development Board (running the cdc_serial_emulator demonstration) to a USB Host personal computer via a commercially available Serial-to-USB Dongle. 5. Start a terminal program on the USB Host personal computer and select the Serial-to-USB Dongle as the communication port. Select the baud rate as 9600, no parity, 1 Stop bit and no flow control. 6. Connect the mini – B connector on the USB PICtail Plus Daughter Board, of the cdc_serial_emulator demonstration setup, to the USB host connector on the starter kit. For PIC32M-based starter kits, connect to the on-board Type-A connector. 7. A prompt (LED :) will be displayed immediately on the terminal emulation program. 8. Pressing either the 1, 2, or 3 key on the USB Host keyboard will cause LEDs on the PIC32 starter kit (running the USB CDC Host application) to switch on, respectively. On PIC32M-based starter kits, the LEDs are LED1, LED2, and LED3. 9. The prompt will again be displayed on terminal emulation program, and step 8 can be repeated. The setup should be similar to the following diagram. The cdc_serial_emulator demonstration emulates a USB-to-Serial Dongle. The CDC Host (running the cdc_basic demonstration application) sends the prompt message to the CDC device. The CDC device forwards the prompt to the UART port from where it is transmitted to the personal computer USB Host through the USB-to-Serial Dongle. A key press on the personal computer USB Host is transmitted to the CDC device, which in turn presents the key press data to the CDC host. The cdc_basic demonstration then analyzes the key press data and switches on the respective LED. cdc_msd Demonstrates host support for multiple device classes. Description This demonstration application creates a USB Host that can support different device classes in one application. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for this USB CDC MSD Host Demonstration. Description To build this project, you must open the cdc_msd.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/host/cdc_msd. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 44 MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location cdc_msd.X /apps/usb/host/cdc_msd/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II JP2 should be in place. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions on how to build and run the USB CDC MSD demonstration. Description This demonstration application creates a USB Host application that enumerates a CDC and a MSD device. This application combines the functionality of the Host cdc_basic and msd_basic demonstration applications into one application. If a CDC device is connected, the demonstration application behaves like the cdc_basic host application. If a MSD device is connected, the demonstration application behaves like the msd_basic host application. Refer to Running the Demonstration section of the host cdc_basic demonstration and the Running the Demonstration section of the host msd_basic demonstration for details on exercising the CDC and MSD host aspects of the demonstration. hid_basic_keyboard Demonstrates using the USB HID Host Client driver with the Keyboard Usage driver to facilitate the use of a USB HID Keyboard with a PIC32 USB Host. Description This application demonstrates the use of the USB HID Host Client Driver to enumerate and operate a HID keyboard device. The application uses the USB Host layer, HID Client driver and HID Keyboard Usage driver to enumerates a USB keyboard and understand keyboard press release events. The keyboard events are displayed using a terminal emulator on a personal computer. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB HID Basic Keyboard Demonstration. Description To build this project, you must open the hid_basic_keyboard.X project in MPLAB X IDE, and then select the desired configuration. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 45 The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/host/hid_basic_keyboard. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location hid_basic_keyboard.X /apps/usb/host/hid_basic_keyboard/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx795_pim_e16_int_dyn pic32mx795_pim+e16 Select this MPLAB X IDE project configuration to run the demonstration configured for Interrupt mode and dynamic operation on the PIC32MX795F512L PIM connected to the Explorer 16 Development Board with the USB PICtail Plus Daughter Board attached. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit No hardware related configuration or jumper setting changes are necessary. Explorer 16 Development Board • Switch S2 should be set to PIM USB PICtail Plus Daughter Board • Jumper the Host Enable pins • Device Enable and OTG Enable should be open PIC32MX795F512L CAN-USB PIM • Keep jumper J10 open • Keep all jumpers in J9 open • Jumper J1 should be shorted between positions 1 and 2. This configuration is only applicable for the PIC32MX795F512L USB CAN PIM (MA320003), and not the PIC32MX795F512L USB PIM (MA320002). • Jumper J2 should be shorted between positions 1 and 2. This configuration is only applicable for the PIC32MX795F512L USB CAN PIM (MA320003) and not the PIC32MX795F512L USB PIM (MA320002). For the pic32mx795_pim_e16_int_dyn configuration: 1. Ensure that the PIC32MX795F512L PIM is connected properly to the PIM socket on the Explorer 16 Development Board. 2. Connect the Serial Port connector on the Explorer 16 Development Board to a PC using a Serial-to-USB converter cable. 3. Connect the USB PICtail Plus Daughter Board to the horizontal edge connector (J9) of the Explorer 16 Development Board. For the pic32mz_ef_sk_int_dyn configuration: Connect the USB to the UART connector (J11) on the PIC32MZ EF Starter Kit to a PC using a USB micro cable. Running the Demonstration Provides instructions on how to build and run the USB HID Basic Keyboard demonstration. Description 1. Open the project in MPLAB X IDE and select the project configuration. 2. Build the code and program the device. 3. Launch a terminal emulator, such as Tera Term, and select the appropriate COM port and set the serial port settings to 115200-N-1. 4. If a USB keyboard is not connected to the PIC32 USB Host, the terminal emulator window will show the Connect Keyboard prompt. 5. Attach a USB keyboard to the Host connector of the target hardware. The message, Keyboard Connected, will appear in the terminal emulator window. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 46 6. Begin typing on the keyboard and the appropriate keys should be displayed on the serial terminal. Subsequent press and release of modifier keys (i.e., CAPS LOCK, NUM LOCK, etc.) will result in the appropriate keyboard LEDs to turning ON and OFF. 7. Disconnecting the keyboard will result in the message, Connect Keyboard. hid_basic_mouse_usart This topic demonstrates USB Host support for a USB HID Mouse. Description This application demonstrates the use of the USB HID Host Client Driver to enumerate and operate a HID mouse device. The application uses the USB Host layer, HID Client driver and HID Mouse Usage driver to enumerate USB mouse and decode mouse-generated data. Mouse-specific movements events are demonstrated by displaying relative coordinate changes using a serial terminal emulator on a personal computer. Mouse button clicks are indicated by LEDs. Building the Application This section does the following: • Identifies the MPLAB X IDE project name and location. • Lists and describes the available configurations for the USB HID Basic Mouse USART demonstration. Description To build this project, you must open the hid_basic_mouse_usart.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/host/hid_basic_mouse_usart. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location hid_basic_mouse_usart.X /apps/usb/host/hid_basic_mouse_usart/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mz_ef_sk_meb2 pic32mz_ef_sk+meb2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit attached to Multimedia Expansion Board II (MEB II) board. Configuring the Hardware This section describes how to configure the supported hardware. Description 1. Ensure that the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit is securely fastened into the MEB II expansion board. 2. Connect the USB to the UART connector (J11) on the PIC32MZ EF Starter Kit to a PC using a USB micro cable. Note: No hardware related configuration or jumper setting changes are necessary. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 47 Running the Demonstration This section provides instructions about how to build and run the USB HID Mouse USART demonstration. Description 1. Open the project in MPLAB X IDE and select the project configuration. 2. Build the code and program the device. 3. Launch a terminal emulator, such as Tera Term. Select the appropriate COM port and set the serial port settings to 115200-N-1. • If a USB mouse is not connected to the Host connector by using J5 on the PIC32 MZ EF Starter Kit, the serial terminal emulator window will show the "Connect Mouse" prompt. 4. Attach a USB mouse to the Host connector of the target hardware. The message, "Mouse Connected", will display in the serial terminal emulator window. 5. Begin moving the mouse and the appropriate relative coordinate changes for X,Y, and Z axes should be displayed in the serial terminal window. 6. Click the mouse button to toggle LEDs on the MEB II board as shown in the following table. Mouse Click MEB II LED Left D3 Right D4 Middle D5 Lower Left D6 Lower Right D7 • Disconnecting the mouse will result in the message, "Connect Mouse", to reappear on the serial console. hub_cdc_hid Demonstrates the enumeration of a HID mouse and CDC emulator device via an external hub. Description This application demonstrates the capability of the USB Host Stack to access and manage multiple USB Devices through a Hub. The demonstration application enumerates a HID mouse and CDC emulator device via an external hub. The host will demonstrate the communication from the CDC emulator device and the HID mouse. Building the Application This topic identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB Host HUB CDC HID Demonstration. Description To build this project, you must open the hub_cdc_hid.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/host/hub_cdc_hid. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location hub_cdc_hid.X /apps/usb/host/hub_cdc_hid/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 48 Project Configuration Name BSP Used Description pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ EF Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II JP2 should be in place. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions on how to build and run the USB Host HUB CDC HID demonstration. Description This application demonstrates the capability of the USB Host Stack to access and manage multiple USB Devices through a Hub. The demonstration application enumerates a HID mouse and CDC emulator device via an external hub. The host will demonstrate the communication from the CDC emulator device and the HID mouse. 1. Open the project in MPLAB X IDE and select the desired project configuration. 2. Build the code and program the device. 3. Connect a hub to the Type A Host connector on the desired board. 4. Connect a mouse to a spare port on the hub. 5. Connect the CDC emulator device to another spare port on the hub. 6. Click the mouse to toggle LEDs on the starter kit. 7. On the personal computer, open a terminal emulator. At the prompt, (LED:), enter 1, 2, or 3 to toggle the LEDs on the starter kit. hub_msd This application demonstrates the capability of the USB Host stack to support multiple MSD device through a hub. Description This application demonstrates the use of the Hub Driver and the MSD Host Client Driver, with File System, to support multiple MSD devices and Hub. The demonstration application copies a file from one pen driver into another pen drive. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB Host Hub MSD Demonstration. Description To build this project, you must open the hub_msd.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/host/hub_msd. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location hub_msd.X /apps/usb/host/hub_msd/firmware Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 49 MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II JP2 should be in place. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions on how to build and run the USB Host Hub MSD demonstration. Description This application demonstrates the capability of the USB Host Stack to access and manage multiple USB Devices through a Hub. The demonstration application copies a file from one USB pen drive (i.e., a USB Flash storage device) to another USB pen drive, where these pen drives are attached to a hub. Note: The demonstration will search for a file named file.txt on any of the connected pen drives. Such a file should be created on one of the pen drives through any suitable method. 1. Open the project in MPLAB X IDE and select the desired project configuration. 2. Build the code and program the device. 3. Connect a hub to the Type A Host connector on the desired board. 4. Connect a USB Pen drive containing an arbitrary file named file.txt to a spare port on the hub. 5. Connect another USB pen drive to another spare port on the hub. 6. The application will copy the file file.txt from the drive containing this file to the other drive. The copied file will be renamed as newfile.txt. LED 2 on the demonstration board will illuminate to indicate completion of the file transfer. 7. Disconnect the drives and confirm demonstration success by inserting them into a personal computer and verifying the file transfer completed as expected. The demonstration application will always be in state where it waits for two pen drives to be connected to the hub and at least one of these pen drives contains a file named file.txt. msd_basic This application demonstrates the use of the MSD Host Class Driver to write a file to USB Flash Drive. Description This application demonstrates the use of the MSD Host Class Driver to write a file to a USB Flash drive. The application uses the USB Host_layer , MSD class driver and the MPLAB Harmony File System Framework to enumerate a USB Flash drive and to write a file to it. Building the Application This section identifies the MPLAB X IDE project name and location, and lists and describes the available configurations for the USB MSD Host Class Driver Demonstration. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 50 Description To build this project, you must open the msd_basic.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/host/msd_basic. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location msd_basic.X /apps/usb/host/msd_basic/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description chipkit_wf32 chipkit_wf32 Demonstration running on the chipKIT WF32 Development Board. chipkit_wifire chipkit_wifire Demonstration running on the chipKIT Wi-FIRE Development Board. pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit II configured for Interrupt mode and dynamic operation. pic32mx_usb_sk3_int_dyn pic32mx_usb_sk3 Select this MPLAB X IDE project configuration to run the demonstration on the PIC32 USB Starter Kit III with the PIC32MX470F512L microcontroller configured for Interrupt mode and dynamic operation. pic32mz_da_sk_intddr_int_dyn pic32mz_da_sk_intddr Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Graphics with Internal DRAM (DA) Starter Kit configured for Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. pic32mx_xlp_sk_int_dyn pic32mx_xlp_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MX XLP Starter Kit configured for Interrupt mode and dynamic operation. pic32wk_sk_int_dyn pic32wk_gbp_gpd_sk+module Select this MPLAB X IDE project configuration to run the demonstration application to run on the PIC32WK Wi-Fi Starter Kit, with the WM32 Wi-Fi module. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mx470_curiosity pic32mx470_curiosity Select this MPLAB X IDE project configuration to run the demonstration application to run on the PIC32MX470 Curiosity Development Board, with the PIC32MX470F512H microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. pic32mz_ef_curiosity pic32mz_ef_curiosity Select this MPLAB X IDE project configuration to run the demonstration application to run on the PIC32MZ EF Curiosity Development Board, with the PIC32MZ2048EFM100 microcontroller. The USB Stack will be configured for Interrupt mode operation and the USB Driver will be configured for Dynamic operation mode. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II JP2 should be in place. PIC32 USB Starter Kit III JP1 should be in place. PIC32MZ Embedded Graphics with Internal DRAM (DA) Starter Kit Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 51 No hardware related configuration or jumper setting changes are necessary. PIC32MZ EC Starter Kit JP1 should be in place and the Ethernet plug-in board should be removed. PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. chipKIT WF32 Wi-Fi Development Board No hardware related configuration or jumper setting changes are necessary. chipKIT Wi-FIRE Development Board No hardware related configuration or jumper setting changes are necessary. PIC32MX470 Curiosity Development Board • Ensure that a jumper is placed at 4-3 on J8, to select supply from debug USB connector. • Power the PIC32MX470 Curiosity Development Board from a Host PC through a Type-A male to mini-B USB cable connected to Mini-B port (J3) • Place a jumper on J13 to drive VBUS in Host mode • Plug in a USB peripheral with a micro-A USB connector, or use a micro USB OTG to USB adapter. PIC32MZ EF Curiosity Development Board • Ensure that a jumper is placed at 4-3 on J8, to select supply from debug USB connector. • Power the PIC32MZ EF Curiosity Development Board from a Host PC through a Type-A male to micro-B USB cable connected to Micro-B port Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 52 (J3). • Place a jumper on J13 to drive VBUS in Host mode. • Plug in a USB peripheral with a micro-A USB connector, or use a micro USB OTG to USB adapter. PIC32WK Wi-Fi Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions on how to build and run the USB Host MSD Basic demonstration. Description This application demonstrates the use of the MSD Host Class Driver to write a file to USB Flash drive. The application uses the USB Host_layer, MSD class driver and the MPLAB Harmony File System Framework to enumerate a USB Flash drive and to write a file to it. Prior to using this demonstration, it is recommended to review the MPLAB Harmony Release Notes for any known issues. A PDF copy of the release notes is provided in the /doc folder of your installation. 1. Open_the project in MPLAB X IDE and select the desired project configuration. 2. Build the code and program the device. 3. With the code running, attach a USB Flash drive to the Host connector on the desired starter kit. 4. The demonstration application will then create a file named file.txt. It will then write the text "Hello World" to this file, and then close the file. 5. The demonstration will then move to Idle mode, which is indicated when the LED on the starter kit illuminates. On PIC32M-based starter kits the LED is LED2. 6. The USB Flash drive can then be attached to a USB Host personal computer to verify the demonstration application operation. 7. Steps 3 through 6 can be repeated. 8. If the USB Flash drive already contains a file with the name file.txt, the demonstration application will append the text "Hello World" to the end of the file contents. 9. The LED on the starter kit illuminates if the file creation or write failed. On PIC32M-based starter kits, the LED is LED1. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 53 Multiple USB Controller This section describes the demonstrations that make use of multiple USB controllers on certain PIC32 microcontrollers. cdc_com_port_dual This application demonstrates dual USB Device operation on a PIC32 microcontroller with two USB Controllers. Description This application demonstrates dual USB Device operation on a PIC32 microcontroller with Two USB Controllers. In this demonstration both of the USB controllers act as CDC devices. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the Multiple USB CDC Device Dual COM Port Demonstration. Description To build this project, you must open the cdc_com_port_dual.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/multi_usb/cdc_com_port_dual. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location cdc_com_port_dual.X /apps/usb/multi_usb/cdc_com_port_dual/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mk_gp_db_int_dyn pic32mk_gp_db Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MK Evaluation Kit configured for interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MK General Purpose (GP) Development Board Switch S4 should be set to the Device position. Running the Demonstration This section provides instructions on how to build and run the USB Multiple Controller CDC Com Port Dual demonstration. Description This application demonstrates dual USB Device operation on a PIC32 microcontroller with two USB Controllers. The MPLAB Harmony USB Stack is capable of handling multiple USB controllers. In this demonstration, both of the USB controllers act as CDC devices. This demonstration allows the each controller on the PIC32 to appear like a serial (COM) port to the host. Do the following to run this demonstration: 1. First compile and program the target device. Refer to Building the Application for details. 2. Attach both USB connectors J15 and J13 to the host. 3. Refer to the Running the Demonstration section of the USB Device cdc_com_port_single demonstration for details on exercising the CDC device features. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 54 msd_dual This application demonstrates the capability of a PIC32 microcontroller and MPLAB Harmony USB Host stack to work with two USB Controllers in an application. Description This application demonstrates the capability of a PIC32 microcontroller and the MPLAB Harmony USB Host stack to work with two USB Controllers in an application. The MPLAB Harmony USB Stack is capable of handling multiple USB controllers. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the Dual MSD demonstration. Description To build this project, you must open the msd_dual.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/multi_usb/dual_msd. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location msd_dual.X /apps/usb/multi_usb/msd_dual/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mk_gp_deb_int_dyn pic32mk_gp_db Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MK Evaluation Kit configured for interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MK General Purpose (GP) Development Board • Switch S4 should be set to Host position • Jumper J28 must be installed • USB Connector J12 must be connected to a USB Host for powering the board • USB Flash drive should be attached to Connector J15 and J14 after programming the microcontroller Running the Demonstration This section provides instructions on how to build and run the USB Multiple Controller Dual MSD demonstration. Description This application demonstrates the capability of a PIC32 microcontroller and the MPLAB Harmony USB Host stack to work with two USB Controllers in an application. The MPLAB Harmony USB Stack is capable of handling multiple USB controllers. The application uses the USB Host_layer, MSD class driver, and the MPLAB Harmony File System Framework to enumerate a USB Flash drive and to write a file to it. Prior to using this demonstration, it is recommended to review the MPLAB Harmony Release Notes for any known issues. A PDF copy of the release notes is provided in the /doc folder of your installation. Do the following to run this demonstration: 1. Open the project in MPLAB X IDE and select the desired project configuration. 2. Build the code and program the device. 3. With the code running, attach a USB Flash drive with a file “file.txt” in it to one of the Host connector on the board. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 55 4. Connect another USB Flash drive to other Host connector on the board. Ensure this flash drive does not contain any file named newfile.txt. 5. The application will copy the file file.txt from the drive containing this file to the other drive. The copied file will be renamed as newfile.txt. LED2 on the demonstration board will illuminate to indicate completion of the file transfer. 6. Disconnect the drives and confirm demonstration success by inserting them into a personal computer and verifying the file transfer completed as expected. Dual Role This section describes the USB Dual Role Demonstrations. These demonstrations project demonstrate operation of the USB Host and the USB Device stack in the same project. host_msd_device_hid This application demonstrates role switching between USB Host MSD Stack and USB Device HID function. The role switch is trigger by a switch press. Description This application demonstrates role switching between USB Host MSD Stack and USB Device HID function. The role switch is trigger by a switch press. In the USB Host mode, the application performs read and write operations to a USB pen drive. In the USB Device mode, the application emulates a HID mouse. Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the USB Host MSD and USB HID Mouse Device Dual Role application. Description To build this project, you must open the host_msd_device_hid.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/usb/dual_role/host_msd_device_hid. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration. Project Name Location host_msd_device_hid.X /apps/usb/dual_role/host_msd_device_hid/firmware MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config. Project Configuration Name BSP Used Description pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit configured for Interrupt mode and dynamic operation. Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MZ EF Starter Kit No hardware related configuration or jumper setting changes are necessary. Running the Demonstration Provides instructions no how to build and run the USB Host MSD and USB HID Mouse Device Dual Role application. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 56 Description This application demonstrates the Dual Role capability of the MPLAB Harmony USB Stack. The application project includes both, the USB Host and Device Stacks. Both the stacks are initialized during application initialization. During operation, the application polls the switch SW2 on the starter kit to trigger a USB role switch. Note that the application cannot simultaneously operate as a host and device. The one USB role is exclusive of the other. Prior to using this demonstration, it is recommended to review the MPLAB Harmony Release Notes for any known issues. A PDF copy of the release notes is provided in the /doc folder of your installation. 1. Open the project and in MPLAB X IDE and select the desired project operation 2. Build the code and program the device. The application initially will not operate in any USB role. 3. Press SW2 on the starter kit. This places the application in a USB Device mode. 4. Connect a USB cable between micro USB connector (J4) on the starter kit and a PC USB host. The application will emulate a USB HID mouse function. The cursor on the PC will rotate. Pressing SW1 will enable and disable the cursor movements. Exercise device plug-n-play operation to confirm USB Device operation 5. Now try switching the USB role. Disconnect the USB cable between micro USB connector (J4) on the starter kit and a PC USB host. Press SW2 on the starter kit. 6. The application now will be in USB Host role. Connect a USB pen drive to the Type-A USB Host connector (J5) on the starter kit. The application will create a file (file.txt) on the pen drive. The completion of the operation is indicated by LED2 on the starter kit. Disconnect the pen driver and connect it to a PC to verify the contents of the file. 7. Repeat steps 3 through 6 to exercise the role switching capability. Volume I: Getting Started With MPLAB Harmony Applications Help USB Demonstrations © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 57 Index A Applications Help 3 audio_speaker 41 B Building the Application 10, 17, 19, 20, 23, 24, 26, 29, 30, 32, 33, 34, 35, 39, 40, 42, 43, 44, 45, 47, 48, 49, 50, 54, 55, 56 C cdc_basic 43 cdc_com_port_dual 10, 54 cdc_com_port_single 16 cdc_msd 44 cdc_msd_basic 19 cdc_serial_emulator 20 cdc_serial_emulator_msd 23 Configuring the Hardware 11, 17, 20, 21, 23, 25, 27, 29, 31, 32, 33, 35, 36, 39, 40, 42, 43, 45, 46, 47, 49, 50, 51, 54, 55, 56 USB Device Demonstration (hid_msd_basic) 32 D Demonstration Application Configurations 7 Demonstrations 10 USB 10 Device 10 Dual Role 56 H hid_basic 24 hid_basic_keyboard 45 hid_basic_mouse_usart 47 hid_joystick 26 hid_keyboard 29 hid_mouse 30 hid_msd_basic 32 Host 41 host_msd_device_hid 56 hub_cdc_hid 48 hub_msd 49 I Introduction 3 M msd_basic 33, 50 msd_dual 55 msd_fs_spiflash 34 msd_multiple_luns 35 msd_sdcard 38 Multiple USB Controller 54 R Running the Demonstration 13, 18, 20, 21, 24, 25, 27, 30, 31, 32, 34, 35, 38, 39, 41, 42, 43, 45, 46, 48, 49, 50, 53, 54, 55, 56 USB Device Demonstration (hid_keyboard) 29 USB Device Demonstrations (audio_speaker) 42 USB Device Demonstrations (hid_keyboard) 30 U USB Demonstrations 3 USB Device Stack Component Memory Requirements 5 USB Device Stack Demonstration Application Program and Data Memory Requirements 3 USB HID Host Keyboard and Mouse Tests 6 USB MSD Host USB Pen Drive Tests 5 V vendor 39 Volume I: Getting Started With MPLAB Harmony Libraries and Applications 2 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 58

 2000 Microchip Technology Inc. DS39500A PICmicro® 18C MCU Family Reference Manual 39500 18C Reference Manual.book Page i Monday, July 10, 2000 6:12 PM DS39500A-page ii  2000 Microchip Technology Inc. “All rights reserved. Copyright © 2000, Microchip Technology Incorporated, USA. Information contained in this publication regarding device applications and the like is intended through suggestion only and may be superseded by updates. No representation or warranty is given and no liability is assumed by Microchip Technology Incorporated with respect to the accuracy or use of such information, or infringement of patents or other intellectual property rights arising from such use or otherwise. Use of Microchip’s products as critical components in life support systems is not authorized except with express written approval by Microchip. No licenses are conveyed, implicitly or otherwise, under any intellectual property rights. The Microchip logo and name are registered trademarks of Microchip Technology Inc. in the U.S.A. and other countries. All rights reserved. All other trademarks mentioned herein are the property of their respective companies. No licenses are conveyed, implicitly or otherwise, under any intellectual property rights.” Trademarks The Microchip name, logo, KEELOQ, PIC, PICMASTER, PICmicro, PRO MATE, PICSTART, MPLAB, and SEEVAL are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. Total Endurance, In-Circuit Serial Programming (ICSP), microID, FilterLab are trademarks of Microchip Technology Incorporated in the U.S.A. Serialized Quick Term Programming (SQTP) is a service mark of Microchip Technology Incorporated in the U.S.A. All other trademarks mentioned herein are property of their respective companies. © 2000, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. 39500 18C Reference Manual.book Page ii Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39500A-page iii PAGE COMPANY PROFILE 1-1 SECTION 1. INTRODUCTION 1-1 Introduction ...................................................................................................................................................... 1-2 Manual Objective ............................................................................................................................................. 1-3 Device Structure ............................................................................................................................................... 1-4 Development Support ...................................................................................................................................... 1-6 Device Varieties ............................................................................................................................................... 1-7 Style and Symbol Conventions ...................................................................................................................... 1-12 Related Documents ........................................................................................................................................ 1-14 Related Application Notes .............................................................................................................................. 1-17 Revision History ............................................................................................................................................. 1-18 SECTION 2. OSCILLATOR 2-1 Introduction ...................................................................................................................................................... 2-2 Control Register ............................................................................................................................................... 2-3 Oscillator Configurations .................................................................................................................................. 2-4 Crystal Oscillators/Ceramic Resonators ........................................................................................................... 2-6 External RC Oscillator .................................................................................................................................... 2-15 HS4 ................................................................................................................................................................ 2-18 Switching to Low Power Clock Source ........................................................................................................... 2-19 Effects of Sleep Mode on the On-Chip Oscillator ........................................................................................... 2-23 Effects of Device Reset on the On-Chip Oscillator ......................................................................................... 2-23 Design Tips .................................................................................................................................................... 2-24 Related Application Notes .............................................................................................................................. 2-25 Revision History ............................................................................................................................................. 2-26 SECTION 3. RESET 3-1 Introduction ...................................................................................................................................................... 3-2 Resets and Delay Timers ................................................................................................................................. 3-4 Registers and Status Bit Values ..................................................................................................................... 3-14 Design Tips .................................................................................................................................................... 3-20 Related Application Notes .............................................................................................................................. 3-21 Revision History ............................................................................................................................................. 3-22 SECTION 4. ARCHITECTURE 4-1 Introduction ...................................................................................................................................................... 4-2 Clocking Scheme/Instruction Cycle .................................................................................................................. 4-5 Instruction Flow/Pipelining ............................................................................................................................... 4-6 I/O Descriptions ................................................................................................................................................ 4-7 Design Tips .................................................................................................................................................... 4-14 Related Application Notes .............................................................................................................................. 4-15 Revision History ............................................................................................................................................. 4-16 Table of Contents 39500 18C Reference Manual.book Page iii Monday, July 10, 2000 6:12 PM DS39500A-page iv  2000 Microchip Technology Inc. PAGE SECTION 5. CPU AND ALU 5-1 Introduction ...................................................................................................................................................... 5-2 General Instruction Format .............................................................................................................................. 5-6 Central Processing Unit (CPU) ......................................................................................................................... 5-7 Instruction Clock ............................................................................................................................................... 5-8 Arithmetic Logical Unit (ALU) ........................................................................................................................... 5-9 STATUS Register ........................................................................................................................................... 5-11 Design Tips .................................................................................................................................................... 5-14 Related Application Notes .............................................................................................................................. 5-15 Revision History ............................................................................................................................................. 5-16 SECTION 6. HARDWARE 8X8 MULTIPLIER 6-1 Introduction ...................................................................................................................................................... 6-2 Operation ......................................................................................................................................................... 6-3 Design Tips ...................................................................................................................................................... 6-6 Related Application Notes ................................................................................................................................ 6-7 Revision History ............................................................................................................................................... 6-8 SECTION 7. MEMORY ORGANIZATION 7-1 Introduction ...................................................................................................................................................... 7-2 Program Memory ............................................................................................................................................. 7-3 Program Counter (PC) ..................................................................................................................................... 7-6 Lookup Tables .................................................................................................................................................. 7-9 Stack .............................................................................................................................................................. 7-12 Data Memory Organization ............................................................................................................................ 7-13 Return Address Stack .................................................................................................................................... 7-17 Initialization .................................................................................................................................................... 7-23 Design Tips .................................................................................................................................................... 7-24 Related Application Notes .............................................................................................................................. 7-25 Revision History ............................................................................................................................................. 7-26 SECTION 8. TABLE READ/TABLE WRITE 8-1 Introduction ...................................................................................................................................................... 8-2 Control Registers ............................................................................................................................................. 8-3 Program Memory ............................................................................................................................................. 8-6 Enabling Internal Programming ...................................................................................................................... 8-12 External Program Memory Operation ............................................................................................................. 8-12 Initialization .................................................................................................................................................... 8-13 Design Tips .................................................................................................................................................... 8-14 Related Application Notes .............................................................................................................................. 8-15 Revision History ............................................................................................................................................. 8-16 Table of Contents 39500 18C Reference Manual.book Page iv Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39500A-page v PAGE SECTION 9. SYSTEM BUS 9-1 Revision History ............................................................................................................................................... 9-2 SECTION 10. INTERRUPTS 10-1 Introduction .................................................................................................................................................... 10-2 Control Registers ........................................................................................................................................... 10-6 Interrupt Handling Operation ........................................................................................................................ 10-19 Initialization .................................................................................................................................................. 10-29 Design Tips .................................................................................................................................................. 10-30 Related Application Notes ............................................................................................................................ 10-31 Revision History ........................................................................................................................................... 10-32 SECTION 11. I/O PORTS 11-1 Introduction .................................................................................................................................................... 11-2 PORTA, TRISA, and the LATA Register ........................................................................................................ 11-8 PORTB, TRISB, and the LATB Register ...................................................................................................... 11-12 PORTC, TRISC, and the LATC Register ..................................................................................................... 11-16 PORTD, LATD, and the TRISD Register ..................................................................................................... 11-19 PORTE, TRISE, and the LATE Register ...................................................................................................... 11-21 PORTF, LATF, and the TRISF Register ....................................................................................................... 11-23 PORTG, LATG, and the TRISG Register ..................................................................................................... 11-25 PORTH, LATH, and the TRISH Register ................................................................................................... 11-27 PORTJ, LATJ, and the TRISJ Register ........................................................................................................ 11-29 PORTK, LATK, and the TRISK Register ...................................................................................................... 11-31 PORTL, LATL, and the TRISL Register ....................................................................................................... 11-33 Functions Multiplexed on I/O Pins ................................................................................................................ 11-35 I/O Programming Considerations ................................................................................................................. 11-37 Initialization .................................................................................................................................................. 11-40 Design Tips .................................................................................................................................................. 11-41 Related Application Notes ............................................................................................................................ 11-43 Revision History ........................................................................................................................................... 11-44 SECTION 12. PARALLEL SLAVE PORT 12-1 Introduction .................................................................................................................................................... 12-2 Control Register ............................................................................................................................................. 12-3 Operation ....................................................................................................................................................... 12-5 Operation in SLEEP Mode ............................................................................................................................. 12-6 Effect of a RESET .......................................................................................................................................... 12-6 PSP Waveforms ............................................................................................................................................. 12-6 Design Tips .................................................................................................................................................... 12-8 Related Application Notes .............................................................................................................................. 12-9 Revision History ........................................................................................................................................... 12-10 Table of Contents 39500 18C Reference Manual.book Page v Monday, July 10, 2000 6:12 PM DS39500A-page vi  2000 Microchip Technology Inc. PAGE SECTION 13. TIMER0 13-1 Introduction .................................................................................................................................................... 13-2 Control Register ............................................................................................................................................. 13-3 Operation ....................................................................................................................................................... 13-4 Timer0 Interrupt .............................................................................................................................................. 13-5 Using Timer0 with an External Clock ............................................................................................................. 13-6 Timer0 Prescaler ............................................................................................................................................ 13-7 Initialization .................................................................................................................................................... 13-9 Design Tips .................................................................................................................................................. 13-10 Related Application Notes ............................................................................................................................ 13-11 Revision History ........................................................................................................................................... 13-12 SECTION 14. TIMER1 14-1 Introduction .................................................................................................................................................... 14-2 Control Register ............................................................................................................................................. 14-4 Timer1 Operation in Timer Mode ................................................................................................................... 14-5 Timer1 Operation in Synchronized Counter Mode ......................................................................................... 14-5 Timer1 Operation in Asynchronous Counter Mode ........................................................................................ 14-6 Reading and Writing of Timer1 ...................................................................................................................... 14-7 Timer1 Oscillator .......................................................................................................................................... 14-10 Typical Application ....................................................................................................................................... 14-11 Sleep Operation ........................................................................................................................................... 14-12 Resetting Timer1 Using a CCP Trigger Output ............................................................................................ 14-12 Resetting Timer1 Register Pair (TMR1H:TMR1L) ........................................................................................ 14-13 Timer1 Prescaler .......................................................................................................................................... 14-13 Initialization .................................................................................................................................................. 14-14 Design Tips .................................................................................................................................................. 14-16 Related Application Notes ............................................................................................................................ 14-17 Revision History ........................................................................................................................................... 14-18 SECTION 15. TIMER2 15-1 Introduction .................................................................................................................................................... 15-2 Control Register ............................................................................................................................................. 15-3 Timer Clock Source ........................................................................................................................................ 15-4 Timer (TMR2) and Period (PR2) Registers .................................................................................................... 15-4 TMR2 Match Output ....................................................................................................................................... 15-4 Clearing the Timer2 Prescaler and Postscaler ............................................................................................... 15-4 Sleep Operation ............................................................................................................................................. 15-4 Initialization .................................................................................................................................................... 15-5 Design Tips .................................................................................................................................................... 15-6 Related Application Notes .............................................................................................................................. 15-7 Revision History ............................................................................................................................................. 15-8 Table of Contents 39500 18C Reference Manual.book Page vi Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39500A-page vii PAGE SECTION 16. TIMER3 16-1 Introduction .................................................................................................................................................... 16-2 Control Registers ........................................................................................................................................... 16-3 Timer3 Operation in Timer Mode ................................................................................................................... 16-4 Timer3 Operation in Synchronized Counter Mode ......................................................................................... 16-4 Timer3 Operation in Asynchronous Counter Mode ........................................................................................ 16-5 Reading and Writing of Timer3 ...................................................................................................................... 16-6 Timer3 using the Timer1 Oscillator ................................................................................................................ 16-9 Timer3 and CCPx Enable ............................................................................................................................ 16-10 Timer3 Prescaler .......................................................................................................................................... 16-10 16-bit Mode Timer Reads/Writes .................................................................................................................. 16-11 Typical Application ....................................................................................................................................... 16-12 Sleep Operation ........................................................................................................................................... 16-13 Timer3 Prescaler .......................................................................................................................................... 16-13 Initialization .................................................................................................................................................. 16-14 Design Tips .................................................................................................................................................. 16-16 Related Application Notes ............................................................................................................................ 16-17 Revision History ........................................................................................................................................... 16-18 SECTION 17. COMPARE/CAPTURE/PWM (CCP) 17-1 Introduction .................................................................................................................................................... 17-2 CCP Control Register ..................................................................................................................................... 17-3 Capture Mode ................................................................................................................................................ 17-4 Compare Mode .............................................................................................................................................. 17-7 PWM Mode .................................................................................................................................................. 17-10 Initialization .................................................................................................................................................. 17-15 Design Tips .................................................................................................................................................. 17-17 Related Application Notes ............................................................................................................................ 17-19 Revision History ........................................................................................................................................... 17-20 SECTION 18. ECCP 18-1 SECTION 19. SYNCHRONOUS SERIAL PORT (SSP) 19-1 Introduction .................................................................................................................................................... 19-2 Control Registers ........................................................................................................................................... 19-4 SPI Mode ....................................................................................................................................................... 19-8 SSP I2C Operation ....................................................................................................................................... 19-18 Initialization .................................................................................................................................................. 19-28 Design Tips .................................................................................................................................................. 19-30 Related Application Notes ............................................................................................................................ 19-31 Revision History ........................................................................................................................................... 19-32 Table of Contents 39500 18C Reference Manual.book Page vii Monday, July 10, 2000 6:12 PM DS39500A-page viii  2000 Microchip Technology Inc. PAGE SECTION 20. MASTER SSP 20-1 Introduction .................................................................................................................................................... 20-2 Control Registers ........................................................................................................................................... 20-4 SPI Mode ....................................................................................................................................................... 20-9 MSSP I2C Operation .................................................................................................................................... 20-18 Design Tips .................................................................................................................................................. 20-58 Related Application Notes ............................................................................................................................ 20-59 Revision History ........................................................................................................................................... 20-60 SECTION 21. ADDRESSABLE USART 21-1 Introduction .................................................................................................................................................... 21-2 Control Registers ........................................................................................................................................... 21-3 USART Baud Rate Generator (BRG) ............................................................................................................. 21-5 USART Asynchronous Mode ......................................................................................................................... 21-9 USART Synchronous Master Mode ............................................................................................................. 21-18 USART Synchronous Slave Mode ............................................................................................................... 21-23 Initialization .................................................................................................................................................. 21-25 Design Tips .................................................................................................................................................. 21-26 Related Application Notes ............................................................................................................................ 21-27 Revision History ........................................................................................................................................... 21-28 SECTION 22. CAN 22-1 Introduction .................................................................................................................................................... 22-2 Control Registers for the CAN Module ........................................................................................................... 22-3 CAN Overview .............................................................................................................................................. 22-28 CAN Bus Features ....................................................................................................................................... 22-32 CAN Module Implementation ....................................................................................................................... 22-33 Frame Types ................................................................................................................................................ 22-37 Modes of Operation ...................................................................................................................................... 22-44 CAN Bus Initialization ................................................................................................................................... 22-48 Message Reception ..................................................................................................................................... 22-49 Transmission ................................................................................................................................................ 22-60 Error Detection ............................................................................................................................................. 22-69 Baud Rate Setting ........................................................................................................................................ 22-71 Interrupts ...................................................................................................................................................... 22-75 Timestamping ............................................................................................................................................... 22-77 CAN Module I/O ........................................................................................................................................... 22-77 Design Tips .................................................................................................................................................. 22-78 Related Application Notes ............................................................................................................................ 22-79 Revision History ........................................................................................................................................... 22-80 Table of Contents 39500 18C Reference Manual.book Page viii Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39500A-page ix PAGE SECTION 23. COMPARATOR VOLTAGE REFERENCE 23-1 Introduction .................................................................................................................................................... 23-2 Control Register ............................................................................................................................................. 23-3 Configuring the Voltage Reference ................................................................................................................ 23-4 Voltage Reference Accuracy/Error ................................................................................................................. 23-5 Operation During Sleep .................................................................................................................................. 23-5 Effects of a Reset ........................................................................................................................................... 23-5 Connection Considerations ............................................................................................................................ 23-6 Initialization .................................................................................................................................................... 23-7 Design Tips .................................................................................................................................................... 23-8 Related Application Notes .............................................................................................................................. 23-9 Revision History ........................................................................................................................................... 23-10 SECTION 24. COMPARATOR 24-1 Introduction .................................................................................................................................................... 24-2 Control Register ............................................................................................................................................. 24-3 Comparator Configuration .............................................................................................................................. 24-4 Comparator Operation ................................................................................................................................... 24-6 Comparator Reference ................................................................................................................................... 24-6 Comparator Response Time .......................................................................................................................... 24-8 Comparator Outputs ....................................................................................................................................... 24-8 Comparator Interrupts .................................................................................................................................... 24-9 Comparator Operation During SLEEP ........................................................................................................... 24-9 Effects of a RESET ........................................................................................................................................ 24-9 Analog Input Connection Considerations ..................................................................................................... 24-10 Initialization .................................................................................................................................................. 24-11 Design Tips .................................................................................................................................................. 24-12 Related Application Notes ............................................................................................................................ 24-13 Revision History ........................................................................................................................................... 24-14 SECTION 25. COMPATIBLE 10-BIT A/D CONVERTER 25-1 Introduction .................................................................................................................................................... 25-2 Control Register ............................................................................................................................................. 25-4 Operation ....................................................................................................................................................... 25-7 A/D Acquisition Requirements ....................................................................................................................... 25-8 Selecting the A/D Conversion Clock ............................................................................................................ 25-10 Configuring Analog Port Pins ....................................................................................................................... 25-11 A/D Conversions .......................................................................................................................................... 25-12 Operation During Sleep ................................................................................................................................ 25-16 Effects of a Reset ......................................................................................................................................... 25-16 A/D Accuracy/Error ...................................................................................................................................... 25-17 Connection Considerations .......................................................................................................................... 25-18 Transfer Function ......................................................................................................................................... 25-18 Initialization .................................................................................................................................................. 25-19 Design Tips .................................................................................................................................................. 25-20 Related Application Notes ............................................................................................................................ 25-21 Revision History ........................................................................................................................................... 25-22 Table of Contents 39500 18C Reference Manual.book Page ix Monday, July 10, 2000 6:12 PM DS39500A-page x  2000 Microchip Technology Inc. PAGE SECTION 26. 10-BIT A/D CONVERTER 26-1 Introduction .................................................................................................................................................... 26-2 Control Register ............................................................................................................................................. 26-4 Operation ....................................................................................................................................................... 26-7 A/D Acquisition Requirements ....................................................................................................................... 26-8 Selecting the A/D Conversion Clock ............................................................................................................ 26-10 Configuring Analog Port Pins ....................................................................................................................... 26-11 A/D Conversions .......................................................................................................................................... 26-12 Operation During Sleep ................................................................................................................................ 26-16 Effects of a Reset ......................................................................................................................................... 26-16 A/D Accuracy/Error ...................................................................................................................................... 26-17 Connection Considerations .......................................................................................................................... 26-18 Transfer Function ......................................................................................................................................... 26-18 Initialization .................................................................................................................................................. 26-19 Design Tips .................................................................................................................................................. 26-20 Related Application Notes ............................................................................................................................ 26-21 Revision History ........................................................................................................................................... 26-22 SECTION 27. LOW VOLTAGE DETECT 27-1 Introduction .................................................................................................................................................... 27-2 Control Register ............................................................................................................................................. 27-4 Operation ....................................................................................................................................................... 27-5 Operation During Sleep .................................................................................................................................. 27-6 Effects of a Reset ........................................................................................................................................... 27-6 Initialization .................................................................................................................................................... 27-7 Design Tips .................................................................................................................................................... 27-8 Related Application Notes .............................................................................................................................. 27-9 Revision History ........................................................................................................................................... 27-10 SECTION 28. WDT AND SLEEP MODE 28-1 Introduction .................................................................................................................................................... 28-2 Control Register ............................................................................................................................................. 28-3 Watchdog Timer (WDT) Operation ................................................................................................................. 28-4 SLEEP (Power-Down) Mode .......................................................................................................................... 28-5 Initialization .................................................................................................................................................. 28-11 Design Tips .................................................................................................................................................. 28-12 Related Application Notes ............................................................................................................................ 28-13 Revision History ........................................................................................................................................... 28-14 Table of Contents 39500 18C Reference Manual.book Page x Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39500A-page xi PAGE SECTION 29. DEVICE CONFIGURATION BITS 29-1 Introduction .................................................................................................................................................... 29-2 Configuration Word Bits ................................................................................................................................. 29-3 Program Verification/Code Protection .......................................................................................................... 29-10 ID Locations ................................................................................................................................................. 29-11 Device ID ...................................................................................................................................................... 29-11 Design Tips .................................................................................................................................................. 29-12 Related Application Notes ............................................................................................................................ 29-13 Revision History ........................................................................................................................................... 29-14 SECTION 30. IN-CIRCUIT SERIAL PROGRAMMING™ (ICSP™) 30-1 Introduction .................................................................................................................................................... 30-2 Entering In-Circuit Serial Programming Mode ................................................................................................ 30-3 Application Circuit .......................................................................................................................................... 30-4 Programmer ................................................................................................................................................... 30-6 Programming Environment ............................................................................................................................ 30-6 Other Benefits ................................................................................................................................................ 30-7 Field Programming of PICmicro OTP MCUs .................................................................................................. 30-8 Field Programming of FLASH PICmicros ..................................................................................................... 30-10 Design Tips .................................................................................................................................................. 30-12 Related Application Notes ............................................................................................................................ 30-13 Revision History ........................................................................................................................................... 30-14 SECTION 31. INSTRUCTION SET 31-1 Introduction .................................................................................................................................................... 31-2 Data Memory Map .......................................................................................................................................... 31-3 Instruction Formats ........................................................................................................................................ 31-9 Special Function Registers as Source/Destination ...................................................................................... 31-12 Fast Register Stack ...................................................................................................................................... 31-13 Q Cycle Activity ............................................................................................................................................ 31-13 Instruction Descriptions ................................................................................................................................ 31-14 Design Tips ................................................................................................................................................ 31-136 Related Application Notes .......................................................................................................................... 31-137 Revision History ......................................................................................................................................... 31-138 Table of Contents 39500 18C Reference Manual.book Page xi Monday, July 10, 2000 6:12 PM DS39500A-page xii  2000 Microchip Technology Inc. PAGE SECTION 32. ELECTRICAL SPECIFICATIONS 32-1 Introduction .................................................................................................................................................... 32-2 Absolute Maximums ....................................................................................................................................... 32-3 Voltage vs Frequency Graph ......................................................................................................................... 32-4 Device Voltage Specifications ........................................................................................................................ 32-6 Device Current Specifications ........................................................................................................................ 32-7 Input Threshold Levels ................................................................................................................................. 32-10 I/O Current Specifications ............................................................................................................................ 32-11 Output Drive Levels ...................................................................................................................................... 32-12 I/O Capacitive Loading ................................................................................................................................. 32-13 Low Voltage Detect (LVD) ............................................................................................................................ 32-14 EPROM/FLASH/Data EEPROM .................................................................................................................. 32-15 Comparators and Voltage Reference ........................................................................................................... 32-16 Timing Parameter Symbology ...................................................................................................................... 32-18 Example External Clock Timing Waveforms and Requirements .................................................................. 32-19 Example Phase Lock Loop (PLL) Timing Waveforms and Requirements ................................................... 32-20 Example Power-up and RESET Timing Waveforms and Requirements ...................................................... 32-22 Example Timer0 and Timer1 Timing Waveforms and Requirements ........................................................... 32-23 Example CCP Timing Waveforms and Requirements ................................................................................. 32-24 Example Parallel Slave Port (PSP) Timing Waveforms and Requirements ................................................. 32-25 Example SSP and Master SSP SPI Mode Timing Waveforms and Requirements ...................................... 32-26 Example SSP I2C Mode Timing Waveforms and Requirements .................................................................. 32-30 Example Master SSP I2C Mode Timing Waveforms and Requirements ...................................................... 32-32 Example USART/SCI Timing Waveforms and Requirements ...................................................................... 32-34 CAN Specifications ...................................................................................................................................... 32-35 Example 8-bit A/D Timing Waveforms and Requirements ........................................................................... 32-36 Example 10-bit A/D Timing Waveforms and Requirements ......................................................................... 32-38 Design Tips .................................................................................................................................................. 32-40 Related Application Notes ............................................................................................................................ 32-41 Revision History ........................................................................................................................................... 32-42 SECTION 33. DEVICE CHARACTERISTICS 33-1 Introduction .................................................................................................................................................... 33-2 Characterization vs. Electrical Specification ................................................................................................... 33-2 DC and AC Characteristics Graphs and Tables ............................................................................................. 33-2 Revision History ........................................................................................................................................... 33-26 Table of Contents 39500 18C Reference Manual.book Page xii Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39500A-page xiii PAGE SECTION 34. DEVELOPMENT TOOLS 34-1 Introduction .................................................................................................................................................... 34-2 The Integrated Development Environment (IDE) ........................................................................................... 34-3 MPLAB® Software Language Support ........................................................................................................... 34-6 MPLAB-SIM Simulator Software .................................................................................................................... 34-8 MPLAB Emulator Hardware Support .............................................................................................................. 34-9 MPLAB High Performance Universal In-Circuit Emulator with MPLAB IDE ................................................... 34-9 MPLAB-ICD In-Circuit Debugger .................................................................................................................... 34-9 MPLAB Programmer Support ...................................................................................................................... 34-10 Supplemental Tools ..................................................................................................................................... 34-11 Development Boards .................................................................................................................................... 34-12 Development Tools for Other Microchip Products ........................................................................................ 34-14 Related Application Notes ............................................................................................................................ 34-15 Revision History ........................................................................................................................................... 34-16 SECTION 35. CODE DEVELOPMENT 35-1 Overview ........................................................................................................................................................ 35-2 Good Practice ................................................................................................................................................ 35-3 Diagnostic Code Techniques ......................................................................................................................... 35-5 Example Scenario and Implementation ......................................................................................................... 35-6 Implications of Using a High Level Language (HLL) ...................................................................................... 35-7 Revision History ............................................................................................................................................. 35-8 SECTION 36. APPENDIX 36-1 Appendix A: I2C Overview............................................................................................................................... 36-1 Appendix B: CAN Overview ......................................................................................................................... 36-12 Appendix C: Module Block Diagrams and Registers..................................................................................... 36-13 Appendix D: Register Definitions .................................................................................................................. 36-14 Appendix E: Migration Tips ........................................................................................................................... 36-15 SECTION 37. GLOSSARY 37-1 Revision History ........................................................................................................................................... 37-14 SOURCE CODE INDEX Table of Contents 39500 18C Reference Manual.book Page xiii Monday, July 10, 2000 6:12 PM DS39500A-page xiv  2000 Microchip Technology Inc. PAGE NOTES: Table of Contents 39500 18C Reference Manual.book Page xiv Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS00027U-page xv The Embedded Control Solutions Company Since its inception, Microchip Technology has focused its resources on delivering innovative semiconductor products to the global embedded control marketplace. To do this, we have focused our technology, engineering, manufacturing and marketing resources on synergistic product lines: PICmicro® microcontrollers (MCUs), high-endurance Serial EEPROMs, an expanding product portfolio of analog/ interface products, RFID tags and KEELOQ® security devices – all aimed at delivering comprehensive, high-value embedded control solutions to a growing base of customers. Inside Microchip Technology you will find: • An experienced executive team focused on innovation and committed to listening to our customers • A focus on providing high-performance, cost-effective embedded control solutions • Fully integrated manufacturing capabilities • A global network of manufacturing and customer support facilities • A unique corporate culture dedicated to continuous improvement • Distributor network support worldwide including certified distribution FAEs • A Complete Product Solution including: - RISC OTP, FLASH, EEPROM and ROM MCUs - A full family of advanced analog MCUs - KEELOQ security devices featuring patented code hopping technology - Stand-alone analog and interface products plus microID™ RFID tagging devices - A complete line of high-endurance Serial EEPROMs - World-class, easy-to-use development tools - An Automotive Products Group to engage with key automotive accounts and provide necessary application expertise and customer service Business Scope Microchip Technology Inc. designs, manufactures, and markets a variety of CMOS semiconductor components to support the market for cost-effective embedded control solutions. Microchip's products feature compact size, integrated functionality, ease of development and technical support so essential to timely and cost-effective product development by our customers. Company Profile Chandler, Arizona: Company headquarters near Phoenix, Arizona; executive offices, R&D and wafer fabrication occupy this 242,000 square-foot multi-building campus. Tempe, Arizona: Microchip’s 200,000 square-foot wafer fabrication facility provides increased manufacturing capacity today and for the future. 39500 18C Reference Manual.book Page xv Monday, July 10, 2000 6:12 PM DS00027U-page xvi  2000 Microchip Technology Inc. Market Focus Microchip targets select markets where our advanced designs, progressive process technology and industry-leading product performance enables us to deliver decidedly superior performance. Our Company is positioned to provide a complete product solution for embedded control applications found throughout the consumer, automotive, telecommunication, office automation and industrial control markets. Microchip products are also meeting the unique design requirements of targeted embedded applications including internet, safety and security. Certified Quality Systems Microchip’s quality systems have been certified to QS-9000 requirements. Its worldwide headquarters and wafer fabrication facilities in Chandler and Tempe, Arizona, received certification on July 23, 1999. The scope of this certification is the design and manufacture of RISC-based MCUs, related non-volatile memory products and microperipheral devices. The quality systems for Microchip’s product test facility in Bangkok, Thailand, were QS-9000 certified on February 26, 1999. The scope of this certification is the design and testing of integrated circuits. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001 certified. QS-9000 was developed by Chrysler, Ford and General Motors to establish fundamental quality systems that provide for continuous improvement, emphasizing defect prevention and the reduction of variation and waste in the supply chain. Microchip was audited by QS-9000 registrar Det Norske Veritas Certification Inc. of Houston, the same firm which granted Microchip its ISO 9001 Quality System certification in 1997. QS-9000 certification recognizes Microchip’s quality systems conform to the stringent standards set forth by the automotive industry, benefiting all customers. Fully Integrated Manufacturing Microchip delivers fast turnaround and consistent quality through total control over all phases of production. Research and development, design, mask making, wafer fabrication, and the major part of assembly and quality assurance testing are conducted at facilities wholly-owned and operated by Microchip. Our integrated approach to manufacturing along with rigorous use of advanced Statistical Process Control (SPC) and a continuous improvement culture has resulted in high and consistent yields which have positioned Microchip as a quality leader in its global markets. Microchip’s unique approach to SPC provides customers with excellent pricing, quality, reliability and on-time delivery. A Global Network of Plants and Facilities Microchip is a global competitor providing local services to the world’s technology centers. The Company’s design and technology advancement facilities, and wafer fabrication sites are located in Chandler and Tempe, Arizona. The Tempe facility provides an additional 200,000 square feet of manufacturing space that meets the increased production requirements of a growing customer base, and provides production capacity which more than doubles that of Chandler. Microchip facilities in Bangkok, Thailand, and Shanghai, China, serve as the foundation of Microchip’s extensive assembly and test capability located throughout Asia. The use of multiple fabrication, assembly and test sites, with more than 640,000-square-feet of facilities worldwide, ensures Microchip’s ability to meet the increased production requirements of a fast growing customer base. Microchip supports its global customer base from direct sales and engineering offices in Asia, North America, Europe and Japan. Offices are staffed to meet the high quality expectations of our customers, and can be accessed for technical and business support. The Company also franchises more than 60 distributors and a network of technical manufacturer’s representatives serving 24 countries worldwide. Bangkok, Thailand: Microchip’s 200,000 square-foot manufacturing facility houses the technology and assembly/test equipment for high speed testing and packaging. 39500 18C Reference Manual.book Page xvi Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS00027U-page xvii Embedded Control Overview Unlike “processor” applications such as personal computers and workstations, the computing or controlling elements of embedded control applications are embedded inside the application. The consumer is only concerned with the very top-level user interface such as keypads, displays and high-level commands. Very rarely does an end-user know (or care to know) the embedded controller inside (unlike the conscientious PC users, who are intimately familiar not only with the processor type, but also its clock speed, DMA capabilities and so on). It is, however, most vital for designers of embedded control products to select the most suitable controller and companion devices. Embedded control products are found in all market segments: consumer, commercial, PC peripherals, telecommunications, automotive and industrial. Most embedded control products must meet special requirements: cost effectiveness, low-power, small-footprint and a high level of system integration. Typically, most embedded control systems are designed around an MCU which integrates on-chip program memory, data memory (RAM) and various peripheral functions, such as timers and serial communication. In addition, these systems usually require complementary Serial EEPROM, analog/interface devices, display drivers, keypads or small displays. Microchip has established itself as a leading supplier of embedded control solutions. The combination of high-performance PIC12CXXX, PIC16C5X, PIC16CXXX, PIC17CXXX and PIC18CXXX MCU families with Migratable Memory™ technology, along with non-volatile memory products, provide the basis for this leadership. By further expanding our product portfolio to provide precision analog and interface products, Microchip is committed to continuous innovation and improvement in design, manufacturing and technical support to provide the best possible embedded control solutions to you. PICmicro MCU Overview and Roadmap Microchip PICmicro MCUs combine high-performance, low-cost, and small package size, offering the best price/performance ratio in the industry. More than one billion of these devices have shipped to customers worldwide since 1990. Microchip offers five families of MCUs to best fit your application needs: • PIC12CXXX 8-pin 12-bit/14-bit program word • PIC16C5X 12-bit program word • PIC16CXXX 14-bit program word • PIC17CXXX 16-bit program word • PIC18CXXX enhanced 16-bit program word All families offer OTP, low-voltage and low-power options, with a variety of package options. Selected members are available in ROM, EEPROM or reprogrammable FLASH versions. PIC12CXXX: 8-Pin, Family The PIC12CXXX family packs Microchip’s powerful RISC-based PICmicro architecture into 8-pin DIP and SOIC packages. These PIC12CXXX products are available with either a 12-bit or 14-bit wide instruction set, a low operating voltage of 2.5V, small package footprints, interrupt handling, a deeper hardware stack, multiple channels and EEPROM data memory. All of these features provide an intelligence level not previously available in applications because of cost or size considerations. PIC16C5X: 12-Bit Architecture Family The PIC16C5X is the well-established base-line family that offers the most cost-effective solution. These PIC16C5X products have a 12-bit wide instruction set and are currently offered in 14-, 18-, 20- and 28-pin packages. In the SOIC and SSOP packaging options, these devices are among the smallest footprint MCUs in the industry. Low-voltage operation, down to 2.0V for OTP MCUs, makes this family ideal for battery operated applications. Additionally, the PIC16HV5XX can operate up to 15 volts for use directly with a battery. PIC16CXXX: 14-Bit Architecture Family With the introduction of new PIC16CXXX family members, Microchip now provides the industry’s highest performance Analog-to-Digital Converter capability at 12-bits for an MCU. The PIC16CXXX family offers a wide-range of options, from 18- to 68-pin packages as well as low to high levels of peripheral integration. This family has a 14-bit wide instruction set, interrupt handling capability and a deep, 8-level hardware stack. The PIC16CXXX family provides the performance and versatility to meet the more demanding requirements of today’s cost-sensitive marketplace for mid-range applications. PIC17CXXX: 16-Bit Architecture Family The PIC17CXXX family offers the world’s fastest execution performance of any MCU family in the industry. The PIC17CXXX family extends the PICmicro MCU’s high-performance RISC architecture with a 16-bit instruction word, enhanced instruction set and powerful vectored interrupt handling capabilities. A powerful array of precise on-chip peripheral features provides the performance for the most demanding applications. PIC18CXXX: 16-Bit Enhanced Architecture Family The PIC18CXXX is a family of high performance, CMOS, fully static, 16-bit MCUs with integrated analog-to-digital (A/D) converter. All PIC18CXXX MCUs incorporate an advanced RISC architecture. The PIC18CXXX has enhanced core features, 32 level-deep stack, and multiple internal and external interrupts sources. The separate instruction and data busses of the Harvard architecture allow a 16-bit wide instruction word with the separate 8-bit wide data. The two-stage instruction pipeline allows all instructions to execute in a single cycle, except for program branches, which require two cycles. A total of 77 instructions (reduced instruction set) are available. Additionally, a large register set gives some of the architectural 39500 18C Reference Manual.book Page xvii Monday, July 10, 2000 6:12 PM DS00027U-page xviii  2000 Microchip Technology Inc. innovations used to achieve a very high performance of 10 MIPS for an MCU. The PIC18CXXX family has special features to reduce external components, thus reducing cost, enhancing system reliability and reducing power consumption. These include programmable Low Voltage Detect (LVD) and programmable Brown-Out Detect (BOD). The Mechatronics Revolution The nature of the revolution is the momentous shift from analog/electro-mechanical timing and control to digital electronics. It is called the Mechatronics Revolution, and it is being staged in companies throughout the world, with design engineers right on the front lines: make it smarter, make it smaller, make it do more, make it cost less to manufacture – and make it snappy. To meet the needs of this growing customer base, Microchip is rapidly expanding its already broad line of PICmicro MCUs. The PIC12CXXX family’s size opens up new possibilities for product design. PICmicro MCU Naming Convention The PICmicro architecture offers users a wider range of cost/performance options than any MCU family. In order to identify the families, the following naming conventions have been applied to the PICmicro MCUs: TABLE 1: PICmicro MCU NAMING CONVENTION* *Please check with your local Microchip distributor, sales representative or sales office for the latest product information. Family Architectural Features Name Technology PIC18CXXX 8-bit HighPerformance MCU Family • 10 MIPS @ 40 MHz • 4x PLL clock • 16-bit wide instruction set • C compiler efficient instruction set • Internal/external vectored interrupts PIC18CXX2 PIC18FXXX OTP program memory with higher resolution analog functions FLASH program memory PIC17CXXX 8-bit High-Performance MCU Family • 16-bit wide instruction set • Internal/external vectored interrupts • DC - 33 MHz clock speed • 120 ns instruction cycle (@ 33 MHz) • Hardware multiply PIC17C4X OTP program memory, digital only PIC17CR4X ROM program memory, digital only PIC17C7XX OTP program memory with mixed-signal functions PIC16CXXX 8-bit Mid-Range MCU Family • 14-bit wide instruction set • Internal/external interrupts • DC - 20 MHz clock speed (Note 1) • 200 ns instruction cycle (@ 20 MHz) PIC14CXXX OTP program memory with A/D and D/A functions PIC16C55X OTP program memory, digital only PIC16C6X OTP program memory, digital only PIC16CR6X ROM program memory, digital only PIC16C62X OTP program memory with comparators PIC16CR62X ROM program memory with comparators PIC16CE62X OTP program memory with comparators and EEPROM data memory PIC16F62X FLASH program memory with comparators and EEPROM data memory PIC16C64X OTP program memory with comparators PIC16C66X OTP program memory with comparators PIC16C7X OTP program memory with analog functions (i.e. A/D) PIC16CR7X ROM program memory with analog functions PIC16C7XX OTP program memory with higher resolution analog functions PIC16F8X FLASH program memory and EEPROM data memory PIC16CR8X ROM program memory and EEPROM data memory PIC16F87X FLASH program memory with higher resolution analog functions PIC16C9XX OTP program memory, LCD driver PIC16C5X 8-bit Base-Line MCU Family • 12-bit wide instruction set • DC - 20 MHz clock speed • 200 ns instruction cycle (@ 20 MHz) PIC16C5X OTP program memory, digital only PIC16CR5X ROM program memory, digital only PIC16C505 OTP program memory, digital only, internal 4 MHz oscillator PIC16HV540 OTP program memory with high voltage operation PIC12CXXX 8-bit, 8-pin MCU Family • 12- or 14-bit wide instruction set • DC - 10 MHz clock speed • 400 ns instruction cycle (@ 10 MHz) • Internal 4 MHz oscillator PIC12C5XX OTP program memory, digital only PIC12CE5XX OTP program memory, digital only with EEPROM data memory PIC12CR5XX ROM program memory, digital only PIC12C67X OTP program memory with analog functions PIC12CE67X OTP program memory with analog functions and EEPROM data memory Note 1: The maximum clock speed for some devices is less than 20 MHz. 39500 18C Reference Manual.book Page xviii Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS00027U-page xix Development Systems Microchip is committed to providing useful and innovative solutions to your embedded system designs. Our installed base of application development systems has grown to an impressive 170,000 systems worldwide. Among support products offered are MPLAB®-ICE 2000 In-Circuit Emulator running under the Windows environment. This new real-time emulator supports low-voltage emulation, to 2.0 volts, and full-speed emulation. MPLAB, a complete Integrated Development Environment (IDE), is provided with MPLAB-ICE 2000. MPLAB allows the user to edit, compile and emulate from a single user interface, making the developer productive very quickly. MPLAB-ICE 2000 is designed to provide product development engineers with an optimized design tool for developing target applications. This universal in-circuit emulator provides a complete MCU design toolset for PICmicro MCUs in the PIC12CXXX, PIC16C5X, PIC16CXXX, PIC17CXXX and PIC18CXXX families. MPLAB-ICE 2000 is CE compliant. Microchip’s newest development tool, MPLAB In-Circuit Debugger (ICD) Evaluation Kit, uses the in-circuit debugging capabilities of the PIC16FXXX and PIC18FXXX MCU family and Microchip’s ICSP™ capability to debug source code in the application, debug hardware in real time and program a target PIC16FXXX and PIC18FXXX device. PRO MATE II, the full-featured, modular device programmer, enables you to quickly and easily program user software into PICmicro MCUs, HCS products and Serial EEPROMs. PRO MATE II runs under MPLAB IDE and operates as a stand-alone unit or in conjunction with a PC-compatible host system. The PICSTART Plus development kit is a low-cost development system for the PIC12CXXX, PIC16C5X, PIC16CXXX and PIC17CXXX MCUs. PICDEM low-cost demonstration boards are simple boards which demonstrate the basic capabilities of the full range of Microchip’s MCUs. Users can program the sample MCUs provided with PICDEM boards, on a PRO MATE II or PICSTART Plus programmer, and easily test firmware. KEELOQ Evaluation Tools support Microchip’s HCS Secure Data Products. The Serial EEPROM Designer’s Kit includes everything necessary to read, write, erase or program special features of any Microchip Serial EEPROMs. The Total Endurance Disk is included to aid in trade-off analysis and reliability calculations. The total kit can significantly reduce time-to-market and result in an optimized system. The FilterLab™ Active Filter Design Tool simplifies active filter design for embedded systems designers. The unique FilterLab software automates the design of the anti-aliasing filter for an analog-to-digital converter-based data acquisition system. FilterLab also provides full schematic diagrams of the filter circuit with component values, a SPICE model, and displays the frequency and phase response. In addition to the FilterLab Active Filter Design Tool, Microchip offers a second analog development tool, the MXDEV™1 Analog Evaluation System, making it easier for embedded systems designers to evaluate and develop with Microchip’s line of stand-alone analog products. The hardware and software within the MXDEV 1 system is configured device-specific and allows single or continuous conversions ofr the analog-to-digital converter under evaluation. The MCP2510 Controller Area Network (CAN) Developer’s Kit makes software developing easy by using a variety of features to manipulate the functionality of the MCP2510. The MCP2510 CAN Developer’s kit provides the ability to read, display and modify all registers of the MCP2510 on a bit-by-bit or a byte-by-byte basis. The microID™ Developer’s Kit is an easy-to-use tool for design engineers at all skill levels. Available in a variety of configurations, the microID family of RFID tags can be configured to match existing tags and be directly installed - upgrading to contactless programmability at no added cost. This kit includes all the hardware, software, reference designs and samples required to get started in RFID designs. TABLE 2: PICmicro SYNERGISTIC DEVELOPMENT TOOLS Development Tool Name PIC12CXXX PIC16C5X PIC16CXXX PIC16F87X PIC17CXXX PIC18CXXX Integrated Development Environment (IDE) MPLAB ✔✔✔ — ✔ ✔ C Compiler MPLAB-C17 — — — — ✔ MPLAB-C18 — — — — — ✔ Full-Featured, Modular In-Circuit Emulator MPLAB-ICE 2000 ✔✔✔ — ✔ ✔ In-Circuit Debugger Evaluation Kit MPLAB-ICD — — — ✔ — — Full-Featured, Modular Device Programmer PRO MATE II ✔✔✔ — ✔ ✔ Entry-Level Development Kit with Programmer PICSTART Plus ✔✔✔ — ✔ ✔ 39500 18C Reference Manual.book Page xix Monday, July 10, 2000 6:12 PM DS00027U-page xx  2000 Microchip Technology Inc. Software Support MPLAB Integrated Development Environment (IDE) is a Windows-based development platform for Microchip’s PICmicro MCUs. MPLAB IDE offers a project manager and program text editor, a user-configurable toolbar containing four pre-defined sets and a status bar which communicates editing and debugging information. MPLAB-IDE is the common user interface for Microchip development systems tools including MPLAB Editor, MPASM Assembler, MPLAB-SIM Software Simulator, MPLIB, MPLINK, MPLAB-C17 Compiler, MPLAB-C18 Compiler, MPLAB-ICE 2000, PRO MATE II Programmer and PICSTART Plus Development Programmer. Microchip endeavors at all times to provide the best service and responsiveness possible to its customers. The Microchip Internet site can provide you with the latest technical information, production released software for development tools, application notes and promotional news on Microchip products and technology. The Microchip World Wide Web address is http://www.microchip.com. Secure Data Products Overview Microchip’s patented KEELOQ® code hopping technology is the perfect solution for remote keyless entry and logical/physical access control systems. The initial device in the family, the HCS300 encoder, replaces current fixed code encoders in transmitter applications providing a low cost, integrated solution. The KEELOQ family is continuing to expand with the HCS301 (high voltage encoder), HCS200 (low-end, low-cost encoder), and high-end encoders (HCS360 and HCS361) that meet OEM specifications and requirements. The HCS410, a self-powered transponder superset of the HCS360, is the initial device in a new and expanding encoder/transponder family. Microchip provides flexible decoder solutions by providing optimized routines for Microchip’s PICmicro MCUs. This allows the designer to combine the decoder and system functionality in a MCU. The decoder routines are available under a license agreement. The HCS500, HCS512 and HCS515 are the first decoder devices in the KEELOQ family. These devices are single chip decoder solutions and simplify designs by handling learning and decoding of transmitters. The KEELOQ product family is expanding to include enhanced encoders and decoders. Typical applications include automotive RKE, alarm and immobilizer systems, garage door openers and home security systems. *Contact Microchip Technology Inc. for availability. Analog/Interface Products Using its technology achievements in developing analog circuitry for its PICmicro MCU family, the Company launched a complementary line of stand-alone analog and interface products. Many of these stand-alone devices support functionality that may not currently available on PICmicro MCUs. Stand-alone analog IC products currently offered include: • Analog-to-Digital Converters • Operational Amplifiers • System Supervisors Microchip also offers innovative silicon products to support a variety of bus interfaces used to transmit data to and from embedded control systems. The first interface products support Controller Area Network (CAN), a bus protocol highly integrated into a variety of networked applications including automotive. High-Performance 12-Bit Analog-to-Digital Converters The MCP320X 12-bit analog-to-digital converter (ADC) family is based on a successive approximation register architecture. The first four members include: MCP3201, MCP3202, MCP3204 and MCP3208. The MCP320X family features 100K samples per second throughput, low power of 400 microamps active and 500 nanoamps standby, wide supply voltage of 2.7-5.5 volts, extended industrial temperature range of –40° to 85°, +/- 1 LSB DNL and +/- 1 LSB INL max. at 100 ksps., no missing codes, and a serial output with an industry-standard SPI™ bus interface. The MCP320X is available in 1-, 2-, 4-, and 8-input channel versions (the MCP3201, MPC3202, MCP3204 and MCP3208, respectively). The devices KEELOQ Encoder Devices Product Transmission Code Length Bits Code Hopping Bits Prog. Encryption Key Bits Seed Length Operating Voltage HCS101* 66 — — — 3.5V to 13.0V HCS200 66 32 64 32 3.5V to 13.0V HCS201* 66 32 64 32 3.5V to 13.0V HCS300 66 32 64 32 2.0V to 6.3V HCS301 66 32 64 32 3.5V to 13.0V HCS320 66 32 64 32 3.5V to 13.0V HCS360 67 32 64 48 2.0V to 6.6V HCS361 67 32 64 48 2.0V to 6.6V HCS365* 69 32 2 x 64 60 2.0V to 6.6V HCS370* 69 32 2 x 64 60 2.0V to 6.6V HCS410 69 32 64 60 2.0V to 6.6V HCS412* 69 32 64 60 2.0V to 6.6V HCS470* 69 32 2 x 64 60 2.0V to 6.6V KEELOQ Decoder Devices Product Reception Length Bits Transmitters Supported Functions Operating Voltage HCS500 67 Up to 7 15 Serial Functions 4.5V to 5.5V HCS512 67 Up to 4 15 (S0, S1, S2, S3); VLOW, Serial 3.0V to 6.0V HCS515 67 Up to 7 15 Serial; 3 Parallel 4.5V to 5.5V 39500 18C Reference Manual.book Page xx Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS00027U-page xxi are offered in PDIP, SOIC and TSSOP packages. Applications include data acquisition, instrumentation and measurement, multi-channel data loggers, industrial PCs, motor control, robotics, industrial automation, smart sensors, portable instrumentation, and home medical appliances. Operational Amplifiers The MCP60X Operational Amplifier family includes four devices: MCP601, MCP602, MCP603 and MCP604. These devices are Microchip’s first 2.7 volt single supply operational amplifier products. The MCP60X family offers a gain bandwidth product of 2.8 MHz with low typical operating current of 230 µA. The MCP60X devices use Microchip's advanced CMOS technology which provides low bias current, high speed operation, high open-loop gain and rail-to-rail output swing. System Supervisors Microchip offers a complete family of system supervisor products. The new devices include the MCP809/810 and MCP100/101 supervisory circuits with push-pull output and the MCP120/130 supervisory circuits with open drain output. The devices are functionally and pin-out comparable to products from other analog suppliers. Controller Area Network (CAN) Microchip is enhancing its product portfolio by introducing the CAN Product Family. The MCP2510 is the smallest, easiest-to-use, CAN controller on the market today. Combining the MCP2510 with Microchip’s broad range of high-performance PICmicro MCUs enables Microchip to support for virtually all of today’s CAN-based applications. Other potential benefits of having a separate CAN controller include the ability for system designers to select from a much wider variety of MCUs for an optimal performance solution. Additional products planned for Microchip’s CAN product portfolio include other CAN peripherals and a family of PICmicro MCUs with integrated CAN support. microID™ RFID Tagging Devices Only Microchip manufactures world-class components for every application in the radio frequency identification (RFID) system. From the advanced, feature-packed microID family of RFID tags and high-endurance Serial EEPROMs to high performance PICmicro MCUs and KEELOQ code hopping encoders - Microchip's full range of RFID solutions are available for your tag, peripheral and reader application designs. The microID family can emulate almost any standard on the market today. It provides drop-in compatible solutions to the most commonly used 125 kHz and 13.56 MHz tags and an upgrade migration path for virtually any application with higher performance and new features. Serial EEPROM Overview Microchip’s high-endurance Serial EEPROMs complement the diverse MCU product families. Serial EEPROMs are available in a variety of densities, operating voltages, bus interface protocols, operating temperature ranges and space-saving packages. Densities: The densities range from 128 bits to 256 Kbits with higher density devices in development. Bus Interface Protocols: We offer all popular protocols: I2C™, Microwire and SPI. Operating Voltages: In addition to standard 5V devices there are two low voltage families. The “LC” devices operate down to 2.5V, while the breakthrough “AA” family operates, in both read and write mode, down to 1.8V, making these devices highly suitable for alkaline and NiCd battery powered applications. Temperature Ranges: Like all Microchip devices, many Serial EEPROMs are offered in Commercial (0°C to +70°C), Industrial (-40°C to +85°C) and Extended (-40°C to +125°C) operating temperature ranges. Packages: Small footprint packages include: industry standard 5-lead SOT-23, 8-lead DIP, 8-lead SOIC in JEDEC and EIAJ body widths, and 14-lead SOIC. The SOIC comes in two body widths; 150 mil and 207 mil. Technology Leadership: Selected Microchip Serial EEPROMs are backed by a 1 million Erase/Write cycle. Microchip's erase/write cycle endurance is among the best in the world, and only Microchip offers such unique and powerful development tools as the Total Endurance disk. This mathematical software model is an innovative tool used by system designers to optimize Serial EEPROM performance and reliability within the application. Microchip offers Plug-and-Play to the DIMM module market with the 24LCS52, a special function single-chip EEPROM that is available in space saving packages. For Plug-and-Play video monitor applications, Microchip offers the 24LC21, a single-chip DDC1™/DDC2-compatible solution. In addition, Microchip released a high-speed 1 MHz 2-wire Serial EEPROM device ideal for high-performance embedded systems. Microchip is a high-volume supplier of Serial EEPROMs to all the major markets worldwide. The Company continues to develop new Serial EEPROM solutions for embedded control applications. 39500 18C Reference Manual.book Page xxi Monday, July 10, 2000 6:12 PM DS00027U-page xxii  2000 Microchip Technology Inc. OTP EPROM Overview Microchip’s CMOS EPROM devices are produced in densities from 64K to 512K. Typical applications include computer peripherals, instrumentation, and automotive devices. Microchip’s expertise in surface mount packaging on SOIC and TSOP packages led to the development of the surface mount OTP EPROM market where Microchip is a leading supplier today. Microchip is also a leading supplier of low-voltage EPROMs for battery powered applications. MIGRATABLE MEMORY™ TECHNOLOGY Microchip’s innovative Migratable Memory technology (MMT) provides socket and software compatibility among all of its equivalent ROM, OTP and FLASH memory MCUs. MMT allows customers to match the selection of MCU memory technology to the product life cycle of their application, providing an easy migration path to a lower cost solution whenever appropriate. FLASH memory is an ideal solution for engineers designing products for embedded systems – especially during the development and early stages of the product. In certain products and applications, FLASH memory may be used for the life of the product because of the advantages of field upgradability or where product inventory flexibility is required. Once the design enters the pre-production stage and continues through introduction and growth stages, OTP program memory provides maximum programming flexibility and minimum inventory scrappage. The OTP device is pin and socket compatible with the FLASH device – providing a lower cost, high-volume flexible solution. As the design enters a mature stage and program code stabilizes, a lower cost, socket compatible ROM memory device could be used. In some cases, OTP memory may still be used as the most cost-effective memory technology for the product. Compatibility and flexibility are key to the success of the PICmicro MCU product family, and ultimately the success of our customers. FLEXIBLE PROGRAMMING OPTIONS To meet the stringent design requirements placed on our customers, the following innovative programming options are offered. These programming options address procurement issues by reducing and limiting work-in-process liability and facilitating finished goods code revisions. Microchip's worldwide distributors stock reprogrammable and one-time programmable inventory, allowing customers to respond to immediate sales opportunities or accommodate engineering changes off the shelf. FLASH (electrically reprogrammable) PICmicro FLASH MCUs allow erase and reprogramming of the MCU program memory. Reprogrammability offers a highly flexible solution to today's ever-changing market demands – and can substantially reduce time to market. Users can program their systems very late in the manufacturing process or update systems in the field. This allows easy code revisions, system parameterization or customer-specific options with no scrappage. Reprogrammability also reduces the design verification cycle. One-Time Programmable (OTP) PICmicro OTP MCUs are manufactured in high volumes without customer specific software and can be shipped immediately for custom programming. This is useful for customers who need rapid time to market and flexibility for frequent software updates. In-Circuit Serial Programming™ (ICSP™) Microchip's PICmicro FLASH and OTP MCUs feature ICSP capability. ICSP allows the MCU to be programmed after being placed in a circuit board, offering tremendous flexibility, reduced development time, increased manufacturing efficiency and improved time to market. This popular technology also enables reduced cost of field upgrades, system calibration during manufacturing, the addition of unique identification codes to the system and system calibration. Requiring only two I/O pins for most devices, Microchip offers the most non-intrusive programming methodology in the industry. Self Programming Microchip's PIC16F87X family features self programming capability. Self programming enables remote upgrades to the FLASH program memory and the end equipment through a variety of medium ranging from Internet and Modem to RF and Infrared. To setup for self programming, the designer programs a simple boot loader algorithm in a code protected area of the FLASH program memory. Through the selected medium, a secure command allows entry into the PIC16F87X MCU through the USART, I2C or SPI serial communication ports. The boot loader is then enabled to reprogram the PIC16F87X FLASH program memory with data received over the desired medium. And, of course, self programming is accomplished without the need for external components and without limitations on the PIC16F87X’s operating speed or voltage. Quick-Turn Programming (QTP) Microchip offers a QTP programming service for factory production orders. This service is ideal for customers who choose not to program a medium to high unit volume in their own factories, and whose production code patterns have stabilized. 39500 18C Reference Manual.book Page xxii Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS00027U-page xxiii Serialized Quick-Turn Programming (SQTPSM) SQTP is a unique, flexible programming option that allows Microchip to program serialized, random or pseudo-random numbers into each device. Serial programming allows each device to have a unique number which can serve as an entry-code, password or ID number. Masked ROM Microchip offers Masked ROM versions of many of its most popular PICmicro MCUs, giving customers the lowest cost option for high volume products with stable firmware. Future Products and Technology Microchip is constantly developing advanced process technology modules and new products that utilize our advanced manufacturing capabilities. Current production technology utilizes lithography dimensions down to 0.7 micron. Microchip’s research and development activities include exploring new process technologies and products that have industry leadership potential. Particular emphasis is placed on products that can be put to work in high-performance broad-based markets. Equipment is continually updated to bring the most sophisticated process, CAD and testing tools online. Cycle times for new technology development are continuously reduced by using in-house mask generation, a high-speed pilot line within the manufacturing facility and continuously improving methodologies. Objective specifications for new products are developed by listening to our customers and by close co-operation with our many customer-partners worldwide. 39500 18C Reference Manual.book Page xxiii Monday, July 10, 2000 6:12 PM DS00027U-page xxiv  2000 Microchip Technology Inc. NOTES: 39500 18C Reference Manual.book Page xxiv Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39501A-page 1-1 Introduction 1 Section 1. Introduction HIGHLIGHTS This section of the manual contains the following major topics: 1.1 Introduction .................................................................................................................... 1-2 1.2 Manual Objective ........................................................................................................... 1-3 1.3 Device Structure ............................................................................................................ 1-4 1.4 Development Support .................................................................................................... 1-6 1.5 Device Varieties ............................................................................................................. 1-7 1.6 Style and Symbol Conventions .................................................................................... 1-12 1.7 Related Documents ..................................................................................................... 1-14 1.8 Related Application Notes............................................................................................ 1-17 1.9 Revision History........................................................................................................... 1-18 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39501A-page 1-2  2000 Microchip Technology Inc. 1.1 Introduction Microchip is the Embedded Control Solutions Company. The company’s focus is on products that meet the needs of the embedded control market. We are a leading supplier of: • 8-bit general purpose microcontrollers (PICmicro® MCUs) • Speciality and standard non-volatile memory devices • Security devices (KEELOQ®) • Application specific standard products Please request a Microchip Product Line Card for a listing of all the interesting products that we have to offer. This literature can be obtained from your local sales office, or downloaded from the Microchip web site (www.microchip.com). In the past, 8-bit MCU users were fixed on the traditional MCU model for production, a ROM device. Microchip has been the leader in changing this perception by showing that OTP devices can give a better lifetime product cost compared to ROM versions. Microchip has strength in FLASH and EPROM technology. This makes it the memory technology of choice for the PICmicro MCU’s program memory. Microchip has minimized the cost difference between EPROM and ROM memory technology. Therefore, Microchip can pass these benefits on to our customers. This is not true for other MCU vendors, and is seen in the price difference between their FLASH/EPROM and ROM versions. The growth of Microchip’s 8-bit MCU market share is a testament to the PICmicro MCU’s ability to meet the needs of many customers. This growth has made the PICmicro architecture one of the top two architectures available in the general market today. This growth was fueled by the Microchip vision of the benefits of a low cost Field Programmable MCU solution. Some of the benefits for the customer include: • Quick time to market • Allows code changes to product during production run • No Non-Recurring Engineering (NRE) charges for Mask Revisions • Ability to easily serialize the product • Ability to store calibration data without additional hardware • Better able to maximize use of PICmicro MCU inventory • Less risk, since the same device is used for development as well as for production. Microchip’s PICmicro 8-bit MCUs offer a price/performance ratio that allows them to be considered for any traditional 8-bit MCU application, as well as some traditional 4-bit applications (Base-Line family), low-end 16-bit applications (PIC17CXXX and PIC18CXXX families), dedicated logic replacement and low-end DSP applications (High-End and Enhanced families). These features and price-performance mix make PICmicro MCUs an attractive solution for most applications. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39501A-page 1-3 Section 1. Introduction Introduction 1 1.2 Manual Objective PICmicro devices are grouped by the size of their Instruction Word and their Instruction Set. The four current PICmicro families and their Instruction Word length are: 1. Base-Line: 12-bit Instruction Word length 2. Mid-Range: 14-bit Instruction Word length 3. High-End: 16-bit Instruction Word length 4. Enhanced: 16-bit Instruction Word length This manual focuses on the Enhanced MCU family of devices, which are also referred to as the PIC18CXXX MCU family. The operation of the Enhanced MCU family architecture and peripheral modules is explained, but does not cover, the specifics of each device. This manual is not intended to replace the device data sheets, but complement them. In other words, this guide supplies the general details and operation of the PICmicro architecture and peripheral modules, while the data sheet gives the specific details (such as device memory mapping). Initialization examples are given throughout this manual. These examples sometimes need to be written as device specific as opposed to family generic, though they are valid for most other devices. Some modifications may be required for devices with variations in register file mappings. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39501A-page 1-4  2000 Microchip Technology Inc. 1.3 Device Structure Each part of a device can be placed into one of three groups: 1. Core 2. Peripherals 3. Special Features 1.3.1 Core The core pertains to the basic features that are required to make the device operate. These include: 1. Oscillator Revision “DS39502A” 2. Reset Revision “DS39503A” 3. Architecture Revision “DS39504A” 4. CPU (Central Processing Unit) and Revision “DS39505A” ALU (Arithmetic Logical Unit) 5. Hardware 8x8 Multiplier Revision “DS31006A” 6. Memory Revision “DS31007A” 7. Table Read / Table Write Revision “DS39508A” 8. System Bus Revision “DS39509A” 9. Interrupts Revision “DS39510A” 10. Instruction Set Revision “DS39532A” 1.3.2 Peripherals Peripherals are the features that add a differentiation from a microprocessor. These ease in interfacing to the external world (such as general purpose I/O, A/D inputs, and PWM outputs), and internal tasks, such as keeping different time bases (i.e. timers). The peripherals that are discussed are: 1. I/O Revision “DS39511A” 1. Parallel Slave Port (PSP) Revision “DS39512A” 2. Timer0 Revision “DS39513A” 3. Timer1 Revision “DS39514A” 4. Timer2 Revision “DS39515A” 5. Timer3 Revision “DS39516A” 6. Capture/Compare/PWM (CCP) Revision “DS39517A” 7. Serial Slave Port (SSP) Revision “DS39519A” 8. Master Synchronous Serial Port (MSSP) Revision “DS39520A” 9. Addressable USART Revision “DS39521A” 10. CAN Revision “DS39522A” 11. Comparator Voltage Reference Revision “DS31023A” 12. Comparators Revision “DS39525A” 13. Compatible 10-bit A/D Converter Revision “DS31026A” 14. 10-bit A/D Converter Revision “DS31027A” 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39501A-page 1-5 Section 1. Introduction Introduction 1 1.3.3 Special Features Special features are the unique features that help to: • Decrease system cost • Increase system reliability • Increase design flexibility The Enhanced PICmicro MCUs offer several features that help achieve these goals. The special features discussed are: 1. Low Voltage Detect Revision “DS39528A” 2. WDT and Sleep Operation Revision “DS31029A” 3. Device Configuration Bits Revision “DS39530A” 4. In-Circuit Serial Programming™ (ICSP™) Revision “DS39531A” 1.3.4 Other Sections This section provides the cross references for the remaining sections of this manual. 1. Introduction Revision “DS39501A” 2. Electrical Specifications Revision “DS31033A” 3. Device Characteristics Revision “DS31034A” 4. Development Tools Revision “DS31035A” 5. Code Development Revision “DS31036A” 6. Appendix Revision “DS39537A” 7. Glossary Revision “DS39538A” 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39501A-page 1-6  2000 Microchip Technology Inc. 1.4 Development Support Microchip offers a wide range of development tools that allow users to efficiently develop and debug application code. Microchip’s development tools can be broken down into four categories: 1. Code generation 2. Hardware/Software debug 3. Device programmer 4. Product evaluation boards All tools developed by Microchip operate under the MPLAB® Integrated Development Environment (IDE), while some third party tools may not. The code generation tools include: • MPASM • MPLAB®-C17 (for PIC17CXXX family only) • MPLAB®-C18 (for PIC18CXXX family only) These software development programs include device header files. Each header file defines the register names (as shown in the device data sheet) to the specified address or bit location. Using the header files eases code migration and reduces the tediousness of memorizing a register’s address or a bit’s position in a register. Tools which ease in debugging software are: • MPLAB®-ICE In-Circuit Emulator • PICMASTER® In-Circuit Emulator • ICEPIC In-Circuit Emulator • MPLAB®-SIM Software Simulator After generating and debugging the application software, the device will need to be programmed. Microchip offers two levels of programmers: 1. PICSTART Plus programmer 2. PRO MATE II programmer Demonstration boards allow the developer of software code to evaluate the capability and suitability of the device to the application. The demo boards offered are: • PICDEM-1 • PICDEM-2 (can be used with PIC18CXX2 devices) • PICDEM-3 • PICDEM-14A • PICDEM-17 At the time of publication, only PICDEM-2 could be used with some Enhanced MCU devices. A full description of each of Microchip’s development tools is discussed in the “Development Tools” section. As new tools are developed, product briefs and user guides may be obtained from the Microchip web site (www.microchip.com) or from your local Microchip Sales Office. Code development recommendations and techniques are provided in the “Code Development” section. Microchip offers other reference tools to speed the development cycle. These include: • Application Notes • Reference Designs • Microchip web site • Local Sales Offices with Field Application Support • Corporate Support Line The Microchip web site lists other sites that may be useful references. Note: Microchip strongly recommends that the supplied header files be used in the source code of your program. This eases code migration, improves code readability, and increases the quality and depth of the technical support that Microchip can offer. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39501A-page 1-7 Section 1. Introduction Introduction 1 1.5 Device Varieties Once the functional requirements of the device are specified, other choices need to be made. These include: • Memory technology • Operating voltage • Operating temperature range • Operating frequency • Packaging Microchip has a large number of options and option combinations, one of which should fulfill your requirements. 1.5.1 Memory Varieties Memory technology has no effect on the logical operation of a device. Due to the different processing steps required, some electrical characteristics may vary between devices with the same feature set/pinout but with different memory technologies. An example is the electrical characteristic VIL (Input Low Voltage), which may have some difference between a typical EPROM device and a typical ROM device. Each device has a variety of frequency ranges and packaging options available. Depending on application and production requirements, the proper device options can be identified using the information in the Product Identification System section at the end of each data sheet. When placing orders, please use the “Product Identification System” at the back of the data sheet to specify the correct part number. When discussing the functionality of the device, the memory technology and the voltage range do not matter. Microchip offers three program memory types. The memory type is designated in the part number by the first letter(s) after the family affiliation designators. 1. C, as in PIC18CXXX. These devices have EPROM type memory. 2. CR, as in PIC18CRXXX. These devices have ROM type memory. 3. F, as in PIC18FXXX. These devices have FLASH type memory. 1.5.1.1 EPROM Microchip focuses on Erasable Programmable Read Only Memory (EPROM) technology to give customers flexibility throughout their entire design cycle. With this technology, Microchip offers various packaging options as well as services. 1.5.1.2 Read Only Memory (ROM) Devices Microchip offers a masked Read Only Memory (ROM) version of several of the highest volume parts, thus giving customers a lower cost option for high volume, mature products. ROM devices do not allow serialization information in the program memory space. For information on submitting ROM code, please contact your local Microchip sales office. 1.5.1.3 FLASH Memory Devices These devices are electrically erasable, and can therefore be offered in a low cost plastic package. Being electrically erasable, these devices can be erased and reprogrammed without removal from the circuit. A device will have the same specifications whether it is used for prototype development, pilot programs or production. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39501A-page 1-8  2000 Microchip Technology Inc. 1.5.2 Operating Voltage Range Options All Enhanced PICmicro MCUs operate over the standard voltage range. Devices are also offered which operate over an extended voltage range (and reduced frequency range). Table 1-1 shows all possible memory types and voltage range designators for the PIC18CXXX MCU family. The designators are in bold typeface. Table 1-1: Device Memory Type and Voltage Range Designators As you can see in Table 1-2, Microchip specifies its extended range devices at a more conservative voltage range until device characterization has ensured they will be able to meet the goal of their final design specifications. Table 1-2: Typical Voltage Ranges for Each Device Type Memory Type Voltage Range Standard Extended EPROM PIC18CXXX PIC18LCXXX ROM PIC18CRXXX PIC18LCRXXX FLASH PIC18FXXX PIC18LFXXX Note: Not all memory types may be available for a particular device. Typical Voltage Range EPROM ROM Flash Standard C 4.2 - 5.5V CR 4.2 - 5.5V F 4.2 - 5.5V Extended Before device characterization LC 3.0 - 5.5V LCR 3.0 - 5.5V LF 3.0 - 5.5V Final specification (1) LC 2.5 - 5.5V LCR 2.5 - 5.5V LF 2.0 - 5.5V Note 1: This voltage range depends on the results of device characterization. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39501A-page 1-9 Section 1. Introduction Introduction 1 Figure 1-1 and Figure 1-2 show example Voltage to Frequency Charts for the Enhanced MCU family. The voltages and frequencies of any given device may be different than those shown. These figures are intended to show that with an LC (extended voltage) device, the user can make a trade-off between voltage of operation and the frequency of the device. The device FMAX is given below the graph. As the voltages and frequencies of the device change, the equation for the device FMAX will change. Equation 1-1 shows the general equation to determine the device FMAX. Equation 1-1: Generic FMAX Equation Figure 1-1: PIC18CXXX Voltage-Frequency Graph - Example Figure 1-2: PIC18LCXXX Voltage-Frequency Graph - Example FMAX = (slope) (VDDAPPMIN - VDDMIN) + offset Frequency Voltage 6.0 V 5.5 V 4.5 V 4.0 V 2.0 V 40 MHz 5.0 V 3.5 V 3.0 V 2.5 V PIC18CXXX 4.2V Frequency Voltage 6.0 V 5.5 V 4.5 V 4.0 V 2.0 V 40 MHz 5.0 V 3.5 V 3.0 V 2.5 V PIC18LCXXX 6 MHz 4.2V Note: VDDAPPMIN is the minimum voltage of the PICmicro device in the application. FMAX = (20.0 MHz/V) (VDDAPPMIN - 2.5 V) + 6 MHz 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39501A-page 1-10  2000 Microchip Technology Inc. 1.5.3 Packaging Varieties Depending on the development phase of your project, one of three package types would be used. The first package type is ceramic with an erasure window. The window allows ultraviolet light into the package so that the device inside may be erased. The package is used for the development phase, since the device’s program memory can be erased and reprogrammed many times. The second package type is a low cost plastic package. This package type is used in production where device cost is to be kept to a minimum. Lastly, there is the Die option. A Die is an unpackaged device that has been tested. Dies are used in low cost designs and designs where board space is at a minimum. For additional information on die support, please refer to the Die Support Document (DS30258). Table 1-3 shows a quick summary of the typical use for each package type. Table 1-3: Typical Package Uses 1.5.3.1 UV Erasable Devices The UV erasable version of EPROM program memory devices is optimal for prototype development and pilot programs. These devices can be erased and reprogrammed to any of the configuration modes. Third party programmers are available. Refer to Microchip’s Third Party Guide (DS00104) for a list of sources. The amount of time required to completely erase a UV erasable device depends on the: • Wavelength of the light • Intensity of the light • Distance of the device from the UV source • Process technology of the device (size of the memory cells). 1.5.3.2 One-Time-Programmable (OTP) Devices The availability of OTP devices is especially useful for customers expecting code changes and updates. OTP devices in plastic packages permit the user to program them once. Often the system can be designed so that programming may be performed in-circuit (after the device has been mounted on the circuit board). 1.5.3.3 FLASH Devices These devices are electrically erasable, and can therefore be offered in a low cost plastic package. Being electrically erasable, these devices can be both erased and reprogrammed without removal from the circuit. A device will have the same specifications whether it is used for prototype development, pilot programs, or production. Package Type Typical Usage Windowed Development mode Plastic Production Die Special applications, such as those which require minimum board space Note: Fluorescent lights and sunlight both emit ultraviolet light at the erasure wavelength. Leaving a UV erasable device’s window uncovered could cause, over time, the device’s memory cells to become erased. The erasure time for a fluorescent light is about three years, while sunlight requires only about one week. To prevent the memory cells from losing data, an opaque label should be placed over the erasure window. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39501A-page 1-11 Section 1. Introduction Introduction 1 1.5.3.4 ROM Devices ROM devices have their program memory fixed at the time of the silicon manufacture. Since the program memory cannot be changed, the device is usually housed in the low cost plastic package. 1.5.3.5 Die The Die option allows the board size to become as small as physically possible. The Die Support document (DS30258) explains general information about using and designing with Die. There are also individual specification sheets that detail Die specific information. Manufacturing with Die requires special knowledge and equipment. This means that the number of manufacturing houses that support Die will be limited. If you decide to use the Die option, please research your manufacturing sites to ensure that they will be able to meet the specialized requirements of Die use. 1.5.3.6 Specialized Services For OTP customers with established code, Microchip offers two specialized services. These two services, Quick Turn Production Programming and Serialized Quick Turn Production Programming, allow customers to shorten their manufacturing cycle time. 1.5.3.6.1 Quick Turn Production (QTP) Programming Microchip offers this programming service for factory production orders. This service is made available for users who choose not to program a medium to high quantity of units at their factory and whose code patterns have stabilized. The devices are identical to the OTP devices, but with all EPROM locations and configuration options already programmed by Microchip. Certain code and prototype verification procedures apply before production shipments are available. Please contact your local Microchip sales office for more details. 1.5.3.6.2 Serialized Quick Turn Production (SQTPSM) Programming Microchip offers a unique programming service where a few user-defined locations in each device are programmed with unique numbers. These numbers may be: • Random numbers • Pseudo-random numbers • Sequential numbers Serial programming allows each device to have a unique number which can serve as an entry-code, password, ID, or serial number. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39501A-page 1-12  2000 Microchip Technology Inc. 1.6 Style and Symbol Conventions Throughout this document, certain style and font format conventions are used. Most format conventions imply a distinction should be made for the emphasized text. The MCU industry has many symbols and non-conventional word definitions/abbreviations. Table 1-4 provides a description for many of the conventions contained in this document. A glossary is provided in the “Glossary” section, which contains more word and abbreviation definitions that are used throughout this manual. 1.6.1 Document Conventions Table 1-4 defines some of the symbols and terms used throughout this manual. Table 1-4: Document Conventions Symbol or Term Description set To force a bit/register to a value of logic ‘1’. clear To force a bit/register to a value of logic ‘0’. reset 1) To force a register/bit to its default state. 2) A condition in which the device places itself after a device reset occurs. Some bits will be forced to ‘0’ (such as interrupt enable bits), while others will be forced to ‘1’ (such as the I/O data direction bits). 0xnn or nnh Designates the number ‘nn’ in the hexadecimal number system. These conventions are used in the code examples. B’bbbbbbbb’ Designates the number ‘bbbbbbbb’ in the binary number system. This convention is used in the text and in figures and tables. R-M-W Read - Modify - Write. This is when a register or port is read, then the value is modified, and that value is then written back to the register or port. This action can occur from a single instruction (such as bit set file, BSF) or a sequence of instructions. : (colon) Used to specify a range or the concatenation of registers/bits/pins. One example is TMR1H:TMR1L, which is the concatenation of two 8-bit registers to form a 16-bit timer value, while SSPM3:SSPM0 are 4-bits used to specify the mode of the SSP module. Concatenation order (left-right) usually specifies a positional relationship (MSb to LSb, higher to lower). < > Specifies bit(s) locations in a particular register. One example is SSPCON (or SSPCON<3:0>) which specifies the register and associated bits or bit positions. Courier Font Used for code examples, binary numbers and for Instruction Mnemonics in the text. Times Font Used for equations and variables. Times, Bold Font, Italics Used in explanatory text for items called out from a graphic/equation/example. Note A Note presents information that we wish to reemphasize, either to help you avoid a common pitfall, or make you aware of operating differences between some device family members. A Note is always in a shaded box (as below), unless used in a table, where it is at the bottom of the table (as in this table). Note: This is a Note in a note box. Caution (1) A caution statement describes a situation that could potentially damage software or equipment. Warning (1) A warning statement describes a situation that could potentially cause personal harm. Note 1: The information in a caution or a warning is provided for your protection. Please read each caution and warning carefully. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39501A-page 1-13 Section 1. Introduction Introduction 1 1.6.2 Electrical Specifications Throughout this manual, there will be references to electrical specification parameter numbers. A parameter number represents a unique set of characteristics and conditions that is consistent between every data sheet, though the actual parameter value may vary from device to device. The “Electrical Specifications” section shows all the specifications that are documented for all devices. No one device has all these specifications. This section is intended to let you know the types of parameters that Microchip specifies. The value of each specification is device dependent, though we strongly attempt to keep them consistent across all devices. Table 1-5: Electrical Specification Parameter Numbering Convention Parameter Number Format Comment DXXX DC Specification AXXX DC Specification for Analog Peripherals XXX Timing (AC) Specification PDXXX Device Programming DC Specification PXXX Device Programming Timing (AC) Specification Legend: XXX represents a number. 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39501A-page 1-14  2000 Microchip Technology Inc. 1.7 Related Documents Microchip, as well as other sources, offers additional documentation which can aid in your development with PICmicro MCUs. These lists contain the most common documentation, but other documents may also be available. Please check the Microchip web site (www.microchip.com) for the latest published technical documentation. 1.7.1 Microchip Documentation The following documents are available from Microchip. Many of these documents provide application specific information that give actual examples of using, programming and designing with PICmicro MCUs. 1. MPASM and MPLINK (w/ MPLIB) User’s Guide (DS33014) This document explains how to use Microchip’s MPASM assembler. 2. MPLAB®-CXX Compiler User’s Guide (DS51217) This document explains how to use Microchip’s MPLAB-C17 and MPLAB-C18 compilers. 3. MPLAB® IDE, Simulator, Editor User’s Guide (DS51025) This document explains how to use Microchip’s MPLAB Integrated Development Environment. 4. MPLAB®-CXX Reference Guide Libraries and Precompiled Object Files (DS51224) This document explains how to use Microchip’s MPLAB Reference Guide Libraries and Precompiled Object Files. 5. PICMASTER® User’s Guide (DS30421) This document explains how to use Microchip’s PICMASTER In-Circuit Emulator. 6. PRO MATE® User’s Guide (DS30082) This document explains how to use Microchip’s PRO MATE Universal Programmer. 7. PICSTART®-Plus User’s Guide (DS51028) This document explains how to use Microchip’s PICSTART-Plus low-cost universal programmer. 8. PICmicro® Mid-Range MCU Family Reference Manual (DS33023) This document discusses the operation of PICmicro Mid-Range MCU devices, explaining the detailed operation of the architecture and peripheral modules. It is a compliment to the device data sheets for the Mid-Range family. 9. Embedded Control Handbook Volume I (DS00092) This document contains a plethora of application notes. This is useful for insight on how to use the device (or parts of it), as well as getting started on your particular application due to the availability of extensive code files. 10. Embedded Control Handbook Update 2000 (DS00711) This document contains additional application notes. 11. Embedded Control Handbook Volume II Math Library (DS00167) This document contains the Math Libraries for PICmicro MCUs. 12. In-Circuit Serial Programming Guide™ (DS30277) This document discusses implementing In-Circuit Serial Programming. 13. PICDEM-1 User’s Guide (DS33015) This document explains how to use Microchip’s PICDEM-1 demo board. 14. PICDEM-2 User’s Guide (DS30374) This document explains how to use Microchip’s PICDEM-2 demo board. 15. PICDEM-3 User’s Guide (DS51079) This document explains how to use Microchip’s PICDEM-3 demo board. 16. PICDEM-14A User’s Guide (DS51097) This document explains how to use Microchip’s PICDEM-14A demo board. 17. PICDEM-17 User’s Guide (DS39024) This document explains how to use Microchip’s PICDEM-17 demo board. 18. Third Party Guide (DS00104) This document lists Microchip’s third parties, as well as various consultants. 19. Die Support (DS30258) This document gives information on using Microchip products in Die form. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39501A-page 1-15 Section 1. Introduction Introduction 1 1.7.2 Third Party Documentation There are several documents available from third party sources around the world. Microchip does not review these documents for technical accuracy. However, they may be a helpful source for understanding the operation of Microchip PICmicro MCU devices. This is not necessarily a complete list, but are the documents that we were aware of at the time of printing. For more information on how to contact some of these sources, as well as any new sources that we become aware of, please visit the Microchip web site (www.microchip.com). DOCUMENT LANGUAGE The PIC16C5X Microcontroller: A Practical Approach to Embedded Control Bill Rigby/ Terry Dalby, Tecksystems Inc. 0-9654740-0-3 ........................................................................................................... English Easy PIC'n David Benson, Square 1 Electronics 0-9654162-0-8 ........................................................................................................... English A Beginner’s Guide to the Microchip PIC® Nigel Gardner, Bluebird Electronics 1-899013-01-6 ........................................................................................................... English PIC Microcontroller Operation and Applications DN de Beer, Cape Technikon..................................................................................... English Digital Systems and Programmable Interface Controllers WP Verburg, Pretoria Technikon ................................................................................ English Mikroprozessor PIC16C5X Michael Rose, Hüthig 3-7785-2169-1 .......................................................................................................... German Mikroprozessor PIC17C42 Michael Rose, Hüthig 3-7785-2170-5 .......................................................................................................... German Les Microcontrolleurs PIC et mise en oeuvre Christian Tavernier, Dunod 2-10-002647-X ............................................................................................................ French Microcontrolleurs PIC a structure RISC C.F. Urbain, Publitronic 2-86661-058-X ............................................................................................................ French New Possibilities with the Microchip PIC RIGA ......................................................................................................................... Russian 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39501A-page 1-16  2000 Microchip Technology Inc. DOCUMENT LANGUAGE PIC16C5X/71/84 Development and Design, Part 1 United Tech Electronic Co. Ltd 957-21-0807-7...........................................................................................................Chinese PIC16C5X/71/84 Development and Design, Part 2 United Tech Electronic Co. Ltd 957-21-1152-3...........................................................................................................Chinese PIC16C5X/71/84 Development and Design, Part 3 United Tech Electronic Co. Ltd 957-21-1187-6...........................................................................................................Chinese PIC16C5X/71/84 Development and Design, Part 4 United Tech Electronic Co. Ltd 957-21-1251-1...........................................................................................................Chinese PIC16C5X/71/84 Development and Design, Part 5 United Tech Electronic Co. Ltd 957-21-1257-0...........................................................................................................Chinese PIC16C84 MCU Architecture and Software Development ICC Company 957-8716-79-6...........................................................................................................Chinese 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39501A-page 1-17 Section 1. Introduction Introduction 1 1.8 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced MCU family (they may be written for the Base-Line, Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to an introduction to Microchip’s PICmicro MCUs are: Title Application Note # A Comparison of Low End 8-bit Microcontrollers AN520 PIC16C54A EMI Results AN577 Continuous Improvement AN503 Improving the Susceptibility of an Application to ESD AN595 Plastic Packaging and the Effects of Surface Mount Soldering Techniques AN598 Migrating Designs from PIC16C74A/74B to PIC18C442 AN716 PIC17CXXX to PIC18CXXX Migration AN726 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39501A-page 1-18  2000 Microchip Technology Inc. 1.9 Revision History Revision A This is the initial released revision of Enhanced MCU Introduction. 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-1 Oscillator 2 Section 2. Oscillator HIGHLIGHTS This section of the manual contains the following major topics: 2.1 Introduction .................................................................................................................... 2-2 2.2 Control Register............................................................................................................. 2-3 2.3 Oscillator Configurations................................................................................................ 2-4 2.4 Crystal Oscillators/Ceramic Resonators ........................................................................ 2-6 2.5 External RC Oscillator.................................................................................................. 2-15 2.6 HS4 (HS oscillator with 4xPLL enabled) ...................................................................... 2-18 2.7 Switching to Low Power Clock Source......................................................................... 2-19 2.8 Effects of Sleep Mode on the On-Chip Oscillator......................................................... 2-23 2.9 Effects of Device Reset on the On-Chip Oscillator ...................................................... 2-23 2.10 Design Tips.................................................................................................................. 2-24 2.11 Related Application Notes............................................................................................ 2-25 2.12 Revision History........................................................................................................... 2-26 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-2  2000 Microchip Technology Inc. 2.1 Introduction The device system clock is required for the device to execute instructions and for the peripherals to function. Four device system clock periods (TSCLK) generate one internal instruction clock cycle (TCY). The device system clock (TSCLK) is derived from an external system clock. This external system clock can be generated in one of eight different oscillator modes. The device configuration bits select the oscillator mode. Device configuration bits are nonvolatile memory locations and the operating mode is determined by the value written during device programming. The oscillator modes are: • EC External Clock • ECIO External Clock with I/O pin enabled • LP Low Frequency (Power) Crystal • XT Crystal/Resonator • HS High Speed Crystal/Resonator • RC External Resistor/Capacitor • RCIO External Resistor/Capacitor with I/O pin enabled • HS4 High Speed Crystal/Resonator with 4x frequency PLL multiplier enabled Multiple oscillator circuits can be implemented on an Enhanced Architecture device. There is the default oscillator (OSC1), and additional oscillators may be available, such as the Timer1 oscillator. Software may allow these auxiliary oscillators to be switched in as the device oscillator. The Timer1 oscillator is a low frequency (low power) oscillator that is designed to be operated at 32kHz. Figure2-1 shows a block diagram of the oscillator options. The output signal of the Timer1 oscillator circuitry is a low frequency (power) clock source (TT1P). The source for the device system clock can be switched from the default clock (TSCLK) to the 32kHz-clock low power clock source (TT1P) under software control. Switching to the 32kHz low frequency (power) clock source from any of the eight default clock sources may allow power saving. These oscillator options are made available to allow a single device type the flexibility to fit applications with different oscillator requirements. The RC oscillator option saves system cost, while the LP crystal option saves power. The HS4 option allows frequency of incoming crystal oscillator signal to be multiplied by four for higher internal clock frequency. This is useful for customers who are concerned with EMI due to high frequency crystals. The device configuration bits are used to select these various options. For more details on the device configuration bits, see the “Device Configuration Bits” section. Figure 2-1: Device Clock Sources PIC18CXXX TOSC 4 x PLL TT1P TSCLK Clock Source MUX TOSC/4 Timer1 Oscillator T1OSCEN Enable Oscillator T1OSO T1OSI Clock Source option for other modules OSC1 OSC2 Sleep Main Oscillator (FOSC2:FOSC0) 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-3 Section 2. Oscillator Oscillator 2 2.2 Control Register Register 2-1 shows the OSCCON register which contains the control bit to allow switching of the system clock between the primary oscillator and the Timer1 oscillator. Register 2-1: OSCCON Register U-0 U-0 U-0 U-0 U-0 U-0 U-0 R/W-1 — — — — — — — SCS bit 7 bit 0 bit 7-1 Unimplemented: Read as '0' bit 0 SCS: System Clock Switch bit when OSCSEN configuration bit = ’0’ and T1OSCEN bit is set: 1 = Switch to Timer1 Oscillator/Clock pin 0 = Use primary Oscillator/Clock input pin when OSCSEN and T1OSCEN are in other states: bit is forced clear Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = Bit is set ’0’ = Bit is cleared x = Bit is unknown Note: The Timer1 oscillator must be enabled to switch the system clock source. The Timer1 oscillator is enabled by setting the T1OSCEN bit in the Timer1 control register (T1CON). If the Timer1 oscillator is not enabled, then any write to the SCS bit will be ignored (SCS bit forced cleared) and the main oscillator will continue to be the system clock source. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-4  2000 Microchip Technology Inc. 2.3 Oscillator Configurations The oscillator selection is configured at time of device programming. The user can program up to three device configuration bits (FOSC2:FOSC0) to select one of eight modes. 2.3.1 Oscillator Types PIC18CXXX devices can have up to eight different oscillator modes for the default clock source (TSCLK). These eight modes are: • EC External Clock • ECIO External Clock with IO pin enabled • LP Low Frequency (Power) Crystal • XT Crystal/Resonator • HS High Speed Crystal/Resonator • RC External Resistor/Capacitor • RCIO External Resistor/Capacitor with IO pin enabled • HS4 High Speed Crystal/Resonator with 4x frequency PLL multiplier enabled The main difference between the LP, XT and HS modes is the gain of the internal inverter of the oscillator circuit, which allows the different frequency ranges. Table 2-1 gives information to aid in selecting an oscillator mode. In general, use the oscillator option with the lowest possible gain that still meets specifications. This will result in lower dynamic currents (IDD). The frequency range of each oscillator mode is the recommended frequency cutoff, but the selection of a different gain mode is acceptable as long as a thorough validation is performed (voltage, temperature, component variations (resistor, capacitor, and internal microcontroller oscillator circuitry). Switching the system clock source to the alternate clock source is controlled by the application software. The user can switch from any of the eight default clock sources. This is done by setting the SCS (System Clock Switch) bit in the OSCCON register. The requirements for switching to the alternate clock source are: • Timer1 clock oscillator must be enabled (T1OSCEN is set ’1’). • The OSCEN configuration bit must be cleared (‘0’). 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-5 Section 2. Oscillator Oscillator 2 Table 2-1: Selecting the Oscillator Mode for Devices FOSC2:FOSC0 Configuration Bits OSC Mode OSC Feedback Inverter Gain OSC2/CLKO Function Comment 111 RCIO Zero Gain. Device turned off to save current. I/O Least expensive solution for device oscillation (only an external resistor and capacitor is required). Most variation in time-base. Device’s default mode. OSC2/CLKO is configured as general purpose I/O pin. This pin is multiplexed with one of the device’s PORT pins. 110 HS4 High Gain — Highest frequency application. This works with the HS oscillator circuit mode and phase lock loop. This mode consumes the most current. The internal phase lock loop circuit multiplies the external oscillator frequency by 4. 101 ECIO Zero Gain. Device turned off to save current. I/O External clock mode with OSC2/CLKO configured as general purpose I/O pin. This pin is multiplexed with one of the device’s PORT pins. OSC1/CLKI is hi-impedance and can be driven by CMOS drivers. 100 EC Zero Gain. Device turned off to save current. Clock out with oscillator frequency divided by 4. External clock mode with OSC2/CLKO configured with oscillator frequency divided by 4. OSC1/CLKI is hi-impedance and can be driven by CMOS drivers. 011 RC Zero Gain. Device turned off to save current. Clock out with oscillator frequency divided by 4. Inexpensive solution for device oscillation. Most variation in timebase. CLKOUT is enabled on OSC2/CLKO with oscillator frequency divided by 4. 010 HS High Gain — High frequency application. Oscillator circuit’s mode consumes the most current of the three crystal modes. 001 XT Medium Gain — Standard crystal/resonator frequency. 000 LP Low Gain — Low power/frequency applications. Oscillator circuit’s mode consumes the least current of the three crystal modes. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-6  2000 Microchip Technology Inc. 2.4 Crystal Oscillators/Ceramic Resonators In XT, LP, HS and HS4 modes, a crystal or ceramic resonator is connected to the OSC1 and OSC2 pins to establish oscillation (Figure2-2). The PIC18CXXX oscillator design requires the use of a parallel cut crystal. Using a series cut crystal may give a frequency out of the crystal manufacturer’s specifications. When in EC and ECIO mode, the device can have an external clock source drive the OSC1 pin (Figure2-3). See Table 3-1 in the “Reset” section for time-out delays associated with crystal oscillators. Figure 2-2: Crystal or Ceramic Resonator Operation (HS4, HS, XT or LP Oscillator Mode) Figure 2-3: External Clock Input Operation (EC or ECIO Oscillator Modes) C1 (3) C2 (3) XTAL OSC2 RS (1) OSC1 RF (2) SLEEP To internal logic PIC18CXXX Note 1: A series resistor, Rs, may be required for AT strip cut crystals. 2: The internal feedback resistor, RF, is typically in the range of 2 to 10 MΩ. 3: See Table 2-2 and 2-3 for example values of C1 and C2. CLKI Open CLKO Clock from ext. system PIC18CXXX 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-7 Section 2. Oscillator Oscillator 2 2.4.1 Oscillator/Resonator Start-up As the device voltage increases from VSS, the oscillator will start its oscillations. The time required for the oscillator to start oscillating depends on many factors. These include: • Crystal/resonator frequency • Capacitor values used (C1 and C2 in Figure2-2) • Device VDD rise time • System temperature • Series resistor value and type if used (Rs in Figure2-2) • Oscillator mode selection of device (selects the gain of the internal oscillator inverter) • Crystal quality • Oscillator circuit layout • System noise Figure2-4 graphs an example oscillator/resonator start-up. The peak-to-peak voltage of the oscillator waveform can be quite low (less than 50% of device VDD), when the waveform is centered at VDD/2 (refer to parameters D033 and D043 in the “Electrical Specifications” section). Figure 2-4: Example Oscillator/Resonator Start-up Characteristics Voltage Crystal Start-up Time Time Device VDD Maximum VDD of System 0V 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-8  2000 Microchip Technology Inc. 2.4.2 Component Selection Figure2-2 is a diagram of the device’s crystal or ceramic resonator circuitry. The resistance for the feedback resistor, RF, is typically within the 2 to 10 MΩ range. This varies with device voltage, temperature and process variations. A series resistor, Rs, may be required if an AT strip cut crystal is used. Be sure to include the device’s operating voltage and the device’s manufacturing process when determining resistor requirements. As you can see in Figure2-2, the connection to the device’s internal logic is device dependent. See the applicable data sheet for device specifics. The typical values of capacitors (C1, C2) are given in Table 2-2 and Table 2-3. Each device’s data sheet will give the specific values that we test to at Microchip. Table 2-2: Example Capacitor Selection for Ceramic Resonators Ranges tested: Mode Frequency C1 (1) C2 (1) XT 455 kHz 2.0 MHz 4.0 MHz TBD TBD TBD TBD TBD TBD HS 8.0 MHz 16.0 MHz TBD TBD TBD TBD Resonators used: Frequency Manufacturer Tolerance 455 kHz Panasonic EFO-A455K04B ±0.3% 2.0 MHz Murata Erie CSA2.00MG ±0.5% 4.0 MHz Murata Erie CSA4.00MG ±0.5% 8.0 MHz Murata Erie CSA8.00MT ±0.5% 16.0 MHz Murata Erie CSA16.00MX ±0.5% Note 1: Recommended values of C1 and C2 are identical to the ranges tested above. Higher capacitance increases the stability of the oscillator but also increases the start-up time. These values are for design guidance only. Since each resonator has its own characteristics, the user should consult the resonator manufacturer for appropriate values of external components or verify oscillator performance. 2: All resonators tested required external capacitors. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-9 Section 2. Oscillator Oscillator 2 Table 2-3: Example Capacitor Selection for Crystal Oscillator Mode Frequency C1 (1) C2 (1) LP 32 kHz 200 kHz TBD TBD TBD TBD XT 200 kHz 1 MHz 4 MHz TBD TBD TBD TBD TBD TBD HS 4.0 MHz 8 MHz 20 MHz 25 MHz TBD TBD TBD TBD TBD TBD TBD TBD Crystals used: Frequency Manufacturer Tolerance 32.0 kHz Epson C-001R32.768K-A ± 20 PPM 200 kHz STD XTL 200.000 kHz ± 20 PPM 1.0 MHz ECS ECS-10-13-1 ± 50 PPM 4.0 MHz ECS ECS-40-20-1 ± 50 PPM 8.0 MHz EPSON CA-301 8.000 M-C ± 30 PPM 20.0 MHz EPSON CA-301 20.000 M-C ± 30 PPM Note 1: Higher capacitance increases the stability of the oscillator, but also increases the start-up time. These values are for design guidance only. A series resistor, Rs, may be required in HS mode, as well as XT mode, to avoid overdriving crystals with low drive level specification. Since each crystal has its own characteristics, the user should consult the crystal manufacturer for appropriate values of external components or verify oscillator performance. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-10  2000 Microchip Technology Inc. 2.4.3 Tuning the Oscillator Circuit Since Microchip devices have wide operating ranges (frequency, voltage, and temperature; depending on the part and version ordered) and external components (crystals, capacitors,...) of varying quality and manufacture, validation of operation needs to be performed to ensure that the component selection will comply with the requirements of the application. There are many factors that go into the selection and arrangement of these external components. These factors include: • amplifier gain • desired frequency • resonant frequency(s) of the crystal • temperature of operation • supply voltage range • start-up time • stability • crystal life • power consumption • simplification of the circuit • use of standard components • combination which results in fewest components 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-11 Section 2. Oscillator Oscillator 2 2.4.3.1 Determining Best Values for Crystals, Clock Mode, C1, C2, and Rs The best method for selecting components is to apply a little knowledge and a lot of trial, measurement, and testing. Crystals are usually selected by their parallel resonant frequency only, however other parameters may be important to your design, such as temperature or frequency tolerance. Application Note AN588 is an excellent reference if you would like to know more about crystal operation and their ordering information. The PICmicro’s internal oscillator circuit is a parallel oscillator circuit, which requires that a parallel resonant crystal be selected. The load capacitance is usually specified in the 20 pF to 32 pF range. The crystal will oscillate closest to the desired frequency with capacitance in this range. It may be necessary to sometimes alter these values a bit, as described later, in order to achieve other benefits. Clock mode is primarily chosen by using the FOSC parameter specification (parameter 1A) in the device data sheet, based on frequency. Clock modes (except RC and EC) are simply gain selections; lower gain for lower frequencies, higher gain for higher frequencies. It is possible to select a higher or lower gain, if desired, based on the specific needs of the oscillator circuit. C1 and C2 should also be initially selected based on the load capacitance as suggested by the crystal manufacturer and the tables supplied in the device data sheet. The values given in the device data sheet can only be used as a starting point, since the crystal manufacturer, supply voltage, and other factors already mentioned may cause your circuit to differ from the one used in the factory characterization process. Ideally, the capacitance is chosen so that it will oscillate at the highest temperature and lowest VDD that the circuit will be expected to perform under. High temperature and low VDD both have a limiting effect on the loop gain, such that if the circuit functions at these extremes, the designer can be more assured of proper operation at other temperatures and supply voltage combinations. The output sine wave should not be clipped in the highest gain environment (highest VDD and lowest temperature) and the sine output amplitude should be great enough in the lowest gain environment (lowest VDD and highest temperature) to cover the logic input requirements of the clock as listed in the device data sheet. A method for improving start-up is to use a value of C2 greater than C1. This causes a greater phase shift across the crystal at power-up, which speeds oscillator start-up. Besides loading the crystal for proper frequency response, these capacitors can have the effect of lowering loop gain if their value is increased. C2 can be selected to affect the overall gain of the circuit. A higher C2 can lower the gain if the crystal is being over driven (see also discussion on Rs). Capacitance values that are too high can store and dump too much current through the crystal, so C1 and C2 should not become excessively large. Unfortunately, measuring the wattage through a crystal is tricky business, but if you do not stray too far from the suggested values, you should not have to be concerned with this. A series resistor, Rs, is added to the circuit if, after all other external components are selected to satisfaction, the crystal is still being overdriven. This can be determined by looking at the OSC2 pin, which is the driven pin, with an oscilloscope. Connecting the probe to the OSC1 pin will load the pin too much and negatively affect performance. Remember that a scope probe adds its own capacitance to the circuit, so this may have to be accounted for in your design, (i.e. if the circuit worked best with a C2 of 20 pF and scope probe was 10 pF, a 30 pF capacitor may actually be called for). The output signal should not be clipping or squashed. Overdriving the crystal can also lead to the circuit jumping to a higher harmonic level or even crystal damage. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-12  2000 Microchip Technology Inc. The OSC2 signal should be a clean sine wave that easily spans the input minimum and maximum of the clock input pin (4V to 5V peak to peak for a 5V VDD is usually good). An easy way to set this is to again test the circuit at the minimum temperature and maximum VDD that the design will be expected to perform in, then look at the output. This should be the maximum amplitude of the clock output. If there is clipping or the sine wave is squashing near VDD and VSS at the top and bottom, increasing load capacitors will risk too much current through the crystal or push the value too far from the manufacturer’s load specification. Add a trimpot between the output pin and C2, and adjust it until the sine wave is clean. Keeping it fairly close to maximum amplitude at the low temperature and high VDD combination will assure this is the maximum amplitude the crystal will see and prevent overdriving. A series resistor, Rs, of the closest standard value can now be inserted in place of the trimpot. If Rs is too high, perhaps more than 20k ohms, the input will be too isolated from the output, making the clock more susceptible to noise. If you find a value this high is needed to prevent overdriving the crystal, try increasing C2 to compensate. Try to get a combination where Rs is around 10k or less and load capacitance is not too far from the 20 pF or 32 pF manufacturer specification. 2.4.3.1.1 Start-up The most difficult time for the oscillator to start-up is when waking up from sleep. This is because the load capacitors have both partially charged to some quiescent value, and phase differential at wake-up is minimal. Thus, more time is required to achieve stable oscillation. Remember also that low voltage, high temperatures and the lower frequency clock modes also impose limitations on loop gain, which in turn affects start-up. Each of the following factors makes the start-up time worse: • a low frequency design (with its low gain clock mode) • a quiet environment (such as a battery operated device) • operating in a shielded box (away from the noisy RF area) • low voltage • high temperature • waking up from sleep. Noise actually helps a design for oscillator start-up, since it helps “kick start” the oscillator. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-13 Section 2. Oscillator Oscillator 2 2.4.4 External Clock Input Two of the oscillator modes use an external clock. These modes are EC and ECIO oscillator modes. In the EC mode (Figure2-5), the OSC1 pin can be driven by CMOS drivers. In this mode, the OSC1/CLKI pin is hi-impedance and the OSC2/CLKO pin is the CLKO output (FOSC/4). The output is at a frequency of the selected oscillator divided by 4. This output clock is useful for testing or synchronization purposes. If the power-up timer is disabled, then there is no time-out after a POR, or else there will be a power-up timer. There is always a power-up time after a brown-out reset. The feedback device between OSC1 and OSC2 is turned off to save current. There is no oscillator start-up time required after wake-up from sleep mode. If the power-up timer is disabled, then there is no time-out after a POR, or else (power-up timer enabled) there will be a power-up timer delay after POR. There is always a power-up timer after a brown-out reset. Figure 2-5: External Clock Input Operation (EC Oscillator Configuration) In the ECIO mode (Figure2-6), the OSC1 pin can be driven by CMOS drivers. In this mode, the OSC1/CLKI pin is hi-impedance and the OSC2/CLKO is now multiplexed with a general purpose I/O pin. The feedback device between OSC1 and OSC2 is turned off to save current. There is no oscillator start-up time required after wake-up from sleep mode. If the power-up timer is disabled, then there is no time-out after a POR, or else (power-up timer enabled) there will be a power-up timer delay after POR. There is always a power-up timer after a brown-out reset. Figure 2-6: External Clock Input Operation (ECIO Oscillator Configuration) OSC1 FOSC/4 OSC2 Clock from ext. system PIC18CXXX CLKI IO pin I/O (CLKO) Clock from ext. system PIC18CXXX 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-14  2000 Microchip Technology Inc. 2.4.5 External Crystal Oscillator Circuit for Device Clock Sometimes more than one device needs to be clocked from a single crystal. Since Microchip does not recommend connecting other logic to the PICmicro’s internal oscillator circuit, an external crystal oscillator circuit is recommended. Each device will then have an external clock source, and the number of devices that can be driven will depend on the buffer drive capability. This circuit is also useful when more than one device needs to operate synchronously to each other. Either a prepackaged oscillator can be used or a simple oscillator circuit with TTL gates can be built. Prepackaged oscillators provide a wide operating range and better stability. A well-designed crystal oscillator will provide good performance with TTL gates. Two types of crystal oscillator circuits can be used; one with series resonance or one with parallel resonance. Figure2-7 shows implementation of an external parallel resonant oscillator circuit. The circuit is designed to use the fundamental frequency of the crystal. The 74AS04 inverter performs the 180-degree phase shift that a parallel oscillator requires. The 4.7 kΩ resistor affects the circuit in three ways: 1. Provides negative feedback. 2. Biases the 74AS04 (#1) into the linear region. 3. Bounds the gain of the amplifier. The 10 kΩ potentiometer is used to prevent overdriving of the crystal. It dissipates the power of the amplifier and allows the requirements of the crystal to be met. Figure 2-7: External Parallel Resonant Crystal Oscillator Circuit Figure2-8 shows an external series resonant oscillator circuit. This circuit is also designed to use the fundamental frequency of the crystal. The inverter performs a 180-degree phase shift in a series resonant oscillator circuit. The 330 kΩ resistors provide the negative feedback to bias the inverters in their linear region. Figure 2-8: External Series Resonant Crystal Oscillator Circuit When the device is clocked from an external clock source (as in Figure2-7 or Figure2-8) then the microcontroller’s oscillator should be configured for EC or ECIO mode (Figure2-3). 20 pF +5V 20 pF 10kΩ 4.7 kΩ 10 kΩ 74AS04 XTAL 10 kΩ 74AS04 CLKI To Other Devices PIC18CXXX (#1) (#2) 330 kΩ 74AS04 74AS04 PIC18CXXX CLKI To Other Devices XTAL 330 kΩ 74AS04 0.1 µF 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-15 Section 2. Oscillator Oscillator 2 2.5 External RC Oscillator For timing insensitive applications, the RC and RCIO device options offer additional cost savings. The RC oscillator frequency is a function of the: • Supply voltage • External resistor (REXT) values • External capacitor (CEXT) values • Operating temperature In addition to this, the oscillator frequency will vary from unit to unit due to normal process parameter variation. Furthermore, the difference in lead frame capacitance between package types will also affect the oscillation frequency, especially for low CEXT values. The user also needs to take into account variation due to tolerance of external REXT and CEXT components used. Figure2-9 shows how the RC combination is connected. For REXT values below 2.2 kΩ, oscillator operation may become unstable, or stop completely. For very high REXT values (e.g. 1 MΩ), the oscillator becomes sensitive to noise, humidity and leakage. Thus, we recommend keeping REXT between 3 kΩ and 100 kΩ. Figure 2-9: RC Oscillator Mode Although the oscillator will operate with no external capacitor (CEXT = 0 pF), we recommend using values above 20 pF for noise and stability reasons. With no or a small external capacitance, the oscillation frequency can vary dramatically due to changes in external capacitances, such as PCB trace capacitance and package lead frame capacitance. See characterization data for RC frequency variation from part to part due to normal process variation. The variation is larger for larger resistance (since leakage current variation will affect RC frequency more for large R) and for smaller capacitance (since variation of input capacitance will affect RC frequency more). See characterization data for the variation of oscillator frequency due to VDD for given REXT/CEXT values, as well as frequency variation due to operating temperature for given REXT, CEXT and VDD values. The oscillator frequency, divided by 4, is available on the OSC2/CLKO pin, and can be used for test purposes or to synchronize other logic (see Figure 4-3: "Clock/Instruction Cycle" in the “Architecture” section, for waveform). OSC2/CLKO CEXT VDD REXT VSS PIC18CXXX OSC1 FOSC/4 (1) Internal Clock FOSC Note 1: This output may also be configured as a general purpose I/O pin. 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-16  2000 Microchip Technology Inc. 2.5.1 RC Oscillator with I/O Enabled The RCIO oscillator mode functions in the exact same manner as the RC oscillator mode. The only difference is that OSC2 pin does not output oscillator frequency divided by 4, but in this mode is configured as an I/O pin. As in the RC mode, the user needs to take into account any variation of the clock frequency due to tolerance of external REXT and CEXT components used, process variation, voltage, and temperature. Figure2-10 shows how the RC with the I/O pin combination is connected. Figure 2-10: RCIO Oscillator Mode I/O (OSC2) CEXT REXT VSS PIC18CXXX OSC1 Internal Clock VDD 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-17 Section 2. Oscillator Oscillator 2 2.5.2 RC Start-up As the device voltage increases, the RC will start its oscillations immediately after the pin voltage levels meet the input threshold specifications (parameters D032 and D042 in the “Electrical Specifications” section). The time required for the RC to start oscillating depends on many factors. These include: • Resistor value used • Capacitor value used • Device VDD rise time • System temperature There is no oscillator start-up time (TOST) regardless of the source of reset or when sleep is terminated. If the power-up timer is disabled, then there is no time-out after a POR, or else (power-up timer enabled) there will be a power-up timer delay after POR. There is always a power-up time after a brown-out reset. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-18  2000 Microchip Technology Inc. 2.6 HS4 (HS oscillator with 4xPLL enabled) A Phase Locked Loop (PLL) circuit is provided as a programmable option for users that want to multiply the frequency of the incoming crystal oscillator signal by 4. For an input clock frequency of 10 MHz, the internal clock frequency will be multiplied to 40 MHz. This is useful for customers who are concerned with EMI due to high frequency crystals. The PLL can only be enabled when the oscillator configuration bits are programmed for HS4 mode (FOSC2:FOSC0 = ‘110’). If they are programmed for any other mode, the PLL is not enabled and the system clock will come directly from OSC1. The oscillator mode is specified during device programming. The PLL is divided into four basic parts (see Figure2-11): • Phase comparator • Loop filter • VCO (Voltage Controlled Oscillator) • Feedback divider When in HS4 mode, the incoming clock is sampled by the phase comparator and is compared to PLL output clock divided by four. If the two are not in phase, the phase comparator drives an input to the loop filter to "pump" the voltage to the VCO, either up or down, depending upon whether the input clock was leading or lagging the output clock. This process continues until the incoming clock on OSC1 and the divide by 4 output clock of the VCO are in phase. The output clock is now "locked" in phase with the incoming clock, and its frequency is four times greater. A PLL lock timer is used to ensure that the PLL has locked before device execution starts. The PLL lock timer has a time-out that is called TPLL. This delay is shown in Figure2-14. Figure 2-11: PLL Block Diagram MUX VCO Loop Filter Divide by 4 Crystal Oscillator OSC2 OSC1 SYSCLK Phase Comparator CVCO Circuitry FOSC2:FOSC0 = ‘110’ PIC18CXXX 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-19 Section 2. Oscillator Oscillator 2 2.7 Switching to Low Power Clock Source This feature allows the clock source to switch from the default clock source that is selected by the FOSC2:FOSC0 bits to the Timer1 oscillator clock source. The availability of this feature is device dependent. 2.7.1 Switching Oscillator Mode Option This feature is enabled by clearing the Oscillator System Clock Switch Enable (OSCSEN) configuration bit. This provides the ability to switch to a low power execution mode if the alternate clock source (such as Timer1) is configured in oscillator mode with a low frequency (32 kHz, for example) crystal. The enabling of the low power clock source is determined by the state of the SCS control bit in the Oscillator control register (OSCCON). (Register 2-1) 2.7.1.2 System Clock Switch Bit The system clock switch bit, SCS (OSCCON) controls the switching of the oscillator source. It can be configured for either the Timer1 Oscillator clock source, or the default clock source (selected by the Fosc2:Fosc0 bits). When the SCS bit is set, it enables the Timer1 Oscillator clock source as the system clock. When the SCS bit is cleared, the system clock comes from the clock source specified by the Fosc2:Fosc0 bits. The SCS bit is cleared on all forms of reset. Note: The Timer1 oscillator must be enabled in order to switch the system clock source. The Timer1 oscillator is enabled by setting the T1OSCEN bit in the Timer1 Control Register (T1CON). If the Timer1 oscillator is not enabled, then any write to the SCS bit will be ignored, and the SCS bit will remain in the default state with the clock source coming from OSC1 or the PLL output. 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-20  2000 Microchip Technology Inc. 2.7.2 Oscillator Transitions Switching from the default clock to the Timer1 Oscillator clock source is controlled as shown in the flow diagram (Figure2-16). This ensures a clean transition when switching oscillator clocks. Circuitry is used to prevent "glitches" due to transitions when switching from the default clock source to the low power clock source and vice versa. Essentially, the circuitry waits for eight rising edges of the clock input to which the processor is switching. This ensures that the clock output pulse width will not be less than the shortest pulse width of the two clock sources. No additional delays are required when switching from the default clock source to the low power clock source. Figure2-12 through Figure2-15 show different transition waveforms when switching between the oscillators. Figure 2-12: Transition From OSC1 to Timer1 Oscillator Waveform Figure 2-13: Transition Between Timer1 and OSC1 Waveform (HS, XT, LP) Q2 Q3 Q4 Q1 Q2 Q3 OSC1 Internal SCS Program PC PC + 2 Note 1: Delay on internal system clock is eight oscillator cycles for synchronization. 2: The T1OSCEN bit is set. 3: The OSCSEN configuration bit is cleared. Q1 T1OSI (2) Q4 Q1 PC + 4 Q1 Tscs Clock Counter System Q2 Q3 Q4 Q1 TDLY TT1P TOSC 1 34 5678 2 (OSCCON) Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 OSC1 Internal SCS (OSCCON) Program PC PC + 2 Note 1: TOST = 1024TOSC (drawing not to scale). T1OSI OSC2 TOST Q1 PC + 6 TT1P TOSC TSCS 1 2 34 567 8 System Clock Counter 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-21 Section 2. Oscillator Oscillator 2 Figure 2-14: Transition Between Timer1 and OSC1 Waveform (HS4) Figure 2-15: Transition Between Timer1 and OSC1 Waveform (RC, EC, ECIO) Additional delays may occur before switching from the low power clock source back to the main oscillator. The sequence of events that take place will depend upon the main oscillator setting in the configuration register (the mode of the main oscillator). If the main oscillator is configured as a RC oscillator (RC, RCIO) or External Clock (EC, ECIO), then there is no oscillator start-up time. The transition from a low power clock to the main oscillator occurs after 8 clock cycles are counted on OSC1. If the main oscillator is configured as a crystal (HS4, HS, XT or LP), then the transition will take place after an oscillator start-up time (TOST). If the main oscillator is configured as a crystal with PLL (HS4) enabled, then the transition will take place after an oscillator start-up time (TOST) plus an additional PLL time-out, TPLL (see “Electrical Specifications” section, parameter 32). This is necessary because the crystal oscillator had been powered down until the time of the transition. In order to provide the system with a reliable clock when the change-over has occurred, the clock will not be released to the change-over circuit until the oscillator start-up time has expired. The additional TPLL time is required after oscillator start-up to allow the phase lock loop ample time to lock to the incoming oscillator frequency from OSC1. Q4 Q1 Q1 Q2 Q3 Q4 Q1 Q2 OSC1 SCS (OSCCON) Program PC PC + 2 Note 1: TOST = 1024TOSC (drawing not to scale). T1OSI TOST Q3 PC + 4 TPLL TOSC TT1P TSCS Q4 OSC2 PLL Clock Input 1 234 5678 Internal System Clock Counter Q3 Q4 Q1 Q1 Q2 Q3 Q4 Q1 Q2 Q3 OSC1 SCS (OSCCON) PC PC + 2 Note 1: RC oscillator mode assumed. PC + 4 T1OSI OSC2 Q4 TT1P TOSC TSCS 1 2 3 4 5 6 7 8 Program Counter Internal System Clock 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-22  2000 Microchip Technology Inc. A flow diagram for switching between a low power clock and the default oscillator clock is shown in Figure2-16. Figure 2-16: Switching Oscillator Flow Diagram Start SCS = 0? Has SCS Begin switch to low power clock N = 0, hold CPU clock Transition on Newclk? N=N+1 N = 8? Sysclk = Newclk, Release Q clocks Begin switch to high speed clock FOSC2:FOSC0 = XT, LP, Start OST, wait 1024 oscillations on OSC1 Newclk = XT, HS, LP FOSC2:FOSC0 = HS4 Newclk = HS4 Newclk = T1OSC input Newclk = EC or RC Start OST, wait 1024 oscillations on OSC1 Yes Yes Yes Yes Yes No No No No No T1OSCEN = 1? Yes No No switch to low power clock. Set SCS = 0 End End changed state? Wait TPLL for PLL to lock in Q1 state OSCSEN = 0? No Yes End No switch to low power clock or HS? 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-23 Section 2. Oscillator Oscillator 2 2.8 Effects of Sleep Mode on the On-Chip Oscillator When the device executes a SLEEP instruction, the on-chip clocks and oscillator are turned off and the device is held at the beginning of an instruction cycle (Q1 state). With the oscillator off, the OSC1 and OSC2 signals will stop oscillating. Since all the transistor switching currents have been removed, SLEEP mode achieves the lowest current consumption of the device (only leakage currents). Enabling any on-chip feature that will operate during SLEEP will increase the current consumed. The user can wake from SLEEP through external reset, Watchdog Timer Reset or through an interrupt. See Table 3-1 in the “Reset” section for time-outs due to SLEEP and MCLR reset. Table 2-4: OSC1 and OSC2 Pin States in Sleep Mode 2.9 Effects of Device Reset on the On-Chip Oscillator Device resets have no effect on the on-chip crystal oscillator circuitry. The oscillator will continue to operate as it does under normal execution. While in RESET, the device logic is held at the Q1 state so that when the device exits RESET, it is at the beginning of an instruction cycle. The OSC2 pin, when used as the external clockout (RC, EC mode), will be held low during RESET, and as soon as the MCLR pin is at VIH (input high voltage), the RC will start to oscillate. See Table 3-1 in the “Reset” section for time-outs due to SLEEP and MCLR reset. 2.9.1 Power-up Delays Power-up delays are controlled by two timers, so that no external reset circuitry is required for most applications. The delays ensure that the device is kept in RESET until the device power supply and clock are stable. For additional information on RESET operation, see the “Reset” section. The Power-up Timer (PWRT) provides a fixed 72 ms delay on power-up due to POR or BOR, and keeps the part in RESET until the device power supply is stable. When a crystal is used (LP, XT, HS), the Oscillator Start-Up Timer (OST) keeps the chip in RESET until the PWRT timer delay has expired, allowing the crystal oscillator to stabilize on power up. The PWRTEN bit must be cleared for this time-out to occur. When the PLL is enabled (HS4 oscillator mode), the Power-up Timer (PWRT) is used to keep the device in RESET for an extra nominal delay (TPLL) above crystal mode. This delay ensures that the PLL is locked to the crystal frequency. For additional information on RESET operation, see the “Reset” section. OSC Mode OSC1 Pin OSC2 Pin RC Floating, external resistor should pull high At logic low RCIO Floating, external resistor should pull high Configured as I/O pin ECIO Floating Configured as I/O pin EC Floating At logic low LP, XT and HS Feedback inverter disabled at quiescent voltage level Feedback inverter disabled at quiescent voltage level HS4 Feedback inverter disabled at quiescent voltage level Feedback inverter disabled at quiescent voltage level 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-24  2000 Microchip Technology Inc. 2.10 Design Tips Question 1: When looking at the OSC2 pin after power-up with an oscilloscope, there is no clock. What can cause this? Answer 1: 1. Executing a SLEEP instruction with no source for wake-up (such as, WDT, MCLR, or an Interrupt). Verify that the code does not put the device to SLEEP without providing for wake-up. If it is possible, try waking it up with a low pulse on MCLR. Powering up with MCLR held low will also give the crystal oscillator more time to start-up, but the Program Counter will not advance until the MCLR pin is high. 2. The wrong clock mode is selected for the desired frequency. For a blank device, the default oscillator is RCIO. Most parts come with the clock selected in the default RC mode, which will not start oscillation with a crystal or resonator. Verify that the clock mode has been programmed correctly. 3. The proper power-up sequence has not been followed. If a CMOS part is powered through an I/O pin prior to power-up, bad things can happen (latch up, improper start-up, etc.) It is also possible for brown-out conditions, noisy power lines at start-up, and slow VDD rise times to cause problems. Try powering up the device with nothing connected to the I/O, and power-up with a known, good, fast-rise, power supply. Refer to the power-up information in the device data sheet for considerations on brown-out and power-up sequences. 4. The C1 and C2 capacitors attached to the crystal have not been connected properly or are not the correct values. Make sure all connections are correct. The device data sheet values for these components will usually get the oscillator running; however, they just might not be the optimal values for your design. Question 2: The PICmicro device starts, but runs at a frequency much higher than the resonant frequency of the crystal. Answer 2: The gain is too high for this oscillator circuit. Refer to subsection 2.4 “Crystal Oscillators/Ceramic Resonators” to aid in the selection of C2 (may need to be higher) Rs (may be needed) and clock mode (wrong mode may be selected). This is especially possible for low frequency crystals, like the common 32.768 kHz. Question 3: The design runs fine, but the frequency is slightly off. What can be done to adjust this? Answer 3: Changing the value of C1 has some effect on the oscillator frequency. If a SERIES resonant crystal is used, it will resonate at a different frequency than a PARALLEL resonant crystal of the same frequency call-out. Ensure that you are using a PARALLEL resonant crystal. Question 4: The board works fine, then suddenly quits or loses time. Answer 4: Other than the obvious software checks that should be done to investigate losing time, it is possible that the amplitude of the oscillator output is not high enough to reliably trigger the oscillator input. Look at the C1 and C2 values and ensure that the the device configuration bits are correct for the desired oscillator mode. Question 5: If I put an oscilloscope probe on an oscillator pin, I don’t see what I expect. Why? Answer 5: Remember that an oscilloscope probe has capacitance. Connecting the probe to the oscillator circuitry will modify the oscillator characteristics. Consider using a low capacitance (active) probe. 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39502A-page 2-25 Section 2. Oscillator Oscillator 2 2.11 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced MCU family (that is they may be written for the Base-Line, Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the oscillator are: Title Application Note # PICmicro Microcontrollers Oscillator Design Guide AN588 Low Power Design using PICmicro Microcontrollers AN606 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39502A-page 2-26  2000 Microchip Technology Inc. 2.12 Revision History Revision A This is the initial released revision of the Enhanced MCU oscillators description. 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-1 Reset 3 Section 3. Reset HIGHLIGHTS This section of the manual contains the following major topics: 3.1 Introduction .................................................................................................................... 3-2 3.2 Resets and Delay Timers............................................................................................... 3-4 3.3 Registers and Status Bit Values................................................................................... 3-14 3.4 Design Tips.................................................................................................................. 3-20 3.5 Related Application Notes............................................................................................ 3-21 3.6 Revision History........................................................................................................... 3-22 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-2  2000 Microchip Technology Inc. 3.1 Introduction The reset logic is used to place the device into a known state. The source of the reset can be determined by reading the device status bits. The reset logic is designed with features that reduce system cost and increase system reliability. Devices differentiate between various kinds of reset: a) Power-on Reset (POR) b) MCLR Reset during normal operation c) MCLR Reset during SLEEP d) WDT Reset (normal operation) e) Programmable Brown-out Reset (BOR) f) RESET Instruction g) Stack Overflow Reset h) Stack Underflow Reset Most registers are unaffected by a reset; their status is unknown on POR and unchanged by all other resets. The other registers are forced to a “reset state” on Power-on Reset, MCLR, WDT Reset, Brown-out Reset, MCLR Reset during SLEEP and by the RESET instruction. Most registers are not affected by a WDT wake-up, since this is viewed as the resumption of normal operation. Status bits from the RCON register, RI, TO, PD, POR and BOR are set or cleared differently in different reset situations as indicated in Table 3-3. These bits are used in software to determine the nature of the reset. See Table 3-4 for a full description of the reset states of all registers. A simplified block diagram of the on-chip reset circuit is shown in Figure 3-1. This block diagram is a superset of reset features. To determine the features that are available on a specific device, please refer to the device’s Data Sheet. Note: While the Enhanced MCU is in a reset state, the internal phase clock is held at Q1 (beginning of an instruction cycle). 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-3 Section 3. Reset Reset 3 Figure 3-1: Simplified Block Diagram of On-chip Reset Circuit S R Q External Reset MCLR VDD OSC1 WDT Module OST/PWRT On-chip (1) RC OSC WDT Time-out Power-on Reset OST 10-bit Ripple counter PWRT Chip_Reset 10-bit Ripple counter Reset Enable OSTT (2) Enable PWRT SLEEP Note 1: This is a separate oscillator from the RC oscillator of the CLKIN pin. 2: See Table 3-1 for time-out situations. Brown-out Reset BOREN RESET Instruction Stack Pointer Stack Overflow/Underflow Reset VDD rise detect 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-4  2000 Microchip Technology Inc. 3.2 Resets and Delay Timers The device has many sources for a device reset. Depending on the source of the reset, different delays may be initiated. These reset sources and the delays are discussed in the following subsections. 3.2.1 Power-on Reset (POR) A Power-on Reset pulse is generated on-chip when VDD rise is detected. To take advantage of the POR, just tie the MCLR pin directly (or through a resistor) to VDD as shown in Figure 3-2. This will eliminate external RC components usually needed to create a Power-on Reset delay. A minimum rise time for VDD is required. See parameter D003 and parameter D004 in the “Electrical Specifications” section for details. Figure 3-2: Using On-Chip POR When the device exits the reset condition (begins normal operation), the device operating parameters (voltage, frequency, temperature, etc.) must be within their operating ranges, otherwise the device will not function correctly. Ensure the delay is long enough to get all operating parameters within specification. Figure 3-3 shows a possible POR circuit for a slow power supply ramp up. The external Power-on Reset circuit is only required if the device would exit reset before the device VDD is in the valid operating range. The diode, D, helps discharge the capacitor quickly when VDD powers down. Figure 3-3: External Power-on Reset Circuit (For Slow VDD Power-up) VDD MCLR PIC18CXXX VDD R (1) Note 1: The resistor is optional. VDD VDD Note 1: R < 40 kΩ is recommended to ensure that the voltage drop across R does not violate the device’s electrical specification. 2: R1 = 100Ω to 1 kΩ will limit any current flowing into MCLR from external capacitor C in the event of MCLR/VPP pin breakdown due to Electrostatic Discharge (ESD) or Electrical Overstress (EOS). C R1 D R MCLR PIC18CXXX  2000 Microchip Technology Inc. DS39503A-page 3-5 Section 3. Reset Reset 3 3.2.2 Power-up Timer (PWRT) The Power-up Timer provides a delay on Power-on Reset (POR) or Brown-out Reset (BOR). See parameter D033 in the ““Electrical Specifications” section. The Power-up Timer operates on a dedicated internal RC oscillator. The device is kept in reset as long as the PWRT is active. The PWRT delay allows VDD to rise to an acceptable level. A configuration bit (PWRTEN) is provided to enable/disable the Power-up Timer. The power-up time delay will vary from device to device due to VDD, temperature and process variations. See DC parameters for details. 3.2.3 Oscillator Start-up Timer (OST) The Oscillator Start-Up Timer (OST) provides a 1024 oscillator cycle delay (from OSC1 input) (parameter 32) after the PWRT delay is over. This ensures that the crystal oscillator or resonator has started and is stable. The OST time-out is invoked only for XT, LP and HS modes, on Power-on Reset, Brown-out Reset, wake-up from SLEEP, or on a transition from Timer1 input clock as the system clock to the oscillator as the system clock by clearing the SCS bit. The oscillator start-up timer is disabled for all resets and wake-ups in RC and EC modes. (See Table 3-1) The OST counts the oscillator pulses on the OSC1/CLKIN pin. The counter only starts incrementing after the amplitude of the signal reaches the oscillator input thresholds. This delay allows the crystal oscillator or resonator to stabilize before the device exits the OST delay. The length of the time-out is a function of the crystal/resonator frequency. Figure 3-4 shows the operation of the OST circuit in conjunction with the power-up timer. For low frequency crystals, this start-up time can become quite long. That is because the time it takes the low frequency oscillator to start oscillating is longer than the power-up timer’s delay. The time from when the power-up timer times out to when the oscillator starts to oscillate is a dead time. There is no minimum or maximum time for this dead time (TDEADTIME), and is dependent on the time for the oscillator circuitry to have “good” oscillations. Figure 3-4: Oscillator Start-up Time 3.2.3.1 PLL Lock Time-out When the PLL is enabled, the time-out sequence following a Power-on Reset is different from other oscillator modes. A portion of the Power-up Timer is used to provide a fixed time-out that is sufficient for the PLL to lock to the main oscillator frequency. This PLL lock time-out TPLL (2ms nominal, Parameter 7 in the “Electrical Specifications” section) follows the Oscillator Start-up Time-out (OST). Note: Some devices require the Power-up Timer to be enabled when the Brown-out Reset circuitry is enabled. Please refer to the device data sheet for requirements. VDD MCLR Oscillator OST TIME_OUT PWRT TIME_OUT INTERNAL RESET TOSC1 TOST TPWRT POR or BOR Trip Point TOSC1 = Time for the crystal oscillator to react to an oscillation level detectable by the Oscillator Start-up Timer (OST). TOST = 1024TOSC. TDEADTIME 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-6  2000 Microchip Technology Inc. 3.2.4 Power-up Sequence On power-up, the time-out sequence is as follows: First the internal POR is detected, then, if enabled, the PWRT time-out is invoked. After the PWRT time-out is over, the OST is activated. The total time-out will vary based on oscillator configuration and PWRTEN bit status. For example, in RC mode with the PWRTEN bit set (PWRT disabled), there will be no time-out at all. Figure 3-5, Figure 3-6 and Figure 3-7 depict time-out sequences. Since the time-outs occur from the internal POR pulse, if MCLR is kept low long enough, the time-outs will expire. Bringing MCLR high will begin execution immediately (Figure 3-7). This is useful for testing purposes or to synchronize more than one device operating in parallel. If the device voltage is not within the electrical specifications by the end of a time-out, the MCLR/VPP pin must be held low until the voltage is within the device specification. The use of an external RC delay is sufficient for many of these applications. On wake-up from sleep, the OST is activated for various oscillator configurations. When the PLL is activated in HS mode, an additional delay called TPLL (2 ms nominal) is added to the OST time-out to allow the necessary lock time for the PLL. See parameter D003 in the “Electrical Specifications” section for details. Table 3-1 shows the time-outs that occur in various situations, while Figure 3-5 through Figure 3-8 show four different cases that can happen on powering up the device. Table 3-1: Time-out in Various Situations Figure 3-5: Time-out Sequence on Power-up (MCLR Tied to VDD) Oscillator Configuration Power-up (2) or Brown-Out (3) Wake-up from SLEEP or PWRTEN Oscillator Switch = 0 PWRTEN = 1 HS with PLL enabled (1) 72 ms + 1024Tosc + 2ms 1024Tosc + 2 ms 1024Tosc + 2 ms HS, XT, LP 72 ms + 1024Tosc 1024Tosc 1024Tosc EC 72 ms — — External RC 72 ms — — Note 1: 2 ms = Nominal time required for the PLL to lock. See the “Electrical Specifications” section. 2: 72 ms is the nominal power-up timer delay. See the “Electrical Specifications” section. 3: It is recommended that the power-up timer is enabled when using the Brown-out Reset module. TPWRT (1) TOST VDD MCLR INTERNAL POR PWRT TIME-OUT OST TIME-OUT INTERNAL RESET Note 1: TPWRT only occurs when PWRTEN = ‘1’. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-7 Section 3. Reset Reset 3 Figure 3-6: Time-out Sequence on Power-up (MCLR not Tied to VDD): Case 1 Figure 3-7: Time-out Sequence on Power-up (MCLR not Tied to VDD): Case 2 Figure 3-8: Time-out Sequence on Power-up with Slow Rise Time (MCLR Tied to VDD) TPWRT (1) TOST VDD MCLR INTERNAL POR PWRT TIME-OUT OST TIME-OUT INTERNAL RESET Note 1: TPWRT only occurs when PWRTEN = ‘1’. VDD MCLR INTERNAL POR PWRT TIME-OUT OST TIME-OUT INTERNAL RESET TOST Note 1: TPWRT only occurs when PWRTEN = ‘1’. TPWRT (1) VDD MCLR INTERNAL POR PWRT TIME-OUT OST TIME-OUT INTERNAL RESET 0V 5V TOST TDEADTIME Note 1: TPWRT only occurs when PWRTEN = ‘1’. TPWRT (1) 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-8  2000 Microchip Technology Inc. Figure 3-9: Time-out Sequence on POR w/ PLL Enabled (MCLR Tied to VDD) TOST VDD MCLR IINTERNAL POR PWRT TIME-OUT OST TIME-OUT INTERNAL RESET PLL TIME-OUT TPLL TOST = 1024 clock cycles. TPLL = PLL lock time. TPWRT (1) Note 1: TPWRT only occurs when PWRTEN = ‘1’. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-9 Section 3. Reset Reset 3 3.2.5 Brown-Out Reset (BOR) On-chip Brown-out Reset circuitry places the device into reset when the device voltage (VDD) falls below a trip point (VBOR). This ensures that the device does not continue program execution outside the valid voltage operation range of the device. Brown-out resets are typically used in AC line applications (such as appliances) or large battery applications where large loads may be switched in (such as automotive). Appliances encounter brown-out situations during plug-in and online voltage dip. Automotive electronics encounter brown-out when the ignition key is turned. In these application scenarios, the device voltage temporarily falls below the specified operating minimum. If the brown-out circuit meets the current consumption requirements of the system, it may also be used as a voltage supervisory function. Figure 3-10 shows typical brown-out situations. The Brown-out Reset module is enabled by default. To disable the module, the BOREN configuration bit must be cleared at device programming. Figure 3-10: Brown-Out Situations Note: Before using the on-chip brown-out for a voltage supervisory function (monitor battery decay), please review the electrical specifications to ensure that they meet your requirements. Note 1: It is recommended that the power-up timer be enabled when using the BOR module. The power-up timer is enabled by programming the PWRTEN configuration bit to ‘0’. Note 2: Some devices require the Power-up Timer to be enabled when the Brown-out Reset circuitry is enabled. Please refer to the device data sheet for requirements. Power-up time VDD Internal Reset VBOR VDD Internal Reset VBOR VDD Internal Reset VBOR Note 1: The Electrical Specification Parameter (parameter 33) has a typical value of 72 ms. parameter 33 parameter 33 parameter 33 (1) (parameter 33) 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-10  2000 Microchip Technology Inc. 3.2.5.1 BOR Operation The BOREN configuration bit can disable (if clear/programmed) or enable (if set) the Brown-out Reset circuitry. If VDD falls below VBOR (parameter D005 in the “Electrical Specifications” section), for greater than the Brown-out Pulse Width Time (TBOR), parameter 35, the brown-out situation will reset the chip. A reset is not guaranteed to occur if VDD falls below VBOR for less than parameter 35. The chip will remain in Brown-out Reset until VDD rises above VBOR. After which, the Power-up Timer is invoked and will keep the chip in reset an additional time delay (parameter 33). If VDD drops below VBOR while the Power-up Timer is running, the chip will go back into Reset and the Power-up Timer will be re-initialized. Once VDD rises above VBOR, the Power-up Timer will again start a time delay. When the BOREN bit is set, all voltages below VBOR will hold the device in the reset state. This includes during the power-up sequence. The brown-out trip point is user programmable at time of device programming. Figure 3-11 is a block diagram for the BOR circuit. Figure 3-11: Block Diagram of BOR Circuit BOR VDD EN BOR 3 to 1 MUX BOREN LVDEN VREN BORV1:BORV0 Configuration Bits Internally Generated Reference Voltage 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-11 Section 3. Reset Reset 3 The Brown-out Reset circuit has four available reset trip point voltages. The device selected determines which trip points make sense in an application. All devices have the trip points of 4.2V and 4.5V available. PIC18LCXXX devices add two more trip points. The first is 2.7V, while the second is dependent on the minimum operating voltage of that device. This means that the lowest trip point voltage will either be 2.5V or 1.8V. Table 3-2 shows the state of the configuration bits (BORV1:BORV0) and the BOR trip points that they select. Table 3-2: Example BOR Trip Point Levels The BOR is programmable to ensure that the BOR can be optimized to the voltage-frequency of the device, since the minimum device VDD value will depend on the frequency of operation. For example, VDD min. at 40 MHz may be 4.2V, whereas at 2 MHz it may be 1.8V. BORV1:BORV0 Configuration Bits Minimum Voltage Trip Point Maximum Voltage Trip Point Comment 1 1 1.8 V 1.86 V PIC18LCXXX Devices (w/ VDDMIN = 1.8V) 1 1 2.5 V 2.58 V PIC18LCXXX Devices (w/ VDDMIN ≥ 2.0V) 1 0 2.7 V 2.78 V PIC18LCXXX Devices 0 1 4.2 V 4.33 V All Devices 0 0 4.5 V 4.64 V All Devices Note: The minimum voltage at which the Brown-out Reset trip point can occur should be in the valid operating voltage range of the device. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-12  2000 Microchip Technology Inc. 3.2.5.2 Current Implications for BOR Operation There are three components to the current consumption of the BOR operation. These are: 1. Current from Internal Reference Voltage 2. Current from BOR comparator 3. Current from resistor ladder The Internal Reference Voltage is also used by the Low Voltage Detect circuitry and the A/D voltage references. The resistor ladder is also used by the Low Voltage Detect circuitry. If the Low Voltage Detect is enabled, then only the additional current of the comparator is added for enabling the BOR feature. When the module is enabled, the BOR comparator and voltage divider are enabled and consume static current. The “Electrical Specifications” section parameter 32 gives the current specification. The Brown-out Comparator circuit consumes current when enabled. To eliminate this current consumption, the Brown-out Reset can be disabled by programming the Brown-out Reset Enable configuration bit (BOREN) to '0'. 3.2.5.3 BOR Initialization The BOR module must be enabled and programmed through the device configuration bits. These include BOREN, which enables or disables the module, and BORV1:BORV0, which set the BOR voltage. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-13 Section 3. Reset Reset 3 3.2.5.4 External Brown-Out Reset Circuits There are some applications where the device’s programmable Brown-out Reset trip point levels may still not be at the desired level for the application. Figure 3-12 shows a circuit for external brown-out protection using the MCP100 device. Figure 3-13 and Figure 3-14 are two examples of external circuitry that may be implemented. Each option needs to be evaluated to determine if they match the requirements of the application. Figure 3-12: External Brown-Out Protection Using the MCP100 Figure 3-13: External Brown-Out Protection Circuit 1 Figure 3-14: External Brown-Out Protection Circuit 2 VSS RST MCP100 VDD bypass capacitor PIC18CXXX VDD MCLR Note 1: Internal Brown-out Reset circuitry should be disabled when using this circuit. 2: Resistors should be adjusted for the characteristics of the transistor. 3: This circuit will activate reset when VDD goes below (Vz + 0.7V) where Vz = Zener voltage. VDD 33 kΩ 10 kΩ 40 kΩ VDD MCLR PIC18CXXX Q1 R2 40 kΩ VDD MCLR PIC18CXXX R1 Q1 VDD Note 1: This circuit is less expensive, but less accurate. Transistor Q1 turns off when VDD is below a certain level such that: 2: Internal Brown-out Reset circuitry should be disabled when using this circuit. 3: Resistors should be adjusted for the characteristics of the transistor. VDD • R1 R1 + R2 = 0.7V 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-14  2000 Microchip Technology Inc. 3.3 Registers and Status Bit Values Table 3-3 shows the significance of the device status bits and the initialization conditions for the RCON register. Table 3-4 shows the reset conditions for the Special Function Registers. Register 3-1 shows the bits of the RCON register and Table 3-3 shows the initialization values. Register 3-1: RCON Register Bits and Positions Table 3-3: Status Bits, Their Significance, and the Initialization Condition for RCON Register R/W-0 R/W-0 U-0 R/W-1 R/W-1 R/W-1 R/W-1 R/W-u IPEN LWRT — RI TO PD POR BOR bit 7 bit 0 Condition Program Counter RCON Register RI TO PD POR BOR STKFUL STKUNF Power-on Reset 0000h 00-1 1100 111 0 u u u MCLR Reset during normal operation 0000h 00-u uuuu uuu u u u u Software Reset during normal operation 0000h 0u-0 uuuu 0uu u u u u Stack Overflow Reset during normal operation 0000h 0u-u uu11 uuu u u u 1 Stack Underflow Reset during normal operation 0000h 0u-u uu11 uuu u u 1 u MCLR Reset during SLEEP 0000h 00-u 10uu u10 u u u u WDT Reset 0000h 0u-u 01uu 101 u u u u WDT Wake-up PC + 2 uu-u 00uu u00 u u u u Brown-out Reset 0000h 0u-1 11u0 111 1 0 u u Interrupt Wake-up from SLEEP PC + 2 (1) uu-u 00uu u10 u u u u Legend: u = unchanged, x = unknown, - = unimplemented bit read as '0'. Note 1: When the wake-up is due to an interrupt and the GIEH or GIEL bits are set, the PC is loaded with the interrupt vector (0008h or 0018h). 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-15 Section 3. Reset Reset 3 Table 3-4: Initialization Conditions for SFR Registers Register Power-on Reset, Brown-out Reset MCLR Resets WDT Reset Reset Instruction Stack Resets Wake-up via WDT or Interrupt TOSU ---0 0000 ---0 0000 ---0 uuuu (3) TOSH 0000 0000 0000 0000 uuuu uuuu (3) TOSL 0000 0000 0000 0000 uuuu uuuu (3) STKPTR 00-0 0000 00-0 0000 uu-u uuuu (3) PCLATU ---0 0000 ---0 0000 ---u uuuu PCLATH 0000 0000 0000 0000 uuuu uuuu PCL 0000 0000 0000 0000 PC + 2 (2) TBLPTRU --00 0000 --00 0000 --uu uuuu TBLPTRH 0000 0000 0000 0000 uuuu uuuu TBLPTRL 0000 0000 0000 0000 uuuu uuuu TABLAT 0000 0000 0000 0000 uuuu uuuu PRODH xxxx xxxx uuuu uuuu uuuu uuuu PRODL xxxx xxxx uuuu uuuu uuuu uuuu INTCON 0000 000x 0000 000u uuuu uuuu (1) INTCON2 1111 -1-1 1111 -1-1 uuuu -u-u (1) INTCON3 11-0 0-00 11-0 0-00 uu-u u-uu (1) INDF0 N/A N/A N/A POSTINC0 N/A N/A N/A POSTDEC0 N/A N/A N/A PREINC0 N/A N/A N/A PLUSW0 N/A N/A N/A FSR0H ---- 0000 ---- 0000 ---- uuuu FSR0L xxxx xxxx uuuu uuuu uuuu uuuu WREG xxxx xxxx uuuu uuuu uuuu uuuu INDF1 N/A N/A N/A POSTINC1 N/A N/A N/A POSTDEC1 N/A N/A N/A PREINC1 N/A N/A N/A Legend: u = unchanged, x = unknown, - = unimplemented bit, read as '0', q = value depends on condition. Note 1: One or more bits in the INTCONx or PIRx registers will be affected (to cause wake-up). 2: When the wake-up is due to an interrupt and the GIEL or GIEH bit is set, the PC is loaded with the interrupt vector (0008h or 0018h). 3: When the wake-up is due to an interrupt and the GIEL or GIEH bit is set, the TOSU, TOSH and TOSL are updated with the current value of the PC. The STKPTR is modified to point to the next location in the hardware stack. 4: The long write enable is only reset on a POR or MCLR reset. 5: The bits in the PIR, PIE, and IPR registers are device dependent. Their function and location may change from device to device. 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-16  2000 Microchip Technology Inc. PLUSW1 N/A N/A N/A FSR1H ---- 0000 ---- 0000 ---- uuuu FSR1L xxxx xxxx uuuu uuuu uuuu uuuu BSR ---- 0000 ---- 0000 ---- uuuu INDF2 N/A N/A N/A POSTINC2 N/A N/A N/A POSTDEC2 N/A N/A N/A PREINC2 N/A N/A N/A PLUSW2 N/A N/A N/A FSR2H ---- 0000 ---- 0000 ---- uuuu FSR2L xxxx xxxx uuuu uuuu uuuu uuuu STATUS ---x xxxx ---u uuuu ---u uuuu TMR0H xxxx xxxx uuuu uuuu uuuu uuuu TMR0L xxxx xxxx uuuu uuuu uuuu uuuu T0CON 1111 1111 1111 1111 uuuu uuuu OSCCON ---- ---0 ---- ---0 ---- ---u LVDCON --00 0101 --00 0101 --uu uuuu WDTCON ---- ---0 ---- ---0 ---- ---u RCON (4) 00-1 11q0 00-1 qquu uu-u qquu TMR1H xxxx xxxx uuuu uuuu uuuu uuuu TMR1L xxxx xxxx uuuu uuuu uuuu uuuu T1CON 0-00 0000 u-uu uuuu u-uu uuuu TMR2 xxxx xxxx uuuu uuuu uuuu uuuu PR2 1111 1111 1111 1111 1111 1111 T2CON -000 0000 -000 0000 -uuu uuuu SSPBUF xxxx xxxx uuuu uuuu uuuu uuuu SSPADD 0000 0000 0000 0000 uuuu uuuu SSPSTAT 0000 0000 0000 0000 uuuu uuuu SSPCON1 0000 0000 0000 0000 uuuu uuuu SSPCON2 0000 0000 0000 0000 uuuu uuuu Table 3-4: Initialization Conditions for SFR Registers (Continued) Register Power-on Reset, Brown-out Reset MCLR Resets WDT Reset Reset Instruction Stack Resets Wake-up via WDT or Interrupt Legend: u = unchanged, x = unknown, - = unimplemented bit, read as '0', q = value depends on condition. Note 1: One or more bits in the INTCONx or PIRx registers will be affected (to cause wake-up). 2: When the wake-up is due to an interrupt and the GIEL or GIEH bit is set, the PC is loaded with the interrupt vector (0008h or 0018h). 3: When the wake-up is due to an interrupt and the GIEL or GIEH bit is set, the TOSU, TOSH and TOSL are updated with the current value of the PC. The STKPTR is modified to point to the next location in the hardware stack. 4: The long write enable is only reset on a POR or MCLR reset. 5: The bits in the PIR, PIE, and IPR registers are device dependent. Their function and location may change from device to device. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-17 Section 3. Reset Reset 3 ADRESH xxxx xxxx uuuu uuuu uuuu uuuu ADRESL xxxx xxxx uuuu uuuu uuuu uuuu ADCON0 0000 0000 0000 0000 uuuu uuuu ADCON1 --0- 0000 --0- 0000 --u- uuuu CCPR1H xxxx xxxx uuuu uuuu uuuu uuuu CCPR1L xxxx xxxx uuuu uuuu uuuu uuuu CCP1CON --00 0000 --00 0000 --uu uuuu CCPR2H xxxx xxxx uuuu uuuu uuuu uuuu CCPR2L xxxx xxxx uuuu uuuu uuuu uuuu CCP2CON --00 0000 --00 0000 --uu uuuu TMR3H xxxx xxxx uuuu uuuu uuuu uuuu TMR3L xxxx xxxx uuuu uuuu uuuu uuuu T3CON 0000 0000 uuuu uuuu uuuu uuuu SPBRG xxxx xxxx uuuu uuuu uuuu uuuu RCREG xxxx xxxx uuuu uuuu uuuu uuuu TXREG xxxx xxxx uuuu uuuu uuuu uuuu TXSTA 0000 -01x 0000 -01u uuuu -uuu RCSTA 0000 000x 0000 000u uuuu uuuu IPR2 (5) 11 u PIR2 (5) 0 0 u (1) PIE2 (5) 00 u IPR1 (5) 11 u PIR1 (5) 0 0 u (1) PIE1 (5) 00 u Table 3-4: Initialization Conditions for SFR Registers (Continued) Register Power-on Reset, Brown-out Reset MCLR Resets WDT Reset Reset Instruction Stack Resets Wake-up via WDT or Interrupt Legend: u = unchanged, x = unknown, - = unimplemented bit, read as '0', q = value depends on condition. Note 1: One or more bits in the INTCONx or PIRx registers will be affected (to cause wake-up). 2: When the wake-up is due to an interrupt and the GIEL or GIEH bit is set, the PC is loaded with the interrupt vector (0008h or 0018h). 3: When the wake-up is due to an interrupt and the GIEL or GIEH bit is set, the TOSU, TOSH and TOSL are updated with the current value of the PC. The STKPTR is modified to point to the next location in the hardware stack. 4: The long write enable is only reset on a POR or MCLR reset. 5: The bits in the PIR, PIE, and IPR registers are device dependent. Their function and location may change from device to device. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-18  2000 Microchip Technology Inc. TRISE 0000 -111 0000 -111 uuuu -uuu TRISD 1111 1111 1111 1111 uuuu uuuu TRISC 1111 1111 1111 1111 uuuu uuuu TRISB 1111 1111 1111 1111 uuuu uuuu TRIS -111 1111 -111 1111 -uuu uuuu LATE ---- -xxx ---- -uuu ---- -uuu LATD xxxx xxxx uuuu uuuu uuuu uuuu LATC xxxx xxxx uuuu uuuu uuuu uuuu LATB xxxx xxxx uuuu uuuu uuuu uuuu LATA -xxx xxxx -uuu uuuu -uuu uuuu PORTE ---- -000 ---- -000 ---- -uuu PORTD xxxx xxxx uuuu uuuu uuuu uuuu PORTC xxxx xxxx uuuu uuuu uuuu uuuu PORTB xxxx xxxx uuuu uuuu uuuu uuuu PORTA -x0x 0000 -u0u 0000 -uuu uuuu Table 3-4: Initialization Conditions for SFR Registers (Continued) Register Power-on Reset, Brown-out Reset MCLR Resets WDT Reset Reset Instruction Stack Resets Wake-up via WDT or Interrupt Legend: u = unchanged, x = unknown, - = unimplemented bit, read as '0', q = value depends on condition. Note 1: One or more bits in the INTCONx or PIRx registers will be affected (to cause wake-up). 2: When the wake-up is due to an interrupt and the GIEL or GIEH bit is set, the PC is loaded with the interrupt vector (0008h or 0018h). 3: When the wake-up is due to an interrupt and the GIEL or GIEH bit is set, the TOSU, TOSH and TOSL are updated with the current value of the PC. The STKPTR is modified to point to the next location in the hardware stack. 4: The long write enable is only reset on a POR or MCLR reset. 5: The bits in the PIR, PIE, and IPR registers are device dependent. Their function and location may change from device to device. 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-19 Section 3. Reset Reset 3 3.3.1 Reset Control (RCON) Register The Reset Control (RCON) register contains flag bits to allow differentiation between resets. The Reset Control register has seven bits. The POR (Power-on Reset) bit is cleared on a Power-on Reset and is unaffected otherwise. The user sets this bit following a Power-on Reset. On subsequent resets, if the POR bit is clear (= ‘0’), it will indicate that a Power-on Reset must have occurred. The power-down bit (PD) provides indication if the device was placed into sleep mode. It is set by a power-up, a CLRWDT instruction or by user software. The PD bit is cleared when the SLEEP instruction is executed or by user software. Register 3-2: RCON Register Note: The state of the BOR bit is unknown on Power-on Reset. It must be set by the user and checked on subsequent resets to see if the BOR bit is clear, indicating a brown-out has occurred. The BOR status bit is a “don't care” and is not necessarily predictable if the brown-out circuit is disabled (by clearing the BOREN bit in the Configuration register). R/W-0 R/W-0 U-0 R/W-1 R/W-1 R/W-1 R/W-1 R/W-u IPEN LWRT — RI TO PD POR BOR bit 7 bit 0 bit 7 IPEN: Interrupt Priority Enable bit 1 = Enable priority levels on interrupts 0 = Disable priority levels on interrupts bit 6 LWRT: Long Write Enable bit 1 = Enable Table Writes to internal program memory Once this bit is set, it can only be cleared by a POR or MCLR reset. 0 = Disable Table Writes to internal program memory; Table Writes only to external program memory. bit 5 Unimplemented: Read as '0' bit 4 RI: Reset Instruction Flag bit 1 = The RESET instruction was not invoked 0 = The RESET instruction was executed (must be set in software after the RESET instruction is executed) bit 3 TO: Time-out bit 1 = After power-up, CLRWDT instruction or SLEEP instruction 0 = A WDT time-out occurred bit 2 PD: Power-down bit 1 = After power-up or by the CLRWDT instruction 0 = By execution of the SLEEP instruction bit 1 POR: Power-on Reset Flag bit 1 = A Power-on Reset has not occurred 0 = A Power-on Reset occurred (must be set in software after a Power-on Reset occurs) bit 0 BOR: Brown-out Reset Flag bit 1 = A Brown-out Reset has not occurred 0 = A Brown-out Reset occurred (must be set in software after a Brown-out Reset or Power-on Reset occurs) Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-20  2000 Microchip Technology Inc. 3.4 Design Tips Question 1: With windowed devices, my system resets and operates properly. With an OTP device, my system does not operate properly. Answer 1: The most common reason for this is that the windowed device has not had its window covered. The background light causes the device to power-up in a different state than would typically be seen in a device where no light is present. In most cases, all the General Purpose RAM and Special Function Registers were not initialized by the application software. 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39503A-page 3-21 Section 3. Reset Reset 3 3.5 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range or High-End families), but the concepts are pertinent and could be used (with modification and possible limitations). The current application notes related to Resets are: Title Application Note # Power-up Trouble Shooting AN607 Power-up Considerations AN522 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39503A-page 3-22  2000 Microchip Technology Inc. 3.6 Revision History Revision A This is the initial released revision of the Enhanced MCU Reset description. 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39504A-page 4-1 Architechture 4 Section 4. Architecture HIGHLIGHTS This section of the manual contains the following major topics: 4.1 Introduction .................................................................................................................... 4-2 4.2 Clocking Scheme/Instruction Cycle ............................................................................... 4-5 4.3 Instruction Flow/Pipelining ............................................................................................. 4-6 4.4 I/O Descriptions ............................................................................................................. 4-7 4.5 Design Tips.................................................................................................................. 4-14 4.6 Related Application Notes............................................................................................ 4-15 4.7 Revision History........................................................................................................... 4-16 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39504A-page 4-2  2000 Microchip Technology Inc. 4.1 Introduction The high performance of the PIC18CXXX devices can be attributed to a number of architectural features commonly found in RISC microprocessors. These include: • Harvard architecture • Long Word Instructions • Single Word Instructions • Single Cycle Instructions • Instruction Pipelining • Reduced Instruction Set • Register File Architecture • Orthogonal (Symmetric) Instructions Figure 4-2 shows a general block diagram for PIC18CXXX devices. Harvard Architecture: Harvard architecture has the program memory and data memory as separate memories which are accessed from separate buses. This improves bandwidth over traditional von Neumann architecture in which program and data are fetched from the same memory using the same bus. To execute an instruction, a von Neumann machine must make one or more (generally more) accesses across the 8-bit bus to fetch the instruction. Then data may need to be fetched, operated on and possibly written. As can be seen from this description, the bus can become extremely congested. With a Harvard architecture, the instruction is fetched in a single instruction cycle (all 16 bits). While the program memory is being accessed, the data memory is on an independent bus and can be read and written. These separated busses allow one instruction to execute, while the next instruction is fetched. A comparison of Harvard and von Neumann architectures is shown in Figure 4-1. Figure 4-1: Harvard vs. von Neumann Block Architectures Long Word Instructions: Long word instructions have a wider (more bits) instruction bus than the 8-bit data memory bus. This is possible because the two buses are separate. This allows instructions to be sized differently than the 8-bit wide data word and allows a more efficient use of the program memory, since the program memory width is optimized to the architectural requirements. Single Word Instructions: Single word instruction opcodes are 16-bits wide making it possible to have all but a few instructions be single word instructions. A 16-bit wide program memory access bus fetches a 16-bit instruction in a single cycle. With single word instructions, the number of words of program memory locations equals the number of instructions for the device. This means that all locations are valid instructions. Typically in the von Neumann architecture, most instructions are multi-byte. In general, a device with 4 Kbytes of program memory would allow approximately 2K of instructions. This 2:1 ratio is generalized and dependent on the application code. Since each instruction may take multiple bytes, there is no assurance that each location is a valid instruction. Program Memory Data Memory Program Memory and Data CPU CPU 8 16 8 Harvard von Neumann 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39504A-page 4-3 Section 4 Architecture Architechture 4 Double Word Instructions: Some operations require more information then can be stored in the 16 bits of a program memory location. These operations require a double word instruction, and are therefore 32-bits wide. Instructions that require this second instruction word are: • Memory to memory move instruction (12 bits for each RAM address) - MOVFF SourceReg, DestReg • Literal value to FSR move instruction (12 bits for data and 2 bits for FSR to load) - LFSR FSR#, Address • Call and goto operations (20 bits for address) - CALL Address - GOTO Address The first word indicates to the CPU that the next program memory location is the additional information for this instruction and not an instruction. If the CPU tries to execute the second word of an instruction (due to a software modified PC pointing to that location as an instruction), the fetched data is executed as a NOP. Double word instruction execution is not split between the two TCY cycles by an interrupt request. That is, when an interrupt request occurs during the execution of a double word instruction, the execution of the instruction is completed before the processor vectors to the interrupt address. The interrupt latency is preserved. Instruction Pipeline: The instruction pipeline is a two-stage pipeline that overlaps the fetch and execution of instructions. The fetch of the instruction takes one TCY, while the execution takes another TCY. However, due to the overlap of the fetch of current instruction and execution of previous instruction, an instruction is fetched and another instruction is executed every TCY. Single Cycle Instructions: With the program memory bus being 16-bits wide, the entire instruction is fetched in a single machine cycle (TCY), except for double word instructions. The instruction contains all the information required and is executed in a single cycle. There may be a one cycle delay in execution if the result of the instruction modified the contents of the program counter. This requires the pipeline to be flushed and a new instruction to be fetched. Two Cycle Instructions: Double word instructions require two cycles to execute, since all the required information is in the 32 bits. Reduced Instruction Set: When an instruction set is well designed and highly orthogonal (symmetric), fewer instructions are required to perform all needed tasks. With fewer instructions, the whole set can be more rapidly learned. Register File Architecture: The register files/data memory can be directly or indirectly addressed. All special function registers, including the program counter, are mapped in the data memory. Orthogonal (Symmetric) Instructions: Orthogonal instructions make it possible to carry out any operation on any register using any addressing mode. This symmetrical nature and lack of “special instructions” make programming simple yet efficient. In addition, the learning curve is reduced significantly. The Enhanced MCU instruction set uses only three non-register oriented instructions, which are used for two of the cores features. One is the SLEEP instruction, which places the device into the lowest power use mode. The second is the CLRWDT instruction, which verifies the chip is operating properly by preventing the on-chip Watchdog Timer (WDT) from overflowing and resetting the device. The third is the RESET instruction, which resets the device. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39504A-page 4-4  2000 Microchip Technology Inc. Figure 4-2: General Enhanced MCU Block Diagram Power-up Timer Oscillator Start-up Timer Power-on Reset Watchdog Timer Instruction Decode & Control OSC1/CLKIN OSC2/CLKOUT MCLR VDD, VSS PORTA PORTB PORTC RA4 RA5 RB0/INT0 RB<7:4> RC0 RC1 RC2 RC3 RC4 RC5 RC6 RC7 Brown-out Reset Note 1: Many of the general purpose I/O pins are multiplexed with one or more peripheral module functions. The multiplexing combinations are device dependent. RA3 RA2 RA1 RA0 Timing Generation 4X PLL RB1/INT1 Data Latch Data RAM (up to 4K address reach) Address Latch Address<12> 12 BSR FSR0 Bank0, F FSR1 FSR2 inc / dec Decode logic 4 12 4 PCH PCL PCLATH 8 31 Level Stack Program Counter PRODH PRODL 8 x 8 Multiply W 8 BITOP 8 8 ALU<8> 8 Address Latch Program Memory (up to 2M Bytes) Data Latch 20 21 21 16 8 8 8 Table Pointer<21> inc/dec logic 21 8 Data Bus<8> TABLELATCH 8 Instruction 12 3 ROMLATCH PORTD RB2/INT2 RB3 T1OSI T1OSO PCLATU PCU RA6 Precision Reference Bandgap Register 8 Addressable CCP’s Synchronous Timer0 Timer1 Timer2 Serial Port Timer3 A/D Converter Enhanced USART Master Other Peripherals RD0 RD1 RD2 RD3 RD4 RD5 RD6 RD7 PORTE RE0 RE1 RE2 RE3 RE4 RE5 RE6 RE7 Peripheral Modules (Note 1) CAN USB PORTx Rx0 Rx1 Rx2 Rx3 Rx4 Rx5 Rx6 Rx7 CCP’s 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39504A-page 4-5 Section 4 Architecture Architechture 4 4.2 Clocking Scheme/Instruction Cycle The clock input is internally divided by four to generate four non-overlapping quadrature clocks, namely Q1, Q2, Q3 and Q4. Internally, the program counter is incremented every Q1, and the instruction is fetched from the program memory and latched into the instruction register in Q4. The instruction is decoded and executed during the following Q1 through Q4. The clocks and instruction execution flow are illustrated in Figure 4-3 and Example 4-1. Figure 4-3: Clock/Instruction Cycle 4.2.1 Phase Lock Loop (PLL) The clock input is multiplied by four by the PLL. Therefore, when it is internally divided by four, it provides an instruction cycle that is the same frequency as the external clock frequency. Four non-overlapping quadrature clocks, namely Q1, Q2, Q3 and Q4 are still generated internally. Internally, the program counter (PC) is incremented every Q1, and the instruction is fetched from the program memory and latched into the instruction register in Q4. The instruction is decoded and executed during the following Q1 through Q4. The clocks and instruction execution flow are illustrated in Figure 4-4 and Example 4-1. Figure 4-4: Clock/Instruction Cycle with PLL Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Device Clock Q1 Q2 Q3 Q4 PC CLKOUT (RC mode) PC PC+2 PC+4 Fetch INST (PC) Execute INST (PC-2) Fetch INST (PC+2) Execute INST (PC) Fetch INST (PC+4) Execute INST (PC+2) Internal phase clock TCY1 TCY2 TCY3 (OSC1 or T1OSCI) Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 PLL Output Q1 Q2 Q3 Q4 PC OSC2/CLKOUT (RC mode) PC PC+2 PC+4 Fetch INST (PC) Execute INST (PC-2) Fetch INST (PC+2) Execute INST (PC) Fetch INST (PC+4) Execute INST (PC+2) Internal phase clock TCY1 TCY2 TCY3 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39504A-page 4-6  2000 Microchip Technology Inc. 4.3 Instruction Flow/Pipelining An “Instruction Cycle” consists of four Q cycles (Q1, Q2, Q3 and Q4). Fetch takes one instruction cycle, while decode and execute takes another instruction cycle. However, due to pipelining, each instruction effectively executes in one cycle. If an instruction causes the program counter to change (e.g. GOTO instruction), then an extra cycle is required to complete the instruction (See Example 4-1). The instruction fetch begins with the program counter incrementing in Q1. In the execution cycle, the fetched instruction is latched into the “Instruction Register (IR)” in cycle Q1. This instruction is then decoded and executed during the Q2, Q3 and Q4 cycles. Data memory is read during Q2 (operand read) and written during Q4 (destination write). Example 4-1 shows the operation of the two stage pipeline for the instruction sequence shown. At time TCY0, the first instruction is fetched from program memory. During TCY1, the first instruction executes, while the second instruction is fetched. During TCY2, the second instruction executes, while the third instruction is fetched. During TCY3, the fourth instruction is fetched, while the third instruction (CALL SUB_1) is executed. When the third instruction completes execution, the CPU forces the address of instruction four onto the Stack and then changes the Program Counter (PC) to the address of SUB_1. This means that the instruction that was fetched during TCY3 needs to be “flushed” from the pipeline. During TCY4, instruction four is flushed (executed as a NOP) and the instruction at address SUB_1 is fetched. Finally during TCY5, instruction five is executed and the instruction at address SUB_1 + 2 is fetched. Example 4-1: Instruction Pipeline Flow Most instructions are single cycle. Program branches take two cycles, since the fetch instruction is “flushed” from the pipeline while the new instruction is being fetched and then executed. TCY0 TCY1 TCY2 TCY3 TCY4 TCY5 1. MOVLW 55h Fetch 1 Execute 1 2. MOVWF PORTB Fetch 2 Execute 2 3. CALL SUB_1 Fetch 3 Execute 3 4. BSF PORTA, BIT3 (Forced NOP) Fetch 4 Flush 5. Instruction @ address SUB_1 Fetch SUB_1 Execute SUB_1 Fetch SUB_1 + 2 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39504A-page 4-7 Section 4 Architecture Architechture 4 4.4 I/O Descriptions Table 4-1 gives a brief description of device pins and the functions that may be multiplexed to a port pin. Multiple functions may exist on one port pin. When multiplexing occurs, the peripheral module’s functional requirements may force an override of the data direction (TRIS bit) of the port pin (such as in the A/D and Comparator modules). Table 4-1: I/O Descriptions Pin Name Pin Type Buffer Type Description A19 O — System bus address line 19 A18 O — System bus address line 18 A17 O — System bus address line 17 A16 O — System bus address line 16 AD15 I/O TTL System bus address/data line 15 AD14 I/O TTL System bus address/data line 14 AD13 I/O TTL System bus address/data line 13 AD12 I/O TTL System bus address/data line 12 AD11 I/O TTL System bus address/data line 11 AD10 I/O TTL System bus address/data line 10 AD9 I/O TTL System bus address/data line 9 AD8 I/O TTL System bus address/data line 8 AD7 I/O TTL System bus address/data line 7 AD6 I/O TTL System bus address/data line 6 AD5 I/O TTL System bus address/data line 5 AD4 I/O TTL System bus address/data line 4 AD3 I/O TTL System bus address/data line 3 AD2 I/O TTL System bus address/data line 2 AD1 I/O TTL System bus address/data line 1 AD0 I/O TTL System bus address/data line 0 ALE O — System bus address latch enable strobe Analog Input Channels AN0 I Analog AN1 I Analog AN2 I Analog AN3 I Analog AN4 I Analog AN5 I Analog AN6 I Analog AN7 I Analog AN8 I Analog AN9 I Analog AN10 I Analog AN11 I Analog AN12 I Analog AN13 I Analog AN14 I Analog AN15 I Analog AVDD P P Analog Power Legend: TTL = TTL-compatible input CMOS = CMOS compatible input or output ST = Schmitt Trigger input with CMOS levels O = output PU = Weak internal pull-up I = input Analog = Analog input or output P = Power 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39504A-page 4-8  2000 Microchip Technology Inc. AVSS P P Analog Ground BA0 O — System bus byte address 0 CANRX I ST CAN bus receive pin CANTX0 O — CAN bus transmit CANTX1 O — CAN bus complimentary transmit or CAN bus bit time clock CCP1 I/O ST Capture1 input/Compare1 output/PWM1 output CCP2 I/O ST Capture2 input/Compare2 output/PWM2 output. CK I/O ST USART Synchronous Clock, always associated with TX pin function (See related TX, RX, DT) CLKI I ST/CMOS External clock source input. Always associated with pin function OSC1. (See related OSC1/CLKIN, OSC2/CLKOUT pins) CLKO O — Oscillator crystal output. Connects to crystal or resonator in crystal oscillator mode. In RC mode, OSC2 pin outputs CLKOUT which has 1/4 the frequency of OSC1, and denotes the instruction cycle rate. Always associated with OSC2 pin function. (See related OSC2, OSC1) CMPA O — Comparator A output CMPB O — Comparator B output CS I TTL Chip select control for parallel slave port (See related RD and WR) CVREF O Analog Comparator voltage reference output DT I/O ST USART Synchronous Data. Always associated RX pin function. (See related RX, TX, CK) Table 4-1: I/O Descriptions (Continued) Pin Name Pin Type Buffer Type Description Legend: TTL = TTL-compatible input CMOS = CMOS compatible input or output ST = Schmitt Trigger input with CMOS levels O = output PU = Weak internal pull-up I = input Analog = Analog input or output P = Power 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39504A-page 4-9 Section 4 Architecture Architechture 4 INT0 I ST External Interrupt0 INT1 I ST External Interrupt1 INT2 I ST External Interrupt2 LB O — System bus low byte strobe LVDIN I Analog Low voltage detect input MCLR I/P ST Master clear (reset) input or programming voltage input. This pin is an active low reset to the device. NC — — These pins should be left unconnected. OE O — System bus output enable strobe OSC1 I ST/CMOS Oscillator crystal input or external clock source input. ST buffer when configured in RC mode. CMOS otherwise. OSC2 O — Oscillator crystal output. Connects to crystal or resonator in crystal oscillator mode. In RC mode, OSC2 pin outputs CLKOUT, which has 1/4 the frequency of OSC1, and denotes the instruction cycle rate. PSP0 I/O TTL Parallel Slave Port for interfacing to a microprocessor port. These PSP1 I/O TTL pins have TTL input buffers when PSP module is enabled. PSP2 I/O TTL PSP3 I/O TTL PSP4 I/O TTL PSP5 I/O TTL PSP6 I/O TTL PSP7 I/O TTL PORTA is a bi-directional I/O port. RA0 I/O TTL RA1 I/O TTL RA2 I/O TTL RA3 I/O TTL RA4 I/O ST RA4 is an open drain when configured as output. RA5 I/O TTL RA6 I/O TTL PORTB is a bi-directional I/O port. PORTB can be software programmed for internal weak pull-ups on all inputs. RB0 I/O TTL RB1 I/O TTL RB2 I/O TTL RB3 I/O TTL RB4 I/O TTL Interrupt on change pin. RB5 I/O TTL Interrupt on change pin. RB6 I/O TTL/ST Interrupt on change pin. Serial programming clock. TTL input buffer as general purpose I/O, Schmitt Trigger input buffer when used as the serial programming clock. RB7 I/O TTL/ST Interrupt on change pin. Serial programming data. TTL input buffer as general purpose I/O, Schmitt Trigger input buffer when used as the serial programming data. Table 4-1: I/O Descriptions (Continued) Pin Name Pin Type Buffer Type Description Legend: TTL = TTL-compatible input CMOS = CMOS compatible input or output ST = Schmitt Trigger input with CMOS levels O = output PU = Weak internal pull-up I = input Analog = Analog input or output P = Power 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39504A-page 4-10  2000 Microchip Technology Inc. PORTC is a bi-directional I/O port. RC0 I/O ST RC1 I/O ST RC2 I/O ST RC3 I/O ST RC4 I/O ST RC5 I/O ST RC6 I/O ST RC7 I/O ST RD I TTL Read control for parallel slave port. (See also WR and CS pins.) PORTD is a bi-directional I/O port. RD0 I/O ST RD1 I/O ST RD2 I/O ST RD3 I/O ST RD4 I/O ST RD5 I/O ST RD6 I/O ST RD7 I/O ST PORTE is a bi-directional I/O port. RE0 I/O ST RE1 I/O ST RE2 I/O ST RE3 I/O ST RE4 I/O ST RE5 I/O ST RE6 I/O ST RE7 I/O ST PORTF is a digital input RF0 I/O ST RF1 I/O ST RF2 I/O ST RF3 I/O ST RF4 I/O ST RF5 I/O ST RF6 I/O ST RF7 I/O ST Table 4-1: I/O Descriptions (Continued) Pin Name Pin Type Buffer Type Description Legend: TTL = TTL-compatible input CMOS = CMOS compatible input or output ST = Schmitt Trigger input with CMOS levels O = output PU = Weak internal pull-up I = input Analog = Analog input or output P = Power 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39504A-page 4-11 Section 4 Architecture Architechture 4 PORTG is a digital input RG0 I/O ST RG1 I/O ST RG2 I/O ST RG3 I/O ST RG4 I/O ST RG5 I/O ST RG6 I/O ST RG7 I/O ST PORTH is a digital input RH0 I/O ST RH1 I/O ST RH2 I/O ST RH3 I/O ST RH4 I/O ST RH5 I/O ST RH6 I/O ST RH7 I/O ST PORTJ is a digital input RJ0 I/O ST RJ1 I/O ST RJ2 I/O ST RJ3 I/O ST RJ4 I/O ST RJ5 I/O ST RJ6 I/O ST RJ7 I/O ST PORTK is a digital input RK0 I/O ST RK1 I/O ST RK2 I/O ST RK3 I/O ST RK4 I/O ST RK5 I/O ST RK6 I/O ST RK7 I/O ST Table 4-1: I/O Descriptions (Continued) Pin Name Pin Type Buffer Type Description Legend: TTL = TTL-compatible input CMOS = CMOS compatible input or output ST = Schmitt Trigger input with CMOS levels O = output PU = Weak internal pull-up I = input Analog = Analog input or output P = Power 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39504A-page 4-12  2000 Microchip Technology Inc. PORTL is a digital input RL0 I/O ST RL1 I/O ST RL2 I/O ST RL3 I/O ST RL4 I/O ST RL5 I/O ST RL6 I/O ST RL7 I/O ST RX I ST USART Asynchronous Receive SCL I/O ST Synchronous serial clock input/output for I2C mode. SCLA I/O ST Synchronous serial clock for I2C interface. SCLB I/O ST Synchronous serial clock for I2C interface. SDA I/O ST I2C™ Data I/O SDAA I/O ST Synchronous serial data I/O for I2C interface SDAB I/O ST Synchronous serial data I/O for I2C interface SCK I/O ST Synchronous serial clock input/output for SPI mode. SDI I ST SPI Data In SDO O — SPI Data Out (SPI mode) SS I ST SPI Slave Select input T0CKI I ST Timer0 external clock input T1CKI I ST Timer1 external clock input T1OSO O CMOS Timer1 oscillator output T1OSI I CMOS Timer1 oscillator input TX O — USART Asynchronous Transmit (See related RX) UB O — System bus upper byte strobe Table 4-1: I/O Descriptions (Continued) Pin Name Pin Type Buffer Type Description Legend: TTL = TTL-compatible input CMOS = CMOS compatible input or output ST = Schmitt Trigger input with CMOS levels O = output PU = Weak internal pull-up I = input Analog = Analog input or output P = Power 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39504A-page 4-13 Section 4 Architecture Architechture 4 VREF I Analog Analog High Voltage Reference input. DR reference voltage output on devices with comparators. VREF+ I Analog Analog High Voltage Reference input. Usually multiplexed onto an analog pin. VREF- I Analog Analog Low Voltage Reference input. Usually multiplexed onto an analog pin. VSS P — Ground reference for logic and I/O pins. VDD P — Positive supply for logic and I/O pins. VPP P — Programming voltage input WR I TTL Write control for parallel slave port (See CS and RD pins also). WRL O — System bus write low byte strobe WRH O — System bus write high byte strobe Table 4-1: I/O Descriptions (Continued) Pin Name Pin Type Buffer Type Description Legend: TTL = TTL-compatible input CMOS = CMOS compatible input or output ST = Schmitt Trigger input with CMOS levels O = output PU = Weak internal pull-up I = input Analog = Analog input or output P = Power 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39504A-page 4-14  2000 Microchip Technology Inc. 4.5 Design Tips No related design tips at this time. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39504A-page 4-15 Section 4 Architecture Architechture 4 4.6 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range, or High-End families), but the concepts are pertinent and could be used (with modification and possible limitations). The current application notes related to Architecture are: Title Application Note # No related application notes at this time. Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39504A-page 4-16  2000 Microchip Technology Inc. 4.7 Revision History Revision A This is the initial released revision of the Enhanced MCU Architecture description. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39505A-page 5-1 CPU and ALU 5 Section 5. CPU and ALU HIGHLIGHTS This section of the manual contains the following major topics: 5.1 Introduction .................................................................................................................... 5-2 5.2 General Instruction Format ............................................................................................ 5-6 5.3 Central Processing Unit (CPU) ...................................................................................... 5-7 5.4 Instruction Clock ............................................................................................................ 5-8 5.5 Arithmetic Logical Unit (ALU)......................................................................................... 5-9 5.6 STATUS Register ......................................................................................................... 5-11 5.7 Design Tips.................................................................................................................. 5-14 5.8 Related Application Notes............................................................................................ 5-15 5.9 Revision History........................................................................................................... 5-16 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39505A-page 5-2  2000 Microchip Technology Inc. 5.1 Introduction The Central Processing Unit (CPU) is responsible for using the information in the program memory (instructions) to control the operation of the device. Many of these instructions operate on data memory. To operate on data memory, the Arithmetic Logical Unit (ALU) is required. In addition to performing arithmetical and logical operations, the ALU controls the state of the status bits, which are found in the STATUS register. The result of some instructions force status bits to a value depending on the state of the result. The machine codes that the CPU recognizes are shown in Table 5-1, as well as the instruction mnemonics that the MPASM uses to generate these codes. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39505A-page 5-3 Section 5. CPU and ALU CPU and ALU 5 Table 5-1: PIC18CXXX Instruction Set Mnemonic, Operands Description Cycles (4) 16-Bit Instruction Word Status Affected Notes MSb LSb BYTE-ORIENTED FILE REGISTER OPERATIONS ADDWF ADDWFC ANDWF CLRF COMF CPFSEQ CPFSGT CPFSLT DECF DECFSZ DCFSNZ INCF INCFSZ INFSNZ IORWF MOVF MOVFF MOVWF MULWF NEGF RLCF RLNCF RRCF RRNCF SETF SUBFWB SUBWF SUBWFB SWAPF TSTFSZ XORWF f, d, a f, d, a f, d, a f, a f, d, a f, a f, a f, a f, d, a f, d, a f, d, a f, d, a f, d, a f, d, a f, d, a f, d, a fs, fd f, a f, a f, a f, d, a f, d, a f, d, a f, d, a f, a f, d, a f, d, a f, d, a f, d, a f, a f, d, a Add WREG and f Add WREG and Carry bit to f AND WREG with f Clear f Complement f Compare f with WREG, skip = Compare f with WREG, skip > Compare f with WREG, skip < Decrement f Decrement f, Skip if 0 Decrement f, Skip if Not 0 Increment f Increment f, Skip if 0 Increment f, Skip if Not 0 Inclusive OR WREG with f Move f Move fs (source) to fd (destination) Move WREG to f Multiply WREG with f Negate f Rotate Left f through Carry Rotate Left f (No Carry) Rotate Right f through Carry Rotate Right f (No Carry) Set f Subtract f from WREG with Subtract WREG from f Subtract WREG from f with Swap nibbles in f Test f, skip if 0 Exclusive OR WREG with f 1 1 1 1 1 1 (2 or 3) 1 (2 or 3) 1 (2 or 3) 1 1 (2 or 3) 1 (2 or 3) 1 1 (2 or 3) 1 (2 or 3) 1 1 2 1 1 1 1 1 1 1 1 1 1 1 1 1 (2 or 3) 1 0010 0010 0001 0110 0001 0110 0110 0110 0000 0010 0100 0010 0011 0100 0001 0101 1100 1111 0110 0000 0110 0011 0100 0011 0100 0110 0101 0101 0101 0011 0110 0001 01da 00da 101a 11da 11da 001a 010a 000a 01da 11da 11da 10da 11da 10da 00da 00da ffff ffff 111a 001a 110a 01da 01da 00da 00da 100a 01da 11da 10da 10da 011a 10da ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff C, DC, Z, OV, N C, DC, Z, OV, N Z, N Z, N Z, N None None None C, DC, Z, OV, N None None C, DC, Z, OV, N None None Z Z None None None C, DC, Z, OV, N C, DC, Z, N C, DC, Z, N C, DC, Z, N C, DC, Z, N None C, DC, Z, OV, N C, DC, Z, OV, N C, DC, Z, OV, N None None Z, N 1, 2 1, 2 1,2 2 1, 2 4 4 1, 2 1, 2, 3, 4 1, 2, 3, 4 1, 2 1, 2, 3, 4 4 1, 2 1, 2 1, 2 1, 2 1, 2 1, 2 4 1, 2 BIT-ORIENTED FILE REGISTER OPERATIONS BCF BSF BTFSC BTFSS BTG f, b, a f, b, a f, b, a f, b, a f, d, a Bit Clear f Bit Set f Bit Test f, Skip if Clear Bit Test f, Skip if Set Bit Toggle f 1 1 1 (2 or 3) 1 (2 or 3) 1 1001 1000 1011 1010 0111 bbba bbba bbba bbba bbba ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff None None None None None 1, 2 1, 2 3, 4 3, 4 1, 2 Note 1: When an I/O register is modified as a function of itself (e.g., MOVF PORTB, 1, 0), the value used will be that value present on the pins themselves. For example, if the data latch is '1' for a pin configured as input and is driven low by an external device, the data will be written back with a '0'. 2: If this instruction is executed on the TMR0 register (and, where applicable, d = 1), the prescaler will be cleared if assigned to the Timer0 Module. 3: If Program Counter (PC) is modified or a conditional test is true, the instruction requires two cycles. The second cycle is executed as a NOP. 4: Some instructions are 2 word instructions. The second word of these instructions will be executed as a NOP, unless the first word retrieves the information embedded in these 16 bits. This ensures that all program memory locations have a valid instruction. 5: If the Table Write starts the write cycle to internal memory, the write will continue until terminated. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39505A-page 5-4  2000 Microchip Technology Inc. CONTROL OPERATIONS BC BN BNC BNN BNOV BNZ BOV BRA BZ CALL CLRWDT DAW GOTO NOP NOP POP PUSH RCALL RESET RETFIE RETLW RETURN SLEEP TBLRD TBLWT n n n n n n n n n n, s — — n — — — — n s k s — m m Branch if Carry Branch if Negative Branch if Not Carry Branch if Not Negative Branch if Not Overflow Branch if Not Zero Branch if Overflow Branch Unconditionally Branch if Zero Call subroutine 1st word 2nd word Clear Watchdog Timer Decimal Adjust WREG Go to address 1st word 2nd word No Operation No Operation (4) Pop top of return stack (TOS) Push top of return stack (TOS) Relative Call Software device RESET Return from interrupt enable Return with literal in WREG Return from Subroutine Go into standby mode Table Read * → mm = 00 *+ → mm = 01 *- → mm = 10 +* → mm = 11 Table Write * → mm = 00 *+ → mm = 01 *- → mm = 10 +* → mm = 11 1 (2) 1 (2) 1 (2) 1 (2) 1 (2) 2 1 (2) 1 (2) 1 (2) 2 1 1 2 1 1 1 1 2 1 2 2 2 1 2 2 1110 1110 1110 1110 1110 1110 1110 1101 1110 1110 1111 0000 0000 1110 1111 0000 1111 0000 0000 1101 0000 0000 0000 0000 0000 0000 0000 0010 0110 0011 0111 0101 0001 0100 0nnn 0000 110s kkkk 0000 0000 1111 kkkk 0000 xxxx 0000 0000 1nnn 0000 0000 1100 0000 0000 0000 0000 nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn kkkk kkkk 0000 0000 kkkk kkkk 0000 xxxx 0000 0000 nnnn 1111 0001 kkkk 0001 0000 0000 0000 nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn kkkk kkkk 0100 0111 kkkk kkkk 0000 xxxx 0110 0101 nnnn 1111 000s kkkk 001s 0011 10mm 11mm None None None None None None None None None None TO, PD C None None None None None None All GIEH, GIEL None None TO, PD None None 5 Table 5-1: PIC18CXXX Instruction Set (Continued) Mnemonic, Operands Description Cycles (4) 16-Bit Instruction Word Status Affected Notes MSb LSb Note 1: When an I/O register is modified as a function of itself (e.g., MOVF PORTB, 1, 0), the value used will be that value present on the pins themselves. For example, if the data latch is '1' for a pin configured as input and is driven low by an external device, the data will be written back with a '0'. 2: If this instruction is executed on the TMR0 register (and, where applicable, d = 1), the prescaler will be cleared if assigned to the Timer0 Module. 3: If Program Counter (PC) is modified or a conditional test is true, the instruction requires two cycles. The second cycle is executed as a NOP. 4: Some instructions are 2 word instructions. The second word of these instructions will be executed as a NOP, unless the first word retrieves the information embedded in these 16 bits. This ensures that all program memory locations have a valid instruction. 5: If the Table Write starts the write cycle to internal memory, the write will continue until terminated. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39505A-page 5-5 Section 5. CPU and ALU CPU and ALU 5 LITERAL OPERATIONS ADDLW ANDLW IORLW MOVLB LFSR MOVLW MULLW RETLW SUBLW XORLW k k k k f, k k k k k k Add literal and WREG AND literal with WREG Inclusive OR literal with WREG Move literal to BSR<3:0> Move literal (12-bit) to FSRx 2nd word Move literal to WREG Multiply literal with WREG Return with literal in WREG Subtract WREG from literal Exclusive OR literal with WREG 1 1 1 1 2 1 1 2 1 1 0000 0000 0000 0000 1110 1111 0000 0000 0000 0000 0000 1111 1011 1001 0001 1110 0000 1110 1101 1100 1000 1010 kkkk kkkk kkkk 0000 00ff kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk C, DC, Z, OV, N Z, N Z, N None None None None None C, DC, Z, OV, N Z, N Table 5-1: PIC18CXXX Instruction Set (Continued) Mnemonic, Operands Description Cycles (4) 16-Bit Instruction Word Status Affected Notes MSb LSb Note 1: When an I/O register is modified as a function of itself (e.g., MOVF PORTB, 1, 0), the value used will be that value present on the pins themselves. For example, if the data latch is '1' for a pin configured as input and is driven low by an external device, the data will be written back with a '0'. 2: If this instruction is executed on the TMR0 register (and, where applicable, d = 1), the prescaler will be cleared if assigned to the Timer0 Module. 3: If Program Counter (PC) is modified or a conditional test is true, the instruction requires two cycles. The second cycle is executed as a NOP. 4: Some instructions are 2 word instructions. The second word of these instructions will be executed as a NOP, unless the first word retrieves the information embedded in these 16 bits. This ensures that all program memory locations have a valid instruction. 5: If the Table Write starts the write cycle to internal memory, the write will continue until terminated. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39505A-page 5-6  2000 Microchip Technology Inc. 5.2 General Instruction Format The Enhanced family instructions can be broken down into five general formats as shown in Figure 5-1. As can be seen, the opcode for the instruction varies from 4 bits to 8 bits. This variable opcode size is what allows 77 instructions to be implemented. Figure 5-1: General Format for Instructions Byte-oriented file register operations 15 10 9 8 7 0 d = 0 for result destination to be WREG register OPCODE d a f (FILE #) d = 1 for result destination to be file register (f) a = 0 to force Access Bank Bit-oriented file register operations 15 12 11 9 8 7 0 OPCODE b (BIT #) a f (FILE #) b = 3-bit position of bit in file register (f) Literal operations 15 8 7 0 OPCODE k (literal) k = 8-bit immediate value Byte to Byte move operations (2-word) 15 12 11 0 OPCODE f (Source FILE #) CALL, GOTO and Branch operations 15 8 7 0 OPCODE n<7:0> (literal) n = 20-bit immediate value a = 1 for BSR to select bank f = 8-bit file register address a = 0 to force Access Bank a = 1 for BSR to select bank f = 8-bit file register address 15 12 11 0 1111 n<19:8> (literal) 15 12 11 0 1111 f (Destination FILE #) f = 12-bit file register address Control operations Example Instruction ADDWF MYREG, W, a MOVFF MYREG1, MYREG2 BSF MYREG, bit, a MOVLW 0x7F GOTO Label 15 8 7 0 OPCODE n<7:0> (literal) 15 12 11 0 CALL MYFUNC 15 11 10 0 OPCODE n<10:0> (literal) S = Fast bit BRA MYFUNC 15 8 7 0 OPCODE n<7:0> (literal) BC MYFUNC S 1111 n<19:8> (literal) 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39505A-page 5-7 Section 5. CPU and ALU CPU and ALU 5 5.3 Central Processing Unit (CPU) The CPU can be thought of as the “brains” of the device. It is responsible for fetching the correct instruction for execution, decoding that instruction and then executing that instruction. The CPU sometimes works in conjunction with the ALU to complete the execution of the instruction (in arithmetic and logical operations). The CPU controls the program memory address bus, the data memory address bus and accesses to the stack. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39505A-page 5-8  2000 Microchip Technology Inc. 5.4 Instruction Clock There are three oscillator clock sources from which the device can operate. These are 1. External System Clock (TOSC) 2. Phase Lock Loop (PLL) 3. Timer1 Oscillator (TT1P) Figure 5-2 shows these clock inputs and the device clock output (TSCLK). TSCLK is the system clock. Four TSCLK cycles are an instruction cycle (TCY). The external system clock (TOSC) goes into the device and is input into a multiplexer anda4x Phase Lock Loop (PLL). The output of the PLL also enters the multiplexer and has a name TOSC/4. Some devices may also have an alternate oscillator called Timer1 oscillator (see “Timer1” section), which can provide another system clock. Timer1 has a cycle time called TT1P. This clock source also enters into the multiplexer. Figure 5-2: Device Clock Sources Each instruction cycle (TCY) is comprised of four Q cycles (Q1-Q4). The Q cycle time is the same as the system clock cycle time (TSCLK). The Q cycles provide the timing/designation for the Decode, Read, Process Data, Write, etc., of each instruction cycle. The four Q cycles that make up an instruction cycle (TCY) are shown in Figure 5-3. The relationship of the Q cycles to the instruction cycle can be generalized as: Q1: Instruction Decode Cycle or forced No Operation (NOP) Q2: Instruction Read Data Cycle or No Operation (NOP) Q3: Process the Data Q4: Instruction Write Data Cycle or No Operation (NOP) Each instruction description will show a detailed Q cycle operation for the instruction. Figure 5-3: Q Cycle Activity PIC18CXXX OSC1 PLL TSCLK Clock Source MUX TOSC/4 T1OSI TOSC TT1P Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 TCY1 TCY2 TCY3 TDOSC 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39505A-page 5-9 Section 5. CPU and ALU CPU and ALU 5 5.5 Arithmetic Logical Unit (ALU) PICmicro devices contain an 8-bit ALU and an 8-bit working register (WREG). The ALU is a general purpose arithmetic and logical unit. It performs arithmetic and Boolean functions between the data in the working register and any register file. The WREG register is directly addressable and in the SFR memory map. Figure 5-4: Operation of the ALU and WREG Register The ALU is 8-bits wide and is capable of addition, subtraction, multiplication, shift and logical operations. Unless otherwise mentioned, arithmetic operations are two's complement in nature. In two-operand instructions, typically one operand is the working register (WREG register). The other operand is a file register or an immediate constant. In single operand instructions, the operand is either the WREG register or a file register. The 8x8 multiplier operates in a single cycle, placing the 16-bit result in the PRODH:PRODL register pair. Depending on the instruction executed, the ALU may affect the values of the Carry (C), Digit Carry (DC), Zero (Z), Overflow (OV), and Negative (N) bits in the STATUS register. The C and DC bits operate as a borrow bit and a digitborrow out bit, respectively, in subtraction. See the SUBLW and SUBWF instructions in the “Instruction Set” section for examples. WREG Register Register File 8 d bit, or from instruction 8 8 8-bit literal (from instruction word) (SFR’s) and General Purpose RAM ALU (GPR) 8 8 Special Function Registers 8-bit register value (from direct or indirect address of instruction) STATUS Register C bit N, OV, Z, DC, and C bits 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39505A-page 5-10  2000 Microchip Technology Inc. 5.5.1 Signed Math Signed arithmetic is comprised of a magnitude and a sign bit. The overflow bit indicates if the magnitude overflows and causes the sign bit to change state when the result of an 8-bit signed operation is greater than 127 (7Fh) or less than -128 (80h). Signed math can have greater than 7-bit values (magnitude), if more than one byte is used. The overflow bit only operates on bit6 (MSb of magnitude) and bit7 (sign bit) of each byte value in the ALU. That is, the overflow bit is not useful if trying to implement signed math where the magnitude, for example, is 11 bits. If the signed math values are greater than 7 bits (such as 15, 24 or 31 bits), the algorithm must ensure that the low order bytes of the signed value ignore the overflow status bit. Example 5-1 shows two cases of doing signed arithmetic. The Carry (C) bit and the Overflow (OV) bit are the most important status bits for signed math operations. Example 5-1: 8-bit Math Addition Case 1: The Negative bit is used to indicate if the MSb of the result is set or cleared. Hex Value Signed Values Unsigned Values FFh + 01h = 00h C bit = 1 OV bit = 0 DC bit = 1 Z bit = 1 N bit = 0 -1 + 1 = 0 (FEh) C bit = 1 OV bit = 0 DC bit = 1 Z bit = 1 N bit = 0 255 + 1 = 256 → 00h C bit = 1 OV bit = 0 DC bit = 1 Z bit = 1 N bit = 0 Case 2: Hex Value Signed Values Unsigned Values 7Fh + 01h = 80h C bit = 0 OV bit = 1 DC bit = 1 Z bit = 0 N bit = 1 127 + 1 = 128 → 00h C bit = 0 OV bit = 1 DC bit = 1 Z bit = 0 N bit = 1 127 + 1 = 128 C bit = 0 OV bit = 1 DC bit = 1 Z bit = 0 N bit = 1 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39505A-page 5-11 Section 5. CPU and ALU CPU and ALU 5 5.6 STATUS Register The STATUS register, shown in Register 5-1, contains the arithmetic status of the ALU. The STATUS register can be the destination for any instruction, as with any other register. If the STATUS register is the destination for an instruction that affects the Z, DC, C, OV or N bits, then the write to these five bits is disabled. These bits are set or cleared according to the device logic. Therefore, the result of an instruction with the STATUS register as destination may be different than intended. For example, CLRF STATUS will clear the upper three bits and set the Z bit. This leaves the STATUS register as 000u u1uu (where u = unchanged). It is recommended, therefore, that only BCF, BSF, SWAPF, MOVFF, and MOVWF instructions are used to alter the STATUS register, because these instructions do not affect the Z, C, DC, OV or N bits of the STATUS register. For other instructions, not affecting any status bits, see Table 5-1. Note 1: The C and DC bits operate as a borrow and digitborrow bit, respectively, in subtraction. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39505A-page 5-12  2000 Microchip Technology Inc. Register 5-1: STATUS Register U-0 U-0 U-0 R/W-x R/W-x R/W-x R/W-x R/W-x — — — N OV Z DC C bit 7 bit 0 bit 7-5 Unimplemented: Read as '0' bit 4 N: Negative bit This bit is used for signed arithmetic (2’s complement). It indicates whether the result was negative, (ALU MSb = 1). 1 = Result was negative 0 = Result was positive bit 3 OV: Overflow bit This bit is used for signed arithmetic (2’s complement). It indicates an overflow of the 7-bit magnitude, which causes the sign bit (bit7) to change state. 1 = Overflow occurred for signed arithmetic (in this arithmetic operation) 0 = No overflow occurred bit 2 Z: Zero bit 1 = The result of an arithmetic or logic operation is zero 0 = The result of an arithmetic or logic operation is not zero bit 1 DC: Digit carry/borrow bit For ADDWF, ADDLW, SUBLW, and SUBWF instructions 1 = A carry-out from the 4th low order bit of the result occurred 0 = No carry-out from the 4th low order bit of the result Note: For borrow, the polarity is reversed. A subtraction is executed by adding the 2’s complement of the second operand. For rotate (RRF, RLF) instructions, this bit is loaded with either the bit4 or bit3 of the source register. bit 0 C: Carry/borrow bit For ADDWF, ADDLW, SUBLW, and SUBWF instructions 1 = A carry-out from the most significant bit of the result occurred 0 = No carry-out from the most significant bit of the result occurred Note: For borrow, the polarity is reversed. A subtraction is executed by adding the 2’s complement of the second operand. For rotate (RRF, RLF) instructions, this bit is loaded with either the high or low order bit of the source register. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39505A-page 5-13 Section 5. CPU and ALU CPU and ALU 5 5.6.1 RCON Register The Reset Control (RCON) register contains flag bit(s) that allow the user to differentiate between the device resets. Register 5-2: RCON Register Note 1: If the BOREN configuration bit is set, BOR is ’0’ on Power-on Reset. If the BOREN configuration bit is clear, BOR is unknown on Power-on Reset. The BOR status bit is a "don't care" and is not necessarily predictable if the brown-out circuit is disabled (the BOREN configuration bit is clear). 2: It is recommended that the POR bit be set after a Power-on Reset has been detected, so that subsequent Power-on Resets may be detected. R/W-0 R/W-0 U-0 R/W-1 R/W-1 R/W-1 R/W-0 R/W-0 IPEN LWRT — RI TO PD POR BOR bit 7 bit 0 bit 7 IPEN: Interrupt Priority Enable bit This bit reflects the value of the MPEEN configuration bit. 1 = Enable priority levels on interrupts 0 = Disable priority levels on interrupts (PIC16CXXX compatibility mode) bit 6 LWRT: Long Write Enable 1 = Enable Table Writes to internal program memory Once this bit is set, it can only be cleared by a POR or MCLR reset. 0 = Disable Table Writes to internal program memory; Table Writes only to external program memory bit 5 Unimplemented: Read as '0' bit 4 RI: Reset Instruction Flag bit 1 = The Reset instruction was not executed to cause the device reset 0 = The Reset instruction was executed (must be set in software after a Brown-out Reset occurs) bit 3 TO: Watchdog Time-out Flag bit 1 = After Power-up, CLRWDT instruction, or SLEEP instruction 0 = A WDT time-out occurred bit 2 PD: Power-down Detection Flag bit 1 = After Power-up or by the CLRWDT instruction 0 = By execution of the SLEEP instruction bit 1 POR: Power-on Reset Status bit 1 = A Power-on Reset has not occurred 0 = A Power-on Reset occurred (After a Power-on Reset occurs, this bit must be set in software to detect subsequent occurrences of Power-on Reset. bit 0 BOR: Brown-out Reset Status bit 1 = A Brown-out Reset has not occurred 0 = A Brown-out Reset occurred (must be set in software after a Brown-out Reset occurs) Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39505A-page 5-14  2000 Microchip Technology Inc. 5.7 Design Tips Question 1: My program algorithm does not seem to function correctly. Answer 1: There are many possible reasons for this. A couple of possibilities are: 1. The destination of the instruction may be specifying the WREG register (d = 0) instead of the file register (d = 1). 2. The access bit may be specifying the Virtual RAM Bank instead of the desired bank of RAM. When possible, the use of an In-Circuit Emulator (such as MPLAB-ICE) or a simulator (such as MPLAB-SIM) can assist in locating the reason for the unexpected execution flow. Question 2: I cannot seem to modify the STATUS register flags. Answer 2: If the STATUS register is the destination for an instruction that affects the Z, DC, C, OV or N bits, then the write to those bits is disabled. These bits are set or cleared based on device logic. Therefore, to modify bits in the STATUS register, it is recommended to use the BCF and BSF instructions. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39505A-page 5-15 Section 5. CPU and ALU CPU and ALU 5 5.8 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Base-Line, the Mid-Range or High-End families), but the concepts are pertinent and could be used (with modification and possible limitations). The current application notes related to the CPU or the ALU are: Title Application Note # IEEE 754 Compliant Floating Point Routines AN575 Fixed Point Routines AN617 Floating Point Math Functions AN660 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39505A-page 5-16  2000 Microchip Technology Inc. 5.9 Revision History Revision A This is the initial released revision of the Enhanced MCU CPU and ALU description. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39506-page 6-1 Hardware 8x8 Multiplier 6 Section 6. Hardware 8x8 Multiplier HIGHLIGHTS This section of the manual contains the following major topics: 6.1 Introduction .................................................................................................................... 6-2 6.2 Operation ....................................................................................................................... 6-3 6.3 Design Tips .................................................................................................................... 6-6 6.4 Related Application Notes.............................................................................................. 6-7 6.5 Revision History ............................................................................................................. 6-8 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39506-page 6-2  2000 Microchip Technology Inc. 6.1 Introduction An 8 x 8 hardware multiplier is included in the ALU of the devices. By making the multiplication a hardware operation, it completes in a single instruction cycle. This is an unsigned multiplication that gives a 16-bit result. The result is stored into the 16-bit Product register (PRODH:PRODL). The multiplier does not affect any flags in the ALUSTA register. Making the 8 x 8 multiplier execute in a single cycle gives the following advantages: • Higher computational throughput • Reduces code size requirements for multiplication algorithms The performance increase allows the device to be used in applications previously reserved for Digital Signal Processors. Table 6-1 shows a performance comparison between devices using the single cycle hardware multiplier and performing the same function without the hardware multiplier. Table 6-1: Performance Comparison Routine Multiply Method Program Memory (Words) Cycles (Max) Time @ 40 MHz @ 10 MHz @ 4 MHz 8 x 8 unsigned Without hardware multiplier 13 69 6.9 µs 27.6 µs 69 µs Hardware multiply 1 1 100 ns 400 ns 1 µs 8 x 8 signed Without hardware multiplier 33 91 9.1 µs 36.4 µs 91 µs Hardware multiply 6 6 600 ns 2.4 µs 6 µs 16 x 16 unsigned Without hardware multiplier 21 242 24.2 µs 96.8 µs 242 µs Hardware multiply 24 24 2.4 µs 9.6 µs 24 µs 16 x 16 signed Without hardware multiplier 52 254 25.4 µs 102.6 µs 254 µs Hardware multiply 36 36 3.6 µs 14.4 µs 36 µs 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39506-page 6-3 Section 6. Hardware 8x8 Multiplier Hardware 8x8 Multiplier 6 6.2 Operation Example 6-1 shows the sequence to do an 8 x 8 unsigned multiply. Only one instruction is required when one argument of the multiply is already loaded in the WREG register. Example 6-2 shows the sequence to do an 8 x 8 signed multiply. To account for the sign bits of the arguments, each argument’s most significant bit (MSb) is tested and the appropriate subtractions are done. Example 6-1: 8 x 8 Unsigned Multiply Routine Example 6-2: 8 x 8 Signed Multiply Routine Example 6-3 shows the sequence to do a 16 x 16 unsigned multiply. Equation 6-1 shows the algorithm that is used. The 32-bit result is stored in four registers, RES3, RES2, RES1 and RES0. Equation 6-1: 16 x 16 Unsigned Multiplication Algorithm MOVFF ARG1, WREG ; MULWF ARG2 ; ARG1 * ARG2 -> ; PRODH:PRODL MOVFF ARG1, WREG MULWF ARG2 ; ARG1 * ARG2 -> ; PRODH:PRODL BTFSC ARG2, SB ; Test Sign Bit SUBWF PRODH, F ; PRODH = PRODH ; - ARG1 MOVFF ARG2, WREG BTFSC ARG1, SB ; Test Sign Bit SUBWF PRODH, F ; PRODH = PRODH ; - ARG2 RES3:RES2:RES1:RES0 = ARG1H:ARG1L • ARG2H:ARG2L = (ARG1H • ARG2H • 2 16)+ (ARG1H • ARG2L • 2 8)+ (ARG1L • ARG2H • 2 8)+ (ARG1L • ARG2L) 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39506-page 6-4  2000 Microchip Technology Inc. Example 6-3: 16 x 16 Unsigned Multiply Routine Example 6-4 shows the sequence to do a 16 x 16 signed multiply. Equation 6-2 shows the algorithm used. The 32-bit result is stored in four registers, RES3, RES2, RES1 and RES0. To account for the sign bits of the arguments, each argument pairs’ most significant bit (MSb) is tested and the appropriate subtractions are done. Equation 6-2: 16 x 16 Signed Multiplication Algorithm MOVFF ARG1L, WREG MULWF ARG2L ; ARG1L * ARG2L -> ; PRODH:PRODL MOVFF PRODH, RES1 ; MOVFF PRODL, RES0 ; ; MOVFF ARG1H, WREG MULWF ARG2H ; ARG1H * ARG2H -> ; PRODH:PRODL MOVFF PRODH, RES3 ; MOVFF PRODL, RES2 ; ; MOVFF ARG1L, WREG MULWF ARG2H ; ARG1L * ARG2H -> ; PRODH:PRODL MOVFF PRODL, WREG ; ADDWF RES1, F ; Add cross MOVFF PRODH, WREG ; products ADDWFC RES2, F ; CLRF WREG, F ; ADDWFC RES3, F ; ; MOVFF ARG1H, WREG ; MULWF ARG2L ; ARG1H * ARG2L -> ; PRODH:PRODL MOVFF PRODL, WREG ; ADDWF RES1, F ; Add cross MOVFF PRODH, WREG ; products ADDWFC RES2, F ; CLRF WREG, F ; ADDWFC RES3, F ; RES3:RES2:RES1:RES0 = ARG1H:ARG1L • ARG2H:ARG2L = (ARG1H • ARG2H • 2 16) + (ARG1H • ARG2L • 2 8) + (ARG1L • ARG2H • 2 8) + (ARG1L • ARG2L) + (-1 • ARG2H<7> • ARG1H:ARG1L • 2 16)+ (-1 • ARG1H<7> • ARG2H:ARG2L • 2 16) 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39506-page 6-5 Section 6. Hardware 8x8 Multiplier Hardware 8x8 Multiplier 6 Example 6-4: 16 x 16 Signed Multiply Routine MOVFF ARG1L, WREG MULWF ARG2L ; ARG1L * ARG2L -> ; PRODH:PRODL MOVFF PRODH, RES1 ; MOVFF PRODL, RES0 ; ; MOVFF ARG1H, WREG MULWF ARG2H ; ARG1H * ARG2H -> ; PRODH:PRODL MOVFF PRODH, RES3 ; MOVFF PRODL, RES2 ; ; MOVFF ARG1L, WREG MULWF ARG2H ; ARG1L * ARG2H -> ; PRODH:PRODL MOVFF PRODL, WREG ; ADDWF RES1, F ; Add cross MOVFF PRODH, WREG ; products ADDWFC RES2, F ; CLRF WREG, F ; ADDWFC RES3, F ; ; MOVFF ARG1H, WREG ; MULWF ARG2L ; ARG1H * ARG2L -> ; PRODH:PRODL MOVFF PRODL, WREG ; ADDWF RES1, F ; Add cross MOVFF PRODH, WREG ; products ADDWFC RES2, F ; CLRF WREG, F ; ADDWFC RES3, F ; ; BTFSS ARG2H, 7 ; ARG2H:ARG2L neg? GOTO SIGN_ARG1 ; no, check ARG1 MOVFF ARG1L, WREG ; SUBWF RES2 ; MOVFF ARG1H, WREG ; SUBWFB RES3 ; SIGN_ARG1 BTFSS ARG1H, 7 ; ARG1H:ARG1L neg? GOTO CONT_CODE ; no, done MOVFF ARG2L, WREG ; SUBWF RES2 ; MOVFF ARG2H, WREG ; SUBWFB RES3 ; CONT_CODE : 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39506-page 6-6  2000 Microchip Technology Inc. 6.3 Design Tips None. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39506-page 6-7 Section 6. Hardware 8x8 Multiplier Hardware 8x8 Multiplier 6 6.4 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the H/W Multiplier modules are: Title Application Note # IEEE 754 Compliant Floating Point Routines AN575 Fixed Point Routines AN617 Floating Point Math Functions AN660 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39506-page 6-8  2000 Microchip Technology Inc. 6.5 Revision History Revision A This is the initial released revision of the Enhanced MCE Hardware Multiplier module description. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-1 Memory 7 Section 7. Memory Organization HIGHLIGHTS This section of the manual contains the following major topics: 7.1 Introduction .................................................................................................................... 7-2 7.2 Program Memory ........................................................................................................... 7-3 7.3 Program Counter (PC) ................................................................................................... 7-6 7.4 Lookup Tables................................................................................................................ 7-9 7.5 Stack ............................................................................................................................ 7-12 7.6 Data Memory Organization.......................................................................................... 7-13 7.7 Return Address Stack .................................................................................................. 7-17 7.8 Initialization .................................................................................................................. 7-23 7.9 Design Tips .................................................................................................................. 7-24 7.10 Related Application Notes............................................................................................ 7-25 7.11 Revision History ........................................................................................................... 7-26 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-2  2000 Microchip Technology Inc. 7.1 Introduction There are two memory blocks in the memory map; program memory and data memory. Each block has its own bus, so that access to each block can occur during the same instruction cycle. The data memory can further be broken down into General Purpose RAM and the Special Function Registers (SFRs). The operation of the SFRs that control the “core” are described here. The SFRs used to control the peripheral modules are described in the section discussing each individual peripheral module. In addition, there are other registers used that are neither part of the program nor data memory spaces. These registers are not directly addressable and include: • return address stack • fast return stack Table 7-1 shows the program memory space used depending on the memory allocated, and Table 7-2 shows the data memory space used. Table 7-1: PIC18CXXX Program Memory Ranges Table 7-2: PIC18CXXX Data Memory Ranges Program Memory Program Memory Address Range Data Memory Banks 1K x 8 0000h - 3FFh 64 0, 15 2K x 8 0000h - 7FFh 128 0, 15 4K x 8 0000h - FFFh 256 0, 15 8K x 8 0000h - 1FFFh 512 0-1, 15 12K x 8 0000h - 2FFFh 640 0-2, 15 16K x 8 0000h - 3FFFh 768 0-2, 15 24K x 8 0000h - 5FFFh 1024 0-3, 15 32K x 8 0000h - 7FFFh 1280 0-4, 15 48K x 8 0000h - BFFFh 1536 0-5,15 64K x 8 0000h - FFFFh 1792 0-6, 15 96K x 8 0000h - 17FFFh 2048 0-7, 15 128K x 8 0000h - 1FFFFh 2304 0-8, 15 160K x 8 0000h - 27FFFh 2560 0-9, 15 192K x 8 0000h - 2FFFFh 2816 0-10, 15 256K x 8 0000h - 3FFFFh 3072 0-11, 15 384K x 8 0000h - 5FFFFh 3328 0-12, 15 512K x 8 0000h - 7FFFFh 3584 0-13,15 768K x 8 0000h - BFFFFh 3840 0-14,15 1024K x 8 0000h - FFFFFh 3968 0-15 1536K x 8 0000h - 17FFFFh 2048K x 8 0000h - 1FFFFFh 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-3 Section 7. Memory Memory 7 7.2 Program Memory Enhanced MCU devices have a 21-bit program counter capable of addressing 2 Mbytes (1Mwords) of program memory space. The program memory contains instructions for execution and data tables for storing fixed data. Data tables may be written once using table write instructions and read as required, using the table read instructions. The program space is implemented as a single contiguous block. The reset vector is at address 000000h, the high priority interrupt vector is at address 000008h, and the low priority interrupt vector is at address 000018h (Figure 7-1). CALL and GOTO instructions can address any location in the memory map, while the BRA and RCALL instructions have a limited program memory reach (+1024, -1023 program memory word locations). To allow the CALL and GOTO instructions to contain the entire address, it requires that these instructions use 2 program memory words (2 word instruction). Instructions are also available to move information between the data memory and the program memory areas. These are called table operations. Table operations work with byte entities. This is discussed in detail in the “Table Read/Table Write” section. Figure 7-1: Program Memory Map and Stack for PIC18CXXX PC<20:0> Stack Level 1 Stack Level 31 Reset Vector Low Priority Interrupt Vector CALL,BSUB,RETURN RETFIE,RETLW 21 0000h 0018h On-chip High Priority Interrupt Vector 0008h User Memory Space External/Unimplemented 1FFFFFh 200000h Program Memory (Read as ’0’ in microcontroller mode) Program Memory 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-4  2000 Microchip Technology Inc. 7.2.1 Reset Vector On any Enhanced MCU device, a reset forces the Program Counter (PC) to address 0h. This is known as the “Reset Vector Address”, since this is the address that program execution will branch to when a device reset occurs. Any reset will also clear the contents of the PCLATU and PCLATH registers. 7.2.2 Interrupt Vectors Two interrupt vectors are implemented; one for interrupts programmed as high priority and the other for the interrupts programmed as low priority. The vector addresses are 08h for high priority interrupts and 18h for low priority interrupts. If the interrupt priority is not used, all interrupts are treated as high priority. When an interrupt is acknowledged, the PC is forced to address 0008h or 0018h. This is known as the “Interrupt Vector Address”. When the PC is forced to the interrupt vector, the PCLATU and PCLATH registers are not modified. Once in the service interrupt routine (ISR), before any write to the PC, the PCLATH register should be written with the value that will specify the desired location in program memory. Before the PCLATH register is modified by the Interrupt Service Routine (ISR), the contents of the PCLATH may need to be saved so it can be restored before returning from the ISR. 7.2.3 Calibration Information Some devices have calibration information stored in their program memory. This information is programmed by Microchip when the device is under final test. The use of these values allows the application to achieve better results. The calibration information is typically at the end of program memory. These bytes can be accessed with the table read instructions. Note: For windowed devices, write down all calibration values BEFORE erasing. This allows the device’s calibration values to be restored when the device is re-programmed. When possible, writing the values on the package is recommended. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-5 Section 7. Memory Memory 7 7.2.4 Instructions in Program Memory The program memory is addressed in bytes. Instructions are stored as two bytes or four bytes in program memory. The least significant byte of an instruction word is always stored in a program memory location with an even address (LSb = ’0’). Figure 7-2 shows an example of how instruction words are stored in the program memory. To maintain alignment with instruction boundaries, the PC increments in steps of 2 and the LSb will always read ’0’. The CALL and GOTO instructions have an absolute program memory address embedded into the instruction. Since instructions are always stored on word boundaries, the data contained in the instruction is a word address. The word address is written to PC<20:1>, which accesses the desired byte address in program memory. Instruction #2 in Figure 7-2 shows how the instruction "GOTO 000006h’ is encoded in the program memory. Program branch instructions which encode a relative address offset operate in the same manner. The offset value stored in a branch instruction represents the number of single word instructions that the PC will be offset by. The “Instruction Set” section provides further details of the instruction set. Figure 7-2: Instructions in Program Memory Word Address High Byte Low Byte ↓ Program Memory Byte Locations → 000000h 000002h 000004h 000006h Instruction 1: MOVLW 055h 0Fh 55h 000008h Instruction 2: GOTO 000006h EFh 03h 00000Ah F0h 00h 00000Ch Instruction 3: MOVFF 123h, 456h C1h 23h 00000Eh F4h 56h 000010h 000012h 000014h 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-6  2000 Microchip Technology Inc. 7.3 Program Counter (PC) The Program Counter (PC) specifies the address of the instruction to fetch for execution. The PC is 21-bits wide and addresses each byte (rather than words) in the program memory. The low byte is called the PCL register (PC<7:0>). This register is readable and writable. The high byte is called the PCH register (PC<15:8>). This register is not directly readable or writable. Updates to the PCH register may be performed through the PCLATH register. The upper byte is called the PCU register (PC<20:16>). The PCU register is not directly readable or writable. Updates to the PCU register may be performed through the PCLATU register. The PC structure is PCU<4:0>:PCH<7:0>:PCL<7:0> and is equivalent to PC<20:0>. Figure 7-3 shows the interaction of the PCU, PCH, and PCL registers with the PCLATU and PCLATH registers. Figure 7-3: Program Counter Structure The low byte of the PC (PCL<7:0>) is mapped in the data memory. PCL is readable and writable just as is any other register. PCU and PCH are the upper and high bytes of the PC respectively, and are not directly addressable. Registers PCLATU<4:0> (PC upper latch) and PCLATH<7:0> (PC high latch) are used as holding latches for the high bytes of the PCU and PCH, and are mapped into data memory. The user can read and write PCH through PCLATH and PCU through PCLATU. Any time PCL is read, the current contents of PCH and PCU are transferred to PCLATH and PCLATU, respectively. Any time PCL is written to, the contents of PCLATH and PCLATU are transferred to PCH and PCU, respectively. The PC addresses bytes rather than words in the program memory. Because the PC must access the instructions in program memory on an even byte boundary, the LSb of the PC is a forced '0' and the PC increments by two for each instruction. The LSb bit of the PCL is readable but not writable. Any write to the LSb is ignored. Figure 7-4 shows the four situations for the loading of the PC. Situation 1 shows how the PC is loaded on a write to PCL (PCLATH<4:0> → PCH). Situation 2 shows how the PC is loaded during a GOTO instruction (PCLATH<4:3> → PCH). Situation 4 shows how the PC is loaded during a CALL instruction (PCLATH<4:3> → PCH), with the PC loaded (PUSHed) onto the Top of Stack. Situation 6 shows how the PC is loaded during one of the return instructions where the PC is loaded (POPed) from the Top of Stack. PC 21 15 16 0 8 7 PCLATU PCLATH PCU PCH PCL 23 20 Reserved. Maintain these bits cleared. Note: The values in PCLATU and PCLATH do not always reflect the current value in PCU and PCH. When needing to modify the current Program Counter (PC) value, first read the PCL register to update the values in the PCLATU and PCLATH registers. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-7 Section 7. Memory Memory 7 Figure 7-4: Loading of PC In Different Situations PC ALU Result 8 PCL Situation 1 - Instruction with PCL as destination Situation 2 - GOTO Instruction PCLATU PCLATH 20 8 7 0 15 PCH 16 PCU PCL 20 8 7 0 15 PCH 16 PCU 9 1 0 K19:K8 (2nd word K7:K0 (1st word of instruction) of instruction) STACK (21-bits x 31) Top of STACK STACK (21-bits x 31) Top of STACK 20 8 7 0 16 1 15 ADDR Situation 3 - BRA Instruction in Conditional Branch Instruction STACK (21-bits x 31) Top of STACK Offset from Instruction 0 PCU PCH PCL Situation 4 - CALL Instruction 20 PCL 20 8 7 0 15 PCH 16 PCU 9 1 0 K19:K8 (2nd word K7:K0 (1st word STACK (21-bits x 31) Top of STACK of instruction) of instruction) Note: PCLATU and PCLATH are not updated with the contents of PCH. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-8  2000 Microchip Technology Inc. Figure 7-4: Loading of PC In Different Situations (Continued) Situation 6 - RETURN, RETFIE, or RETLW Instruction PCL 20 8 7 0 15 PCH 16 PLU 9 1 PCLATU PCLATH STACK (21-bits x 31) Top of STACK Situation 5 - RCALL Instruction 20 8 7 0 16 15 1 ADDR Offset from Instruction 0 PCU PCH PCL STACK (21-bits x 31) Top of STACK 21 Note: PCLATU and PCLATH are not updated with the contents of PCH. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-9 Section 7. Memory Memory 7 7.3.1 Computed GOTO A computed GOTO is accomplished by adding an offset to the program counter (ADDWF PCL). When doing a table read using a computed GOTO method, care should be exercised if the table location crosses a PCL memory boundary (each 256 byte block) and the PCH memory boundary (each 64Kbyte block). A lookup table can be formed with an ADDWF PCL instruction and a group of RETLW 0xnn instructions. WREG is loaded with an offset into the table before executing a call to that table. The first instruction of the called routine is the ADDWF PCL instruction. The next instruction executed will be one of the RETLW 0xnn instructions that returns the value 0xnn to the calling function. Since the Program Counter is a byte counter (instead of a word counter), adds to the PCL allow a table size of 128 entries before the PCLATH needs to be modified. In this method of storing tables in PIC18CXXX devices, only one data value may be stored in each instruction location, and room on the return address stack is required. A better method of storing data in program memory is through the use of table reads and writes. Two bytes of data can now be stored in each instruction location. 7.4 Lookup Tables Look-up tables instructions are implemented two ways in the PIC18CXXX devices. The computed goto is compatible with the PIC16CXXX and PIC17CXXX parts. Code written for those devices will run on the PIC18CXXX devices with minor modifications. Table read instructions are implemented on the PIC17CXXX and PIC18CXXX devices. However, table operations on the PIC18CXXX work differently than on the PIC17CXXX. 7.4.1 Table Reads/Table Writes Lookup table data may be stored 2 bytes per program word. By using TBLPTR and TABLAT, data may be retrieved from program memory one byte at a time as required. Table writes to program memory can be executed as many times as desired. Remember that the technology of the program memory determines the outcome of the table write. Table writes to EPROM memory allow the program memory cell to go from a ’1’ state to a ’0’ state, but not the other direction. FLASH memory allows the cell to go from a ’1’ to a ’0’ and a ’0’ to a ’1’ (though typically a program memory word or block location is always written). Note: Since the Program Counter is 21-bits, the uppercase PCLATU register may also need to be modified when doing computed gotos. Note: Any write to the Program Counter (PCL) will cause the contents of PCLATU and PCLATH to be loaded into PCU and PCH, respectively. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-10  2000 Microchip Technology Inc. Example 7-1: PIC18CXXX Table Lookup Example 7-2: PIC17CXXX Table Lookup MOVLW BYTE_COUNT ; Load the Byte Count value MOVWF CNTR ; into CNTR ; ;; MOVLW UPPER(TBL_ADDR) ; Load the Table Address ;; MOVWF TBLPTRU ; (on POR TBLPTRU = 0, so ;; ; loading TBLPTRU is not ;; ; required for conversions) MOVLW HIGH(TBL_ADDR) ; Load the Table Address MOVWF TBLPTRH ; MOVLW LOW(TBL_ADDR) ; MOVWF TBLPTRL ; LOOP1 TBLRD*+ ; Read value into TABLAT, ; Increment TBLPTR MOVFF TABLAT, POSTINC0 ; Copy byte to RAM @ FSR0 ; Increment FSR0 DECFSZ CNTR ; Read Byte Count locations GOTO LOOP1 ; Read next Byte MOVLW WORD_COUNT ; Load the Word Count value MOVWF CNTR ; into CNTR ; MOVLW HIGH(TBL_ADDR) ; Load the Table Address MOVWF TBLPTRH ; MOVLW LOW(TBL_ADDR) ; MOVWF TBLPTRL ; TABLRD 0, 1, DUMMY ; Dummy read, ; Updates TABLATH ; Increments TBLPTR LOOP1 TLRD 1, INDF0 ; Read HI byte in TABLATH TABLRD 0, 1, INDF0 ; Read LO byte in TABLATL, ; update TABLATH:TABLATL, ; and increment TBLPTR DECFSZ CNTR ; Read Word Count locations GOTO LOOP1 ; Read next word 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-11 Section 7. Memory Memory 7 Example 7-3: PIC16CXXX Table Lookup CLRF CNTR ; TABLELP MOVF CNTR, W ; Place value in ; WREG register CALL TABLE1 MOVWF INDF INCF FSR INCF CNTR BTFSS CNTR, 3 ; CNTR = 00001000b? GOTO TABLE_LP : : TABLE1 ADDWF PCL ; Enusure that table does ; not cross 256 byte ; page boundary. RETLW ’G’ RETLW ’O’ RETLW ’ ’ RETLW ’M’ RETLW ’C’ RETLW ’H’ RETLW ’P’ RETLW ’!’ 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-12  2000 Microchip Technology Inc. 7.5 Stack The stack allows a combination of up to 31 program calls and interrupts to occur. The stack contains the return address from this branch in program execution. Enhanced MCU devices have an 31-level deep x 21-bit wide hardware stack. The stack space is not part of either program or data space and the stack pointer is not readable nor writable. The PC is PUSHed onto the stack when a CALL instruction is executed or an interrupt causes a branch. The stack is POPed in the event of a RETURN, RETLW or a RETFIE instruction execution. PCLATH is not modified when the stack is PUSHed or POPed. After the PC is PUSHed onto the stack 31 times (without POPing any values off the stack), the 32nd PUSH over-writes the value from the 31st PUSH and sets the STKFUL bit while the STKPTR remains at 11111b. The 33rd PUSH overwrites the 32nd PUSH (and so on) while STKPTR remains 11111b. When the stack overflow enable bit is enabled a device reset will occur. Figure 7-5: Stack Modification Whenever the program branches, the return address is saved to the stack. Such branches include CALL, RCALL, or an interrupt. The stack pointer is incremented and PC<20:1> is PUSHed onto the return stack. PC<0> is always assumed to be 0. When a branch return is executed, the top of the stack is POPed to the Program Counter and the stack pointer is decremented. PCLATU and PCLATH are not affected during these branches. The PC is word incremented by 2 after each instruction fetch during Q1 unless: • Modified by a GOTO, CALL, RCALL, RETURN, RETLW, RETFIE, or branch instruction • Modified by an interrupt response • Due to a write to PCL by an instruction Skips are equivalent to a forced NOP cycle at the skipped address. Top of Stack (1) STACK STACK POINTER 11111b 00000b Note1:The stack pointer value does not increment past 11111b. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-13 Section 7. Memory Memory 7 7.6 Data Memory Organization Data memory is made up of the Special Function Registers (SFR) area and the General Purpose Registers (GPR) area. The SFRs are used for control and status of the microcontroller and peripheral functions, while GPRs are the general area for user data storage and scratch pad operations. Each register has a 12-bit address. This allows up to 4096 bytes of data memory. This memory is partitioned into 16 banks of 256 bytes that contain the General Purpose Registers (GPRs) and Special Function Registers (SFRs). The data memory can be banked for both the GPR and SFR areas. Banking requires the use of BSR Register. Figure 7-6 shows the data memory map organizations, while Table 7-2 shows which banks will be used depending on the memory size of the devices. SFRs start at the last location of Bank 15 (0xFFF) and work up. Once the SFR space ends, any lower locations in that bank may be implemented as GPRs. GPRs start at the first location of Bank 0 (0h) and work down. Any read of an unimplemented location will read as ’0’s. The Instruction set and architecture allows operations across all banks. To move values from one register to another register, the MOVFF instruction can be used. This is a two word / two cycle instruction. The entire data memory can be accessed either directly or indirectly. Direct addressing may require the use of the BSR register. Indirect addressing requires the use of the File Select Registers (FSRs). Each FSR holds a 12-bit value that can access any location in the Data Memory map. To ensure that commonly used registers (SFRs and select GPRs) can be accessed in a single cycle, regardless of the current BSR values, an Access Bank is implemented. This is explained in Section 7.6.1. The GPR area is banked to allow greater than 256 bytes of general purpose RAM to be addressed. SFRs are for the registers that control the peripheral and core functions. Figure 7-6: The Data Memory Map and the Access Bank Bank 0 Bank 1 Bank 14 Bank 15 BSR<3:0> Data Memory Map = 0000b = 0001b = 1110b = 1111b 00h FFh 00h FFh Access Bank When a = 0, the BSR is ignored and this Access Bank is used. The first 128 bytes are General Purpose RAM (from Bank 0). The second 128 bytes are Special Function Registers (from Bank 15). See Section 7.6.1. When a = 1, the BSR is used to specify the RAM location that the instruction uses. Bank n 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-14  2000 Microchip Technology Inc. 7.6.1 Access Bank The Access Bank is an architectural enhancement that is very useful for C compiler code optimization. The techniques used by the C compiler may also be useful for programs written in assembly. This data memory region can be used for: • Intermediate computational values • Local variables of subroutines • Faster context saving/switching of variables • Common variables • Faster evaluation/control of SFRs (no banking) The Access Bank is comprised of the upper portion of Bank 15 (SFRs) and the lower portion of Bank 0 (GPR). These two sections will be referred to as Access RAM High and Access RAM Low, respectively. Figure 7-6 indicates the Access RAM areas. The actual size of memory used from Bank 0 and Bank 15 depends on the specific device. When appropriate, devices will use 128 bytes from Bank 0 (GPR) and 128 bytes from Bank 15 (SFR). In larger devices with more SFRs, the GPR Access bank size may be reduced to allocate that space to SFRs Access space. A bit in the instruction word specifies if the operation is to occur in the bank specified by the BSR register or in the Access Bank. This bit is denoted by the ’a’ bit (for access bit). When forced in the Access Bank (a = ’0’), the last address in Access RAM Low is followed by the first address in Access RAM High. Access RAM High maps the Special Function Registers so that these registers can be accessed without any software overhead. This is useful for testing status flags, modifying control bits, software stacks, and context saving of registers. 7.6.2 General Purpose Registers (GPR) Enhanced MCU devices may have banked memory in the GPR area. GPRs are not initialized by a Power-on Reset and are unchanged on all other resets. The register file can be accessed either directly, or indirectly, using the File Select Register (FSR). Some devices have areas that are shared across the data memory banks, so a read/write to that area will appear as the same location (value), regardless of the current bank. We refer to this area as the Common RAM. Data RAM is available for use as GPR registers by all instructions. Most banks of data memory contain only GPR registers starting with bank 0. The top half of bank 15 (0xF80 to 0xFFF) contains SFRs. Each data memory bank has 256 locations and can be addressed using an 8-bit address. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-15 Section 7. Memory Memory 7 7.6.3 Special Function Registers The SFRs are used by the CPU and peripheral modules for controlling the desired operation of the device. These registers are implemented as static RAM. The SFRs can be classified into two sets; those associated with the “core” function and those related to the peripheral functions. Those registers related to the “core” are described in this section, while those related to the operation of the peripheral features are described in the section of that peripheral feature. The SFRs are typically distributed among the peripherals whose functions they control. If the SFRs do not use all the available locations on a particular device, the unused locations will be unimplemented and read as '0's. In devices that have a high integration of features, some of the SFRs may be in banks other than bank 15. See Figure 7-7 for addresses for the SFRs. As new devices are introduced with new SFRs, this register map will be updated. Please refer to the device data sheet for that device’s register map. Figure 7-7: Special Function Register Map FFFh TOSU FDFh INDF2 (2) FBFh CCPR1H F9Fh IPR1 FFEh TOSH FDEh POSTINC2 (2) FBEh CCPR1L F9Eh PIR1 FFDh TOSL FDDh POSTDEC2 (2) FBDh CCP1CON F9Dh PIE1 FFCh STKPTR FDCh PREINC2 (2) FBCh CCPR2H F9Ch — FFBh PCLATU FDBh PLUSW2 (2) FBBh CCPR2L F9Bh — FFAh PCLATH FDAh FSR2H FBAh CCP2CON F9Ah — FF9h PCL FD9h FSR2L FB9h — F99h — FF8h TBLPTRU FD8h STATUS FB8h — F98h — FF7h TBLPTRH FD7h TMR0H FB7h — F97h — FF6h TBLPTRL FD6h TMR0L FB6h — F96h TRISE FF5h TABLAT FD5h T0CON FB5h — F95h TRISD FF4h PRODH FD4h — FB4h — F94h TRISC FF3h PRODL FD3h OSCCON FB3h TMR3H F93h TRISB FF2h INTCON FD2h LVDCON FB2h TMR3L F92h TRISA FF1h INTCON2 FD1h WDTCON FB1h T3CON F91h — FF0h INTCON3 FD0h RCON FB0h — F90h — FEFh INDF0 (2) FCFh TMR1H FAFh SPBRG F8Fh — FEEh POSTINC0 (2) FCEh TMR1L FAEh RCREG F8Eh — FEDh POSTDEC0 (2) FCDh T1CON FADh TXREG F8Dh LATE FECh PREINC0 (2) FCCh TMR2 FACh TXSTA F8Ch LATD FEBh PLUSW0 (2) FCBh PR2 FABh RCSTA F8Bh LATC FEAh FSR0H FCAh T2CON FAAh — F8Ah LATB FE9h FSR0L FC9h SSPBUF FA9h — F89h LATA FE8h WREG FC8h SSPADD FA8h — F88h — FE7h INDF1 (2) FC7h SSPSTAT FA7h — F87h — FE6h POSTINC1 (2) FC6h SSPCON1 FA6h — F86h — FE5h POSTDEC1 (2) FC5h SSPCON2 FA5h — F85h — FE4h PREINC1 (2) FC4h ADRESH FA4h — F84h PORTE FE3h PLUSW1 (2) FC3h ADRESL FA3h — F83h PORTD FE2h FSR1H FC2h ADCON0 FA2h IPR2 F82h PORTC FE1h FSR1L FC1h ADCON1 FA1h PIR2 F81h PORTB FE0h BSR FC0h — FA0h PIE2 F80h PORTA Note 1: Unimplemented-registers are read as ’0’. 2: This is not a physical register. 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-16  2000 Microchip Technology Inc. 7.6.4 Bank Select Register (BSR) The need for a large general purpose memory space dictated a general purpose RAM banking scheme. A Special Function Register (named BSR) selects the currently active general purpose RAM bank. Only the lower middle of the BSR register (BSR<3:0>) is used. This allows access to potentially 16 banks. Direct long addressing mode is limited to 12-bit addresses. This also allows accesses to any of the 16 banks. BSR<7:4> will always read 0’s, and writes have no effect. All data memory is implemented as static RAM. A MOVLB bank instruction has been provided in the instruction set to assist in selecting banks. If the currently selected bank is not implemented, any read will return all '0's, and all writes are ignored and the STATUS register bits will be set/cleared as appropriate for the instruction performed. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-17 Section 7. Memory Memory 7 7.7 Return Address Stack The Return Address Stack allows any combination of up to 31 program calls and interrupts to occur. The PC (Program Counter) is PUSHed onto the stack when a CALL or RCALL instruction is executed or an interrupt is acknowledged. The PC value is pulled off the stack on a RETURN, RETLW, or a RETFIE instruction. PCLATU and PCLATH are not affected by any of the return instructions. The stack operates as a 31 word by 21-bit RAM and a 5-bit stack pointer (STKPTR), with the stack pointer initialized to 00000b after all resets. There is no RAM associated with stack pointer location 00000b. This is only a reset value. During a CALL type instruction causing a PUSH onto the stack, the stack pointer is first incremented and the RAM location pointed to by the stack pointer is written with the contents of the PC. During a RETURN type instruction causing a POP from the stack, the contents of the RAM location pointed to by the STKPTR register are transferred to the PC and then the stack pointer is decremented. The stack space is not part of either program or data space and the stack pointer is neither readable nor writable. The address on the top of the stack is readable and writable through SFR registers. Data can also be PUSHed to or POPed from the stack using the top-of-stack SFRs. Status bits indicate if the stack pointer attempts to exceed the 31 levels provided. The stack does not wrap when the stack is PUSHed greater than 31 times. Figure 7-8: Return Address Stack and Associated Registers 7.7.1 Top-Of-Stack Access The Top-of-Stack (TOS) is readable and writable. Three register locations, TOSU, TOSH and TOSL, hold the contents of the stack location pointed to by the STKPTR register. This allows users to implement a software stack if necessary. After a CALL, RCALL or interrupt, the software can read the PUSHed value by reading the TOSU, TOSH and TOSL registers. These values can be placed on a user defined software stack. At return time, the software can replace the TOSU, TOSH and TOSL and do a return. The user must disable the global interrupt enable bits during this time to prevent inadvertent stack operations. 0x001A34 11111 11110 11101 ... ... ... 00011 00010 00001 00000 00010 Return Address Stack Top of Stack 0x000D58 TOSU TOSH TOSL 0x00 0x1A 0x34 STKPTR<4:0> Note: The user must disable interrupts when manipulating the stack. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-18  2000 Microchip Technology Inc. 7.7.2 PUSH and POP Instructions Since the Top-of-Stack (TOS) is readable and writable, the ability to PUSH values onto the stack and pull values off the stack without disturbing normal program execution is a desirable option. To PUSH the current PC value onto the stack, a PUSH instruction can be executed. This will increment the stack pointer and load the current PC value onto the stack. TOSU, TOSH, and TOSL can then be modified to place data on the stack instead of a return address. This data may be a new return address. This may be done in the operation of a Real Time Operating System (RTOS). The ability to pull the TOS value off of the stack and replace it with the value that was previously PUSHed onto the stack, without disturbing normal execution, is achieved by using the POP instruction. The POP instruction discards the current TOS by decrementing the stack pointer. The previous value PUSHed onto the stack then becomes the TOS value. Example 7-4: Using the PUSH Instruction Example 7-5: Using the POP Instruction MOVLW Dummy_TOSU ; MOVWF TOSU ; MOVLW Dummy_TOSH ; MOVWF TOSH ; MOVLW Dummy_TOSL ; MOVWF TOSL ; PUSH ; MOVFF TOSU, PREINC1 ; MOVFF TOSH, PREINC1 ; MOVFF TOSL, PREINC1 ; POP ; 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-19 Section 7. Memory Memory 7 7.7.3 Return Stack Pointer (STKPTR) The STKPTR register contains the return stack pointer value and the overflow and underflow bits. The stack overflow bit (STKFUL) and underflow bit (STKUNF) allow software verification of a stack condition. The STKFUL and STKUNF bits are cleared only after a POR reset. After the PC is PUSHed onto the stack 31 times (without POPing any values off the stack), the 32nd PUSH over-writes the value from the 31st PUSH and sets the STKFUL bit, while the STKPTR remains at 11111b. The 33rd PUSH overwrites the 32nd PUSH (and so on), while STKPTR remains 11111b. After the stack is POPed enough times to unload the stack, the next POP will return a value of zero to the PC and set the STKUNF bit while the STKPTR remains at 00000b. The next POP returns zero again (and so on), while STKPTR remains 00000b. The stack pointer can be accessed through the STKPTR register. The user may read and write the stack pointer values. This can be used by a Real Time Operating System (RTOS) for return stack maintenance. Figure 7-8 shows the STKPTR register. The value of the stack pointer will be 0 through 31. At reset, the stack pointer value will be 0. The stack pointer will increment when PUSHing and will decrement when POPing. 7.7.4 Stack Full/Underflow Resets At the user’s option, the overflow and underflow can cause a device reset to interrupt the program code. The reset is enabled with a configuration bit, STVREN. When the STVREN bit is disabled, a full or underflow condition will set the appropriate STKFUL or STKUNF bit but not cause a reset. When the STVREN bit is enabled, a overflow or underflow will set the appropriate STKFUL or STKUNF bit and then cause a device reset very similar in nature to the WDT reset. In either case, the STKFUL or STKUNF bits are only cleared by user software or a POR reset. 7.7.5 Fast Register Stack A "fast interrupt return" option is available for interrupts. A fast register stack is provided for the STATUS, WREG, and BSR registers and are only one in depth. The stack is neither readable nor writable and is loaded with the current value of the corresponding register when the processor vectors for an interrupt. The values in the registers are then loaded back into the working registers if the fast return instruction is used to return from the interrupt. Low or high priority interrupt PUSHes values into the stack registers. If both low and high priority interrupts are enabled, the stack registers cannot be used reliably for low priority interrupts. A high priority interrupt, if one occurs while servicing a low priority interrupt, will overwrite the stack registers stored by the low priority interrupt. If high priority interrupts are not disabled during low priority interrupts, users must save the key registers in software during a low priority interrupt. If no interrupts are used, the fast register stack can be used to restore the STATUS, WREG and BSR registers at the end of a subroutine call. To use the fast register stack for a subroutine call, a fast call instruction must be executed. Note: Returning a zero to the PC on an underflow has the effect of vectoring the program to the reset vector, where the stack conditions can be verified and appropriate actions can be taken. 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-20  2000 Microchip Technology Inc. 7.7.6 Indirect Addressing, INDF, and FSR Registers Indirect addressing is a mode of addressing data memory where the data memory address in the instruction is not fixed. An SFR register is used as a pointer to the data memory location that is to be read or written. Since this pointer is in RAM, the contents can be modified by the program. This can be useful for data tables in the data memory and for software stacks. Figure 7-9 shows the operation of indirect addressing. This shows the moving of the value to the data memory address specified by the value of the FSR register. Indirect addressing is possible by using the INDF register. Any instruction using the INDF register actually accesses the register pointed to by the File Select Register, FSR. Reading the INDF register itself indirectly (FSR = '0') will read 00h. Writing to the INDF register indirectly results in a no-operation (although status bits may be affected). The FSR register contains a 12-bit address, which is shown in Figure 7-9. Figure 7-9: FSR Operation (Indirect Addressing) There are three indirect addressing registers. To address the entire Data Memory space (4096 bytes), these registers are 12 bits wide. To store the 12 bits of addressing information, two 8-bit registers are required. These indirect addressing registers are: 1. FSR0: composed of FSR0H:FSR0L 2. FSR1: composed of FSR1H:FSR1L 3. FSR2: composed of FSR2H:FSR2L In addition, there are registers INDF0, INDF1 and INDF2, which are not physically implemented. Reading or writing to these registers activates indirect addressing, with the value in the corresponding FSR register being the address of the data. If an instruction writes a value to INDF0, the value will be written to the address pointed to by FSR0H:FSR0L. A read from INDF1 actually reads the data from the address pointed to by FSR1H:FSR1L. INDFn can be used in code anywhere an operand can be used. If the INDF0, INDF1 or INDF2 register is read indirectly via an FSR, all '0's are read (Zero bit is set). Similarly, if INDF0, INDF1or INDF2 is written to indirectly, the operation will be equivalent to a NOP, and the STATUS bits are not affected. Opcode Address File Address = INDF FSR Instruction Executed Instruction Fetched RAM Opcode File 12 12 12 BSR<3:0> 4 8 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-21 Section 7. Memory Memory 7 7.7.6.1 Indirect Addressing Operation Each FSR register has an INDF register plus four addresses associated with it. The same INDFn, and FSRnH:FSRnL registers are used, but depending on the INDFn address selected, the FSRnH:FSRnL registers may be modified. When a data access is done to the one of the five INDFn locations, the address selected will configure the FSRn register to: • Do nothing to FSRn after an indirect access (no change) - INDFn • Auto-decrement FSRn after an indirect access (post-decrement) - POSTDECn • Auto-increment FSRn after an indirect access (post-increment) - POSTINCn • Auto-increment FSRn before an indirect access (pre-increment) - PREINCn • Use the value in the WREG register as an offset to FSRn. Do not modify the value of the WREG or the FSRn register after an indirect access (no change) - PLUSWn When using the auto-increment or auto-decrement features, the effect on the FSR is not reflected in the STATUS register. For example, if the indirect address causes the FSR to equal '0', the Z bit will not be set. Incrementing or decrementing an FSR affects all 12 bits. That is, when FSRnL overflows from an increment, FSRnH will be incremented automatically. Adding these features allows the FSRn to be used as a stack pointer in addition to its uses for table operations in data memory. Each FSR has an address associated with it that performs an indexed indirect access. When a data access to this INDFn location (PLUSWn) occurs, the FSRn is configured to add the signed value in the WREG register and the value in FSR to form the address before an indirect access. The FSR value is not changed. If an FSR register contains a value that points to one of the INDFn, an indirect read will read 00h (Zero bit is set), while an indirect write will be equivalent to a NOP (STATUS bits are not affected). If an indirect addressing operation is done where the target address is an FSRnH or FSRnL register, the write operation will dominate over the pre- or post-increment/decrement functions. Figure 7-10 shows the interaction of the FSR register and the data memory. Figure 7-10: FSR Operation (Indirect Addressing) Note: Accessing the PLUSWn address causes indexed indirect access. The addressed register is the addition of the value in the FSRn register and the SIGNED value in the WREG register. 11 FSRn 0 Bank0 Bank1 Bank15 0h 1h Bank Fh 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-22  2000 Microchip Technology Inc. Example 7-6 shows a simple use of indirect addressing to clear RAM (locations 20h-2Fh) in a minimum number of instructions. A similar concept could be used to move a defined number of bytes (block) of data to the USART transmit register (TXREG). The starting address of the block of data to be transmitted could easily be modified by the program. Example 7-6: Indirect Addressing CLRF FSR1H ; Clear High byte of FSR MOVLW 0x20 ; Load Low byte of 20h MOVWF FSR1L ; NEXT CLRF POSTINC1 ; Clear register and the ; increment BTFSS FSR1L, 4 ; GOTO NEXT ; CONTINUE ; : 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-23 Section 7. Memory Memory 7 7.8 Initialization Example 7-7 shows how the bank switching occurs for direct addressing, while Example 7-8 shows some code to do initialization (clearing) of General Purpose RAM. Example 7-7: Bank Switching Example 7-8: RAM Initialization CLRF BSR ; Clear BSR register (Bank0) : ; BSF BSR, 0 ; Bank1 : ; BCF BSR, 0 ; Bank0 : ; MOVLW 0x06 ; MOVWF BSR ; Bank6 : ; BCF BSR, 2 ; Bank2 : ; BCF BSR, 1 ; Bank0 CLRF FSR1H CLRF FSR1L CLR_LP CLRF POSTINC1 ; Clear location, increment MOVLW 0x0F ; Bank is FSR1H:FSR1L SUBWF FSR1H,W ; Are we now in Bank 15? BNZ CLR_LP ; NO, continue to clear GPRs CONTINUE ; : : 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-24  2000 Microchip Technology Inc. 7.9 Design Tips Question 1: I need to initialize RAM to ’0’s. What is an easy way to do that? Answer 1: Example 7-8 shows this. If the device you are using does not use all 15 data memory banks, the value to compare FSR1H against will need to be modified. Question 2: I want to convert from a PIC16C77 which has 368 bytes of RAM (across 4 banks). What is the best way to remap this memory? Answer 2: In devices where the Access GPR region is greater or equal to 128 bytes and Bank 1 contains 256 bytes of GPR, the RAM should be partitioned with the RAM in Bank0 at locations 0x00 to 0x7F and all of Bank1. This allows a total of 384 bytes, which is larger than the 368 bytes in the PIC16C77. Now the BSR can be loaded with 0x01 (pointing to Bank1). All memory access are now either in Bank1 or the Access RAM, so no bank switching is required. 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39507A-page 7-25 Section 7. Memory Memory 7 7.10 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Base-Line, the Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the Memory Organization are: Title Application Note # Implementing a Table Read AN556 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39507A-page 7-26  2000 Microchip Technology Inc. 7.11 Revision History Revision A This is the initial released revision of the Enhanced MCU Memory Organization description. 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39508-page 8-1 Table Write Table Read/ 8 HIGHLIGHTS This section of the manual contains the following major topics: 8.1 Introduction .................................................................................................................... 8-2 8.2 Control Registers ........................................................................................................... 8-3 8.3 Program Memory ........................................................................................................... 8-6 8.4 Enabling Internal Programming ................................................................................... 8-12 8.5 External Program Memory Operation .......................................................................... 8-12 8.6 Initialization .................................................................................................................. 8-13 8.7 Design Tips .................................................................................................................. 8-14 8.8 Related Application Notes............................................................................................ 8-15 8.9 Revision History ........................................................................................................... 8-16 Section 8. Table Read/Table Write 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39508-page 8-2  2000 Microchip Technology Inc. 8.1 Introduction Enhanced devices have two memory spaces. The program memory space and the data memory space. The program memory space is 16 bits wide, while the data memory space is 8 bits wide. Table Reads and Table Writes have been provided to move data between these two memory spaces through an 8-bit register (TABLAT). The operations that allow the processor to move data between the data and program memory spaces are: • Table Read (TBLRD) • Table Write (TBLWT) Table Read operations retrieve data from program memory and place it into the data memory space. Figure 8-1 shows the operation of a Table Read with program and data memory. Table Write operations store data from the data memory space into program memory. Figure 8-2 shows the operation of a Table Write with program and data memory. Table operations work with byte entities. A table block containing data is not required to be word aligned, so a table block can start and end at any byte address. If Enhanced MCU instructions are being written to program memory, these instructions must be word aligned. Figure 8-1: Table Read Operation Figure 8-2: Table Write Operation TABLE POINTER (1) TABLE LATCH (8-bit) Program Memory TBLPTRH TBLPTRL TABLAT Program Memory Address (TBLPTR) TBLPTRU Instruction: TBLRD* Note 1: Table Pointer points to a byte in program memory. TABLE POINTER (1) TABLE LATCH (8-bit) Program Memory TBLPTRU TBLPTRH TBLPTRL TABLAT Instruction: TBLWT* Note 1: Table Pointer points to a byte in program memory. Program Memory Address (TBLPTR) 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39508-page 8-3 Section 8. Table Read/Table Write Table Write Table Read/ 8 8.2 Control Registers Several control registers are used in conjunction with the TBLRD and TBLWT instructions. These include the: • RCON register • MEMCON register • TBLPTR registers • TABLAT register 8.2.1 RCON Register The LWRT bit specifies the operation of Table Writes to internal memory when the VPP voltage is applied to the MCLR pin. When the LWRT bit is set, the controller continues to execute user code, but long Table Writes are allowed (for programming internal program memory) from user mode. The LWRT bit can be cleared only by performing either a Power-On Reset (POR) or MCLR reset. The other bits of the RCON register do not relate to Table Read nor Table Write operation. Register 8-1: RCON Register R/W-0 R/W-0 U-0 R/W-1 R/W-1 R/W-1 R/W-0 R/W-0 IPEN LWRT — RI TO PD POR BOR bit 7 bit 0 bit 7 IPEN: Interrupt Priority Enable 1 = Enable priority levels on interrupts 0 = Disable priority levels on interrupts (PIC16CXXX compatibility mode) bit 6 LWRT: Long Write Enable 1 = Enable TABLE WRITE to internal program memory 0 = Disable TABLE WRITE to internal program memory Note 1: Only cleared on a POR or MCLR reset. Note 2: This bit has no effect on TBLWT instructions to external program memory. bit 5 Unimplemented: Read as '0' bit 4 RI: Reset Instruction Flag bit 1 = No Reset instruction occurred 0 = A Reset instruction occurred bit 3 TO: Time-out bit 1 = After power-up, CLRWDT instruction, or SLEEP instruction 0 = A WDT time-out occurred bit 2 PD: Power-down bit 1 = After power-up or by the CLRWDT instruction 0 = By execution of the SLEEP instruction bit 1 POR: Power-On Reset Status bit 1 = No Power-On Reset occurred 0 = A Power-On Reset occurred (must be set in software after a Power-On Reset occurs) bit 0 BOR: Brown-out Reset Status bit 1 = No Brown-out Reset or POR reset occurred 0 = A Brown-out Reset or POR reset occurred (must be set in software after a Brown-out Reset occurs) Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39508-page 8-4  2000 Microchip Technology Inc. 8.2.2 MEMCON Register This register is only available on devices with a system bus to interface to external program memory. The MEMCON register is used to specify the operation of the 16-bit external system bus for Table Write operations. For additional information see the “System Bus” section. This register is not implemented in devices without a System Bus. Register 8-2: MEMCON Register R/W-0 R/W-0 R/W-0 R/W-0 U-0 U-0 R/W-0 R/W-0 EBDIS PGRM WAIT1 WAIT0 — — WM1 WM0 bit 7 bit 0 bit 7 EBDIS: External bus disable bit This bit is used to disable the System Bus pins when in Extended Microcontroller mode. When disabled, the system bus pins become general purpose I/O. 1 = External system bus disabled, all I/O pin functions are enabled 0 = External system bus enabled, and I/O pin functions are disabled bit 6 PGRM: Program RAM enable bit This bit is used to configure internal GPR locations into the program memory map. This is useful for boot loaders in devices operating in microprocessor mode. The amount of GPR mapped will be device dependant 1 = GPR memory is mapped to internal program memory space. External program memory at these locations is unused. The internal GPR memory locations are disabled and returns 00h. 0 = GPR memory remains in data memory space. External program memory space is available. bit 5-4 WAIT1:WAIT0: Wait Cycle count bits Table reads and writes bus cycle wait count 11 = Table reads and writes will wait 0 TCY 10 = Table reads and writes will wait 1 TCY 01 = Table reads and writes will wait 2 TCY 00 = Table reads and writes will wait 3 TCY bit 3-2 Unimplemented: Read as '0' bit 1-0 WM1:WM0: Write Mode bit Table Write write mode operation with 16-bit bus 11 = Word Write Mode: TABLAT0 and TABLAT1 word output, WRH active when TABLAT1 written 10 = Reserved 01 = Byte Select Mode: TABLAT data copied on both MS and LS Byte, WRH and (UB or LB) will activate 00 = Byte Write Mode: TABLAT data copied on both MS and LS Byte, WRH or WRL will activate Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note: Any register that has a protected bit requires that the entire register is protected. To write to a protected register requires the proper write sequence on the CMLK1:CMLK0 bits before this register can be updated. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39508-page 8-5 Section 8. Table Read/Table Write Table Write Table Read/ 8 8.2.3 TABLAT - Table Latch Register The Table Latch (TABLAT) is an 8-bit register mapped into the SFR space. The Table Latch is used to hold 8-bit data during data transfers between program memory and data memory. 8.2.4 TBLPTR - Table Pointer Register The Table Pointer (TBLPTR) addresses a byte within the program memory. The TBLPTR is comprised of three SFR registers (Table Pointer Upper byte, High byte, and Low byte). These three registers (TBLPTRU:TBLPTRH:TBLPTRL) join to form a 22-bit wide pointer. The low order 21-bits allows the device to address up to 2M bytes (or 1M words) of program memory space. The 22nd bit allows access to the Device ID, the User ID, and the Configuration bits. The Table Pointer, TBLPTR, is used by the TBLRD and TBLWT instructions. These instructions can update the TBLPTR in one of four ways, based on the table operation. These operations are shown in Table 8-1. These operations on the TBLPTR only affect the low order 21-bits. Table 8-1: Table Pointer Operations with TBLRD and TBLWT Instructions Instruction Operation on Table Pointer TBLRD* TBLWT* TBLPTR is not modified TBLRD*+ TBLWT*+ TBLPTR is incremented after the read/write TBLRD*- TBLWT*- TBLPTR is decremented after the read/write TBLRD+* TBLWT+* TBLPTR is incremented before the read/write 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39508-page 8-6 Section 8. Table Read/Table Write Table Write Table Read/ 8 8.3 Program Memory The program memory can be either internal or external. External program memory requires that the device has the system bus interface. The operation of Table Reads and Table Writes is different depending on the location of the program memory (internal or external). For the device to access external memory, the device needs to be operating in either extended microcontroller mode (some program memory is also internal), or microprocessor mode (no program memory is internal). In this section, the discussion of Table Read and Table Write operation will be limited to the operation with internal program memory. For operation with external program memory, please refer to the “System Bus” section. 8.3.1 Internal Program Memory The device selected will determine the program memory technology used. The Internal Program Memory can currently be one of three different memory technologies: 1. EPROM 2. FLASH 3. ROM Depending on the memory technology the following statements can be made. For EPROM devices: • All unprogrammed memory locations will read back 0xFF (all bits set) • Any bit that is set can be programmed clear • Locations with data can be reprogrammed only if 1’s are changed to 0’s • No cleared bit can be set unless the entire device is erased, which is only possible with windowed parts. For FLASH devices: • Any bit can be modified on a byte/block basis (individual bits cannot be modified) • All writes occur with the write of an entire write block • The size of the write block is device dependent For ROM devices: • All unprogrammed memory locations will read back 0xFF (all bits set) • No program memory location can be modified 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39508-page 8-7  2000 Microchip Technology Inc. 8.3.2 Internal Program Memory Operation Table Read operation is independent of internal Program Memory Technology used. Table Write operation will be dependent on the memory technology of the internal Program Memory. The notation “TBLRD instruction” means any of the four Table Read forms (TBLRD*, TBLRD*+, TBLRD*-, TBLRD+*) and the notation “TBLWT instruction” means any of the four Table Write forms (TBLWT*, TBLWT*+, TBLWT*-, TBLWT+*). For additional details on the operation of these instructions refer to the “Instruction Set” section. 8.3.2.1 Table Read Overview (TBLRD) The TBLRD instructions are used to read data from program memory to data memory. The Table Reads from program memory are performed one byte at a time. The TBLPTR points to a byte address in program space. Executing a TBLRD instruction moves the contents of the addressed byte into the TABLAT register. In addition, the TBLPTR can be modified automatically for the next Table Read operation. The TBLPTR can be automatically modified, depending on the form of the TBLRD instruction (see Table 8-1). All of the TBLRD instructions require two instruction cycles (TCY) to execute. 8.3.2.1.1 Effects of a Reset The TABLAT register will retain the value read from program memory (if the instruction completed). The Table Pointer registers will not change, and the RCON register will be forced to the appropriate reset state. 8.3.2.2 Table Write Overview (TBLWT) The TBLWT instructions are used to write data from data memory to program memory. For devices with EPROM Program Memory, Table Writes are performed in pairs, one byte at a time. Table Writes to an even program memory address (TBLPTR<0> is clear) will load an internal memory latch from TABLAT, and is known as a short write. Table Writes to an odd program memory address (TBLPTR<0> is set) will start long writes. (TABLAT is programmed to the program word high byte, and the internal memory latch is programmed to the same word low byte). For devices using another program memory technology, the operation may be different. Please refer to the device data sheet. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39508-page 8-8  2000 Microchip Technology Inc. 8.3.2.2.1 Memory Write Block Size Depending on the device used, the write block size will be different. The larger the block size, the faster the entire internal program memory space can be programmed. This is because the EPROM/FLASH write time is much longer than the time to load the holding registers. For internal program memory, the write block size can vary from 2 bytes to many bytes (in FLASH devices). A write to the Most Significant byte (MSB) of the block causes the entire block to be written to program memory. Writes to all other locations in the write block only modify the contents of the specified holding register. After a write cycle has completed, the contents of the Write Block Holding Registers are forced set (‘1’s). This eases the writing of only a single byte within a program memory block. Figure 8-3 shows the write block for EPROM program memory. The write block size is 2 bytes. If a single byte is to be programmed, the low (even) byte of the destination program word should be read using TBLRD*, then modified if required, and written back to the same address using TBLWT*+. Then the high (odd) byte should be read using TBLRD*, modified if required, and written back to the same address using a TBLWT instruction. The write to an odd address will cause a long write to begin (in EPROM program memory devices). This process ensures that existing data in either byte will not be changed unless desired. Figure 8-3: Holding Registers and the Write Block (EPROM Program Memory) Block n Block n + 1 Block n + 2 MSB The write to the MSB of the write block causes the entire block to be written to program memory. The program memory block that is written depends on the address that is written to in the MSB of the write block. All writes to the holding registers use only the LSb’s of the address to specify into which holding register to load the data. Holding Registers Program Memory (x 16-bits) Write Block 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39508-page 8-9 Section 8. Table Read/Table Write Table Write Table Read/ 8 8.3.2.2.2 EPROM Program Memory Operation The long write is what actually programs the data into the internal memory. When a TBLWT instruction to the MSB of the write block occurs, instruction execution is halted. During this time, programming voltage and the data stored in internal latches is applied to program memory. The sequence of steps to program the internal program memory is: 1. MCLR/VPP pin must be at the programming voltage 2. LWRT bit must be set 3. TBLWT to the address of the MSB of the write block If the LWRT bit is clear, a short write will occur and program memory will not be changed. If the TBLWT is not to the MSB of the write block, then the programming phase is not initiated. Setting the LWRT bit enables long writes when the MCLR pin is taken to VPP voltage. Once the LWRT bit is set, it can be cleared only by performing a Power-On Reset (POR) or MCLR reset. To ensure that the memory location has been well programmed, a minimum programming time is required. The long write can be terminated after the programming time has expired by any event that can wake the controller from SLEEP. This may be a reset or an interrupt that operates during sleep. Having only one interrupt source enabled to terminate the long write ensures that no unintended interrupts will prematurely terminate the long write. Usable interrupt sources include: • WDT • A/D • External Interrupts (INT0, INT1, or INT2) • PORTB interrupt on change • USART on address detect • Timer1 in async counter mode or async external clock mode. • Timer3 in async counter mode or async external clock mode. • Capture • SPI 8.3.2.2.3 Sequence of events The sequence of events for programming an internal program memory location should be: 1. Enable the interrupt that terminates the long write. Disable all other interrupts. 2. Clear the source interrupt flag. 3. If Interrupt Service Routine (ISR) execution is desired when the device wakes, enable global interrupts (GIE, GIEH, or GIEL). 4. Set LWRT bit in RCON register. 5. Raise MCLR/VPP pin to the programming voltage, VPP. 6. Clear the WDT (if enabled). 7. Set the interrupt source to interrupt at the required time. 8. Load the desired Table Pointer Address. 9. Execute the Table Write for the lower (even) byte. This will be a short write. 10. Execute the Table Write for the upper (odd) byte. This will be a long write. The controller will halt instruction execution while programming. The interrupt wakes the controller. 11. If GIE was set, service the interrupt request. 12. If more locations to program, go to step 2. 13. Lower MCLR/VPP pin to VDD. 14. Verify the memory location (Table Read). 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39508-page 8-10  2000 Microchip Technology Inc. 8.3.2.2.4 Interrupts The long write must be terminated by a RESET or any interrupt that can wake the controller from SLEEP mode. Usable interrupt sources include: • WDT • A/D • INT0 • INT1 • INT2 • RB<7:4> interrupt on change • USART on address detect • Timer1 in asynchronous counter mode or asynchronous external clock mode • Timer3 in asynchronous counter mode or asynchronous external clock mode The interrupt source must have its interrupt enable bit set. When the source sets its interrupt flag, programming will terminate. This will occur regardless of the settings of interrupt priority bits, the GIE/GIEH bit, or the PIE/GIEL bit. Depending on the states of interrupt priority bits, the GIE/GIEH bit, or the PIE/GIEL bit, program execution can either be vectored to the high or low priority Interrupt Service Routine (ISR), or resume program execution. In either case, the interrupt flag will not be automatically cleared when programming is terminated, and will need to be cleared by the software. Table 8-2: SLEEP Mode, Interrupt Enable Bits and Interrupt Results Interrupt Source GIE/ GIEH PIE/ GIEL Priority Interrupt Enable Interrupt Flag Action Any interrupt source that operates during SLEEP XX X 0 (default) X SLEEP mode continues even if interrupt flag becomes set during SLEEP. X X X 1 0 SLEEP mode continues, will wake when Interrupt flag is set. 0 (default) 0 (default) X 1 1 Wakes controller, terminates long write, executes next instruction. Interrupt flag not cleared. 0 (default) 1 1 high priority (default) 1 1 Wakes controller, terminates long write, executes next instruction. Interrupt flag not cleared. 1 0 (default) 0 low 1 1 Wakes controller, terminates long write, executes next instruction. Interrupt flag not cleared. 0 (default) 1 0 low 1 1 Wakes controller, terminates long write, branches to low priority interrupt vector. Interrupt flag can be cleared by ISR. 1 0 (default) 1 high priority (default) 1 1 Wakes controller, terminates long write, branches to high priority interrupt vector. Interrupt flag can be cleared by ISR. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39508-page 8-11 Section 8. Table Read/Table Write Table Write Table Read/ 8 8.3.2.2.5 Unexpected Termination of Write Operations If a table write operation is terminated by an unplanned event, such as loss of power, an unexpected reset, or an interrupt that was not disabled, the memory location just programmed should be verified and reprogrammed if needed. For applications where a loss of power could occur, a Brown-out reset circuit is recommended to ensure that the write operation is terminated cleanly. This reduces the possibility that a programmed location could not be reprogrammed to the desired value. 8.3.2.2.6 Effects of a RESET A device reset during a long write may cause the location being programmed to be incompletely programmed. The location should be verified and reprogrammed if needed. A device reset during a write (short) will not effect the value in the TABLAT register (if the write cycle completed). The RCON register will be forced into the appropriate reset state. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39508-page 8-12  2000 Microchip Technology Inc. 8.4 Enabling Internal Programming There is a combination of actions that need to occur to enable programming of the internal program memory. These modes are entered by applying the VIHH voltage on the MCLR/VPP pin and either setting the LWRT bit (self-programming) or having RB6 and RB7 at a low level when VIHH was detected (ICSP mode). 8.4.1 Programming Modes Table 8-3 shows the device operating modes depending on the state of the MCLR pin, the LWRT bit, and the RB7:RB6. Table 8-3: Device Programming Mode (Depending on MCLR voltage and LWRT bit and RB7 and RB6 pins) 8.5 External Program Memory Operation Regardless of the system bus mode selected, Table Reads and Table Writes to external memory execute in 2 TCY. For information regarding the modes and waveforms of the System Bus, see the “System Bus” section. All further details of external program memory and table operations will be described in that section. MCLR/VPP Voltage LWRT RB6 RB7 OPERATING MODE VPP 0 0 0 ICSP VPP 0 1 X Reserved VPP 0 X 1 Reserved VPP 1 X X Normal execution, long Table Writes enabled VDD 1 X X Normal execution, short Table Writes only VSS 0 (1) X X In Device Reset Legend: X = Don’t care. Note 1: The LWRT bit is cleared by any device reset. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39508-page 8-13 Section 8. Table Read/Table Write Table Write Table Read/ 8 8.6 Initialization Example 8-1 shows the initialization of the Table pointer and the FSR0 register to read the value from Program memory to a RAM buffer (starting at address RAMBUFADDR). Example 8-2 shows the sequence to initialize these same registers and then write a word to the internal EPROM Program memory. Example 8-1: Initialization to do a Table Read Example 8-2: Initialization to do a Table Write (to internal EPROM memory) LFSR FSR0, RAMBUFADDR ; MOVLW UPPER (Read Table) ; MOVWF TBLPTRU ; MOVLW HIGH (Read Table) ; MOVWF TBLPTRH ; MOVLW LOW (Read Table) ; MOVWF TBLPTRL ; TBLRD*+ ; Read location and then increment ; the table pointer MOVFF TABLAT, POSTINC0 ; Copy contents of table latch to the ; indirect address and then ; increment the indirect address ; pointer. : ; Set up interrupts to terminate : ; long write LFSR FSR0, RAMBUFADDR ; MOVLW UPPER (Read Table) ; MOVWF TBLPTRU ; MOVLW HIGH (Read Table) ; MOVWF TBLPTRH ; MOVLW LOW (Read Table) ; MOVWF TBLPTRL ; MOVFF POSTINC0, TABLAT ; Load table latch with value ; to write TBLWT*+ ; Write to holding register MOVFF POSTINC0, TABLAT ; Load second byte to table latch TBLWT*+ ; Write to MSB, (odd address) ; start long write 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39508-page 8-14  2000 Microchip Technology Inc. 8.7 Design Tips Question 1: The location I programmed does not contain the value I wrote. What is wrong? Answer 1: There are several possibilities. These include, but are not limited to: • The maximum time requirement of the long write time was not met (for internal program memory). • The address of the location to program was changed during the write cycle. • A device reset occurred during the write cycle. • If the program memory is EPROM or EOTP, then required overprogramming was not done. • An Interrupt flag may have been set, so the long write cycle was immediately completed (violated long write time specification). Question 2: Occasionally the device hangs. What is this? Answer 2: Your program may have executed a long write, and the device may not have the interrupts/modules set up to terminate this long write. Question 3: When programming the program memory are there any required algorithm algorithms to follow? Answer 3: The programming algorithm will be dependent on the memory technology of the device. For complete information on device programming please refer to the device’s programming specifications. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39508-page 8-15 Section 8. Table Read/Table Write Table Write Table Read/ 8 8.8 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the oscillator are: Title Application Note # No related application notes at this time. Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39508-page 8-16  2000 Microchip Technology Inc. 8.9 Revision History This is the initial released revision of the Enhanced MCU Table Read/Table Write description. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39509A-page 9-1 System Bus 9 Section 9. System Bus Please check the Microchip web site for Revision B of the System Bus Section. 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39509A-page 9-2  2000 Microchip Technology Inc. 9.1 Revision History Revision A This is the initial released revision of the Enhanced MCU System Bus module description. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-1 Interrupts 10 Section 10. Interrupts HIGHLIGHTS This section of the manual contains the following major topics: 10.1 Introduction .................................................................................................................. 10-2 10.2 Control Registers ......................................................................................................... 10-6 10.3 Interrupt Handling Operation...................................................................................... 10-19 10.4 Initialization ................................................................................................................ 10-29 10.5 Design Tips ................................................................................................................ 10-30 10.6 Related Application Notes.......................................................................................... 10-31 10.7 Revision History ......................................................................................................... 10-32 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-2  2000 Microchip Technology Inc. 10.1 Introduction Interrupts can come from many sources. These sources currently include: • External interrupt from the INT, INT1, and INT2 pins • Change on RB7:RB4 pins • TMR0 Overflow • TMR1 Overflow • TMR2 Overflow • TMR3 Overflow • USART Interrupts - Receive buffer full - Transmit buffer empty • SSP Interrupt • SSP I2C bus collision interrupt • A/D conversion complete • CCP interrupt • LVD Interrupt • Parallel Slave Port • CAN interrupts - Receive buffer 1 full - Receive buffer 2 full - Receive invalid - Transmit buffer 0 empty - Transmit buffer 1 empty - Transmit buffer 2 empty - Bus wakeup - Bus invalid error As other peripheral modules are developed, they will have interrupt sources. These sources will map into the 10 registers used in the control and status of interrupts. These registers are: • INTCON • INTCON1 • INTCON2 • INTCON3 • PIR1 • PIR2 • PIE1 • PIE2 • IPR1 • IPR2 The INTCON register contains the GIE/GIEH bit. This is the Global Interrupt Enable bit. When this bit is set, all interrupts are enabled. If needed for any single device, additional INTCON, PIR, PIE, and IPR registers will be defined. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-3 Section 10. Interrupts Interrupts 10 10.1.1 Interrupt Priority There are two interrupt vectors. One interrupt vector is for high priority interrupts and is located at address 000008h. The other interrupt vector is for low priority interrupts and is located at address 000018h. When a valid interrupt occurs, program execution vectors to one of these interrupt vector addresses and the corresponding Global Interrupt Enable bit (GIE, GIEH, or GIEL) is automatically cleared. In the interrupt service routine, the source(s) of the interrupt can be determined by testing the interrupt flag bits. The interrupt flag bit(s) must be cleared before re-enabling interrupts to avoid infinite interrupt requests. Most flag bits are required to be cleared by the application software. There are some flag bits that are automatically cleared by the hardware. When an interrupt condition is met, that individual interrupt flag bit will be set regardless of the status of its corresponding mask bit . For external interrupt events, such as the RB0/INT0 pin or PORTB change interrupt, the interrupt latency will be three or four instruction cycles. The exact latency depends when the interrupt event occurs. The interrupt latency is the same for one or two cycle instructions. The “return from interrupt” instruction, RETFIE, can be used to mark the end of the interrupt service routine. When this instruction is executed, the stack is “POPed” and the GIE bit is set (to re-enable interrupts). Figure 10-1: Interrupt Logic High Level Block Diagram T0IE GIEH/GIE GIEL/PEIE Wake-up if in SLEEP mode Interrupt to CPU Vector to location 0008h INT2F INT2E INT2P INT1F INT1E INT1P T0IF T0IE T0IP INT0F INT0E RBIF RBIE RBIP IPEN T0IF T0IP INT1F INT1E INT1P INT2F INT2E INT2P RBIF RBIE RBIP INT0F INT0E GIEL\PEIE IPEN IPEN Peripheral Interrupt Enable bit Peripheral Interrupt Flag bit Peripheral Interrupt Priority bit High Priority Interrupt Generation Low Priority Interrupt Generation Peripheral Interrupt Enable bit Peripheral Interrupt Flag bit Peripheral Interrupt Priority bit Additional Peripheral Interrupts Additional Peripheral Interrupts (If in SLEEP mode) High Priority Interrupt initialized (disable low priority interrupts) (High Priority Interrupt Vector Address) Interrupt to CPU Vector to Location 0018h (Low Priority Interrupt Vector Address) Wake-up 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-4  2000 Microchip Technology Inc. Figure 10-2: High Priority Interrupt Logic Block Diagram PSPIF PSPIE GIE/GIEH PEIE/GIEL Wake-up (If in SLEEP mode) Interrupt to CPU Vector to Location 00008h PSPIP ADIF ADIE ADIP RCIF RCIE RCIP TXIF TXIE TXIP SSPIF SSPIE SSPIP CCP1IF CCP1IE CCP1IP CCP2IF CCP2IE CCP2IP TMR1IF TMR1IE TMR1IP TMR2IF TMR2IE TMR2IP TMR3IF TMR3IE TMR3IP BCLIF BCLIE BCLIP LVDIF LVDIE LVDIP INT2IF INT2IE INT2IP INT1IF INT1IE INT1IP TMR0IF TMR0IE TMR0IP INT0IF INT0IE INT0IP RBIF RBIE RBIP IPEN To low priority interrupt logic 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-5 Section 10. Interrupts Interrupts 10 Figure 10-3: Low Priority Interrupt Logic Block Diagram TMR0IE TMR0IF TMR0IP INT1IF INT1IE INT1IP INT2IF INT2IE INT2IP RBIF RBIE RBIP INT0IF INT0IE INT0IP GIEL Wake-up (If in SLEEP Mode) Interrupt to CPU Vector to Location 00018h PSPIE PSPIP ADIF ADIE ADIP RCIF RCIE RCIP TXIF TXIE TXIP SSPIF SSPIE SSPIP CCP1IF CCP1IE CCP1IP CCP2IF CCP2IE CCP2IP TMR1IF TMR1IE TMR1IP TMR2IF TMR2IE TMR2IP TMR3IF TMR3IE TMR3IP BCLIF BCLIE BCLIP LVDIF LVDIE LVDIP (Low Priority Interrupt Vector Address) High priority interrupt initiated signal (Disable Low Priority Interrupts) IPEN 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-6  2000 Microchip Technology Inc. 10.2 Control Registers Generally devices have a minimum of four registers associated with interrupts. The INTCON register contains the Global Interrupt Enable bit, GIE, as well as the Peripheral Interrupt Enable bit, PEIE, the PIE / PIR register pair that enables the peripheral interrupts and displays the interrupt flag status, and the Interrupt Priority Register (IPR) that controls whether the interrupt source is a high priority or low priority interrupt. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-7 Section 10. Interrupts Interrupts 10 10.2.1 INTCON Register The INTCON Registers are readable and writable registers that contain various enable, priority, and flag bits. Register 10-1: INTCON Register R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-x GIE/GIEH PEIE/GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF bit 7 bit 0 bit 7 GIE/GIEH: Global Interrupt Enable bit When IPEN = 0: 1 = Enables all un-masked interrupts 0 = Disables all interrupts When IPEN = 1: 1 = Enables all interrupts 0 = Disables all interrupts bit 6 PEIE/GEIL: Peripheral Interrupt Enable bit When IPEN = 0: 1 = Enables all un-masked peripheral interrupts 0 = Disables all peripheral interrupts When IPEN = 1: 1 = Enables all low peripheral interrupts 0 = Disables all priority peripheral interrupts bit 5 TMR0IE: TMR0 Overflow Interrupt Enable bit 1 = Enables the TMR0 overflow interrupt 0 = Disables the TMR0 overflow interrupt bit 4 INT0IE: INT0 External Interrupt Enable bit 1 = Enables the INT0 external interrupt 0 = Disables the INT0 external interrupt bit 3 RBIE: RB Port Change Interrupt Enable bit 1 = Enables the RB port change interrupt 0 = Disables the RB port change interrupt bit 2 TMR0IF: TMR0 Overflow Interrupt Flag bit 1 = TMR0 register has overflowed (must be cleared in software) 0 = TMR0 register did not overflow bit 1 INT0IF: INT0 External Interrupt Flag bit 1 = The INT0 external interrupt occurred (must be cleared in software) 0 = The INT0 external interrupt did not occur bit 0 RBIF: RB Port Change Interrupt Flag bit 1 = At least one of the RB7:RB4 pins changed state (must be cleared in software) 0 = None of the RB7:RB4 pins have changed state Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note: Interrupt flag bits are set when an interrupt condition occurs, regardless of the state of its corresponding enable bit or the global enable bit. User software should ensure the appropriate interrupt flag bits are clear prior to enabling an interrupt. This feature allows for software polling. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-8  2000 Microchip Technology Inc. Register 10-2: INTCON2 Register R/W-1 R/W-1 R/W-1 R/W-1 U-0 R/W-1 U-0 R/W-1 RBPU INTEDG0 INTEDG1 INTEDG2 — TMR0IP — RBIP bit 7 bit 0 bit 7 RBPU: PORTB Pull-up Enable bit 1 = All PORTB pull-ups are disabled 0 = PORTB pull-ups are enabled by individual port latch values bit 6 INTEDG0:External Interrupt0 Edge Select bit 1 = Interrupt on rising edge 0 = Interrupt on falling edge bit 5 INTEDG1: External Interrupt1 Edge Select bit 1 = Interrupt on rising edge 0 = Interrupt on falling edge bit 4 INTEDG2: External Interrupt2 Edge Select bit 1 = Interrupt on rising edge 0 = Interrupt on falling edge bit 3 Unimplemented: Read as '1' bit 2 TMR0IP: TMR0 Overflow Interrupt Priority bit 1 = TMR0 Overflow Interrupt is a high priority event 0 = TMR0 Overflow Interrupt is a low priority event bit 1 Unimplemented: Read as '1' bit 0 RBIP: RB Port Change Interrupt Priority bit 1 = RB Port Change Interrupt is a high priority event 0 = RB Port Change Interrupt is a low priority event Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note: Interrupt flag bits are set when an interrupt condition occurs, regardless of the state of its corresponding enable bit or the global enable bit. User software should ensure the appropriate interrupt flag bits are clear prior to enabling an interrupt. This feature allows for software polling. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-9 Section 10. Interrupts Interrupts 10 Register 10-3: INTCON3 Register R/W-1 R/W-1 U-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 INT2IP INT1IP — INT2IE INT1IE — INT2IF INT1IF bit 7 bit 0 bit 7 INT2IP: INT2 External Interrupt Priority bit 1 = INT2 External Interrupt is a high priority event 0 = INT2 External Interrupt is a low priority event bit 6 INT1IP: INT1 External Interrupt Priority bit 1 = INT1 External Interrupt is a high priority event 0 = INT1 External Interrupt is a low priority event bit 5 Unimplemented: Read as '0' bit 4 INT2IE: INT2 External Interrupt Enable bit 1 = Enables the INT2 external interrupt 0 = Disables the INT2 external interrupt bit 3 INT1IE: INT1 External Interrupt Enable bit 1 = Enables the INT1 external interrupt 0 = Disables the INT1 external interrupt bit 2 Unimplemented: Read as '0' bit 1 INT2IF: INT2 External Interrupt Flag bit 1 = The INT2 external interrupt occurred (must be cleared in software) 0 = The INT2 external interrupt did not occur bit 0 INT1IF: INT1 External Interrupt Flag bit 1 = The INT1 external interrupt occurred (must be cleared in software) 0 = The INT1 external interrupt did not occur Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note: Interrupt flag bits are set when an interrupt condition occurs, regardless of the state of its corresponding enable bit or the global enable bit. User software should ensure the appropriate interrupt flag bits are clear prior to enabling an interrupt. This feature allows for software polling. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-10  2000 Microchip Technology Inc. 10.2.2 PIE Register(s) Depending on the number of peripheral interrupt sources, there may be multiple Peripheral Interrupt Enable registers (such as PIE1 and PIE2). These registers contain the individual enable bits for the peripheral interrupts. These registers will be generically referred to as PIE. Although the PIE register bits have a general bit location with each register, future devices may not have consistent placement. Bit location inconsistencies will not be a problem if you use the supplied Microchip Include files for the symbolic use of these bits. This will allow the Assembler/Compiler to automatically take care of the placement of these bits by specifying the correct Register number and bit name. Register 10-4: PIE Peripheral Interrupt Enable Registers Note: If the device has a PIE register and IPEN = 0, the PEIE bit must be set to enable any of the peripheral interrupts. R/W-0 (Note 1) bit 7 bit 0 bit TMR1IE: TMR1 Overflow Interrupt Enable bit 1 = Enables the TMR1 overflow interrupt 0 = Disables the TMR1 overflow interrupt bit TMR2IE: TMR2 to PR2 Match Interrupt Enable bit 1 = Enables the TMR2 to PR2 match interrupt 0 = Disables the TMR2 to PR2 match interrupt bit TMR3IE: TMR3 Overflow Interrupt Enable bit 1 = Enables the TMR3 overflow interrupt 0 = Disables the TMR3 overflow interrupt bit CCPxIE: CCPx Interrupt Enable bit 1 = Enables the CCPx interrupt 0 = Disables the CCPx interrupt bit ECCPxIE: Enhanced CCPx Interrupt Enable bit 1 = Enables the CCPx interrupt 0 = Disables the CCPx interrupt bit SSPIE: Synchronous Serial Port Interrupt Enable bit 1 = Enables the SSP interrupt 0 = Disables the SSP interrupt bit MSSPIE: Master Synchronous Serial Port Interrupt Enable bit 1 = Enables the MSSP interrupt 0 = Disables the MSSP interrupt bit RCIE: USART Receive Interrupt Enable bit 1 = Enables the USART receive interrupt 0 = Disables the USART receive interrupt bit TXIE: USART Transmit Interrupt Enable bit 1 = Enables the USART transmit interrupt 0 = Disables the USART transmit interrupt bit IRXIE: CAN Invalid Received message Interrupt Enable bit 1 = Enable invalid message received interrupt 0 = Disable invalid message received interrupt bit WAKIE: CAN Bus Activity Wake-up Interrupt Enable bit 1 = Enable Bus Activity Wake-up Interrupt 0 = Disable Bus Activity Wake-up Interrupt bit ERRIE: CAN bus Error Interrupt Enable bit 1 = Enable CAN bus Error Interrupt 0 = Disable CAN bus Error Interrupt 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-11 Section 10. Interrupts Interrupts 10 bit TXB2IE: CAN Transmit Buffer 2 Interrupt Enable bit 1 = Enable Transmit Buffer 2 Interrupt 0 = Disable Transmit Buffer 2 Interrupt bit TXB1IE: CAN Transmit Buffer 1 Interrupt Enable bit 1 = Enable Transmit Buffer 1 Interrupt 0 = Disable Transmit Buffer 1 Interrupt bit TXB0IE: CAN Transmit Buffer 0 Interrupt Enable bit 1 = Enable Transmit Buffer 0 Interrupt 0 = Disable Transmit Buffer 0 Interrupt bit RXB1IE: CAN Receive Buffer 1 Interrupt Enable bit 1 = Enable Receive Buffer 1 Interrupt 0 = Disable Receive Buffer 1 Interrupt bit RXB0IE: CAN Receive Buffer 0 Interrupt Enable bit 1 = Enable Receive Buffer 0 Interrupt 0 = Disable Receive Buffer 0 Interrupt bit ADIE: A/D Converter Interrupt Enable bit 1 = Enables the A/D interrupt 0 = Disables the A/D interrupt bit PSPIE: Parallel Slave Port Read/Write Interrupt Enable bit 1 = Enables the PSP read/write interrupt 0 = Disables the PSP read/write interrupt bit EEIE: EE Write Complete Interrupt Enable bit 1 = Enables the EE write complete interrupt 0 = Disables the EE write complete interrupt bit CMIE: Comparator Interrupt Enable bit 1 = Enables the Comparator interrupt 0 = Disables the Comparator interrupt bit BCLIE: Bus Collision Interrupt Enable bit 1 = Enabled 0 = Disabled bit LVDIE: Low-voltage Detect Interrupt Enable bit 1 = Enabled 0 = Disabled Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note 1: The bit position of the enable bits is device dependent. Please refer to the device data sheet for bit placement. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-12  2000 Microchip Technology Inc. 10.2.3 PIR Register(s) Depending on the number of peripheral interrupt sources, there may be multiple Peripheral Interrupt Flag registers (PIR1, PIR2). These registers contain the individual flag bits for the peripheral interrupts. These registers will be generically referred to as PIR. Although the PIR bits have a general bit location within each register, future devices may not have consistent placement. It is recommended that you use the supplied Microchip Include files for the symbolic use of these bits. This will allow the Assembler/Compiler to automatically take care of the placement of these bits within the specified register. Note 1: Interrupt flag bits are set when an interrupt condition occurs, regardless of the state of its corresponding enable bit or the global enable bit, GIE (INTCON<7>). Note 2: User software should ensure the appropriate interrupt flag bits are cleared prior to enabling an interrupt and after servicing that interrupt. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-13 Section 10. Interrupts Interrupts 10 Register 10-5: PIR Register R/W-0 (Note 1) bit 7 bit 0 bit TMR1IF: TMR1 Overflow Interrupt Flag bit 1 = TMR1 register overflowed (must be cleared in software) 0 = TMR1 register did not overflow bit TMR2IF: TMR2 to PR2 Match Interrupt Flag bit 1 = TMR2 to PR2 match occurred (must be cleared in software) 0 = No TMR2 to PR2 match occurred bit TMR3IF: TMR3 Overflow Interrupt Flag bit 1 = TMR3 register overflowed (must be cleared in software) 0 = TMR3 register did not overflow bit CCPxIF: CCPx Interrupt Flag bit Capture Mode 1 = A TMR1 register capture occurred (must be cleared in software) 0 = No TMR1 register capture occurred Compare Mode 1 = A TMR1 register compare match occurred (must be cleared in software) 0 = No TMR1 register compare match occurred PWM Mode Unused in this mode bit ECCPxIF: Enhanced CCPx Interrupt Flag bit Capture Mode 1 = A TMR1 register capture occurred (must be cleared in software) 0 = No TMR1 register capture occurred Compare Mode 1 = A TMR1 register compare match occurred (must be cleared in software) 0 = No TMR1 register compare match occurred PWM Mode Unused in this mode 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-14  2000 Microchip Technology Inc. bit IRXIF: CAN Invalid Received message Interrupt Flag bit 1 = An invalid message has occurred on the CAN bus 0 = No invalid message on CAN bus bit WAKIF: CAN Bus Activity Wake-up Interrupt Flag bit 1 = Activity on CAN bus has occurred 0 = No activity on CAN bus bit ERRIF: CAN bus Error Interrupt Flag bit 1 = An error has occurred in the CAN module (multiple sources) 0 = No CAN module errors bit TXB2IF: CAN Transmit Buffer 2 Interrupt Flag bit 1 = Transmit Buffer 2 has completed transmission of a message, and may be re-loaded 0 = Transmit Buffer 2 has not completed transmission of a message bit TXB1IF: CAN Transmit Buffer 1 Interrupt Flag bit 1 = Transmit Buffer 1 has completed transmission of a message, and may be re-loaded 0 = Transmit Buffer 1 has not completed transmission of a message bit TXB0IF: CAN Transmit Buffer 0 Interrupt Flag bit 1 = Transmit Buffer 0 has completed transmission of a message, and may be re-loaded 0 = Transmit Buffer 0 has not completed transmission of a message bit RXB1IF: CAN Receive Buffer 1 Interrupt Flag bit 1 = Receive Buffer 1 has received a new message 0 = Receive Buffer 1 has not received a new message bit RXB0IF: CAN Receive Buffer 0 Interrupt Flag bit 1 = Receive Buffer 0 has received a new message 0 = Receive Buffer 0 has not received a new message bit SSPIF: Synchronous Serial Port Interrupt Flag bit 1 = The transmission/reception is complete (must be cleared in software) 0 = Waiting to transmit/receive bit MSSPIF: Master Synchronous Serial Port Interrupt Flag bit 1 = The transmission/reception is complete (must be cleared in software) 0 = Waiting to transmit/receive bit RCIF: USART Receive Interrupt Flag bit 1 = The USART receive buffer, RCREG, is full (cleared when RCREG is read) 0 = The USART receive buffer is empty bit TXIF: USART Transmit Interrupt Flag bit 1 = The USART transmit buffer, TXREG, is empty (cleared when TXREG is written) 0 = The USART transmit buffer is full 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-15 Section 10. Interrupts Interrupts 10 bit ADIF: A/D Converter Interrupt Flag bit 1 = An A/D conversion completed (must be cleared in software) 0 = The A/D conversion is not complete bit PSPIF: Parallel Slave Port Read/Write Interrupt Flag bit 1 = A read or a write operation has taken place (must be cleared in software) 0 = No read or write has occurred bit EEIF: EE Write Complete Interrupt Flag bit 1 = The data EEPROM write operation is complete (must be cleared in software) 0 = The data EEPROM write operation is not complete bit CMIF: Comparator Interrupt Flag bit 1 = Comparator input has changed (must be cleared in software) 0 = Comparator input has not changed bit BCLIF: Bus Collision Interrupt Flag bit 1 = A Bus Collision occurred (must be cleared in software) 0 = No Bus Collision occurred bit LVDIF: Low-voltage Detect Interrupt Flag bit 1 = A Low Voltage condition occurred (must be cleared in software) 0 = The device voltage is above the Low Voltage Detect trip point Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note 1: The bit position of the enable bits is device dependent. Please refer to the device data sheet for bit placement. 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-16  2000 Microchip Technology Inc. 10.2.4 IPR Register Depending on the number of peripheral interrupt sources, there may be multiple Peripheral Interrupt Priority registers (such as IPR1 and IPR2). These registers contain the individual priority bits for the peripheral interrupts. These registers will be generically referred to as IPR. If the device has an IPR register and IPEN = 0, the PEIE bit must be set to enable any of these peripheral interrupts. Although the IPR register bits have a general bit location with each register, future devices may not have consistent placement. Bit location inconsistencies will not be a problem if you use the supplied Microchip Include files for the symbolic use of these bits. This will allow the Assembler/Compiler to automatically take care of the placement of these bits by specifying the correct register and bit name. Register 10-6:IPR Peripheral Interrupt Priority Register Note: The IP bit specifies the priority of the peripheral interrupt. R/W-0 (Note 1) bit 7 bit 0 bit TMR1IP: TMR1 Overflow Interrupt Priority bit 1 = TMR1 Overflow Interrupt is a high priority event 0 = TMR1 Overflow Interrupt is a low priority event bit TMR2IP: TMR2 to PR2 Match Interrupt Priority bit 1 = TMR2 to PR2 Match Interrupt is a high priority event 0 = TMR2 to PR2 Match Interrupt is a low priority event bit TMR3IP: TMR3 Overflow Interrupt Priority bit 1 = TMR3 Overflow Interrupt is a high priority event 0 = TMR3 Overflow Interrupt is a low priority event bit CCPxIP: CCPx Interrupt Priority bit 1 = CCPx Interrupt is a high priority event 0 = CCPx Interrupt is a low priority event bit ECCPxIP: Enhanced CCPx Interrupt Priority bit 1 = Enhanced CCPx Interrupt is a high priority event 0 = Enhanced CCPx Interrupt is a low priority event bit MSSPIP: Master Synchronous Serial Port Interrupt Priority bit 1 = Master Synchronous Serial Port Interrupt is a high priority event 0 = Master Synchronous Serial Port Interrupt is a low priority event bit SSPIP: Synchronous Serial Port Interrupt Priority bit 1 = Synchronous Serial Port Interrupt is a high priority event 0 = Synchronous Serial Port Interrupt is a low priority event bit RCIP: USART Receive Interrupt Priority bit 1 = USART Receive Interrupt is a high priority event 0 = USART Receive Interrupt is a low priority event bit TXIP: USART Transmit Interrupt Priority bit 1 = USART Transmit Interrupt is a high priority event 0 = USART Transmit Interrupt is a low priority event bit ADIP: A/D Converter Interrupt Priority bit 1 = A/D Converter Interrupt is a high priority event 0 = A/D Converter Interrupt is a low priority event bit PSPIP: Parallel Slave Port Read/Write Interrupt Priority bit 1 = Parallel Slave Port Read/Write Interrupt is a high priority event 0 = Parallel Slave Port Read/Write Interrupt is a low priority event 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-17 Section 10. Interrupts Interrupts 10 bit IRXIP: CAN Invalid Received message Interrupt Priority bit 1 = CAN Invalid Received message Interrupt is a high priority event 0 = CAN Invalid Received message Interrupt is a low priority event bit WAKIP: CAN Bus Activity Wake-up Interrupt Priority bit 1 = CAN Bus Activity Wake-up Interrupt is a high priority event 0 = CAN Bus Activity Wake-up Interrupt is a low priority event bit ERRIP: CAN bus Error Interrupt Priority bit 1 = CAN bus Error Interrupt is a high priority event 0 = CAN bus Error Interrupt is a low priority event bit TXB2IP: CAN Transmit Buffer 2 Interrupt Priority bit 1 = CAN Transmit Buffer 2 Interrupt is a high priority event 0 = CAN Transmit Buffer 2 Interrupt is a low priority event bit TXB1IP: CAN Transmit Buffer 1 Interrupt Priority bit 1 = CAN Transmit Buffer 1 Interrupt is a high priority event 0 = CAN Transmit Buffer 1 Interrupt is a low priority event bit TXB0IP: CAN Transmit Buffer 0 Interrupt Priority bit 1 = CAN Transmit Buffer 0 Interrupt is a high priority event 0 = CAN Transmit Buffer 0 Interrupt is a low priority event bit RXB1IP: CAN Receive Buffer 1 Interrupt Priority bit 1 = CAN Receive Buffer 1 Interrupt is a high priority event 0 = CAN Receive Buffer 1 Interrupt is a low priority event bit RXB0IP: CAN Receive Buffer 0 Interrupt Priority bit 1 = CAN Receive Buffer 0 Interrupt is a high priority event 0 = CAN Receive Buffer 0 Interrupt is a low priority event bit EEIP: EE Write Complete Interrupt Priority bit 1 = EE Write Complete Interrupt is a high priority event 0 = EE Write Complete Interrupt is a low priority event bit CMIP: Comparator Interrupt Priority bit 1 = Comparator Interrupt is a high priority event 0 = Comparator Interrupt is a low priority event bit BCLIP: Bus Collision Interrupt Priority bit 1 = Bus Collision Interrupt is a high priority event 0 = Bus Collision Interrupt is a low priority event bit LVDIP: Low-voltage Detect Interrupt Priority bit 1 = Low-voltage Detect Interrupt is a high priority event 0 = Low-voltage Detect Interrupt is a low priority event Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note 1: The bit position of the priority bits is device dependent. Please refer to the device data sheet for bit placement. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-18  2000 Microchip Technology Inc. 10.2.5 RCON Register The RCON register contains the bit that is used to enable prioritized interrupts (IPEN) as well as status bits to indicate the cause of a device reset, if the device was in sleep mode and if long writes to internal memory are enabled. Register 10-7: RCON Register R/W-0 R/W-0 U-0 R/W-1 R/W-1 R/W-1 R/W-0 R/W-0 IPEN LWRT — RI TO PD POR BOR bit 7 bit 0 bit IPEN: Interrupt Priority Enable bit 1 = Enable priority levels (high and low) on interrupts 0 = Disable priority levels (all peripherals are high) on interrupts (PIC16CXXX compatibility) (This causes the Interrupt Priority (IP) bits to be ignored) bit 6 LWRT: Long Write Enable For details of bit operation see description of RCON register bit in Register 3-2 bit 5 Unimplemented: Read as '0' bit 4 RI: Reset Instruction Flag bit For details of bit operation see description of RCON register bit in Register 3-2 bit 3 TO: Watchdog Time-out Flag bit For details of bit operation see description of RCON register bit in Register 3-2 bit 2 PD: Power-down Detection Flag bit For details of bit operation see description of RCON register bit in Register 3-2 bit 1 POR: Power-on Reset Status bit For details of bit operation see description of RCON register bit in Register 3-2 bit 0 BOR: Brown-out Reset Status bit For details of bit operation see description of RCON register bit in Register 3-2 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-19 Section 10. Interrupts Interrupts 10 10.3 Interrupt Handling Operation The interrupts are controlled and monitored using several Special Function Registers. These may include the following register types: • INTCON registers • PIR registers • PIE registers • IPR registers The PIR registers contain the interrupt flag bits, the PIE registers contain the enable bits and the IPR registers contain the priority bits. The number of PIR, PIE, and IPR registers depends on the number of interrupt sources on the device. 10.3.1 Interrupt Priority Each interrupt can be assigned a priority level by clearing or setting the corresponding interrupt priority bit. The priority bits are located in the interrupt priority registers (IPR1, IPR2, IPR3, INTCON2 and INTCON3). A ‘1’ in the priority register assigns high priority to the corresponding interrupt. A ’0’ in the register assigns low priority to the interrupt. All interrupt priority bits are reset to ’1’, meaning that all interrupts are assigned high priority at reset. The IPEN bit in the RCON register enables priority levels for interrupts. If clear, all priorities are set to high. 10.3.1.1 High Priority Interrupts A global interrupt enable bit, GIE/GIEH (INTCON<7>) enables (if set) all un-masked interrupts or disables (if cleared) all interrupts. When bit GIE/GIEH is enabled and an interrupt’s flag bit and enable bit are set while the priority is high, the interrupt will vector immediately. Individual interrupts can be disabled through their corresponding enable bits in various registers. Individual interrupt flag bits are set, regardless of the status of the GIE/GIEH bit. The GIE/GIEH bit is cleared on reset. When a high priority interrupt is responded to, the GIE/GIEH bit is automatically cleared to disable any further interrupts, the return address is pushed onto the stack, and the PC is loaded with 000008h. Once in the interrupt service routine, the source of the interrupt can be determined by polling the interrupt flag bits. The interrupt flag bit(s) must be cleared before re-enabling interrupts to avoid recursive interrupts. Most flag bits are required to be cleared by the application software. There are some flag bits that are automatically cleared by the hardware. The “return from interrupt” instruction, RETFIE, exits the interrupt routine and sets the GIE/GIEH bit, which re-enables high priority interrupts. 10.3.1.2 Low Priority Interrupts Low priority interrupts are defined by having a “0” in an interrupt priority register IPRx. To enable low priority interrupts, the IPEN bit must be set. When the IPEN is set, the PEIE/GIEL bit (INTCON<6>) is no longer used to enable peripheral interrupts. Its new function is to globally enable and disable low priority interrupts only. When the service routine for a low priority interrupt is vectored to, the PEIE/GIEL bit is automatically cleared in hardware to disable any further low priority interrupts. The return address is pushed onto the stack and the PC is loaded with 000018h instead of 000008h (all low priority interrupts will vector to 000018h). Once in the interrupt service routine, the source(s) of the low priority interrupt can be determined by polling the low priority interrupt flag bits. The interrupt flag bit(s) must be cleared before re-enabling interrupts to avoid recursive interrupts. Most flag bits are required to be cleared by the application software. There are some flag bits that are automatically cleared by the hardware. The RETFIE instruction will reset the PEIE/GIEL bit on return from low priority interrupts. The GIE/GIEH bit’s function has not changed in that it still enables/disables all interrupts, however, it is only cleared by hardware when servicing a high priority interrupt. 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-20  2000 Microchip Technology Inc. 10.3.1.3 High Priority Interrupts Interrupting a Low Priority ISR If a high priority interrupt flag and enable bits are set while servicing a low priority interrupt, the high priority interrupt will cause the low priority ISR to be interrupted (regardless of the state of the PEIE/GIEL bit), because it is used to disable/enable low priority interrupts only. The GIE/GIEH bit is cleared by hardware to disable any further high and low priority interrupts, the return address is pushed onto the stack, and the PC is loaded with 000008h (the high priority interrupt vector). Once in the interrupt service routine, the source of the high priority interrupt can be determined by polling the interrupt flag bits. The interrupt flag bit(s) must be cleared in software before re-enabling interrupts to avoid recursive interrupts. Figure 10-4 shows a high priority interrupt interrupting a low priority ISR. Figure 10-5 shows a high priority FSR with a low priority interrupt pending. Figure 10-4: Low Priority ISR Interrupted By High Priority Interrupt Figure 10-5: High Priority Interrupt With Pending Low Priority Interrupt Note: The GIEH bit, when cleared, will disable all interrupts regardless of priority. Q1 Q2Q3 Q4 Q1 Q2Q3 Q4 Q1 Q2Q3 Q4 Q1 Q2Q3 Q4 Q1 Q2Q3 Q4 Q1 Q2Q3 Q4 Q1 Q2Q3 Q4 Q1 Q2Q3 Q4 Q1 Q2Q3 Q4 Q1 Q2Q3 Q4 OSC1 CLKOUT INT2 pin INT2IF PEIE/GIEL Program Counter PC PC + 2 (low priority) INT0 pin INT0IF GIE/GIEH (high priority) PC + 2 Inst(0018h) 0018h 001Ah 001Ch 001Ch 0008h 000Ah 000Ch Inst(PC) Inst(PC - 2) Inst(PC + 2) Inst(PC) Inst(001Ah) Inst(0018h) Instruction Fetched Instruction Executed Dummy Dummy Vector to High Priority ISR High Priority Interrupt Occurs Here Inst(001Ah) Inst(001Ch) Inst(0008h) Dummy Dummy Inst(000Ah) Inst(0008h) Inst(000Ah) Inst(000Ch) Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 OSC1 CLKOUT INT0 pin INT0IF GIE/GIEH Program Counter PC PC + 2 (high priority) INT2 pin INT2IF PEIE/GIEL (low priority) PC + 2 Inst(0008h) 0008h 000Ah 000Ch 000Eh PC + 2 PC + 2 0018h Inst(PC) Inst(PC - 2) Inst(PC + 2) Inst(PC) Inst(000Ah) Inst(0008h) Instruction Instruction Dummy Dummy RETFIE Inst(000Ah) Inst(000Eh) RETFIE Dummy Dummy Fetched Executed Q1Q2 Q3 Q4 001Ah Inst(PC+2) Dummy Inst(0018h) Vector to Low Priority Interrupt Vector to High Priority Interrupt Return from High Priority Interrupt Inst(PC+2) Inst(0018h) Inst(001Ah) 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-21 Section 10. Interrupts Interrupts 10 Figure 10-6 and Figure 10-7 show the two cases where a low priority interrupt has occurred and then a high priority interrupt occurs before the low priority ISR can begin execution. Figure 10-8 shows the first instruction of the low priority interrupt (at address 18h) beginning execution, when the high priority interrupt causes the program counter to be forced to the high priority interrupt vector address (08h). Figure 10-6: Low Interrupt With High Interrupt Within 1 Cycle Figure 10-7: Low Interrupt With High Interrupt Within 2 Cycles Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 OSC1 CLKOUT Program Counter PC INT2 pin INT2IF PEIE/GIEL (low priority) PC PC - 2 Instruction Instruction Fetched Executed Q1 Q2 Q3Q4 INT0 pin INT0IF GIE/GIEH (high priority) PC + 2 PC - Dummy - Dummy 0008h Dummy 000Ah 0008h RETFIE 000Ah 000Eh RETFIE 0018h Dummy 001Ah 0018h 001Ch 0018h PC + 2 PC + 2 0018h 0008h 000Ah 000Ch 000Eh 0018h 001Ah 001Ch Begin Vector to Low Priority Interrupt Return from High Priority Interrupt Vector to High Priority Interrupt to Low Priority ISR Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 OSC1 CLKOUT Program Counter PC INT2 pin INT2IF PEIE/GIEL (low priority) PC PC - 2 Instruction Instruction Fetched Executed Q1 Q2 Q3Q4 INT0 pin INT0IF GIE/GIEH (high priority) PC + 2 PC - Dummy 0018h Dummy - Dummy 0008h Dummy 000Ah 0008h RETFIE 000Ah 000Eh RETFIE 0018h Dummy 001Ah 0018h PC + 2 PC + 2 0018h 0018h 0008h 000Ah 000Ch 000Eh 0018h 001Ah Vector to Low Priority Interrupt Vector to High Priority Interrupt Interrupt to Low Priority ISR High Priority Return from 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-22  2000 Microchip Technology Inc. Figure 10-8: Low Interrupt With High Interrupt Within 3 Cycles Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 OSC1 CLKOUT Program Counter PC INT2 pin INT2IF PEIE/GIEL (low priority) PC PC - 2 Instruction Instruction Fetched Executed Q1Q2 Q3 Q4 INT0 pin INT0IF GIE/GIEH (high priority) PC + 2 PC - Dummy 0018h Dummy 001Ah 0018h - Dummy 0008h Dummy RETFIE 0008h 000Ch RETFIE 001Ah Dummy 001Ch 001Ah PC + 2 PC + 2 0018h 001Ah 001Ah 0008h 000Ah 000Ch 001Ah 001Ch Vector to High Priority Interrupt Vector to Low Priority Interrupt Return from Interrupt to Low Priority ISR High Priority 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-23 Section 10. Interrupts Interrupts 10 10.3.1.4 Low Priority Interrupts Interrupting a High Priority ISR A low priority interrupt cannot interrupt a high priority ISR. The low priority interrupt will be served after all high priority interrupts have been served. 10.3.1.5 Simultaneous High and Low Priority Interrupts If a high priority interrupt and a low priority interrupt are sampled at the same time, the high priority interrupt service routine is always serviced first. The GIE/GIEH bit is cleared by the hardware and the device vectors to location 000008h to the high priority ISR. After the interrupt is serviced, the corresponding interrupt flag should be cleared to avoid a recursive interrupt. The RETFIE instruction resets the GIE/GIEH bit, and if no other high priority interrupts are pending, the low priority interrupt is serviced. 10.3.1.6 Fast Context Saving During High Priority Interrupts A "fast interrupt service" option is available for high priority interrupts. This is done by creating shadow registers for a few key registers (WREG, BSR and STATUS). Shadow registers are provided for the STATUS, WREG, and BSR registers and are only 1 deep. The shadow registers are not readable and are loaded with the current value of their corresponding register when the processor vectors for a high priority interrupt. The values in the shadow registers are then loaded back into the actual register if the fast return instruction (RETFIE 0x01) is used to return from the interrupt. An example for fast context saving is shown in Example 10-1. Example 10-1: Fast Context Saving ORG 0x08 ; ; Interrupt Service Routine (ISR) code. WREG, BSR and STATUS need ; to be saved upon entering the high priority interrupt service routine ; RETFIE 0x01 ; WREG, BSR and STATUS will be restored Note: Fast interrupt saving cannot be used reliably if high and low priority interrupts are enabled. See Section 10.3.1.7. 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-24  2000 Microchip Technology Inc. 10.3.1.7 Context Saving During Low Priority Interrupts Low priority interrupts may use the shadow registers. Any interrupt pushes values into the shadow registers. If both low and high priority interrupts are enabled, the shadow registers cannot be used reliably for low priority interrupts, as a high priority interrupt event will overwrite the shadow registers. Users must save the key registers in software during a low priority interrupt. For example: a) Store the STATUS, WREG and BSR registers on a software stack. b) Execute the ISR code. c) Restore the STATUS, WREG and BSR registers from the software stack. 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-25 Section 10. Interrupts Interrupts 10 Example 10-2 shows example service routine code for when high and low priority interrupts are enabled. Example 10-2: Interrupt Service Routine Template ORG 0x08 ; high priority ISR PUSH_REG_H MOVWF WREG_TEMP_HIGH MOVFF BSR, BSR_TEMP_HIGH MOVFF STATUS, STATUS_TEMP_HIGH ; ; High Priority Interrupt Service Routine (ISR) Code goes here ; POP_REG_H MOVFF BSR_TEMP_HIGH, BSR MOVF WREG_TEMP_HIGH, W MOVFF STATUS_TEMP_HIGH, STATUS RETFIE 0x00 ; PUSH_REG_L ORG 0x18 ; Low Priority ISR MOVWF WREG_TEMP_LOW MOVFF BSR, BSR_TEMP_LOW MOVFF STATUS, STATUS_TEMP_LOW ; ; Low Priority Interrupt Service Routine (ISR) code goes here ; Pop_REG_L MOVFF BSR_TEMP_LOW, BSR MOVF WREG_TEMP_LOW MOVFF STATUS_TEMP_LOW, STATUS RETFIE 0x00 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-26  2000 Microchip Technology Inc. 10.3.1.8 Interrupt Latency For external interrupt events, such as the RB0/INT0 pin or PORTB change interrupt, the interrupt latency will be three or four instruction cycles. The exact latency depends when the interrupt event occurs. The interrupt latency is the same for one or two cycle instructions. 10.3.1.8.1 Interrupt Latency For One Cycle Instructions Figure 10-9 shows the timing when an external interrupt is asserted during a one cycle instruction. The interrupt is sampled on Q4. The interrupt is then acknowledged on the Q2 cycle of the following instruction cycle when instruction PC is executed. This is followed by a forced NOP (dummy cycle) and the contents of the PC are stored on the stack during the Q3 cycle of this machine cycle. By the Q3/Q4 boundary of instruction cycle two, the interrupt vector is placed into the PC, and is presented on the program memory bus on the following cycle. This cycle is also a dummy cycle executing a forced NOP (FNOP) so that the CPU can fetch the first instruction from the interrupt service routine. Figure 10-9: Interrupt Flow on a 1 Cycle Instruction INST(PC) Executed here FNOP Executed here FNOP Executed here PC PC PC+2 PC+2 PC+3 000Ch INTxIF flag INST (PC) INST (PC+2) INST (0008h) 0008h 000Ah INST (000Ah) INST (PC+2) INST(PC-1) Executed here INST(0008h) Executed here INST(000Ah) Executed here Inst Fetched STACK RAM register Inst Execute GIE/GIEH bit 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-27 Section 10. Interrupts Interrupts 10 10.3.1.8.2 Interrupt Latency For Two Cycle Instructions Figure 10-10 shows the timing when an external interrupt is asserted during a two cycle instruction. The interrupt is sampled on Q4. The interrupt is then acknowledged on the Q1 of the following instruction cycle when instruction PC is executed. This is followed by the second cycle of the instruction and the contents of the PC are stored on the stack during Q3 of this machine cycle. For all two cycle instructions, the PC may be updated with a new PC value due to execution control instructions like GOTO and CALL. The reason for the forced NOP (dummy cycle) is to maintain consistent interrupt latency between one and two cycle instructions. Two cycle instructions require this cycle for the update of the PC to a new PC value, because all two cycle instructions with the exception of MOVFF and MOVLF are execution control type instructions that update the PC with a new value (i.e. GOTO and CALL). The MOVFF and MOVLF instructions will increment the PC by 2 in this cycle because an operand fetch takes place in the second cycle. By Q3/Q4 the interrupt vector 000008h is placed into the PC and is presented on the program memory bus on the following cycle. This cycle is a dummy cycle executing a forced NOP (FNOP) so that the CPU can fetch the first instruction from the interrupt service routine. Figure 10-10:Interrupt Flow on a 2 Cycle or 2 Word Instruction Note: When using the MOVFF instruction with any one of the PCL, TOSU, TOSH, and TOSL registers as destination, all interrupts have to be disabled. INST(PC) Executed here CYCLE 2 Executed here FNOP Executed here PC PC PC+2 New PC PC+3 000Ch INTxIF flag INST (PC) INST (New PC) INST (0008h) 0008h 000Ah INST (PC+2) INST (000Ah) INST(PC-2) Executed here INST(0008h) Executed here INST(000Ah) Executed here Inst Fetched STACK RAM register Inst Execute GIE/GIEH bit 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-28  2000 Microchip Technology Inc. 10.3.1.9 InTerrupts During Table Write Operations (Long Writes) The long write is necessary for programming the internal EPROM. Instruction execution is halted while in a long write cycle. The long write will be terminated by any enabled interrupt. To ensure that the EPROM location has been well programmed, a minimum programming time is required. Typically, a Timer interrupt is used to time and terminate the long write. Having only one interrupt enabled to terminate the long write ensures that no unintended interrupts will prematurely terminate the long write. Figure 10-11:INT0, INT1, and INT2 Pin Interrupt Timing (High Priority Shown) Q1 Q3 Q4 Q2 Q1 Q3 Q4 Q2 Q1 Q3 Q4 Q2 Q2Q1 Q3 Q4 Q1 Q3 Q4 Q2 OSC1 CLKOUT INT pin INTxIF flag GIE/GIEH bit (INTCON<7>) INSTRUCTION FLOW PC Instruction fetched Instruction executed Interrupt Latency PC PC+2 PC+2 0008h 000Ah Inst (0008h) Inst (000Ah) Dummy Cycle Inst (PC) Inst (PC+2) Inst (PC-2) Dummy Cycle Inst (0008h) Inst (PC) — 1 4 5 1 2 3 Note 1: INTxIF flag is sampled here (every Q1). Note 2: Interrupt latency = 3-4TCY where TCY = instruction cycle time. Latency is the same whether Inst (PC) is a single cycle or a 2-cycle instruction. Note 3: CLKOUT is available only in RC oscillator mode. Note 4: For minimum width of INT pulse, refer to AC specs. Note 5: INTxIF is enabled to be set anytime during the Q1 cycle. 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-29 Section 10. Interrupts Interrupts 10 10.4 Initialization Example 10-3 enables high and low priority interrupts. The priority level for the peripherals is loaded into the IRP1 register (IRP1_VALUE) and the peripherals that are enabled depend on the value of PIE1_VALUE, which is loaded into the PIE1 register. Example 10-3: Generic Initialization Example MOVLW RCON_VALUE ; RCON_VALUE = 1???????b MOVWF RCON ; MOVLW IPR1_VALUE ; Peripherals with high priority ; have a ’1’ in their bit ; position. ; Those with a low priority have ; a ’0’ in their bit position. MOVWF IRP1 ; CLRF PIR1 ; Clear all flag bits MOVLW PIE1_VALUE ; Enable desired peripheral ; interrupts by setting their ; bit position. ; Disable others by clearing their ; bit position. MOVWF PIE1 ; CLRF INTCON3 ; CLRF INTCON2 ; MOVLW OxC0 ; Enable high and low global ; interrupts. MOVWF INTCON ; 39500 18C Reference Manual.book Page 29 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-30  2000 Microchip Technology Inc. 10.5 Design Tips Question 1: My code does not seem to execute properly. Answer 1: There are many possible reasons. A couple of possibilities related to Interrupts are: • Interrupts are not enabled, so the code cannot execute your expected ISR. • The Interrupt may not be set to the priority level where your ISR code is located. 39500 18C Reference Manual.book Page 30 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39510A-page 10-31 Section 10. Interrupts Interrupts 10 10.6 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Base-Line, the Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the interrupts are: Title Application Note # No related application notes at this time. Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 31 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39510A-page 10-32  2000 Microchip Technology Inc. 10.7 Revision History Revision A This is the initial released revision of the Enhanced MCU Interrupt description. 39500 18C Reference Manual.book Page 32 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-1 I/O Ports 11 Section 11. I/O Ports HIGHLIGHTS This section of the manual contains the following major topics: 11.1 Introduction .................................................................................................................. 11-2 11.2 PORTA, TRISA, and the LATA Register ....................................................................... 11-8 11.3 PORTB, TRISB, and the LATB Register..................................................................... 11-12 11.4 PORTC, TRISC, and the LATC Register .................................................................... 11-16 11.5 PORTD, LATD, and the TRISD Register .................................................................... 11-19 11.6 PORTE, TRISE, and the LATE Register .................................................................... 11-21 11.7 PORTF, LATF, and the TRISF Register ...................................................................... 11-23 11.8 PORTG, LATG, and the TRISG Register ................................................................... 11-25 11.9 PORTH, LATH, and the TRISH Register.................................................................... 11-27 11.10 PORTJ, LATJ, and the TRISJ Register ...................................................................... 11-29 11.11 PORTK, LATK, and the TRISK Register .................................................................... 11-31 11.12 PORTL, LATL, and the TRISL Register...................................................................... 11-33 11.14 I/O Programming Considerations ............................................................................... 11-37 11.15 Initialization ................................................................................................................ 11-40 11.16 Design Tips ................................................................................................................ 11-41 11.17 Related Application Notes.......................................................................................... 11-43 11.18 Revision History ......................................................................................................... 11-44 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-2  2000 Microchip Technology Inc. 11.1 Introduction General purpose I/O pins can be considered the simplest of peripherals. They allow the PICmicro to monitor and control other devices. To add flexibility and functionality to a device, some pins are multiplexed with an alternate function(s). These functions depend on which peripheral features are on the device. In general, when a peripheral is functioning, that pin may not be used as a general purpose I/O pin. For most ports, the I/O pin’s direction (input or output) is controlled by the data direction register, called the TRIS register. TRIS controls the direction of PORT. A ’1’ in the TRIS bit corresponds to that pin being an input, while a ’0’ corresponds to that pin being an output. An easy way to remember is that a ’1’ looks like an I (input) and a ’0’ looks like an O (output). The PORT register is the latch for the data to be output. When the PORT is read, the device reads the levels present on the I/O pins (not the latch). This means that care should be taken with read-modify-write commands on the ports and changing the direction of a pin from an input to an output. Figure 11-1 shows a typical I/O port. This does not take into account peripheral functions that may be multiplexed onto the I/O pin. Reading the PORT register reads the status of the pins whereas writing to it will write to the port latch. All write operations (such as BSF and BCF instructions) are read-modify-write operations. Therefore, a write to a port implies that the port pins are read, this value is modified, and then written to the port data latch. Figure 11-1: Typical I/O Port Data Bus WR PORT WR TRIS RD PORT Data Latch TRIS Latch P VSS I/O pin D Q CK Q D Q CK Q Q D EN N VDD RD TRIS Schmitt Trigger TTL or RD LAT Note : I/O pins have protection diodes to VDD and VSS. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-3 Section 11. I/O Ports I/O Ports 11 When peripheral functions are multiplexed onto general I/O pins, the functionality of the I/O pins may change to accommodate the requirements of the peripheral module. An example of this is the Analog to Digital converter module which forces the I/O pin to the peripheral function when the device is reset. This prevents the device from consuming excess current if any analog levels were on the A/D pins after a reset occurred. With some peripherals, the TRIS bit is overridden while the peripheral is enabled. Therefore, read-modify-write instructions (BSF, BCF, XORWF) with TRIS as destination should be avoided. The user should refer to the corresponding peripheral section for the correct TRIS bit settings. PORT pins may be multiplexed with analog inputs and analog VREF inputs. The operation of each of these pins is selected, to be an analog input or digital I/O, by clearing/setting the control bits in other Special Function registers (SFRs). An example of this is the ADCON1 register for the 10-bit A/D module. Currently, when devices have pins selected as an analog input, these pins will read as '0's. The TRIS registers control the direction of the port pins, even when they are being used as analog inputs. The user must ensure the TRIS bits are maintained set when using the pins as analog inputs. Note 1: If pins are multiplexed with analog inputs, then on a Power-on Reset these pins are configured as analog inputs, as controlled by the ADCON1 register. Reading port pins configured as analog inputs read a '0'. Note 2: If pins are multiplexed with comparator inputs, then on a Power-on Reset these pins are configured as analog inputs, as controlled by the CMCON register. Reading port pins configured as analog inputs read a '0'. Note 3: Pins may be multiplexed with the Parallel Slave Port (PSP). For the PSP to function, the I/O pins must be configured as digital inputs and the PSPMODE bit must be set. Note 4: At present, the Parallel Slave Port (PSP) is only multiplexed onto PORTD and PORTE. The PSP port becomes enabled when the PSPMODE bit is set. In this mode, the user must make sure that the TRISE bits are set (pins are configured as digital inputs) and that PORTE is configured for digital I/O. PORTD will override the values in the TRISD register. In this mode, the PORTD and PORTE input buffers are TTL. The control bits for the PSP operation are located in TRISE. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-4  2000 Microchip Technology Inc. 11.1.1 Multiplexed Peripherals Pins may be configured as either digital inputs or digital outputs. Digital inputs are either TTL buffers or Schmitt Triggers. Outputs are CMOS drivers except for pin RA4, which is an open-drain output. All pins also support one or more peripheral modules. When configured to operate with a peripheral, a pin may not be used for general input or output. In many cases, a pin must still be configured for input or output, although some peripherals override the TRIS configuration. Peripherals supported include: • Analog to Digital Converter Modules (A/D) • Timer Modules - Timer0 - Timer1 - Timer2 - Timer3 • Capture/Compare/Pulse Width Modulation (CCP) modules • External Interrupts • Interrupt On Change pins • Parallel Slave Port (PSP) module • In Circuit Serial Programming • System Oscillator • Weak Pull-Up sources • Synchronous Serial Port (SSP) module - Serial Peripheral Interface (SPI) - I2C • Master Synchronous Serial Port (MSSP) module - Serial Peripheral Interface (SPI) - I2C with full hardware Master mode support • Addressable USART module • Controller Area Network (CAN) module • Comparator modules • Voltage Reference modules • Low Voltage Detect (LVD) module 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-5 Section 11. I/O Ports I/O Ports 11 11.1.2 Output Data Latches (LATx) and Data Direction Register (TRISx) All port pins have an output data latch. Writing to a port writes to that latch (LATx). The data latch may also be read from and written to directly. If the pin is not being used by a peripheral, and is configured as an output by its TRIS bit, data in the latch will be output to the pin. All port pins have corresponding Data Direction Register bits (TRISx register) which configure each pin as an input or output. Clearing a bit in a TRIS register (bit=0) configures the corresponding pin for output, and drives the contents of the output data latch (LATx) to the selected pin. Setting a TRIS register bit (bit=1) configures the corresponding pin as an input, and puts the corresponding output driver in a high impedance state. After a reset, all pins are configured as inputs. Example 11-1 shows that writing the value in the WREG register to PORTB actually writes the value to the LATB register. Example 11-1: Writing to PORTB actually writes to LATB There are two input paths from a port. One path simply reads back what is in the data latch (LATx) without regard to whether or not the bits are being output, and may return values not present at the pin. The other path reads back the state of the pin (PORTx) unless a peripheral forces it to read back a fixed state. Example 11-2 demonstrates the difference between reading a PORT and reading the output latch of the PORT. Example 11-2: Reading PORTB compared to reading LATB Reading the PORTx register reads the status of the pins whereas writing to it will write to the port data latch (LATx). A write to LATx can also be performed. Example 11-3 shows the result of simply reading the PORT register. In this example, RB0 is being overdrive low and RB1 is being overdriven high. This is NOT recommended, and may actually violate device specifications, but is shown to give insight to the operation of an instruction which reads the I/O port with respect to the I/O ports data latch. Example 11-3: Reading PORTB reads the state of RB7:RB0 ; LATB = 1100 0011 ; RB<7:0> = 1001 0011 ; TRISB = 1111 0000 1=input 0=output ; W_REG = 0010 1110 movwf PORTB ; writes W_REG to PORTB output data ; latch (LATB) ; LATB = 0010 1110 ; RB<7:0> = 1001 1110 high nibble ; no change (TRISB) ; RB<7:0> = 1001 0101 ; LATB = 0111 0101 ; TRISB = 1111 0000 1=input 0=output movf PORTB,W ; reads states of PORTB pins ; W_REG = 1001 0101 movf LATB,W ; reads contents of LATB data latch ; W_REG = 0111 0101 ; RB<7:0> = 1001 0110 ; LATB = 1100 0011 ; TRISB = 1111 0000 1=input 0=output movf PORTB,W ; reads state of pins ; W_REG = 1001 0110 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-6  2000 Microchip Technology Inc. Example 11-4 shows what effects can occur when writing to the PORT registers. Example 11-4: Writing to PORTB Example 11-5 shows what effects can occur when writing to the LAT registers. Example 11-5: Writing to LATB Any instruction that performs a write operates internally as a read-modify-write operation. Caution must be used when these instructions are applied to a port where pins are switching between input and output states. For example, a BSF PORTB, 5 instruction will cause all eight bits of PORTB to be read into the CPU. Then the instruction sets bit 5 and the resulting data is written to LATB. If the RB7 pin is used for bi-directional I/O and is defined as an input when BSF PORTB, 5 executes, the input signal present on the pin itself would be read into the CPU and be written to LATB<7>, overwriting the previous contents. As long as the RB7 pin stays in the input mode, no problem occurs. However, if the RB7 pin is switched to an output, the contents of the data latch may be in an unintended state, causing the RB7 pin to be in the wrong state. Example 11-6 shows how read-modify-write operations can affect the PORT register or the TRIS register. Example 11-6: Read-modify-write of PORTB, and TRISB change toggles RB7 A better solution would be to use the data latch instead. A BSF LATB, 5 instruction will read the bits in the output latch, set bit 5, and write the results back to the output latch. LATB<7> will never be at risk of being changed. ; TRISB = 1111 0000 1=input 0=output ; W_REG = 1011 0110 ; LATB = 1100 0011 ; RB<7:0> = 1001 0011 movwf PORTB ; writes W_REG to LATB ; LATB = 1011 0110 ; RB<7:0> = 1001 0110 low nibble only ; is output ; TRISB = 1111 0000 1=input 0=output ; W_REG = 1011 0110 ; LATB = 1100 0011 ; RB<7:0> = 1001 0011 movwf LATB ; writes W_REG to LATB ; LATB = 1011 0110 ; RB<7:0> = 1001 0110 same result as ; ‘movwf PORTB’ ; RB<7:0> = 0001 0110 ; LATB = 1001 0110 ; TRISB = 1100 0000 bsf PORTB,5 ; read-modify-write operation. ; LATB = 0011 0110 bit 7 cleared ; RB<7:0> = 1011 0110 RB7 changes to high speed bcf TRISB,7 ; changes RB7 from input to output ; TRISB = 0100 0000 ; RB<7:0> = 0011 0110 RB7 in now driven low 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-7 Section 11. I/O Ports I/O Ports 11 Example 11-7 shows that doing read-modify-writes on the LATx register and TRISx register may not cause the voltage level on the pin to change. Example 11-7: Read-modify-write of LATB, and TRISB change has no effect on RB7 ; RB<7:0> = 1001 0110 ; LATB = 1001 0110 bit 7 is high ; TRISB = 1100 0000 bsf LATB,5 ; read-modify-write operation ; LATB = 1011 0110 bit 7 has not changed ; RB<7:0> = 1011 0110 bcf TRISB,7 ; changes RB7 from input to output ; TRISB = 0100 0000 ; RB<7:0> = 1011 0110 RB7 remains high 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-8  2000 Microchip Technology Inc. 11.2 PORTA, TRISA, and the LATA Register PORTA is a 6-bit, or 7-bit latch depending upon the oscillator configuration selected by the FOSC configuration bits. The corresponding data direction register is TRISA, the data output latch is LATA, and the pins are PORTA. Except for RA4, all PORTA pins have TTL input buffers and full CMOS output drivers. All pins are configured as inputs on a reset. The RA4 pin is a Schmitt Trigger input and an open drain output. All other RA port pins have TTL input levels and full CMOS output drivers. All pins have data direction bits (TRIS registers) which can configure these pins as output or input. Setting a TRISA register bit puts the corresponding output driver in a hi-impedance mode. Clearing a bit in the TRISA register puts the contents of the output latch on the selected pin(s). Example 11-8: Initializing PORTA 11.2.1 PORTA multi-plexed with Analog inputs PORTA may be multiplexed with the AD module. When used as analog inputs, the TRISA must configure the corresponding pins as digital inputs (‘1’ on TRIS bit). On all resets, the PORTA pins are configured as analog inputs and a read of the digital inputs will result in read values of ‘0’. CLRF PORTA ; Initialize PORTA by clearing output ; data latches ; CLRF LATA ; Alternate method to initialize PORTA MOVLW 0xCF ; Value used to initialize data direction MOVWF TRISA ; PORTA<3:0> = inputs PORTA<5:4> = outputs ; TRISA<7:6> always read as '0' 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-9 Section 11. I/O Ports I/O Ports 11 Figure 11-2: Block Diagram of RA3:RA0 and RA5 Pins Data Bus WR PORTA WR TRISA RD PORTA Data Latch TRIS Latch P VSS I/O pin To Peripheral Module(s) D Q CK Q QD CK Q Q D EN N Analog input mode TTL VDD RD TRISA Input Buffer RD LATA or LATA Note: I/O pins have protection diodes to VDD and VSS. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-10  2000 Microchip Technology Inc. 11.2.2 RA4 / Timer0 Clock Input The RA4/T0CKI pin is a Schmitt Trigger input and an open drain output. Pin RA4 may be multiplexed with the peripheral module. All other PORTA pins have TTL input levels and CMOS output drivers. Figure 11-3: Block Diagram of RA4 Pin Data Bus WR PORT WR TRISA RD PORTA Data Latch TRIS Latch Schmitt Trigger Input Buffer N VSS To Peripheral Module D Q CK Q D Q CK Q Q D EN RD TRISA RA4 pin RD LATA or LATA Note: I/O pins have protection diodes to VSS only. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-11 Section 11. I/O Ports I/O Ports 11 Table 11-1: PORTA Functions Table 11-2: Summary of Registers Associated with PORTA Name Bit# Buffer Function RA0 bit0 TTL Input/output port pin RA1 bit1 TTL Input/output port pin RA2 bit2 TTL Input/output port pin RA3 bit3 TTL Input/output port pin RA4/T0CKI bit4 ST Input/output port pin or external clock input for Timer0 Output is open drain type RA5 bit5 TTL Input/output port pin RA6 bit6 TTL Input/output port pin Legend: TTL = TTL input, ST = Schmitt Trigger input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISA — PORTA Data Direction Control Register -111 1111 -111 1111 PORTA — Read PORTA pin/Write PORTA Data Latch -00x 0000 -00u 0000 LATA — Read PORTA Data Latch/Write PORTA Data Latch -xxx xxxx -uuu uuuu ADCON1 ADFM ADCS2 — — PCFG3 PCFG2 PCFG1 PCFG0 00-- 0000 00-- 0000 Legend: x = unknown, u = unchanged, - = unimplemented locations read as '0'. Shaded cells are not used by PORTA. ST = Schmitt Trigger input, TTL = TTL input. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-12  2000 Microchip Technology Inc. 11.3 PORTB, TRISB, and the LATB Register PORTB is an 8-bit wide bidirectional port. The corresponding data direction register is TRISB, the data output latch is LATB, and the pins are PORTB. All pins have TTL inputs. Setting a bit in the TRISB register puts the corresponding output driver in a hi-impedance input mode. Clearing a bit in the TRISB register puts the contents of the output latch on the selected pin. All pins are configured as inputs on a reset. Four of the PORTB pins have a weak internal pull-up. Clearing the RBPU bit (INTCON2<7>) turns on pull-ups on all pins. The weak pull-up is automatically turned off when the port pin is configured as an output. The pull-ups are disabled on a reset. Example 11-9: Initializing PORTB 11.3.1 RB2:RB0 / External Interrupts INT2:INT0 RB2:RB0 pins can also function as external interrupt sources INT2:INT0 while working as digital inputs. These interrupts are edge triggered on the edges selected by the bits. If enabled prior to entering sleep mode, these interrupts can wake the controller. INT2:INT0 inputs have Schmitt trigger inputs, while the RB2:RB0 inputs have TTL buffer inputs. Figure 11-4: Block Diagram of RB3:RB0 Pins CLRF PORTS ; Initialize PORTS by clearing output ; data latches ; CLRF LATB ; Alternate method to initialize data latches MOVLW 0xCF ; Value used to initialize data direction MOVWF TRISB ; PORTB<3:0> = inputs, PORTB<5:4> = outputs ; PORTB<7:6> = inputs Data Latch RBPU (2) P VDD D Q CK D Q CK Q D EN Data Bus WR PORTB WR TRISB RD TRISB RD PORTB weak pull-up RD PORTB To Peripheral Module TTL Input Buffer Schmitt Trigger Buffer TRIS Latch Note 1: I/O pins have diode protection to VDD and VSS. Note : To enable weak pull-ups, set the appropriate TRIS bit(s) and clear the RBPU bit. RD LATA I/O pin (1) 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-13 Section 11. I/O Ports I/O Ports 11 Four of PORTB’s pins, RB7:RB4, have an interrupt on change feature. Only pins configured as inputs can cause this interrupt to occur (i.e., any RB7:RB4 pin configured as an output is excluded from the interrupt on change comparison). The input pins (of RB7:RB4) are compared with the old value latched on the last read of PORTB. The present inputs of RB7:RB4 and their previous values are XOR’ed together to detect a “mismatch” condition and set the RB Port change interrupt flag bit RBIF. When enabled, this flag will generate an interrupt that can wake the device from SLEEP. This interrupt can wake the device from SLEEP. The user, in the interrupt service routine, can clear the interrupt in the following manner: a) Any read or write of PORTB will end the mismatch condition, except a write using the MOVFF instruction. b) Clear flag bit RBIF. The MOVFF instruction will not end the mismatch condition if PORTB is used only as the destination register. The contents of the destination register are not automatically read by this instruction in the second cycle. All other reads, writes, and bit operations will read the port during execution. A mismatch condition will continue to set flag bit RBIF. Reading PORTB will end the mismatch condition, and allow flag bit RBIF to be cleared. This interrupt on change (i.e., mismatch) feature, together with software configurable pull-ups on these four pins allow easy interface to a keypad and make it possible for wake-up on key-depression. The interrupt on change feature is recommended for wake-up on key depression and operations where PORTB is only used for the interrupt on change feature. Polling of PORTB is not recommended while using the interrupt on change feature. 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-14  2000 Microchip Technology Inc. Figure 11-5: Block Diagram of RB7:RB4 Pins 11.3.2 RB7:RB6 - In Circuit Serial Programming If ICSP is implemented in the target application, some means of isolating RB7:RB6 from the rest of the circuit should be provided. The ISCP inputs have Schmitt Triggers while the RB7:RB6 inputs have TTL inputs. Note 1: I/O pins have diode protection to VDD and VSS. Note 2: To enable weak pull-ups, set the appropriate TRIS bit(s) and clear the RBPU bit. Data Latch From other RBPU (2) P D Q CK D Q CK Q D EN Q D EN Data Bus WR PORTB WR TRISB Set RBIF TRIS Latch RD TRISB RD PORTB RB7:RB4 pins weak pull-up RD PORTB Latch TTL Input Buffer ST Buffer RB7:RB6 for In-Circuit Serial Programming mode Q3 Q1 RD LATB or LATB VDD I/O pin (1) RD LATB 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-15 Section 11. I/O Ports I/O Ports 11 Table 11-3: PORTB Functions Table 11-4: Summary of Registers Associated with PORTB Name Bit# Buffer Function RB0/INT0 bit0 TTL/ST (1) Input/output port pin or external interrupt0 input. Internal software programmable weak pull-up. RB1/INT1 bit1 TTL/ST (1) Input/output port pin or external interrupt1 input. Internal software programmable weak pull-up. RB2/INT2 bit2 TTL/ST (1) Input/output port pin or external interrupt2 input. Internal software programmable weak pull-up. RB3/CCP2 (3) bit3 TTL/ST (4) Input/output port pin or Capture2 input/Compare2 output/PWM2 output if CCP2MX is enabled in the configuration register. Internal software programmable weak pull-up. RB4 bit4 TTL Input/output port pin (with interrupt on change). Internal software programmable weak pull-up. RB5 bit5 TTL Input/output port pin (with interrupt on change). Internal software programmable weak pull-up. RB6 bit6 TTL/ST (2) Input/output port pin (with interrupt on change). Internal software programmable weak pull-up. Serial programming (CLOCK). RB7 bit7 TTL/ST (2) Input/output port pin (with interrupt on change). Internal software programmable weak pull-up. Serial programming (DATA). Legend: TTL = TTL input, ST = Schmitt Trigger input. Note 1: This buffer is a Schmitt Trigger input when configured as the external interrupt. Note 2: This buffer is a Schmitt Trigger input when used in serial programming mode. Note 3: The CCP2 input is only multiplexed on the RB3 pin if the CCP2MX configuration bit is ’0’. Note 4: The CCP2 input is a Schmitt Trigger if the CCP2MX configuration bit is ’0’. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISB PORTB Data Direction Register 1111 1111 1111 1111 PORTB Read PORTB pins/Write PORTB Data Latch xxxx xxxx uuuu uuuu LATB Read PORTB Data Latch/Write PORTB Data Latch xxxx xxxx uuuu uuuu INTCON GIE/GIEH PEIE/GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u INTCON2 RBPU INTEDG0 INTEDG1 INTEDG2 — TMR0IP — RBIP 1111 -1-1 1111 -1-1 INTCON3 INT2IP INT1IP — INT2IE INT1IE — INT2IF INT1IF 11-0 0-00 11-0 0-00 Legend: x = unknown, u = unchanged, - = unimplemented locations read as '0'. Shaded cells are not used by PORTB. 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-16  2000 Microchip Technology Inc. 11.4 PORTC, TRISC, and the LATC Register PORTC is an 8-bit bi-directional port. Each pin is individually configurable as an input or output through the TRISC register. The data output latch is LATC. PORTC pins have Schmitt Trigger input buffers. When enabling peripheral functions, care should be taken in defining TRIS bits for each PORTC pin. Some peripherals override the TRIS bit to make a pin an output, while other peripherals override the TRIS bit to make a pin an input, and other peripherals may not override the TRIS bits (requires that TRIS bits are configured for proper peripheral operation). The user should refer to the corresponding peripheral section for the correct TRIS bit settings. Example 11-10: Initializing PORTC Figure 11-6: PORTC Block Diagram (Peripheral Output Override) CLRF PORTC ; Initialize PORTC ; by clearing output data latches ; CLRF LATC ; Alternate method ; to clear output latch MOVLW 0xCF ; Value used to initialize data direction MOVWF TRISC ; PORTC<3:0> = inputs, ; PORTC<5:4> = outputs, ; PORTC<7:6> = inputs Data Latch TRIS Latch RD TRISC P VSS QD CK Q D Q CK Q Q D EN N VDD 0 1 WR PORTC WR TRISC Schmitt Trigger Peripheral Input Peripheral OE (2) Data Bus PORT/PERIPHERAL Select (1) Peripheral Data-out RD PORTC Note 1: Port/Peripheral select signal selects between port data and peripheral output. Peripheral OE (output enable) is only activated if peripheral select is active. I/O pins have diode protection to VDD and VSS. I/O pin (3) RD LATC 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-17 Section 11. I/O Ports I/O Ports 11 All PORTC pins have Schmitt Trigger input buffers. When a peripheral uses a pin for output, the peripheral will override the TRIS and force the pin to be an output. Conversely, when a peripheral uses a pin for input, the peripheral will override the TRIS and force the pin to be an input. The TRIS is ignored while the peripheral controls the pin. A read from the TRISC register bits will always yield the value contained in the TRISC latch whether or not a peripheral TRIS override is being asserted. This will allow a user to read the status of the TRISC bits at all times. Since the TRIS bit override is in effect when the peripheral is enabled, read-modify-write instructions (BSF, BCF and others) with TRIS as destination should be used with care. These instructions will have no effect on the current state of the pin. However, prior to disabling the peripheral and returning the pin to general use, the user should ensure that the TRIS bit is correctly set for that pin. When a peripheral uses a pin for output, the peripheral will override the TRIS and force the pin to be an output. Conversely, when a peripheral uses a pin for input, the peripheral will override the TRIS and force the pin to be an input. The TRIS is ignored while the peripheral controls the pin. A read from the TRISC register bits will always yield the value contained in the TRISC latch whether or not a peripheral TRIS override is being asserted. This will allow a user to read the status of the TRISC bits at all times. Since the TRIS bit override is in effect when the peripheral is enabled, read-modify-write instructions (BSF, BCF, and others) with TRIS as destination should be used with care. These instructions will have no effect on the current state of the pin. However, prior to disabling the peripheral and returning the pin to general use, the user should ensure that the TRIS bit is correctly set for that pin. Figure 11-7: PORTC Block Diagram (Peripheral Output Override) Data Bus WR LATC or WR TRISC RD TRISC D Q CK Q Q D CK Peripheral Data Out 1 0 D Q CK Q RD PORTC Peripheral Data In WR PORTC RD LATC Q Peripheral Out Select Peripheral In Select RC7: RC0 ST Buffer WR LATC or PORTC 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-18  2000 Microchip Technology Inc. 11.4.1 RC1 / CCP2 Input / Output The RC1 pin can be multiplexed with the CCP2 module input/output. To achieve this, the CCP2MX Configuration bit must be programmed to a ‘1’. Table 11-5: PORTC Functions Table 11-6: Summary of Registers Associated with PORTC Name Bit# Buffer Type Function RC0 bit0 ST Input/output port pin or Timer1 oscillator output or Timer1/Timer3 clock input RC1 bit1 ST Input/output port pin or Timer1 oscillator input RC2 bit2 ST Input/output port pin or Capture1 input/Compare1 output/PWM1 output RC3 bit3 ST Input/output port pin RC4 bit4 ST Input/output port pin RC5 bit5 ST Input/output port pin RC6 bit6 ST Input/output port pin RC7 bit7 ST Input/output port pin Legend: ST = Schmitt Trigger input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISC PORTC Data Direction Control Register 1111 1111 1111 1111 PORTC Read PORTC pin/Write PORTC Data Latch (LATC) xxxx xxxx uuuu uuuu LATC LATC Data Output Register xxxx xxxx uuuu uuuu Legend: x = unknown, u = unchanged. 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-19 Section 11. I/O Ports I/O Ports 11 11.5 PORTD, LATD, and the TRISD Register PORTD is an 8-bit port with Schmitt Trigger input buffers. Each pin is individually configured as an input or output. All PORTD pins have latch bits (LATD register). The LATD register, when read, will yield the contents of the PORTD latch, and when written, will modify the contents of the PORTD latch. This modifies the value driven out on a pin if the corresponding TRISD bit is configured for output. This can be used in read-modify-write instructions that allow the user to modify the contents of the latch register regardless of the status of the corresponding pins. Example 11-11: Initializing PORTD Figure 11-8: Typical PORTD Block Diagram (in I/O Port Mode) CLRF PORTD ; Initialize PORTD ; by clearing output data latches ; CLRF LATD ; Alternate method to initialize ; data output latch MOVLW 0xCF ; Value used to initialize data direction MOVWF TRISD ; PORTD<3:0> = inputs, ; PORTD<5:4> = outputs, ; PORTD<7:6> = inputs Data Bus WR LATD WR TRISD RD PORTD Data Latch TRIS Latch Schmitt Trigger Input Buffer D Q CK D Q CK Q D EN I/O pin (1) RD TRISD Note 1: I/O pins have protection diodes to VDD and VSS. RD LATD or PORTD 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-20  2000 Microchip Technology Inc. Table 11-7: PORTD Functions Table 11-8: Summary of Registers Associated with PORTD Name Bit# Buffer Type Function RD0 bit0 ST Input/output port pin RD1 bit1 ST Input/output port pin RD2 bit2 ST Input/output port pin RD3 bit3 ST Input/output port pin RD4 bit4 ST Input/output port pin RD5 bit5 ST Input/output port pin RD6 bit6 ST Input/output port pin RD7 bit7 ST Input/output port pin Legend: ST = Schmitt Trigger input, TTL = TTL input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISD PORTD Data Direction Control Register 1111 1111 1111 1111 PORTD Read PORTD pin / Write PORTD Data Latch xxxx xxxx uuuu uuuu LATD Read PORTD Data Latch/Write PORTD Data Latch xxxx xxxx uuuu uuuu PSPCON (1) IBF OBF IBOV PSPMODE — — — — 0000 xxxx 0000 uuuu Legend: x = unknown, u = unchanged. Note 1: In some devices, the four bits in the PSPCON register may be located in the upper four bits of the TRISE register. 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-21 Section 11. I/O Ports I/O Ports 11 11.6 PORTE, TRISE, and the LATE Register PORTE can be up to an 8-bit port with Schmitt Trigger input buffers. Each pin is individually configurable as an input or output. Example 11-12: Initializing PORTE Figure 11-9: Typical PORTE Block Diagram (in I/O Port Mode) CLRF PORTE ; Initialize PORTE by clearing output ; data latches ; CLRF LATE ; Alternate method to initialize ; data output latch MOVLW 0x03 ; Value used to initialize data direction MOVWF TRISE ; PORTE<1:0> = inputs, ; PORTE<7:2> = outputs Data Bus WR PORT WR TRIS RD PORT Data Latch TRIS Latch Schmitt Trigger Input Buffer D Q CK Q D Q CK Q Q D EN I/O pin (1) RD TRIS Note 1: I/O pins have protection diodes to VDD and VSS. Note: On some devices with PORTE, the upper bits of the TRISE register are used for the Parallel Slave Port control and status bits. 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-22  2000 Microchip Technology Inc. Table 11-9: PORTE Functions Table 11-10: Summary of Registers Associated with PORTE Name Bit# Buffer Type Function RE0 bit0 ST Input/output port pin RE1 bit1 ST Input/output port pin RE2 bit2 ST Input/output port pin Legend: ST = Schmitt Trigger input, TTL = TTL input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISE IBF OBF IBOV PSPMODE — PORTE Data Direction Bits 0000 -111 0000 -111 PORTE — — — — — RE2 RE1 RE0 ---- -000 ---- -000 LATE — — — — — LATE Data Output Register ---- -xxx ---- -uuu ADCON1 ADFM ADCS2 — — PCFG3 PCFG2 PCFG1 PCFG0 --0- 0000 --0- 0000 PSPCON (1) IBF OBF IBOV PSPMODE — — — — 0000 xxxx 0000 uuuu Legend: x = unknown, u = unchanged. Note 1: In some devices, the four bits in the PSPCON register may be located in the upper four bits of the TRISE register. 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-23 Section 11. I/O Ports I/O Ports 11 11.7 PORTF, LATF, and the TRISF Register PORTF is an 8-bit port with Schmitt Trigger input buffers. Each pin is individually configured as an input or output. All PORTF pins have latch bits (LATF register). The LATF register, when read, will yield the contents of the PORTF latch, and when written, will modify the contents of the PORTF latch. This modifies the value driven out on a pin if the corresponding TRISF bit is configured for output. This can be used in read-modify-write instructions that allow the user to modify the contents of the latch register regardless of the status of the corresponding pins. PORTF pins are multiplexed with analog inputs, system bus address bits, chip enables, and the UB and LB external bus control signals. The operation of each analog pin is selected by clearing/setting the control bits in the ADCON0 and ADCON1 register. The TRISF register controls the direction of the RF pins, even when they are being used as analog inputs. The user must ensure the bits in the TRISF register are maintained set when using them as analog inputs. Figure 11-10: RF1:RF0 Block Diagram Note: On all forms of Reset, the RF2:RF0 are configured as analog inputs and read as '0'. Data Bus WR LATF WR TRISF RD PORTF Data Latch TRIS Latch P VSS I/O pin (1) D Q CK Q D Q CK Q Q D EN N VDD RD TRISF RD LATF or PORTF To Peripheral Module Analog Input Mode ST Input Buffer Note 1: I/O pins have protection diodes to VDD and VSS. 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-24  2000 Microchip Technology Inc. Table 11-11: PORTF Functions Table 11-12: Summary of Registers Associated with PORTF Name Bit# Buffer Type Function RF0 bit0 ST Input/output port pin RF1 bit1 ST Input/output port pin RF2 bit2 ST Input/output port pin RF3 bit3 ST Input/output port pin RF4 bit4 ST Input/output port pin RF5 bit5 ST Input/output port pin RF6 bit6 ST Input/output port pin RF7 bit7 ST Input/output port pin Legend: ST = Schmitt Trigger input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISF PORTF Data Direction Control Register 1111 1111 1111 1111 PORTF Read PORTF pin / Write PORTF Data Latch xxxx xx00 uuuu u000 LATF Read PORTF Data Latch/Write PORTF Data Latch 0000 0000 uuuu u000 Legend: x = unknown, u = unchanged. Shaded cells are not used by Port F. 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-25 Section 11. I/O Ports I/O Ports 11 11.8 PORTG, LATG, and the TRISG Register PORTG is a 5-bit port with Schmitt Trigger input buffers. Each pin is individually configured as an input or output. All PORTG pins have latch bits (LATG register). The LATG register, when read, will yield the contents of the PORTG latch, and when written, will modify the contents of the PORTG latch. This modifies the value driven out on a pin if the corresponding TRISG bit is configured for output. This can be used in read-modify-write instructions that allow the user to modify the contents of the latch register regardless of the status of the corresponding pins. Figure 11-11: PORTG Block Diagram Data Bus WR LATG WR TRISG RD PORTG Data Latch TRIS Latch Schmitt Trigger Input Buffer D Q CK D Q CK Q D EN I/O pin (1) RD TRISG Note 1: I/O pins have protection diodes to VDD and VSS. RD LATG or PORTG 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-26  2000 Microchip Technology Inc. Table 11-13: PORTG Functions Table 11-14: Summary of Registers Associated with PORTG Name Bit# Buffer Type Function RG0 bit0 ST Input/output port pin RG1 bit1 ST Input/output port pin RG2 bit2 ST Input/output port pin RG3 bit3 ST Input/output port pin RG4 bit4 ST Input/output port pin RG5 bit5 ST Input/output port pin RG6 bit6 ST Input/output port pin RG7 bit7 ST Input/output port pin Legend: ST = Schmitt Trigger input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISG PORTG Data Direction Control Register ---1 1111 ---1 1111 PORTG Read PORTG pin / Write PORTG Data Latch ---x xxxx ---u uuuu LATG Read PORTG Data Latch/Write PORTG Data Latch ---x xxxx ---u uuuu Legend: x = unknown, u = unchanged. 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-27 Section 11. I/O Ports I/O Ports 11 11.9 PORTH, LATH, and the TRISH Register PORTH is an 8-bit port with Schmitt Trigger input buffers. Each pin is individually configured as an input or output. All PORTH pins have latch bits (LATH register). The LATH register, when read, will yield the contents of the PORTH latch, and when written, will modify the contents of the PORTH latch. This modifies the value driven out on a pin if the corresponding TRISH bit is configured for output. This can be used in read-modify-write instructions that allow the user to modify the contents of the latch register regardless of the status of the corresponding pins. Figure 11-12: PORTH Block Diagram Data Bus WR LATH WR TRISG RD PORTH Data Latch TRIS Latch Schmitt Trigger Input Buffer D Q CK D Q CK Q D EN I/O pin (1) RD TRISH Note 1: I/O pins have protection diodes to VDD and VSS. RD LATH or PORTH To Peripheral Module 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-28  2000 Microchip Technology Inc. Table 11-15: PORTH Functions Table 11-16: Summary of Registers Associated with PORTH Name Bit# Buffer Type Function RH0 bit0 ST Input/output port pin RH1 bit1 ST Input/output port pin RH2 bit2 ST Input/output port pin RH3 bit3 ST Input/output port pin RH4 bit4 ST Input/output port pin RH5 bit5 ST Input/output port pin RH6 bit6 ST Input/output port pin RH7 bit7 ST Input/output port pin Legend: TTL = TTL input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISH PORTH Data Direction Control Register 1111 1111 1111 1111 PORTH Read PORTH pin / Write PORTH Data Latch 0000 xxxx 0000 uuuu LATH Read PORTH Data Latch/Write PORTH Data Latch xxxx xxxx uuuu uuuu Legend: x = unknown, u = unchanged, - = unimplemented. Shaded cells are not used by Port H. 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-29 Section 11. I/O Ports I/O Ports 11 11.10 PORTJ, LATJ, and the TRISJ Register PORTJ is an 8-bit port with Schmitt Trigger input buffers. Each pin is individually configured as an input or output. All PORTJ pins have latch bits (LATJ register). The LATJ register, when read, will yield the contents of the PORTJ latch, and when written, will modify the contents of the PORTJ latch. This modifies the value driven out on a pin if the corresponding TRISJ bit is configured for output. This can be used in read-modify-write instructions that allow the user to modify the contents of the latch register regardless of the status of the corresponding pins. Figure 11-13: PORTJ Block Diagram Data Bus WR LATJ WR TRISJ RD PORTJ Data Latch TRIS Latch Schmitt Trigger Input Buffer D Q CK D Q CK Q D EN I/O pin (1) RD TRISJ Note 1: I/O pins have protection diodes to VDD and VSS. RD LATJ or PORTJ 39500 18C Reference Manual.book Page 29 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-30  2000 Microchip Technology Inc. Table 11-17: PORTJ Functions Table 11-18: Summary of Registers Associated with PORTJ Name Bit# Buffer Type Function RJ0 bit0 ST Input/output port pin RJ1 bit1 ST Input/output port pin RJ2 bit2 ST Input/output port pin RJ3 bit3 ST Input/output port pin RJ4 bit4 ST Input/output port pin RJ5 bit5 ST Input/output port pin RJ6 bit6 ST Input/output port pin RJ7 bit7 ST Input/output port pin Legend: ST = Schmitt Trigger input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISJ PORTJ Data Direction Control Register 1111 1111 1111 1111 PORTJ Read PORTJ pin / Write PORTJ Data Latch xxxx xxxx uuuu uuuu LATJ Read PORTJ Data Latch/Write PORTJ Data Latch xxxx xxxx uuuu uuuu Legend: x = unknown, u = unchanged. 39500 18C Reference Manual.book Page 30 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-31 Section 11. I/O Ports I/O Ports 11 11.11 PORTK, LATK, and the TRISK Register PORTK is an 8-bit port with Schmitt Trigger input buffers. Each pin is individually configured as an input or output. Figure 11-14: PORTK Block Diagram Data Bus WR LATK WR TRISK RD PORTK Data Latch TRIS Latch Schmitt Trigger Input Buffer D Q CK D Q CK Q D EN I/O pin (1) RD TRISK Note 1: I/O pins have protection diodes to VDD and VSS. RD LATK or PORTK 39500 18C Reference Manual.book Page 31 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-32  2000 Microchip Technology Inc. Table 11-19: PORTK Functions Table 11-20: Summary of Registers Associated with PORTK Name Bit# Buffer Type Function RK0 bit0 ST Input/output port pin RK1 bit1 ST Input/output port pin RK2 bit2 ST Input/output port pin RK3 bit3 ST Input/output port pin RK4 bit4 ST Input/output port pin RK5 bit5 ST Input/output port pin RK6 bit6 ST Input/output port pin RK7 bit7 ST Input/output port pin Legend: ST = Schmitt Trigger input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISK PORTK Data Direction Control Register 1111 1111 1111 1111 PORTK Read PORTK pin / Write PORTK Data Latch xxxx xxxx uuuu uuuu LATK Read PORTK Data Latch/Write PORTK Data Latch xxxx xxxx uuuu uuuu Legend: x = unknown, u = unchanged. 39500 18C Reference Manual.book Page 32 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-33 Section 11. I/O Ports I/O Ports 11 11.12 PORTL, LATL, and the TRISL Register PORTL is a 8-bit port with Schmitt Trigger input buffers. Each pin is individually configured as an input or output. Figure 11-15: Block Diagram of PORTL Pins Data Bus WR LATL WR TRISL RD PORTL Data Latch TRIS Latch Schmitt Trigger Input Buffer D Q CK D Q CK Q D EN I/O pin (1) RD TRISL Note 1: I/O pins have protection diodes to VDD and VSS. RD LATL or PORTL 39500 18C Reference Manual.book Page 33 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-34  2000 Microchip Technology Inc. Table 11-21: PORTL Functions Table 11-22: Summary of Registers Associated with PORTL Name Bit# Buffer Type Function RL0 bit0 ST Input/output port pin RL1 bit1 ST Input/output port pin RL2 bit2 ST Input/output port pin RL3 bit3 ST Input/output port pin RL4 bit4 ST Input/output port pin RL5 bit5 ST Input/output port pin RL6 bit6 ST Input/output port pin RL7 bit7 ST Input/output port pin Legend: ST = Schmitt Trigger input. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TRISL PORTL Data Direction Control Register 1111 1111 1111 1111 PORTL Read PORTL pin / Write PORTL Data Latch xxxx xxxx uuuu uuuu LATL Read PORTL Data Latch/Write PORTL Data Latch xxxx xxxx uuuu uuuu Legend: x = unknown, u = unchanged. 39500 18C Reference Manual.book Page 34 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-35 Section 11. I/O Ports I/O Ports 11 11.13 Functions Multiplexed on I/O Pins This section discusses a couple of functions that are multiplexed on to I/O pins that are new concepts when compared to the Mid-Range family. 11.13.1 Oscillator Configuration If the system oscillator uses RCIO or ECIO mode, then the OSC2 pin may be used as a general purpose I/O pin. If any other oscillator mode is used, the I/O pin multiplexed with OSC2 is disabled and will read ‘0’, as will the TRIS bit and LAT bit associated with the I/O pin. Writes to I/O pin will have no effect. See Table 11-23. If the system oscillator uses RC or EC mode, then the I/O pin is configured as OSC2 and outputs Fosc/4. Table 11-23: RA6 Configuration for Oscillator Configuration Figure 11-16: Block Diagram of I/O Oscillator Configuration TRIS PORT LAT OSC2 / I/O Function RCIO / ERIO Read / Write Read / Write Read / Write General I/O RC / EC Disabled (reads 0) Disabled (reads 0) Disabled (reads 0) FOSC/4 Other system oscillator modes Disabled (reads 0) Disabled (reads 0) Disabled (reads 0) OSC2 D Q CK Q D Q CK Q Q D EN P N WR TRIS Data Latch TRIS Latch RD TRIS RD PORT Vss VDD I/O pin (1) Note 1: I/O pins have protection diodes to VDD and VSS. RD LAT ECIO or RCIO enable Data Bus ECIO or enable Data Bus TTL Input Buffer RCIO Data Bus WR LAT or PORT 39500 18C Reference Manual.book Page 35 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-36  2000 Microchip Technology Inc. 11.13.2 CCP2 Pin Multiplexing In the PIC18CXX2 devices, the RB3 pin can be multiplexed with the CCP2 module input/output. To achieve this, the CCP2MX configuration bit must be programmed to a ‘0’. Figure 11-17: Block Diagram of RB3 RB LATB P CK Data Bus weak pull-up CCP2 Input TTL Buffer Schmitt Trigger RBPU P N VDD Vss RB3/CCP2 CCP2MX QD Q 1 0 CK QD Q RD TRISB WR TRISB Q Q D CK RD PORTB PWM2 OUT PWM2 OUT CCP2 IN SELECT WR LATB or WR PORTB SELECT Note: I/O pin has diode protection to VDD and VSS. Note:To enable weak pull-ups, set the appropriate TRIS bit(s) and clear the RBPU bit (INTCON2). Note:The CCP2 input/output is multiplexed with RB3 if the CCP2MX bit is enabled (=’0’) in the configuration register. VDD 39500 18C Reference Manual.book Page 36 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-37 Section 11. I/O Ports I/O Ports 11 11.14 I/O Programming Considerations When using the ports as I/O, design considerations need to be taken into account to ensure that the operation is as intended. 11.14.1 Bi-directional I/O Ports Any instruction that performs a write operation, actually does a read followed by a write operation. The BCF and BSF instructions, for example, read the register into the CPU, execute the bit operation and write the result back to the register. Caution must be used when these instructions are applied to a port with both inputs and outputs defined. For example, a BSF operation on bit5 of PORTB will cause all eight bits of PORTB to be read into the CPU. Then the BSF operation takes place on bit5 and PORTB is written to the output latches. If another bit of PORTB is used as a bi-directional I/O pin (e.g., bit0) and it is defined as an input at this time, the input signal present on the pin itself would be read into the CPU and rewritten to the data latch of this particular pin, overwriting the previous content. As long as the pin stays in the input mode, no problem occurs. However, if bit0 is switched to an output, the content of the data latch may now be unknown. Reading the port register, reads the values of the port pins. Writing to the port register writes the value to the port latch. When using read-modify-write instructions (e.g., BCF, BSF, etc.) on a port, the value of the port pins is read, the desired operation is performed on this value, and the value is then written to the port latch. Example 11-13 shows the effect of two sequential read-modify-write instructions on an I/O port. Example 11-13: Read-Modify-Write Instructions on an I/O Port A pin configured as an output, actively driving a Low or High, should not be driven from external devices at the same time in order to change the level on this pin (“wired-or”, “wired-and”). The resulting high output currents may damage the chip. ; Initial PORT settings: PORTB<7:4> Inputs ; PORTB<3:0> Outputs ; PORTB<7:6> have external pull-ups and are not connected to other circuitry ; ; PORT latch PORT pins ; ---------- --------- BCF PORTB, 7 ; 01pp pppp 11pp pppp BCF PORTB, 6 ; 10pp pppp 11pp pppp BCF TRISB, 7 ; 10pp pppp 11pp pppp BCF TRISB, 6 ; 10pp pppp 10pp pppp ; ; Note that the user may have expected the pin values to be 00pp ppp. ; The 2nd BCF caused RB7 to be latched as the pin value (high). 39500 18C Reference Manual.book Page 37 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-38  2000 Microchip Technology Inc. 11.14.2 Successive Operations on an I/O Port The actual write to an I/O port happens at the end of an instruction cycle, whereas for reading, the data must be valid at the beginning of the instruction cycle (Figure 11-18). Therefore, care must be exercised if a write followed by a read operation is carried out on the same I/O port. The sequence of instructions should be such to allow the pin voltage to stabilize (load dependent) before the next instruction that causes that file to be read into the CPU is executed. Otherwise, the previous state of that pin may be read into the CPU rather than the new state. When in doubt, it is better to separate these instructions with a NOP or another instruction not accessing this I/O port. This example shows a write to PORTB followed by a read from PORTB. Therefore, at higher clock frequencies, a write followed by a read may be problematic due to external capacitance. Figure 11-18: Successive I/O Operation Note: Data setup time = (0.25TCY - TPD), where TCY = instruction cycle, TPD = propagation delay. PC PC + 1 PC + 2 PC + 3 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Instruction fetched RB7:RB0 MOVWF PORTB write to PORTB NOP Port pin sampled here NOP MOVF PORTB,W Instruction executed MOVWF PORTB write to PORTB NOP MOVF PORTB,W PC TPD 39500 18C Reference Manual.book Page 38 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-39 Section 11. I/O Ports I/O Ports 11 Figure 11-19 shows the I/O model that causes this situation. As the effective capacitance (C) becomes larger, the rise/fall time of the I/O pin increases. As the device frequency increases or the effective capacitance increases, the possibility of this subsequent PORTx read-modify-write instruction issue increases. This effective capacitance includes the effects of the board traces. A way to address this is to add an series resistor at the I/O pin. This resistor allows the I/O pin to get to the desired level before the next instruction. The use of NOP instructions between the subsequent PORTx read-modify-write instructions, is a lower cost solution, but has the issue that the number of NOP instructions is dependent on the effective capacitance C and the frequency of the device. Figure 11-19: I/O Connection Issues PIC18CXXX I/O C (1) Q4 Q1 Q2 Q3 Q4 Q1 VIL BSF PORTx, PINy Q2 Q3 BSF PORTx, PINz PORTx, PINy Read PORTx, PINy as low BSF PORTx, PINz clears the value to be driven on the PORTx, PINy pin. Note 1: This is not a capacitor to ground, but the effective capacitive loading on the trace. 39500 18C Reference Manual.book Page 39 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-40  2000 Microchip Technology Inc. 11.15 Initialization See the section describing each port for examples of initialization of the ports. Note: It is recommended that when initializing the port, the PORT data latch (LAT or PORT register) should be initialized first, and then the data direction (TRIS register). This will eliminate a possible pin glitch, since the LAT register (PORT data latch values) power up in a random state. 39500 18C Reference Manual.book Page 40 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-41 Section 11. I/O Ports I/O Ports 11 11.16 Design Tips Question 1: Code will not toggle any I/O ports, but the oscillator is running. What can I be doing wrong? Answer 1: 1. Have the TRIS registers been initialized properly? These registers can be written to directly in the access bank (Bank15). 2. Is there a peripheral multiplexed onto those pins that are enabled? 3. Is the Watchdog Timer enabled (done at programming)? If it is enabled, is it being cleared properly with a CLRWDT instruction at least every 9 ms (or more if prescaled)? 4. Are you using the correct instructions to write to the port? More than one person has used the MOVF command when they should have used MOVWF. 5. For parts with interrupts, are the interrupts disabled? If not, try disabling them to verify they are not interfering. Question 2: When my program reads a port, I get a different value than what I put in the port register. What can cause this? Answer 2: 1. When a port is read, it is always the pin that is read, regardless of its being set to input or output. So if a pin is set to an input, you will read the value on the pin regardless of the register value. 2. If a pin is set to output, for instance, it has a one in the data latch; if it is shorted to ground, you will still read a zero on the pin. This is very useful for building fault tolerant systems, or handling I2C bus conflicts. (The I2C bus is only driven low, and the pin is high impedance for a one. If the pin is low and you are not driving it, some other device is trying to take the bus). 3. Enhanced devices all have at least one open drain (or open collector) pin. These pins can only drive a zero or high impedance. For most Enhanced devices, this is pin RA4. Open drain pins must have a pull-up resistor to have a high state. This pin is useful for driving odd voltage loads. The pull-up can be connected to a voltage (typically less than VDD) which becomes the high state. 4. Some analog modules, when enabled, will force a read value of ‘0’ from the pin, regardless of the voltage level on the pin. Question 3: I have a PIC18CXX2 with pin RB0 configured as an interrupt input, but am not getting interrupted. When I change my routine to poll the pin, it reads the high input and operates fine. What is the problem? Answer 3: PORTB accepts TTL input levels (on most parts), so when you have an input of say 3V (with VDD = 5V), you will read a ‘1’. However, the buffer to the interrupt structure from pin RB0 is a Schmitt Trigger, which requires a higher voltage (than TTL input) before the high input is registered. So it is possible to read a ‘1’, but not get the interrupt. The interrupt was given a Schmitt Trigger input with hysteresis to minimize noise problems. It is one thing to have short noise spikes on a pin that is a data input that can potentially cause bad data, but quite another to permit noise to cause an interrupt, hence the difference. 39500 18C Reference Manual.book Page 41 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-42  2000 Microchip Technology Inc. Question 4: When I perform a BCF instruction, other pins get cleared in the port. Why? Answer 4: 1. Another case where a read-modify-write instruction may seem to change other pin values unexpectedly can be illustrated as follows: Suppose you make PORTC all outputs, and drive the pins low. On each of the port pins is an LED connected to ground, such that a high output lights it. Across each LED is a 100 µF capacitor. Let's also suppose that the processor is running very fast, say 20 MHz. Now if you go down the port, setting each pin in order; BSF PORTC,0 then BSF PORTC,1 then BSF PORTC,2 and so on, you may see that only the last pin was set, and only the last LED actually turns on. This is because the capacitors take a while to charge. As each pin was set, the pin before it was not charged yet, and so was read as a zero. This zero is written back out to the port latch (r-m-w, remember), which clears the bit you just tried to set in the previous instruction. This is usually only a concern at high speeds and for successive port operations, but it can happen, so take it into consideration. 2. If this is on a PIC18CXXX device with A/D, you have not configured the I/O pins properly in the ADCON1 register. If a pin is configured for analog input, any read of that pin will read a zero, regardless of the voltage on the pin. This is an exception to the normal rule that the pin state is always read. You can still configure an analog pin as an output in the TRIS register, and drive the pin high or low by writing to it, but you will always read a zero. Therefore, if you execute a Read-Modify-Write instruction (see previous question), all analog pins are read as zero; those not directly modified by the instruction will be written back to the port latch as zero. A pin configured as analog is expected to have values that may be neither high nor low to a digital pin, or floating. Floating inputs on digital pins are a no-no, and can lead to high current draw in the input buffer, so the input buffer is disabled. 39500 18C Reference Manual.book Page 42 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39511A-page 11-43 Section 11. I/O Ports I/O Ports 11 11.17 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Baseline, the Midrange, or High-end families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to I/O ports are: Title Application Note # Improving the Susceptibility of an Application to ESD AN595 Clock Design using Low Power/Cost Techniques AN615 Implementing Wake-up on Keystroke AN528 Interfacing to AC Power Lines AN521 Multiplexing LED Drive and a 4 x 4 Keypad Sampling AN529 Using PIC16C5X as an LCD Drivers AN563 Serial Port Routines Without Using TMR0 AN593 Implementation of an Asynchronous Serial I/O AN510 Using the PORTB Interrupt on Change Feature as an External Interrupt AN566 Implementing Wake-up on Keystroke AN522 Apple Desktop Bus AN591 Software Implementation of Asynchronous Serial I/O AN555 Communicating with the I2C Bus using the PIC16C5X AN515 Interfacing 93CX6 Serial EEPROMs to the PIC16C5X Microcontrollers AN530 Logic Powered Serial EEPROMs AN535 Interfacing 24LCXXB Serial EEPROMs to the PIC16C54 AN567 Using the 24XX65 and 24XX32 with Stand-alone PIC16C54 Code AN558 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 43 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39511A-page 11-44  2000 Microchip Technology Inc. 11.18 Revision History Revision A This is the initial released revision of the Enhanced MCU I/O Ports description. 39500 18C Reference Manual.book Page 44 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39512-page 12-1 Parallel Slave Port 12 Section 12. Parallel Slave Port HIGHLIGHTS This section of the manual contains the following major topics: 12.1 Introduction .................................................................................................................. 12-2 12.2 Control Register ........................................................................................................... 12-3 12.3 Operation ..................................................................................................................... 12-5 12.4 Operation in SLEEP Mode........................................................................................... 12-6 12.5 Effect of a RESET........................................................................................................ 12-6 12.6 PSP Waveforms ........................................................................................................... 12-6 12.7 Design Tips .................................................................................................................. 12-8 12.8 Related Application Notes............................................................................................ 12-9 12.9 Revision History ......................................................................................................... 12-10 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39512-page 12-2  2000 Microchip Technology Inc. 12.1 Introduction Some devices have an 8-bit wide Parallel Slave Port (PSP). This port is multiplexed onto one of the device’s I/O ports. The port operates as an 8-bit wide Parallel Slave Port, or microprocessor port, when the PSPMODE control bit is set. In this mode, the input buffers are TTL. In slave mode, the module is asynchronously readable and writable by the external world through the RD control input pin and the WR control input pin. It can directly interface to an 8-bit microprocessor data bus. The external microprocessor can read or write the PORT latch as an 8-bit latch. Setting the PSPMODE bit enables port pins to be the RD input, the WR input, and the CS (chip select) input. There are actually two 8-bit latches, one for data-out (from the PICmicro) and one for data input. The user writes 8-bit data to the PORT data latch and reads data from the port pin latch (note that they have the same address). In this mode, the TRIS register is ignored, since the microprocessor is controlling the direction of data flow. Register 12-1 shows the block diagram for the PSP module. Figure 12-1: PORTD and PORTE Block Diagram (Parallel Slave Port) Note 1: At present the Parallel Slave Port (PSP) is only multiplexed onto PORTD and PORTE. The microprocessor port becomes enabled when the PSPMODE bit is set. In this mode, the user must make sure that PORTD and PORTE are configured as digital I/O. That is, peripheral modules multiplexed onto the PSP functions are disabled (such as the A/D). When PORTE is configured for digital I/O, PORTD will override the values in the TRISD register. 2: In this mode the PORTD and PORTE input buffers are TTL. The control bits for the PSP operation are located in TRISE. EN D Q CK Data Bus WR LATD RD PORTD One bit of PORTD Set interrupt flag PSPIF PSP<7:0> TTL TTL Read Chip Select Write RD CS WR EN Q D EN TTL TTL or PORTD RD LATD Note: I/O pins have protection diodes to VDD and VSS. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39512-page 12-3 Section 12. Parallel Slave Port Parallel Slave Port 12 12.2 Control Register Register 12-1 is the PSP control register (PSPCON). The TRISE register (Register 12-2) contains the 4 bits for the PSP module found in some devices (such as PIC18C4X2) for compatibility with 40-pin midrange devices. Register 12-1: PSPCON Register R-0 R-0 R/W-0 R/W-0 U-0 U-0 U-0 U-0 IBF OBF IBOV PSPMODE — — — — bit 7 bit 0 bit 7 IBF: Input Buffer Full Status bit 1 = A word has been received and waiting to be read by the CPU 0 = No word has been received bit 6 OBF: Output Buffer Full Status bit 1 = The output buffer still holds a previously written word 0 = The output buffer has been read bit 5 IBOV: Input Buffer Overflow Detect bit (in microprocessor mode) 1 = A write occurred when a previously input word has not been read (must be cleared in software) 0 = No overflow occurred bit 4 PSPMODE: Parallel Slave Port Mode Select bit 1 = Parallel slave port mode 0 = General purpose I/O mode bits 3:0 Unimplemented: Read as '0' Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39512-page 12-4  2000 Microchip Technology Inc. Register 12-2: TRISE Register R-0 R-0 R/W-0 R/W-0 U-0 R/W-1 R/W-1 R/W-1 IBF OBF IBOV PSPMODE — TRISE2 TRISE1 TRISE0 bit 7 bit 0 bit 7 IBF: Input Buffer Full Status bit 1 = A word has been received and waiting to be read by the CPU 0 = No word has been received bit 6 OBF: Output Buffer Full Status bit 1 = The output buffer still holds a previously written word 0 = The output buffer has been read bit 5 IBOV: Input Buffer Overflow Detect bit (in microprocessor mode) 1 = A write occurred when a previously input word has not been read (must be cleared in software) 0 = No overflow occurred bit 4 PSPMODE: Parallel Slave Port Mode Select bit 1 = Parallel slave port mode 0 = General purpose I/O mode bit 3 Unimplemented: Read as '0' bit 2 TRISE2: RE2 Direction Control bit 1 = Input 0 = Output bit 1 TRISE1: RE1 Direction Control bit 1 = Input 0 = Output bit 0 TRISE0: RE0 Direction Control bit 1 = Input 0 = Output Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39512-page 12-5 Section 12. Parallel Slave Port Parallel Slave Port 12 12.3 Operation A write to the PSP from the external system occurs when both the CS and WR lines are first detected low. When either the CS or WR lines become high (edge triggered), the Input Buffer Full status flag bit IBF is set on the Q4 clock cycle following the next Q2 cycle. This signals that the write is complete. The interrupt flag bit, PSPIF, is also set on the same Q4 clock cycle. The IBF flag bit is inhibited from being cleared for additional TCY cycles (see parameter 66 in the "Electrical Specifications" section). If the IBF flag bit is cleared by reading the PORTD input latch, then this has to be a read-only instruction (i.e., MOVF) and not a read-modify-write instruction. The Input Buffer Overflow status flag bit IBOV is set if a second write to the Parallel Slave Port is attempted when the previous byte has not been read out of the buffer. A read of the PSP from the external system occurs when both the CS and RD lines are first detected low. The Output Buffer Full status flag bit OBF is cleared immediately indicating that the PORTD latch was read by the external bus. When either the CS or RD pin becomes high (edge triggered), the interrupt flag bit, PSPIF, is set on the Q4 clock cycle following the next Q2 cycle, indicating that the read is complete. OBF remains low until data is written to PORTD by the user firmware. Input Buffer Full Status Flag bit, IBF, is set if a received word is waiting to be read by the CPU. Once the PORT input latch is read, the IBF bit is cleared. The IBF bit is a read only status bit. Output Buffer Full Status Flag bit, OBF, is set if a word written to the PORT latch is waiting to be read by the external bus. Once the PORTD output latch is read by the microprocessor, OBF is cleared. Input Buffer Overflow Status Flag bit, IBOV, is set if a second write to the microprocessor port is attempted when the previous word has not been read by the CPU (the first word is retained in the buffer). When not in Parallel Slave Port mode, the IBF and OBF bits are held clear. However, if the IBOV bit was previously set, it must be cleared in the software. An interrupt is generated and latched into flag bit PSPIF when a read or a write operation is completed. Interrupt flag bit PSPIF must be cleared by user software and the interrupt can be disabled by clearing interrupt enable bit PSPIE. Table 12-1: PORTE Functions Name Function RD Read Control Input in parallel slave port mode: RD 1 = Not a read operation 0 = Read operation. Reads PORTD register (if chip selected) WR Write Control Input in parallel slave port mode: WR 1 = Not a write operation 0 = Write operation. Writes PORTD register (if chip selected) CS Chip Select Control Input in parallel slave port mode: CS 1 = Device is not selected 0 = Device is selected Note: The PSP may have other functions multiplexed onto the same pins. For the PSP to operate, the pins must be configured as digital I/O. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39512-page 12-6  2000 Microchip Technology Inc. 12.4 Operation in SLEEP Mode When in SLEEP mode, the microprocessor may still read and write the Parallel Slave Port. These actions will set the PSPIF bit. If the PSP interrupts are enabled, this will wake the processor from SLEEP mode so that the PSP data latch may be either read, or written with the next value for the microprocessor. 12.5 Effect of a RESET After any RESET, the PSP is disabled and PORTD and PORTE are forced to their default mode. 12.6 PSP Waveforms Register 12-2 shows the waveform for a write from the microprocessor to the PSP, while Register 12-3 shows the waveform for a read of the PSP by the microprocessor. Figure 12-2: Parallel Slave Port Write Waveforms Figure 12-3: Parallel Slave Port Read Waveforms Q1 Q2 Q3 Q4 CS Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 WR RD IBF OBF PSPIF PORTD<7:0> Q1 Q2 Q3 Q4 CS Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 WR IBF PSPIF RD OBF PORTD<7:0> 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39512-page 12-7 Section 12. Parallel Slave Port Parallel Slave Port 12 Table 12-2: Registers Associated with Parallel Slave Port Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other resets PORTD Port data latch when written; port pins when read xxxx xxxx uuuu uuuu LATD LATD Data Output Bits xxxx xxxx uuuu uuuu TRISD PORTD Data Direction Bits 1111 1111 1111 1111 PORTE (1) — — — — — RE2 RE1 RE0 ---- -000 ---- -000 LATE — — — — — LATE Data Output Bits ---- -xxx ---- -uuu TRISE (1) IBF OBF IBOV PSPMODE — PORTE Data Direction Bits 0000 -111 0000 -111 PSPCON IBF OBF IBOV PSPMODE — — — — 0000 ---- 0000 ---- INTCON GIE/ GIEH PEIE/ GIEL TMR0IF INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIR1 PSPIF ADIF RCIF TXIF SSPIF CCP1IF TMR2IF TMR1IF 0000 0000 0000 0000 PIE1 PSPIE ADIE RCIE TXIE SSPIE CCP1IE TMR2IE TMR1IE 0000 0000 0000 0000 IPR1 PSPIP ADIP RCIP TXIP SSPIP CCP1IP TMR2IP TMR1IP 0000 0000 0000 0000 ADCON1 ADFM ADCS2 — — PCFG3 PCFG2 PCFG1 PCFG0 --0- -000 --0- -000 Legend: x = unknown, u = unchanged, - = unimplemented read as '0'. Shaded cells are not used by the Parallel Slave Port. Note 1: On some devices the entire PORTE will be implemented with I/O functions. In these devices, the TRISE register will contain the eight data direction bits and the PSP bits will be located in the PSPCON register. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39512-page 12-8  2000 Microchip Technology Inc. 12.7 Design Tips Question 1: Migrating from the PIC16C74 to the PIC18CXX2, the operation of the PSP seems to have changed. Answer 1: Yes, a design change was made so the PIC18CXX2 is edge sensitive (while the PIC16C74 was level sensitive). 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39512-page 12-9 Section 12. Parallel Slave Port Parallel Slave Port 12 12.8 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced MCU family (that is, they may be written for the Base-Line, the Mid-Range or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the Parallel Slave Port are: Title Application Note # Using the 8-bit Parallel Slave Port AN579 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39512-page 12-10  2000 Microchip Technology Inc. 12.9 Revision History Revision A This is the initial released revision of the Parallel Slave Port description. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39513A-page 13-1 Timer0 13 Section 13. Timer0 HIGHLIGHTS This section of the manual contains the following major topics: 13.1 Introduction .................................................................................................................. 13-2 13.2 Control Register ........................................................................................................... 13-3 13.3 Operation ..................................................................................................................... 13-4 13.4 Timer0 Interrupt ........................................................................................................... 13-5 13.5 Using Timer0 with an External Clock ........................................................................... 13-6 13.6 Timer0 Prescaler.......................................................................................................... 13-7 13.7 Initialization .................................................................................................................. 13-9 13.8 Design Tips ................................................................................................................ 13-10 13.9 Related Application Notes.......................................................................................... 13-11 13.10 Revision History ......................................................................................................... 13-12 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39513A-page 13-2  2000 Microchip Technology Inc. 13.1 Introduction The Timer0 module has the following features: • Software selectable as an 8-bit or 16-bit timer/counter • Readable and writable • Dedicated 8-bit software programmable prescaler • Clock source selectable to be external or internal • Interrupt on overflow from FFh to 00h (FFFFh to 0000h in 16-bit mode) • Edge select for external clock Figure 13-1 shows a simplified block diagram of the Timer0 module in 8-bit mode and Figure 13-2 shows a simplified block diagram of the Timer0 module in 16-bit mode. Figure 13-1: Timer0 Block Diagram in 8-bit Mode Figure 13-2: Timer0 Block Diagram in 16-bit Mode T0CKI pin T0SE 0 1 0 1 T0CS FOSC/4 Programmable Prescaler Sync with Internal clocks TMR0 PSOUT (2 TCY delay) POUT Data Bus 8 PSA T0PS2:T0PS0 Set interrupt flag bit T0IF on overflow 3 Note 1: T0CS, T0SE, PSA, T0PS2:T0PS0 (T0CON<5:0>). 2: Upon reset, Timer0 is enabled in 8-bit mode, with clock input from T0CKI, max. prescale. Note 1: T0CS, T0SE, PSA, T0PS2:T0PS0 (T0CON<5:0>). 2: Upon reset, Timer0 is enabled in 8-bit mode, with clock input from T0CKI, max. prescale. T0CKI pin T0SE 0 1 0 1 T0CS FOSC/4 Programmable Prescaler Sync with Internal clocks TMR0L PSOUT (2 TCY delay) POUT Data Bus<7:0> 8 PSA T0PS2:T0PS0 3 TMR0 TMR0H High Byte 8 8 8 Read TMR0L Write TMR0L Set interrupt flag bit T0IF on overflow 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39513A-page 13-3 Section 13. Timer0 Timer0 14 13.2 Control Register The T0CON register is a readable and writable register that controls all the aspects of Timer0, including the prescale selection. Register 13-1: T0CON: TImer0 Control Register R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 TMR0ON T08BIT T0CS T0SE PSA T0PS2 T0PS1 T0PS0 bit 7 bit 0 bit 7 TMR0ON: Timer0 On/Off Control bit 1 = Enables Timer0 0 = Stops Timer0 bit 6 T08BIT: Timer0 8-bit/16-bit Control bit 1 = Timer0 is configured as an 8-bit timer/counter 0 = Timer0 is configured as a 16-bit timer/counter bit 5 T0CS: Timer0 Clock Source Select bit 1 = Transition on T0CKI pin is clock (counter mode) 0 = Internal instruction cycle is clock (timer mode) bit 4 T0SE: Timer0 Source Edge Select bit 1 = Increment on high-to-low transition on T0CKI pin 0 = Increment on low-to-high transition on T0CKI pin bit 3 PSA: Timer0 Prescaler Assignment bit 1 = Timer0 prescaler is NOT assigned. Timer0 clock input bypasses prescaler. 0 = Timer0 prescaler is assigned. Timer0 clock input comes from prescaler output. bit 2-0 T0PS2:T0PS0: Timer0 Prescaler Select bits These bits are ignored if PSA = 1 111 = 1:256 prescale value 110 = 1:128 prescale value 101 = 1:64 prescale value 100 = 1:32 prescale value 011 = 1:16 prescale value 010 = 1:8 prescale value 001 = 1:4 prescale value 000 = 1:2 prescale value Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39513A-page 13-4  2000 Microchip Technology Inc. 13.3 Operation When initializing Timer0, several options need to be specified. This is done by programming the appropriate bits in the T0CON register. 13.3.1 8-Bit/16-Bit Modes Timer0 can be configured as an 8-bit or a 16-bit counter. The default state for Timer0 is an 8-bit counter. To configure the timer as a 16-bit counter, the T08BIT bit (T0CON register) must be cleared. If the timer is configured as an 8-bit timer, the MSB of TMR0 (TMR0H) is held clear and will read 00h. Normally once the mode of the timer is selected, it is not changed. Some applications may require the ability to switch back and forth between 8-bit and 16-bit modes. The two cases are: 1. Changing from 8-bit to 16-bit mode 2. Changing from 16-bit to 8-bit mode The condition when bit 7 of the Timer0 rolls over must be addressed. If Timer0 is configured as an 8-bit timer and is changed to a 16-bit timer on the same cycle as a rollover occurs, no interrupt is generated. If Timer0 is configured as a 16-bit timer and is changed to an 8-bit timer on the same cycle as a rollover occurs, the TMR0IF bit will be set. 13.3.1.1 16-Bit Mode Timer Reads TMR0H is not the high byte of the timer/counter, but actually a buffered version of the high byte of Timer0. The high byte of the Timer0 counter/timer is not directly readable or writable. TMR0H is updated with the contents of the high byte of Timer0 during a read of TMR0L. This provides a user with the ability to read all 16 bits of Timer0 without having to verify that the read of the high and low byte were valid due to a rollover between successive reads of the high and low byte. The user simply reads the low byte of Timer0, followed by a read of TMR0H, which contains the value in the high byte of Timer0 at the time that the low byte was read. 13.3.1.2 16-Bit Mode Timer Write A write to the high byte of Timer0 must also take place through the TMR0H buffer register. Timer0 high byte is updated with the contents of TMR0H when a write occurs to TMR0L. This allows a user to update all 16 bits to both the high and low bytes of Timer0 at once (see Figure 13-2). When performing a write of TMR0, the carry is held off during the write of the TMR0L register. Writes to the TMR0H register only modify the holding latch, not the timer (TMR0<15:8>). Steps to write to the TMR0: 1. Load the TMR0H register. 2. Write to the TMR0L register. 13.3.1.3 16-Bit Read/Modify Write Read-modify-write instructions like BSF or BCF, read the contents of a register, make the appropriate changes, and place the result back into the register. The read cycle of a read-modify-write instruction of TMR0L will not update the contents of the TMR0H buffer. The TMR0H buffer will remain unchanged. When the write cycle (to TMR0L) of the instruction takes place, the contents of TMR0H are placed into the high byte of Timer0. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39513A-page 13-5 Section 13. Timer0 Timer0 14 13.3.2 Timer/Counter Modes Timer mode is selected by clearing the T0CS bit (T0CON register). In timer mode, the Timer0 module will increment every instruction cycle (without prescaler). If the TMR0 register is written, the increment is inhibited for the following two instruction cycles. The user can work around this by writing an adjusted value to the TMR0 register. Counter mode is selected by setting the T0CS bit (T0CON register). In counter mode, Timer0 will increment either on every rising or falling edge of the T0CKI pin. The incrementing edge is determined by the Timer0 Source Edge Select bit T0SE (T0CON register). Clearing the T0SE bit selects the rising edge. Restrictions on the external clock input are discussed in detail in Section 13.5.1. 13.4 Timer0 Interrupt The TMR0 interrupt flag bit is set when the TMR0 register overflows. When TMR0 is in 8-bit mode, this means the overflow from FFh to 00h. When TMR0 is in 16-bit mode, this means the overflow from FFFFh to 0000h. This overflow sets the TMR0IF bit (INTCON register). The interrupt can be disabled by clearing the TMR0IE bit (INTCON register). The TMR0IF bit must be cleared in software by the interrupt service routine. The TMR0 interrupt cannot awaken the processor from SLEEP, since the timer is shut off during SLEEP. See Figure 13-3 for Timer0 interrupt timing. Figure 13-3: TMR0 Interrupt Timing Q1 Q3 Q4 Q2 Q1 Q3 Q4 Q2 Q1 Q3 Q4 Q2 Q1 Q3 Q4 Q2 Q1 Q3 Q4 Q2 1 1 OSC1 CLKO(3) 8-bit Timer0 TMR0IF bit (INTCON<2>) FEh GIE bit (INTCON<7>) INSTRUCTION PC Instruction fetched PC PC + 2 PC + 4 PC + 4 0008h Instruction executed Inst (PC) Inst (PC-2) Inst (PC+2) Inst (PC) Inst (0008h) Dummy cycle Dummy cycle FFh 00h 01h 02h FLOW 16-bit Timer0 FFFEh FFFFh 0000h 0001h 0002h 1 Inst (PC+4) Inst (PC+2) Note 1: Interrupt flag bit TMR0IF is sampled here (every Q1). 2: Interrupt latency = 4TCY where TCY = instruction cycle time. 3: CLKO is available only in RC oscillator mode. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39513A-page 13-6  2000 Microchip Technology Inc. 13.5 Using Timer0 with an External Clock When an external clock input is used for Timer0, it must meet certain requirements as detailed in 13.5.1 “External Clock Synchronization”. The requirements ensure the external clock can be synchronized with the internal phase clock (TSCLK). Also, there is a delay in the actual incrementing of Timer0 after synchronization. 13.5.1 External Clock Synchronization When no prescaler is used, the external clock input is used instead of the prescaler output. The synchronization of T0CKI with the internal phase clocks is accomplished by sampling the prescaler output on the Q2 and Q4 cycles of the internal phase clocks (Figure 13-4). Therefore, it is necessary for T0CKI to be high for at least 2TSCLK (and a small RC delay) and low for at least 2TSCLK (and a small RC delay). Refer to parameters 40, 41 and 42 in the electrical specification of the desired device. When a prescaler is used, the external clock input is divided by the prescaler so that the prescaler output is symmetrical. For the external clock to meet the sampling requirement, the ripple-counter must be taken into account. Therefore, it is necessary for T0CKI to have a period of at least 4TSCLK (and a small RC delay) divided by the prescaler value. The only requirement on T0CKI high and low time is that they do not violate the minimum pulse width requirement. Refer to parameters 40, 41 and 42 in the electrical specification of the desired device. 13.5.2 TMR0 Increment Delay Since the prescaler output is synchronized with the internal clocks, there is a small delay from the time the external clock edge occurs to the time the Timer0 module is actually incremented. Figure 13-4 shows the delay from the external clock edge to the timer incrementing. Figure 13-4: Timer0 Timing with External Clock Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 External Clock Input or Prescaler output(2) External Clock/Prescaler Output after sampling Increment Timer0 (Q4) Timer0 T0 T0 + 1 T0 + 2 Small pulse misses sampling (3) (1) Note 1: Delay from clock input change to Timer0 increment is 3Tosc to 7Tosc. (Duration of Q = Tosc). Therefore, the error in measuring the interval between two edges on Timer0 input = ±4Tosc max. 2: External clock if no prescaler selected, prescaler output otherwise. 3: The arrows indicate the points in time where sampling occurs. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39513A-page 13-7 Section 13. Timer0 Timer0 14 13.6 Timer0 Prescaler An 8-bit counter is available as a prescaler for the Timer0 module (Figure 13-5). The PSA and T0PS2:T0PS0 bits (T0CON register) are the prescaler enable and prescale select bits. All instructions that write to the Timer0 (TMR0) register (such as: CLRF TMR0; BSF TMR0,x; MOVWF TMR0; ....etc.) will clear the prescaler if enabled. The prescaler is not readable or writable. Writes to TMR0H do not clear the Timer0 prescaler in 16-bit mode, because a write to TMR0H only modifies the Timer0 latch and does not change the contents of Timer0. The prescaler is only cleared on writes to TMR0L. Figure 13-5: Block Diagram of the Timer0 Prescaler The prescaler for Timer0 is enabled or disabled in software by the PSA bit (T0CON register). Setting the PSA bit will enable the prescaler. The prescaler can be modified under software control through the T0PS2:T0PS0 bits. This allows the prescaler reload value to be readable and writable. The prescaler count value (the contents of the prescaler) can not be read or written. When the prescaler is enabled, prescale values of 1:2, 1:4, ..., 1:256 are selectable. T0CKI pin T0SE M U X CLKO (=FOSC/4) TMR0L 8-bit Prescaler T0PS2:T0PS0 8 - to - 1 MUX 8 M U X 0 1 1 0 Data Bus Set flag bit 8 PSA T0CS TMR0 TMR0IF on overflow Data Bus 8 T08BIT T08BIT Set flag bit TMR0IF on overflow for TMR0L TMR0H high reg 8 Synchronization 2 TCY delay Note: T0CS, T0SE, PSA, T0PS2:T0PS0 are located in the T0CON register. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39513A-page 13-8  2000 Microchip Technology Inc. Any write to the TMR0 register will cause a 2 instruction cycle (2TCY) inhibit. That is, after the TMR0 register has been written with the new value, TMR0 will not be incremented until the third instruction cycle later (Figure 13-6). When the prescaler is assigned to the Timer0 module, any write to the TMR0 register will immediately update the TMR0 register and clear the prescaler. The incrementing of Timer0 (TMR0 and Prescaler) will also be inhibited 2 instruction cycles (TCY). So if the prescaler is configured as 2, then after a write to the TMR0 register, TMR0 will not increment for 4 Timer0 clocks (Figure 13-7). After that, TMR0 will increment every prescaler number of clocks later. Figure 13-6: Timer0 Timing: Internal Clock/No Prescale Figure 13-7: Timer0 Timing: Internal Clock/Prescale 1:2 Table 13-1: Registers Associated with Timer0 Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other resets TMR0L Timer0 Module’s Low Byte Register xxxx xxxx uuuu uuuu TMR0H Timer0 Module’s High Byte Register 0000 0000 0000 0000 INTCON GIE/GIEH PEIE/GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u T0CON TMR0ON T08BIT T0CS T0SE PSA T0PS2 T0PS1 T0PS0 1111 1111 1111 1111 TRISA — — PORTA Data Direction Register --11 1111 --11 1111 Legend: x = unknown, u = unchanged, - = unimplemented locations read as '0'. Shaded cells are not used by Timer0. PC-2 PC Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 (Program Counter) Instruction Fetch TMR0 PC PC+2 PC+4 PC+6 PC+8 PC+10 PC+12 T0 T0+1 T0+2 NT0 NT0 NT0 NT0+1 NT0+2 T0 MOVWF TMR0 MOVF TMR0,W MOVF TMR0,W MOVF TMR0,W MOVF TMR0,W MOVF TMR0,W Write TMR0 executed Read TMR0 reads NT0 Read TMR0 reads NT0 Read TMR0 reads NT0 Read TMR0 reads NT0 + 1 Read TMR0 reads NT0 + 2 Instruction Executed PC+6 PC-2 PC Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 (Program Counter) Instruction Fetch TMR0 PC PC+2 PC+4 PC+6 PC+8 PC+10 PC+12 T0 NT0+1 MOVWF TMR0 MOVF TMR0,W MOVF TMR0,W MOVF TMR0,W MOVF TMR0,W MOVF TMR0,W Write TMR0 executed Read TMR0 reads NT0 Read TMR0 reads NT0 Read TMR0 reads NT0 Read TMR0 reads NT0 Read TMR0 reads NT0 + 1 T0+1 NT0 Instruction Execute 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39513A-page 13-9 Section 13. Timer0 Timer0 14 13.7 Initialization Since Timer0 has a software programmable clock source, there are two examples to show the initialization of Timer0 with each source. Example 13-1 shows the initialization for the internal clock source (timer mode), while Example 13-2 shows the initialization for the external clock source (counter mode). Example 13-1: Timer0 Initialization (Internal Clock Source) Example 13-2: Timer0 Initialization (External Clock Source) CLRF TMR0 ; Clear Timer0 register CLRF INTCON ; Disable interrupts and clear T0IF BCF INTCON2, RBPU ; MOVLW 0x80 ; PortB pull-ups are disabled, MOVWF T0CON ; Interrupt on rising edge of RB0, ; TMR0 = 16-Bit Time ; Timer0 increment from internal clock ; with a prescaler of 1:2. ;** BSF INTCON, T0IE ; Enable TMR0 interrupt ;** BSF INTCON, GIE ; Enable all interrupts ; ; The TMR0 interrupt is disabled, do polling on the overflow bit ; T0_OVFL_WAIT BTFSS INTCON, T0IF GOTO T0_OVFL_WAIT ; Timer has overflowed CLRF TMR0 ; Clear Timer0 register CLRF INTCON ; Disable interrupts and clear T0IF BCF INTCON2, RBPU ; MOVLW 0xBF ; PortB pull-ups are enabled, MOVWF T0CON ; Interrupt on falling edge of RB0 ; Timer0 increment from external clock ; on the high-to-low transition ; of T0CKI ; with a prescaler of 1:256. ;** BSF INTCON, T0IE ; Enable TMR0 interrupt ;** BSF INTCON, GIE ; Enable all interrupts ; ; The TMR0 interrupt is disabled, do polling on the overflow bit ; T0_OVFL_WAIT BTFSS INTCON, T0IF GOTO T0_OVFL_WAIT ; Timer has overflowed 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39513A-page 13-10  2000 Microchip Technology Inc. 13.8 Design Tips Question 1: I am implementing a counter/clock, but the clock loses time or is inaccurate. Answer 1: If you are polling TMR0 to see if it has rolled over to zero, you could do this by executing: wait MOVF TMR0,W ; read the timer into W BTFSS STATUS,Z ; see if it was zero, if so, ; break from loop GOTO wait ; if not zero yet, keep waiting Two possible scenarios to lose clock cycles are: 1. If you are incrementing TMR0 from the internal instruction clock (or an external source that is about as fast), the overflow could occur during the two cycle GOTO, so you could miss it. In this case, the TMR0 source should be prescaled. 2. When writing to TMR0, two instruction clock cycles are lost. Often you have a specific time period you want to count, say 100 decimal. In that case, you might put 156 into TMR0 (256 - 100 = 156). However, since two instruction cycles are lost when you write to TMR0 (for internal logic synchronization), you should actually write 158 to the timer. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39513A-page 13-11 Section 13. Timer0 Timer0 14 13.9 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to Timer0 are: Title Application Note # Frequency Counter Using PIC16C5X AN592 A Clock Design using the PIC16C54 for LED Display and Switch Inputs AN590 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39513A-page 13-12  2000 Microchip Technology Inc. 13.10 Revision History Revision A This is the initial released revision of the Enhanced MCU Timer0 Module description. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39514A-page 14-1 Timer1 14 Section 14. Timer1 HIGHLIGHTS This section of the manual contains the following major topics: 14.1 Introduction .................................................................................................................. 14-2 14.2 Control Register ........................................................................................................... 14-4 14.3 Timer1 Operation in Timer Mode ................................................................................. 14-5 14.4 Timer1 Operation in Synchronized Counter Mode....................................................... 14-5 14.5 Timer1 Operation in Asynchronous Counter Mode...................................................... 14-6 14.6 Reading and Writing of Timer1 .................................................................................... 14-7 14.7 Timer1 Oscillator........................................................................................................ 14-10 14.8 Typical Application ..................................................................................................... 14-11 14.9 Sleep Operation ......................................................................................................... 14-12 14.10 Resetting Timer1 Using a CCP Trigger Output.......................................................... 14-12 14.11 Resetting Timer1 Register Pair (TMR1H:TMR1L) ..................................................... 14-13 14.12 Timer1 Prescaler........................................................................................................ 14-13 14.13 Initialization ................................................................................................................ 14-14 14.14 Design Tips ................................................................................................................ 14-16 14.15 Related Application Notes.......................................................................................... 14-17 14.16 Revision History ......................................................................................................... 14-18 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39514A-page 14-2  2000 Microchip Technology Inc. 14.1 Introduction The Timer1 module is a 16-bit timer/counter consisting of two 8-bit registers (TMR1H and TMR1L) that are readable and writable. The TMR1 register pair (TMR1H:TMR1L) increments from 0000h to FFFFh and rolls over to 0000h. If enabled, the Timer1 Interrupt is generated on overflow that is latched in the TMR1IF interrupt flag bit. This interrupt can be enabled/disabled by setting/clearing the TMR1IE interrupt enable bit. Timer1 can operate in one of three modes: • As a synchronous timer • As a synchronous counter • As an asynchronous counter The operating mode is determined by clock select bit, TMR1CS (T1CON register), and the synchronization bit, T1SYNC (Figure 14-1). In timer mode, Timer1 increments every instruction cycle. In counter mode, it increments on every rising edge of the external clock input pin T1OSI. Timer1 can be turned on and off using theTMR1ON control bit (T1CON register). Timer1 also has an internal “reset input”, which can be generated by a CCP module. Timer1 has the capability to operate off an external crystal. When the Timer1 oscillator is enabled (T1OSCEN is set), the T1OSI and T1OSO pins become inputs, so their corresponding TRIS values are ignored. Figure 14-1: Timer1 Block Diagram TMR1H TMR1L T1SYNC TMR1CS T1CKPS1:T1CKPS0 SLEEP input TMR1ON on/off Prescaler 1, 2, 4, 8 Synchronize det 1 0 0 1 Synchronized Clock Input 2 Set TMR1IF flag bit on Overflow TMR1 CLR CCP Special Event Trigger T1OSCEN Enable Oscillator T1OSI (1) T1OSO/T1CKI T1OSC Note 1: When enable bit T1OSCEN is cleared, the inverter and feedback resistor are turned off. This eliminates power drain. Fosc/4 Internal Clock 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39514A-page 14-3 Section 14. Timer1 Timer1 14 Figure 14-2: Timer1 Block Diagram 16-Bit Read/Write Mode Timer 1 TMR1L T1SYNC TMR1CS T1CKPS1:T1CKPS0 SLEEP input T1OSCEN Enable Oscillator (1) TMR1IF Overflow Interrupt Fosc/4 Internal Clock TMR1ON on/off Prescaler 1, 2, 4, 8 Synchronize det 1 0 0 1 Synchronized Clock Input 2 T13CKI/ T1OSI TMR1 flag bit Note 1: When enable bit T1OSCEN is cleared, the inverter and feedback resistor are turned off. This eliminates power drain. Data Bus<7:0> 8 TMR1H 8 8 8 Read TMR1L Write TMR1L T1OSO High Byte 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39514A-page 14-4  2000 Microchip Technology Inc. 14.2 Control Register Register 14-1 shows the Timer1 Control register. This register controls the operating mode of the Timer1 module and contains the Timer1 oscillator enable bit (T1OSCEN). Register 14-1: T1CON: Timer1 Control Register R/W-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 RD16 — T1CKPS1 T1CKPS0 T1OSCEN T1SYNC TMR1CS TMR1ON bit 7 bit 0 bit 7 RD16: 16-bit Read/Write Mode Enable bit 1 = Enables register Read/Write of Timer1 in one 16-bit operation 0 = Enables register Read/Write of Timer1 in two 8-bit operations bit 6 Unimplemented: Read as '0' bit 5:4 T1CKPS1:T1CKPS0: Timer1 Input Clock Prescale Select bits 11 = 1:8 Prescale value 10 = 1:4 Prescale value 01 = 1:2 Prescale value 00 = 1:1 Prescale value bit 3 T1OSCEN: Timer1 Oscillator Enable bit 1 = Timer1 Oscillator is enabled 0 = Timer1 Oscillator is shut off. The oscillator inverter and feedback resistor are turned off to eliminate power drain. bit 2 T1SYNC: Timer1 External Clock Input Synchronization Select bit When TMR1CS = 1: 1 = Do not synchronize external clock input 0 = Synchronize external clock input When TMR1CS = 0: This bit is ignored. Timer1 uses the internal clock when TMR1CS = 0. bit 1 TMR1CS: Timer1 Clock Source Select bit 1 = External clock from pin T1OSO/T13CKI (on the rising edge) 0 = Internal clock (FOSC/4) bit 0 TMR1ON: Timer1 On bit 1 = Enables Timer1 0 = Stops Timer1 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39514A-page 14-5 Section 14. Timer1 Timer1 14 14.3 Timer1 Operation in Timer Mode Timer mode is selected by clearing the TMR1CS (T1CON register) bit. In this mode, the input clock to the timer is FOSC/4. The synchronize control bit, T1SYNC (T1CON register), has no effect since the internal clock is always synchronized. 14.4 Timer1 Operation in Synchronized Counter Mode Counter mode is selected by setting the TMR1CS bit. In this mode, the timer increments on every rising edge of clock input on the T1OSI pin when the Timer1 oscillator enable bit (T1OSCEN) is set, or the T1OSO/T13CKI pin when the T1OSCEN bit is cleared. If the T1SYNC bit is cleared, then the external clock input is synchronized with internal phase clocks. The synchronization is done after the prescaler stage. The prescaler operates asynchronously. The timer increments at the Q4:Q1 edge. In this configuration, during SLEEP mode, Timer1 will not increment even if the external clock is present, since the synchronization circuit is shut off. The prescaler however will continue to increment. 14.4.1 External Clock Input Timing for Synchronized Counter Mode When an external clock input is used for Timer1 in synchronized counter mode, it must meet certain requirements. The external clock requirement is due to internal phase clock (TSCLK) synchronization. Also, there is a delay in the actual incrementing of TMR1 after synchronization. When the prescaler is 1:1, the external clock input is the same as the prescaler output. The synchronization of T1CKI with the internal phase clocks is accomplished by sampling the prescaler output on alternating TscLK clocks of the internal phase clocks. Therefore, it is necessary for the T1CKI pin to be high for at least 2TscLK (and a small RC delay) and low for at least 2TscLK (and a small RC delay). Refer to parameters 45, 46, and 47 in the “Electrical Specifications” section. When a prescaler other than 1:1 is used, the external clock input is divided by the asynchronous prescaler so that the prescaler output is symmetrical. In order for the external clock to meet the sampling requirement, the prescaler counter must be taken into account. Therefore, it is necessary for the T1CKI pin to have a period of at least 4TscLK (and a small RC delay) divided by the prescaler value. Another requirement on the T1CKI pin high and low time is that they do not violate the minimum pulse width requirements). Refer to parameters 40, 42, 45, 46, and 47 in the “Electrical Specifications” section. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39514A-page 14-6  2000 Microchip Technology Inc. 14.5 Timer1 Operation in Asynchronous Counter Mode If T1SYNC (T1CON register) is set, the external clock input is not synchronized. The timer continues to increment asynchronously to the internal phase clocks. The timer will continue to run during SLEEP and can generate an interrupt on overflow that will wake-up the processor. However, special precautions in software are needed to read/write the timer (Subsection 14.6.4 “Reading and Writing Timer1 in Asynchronous Counter Mode with RD16 = 0” ). Since the counter can operate in sleep, Timer1 can be used to implement a true real-time clock. The timer increments at the Q4:Q1 and Q2:Q3 edges. In asynchronous counter mode, Timer1 cannot be used as a time-base for capture or compare operations. 14.5.1 External Clock Input Timing with Unsynchronized Clock If the T1SYNC control bit is set, the timer will increment completely asynchronously. The input clock must meet certain minimum high time and low time requirements. Refer to the Device Data Sheet “Electrical Specifications” section, timing parameters 45, 46, and 47. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39514A-page 14-7 Section 14. Timer1 Timer1 14 14.6 Reading and Writing of Timer1 Timer1 has modes that allow the 16-bit timer register to be read/written as two 8-bit registers or one 16-bit register. The mode depends on the state of the RD16 bit. The following subsections discuss this operation. 14.6.1 Timer1 and 16-bit Read/Write Modes Timer1 can be configured for 16-bit reads and writes. When the RD16 control bit (T1CON register) is set, the address for TMR1H is mapped to a buffer register for the high byte of Timer1. A read from TMR1L will load the contents of the high byte of Timer1 into the Timer1 high byte buffer. This provides the user with the ability to accurately read all 16 bits of Timer1 without having to determine whether a read of the high byte followed by a read of the low byte is valid due to a rollover between reads. 14.6.2 16-bit Mode Timer Write A write to the high byte of Timer1 must also take place through the TMR1H buffer register. Timer1 high byte is updated with the contents of TMR1H when a write occurs to TMR1L. This allows a user to write all 16 bits to both the high and low bytes of Timer1 at once (See Figure 14-3). The high byte of Timer1 is not directly readable or writable in this mode. All reads and writes must take place through the Timer1 high byte buffer register. Writes to TMR1H do not clear the Timer1 prescaler. The prescaler is only cleared on writes to TMR1L. 14.6.3 16-bit Read-Modify-Write Read-modify-write instructions like BSF or BCF will read the contents of a register, make the appropriate changes, and place the result back into the register. In the case of Timer1 when configured in 16-bit mode, the read portion of a read-modify-write instruction of TMR1L will not update the contents of the TMR1H buffer. The TMR1H buffer will remain unchanged. When the write of TMR1L portion of the instruction takes place, the contents of TMR1H will be placed into the high byte of Timer1. Figure 14-3: Timer1 Block Diagram When Configured in 16-bit Read/Write Mode Timer 1 TMR1L T1SYNC TMR1CS T1CKPS1:T1CKPS0 SLEEP input TMR1IF Overflow Interrupt FOSC/4 Internal Clock TMR1ON on/off Prescaler 1, 2, 4, 8 Synchronize det 1 0 0 1 Synchronized Clock Input 2 TMR1 flag bit high byte Data Bus<7:0> 8 TMR1H 8 8 8 Read TMR1L Write TMR1L T1OSC T1OSCEN Enable Oscillator (1) T13CKI/ T1OSO TTIP Note 1: When enable bit T1OSCEN is cleared, the inverter and feedback resistor are turned off. This eliminates power drain. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39514A-page 14-8  2000 Microchip Technology Inc. 14.6.4 Reading and Writing Timer1 in Asynchronous Counter Mode with RD16 = 0 Reading TMR1H or TMR1L while the timer is running from an external asynchronous clock will ensure a valid read (taken care of in hardware). However, the user should keep in mind that reading the 16-bit timer in two 8-bit values itself poses certain problems, since the timer may overflow between the reads. For writes, it is recommended that the user simply stop the timer and write the desired values. A write contention may occur by writing to the timer registers while the register is incrementing. This may produce an unpredictable value in the timer register. Reading the 16-bit value requires some care, since two separate reads are required to read the entire 16-bits. Example 14-1 shows why this may not be a straight forward read of the 16-bit register. Example 14-1: Reading 16-bit Register Issues TMR1 Sequence 1 Sequence 2 Action TMPH:TMPL Action TMPH:TMPL 04FFh READ TMR1L xxxxh READ TMR1H xxxxh 0500h Store in TMPL xxFFh Store in TMPH 04xxh 0501h READ TMR1H xxFFh READ TMR1L 04xxh 0502h Store in TMPH 05FFh Store in TMPL 0401h 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39514A-page 14-9 Section 14. Timer1 Timer1 14 Example 14-2 shows a routine to read the 16-bit timer value without experiencing the issues shown in Example 14-1. This is useful if the timer cannot be stopped. Example 14-2: Reading a 16-bit Free-Running Timer Writing a 16-bit value to the 16-bit TMR1 register is straightforward. First the TMR1L register is cleared to ensure that there are many Timer1 clock/oscillator cycles before there is a rollover into the TMR1H register. The TMR1H register is then loaded, and finally the TMR1L register is loaded. Example 14-3 shows a routine that does a 16-bit write to a Free Running Timer. Example 14-3: Writing a 16-bit Free Running Timer ; All interrupts are disabled MOVF TMR1H, W ; Read high byte MOVWF TMPH ; MOVF TMR1L, W ; Read low byte MOVWF TMPL ; MOVF TMR1H, W ; Read high byte SUBWF TMPH, W ; Sub 1st read with 2nd read BTFSC STATUS,Z ; Is result = 0 GOTO CONTINUE ; Good 16-bit read ; ; TMR1L may have rolled over between the read of the high and low bytes. ; Reading the high and low bytes now will read a good value. ; MOVF TMR1H, W ; Read high byte MOVWF TMPH ; MOVF TMR1L, W ; Read low byte MOVWF TMPL ; ; Re-enable the Interrupt (if required) CONTINUE ; Continue with your code ; All interrupts are disabled CLRF TMR1L ; Clear Low byte, Ensures no ; rollover into TMR1H MOVLW HI_BYTE ; Value to load into TMR1H MOVWF TMR1H, F ; Write High byte MOVLW LO_BYTE ; Value to load into TMR1L MOVWF TMR1H, F ; Write Low byte ; Re-enable the Interrupt (if required) CONTINUE ; Continue with your code 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39514A-page 14-10  2000 Microchip Technology Inc. 14.7 Timer1 Oscillator An alternate crystal oscillator circuit is built into the device. The output of this oscillator can be selected as the input into Timer1. The Timer1 oscillator is primarily intended to operate as a timebase for the timer modules; therefore, the oscillator is primarily intended for a 32 kHz crystal, which is an ideal frequency for real-time keeping. In real-time applications, the timer needs to increment during SLEEP, so SLEEP does not disable the Timer1 oscillator. For many applications, power consumption is also an issue, so the oscillator is designed to minimize power consumption. The Timer1 oscillator is enabled by setting the T1OSCEN control bit (T1CON register). After the Timer1 oscillator is enabled, the user must provide a software time delay to ensure proper oscillator start-up. Table 14-1 shows the capacitor selection for the Timer1 oscillator. Table 14-1: Capacitor Selection for the Timer1 Oscillator Note: The Timer1 oscillator allows the counter to operate (increment) when the device is in sleep mode. This allows Timer1 to be used as a real-time clock. Osc Type Freq C1 C2 LP 32 kHz 33 pF 33 pF 100 kHz 15 pF 15 pF 200 kHz 15 pF 15 pF Crystals Tested: 32.768 kHz Epson C-001R32.768K-A ± 20 PPM 100 kHz Epson C-2 100.00 KC-P ± 20 PPM 200 kHz STD XTL 200.000 kHz ± 20 PPM Note 1: Higher capacitance increases the stability of oscillator but also increases the start-up time. 2: Since each resonator/crystal has its own characteristics, the user should consult the resonator/crystal manufacturer for appropriate values of external components. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39514A-page 14-11 Section 14. Timer1 Timer1 14 14.8 Typical Application In Figure 14-4 an example application is given, where Timer1 is driven from an external 32 kHz oscillator. The external 32 kHz oscillator is typically used in applications where real-time needs to be kept, but it is also desirable to have the lowest possible power consumption. The Timer1 oscillator allows the device to be placed in sleep while the timer continues to increment. When Timer1 overflows, the interrupt wakes up the device so that the appropriate registers can be updated. Figure 14-4: Timer1 Application In this example, a 32 kHz crystal is used as the time base for the Real Time Clock. If the clock needs to be updated at 1 second intervals, then the Timer1 must be loaded with a value to allow the Timer1 to overflow at the desired rate. In the case of a 1 second Timer1 overflow, the TMR1H register should be loaded with a value of 80k after each overflow. 8 4 4 4 4x4 Keypad Current Sink TMR1 VSS VDD 32 kHz Backup Battery Power-Down Detect T1OSI T1OSO OSC1 TT1P Note: The TMR1L register should never be modified, since an external clock is asychronous to the system clock. Writes to the TRM1L register may corrupt the real time counter value causing inaccuracies. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39514A-page 14-12  2000 Microchip Technology Inc. 14.9 Sleep Operation When Timer1 is configured for asynchronous operation, the TMR1 registers will continue to increment for each timer clock (or prescale multiple of clocks). When the TMR1 register overflows, the TMR1IF bit will get set. If enabled, this will generate an interrupt that will wake the processor from sleep mode. The Timer1 oscillator will add a delta current, due to the operation of this circuitry. That is, the power-down current will no longer only be the leakage current of the device, but also the active current of the Timer1 oscillator and other circuitry. 14.10 Resetting Timer1 Using a CCP Trigger Output If a CCP module is configured in compare mode to generate a “Special Event Trigger” (CCP1M3:CCP1M0 = 1011), this signal resets Timer1. Timer1 must be configured for either timer or synchronized counter mode to take advantage of the special event trigger feature. If Timer1 is running in asynchronous counter mode, this reset operation may not work and should not be used. In the event that a write to Timer1 coincides with a special event trigger from the CCP module, the write will take precedence. In this mode of operation, the CCPRxH:CCPRxL register pair effectively becomes the period register for Timer1. 14.10.1 CCP Trigger and A/D Module Some devices that have the CCP Trigger capability also have an A/D module. These devices may be able to be configured, so the “Special Event Trigger” not only resets the Timer1 registers, 0but will start an A/D conversion. This allows a constant sampling rate for the A/D, as specified by the value of the compare registers. Note: The special event trigger from the CCP module does not set interrupt flag bit TMR1IF. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39514A-page 14-13 Section 14. Timer1 Timer1 14 14.11 Resetting Timer1 Register Pair (TMR1H:TMR1L) TMR1H and TMR1L registers are not cleared on any reset, only by the CCP special event triggers. T1CON register is reset to 00h on a Power-on Reset or a Brown-out Reset. In any other reset, the register is unaffected. Timer1 is the default time base for the CCP1 and CCP2 modules. The timer can be disabled as the time base for either CCP1, CCP2, or both, and Timer3 can be substituted. This is achieved by setting control bits in the Timer3 control register. This is explained in Section 16.8 - Timer3 and CCPx Enable. When Timer1 is disabled as a the time base for a CCP, the reset on Compare will have no effect on Timer1. 14.12 Timer1 Prescaler The prescaler counter is cleared on writes to the TMR1H or TMR1L registers. 14.12.1 Timer1 Prescaler 16-bit Read/WriteMode Writes to TMR1H do not clear the Timer1 prescaler in 16-bit read/write mode, because a write to TMR1H only modifies the Timer1 latch and does not change the contents of Timer1. The prescaler is only cleared on writes to TMR1L. Table 14-2: Registers Associated with Timer1 as a Timer/Counter Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets INTCON GIE PEIE T0IE INTE RBIE T0IF INTF RBIF 0000 000x 0000 000u PIR TMR1IE (1) 0 0 PIE TMR1IE (1) 0 0 IPR TMR1IP (1) 0 0 TMR1L Holding register for the Least Significant Byte of the 16-bit TMR1 register xxxx xxxx uuuu uuuu TMR1H Holding register for the Most Significant Byte of the 16-bit TMR1 register xxxx xxxx uuuu uuuu T1CON RD16 — T1CKPS1 T1CKPS0 T1OSCEN T1SYNC TMR1CS TMR1ON --00 0000 --uu uuuu Legend: x = unknown,u = unchanged,- = unimplemented read as '0'. Shaded cells are not used by the Timer1 module. Note 1: The placement of this bit is device dependent. 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39514A-page 14-14  2000 Microchip Technology Inc. 14.13 Initialization Since Timer1 has a software programmable clock source, there are three examples to show the initialization of each mode. Example 14-4 shows the initialization for the internal clock source, Example 14-5 shows the initialization for the external clock source, and Example 14-6 shows the initialization of the external oscillator mode. Example 14-4: Timer1 Initialization (Internal Clock Source) Example 14-5: Timer1 Initialization (External Clock Source) CLRF T1CON ; Stop Timer1, Internal Clock Source, ; T1 oscillator disabled, ; prescaler = 1:1 CLRF TMR1H ; Clear Timer1 High byte register CLRF TMR1L ; Clear Timer1 Low byte register CLRF INTCON ; Disable interrupts CLRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x30 ; Internal Clock source ; with 1:8 prescaler MOVWF T1CON ; Timer1 is stopped and ; T1 osc is disabled BSF T1CON, TMR1ON ; Timer1 starts to increment ; ; The Timer1 interrupt is disabled, do polling on the overflow bit ; T1_OVFL_WAIT BTFSS PIR1, TMR1IF GOTO T1_OVFL_WAIT ; ; Timer has overflowed ; BCF PIR1, TMR1IF CLRF T1CON ; Stop Timer1, Internal Clock Source, ; T1 oscillator disabled, ; prescaler = 1:1 CLRF TMR1H ; Clear Timer1 High byte register CLRF TMR1L ; Clear Timer1 Low byte register CLRF INTCON ; Disable interrupts CLRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x32 ; External Clock source ; with 1:8 prescaler MOVWF T1CON ; Clock source is ; synchronized to device ; Timer1 is stopped ; and T1 osc is disabled BSF T1CON, TMR1ON ; Timer1 starts to increment ; ; The Timer1 interrupt is disabled, do polling on the overflow bit ; T1_OVFL_WAIT BTFSS PIR1, TMR1IF GOTO T1_OVFL_WAIT ; ; Timer has overflowed ; BCF PIR1, TMR1IF 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39514A-page 14-15 Section 14. Timer1 Timer1 14 Example 14-6: Timer1 Initialization (External Oscillator Clock Source) CLRF T1CON ; Stop Timer1, Internal Clock Source, ; T1 oscillator disabled, ; prescaler = 1:1 CLRF TMR1H ; Clear Timer1 High byte register CLRF TMR1L ; Clear Timer1 Low byte register CLRF INTCON ; Disable interrupts CLRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x3E ; External Clock source ; with oscillator MOVWF T1CON ; circuitry, 1:8 prescaler, ; Clock source is ; asynchronous to device ; Timer1 is stopped BSF T1CON, TMR1ON ; Timer1 starts to increment ; ; The Timer1 interrupt is disabled, do polling on the overflow bit ; T1_OVFL_WAIT BTFSS PIR1, TMR1IF GOTO T1_OVFL_WAIT ; ; Timer has overflowed ; BCF PIR1, TMR1IF 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39514A-page 14-16  2000 Microchip Technology Inc. 14.14 Design Tips Question 1: Timer1 does not seem to be keeping accurate time. Answer 1: There are a few reasons that this could occur: 1. You should never write to Timer1 where that could cause the loss of time. In most cases, that means you should not write to the TMR1L register, but if the conditions are OK, you may write to the TMR1H register. Normally, you write to the TMR1H register if you want the Timer1 overflow interrupt to be sooner than the full 16-bit time-out. 2. You should ensure that your layout uses good PCB layout techniques so noise does not couple onto the Timer1/Timer3 oscillator lines. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39514A-page 14-17 Section 14. Timer1 Timer1 14 14.15 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Baseline, the Midrange, or High-end families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to Timer1 are: Title Application Note # Using Timer1 in Asynchronous Clock Mode AN580 Low Power Real Time Clock AN582 Yet another Clock using the PIC16C92X AN649 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39514A-page 14-18  2000 Microchip Technology Inc. 14.16 Revision History Revision A This is the initial released revision of the Timer1 module description. 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39515A-page 15-1 Timer2 15 Section 15. Timer2 HIGHLIGHTS This section of the manual contains the following major topics: 15.1 Introduction .................................................................................................................. 15-2 15.2 Control Register ........................................................................................................... 15-3 15.3 Timer Clock Source ..................................................................................................... 15-4 15.4 Timer (TMR2) and Period (PR2) Registers.................................................................. 15-4 15.5 TMR2 Match Output..................................................................................................... 15-4 15.6 Clearing the Timer2 Prescaler and Postscaler............................................................. 15-4 15.7 Sleep Operation ........................................................................................................... 15-4 15.8 Initialization .................................................................................................................. 15-5 15.9 Design Tips .................................................................................................................. 15-6 15.10 Related Application Notes............................................................................................ 15-7 15.11 Revision History ........................................................................................................... 15-8 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39515A-page 15-2  2000 Microchip Technology Inc. 15.1 Introduction Timer2 is an 8-bit timer with a prescaler, a postscaler and a period register. Using the prescaler and postscaler at their maximum settings, the overflow time is the same as a 16-bit timer. Timer2 is the PWM time-base when the CCP module(s) is used in the PWM mode. Figure 15-1 shows a block diagram of Timer2. The postscaler counts the number of times that the TMR2 register matched the PR2 register. This can be useful in reducing the overhead of the interrupt service routine on the CPU performance. Figure 15-1: Timer2 Block Diagram Comparator TMR2 Sets flag TMR2 reg output (1) Reset Postscaler Prescaler PR2 reg 2 FOSC/4 1:1 1:16 1:1, 1:4, 1:16 EQ 4 bit TMR2IF Note 1: TMR2 register output can be software selected by the SSP Module as a baud clock. to TOUTPS3:TOUTPS0 T2CKPS1:T2CKPS0 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39515A-page 15-3 Section 15. Timer2 Timer2 15 15.2 Control Register Register 15-1 shows the Timer2 control register. The prescaler and postscaler selection of Timer2 are controlled by this register. Register 15-1: T2CON: Timer2 Control Register U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — TOUTPS3 TOUTPS2 TOUTPS1 TOUTPS0 TMR2ON T2CKPS1 T2CKPS0 bit 7 bit 0 bit 7 Unimplemented: Read as '0' bit 6-3 TOUTPS3:TOUTPS0: Timer2 Output Postscale Select bits 0000 = 1:1 Postscale 0001 = 1:2 Postscale • • • 1111 = 1:16 Postscale bit 2 TMR2ON: Timer2 On bit 1 = Timer2 is on 0 = Timer2 is off bit 1-0 T2CKPS1:T2CKPS0: Timer2 Clock Prescale Select bits 00 = Prescaler is 1 01 = Prescaler is 4 1x = Prescaler is 16 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39515A-page 15-4  2000 Microchip Technology Inc. 15.3 Timer Clock Source The Timer2 module has one source of input clock, the device clock (FOSC/4). A prescale option of 1:1, 1:4 or 1:16 is software selected by control bits T2CKPS1:T2CKPS0 (T2CON register). 15.4 Timer (TMR2) and Period (PR2) Registers The TMR2 register is readable and writable, and is cleared on all device resets. Timer2 increments from 00h until it matches PR2 and then resets to 00h on the next increment cycle. PR2 is a readable and writable register. The TMR2 register is cleared and the PR2 register is set when a WDT, POR, MCLR or a BOR reset occurs. Timer2 can be shut off (disabled from incrementing) by clearing the TMR2ON control bit (T2CON register). This minimizes the power consumption of the module. 15.5 TMR2 Match Output The match output of TMR2 goes to two sources: 1. Timer2 Postscaler 2. SSP Clock Input There are 4-bits which select the postscaler. This allows the postscaler a 1:1 to 1:16 scaling (inclusive). After the postscaler overflows, the TMR2 interrupt flag bit (TMR2IF) is set to indicate the Timer2 overflow. This is useful in reducing the software overhead of the Timer2 interrupt service routine, since it will only execute once every postscaler # of matches. The match output of TMR2 is also routed to the Synchronous Serial Port module, which may select this via software, as the clock source for the shift clock. 15.6 Clearing the Timer2 Prescaler and Postscaler The prescaler and postscaler counters are cleared when any of the following occurs: • a write to the TMR2 register • a write to the T2CON register • any device reset (Power-on Reset, MCLR reset, Watchdog Timer Reset, Brown-out Reset) 15.7 Sleep Operation During sleep, TMR2 will not increment. The prescaler will retain the last prescale count, ready for operation to resume after the device wakes from sleep. Table 15-1: Registers Associated with Timer2 Note: If the PR2 register = 00h, the TMR2 register will not increment (Timer2 cleared). Note: When T2CON is written, TMR2 does not clear. Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets INTCON GIE PEIE TMR0IE INTE RBIE TMR0IF INTF RBIF 0000 000x 0000 000u PIR TMR2IF (1) 0 0 PIE TMR2IE (1) 0 0 IPR TMR21P (1) 0 0 TMR2 Timer2 module’s register 0000 0000 0000 0000 T2CON — TOUTPS3 TOUTPS2 TOUTPS1 TOUTPS0 TMR2ON T2CKPS1 T2CKPS0 -000 0000 -000 0000 PR2 Timer2 Period Register 1111 1111 1111 1111 Legend: x = unknown,u = unchanged,- = unimplemented read as '0'. Shaded cells are not used by the Timer2 module. Note 1: The position of this bit is device dependent. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39515A-page 15-5 Section 15. Timer2 Timer2 15 15.8 Initialization Example 15-1 shows how to initialize the Timer2 module, including specifying the Timer2 prescaler and postscaler. Example 15-1:Timer2 Initialization CLRF T2CON ; Stop Timer2, Prescaler = 1:1, ; Postscaler = 1:1 CLRF TMR2 ; Clear Timer2 register CLRF INTCON ; Disable interrupts LRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x72 ; Postscaler = 1:15, Prescaler = 1:16 MOVWF T2CON ; Timer2 is off MOVLW PR2VALUE ; This is the value MOVWF PR2 ; to load into the PR2 register. BSF T2CON, TMR2ON ; Timer2 starts to increment ; ; The Timer2 interrupt is disabled, do polling on the overflow bit ; T2_OVFL_WAIT BTFSS PIR1, TMR2IF ; Has TMR2 interrupt occurred? GOTO T2_OVFL_WAIT ; NO, continue loop ; ; Timer has overflowed ; BCF PIR1, TMR2IF ; YES, clear flag and continue. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39515A-page 15-6  2000 Microchip Technology Inc. 15.9 Design Tips Question 1: Timer2 never seems to increment? Answer 1: Ensure that the Timer2 Period register (PR2) is not 0h. This is because when a period match occurs, the TMR2 register is cleared on the next cycle so Timer2 will never increment. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39515A-page 15-7 Section 15. Timer2 Timer2 15 15.10 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the Timer2 Module are: Title Application Note # Using the CCP Module AN594 Air Flow Control using Fuzzy Logic AN600 Adaptive Differential Pulse Code Modulation using the PIC16/17 AN643 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39515A-page 15-8  2000 Microchip Technology Inc. 15.11 Revision History Revision A This is the initial released revision of the TImer2 module description. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39516A-page 16-1 Timer3 16 Section 16. Timer3 HIGHLIGHTS This section of the manual contains the following major topics: 16.1 Introduction .................................................................................................................. 16-2 16.2 Control Registers ......................................................................................................... 16-3 16.3 Timer3 Operation in Timer Mode ................................................................................. 16-4 16.4 Timer3 Operation in Synchronized Counter Mode....................................................... 16-4 16.5 Timer3 Operation in Asynchronous Counter Mode...................................................... 16-5 16.6 Reading and Writing of Timer3 .................................................................................... 16-6 16.7 Timer3 using the Timer1 Oscillator .............................................................................. 16-9 16.8 Timer3 and CCPx Enable .......................................................................................... 16-10 16.9 Timer3 Prescaler........................................................................................................ 16-10 16.10 16-bit Mode Timer Reads/Writes ............................................................................... 16-11 16.11 Typical Application ..................................................................................................... 16-12 16.12 Sleep Operation ......................................................................................................... 16-13 16.13 Timer3 Prescaler........................................................................................................ 16-13 16.14 Initialization ................................................................................................................ 16-14 16.15 Design Tips ................................................................................................................ 16-16 16.16 Related Application Notes.......................................................................................... 16-17 16.17 Revision History ......................................................................................................... 16-18 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39516A-page 16-2  2000 Microchip Technology Inc. 16.1 Introduction The Timer3 module is a 16-bit timer/counter consisting of two 8-bit registers (TMR3H and TMR3L) that are readable and writable. The TMR3 register pair (TMR3H:TMR3L) increments from 0000h to FFFFh and rolls over to 0000h. The Timer3 Interrupt, if enabled, is generated on overflow, which is latched in the TMR3IF interrupt flag bit. This interrupt can be enabled/disabled by setting/clearing the TMR3IE interrupt enable bit. Timer3 can operate in one of three modes: • As a synchronous timer • As a synchronous counter • As an asynchronous counter Some features of Timer3 include: • TMR3 also has an internal “reset input”, which can be generated by a CCP module. • TMR3 has the capability to operate off an external crystal/clock. • TMR3 is the alternate time base for capture/compare In timer mode, Timer3 increments every instruction cycle. In counter mode, it increments on every rising edge of the external clock input. The Timer3 increment can be enabled/disabled by setting/clearing control bit TMR3ON (T3CON register). Timer3 also has an internal “reset input”. This reset can be generated by a CCP special event trigger (Capture/Compare/PWM) module. See the CCP (Capture/Compare/PWM) section for details. When the Timer1 oscillator is enabled (T1OSCEN, in T1CON, is set), the T1OSCI1 and T1OSO2 pins are configured as oscillator input and output, so the corresponding values in the TRIS register are ignored. The Timer3 module also has a software programmable prescaler. The operating mode is determined by clock select bit, TMR3CS (T3CON register), and the synchronization bit, T3SYNC (Figure 16-1). Figure 16-1: Timer3 Block Diagram TMR3H TMR3L T3SYNC TMR3CS T3CKPS1:T3CKPS0 SLEEP input FOSC/4 Internal Clock TMR3ON on/off Prescaler 1, 2, 4, 8 Synchronize det 1 0 0 1 Synchronized Clock Input 2 Set TMR3IF flag bit on Overflow TMR3 CLR TT1P CCP Special Trigger T3CCPx 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39516A-page 16-3 Section 16. Timer3 Timer3 16 16.2 Control Registers Register 16-1 shows the Timer3 control register. This register controls the operating mode of the Timer3 module and contains the function of the CCP Special Event Trigger. Register 16-1: T3CON: Timer3 Control Register R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 RD16 T3CCP2 T3CKPS1 T3CKPS0 T3CCP1 T3SYNC TMR3CS TMR3ON bit 7 bit 0 bit 7 RD16: 16-bit Read/Write Mode Enable 1 = Enables register Read/Write of Timer3 in one 16-bit operation 0 = Enables register Read/Write of Timer3 in two 8-bit operations bit 6,3 T3CCP2:T3CCP1: Timer3 and Timer1 to CCPx Enable bits 1x = Timer3 is the clock source for compare/capture of the CCP modules 01 = Timer3 is the clock source for compare/capture of CCP2, Timer1 is the clock source for compare/capture of CCP1 00 = Timer1 is the clock source for compare/capture of the CCP modules bit 5:4 T3CKPS1:T3CKPS0: Timer3 Input Clock Prescale Select bits 11 = 1:8 Prescale value 10 = 1:4 Prescale value 01 = 1:2 Prescale value 00 = 1:1 Prescale value bit 2 T3SYNC: Timer3 External Clock Input Synchronization Control bit (Not usable if the system clock comes from Timer1/Timer3) When TMR3CS = 1: 1 = Do not synchronize external clock input 0 = Synchronize external clock input When TMR3CS = 0: This bit is ignored. Timer3 uses the internal clock when TMR3CS = 0. bit 1 TMR3CS: Timer3 Clock Source Select bit 1 = External clock input from T1OSI or T1CKI (on the rising edge after the first falling edge) 0 = Internal clock (FOSC/4) bit 0 TMR3ON: Timer3 On bit 1 = Enables Timer3 0 = Stops Timer3 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39516A-page 16-4  2000 Microchip Technology Inc. 16.3 Timer3 Operation in Timer Mode Timer mode is selected by clearing the TMR3CS (T3CON register) bit. In this mode, the input clock to the timer is FOSC/4. The synchronize control bit, T3SYNC (T3CON register), has no effect since the internal clock is always synchronized. 16.4 Timer3 Operation in Synchronized Counter Mode Counter mode is selected by setting bit TMR3CS. In this mode, the timer increments on every rising edge of input on the T1OSI pin (when enable bit T1OSCEN is set) or the T13CKI pin (when bit T1OSCEN is cleared). If the T3SYNC bit is cleared, then the external clock input is synchronized with internal phase clocks. The synchronization is done after the prescaler stage. The prescaler operates asynchronously. The timer increments at the Q4:Q1 edge. In this configuration, during SLEEP mode, Timer3 will not increment even if an external clock is present, since the synchronization circuit is shut off. The prescaler, however, will continue to increment. 16.4.1 External Clock Input Timing for Synchronized Counter Mode When an external clock input is used for Timer3 in synchronized counter mode, it must meet certain requirements. The external clock requirement is due to internal phase clock (TSCLK) synchronization. Also, there is a delay in the actual incrementing of TMR3 after synchronization. When the prescaler is 1:1, the external clock input is the same as the prescaler output. There is synchronization of T1OSI/T13CKI with the internal phase clocks. Therefore, it is necessary for (T1OSI/T13CKI to be high for at least 2TSCLK (and a small RC delay) and low for at least 2TSCLK (and a small RC relay). Refer to parameters 45, 46, and 47 in the “Electrical Specifications” section. When a prescaler other than 1:1 is used, the external clock input is divided by the asynchronous prescaler, so that the prescaler output is symmetrical. In order for the external clock to meet the sampling requirement, the prescaler counter must be taken into account. Therefore, it is necessary for T1OSI/T1CKI to have a period of at least 4TSCLK (and a small RC delay) divided by the prescaler value. The only requirement on T1OSI/T1CKI high and low time is that they do not violate the minimum pulse width requirements. Refer to parameters 40, 42, 45, 46, and 47 in the “Electrical Specifications” section. Note: Timer3 gets its external clock input from the same source as Timer1. The configuration of the Timer1 and Timer3 clock input will be controlled by the T1OSCEN bit in the Timer1 control register. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39516A-page 16-5 Section 16. Timer3 Timer3 16 16.5 Timer3 Operation in Asynchronous Counter Mode If T3SYNC (T3CON register) is set, the external clock input is not synchronized. The timer continues to increment asynchronously to the internal phase clocks. The timer will continue to run during SLEEP and can generate an interrupt on overflow that will wake-up the processor. However, special precautions in software are needed to read/write the timer (Subsection 16.6.4 “Reading and Writing Timer3 in Asynchronous Counter Mode with RD16 = 0” ). Since the counter can operate in sleep, Timer1 can be used to implement a true real-time clock. The timer increments at the Q4:Q1 and Q2:Q3 edges. In asynchronous counter mode, Timer3 cannot be used as a time-base for capture or compare operations. 16.5.1 External Clock Input Timing with Unsynchronized Clock If the T3SYNC control bit is set, the timer will increment completely asynchronously. The input clock must meet certain minimum high time and low time requirements. Refer to the Device Data Sheet “Electrical Specifications” section, timing parameters 45, 46, and 47. Note: The control bit T3SYNC is not usable when the system clock source comes from the same source as the Timer1/Timer3 clock input, because the T1CKI input will be sampled at one quarter the frequency of the incoming clock. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39516A-page 16-6  2000 Microchip Technology Inc. 16.6 Reading and Writing of Timer3 Timer3 has modes that allow the 16-bit timer register to be read/written as two 8-bit registers or one 16-bit register. The mode depends on the state of the RD16 bit. The follow subsections discuss this operation. 16.6.1 Timer3 and 16-bit Read/Write Modes Timer3 can be configured for 16-bit reads. When the RD16 control bit (T3CON register) is set, the address for TMR3H is mapped to a buffer register for the high byte of Timer3. A read from TMR3L will load the contents of the high byte of Timer3 into the Timer3 high byte buffer. This provides the user with the ability to accurately read all 16-bits of Timer3 without having to determine whether a read of the high byte followed by a read of the low byte is valid due to a rollover between reads. 16.6.2 16-bit Mode Timer Write A write to the high byte of Timer3 must also take place through the TMR3H buffer register. Timer3 high byte is updated with the contents of TMR3H when a write occurs to TMR3L. This allows a user to write all 16 bits to both the high and low bytes of Timer3 at once (See Figure 16-2). The high byte of Timer3 is not directly readable or writable in this mode. All reads and writes must take place through the Timer3 high byte buffer register. Writes to TMR3H do not clear the Timer3 prescaler. The prescaler is only cleared on writes to TMR3L. 16.6.3 16-bit Read-Modify-Write Read-modify-write instructions like BSF or BCF will read the contents of a register, make the appropriate changes, and place the result back into the register. In the case of Timer3 when configured in 16-bit mode, the read portion of a read-modify-write instruction of TMR3L will not update the contents of the TMR3H buffer. The TMR3H buffer will remain unchanged. When the write of TMR3L portion of the instruction takes place, the contents of TMR3H will be placed into the high byte of Timer3. Figure 16-2: Timer3 Block Diagram When Configured in 16-bit Read/Write Mode Timer 3 TMR3L T1SYNC TMR3CS T3CKPS1:T3CKPS0 SLEEP input TMR3IF Overflow Interrupt FOSC/4 Internal Clock TMR3ON on/off Prescaler 1, 2, 4, 8 Synchronize det 1 0 0 1 Synchronized Clock Input 2 TMR1 flag bit high byte Data Bus<7:0> 8 TMR3H 8 8 8 Read TMR3L Write TMR3L TT1P CCP Special Trigger T3CCPx 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39516A-page 16-7 Section 16. Timer3 Timer3 16 16.6.4 Reading and Writing Timer3 in Asynchronous Counter Mode with RD16 = 0 Reading TMR3H or TMR3L while the timer is running from an external asynchronous clock will ensure a valid read (taken care of in hardware). However, the user should keep in mind that reading the 16-bit timer in two 8-bit values poses certain problems, since the timer may overflow between the reads. For writes, it is recommended that the user simply stop the timer and write the desired values. A write contention may occur by writing to the timer registers, while the register is incrementing. This may produce an unpredictable value in the timer register. Reading the 16-bit value requires some care, since two separate reads are required to read the entire 16-bits. Example 16-1 shows why this may not be a straightforward read of the 16-bit register. Example 16-1:Reading 16-bit Register Issues TMR3 Sequence 1 Sequence 2 Action TMPH:TMPL Action TMPH:TMPL 04FFh READ TMR3L xxxxh READ TMR3H xxxxh 0500h Store in TMPL xxFFh Store in TMPH 04xxh 0501h READ TMR3H xxFFh READ TMR3L 04xxh 0502h Store in TMPH 05FFh Store in TMPL 0401h 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39516A-page 16-8  2000 Microchip Technology Inc. Example 16-2 shows a routine to read the 16-bit timer value without experiencing the issues shown in Example 16-1. This is useful if the timer cannot be stopped. Example 16-2:Reading a 16-bit Free-Running Timer Writing a 16-bit value to the 16-bit TMR3 register is straight forward. First the TMR3L register is cleared to ensure that there are many Timer3 clock/oscillator cycles before there is a rollover into the TMR3H register. The TMR3H register is then loaded, and finally, the TMR3L register is loaded. Example 16-3 shows a routine that accomplishes this: Example 16-3:Writing a 16-bit Free Running Timer ; All interrupts are disabled MOVF TMR3H, W ; Read high byte MOVWF TMPH ; MOVF TMR3L, W ; Read low byte MOVWF TMPL ; MOVF TMR3H, W ; Read high byte SUBWF TMPH, W ; Sub 1st read with 2nd read BTFSC STATUS,Z ; Is result = 0 GOTO CONTINUE ; Good 16-bit read ; ; TMR3L may have rolled over between the read of the high and low bytes. ; Reading the high and low bytes now will read a good value. ; MOVF TMR3H, W ; Read high byte MOVWF TMPH ; MOVF TMR3L, W ; Read low byte MOVWF TMPL ; ; Re-enable the Interrupt (if required) CONTINUE ; Continue with your code ; All interrupts are disabled CLRF TMR3L ; Clear Low byte, Ensures no ; rollover into TMR3H MOVLW HI_BYTE ; Value to load into TMR3H MOVWF TMR3H, F ; Write High byte MOVLW LO_BYTE ; Value to load into TMR3L MOVWF TMR3H, F ; Write Low byte ; Re-enable the Interrupt (if required) CONTINUE ; Continue with your code 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39516A-page 16-9 Section 16. Timer3 Timer3 16 16.7 Timer3 using the Timer1 Oscillator An alternate crystal oscillator circuit is built into the device. The output of this oscillator can be selected as the input into Timer3. The Timer1 oscillator is primarily intended to operate as a timebase for the timer modules; therefore, the oscillator is primarily intended for a 32 kHz crystal, which is an ideal frequency for real-time keeping. In real-time applications, the timer needs to increment during SLEEP, so SLEEP does not disable the Timer1 oscillator. For many applications, power consumption is also an issue, so the oscillator is designed to minimize consumption. The Timer1 oscillator is enabled by setting the T1OSCEN control bit (T1CON register). After the Timer1 oscillator is enabled, the user must provide a software time delay to ensure proper oscillator start-up. Table 16-1 shows the capacitor selection for the Timer1 oscillator. Table 16-1: Capacitor Selection for the Timer1 oscillator Note: The Timer1 oscillator allows the counter to operate (increment) when the device is in sleep mode. This allows Timer1 to be used as a real-time clock. Osc Type Freq C1 C2 LP 32 kHz 33 pF 33 pF 100 kHz 15 pF 15 pF 200 kHz 15 pF 15 pF Crystals Tested: 32.768 kHz Epson C-001R32.768K-A ± 20 PPM 100 kHz Epson C-2 100.00 KC-P ± 20 PPM 200 kHz STD XTL 200.000 kHz ± 20 PPM Note 1: Higher capacitance increases the stability of oscillator, but also increases the start-up time. 2: Since each resonator/crystal has its own characteristics, the user should consult the resonator/crystal manufacturer for appropriate values of external components. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39516A-page 16-10  2000 Microchip Technology Inc. 16.8 Timer3 and CCPx Enable Timer3 can be configured as the time base for capture and compare for either CCP2 or both CCP1 and CCP2. Timer3 cannot be used as the time base for CCP1 only. Timer1 can be used as the time base for CCP1 or both CCP1 and CCP2, but not CCP2 only. Control for the assignment of each of the time bases is given by configuring the corresponding T3CCP2 and T3CCP1 bits in the Timer3 control register, and is described in Table 16-2. Table 16-2: T3CCPx, TMR1, and TMR3 After reset, Timer1 defaults as the time base for compare and capture for both CCP’s. 16.8.1 Resetting Timer3 Using a CCP Trigger Output If the T3CCP2 or T3CCP1 bit is set and CCP1 or CCP2 is configured in Compare mode to generate a “Special Event Trigger” (CCPxM3:CCPxM0 = 1011), this signal will reset Timer3. Timer3 must be configured for either timer or synchronized counter mode to take advantage of this feature. If Timer3 is running in asynchronous counter mode, this reset operation may not work. In the event that a write to Timer3 coincides with a special event trigger from a CCP module, the write will take precedence. In this mode of operation, the CCPRxH:CCPRxL register pair effectively becomes the period register for the Timer3 module. 16.8.2 Resetting of TMR3 Register Pair (TMR3H:TMR3L) TMR3H and TMR3L registers are not cleared on any reset, only by the CCP special event triggers. T1CON register is reset to 00h on a Power-on Reset or a Brown-out Reset. In any other reset, the register is unaffected. Timer3 is the default time base for the CCP1 and CCP2 modules. The timer can be disabled as the time base for either CCP1, CCP2, or both, and Timer3 can be substituted. This is achieved by setting control bits in the Timer3 control register. This is explained in Section 16.8 - Timer3 and CCPx Enable. When Timer3 is disabled as a the time base for a CCP, the reset on compare for that particular CCP will have no effect on Timer3. 16.9 Timer3 Prescaler The prescaler counter is cleared on writes to the TMR3H or TMR3L registers. 16.9.1 Timer3 Prescaler 16-bit Read/Write Mode Writes to TMR3H do not clear the Timer3 prescaler in 16-bit read/write mode, because a write to TMR3H only modifies the Timer3 latch and does not change the contents of Timer3. The prescaler is only cleared on writes to TMR3L. T3CCP2:T3CCP1 Time base for CCP1 Time base for CCP2 00 TMR1 TMR1 01 TMR1 TMR3 10 TMR3 TMR3 11 TMR3 TMR3 Note: The “Special Event Trigger” from the CCP1 and CCP2 modules will not set interrupt flag bit TMR3IF. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39516A-page 16-11 Section 16. Timer3 Timer3 16 16.10 16-bit Mode Timer Reads/Writes Timer3 has modes that allow the 16-bit time register to be read as two 8-bit registers or one 16-bit register depending on the state of the RD16 bit. When the RD16 control bit is set, the address for TMR3H is mapped to a buffer register for the high byte of Timer3. A read from TMR3L will load the contents of the high byte of Timer3 into the Timer3 high byte buffer. This provides the user with the ability to accurately read all 16 bits of Timer3 without having to determine whether a read of the high byte followed by a read of the low byte is valid due to a rollover between reads. 16.10.1 16-bit Mode Timer Write A write to the high byte of Timer3 must also take place through the TMR3H buffer register. Timer3 high byte is updated with the contents of TMR3H when a write occurs to TMR3L. This allows a user to write all 16 bits to both the high and low bytes of Timer3 at once (See Figure 16-3). The high byte of Timer3 is not directly readable or writable in this mode. All reads and writes must take place through the Timer3 high byte buffer register. 16.10.2 16-bit Read/Modify Write Read modify write instructions like BSF or BCF will read the contents of a register, make the appropriate changes, and place the result back into the register. In the case of Timer3 when configured in 16-bit Read/Write mode, the read portion of a read-modify-write instruction of TMR3L will not update the contents of the TMR3H buffer. The TMR3H buffer will remain unchanged. When the write of TMR3L portion of the instruction takes place, the contents of TMR3H will be placed into the high byte of Timer3. Figure 16-3: Timer3 Block Diagram Configured in 16-bit Read/Write Mode Timer3 TMR3L T3SYNC TMR3CS T3CKPS1:T3CKPS0 SLEEP input FOSC/4 Internal Clock TMR3ON on/off Prescaler 1, 2, 4, 8 Synchronize det 1 0 0 1 Synchronized Clock Input 2 TMR3 CLR CCP Special Event Trigger T3CCPx To Timer1 Clock Input High Byte Data Bus<7:0> 8 TMR3H 8 8 8 Read TMR3L Write TMR3L Set TMR3IF flag bit on Overflow TT1P (1) Note 1: Signal coming from TMR1 oscillator (see Figure 14-2 ). 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39516A-page 16-12  2000 Microchip Technology Inc. 16.11 Typical Application The external oscillator clock input feature is typically used in applications where real-time needs to be kept, but it is also desirable to have the lowest possible power consumption. The Timer1 oscillator allows the device to be placed in sleep, while the timer continues to increment. When Timer3 overflows the interrupt wakes up the device so that the appropriate registers can be updated. Figure 16-4: Timer3 Application In this example, a 32kHz crystal is used as the time base for the Real Time Clock. If the clock needs to be updated at 1 second intervals, then the Timer1 must be loaded with a value to allow the Timer1 to overflow at the desired rate. In the case of a 1 second Timer1 overflow, the TMR1H register should be loaded with a value of 80k after each overflow. 8 4 4 4 4x4 Keypad Current Sink VSS VDD 32 kHz Backup Battery Power-Down Detect OSC1 TMR3 T1OSI T1OSO TT1P Note: The TMR3L register should never be modified, since an external clock is asychronous to the system clock. Writes to the TRM3L register may corrupt the real time counter value causing inaccuracies. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39516A-page 16-13 Section 16. Timer3 Timer3 16 16.12 Sleep Operation When Timer3 is configured for asynchronous operation, the TMR3 registers will continue to increment for each timer clock (or prescale multiple of clocks). When the TMR3 register overflows, the TMR3IF bit will get set, and if enabled, generate an interrupt that will wake the processor from sleep mode. The Timer1 oscillator will add a delta current, due to the operation of this circuitry. That is, the power-down current will no longer only be the leakage current of the device, but also the active current of the Timer1 oscillator and other Timer1 circuitry. 16.13 Timer3 Prescaler The prescaler counter is cleared on writes to the TMR3H or TMR3L registers. Table 16-3: Registers Associated with Timer3 as a Timer/Counter Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets INTCON GIE PEIE T0IE INTE RBIE T0IF INTF RBIF 0000 000x 0000 000u PIR TMR3IF (1) 0 0 PIE TMR3IE (1) 0 0 IPR TMR3IP (1) 0 0 TMR3L Holding register for the Least Significant Byte of the 16-bit TMR3 register xxxx xxxx uuuu uuuu TMR3H Holding register for the Most Significant Byte of the 16-bit TMR3 register xxxx xxxx uuuu uuuu T3CON RD16 T3CKPSI T3CKPS0 T30SCEN T3SYNC TMR3CS TMR3ON --00 0000 --uu uuuu Legend: x = unknown, u = unchanged, - = unimplemented read as '0'. Shaded cells are not used by the Timer1 module. Note 1: The placement of this bit is device dependent. 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39516A-page 16-14  2000 Microchip Technology Inc. 16.14 Initialization Since Timer3 has a software programmable clock source, there are three examples to show the initialization of each mode. Example 16-4 shows the initialization for the internal clock source, Example 16-5 shows the initialization for the external clock source, and Example 16-6 shows the initialization of the external oscillator mode. Example 16-4:Timer3 Initialization (Internal Clock Source) Example 16-5:Timer3 Initialization (External Clock Source) CLRF T3CON ; Stop Timer3, Internal Clock Source, ; T1 oscillator disabled, ; prescaler = 1:1 CLRF TMR3H ; Clear Timer3 High byte register CLRF TMR3L ; Clear Timer3 Low byte register CLRF INTCON ; Disable interrupts CLRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x30 ; Internal Clock source ; with 1:8 prescaler MOVWF T3CON ; Timer3 is stopped and ; T1 osc is disabled BSF T3CON, TMR3ON ; Timer3 starts to increment ; ; The Timer3 interrupt is disabled, do polling on the overflow bit ; T3_OVFL_WAIT BTFSS PIR1, TMR3IF GOTO T3_OVFL_WAIT ; ; Timer has overflowed ; BCF PIR1, TMR3IF CLRF T3CON ; Stop Timer3, Internal Clock Source, ; T1 oscillator disabled, ; prescaler = 1:1 CLRF TMR3H ; Clear Timer3 High byte register CLRF TMR3L ; Clear Timer3 Low byte register CLRF INTCON ; Disable interrupts CLRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x32 ; External Clock source ; with 1:8 prescaler MOVWF T3CON ; Clock source is ; synchronized to device ; Timer3 is stopped and ; T1 osc is disabled BSF T3CON, TMR3ON ; Timer3 starts to increment ; ; The Timer3 interrupt is disabled, do polling on the overflow bit ; T3_OVFL_WAIT BTFSS PIR1, TMR3IF GOTO T3_OVFL_WAIT ; ; Timer has overflowed ; BCF PIR1, TMR3IF 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39516A-page 16-15 Section 16. Timer3 Timer3 16 Example 16-6:Timer3 Initialization (External Oscillator Clock Source) CLRF T3CON ; Stop Timer3, Internal Clock Source, ; T1 oscillator disabled, ; prescaler = 1:1 CLRF TMR3H ; Clear Timer3 High byte register CLRF TMR3L ; Clear Timer3 Low byte register CLRF INTCON ; Disable interrupts CLRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x3E ; External Clock source ; with oscillator MOVWF T3CON ; circuitry, 1:8 prescaler, ; Clock source is ; asynchronous to device ; Timer3 is stopped BSF T3CON, TMR3ON ; Timer3 starts to increment ; ; The Timer3 interrupt is disabled, do polling on the overflow bit ; T3_OVFL_WAIT BTFSS PIR1, TMR3IF GOTO T3_OVFL_WAIT ; ; Timer has overflowed ; BCF PIR1, TMR3IF 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39516A-page 16-16  2000 Microchip Technology Inc. 16.15 Design Tips Question 1: Timer3 does not seem to be keeping accurate time. Answer 1: There are a few reasons that this could occur: 1. You should never write to Timer3, where that could cause the loss of time. In most cases, that means you should not write to the TMR3L register, but if the conditions are ok, you may write to the TMR3H register. Normally you write to the TMR3H register if you want the Timer3 overflow interrupt to be sooner then the full 16-bit time-out. 2. You should ensure the your layout uses good PCB layout techniques so that noise does not couple onto the Timer1/Timer3 oscillator lines. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39516A-page 16-17 Section 16. Timer3 Timer3 16 16.16 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhance family (that is they may be written for the Baseline, the Midrange, or High-end families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to Timer1 are: Title Application Note # Using Timer1 in Asynchronous Clock Mode AN580 Low Power Real Time Clock AN582 Yet another Clock using the PIC16C92X AN649 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39516A-page 16-18  2000 Microchip Technology Inc. 16.17 Revision History Revision A This is the initial released revision of the Timer3 module description. 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-1 CCP 17 Section 17. Compare/Capture/PWM (CCP) HIGHLIGHTS This section of the manual contains the following major topics: 17.1 Introduction .................................................................................................................. 17-2 17.2 CCP Control Register .................................................................................................. 17-3 17.3 Capture Mode .............................................................................................................. 17-4 17.4 Compare Mode ............................................................................................................ 17-7 17.5 PWM Mode ................................................................................................................ 17-10 17.6 Initialization ................................................................................................................ 17-15 17.7 Design Tips ................................................................................................................ 17-17 17.8 Related Application Notes.......................................................................................... 17-19 17.9 Revision History ......................................................................................................... 17-20 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-2  2000 Microchip Technology Inc. 17.1 Introduction Each CCP (Capture/Compare/PWM) module has three 8-bit registers. These are: • An 8-bit control register (CCPxCON) • A 16-bit register (CCPRxH:CCPRxL) that operates as: - a 16-bit capture register - a 16-bit compare register - a 10-bit PWM master/slave duty cycle register Multiple CCP modules may exist on a single device. The CCP modules are identical in operation, with the exception of the operation of the special event trigger. Throughout this section, we use generic names for the CCP registers. These generic names are shown in Table 17-1. Table 17-1: Specific to Generic CCP Nomenclature 17.1.1 Timer Resources Table 17-2 shows the resources of the CCP modules, in each of its modes. Table 17-3 shows the interactions between the CCP modules, where CCPx is one CCP module and CCPy is another CCP module. Table 17-2: CCP Mode - Timer Resource Table 17-3: Interaction of Two CCP Modules Generic Name CCP1 CCP2 Comment CCPxCON CCP1CON CCP2CON CCP Control Register CCPRxH CCPR1H CCPR2H CCP high byte CCPRxL CCPR1L CCPR2L CCP low byte CCPx CCP1 CCP2 CCP pin CCP Mode Timer Resource Capture Compare PWM Timer1 or Timer3 Timer1 or Timer3 Timer2 CCPx Mode CCPy Mode Interaction Capture Capture TMR1 or TMR3 time-base. Time base can be different for each CCP. Capture Compare The compare could be configured for the special event trigger, which clears either TMR1 or TMR3 depending upon which time base is used. Compare Compare The compare(s) could be configured for the special event trigger, which clears TMR1 or TMR3 depending upon which time base is used. PWM PWM The PWMs will have the same frequency, and update rate (TMR2 interrupt). PWM Capture None PWM Compare None 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-3 Section 17. CCP CCP 17 17.2 CCP Control Register Register 17-1 shows the CCP Control Register. This register selects the mode of operation of the CCP module, as well as contains the 2-LSb of the PWM Duty Cycle. Register 17-1: CCPxCON Register U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — DCxB1 DCxB0 CCPxM3 CCPxM2 CCPxM1 CCPxM0 bit 7 bit 0 bit 7-6 Unimplemented: Read as '0' bit 5-4 DCxB<1:0>: PWM Duty Cycle bit1 and bit0 Capture Mode: Unused Compare Mode: Unused PWM Mode: These bits are the two LSbs (bit1 and bit0) of the 10-bit PWM duty cycle. The upper eight bits (DCx<9:2>) of the duty cycle are found in CCPRxL. bit 3-0 CCPxM<3:0>: CCPx Mode Select bits 0000 = Capture/Compare/PWM off (resets CCPx module) 0001 = Reserved 0010 = Compare mode, toggle output on match (CCPxIF bit is set) 0011 = Reserved 0100 = Capture mode, every falling edge 0101 = Capture mode, every rising edge 0110 = Capture mode, every 4th rising edge 0111 = Capture mode, every 16th rising edge 1000 = Compare mode, Initialize CCP pin Low, on compare match force CCP pin High (CCPIF bit is set) 1001 = Compare mode, Initialize CCP pin High, on compare match force CCP pin Low (CCPIF bit is set) 1010 = Compare mode, Generate software interrupt on compare match (CCPIF bit is set, CCP pin is unaffected) 1011 = Compare mode, Trigger special event (CCPIF bit is set) 11xx = PWM mode Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-4  2000 Microchip Technology Inc. 17.3 Capture Mode In Capture mode, CCPRxH:CCPRxL captures the 16-bit value of the TMR1 or TMR3 register when an event occurs on the CCPx pin. An event is defined as: • Every falling edge • Every rising edge • Every 4th rising edge • Every 16th rising edge An event is selected by control bits CCPxM3:CCPxM0 (CCPxCON<3:0>). When a capture is made, the interrupt request flag bit, CCPxIF, is set. The CCPxIF bit must be cleared in software. If another capture occurs before the value in register CCPRx is read, the old captured value will be lost. When the Capture mode is changed, a false capture interrupt may be generated. The user should keep bit CCPxIE clear to avoid false interrupts and should clear flag bit CCPxIF following any such change in operating mode. Figure 17-1 shows that a capture does not modify (clear) the 16-bit timer register. This is so the timer (Timer1 or Timer3) can also be used as the time-base for other operations. The time between two captures can easily be computed as the difference between the value of the 2nd capture and that of the 1st capture. When the timer overflows, the timer interrupt bit, TMRxIF will be set. If enabled, an interrupt will occur, allowing the time-base to be extended to greater than 16 bits. Note: The dedicated time base (Timer1 or Timer3) must be running in Timer mode or Synchronized Counter mode for the CCP module to use the capture feature. In Asynchronous Counter mode, the capture operation may not work. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-5 Section 17. CCP CCP 17 17.3.1 CCP Pin Configuration In Capture mode, the CCPx pin should be configured as an input by setting its corresponding TRIS bit. The prescaler can be used to get a very fine average resolution on a constant input frequency. For example, if we have a stable input frequency and we set the prescaler to 1:16, then the total error for those 16 periods is 1 TCY. This gives an effective resolution of TCY/16, which at 40 MHz is 6.25 ns. This technique is only valid where the input frequency is “stable” over the 16 samples. Without using the prescaler (1:1), each sample would have a resolution of TCY. Figure 17-1: Capture Mode Operation Block Diagram Note: If the CCPx pin is configured as an output, a write to the port can cause a capture condition. CCPR1H CCPR1L TMR1H TMR1L Set flag bit CCPxIF TMR3 Enable Q’s CCP1CON<3:0> CCPx Pin Prescaler ³ 1, 4, 16 and edge detect TMR3H TMR3L TMR1 Enable T3CCP2 T3CCP2 CCPR2H CCPR2L TMR1H TMR1L Set flag bit CCP2IF TMR3 Enable Q’s CCP2CON<3:0> CCPx Pin Prescaler ³ 1, 4, 16 and edge detect TMR3H TMR3L TMR1 Enable T3CCP2 T3CCP1 T3CCP2 T3CCP1 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-6  2000 Microchip Technology Inc. 17.3.2 Changing Between Capture Modes When the Capture mode is changed, a capture interrupt may be generated. The user should keep the CCPxIE bit clear to disable these interrupts and should clear the CCPxIF flag bit following any such change in operating mode. 17.3.2.1 CCP Prescaler There are four prescaler settings, specified by the CCPxM3:CCPxM0 bits. Whenever the CCP module is turned off, or the CCP module is not in capture mode, the prescaler counter is cleared. This means that any reset will clear the prescaler counter. Switching from one capture prescale setting to another may generate an interrupt. Also, the prescaler counter will not be cleared, therefore the first capture may be from a non-zero prescaler. Example 17-1 shows the recommended method for switching between capture prescale settings. This example uses CCP1 and clears the prescaler counter so not to generate an unintended interrupt. Example 17-1:Changing Between Capture Prescalers To clear the Capture prescaler count, the CCP module must be configured into any non-capture CCP mode (Compare, PWM, or CCP off modes). 17.3.3 Sleep Operation When the device is placed in SLEEP, the timer will not increment (since it is in synchronous mode), but the prescaler will continue to count events (not synchronized). When a specified capture event occurs, the CCPxIF bit will be set, but the capture register will not be updated. If the CCP interrupt is enabled, the device will wake-up from SLEEP. The value in the 16-bit TMR1 register is not transferred to the 16-bit capture register. Effectively, this allows the CCP pin to be used as another external interrupt. 17.3.4 Effects of a Reset The CCP module is off, and the value in the capture prescaler is cleared. CLRF CCP1CON ; Turn CCP module off MOVLW NEW_CAPT_PS ; Load the W reg with the new prescaler ; mode value and CCP ON MOVWF CCP1CON ; Load CCP1CON with this value 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-7 Section 17. CCP CCP 17 17.4 Compare Mode In Compare mode, the 16-bit CCPRx register value is constantly compared against the TMR1 or TMR3 register pair value. When a match occurs, the CCPx pin is: • Driven High • Driven Low • Toggle output (Low to High or High to Low) • Not affected (remains unchanged) and configured as I/O pin The action on the pin is based on the value of control bits CCPxM3:CCPxM0 (CCPxCON3:CCPxCON0). At the same time, interrupt flag bit CCPxIF is set. Figure 17-2: Compare Mode Operation Block Diagram Note: The dedicated time base (Timer1 or Timer3) must be running in Timer mode or Synchronized Counter mode if the CCP module is using the compare feature. In Asynchronous Counter mode, the compare operation may not work. CCPR1H CCPR1L TMR1H TMR1L Comparator Q S R Output Logic Special Event Trigger Set flag bit CCP1IF CCP1 match TRISX CCP1CON<3:0> Mode Select Output Enable Pin Special event trigger will: Reset Timer1or Timer3, but not set Timer1 or Timer3 interrupt flag bit, and set bit GO/DONE (ADCON0 register), which starts an A/D conversion (CCP2 only). TMR3H TMR3L T3CCP2 CCPR2H CCPR2L Comparator 0 1 T3CCP2 T3CCP1 Q S R Output Logic Special Event Trigger Set flag bit CCP2IF CCP2 match TRIS CCP2CON<3:0> Mode Select Output Enable Pin 0 1 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-8  2000 Microchip Technology Inc. 17.4.1 CCP Pin Operation in Compare Mode The user must configure the CCPx pin as an output by clearing the appropriate TRIS bit. Selecting the compare output mode, forces the state of the CCP pin to the state that is opposite of the match state. So if the Compare mode is selected to force the output pin low on match, then the output will be forced high until the match occurs (or the mode is changed). In the compare toggle mode, the CCPx pin output is initially forced to the low state. 17.4.2 Software Interrupt Mode When Generate Software Interrupt mode is chosen, the CCPx pin is not affected. Only a CCP interrupt is generated (if enabled). 17.4.3 Special Event Trigger In this mode, an internal hardware trigger is generated that may be used to initiate an action. The special event trigger output of CCPx resets the assigned timer register pair (TMR1 or TMR3 depending upon the state of the T3CCPx bits). This allows the CCPRxH:CCPRxL registers to effectively be a 16-bit programmable period register for the timer (Timer1 or Timer3). For some devices, the special trigger output of the CCP module resets the timer (TMR1 or TMR3) register pair (depending upon the state of the T3CCPx bits), and starts an A/D conversion (if the A/D module is enabled). 17.4.4 Sleep Operation When the device is placed in SLEEP, the timer will not increment (since it is in Synchronous mode), and the state of the module will not change. If the CCP pin is driving a value, it will continue to drive that value. When the device wakes-up, it will continue from this state. 17.4.5 Effects of a Reset The CCP module is off. Note: Clearing the CCPxCON register will force the CCPx compare output latch to the default low level. This is not the Port I/O data latch. Note: The special event trigger will not set the Timers interrupt flag bit, TMRxIF. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-9 Section 17. CCP CCP 17 Table 17-4: Registers Associated with Capture, Compare, Timer1 and Timer3 Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other resets INTCON GIE/ GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIR1 PSPIF (1) ADIF RCIF TXIF SSPIF CCP1IF TMR2IF TMR1IF 0000 0000 0000 0000 PIE1 PSPIE (1) ADIE RCIE TXIE SSPIE CCP1IE TMR2IE TMR1IE 0000 0000 0000 0000 IPR1 PSPIP (1) ADIP RCIP TXIP SSPIP CCP1IP TMR2IP TMR1IP 0000 0000 0000 0000 TRISC PORTC Data Direction Register 1111 1111 1111 1111 TMR1L Holding register for the Least Significant Byte of the 16-bit TMR1 register xxxx xxxx uuuu uuuu TMR1H Holding register for the Most Significant Byte of the 16-bit TMR1register xxxx xxxx uuuu uuuu T1CON RD16 — T1CKPS1 T1CKPS0 T1OSCEN T1SYNC TMR1CS TMR1ON --00 0000 --uu uuuu CCPR1L Capture/Compare/PWM register1 (LSB) xxxx xxxx uuuu uuuu CCPR1H Capture/Compare/PWM register1 (MSB) xxxx xxxx uuuu uuuu CCP1CON — — DC1B1 DC1B0 CCP1M3 CCP1M2 CCP1M1 CCP1M0 --00 0000 --00 0000 CCPR2L Capture/Compare/PWM register2 (LSB) xxxx xxxx uuuu uuuu CCPR2H Capture/Compare/PWM register2 (MSB) xxxx xxxx uuuu uuuu CCP2CON — — DC2B1 DC2B0 CCP2M3 CCP2M2 CCP2M1 CCP2M0 --00 0000 --00 0000 PIR2 — — — — BCLIF LVDIF TMR3IF CCP2IF 0000 0000 0000 0000 PIE2 — — — — BCLIE LVDIE TMR3IE CCP2IE 0000 0000 0000 0000 IPR2 — — — — BCLIP LVDIP TMR3IP CCP2IP 0000 0000 0000 0000 TMR3L Holding register for the Least Significant Byte of the 16-bit TMR3 register xxxx xxxx uuuu uuuu TMR3H Holding register for the Most Significant Byte of the 16-bit TMR3 register xxxx xxxx uuuu uuuu T3CON RD16 T3CCP2 T3CKPS1 T3CKPS0 T3CCP1 T3SYNC TMR3CS TMR3ON -000 0000 -uuu uuuu Legend: x = unknown, u = unchanged, - = unimplemented read as '0'. Shaded cells are not used by Capture, Compare, Timer1 and Timer3. Note 1: The PSPIF, PSPIE and PSPIP bits are reserved on the PIC18C2x2 devices. Always maintain these bits clear. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-10  2000 Microchip Technology Inc. 17.5 PWM Mode In Pulse Width Modulation (PWM) mode, the CCPx pin produces up to a 10-bit resolution PWM output. Since the CCPx pin is multiplexed with the PORT data latch, the corresponding TRIS bit must be cleared to make the CCPx pin an output. Figure 17-3 shows a simplified block diagram of one CCP module in PWM mode. Depending on the device there can be more than one CCP module connected to Timer2. Each CCP module can support one Pulse Width Modulation (PWM) output signal. This PWM signal can attain a resolution of up to 10-bits, from the 8-bit Timer2 module. Two extra bits are used to extend Timer2 to 10 bits (see Section 17.5.1). A PWM output waveform is shown in Figure 17-4. For a step-by-step procedure on how to set up the CCP module for PWM operation, see Section 17.5.4. Figure 17-3: Simplified PWM Block Diagram Figure 17-4: PWM Output Waveform Note: Clearing the CCPxCON register will force the CCPx PWM output latch to the default low level. This is not the Port I/O data latch. CCPRxL CCPRxH (Slave) Comparator TMR2 Comparator PR2 R Q S Duty Cycle Registers CCPxCON<5:4> Clear Timer, TRIS CCPx Timer2 Module (Note 1) 8 8 10 10 10 CCP Module Note 1: For 10-bit time base generation see Section 17.5.1. (DCxB<9:2>) (DCxB<1:0>) Force CCPx pin high, and latch the Duty Cycle Period = PR2 + 1 Timer2 is cleared and new duty cycle value is loaded from the Duty Cycle latch into the Timer2 value equals to value in Duty Cycle Latch register, CCP Pin is driven low Timer2 overflow, value from Duty Cycle Latch is loaded into Slave Register, CCP Pin driven high DutyCycle = DCxB9:DCxB0 1 3 2 2 3 1 Duty Cycle Slave register 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-11 Section 17. CCP CCP 17 17.5.1 10-bit Time Base Generation The PWM output has up to 10-bits of resolution. This is achieved by creating a 10-bit PWM Time base (TB9:TB0). Figure 17-5 shows the block diagram of this 10-bit PWM Time base. When TSCLK is the clock source to the 10-bit counter, the counter increments on each Tsclk. If a prescaler is selected, the 10-bit counter increments every prescale would by TSCLK. Figure 17-5: 10-bit Time Base Block Diagram 17.5.2 PWM Period The PWM period is specified by writing to the PR2 register. The PWM period can be calculated using Equation 17-1. Equation 17-1:Calculation for PWM Period When TMR2 is equal to PR2, the following three events occur on the next increment cycle: • TMR2 is cleared • The CCPx pin is set (exception: if PWM duty cycle = 0%, the CCPx pin will not be set) • The PWM duty cycle is latched from CCPRxL into CCPRxH TMR2 TSCLK Note 1: These two bits are not readable or writable and are not mapped into the data memory. TB0 (1) TB1 TB9 TB2 (1) Prescaler TMR2 Where PR2 = Value in PR2 Register TSCLK = Oscillator Clock TPWM period = [(PR2) + 1] • 4 • TSCLK • (TMR2 prescale value) Note: The Timer2 postscaler is not used in the determination of the PWM frequency. The postscaler could be used to generate TMR2 interrupts at a different frequency than the PWM output. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-12  2000 Microchip Technology Inc. 17.5.3 PWM Duty Cycle The PWM duty cycle is specified by writing to the CCPRxL register and to the DCxB1:DCxB0 (CCPxCON<5:4>) bits, if 10-bit resolution is desired. The CCPRxL contains the eight MSbs and CCPxCON<5:4> contains the two LSbs. This 10-bit value is represented by DCxB9:DCxB0. Equation 17-2 is used to calculate the PWM duty cycle. Equation 17-2:Equation for calculating the PWM Duty Cycle The DCxB<9:0> bits can be written to at any time, but the duty cycle value is not latched into CCPRxH until after a match between PR2 and TMR2 occurs (which is the end of the current period). In PWM mode, CCPRxH is a read-only register. The CCPRxH register and a 2-bit internal latch are used to double buffer the PWM duty cycle. This double buffering is essential for glitchless PWM operation. When CCPRxH and a 2-bit latch match the value of TMR2 concatenated with the internal 2-bit Q clock (or two bits of the TMR2 prescaler), the CCPx pin is cleared. This is the end of the duty cycle. Equation 17-3 is used to calculate the maximum PWM resolution in bits for a given PWM frequency. Equation 17-3:Calculation for Maximum PWM Resolution 17.5.3.1 Minimum Resolution The minimum resolution (in time) of each bit of the PWM duty cycle depends on the prescaler of Timer2. Table 17-5 shows the selections for the minimum resolution time. Table 17-5: Minimum Duty Cycle Bit Time Where PWM Duty Cycle = PWM Duty Cycle Time TSCLK = Oscillator Clock PWM Duty Cycle = (DCxB<9:0> bits value) • TSLCK • (TMR2 prescale value) log( FPWM log(2) FOSC ) Maximum PWM Resolution (bits) = bits Note: If the PWM duty cycle value is longer than the PWM period, the CCPx pin will not be cleared. This allows a duty cycle of 100%. Prescaler Value T2CKPS1:T2CKPS0 Minimum Resolution (Time) 1 0 0 TSCLK 4 0 1 TCY 16 1 x 4 TCY 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-13 Section 17. CCP CCP 17 17.5.3.2 Example Calculation for PWM Period and Duty Cycle This section shows an example calcuation for the PWM Period and Duty Cycle. Furthermore example PWM frequencies based upon different oscillator frequencies are given. Example 17-2:PWM Period and Duty Cycle Calculation At most, an 8-bit resolution duty cycle can be obtained from a 78.125 kHz frequency and a 20 MHz oscillator (i.e., 0 ≤ DCxB9:DCxB0 ≤ 255). Any value greater than 255 will result in a 100% duty cycle. In order to achieve higher resolution, the PWM frequency must be decreased. In order to achieve higher PWM frequency, the resolution must be decreased. Table 17-6 lists example PWM frequencies and resolutions for FOSC = 20 MHz. Table 17-7 lists example PWM frequencies and resolutions for FOSC = 40 MHz. The TMR2 prescaler and PR2 values are also shown. Table 17-6: Example PWM Frequencies and Bit Resolutions at 20 MHz Table 17-7: Example PWM Frequencies and Bit Resolutions at 40 MHz Desired PWM frequency is 78.125 kHz, Fosc = 20 MHz TMR2 prescale = 1 1 / 78.125 kHz = [(PR2) + 1] • 4 • 1/20 MHz • 1 12.8 ms = [(PR2) + 1] • 4 • 50 ns • 1 PR2 = 63 Find the maximum resolution of the duty cycle that can be used with a 78.125 kHz frequency and 20 MHz oscillator: 1 / 78.125 kHz = 2PWM RESOLUTION • 1/20 MHz • 1 12.8 ms = 2PWM RESOLUTION • 50 ns • 1 256 = 2PWM RESOLUTION log(256) = (PWM Resolution) • log(2) PWM Resolution= 8.0 PWM Frequency 1.22 kHz 4.88 kHz 19.53 kHz 78.12 kHz 156.3 kHz 208.3 kHz Timer Prescaler (1, 4, 16) 16 4 1 1 1 1 PR2 Value 0xFF 0xFF 0xFF 0x3F 0x1F 0x17 Maximum Resolution (bits) 10 10 10 8 7 5.5 PWM Frequency 2.44 kHz 9.76 kHz 39.06 kHz 78.12 kHz 208.3 kHz 416.6 kHz Timer Prescaler (1, 4, 16) 16 4 1 1 1 1 PR2 Value 0xFF 0xFF 0xFF 0x3F 0x1F 0x17 Maximum Resolution (bits) 10 10 10 8 7 5.5 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-14  2000 Microchip Technology Inc. 17.5.4 Set-up for PWM Operation The following steps configure the CCP module for PWM operation: 1. Establish the PWM period by writing to the PR2 register. 2. Establish the PWM duty cycle by writing to the DCxB9:DCxB0 bits. 3. Make the CCPx pin an output by clearing the appropriate TRIS bit. 4. Establish the TMR2 prescale value and enable Timer2 by writing to T2CON. 5. Configure the CCP module for PWM operation. 17.5.5 Sleep Operation When the device is placed in sleep, Timer2 will not increment, and the state of the module will not change. If the CCP pin is driving a value, it will continue to drive that value. When the device wakes-up, it will continue from this state. 17.5.6 Effects of a Reset The CCP module is off. Table 17-8: Registers Associated with PWM and Timer2 Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other resets INTCON GIE/GIEH PEIE/GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIR1 TMR2IF (1) 0000 0000 0000 0000 PIE1 TMR2IE (1) 0000 0000 0000 0000 IPR1 TMR2IP (1) 0000 0000 0000 0000 TRISC PORTC Data Direction Register 1111 1111 1111 1111 TMR2 Timer2 module’s register 0000 0000 0000 0000 PR2 Timer2 module’s period register 1111 1111 1111 1111 T2CON — TOUTPS3 TOUTPS2 TOUTPS1 TOUTPS0 TMR2ON T2CKPS1 T2CKPS0 -000 0000 -000 0000 CCPR1L Capture/Compare/PWM register1 (LSB) xxxx xxxx uuuu uuuu CCPR1H Capture/Compare/PWM register1 (MSB) xxxx xxxx uuuu uuuu CCP1CON — — DC1B1 DC1B0 CCP1M3 CCP1M2 CCP1M1 CCP1M0 --00 0000 --00 0000 CCPR2L Capture/Compare/PWM register2 (LSB) xxxx xxxx uuuu uuuu CCPR2H Capture/Compare/PWM register2 (MSB) xxxx xxxx uuuu uuuu CCP2CON — — DC2B1 DC2B0 CCP2M3 CCP2M2 CCP2M1 CCP2M0 --00 0000 --00 0000 Legend: x = unknown, u = unchanged, — = unimplemented read as '0'. Shaded cells are not used by PWM and Timer2. Note 1: The PSPIF, PSPIE and PSPIP bits are reserved on the PIC18C2X2 devices. Always maintain these bits clear. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-15 Section 17. CCP CCP 17 17.6 Initialization The CCP module has three modes of operation. Example 17-3 shows the initialization of capture mode, Example 17-4 shows the initialization of compare mode and Example 17-5 shows the initialization of PWM mode. Example 17-3:Capture Initialization CLRF CCP1CON ; CCP Module is off CLRF TMR1H ; Clear Timer1 High byte CLRF TMR1L ; Clear Timer1 Low byte CLRF INTCON ; Disable interrupts and clear T0IF BSF TRISC, CCP1 ; Make CCP pin input CLRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x06 ; Capture mode, every 4th rising edge MOVWF CCP1CON ; BSF T1CON, TMR1ON ; Timer1 starts to increment ; ; The CCP1 interrupt is disabled, ; do polling on the CCP Interrupt flag bit ; Capture_Event BTFSS PIR1, CCP1IF GOTO Capture_Event ; ; Capture has occured ; BCF PIR1, CCP1IF ; This needs to be done before ; next compare 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-16  2000 Microchip Technology Inc. Example 17-4:Compare Initialization Example 17-5:PWM Initialization CLRF CCP1CON ; CCP Module is off CLRF TMR1H ; Clear Timer1 High byte CLRF TMR1L ; Clear Timer1 Low byte CLRF INTCON ; Disable interrupts and clear T0IF MOVLW 0x80 ; Load 0x80 (Example Value) ; into W-Register MOVWF CCPRIH ; Load value to compare into CCPRIH MOVWF CCPRIL ; Load value to compare into CCPRIL BCF TRISC, CCP1 ; Make CCP pin output if controlling ; state of pin CLRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x08 ; Compare mode, set CCP1 pin on match MOVWF CCP1CON ; BSF T1CON, TMR1ON ; Timer1 starts to increment ; ; The CCP1 interrupt is disabled, ; do polling on the CCP Interrupt flag bit ; Compare_Event BTFSS PIR1, CCP1IF GOTO Compare_Event ; ; Compare has occured ; BCF PIR1, CCP1IF ; This needs to be done before ; next compare CLRF CCP1CON ; CCP Module is off CLRF TMR2 ; Clear Timer2 MOVLW 0x7F ; MOVWF PR2 ; MOVLW 0x1F ; MOVWF CCPR1L ; Duty Cycle is 25% of PWM Period CLRF INTCON ; Disable interrupts and clear T0IF BCF TRISC, PWM1 ; Make pin output CLRF PIE1 ; Disable peripheral interrupts CLRF PIR1 ; Clear peripheral interrupts Flags MOVLW 0x2C ; PWM mode, 2 LSbs of ; Duty cycle = 10 MOVWF CCP1CON ; BSF T2CON, TMR2ON ; Timer2 starts to increment ; ; The CCP1 interrupt is disabled, ; do polling on the TMR2 Interrupt flag bit ; PWM_Period_Match BTFSS PIR1, TMR2IF GOTO PWM_Period_Match ; ; Update this PWM period and the following PWM Duty cycle ; BCF PIR1, TMR2IF 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-17 Section 17. CCP CCP 17 17.7 Design Tips Question 1: What timers can I use for the capture and compare modes? Answer 1: The capture and compare modes are designed around Timer1 and Timer3, so no other timer can be used for these functions. This also means that if multiple CCP modules are being used for a capture or compare function, they can share the same timer. Question 2: What timers can I use with the PWM mode? Answer 2: The PWM mode is designed around Timer2, so no other timer can be used for this function. It is the only timer with a period register associated with it. If multiple CCP modules are doing PWM, they will share the same timer and have the same PWM period and frequency. Question 3: Can I use one CCP module to do capture (or compare) AND PWM at the same time, since they use different timers as their reference? Answer 3: The timers may be different, but other logic functions are shared. However, you can switch from one mode to the other. For a device with 2 CCP modules, you can also have CCP1 set up for PWM and CCP2 set up for capture or compare (or vice versa) since they are two independent modules. Question 4: How does a reset affect the CCP module? Answer 4: Any reset will turn the CCP module off. See the “Reset” section to see reset values. Question 5: I am setting up the CCP1CON module for “Compare Mode, trigger special event” (1011) that resets TMR1. When a compare match occurs, will I have both the TMR1 and the CCP1 interrupts pending (TMR1IF is set, CCP1IF is set)? Answer 5: The CCP1IF flag will be set on the match condition. TMR1IF is set when Timer1 overflows, and the special trigger reset of Timer1 is not considered an overflow. However, if both the CCPR1L and CCPR1H registers are set at FFh, then an overflow occurs at the same time as the match, which will then set both CCP1IF and TMR1IF. Question 6: How do I use Timer2 as a general purpose timer, with an interrupt flag on rollover? Answer 6: Timer2 always resets to zero when it equals PR2 and flag bit TMR2IF always gets set at this time. By putting FFh into PR2, you will get an interrupt on overflow at FFh. Quite often it is desirable to have an event occur at a periodic rate, perhaps an interrupt driven event. Normally an initial value would be placed into the timer so that the overflow will occur at the desired time. This value would have to be placed back into the timer every time it overflowed to make the interrupts occur at the same desired rate. The benefit of Timer2 is that a value can be written to PR2 that will cause it to reset at your desired time interval. This means you do not have the housekeeping chore of reloading the timer every time it overflows, since PR2 maintains its value. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-18  2000 Microchip Technology Inc. Question 7: I am using a CCP module in PWM mode. The duty cycle being outputted is almost always 100%, even when my program writes a value like 7Fh to the duty cycle register, which should be 50%. What am I doing wrong? Answer 7: 1. The value in CCPRxL is higher than PR2. This happens quite often when a user desires a fast PWM output frequency and writes a small value in the PR2. In this case, if a value of 7Eh were written to PR2, then a value 7Fh in CCPRxL will result in 100% duty cycle. 2. If the TRIS bit corresponding to the CCP output pin you are using is configured as an input, the PWM output cannot drive the pin. In this case, the pin would float and duty cycle may appear to be 0%, 100% or some other floating value. Question 8: I want to determine a signal frequency using the CCP module in capture mode to find the period. I am currently resetting Timer1 on the first edge, then using the value in the capture register on the second edge as the time period. The problem is that my code to clear the timer does not occur until almost twelve instructions after the first capture edge (interrupt latency plus saving of registers in interrupt), so I cannot measure very fast frequencies. Is there a better way to do this? Answer 8: You do not need to zero the counter to find the difference between two pulse edges. Just take the first captured value and put it into another set of registers. Then when the second capture event occurs, subtract the first event from the second. Assuming that your pulse edges are not so far apart that the counter can wrap around past the last capture value, the answer will always be correct. This is illustrated by the following example: 1. First captured value is FFFEh. Store this value in two registers. 2. The second capture value is 0001h (the counter has incremented three times). 3. 0001h - FFFEh = 0003, which is the same as if you had cleared Timer1 to zero and let it count to 3. (Theoretically, except that there was a delay getting to the code that clears Timer1, so actual values would differ). The interrupt overhead is now less important because the values are captured automatically. For even faster inputs, do not enable interrupts and just test the flag bit in a loop. If you must also capture very long time periods, such that the timer can wrap around past the previous capture value, then consider using an auto-scaling technique that starts with a large prescale, and shorten the prescale as you converge on the exact frequency. 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39517A-page 17-19 Section 17. CCP CCP 17 17.8 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the CCP modules are: Title Application Note # Using the CCP Modules AN594 Implementing Ultrasonic Ranging AN597 Air Flow Control Using Fuzzy Logic AN600 Adaptive Differential Pulse Code Modulation AN643 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39517A-page 17-20  2000 Microchip Technology Inc. 17.9 Revision History Revision A This is the initial released revision of the Enhanced MCU CCP module description. 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39518A-page 18-1 ECCP 18 Section 18. ECCP Please check the Microchip web site for Revision B of the ECCP Section. 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39518A-page 18-2  2000 Microchip Technology Inc. 18.1 Revision History Revision A This is the initial released revision of the Enhanced MCU ECCP module description. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-1 SSP 19 Section 19. Synchronous Serial Port (SSP) HIGHLIGHTS This section of the manual contains the following major topics: 19.1 Introduction .................................................................................................................. 19-2 19.2 Control Registers ......................................................................................................... 19-4 19.3 SPI Mode ..................................................................................................................... 19-8 19.4 SSP I2C Operation .................................................................................................... 19-18 19.5 Initialization ................................................................................................................ 19-28 19.6 Design Tips ................................................................................................................ 19-30 19.7 Related Application Notes.......................................................................................... 19-31 19.8 Revision History ......................................................................................................... 19-32 I 2C is a trademark of Philips Corporation. 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-2  2000 Microchip Technology Inc. 19.1 Introduction The Synchronous Serial Port (SSP) module is a serial interface useful for communicating with other peripherals or microcontroller devices. These peripheral devices may be serial EEPROMs, shift registers, display drivers, A/D converters, etc. The SSP module can operate in one of two modes: • Serial Peripheral Interface (SPI™) • Inter-Integrated Circuit (I2C™) - Slave mode - I/O slope control, and Start and Stop bit detection to ease software implementation of Master and Multi-master modes SPI is a registered trademark of Motorola Corporation. I 2C is a trademark of Philips Corporation. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-3 Section 19. SSP SSP 19 Section 19.2 forced to next page for formatting purposes. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-4  2000 Microchip Technology Inc. 19.2 Control Registers Register 19-1 shows the SSPSTAT register while Register 19-2 shows the SSPCON register. Register 19-1: SSPSTAT: Synchronous Serial Port Status Register R/W-0 R/W-0 R-0 R-0 R-0 R-0 R-0 R-0 SMP CKE D/A P S R/W UA BF bit 7 bit 0 bit 7 SMP: SPI data input sample phase SPI Master Mode 1 = Input data sampled at end of data output time 0 = Input data sampled at middle of data output time SPI Slave Mode SMP must be cleared when SPI is used in slave mode I2C Mode This bit must be maintained clear. bit 6 CKE: SPI Clock Edge Select (Figure 19-3, Figure 19-4, and Figure 19-5) SPI Mode CKP = 0 (SSPCON<4>) 1 = Data transmitted on rising edge of SCK 0 = Data transmitted on falling edge of SCK CKP = 1 (SSPCON<4>) 1 = Data transmitted on falling edge of SCK 0 = Data transmitted on rising edge of SCK I 2C Mode This bit must be maintained clear. bit 5 D/A: Data/Address bit (I2C mode only) 1 = Indicates that the last byte received or transmitted was data 0 = Indicates that the last byte received or transmitted was address bit 4 P: Stop bit (I2C mode only. This bit is cleared when the SSP module is disabled) 1 = Indicates that a stop bit has been detected last (this bit is '0' on RESET) 0 = Stop bit was not detected last bit 3 S: Start bit (I2C mode only. This bit is cleared when the SSP module is disabled) 1 = Indicates that a start bit has been detected last (this bit is '0' on RESET) 0 = Start bit was not detected last bit 2 R/W: Read/Write bit information (I2C mode only) This bit holds the R/W bit information following the last address match. This bit is only valid from the address match to the next start bit, stop bit, or not ACK bit. 1 = Read 0 = Write bit 1 UA: Update Address (10-bit I2C mode only) 1 = Indicates that the user needs to update the address in the SSPADD register 0 = Address does not need to be updated 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-5 Section 19. SSP SSP 19 bit 0 BF: Buffer Full Status bit Receive (SPI and I2C modes) 1 = Receive complete, SSPBUF is full 0 = Receive not complete, SSPBUF is empty Transmit (I2 C mode only) 1 = Transmit in progress, SSPBUF is full 0 = Transmit complete, SSPBUF is empty Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-6  2000 Microchip Technology Inc. Register 19-2: SSPCON: Synchronous Serial Port Control Register R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 WCOL SSPOV SSPEN CKP SSPM3 SSPM2 SSPM1 SSPM0 bit 7 bit 0 bit 7 WCOL: Write Collision Detect bit 1 = The SSPBUF register was written to while the previous word was being transmitted. (must be cleared in software) 0 = No collision bit 6 SSPOV: Receive Overflow Indicator bit In SPI mode: 1 = A new byte was received while the SSPBUF register was still holding the previous data. In case of overflow, the data in SSPSR is lost and the SSPBUF is no longer updated. Overflow can only occur in slave mode. The user must read the SSPBUF, even if only transmitting data, to avoid setting overflow. In master mode the overflow bit is not set since each new reception (and transmission) is initiated by writing to the SSPBUF register. 0 = No overflow In I2C mode: 1 = A byte was received while the SSPBUF register was still holding the previous byte. SSPO is a “don‘t care” in transmit mode. SSPOV must be cleared in software in either mode. 0 = No overflow bit 5 SSPEN: Synchronous Serial Port Enable bit In both modes, when enabled, these pins must be properly configured as input or output. In SPI mode: 1 = Enables serial port and configures SCK, SDO, SDI, and SS as the source of the serial port pins 0 = Disables serial port and configures these pins as I/O port pins In I2C mode: 1 = Enables the serial port and configures the SDA and SCL pins as the source of the serial port pins 0 = Disables serial port and configures these pins as I/O port pins bit 4 CKP: Clock Polarity Select bit In SPI mode: 1 = Idle state for clock is a high level 0 = Idle state for clock is a low level In I2C mode: SCK release control 1 = Enable clock 0 = Holds clock low (clock stretch) (Used to ensure data setup time) 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-7 Section 19. SSP SSP 19 bit 3:0 SSPM3:SSPM0: Synchronous Serial Port Mode Select bits 0000 = SPI master mode, clock = FOSC/4 0001 = SPI master mode, clock = FOSC/16 0010 = SPI master mode, clock = FOSC/64 0011 = SPI master mode, clock = TMR2 output/2 0100 = SPI slave mode, clock = SCK pin. SS pin control enabled. 0101 = SPI slave mode, clock = SCK pin. SS pin control disabled. SS can be used as I/O pin 0110 = I2C slave mode, 7-bit address 0111 = I2C slave mode, 10-bit address 1000 = Reserved 1001 = Reserved 1010 = Reserved 1011 = I2C firmware controlled master mode (slave idle) 1100 = Reserved 1101 = Reserved 1110 = I2C slave mode, 7-bit address with start and stop bit interrupts enabled 1111 = I2C slave mode, 10-bit address with start and stop bit interrupts enabled Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Microwire is a trademark of National Semiconductor. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-8  2000 Microchip Technology Inc. 19.3 SPI Mode The SPI mode allows 8-bits of data to be synchronously transmitted and received simultaneously. All four modes of SPI are supported, as well as Microwire™ (sample edge) when the SPI is in the master mode. To accomplish communication, typically three pins are used: • Serial Data Out (SDO) • Serial Data In (SDI) • Serial Clock (SCK) Additionally a fourth pin may be used when in a slave mode of operation: • Slave Select (SS) 19.3.1 Operation When initializing the SPI, several options need to be specified. This is done by programming the appropriate control bits in the SSPCON register (SSPCON<5:0>) and SSPSTAT<7:6>. These control bits allow the following to be specified: • Master Mode (SCK is the clock output) • Slave Mode (SCK is the clock input) • Clock Polarity (Idle state of SCK) • Clock edge (output data on rising/falling edge of SCK) • Data Input Sample Phase • Clock Rate (Master mode only) • Slave Select Mode (Slave mode only) Figure 19-1 shows the block diagram of the SSP module, when in SPI mode. Figure 19-1: SSP Block Diagram (SPI Mode) Read Write Internal Data Bus SDI SDO SS SCK SSPSR reg SSPBUF reg SSPM3:SSPM0 bit0 Shift Clock SS Control Enable Edge Select Clock Select TMR2 output Prescaler TCY 4, 16, 64 TRIS bit of SCK pin 2 Edge Select 2 4 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-9 Section 19. SSP SSP 19 The SSP consists of a transmit/receive Shift Register (SSPSR) and a buffer register (SSPBUF). The SSPSR shifts the data in and out of the device, MSb first. The SSPBUF holds the data that was written to the SSPSR, until the received data is ready. Once the 8-bits of data have been received, that byte is moved to the SSPBUF register. Then the buffer full detect bit, BF (SSPSTAT<0>), and interrupt flag bit, SSPIF, are set. This double buffering of the received data (SSPBUF) allows the next byte to start reception before reading the data that was just received. Any write to the SSPBUF register during transmission/reception of data will be ignored, and the write collision detect bit, WCOL (SSPCON<7>), will be set. User software must clear the WCOL bit so that it can be determined if the following write(s) to the SSPBUF register completed successfully. When the application software is expecting to receive valid data, the SSPBUF should be read before the next byte of data to transfer is written to the SSPBUF. Buffer full bit, BF (SSPSTAT<0>), indicates when SSPBUF has been loaded with the received data (transmission is complete). When the SSPBUF is read, the BF bit is cleared. This data may be irrelevant if the SPI is only a transmitter. Generally the SSP Interrupt is used to determine when the transmission/reception has completed. The SSPBUF must be read and/or written. If the interrupt method is not going to be used, then software polling can be done to ensure that a write collision does not occur. Example 19-1 shows the loading of the SSPBUF (SSPSR) for data transmission. The shaded instruction is only required if the received data is meaningful (some SPI applications are transmit only). Example 19-1: Loading the SSPBUF (SSPSR) Register The SSPSR is not directly readable or writable, and can only be accessed from addressing the SSPBUF register. Additionally, the SSP status register (SSPSTAT) indicates the various status conditions. LOOP BTFSS SSPSTAT, BF ;Has data been received ; (transmit complete)? GOTO LOOP ;No MOVF SSPBUF, W ;W reg = contents of SSPBUF MOVWF RXDATA ;Save in user RAM, ; if data is meaningful MOVFF TXDATA, SSPBUF ;contents of TXDATA ; is the new data to transmit 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-10  2000 Microchip Technology Inc. 19.3.2 Enabling SPI I/O To enable the serial port the SSP Enable bit, SSPEN (SSPCON<5>), must be set. To reset or reconfigure SPI mode, clear the SSPEN bit which re-initializes the SSPCON register, and then set the SSPEN bit. This configures the SDI, SDO, SCK, and SS pins as serial port pins. For the pins to behave as the serial port function, they must have their data direction bits (in the TRIS register) appropriately programmed. That is: • SDI must have the TRIS bit set • SDO must have the TRIS bit cleared • SCK (Master mode) must have the TRIS bit cleared • SCK (Slave mode) must have the TRIS bit set • SS must have the TRIS bit set Any serial port function that is not desired may be overridden by programming the corresponding data direction (TRIS) register to the opposite value. An example would be in master mode where you are only sending data (to a display driver), then both SDI and SS could be used as general purpose outputs by clearing their corresponding TRIS register bits. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-11 Section 19. SSP SSP 19 19.3.3 Typical Connection Figure 19-2 shows a typical connection between two microcontrollers. The master controller (Processor 1) initiates the data transfer by sending the SCK signal. Data is shifted out of both shift registers on their programmed clock edge, and latched on the edge of the clock specified by the SMP bit. Both processors should be programmed to same Clock Polarity (CKP), so both controllers would send and receive data at the same time. Whether the data is meaningful (or dummy data) depends on the application software. This leads to three scenarios for data transmission: • Master sends data — Slave sends dummy data • Master sends data — Slave sends data • Master sends dummy data — Slave sends data Figure 19-2: SPI Master/Slave Connection Serial Input Buffer (SSPBUF) Shift Register (SSPSR) MSb LSb SDO SDI PROCESSOR 1 SCK SPI Master SSPM3:SSPM0 = 00xxb Serial Input Buffer (SSPBUF) Shift Register (SSPSR) MSb LSb SDI SDO PROCESSOR 2 SCK SPI Slave SSPM3:SSPM0 = 010xb Serial Clock 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-12  2000 Microchip Technology Inc. 19.3.4 Master Operation The master can initiate the data transfer at any time because it controls the SCK. The master determines when the slave (Processor 2) is to broadcast data by the software protocol. In master mode the data is transmitted/received as soon as the SSPBUF register is written to. If the SPI is only going to receive, the SDO output could be disabled (programmed as an input). The SSPSR register will continue to shift in the signal present on the SDI pin at the programmed clock rate. As each byte is received, it will be loaded into the SSPBUF register as if a normal received byte (interrupts and status bits appropriately set). This could be useful in receiver applications as a “line activity monitor” mode. The clock polarity is selected by appropriately programming bit CKP (SSPCON<4>). This would give waveforms for SPI communication as shown in Figure 19-3, Figure 19-4, and Figure 19-5 where the MSb is transmitted first. In master mode, the SPI clock rate (bit rate) is user programmable to be one of the following: • FOSC/4 (or TCY) • FOSC/16 (or 4 • TCY) • FOSC/64 (or 16 • TCY) • Timer2 output/2 This allows a maximum data rate of 5 Mbps (at 20 MHz). Figure 19-3: SPI Mode Waveform, Master Mode 4 clock modes Input Sample (SMP = 0) Input Sample (SMP = 1) SDI (SMP = 0) bit7 bit0 SDO (CKE = 0) bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 bit7 bit0 SDI (SMP = 1) SSPIF Write to SSPBUF SSPSR to SSPBUF SDO (CKE = 1) bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 SCK (CKP = 0, CKE = 0) SCK (CKP = 0, CKE = 1) SCK (CKP = 1, CKE = 0) SCK (CKP = 1, CKE = 1) Next Q4 cycle after Q2 ↓ 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-13 Section 19. SSP SSP 19 19.3.5 Slave Operation In slave mode, the data is transmitted and received as the external clock pulses appear on SCK. When the last bit is latched, the interrupt flag bit SSPIF is set. The clock polarity is selected by appropriately programming bit CKP (SSPCON). This then would give waveforms for SPI communication as shown in Figure 19-3, Figure 19-4, and Figure 19-5 where the MSb is transmitted first. When in slave mode the external clock must meet the minimum high and low times. In sleep mode, the slave can transmit and receive data. When a byte is received, the device will wake-up from sleep, if the interrupt is enabled. Figure 19-4: SPI Mode Waveform (Slave Mode With CKE = 0) SCK (CKP = 1, SCK (CKP = 0, Input Sample (SMP = 0) SDI bit7 bit0 SDO bit6 bit5 bit4 bit3 bit2 bit1 bit0 SSPIF CKE = 0) CKE = 0) (SMP = 0) Write to SSPBUF SSPSR to SSPBUF SS optional Next Q4 Cycle after Q2↓ bit7 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-14  2000 Microchip Technology Inc. 19.3.6 Slave Select Mode When in slave select mode, the SS pin allows multi-drop for multiple slaves with a single master. The SPI must be in slave mode (SSPCON<3:0> = 04h) and the TRIS bit, for the SS pin, must be set for the slave select mode to be enabled. When the SS pin is low, transmission and reception are enabled and the SDO pin is driven. When the SS pin goes high, the SDO pin is no longer driven, even if in the middle of a transmitted byte, and becomes a floating output. External pull-up/ pull-down resistors may be desirable, depending on the application. When the SPI is in Slave Mode with SS pin control enabled, (SSPCON<3:0> = 0100) the SPI module will reset if the SS pin is set to VDD. If the SPI is used in Slave Mode with the CKE bit is set, then the SS pin control must be enabled. When the SPI module resets, the bit counter is forced to 0. This can be done by either by forcing the SS pin to a high level or clearing the SSPEN bit (Figure 19-6). To emulate two-wire communication, the SDO pin can be connected to the SDI pin. When the SPI needs to operate as a receiver the SDO pin can be configured as an input. This disables transmissions from the SDO. The SDI can always be left as an input (SDI function) since it cannot create a bus conflict. Figure 19-5: SPI Mode Waveform (Slave Select Mode With CKE = 1) SCK (CKP = 1 SCK (CKP = 0 Input Sample SDI bit7 bit0 SDO bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 SSPIF Interrupt (SMP = 0) CKE = 1) CKE = 1) (SMP = 0) Write to SSPBUF SSPSR to SSPBUF SS Flag (required) Next Q4 cycle after Q2↓ 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-15 Section 19. SSP SSP 19 Figure 19-6: Slave Synchronization Waveform SCK (CKP = 1 SCK (CKP = 0 Input Sample SDI bit7 SDO bit7 bit6 bit7 SSPIF Interrupt (SMP = 0) CKE = 0) CKE = 0) (SMP = 0) Write to SSPBUF SSPSR to SSPBUF SS Flag bit0 bit7 bit0 (Required) 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-16  2000 Microchip Technology Inc. 19.3.7 Sleep Operation In master mode all module clocks are halted, and the transmission/reception will remain in that state until the device wakes from sleep. After the device returns to normal mode, the module will continue to transmit/receive data. In slave mode, the SPI transmit/receive shift register operates asynchronously to the device. This allows the device to be placed in sleep mode, and data to be shifted into the SPI transmit/receive shift register. When all 8-bits have been received, the SSP interrupt flag bit will be set and if enabled will wake the device from sleep. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-17 Section 19. SSP SSP 19 19.3.8 Effects of a Reset A reset disables the SSP module and terminates the current transfer. Table 19-1: Registers Associated with SPI Operation Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other resets INTCON GIE/ GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIR SSPIF (1) 0 0 IPR SSPIP (1) 0 0 SSPBUF Synchronous Serial Port Receive Buffer/Transmit Register xxxx xxxx uuuu uuuu SSPCON WCOL SSPOV SSPEN CKP SSPM3 SSPM2 SSPM1 SSPM0 0000 0000 0000 0000 TRISA — — PORTA Data Direction Register --11 1111 --11 1111 TRISC PORTC Data Direction Control Register 1111 1111 1111 1111 SSPSTAT SMP CKE D/A P S R/W UA BF 0000 0000 0000 0000 Legend: x = unknown, u = unchanged, - = unimplemented read as '0'. Shaded cells are not used by the SSP in SPI mode. Note 1: The position of this bit is device dependent. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-18  2000 Microchip Technology Inc. 19.4 SSP I2C Operation The SSP module in I2C mode fully implements all slave functions, except general call support, and provides interrupts on start and stop bits in hardware to facilitate software implementations of the master functions. The SSP module implements the standard mode specifications as well as 7-bit and 10-bit addressing. The "Appendix" section gives an overview of the I2C bus specification. Two pins are used for data transfer. These are the SCL pin, which is the clock, and the SDA pin, which is the data. The user must configure these pins as inputs through the TRIS bits. The SSP module functions are enabled by setting SSP Enable bit, SSPEN (SSPCON). A “glitch” filter is on the SCL and SDA pins when the pin is an input. This filter operates in both the 100 KHz and 400 KHz modes. In the 100 KHz mode, when these pins are an output, there is a slew rate control of the pin that is independent of device frequency. Figure 19-7: SSP Block Diagram (I2C Mode) Read Write SSPSR reg Match detect SSPADD reg Start and Stop bit detect SSPBUF reg Internal Data Bus Address Match Set, Reset S, P bits (SSPSTAT reg) SCL shift clock SDA MSb LSb 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-19 Section 19. SSP SSP 19 The SSP module has five registers for I2C operation. They are: • SSP Control Register (SSPCON) • SSP Status Register (SSPSTAT) • Serial Receive/Transmit Buffer (SSPBUF) • SSP Shift Register (SSPSR) - Not directly accessible • SSP Address Register (SSPADD) The SSPCON register allows control of the I2C operation. Four mode selection bits (SSPCON<3:0>) allow one of the following I2C modes to be selected: • I2C Slave mode (7-bit address) • I2C Slave mode (10-bit address) • I2C Firmware controlled Multi-Master mode (start and stop bit interrupts enabled) • I2C Firmware controlled Multi-Master mode (start and stop bit interrupts enabled) • I2C Firmware controlled Master mode, slave is idle Before selecting any I2C mode, the SCL and SDA pins must be programmed to inputs by setting the appropriate TRIS bits. Selecting an I2C mode by setting the SSPEN bit enables the SCL and SDA pins to be used as the clock and data lines in I2C mode. The SSPSTAT register gives the status of the data transfer. This information includes detection of a START or STOP bit, specifies if the received byte was data or address, if the next byte is the completion of 10-bit address, and if this will be a read or write data transfer. The SSPBUF is the register to which transfer data is written to or read from. The SSPSR register shifts the data in or out of the device. In receive operations, the SSPBUF and SSPSR create a doubled buffered receiver. This allows reception of the next byte to begin before reading the last byte of received data. When the complete byte is received, it is transferred to the SSPBUF register and flag bit SSPIF is set. If another complete byte is received before the SSPBUF register is read, a receiver overflow has occurred and the SSPOV bit (SSPCON<6>) is set and the byte in the SSPSR is lost. The SSPADD register holds the slave address. In 10-bit mode, the user needs to write the high byte of the address (1111 0 A9 A8 0). Following the high byte address match, the low byte of the address needs to be loaded (A7:A0). 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-20  2000 Microchip Technology Inc. 19.4.1 Slave Mode In slave mode, the SCL and SDA pins must be configured as inputs (TRIS set). The SSP module will override the input state with the output data when required (slave-transmitter). When an address is matched or the data transfer after an address match is received, the hardware automatically will generate the acknowledge (ACK) pulse, and then load the SSPBUF register with the received value currently in the SSPSR register. There are certain conditions that will cause the SSP module not to give this ACK pulse. These are if either (or both): a) The buffer full bit, BF (SSPSTAT<0>), was set before the message completed. b) The overflow bit, SSPOV (SSPCON<6>), was set before the message completed. In this case, the SSPSR register value is not loaded into the SSPBUF, but the SSPIF and SSPOV bits are set. Table 19-2 shows what happens when a data transfer byte is received, given the status of bits BF and SSPOV. The shaded cells show the condition where user software did not properly clear the overflow condition. The BF flag bit is cleared by reading the SSPBUF register while bit SSPOV is cleared through software. The SCL clock input must have a minimum high and low time for proper operation. The high and low times of the I2C specification as well as the requirement of the SSP module is shown in the Device Data Sheet electrical specifications parameters 100 and 101. 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-21 Section 19. SSP SSP 19 19.4.1.1 Addressing Once the SSP module has been enabled, it waits for a START condition to occur. Following the START condition, the 8-bits are shifted into the SSPSR register. All incoming bits are sampled with the rising edge of the clock (SCL) line. The value of register SSPSR<7:1> is compared to the value of the SSPADD register. The address is compared on the falling edge of the eighth clock (SCL) pulse. If the addresses match, and the BF and SSPOV bits are clear, the following events occur: a) The SSPSR register value is loaded into the SSPBUF register on the falling edge of the eighth SCL pulse. b) The buffer full bit, BF, is set on the falling edge of the eighth SCL pulse. c) An ACK pulse is generated. d) The SSP interrupt flag bit, SSPIF, is set (and an interrupt is generated if enabled) - on the falling edge of the ninth SCL pulse. In 10-bit address mode, two address bytes need to be received by the slave. The five Most Significant bits (MSbs) of the first address byte specify if this is a 10-bit address. The R/W bit (SSPSTAT) must specify a write so the slave device will receive the second address byte. For a 10-bit address the first byte would equal ‘1111 0 A9 A8 0’, where A9 and A8 are the two MSbs of the address. The sequence of events for a 10-bit address is as follows, with steps 7- 9 for slave-transmitter: 1. Receive first (high) byte of Address (the SSPIF, BF, and UA (SSPSTAT) bits are set). 2. Update the SSPADD register with second (low) byte of Address (clears the UA bit and releases the SCL line). 3. Read the SSPBUF register (clears the BF bit) and clear the SSPIF flag bit. 4. Receive second (low) byte of Address (the SSPIF, BF, and UA bits are set). 5. Update the SSPADD register with the high byte of Address. This will clear the UA bit and releases SCL line. 6. Read the SSPBUF register (clears the BF bit) and clear the SSPIF flag bit. 7. Receive repeated START condition. 8. Receive first (high) byte of Address (the SSPIF and BF bits are set). 9. Read the SSPBUF register (clears the BF bit) and clear the SSPIF flag bit. Table 19-2: Data Transfer Received Byte Actions Note: Following the RESTART condition (step 7) in 10-bit mode, the user only needs to match the first 7-bit address. The user does not update the SSPADD for the second half of the address. Status Bits as Data Transfer is Received SSPSR → SSPBUF Generate ACK Pulse Set bit SSPIF (SSP Interrupt occurs BF SSPOV if enabled) 0 0 Yes Yes Yes 1 0 No No Yes 1 1 No No Yes 0 1 Yes No Yes Note:Shaded cells show the conditions where the user software did not properly clear the overflow condition. 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-22  2000 Microchip Technology Inc. 19.4.1.2 Reception When the R/W bit of the address byte is clear and an address match occurs, the R/W bit of the SSPSTAT register is cleared. The received address is loaded into the SSPBUF register. When the address byte overflow condition exists, then no acknowledge (ACK) pulse is given. An overflow condition is defined as either the BF bit (SSPSTAT) is set or the SSPOV bit (SSPCON) is set. When a byte is received with these conditions, and attempts to move from the SSPSR register to the SSPBUF register, no acknowledge pulse is given. An SSP interrupt is generated for each data transfer byte. The SSPIF flag bit must be cleared in software. The SSPSTAT register is used to determine the status of the receive byte. Figure 19-8: I 2 C Waveforms for Reception (7-bit Address) 5 76 8 9 P D6D7 D5 D3D4 D2 D1 D0 S A7 A6 A5 A4 A3 A2 A1SDA SCL 1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9 1 23 4 Bus Master terminates transfer Bit SSPOV is set because the SSPBUF register is still full. Cleared in software SSPBUF register is read Receiving Data ACK Receiving Data D6D7 D5 D3D4 D2 D1 D0 ACK Receiving Address R/W=0 SSPIF BF (SSPSTAT<0>) SSPOV (SSPCON<6>) ACK ACK is not sent. 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-23 Section 19. SSP SSP 19 Figure 19-9: I 2 C Waveforms for Reception (10-bit Address) SDA SCL SSPIF BF (SSPSTAT<0>) S 1 2 34 56 7 8 9 1 234 5 67 89 1 2345 7 89 P 1 1 1 1 0 A9 A8 A7 A6 A5 A4 A3 A2 A1 A0 D7 D6 D5 D4 D3 D1 D0 Receive Data Byte ACK R/W = 0ACK Receive First Byte of Address Cleared in software Bus Master terminates transfer D2 6 (PIR1<3>) Receive Second Byte of Address Cleared by hardware when SSPADD is updated. UA (SSPSTAT<1>) Clock is held low until update of SSPADD has taken place UA is set indicating that the SSPADD needs to be updated UA is set indicating that SSPADD needs to be updated SSPBUF is written with contents of SSPSR Dummy read of SSPBUF to clear BF flag ACK R/W = 1 Cleared in software Dummy read of SSPBUF to clear BF flag Read of SSPBUF clears BF flag Cleared by hardware when SSPADD is updated. 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-24  2000 Microchip Technology Inc. 19.4.1.3 Transmission When the R/W bit of the incoming address byte is set and an address match occurs, the R/W bit of the SSPSTAT register is set. The received address is loaded into the SSPBUF register. The ACK pulse will be sent on the ninth bit, and the SCL pin is held low. The transmit data must be loaded into the SSPBUF register, which also loads the SSPSR register. Then the SCL pin should be enabled by setting the CKP bit (SSPCON<4>). The master must monitor the SCL pin prior to asserting another clock pulse. The slave devices may be holding off the master by stretching the clock. The eight data bits are shifted out on the falling edge of the SCL input. This ensures that the SDA signal is valid during the SCL high time (Figure 19-10). An SSP interrupt is generated for each data transfer byte. The SSPIF flag bit must be cleared in software, and the SSPSTAT register is used to determine the status of the byte transfer. The SSPIF flag bit is set on the falling edge of the ninth clock pulse. As a slave-transmitter, the ACK pulse from the master-receiver is latched on the rising edge of the ninth SCL input pulse. If the SDA line was high (not ACK), then the data transfer is complete. When the not ACK is latched by the slave, the slave logic is reset and the slave then monitors for another occurrence of the START bit. If the SDA line was low (ACK), the transmit data must be loaded into the SSPBUF register, which also loads the SSPSR register. Then the SCL pin should be enabled by setting the CKP bit. Figure 19-10: I 2C Waveforms for Transmission (7-bit Address) SDA SCL SSPIF BF (SSPSTAT<0>) CKP (SSPCON<4>) A7 A6 A5 A4 A3 A2 A1 ACK D7 D6 D5 D4 D3 D2 D1 D0 Receiving Address R/W = 1 Transmitting Data ACK 123456789 1234 56789 P cleared in software SSPBUF is written in software From SSP interrupt service routine Set bit after writing to SSPBUF S Data in sampled SCL held low while CPU responds to SSPIF (the SSPBUF must be written-to before the CKP bit can be set) R/W = 0 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-25 Section 19. SSP SSP 19 Figure 19-11: I 2 C Waveforms for Transmission (10-bit Address) SDA SCL SSPIF BF (SSPSTAT<0>) S 1 234 56 7 8 9 1 234 5 67 89 1 2345 7 89 P 1 1 1 1 0 A9 A8 A7 A6 A5 A4 A3 A2 A1 A0 1 1 1 1 0 A8R/W=1 ACK ACK R/W = 0ACK Receive First Byte of Address Cleared in software Master sends NACK A9 6 (PIR1<3>) Receive Second Byte of Address Cleared by hardware when SSPADD is updated. UA (SSPSTAT<1>) Clock is held low until update of SSPADD has taken place UA is set indicating that the SSPADD needs to be updated UA is set indicating that SSPADD needs to be updated Cleared by hardware when SSPADD is updated. SSPBUF is written with contents of SSPSR Dummy read of SSPBUF to clear BF flag Receive First Byte of Address D7 D6 D5 D4 D3 D1 12345 789 ACK D2 6 Transmitting Data Byte D0 Dummy read of SSPBUF to clear BF flag Sr Cleared in software Write of SSPBUF initiates transmit Cleared in software Transmit is complete CKP has to be set for clock to be released Bus Master terminates transfer 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-26  2000 Microchip Technology Inc. 19.4.1.4 Clock Arbitration Clock arbitration has the SCL pin to inhibit the master device from sending the next clock pulse. The SSP module in I2C slave mode will hold the SCL pin low when the CPU needs to respond to the SSP interrupt (SSPIF bit is set and the CKP bit is cleared). The data that needs to be transmitted will need to be written to the SSPBUF register, and then the CKP bit will need to be set to allow the master to generate the required clocks. 19.4.2 Master Mode (Firmware) Master mode of operation is supported by interrupt generation on the detection of the START and STOP conditions. The STOP (P) and START (S) bits are cleared from a reset or when the SSP module is disabled. Control of the I2C bus may be taken when the P bit is set, or the bus is idle with both the S and P bits clear. In master mode the SCL and SDA lines are manipulated by clearing the corresponding TRIS bit(s). The output level is always low, irrespective of the value(s) in the PORT register. So when transmitting data, a '1' data bit must have it’s TRIS bit set (input) and a '0' data bit must have it’s TRIS bit cleared (output). The same scenario is true for the SCL line with the TRIS bit. The following events will cause SSP Interrupt Flag bit, SSPIF, to be set (SSP Interrupt if enabled): • START condition • STOP condition • Data transfer byte transmitted/received Master mode of operation can be done with either the slave mode idle (SSPM3:SSPM0 = 1011) or with the slave active (SSPM3:SSP0 = 1110 or 1111). When the slave modes are enabled, the software needs to differentiate the source(s) of the interrupt. 19.4.3 Multi-Master Mode (Firmware) In multi-Master mode, the interrupt generation on the detection of the START and STOP conditions allows the determination of when the bus is free. The STOP (P) and START (S) bits are cleared from a reset or when the SSP module is disabled. Control of the I2C bus may be taken when the P bit (SSPSTAT<4>) is set, or the bus is idle with both the S and P bits clear. When the bus is busy, enabling the SSP Interrupt will generate the interrupt when the STOP condition occurs. In Multi-Master operation, the SDA line must be monitored to see if the signal level is the expected output level. This check only needs to be done when a high level is output. If a high level is expected and a low level is present, the device needs to release the SDA and SCL lines (set the TRIS bits). There are two stages where this arbitration can be lost, they are: • Address transfer • Data transfer When the slave logic is enabled, the slave continues to receive. If arbitration was lost during the address transfer stage, communication to the device may be in progress. If addressed an ACK pulse will be generated. If arbitration was lost during the data transfer stage, the device will need to retransfer the data at a later time. 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-27 Section 19. SSP SSP 19 19.4.4 Sleep Operation While in sleep mode, the I2C module can receive addresses or data, and when an address match or complete byte transfer occurs wake the processor from sleep (if the SSP interrupt is enabled). 19.4.5 Effect of a Reset A reset disables the SSP module and terminates the current transfer. Table 19-3: Registers Associated with I 2C Operation Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other resets INTCON GIE/ GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIR SSPIF (1) 0 0 IPR SSPIP (1) 0 0 SSPBUF Synchronous Serial Port Receive Buffer/Transmit Register xxxx xxxx uuuu uuuu SSPADD Synchronous Serial Port (I2C mode) Address Register 0000 0000 0000 0000 SSPCON WCOL SSPOV SSPEN CKP SSPM3 SSPM2 SSPM1 SSPM0 0000 0000 0000 0000 SSPSTAT SMP CKE D/A P S R/W UA BF 0000 0000 0000 0000 Legend: x = unknown, u = unchanged, - = unimplemented read as '0'. Shaded cells are not used by SSP in I2C mode. Note 1: The positions of these bits are device dependent. 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-28  2000 Microchip Technology Inc. 19.5 Initialization Example 19-2: SPI Master Mode Initialization CLRF SSPSTAT ; SMP = 0, CKE = 0, and clear status bits BSF SSPSTAT, CKE ; CKE = 1 MOVLW 0x31 ; Set up SPI port, Master mode, CLK/16, MOVWF SSPCON ; Data xmit on falling edge (CKE=1 & CKP=1) ; Data sampled in middle (SMP=0 & Master mode) BSF PIE, SSPIE ; Enable SSP interrupt BSF INTCON, GIE ; Enable, enabled interrupts MOVLW DataByte ; Data to be Transmitted ; Could move data from RAM location MOVWF SSPBUF ; Start Transmission 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-29 Section 19. SSP SSP 19 19.5.1 SSP Module / Basic SSP Module Compatibility When upgrading from the Mid-Range family’s basic SSP module, the SSPSTAT register contains two additional control bits. These bits are used only in SPI mode and are: • SMP, SPI data input sample phase • CKE, SPI Clock Edge Select To be compatible with the SPI of the basic SSP module, these bits must be appropriately configured. If these bits are not at the states shown in Table 19-4, improper SPI communication may occur. Table 19-4: New Bit States for Compatibility Mid-Range Family’s Basic SSP Module SSP Module CKP CKP CKE SMP 1 100 0 000 39500 18C Reference Manual.book Page 29 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-30  2000 Microchip Technology Inc. 19.6 Design Tips Question 1: Using SPI mode, I do not seem able to talk to an SPI device. Answer 1: Ensure that you are using the correct SPI mode for that device. This SPI supports all four SPI modes so you should be able to get it to function. Check the clock polarity and the clock phase. These settings should match what the SPI is interfacing to. Question 2: Using I2C mode, I do not seem able to make the master mode work. Answer 2: This SSP module does not have master mode fully automated in hardware, see Application Note AN578 for software which uses the SSP module to implement master mode. If you require a fully automated hardware implementation of I2C Master Mode, please refer to the Microchip Line Card for devices that have the Master SSP module. Question 3: Using I2C mode, I write data to the SSPBUF register, but the data did not transmit. Answer 3: Ensure that you set the CKP bit to release the I2C clock. 39500 18C Reference Manual.book Page 30 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39519A-page 19-31 Section 19. SSP SSP 19 19.7 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced MCU family (that is they may be written for the Base-Line, Mid-Range or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the SSP Module are: Title Application Note # Use of the SSP Module in the I 2C Multi-Master Environment. AN578 Using Microchip 93 Series Serial EEPROMs with Microcontroller SPI Ports AN613 Software Implementation of I2C Bus Master AN554 Use of the SSP module in the Multi-master Environment AN578 Interfacing PIC16C64/74 to Microchip SPI Serial EEPROM AN647 Interfacing a Microchip PIC16C92x to Microchip SPI Serial EEPROM AN668 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 31 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39519A-page 19-32  2000 Microchip Technology Inc. 19.8 Revision History Revision A This is the initial released revision of the SSP module description. 39500 18C Reference Manual.book Page 32 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-1 Master SSP 20 Section 20. Master SSP HIGHLIGHTS This section of the manual contains the following major topics: 20.1 Introduction .................................................................................................................. 20-2 20.2 Control Registers ......................................................................................................... 20-4 20.3 SPI Mode ..................................................................................................................... 20-9 20.4 MSSP I2C Operation ................................................................................................. 20-17 20.5 Design Tips ................................................................................................................ 20-55 20.6 Related Application Notes.......................................................................................... 20-56 20.7 Revision History ......................................................................................................... 20-57 I 2C is a trademark of Philips 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-2  2000 Microchip Technology Inc. 20.1 Introduction The Master Synchronous Serial Port (MSSP) module is a serial interface useful for communicating with other peripheral or microcontroller devices. These peripheral devices may be serial EEPROMs, Shift Registers, display drivers, A/D converters, etc. The MSSP module can operate in one of two modes: • Serial Peripheral Interface (SPI) • Inter-Integrated Circuit (I2C) - Full Master Mode - Slave Mode (with general address call) The I2C interface supports the following modes in hardware: • Master Mode • Multi-Master Mode • Slave Mode Figure 20-1 shows a block diagram for the SPI Mode, while Figure 20-2 and Figure 20-3 show the block diagrams for the two different I2C Modes of operation. Figure 20-1: SPI Mode Block Diagram Read Write Internal Data Bus SSPSR Reg SSPBUF Reg SSPM3:SSPM0 bit0 Shift Clock SS Control Enable Edge Select Clock Select TMR2 Output Prescaler TOSC 4, 16, 64 2 Edge Select 2 4 Data to TX/RX in SSPSR TRIS Bit 2 SMP:CKE SDI SDO SS SCK ( ) 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-3 Section 20. Master SSP Master SSP 20 Figure 20-2: I2C Slave Mode Block Diagram Figure 20-3: I2C Master Mode Block Diagram Read Write SSPSR Reg Match Detect SSPADD Reg Start and Stop Bit Detect SSPBUF Reg Internal Data Bus Address Match or Set, Reset S, P Bits (SSPSTAT Reg) SCL Shift Clock SDA MSb LSb General Call Detected Read Write SSPSR Start Bit, Stop Bit, SSPBUF Internal Data Bus Set/Reset, S, P, WCOL (SSPSTAT) Shift Clock MSb LSb SDA Acknowledge Generate SCL SCL in Bus Collision SDA in Receive Enable Clock Cntl Clock Arbitrate/WCOL Detect (Hold Off Clock Source) SSPADD<6:0> Baud Set SSPIF, BCLIF Reset ACKSTAT, PEN (SSPCON2) Rate Generator SSPM3:SSPM0 Start Bit Detect Stop Bit Detect Write Collision Detect Clock Arbitration State Counter for End of XMIT/RCV 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-4  2000 Microchip Technology Inc. 20.2 Control Registers The Master SSP (MSSP) module has three registers that control the operation and indicate the status of the module. These are the SSPSTAT register (Register 20-1), the SSPCON1register (Register 20-2), and the SSPCON2 register (Register 20-3). Register 20-1: SSPSTAT: MSSP Status Register R/W-0 R/W-0 R-0 R-0 R-0 R-0 R-0 R-0 SMP CKE D/A P S R/W UA BF bit 7 bit 0 bit 7 SMP: Sample bit SPI Master Mode 1 = Input data sampled at end of data output time 0 = Input data sampled at middle of data output time SPI Slave Mode SMP must be cleared when SPI is used in Slave Mode In I2C Master or Slave Mode: 1= Slew rate control disabled for standard speed mode (100 kHz and 1 MHz) 0= Slew rate control enabled for high speed mode (400 kHz) bit 6 CKE: SPI Clock Edge Select CKP = 0 1 = Data transmitted on rising edge of SCK 0 = Data transmitted on falling edge of SCK CKP = 1 1 = Data transmitted on falling edge of SCK 0 = Data transmitted on rising edge of SCK bit 5 D/A: Data/Address bit (I2C Mode only) 1 = Indicates that the last byte received or transmitted was data 0 = Indicates that the last byte received or transmitted was address bit 4 P: Stop bit (I2C Mode only. This bit is cleared when the MSSP module is disabled, SSPEN is cleared) 1 = Indicates that a Stop bit has been detected last (this bit is '0' on RESET) 0 = Stop bit was not detected last bit 3 S: Start bit (I2C Mode only. This bit is cleared when the MSSP module is disabled, SSPEN is cleared) 1 = Indicates that a Start bit has been detected last (this bit is '0' on RESET) 0 = Start bit was not detected last bit 2 R/W: Read/Write bit information (I2C Mode only) This bit holds the R/W bit information following the last address match. This bit is only valid from the address match to the next Start bit, Stop bit, or not ACK bit. In I 2C Slave Mode: 1 = Read 0 = Write In I 2C Master Mode: 1 = Transmit is in progress 0 = Transmit is not in progress. Or’ing this bit with SEN, RSEN, PEN, RCEN, or ACKEN will indicate if the MSSP is in idle Mode. bit 1 UA: Update Address (10-bit I2C mode only) 1 = Indicates that the user needs to update the address in the SSPADD Register 0 = Address does not need to be updated 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-5 Section 20. Master SSP Master SSP 20 bit 0 BF: Buffer Full Status bit Receive (SPI and I 2C Modes) 1 = Receive complete, SSPBUF is full 0 = Receive not complete, SSPBUF is empty Transmit (I 2C Mode only) 1 = Data transmit in progress (does not include the ACK and Stop bits), SSPBUF is full 0 = Data transmit complete (does not include the ACK and Stop bits), SSPBUF is empty Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleard x = bit is unknown 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-6  2000 Microchip Technology Inc. Register 20-2: SSPCON1: MSSP Control Register1 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 WCOL SSPOV SSPEN CKP SSPM3 SSPM2 SSPM1 SSPM0 bit 7 bit 0 bit 7 WCOL: Write Collision Detect bit Master Mode: 1 = A write to the SSPBUF Register was attempted while the I2C conditions were not valid for a transmission to be started 0 = No collision Slave Mode: 1 = The SSPBUF Register is written while it is still transmitting the previous word (must be cleared in software) 0 = No collision bit 6 SSPOV: Receive Overflow Indicator bit In SPI Mode: 1 = A new byte is received while the SSPBUF Register is still holding the previous data. In case of overflow, the data in SSPSR is lost. Overflow can only occur in Slave Mode. In Slave Mode, the user must read the SSPBUF, even if only transmitting data, to avoid setting overflow. In Master Mode the overflow bit is not set since each new reception (and transmission) is initiated by writing to the SSPBUF Register. (Must be cleared in software) 0 = No overflow In I2C Mode: 1 = A byte is received while the SSPBUF Register is still holding the previous byte. SSPOV is a "don’t care" in transmit mode. (Must be cleared in software) 0 = No overflow bit 5 SSPEN: Synchronous Serial Port Enable bit In both modes, when enabled, the I/O pins must be properly configured as input or output. In SPI Mode: 1 = Enables serial port and configures SCK, SDO, SDI, and SS as the source of the serial port pins 0 = Disables serial port and configures these pins as I/O port pins In I 2C Mode: 1 = Enables the serial port and configures the SDA and SCL pins as the source of the serial port pins 0 = Disables serial port and configures these pins as I/O port pins bit 4 CKP: Clock Polarity Select bit In SPI Mode: 1 = Idle state for clock is a high level 0 = Idle state for clock is a low level In I 2C Slave Mode: SCK release control 1 = Enable clock 0 = Holds clock low (clock stretch) (Used to ensure data setup time) In I 2C Master Mode Unused in this mode 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-7 Section 20. Master SSP Master SSP 20 bit 3 - 0 SSPM3:SSPM0: Synchronous Serial Port Mode Select bits 0000 = SPI Master Mode, clock = FOSC/4 0001 = SPI Master Mode, clock = FOSC/16 0010 = SPI Master Mode, clock = FOSC/64 0011 = SPI Master Mode, clock = TMR2 output/2 0100 = SPI Slave Mode, clock = SCK pin. SS pin control enabled. 0101 = SPI Slave Mode, clock = SCK pin. SS pin control disabled. SS can be used as I/O pin 0110 = I2C Slave Mode, 7-bit address 0111 = I2C Slave Mode, 10-bit address 1000 = I2C Master Mode, clock = FOSC / (4 * (SSPADD+1) ) 1001 = Reserved 1010 = Reserved 1011 = I2C firmware controlled master mode (Slave idle) 1100 = Reserved 1101 = Reserved 1110 = I2C Slave Mode, 7-bit address with Start and Stop bit interrupts enabled 1111 = I2C Slave Mode, 10-bit address with Start and Stop bit interrupts enabled Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleard x = bit is unknown 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-8  2000 Microchip Technology Inc. Register 20-3: SSPCON2: MSSP Control Register2 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 GCEN ACKSTAT ACKDT ACKEN RCEN PEN RSEN SEN bit 7 bit 0 bit 7 GCEN: General Call Enable bit (In I2C Slave Mode only) 1 = Enable interrupt when a general call address (0000h) is received in the SSPSR 0 = General call address disabled bit 6 ACKSTAT: Acknowledge Status bit (In I2C Master Mode only) In Master Transmit Mode: 1 = Acknowledge was not received from slave 0 = Acknowledge was received from slave bit 5 ACKDT: Acknowledge Data bit (In I2C Master Mode only) In Master Receive Mode: Value that will be transmitted when the user initiates an Acknowledge sequence at the end of a receive. 1 = Not Acknowledge 0 = Acknowledge bit 4 ACKEN: Acknowledge Sequence Enable bit (In I2C Master Mode only) In Master Receive Mode: 1 = Initiate Acknowledge sequence on SDA and SCL pins, and transmit ACKDT data bit. Automatically cleared by hardware. 0 = Acknowledge sequence idle bit 3 RCEN: Receive Enable bit (In I2C Master Mode only) 1 = Enables Receive mode for I2C 0 = Receive idle bit 2 PEN: Stop condition enable bit (In I2C Master Mode only) SCK release control 1 = Initiate Stop condition on SDA and SCL pins. Automatically cleared by hardware. 0 = Stop condition idle bit 1 RSEN: Repeated Start condition enabled bit (In I2C Master Mode only) 1 = Initiate Repeated Start condition on SDA and SCL pins. Automatically cleared by hardware. 0 = Repeated Start condition idle. bit 0 SEN: Start condition enabled bit (In I2C Master Mode only) 1 = Initiate Start condition on SDA and SCL pins. Automatically cleared by hardware. 0 = Start condition idle Note: For the ACKEN, RCEN, PEN, RSEN, SEN bits: If the I2C module is not in the idle mode, the bit may not be set (no spooling) and the SSPBUF may not be written (writes to the SSPBUF are disabled). Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleard x = bit is unknown 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-9 Section 20. Master SSP Master SSP 20 20.3 SPI Mode The SPI mode allows 8 bits of data to be synchronously transmitted and received simultaneously. All four modes of SPI are supported. To accomplish communication, typically three pins are used: • Serial Data Out (SDO) • Serial Data In (SDI) • Serial Clock (SCK) Additionally a fourth pin may be used when in a Slave Mode of operation: • Slave Select (SS) 20.3.1 Operation When initializing the SPI, several options need to be specified. This is done by programming the appropriate control bits (SSPCON1<5:0>) and SSPSTAT<7:6>. These control bits allow the following to be specified: • Master Mode (SCK is the clock output) • Slave Mode (SCK is the clock input) • Clock Polarity (Idle state of SCK) • Data input sample phase (middle or end of data output time) • Clock edge (output data on rising/falling edge of SCK) • Clock Rate (Master Mode only) • Slave Select Mode (Slave Mode only) Figure 20-4 shows the block diagram of the MSSP module, when in SPI mode. Figure 20-4: MSSP Block Diagram (SPI Mode) Read Write Internal Data Bus SSPSR Reg SSPBUF Reg SSPM3:SSPM0 bit0 Shift Clock SS Control Enable Edge Select Clock Select TMR2 Output Prescaler TOSC 4, 16, 64 2 Edge Select 2 4 Data to TX/RX in SSPSR TRIS bit 2 SMP:CKE SDI SDO SS SCK 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-10  2000 Microchip Technology Inc. The MSSP consists of a transmit/receive Shift Register (SSPSR) and a Buffer Register (SSPBUF). The SSPSR shifts the data in and out of the device, MSb first. The SSPBUF holds the data that was written to the SSPSR, until the received data is ready. Once the 8 bits of data have been received, that byte is moved to the SSPBUF Register. Then the buffer full detect bit, BF (SSPSTAT register), and the interrupt flag bit, SSPIF, are set. This double buffering of the received data (SSPBUF) allows the next byte to start reception before reading the data that was just received. Any write to the SSPBUF Register during transmission/reception of data will be ignored, and the write collision detect bit, WCOL (SSPCON1 register), will be set. User software must clear the WCOL bit so that it can be determined if the following write(s) to the SSPBUF Register completed successfully. When the application software is expecting to receive valid data, the SSPBUF should be read before the next byte of data to transfer is written to the SSPBUF. Buffer full bit, BF (SSPSTAT register), indicates when SSPBUF has been loaded with the received data (transmission is complete). When the SSPBUF is read, the BF bit is cleared. This data may be irrelevant if the SPI is only a transmitter. Generally the MSSP Interrupt is used to determine when the transmission/reception has completed. The SSPBUF must be read and/or written. If the interrupt method is not going to be used, then software polling can be done to ensure that a write collision does not occur. Example 20-1 shows the loading of the SSPBUF (SSPSR) for data transmission. Example 20-1:Loading the SSPBUF (SSPSR) Register The SSPSR is not directly readable or writable, and can only be accessed by addressing the SSPBUF Register. Additionally, the MSSP Status Register (SSPSTAT) indicates the various status conditions. LOOP BTFSS SSPSTAT, BF ;Has data been received (transmit complete)? GOTO LOOP ;No MOVF SSPBUF, W ;WREG reg = contents of SSPBUF MOVWF RXDATA ;Save in user RAM, if data is meaningful MOVF TXDATA, W ;W reg = contents of TXDATA MOVWF SSPBUF ;New data to xmit 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-11 Section 20. Master SSP Master SSP 20 20.3.2 Enabling SPI I/O To enable the serial port, SSP Enable bit, SSPEN, must be set. To reset or reconfigure SPI mode, clear the SSPEN bit, re-initialize the SSPCON Registers, and then set the SSPEN bit. This configures the SDI, SDO, SCK, and SS pins as serial port pins. For the pins to behave as the serial port function, some must have their data direction bits (in the TRIS Register) appropriately programmed. That is: • SDI is automatically controlled by the SPI module • SDO must have the TRIS bit cleared • SCK (Master Mode) must have the TRIS bit cleared • SCK (Slave Mode) must have the TRIS bit set • SS must have the TRIS bit set Any serial port function that is not desired may be overridden by programming the corresponding data direction (TRIS) Register to the opposite value. 20.3.3 Typical Connection Figure 20-5 shows a typical connection between two microcontrollers. The master controller (Processor 1) initiates the data transfer by sending the SCK signal. Data is shifted out of both Shift Registers on their programmed clock edge, and latched on the opposite edge of the clock. Both processors should be programmed to same Clock Polarity (CKP), then both controllers would send and receive data at the same time. Whether the data is meaningful (or dummy data) depends on the application software. This leads to three scenarios for data transmission: • Master sends data — Slave sends dummy data • Master sends data — Slave sends data • Master sends dummy data — Slave sends data Figure 20-5:SPI Master/Slave Connection Serial Input Buffer (SSPBUF) Shift Register (SSPSR) MSb LSb SDO SDI PROCESSOR 1 SCK SPI Master SSPM3:SSPM0 = 00xxb Serial Input Buffer (SSPBUF) Shift Register (SSPSR) MSb LSb SDI SDO PROCESSOR 2 SCK SPI Slave SSPM3:SSPM0 = 010xb Serial Clock 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-12  2000 Microchip Technology Inc. 20.3.4 SPI Master Mode The master can initiate the data transfer at any time because it controls the SCK. The master determines when the slave (Processor 2, Figure 20-5) is to broadcast data by the software protocol. In Master Mode, the data is transmitted/received as soon as the SSPBUF Register is written to. If the SPI is only going to receive, the SDO output could be disabled (programmed as an input). The SSPSR Register will continue to shift in the signal present on the SDI pin at the programmed clock rate. As each byte is received, it will be loaded into the SSPBUF Register (interrupts and status bits appropriately set). This could be useful in receiver applications as a “line activity monitor” mode. The clock polarity is selected by appropriately programming the CKP bit. This gives waveforms for SPI communication as shown in Figure 20-6, Figure 20-8, and Figure 20-9 where the Msb is transmitted first. In Master Mode, the SPI clock rate (bit rate) is user programmable to be one of the following: • FOSC/4 (or TCY) • FOSC/16 (or 4 • TCY) • FOSC/64 (or 16 • TCY) • Timer2 output/2 This allows a maximum data rate (at 40 MHz) of 10.00 Mbps. Figure 20-6 shows the waveforms for Master Mode. When the CKE bit is set, the SDO data is valid before there is a clock edge on SCK. The change of the input sample is shown based on the state of the SMP bit. The time when the SSPBUF is loaded with the received data is shown. Figure 20-6:SPI Mode Waveform (Master Mode) SCK (CKP = 0 SCK (CKP = 1 SCK (CKP = 0 SCK (CKP = 1 4 clock modes Input Sample Input Sample SDI bit7 bit0 SDO bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 bit7 bit0 SDI SSPIF (SMP = 1) (SMP = 0) (SMP = 1) CKE = 1) CKE = 0) CKE = 1) CKE = 0) (SMP = 0) Write to SSPBUF SSPSR to SSPBUF SDO bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 (CKE = 0) (CKE = 1) Next Q4 cycle after Q2↓ 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-13 Section 20. Master SSP Master SSP 20 20.3.5 SPI Slave Mode In Slave Mode, the data is transmitted and received as the external clock pulses appear on SCK. When the last bit is latched, the SSPIF interrupt flag bit is set. While in Slave Mode, the external clock is supplied by the external clock source on the SCK pin. This external clock must meet the minimum high and low times as specified in the electrical specifications. While in sleep mode, the slave can transmit/receive data. When a byte is received, the device will wake-up from sleep. 20.3.6 Slave Select Synchronization The SS pin is a Slave Select pin, and functions similar to a chip select pin. The SPI must be in Slave Mode with SS pin control enabled (SSPCON1<3:0> = 04h). The pin must be configured as an input by setting the corresponding TRIS bit. When the SS pin is low, transmission and reception are enabled and the SDO pin is driven. When the SS pin goes high, the SDO pin is no longer driven, even if in the middle of a transmitted byte, and becomes a floating output. External pull-up/ pull-down resistors may be desirable, depending on the application. If the TRIS bit is cleared, making the pin an output, and the pin outputs a high , the SPI receive logic (slave mode) will be in reset. It will remain in reset until either the pin outputs a low, or the pin’s TRIS bit is set and external circuits pull the pin low. When the SPI module resets, the bit counter is forced to 0. This can be done by either by forcing the SS pin to a high level or clearing the SSPEN bit. To emulate two-wire communication, the SDO pin can be connected to the SDI pin. When the SPI needs to operate as a receiver, the SDO pin can be configured as an input. This disables transmissions from the SDO. The SDI can always be left as an input (SDI function) since it cannot create a bus conflict. Note 1: When the SPI is in Slave Mode with SS pin control enabled, (SSPCON<3:0> = 0100) the SPI module will reset if the SS pin is set to VDD. Note 2: If the SPI is used in Slave Mode with CKE set, then the SS pin control must be enabled. 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-14  2000 Microchip Technology Inc. Figure 20-7:Slave Synchronization Waveform Figure 20-8:SPI Slave Mode Waveform (CKE = 0) bit7 bit7 bit6 bit7 bit0 bit7 bit0 Next Q4 cycle after Q2Ø SS SCK (CKP = 0) (CKE = 0) SCK (CKP = 1) (CKE = 0) Write to SSPBUF SDI (SMP = 0) Input Sample (SMP = 0) SSPIF Interrupt Flag SSPSR to SSPBUF SDO bit7 bit0 bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 Next Q4 cycle after Q2Ø SS SCK (CKP = 0) (CKE = 0) SCK (CKP = 1) (CKE = 0) Write to SSPBUF SDI (SMP = 0) Input Sample (SMP = 0) SSPIF Interrupt Flag SSPSR to SSPBUF SDO 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-15 Section 20. Master SSP Master SSP 20 Figure 20-9:SPI Slave Mode Waveform (CKE = 1) SCK (CKP = 1) SCK (KP = 0) Input Sample SDI bit7 bit0 SDO bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 SSPIF Interrupt (SMP = 0) (SMP = 0) Write to SSPBUF SSPSR to SSPBUF SS Flag required Next Q4 cycle after Q2Ø 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-16  2000 Microchip Technology Inc. 20.3.7 Sleep Operation In Master Mode, when the SLEEP instruction is executed, all module clocks are halted. The transmission/reception that is in progress will remain in the current state until the device wakes from sleep. After the device returns to normal mode, the module will continue to transmit/receive data. In Slave Mode, the SPI transmit/receive Shift Register operates asynchronously to the device. This allows the device to be placed in sleep mode, and data to be shifted into the SPI transmit/receive Shift Register. When all 8 bits have been received, the MSSP interrupt flag bit will be set. If the SSPIF is enabled, it will wake the device from sleep. 20.3.8 Effects of a Reset A reset disables the MSSP module and terminates the current transfer. 20.3.9 Bus Mode Compatibility Table 20-1 shows the compatibility between the standard SPI modes and the states of the CKP and CKE control bits. Table 20-1: SPI Bus Modes There is also a SMP bit that controls when the data is sampled. Table 20-2: Registers Associated with SPI Operation Standard SPI Mode Terminology Control Bits State CKP CKE 0, 0 0 1 0, 1 0 0 1, 0 1 1 1, 1 1 0 Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other resets INTCON GIE/ GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIR1 PSPIF (1) ADIF RCIF TXIF SSPIF CCP1IF TMR2IF TMR1IF 0000 0000 0000 0000 PIE1 PSPIE (1) ADIE RCIE TXIE SSPIE CCP1IE TMR2IE TMR1IE 0000 0000 0000 0000 IPR1 PSPIP (1) ADIP RCIP TXIP SSPIP CCP1IP TMR2IP TMR1IP 0000 0000 0000 0000 TRISC PORTC Data Direction Register 1111 1111 1111 1111 SSPBUF Synchronous Serial Port Receive Buffer/Transmit Register xxxx xxxx uuuu uuuu SSPCON WCOL SSPOV SSPEN CKP SSPM3 SSPM2 SSPM1 SSPM0 0000 0000 0000 0000 TRISA — PORTA Data Direction Register --11 1111 --11 1111 SSPSTAT SMP CKE D/A P S R/W UA BF 0000 0000 0000 0000 Legend: x = unknown, u = unchanged, - = unimplemented read as '0'. Shaded cells are not used by the MSSP in SPI mode. Note 1: The PSPIF, PSPIE and PSPIP bits are reserved on the PIC18C2X2 devices. Always maintain these bits clear. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-17 Section 20. Master SSP Master SSP 20 20.4 MSSP I2C Operation The MSSP module in I2C mode fully implements all master and slave functions (including general call support) and provides interrupts on Start and Stop bits in hardware to determine a free bus (multi-master function). The MSSP module implements the standard mode specifications as well as 7-bit and 10-bit addressing. Appendix A gives an overview of the I2C bus specification. A "glitch" filter is on the SCL and SDA pins when the pin is an input. This filter operates in both the 100 kHz and 400 kHz modes. In the 100 kHz mode, when these pins are an output, there is a slew rate control of the pin that is independent of device frequency. Figure 20-10: I2C Slave Mode Block Diagram Figure 20-11: I2C Master Mode Block Diagram Read Write SSPSR reg Match detect SSPADD reg Start and Stop bit detect SSPBUF reg Internal Data Bus Address Match Set, Reset S, P bits (SSPSTAT reg) SCL shift clock SDA MSb LSb Read Write SSPSR reg Match detect SSPADD reg Start and Stop bit detect / generate SSPBUF reg Internal Data Bus Address Match Set/Clear S bit Clear/Set P bit (SSPSTAT reg) SCL shift clock SDA MSb LSb Baud Rate Generator 7 SSPADD<6:0> and and Set SSPIF 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-18  2000 Microchip Technology Inc. Two pins are used for data transfer. These are the SCL pin, which is the clock, and the SDA pin, which is the data. The SDA and SCL pins must be configured as inputs in the corresponding TRIS registers when the I2C mode is enabled. The MSSP module functions are enabled by setting the MSSP Enable bit, SSPEN (SSPCON register).The MSSP module has six registers for I 2C operation. They are the: • MSSP Control Register1 (SSPCON1) • MSSP Control Register2 (SSPCON2) • MSSP Status Register (SSPSTAT) • Serial Receive/Transmit Buffer (SSPBUF) • MSSP Shift Register (SSPSR) - Not directly accessible • MSSP Address Register (SSPADD) The SSPCON1 Register allows control of the I2C operation. Four mode selection bits (SSPCON1<3:0>) allow one of the following I2C modes to be selected: • I2C Slave Mode (7-bit address) • I2C Slave Mode (10-bit address) • I2C Master Mode, clock = OSC/4 (SSPADD +1) • I2C Slave Mode (7-bit address), with Start and Stop bit interrupts enabled • I2C Slave Mode (10-bit address), with Start and Stop bit interrupts enabled • I2C Firmware controlled master operation, slave is idle Before selecting any I2C mode, the SCL and SDA pins must be programmed to inputs by setting the appropriate TRIS bits. Selecting an I2C mode, by setting the SSPEN bit, enables the SCL and SDA pins to be used as the clock and data lines in I2C mode. The SSPSTAT Register gives the status of the data transfer. This information includes detection of a Start or Stop bit, specifies if the received byte was data or address, if the next byte is the completion of 10-bit address, and if this will be a read or write data transfer. The SSPBUF is the register to which transfer data is written to or read from. The SSPSR Register shifts the data in or out of the device. In receive operations, the SSPBUF and SSPSR create a double buffered receiver. This allows reception of the next byte to begin before reading the current byte of received data. When the complete byte is received, it is transferred to the SSPBUF Register and the SSPIF bit is set. If another complete byte is received before the SSPBUF Register is read, a receiver overflow has occurred and the SSPOV bit (SSPCON1 register) is set and the byte in the SSPSR is lost. The SSPADD Register holds the slave address. In 10-bit mode, the user needs to write the high byte of the address (1111 0 A9 A8 0). Following the high byte address match, the low byte of the address needs to be loaded (A7:A0). 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-19 Section 20. Master SSP Master SSP 20 20.4.1 Slave Mode In Slave Mode, the SCL and SDA pins must be configured as inputs. The MSSP module will override the input state with the output data when required (slave-transmitter). When an address is matched or the data transfer after an address match is received, the hardware automatically generates the acknowledge (ACK) pulse, and loads the SSPBUF Register with the received value currently in the SSPSR Register. There are certain conditions that will cause the MSSP module not to give this ACK pulse. These are if either (or both): a) The buffer full bit, BF (SSPSTAT register), was set before the transfer was received. b) The overflow bit, SSPOV (SSPCON1 register), was set before the transfer was received. If the BF bit is set, the SSPSR Register value is not loaded into the SSPBUF, but the SSPIF and SSPOV bits are set. Table 20-3 shows what happens when a data transfer byte is received, given the status of the BF and SSPOV bits. The shaded cells show the condition where user software did not properly clear the overflow condition. The BF bit is cleared by reading the SSPBUF register while bit SSPOV is cleared through software. The SCL clock input must have a minimum high and low time for proper operation. The high and low times of the I2C specification as well as the requirement of the MSSP module is shown in timing parameters 100 and 101 of the “Electrical Specifications” section. 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-20  2000 Microchip Technology Inc. 20.4.1.1 Addressing Once the MSSP module has been enabled, it waits for a Start condition to occur. Following the Start condition, the 8 bits are shifted into the SSPSR Register. All incoming bits are sampled with the rising edge of the clock (SCL) line. The value of register SSPSR<7:1> is compared to the value of the SSPADD Register (bits 7:1). The address is compared on the falling edge of the eighth clock (SCL) pulse. If the addresses match, and the BF and SSPOV bits are clear, the following events occur: a) The SSPSR Register value is loaded into the SSPBUF Register on the falling edge of the eighth SCL pulse. b) The buffer full bit, BF, is set on the falling edge of the eighth SCL pulse. c) An ACK pulse is generated. d) MSSP interrupt flag bit, SSPIF, is set (interrupt is generated if enabled) - on the falling edge of the ninth SCL pulse. In 10-bit address mode, two address bytes need to be received by the slave. The five Most Significant bits (MSbs) of the first address byte specify if this is a 10-bit address. The R/W bit (SSPSTAT<2>) must specify a write so the slave device will receive the second address byte. For a 10-bit address the first byte would equal ‘1111 0 A9 A8 0’, where A9 and A8 are the two MSbs of the address. The sequence of events for a 10-bit address is as follows (with steps 7- 9 for a slave-transmitter): 1. Receive first (high) byte of the address (the SSPIF, BF, and UA (SSPSTAT register) bits are set). 2. Update the SSPADD Register with second (low) byte of the address (clears the UA bit and releases the SCL line). 3. Read the SSPBUF Register (clears the BF bit) and clear flag bit SSPIF. 4. Receive second (low) byte of the address (the SSPIF, BF, and UA bits are set). 5. Update the SSPADD Register with the first (high) byte of the address. This will clear the UA bit and release the SCL line. 6. Read the SSPBUF Register (clears the BF bit) and clear the SSPIF flag bit. 7. Receive repeated Start condition. 8. Receive first (high) byte of the address (the SSPIF and BF bits are set). 9. Read the SSPBUF Register (clears the BF bit) and clear the SSPIF flag bit. Table 20-3: Data Transfer Received Byte Actions Note: Following the Repeated Start condition (step 7) in 10-bit mode, the user only needs to match the first 7-bit address. The user does not update the SSPADD for the second half of the address. Status Bits as Data Transfer is Received SSPSR → SSPBUF Generate ACK Pulse Set bit SSPIF (SSP Interrupt occurs BF SSPOV if enabled) 0 0 Yes Yes Yes 1 0 No No Yes 1 1 No No Yes 0 1 Yes No Yes Note: Shaded cells show the conditions where the user software did not properly clear the overflow condition 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-21 Section 20. Master SSP Master SSP 20 20.4.1.2 Slave Reception When the R/W bit of the address byte is clear and an address match occurs, the R/W bit of the SSPSTAT Register is cleared. The received address is loaded into the SSPBUF Register. When the address byte overflow condition exists, then no acknowledge (ACK) pulse is given. An overflow condition is defined as either the BF bit (SSPSTAT register) is set or the SSPOV bit (SSPCON1 register) is set. An MSSP interrupt is generated for each data transfer byte. The SSPIF flag bit must be cleared in software. The SSPSTAT Register is used to determine the status of the received byte. Note: The SSPBUF will be loaded if the SSPOV bit is set and the BF flag bit is cleared. If a read of the SSPBUF was performed, but the user did not clear the state of the SSPOV bit before the next receive occurred. The ACK is not sent and the SSPBUF is updated. 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-22  2000 Microchip Technology Inc. 20.4.1.3 Slave Transmission When the R/W bit of the incoming address byte is set and an address match occurs, the R/W bit of the SSPSTAT Register is set. The received address is loaded into the SSPBUF Register. The ACK pulse will be sent on the ninth bit, and the SCL pin is held low. The transmit data must be loaded into the SSPBUF Register, which also loads the SSPSR Register and sets the BF bit. Then the SCL pin should be enabled by setting the CKP bit (SSPCON1 register). The master should monitor the SCL pin prior to asserting another clock pulse. The slave devices may be holding off the master by stretching the clock. The eight data bits are shifted out on the falling edge of the SCL input. This ensures that the SDA signal is valid during the SCL high time (Figure 20-13). When all eight bits have been shifted out, the BF bit will be cleared. An MSSP interrupt is generated for each data transfer byte. The SSPIF flag bit must be cleared in software, and the SSPSTAT Register is used to determine the status of the byte transfer. The SSPIF flag bit is set on the falling edge of the ninth clock pulse. As a slave-transmitter, the ACK pulse from the master-receiver is latched on the rising edge of the ninth SCL input pulse. If the SDA line was high (not ACK), then the data transfer is complete. When the not ACK is latched by the slave, the slave logic is reset and the slave then monitors for another occurrence of the Start bit. If the SDA line was low (ACK), the transmit data must be loaded into the SSPBUF Register, which also loads the SSPSR Register and sets the BF bit. Then the SCL pin should be enabled by setting the CKP bit. Figure 20-12: I 2C Slave Mode Waveforms for Reception (7-bit Address) Figure 20-13: I2C Slave Mode Waveforms for Transmission (7-bit Address) 5 76 8 9 P D6D7 D5 D3D4 D2 D1 D0 S A7 A6 A5 A4 A3 A2 A1SDA SCL 1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9 1 23 4 Bus Master terminates transfer Bit SSPOV is set because the SSPBUF Register is still full. Cleared in software SSPBUF Register is read Receiving Data ACK Receiving Data D6D7 D5 D3D4 D2 D1 D0 ACK R/W=0 Receiving Address SSPIF BF (SSPSTAT<0>) SSPOV (SSPCON1<6>) Not ACK ACK is not sent. SDA SCL SSPIF BF (SSPSTAT<0>) CKP (SSPCON1<4>) A7 A6 A5 A4 A3 A2 A1 ACK D7 D6 D5 D4 D3 D2 D1 D0 Receiving Address R/W = 1 Transmitting Data Not ACK 123456789 1234 56789 P Cleared in software SSPBUF is written in software From MSSP interrupt service routine Set bit after writing to SSPBUF S Data in sampled SCL held low while CPU responds to SSPIF (the SSPBUF must be written-to before the CKP bit can be set) R/W = 0 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-23 Section 20. Master SSP Master SSP 20 Figure 20-14: I 2C Slave Mode Waveform (Transmission 10-bit Address) SDA SCL SSPIF BF (SSPSTAT<0>) S 123 45 6 78 9 1 2345 67 89 12 34 5 7 8 9 P 1 1 1 1 0 A9 A8 A7 A6 A5 A4 A3 A2 A1 A0 1 1 1 1 0 A8 R/W=1 ACK ACK R/W = 0 ACK Receive First Byte of Address Cleared in software Master sends NACK A96 (PIR1<3>) Receive Second Byte of Address Cleared by hardware when SSPADD is updated UA (SSPSTAT<1>) Clock is held low until update of SSPADD has taken place UA is set indicating that the SSPADD needs to be updated UA is set indicating that SSPADD needs to be updated Cleared by hardware when SSPADD is updated SSPBUF is written with contents of SSPSR Dummy read of SSPBUF to clear BF flag Receive First Byte of Address 12345 78 9 D7 D6 D5 D4 D3 D1 ACK D2 6 Transmitting Data Byte D0 Dummy read of SSPBUF to clear BF flag Sr Cleared in software Write of SSPBUF initiates transmit Cleared in software Transmit is complete clock to be released CKP has to be set for Bus Master terminates transfer 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM DS39520A-page 20-24 PIC18C Reference Manual  2000 Microchip Technology Inc. Figure 20-15: I 2C Slave Mode Waveform (Reception 10-bit Address) SDA SCL SSPIF BF (SSPSTAT<0>) S 1 234 56 7 89 1 2345 67 89 1 2345 789 P 1 1 1 1 0 A9 A8 A7 A6 A5 A4 A3 A2 A1 A0 D7 D6 D5 D4 D3 D1 D0 Receive Data Byte ACK R/W = 0 ACK Receive First Byte of Address Cleared in software Bus Master terminates transfer D2 6 (PIR1<3>) Receive Second Byte of Address Cleared by hardware when SSPADD is updated with UA (SSPSTAT<1>) Clock is held low until update of SSPADD has taken place UA is set indicating that the SSPADD needs to be updated UA is set indicating that SSPADD needs to be updated SSPBUF is written with contents of SSPSR Dummy read of SSPBUF to clear BF flag ACK R/W = 1 Cleared in software Dummy read of SSPBUF to clear BF flag Read of SSPBUF clears BF flag Cleared by hardware when SSPADD is updated with low byte of address high byte of address 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-25 Section 20. Master SSP Master SSP 20 20.4.2 General Call Address Support The addressing procedure for the I2C bus is such that the first byte after the Start condition usually determines which device will be the slave addressed by the master. The exception is the general call address, which can address all devices. When this address is used, all devices should respond with an acknowledge. The general call address is one of eight addresses reserved for specific purposes by the I2C protocol. It consists of all 0’s with R/W = 0. The general call address is recognized when the General Call Enable bit (GCEN) is set. Following a Start bit detect, 8 bits are shifted into the SSPSR and the address is compared against the SSPADD, and is also compared to the general call address, fixed in hardware. If the general call address matches, the SSPSR is transferred to the SSPBUF, the BF flag bit is set (during the eighth bit), and on the falling edge of the ninth bit (the ACK bit) the SSPIF interrupt flag bit is set. When the interrupt is serviced. The source for the interrupt can be checked by reading the contents of the SSPBUF to determine if the address was device specific or a general call address. In 10-bit address mode, SSPADD must be updated for the second half of the address to match and the UA bit to be set. If the general call address is sampled when the GCEN bit is set, then the second half of the address is not necessary. The UA bit will not be set, and the slave (configured in 10-bit address mode) will begin receiving data after the acknowledge (Figure 20-16). Figure 20-16: Slave Mode General Call Address Sequence (7 or 10-bit Address Mode) SDA SCL S SSPIF BF (SSPSTAT<0>) SSPOV (SSPCON1<6>) Cleared in software SSPBUF is read R/W = 0 ACK General Call Address Address is compared to General Call Address GCEN (SSPCON2<7>) Receiving data ACK 1 2 34 56 78 91 2 34 56 789 D7 D6 D5 D4 D3 D2 D1 D0 after ACK, set interrupt '0' '1' 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-26  2000 Microchip Technology Inc. 20.4.3 Sleep Operation While in sleep mode, the I2C module can receive addresses or data. When an address match or complete byte transfer occurs, the processor will wake-up from sleep (if the MSSP interrupt is enabled). 20.4.4 Effect of a Reset A reset disables the MSSP module and terminates the current transfer. Table 20-4: Registers Associated with I2C Operation Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other resets INTCON GIE/ GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIR SSPIF, BCLIF (1) 0, 0 0, 0 PIE SSPIE, BCLIF (1) 0, 0 0, 0 SSPADD Synchronous Serial Port (I2C mode) Address Register (Slave Mode)/Baud Rate Generator (Master Mode) 0000 0000 0000 0000 SSPBUF Synchronous Serial Port Receive Buffer/Transmit Register xxxx xxxx uuuu uuuu SSPCON1 WCOL SSPOV SSPEN CKP SSPM3 SSPM2 SSPM1 SSPM0 0000 0000 0000 0000 SSPCON2 GCEN ACKSTAT ACKDT ACKEN RCEN PEN RSEN SEN 0000 0000 0000 0000 SSPSTAT SMP CKE D/A P S R/W UA BF 0000 0000 0000 0000 Legend: x = unknown, u = unchanged, - = unimplemented read as '0'. Shaded cells are not used by the MSSP in I2C mode. Note 1: The position of these bits is device dependent. 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-27 Section 20. Master SSP Master SSP 20 20.4.5 Master Mode Master Mode of operation is supported by interrupt generation on the detection of the Start and Stop conditions. The Stop (P) and Start (S) bits are cleared when a reset occurs or when the MSSP module is disabled. Control of the I2C bus may be taken when the P bit is set, or the bus is idle with both the S and P bits clear. In Master Mode, the SCL and SDA lines are manipulated by the MSSP hardware. The following events will cause SSP Interrupt Flag bit, SSPIF, to be set (SSP Interrupt if enabled): • Start condition • Stop condition • Data transfer byte transmitted/received • Acknowledge Transmit • Repeated Start Figure 20-17: MSSP Block Diagram (I 2C Master Mode) Read Write SSPSR Start Bit, Stop Bit, Start Bit Detect SSPBUF Internal Data Bus Set/Reset, S, P, WCOL (SSPSTAT) Shift Clock MSb LSb SDA Acknowledge Generate Stop Bit Detect Write Collision Detect Clock Arbitration State Counter for End of XMIT/RCV SCL SCL In Bus Collision SDA In Receive Enable Clock Cntl Clock Arbitrate/WCOLDetect (Hold Off Clock Source) SSPADD<6:0> Baud Set SSPIF, BCLIF Reset ACKSTAT, PEN (SSPCON2) Rate Generator SSPM3:SSPM0 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-28  2000 Microchip Technology Inc. 20.4.6 Multi-Master Mode In Multi-Master Mode, the interrupt generation on the detection of the Start and Stop conditions allows the determination of when the bus is free. The Stop (P) and Start (S) bits are cleared from a reset or when the MSSP module is disabled. Control of the I2C bus may be taken when the P bit (SSPSTAT register) is set, or the bus is idle with both the S and P bits clear. When the bus is busy, enabling the MSSP Interrupt will generate the interrupt when the Stop condition occurs. In multi-master operation, the SDA line must be monitored, for arbitration, to see if the signal level is the expected output level. This check is performed in hardware, with the result placed in the BCLIF bit. The states where arbitration can be lost are: • Address transfer • Data transfer • A Start condition • A Repeated Start condition • An Acknowledge condition 20.4.7 I2C Master Mode Support Master Mode is enabled by setting and clearing the appropriate SSPM bits in SSPCON1 and by setting the SSPEN bit. Once Master Mode is enabled, the user has six options. 1. Assert a Start condition on SDA and SCL. 2. Assert a Repeated Start condition on SDA and SCL. 3. Write to the SSPBUF Register initiating transmission of data/address. 4. Generate a Stop condition on SDA and SCL. 5. Configure the I2C port to receive data. 6. Generate an acknowledge condition at the end of a received byte of data. Note: The MSSP Module when configured in I2C Master Mode does not allow queueing of events. For instance: The user is not allowed to initiate a Start condition, and immediately write the SSPBUF Register to imitate transmission before the Start condition is complete. In this case the SSPBUF will not be written to, and the WCOL bit will be set, indicating that this write to the SSPBUF did not occur. 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-29 Section 20. Master SSP Master SSP 20 20.4.7.1 I2 C Master Mode Operation The master device generates all of the serial clock pulses and the Start and Stop conditions. A transfer is ended with a Stop condition or with a Repeated Start condition. Since the Repeated Start condition is also the beginning of the next serial transfer, the I2C bus will not be released. In master transmitter mode, serial data is output through SDA, while SCL outputs the serial clock. The first byte transmitted contains the slave address of the receiving device (7 bits), and the Read/Write (R/W) bit. In this case, the R/W bit will be logic '0'. Serial data is transmitted 8 bits at a time. After each byte is transmitted, an Acknowledge bit is received. Start and Stop conditions are output to indicate the beginning and the end of a serial transfer. In master receive mode, the first byte transmitted contains the slave address of the transmitting device (7 bits), and the R/W bit. In this case, the R/W bit will be logic '1'. Thus, the first byte transmitted is a 7-bit slave address followed by a '1' to indicate receive bit. Serial data is received via the SDA pin, while the SCL pin outputs the serial clock. Serial data is received 8 bits at a time. After each byte is received, an Acknowledge bit is transmitted. Start and Stop conditions indicate the beginning and end of transmission. The baud rate generator used for SPI mode operation is now used to set the SCL clock frequency for either 100 kHz, 400 kHz, or 1 MHz I2C operation. The baud rate generator reload value is contained in the lower 7 bits of the SSPADD Register. The baud rate generator will automatically begin counting on a write to the SSPBUF. Once the given operation is complete (i.e., transmission of the last data bit is followed by ACK), the internal clock will automatically stop counting and the SCL pin will remain in its last state. A typical transmit sequence would go as follows: a) The user generates a Start condition by setting the Start enable bit, SEN (SSPCON2 register). b) SSPIF is set. The MSSP module will wait the required start time before any other operation takes place. c) The user loads the SSPBUF with the address to transmit. d) Address is shifted out the SDA pin until all 8 bits are transmitted. e) The MSSP module shifts in the ACK bit from the slave device, and writes its value into the SSPCON2 Register (SSPCON2 register). f) The MSSP module generates an interrupt at the end of the ninth clock cycle by setting the SSPIF bit. g) The user loads the SSPBUF with eight bits of data. h) DATA is shifted out the SDA pin until all 8 bits are transmitted. i) The MSSP module shifts in the ACK bit from the slave device, and writes its value into the SSPCON2 Register (SSPCON2 register). j) The MSSP module generates an interrupt at the end of the ninth clock cycle by setting the SSPIF bit. k) The user generates a Stop condition by setting the Stop enable bit, PEN (SSPCON2 register). l) Interrupt is generated once the Stop condition is complete. 39500 18C Reference Manual.book Page 29 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-30  2000 Microchip Technology Inc. 20.4.8 Baud Rate Generator In I2C Master Mode, the reload value for the BRG is located in the lower 7 bits of the SSPADD Register (Figure 20-18). When the BRG is loaded with this value, the BRG counts down to 0 and stops until another reload has taken place. The BRG count is decremented twice per instruction cycle (TCY) on the Q2 and Q4 clocks. In I2C Master Mode, the BRG is reloaded automatically. If clock arbitration is taking place for instance, the BRG will be reloaded when the SCL pin is sampled high (Figure 20-19). Figure 20-18: Baud Rate Generator Block Diagram Figure 20-19: Baud Rate Generator Timing With Clock Arbitration SSPM3:SSPM0 CLK BRG Down Counter FOSC/4 SSPADD<6:0> SSPM3:SSPM0 SCL Reload Control Reload SDA SCL SCL de-asserted, but Slave holds DX DX-1 BRG SCL is sampled high, reload takes place, and BRG starts its count 03h 02h 01h 00h (hold off) 03h 02h reload BRG value SCL low (Clock Arbitration) SCL allowed to transition high BRG decrements on Q2 and Q4 cycles 39500 18C Reference Manual.book Page 30 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-31 Section 20. Master SSP Master SSP 20 20.4.9 I2C Master Mode Start Condition Timing To initiate a Start condition, the user sets the Start condition enable bit, SEN (SSPCON2 register). If the SDA and SCL pins are sampled high, the baud rate generator is re-loaded with the contents of SSPADD<6:0>, and starts its count. If the SCL and SDA pins are both sampled high when the baud rate generator times out (TBRG), the SDA pin is driven low. The action of the SDA pin being driven low while the SCL pin is high in the Start condition, and causes the S bit (SSPSTAT register) to be set. Following this, the baud rate generator is reloaded with the contents of SSPADD<6:0> and resumes its count. When the baud rate generator times out (TBRG) the SEN bit (SSPCON2 register) will be automatically cleared by hardware, the baud rate generator is suspended leaving the SDA line held low, and the Start condition is complete. 20.4.9.1 WCOL Status Flag If the user writes the SSPBUF when an Start sequence is in progress, then WCOL is set and the contents of the buffer are unchanged (the write doesn’t occur). Figure 20-20: First Start Bit Timing Note: If at the beginning of Start condition, the SDA and SCL pins are already sampled low, or if during the Start condition the SCL pin is sampled low before the SDA pin is driven low, a bus collision occurs. The Bus Collision Interrupt Flag, BCLIF, is set, the Start condition is aborted, and the I2C module is reset into its idle state. Note: Because queueing of events is not allowed, writing to the lower 5 bits of SSPCON2 is disabled until the Start condition is complete. SDA SCL S TBRG 1st Bit 2nd Bit TBRG SDA = 1, At completion of Start Bit, SCL = 1 TBRG Write to SSPBUF occurs here hardware clears SEN Bit TBRG Write to SEN Bit occurs here Set S bit (SSPSTAT<3>) and sets SSPIF Bit 39500 18C Reference Manual.book Page 31 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-32  2000 Microchip Technology Inc. Figure 20-21: Start Condition Flowchart Idle Mode SEN (SSPCON2<0> = 1) Bus collision detected Set BCLIF Bit SDA = 1? Load BRG with Yes BRG Rollover? Force SDA = 0, Load BRG with SSPADD<6:0>, No Yes Force SCL = 0, Clear SEN bit, Set S Bit SSPADD<6:0> SCL = 1? SDA = 0? No Yes BRG rollover? No Clear SEN Bit Start condition Done, No Yes Reset BRG SCL= 0? No Yes SCL = 0? No Yes Reset BRG Release SCL Bit SSPEN = 1 SSPCON1<3:0> =1000 Set SSPIF bit 39500 18C Reference Manual.book Page 32 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-33 Section 20. Master SSP Master SSP 20 20.4.10 I2C Master Mode Repeated Start Condition Timing A Repeated Start condition occurs when the RSEN bit (SSPCON2 register) is programmed high and the I2C logic module is in the idle state. When the RSEN bit is set, the SCL pin is asserted low. When the SCL pin is sampled low, the baud rate generator is loaded with the contents of SSPADD<5:0>, and begins counting. The SDA pin is released (brought high) for one baud rate generator count (TBRG). When the baud rate generator times out, if SDA is sampled high, the SCL pin will be de-asserted (brought high). When the SCL pin is sampled high, the baud rate generator is re-loaded with the contents of SSPADD<6:0> and begins counting. SDA and SCL must be sampled high for one TBRG. This action is then followed by assertion of the SDA pin (SDA = 0) for one TBRG while SCL is high. Following this, the RSEN bit (SSPCON2 register) will be automatically cleared and the baud rate generator is not reloaded, leaving the SDA pin held low. As soon as a Start condition is detected on the SDA and SCL pins, the S bit (SSPSTAT register) will be set. The SSPIF bit will not be set until the baud rate generator has timed-out. Immediately following the SSPIF bit getting set, the user may write the SSPBUF with the 7-bit address in 7-bit mode, or the default first address in 10-bit mode. After the first eight bits are transmitted and an ACK is received, the user may then transmit an additional eight bits of address (10-bit mode) or eight bits of data (7-bit mode). Note 1: If RSEN is programmed while any other event is in progress, it will not take effect. Note 2: A bus collision during the Repeated Start condition occurs if: • SDA is sampled low when SCL goes from low to high. • SCL goes low before SDA is asserted low. This may indicate that another master is attempting to transmit a data "1". 39500 18C Reference Manual.book Page 33 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-34  2000 Microchip Technology Inc. 20.4.10.1 WCOL Status Flag If the user writes the SSPBUF when a Repeated Start sequence is in progress, then WCOL is set and the contents of the buffer are unchanged (the write doesn’t occur). Figure 20-22: Repeat Start Condition Waveform Note: Because queueing of events is not allowed, writing of the lower 5 bits of SSPCON2 is disabled until the Repeated Start condition is complete. SDA SCL Sr = Repeated Start Write to SSPCON2 Falling edge of ninth clock Write to SSPBUF occurs here End of transmit At completion of START Bit, hardware clear RSEN bit 1st Bit Set S (SSPSTAT<3>) TBRG TBRG SDA = 1, SDA = 1 SCL (no change) SCL = 1 occurs here TBRG TBRG TBRG and sets SSPIF 39500 18C Reference Manual.book Page 34 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-35 Section 20. Master SSP Master SSP 20 Figure 20-23: Repeated Start Condition Flowchart (part 1 of 2) Idle Mode, SSPEN = 1, Force SCL = 0 SCL = 0? Release SDA pin, Load BRG with SCL = 1? No Yes No Yes BRG No Yes Release SCL pin SSPCON1<3:0> = 1000 rollover? SSPADD<6:0> Load BRG with SSPADD<6:0> (Clock Arbitration) A B C SDA = 1? No Yes Start RSEN = 1 Bus Collision, Set BCLIF, Release SDA pin, Clear RSEN 39500 18C Reference Manual.book Page 35 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-36  2000 Microchip Technology Inc. Figure 20-24: Repeated Start Condition Flowchart (part 2 of 2) Force SDA = 0, Load BRG with SSPADD<6:0> Yes Repeated Start Clear RSEN, Yes BRG rollover? BRG rollover? Yes SDA = 0? No SCL = 1? No B Set S C A No No Yes Force SCL = 0, Reset BRG Set SSPIF SCL = '0'? Reset BRG No Yes condition done, 39500 18C Reference Manual.book Page 36 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-37 Section 20. Master SSP Master SSP 20 20.4.11 I2C Master Mode Transmission Transmission of a data byte, a 7-bit address, or the other half of a 10-bit address is accomplished by simply writing a value to SSPBUF Register. This action will set the buffer full flag bit, BF, and allow the baud rate generator to begin counting and start the next transmission. Each bit of address/data will be shifted out onto the SDA pin after the falling edge of SCL is asserted (see data hold time specification parameter 106 in the “Electrical Specifications” section). SCL is held low for one baud rate generator roll over count (TBRG). Data should be valid before SCL is released high (see data setup time specification parameter 107 in the “Electrical Specifications” section). When the SCL pin is released high, it is held that way for TBRG, the data on the SDA pin must remain stable for that duration and some hold time after the next falling edge of SCL. After the eighth bit is shifted out (the falling edge of the eighth clock), the BF bit is cleared and the master releases the SDA pin. This allows the slave device being addressed to respond with an ACK bit during the ninth bit time, if an address match occurs or if data was received properly. The status of ACK is written into the ACKDT bit on the falling edge of the ninth clock. If the master receives an acknowledge, the acknowledge status bit, ACKSTAT, is cleared. If not, the bit is set. After the ninth clock, the SSPIF bit is set and the master clock (baud rate generator) is suspended until the next data byte is loaded into the SSPBUF, leaving the SCL pin low and the SDA pin unchanged (Figure 20-26). After the write to the SSPBUF, each bit of address will be shifted out on the falling edge of SCL until all seven address bits and the R/W bit are completed. On the falling edge of the eighth clock, the master will de-assert the SDA pin allowing the slave to respond with an acknowledge. On the falling edge of the ninth clock, the master will sample the SDA pin to see if the address was recognized by a slave. The status of the ACK bit is loaded into the ACKSTAT status bit (SSPCON2 register). Following the falling edge of the ninth clock transmission of the address, the SSPIF is set, the BF flag is cleared, and the baud rate generator is turned off until another write to the SSPBUF takes place, holding SCL low and allowing SDA to float. 20.4.11.1 BF Status Flag In transmit mode, the BF bit (SSPSTAT register) is set when the CPU writes to SSPBUF and is cleared when all 8 bits are shifted out. 20.4.11.2 WCOL Status Flag If the user writes the SSPBUF when a transmit is already in progress (i.e. SSPSR is still shifting out a data byte), then WCOL is set and the contents of the buffer are unchanged (the write doesn’t occur). WCOL must be cleared in software. 20.4.11.3 ACKSTAT Status Flag In transmit mode, the ACKSTAT bit (SSPCON2 register) is cleared when the slave has sent an acknowledge (ACK = 0), and is set when the slave does not acknowledge (ACK = 1). A slave sends an acknowledge when it has recognized its address (including a general call), or when the slave has properly received its data. 39500 18C Reference Manual.book Page 37 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-38  2000 Microchip Technology Inc. Figure 20-25: Master Transmit Flowchart Idle Mode Num_Clocks = 0, Release SDA so Num_Clocks slave can drive ACK, Load BRG with SDA = Current Data bit Yes BRG rollover? BRG No No Yes Force SCL = 0 = 8? Yes No Yes BRG rollover? No Force SCL = 1, Stop BRG SCL = 1? Load BRG with count high time Rollover? No Read SDA and place into ACKSTAT bit (SSPCON2<6>) Force SCL = 0, SCL = 1? SDA = Data bit? No Yes Yes rollover? No Yes Stop BRG, Force SCL = 1 (Clock Arbitration) (Clock Arbitration) Num_Clocks = Num_Clocks + 1 Bus collision detected Set BCLIF, hold prescale off, Yes No BF = 1 Force BF = 0 SSPADD<6:0>, start BRG count, Load BRG with SSPADD<6:0>, start BRG count SSPADD<6:0>, Load BRG with count SCL high time SSPADD<6:0>, SDA = Data bit? Yes No Clear Transmit enable SCL = 0? No Yes Reset BRG Write SSPBUF Set SSPIF 39500 18C Reference Manual.book Page 38 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-39 Section 20. Master SSP Master SSP 20 Figure 20-26: I2C Master Mode Waveform (Transmission, 7 or 10-bit Address) SDA SCL SSPIF BF (SSPSTAT<0>) SEN A7 A6 A5 A4 A3 A2 A1 ACK = 0 D7 D6 D5 D4 D3 D2 D1 D0 ACK Transmitting data or second half Transmit Address to Slave R/W = 0 123456789 123456789 P Cleared in software service routine SSPBUF is written in software From SSP interrupt After Start condition, SEN bit cleared by hardware S SSPBUF written with 7-bit address and R/W. Start transmit SCL held low while CPU responds to SSPIF SEN = 0 of 10-bit address Write SSPCON2<0> SEN = 1 Start condition begins From Slave, clear ACKSTAT bit SSPCON2<6> ACKSTAT in SSPCON2 = 1 Cleared in software SSPBUF written PEN Cleared in software R/W 39500 18C Reference Manual.book Page 39 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-40  2000 Microchip Technology Inc. 20.4.12 I2C Master Mode Reception Master Mode reception is enabled by programming the receive enable bit, RCEN (SSPCON2 register). The baud rate generator begins counting, and on each rollover, the state of the SCL pin changes (high to low/low to high) and data is shifted into the SSPSR. After the falling edge of the eighth clock, the receive enable flag is automatically cleared, the contents of the SSPSR are loaded into the SSPBUF, the BF flag bit is set, the SSPIF flag bit is set, and the baud rate generator is suspended from counting, holding SCL low. The MSSP is now in idle state, awaiting the next command. When the buffer is read by the CPU, the BF flag bit is automatically cleared. The user can then send an acknowledge bit at the end of reception by setting the acknowledge sequence enable bit, ACKEN (SSPCON2 register). 20.4.12.1 BF Status Flag In receive mode, the BF bit is set when an address or data byte is loaded into SSPBUF from SSPSR. It is cleared when the SSPBUF Register is read. 20.4.12.2 SSPOV Status Flag In receive mode, the SSPOV bit is set when 8 bits are received into the SSPSR, and the BF flag bit is already set from a previous reception. 20.4.12.3 WCOL Status Flag If the user writes the SSPBUF when a receive is already in progress (i.e., SSPSR is still shifting in a data byte), then the WCOL bit is set and the contents of the buffer are unchanged (the write doesn’t occur). Note: The MSSP module must be in an idle state before the RCEN bit is set, or the RCEN bit will be disregarded. 39500 18C Reference Manual.book Page 40 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-41 Section 20. Master SSP Master SSP 20 Figure 20-27: Master Receiver Flowchart Idle Mode Num_Clocks = 0, Release SDA Force SCL=0, Yes BRG No rollover? Release SCL Yes No SCL = 1? Load BRG with Yes BRG No rollover? (Clock Arbitration) Load BRG w/ start count SSPADD<6:0>, start count Sample SDA pin, Shift data into SSPSR Num_Clocks = Num_Clocks + 1 Yes Num_Clocks = 8? No Force SCL = 0, Set SSPIF bit, Set BF bit. Move contents of SSPSR into SSPBUF, Clear RCEN RCEN = 1 SSPADD<6:0>, SCL = 0? Yes No 39500 18C Reference Manual.book Page 41 Monday, July 10, 2000 6:12 PM DS39520A-page 20-42 PIC18C Reference Manual  2000 Microchip Technology Inc. Figure 20-28: I2C Master Mode Waveform (Reception 7-Bit Address) P 5 6 7 8 9 D7 D6 D5 D4 D3 D2 D1 D0 S SDA A7 A6 A5 A4 A3 A2 A1 SCL 1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9 1234 Bus Master terminates transfer ACK Receiving Data from Slave Receiving Data from Slave ACK D7 D6 D5 D4 D3 D2 D1 D0 R/W = 1 Transmit Address to Slave SSPIF BF ACK is not sent Write to SSPCON2<0> (SEN = 1) Write to SSPBUF occurs here ACK from Slave Master configured as a receiver SSPCON2<3>, (RCEN = 1) PEN bit = 1 written here Data shifted in on falling edge Cleared in software Start transmit SEN = 0 SSPOV SDA = 0, SCL = 1 (SSPSTAT<0>) ACK Last bit is shifted into SSPSR and contents are unloaded into SSPBUF Cleared in software Cleared in software Set SSPIF interrupt at end of receive Set P bit (SSPSTAT<4>) and SSPIF Cleared in software ACK from Master Set SSPIF at end Set SSPIF interrupt at end of acknowledge sequence Set SSPIF interrupt at end of acknowledge sequence of receive Set ACKEN, start acknowledge sequence SSPOV is set because SSPBUF is still full SDA = ACKDT = 1 RCEN cleared automatically RCEN = 1 start next receive Write to SSPCON2<4> to start acknowledge sequence SDA = ACKDT (SSPCON2<5>) = 0 RCEN cleared automatically responds to SSPIF ACKEN Begin Start condition Cleared in software SDA = ACKDT = 0 by programming of CLK while CPU 39500 18C Reference Manual.book Page 42 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-43 Section 20. Master SSP Master SSP 20 20.4.13 Acknowledge Sequence Timing An acknowledge sequence is enabled by setting the acknowledge sequence enable bit, ACKEN (SSPCON2 register). When this bit is set, the SCL pin is pulled low and the contents of the acknowledge data bit is presented on the SDA pin. If the user wishes to generate an acknowledge, then the ACKDT bit should be cleared. If not, the user should set the ACKDT bit before starting an acknowledge sequence. The baud rate generator then counts for one rollover period (TBRG), and the SCL pin is de-asserted (pulled high). When the SCL pin is sampled high (clock arbitration), the baud rate generator counts for TBRG. The SCL pin is then pulled low. Following this, the ACKEN bit is automatically cleared, the baud rate generator is turned off, and the MSSP module then goes into idle mode (Figure 20-29). 20.4.13.1 WCOL Status Flag If the user writes the SSPBUF when an acknowledge sequence is in progress, then WCOL is set and the contents of the buffer are unchanged (the write doesn’t occur). Figure 20-29: Acknowledge Sequence Waveform SDA SCL Set SSPIF at the end Acknowledge sequence starts here, Write to SSPCON2 ACKEN bit automatically cleared Cleared in TBRG TBRG of receive ACK 8 ACKEN = 1, ACKDT = 0 D0 9 SSPIF software Set SSPIF at the end of acknowledge sequence Cleared in software Note: TBRG = one baud rate generator period. 39500 18C Reference Manual.book Page 43 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-44  2000 Microchip Technology Inc. Figure 20-30: Acknowledge Flowchart Idle Mode Force SCL = 0 Yes No SCL = 0? Drive ACKDT bit Yes No BRG rollover? (SSPCON2<5>) onto SDA pin, Load BRG with SSPADD<6:0>, start count Force SCL = 1 Yes No SCL = 1? No ACKDT = 1? Load BRG with No BRG rollover? SSPADD <6:0>, start count No SDA = 1? Bus collision detected, Set BCLIF, Yes Force SCL = 0, (Clock Arbitration) Clear ACKEN No SCL = 0? Reset BRG Clear ACKEN Set ACKEN Release SCL, Yes Yes Yes Set SSPIF 39500 18C Reference Manual.book Page 44 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-45 Section 20. Master SSP Master SSP 20 20.4.14 Stop Condition Timing A Stop bit is asserted on the SDA pin at the end of a receive/transmit by setting the Stop sequence enable bit, PEN (SSPCON2 register). At the end of a receive/transmit, the SCL pin is held low after the falling edge of the ninth clock. When the PEN bit is set, the master will assert the SDA line low. When the SDA line is sampled low, the baud rate generator is reloaded and counts down to 0. When the baud rate generator times out, the SCL pin will be brought high, and one TBRG (baud rate generator rollover count) later, the SDA pin will be de-asserted. When the SDA pin is sampled high while the SCL pin is high, the P bit (SSPSTAT register) is set. A TBRG later, the PEN bit is cleared and the SSPIF bit is set (Figure 20-31). Whenever the firmware decides to take control of the bus, it will first determine if the bus is busy by checking the S and P bits in the SSPSTAT Register. If the bus is busy, then the CPU can be interrupted (notified) when a Stop bit is detected (i.e., bus is free). 20.4.14.1 WCOL Status Flag If the user writes the SSPBUF when a Stop sequence is in progress, then the WCOL bit is set and the contents of the buffer are unchanged (the write doesn’t occur). Figure 20-31: Stop Condition Receive or Transmit Mode SCL SDA SDA asserted low before rising edge of clock Write to SSPCON2 Set PEN Falling edge of SCL = 1 for TBRG, followed by SDA = 1 for TBRG 9th clock SCL brought high after TBRG TBRG TBRG after SDA sampled high. P bit (SSPSTAT<4>) is set TBRG to setup STOP condition. ACK P TBRG PEN bit (SSPCON2<2>) is cleared by hardware and the SSPIF bit is set Note: TBRG = one baud rate generator period. 39500 18C Reference Manual.book Page 45 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-46  2000 Microchip Technology Inc. Figure 20-32: Stop Condition Flowchart Idle Mode, SSPEN = 1, Force SDA = 0 SCL doesn’t change SDA = 0? De-assert SCL, SCL = 1 SCL = 1? No Yes Start BRG No Yes BRG SDA going from 0 to 1 while SCL = 1, No Yes Set SSPIF, Release SDA, Start BRG Stop condition done SSPCON1<3:0>=1000 rollover? BRG No rollover? Yes P bit set? No Yes Bus Collision detected, Set BCLIF, Clear PEN Start BRG No Yes BRG rollover? (Clock Arbitration) PEN = 1 PEN cleared 39500 18C Reference Manual.book Page 46 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-47 Section 20. Master SSP Master SSP 20 20.4.15 Clock Arbitration Clock arbitration occurs when the master, during any receive, transmit, or Repeated Start/Stop condition de-asserts the SCL pin (SCL allowed to float high). When the SCL pin is allowed to float high, the baud rate generator (BRG) is suspended from counting until the SCL pin is actually sampled high. When the SCL pin is sampled high, the baud rate generator is reloaded with the contents of SSPADD<6:0> and begins counting. This ensures that the SCL high time will always be at least one BRG rollover count in the event that the clock is held low by an external device (Figure 20-33). Figure 20-33: Clock Arbitration Timing in Master Transmit Mode 20.4.15.1 Sleep Operation While in sleep mode, the I2C module can receive addresses or data. When an address match or complete byte transfer occurs, the processor will wake-up from sleep (if the MSSP interrupt is enabled). 20.4.15.2 Effect of a Reset A reset disables the MSSP module and terminates the current transfer. SCL SDA BRG overflow, Release the SCL pin, If SCL = 1 Load BRG with SSPADD<6:0>, and start count BRG overflow occurs, Release SCL, slave device holds the SCL pin low. SCL = 1 BRG starts counting clock high interval. SCL line sampled once every machine cycle (TOSC • 4). Hold off BRG until SCL is sampled high TBRG TBRG TBRG to measure high time interval 39500 18C Reference Manual.book Page 47 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-48  2000 Microchip Technology Inc. 20.4.16 Multi-Master Communication, Bus Collision, and Bus Arbitration Multi-Master Mode support is achieved by bus arbitration. When the master outputs address/data bits onto the SDA pin, arbitration takes place when the master outputs a '1' on SDA by letting SDA float high and another master asserts a '0'. When the SCL pin floats high, data should be stable. If the expected data on SDA is a '1' and the data sampled on the SDA pin = '0', then a bus collision has taken place. The master will set the Bus Collision Interrupt Flag, BCLIF and reset the I2C port to its idle state. (Figure 20-34). If a transmit was in progress when the bus collision occurred, the transmission is halted, the BF flag is cleared, the SDA and SCL pins are de-asserted, and the SSPBUF can be written to. When the user services the bus collision interrupt service routine, and if the I2C bus is free, the user can resume communication by asserting a Start condition. If a Start, Repeated Start, Stop, or Acknowledge condition was in progress when the bus collision occurred, the condition is aborted, the SDA and SCL lines are de-asserted, and the respective control bits in the SSPCON2 Register are cleared. When the user services the bus collision interrupt service routine, and if the I2C bus is free, the user can resume communication by asserting a Start condition. The Master will continue to monitor the SDA and SCL pins, and if a Stop condition occurs, the SSPIF bit will be set. A write to the SSPBUF will start the transmission of data at the first data bit, regardless of where the transmitter left off when bus collision occurred. In multi-Master Mode, the interrupt generation on the detection of Start and Stop conditions allows the determination of when the bus is free. Control of the I2C bus can be taken when the P bit is set in the SSPSTAT Register, or the bus is idle and the S and P bits are cleared. Figure 20-34: Bus Collision Timing for Transmit and Acknowledge SDA SCL BCLIF SDA released SDA line pulled low by another source data doesn’t match what is driven Bus collision has occurred Set bus collision interrupt (BCLIF) by the Master. by Master Data changes while SCL = 0 While the SCL pin is high 39500 18C Reference Manual.book Page 48 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-49 Section 20. Master SSP Master SSP 20 20.4.16.1 Bus Collision During a Start Condition During a Start condition, a bus collision occurs if: a) SDA or SCL pins are sampled low at the beginning of the Start condition (Figure 20-35). b) SCL pins are sampled low before the SDA pin is asserted low (Figure 20-36). During a Start condition both the SDA and the SCL pins are monitored. If one of the following conditions exists: • the SDA pin is already low • or the SCL pin is already low, Then, the following actions occur: • the Start condition is aborted, • the BCLIF bit is set, • the MSSP module is reset to its idle state (Figure 20-35). The Start condition begins with the SDA and SCL pins de-asserted. When the SDA pin is sampled high, the baud rate generator is loaded from SSPADD<6:0> and counts down to O. If the SCL pin is sampled low while SDA is high, a bus collision occurs, because it is assumed that another master is attempting to drive a data '1' during the Start condition. If the SDA pin is sampled low during this count, the BRG is reset and the SDA line is asserted early (Figure 20-37). If however a '1' is sampled on the SDA pin, the SDA pin is asserted low at the end of the BRG count. The baud rate generator is then reloaded and counts down to O. During this time, if the SCL pins is sampled as '0', a bus collision does not occur. At the end of the BRG count the SCL pin is asserted low. Figure 20-35: Bus Collision During Start Condition (SDA only) Note: The reason that bus collision is not a factor during a Start condition is that no two bus masters can assert a Start condition at the exact same time. Therefore, one master will always assert SDA before the other. This condition does not cause a bus collision because the two masters must be allowed to arbitrate the first address following the Start condition, and if the address is the same, arbitration must be allowed to continue into the data portion, Repeated Start, or Stop conditions. SDA SCL SEN SDA sampled low before SDA goes low before the SEN bit is set. S bit and SSPIF set because SDA = 0, SCL = 1 SSP module reset into idle state SEN cleared automatically because of bus collision. S bit and SSPIF set because Set SEN, enable Start condition if SDA = 1, SCL=1 BCLIF S SSPIF SDA = 0, SCL = 1 SSPIF and BCLIF are cleared in software SSPIF and BCLIF are cleared in software Set BCLIF, START condition; Set BCLIF 39500 18C Reference Manual.book Page 49 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-50  2000 Microchip Technology Inc. Figure 20-36: Bus Collision During Start Condition (SCL = 0) Figure 20-37: BRG Reset Due to SDA Arbitration During Start Condition SDA SCL SEN Bus collision occurs, Set BCLIF SCL = 0 before SDA = 0, Set SEN, enable start sequence if SDA = 1, SCL = 1 TBRG TBRG SDA = 0, SCL = 1 BCLIF S SSPIF Interrupt cleared in software Bus collision occurs, Set BCLIF SCL = 0 before BRG time out, '0' '0' '0' '0' SDA SCL SEN Set S Set SEN, enable START sequence if SDA = 1, SCL = 1 Less than TBRG TBRG SDA = 0, SCL = 1 BCLIF S SSPIF s Interrupts cleared Set SSPIF in software SDA = 0, SCL = 1 SDA pulled low by other Master. Reset BRG and assert SDA SCL pulled low after BRG Timeout Set SSPIF '0' 39500 18C Reference Manual.book Page 50 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-51 Section 20. Master SSP Master SSP 20 20.4.16.2 Bus Collision During a Repeated Start Condition During a Repeated Start condition, a bus collision occurs if: a) A low level is sampled on SDA when SCL goes from low level to high level. b) SCL goes low before SDA is asserted low, indicating that another master is attempting to transmit a data ’1’. When the user de-asserts SDA and the pin is allowed to float high, the BRG is loaded with SSPADD<6:0> and counts down to 0. The SCL pin is then de-asserted, and when sampled high, the SDA pin is sampled. If SDA is low, a bus collision has occurred (i.e., another master, is attempting to transmit a data ’0’). If the SDA pin is sampled high, then the BRG is reloaded and begins counting. If the SDA pin goes from high to low before the BRG times out, no bus collision occurs because no two masters can assert SDA at exactly the same time, (Figure 20-38). If the SCL pin goes from high to low before the BRG times out and the SDA pin has not already been asserted, then a bus collision occurs. In this case, another master is attempting to transmit a data ’1’ during the Repeated Start condition, (Figure 20-39). If at the end of the BRG time-out, both the SCL and SDA pins are still high, the SDA pin is driven low and the BRG is reloaded and begins counting. At the end of the count, regardless of the status of the SCL pin, the SCL pin is driven low and the Repeated Start condition is complete. Figure 20-38: Bus Collision During a Repeated Start Condition (Case 1) Figure 20-39: Bus Collision During Repeated Start Condition (Case 2) SDA SCL RSEN BCLIF S SSPIF Sample SDA when SCL goes high. If SDA = 0, set BCLIF and release SDA and SCL Cleared in software '0' '0' SDA SCL BCLIF RSEN S SSPIF Interrupt cleared in software SCL pin goes low before SDA pin, Set BCLIF, Release SDA and SCL pins TBRG TBRG '0' 39500 18C Reference Manual.book Page 51 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-52  2000 Microchip Technology Inc. 20.4.16.3 Bus Collision During a Stop Condition Bus collision occurs during a Stop condition if: a) After the SDA pin has been de-asserted and allowed to float high, SDA is sampled low after the BRG has timed out. b) After the SCL pin is de-asserted, SCL is sampled low before SDA goes high. The Stop condition begins with SDA asserted low. When SDA is sampled low, the SCL pin is allow to float. When the pin is sampled high (clock arbitration), the baud rate generator is loaded with SSPADD<6:0> and counts down to 0. After the BRG times out, SDA is sampled. If SDA is sampled low, a bus collision has occurred. This is due to another master attempting to drive a data '0' (Figure 20-40). If the SCL pin is sampled low before SDA is allowed to float high, a bus collision occurs. This is another case of another master attempting to drive a data '0' (Figure 20-41). Figure 20-40: Bus Collision During a Stop Condition (Case 1) Figure 20-41: Bus Collision During a Stop Condition (Case 2) SDA SCL BCLIF PEN P SSPIF TBRG TBRG TBRG SDA asserted low SDA sampled low after TBRG, Set BCLIF '0' '0' SDA SCL BCLIF PEN P SSPIF TBRG TBRG TBRG Assert SDA SCL goes low before SDA goes high Set BCLIF '0' '0' 39500 18C Reference Manual.book Page 52 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-53 Section 20. Master SSP Master SSP 20 20.4.17 Connection Considerations for I2C Bus For standard-mode I2C bus devices, the values of resistors Rp and Rs in Figure 20-42 depend on the following parameters: • Supply voltage • Bus capacitance • Number of connected devices (input current + leakage current) The supply voltage limits the minimum value of resistor Rp due to the specified minimum sink current of 3 mA at VOLMAX = 0.4V for the specified output stages. For example, with a supply voltage of VDD = 5V+10% and VOLMAX = 0.4V at 3 mA, RPMIN = (5.5-0.4)/0.003 = 1.7 kΩ. VDD as a function of Rp is shown in Figure 20-42. The desired noise margin of 0.1VDD for the low level. This limits the maximum value of Rs. Series resistors are optional, and used to improve ESD susceptibility. The bus capacitance is the total capacitance of wire, connections, and pins. This capacitance limits the maximum value of Rp due to the specified rise time (Figure 20-42). The SMP bit is the slew rate control enabled bit. This bit is in the SSPSTAT Register, and controls the slew rate of the I/O pins when in I2C mode (master or slave). Figure 20-42: Sample Device Configuration for I2C Bus RP RP VDD + 10% SDA SCL DEVICE CB = 10 - 400 pF RS RS Note: I 2C devices with input levels related to VDD must have one common supply line to which the pull up resistor is also connected. 39500 18C Reference Manual.book Page 53 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-54  2000 Microchip Technology Inc. 20.4.18 Initialization Example 20-2: SPI Master Mode Initialization 20.4.19 Master SSP Module / Basic SSP Module Compatibility When changing from the SPI in the Mid-range Family Basic SSP module, the SSPSTAT Register contains two additional control bits. These bits are: • SMP, SPI data input sample phase • CKE, SPI Clock Edge Select To be compatible with the SPI of the Master SSP module, these bits must be appropriately configured. If these bits are not at the states shown in Table 20-5, improper SPI communication may occur. Table 20-5: New bit States for Compatibility CLRF STATUS ; Bank 0 CLRF SSPSTAT ; SMP = 0, CKE = 0, and ; clear status bits BSF SSPSTAT, CKE ; CKE = 1 MOVLW 0x31 ; Set up SPI port, Master Mode, CLK/16, MOVWF SSPCON ; Data xmit on falling edge ; (CKE=1 & CKP=1) ; Data sampled in middle ; (SMP=0 & Master Mode) BSF PIE, SSPIE ; Enable SSP interrupt BSF INTCON, GIE ; Enable, enabled interrupts MOVLW DataByte ; Data to be Transmitted ; Could move data from RAM location MOVWF SSPBUF ; Start Transmission Basic SSP Module Master SSP Module CKP CKP CKE SMP 1 100 0 000 39500 18C Reference Manual.book Page 54 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-55 Section 20. Master SSP Master SSP 20 20.5 Design Tips Question 1: Using SPI mode, I do not seem able to talk to an SPI device. Answer 1: Ensure that you are using the correct SPI mode for that device. This SPI supports all 4 SPI modes so you should be able to get it to function. Check the clock polarity and the clock phase. Question 2: Using I2C mode, I write data to the SSPBUF Register, but the data did not transmit. Answer 2: Ensure that you set the CKP bit to release the I2C clock. 39500 18C Reference Manual.book Page 55 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-56  2000 Microchip Technology Inc. 20.6 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Baseline, the Midrange, or High-end families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the Master SSP modules are: Title Application Note # Use of the SSP Module in the I 2C Multi-Master Environment. AN578 Using Microchip 93 Series Serial EEPROMs with Microcontroller SPI Ports AN613 Interfacing PIC16C64/74 to Microchip SPI Serial EEPROM AN647 Interfacing a Microchip PIC16C92x to Microchip SPI Serial EEPROM AN668 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 56 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39520A-page 20-57 Section 20. Master SSP Master SSP 20 20.7 Revision History Revision A This is the initial released revision of the Enhanced MCU Master SSP module description. 39500 18C Reference Manual.book Page 57 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39520A-page 20-58  2000 Microchip Technology Inc. 39500 18C Reference Manual.book Page 58 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-1 Addressable USART 21 Section 21. Addressable USART HIGHLIGHTS This section of the manual contains the following major topics: 21.1 Introduction .................................................................................................................. 21-2 21.2 Control Registers ......................................................................................................... 21-3 21.3 USART Baud Rate Generator (BRG)........................................................................... 21-5 21.4 USART Asynchronous Mode ....................................................................................... 21-9 21.5 USART Synchronous Master Mode........................................................................... 21-18 21.6 USART Synchronous Slave Mode ............................................................................. 21-23 21.7 Initialization ................................................................................................................ 21-25 21.8 Design Tips ................................................................................................................ 21-26 21.9 Related Application Notes.......................................................................................... 21-27 21.10 Revision History ......................................................................................................... 21-28 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-2  2000 Microchip Technology Inc. 21.1 Introduction The Addressable Universal Synchronous Asynchronous Receiver Transmitter (Addressable USART) module is one of the serial I/O modules available in the PIC18CXXX family (another is the MSSP module). The Addressable USART can be configured as a full duplex asynchronous system that can communicate with peripheral devices, such as CRT terminals and personal computers, or it can be configured as a half duplex synchronous system that can communicate with peripheral devices, such as A/D or D/A integrated circuits, Serial EEPROMs, etc. The Addressable USART can be configured in the following modes: • Asynchronous (full duplex) • Synchronous - Master (half duplex) • Synchronous - Slave (half duplex) The SPEN bit (RCSTA register) and the TRIS bits, for the USART’s pins, need to be set in order to configure the TX/CK and RX/DT pins for the Addressable USART. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-3 Section 21. Addressable USART Addressable USART 21 21.2 Control Registers Register 21-1: TXSTA: Transmit Status and Control Register R/W-0 R/W-0 R/W-0 R/W-0 U-0 R/W-0 R-1 R/W-0 CSRC TX9 TXEN SYNC — BRGH TRMT TX9D bit 7 bit 0 bit 7 CSRC: Clock Source Select bit When SYNC = 0 (Asynchronous mode) Don’t care When SYNC = 1 (Synchronous mode) 1 = Master mode (Clock generated internally from BRG) 0 = Slave mode (Clock from external source) bit 6 TX9: 9-bit Transmit Enable bit 1 = Selects 9-bit transmission 0 = Selects 8-bit transmission bit 5 TXEN: Transmit Enable bit 1 = Transmit enabled 0 = Transmit disabled Note: The Receive Enable (SREN/CREN) bit overrides Transmit Enable (TXEN) bit in SYNC mode. bit 4 SYNC: Addressable USART Mode Select bit 1 = Synchronous mode 0 = Asynchronous mode bit 3 Unimplemented: Read as '0' bit 2 BRGH: High Baud Rate Select bit When SYNC = 0 (Asynchronous mode) 1 = High speed 0 = Low speed When SYNC = 1 (Synchronous mode) Unused in this mode bit 1 TRMT: Transmit Shift Register Status bit 1 = TSR empty 0 = TSR full bit 0 TX9D: 9th bit of transmit data. This bit can be used as an address/data bit or a parity bit. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-4  2000 Microchip Technology Inc. Register 21-2: RCSTA: Receive Status and Control Register R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R-0 R-0 R-x SPEN RX9 SREN CREN ADDEN FERR OERR RX9D bit 7 bit 0 bit 7 SPEN: Serial Port Enable bit 1 = Serial port enabled (Configures RX/DT and TX/CK pins as serial port pins) 0 = Serial port disabled bit 6 RX9: 9-bit Receive Enable bit 1 = Selects 9-bit reception 0 = Selects 8-bit reception bit 5 SREN: Single Receive Enable bit When SYNC = 0 (Asynchronous mode) Don’t care When SYNC = 1 (Synchronous mode) - master 1 = Enables single receive 0 = Disables single receive This bit is cleared after reception of one byte is complete. When SYNC = 1 (Synchronous mode) - slave Unused in this mode bit 4 CREN: Continuous Receive Enable bit When SYNC = 0 (Asynchronous mode) 1 = Enables continuous receive 0 = Disables continuous receive When SYNC = 1 (Synchronous mode) 1 = Enables continuous receive (CREN overrides SREN) 0 = Disables continuous receive bit 3 ADDEN: Address Detect Enable bit When SYNC = 0 (Asynchronous mode) with RX9 = 1 (9-bit receive enabled) 1 = Enables address detection, enable interrupt and loads of the receive buffer when RSR<8> is set 0 = Disables address detection, all bytes are received, and ninth bit can be used as parity bit When SYNC = 0 (Asynchronous mode) with RX9 = 0 (9-bit receive disabled) Don’t care When SYNC = 1 (Synchronous mode) Don’t care bit 2 FERR: Framing Error bit 1 = Framing error (Can be updated by reading RCREG register and receive next valid byte) 0 = No framing error bit 1 OERR: Overrun Error bit 1 = Overrun error (Can be cleared by clearing bit CREN) 0 = No overrun error bit 0 RX9D: 9th bit of received data. Can be address/data bit or a parity bit. 1 = Ninth received bit was ’1’ 0 = Ninth received bit was ’0’ Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-5 Section 21. Addressable USART Addressable USART 21 21.3 USART Baud Rate Generator (BRG) The BRG supports both the Asynchronous and Synchronous modes of the USART. It is a dedicated 8-bit baud rate generator. The SPBRG register controls the period of a free running 8-bit timer. In Asynchronous mode, the BRGH bit (TXSTA<2>) also controls the baud rate. In Synchronous mode, the BRGH bit is ignored. Table 21-1 shows the formula for computation of the baud rate for different USART modes that only apply in master mode (internal clock). Given the desired baud rate and FOSC, the nearest integer value for the SPBRG register can be calculated using the formula in Table 21-1, where X equals the value in the SPBRG register (0 to 255). From this, the error in baud rate can be determined. Table 21-1: Baud Rate Formula Example 21-1 shows the calculation of the baud rate error for the following conditions: FOSC = 16 MHz Desired Baud Rate = 9600 BRGH = 0 SYNC = 0 Example 21-1:Calculating Baud Rate Error It may be advantageous to use the high baud rate (BRGH = 1) even for slower baud clocks. This is because the FOSC / (16(X + 1)) equation can reduce the baud rate error in some cases. Writing a new value to the SPBRG register causes the BRG timer to be reset (or cleared). This ensures the BRG does not wait for a timer overflow before outputting the new baud rate. 21.3.1 SAMPLING The data on the RX/DT pin is sampled three times by a majority detect circuit to determine if a high or a low level is present at the RX pin. See Section 21.4.4 for additional information. Table 21-2: Registers Associated with Baud Rate Generator SYNC BRGH = 0 (Low Speed) BRGH = 1 (High Speed) 0 1 (Asynchronous) Baud Rate = FOSC/(64(X+1)) (Synchronous) Baud Rate = FOSC/(4(X+1)) Baud Rate = FOSC/(16(X+1)) NA X = value in SPBRG (0 to 255) Desired Baud Rate = FOSC / (64 (X + 1)) Solving for X: X = ( (FOSC / Desired Baud Rate) / 64 ) - 1 X = ((16000000 / 9600) / 64) - 1 X = [25.042] = 25 Calculated Baud Rate = 16000000 / (64 (25 + 1)) = 9615 Error = (Calculated Baud Rate - Desired Baud Rate) Desired Baud Rate = (9615 - 9600) / 9600 = 0.16% Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other resets TXSTA CSRC TX9 TXEN SYNC — BRGH TRMT TX9D 0000 -010 0000 -010 RCSTA SPEN RX9 SREN CREN ADDEN FERR OERR RX9D 0000 0000x 0000 000x SPBRG Baud Rate Generator Register 0000 0000 0000 0000 Legend: x = unknown, - = unimplemented read as '0'. Shaded cells are not used by the BRG. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-6  2000 Microchip Technology Inc. Table 21-3: Baud Rates for Synchronous Mode BAUD RATE (Kbps) FOSC = 40 MHz SPBRG value (decimal) 33 MHz SPBRG value (decimal) 25 MHz SPBRG value (decimal) 20 MHz SPBRG value (decimal) KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR 0.3 NA - - NA - - NA - - NA - - 1.2 NA - - NA - - NA - - NA - - 2.4 NA - - NA - - NA - - NA - - 9.6 NA - - NA - - NA - - NA - - 19.2 NA - - NA - - NA - - NA - - 76.8 76.92 +0.16 129 77.10 +0.39 106 77.16 +0.47 80 76.92 +0.16 64 96 96.15 +0.16 103 95.93 -0.07 85 96.15 +0.16 64 96.15 +0.16 51 300 303.03 +1.01 32 294.64 -1.79 27 297.62 -0.79 20 294.12 -1.96 16 500 500 0 19 485.30 -2.94 16 480.77 -3.85 12 500 0 9 HIGH 10000 - 0 8250 - 0 6250 - 0 5000 - 0 LOW 39.06 - 255 32.23 - 255 24.41 - 255 19.53 - 255 BAUD RATE (Kbps) FOSC = 16 MHz SPBRG value (decimal) 10 MHz SPBRG value (decimal) 7.15909 MHz SPBRG value (decimal) 5.0688 MHz SPBRG value (decimal) KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR 0.3 NA - - NA - - NA - - NA - - 1.2 NA - - NA - - NA - - NA - - 2.4 NA - - NA - - NA - - NA - - 9.6 NA - - NA - - 9.62 +0.23 185 9.60 0 131 19.2 19.23 +0.16 207 19.23 +0.16 129 19.24 +0.23 92 19.20 0 65 76.8 76.92 +0.16 51 75.76 -1.36 32 77.82 +1.32 22 74.54 -2.94 16 96 95.24 -0.79 41 96.15 +0.16 25 94.20 -1.88 18 97.48 +1.54 12 300 307.70 +2.56 12 312.50 +4.17 7 298.35 -0.57 5 316.80 +5.60 3 500 500 0 7 500 0 4 447.44 -10.51 3 422.40 -15.52 2 HIGH 4000 - 0 2500 - 0 1789.80 - 0 1267.20 - 0 LOW 15.63 - 255 9.77 - 255 6.99 - 255 4.95 - 255 BAUD RATE (Kbps) FOSC = 4 MHz SPBRG value (decimal) 3.579545 MHz SPBRG value (decimal) 1 MHz SPBRG value (decimal) 32.768 kHz SPBRG value (decimal) KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR 0.3 NA - - NA - - NA - - 0.30 +1.14 26 1.2 NA - - NA - - 1.20 +0.16 207 1.17 -2.48 6 2.4 NA - - NA - - 2.40 +0.16 103 2.73 +13.78 2 9.6 9.62 +0.16 103 9.62 +0.23 92 9.62 +0.16 25 8.20 -14.67 0 19.2 19.23 +0.16 51 19.04 -0.83 46 19.23 +0.16 12 NA - - 76.8 76.92 +0.16 12 74.57 -2.90 11 83.33 +8.51 2 NA - - 96 1000 +4.17 9 99.43 +3.57 8 83.33 -13.19 2 NA - - 300 333.33 +11.11 2 298.30 -0.57 2 250 -16.67 0 NA - - 500 500 0 1 447.44 -10.51 1 NA - - NA - - HIGH 1000 - 0 894.89 - 0 250 - 0 8.20 - 0 LOW 3.91 - 255 3.50 - 255 0.98 - 255 0.03 - 255 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-7 Section 21. Addressable USART Addressable USART 21 Table 21-4: Baud Rates for Asynchronous Mode (BRGH = 0) BAUD RATE (Kbps) FOSC = 40 MHz SPBRG value (decimal) 33 MHz SPBRG value (decimal) 25 MHz SPBRG value (decimal) 20 MHz SPBRG value (decimal) KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR 0.3 NA - - NA - - NA - - NA - - 1.2 NA - - NA - - NA - - NA - - 2.4 NA - - 2.40 -0.07 214 2.40 -0.15 162 2.40 +0.16 129 9.6 9.62 +0.16 64 9.55 -0.54 53 9.53 -0.76 40 9.47 -1.36 32 19.2 18.94 -1.36 32 19.10 -0.54 26 19.53 +1.73 19 19.53 +1.73 15 76.8 78.13 +1.73 7 73.66 -4.09 6 78.13 +1.73 4 78.13 +1.73 3 96 89.29 -6.99 6 103.13 +7.42 4 97.66 +1.73 3 104.17 +8.51 2 300 312.50 +4.17 1 257.81 -14.06 1 NA - - 312.50 +4.17 0 500 625 +25.00 0 NA - - NA - - NA - - HIGH 625 - 0 515.63 - 0 390.63 - 0 312.50 - 0 LOW 2.44 - 255 2.01 - 255 1.53 - 255 1.22 - 255 BAUD RATE (Kbps) FOSC = 16 MHz SPBRG value (decimal) 10 MHz SPBRG value (decimal) 7.15909 MHz SPBRG value (decimal) 5.0688 MHz SPBRG value (decimal) KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR 0.3 NA - - NA - - NA - - NA - - 1.2 1.20 +0.16 207 1.20 +0.16 129 1.20 +0.23 92 1.20 0 65 2.4 2.40 +0.16 103 2.40 +0.16 64 2.38 -0.83 46 2.40 0 32 9.6 9.62 +0.16 25 9.77 +1.73 15 9.32 -2.90 11 9.90 +3.13 7 19.2 19.23 +0.16 12 19.53 +1.73 7 18.64 -2.90 5 19.80 +3.13 3 76.8 83.33 +8.51 2 78.13 +1.73 1 111.86 +45.65 0 79.20 +3.13 0 96 83.33 -13.19 2 78.13 -18.62 1 NA - - NA - - 300 250 -16.67 0 156.25 -47.92 0 NA - - NA - - 500 NA - - NA - - NA - - NA - - HIGH 250 - 0 156.25 - 0 111.86 - 0 79.20 - 0 LOW 0.98 - 255 0.61 - 255 0.44 - 255 0.31 - 255 BAUD RATE (Kbps) FOSC = 4 MHz SPBRG value (decimal) 3.579545 MHz SPBRG value (decimal) 1 MHz SPBRG value (decimal) 32.768 kHz SPBRG value (decimal) KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR 0.3 0.30 -0.16 207 0.30 +0.23 185 0.30 +0.16 51 0.26 -14.67 1 1.2 1.20 +1.67 51 1.19 -0.83 46 1.20 +0.16 12 NA - - 2.4 2.40 +1.67 25 2.43 +1.32 22 2.23 -6.99 6 NA - - 9.6 8.93 -6.99 6 9.32 -2.90 5 7.81 -18.62 1 NA - - 19.2 20.83 +8.51 2 18.64 -2.90 2 15.63 -18.62 0 NA - - 76.8 62.50 -18.62 0 55.93 -27.17 0 NA - - NA - - 96 NA - - NA - - NA - - NA - - 300 NA - - NA - - NA - - NA - - 500 NA - - NA - - NA - - NA - - HIGH 62.50 - 0 55.93 - 0 15.63 - 0 0.51 - 0 LOW 0.24 - 255 0.22 - 255 0.06 - 255 0.002 - 255 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-8  2000 Microchip Technology Inc. Table 21-5: Baud Rates for Asynchronous Mode (BRGH = 1) BAUD RATE (Kbps) FOSC = 40 MHz SPBRG value (decimal) 33 MHz SPBRG value (decimal) 25 MHz SPBRG value (decimal) 20 MHz SPBRG value (decimal) KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR 0.3 NA - - NA - - NA - - NA - - 1.2 NA - - NA - - NA - - NA - - 2.4 NA - - NA - - NA - - NA - - 9.6 NA - - 9.60 -0.07 214 9.59 -0.15 162 9.62 +0.16 129 19.2 19.23 +0.16 129 19.28 +0.39 106 19.30 +0.47 80 19.23 +0.16 64 76.8 75.76 -1.36 32 76.39 -0.54 26 78.13 +1.73 19 78.13 +1.73 15 96 96.15 +0.16 25 98.21 +2.31 20 97.66 +1.73 15 96.15 +0.16 12 300 312.50 +4.17 7 294.64 -1.79 6 312.50 +4.17 4 312.50 +4.17 3 500 500 0 4 515.63 +3.13 3 520.83 +4.17 2 416.67 -16.67 2 HIGH 2500 - 0 2062.50 - 0 1562.50 - 0 1250 - 0 LOW 9.77 - 255 8,06 - 255 6.10 - 255 4.88 - 255 BAUD RATE (Kbps) FOSC = 16 MHz SPBRG value (decimal) 10 MHz SPBRG value (decimal) 7.15909 MHz SPBRG value (decimal) 5.0688 MHz SPBRG value (decimal) KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR 0.3 NA - - NA - - NA - - NA - - 1.2 NA - - NA - - NA - - NA - - 2.4 NA - - NA - - 2.41 +0.23 185 2.40 0 131 9.6 9.62 +0.16 103 9.62 +0.16 64 9.52 -0.83 46 9.60 0 32 19.2 19.23 +0.16 51 18.94 -1.36 32 19.45 +1.32 22 18.64 -2.94 16 76.8 76.92 +0.16 12 78.13 +1.73 7 74.57 -2.90 5 79.20 +3.13 3 96 100 +4.17 9 89.29 -6.99 6 89.49 -6.78 4 105.60 +10.00 2 300 333.33 +11.11 2 312.50 +4.17 1 447.44 +49.15 0 316.80 +5.60 0 500 500 0 1 625 +25.00 0 447.44 -10.51 0 NA - - HIGH 1000 - 0 625 - 0 447.44 - 0 316.80 - 0 LOW 3.91 - 255 2.44 - 255 1.75 - 255 1.24 - 255 BAUD RATE (Kbps) FOSC = 4 MHz SPBRG value (decimal) 3.579545 MHz SPBRG value (decimal) 1 MHz SPBRG value (decimal) 32.768 kHz SPBRG value (decimal) KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR KBAUD % ERROR 0.3 NA - - NA - - 0.30 +0.16 207 0.29 -2.48 6 1.2 1.20 +0.16 207 1.20 +0.23 185 1.20 +0.16 51 1.02 -14.67 1 2.4 2.40 +0.16 103 2.41 +0.23 92 2.40 +0.16 25 2.05 -14.67 0 9.6 9.62 +0.16 25 9.73 +1.32 22 8.93 -6.99 6 NA - - 19.2 19.23 +0.16 12 18.64 -2.90 11 20.83 +8.51 2 NA - - 76.8 NA - - 74.57 -2.90 2 62.50 -18.62 0 NA - - 96 NA - - 111.86 +16.52 1 NA - - NA - - 300 NA - - 223.72 -25.43 0 NA - - NA - - 500 NA - - NA - - NA - - NA - - HIGH 250 - 0 55.93 - 0 62.50 - 0 2.05 - 0 LOW 0.98 - 255 0.22 - 255 0.24 - 255 0.008 - 255 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-9 Section 21. Addressable USART Addressable USART 21 21.4 USART Asynchronous Mode In this mode, the USART uses standard nonreturn-to-zero (NRZ) format (one start bit, eight or nine data bits and one stop bit). The most common data format is 8 bits. An on-chip dedicated 8-bit baud rate generator can be used to derive standard baud rate frequencies from the oscillator. The USART transmits and receives the LSb first. The USART’s transmitter and receiver are functionally independent, but use the same data format and baud rate. The baud rate generator produces a clock either x16 or x64 of the bit shift rate, depending on the BRGH bit (TXSTA register). Parity is not supported by the hardware, but can be implemented in software (stored as the ninth data bit). Asynchronous mode is stopped during SLEEP. Asynchronous mode is selected by clearing the SYNC bit (TXSTA register). The USART Asynchronous module consists of the following important elements: • Baud Rate Generator • Sampling Circuit • Asynchronous Transmitter • Asynchronous Receiver 21.4.1 USART Asynchronous Transmitter The USART transmitter block diagram is shown in Figure 21-1. The heart of the transmitter is the Transmit Shift Register (TSR). The shift register obtains its data from the transmit buffer, TXREG. The TXREG register is loaded with data in software. The TSR register is not loaded until the STOP bit has been transmitted from the previous load. As soon as the STOP bit is transmitted, the TSR is loaded with new data from the TXREG register (if available). Once the TXREG register transfers the data to the TSR register (occurs in one TCY), the TXREG register is empty and the TXIF flag bit is set. This interrupt can be enabled/disabled by setting/clearing the TXIE enable bit. The TXIF flag bit will be set, regardless of the state of the TXIE enable bit and cannot be cleared in software. It will reset only when new data is loaded into the TXREG register. While the TXIF flag bit indicated the status of the TXREG register, the TRMT bit (TXSTA register) shows the status of the TSR register. The TRMT status bit is a read only bit, which is set when the TSR register is empty. No interrupt logic is tied to this bit, so the user has to poll this bit in order to determine if the TSR register is empty. Transmission is enabled by setting the TXEN enable bit (TXSTA register). The actual transmission will not occur until the TXREG register has been loaded with data and the Baud Rate Generator (BRG) has produced a shift clock (Figure 21-1). The transmission can also be started by first loading the TXREG register and then setting the TXEN enable bit. Normally when transmission is first started, the TSR register is empty, so a transfer to the TXREG register will result in an immediate transfer to TSR, resulting in an empty TXREG. A back-to-back transfer is thus possible (Figure 21-3). Clearing the TXEN enable bit during a transmission will cause the transmission to be aborted and will reset the transmitter. As a result, the TX/CK pin will revert to hi-impedance. In order to select 9-bit transmission the TX9 bit (TXSTA register) should be set and the ninth bit should be written to the TX9D bit (TXSTA register). The ninth bit must be written before writing the 8-bit data to the TXREG register. This is because a data write to the TXREG register can result in an immediate transfer of the data to the TSR register (if the TSR is empty). In such a case, an incorrect ninth data bit may be loaded in the TSR register. Note 1: The TSR register is not mapped in data memory, so it is not available to the user. 2: When the TXEN bit is set, the TXIF flag bit will also be set since the transmit buffer is not yet full (can move transmit data to the TXREG register). 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-10  2000 Microchip Technology Inc. Figure 21-1: USART Transmit Block Diagram Steps to follow when setting up an Asynchronous Transmission: 1. Initialize the SPBRG register for the appropriate baud rate. If a high speed baud rate is desired, set the BRGH bit. (Subsection 21.3 “USART Baud Rate Generator (BRG)” ). 2. Enable the asynchronous serial port by clearing the SYNC bit and setting the SPEN bit. 3. If interrupts are desired, then set the TXIE, GIE/GIEH and PEIE/GIEL bits. Specify the interrupt priority if required. 4. If 9-bit transmission is desired, then set the TX9 bit (can be used as address/data bit). 5. Enable the transmission by setting the TXEN bit, which will also set the TXIF bit. 6. If 9-bit transmission is selected, the ninth bit should be loaded in the TX9D bit. 7. Load data to the TXREG register (starts transmission). Figure 21-2: Asynchronous Transmission (8- or 9-bit Data) TXIF TXIE Interrupt TXEN Baud Rate CLK SPBRG Baud Rate Generator TX9D MSb LSb Data Bus TXREG register TSR register (8) 0 TX9 TRMT SPEN TX/CK pin Pin Buffer and Control 8 • • • 8 WORD 1 Stop Bit WORD 1 Transmit Shift Reg Start Bit Bit 0 Bit 1 Bit 7/8 Write to TXREG Word 1 BRG output (shift clock) TX/CK pin TXIF bit (Transmit buffer reg. empty flag) TRMT bit (Transmit shift reg. empty flag) Write to TX9D (required for 9-bit Word 1 transmissions) 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-11 Section 21. Addressable USART Addressable USART 21 Figure 21-3: Asynchronous Transmission (Back to Back) Table 21-6: Registers Associated with Asynchronous Transmission Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other Resets INTCON GIE/GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIRx TXIF (1) 0 0 PIEx TXIE (1) 0 0 IPRx TXIP (1) 0 0 RCSTA SPEN RX9 SREN CREN ADDEN FERR OERR RX9D 0000 000x 0000 000x TXREG TX7 TX6 TX5 TX4 TX3 TX2 TX1 TX0 0000 0000 0000 0000 TXSTA CSRC TX9 TXEN SYNC — BRGH TRMT TX9D 0000 -010 0000 -010 SPBRG Baud Rate Generator Register 0000 0000 0000 0000 Legend: x = unknown, - = unimplemented locations read as '0'. Shaded cells are not used for Asynchronous Transmission. Note 1: The PSPIF, PSPIE and PSPIP bits are reserved on the PIC18C2X2 devices. Always maintain these bits clear. 2: The position of this bit is device dependent. Transmit Shift Reg. Write to TXREG BRG output (shift clock) TX/CK pin TXIF bit (interrupt reg. flag) TRMT bit (Transmit shift reg. empty flag) Word 1 Word 2 WORD 1 WORD 2 Start Bit Stop Bit Start Bit Transmit Shift Reg. WORD 1 WORD 2 Bit 0 Bit 1 Bit 7/8 Bit 0 Note: This timing diagram shows two consecutive transmissions. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-12  2000 Microchip Technology Inc. 21.4.2 USART Asynchronous Receiver The receiver block diagram is shown in Figure 21-4. The data is received on the RX/DT pin and drives the data recovery block. The data recovery block is actually a high speed shifter operating at x16 times the baud rate, whereas the main receive serial shifter operates at the bit rate or at FOSC. This mode would typically be used in RS-232 systems. The USART module has a special provision for multi-processor communication. When the RX9 bit is set in the RCSTA register, 9-bits are received and the ninth bit is placed in the RX9D status bit of the RSTA register. The port can be programmed such that when the stop bit is received, the serial port interrupt will only be activated if the RX9D bit is set. This feature is enabled by setting the ADDEN bit in the RCSTA register and can be used in a multi-processor system in the following manner. To transmit a block of data in a multi-processor system, the master processor must first send an address byte that identifies the target slave. An address byte is identified by the RX9D bit being a ‘1’ (instead of a ‘0’ for a data byte). If the ADDEN bit is set in the slave’s RCSTA register, all data bytes will be ignored. However, if the ninth received bit is equal to a ‘1’, indicating that the received byte is an address, the slave will be interrupted and the contents of the Receive Shift Register (RSR) will be transferred into the receive buffer. This allows the slave to be interrupted only by addresses, so that the slave can examine the received byte to see if it is addressed. The addressed slave will then clear its ADDEN bit and prepare to receive data bytes from the master. When the ADDEN bit is set, all data bytes are ignored. Following the STOP bit, the data will not be loaded into the receive buffer and no interrupt will occur. If another byte is shifted into the RSR register, the previous data byte will be lost. The ADDEN bit will only take effect when the receiver is configured in 9-bit mode. Once Asynchronous mode is selected, reception is enabled by setting the CREN bit. The heart of the receiver is the Receive (serial) Shift Register (RSR). After sampling the RX/TX pin for the STOP bit, the received data in the RSR is transferred to the RCREG register (if it is empty). If the transfer is complete, the RCIF flag bit is set. The actual interrupt can be enabled/disabled by setting/clearing the RCIE enable bit. The RCIF flag bit is a read only bit that is cleared by the hardware. It is cleared when the RCREG register has been read and is empty. The RCREG is a double-buffered register (i.e., it is a two-deep FIFO). It is possible for two bytes of data to be received and transferred to the RCREG FIFO and a third byte begin shifting to the RSR register. On the detection of the STOP bit of the third byte, if the RCREG register is still full, overrun error bit, OERR, will be set. The word in the RSR will be lost. The RCREG register can be read twice to retrieve the two bytes in the FIFO. The OERR bit has to be cleared in software. This is done by resetting the receive logic (the CREN bit is cleared and then set). If the OERR bit is set, transfers from the RSR register to the RCREG register are inhibited, so it is essential to clear the OERR bit if it is set. Framing error bit, FERR, is set if a stop bit is detected as a low level. The FERR bit and the 9th receive bit are buffered the same way as the receive data. Reading the RCREG will load the RX9D and FERR bits with new values. Therefore, it is essential for the user to read the RCSTA register before reading the next RCREG register, in order not to lose the old (previous) information in the FERR and RX9D bits. Figure 21-4 shows a block diagram for the receive of the Addressable USART. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-13 Section 21. Addressable USART Addressable USART 21 Figure 21-4: Addressable USART Receive Block Diagram x64 Baud Rate CLK SPBRG Baud Rate Generator RX/DT Pin Buffer and Control SPEN Data Recovery CREN OERR FERR MSb LSb RSR Register RX9D RCREG Register FIFO Interrupt RCIF RCIE Data Bus 8 ÷ 64 ÷ 16 or Stop Start (8) 7 1 0 RX9 • • • RX9 ADDEN RX9 ADDEN RSR<8> Enable Load of Receive Buffer 8 8 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-14  2000 Microchip Technology Inc. 21.4.2.1 Asynchronous Receptions (no Address Detect) Steps to follow when setting up an Asynchronous Reception: 1. Initialize the SPBRG register for the appropriate baud rate. If a high speed baud rate is desired, set bit BRGH. (Subsection 21.3 “USART Baud Rate Generator (BRG)” ). 2. Enable the asynchronous serial port by clearing the SYNC bit and setting the SPEN bit. 3. If interrupts are desired, then set the RCIE bit and configure the RCIP, GIE/GIEH and PEIE/GIEL bits, appropriately. 4. If 9-bit reception is desired, then set the RX9 bit. 5. Enable the reception by setting the CREN bit. 6. The RCIF flag bit will be set when reception is complete. An interrupt will be generated depending on the configuration of the RCIE, RCIP, GIE/GIEH and PEIE/GIEL bits. 7. Read the RCSTA register to get the ninth bit (if enabled) and determine if any error occurred during reception. 8. Read the 8-bit received data by reading the RCREG register. 9. If any error occurred, clear the error by clearing the CREN bit. Figure 21-5: Asynchronous Reception (8- or 9-bit Data) Start bit bit0 bit1 bit7/8 bit0 Stop bit7/8 bit Start bit Start bit7/8 Stop bit bit RX (pin) reg Rcv buffer reg Rcv shift Read Rcv buffer reg RCREG RCIF (interrupt flag) OERR bit CREN WORD 1 RCREG WORD 2 RCREG Stop bit Note: This timing diagram shows three words appearing on the RX input. The RCREG (receive buffer) is read after the third word, causing the OERR (overrun) bit to be set. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-15 Section 21. Addressable USART Addressable USART 21 21.4.3 Setting up 9-bit mode with Address Detect Address detect mode allows an Addressable USART node to ignore all data on the bus until a new address byte is present. This reduces the interrupt overhead since not every byte will generate an interrupt (only bytes that are directed to that node). 21.4.3.1 Transmit Steps to follow when setting up an Asynchronous Transmission: 1. Initialize the SPBRG register for the appropriate baud rate. If a high speed baud rate is desired, set the BRGH bit. (Subsection 21.3 “USART Baud Rate Generator (BRG)” ). 2. Enable the asynchronous serial port by clearing the SYNC bit and setting the SPEN bit. 3. If interrupts are desired, then set the TXIE, TXIP, GIE/GIEH and PEIE/GIEL bits. 4. If 9-bit transmission is desired, then set the TX9 bit (can be used as address/data bit). 5. Enable the transmission by setting the TXEN bit, which will also set the TXIF bit. 6. If 9-bit transmission is selected, set the TX9D bit for address, clear the TX9D bit for data, set the TX9D bit for address and clear the TX9D bit for data. 7. Load data to the TXREG register (starts transmission). 21.4.3.2 Receive Steps to follow when setting up an Asynchronous Reception with Address Detect enabled: 1. Initialize the SPBRG register for the appropriate baud rate. If a high speed baud rate is desired, set bit BRGH. 2. Enable the asynchronous serial port by clearing bit SYNC and setting bit SPEN. 3. If interrupts are desired, then set the RCIE bit and configure the RCIP, GIE/GIEH and PEIE/GIEL bits, appropriately. 4. Set bit RX9 to enable 9-bit reception. 5. Set ADDEN to enable address detect. 6. Enable the reception by setting enable bit CREN. 7. The RCIF flag bit will be set when reception is complete. An interrupt will be generated depending on the configuration of the RCIE, RCIP, GIE/GIEH and PEIE/GIEL bits. 8. Read the RCSTA register to get the ninth bit and determine if any error occurred during reception. 9. Read the 8-bit received data by reading the RCREG register, to determine if the device is being addressed. 10. If any error occurred, clear the error by clearing enable bit CREN. 11. If the device has been addressed, clear the ADDEN bit to allow data bytes and address bytes to be read into the receive buffer, and interrupt the CPU. 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-16  2000 Microchip Technology Inc. Figure 21-6: USART Receive Block Diagram Figure 21-7: Asynchronous Reception with Address Detect Figure 21-8: Asynchronous Reception with Address Byte First x64 Baud Rate CLK SPBRG Baud Rate Generator RX/DT Pin Buffer and Control SPEN Data Recovery CREN OERR FERR MSb RSR Register LSb RX9D RCREG Register FIFO Interrupt RCIF RCIE Data Bus 8 ÷ 64 ÷ 16 or Stop (8) 7 1 0 Start RX9 • • • RX9 ADDEN RX9 ADDEN RSR<8> Enable Load of Receive Buffer 8 8 Start bit bit0 bit1 bit8 bit0 Stop bit Start bit bit8 Stop bit RX/DT (pin) reg Rcv buffer reg Rcv shift Read Rcv buffer reg RCREG RCIF (interrupt flag) WORD 1 RCREG Note: This timing diagram shows a data byte followed by an address byte. The data byte is not read into the RCREG (receive buffer) Bit8 = 0, Data Byte Bit8 = 1, Address Byte because ADDEN = 0. Start bit bit0 bit1 bit8 bit0 Stop bit Start bit bit8 Stop bit RX/DT (pin) reg Rcv buffer reg Rcv shift Read Rcv buffer reg RCREG RCIF (interrupt flag) WORD 1 RCREG Bit8 = 1, Address Byte Bit8 = 0, Data Byte Note: This timing diagram shows an address byte followed by an data byte. The data byte is not read into the RCREG (receive buffer) because ADDEN was not updated and still = 0. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-17 Section 21. Addressable USART Addressable USART 21 21.4.4 Sampling The data on the RX/DT pin is sampled three times by a majority detect circuit to determine if a high or a low level is present at the RX pin. Figure 21-9 shows the waveform for the sampling circuit. The sampling operates the same regardless of the state of the BRGH bit, only the source of the x16 clock is different. Figure 21-9: RX Pin Sampling Scheme, BRGH = 0 or BRGH = 1 Table 21-7: Registers Associated with Asynchronous Reception Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other Resets INTCON GIE/GIEH PEIE/GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIRx RCIF (1) 0 0 PIEx RCIE (1) 0 0 IPRx RCIP (1) 0 0 RCSTA SPEN RX9 SREN CREN ADDEN FERR OERR RX9D 0000 000x 0000 000x RCREG RX7 RX6 RX5 RX4 RX3 RX2 RX1 RX0 0000 0000 0000 0000 TXSTA CSRC TX9 TXEN SYNC — BRGH TRMT TX9D 0000 -010 0000 -010 SPBRG Baud Rate Generator Register 0000 0000 0000 0000 Legend: x = unknown, - = unimplemented locations read as '0'. Shaded cells are not used for Asynchronous Reception. Note 1: The position of this bit is device dependent. RX baud CLK x16 CLK Start bit Bit0 Samples 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 1 2 3 Baud CLK for all but start bit (RX/DT pin) 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-18  2000 Microchip Technology Inc. 21.5 USART Synchronous Master Mode In Synchronous Master mode, the data is transmitted in a half-duplex manner, (i.e., transmission and reception do not occur at the same time). When transmitting data, the reception is inhibited and vice versa. Synchronous mode is entered by setting the SYNC bit. In addition, the SPEN enable bit is set in order to configure the TX/CK and RX/DT I/O pins to CK (clock) and DT (data) lines respectively. The Master mode indicates that the processor transmits the master clock on the CK line. The Master mode is entered by setting the CSRC bit. 21.5.1 USART Synchronous Master Transmission The USART transmitter block diagram is shown in Figure 21-1. The heart of the transmitter is the Transmit Shift Register (TSR). The shift register obtains its data from the read/write transmit buffer register TXREG. The TXREG register is loaded with data in software. The TSR register is not loaded until the last bit has been transmitted from the previous load. As soon as the last bit is transmitted, the TSR is loaded with new data from the TXREG (if available). Once the TXREG register transfers the data to the TSR register (occurs in one Tcycle), the TXREG is empty and the TXIF interrupt flag bit is set. The interrupt can be enabled/disabled by setting/clearing the TXIE enable bit. The TXIF flag bit will be set regardless of the state of the TXIE enable bit and cannot be cleared in software. It will reset only when new data is loaded into the TXREG register. While the TXIF flag bit indicates the status of the TXREG register, the TRMT bit shows the status of the TSR register. The TRMT bit is a read only bit that is set when the TSR is empty. No interrupt logic is tied to this bit, so the user has to poll this bit in order to determine if the TSR register is empty. The TSR is not mapped in data memory, so it is not available to the user. Transmission is enabled by setting the TXEN bit. The actual transmission will not occur until the TXREG register has been loaded with data. The first data bit will be shifted out on the next available rising edge of the clock on the CK line. Data out is stable at the falling edge of the synchronous clock (Figure 21-10). The transmission can also be started by first loading the TXREG register and then setting the TXEN bit. This is advantageous when slow baud rates are selected, since the BRG is kept in RESET when the TXEN, CREN and SREN bits are clear. Setting the TXEN bit will start the BRG, creating a shift clock immediately. Normally, when transmission is first started, the TSR register is empty, so a transfer to the TXREG register will result in an immediate transfer to TSR, resulting in an empty TXREG. Back-to-back transfers are possible. Clearing the TXEN bit during a transmission will cause the transmission to be aborted and will reset the transmitter. The DT and CK pins will revert to hi-impedance. If either of the CREN or SREN bits are set during a transmission, the transmission is aborted and the DT pin reverts to a hi-impedance state (for a reception). The CK pin will remain an output if the CSRC bit is set (internal clock). The transmitter logic is not reset although it is disconnected from the pins. In order to reset the transmitter, the user has to clear the TXEN bit. If the SREN bit is set (to interrupt an on-going transmission and receive a single word), then after the single word is received, the SREN bit will be cleared and the serial port will revert back to transmitting, since the TXEN bit is still set. The DT line will immediately switch from hi-impedance receive mode to transmit and start driving. To avoid this, the TXEN bit should be cleared. In order to select 9-bit transmission, the TX9 bit should be set and the ninth bit should be written to the TX9D bit. The ninth bit must be written before writing the 8-bit data to the TXREG register. This is because a data write to the TXREG can result in an immediate transfer of the data to the TSR register (if the TSR is empty). If the TSR was empty and the TXREG was written before writing the “new” value to the TX9D bit, the “present” value of the TX9D bit is loaded. 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-19 Section 21. Addressable USART Addressable USART 21 Steps to follow when setting up a Synchronous Master Transmission: 1. Initialize the SPBRG register for the appropriate baud rate. (Subsection 21.3 “USART Baud Rate Generator (BRG)” ). 2. Enable the synchronous master serial port by setting the SYNC, SPEN and CSRC bits. 3. If interrupts are desired, then set the TXIE bit and configure the RCIP, GIE/GIEH and PEIE/GIEL bits, appropriately. 4. If 9-bit transmission is desired, then set the TX9 bit. 5. Enable the transmission by setting the TXEN bit. 6. If 9-bit transmission is selected, the ninth bit should be loaded in the TX9D bit. 7. Start transmission by loading data to the TXREG register. Table 21-8: Registers Associated with Synchronous Master Transmission Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on all other Resets INTCON GIE/GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIRx TXIF (1) 0 0 PIEx TXIE (1) 0 0 IPRx TXIP (1) 0 0 RCSTA SPEN RX9 SREN CREN ADDEN FERR OERR RX9D 0000 -00x 0000 -00x TXREG TX7 TX6 TX5 TX4 TX3 TX2 TX1 TX0 0000 0000 0000 0000 TXSTA CSRC TX9 TXEN SYNC — BRGH TRMT TX9D 0000 -010 0000 -010 SPBRG Baud Rate Generator Register 0000 0000 0000 0000 Legend: x = unknown, — = unimplemented, read as '0'. Shaded cells are not used for Synchronous Master Transmission. Note 1: The position of this bit is device dependent. 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-20  2000 Microchip Technology Inc. Figure 21-10:Synchronous Transmission Figure 21-11:Synchronous Transmission (Through TXEN) Bit 0 Bit 1 Bit 7 WORD 1 Q1Q2 Q3Q4 Q1 Q2Q3 Q4Q1 Q2Q3 Q4Q1 Q2Q3 Q4Q1 Q2 Q3Q4 Q3Q4 Q1Q2 Q3Q4 Q1Q2 Q3Q4 Q1Q2 Q3 Q4Q1 Q2Q3 Q4Q1 Q2Q3 Q4Q1 Q2Q3 Q4 RX/DT pin Bit 2 Bit 0 Bit 1 Bit 7 TX/CK pin Write to TXREG reg TRMT TXEN bit '1' '1' Note: Sync Master mode; SPBRG = '0'. Continuous transmission of two 8-bit words. WORD 2 TRMT bit Write word1 Write word2 TXIF bit (Interrupt flag) RX/DT pin TX/CK pin Write to TXREG reg TXIF bit TRMT bit bit0 bit1 bit2 bit6 bit7 TXEN bit 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-21 Section 21. Addressable USART Addressable USART 21 21.5.1.1 USART Synchronous Master Reception Once Synchronous mode is selected, reception is enabled by setting either the SREN or CREN bits. Data is sampled on the RX/DT pin on the falling edge of the clock. If the SREN bit is set, then only a single word is received. If the CREN bit is set, the reception is continuous until the CREN bit is cleared. If both bits are set, then the CREN bit takes precedence. After clocking the last serial data bit, the received data in the Receive Shift Register (RSR) is transferred to the RCREG register (if it is empty). When the transfer is complete, the RCIF interrupt flag bit is set. The actual interrupt can be enabled/disabled by setting/clearing the RCIE enable bit. The RCIF flag bit is a read only bit that is cleared by the hardware. In this case, it is cleared when the RCREG register has been read and is empty. The RCREG is a double buffered register (i.e., it is a two-deep FIFO). It is possible for two bytes of data to be received and transferred to the RCREG FIFO and a third byte to begin shifting into the RSR register. On the clocking of the last bit of the third byte, if the RCREG register is still full, then the overrun error bit, OERR, is set and the word in the RSR is lost. The RCREG register can be read twice to retrieve the two bytes in the FIFO. The OERR bit has to be cleared in software (by clearing the CREN bit). If the OERR bit is set, transfers from the RSR to the RCREG are inhibited, so it is essential to clear the OERR bit if it is set. The 9th receive bit is buffered the same way as the receive data. Reading the RCREG register will load the RX9D bit with a new value; therefore, it is essential for the user to read the RCSTA register before reading RCREG in order to not lose the old (previous) information in the RX9D bit. Steps to follow when setting up a Synchronous Master Reception: 1. Initialize the SPBRG register for the appropriate baud rate. (Subsection 21.3 “USART Baud Rate Generator (BRG)” ) 2. Enable the synchronous master serial port by setting the SYNC, SPEN and CSRC bits. 3. Ensure that the CREN and SREN bits are clear. 4. If interrupts are desired, then set the RCIE bit and configure the RCIP, GIE/GIEH and PEIE/GIEL bits, appropriately. 5. If 9-bit reception is desired, then set the RX9 bit. 6. If a single reception is required, set the SREN bit. For continuous reception, set the CREN bit. 7. The RCIF bit will be set when reception is complete and an interrupt will be generated if the RCIE bit is set. 8. Read the RCSTA register to get the ninth bit (if enabled) and determine if any error occurred during reception. 9. Read the 8-bit received data by reading the RCREG register. 10. If any error occurred, clear the error by clearing the CREN bit. Table 21-9: Registers Associated with Synchronous Master Reception Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other Resets INTCON GIE/ GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIRx RCIF (1) 0 0 PIEx RCIE (1) 0 0 IPRx RCIP (1) 0 0 RCSTA SPEN RX9 SREN CREN ADDEN FERR OERR RX9D 0000 000x 0000 000x RCREG RX7 RX6 RX5 RX4 RX3 RX2 RX1 RX0 0000 0000 0000 0000 TXSTA CSRC TX9 TXEN SYNC — BRGH TRMT TX9D 0000 -010 0000 -010 SPBRG Baud Rate Generator Register 0000 0000 0000 0000 Legend: x = unknown, - = unimplemented read as '0'. Shaded cells are not used for Synchronous Master Reception. Note 1: The position of this bit is device dependent. 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-22  2000 Microchip Technology Inc. Figure 21-12: Synchronous Reception (Master Mode, SREN) CREN bit RX/DT pin TX/CK pin Write to SREN bit SREN bit RCIF bit (interrupt) Read RXREG Note: Timing diagram demonstrates SYNC Master mode with SREN = '1' and BRG = '0'. Q2 Q1 Q2 Q3 Q4Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 '0' bit0 bit1 bit2 bit3 bit4 bit5 bit6 bit7 Q1 Q2 Q3 Q4 ’0’ 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-23 Section 21. Addressable USART Addressable USART 21 21.6 USART Synchronous Slave Mode Synchronous slave mode differs from the Master mode in the fact that the shift clock is supplied externally at the TX/CK pin (instead of being supplied internally in Master mode). This allows the device to transfer or receive data while in SLEEP mode. Slave mode is entered by clearing the CSRC bit (TXSTA<7>). 21.6.1 USART Synchronous Slave Transmit The operation of the Synchronous Master and Slave modes are identical, except in the case of the SLEEP mode. If two words are written to the TXREG and then the SLEEP instruction is executed, the following will occur: a) The first word will immediately transfer to the TSR register and transmit. b) The second word will remain in TXREG register. c) The TXIF flag bit will not be set. d) When the first word has been shifted out of TSR, the TXREG register will transfer the second word to the TSR and the TXIF flag bit will now be set. e) If the TXIE enable bit is set, the interrupt will wake the chip from SLEEP and if the global interrupt is enabled, the program will branch to the interrupt vector. Steps to follow when setting up a Synchronous Slave Transmission: 1. Enable the synchronous slave serial port by setting the SYNC and SPEN bits and clearing the CSRC bit. 2. Clear the CREN and SREN bits. 3. If interrupts are desired, then set the TXIE enable bit and configure the RCIP, GIE/GIEH and PEIE/GIEL bits, appropriately. 4. If 9-bit transmission is desired, then set the TX9 bit. 5. Enable the transmission by setting the TXEN enable bit. 6. If 9-bit transmission is selected, the ninth bit should be loaded into the TX9D bit. 7. Start transmission by loading data to the TXREG register. Table 21-10: Registers Associated with Synchronous Slave Transmission Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other Resets INTCON GIE/ GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIRx TXIF (1) 0 0 PIEx TXIE (1) 0 0 IPRx TXIP (1) 0 0 RCSTA SPEN RX9 SREN CREN ADDEN FERR OERR RX9D 0000 000x 0000 000x TXREG TX7 TX6 TX5 TX4 TX3 TX2 TX1 TX0 0000 0000 0000 0000 TXSTA CSRC TX9 TXEN SYNC — BRGH TRMT TX9D 0000 -010 0000 -010 SPBRG Baud Rate Generator Register 0000 0000 0000 0000 Legend: x = unknown, - = unimplemented read as '0'. Shaded cells are not used for Synchronous Slave Transmission. Note 1: The position of this bit is device dependent. 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-24  2000 Microchip Technology Inc. 21.6.2 USART Synchronous Slave Reception The operation of the Synchronous Master and Slave modes is identical, except in the case of the SLEEP mode. Also, bit SREN is a "don't care" in Slave mode. If receive is enabled, by setting the CREN bit prior to the SLEEP instruction, then a word may be received during SLEEP. On completely receiving the word, the RSR register will transfer the data to the RCREG register and if the RCIE enable bit bit is set, the interrupt generated will wake the chip from SLEEP. If the global interrupt is enabled, the program will branch to the appropriate interrupt vector. Steps to follow when setting up a Synchronous Slave Reception: 1. Enable the synchronous master serial port by setting the SYNC and SPEN bits and clearing the CSRC bit. 2. If interrupts are desired, then set the RCIE enable bit and configure the RCIP, GIE/GIEH and PEIE/GIEL bits, appropriately. 3. If 9-bit reception is desired, then set the RX9 bit. 4. To enable reception, set the CREN enable bit. 5. The RCIF bit will be set when reception is complete and an interrupt will be generated, if the RCIE bit is set. 6. Read the RCSTA register to get the ninth bit (if enabled) and determine if any error occurred during reception. 7. Read the 8-bit received data by reading the RCREG register. 8. If any error occurred, clear the error by clearing the CREN bit. Table 21-11: Registers Associated with Synchronous Slave Reception Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on: POR, BOR Value on all other Resets INTCON GIE/ GIEH PEIE/ GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000u PIRx RCIF (1) 0 0 PIEx RCIE (1) 0 0 IPRx RCIP (1) 0 0 RCSTA SPEN RX9 SREN CREN ADDEN FERR OERR RX9D 0000 000x 0000 000x RCREG RX7 RX6 RX5 RX4 RX3 RX2 RX1 RX0 0000 0000 0000 0000 TXSTA CSRC TX9 TXEN SYNC — BRGH TRMT TX9D 0000 -010 0000 -010 SPBRG Baud Rate Generator Register 0000 0000 0000 0000 Legend: x = unknown, - = unimplemented read as '0'. Shaded cells are not used for Synchronous Slave Reception. Note 1: The position of this bit is device dependent. 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-25 Section 21. Addressable USART Addressable USART 21 21.7 Initialization Example 21-2 is an initialization routine for Asynchronous Transmitter/Receiver mode. Example 21-3 is for the Synchronous mode. In both examples, the data is 8 bits, and the value to load into the SPBRG register is dependent on the desired baud rate and the device frequency. Example 21-4 is an initialization of the Addressable USART in 9-bit address detect mode. Example 21-2: Asynchronous Transmitter/Receiver Example 21-3: Synchronous Transmitter/Receiver Example 21-4: Asynchronous 9-bit Transmitter/Receiver (Address Detect Enabled) MOVLW baudrate ; Set Baudrate MOVWF SPBRG MOVLW 0x20 ; 8-bit transmit, transmitter enabled, MOVWF TXSTA ; asynchronous mode, low speed mode CLRF PIR1 ; Clear all iterrupt flags ; including AUSART TX & RX BSF PIE1,TXIE ; Enable transmit interrupts BSF PIE1,RCIE ; Enable receive interrupts MOVLW 0x90 ; 8-bit receive, receiver enabled, MOVWF RCSTA ; serial port enabled MOVLW baudrate ; Set Baudrate MOVWF SPBRG MOVLW 0xB0 ; Synchronous Master,8-bit transmit, MOVWF TXSTA ; transmitter enabled, low speed mode CLRF PIR1 ; Clear all iterrupt flags ; including AUSART TX & RX BSF PIE1,TXIE ; Enable transmit interrupts BSF PIE1,RCIE ; Enable receive interrupts MOVLW 0x90 ; 8-bit receive, receiver enabled, MOVWF RCSTA ; continuous receive, serial port enabled MOVLW baudrate ; Set Baudrate MOVWF SPBRG MOVLW 0x60 ; 9-bit transmit, transmitter enabled, MOVWF TXSTA ; asynchronous mode, low speed mode CLRF PIR1 ; Clear all iterrupt flags ; including AUSART TX & RX BSF PIE1,TXIE ; Enable transmit interrupts BSF PIE1,RCIE ; Enable receive interrupts MOVLW 0xD8 ; 9-bit, Address Detect Enable MOVWF RCSTA ; serial port enabled 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-26  2000 Microchip Technology Inc. 21.8 Design Tips Question 1: Using the Asynchronous mode I am getting a lot of transmission errors. Answer 1: The most common reasons are 1. You have incorrectly calculated the value to load in to the SPBRG register. 2. The sum of the baud errors for the transmitter and receiver is too high. Question 2: The PICmicro device is not receiving the data transmitted even though there are good levels on the Addressable USART pins. Answer 2: Ensure that the Address Detect Enable bit is at the desired setting. 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39521A-page 21-27 Section 21. Addressable USART Addressable USART 21 21.9 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to this section are: Title Application Note # Serial Port Utilities AN547 Servo Control of a DC Brush Motor AN532 Brush-DC Servomotor Implementation using PIC17C756A AN718 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39521A-page 21-28  2000 Microchip Technology Inc. 21.10 Revision History Revision A This is the initial released revision of the Enhanced MCU Addressable USART module description. 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-1 CAN 22 Section 22. CAN HIGHLIGHTS This section of the manual contains the following major topics: 22.1 Introduction .................................................................................................................. 22-2 22.2 Control Registers for the CAN Module......................................................................... 22-3 22.3 CAN Overview ........................................................................................................... 22-28 22.4 CAN Bus Features ..................................................................................................... 22-32 22.5 CAN Module Implementation ..................................................................................... 22-33 22.6 Frame Types .............................................................................................................. 22-37 22.7 Modes of Operation ................................................................................................... 22-44 22.8 CAN Bus Initialization ................................................................................................ 22-48 22.9 Message Reception ................................................................................................... 22-49 22.10 Transmission .............................................................................................................. 22-60 22.11 Error Detection........................................................................................................... 22-69 22.12 Baud Rate Setting...................................................................................................... 22-71 22.13 Interrupts.................................................................................................................... 22-75 22.14 Timestamping ............................................................................................................ 22-77 22.15 CAN Module I/O......................................................................................................... 22-77 22.16 Design Tips ................................................................................................................ 22-78 22.17 Related Application Notes.......................................................................................... 22-79 22.18 Revision History ......................................................................................................... 22-80 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-2  2000 Microchip Technology Inc. 22.1 Introduction The Controller Area Network (CAN) module is a serial interface useful for communicating with other peripherals or microcontroller devices. This interface/protocol was designed to allow communications within noisy environments. Figure 22-1 shows an example CAN Bus network. Figure 22-1: Example CAN Bus Network MCP2510 SPI MCP2510 INTERFACE CAN BUS CAN Transceiver PICmicro Controller CAN Transceiver CAN Transceiver CAN Transceiver CAN Transceiver PICmicro Controller PIC18CXX8 with CAN PIC18CXX8 with integrated PIC18CXX8 with integrated Microchip Microchip CAN CAN 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-3 Section 22. CAN CAN 22 22.2 Control Registers for the CAN Module There are many registers associated with the CAN module. Descriptions of these registers are grouped into sections. These sections are: • Control and Status Registers • Transmit Buffer Registers • Receive Buffer Registers • Baud Rate Control Registers • Interrupt Status and Control Registers 22.2.1 CAN Control and Status Registers This section shows the CAN Control and Status registers. Register 22-1: CANCON: CAN Control Register R/W-1 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 REQOP2 REQOP1 REQOP0 ABAT WIN2 WIN1 WIN0 — bit 7 bit 0 bit 7 - 5 REQOP2:REQOP0: Request CAN Operation mode bits 1xx = Request Configuration mode 011 = Request Listen Only mode 010 = Request Loopback mode 001 = Request Disable mode 000 = Request Normal mode bit 4 ABAT: Abort All Pending Transmissions bit 1 = Abort All Pending Transmissions (in all transmit buffers) 0 = Transmissions proceeding as normal, or all Transmissions aborted Note: This bit will automatically be cleared when all transmissions are aborted. bit 3 - 1 WIN2:WIN0: Window Address bits This selects which of the CAN buffers to switch into the access bank area. This allows access to the buffer registers from any data memory bank. After a frame has caused an interrupt, the ICODE2:ICODE0 bits can be copied to the WIN2:WIN0 bits to select the correct buffer. 111 = Receive Buffer 0 110 = Receive Buffer 0 101 = Receive Buffer 1 100 = Transmit Buffer 0 011 = Transmit Buffer 1 010 = Transmit Buffer 2 001 = Receive Buffer 0 000 = Receive Buffer 0 bit 0 Unimplemented: Read as ’0’ Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-4  2000 Microchip Technology Inc. Register 22-2: CANSTAT: CAN Status Register R-1 R-0 R-0 U-0 R-0 R-0 R-0 U-0 OPMODE2 OPMODE1 OPMODE0 — ICODE2 ICODE1 ICODE0 — bit 7 bit 0 bit 7-5 OPMODE2:OPMODE0: Operation Mode Status bits 111 = Reserved 110 = Reserved 101 = Reserved 100 = Configuration mode 011 = Listen Only mode 010 = Loopback mode 001 = Disable mode 000 = Normal mode Note: Before the device goes into SLEEP mode, select Disable Mode. bit 4 Unimplemented: Read as ’0’ bit 3-1 ICODE2:ICODE0: Interrupt Code bits When an interrupt occurs, a prioritized coded Interrupt value will be present in the ICODE2:ICODE0 bits. These codes indicate the source of the interrupt. The ICODE2:ICODE0 bits can be copied to the WIN2:WIN0 bits to select the correct buffer to map into the Access Bank area. 111 = Wake-up on Interrupt 110 = RXB0 Interrupt 101 = RXB1 Interrupt 100 = TXB0 Interrupt 011 = TXB1 Interrupt 010 = TXB2 Interrupt 001 = Error Interrupt 000 = No Interrupt bit 0 Unimplemented: Read as ’0’ Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-5 Section 22. CAN CAN 22 Register 22-3: COMSTAT: Communication Status Register R/C-0 R/C-0 R-0 R-0 R-0 R-0 R-0 R-0 RX0OVFL RX1OVFL TXBO TXBP RXBP TXWARN RXWARN EWARN bit 7 bit 0 bit 7 RX0OVFL: Receive Buffer 0 Overflow bit 1 = Receive Buffer 0 Overflowed 0 = Receive Buffer 0 has not overflowed. bit 6 RX1OVFL: Receive Buffer 1 Overflow bit 1 = Receive Buffer 1 Overflowed 0 = Receive Buffer 1 has not overflowed bit 5 TXB0: Transmitter Bus Off bit 1 = Transmit Error Counter > 255 0 = Transmit Error Counter ≤ 255 bit 4 TXBP: Transmitter Bus Passive bit 1 = Transmission Error Counter >127 0 = Transmission Error Counter ≤127 bit 3 RXBP: Receiver Bus Passive bit 1 = Receive Error Counter > 127 0 = Receive Error Counter ≤127 bit 2 TXWARN: Transmitter Warning bit 1 = Transmit Error Counter > 95 0 = Transmit Error Counter ≤ 95 bit 1 RXWARN: Receiver Warning bit 1 = Receive Error Counter > 95 0 = Receive Error Counter ≤ 95 bit 0 EWARN: Error Warning bit This bit is a flag of the RXWARN and TXWARN bits 1 = The RXWARN or the TXWARN bits are set 0 = Neither the RXWARN or the TXWARN bits are set Legend R = Readable bit C = Clearable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-6  2000 Microchip Technology Inc. 22.2.2 CAN Transmit Buffer Registers This section describes the CAN Transmit Buffer Register and the associated Transmit Buffer Control Registers. Register 22-4: TXB0CON: Transmit Buffer 0 Control Register TXB1CON: Transmit Buffer 1 Control Register TXB2CON: Transmit Buffer 2 Control Register U-0 R-0 R-0 R-0 R/W-0 U-0 R/W-0 R/W-0 — TXABT TXLARB TXERR TXREQ — TXPRI1 TXPRI0 bit 7 bit 0 bit 7 Unimplemented: Read as ’0’ bit 6 TXABT: Transmission Aborted Status bit 1 = Message was aborted 0 = Message completed transmission successfully bit 5 TXLARB: Transmission Lost Arbitration Status bit 1 = Message lost arbitration while being sent 0 = Message did not lose arbitration while being sent bit 4 TXERR: Transmission Error detected Status bit 1 = A bus error occurred while the message was being sent 0 = A bus error did not occur while the message was being sent bit 3 TXREQ: Transmit Request Status bit 1 = Requests sending a message. Clears the TXABT, TXLARB, and TXERR bits. 0 = Automatically cleared when the message is successfully sent Note: Clearing this bit in software, while the bit is set will request a message abort. bit 2 Unimplemented: Read as ’0’ bit 1:0 TXPRI1:TXPRI0: Transmit Priority bits 11 = Priority Level 3 (Highest Priority) 10 = Priority Level 2 01 = Priority Level 1 00 = Priority Level 0 (Lowest Priority) Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-7 Section 22. CAN CAN 22 Register 22-5: TXB0SIDH: Transmit Buffer 0 Standard Identifier High Byte Register TXB1SIDH: Transmit Buffer 1 Standard Identifier High Byte Register TXB2SIDH: Transmit Buffer 2 Standard Identifier High Byte Register Register 22-6: TXB0SIDL: Transmit Buffer 0 Standard Identifier Low Byte Register TXB1SIDL: Transmit Buffer 1 Standard Identifier Low Byte Register TXB2SIDL: Transmit Buffer 2 Standard Identifier Low Byte Register R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x SID10 SID9 SID8 SID7 SID6 SID5 SID4 SID3 bit 7 bit 0 bit 7-0 SID10:SID3: Standard Identifier bits Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x SID2 SID1 SID0 — EXIDEN — EID17 EID16 bit 7 bit 0 bit 7-5 SID2:SID0: Standard Identifier bits bit 4 Unimplemented: Read as ’0’ bit 3 EXIDEN: Extended Identifier Enable bit 1 = Message will transmit Extended ID 0 = Message will transmit Standard ID bit 2 Unimplemented: Read as ’0’ bit 1-0 EID17:EID16: Extended Identifier bits Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-8  2000 Microchip Technology Inc. Register 22-7: TXB0EIDH: Transmit Buffer 0 Extended Identifier High Byte Register TXB1EIDH: Transmit Buffer 1 Extended Identifier High Byte Register TXB2EIDH: Transmit Buffer 2 Extended Identifier High Byte Register Register 22-8: TXB0EIDL: Transmit Buffer 0 Extended Identifier Low Byte Register TXB1EIDL: Transmit Buffer 1 Extended Identifier Low Byte Register TXB2EIDL: Transmit Buffer 2 Extended Identifier Low Byte Register Register 22-9: TXB0Dm: Transmit Buffer 0 Data Field Byte m Register TXB1Dm: Transmit Buffer 1 Data Field Byte m Register TXB2Dm: Transmit Buffer 2 Data Field Byte m Register R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID15 EID14 EID13 EID12 EID11 EID10 EID9 EID8 bit 7 bit 0 bit 7-0 EID15:EID8: Extended Identifier bits EID15 to EID8 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID7 EID6 EID5 EID4 EID3 EID2 EID1 EID0 bit 7 bit 0 bit 7-0 EID7:EID0: Extended Identifier bits EID7 to EID0 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x TXBnDm7 TXBnDm6 TXBnDm5 TXBnDm4 TXBnDm3 TXBnDm2 TXBnDm1 TXBnDm0 bit 7 bit 0 bit 1-0 TXBnDm7:TXBnDm0: Transmit Buffer n Data Field Byte m bits (where 0 < n < 3 and 0 < m < 8) Each Transmit Buffer has an array of registers. For example Transmit buffer 0 has 7 registers: TXB0D1 to TXB0D7. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-9 Section 22. CAN CAN 22 Register 22-10: TXB0DLC: Transmit Buffer 0 Data Length Code Register TXB1DLC: Transmit Buffer 1 Data Length Code Register TXB2DLC: Transmit Buffer 2 Data Length Code Register Register 22-11: TXERRCNT: Transmit Error Count Register U-0 R/W-x U-0 U-0 R/W-x R/W-x R/W-x R/W-x — TXRTR — — DLC3 DLC2 DLC1 DLC0 bit 7 bit 0 bit 7 Unimplemented: Read as ’0’ bit 6 TXRTR: Transmission Frame Remote Transmission Request bit 1 = Transmitted Message will have TXRTR bit set 0 = Transmitted Message will have TXRTR bit cleared. bit 5-4 Unimplemented: Read as ’0’ bit 3-0 DLC3:DLC0: Data Length Code bits 1111 = Reserved 1110 = Reserved 1101 = Reserved 1100 = Reserved 1011 = Reserved 1010 = Reserved 1001 = Reserved 1000 = Data Length = 8 bytes 0111 = Data Length = 7 bytes 0110 = Data Length = 6 bytes 0101 = Data Length = 5 bytes 0100 = Data Length = 4 bytes 0011 = Data Length = 3 bytes 0010 = Data Length = 2 bytes 0001 = Data Length = 1 bytes 0000 = Data Length = 0 bytes Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 TEC7 TEC6 TEC5 TEC4 TEC3 TEC2 TEC1 TEC0 bit 7 bit 0 bit 7-0 TEC7:TEC0: Transmit Error Counter bits This register contains a value which is derived from the rate at which errors occur. When the error count overflows, the bus off state occurs. When the bus has an occurrence of 11 consecutive recessive bits, the counter value is cleared. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-10  2000 Microchip Technology Inc. 22.2.3 CAN Receive Buffer Registers This section shows the Receive buffer registers with their associated control registers. Register 22-12: RXB0CON: Receive Buffer 0 Control Register R/C-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 R-0 R/W-0 RXFUL RXM1 RXM0 — RXRTRRO RX0DBEN JTOFF FILHIT0 bit 7 bit 0 bit 7 RXFUL: Receive Full status bit 1 = Receive buffer contains a valid received message 0 = Receive buffer is open to receive a new message Note: This bit is set by the CAN module and should be cleared by software after the buffer is read. bit 6-5 RXM1:RXM0: Receive Buffer Mode bits 11 = Receive all messages (including those with errors) 10 = Receive only valid messages with extended identifier 01 = Receive only valid messages with standard identifier 00 = Receive all valid messages bit 4 Unimplemented: Read as ’0’ bit 3 RXRTRRO: Receive Remote Transfer Request Read Only bit 1 = Remote Transfer Request 0 = No Remote Transfer Request bit 2 RX0DBEN: Receive Buffer 0 Double Buffer Enable bit 1 = Receive Buffer 0 overflow will write to Receive Buffer 1 0 = No Receive Buffer 0 overflow to Receive Buffer 1 bit 1 JTOFF: Jump Table offset bit 1 = Allows Jump Table offset between 6 and 7 0 = Allows Jump Table offset between 1 and 0 bit 0 FILHIT0: Filter Hit bit This bit indicates which acceptance filter enabled the message reception into receive buffer 0. 1 = Acceptance Filter 1 (RXF1) 0 = Acceptance Filter 0 (RXF0) Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ C = Clearable bit - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-11 Section 22. CAN CAN 22 Register 22-13: RXB1CON: Receive Buffer 1 Control Register R/C-0 R/W-0 R/W-0 U-0 R-0 R-0 R-0 R-0 RXFUL RXM1 RXM0 — RXRTRRO FILHIT2 FILHIT1 FILHIT0 bit 7 bit 0 bit 7 RXFUL: Receive Full status bit 1 = Receive buffer contains a valid received message 0 = Receive buffer is open to receive a new message Note: This bit is set by the CAN module and should be cleared by software after the buffer is read. bit 6-5 RXM1:RXM0: Receive Buffer Mode bits 11 = Receive all messages (including those with errors) 10 = Receive only valid messages with extended identifier 01 = Receive only valid messages with standard identifier 00 = Receive all valid messages bit 4 Unimplemented: Read as ’0’ bit 3 RXRTRRO: Receive Remote Transfer Request bit (read only) 1 = Remote Transfer Request 0 = No Remote Transfer Request bit 2-0 FILHIT2:FILHIT0: Filter Hit bits These bits indicate which acceptance filter enabled the last message reception into Receive Buffer 1 111 = Reserved 110 = Reserved 101 = Acceptance Filter 5 (RXF5) 100 = Acceptance Filter 4 (RXF4) 011 = Acceptance Filter 3 (RXF3) 010 = Acceptance Filter 2 (RXF2) 001 = Acceptance Filter 1 (RXF1) only possible when RX0DBEN bit is set 000 = Acceptance Filter 0 (RXF0) only possible when RX0DBEN bit is set Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ C = Clearable bit - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-12  2000 Microchip Technology Inc. Register 22-14: RXB0SIDH: Receive Buffer 0 Standard Identifier High Byte Register RXB1SIDH: Receive Buffer 1 Standard Identifier High Byte Register Register 22-15: RXB0SIDL: Receive Buffer 0 Standard Identifier Low Byte Register RXB1SIDL: Receive Buffer 1 Standard Identifier Low Byte Register R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x SID10 SID9 SID8 SID7 SID6 SID5 SID4 SID3 bit 7 bit 0 bit 7-0 SID10:SID3: Standard Identifier bits Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-x R/W-x R/W-x R/W-x R/W-x U-0 R/W-x R/W-x SID2 SID1 SID0 SRR EXID — EID17 EID16 bit 7 bit 0 bit 7-5 SID2:SID0: Standard Identifier bits SID2 to SID1 bit 4 SRR: Substitute Remove Request bit (only when EXID = ’1’) 1 = Remote Transfer Request Occurred 0 = No Remote Transfer Request Occurred bit 3 EXID: Extended Identifier bit 1 = Received message is an Extended Data Frame 0 = Received message is a Standard Data Frame bit 2 Unimplemented: Read as ’0’ bit 1-0 EID17:EID16: Extended Identifier bits EID17 to EID16 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-13 Section 22. CAN CAN 22 Register 22-16: RXB0EIDH: Receive Buffer 0 Extended Identifier High Byte Register RXB1EIDH: Receive Buffer 1 Extended Identifier High Byte Register Register 22-17: RXB0EIDL: Transmit Buffer 0 Extended Identifier Low Byte Register RXB1EIDL: Transmit Buffer 1 Extended Identifier Low Byte Register R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID15 EID14 EID13 EID12 EID11 EID10 EID9 EID8 bit 7 bit 0 bit 7-0 EID15:EID8: Extended Identifier bits EID15 to EID8 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID7 EID6 EID5 EID4 EID3 EID2 EID1 EID0 bit 7 bit 0 bit 7-0 EID7:EID0: Extended Identifier bits EID7 to EID0 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-14  2000 Microchip Technology Inc. Register 22-18: RXB0DLC: Receive Buffer 0 Data Length Code Register RXB1DLC: Receive Buffer 1 Data Length Code Register U-x R/W-x R-x R-x R-x R-x R-x R-x — RXRTR RB1 RB0 DLC3 DLC2 DLC1 DLC0 bit 7 bit 0 bit 7 Unimplemented: Read as ’0’ bit 6 RXRTR: Receiver Remote Transmission Request bit 1 = Remote Transfer Request 0 = No Remote Transfer Request bit 5 RB1: Reserved bit 1 Reserved by CAN Specification and read as ’0’ bit 4 RB0: Reserved bit 0 Reserved by CAN Specification and read as ’0’ bit 3-0 DLC3:DLC0: Data Length Code bits 1111 = Invalid 1110 = Invalid 1101 = Invalid 1100 = Invalid 1011 = Invalid 1010 = Invalid 1001 = Invalid 1000 = Data Length = 8 bytes 0111 = Data Length = 7 bytes 0110 = Data Length = 6 bytes 0101 = Data Length = 5 bytes 0100 = Data Length = 4 bytes 0011 = Data Length = 3 bytes 0010 = Data Length = 2 bytes 0001 = Data Length = 1 bytes 0000 = Data Length = 0 bytes Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-15 Section 22. CAN CAN 22 Register 22-19: RXB0Dm: Receive Buffer 0 Data Field Byte m Register RXB1Dm: Receive Buffer 1 Data Field Byte m Register Register 22-20: RXERRCNT: Receive Error Count Register R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x RXBnDm7 RXBnDm6 RXBnDm5 RXBnDm4 RXBnDm3 RXBnDm2 RXBnDm1 RXBnDm0 bit 7 bit 0 bit 7-0 RXBnDm7:RXBnDm0: Receive Buffer n Data Field Byte m bits (where 0 < n < 1 and 0 < m < 7) Each Receive Buffer has an array of registers. For example Receive buffer 0 has 7 registers: RXB0D1 to RXB0D7. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R-0 R-0 R-0 R-0 R-0 R-0 R-0 R-0 REC7 REC6 REC5 REC4 REC3 REC2 REC1 REC0 bit 7 bit 0 bit 7-0 REC7:REC0: Receive Error Counter bits This register contains the number of errors that occurred for the Reception of this buffers message. When the error count overflows, the bus off state occurs. When the bus has 256 occurrences of 11 consecutive recessive bits, the counter value is cleared. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-16  2000 Microchip Technology Inc. 22.2.4 Message Acceptance Filters This subsection describes the Message Acceptance filters. Register 22-21: RXF0SIDH: Receive Acceptance Filter 0 Std. Identifier Filter High Byte RXF1SIDH: Receive Acceptance Filter 1 Std. Identifier Filter High Byte RXF2SIDH: Receive Acceptance Filter 2 Std. Identifier Filter High Byte RXF3SIDH: Receive Acceptance Filter 3 Std. Identifier Filter High Byte RXF4SIDH: Receive Acceptance Filter 4 Std. Identifier Filter High Byte RXF5SIDH: Receive Acceptance Filter 5 Std. Identifier Filter High Byte Register 22-22: RXF0SIDL: Receive Acceptance Filter 0 Std. Identifier Filter Low Byte RXF1SIDL: Receive Acceptance Filter 1 Std. Identifier Filter Low Byte RXF2SIDL: Receive Acceptance Filter 2 Std. Identifier Filter Low Byte RXF3SIDL: Receive Acceptance Filter 3 Std. Identifier Filter Low Byte RXF4SIDL: Receive Acceptance Filter 4 Std. Identifier Filter Low Byte RXF5SIDL:Receive Acceptance Filter 5 Std. Identifier Filter Low Byte R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x SID10 SID9 SID8 SID7 SID6 SID5 SID4 SID3 bit 7 bit 0 bit 7-0 SID10:SID3: Standard Identifier Filter bits SID10 to SID3 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-x R/W-x R/W-x U-0 R/W-x U-0 R/W-x R/W-x SID2 SID1 SID0 — EXIDEN — EID17 EID16 bit 7 bit 0 bit 7-5 SID2:SID0: Standard Identifier Filter bits SID2 to SID0 bit 4 Unimplemented: Read as ’0’ bit 3 EXIDEN: Extended Identifier Filter Enable bit 1 = Message will transmit Extended ID 0 = Message will not transmit Extended ID. bit 2 Unimplemented: Read as ’0’ bit 1-0 EID17:EID16: Extended Identifier Filter bits EID17 to EID16 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-17 Section 22. CAN CAN 22 Register 22-23: RXF0EIDH: Receive Acceptance Filter 0 Extended Identifier High Byte RXF1EIDH: Receive Acceptance Filter 1 Extended Identifier High Byte RXF2EIDH: Receive Acceptance Filter 2 Extended Identifier High Byte RXF3EIDH: Receive Acceptance Filter 3 Extended Identifier High Byte RXF4EIDH: Receive Acceptance Filter 4 Extended Identifier High Byte RXF5EIDH:Receive Acceptance Filter 5 Extended Identifier High Byte Register 22-24: RXB0EIDL: Receive Buffer 0 Extended Identifier Low Byte Register RXB1EIDL: Receive Buffer 1 Extended Identifier Low Byte Register RXB2EIDL: Receive Buffer 2 Extended Identifier Low Byte Register RXB3EIDL: Receive Buffer 3 Extended Identifier Low Byte Register RXB4EIDL: Receive Buffer 4 Extended Identifier Low Byte Register RXB5EIDL: Receive Buffer 5 Extended Identifier Low Byte Register R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID15 EID14 EID13 EID12 EID11 EID10 EID9 EID8 bit 7 bit 0 bit 7-0 EID15:EID8: Extended Identifier Filter bits EID15 to EID8 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID7 EID6 EID5 EID4 EID3 EID2 EID1 EID0 bit 7 bit 0 bit 7-0 EID7:EID0: Extended Identifier Filterbits EID7 to EID0 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-18  2000 Microchip Technology Inc. Register 22-25: RXM0SIDH: Receive Acceptance Mask 0 Std. Identifier Mask High Byte Register RXM1SIDH: Receive Acceptance Mask 1 Std. Identifier Mask High Byte Register Register 22-26: RXM0SIDL: Receive Acceptance Mask 0 Std. Identifier Mask Low Byte Register RXM1SIDL: Receive Acceptance Mask 1 Std. Identifier Mask Low Byte Register R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x SID10 SID9 SID8 SID7 SID6 SID5 SID4 SID3 bit 7 bit 0 bit 7-0 SID10:SID3: Standard Identifier Mask bits SID10 to SID3 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-x R/W-x R/W-x U-0 U-0 U-0 R/W-x R/W-x SID2 SID1 SID0 — — — EID17 EID16 bit 7 bit 0 bit 7-5 SID2:SID0: Standard Identifier Mask bits SID2 to SID0 bit 4-2 Unimplemented: Read as ’0’ bit 1-0 EID17:EID16: Extended Identifier Mask bits EID17 to EID16 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-19 Section 22. CAN CAN 22 Register 22-27: RXM0EIDH: Receive Acceptance Mask 0 Extended Identifier Mask High Byte Register RXM1EIDH: Receive Acceptance Mask 1 Extended Identifier Mask High Byte Register Register 22-28: RXM0EIDL: Receive Acceptance Mask 0 Extended Identifier Mask Low Byte Register RXM1EIDL: Receive Acceptance Mask 1 Extended Identifier Mask Low Byte Register R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID15 EID14 EID13 EID12 EID11 EID10 EID9 EID8 bit 7 bit 0 bit 1-0 EID15:EID8: Extended Identifier Mask bits EID15 to EID8 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID7 EID6 EID5 EID4 EID3 EID2 EID1 EID0 bit 7 bit 0 bit 1-0 EID7:EID0: Extended Identifier Mask bits EID7 to EID0 Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-20  2000 Microchip Technology Inc. 22.2.5 CAN Baud Rate Registers This subsection describes the CAN baud rate registers. Register 22-29: BRGCON1: Baud Rate Control Register 1 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 SJW1 SJW0 BRP5 BRP4 BRP3 BRP2 BRP1 BRP0 bit 7 bit 0 bit 7-6 SJW1:SJW0: Synchronized Jump Width bits 11 = Synchronization Jump Width Time = 4 x TQ 10 = Synchronization Jump Width Time = 3 x TQ 01 = Synchronization Jump Width Time = 2 x TQ 00 = Synchronization Jump Width Time = 1 x TQ bit 5-0 BRP5:BRP0: Baud Rate Prescaler bits 11111 = TQ = (2 x 64)/FOSC 11110 = TQ = (2 x 63)/FOSC : : 00001 = TQ = (2 x 2)/FOSC 00000 = TQ = (2 x 1)/FOSC Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note: This register is only accessible in configuration mode (see Section 22.7.1). 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-21 Section 22. CAN CAN 22 Register 22-30: BRGCON2: Baud Rate Control Register 2 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 SEG2PHTS SAM SEG1PH2 SEG1PH1 SEG1PH0 PRSEG2 PRSEG1 PRSEG0 bit 7 bit 0 bit 7 SEG2PHTS: Phase Segment 2 Time Select bit 1 = Freely programmable 0 = Maximum of PHEG1 or Information Processing Time (IPT), whichever is greater bit 6 SAM: Sample of the CAN bus line bit 1 = Bus line is sampled three times at the sample point 0 = Bus line is sampled once at the sample point bit 5-3 SEG1PH2:SEG1PH0: Phase segment 1 bits 111 = Phase segment 1 Time = 8 x TQ 110 = Phase segment 1 Time= 7 x TQ 101 = Phase segment 1 Time = 6 x TQ 100 = Phase segment 1 Time = 5 x TQ 011 = Phase segment 1 Time = 4 x TQ 010 = Phase segment 1 Time = 3 x TQ 001 = Phase segment 1 Time = 2 x TQ 000 = Phase segment 1 Time = 1 x TQ bit 2-0 PRSEG2:PRSEG0: Propagation Time Select bits 111 = Propagation Time = 8 x TQ 110 = Propagation Time = 7 x TQ 101 = Propagation Time = 6 x TQ 100 = Propagation Time = 5 x TQ 011 = Propagation Time = 4 x TQ 010 = Propagation Time = 3 x TQ 001 = Propagation Time = 2 x TQ 000 = Propagation Time = 1 x TQ Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note: This register is only accessible in configuration mode (see Section 22.7.1). 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-22  2000 Microchip Technology Inc. Register 22-31: BRGCON3: Baud Rate Control Register 3 U-0 R/W-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 — WAKFIL — — — SEG2PH2 SEG2PH1 SEG2PH0 bit 7 bit 0 bit 7 Unimplemented: Read as ’0’ bit 6 WAKFIL: Selects CAN Bus Line Filter for Wake-up bit 1 = Use CAN bus line filter for wake-up 0 = CAN bus line filter is not used for wake-up bit 5-3 Unimplemented: Read as ’0’ bit 2-0 SEG2PH2:SEG2PH0: Phase Segment 2 Time Select bits 111 = Phase Segment 2 Time = 8 x TQ 110 = Phase Segment 2 Time = 7 x TQ 101 = Phase Segment 2 Time = 6 x TQ 100 = Phase Segment 2 Time = 5 x TQ 011 = Phase Segment 2 Time = 4 x TQ 010 = Phase Segment 2 Time = 3 x TQ 001 = Phase Segment 2 Time = 2 x TQ 000 = Phase Segment 2 Time = 1 x TQ Note: Ignored if SEG2PHTS bit is clear. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-23 Section 22. CAN CAN 22 22.2.6 CAN Module I/O Control Register This subsection describes the CAN Module I/O Control register. Register 22-32: CIOCON: CAN I/O Control Register R/W-0 R/W-0 R/W-0 R/W-0 U-0 U-0 U-0 U-0 TX1SRC TX1EN ENDRHI CANCAP — — — — bit 7 bit 0 bit 7 TX1SRC: TX1 Pin Data Source 1 = TX1 pin will output the CAN clock 0 = TX1 pin will output TXD bit 6 TX1EN: TX1 Pin Enable 1 = TX1 pin will output TXD or CAN clock 0 = TX1 pin will have digital I/O function bit 5 ENDRHI: Enable Drive High 1 = TX0, TX1 pins will drive Vdd when recessive 0 = TX0, TX1 pins will tri-state when recessive bit 4 CANCAP: CAN Message Receive Capture Enable 1 = Enable CAN capture 0 = Disable CAN capture bit 3-0 Unimplemented: Read as ’0’ Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-24  2000 Microchip Technology Inc. 22.2.7 CAN Interrupt Registers This subsection documents the CAN Registers which are associated to Interrupts. Register 22-33: PIR3: Peripheral Interrupt Flag Register R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 IRXIF WAKIF ERRIF TXB2IF TXB1IF TXB0IF RXB1IF RXB0IF bit 7 bit 0 bit 7 IRXIF: CAN Invalid Received message Interrupt Flag bit 1 = An invalid message has occurred on the CAN bus 0 = No invalid message on CAN bus bit 6 WAKIF: CAN Bus Activity Wake-up Interrupt Flag bit 1 = Activity on CAN bus has occurred 0 = No activity on CAN bus bit 5 ERRIF: CAN bus Error Interrupt Flag bit 1 = An error has occurred in the CAN module (multiple sources) 0 = No CAN module errors bit 4 TXB2IF: CAN Transmit Buffer 2 Interrupt Flag bit 1 = Transmit Buffer 2 has completed transmission of a message, and may be re-loaded 0 = Transmit Buffer 2 has not completed transmission of a message bit 3 TXB1IF: CAN Transmit Buffer 1 Interrupt Flag bit 1 = Transmit Buffer 1 has completed transmission of a message, and may be re-loaded 0 = Transmit Buffer 1 has not completed transmission of a message bit 2 TXB0IF: CAN Transmit Buffer 0 Interrupt Flag bit 1 = Transmit Buffer 0 has completed transmission of a message, and may be re-loaded 0 = Transmit Buffer 0 has not completed transmission of a message bit 1 RXB1IF: CAN Receive Buffer 1 Interrupt Flag bit 1 = Receive Buffer 1 has received a new message 0 = Receive Buffer 1 has not received a new message bit 0 RXB0IF: CAN Receive Buffer 0 Interrupt Flag bit 1 = Receive Buffer 0 has received a new message 0 = Receive Buffer 0 has not received a new message Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-25 Section 22. CAN CAN 22 Register 22-34: PIE3: Peripheral Interrupt Enable Register R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 IRXIE WAKIE ERRIE TXB2IE TXB1IE TXB0IE RXB1IE RXB0IE bit 7 bit 0 bit 7 IRXIE: CAN Invalid Received Message Interrupt Enable bit 1 = Enable invalid message received interrupt 0 = Disable invalid message received interrupt bit 6 WAKIE: CAN Bus Activity Wake-up Interrupt Enable bit 1 = Enable Bus Activity Wake-up Interrupt 0 = Disable Bus Activity Wake-up Interrupt bit 5 ERRIE: CAN Bus Error Interrupt Enable bit 1 = Enable CAN bus Error Interrupt 0 = Disable CAN bus Error Interrupt bit 4 TXB2IE: CAN Transmit Buffer 2 Interrupt Enable bit 1 = Enable Transmit Buffer 2 Interrupt 0 = Disable Transmit Buffer 2 Interrupt bit 3 TXB1IE: CAN Transmit Buffer 1 Interrupt Enable bit 1 = Enable Transmit Buffer 1 Interrupt 0 = Disable Transmit Buffer 1 Interrupt bit 2 TXB0IE: CAN Transmit Buffer 0 Interrupt Enable bit 1 = Enable Transmit Buffer 0 Interrupt 0 = Disable Transmit Buffer 0 Interrupt bit 1 RXB1IE: CAN Receive Buffer 1 Interrupt Enable bit 1 = Enable Receive Buffer 1 Interrupt 0 = Disable Receive Buffer 1 Interrupt bit 0 RXB0IE: CAN Receive Buffer 0 Interrupt Enable bit 1 = Enable Receive Buffer 0 Interrupt 0 = Disable Receive Buffer 0 Interrupt Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-26  2000 Microchip Technology Inc. Register 22-35: IPR3: Peripheral Interrupt Priority Register R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 IRXIP WAKIP ERRIP TXB2IP TXB1IP TXB0IP RXB1IP RXB0IP bit 7 bit 0 bit 7 IRXIP: CAN Invalid Received Message Interrupt Priority bit 1 = High Priority 0 = Low Priority bit 6 WAKIP: CAN Bus Activity Wake-up Interrupt Priority bit 1 = High Priority 0 = Low Priority bit 5 ERRIP: CAN Bus Error Interrupt Priority bit 1 = High Priority 0 = Low Priority bit 4 TXB2IP: CAN Transmit Buffer 2 Interrupt Priority bit 1 = High Priority 0 = Low Priority bit 3 TXB1IP: CAN Transmit Buffer 1 Interrupt Priority bit 1 = High Priority 0 = Low Priority bit 2 TXB0IP: CAN Transmit Buffer 0 Interrupt Priority bit 1 = High Priority 0 = Low Priority bit 1 RXB1IP: CAN Receive Buffer 1 Interrupt Priority bit 1 = High Priority 0 = Low Priority bit 0 RXB0IP: CAN Receive Buffer 0 Interrupt Priority bit 1 = High Priority 0 = Low Priority Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-27 Section 22. CAN CAN 22 Table 22-1: CAN Controller Register Map Address Register Name Address Register Name Address Register Name Address Register Name F7Fh — F5Fh — F3Fh — F1Fh RXM1EIDL F7Eh — F5Eh CANSTATRO1 F3Eh CANSTATRO3 F1Eh RXM1EIDH F7Dh — F5Dh RXB1D7 F3Dh TXB1D7 F1Dh RXM1SIDL F7Ch — F5Ch RXB1D6 F3Ch TXB1D6 F1Ch RXM1SIDH F7Bh — F5Bh RXB1D5 F3Bh TXB1D5 F1Bh RXM0EIDL F7Ah — F5Ah RXB1D4 F3Ah TXB1D4 F1Ah RXM0EIDH F79h — F59h RXB1D3 F39h TXB1D3 F19h RXM0SIDL F78h — F58h RXB1D2 F38h TXB1D2 F18h RXM0SIDH F77h — F57h RXB1D1 F37h TXB1D1 F17h RXF5EIDL F76h TXERRCNT F56h RXB1D0 F36h TXB1D0 F16h RXF5EIDH F75h RXERRCNT F55h RXB1DLC F35h TXB1DLC F15h RXF5SIDL F74h COMSTAT F54h RXB1EIDH F34h TXB1EIDH F14h RXF5SIDH F73h CIOCON F53h RXB1EIDL F33h TXB1EIDL F13h RXF4EIDL F72h BRGCON3 F52h RXB1SIDL F32h TXB1SIDL F12h RXF4EIDH F71h BRGCON2 F51h RXB1SIDH F31h TXB1SIDH F11h RXF4SIDL F70h BRGCON1 F50h RXB1CON F30h TXB1CON F10h RXF4SIDH F6Fh CANCON F4Fh — F2Fh — F0Fh RXF3EIDL F6Eh CANSTAT F4Eh CANSTATRO2 F2Eh CANSTATRO4 F0Eh RXF3EIDH F6Dh RXB0D7 F4Dh TXB0D7 F2Dh TXB2D7 F0Dh RXF3SIDL F6Ch RXB0D6 F4Ch TXB0D6 F2Ch TXB2D6 F0Ch RXF3SIDH F6Bh RXB0D5 F4Bh TXB0D5 F2Bh TXB2D5 F0Bh RXF2EIDL F6Ah RXB0D4 F4Ah TXB0D4 F2Ah TXB2D4 F0Ah RXF2EIDH F69h RXB0D3 F49h TXB0D3 F29h TXB2D3 F09h RXF2SIDL F68h RXB0D2 F48h TXB0D2 F28h TXB2D2 F08h RXF2SIDH F67h RXB0D1 F47h TXB0D1 F27h TXB2D1 F07h RXF1EIDL F66h RXB0D0 F46h TXB0D0 F26h TXB2D0 F06h RXF1EIDH F65h RXB0DLC F45h TXB0DLC F25h TXB2DLC F05h RXF1SIDL F64h RXB0EIDL F44h TXB0EIDL F24h TXB2EIDL F04h RXF1SIDH F63h RXB0EIDH F43h TXB0EIDH F23h TXB2EIDH F03h RXF0EIDH F62h RXB0SIDL F42h TXB0SIDL F22h TXB2SIDL F02h RXF0EIDL F61h RXB0SIDH F41h TXB0SIDH F21h TXB2SIDH F01h RXF0SIDL F60h RXB0CON F40h TXB0CON F20h TXB2CON F00h RXF0SIDH Note: The shaded addresses indicate the registers that are in the access RAM. 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-28  2000 Microchip Technology Inc. 22.3 CAN Overview The Controller Area Network (CAN) is a serial communications protocol which efficiently supports distributed real-time control with a very high level of robustness. The Protocol is fully defined by Robert Bosch GmbH, in the CAN Specification V2.0B from 1991. Its domain of application ranges from high speed networks to low cost multiplex wiring. In automotive electronics; (engine control units, sensors, anti-skid-systems, etc.) are connected using CAN with bit rates up to 1 Mbit/sec. The CAN Network allows a cost effective replacement of the wiring harnesses in the automobile. The robustness of the bus in noisy environments and the ability to detect and recover from fault conditions makes the bus suitable for industrial control applications such as DeviceNet, SDS and other fieldbus protocols. CAN is an asynchronous serial bus system with one logical bus line. It has an open, linear bus structure with equal bus nodes. A CAN bus consists of two or more nodes. The number of nodes on the bus may be changed dynamically without disturbing the communication of other nodes. This allows easy connection and disconnection of bus nodes (e.g. for addition of system function, error recovery or bus monitoring). The bus logic corresponds to a "wired-AND" mechanism, "Recessive" bits (mostly, but not necessarily equivalent to the logic level “1”) are overwritten by "Dominant" bits (mostly logic level "0"). As long as no bus node is sending a dominant bit, the bus line is in the recessive state, but a dominant bit from any bus node generates the dominant bus state. Therefore, for the CAN bus line, a medium must be chosen that is able to transmit the two possible bit states (dominant and recessive). One of the most common and cheapest ways is to use a twisted wire pair. The bus lines are then called "CANH" and "CANL", and may be connected directly to the nodes or via a connector. There's no standard defined by CAN regarding the connector to be used. The twisted wire pair is terminated by terminating resistors at each end of the bus line. The maximum bus speed is 1 Mbit, which can be achieved with a bus length of up to 40 meters. For bus lengths longer than 40 meters the bus speed must be reduced (a 1000 m bus can be realized with a 40 Kbit bus speed). For a bus length above 1000 meters special drivers should be used. At least 20 nodes may be connected without additional equipment. Due to the differential nature of transmission, CAN is insensitive to EMI because both bus lines are affected in the same way which leaves the differential signal unaffected. The bus lines can also be shielded to reduce the electromagnetic emission of the bus itself, especially at high baud rates. The binary data is coded corresponding to the NRZ code (Non-Return-to-Zero; low level = dominant state; high level = recessive state). To ensure clock synchronization of all bus nodes, bit-stuffing is used. This means that during the transmission of a message a maximum of five consecutive bits may have the same polarity. Whenever five consecutive bits of the same polarity have been transmitted, the transmitter will insert one additional bit of the opposite polarity into the bit stream before transmitting further bits. The receiver also checks the number of bits with the same polarity and removes the stuff bits from the bit stream (destuffing). In the CAN protocol it is not bus nodes that are addressed, but the address information is contained in the messages that are transmitted. This is done via an identifier (part of each message) which identifies the message content (e.g. engine speed, oil temperature etc.,). The identifier additionally indicates the priority of the message. The lower the binary value of the identifier, the higher the priority of the message. For bus arbitration, Carrier Sense Multiple Access/Collision Detection (CSMA/CD) with Non-Destructive Arbitration (NDA) is used. If bus node A wants to transmit a message across the network, it first checks that the bus is in the idle state ("Carrier Sense") i.e., no node is currently transmitting. If this is the case (and no other node wishes to start a transmission at the same moment) node A becomes the bus master and sends its message. All other nodes switch to receive mode during the first transmitted bit (Start Of Frame bit). After correct reception of the message (which is acknowledged by each node) each bus node checks the message identifier and stores the message, if required. Otherwise, the message is discarded. If two or more bus nodes start their transmission at the same time ("Multiple Access"), collision of the messages is avoided by bitwise arbitration ("Collision Detection/Non-Destructive Arbitration" together with the "Wired-AND" mechanism, "dominant" bits override "recessive" bits). Each node sends the bits of its message identifier (MSb first) and monitors the bus level. A node that sends a recessive identifier bit but reads back a dominant one loses bus arbitration and switches to receive mode. This condition occurs when the message identifier of a competing node has a 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-29 Section 22. CAN CAN 22 lower binary value (dominant state = logic 0) and therefore, the competing node is sending a message with a higher priority. In this way, the bus node with the highest priority message wins arbitration without losing time by having to repeat the message. All other nodes automatically try to repeat their transmission once the bus returns to the idle state. It is not permitted for different nodes to send messages with the same identifier as arbitration could fail leading to collisions and errors later in the message. The original CAN specifications (Versions 1.0, 1.2 and 2.0A) defined the message identifier as having a length of 11 bits giving a possible 2048 message identifiers. The specification has since been updated (to version 2.0B) to remove this limitation. CAN specification Version 2.0B allows message identifier lengths of 11 and/or 29 bits to be used (an identifier length of 29 bits allows over 536 Million message identifiers). Version 2.0B CAN is also referred to as "Extended CAN"; and Versions 1.0, 1.2 and 2.0A) are referred to as "Standard CAN". 22.3.1 Standard CAN vs. Extended CAN Those Data Frames and Remote Frames, which only contain the 11 bit identifier, are called Standard Frames according to CAN specification V2.0A. With these frames, 2048 different messages can be identified (identifiers 0-2047). However, the 16 messages with the lowest priority (2032-2047) are reserved. Extended Frames according to CAN specification V2.0B have a 29 bit identifier. As already mentioned, this 29 bit identifier is made up of the 11 bit identifier ("Standard lD") and the 18 bit Extended identifier ("Extended ID"). CAN modules specified by CAN V2.0A are only able to transmit and receive Standard Frames according to the Standard CAN protocol. Messages using the 29 bit identifier cause errors. If a device is specified by CAN V2.0B, there is one more distinction. Modules named "Part B Passive" can only transmit and receive Standard Frames but tolerate Extended Frames without generating Error Frames. "Part B Active" devices are able to transmit and receive both Standard and Extended Frames. 22.3.2 Basic CAN vs. Full CAN There is one more CAN characteristic concerning the interface between the CAN module and the host CPU, dividing CAN chips into "Basic CAN" and "Full CAN" devices. This distinction is not related to Standard vs. Extended CAN, which makes it possible to use both Basic and Full CAN devices in the same network. In the Basic CAN devices, only basic functions of the protocol are implemented in hardware, e.g. the generation and the check of the bit stream. The decision, if a received message has to be stored or not (acceptance filtering) and the whole message management has to be done by software, i.e., by the host CPU. In addition, the CAN chip typically provides only one transmit buffer and one or two receive buffers. So the host CPU load is quite high using Basic CAN modules, and these devices can only be used at low baud rates and low bus loads with only a few different messages. The advantages of Basic CAN are the small chip size leading to low costs of these devices. Full CAN devices implement the whole bus protocol in hardware including the acceptance filtering and the message management. They contain several so called message objects which handle the identifier, the data, the direction (receive or transmit) and the information Standard CAN/Extended CAN. During the initialization of the device, the host CPU defines which messages are to be sent and which are to be received. The host CPU is informed by interrupt if the identifier of a received message matches with one of the programmed (receive-) message objects. In this way. the CPU load is reduced. Using Full CAN devices, high baud rates and high bus loads with many messages can be handled. These chips are more expensive than the Basic CAN devices, though. Many Full CAN chips provide a "Basic-CAN Feature". One of the messages objects can be programmed in so that every message is stored there that does not match with one of the other message objects. This can be very helpful in a number of applications. 39500 18C Reference Manual.book Page 29 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-30  2000 Microchip Technology Inc. 22.3.3 ISO Model The lSO/OSl Reference Model is used to define the layers of protocol of a communication system as shown in Figure 22-2. At the highest end, the applications need to communicate between each other. At the lowest end, some physical medium is used to provide electrical signaling. The higher levels of the protocol are run by software. Within the CAN bus specification, there is no definition of the type of message or the contents or meaning of the messages transferred. These definitions are made in systems such as Volcano, the Volvo automotive CAN specification; J1939, the U.S. heavy truck multiplex wiring specification; and Allen-Bradly DeviceNet and Honeywell SDS, examples of industrial protocols. The CAN bus module definition encompasses two levels of the overall protocol. • The Data Link Layer - The Logical Link Control (LLC) sub layer - The Medium Access Control (MAC) sub layer • The Physical Layer - The Physical Signaling (PLS) sub layer The LLC sub layer is concerned with Message Filtering, Overload Notification and Error Recovery Management. The scope of the LLC sub layer is: • To provide services for data transfer and for remote data request, • To decide which messages received by the LLC sub layer are actually to be accepted, • To provide means for error recovery management and overload notifications. The MAC sub layer represents the kernel of the CAN protocol. The MAC sub layer defines the transfer protocol, i.e., controlling the Framing, Performing Arbitration, Error Checking, Error Signalling and Fault Confinement. It presents messages received from the LLC sub layer and accepts messages to be transmitted to the LLC sub layer. Within the MAC sub layer it is decided whether the bus is free for starting a new transmission or whether a reception is just starting. The MAC sub layer is supervised by a management entity called Fault Confinement which is self-checking mechanism for distinguishing short disturbances from permanent failures. Also, some general features of the bit timing are regarded as part of the MAC sub layer. The physical layer defines the actual transfer of the bits between the different nodes with respect to all electrical properties. The PLS sub layer defines how signals are actually transmitted and therefore deals with the description of Bit Timing, Bit Encoding, and Synchronization. The lower levels of the protocol are implemented in driver/receiver chips and the actual interface such as twisted pair wiring or optical fiber etc. Within one network, the physical layer has to be the same for all nodes. The Driver/Receiver Characteristics of the Physical Layer are not defined so as to allow transmission medium and signal level implementations to be optimized for their application. The most common example is defined in ISO11898 Road Vehicles multiplex wiring specification. 39500 18C Reference Manual.book Page 30 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-31 Section 22. CAN CAN 22 Figure 22-2: CAN Bus in ISO/OSI Reference Model OSI REFERENCE LAYERS Presentation Transport Data Link Layer LLC (Logical Link Control) Acceptance Filtering Overload Notification Recovery Management MAC (Medium Access Control) Data Encapsulation/Decapsulation Frame Coding (stuffing, destuffing) Medium Access Management Error Detection Error Signalling Acknowledgment Serialization/Deserialization Physical Layer PLS (Physical Signalling) Bit Encoding/Decoding Bit Timing Synchronization PMA (Physical Medium Attachment) Driver/Receiver Characteristics MDI (Medium Dependent Interface) Connectors Fault confinement (MAC-LME) Bus Failure management (PLS-LME) Supervisor Shaded Regions Implemented by the CAN Module Has to be Implemented in PICmicro Firmware Session Network Application CAN Transceiver Chip Connector 39500 18C Reference Manual.book Page 31 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-32  2000 Microchip Technology Inc. 22.4 CAN Bus Features The CAN module is a communication controller implementing the CAN 2.0A/B protocol as defined in the BOSCH specification. The module will support CAN 1.2, CAN 2.0A, CAN 2.0B Passive, and CAN 2.0B Active versions of the protocol. The module implementation is a Full CAN system. The module features are as follows: • Implementation of the CAN protocol CAN 1.2, CAN 2.0A and CAN 2.0B • Standard and extended data frames • Data length from 0 - 8 bytes • Programmable bit rate up to 1 Mbit/sec • Support for remote frames • Double buffered receiver with two prioritized received message storage buffers • 6 full (standard/extended identifier) acceptance filters, 2 associated with the high priority receive buffer, and 4 associated with the low priority receive buffer • 2 full acceptance filter masks, one each associated with the high and low priority receive buffers • Three transmit buffers with application specified prioritization and abort capability • Programmable wake-up functionality with integrated low-pass filter • Programmable loop-back mode and programmable state clocking supports self-test operation • Signaling via interrupt capabilities for all CAN receiver and transmitter error states • Programmable clock source • Programmable link to timer module for time-stamping and network synchronization • Low power SLEEP mode 39500 18C Reference Manual.book Page 32 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-33 Section 22. CAN CAN 22 22.5 CAN Module Implementation This subsection will discuss the implementation of the CAN module and the supported frame formats. 22.5.1 Overview of the Module The CAN bus module consists of a Protocol Engine and message buffering and control. The Protocol Engine can best be understood by defining the types of data frames to be transmitted and received by the module. These blocks are shown in Figure 22-3. Figure 22-3: CAN Buffers and Protocol Engine Block Diagram Acceptance Filter RXF2 R X B 1 A c c e p t A c c e p t Identifier Data Field Data Field Identifier Acceptance Mask RXM1 Acceptance Filter RXF3 Acceptance Filter RXF4 Acceptance Filter RXF5 M A B Acceptance Mask RXM0 Acceptance Filter RXF0 Acceptance Filter RXF1 R X B 0 MSGREQ TXB2 TXABT TXLARB TXERR MTXBUFF MESSAGE Message Queue Control Transmit Byte Sequencer MSGREQ TXB1 TXABT TXLARB MSGREQ TXERR MTXBUFF MESSAGE TXB0 TXABT TXLARB TXERR MTXBUFF MESSAGE Transmit Shift Receive Shift Receive Error Transmit Error Protocol RXERRCNT TXERRCNT Finite State Machine Counter Counter Transmit Logic Bit Timing Logic TX CANRX Bit Timing Generator PROTOCOL ENGINE BUFFERS CRC Generator CRC Check CANTX 39500 18C Reference Manual.book Page 33 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-34  2000 Microchip Technology Inc. 22.5.1.1 Typical Connection Figure 22-4 shows a typical connection between multiple CAN nodes with CAN bus terminators. Figure 22-4: CAN Bus Connection with CAN Bus Terminators 22.5.2 CAN Protocol Engine The CAN protocol engine combines several functional blocks, shown in Figure 22-5. These units and the functions they provide are described below. The heart of the engine is the Protocol Finite State Machine (FSM). This state machine sequences through the messages on a bit by bit basis, changing states of the machine as various fields of various frame types are transmitted or received. The framing messages in Section 22.6 show the states associated with each bit. The FSM is a sequencer controlling the sequential data stream between the TX/RX Shift Register, the CRC Register, and the bus line. The FSM also controls the Error Management Logic (EML) and the parallel data stream between the TX/RX Shift Register and the buffers such that the processes of reception arbitration, transmission, and error signaling are performed according to the CAN protocol. Note that the automatic retransmission of messages on the bus line is handled by the FSM. The data interface to the engine consists of byte wide transmit and receive data. Rather than assembling and shifting an entire frame, the frames are broken into bytes. A receive or transmit address from the Protocol FSM signifies which byte of the frame is current. For transmission, the appropriate byte from the transmit buffer is selected and presented to the engine, which then uses an 8 bit shift register to serialize the data. For reception, an 8 bit shift register assembles a byte which is then loaded into the appropriate byte in the message assembly buffer. The Cyclic Redundancy Check Register generates the Cyclic Redundancy Check (CRC) code to be transmitted over the data bytes and checks the CRC code of incoming messages. The Error Management Logic (EML) is responsible for the fault confinement of the CAN device. Its counters, the Receive Error Counter and the Transmit Error Counter, are incremented and decremented by commands from the Bit Stream Processor. According to the values of the error counters, the CAN controller is set into the states error active, error passive or bus off. The Bit Timing Logic (BTL) monitors the bus line input and handles the bus line related bit timing according to the CAN protocol. The BTL synchronizes on a recessive to dominant busline transition at Start of Frame (hard synchronization) and on any further recessive to dominant bus line transition, if the CAN controller itself does not transmit a dominant bit (resynchronization). The BTL also provides programmable time segments to compensate for the propagation delay time and for phase shifts and in defining the position of the Sample Point in the bit time. The programming of the BTL depends on the baud rate and on external physical delay times. CAN Node 1 CAN Node 2 CAN Node 3 CAN Node 4 CAN Node 5 CAN Node n Bus Terminator CAN BUS Bus Terminator 39500 18C Reference Manual.book Page 34 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-35 Section 22. CAN CAN 22 Figure 22-5: CAN Protocol Engine Block Diagram Bit Timing Logic (BTL) CRC <14:0> Comparator Receive Shift Transmit Shift Sample <2:0> Majority Decision StuffReg <5:0> Comparator Transmit Logic Receive Error Counter Transmit Error Counter Protocol FSM CANRX SAM BusMon Received Data Data to Transmit CANTX RXERRCNT TXERRCNT Interface to Standard Buffer 39500 18C Reference Manual.book Page 35 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-36  2000 Microchip Technology Inc. 22.5.3 CAN Module Functionality The CAN protocol engine handles all functions for receiving and transmitting messages on the CAN bus. Messages are transmitted by first loading the appropriate data registers. Status and errors can be checked by reading the appropriate registers. Any message detected on the CAN bus is checked for errors and then matched against filters to see if it should be received and stored in one of the 2 receive registers. The CAN Module supports the following Frame types: • Standard Data Frame • Extended Data Frame • Remote Frame • Error Frame • Overload Frame • Interframe Space Section 22.6 describes the Frames and their formats. 39500 18C Reference Manual.book Page 36 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-37 Section 22. CAN CAN 22 22.6 Frame Types This chapter describes the CAN Frame types supported by the CAN module. 22.6.1 Standard Data Frame A Standard Data Frame is generated by a node when the node wishes to transmit data. The Standard CAN Data Frame is shown in Figure 22-6. In common with all other frames, the frame begins with a Start Of Frame bit (SOF - dominant state) for hard synchronization of all nodes. The SOF is followed by the Arbitration Field consisting of 12 bits, the 11 bit ldentifier (reflecting the contents and priority of the message) and the RTR bit (Remote Transmission Request bit). The RTR bit is used to distinguish a data Frame (RTR - dominant) from a Remote Frame. The next field is the Control Field, consisting of 6 bits. The first bit of this field is called the Identifier Extension (IDE) bit and is at dominant state to specify that the frame is a Standard Frame. The following bit is reserved, RB0, and defined as a dominant bit. The remaining 4 bits of the Control Field are the Data Length Code (DLC) and specify the number of bytes of data contained in the message. The data being sent follows in the Data Field which is of the length defined by the DLC above (0 - 8 bytes). The Cyclic Redundancy Field (CRC) follows and is used to detect possible transmission errors. The CRC Field consists of a 15 bit CRC sequence, completed by the End of Frame (EOF) field, which consists of seven recessive bits (no bit-stuffing). The final field is the Acknowledge Field. During the ACK Slot bit the transmitting node sends out a recessive bit. Any node that has received an error free frame acknowledges the correct reception of the frame by sending back a dominant bit (regardless of whether the node is configured to accept that specific message or not). The recessive Acknowledge Delimiter completes the Acknowledge Slot and may not be overwritten by a dominant bit. 22.6.1.1 Extended Data Frame In the Extended CAN Data Frame, shown in Figure 22-7, the Start of Frame bit (SOF) is followed by the Arbitration Field consisting of 38 bits. The first 11 bits are the 11 most significant bits of the 29 bit identifier ("Base-lD"). These 11 bits are followed by the Substitute Remote Request bit (SRR), which is transmitted as recessive. The SRR is followed by the lDE bit which is recessive to denote that the frame is an Extended CAN frame. It should be noted from this, that if arbitration remains unresolved after transmission of the first 11 bits of the identifier, and one of the nodes involved in arbitration is sending a Standard CAN frame (11 bit identifier), then the Standard CAN frame will win arbitration due to the assertion of a dominant lDE bit. Also, the SRR bit in an Extended CAN frame must be recessive to allow the assertion of a dominant RTR bit by a node that is sending a Standard CAN Remote Frame. The SRR and lDE bits are followed by the remaining 18 bits of the identifier ("lD-Extension") and the Remote Transmission Request bit. To enable standard and extended frames to be sent across a shared network, it is necessary to split the 29 bit extended message Identifier into 11 bit (most significant) and 18 bit (least significant) sections. This split ensures that the Identifier Extension bit (lDE) can remain at the same bit position in both standard and extended frames. The next field is the Control Field, consisting of 6 bits. The first 2 bits of this field are reserved and are at dominant state. The remaining 4 bits of the Control Field are the Data Length Code (DLC) and specify the number of data bytes. The remaining portion of the frame (Data Field, CRC Field, Acknowledge Field, End Of Frame and lntermission) is constructed in the same way as for a Standard Data Frame. 39500 18C Reference Manual.book Page 37 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-38  2000 Microchip Technology Inc. 22.6.1.2 Remote Frame Normally data transmission is performed on an autonomous basis with the data source node (e.g. a sensor sending out a Data Frame). It is possible, however, for a destination node to request the data from the source. For this purpose, the destination node sends a "Remote Frame" with an identifier that matches the identifier of the required Data Frame. The appropriate data source node will then send a Data Frame as a response to this Remote request. There are 2 differences between a Remote Frame and a Data Frame, shown in Figure 22-8. First, the RTR bit is at the recessive state and second there is no Data Field. In the very unlikely event of a Data Frame and a Remote Frame with the same identifier being transmitted at the same time, the Data Frame wins arbitration due to the dominant RTR bit following the identifier. In this way, the node that transmitted the Remote Frame receives the desired data immediately. 22.6.1.3 The Error Frame An Error Frame is generated by any node that detects a bus error. An error frame, shown in Figure 22-9, consists of 2 fields, an Error Flag field followed by an Error Delimiter field. The Error Delimiter consists of 8 recessive bits and allows the bus nodes to restart bus communications cleanly after an error. There are two forms of Error Flag fields. The form of the Error Flag field depends on the error status of the node that detects the error. If an error-active node detects a bus error then the node interrupts transmission of the current message by generating an active error flag. The active error flag is composed of six consecutive dominant bits. This bit sequence actively violates the bit-stuffing rule. All other stations recognize the resulting bit-stuffing error and in turn generate Error Frames themselves, called Error Echo Flags. The Error Flag field therefore consists of between six and twelve consecutive dominant bits (generated by one or more nodes). The Error Delimiter field completes the Error Frame. After completion of the Error Frame, bus activity retains to normal and the interrupted node attempts to resend the aborted message. If an error passive node detects a bus error then the node transmits an error passive flag followed, again, by the Error Delimiter field. The error passive flag consists of six consecutive recessive bits. From this it follows that, unless the bus error is detected by the bus master node or other error active receiver, that is actually transmitting, the transmission of an Error Frame by an error passive node will not affect any other node on the network. If the bus master node generates an error passive flag then this may cause other nodes to generate error frames due to the resulting bit-stuffing violation. After transmission of an Error Frame, an error passive node must wait for 6 consecutive recessive bits on the bus before attempting to rejoin bus communications. 22.6.1.4 The Overload Frame An Overload Frame, shown in Figure 22-10, has the same format as an Active Error Frame. An Overload Frame, however can only be generated during lnterframe Space. This way, an Overload Frame can be differentiated from an Error Frame (an Error Frame is sent during the transmission of a message). The Overload Frame consists of 2 fields, an Overload Flag followed by an Overload Delimiter. The Overload Flag consists of six dominant bits followed by Overload Flags generated by other nodes (as for active error flag, again giving a maximum of twelve dominant bits). The Overload Delimiter consists of eight recessive bits. An Overload Frame can be generated by a node as a result of 2 conditions. First, the node detects a dominant bit during lnterframe Space which is an illegal condition. Second, due to internal conditions, the node is not yet able to start reception of the next message. A node may generate a maximum of 2 sequential Overload Frames to delay the start of the next message. 22.6.1.5 The Interframe Space Interframe Space separates a proceeding frame (of whatever type) from a following Data or Remote Frame. lnterframe space is composed of at least 3 recessive bits, called the intermission. This is provided to allow nodes time for internal processing before the start of the next message frame. After the intermission, the bus line remains in the recessive state (Bus idle) until the next transmission starts. 39500 18C Reference Manual.book Page 38 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-39 Section 22. CAN CAN 22 Figure 22-6: Standard Data Frame 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 INT Suspend Transmit Bus Idle Any Frame Inter-Frame Space Start of Frame Data Frame or Remote Frame 3 8 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 Start of Frame Data Frame (number of bits = 44 + 8 N) 12 Arbitration Field ID 10 11 ID3 ID0 Identifier Message Filtering Stored in Buffers RTR IDE RB0 DLC3 DLC0 6 4 Control Field Data Length Code Reserved Bits 8N(≤ N ≤ 8) Data Field 8 8 Stored in Transmit/Receive Buffers Bit-Stuffing 16 CRC Field 15 CRC 7 End of Frame CRC Del Acknowledgment ACK Del 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 INT Suspend Transmit Bus Idle Any Frame Inter-Frame Space Start of Frame Data Frame or Remote Frame 3 8 39500 18C Reference Manual.book Page 39 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-40  2000 Microchip Technology Inc. F igu r e 2 2 - 7 : E x t e n d e d D a t a F o r m a t 1 1 1 1 1 0 Bus Idle Start of Frame Data Frame or Remote Frame 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 Start of FrameArbitration Field 32 11 ID10 ID3 ID0 IDE Identifier Message Filtering Stored in Buffers SRR EID17 EID0 RTR RB1 RB0 DLC3 18 DLC0 6 Control Field 4 Reserved bitsData Length Code Stored in Transmit/Receive Buffers 8 8 Data Frame (number of bits = 64 + 8 N) 8 N (N ≤ 8) Data Field 1 1 1 1 1 1 1 1 16 CRC Field 15 CRC CRC Del Acknowledgment ACK Del End of Frame 7 Bit-Stuffing 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 INT Suspend Transmit Bus Idle Any Frame Inter-Frame Space Start of Frame Data Frame or Remote Frame 3 8 Extended Identifier 39500 18C Reference Manual.book Page 40 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-41 Section 22. CAN CAN 22 Figure 22-8: Remote Data Frame Identifier Message Filtering Stored in Buffers Data Length Code Reserved Bits Bit-Stuffing 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 INT Suspend Transmit Bus Idle Any Frame Inter-Frame Space Start of Frame Data Frame or Remote Frame 3 8 0 1 0 0 1 1 1 1 1 1 1 1 1 Start of Frame Remote Frame (number of bits = 44) 12 Arbitration Field ID 10 11 ID0 RTR IDE RB0 DLC3 DLC0 6 4 Control Field 16 CRC Field 15 CRC 7 End of Frame CRC Del Acknowledgment ACK Del 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 INT Suspend Transmit Bus Idle Any Frame Inter-Frame Space Start of Frame Data Frame or Remote Frame 3 8 39500 18C Reference Manual.book Page 41 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-42  2000 Microchip Technology Inc. Figure 22-9: Error Frame 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 INT Suspend Transmit Bus Idle Any Frame Inter-Frame Space Start of Frame Data Frame or Remote Frame 3 8 0 0 0 0 Start of Frame Interrupted Data Frame 12 Arbitration Field ID 10 11 ID3 ID0 Identifier Message Filtering RTR IDE RB0 DLC3 DLC0 6 4 Control Field Data Length Code Reserved Bits 8N (≤ N ≤ 8) Data Field 8 8 Bit-Stuffing 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 INT Suspend Transmit Bus Idle Any Frame Inter-Frame Space Start of Frame Data Frame or Remote Frame 3 8 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 0 Data Frame or Remote Frame Error Frame 6 Error Flag ≤ 6 Echo Error Flag 8 Error Delimiter Inter-Frame Space or Overload Frame 39500 18C Reference Manual.book Page 42 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-43 Section 22. CAN CAN 22 F i g ure 22 -10: Over l oad Frame 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 INT Suspend Transmit Bus Idle Any Frame Inter-Frame Space Start of Frame Data Frame or Remote Frame 3 8 0 1 0 0 1 1 1 1 1 1 1 1 1 Start of Frame Remote Frame (number of bits = 44) 12 Arbitration Field ID 10 11 ID0 RTR IDE RB0 DLC3 DLC0 6 4 Control Field 16 CRC Field 15 CRC 7 End of Frame CRC Del Acknowledgment ACK Del 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 INT Suspend Transmit Bus Idle Any Frame Inter-Frame Space Start of Frame Data Frame or Remote Frame 3 8 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 Overload Frame End of Frame or Error Delimiter or Overload Delimiter 6 Overload Flag Overload Delimiter 8 Inter-Frame Space or Error Frame 39500 18C Reference Manual.book Page 43 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-44  2000 Microchip Technology Inc. 22.7 Modes of Operation The CAN Module can operate in one of several operation modes selected by the user. These modes include: • Initialization Mode • Disable Mode • Normal Operation Mode • Listen Only Mode • Loop Back Mode • Error Recognition Mode (selected through CANRXM bits) Modes are requested by setting the REQOP2:REQOP0 bits except the Error Recognition Mode, which is requested through the CANRXM bits. Entry into a mode is acknowledged by monitoring the OPMODE bits. The module will not change the mode and the OPMODE2:OPMODE0 bits until a change in mode is acceptable, generally during bus idle time which is defined as at least 11 consecutive recessive bits. 22.7.1 Initialization Mode In the initialization mode, the module will not transmit or receive. The error counters are cleared and the interrupt flags remain unchanged. The programmer will have access to configuration registers that are access restricted in other modes. The CAN bus configuration mode is explained in Section 22.8. 39500 18C Reference Manual.book Page 44 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-45 Section 22. CAN CAN 22 22.7.2 Disable Mode In Disable Mode, the module will not transmit or receive. The module has the ability to set the WAKIF bit due to bus activity, however any pending interrupts will remain and the error counters will retain their value. If the REQOP2:REQOP0 bits = 001, the module will enter the module disable mode. This mode is similar to disabling other peripheral modules by turning off the module enables. This causes the module internal clock to stop unless the module is active (i.e., receiving or transmitting a message). If the module is active, the module will wait for 11 recessive bits on the CAN bus, detect that condition as an idle bus then accept the module disable command. When the OPMODE2:OPMODE0 bits = 001, that indicates whether the module successfully went into module disable mode (see Figure 22-11). The WAKIF interrupt is the only module interrupt that is still active in the module disable mode. If the WAKIE is set, the processor will receive an interrupt whenever the CAN bus detects a dominant state, as occurs with a Start of Frame (SOF). The I/O pins will revert to normal I/O function when the module is in the module disable mode. Figure 22-11: Entering and Exiting Module Disable Mode 1 2 4 5 - Processor writes REQOP2:REQOP0 while module receiving/transmitting message. Module continues with CAN message. - Module detects 11 recessive bits. Module acknowledges disable mode and sets OPMODE2:OPMODE0 bits. Module disables. - Processor writes REQOP2:REQOP0 during CAN bus activity. Module waits for 11 recessive bits before accepting activate. - Module detects 11 recessive bits. Module acknowledges normal mode and sets OPMODE2:OPMODE0 bits. Module activates. OSC1 CAN BUS CAN Module Disabled 3 REQOP2: OPMODE2: 001 000 001 000 000 000 - CAN bus message will set WAKIF bit. If WAKIE = ’1’, processor will vector to the interrupt address. CAN message ignored. WAKIF WAKIE 1 2 3 4 5 REQOP0 OPMODE0 39500 18C Reference Manual.book Page 45 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-46  2000 Microchip Technology Inc. 22.7.2.1 SLEEP Mode A CPU SLEEP instruction will stop the crystal oscillator and shut down all system clocks. The user is responsible to take care that the module is not active when the CPU goes into SLEEP mode. The pins will revert into normal I/O function, dependent on the value in the TRIS register. The recommended procedure is to bring the module into disabled mode before the CPU SLEEP instruction is executed. Figure 22-12 illustrates the sequence of events when a CAN message is received during execution of the SLEEP instruction. Figure 22-12:SLEEP Interrupted By Message 2 3 4 - CAN bus activity sets WAKIF flag. If GIE = ’1’ processor will vector to interrupt address, bypassing SLEEP instruction. - Processor attempts to execute SLEEP instruction. Since WAKIF = ’1’, WAKIE = ’1’ and GIE = ’0’ OSC1 CAN BUS CAN Module Disabled REQOP2: OPMODE2: 001 000 001 000 000 000 SLEEP WAKIF WAKIE 1 - Processor requests and receives module disable mode. Wake up interrupt enabled. processor will execute NOP in place of SLEEP instruction. CAN message ignored. - Processor requests and receives module normal mode. CAN activity resumes. 1 2 3 4 0 0 REQOP0 OPMODE0 39500 18C Reference Manual.book Page 46 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-47 Section 22. CAN CAN 22 22.7.2.2 Wake-up from SLEEP Figure 22-13 depicts how the CAN module will execute the SLEEP instruction and how the module wakes up on bus activity. Upon a Wake-up from SLEEP the WAKIF flag is set. The module will monitor the RX line for activity while the MCU is in SLEEP mode. If the module is in CPU SLEEP mode and the WAKIE wake-up interrupt enable is set, the module will generate an interrupt, bringing up the CPU. Due to the delays in starting up the oscillator and CPU, the message activity that caused the wake-up will be lost. If the module is in CPU SLEEP mode and the WAKIE is not set, no interrupt will be generated and the CPU and the module will continue to sleep. If the CAN module is in disable mode, the module will wake-up and, depending on the condition of the WAKIE bit, may generate an interrupt. It is expected that the module will correctly receive the message that caused the wake-up from SLEEP mode. The module can be programmed to apply a low-pass filter function to the RxCAN input line while the module or the CPU is in SLEEP mode. This feature can be used to protect the module from Wake-up due to short glitches on the CAN bus lines. Such glitches can result from electromagnetic inference within noisy environments. The WAKFIL bit enables or disables the filter. Figure 22-13:Processor SLEEP and CAN Bus Wake-up Interrupt TOST Processor in SLEEP 2 3 4 5 - Processor executes SLEEP instruction. - SOF of message wakes up processor. Oscillator start time begins. CAN message lost. WAKIF bit set. - Processor completes oscillator start time. Processor resumes program or interrupt, based on GIE bits. accepting CAN bus activity. CAN message lost. - Module detects 11 recessive bits. Module will begin to receive messages and transmit any pending messages. OSC1 CAN BUS CAN Module Disabled REQOP2: OPMODE2: 001 000 001 000 000 000 SLEEP WAKIF WAKIE 1 - Processor requests and receives module disable mode. Wake-up interrupt enabled. Processor requests normal operating mode. Module waits for 11 recessive bits before 1 2 3 4 5 REQOP0 OPMODE0 39500 18C Reference Manual.book Page 47 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-48  2000 Microchip Technology Inc. 22.7.3 Normal Operation Mode Normal operating mode is selected when REQOP2:REQOP0 = 000. In this mode, the module is activated, the I/O pins will assume the CAN bus functions. The module will transmit and receive CAN bus messages as described in subsequent paragraphs. 22.7.4 Listen Only Mode Listen only mode and loopback modes are special cases of normal operation mode to allow system debug. If the listen only mode is activated, the module on the CAN bus is passive. The transmitter buffers revert to Port I/O function. The receive pins remain input. For the receiver, no error flags or acknowledge signals are sent. The error counters are deactivated in this state. The listen only mode can be used for detecting the baud rate on the CAN bus. To use this, it is necessary that there are at least two further nodes that communicate with each other. The baud rate can be detected empirically by testing different values. This mode is also useful as a bus monitor without influencing the data traffic. 22.7.5 Error Recognition Mode The module can be set to ignore all errors and receive any message. The error recognition mode is activated by setting the RXM1:RXM0 bits in the RXBnCON registers to 11. In this mode the data which is in the message assembly buffer until the error time is copied in the receive buffer and can be read via the CPU interface. In addition the data which was on the internal sampling of the CAN bus at the error time and the state vector of the protocol state machine and the bit counter CntCan are stored in registers and can be read. 22.7.6 Loop Back Mode If the loopback mode is activated, the module will connect the internal transmit signal to the internal receive signal at the module boundary. The transmit and receive pins revert to their Port I/O function. The transmitter will receive an acknowledge for its sent messages. Special hardware will generate an acknowledge for the transmitter. 22.8 CAN Bus Initialization After a RESET the CAN module is in the configuration mode (OPMODE2 is set). The error counters are cleared and all registers contain the reset values. It should be ensured that the initialization is performed before REQOP2 bit is cleared. 22.8.1 Initialization The CAN module has to be initialized before the activation. This is only possible if the module is in the configuration mode. The configuration mode is requested by setting REQOP2 bit. Only when the status bit OPMODE2 has a high level, the initialization can be performed. Afterwards the configuration registers and the acceptance mask registers and the acceptance filter registers can be written. The module is activated by setting the control bits CFGREQ to zero. The module will protect the user from accidentally violating the CAN protocol through programming errors. All registers which control the configuration of the module can not be modified while the module is on-line. The CAN module will not be allowed to enter the configuration mode while a transmission is taking place. The CONFIG mode serves as a lock to protect the following registers. • All Module Control Registers • Configuration Registers • Bus Timing Registers • Identifier Acceptance Filter Registers • Identifier Acceptance Mask Registers 39500 18C Reference Manual.book Page 48 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-49 Section 22. CAN CAN 22 22.9 Message Reception This chapter describes the message reception. 22.9.1 Receive Buffers The CAN bus module has 3 receive buffers. However, one of the receive buffers is always committed to monitoring the bus for incoming messages. This buffer is called the message assembly buffer, MAB. So there are 2 receive buffers visible, RXB0 and RXB1, that can essentially instantaneously receive a complete message from the protocol engine. The CPU can be operating on one while the other is available for reception or holding a previously received message. The MAB holds the destuffed bit stream from the bus line to allow parallel access to the whole data or Remote Frame for the acceptance match test and the parallel transfer of the frame to the receive buffers. The MAB will assemble all messages received. These messages will be transferred to the RXBn buffers only if the acceptance filter criterion are met. When a message is received, the RXFUL bit will be set. This bit can only be set by the module when a message is received. The bit is cleared by the CPU when it has completed processing the message in the buffer. This bit provides a positive lockout to ensure that the CPU has finished with the message buffer. If the RXnIE bit is set , an interrupt will be generated when a message is received. There are 2 programmable acceptance filter masks associated with the receive buffers, one for each buffer. When the message is received, the FILHIT2:FILHIT0 bits (RXBnCON register) indicate the acceptance criterion for the message. The number of the acceptance filter that enabled the reception will be indicated as well as a status bit that indicates that the received message is a remote transfer request. 39500 18C Reference Manual.book Page 49 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-50  2000 Microchip Technology Inc. 22.9.1.1 Receive Buffer Priority To provide flexibility, there are several acceptance filters corresponding to each receive buffer. There is also an implied priority to the receive buffers. RXB0 is the higher priority buffer and has 2 message acceptance filters associated with it. RXB1 is the lower priority buffer and has 4 acceptance filters associated with it. The lower number of possible acceptance filters makes the match on RXB0 more restrictive and implies the higher criticality associated with that buffer. Additionally, if the RXB0 contains a valid message, and another valid message is received, the RXB0 can be setup such that it will not overrun and the new message for RXB0 will be placed into RXB1. Figure 22-14 shows a block diagram of the receive buffer, while Figure 22-15 shows a flow chart for receive operation. Figure 22-14:The Receive Buffers Acceptance Mask RXM1 Acceptance Filter RXF2 Acceptance Filter RXF3 Acceptance Filter RXF4 Acceptance Filter RXF5 R X B 1 M A B R X B 0 Acceptance Mask RXM0 Acceptance Filter RXF0 Acceptance Filter RXF1 A c c e p A t c c e p t Identifier Data Field Data Field Identifier 39500 18C Reference Manual.book Page 50 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-51 Section 22. CAN CAN 22 Figure 22-15:Receive Flowchart Start Detect Start of Message ? Valid Message Received ? Generate Error Message Identifier meets a filter criteria ? Is RXRDY=0 ? Go to Start Move message into RXB0 Set RXRDY = 1 Set FILHIT<2:0> Is RXRDY=0 ? Move message into RXB1 Set RXRDY=1 Yes, meets criteria for RXBO Yes, meets criteria for RXB1 No Generate Interrupt Yes Yes No No Yes Yes No No Yes Yes Frame The RXRDY bit determines if the receive register is empty and able to accept a new message. No Yes No Generate Overrun Error: Begin Loading Message into Message Assembly Buffer (MAB) was met Is RXIE=1 ? Does RXIE=1 ? Is RX0DBEN=1 ? The RX0DBEN bit determines if RXB0 can roll over into RXB1 if it is full. Set RX0OVFL Generate Overrun Error: Set RX1OVFL Does ERRIE=1 ? No Go to Start Yes Set FILHIT<0> No according to which filter criteria was met Set CANSTAT<3:0> according to which receive buffer the message was loaded into according to which filter criteria 39500 18C Reference Manual.book Page 51 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-52  2000 Microchip Technology Inc. 22.9.2 Message Acceptance Filters The message acceptance filters and masks are used to determine if a message in the message assembly buffer should be loaded into either of the receive buffers. Once a valid message has been received into the MAB, the identifier fields of the message are compared to the filter values. If there is a match, that message will be loaded into the appropriate receive buffer. The filter masks are used to determine which bits in the identifiers are examined with the filters. A truthtable is shown in Table 22-2 that indicates how each bit in the identifier is compared to the masks and filters to determine if the message should be loaded into a receive buffer. The mask bit essentially determines which bits to apply the filter to. If any mask bit is set to a zero, then that bit will automatically be accepted regardless of the filter bit. Table 22-2: Filter/Mask Truth Table The acceptance filter looks at incoming messages for the EXIDEN bit to determine how to compare the identifiers. If the EXIDEN bit is clear, the message is a standard frame, and only filters with the EXIDEN bit clear are compared. If the EXIDEN bit is set, the message is an extended frame, and only filters with the EXIDEN bit set are compared. Configuring the RXM1:RXM0 bits to 01 or 10 can override the EXIDEN bit. As shown in the Receive Buffers Block Diagram, Figure 22-14, RXF0 and RXF1 filters with RXM0 mask are associated with RXB0. The filters RXF2, RXF3, RXF4, and RXF5 and the mask RXM1 are associated with RXB1. When a filter matches and a message is loaded into the receive buffer, the number of the filter that enabled the message reception is coded into a portion of the RXBnCON register. The RXB1CON register contains the FILHIT2:FILHIT0 bits. They are coded as shown in Table 22-3. Table 22-3: Acceptance Filter Mask Bit n Filter Bit n Message Identifier bit Accept or reject bit n 0x x Accept 10 0 Accept 10 1 Reject 11 0 Reject 11 1 Accept Legend: x = 0 don’t care. FILHIT2:FILHIT0 Acceptance Filter Comment 000(1) RXF0 Only if RX0DBEN = 1 001(1) RXF1 Only if RX0DBEN = 1 010 RXF2 — 011 RXF3 — 100 RXF4 — 101 RXF5 — Note 1: Is only valid if the RX0DBEN bit is set. 39500 18C Reference Manual.book Page 52 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-53 Section 22. CAN CAN 22 The coding of the RX0DBEN bit enables these 3 bits to be used similarly to the FILHIT bits and to distinguish a hit on filter RXF0 and RXF1 in either RXB0 or overrun into RXB1. 111 = Acceptance Filter 1 (RXF1) 110 = Acceptance Filter 0 (RXF0) 001 = Acceptance Filter 1 (RXF1) 000 = Acceptance Filter 0 (RXF0) If the RX0DBEN bit is clear, there are 6 codes corresponding to the 6 filters. If the RX0DBEN bit is set, there are 6 codes corresponding to the 6 filters plus 2 additional codes corresponding to RXF0 and RXF1 filters overrun to RXB1. If more than 1 acceptance filter matches, the FILHIT bits will encode the lowest binary value of the filters that matched. In other words, if filter 2 and filter 4 match, FILHIT will code the value for 2. This essentially prioritizes the acceptance filters with lower numbers having priority. Figure 22-16 shows a block diagram of the message acceptance filters. Figure 22-16:Message Acceptance Filter Acceptance Filter Register Acceptance Mask Register RxRqst Message Assembly Buffer RXFn0 RXFn1 RXFnn RXMn0 RXMn1 RXMnn Identifier 39500 18C Reference Manual.book Page 53 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-54  2000 Microchip Technology Inc. 22.9.3 Receiver Overrun An overrun condition occurs when the MAB has assembled a valid received message, the message is accepted through the acceptance filters, however, the receive buffer associated with the filter has not been designated as clear of the previous message. The overrun error flag, RXnOVR and the EERIF bit will be set and the message in the MAB will be discarded. While in the overrun situation, the module will stay synchronized with the CAN bus and is able to transmit messages but will discard all incoming messages destined for the overrun buffer. If the RX0DBEN bit is clear, RXB1 and RXB0 operate independently. When this is the case, a message intended for RXB0 will not be diverted into RXB1 if RXB0 contains an unread message and the RX0OVFL bit will be set. If the RX0DBEN bit is set, the overrun for RXB0 is handled differently. If a valid message is received for RXB0 and RXFUL = 1 indicates that RXB0 is full and RXFUL = 0 indicates that RXB1 is empty, the message for RXB0 will be loaded into RXB1. An overrun error will not be generated for RXB0. If a valid message is received for RXB0 and RXFUL = 1 and RXFUL = 1 indicating that both RXB0 and RXB1 are full the message will be lost and an overrun will be indicated for RXB1. If the RX0DBEN bit is clear, there are 6 codes corresponding to the 6 filters. If the RX0DBEN bit is set, there are 6 codes corresponding to the 6 filters plus 2 additional codes corresponding to RXF0 and RXF1 filters overrun to RXB1. These codes are given in Table 22-4. Table 22-4: Buffer Reception and Overflow Truth Table Message Matches Filter 0 or 1 Message Matches Filter 2,3,4,5 RXFUL0 Bit RXFUL1 Bit RX0DBEN Bit Action Action 0 0 XX X None No message received 0 1 X0 X MAB → RXB1 Message for RXB1, RXB1 available 0 1 X1 X MAB discarded RX1OVFL = 1 Message for RXB1, RXB1 full 1 0 0X X MAB → RXB0 Message for RXB0, RXB0 available 1 0 1X 0 MAB discarded RX0OVFL = 1 Message for RXB0, RXB0 full, RX0DBEN not enabled 1 0 10 1 MAB → RXB1 Message for RXB0, RXB0 full, RX0DBEN enabled, RXB1 available 1 0 11 1 MAB discarded RX1OVFL = 1 Message for RXB0, RXB0 full, RX0DBEN enabled, RXB1 full 1 1 0X X MAB → RXB0 Message for RXB0 and RXB1, RXB0 available 1 1 1X 0 MAB discarded RX0OVFL = 1 Message for RXB0 and RXB1, RXB0 full, RX0DBEN not enabled 1 1 10 1 MAB → RXB1 Message for RXB0 and RXB1, RXB0 full, RX0DBEN enabled, RXB1 available 1 1 11 1 MAB discarded RX1OVFL = 1 Message for RXB0 and RXB1, RXB0 full, RX0DBEN enabled, RXB1 full Legend: X = Don’t care. 39500 18C Reference Manual.book Page 54 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-55 Section 22. CAN CAN 22 22.9.4 Effects of a RESET Upon any RESET the CAN module has to be initialized. All registers are set according to the reset values. The content of a received message is lost. The initialization is discussed in Section 22.8. 22.9.5 Baud Rate Setting All nodes on any particular CAN bus must have the same nominal bit rate. The Baud Rate is set once during the initialization mode of the CAN module. After that the baud Rate is not changed again. Section 22.12 explains the setting of the Baud Rate. 22.9.6 Receive Errors The CAN module will detect the following receive errors: • Cyclic Redundancy Check (CRC) Error • Bit Stuffing Error • Invalid message receive error. These receive errors do not generate an interrupt. However, the receive error counter is incremented by one in case one of these errors occur. The RXWARN bit indicates that the Receive Error Counter has reached the CPU Warning limit of 96 and an interrupt is generated. 22.9.6.1 Cyclic Redundancy Check (CRC) Error With the Cyclic Redundancy Check, the transmitter calculates special check bits for the bit sequence from the start of a frame until the end of the Data Field. This CRC sequence is transmitted in the CRC Field. The receiving node also calculates the CRC sequence using the same formula and performs a comparison to the received sequence. If a mismatch is detected, a CRC error has occurred and an Error Frame is generated. The message is repeated. The receive error interrupt counter is incremented by one. An Interrupt will only be generated if the error counter passes a threshold value. 22.9.6.2 Bit Stuffing Error If in between Start of Frame and CRC Delimiter 6 consecutive bits with the same polarity are detected, the bit-stuffing rule has been violated. A Bit-Stuffing error occurs and an Error Frame is generated. The message is repeated. No Interrupt will be generated upon this event. 22.9.6.3 Invalid Message Received Error If any type of error occurs during reception of a message, an error will be indicated by the IXRIF bit. This bit can be used (optionally with an interrupt) for autobaud detection with the device in listen-only mode. This error is not an indicator that any action needs to occur, but an indicator that an error has occurred on the CAN bus. 39500 18C Reference Manual.book Page 55 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-56  2000 Microchip Technology Inc. 22.9.6.4 Rules for Modifying the Receive Error Counter The Receive Error Counter is modified according to the following rules: • When the receiver detects an error, the Receive Error Counter is incremented by 1, except when the detected error was a Bit Error during the transmission of an Active Error Flag or an Overload Flag. • When the receiver detects a "dominant" bit as the first bit after sending an Error Flag the Receive Error Counter will be incremented by 8. • If a Receiver detects a Bit Error while sending an Active Error Flag or an Overload Flag the Receive Error Counter is incremented by 8. • Any Node tolerates up to 7 consecutive "dominant" bits after sending an Active Error Flag, Passive Error Flag or an Overload Flag. After detecting the 14th consecutive "dominant" bit (in case of an Active Error Flag or an Overload flag) or after detecting the 8th consecutive "dominant" following a passive error flag, and after each sequence of additional eight consecutive "dominant" bits every Transmitter increases its Transmission Error Counter and every Receiver increases its Receive Error Counter by 8. • After a successful reception of a message (reception without error up to the ACK slot and the successful sending of the ACK bit), the Receive Error Counter is decreased by one, if the Receive Error Counter was between 1 and 127. If the Receive Error Counter was 0 it will stay 0. If the Receive Error Counter was greater than 127, it will change to a value between 119 and 127. 22.9.7 Receive Interrupts Several Interrupts are linked to the message reception. The receive interrupts can be broken up into two separate groups: • Receive Error Interrupts • Receive interrupts 22.9.7.1 Receive Interrupt A message has been successfully received and loaded into one of the receive buffers. This interrupt is activated immediately after receiving the End of Frame (EOF) field. Reading the RXnIF flag will indicate which receive buffer caused the interrupt. Figure 22-17 depicts when the receive buffer interrupt flag RXnIF will be set. 22.9.7.2 Wake-up Interrupt The Wake-up Interrupt sequences are described in Section 22.7.2.2. 39500 18C Reference Manual.book Page 56 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-57 Section 22. CAN CAN 22 Figure 22-17: Receive Buffer Interrupt Flag SOF ID10 ID9 ID8 ID7 ID6 ID5 ID4 ID3 ID2 ID1 RTR IDE RB0 DLC3 DLC2 STUFF DLC1 DLC0 CRC14 CRC13 CRC12 CRC11 CRC10 CRC9 CRC8 CRC7 CRC6 CRC5 CRC4 CRC3 CRC2 CRC1 CRC0 CRCDEL ACK SIST BIT ACK DELIMITER EOF EOF EOF EOF EOF EOF EOF ID0 RECEIVE BUFFER INTERRUPT FLAG DATA CAN BIT TIMING CAN BIT NAMES 39500 18C Reference Manual.book Page 57 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-58  2000 Microchip Technology Inc. 22.9.7.3 Receive Error Interrupts A receive error interrupt will be indicated by the ERRIF bit. This bit shows that an error condition occurred. The source of the error can be determined by checking the bits in the Communication Status Register COMSTAT. The bits in this register are related to receive and transmit errors. The following subsequences will show which flags are linked to the receive errors. 22.9.7.3.1 Invalid Message Received Interrupt If any type of error occurred during reception of the last message, an error will be indicated by the IXRIF bit. The specific error that occurred is unknown. This bit can be used (optionally with an interrupt) for autobaud detection with the device in listen only mode. This error is not an indicator that any action needs to occur, but an indicator that an error has occurred on the CAN bus. 22.9.7.3.2 Receiver Overrun Interrupt The RXnOVR bit indicates that an Overrun condition occurred. An overrun condition occurs when the Message Assembly Buffer (MAB) has assembled a valid received message, the message is accepted through the acceptance filters, however, the receive buffer associated with the filter is not clear of the previous message. The overflow error interrupt will be set and the message is discarded. While in the overrun situation, the module will stay synchronized with the CAN bus and is able to transmit and receive messages. 22.9.7.4 Receiver Warning Interrupt The RXWARN bit indicates that the Receive Error Counter has reached the CPU Warning limit of 96. When RXWARN transitions from a 0 to a 1, it will cause the Error Interrupt Flag ERRIF to become set. This bit cannot be manually cleared, as it should remain an indicator that the Receive Error Counter has reached the CPU Warning limit of 96. The RXWARN bit will become clear automatically if the Receive Error Counter becomes less than or equal to 95. The ERRIF bit can be manually cleared allowing the interrupt service routine to be exited without affecting the RXWARN bit. 22.9.7.5 Receiver Error Passive The RXBP bit indicates that the Receive Error Counter has exceeded the Error Passive limit of 127 and the module has gone to Error Passive state. When the RXBP bit transitions from a 0 to a 1, it will cause the Error Interrupt Flag to become set. The RXBP bit cannot be manually cleared, as it should remain an indicator that the Bus is in Error State Passive. The RXBP bit will become clear automatically if the Receive Error Counter becomes less than or equal to 127. The ERRIF bit can be manually cleared allowing the interrupt service routine to be exited without affecting the RXBP bit. 22.9.8 Receive Modes The RXM1:RXM0 bits will set special receive modes. Normally, these bits are set to 00 to enable reception of all valid messages as accepted by the acceptance filters. In this case, the determination of whether or not to receive standard or extended messages is determined by the EXIDEN bit in the Acceptance Filter Registers. If the RXM1:RXM0 bits are set to 01 or 10, the receiver will accept only messages with standard or extended identifiers respectively. If an acceptance filter has the EXIDEN bit such that it does not correspond with the RXM1:RXM0 mode, that acceptance filter is rendered useless. These 2 modes of RXM1:RXM0 bits can be used in systems where it is known that only standard or extended messages will be on the bus. If the RXM1:RXM0 bits are set to 11, the buffer will receive all messages regardless of the values of the acceptance filters. Also, if a message has an error before the End of Frame, that portion of the message assembled in the Message Assembly Buffer (MAB) before the error frame will be loaded into the buffer. This mode may have some value in debugging a CAN system. 39500 18C Reference Manual.book Page 58 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-59 Section 22. CAN CAN 22 22.9.8.1 Listen Only Mode If the receive only mode is activated, the module on the CAN bus is passive. That means that no error flags or acknowledge signals are sent. The error counters are deactivated in this state. The receive only mode can be used for detecting the baud rate on the CAN bus. For this it is necessary that there are at least two further nodes, which communicate with each other. The baud rate can be detected empirically by testing different values. This mode is also useful as a bus monitor without influencing the data traffic. 22.9.8.2 Error Recognition Mode The module can be set to ignore all errors and receive any message. The error recognition mode is activated by configuring the RXM1:RXM0 bits (RXBnCON registers) = ’11’. In this mode the data which is in the message assembly buffer until the error time is copied in the receive buffer and can be read via the CPU interface. 39500 18C Reference Manual.book Page 59 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-60  2000 Microchip Technology Inc. 22.10 Transmission This subsection describes how the CAN module is used for receiving CAN messages. 22.10.1 Real Time Communication and Transmit Message Buffering For an application to effectively transmit messages in real time, the CAN nodes must be able to dominate and hold the bus assuming that nodes messages are of a high enough priority to win arbitration on the bus. If a node only has 1 transmission buffer, it must transmit a message, then release the bus while the CPU reloads the buffer. If a node has two transmission buffers, one buffer could be transmitting while the second buffer is being reloaded. However, the CPU would need to maintain tight tracking of the bus activity to ensure that the second buffer is reloaded before the first message completes. Typical applications require three transmit message buffers. Having three buffers, one buffer can be transmitting, the second buffer can be ready to transmit as soon as the first is complete, and the third can be reloaded by the CPU. This eases the burden of the software to maintain synchronization with the bus (see Figure 22-18). Additionally, having three buffers allows some degree of prioritizing of the outgoing messages. For example, the application software may have a message enqueued in the second buffer while it is working on the third buffer. The application may require that the message going into the third buffer is of higher importance than the one already enqueued. If only 2 buffers are available, the enqueued message would have to be deleted and replaced with the third. The process of deleting the message may mean losing control of the bus. With 3 buffers, both the second and the third message can be enqueued, and the module can be instructed that the third message is higher priority than the second. The third message will be the next one sent followed by the second. 22.10.2 Transmit Message Buffers The CAN module has three transmit buffers. Each of the three buffers occupies 14 bytes of data. Eight of the bytes are the maximum 8 bytes of the transmitted message. Five bytes hold the standard and extended identifiers and other message arbitration information. The last byte is a control byte associated with each message. The information in this byte determines the conditions under which the message will be transmitted and indicates status of the transmission of the message. The TXBnIF bit will be set and the TXREQ bit will be clear, indicating that the message buffer has completed a transmission. The CPU will then load the message buffer with the contents of the message to be sent. At a minimum, the standard identifier register TXBnSIDH and TXBnSIDL must be loaded. If data bytes are present in the message, the TXBnDm registers are loaded. If the message is to use extended identifiers, the TXBnEIDm registers are loaded and the EXIDEN bit is set. Prior to sending the message, the user must initialize the TXIE bit to enable or disable an interrupt when the message is sent. The user must also initialize the transmit priority. Figure 22-18 shows a block diagram of the transmit buffers. Figure 22-18:Transmit Buffers TXREQ TXB0 TXABT TXLARB TXERR TXBUFE MESSAGE Message Queue Control Transmit Byte Sequencer TXREQ TXB1 TXABT TXLARB TXERR TXBUFE MESSAGE TXREQ TXB2 TXABT TXLARB TXERR TXBUFE MESSAGE 39500 18C Reference Manual.book Page 60 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-61 Section 22. CAN CAN 22 22.10.3 Transmit Message Priority Transmit priority is a prioritization within each node of the pending transmittable messages. Prior to sending the SOF (Start of Frame), the priorities of all buffers ready for transmission are compared. The transmit buffer with the highest priority will be sent first. For example, if transmit buffer 0 has a higher priority setting than transmit buffer 1, buffer 0 will be sent first. If two buffers have the same priority setting, the buffer with the highest address will be sent. For example, if transmit buffer 1 has the same priority setting as transmit buffer 0, buffer 1 will be sent first. There are 4 levels of transmit priority. If TXPRI1:TXPRI0 for a particular message buffer is set to 11, that buffer has the highest priority. If TXPRI1:TXPRI0 for a particular message buffer is set to 10 or 01, that buffer has an intermediate priority. If TXPRI1:TXPRI0 for a particular message buffer is 00, that buffer has the lowest priority. 22.10.4 Message Transmission To initiate transmitting the message, the TXREQ bit must be set. The CAN bus module resolves any timing conflicts between setting of the TXREQ bit and the SOF time, ensuring that if the priority was changed, it is resolved correctly before SOF. When TXREQ is set the TXABT, TXLARB and TXERR flag bits will be cleared. Setting TXREQ bit does not actually start a message transmission, it flags a message buffer as enqueued for transmission. Transmission will start when the module detects an available bus for SOF. The module will then begin transmission on the message which has been determined to have the highest priority. If the transmission completes successfully on the first try, the TXREQ bit will clear and an interrupt will be generated if TXIE was set. If the message fails to transmit, one of the other condition flags will be set, the TXREQ bit will remain set indicating that the message is still pending for transmission. If the message tried to transmit but encountered an error condition, the TXERR bit will be set. In this case, the error condition can also cause an interrupt. If the message tried to transmit but lost arbitration, the TXLARB bit will be set. In this case, no interrupt is available to signal the loss of arbitration. 22.10.5 Transmit Message Aborting The system can also abort a message by clearing the TXREQ bit associated with each message buffer. Setting the ABAT bit will request an abort of all pending messages. If the message has not yet started transmission, or if the message started but is interrupted by loss of arbitration or an error; the abort will be processed. The abort is indicated when the module sets the TXABT bit, and the TXnIF flag is not automatically set. 39500 18C Reference Manual.book Page 61 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-62  2000 Microchip Technology Inc. Figure 22-19:Transmit Flowchart Start Is CAN bus available to start transmission No Examine TXPRI <1:0> to Are any TXREQ ? bits = 1 The message transmission sequence begins when the device determines that the TXREQ for any of the transmit registers has been set. Clear: TXABT, TXLARB, and TXERR Yes ? Does TXREQ=0 ABAT =1 Clearing the TXREQ bit while it is set, or setting the ABAT bit before the message has started transmission will abort the message. No Begin transmission (SOF) Abort Transmission: Was message transmitted successfully? No Yes Set TXREQ=0 Is TXIE=1? Generate Interrupt Yes Yes Set TXABT=1 Set Set TXERR=1 Yes No Determine Highest Priority Message No ? Does TXLARB=1? The TXIE bit determines if an interrupt should be generated when a message is successfully transmitted. END Does TXREQ=0 or TXABT =1 ? Yes No TXBUFE=1 Yes A message can also be aborted if a message error or lost arbitration condition occurred during transmission. Arbitration lost during transmission 39500 18C Reference Manual.book Page 62 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-63 Section 22. CAN CAN 22 22.10.6 Transmit Boundary Conditions The module handles transmit commands which are not necessarily synchronized to the CAN bus message framing time. 22.10.6.1 Clearing TXREQ bit as a Message Starts The TXREQ bit can be cleared just when a message is starting transmission, with the intent of aborting the message. If the message is not being transmitted, the TXABT bit will be set, indicating that the Abort was successfully processed. When the user clears the TXREQ bit and the TXABT bit is not set two cycles later, the message has already begun transmission. If the message is being transmitted, the abort is not immediately processed, at some point later, the TXnIF Interrupt Flag or the TXABT bit is set. If transmission has begun the message will only be aborted if either an error or a loss of arbitration occurs. 22.10.6.2 Setting TXABT bit as a Message Starts Setting the ABAT bit will abort all pending transmit buffers and has the function of clearing all of the TXREQ bits for all buffers. The boundary conditions are the same as clearing the TXREQ bit. 22.10.6.3 Clearing TXREQ bit as a Message Completes The TXREQ bit can be cleared when a message is just about to successfully complete transmission. Even if the TXREQ bit is cleared by the Data bus a short time before it will be cleared by the successful transmission of the message, the TXnIF flag will still be set due to the successful transmission. 22.10.6.4 Setting TXABT bit as a Message Completes The boundary conditions are the same as clearing the TXREQ bit. 22.10.6.5 Clearing TXREQ bit as a Message Loses Transmission The TXREQ bit can be cleared when a message is just about to be lost to arbitration or an error. If the TXREQ signal falls before the loss of arbitration signal or error signal, the result will be like clearing TXREQ during transmission. When the arbitration is lost or the error is set, the TXABT bit will be set, as it will see that an error has occurred while transmitting, and that the TXREQ bit was not set. If the TXREQ bit falls after the arbitration signal has entered the block, the result will be like clearing TXREQ during an inactive transmit time. The TXABT bit will be set. 22.10.6.6 Setting TXABT bit as a Message Loses Transmission The boundary conditions are the same as clearing the TXREQ bit. 39500 18C Reference Manual.book Page 63 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-64  2000 Microchip Technology Inc. 22.10.7 Effects of a RESET Upon any RESET the CAN module has to be initialized. All registers are set according to the reset values. The content of a received message is lost. The initialization is discussed in Section 22.8. 22.10.8 Baud Rate Setting All nodes on any particular CAN bus must have the same nominal bit rate. The baud rate is set once during the initialization phase of the CAN module. After that, the baud rate is not changed again. Section 22.12 explains the setting of the Baud Rate. 22.10.9 Transmit Message Aborting The system can also abort a message by clearing the TXREQ bit associated with each message buffer. Setting the ABAT bit will request an abort of all pending messages (see Figure 22-21). A queued message is aborted by clearing the TXREQ bit. Aborting a queued message is illustrated in Figure 22-20. If the message has not yet started transmission, or if the message started but is interrupted by loss of arbitration or an error; the abort will be processed. The abort is indicated when the module sets the TXABT bits. If the message has started to transmit, it will attempt to transmit the current message fully (see Figure 22-22). If the current message is transmitted fully, and is not lost to arbitration or an error, the TXABT bit will not be set, because the message was transmitted successfully. Likewise, if a message is being transmitted during an abort request, and the message is lost to arbitration (see Figure 22-23) or an error, the message will not be re-transmitted, and the TXABT bit will be set, indicating that the message was successfully aborted. Figure 22-20:Abort Queued Message 1 2 - Processor sets TXREQ while module receiving/transmitting message. Module continues with CAN message. - Processor clears TXREQ while module looking for 11 recessive bits. CAN BUS 3 TXREQ - Another module takes the available transmit slot. CANTX0 TXIF TXABT Module aborts pending transmission, sets TXABT bit in 2 clocks. 1 2 3 39500 18C Reference Manual.book Page 64 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-65 Section 22. CAN CAN 22 Figure 22-21:Abort All Messages Figure 22-22:Failed Abort During Transmission 1 2 - Processor sets TXREQ while module receiving/transmitting message. Module continues with CAN message. - Processor sets ABAT while module looking for 11 recessive bits. Module clears TXREQ bits. CAN BUS 3 TXREQ - Another module takes the available transmit slot. CANTX0 TXIF TXABT ABAT Module aborts pending transmission, sets TXABT bit. 1 2 3 1 2 - Processor sets TXREQ while module receiving/transmitting message. Module continues with CAN message. - Module detects 11 recessive bits. Module begins transmission of queued message. CAN BUS TXREQ - Processor clears TXREQ requesting message abort. Abort cannot be acknowledged. CANTX0 TXIF TXABT 3 4 - At successful completion of transmission, TXREQ bit remains clear and TXIF bit set. TXABT remains clear. 1 2 3 4 39500 18C Reference Manual.book Page 65 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-66  2000 Microchip Technology Inc. Figure 22-23:Loss of Arbitration During Transmission 22.10.10 Transmission Errors The CAN module will detect the following transmission errors: • Acknowledge Error • Form Error • Bit Error These transmission errors will not necessarily generate an interrupt but are indicated by the transmission error counter. However, each of these errors will cause the transmission error counter to be incremented by one. Once the value of the error counter exceeds the value of 96, the ERRIF and the TXWARN bit are set. Once the value of the error counter exceeds the value of 96 an interrupt is generated and the TXWARN bit in the error flag register is set. An example transmission error is illustrated in Figure 22-24. Figure 22-24:Error During Transmission 1 2 4 5 - Processor sets TXREQ while module inactive. TXLARB bit cleared. - Module in inactive state. Module begins transmission of queued message. - Module waits for 11 recessive bits before re-trying transmission of queued message. - At successful completion of transmission, TXREQ bit cleared and TXIF bit set. CAN BUS 3 TXREQ - Message loses arbitration. Module releases bus and sets TXLARB bit. CANTX0 TXIF TXLARB 1 2 3 4 5 1 2 4 5 - Processor sets TXREQ while module inactive. TXERR bit is cleared. - Module in inactive state. Module begins transmission of queued message. - Module waits for 11 recessive bits before re-trying transmission of queued message. - At successful completion of transmission, TXREQ bit cleared and TXIF bit set. CAN BUS 3 TXREQ - Module detects error during transmission, releases bus and sets TXERR bit. CANTX0 TXIF TXERR 1 2 3 4 5 39500 18C Reference Manual.book Page 66 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-67 Section 22. CAN CAN 22 22.10.10.1 Acknowledge Error In the Acknowledge Field of a message, the transmitter checks if the Acknowledge Slot (which it has sent out as a recessive bit) contains a dominant bit. If not, no other node has received the frame correctly. An Acknowledge Error has occurred and the message has to be repeated. No Error Frame is generated. 22.10.10.2 Form Error lf a transmitter detects a dominant bit in one of the four segments including End of Frame, lnterframe Space, Acknowledge Delimiter or CRC Delimiter; then a Form Error has occurred and an Error Frame is generated. The message is repeated. 22.10.10.3 Bit Error A Bit Error occurs if a transmitter sends a dominant bit and detects a recessive bit. In the case where the transmitter sends a recessive bit and a dominant bit is detected during the Arbitration Field and the Acknowledge Slot, no bit error is generated because normal arbitration is occurring. 22.10.10.4 Rules for Modifying the Transmit Error Counter The Transmit Error Counter is modified according to the following rules: • When the Transmitter sends an error flag the Transmit Error Counter is increased by 8 with the following exceptions. In these two exceptions, the Transmit Error Counter is not changed. - If the transmitter is "error passive" and detects an acknowledgment error because of not detecting a "dominant" ACK, and does not detect a "dominant" bit while sending a Passive Error Flag. - If the Transmitter sends an Error Flag because of a bit-stuffing Error occurred during arbitration whereby the Stuffbit is located before the RTR bit, and should have been "recessive", and has been sent as "recessive" but monitored as "dominant". • If a Transmitter detects a Bit Error while sending an Active Error Flag or an Overload Flag the Transmit Error Counter is increased by 8. • Any Node tolerates up to 7 consecutive "dominant" bits after sending an Active Error Flag, Passive Error Flag or an Overload Flag. After detecting the 14th consecutive "dominant" bit (in case of an Active Error Flag or an Overload flag) or after detecting the 8th consecutive "dominant" following a passive error flag, and after each sequence of eight additional consecutive "dominant" bits, every Transmitter increases its Transmission Error Counter and every Receiver increases its Receive Error Counter by 8. • After the successful transmission of a message (getting an acknowledge and no error until End of Frame is finished) the Transmit Error Counter is decreased by one unless it was already 0. 39500 18C Reference Manual.book Page 67 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-68  2000 Microchip Technology Inc. 22.10.11 Transmission Interrupts There are several interrupts linked to the message transmission. The transmission interrupts can be broken up into two groups: • Transmission interrupts • Transmission error interrupts 22.10.11.1 Transmit Interrupt At least one of the three transmit buffers is empty (not scheduled) and can be loaded to schedule a message for transmission. Reading the TXIF flags will indicate which transmit buffer is available and caused the interrupt. 22.10.11.2 Transmission Error Interrupts A transmission error interrupt will be indicated by the ERRIF flag. This flag shows that an error condition occurred. The source of the error can be determined by checking the error flags in the Communication Status register COMSTAT. The flags in this register are related to receive and transmit errors. The following subsequences will show which flags are linked to the transmit errors. 22.10.11.3 Transmitter Warning Interrupt The TXWARN bit indicates that the Transmit Error Counter has reached the CPU Warning limit of 96. When this bit transitions from a 0 to a 1, it will cause the Error Interrupt Flag to become set. The TXWARN bit cannot be manually cleared, as it should remain as an indicator that the Transmit Error Counter has reached the CPU Warning limit of 96. The TXWARN bit will become clear automatically if the Transmit Error Counter becomes less than or equal to 95. The ERRIF flag can be manually cleared allowing the interrupt service routine to be exited without affecting the TXWARN bit. 22.10.11.4 Transmitter Error Passive The TXEP bit indicates that the Transmit Error Counter has exceeded the Error Passive limit of 127 and the module has gone to Error Passive state. When this bit transitions from a 0 to a 1, it will cause the Error Interrupt Flag to become set. The TXEP bit cannot be manually cleared, as it should remain as an indicator that the Bus is in Error State Passive. The TXEP bit will become clear automatically if the Transmit Error Counter becomes less than or equal to 127. The ERRIF flag can be manually cleared allowing the interrupt service routine to be exited without affecting the TXEP bit. 22.10.11.5 Bus Off Interrupt The TXBO bit indicates that the Transmit Error Counter has exceeded 255 and the module has gone to Bus Off state. When this bit transitions from a 0 to a 1, it will cause the Error Interrupt Flag to become set. The TXBO bit cannot be manually cleared, as it should remain as an indicator that the Bus is Off. The ERRIF flag can be manually cleared allowing the interrupt service routine to be exited without affecting the TXBO bit. 39500 18C Reference Manual.book Page 68 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-69 Section 22. CAN CAN 22 22.11 Error Detection The CAN protocol provides sophisticated error detection mechanisms. The following errors can be detected. These errors are either receive or transmit errors. Receive errors are: • Cyclic Redundancy Check (CRC) Error (see Section 22.9.6.1) • Bit Stuffing Bit Error (see Section 22.9.6.2) • lnvalid Message Received Error (see Section 22.9.6.2) The transmit errors are • Acknowledge Error (see Section 22.10.10.1) • Form Error (see Section 22.10.10.2) • Bit Error (see Section 22.10.10.3) 22.11.1 Error States Detected errors are made public to all other nodes via Error Frames. The transmission of the erroneous message is aborted and the frame is repeated as soon as possible. Furthermore, each CAN node is in one of the three error states "error active", "error passive" or "bus off" according to the value of the internal error counters. The error-active state is the usual state where the bus node can transmit messages and active Error Frames (made of dominant bits) without any restrictions. In the error-passive state, messages and passive Error Frames (made of recessive bits) may be transmitted. The bus-off state makes it temporarily impossible for the station to participate in the bus communication. During this state, messages can neither be received nor transmitted. 22.11.2 Error Modes and Error Counters The CAN controller contains the two error counters Receive Error Counter (RXERRCNT) and Transmit Error Counter (TXERRCNT). The values of both counters can be read by the CPU. These counters are incremented or decremented according to the CAN bus specification. The CAN controller is error active if both error counters are below the error passive limit of 128. It is error passive if at least one of the error counters equals or exceeds 128. It goes bus off if the Transmit Error Counter equals or exceeds the bus off limit of 256. The device remains in this state, until the bus off recovery sequence is finished, which is 128 consecutive 11 recessive bit times. Additionally, there is a error state warning flag bit, EWARN, which is set if at least one of the error counters equals or exceeds the error warning limit of 96. EWARN is reset if both error counters are less than the error warning limit. 39500 18C Reference Manual.book Page 69 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-70  2000 Microchip Technology Inc. Figure 22-25:Error Modes 22.11.3 Error Flag Register The values in the error flag register indicate which error(s) caused the Error Interrupt Flag. The RXXOVR Error Flags have a different function than the other Error Flag bits in this register. The RXXOVR bits must be cleared in order to clear the ERRIF interrupt flag. The other Error Flag bits in this register will cause the ERRIF interrupt flag to become set as the value of the Transmit and Receive Error Counters crosses a specific threshold. Clearing the ERRIF interrupt flag in these cases will allow the interrupt service routine to be exited without recursive interrupt occurring. It may be desirable to disable specific interrupts after they have occurred once to stop the device from interrupting repeatedly as the Error Counter moves up and down in the vicinity of a threshold value. Bus Off Error Active Error Passive RXERRCNT > 127 or TXERRCNT > 127 RXERRCNT < 127 or TXERRCNT < 127 TXERRCNT > 255 128 occurrences of 11 consecutive "recessive" bits Reset 39500 18C Reference Manual.book Page 70 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-71 Section 22. CAN CAN 22 22.12 Baud Rate Setting All nodes on any particular CAN bus must have the same nominal bit rate. The CAN bus uses NRZ coding which does not encode a clock. Therefore the receivers independent clock must be recovered by the receiving nodes and synchronized to the transmitters clock. In order to set the baud rate the following bits have to be initialized: • Synchronization Jump Width (see Section 22.12.6.2) • Baud rate prescaler (see Section 22.12.2) • Phase segments (see Section 22.12.4) • Length determination of Phase segment 2 (see Section 22.12.4) • Sample Point (see Section 22.12.5) • Propagation segment bits (see Section 22.12.3) 22.12.1 Bit Timing As oscillators and transmission time may vary from node to node, the receiver must have some type of PLL synchronized to data transmission edges to synchronize and maintain the receiver clock. Since the data is NRZ coded, it is necessary to include bit-stuffing to ensure that an edge occurs at least every 6 bit times, to maintain the Digital Phase Lock Loop (DPLL) synchronization. Bus timing functions executed within the bit time frame, such as synchronization to the local oscillator, network transmission delay compensation, and sample point positioning, are defined by the programmable bit timing logic of the DPLL. All controllers on the CAN bus must have the same baud rate and bit length. However, different controllers are not required to have the same master oscillator clock. At different clock frequencies of the individual controllers, the baud rate has to be adjusted by adjusting the number of time quanta in each segment. The Nominal Bit Time can be thought of as being divided into separate non-overlapping time segments. These segments are shown in Figure 22-26. • Synchronization segment (Sync Seg) • Propagation time segment (Prop Seg) • Phase buffer segment 1 (Phase1 Seg) • Phase buffer segment 2 (Phase2 Seg) The time segments and also the nominal bit time are made up of integer units of time called time quanta or TQ. By definition, the Nominal Bit Time has a minimum of 8 TQ and a maximum of 25 TQ. Also, by definition the minimum nominal bit time is 1 usec, corresponding to a maximum 1 MHz bit rate. Figure 22-26:CAN Bit Timing Input Signal Sync Prop Segment Phase Segment 1 Phase Segment 2 Sync Sample Point TQ 39500 18C Reference Manual.book Page 71 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-72  2000 Microchip Technology Inc. 22.12.2 Prescaler Setting There is a programmable prescaler, with integral values ranging at least from 1 to 64, in addition to a fixed divide by 2 for clock generation. The Time Quanta (TQ) is a fixed unit of time derived from the oscillator period. Time quanta is defined as: Equation 22-1:Time Quanta for Clock Generation Example 22-1:Calculation for Fosc = 16 MHz Example 22-2:Calculation for Fosc = 32 MHz Example 22-3:Calculation for Fosc = 32 MHz and 25 TQ The frequencies of the oscillators in the different nodes must be coordinated in order to provide a system-wide specified time quantum. This means that all oscillators must have a Tosc that is a integral divisor of TQ. 22.12.3 Propagation Segment This part of the bit time is used to compensate physical delay times within the network. These delay times consist of the signal propagation time on the bus line and the internal delay time of the nodes. The delay is calculated as the round trip from transmitter to receiver as twice the signal's propagation time on the bus line, the input comparator delay, and the output driver delay. The Propagation Segment can be programmed from 1 TQ to 8 TQ by setting the PRSE2:PRSEG0 bits. 22.12.4 Phase Segments The phase segments are used to optimally locate the sampling of the received bit within the transmitted bit time. The sampling point is between Phase1 Segment and Phase2 Segment. These segments are lengthened or shortened by resynchronization. The end of the Phase1 Segment determines the sampling point within a bit period. The segment is programmable from 1 TQ to 8 TQ. Phase2 Segment provides delay to the next transmitted data transition. The segment is programmable from 1 TQ to 8 TQ or it may be defined to be equal to the greater of Phase1 Segment or the Information Processing Time. The phase segment 1 is initialized by setting bits SEG1PH2:SEG1PH0, and phase segment 2 is initialized by setting SEG2PH2:SEG2PH0. TQ 2 ( ) BaudRate + 1 TOSC = ⋅ ⋅ Where Baud Rate is the binary value of BRP <5:0> If FOSC = 16 MHz, BRP5:BRP0 = 00h, and Nominal Bit Time = 8 TQ; then TQ = 125 nsec and Nominal Bit Rate = 1 MHz If FOSC = 32 MHz, BRP5:BRP0 = 01h, and Nominal Bit Time = 8 TQ; then TQ = 125 nsec and Nominal Bit Rate = 1 MHz If FOSC = 32 MHz, BRP5:BRP0 = 3Fh, and Nominal Bit Time = 25 TQ; then TQ = 4 usec and Nominal Bit Rate = 10 kHz 39500 18C Reference Manual.book Page 72 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-73 Section 22. CAN CAN 22 22.12.5 Sample Point The sample point is the point of time at which the bus level is read and interpreted as the Value of that respective bit. The location is at the end of Phase Segment 1. If the bit timing is slow and contains many TQ, it is possible to specify multiple sampling of the bus line at the sample point. The level determined by the CAN bus then corresponds to the result from the majority decision of three values. The majority samples are taken at the sample point and twice before with a distance of TQ/2. The CAN module allows to chose between sampling three times at the same point or once at the same point. This is done by setting or clearing the SAM bit (BRG2CON register). 22.12.6 Synchronization To compensate for phase shifts between the oscillator frequencies of the different bus stations, each CAN controller must be able to synchronize to the relevant signal edge of the incoming signal. When an edge in the transmitted data is detected, the logic will compare the location of the edge to the expected time (Synchronous Segment). The circuit will then adjust the values of Phase1 Segment and Phase2 Segment. There are 2 mechanisms used to synchronize. 22.12.6.1 Hard Synchronization Hard Synchronization is only done whenever there is a 'recessive' to 'dominant' edge during Bus Idle, indicating the start of a message. After hard synchronization, the bit time counters are restarted with Synchronous Segment. Hard synchronization forces the edge which has caused the hard synchronization to lie within the synchronization segment of the restarted bit time. Due to the rules of synchronization, if a hard synchronization is done, there will not be a resynchronization within that bit time. 22.12.6.2 Resynchronization As a result of resynchronization Phase Segment 1 may be lengthened or Phase Segment 2 may be shortened. The amount of lengthening or shortening (SJW1:SJW0) of the phase buffer segment has an upper bound given by the resynchronization jump width bits. The value of the synchronization jump width will be added to Phase Segment 1 or subtracted from Phase Segment 2. The resynchronization jump width is programmable between 1 TQ and 4 TQ. Clocking information will only be derived from transitions of recessive to dominant bus states. The property that only a fixed maximum number of successive bits have the same value ensures resynchronizing a bus unit to the bit stream during a frame (e.g. bit-stuffing). The Phase Error of an edge is given by the position of the edge relative to Synchronous Segment, measured in Time Quanta. The Phase Error is defined in magnitude of TQ as follows: • e = 0 if the edge lies within Synchronous Segment. • e > 0 if the edge lies before the Sample Point. • e < 0 if the edge lies after the Sample Point of the previous bit. If the magnitude of the phase error is less than or equal to the programmed value of the resynchronization jump width, the effect of a resynchronization is the same as that of a hard synchronization, If the magnitude of the phase error is larger than the resynchronization jump width, and if the phase error is positive, then Phase Segment 1 is lengthened by an amount equal to the resynchronization jump width. If the magnitude of the phase error is larger than the resynchronization jump width, and if the phase error is negative, then Phase Segment 2 is shortened by an amount equal to the resynchronization jump width. 39500 18C Reference Manual.book Page 73 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-74  2000 Microchip Technology Inc. Figure 22-27:Lengthening a Bit Period Figure 22-28:Shortening a Bit Period 22.12.7 Programming Time Segments Some requirements for programming of the time segments: Propagation Segment + Phase1 Segment > = Phase2 Segment Phase2 Segment > Synchronous Jump Width Example 22-4:Segment Time Typically, the sampling of the bit should take place at about 60 - 70% of the bit time, depending on the system parameters. Synchronous Segment = 1 TQ; Propagation Segment = 2 TQ; So setting Phase Segment 1=7TQ would place the sample at 10 TQ after the transition. This would leave 6 TQ for Phase Segment 2. Since Phase Segment 2 is 6, by the rules, the SJW1:SJW0 bits could be set to the maximum of 4 TQ. However, normally a large synchronization jump width is only necessary when the clock generation of the different nodes is inaccurate or unstable, such as using ceramic resonators. So a synchronization jump width of 1 is typically enough. Input Signal Sync Propagation Segment Phase Segment 1 Phase Segment 2 ≤ sjw Sample Nominal Actual Bit Point Bit Length Length TQ Input Signal Sync Propagation Segment Phase Segment 1 Phase Segment 2 ≤ sjw Sample Actual Nominal Bit Length TQ Point Bit Length CAN Baud Rate = 125 kHz TOSC = 50 nsec bit time = 16 TQ FOSC = 20 MHz Then: BRP5:BRP0 = 04h, → TQ = 500 nsec For: 125 kHz 39500 18C Reference Manual.book Page 74 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-75 Section 22. CAN CAN 22 22.13 Interrupts The module has several sources of interrupts. Each of these interrupts can be individually enabled or disabled. A PIR register contains interrupt flags. A PIE register contains the enables for the 8 main interrupts. A special set of read-only bits in the CANSTAT register (ICODE2:ICODE0) can be used in combination with a jump table for efficient handling of interrupts. All interrupts have one source, with the exception of the Error Interrupt. Any of the Error Interrupt sources can set the Error Interrupt Flag. The source of the Error Interrupt can be determined by reading the Communication Status (COMSTAT) register. The interrupts can be broken up into two categories: receive and transmit interrupts. The receive related interrupts are: • Receive Interrupt (see Section 22.9.7.1) • Wake-up Interrupt (see Section 22.9.7.2) • Receiver Overrun Interrupt (see Section 22.9.7.3.2) • Receiver Warning Interrupt (see Section 22.9.7.4) • Receiver Error Passive Interrupt (Section 22.9.7.5) The Transmit related interrupts are • Transmit interrupt (see Section 22.10.11.1) • Transmitter Warning Interrupt (Section 22.10.11.3) • Transmitter Error Passive Interrupt (see Section 22.10.11.4) • Bus Off Interrupt (see Section 22.10.11.5) 22.13.1 Interrupt Acknowledge Interrupts are directly associated with one or more status flags in either a PIR or COMSTAT registers. Interrupts are pending as long as one of the corresponding flags is set. The flags in the registers must be reset within the interrupt handler in order to handshake the interrupt. A flag can not be cleared if the respective condition still prevails, with the exception being interrupts that are caused by a certain value being reached in one of the Error Counter Registers. 39500 18C Reference Manual.book Page 75 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-76  2000 Microchip Technology Inc. 22.13.2 The ICODE Bits The ICODE2:ICODE0 bits are a set of read-only bits designed for efficient handling of interrupts via a jump table. The ICODE2:ICODE0 bits can only display one interrupt at a time because the interrupt bits are multiplexed into this register. Therefore, the pending interrupt with the highest priority and enabled interrupt is reflected in the ICODE2:ICODE0 bits. Once the highest priority interrupt flag has been cleared, the next highest priority interrupt code is reflected in the ICODE2:ICODE0 bits. An interrupt code for a corresponding interrupt can only be displayed if both its interrupt flag and interrupt enable are set. Table 22-5 describes the operation of the ICODE2:ICODE0 bits. Table 22-5: ICODE Bits Decode Table ICODE2:ICODE0 Boolean Expression 000 ERR•WAK•TX0•TX1•TX2•RX0•RX1 001 ERR 100 ERR•TX0 011 ERR•TX0•TX1 010 ERR•TX0•TX1•TX2 110 ERR•TX0•TX1•TX2•RX0 101 ERR•TX0•TX1•TX2•RX0•RX1 111 ERR•TX0•TX1•TX2•RX0•RX1•WAK Legend: ERR = ERRIF • ERRIE TX0 = TX0IF • TX0IE TX1 = TX1IF • TX1IE TX2 = TX2IF • TX2IE RX0 = RX0IF • RX0IE RX1 = RX1IF • RX1IE WAK = WAKIF • WAKIE 39500 18C Reference Manual.book Page 76 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-77 Section 22. CAN CAN 22 22.14 Timestamping The CAN module will generate a signal that can be selected to a timer capture input whenever a valid frame has been accepted. Because the CAN specification defines a frame to be valid if no errors occurred before the EOF field has been transmitted successfully, the timer signal will be generated right after the EOF. A pulse of one bit time is generated. 22.15 CAN Module I/O The CAN bus module communicates on up to 3 I/O pins. There are 1 or 2 transmit pins and 1 receive pin. These pins are multiplexed with normal digital I/O functions of the device. The CIOCON register controls the functions of the I/O pins. When the module is in the configuration mode, module disable mode or loopback mode, the I/O pins revert to a Port I/O function. When the module is active, the TX0 pin is always dedicated to the CAN output function. If a single ended driver is needed, then only the TX0 pin is required. If a differential driver is required, then the TX1 pin must be enabled by setting the TX1EN bit. If the bus requires an active pull-up on the line, the ENDRHI bit should be cleared. The TRIS bits associated with the transmit pins are overridden by the CAN bus modes. If the CAN module expects an output to be driving, it will be regardless of the state of the TRIS bit associated with that pin. The output buffers for the TX0 and TX1 pin are designed such that the rise and fall rate of the output signal is approximately equal as is necessary for differential drive. The module can receive the CAN input on one digital input line. 39500 18C Reference Manual.book Page 77 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-78  2000 Microchip Technology Inc. 22.16 Design Tips Question 1: My CAN module does not seem to work after a RESET. Answer 1: Ensure that you reinitialize your CAN bus module. After a RESET, the CAN bus module will automatically go into the initialization mode. Question 2: I constantly get a Receive error warning interrupt. Answer 2: Ensure that your CAN module is set up correctly. Check if the Baud rate is set correctly. 39500 18C Reference Manual.book Page 78 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39522A-page 22-79 Section 22. CAN CAN 22 22.17 Related Application Notes This subsection lists application notes that are related to this subsection of the manual. These application notes may not be written for the Mid-range family (that is they may be written for the Baseline, or the High-end), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to this section are: Title Application Note # An Introduction to the CAN Protocol AN713 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 79 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39522A-page 22-80  2000 Microchip Technology Inc. 22.18 Revision History Revision A This is the initial released revision of this document. 39500 18C Reference Manual.book Page 80 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39523A-page 23-1 Comparator Voltage Reference 23 Section 23. Comparator Voltage Reference HIGHLIGHTS This section of the manual contains the following major topics: 23.1 Introduction .................................................................................................................. 23-2 23.2 Control Register ........................................................................................................... 23-3 23.3 Configuring the Voltage Reference .............................................................................. 23-4 23.4 Voltage Reference Accuracy/Error............................................................................... 23-5 23.5 Operation During SLEEP ............................................................................................. 23-5 23.6 Effects of a RESET ...................................................................................................... 23-5 23.7 Connection Considerations.......................................................................................... 23-6 23.8 Initialization .................................................................................................................. 23-7 23.9 Design Tips .................................................................................................................. 23-8 23.10 Related Application Notes............................................................................................ 23-9 23.11 Revision History ......................................................................................................... 23-10 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39523A-page 23-2  2000 Microchip Technology Inc. 23.1 Introduction This Voltage Reference module is typically used in conjunction with the Comparator module. The Comparator module’s inputs do not require very large drive, and therefore the drive capability of this Voltage Reference is limited. The Voltage Reference is a 16-tap resistor ladder network that provides a selectable Voltage Reference. The resistor ladder is segmented to provide two ranges of VREF values and has a power-down function to conserve power when the reference is not being used. The VRCON register controls the operation of the reference (shown in Register 23-1). The block diagram is given in Figure 23-1. Within each range, the 16 steps are monotonic (i.e., each increasing code will result in an increasing output). Figure 23-1: Voltage Reference Block Diagram Table 23-1: Typical Voltage Reference with VDD = 5.0V VR3:VR0 VREF VRR = 1 VRR = 0 0000 0.00 V 1.25 V 0001 0.21 V 1.41 V 0010 0.42 V 1.56 V 0011 0.63 V 1.72 V 0100 0.83 V 1.88 V 0101 1.04 V 2.03 V 0110 1.25 V 2.19 V 0111 1.46 V 2.34 V 1000 1.67 V 2.50 V 1001 1.88 V 2.66 V 1010 2.08 V 2.81 V 1011 2.29 V 2.97 V 1100 2.50 V 3.13 V 1101 2.71 V 3.28 V 1110 2.92 V 3.44 V 1111 3.13 V 3.59 V Note 1: See parameter D312 in the "Electrical Specifications" section of the device data sheet. 8R VRR (1) VR3 VR0 16-1 Analog MUX (From VRCON<3:0>) 8R (1) R (1) R (1) R (1) R VREN (1) VREF 16 Stages 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39523A-page 23-3 Section 23. Comparator Voltage Reference Comparator Voltage Reference 23 23.2 Control Register The Voltage Reference Control register (VRCON) is shown in Register 23-1. Register 23-1: VRCON Register R/W-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 VREN VROEN VRR — VR3 VR2 VR1 VR0 bit 7 bit 0 bit 7 VREN: VREF Enable 1=VREF circuit powered on 0=VREF circuit powered down bit 6 VROEN: VREF Output Enable 1=VREF is internally connected to Comparator module’s VREF. This voltage level is also output on the VREF pin 0=VREF is not connected to the Comparator module. This voltage is disconnected from the VREF pin bit 5 VRR: VREF Range Selection 1 = 0V to 0.75 VDD, with VDD/24 step size 0 = 0.25 VDD to 0.75 VDD, with VDD/32 step size bit 4 Unimplemented: Read as '0' bit 3:0 VR3:VR0: VREF Value Selection 0 ≤ VR3:VR0 ≤ 15 When VRR = 1: VREF = (VR<3:0> / 24) • VDD When VRR = 0: VREF = 1/4 * VDD + (VR3:VR0 / 32) • VDD Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39523A-page 23-4  2000 Microchip Technology Inc. 23.3 Configuring the Voltage Reference The Voltage Reference can output 16 distinct voltage levels for each range. The equations used to calculate the output of the Voltage Reference are as follows: if VRR = 1: VREF = (VR3:VR0 / 24) x VDD if VRR = 0: VREF = (VDD x 1/4) + (VR3:VR0 / 32) x VDD The settling time of the Voltage Reference must be considered when changing the VREF output. Example 23-1 shows an example of how to configure the Voltage Reference for an output voltage of 1.25V with VDD = 5.0V. Generally the VREF and VDD of the system will be known and you need to determine the value to load into VR3:VR0. Equation 23-1 shows how to calculate the VR3:VR0 value. There will be some error since VR3:VR0 can only be an integer, and the VREF and VDD levels must be chosen so that the result is not greater then 15. Equation 23-1: Calculating VR3:VR0 VREF VDD VR3:VR0 = X 24 When VRR = 1 VREF - VDD/4 VDD VR3:VR0 = X 32 When VRR = 0 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39523A-page 23-5 Section 23. Comparator Voltage Reference Comparator Voltage Reference 23 23.4 Voltage Reference Accuracy/Error The full range of VSS to VDD cannot be realized due to the construction of the module. The transistors on the top and bottom of the resistor ladder network (Figure 23-1) keep VREF from approaching VSS or VDD. The Voltage Reference is VDD derived and therefore, the VREF output changes with fluctuations in VDD. The absolute accuracy of the Voltage Reference can be found in the Electrical Specifications parameter D311. 23.5 Operation During SLEEP When the device wakes up from SLEEP through an interrupt or a Watchdog Timer time-out, the contents of the VRCON register are not affected. To minimize current consumption in SLEEP mode, the Voltage Reference should be disabled. 23.6 Effects of a RESET A device RESET disables the Voltage Reference by clearing the VREN bit (VRCON<7>). This RESET also disconnects the reference from the VREF pin by clearing the VROEN bit (VRCON<6>) and selects the high voltage range by clearing the VRR bit (VRCON<5>). The VREF value select bits, VRCON<3:0>, are also cleared. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39523A-page 23-6  2000 Microchip Technology Inc. 23.7 Connection Considerations The Voltage Reference Module operates independently of the Comparator module. The output of the reference generator may be connected to the VREF pin if the corresponding TRIS bit is set and the VROEN bit (VRCON<6>) is set. Enabling the Voltage Reference output onto the VREF pin with an input signal present will increase current consumption. Configuring the VREF as a digital output with VREF enabled will also increase current consumption. The VREF pin can be used as a simple D/A output with limited drive capability. Due to the limited drive capability, a buffer must be used in conjunction with the Voltage Reference output for external connections to VREF. Figure 23-2 shows an example buffering technique. Figure 23-2: Voltage Reference Output Buffer Example VREF Output + – • • VREF Module R (1) ANx Note 1: R is the Voltage Reference Output Impedance and is dependent upon the Voltage Reference Configuration (the VR3:VR0 bits and the VRR bit). PIC18CXXX 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39523A-page 23-7 Section 23. Comparator Voltage Reference Comparator Voltage Reference 23 23.8 Initialization Example 23-1 shows a program sequence to configure the Voltage Reference, comparator module, and PORT pins. Example 23-1: Voltage Reference Configuration MOVLW 0x02 ; 4 Inputs Muxed to 2 comparators MOVWF CMCON ; MOVLW PORTxout ; Select PORTx pins MOVWF TRISx ; to be output MOVLW 0xA6 ; enable VREF MOVWF VRCON ; low range set VR3:VR0 = 6 CALL DELAY10 ; 10 µs delay 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39523A-page 23-8  2000 Microchip Technology Inc. 23.9 Design Tips Question 1: My VREF is not what I expect. Answer 1: Any variation of the device VDD will translate directly onto the VREF pin. Also ensure that you have correctly calculated (specified) the VDD divider which generates the VREF. Question 2: I am connecting VREF into a low impedance circuit, and the VREF is not at the expected level. Answer 2: The Voltage Reference module is not intended to drive large loads. A buffer must be used between the PICmicro’s VREF pin and the load. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39523A-page 23-9 Section 23. Comparator Voltage Reference Comparator Voltage Reference 23 23.10 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced MCU family (that is they may be written for the Base-Line, Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to Voltage Reference are: Title Application Note # Resistance and Capacitance Meter using a PIC16C622 AN611 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39523A-page 23-10  2000 Microchip Technology Inc. 23.11 Revision History Revision A This is the initial released revision of the Voltage Reference description. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39525A-page 24-1 Comparator 24 Section 24. Comparator HIGHLIGHTS This section of the manual contains the following major topics: 24.1 Introduction .................................................................................................................. 24-2 24.2 Control Register ........................................................................................................... 24-3 24.3 Comparator Configuration............................................................................................ 24-4 24.4 Comparator Operation ................................................................................................. 24-6 24.5 Comparator Reference................................................................................................. 24-6 24.6 Comparator Response Time........................................................................................ 24-8 24.7 Comparator Outputs .................................................................................................... 24-8 24.8 Comparator Interrupts.................................................................................................. 24-9 24.9 Comparator Operation During SLEEP ......................................................................... 24-9 24.10 Effects of a RESET ...................................................................................................... 24-9 24.11 Analog Input Connection Considerations................................................................... 24-10 24.12 Initialization ................................................................................................................ 24-11 24.13 Design Tips ................................................................................................................ 24-12 24.14 Related Application Notes.......................................................................................... 24-13 24.15 Revision History ......................................................................................................... 24-14 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39525A-page 24-2  2000 Microchip Technology Inc. 24.1 Introduction The comparator module contains two analog comparators. The inputs to the comparators are multiplexed with the I/O pins. The on-chip Voltage Reference (see the “Comparator Voltage Reference” section) can also be an input to the comparators. The CMCON register, shown in Register 24-1, controls the comparator input and output multiplexers. A block diagram of the comparator is shown in Figure 24-1. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39525A-page 24-3 Section 24. Comparator Comparator 24 24.2 Control Register The Comparator Control register (CMCON) is shown in Register 24-1. Register 24-1: CMCON Register R-0 R-0 R-0 R-0 R/W-0 R/W-0 R/W-0 R/W-0 C2OUT C1OUT C2INV C1INV CIS CM2 CM1 CM0 bit 7 bit 0 bit 7 C2OUT: Comparator2 Output State bit This bit indicates the output state of comparator 2. 1 = C2 VIN+ > C2 VIN– 0 = C2 VIN+ < C2 VIN– bit 6 C1OUT: Comparator1 Output State bit This bit indicates the output state of comparator 1. 1 = C1 VIN+ > C1 VIN– 0 = C1 VIN+ < C1 VIN– bit 5 C2INV: Comparator2 Inverted Output State bit 1 = Invert the state of C2 output 0 = State of C2 output is not inverted bit 4 C1INV: Comparator1 Inverted Output State bit 1 = Invert the state of C1 output 0 = State of C1 output is not inverted bit 3 CIS: Comparator Input Switch bit This bit selects which analog inputs are used as the input to the comparator. When CM2:CM0: = 001: 1 = C1 VIN– connects to ANx3 0 = C1 VIN– connects to ANx0 When CM2:CM0 = 010: 1 = C1 VIN– connects to ANx3 C2 VIN– connects to ANx2 0 = C1 VIN– connects to ANx0 C2 VIN– connects to ANx1 bit 2:0 CM2:CM0: Comparator Mode Select bits This bit selects the configuration of the two comparators with the comparator input pins and the “Comparator Voltage Reference”. See Figure 24-1 to select the CM2:CM0 state for the desired mode. The use of ANx0 through ANx3 indicates that there are four analog inputs used with the comparator module. The actual analog inputs connected to the comparator inputs will be device dependent. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39525A-page 24-4  2000 Microchip Technology Inc. 24.3 Comparator Configuration There are eight modes of operation for the comparators. The CMCON register is used to select the mode. Figure 24-1 shows the eight possible modes. The TRIS register controls the data direction of the comparator I/O pins for each mode. If the comparator mode is changed, the comparator output level may not be valid for the new mode for the delay specified in the electrical specifications of the device. Note: Comparator interrupts should be disabled during a comparator mode change, otherwise a false interrupt may occur. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39525A-page 24-5 Section 24. Comparator Comparator 24 Figure 24-1: Comparator I/O Operating Modes C1 VINVIN+ Off (Read as '0') Comparators Reset (POR Default Value) A A CM2:CM0 = 000 C2 VINVIN+ Off (Read as '0') A A C1 VINVIN+ C1OUT Two Independent Comparators A A CM2:CM0 = 010 C2 VINVIN+ C2OUT A A C1 VINVIN+ C1OUT Two Common Reference Comparators A A CM2:CM0 = 100 C2 VINVIN+ C2OUT A D C1 VINVIN+ Off (Read as '0') One Independent Comparator D D CM2:CM0 = 001 C1 VINVIN+ C1OUT A A C1 VINVIN+ Off (Read as '0') Comparators Off D D CM2:CM0 = 111 C2 VINVIN+ Off (Read as '0') D D C1 VINVIN+ C1OUT Four Inputs Multiplexed to Two Comparators A A CM2:CM0 = 110 C2 VINVIN+ C2OUT A A From VREF Module CIS = 0 CIS = 1 CIS = 0 CIS = 1 C1 VINVIN+ C1OUT Two Common Reference Comparators with Outputs A A CM2:CM0 = 101 C2 VINVIN+ C2OUT A D C2OUT Three Inputs Multiplexed to Two Comparators CM2:CM0 = 011 ANx0 ANx3 ANx1 ANx2 ANx0 ANx3 ANx1 ANx2 ANx0 ANx3 ANx1 ANx2 ANx0 ANx3 ANx1 ANx2 ANx0 ANx3 ANx1 ANx2 ANx0 ANx3 ANx1 ANx2 ANx0 ANx3 ANx1 ANx2 C1OUT C1OUT C1 VINVIN+ C1OUT A A C2 VINVIN+ C2OUT A A C2OUT ANx0 ANx3 ANx1 ANx2 C1OUT A = Analog Input, port reads as zeros always. D = Digital Input. CIS (CMCON<3>) is the Comparator Input Switch. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39525A-page 24-6  2000 Microchip Technology Inc. 24.4 Comparator Operation A single comparator is shown in Figure 24-2 along with the relationship between the analog input levels and the digital output. When the analog input at VIN+ is less than the analog input VIN–, the output of the comparator is a digital low level. When the analog input at VIN+ is greater than the analog input VIN–, the output of the comparator is a digital high level. The shaded areas of the output of the comparator (shown in Figure 24-2) represent the uncertainty due to input offsets and response time. 24.5 Comparator Reference An external or internal reference signal may be used depending on the comparator operating mode. The analog signal that is present at VIN– is compared to the signal at VIN+, and the digital output of the comparator is adjusted accordingly (Figure 24-2). Figure 24-2: Single Comparator – VIN+ + VIN– Output VIN– VIN+ utput 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39525A-page 24-7 Section 24. Comparator Comparator 24 24.5.1 External Reference Signal When external voltage references are used, the comparator module can be configured to have the comparators operate from the same or different reference sources. The reference signal must be between VSS and VDD, and can be applied to either pin of the comparator(s). 24.5.2 Internal Reference Signal The comparator module also allows the selection of an internally generated voltage reference for the comparators. The “Comparator Voltage Reference” section contains a detailed description of the Voltage Reference Module that provides this signal. The internal reference signal is used when the comparators are in mode CM2:CM0 = 110 (Figure 24-1). In this mode, the internal voltage reference is applied to the VIN+ input of both comparators. The internal voltage reference may be used in any comparator mode. The voltage reference is output to the VREF pin. Any comparator input pin may be connected externally to the VREF pin. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39525A-page 24-8  2000 Microchip Technology Inc. 24.6 Comparator Response Time Response time is the minimum time, after selecting a new reference voltage or input source, before the comparator output is guaranteed to have a valid level. If the internal reference is changed, the maximum settling time of the internal voltage reference must be considered when using the comparator outputs. Otherwise the maximum response time of the comparators should be used. 24.7 Comparator Outputs The comparator outputs are read through the CMCON register. These bits are read only. The comparator outputs may also be directly output to the I/O pins. When CM2:CM0 = 011, multiplexors in the output path of the I/O pins will switch and the output of each pin will be the unsynchronized output of the comparator. The uncertainty of each of the comparators is related to the input offset voltage and the response time given in the specifications. Figure 24-3 shows the comparator output block diagram. The TRIS bits will still function as the output enable/disable for the I/O pins while in this mode. Figure 24-3: Comparator Output Block Diagram Note 1: When reading the Port register, all pins configured as analog inputs will read as a ‘0’. Pins configured as digital inputs will convert an analog input according to the Schmitt Trigger input specification. 2: Analog levels on any pin that is defined as a digital input may cause the input buffer to consume more current than is specified. Q D EN To I/O pin Bus Data RD CMCON Set MULTIPLEX CMIF bit + - Q D EN CL Port Pins RD CMCON RESET From Other Comparator 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39525A-page 24-9 Section 24. Comparator Comparator 24 24.8 Comparator Interrupts The comparator interrupt flag is set whenever the comparators value changes relative to the last value loaded into CMxOUT bits. Software will need to maintain information about the status of the output bits, as read from CMCON<7:6>, to determine the actual change that has occurred. The CMIF bit is the comparator interrupt flag. The CMIF bit must be cleared. Since it is also possible to set this bit, a simulated interrupt may be initiated. The CMIE bit, the PEIE/GIEL bit, and the GIE/GIEH bit must be set to enable the interrupt. If any of these bits are clear, an interrupt from the comparator module will not occur, though the CMIF bit will still be set if an interrupt condition occurs. Table 24-1 shows the state of the comparator interrupt bits to enable an interrupt to vector to the interrupt vector address. If these conditions are not met, the comparator module will set the CMIF bit, but the program execution will not go to the interrupt vector address. The user, in the interrupt service routine, can clear the interrupt in the following manner: a) Any read or write of the CMCON register. This will load the CMCON register with the new value with the CMxOUT bits. b) Clear the CMIF flag bit. An interrupt condition will continue to set the CMIF flag bit. Reading CMCON will end the interrupt condition, and allow the CMIF flag bit to be cleared. Table 24-1: How State of Interrupt Control Bits Determine Action After Comparator Trip (CMIF is Set) 24.9 Comparator Operation During SLEEP When a comparator is active and the device is placed in SLEEP mode, the comparator remains active and the interrupt is functional if enabled. This interrupt will wake-up the device from SLEEP mode when enabled. While the comparator is powered up, each comparator that is operational will consume additional current as shown in the comparator specifications. To minimize power consumption while in SLEEP mode, turn off the comparators (CM2:CM0 = 111), before entering SLEEP. If the device wakes up from SLEEP, the contents of the CMCON register are not affected. 24.10 Effects of a RESET A device RESET forces the CMCON register to its reset state. This forces the comparator module to be in the comparator reset mode, CM2:CM0 = 000. This ensures that all potential inputs are analog inputs. Device current is minimized when analog inputs are present at RESET time. The comparators will be powered down disabled during the RESET interval. GIE GIEH PEIE GIEL CMIE IPEN CMIP Comment 1 — 1 — 1 0 — CMIF set Branch to ISR x — x — 0 0 — CMIF set x — 0 — x 0 — CMIF set 0 — x — x 0 — CMIF set — x — 1 11 0 CMIF set Branch to ISR — 1 — x 11 1 CMIF set Branch to ISR — x — x 0 1 x CMIF set — x — 0 x 1 0 CMIF set — x 0 — x 1 1 CMIF set — 0 x — x 1 1 CMIF set 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39525A-page 24-10  2000 Microchip Technology Inc. 24.11 Analog Input Connection Considerations A simplified circuit for an analog input is shown in Figure 24-4. Since the analog pins are connected to a digital output, they have reverse biased diodes to VDD and VSS. The analog input therefore, must be between VSS and VDD. If the input voltage deviates from this range by more than 0.6V in either direction, one of the diodes is forward biased and a latch-up may occur. A maximum source impedance of 10 kΩ is recommended for the analog sources. Figure 24-4: Analog Input Model Table 24-2: Registers Associated with Comparator Module Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Value on POR, BOR Value on All Other Resets CMCON C2OUT C1OUT — — CIS CM2 CM1 CM0 00-- 0000 00-- 0000 VRCON VREN VROE VRR — VR3 VR2 VR1 VR0 000- 0000 000- 0000 INTCON GIE/GIEH PEIE/GIEL TMR0IE INT0IE RBIE TMR0IF INT0IF RBIF 0000 000x 0000 000x PIR CMIF (1) 0 0 PIE CMIE (1) 0 0 IPE CMIP (1) 0 0 Legend: x = unknown, - = unimplemented locations read as '0'. Shaded cells are not used for Comparator Module. Note 1: The position of this bit is device dependent. VAIN RS AIN CPIN 5 pF VDD VT = 0.6V VT = 0.6V RC < 10k ILEAKAGE ±500 nA VSS Legend CPIN = Input Capacitance VT = Threshold Voltage ILEAKAGE = Leakage Current at the pin due to various junctions RIC = Interconnect Resistance RS = Source Impedance VA = Analog Voltage 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39525A-page 24-11 Section 24. Comparator Comparator 24 24.12 Initialization The code in Example 24-1 depicts example steps required to configure the comparator module. The Port registers (PORTx, LATx, and TRISx) need to be configured appropriately depending on the mode selected. For CM2:CM0 = 100, the I/O multiplied with ANx0, ANx1, and ANx2 needs to be configured for analog inputs. Other I/O may be digital. Example 24-1: Initializing Comparator Module FLAG_REG EQU 0x020 ; CLRF FLAG_REG ; Init flag register CLRF PORTx ; Init the desired port MOVF CMCON, W ; ANDLW 0xC0 ; Mask comparator bits IORWF FLAG_REG,F ; Store bits in flag register MOVLW 0x04 ; Init comparator mode MOVWF CMCON ; CM<2:0> = 100 MOVLW PORTxDIR ; Initialize data direction of the ANx0, ANx1, MOVWF TRISx ; and ANx2. Set as inputs, other I/O ; on port as desired (either inputs or outputs) CALL DELAY10 ; 10us delay MOVF CMCON, F ; Read CMCON to end change condition BCF PIR1,CMIF ; Clear pending interrupts BSF PIE1,CMIE ; Enable comparator interrupts BSF INTCON,PEIE ; Enable peripheral interrupts BSF INTCON,GIE ; Global interrupt enable 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39525A-page 24-12  2000 Microchip Technology Inc. 24.13 Design Tips Question 1: My program appears to lock up. Answer 1: You may be getting stuck in an infinite loop with the comparator interrupt service routine if you did not follow the proper sequence to clear the CMIF flag bit. First, you must read the CMCON register and then you can clear the CMIF flag bit. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39525A-page 24-13 Section 24. Comparator Comparator 24 24.14 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced MCU family (that is they may be written for the Base-Line, Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the comparator module are: Title Application Note # Resistance and Capacitance Meter using a PIC16C622 AN611 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39525A-page 24-14  2000 Microchip Technology Inc. 24.15 Revision History Revision A This is the initial released revision of the Comparator module description. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-1 Compatible 10-bit A/D Converter 25 Section 25. Compatible 10-bit A/D Converter HIGHLIGHTS This section of the manual contains the following major topics: 25.1 Introduction .................................................................................................................. 25-2 25.2 Control Register ........................................................................................................... 25-4 25.3 Operation ..................................................................................................................... 25-7 25.4 A/D Acquisition Requirements ..................................................................................... 25-8 25.5 Selecting the A/D Conversion Clock .......................................................................... 25-10 25.6 Configuring Analog Port Pins..................................................................................... 25-11 25.7 A/D Conversions ........................................................................................................ 25-12 25.8 Operation During SLEEP ........................................................................................... 25-16 25.9 Effects of a RESET .................................................................................................... 25-16 25.10 A/D Accuracy/Error .................................................................................................... 25-17 25.11 Connection Considerations........................................................................................ 25-18 25.12 Transfer Function ....................................................................................................... 25-18 25.13 Initialization ................................................................................................................ 25-19 25.14 Design Tips ................................................................................................................ 25-20 25.15 Related Application Notes.......................................................................................... 25-21 25.16 Revision History ......................................................................................................... 25-22 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-2  2000 Microchip Technology Inc. 25.1 Introduction The compatible analog-to-digital (A/D) converter module is software compatible with the Standard 10-bit A/D converter and can have up to sixteen analog inputs. The analog input charges a sample and hold capacitor. The output of the sample and hold capacitor is the input into the converter. The converter then generates a digital result of this analog level via successive approximation. This A/D conversion of the analog input signal results in a corresponding 10-bit digital number. The analog reference voltages (positive and negative supply) are software selectable to either the device’s supply voltages (AVDD, AVss) or the voltage level on the AN3/VREF+ and AN2/VREFpins. The A/D converter has the unique feature of being able to convert while the device is in SLEEP mode. The A/D module has four registers. These registers are: • A/D Result High Register (ADRESH) • A/D Result Low Register (ADRESL) • A/D Control Register0 (ADCON0) • A/D Control Register1 (ADCON1) The ADCON0 register, shown in Register 25-1, controls the operation of the A/D module. The ADCON1 register, shown in Register 25-2, configures the functions of the port pins. The port pins can be configured as analog inputs (AN3 and AN2 can also be the voltage references) or as digital I/O. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-3 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 Figure 25-1: Compatible 10-bit A/D Block Diagram (Input voltage) VAIN VREF- (Reference voltage) AVDD PCFG0 CHS3:CHS0 AN7 AN6 AN5 AN4 AN3 AN2 AN1 AN0 0111 0110 0101 0100 0011 0010 0001 0000 A/D Converter AN11 AN10 AN9 AN8 1011 1010 1001 1000 VREF+ AVSS AN12 1100 AN13 1101 AN14 1110 AN15 1111 Note: Not all 16 input channels may be implemented on every device. Unimplemented selections are reserved and must not be selected. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-4  2000 Microchip Technology Inc. 25.2 Control Register ADCON0 (Register 25-1) is used to select the clock and the analog channel. ADCON1 (Register 25-2) configures the port logic to either analog or digital inputs and the format of the result. Register 25-1: ADCON0 Register R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 ADCS1 ADCS0 CHS2 CHS1 CHS0 GO/DONE CHS3 ADON bit 7 bit 0 bit 7-6: ADCS1:ADCS0: A/D Conversion Clock Select bits (shown in bold) Three bits are required to select the A/D clock source. These bits are ADCS2:ADCS0. 000 = FOSC/2 001 = FOSC/8 010 = FOSC/32 011 = FRC (clock derived from the internal A/D RC oscillator) 100 = FOSC/4 101 = FOSC/16 110 = FOSC/64 111 = FRC (clock derived from the internal A/D RC oscillator) Note: The ADCS2 bit is located in the ADCON1 register. bit 5-3: CHS2:CHS0: Analog Channel Select bits There are four bits that select the A/D channel. These are CHS3:CHS0. 0000 = channel 0, (AN0) 0001 = channel 1, (AN1) 0010 = channel 2, (AN2) 0011 = channel 3, (AN3) 0100 = channel 4, (AN4) 0101 = channel 5, (AN5) 0110 = channel 6, (AN6) 0111 = channel 7, (AN7) 1000 = channel 8, (AN8) 1001 = channel 8, (AN9) 1010 = channel 10, (AN10) 1011 = channel 11, (AN11) 1100 = channel 12, (AN12) 1101 = channel 13, (AN13) 1110 = channel 14, (AN14) 1111 = channel 15, (AN15) Note: For devices that do not implement the full 16 A/D channels, the unimplemented selections are reserved. Do not select any unimplemented channel. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-5 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 bit 2: GO/DONE: A/D Conversion Status bit When ADON = 1 1 = A/D conversion in progress. Setting this bit starts an A/D conversion cycle. This bit is automatically cleared by hardware when the A/D conversion is completed. 0 = A/D conversion not in progress bit 1: CHS3: Analog Channel Select bit The CHS2:CHS0 bits are located in positions bit 5 to bit 3. See the CHS2:CHS0 description for operational details. bit 0: ADON: A/D On bit 1 = A/D converter module is powered up 0 = A/D converter module is shut off and consumes no operating current Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-6  2000 Microchip Technology Inc. Register 25-2: ADCON1 Register R/W-0 R/W-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 ADFM ADCS2 — — PCFG3 PCFG2 PCFG1 PCFG0 bit 7 bit 0 bit 7: ADFM: A/D Result Format Select (also see Figure 25-6) 1 = Right justified. 6 Most Significant bits of ADRESH are read as ’0’. 0 = Left justified. 6 Least Significant bits of ADRESL are read as ’0’. bit 6: ADCS2: A/D Conversion Clock Select bits (shown in bold) Three bits are required to select the A/D clock source. These bits are ADCS2:ADCS0. 000 = FOSC/2 001 = FOSC/8 010 = FOSC/32 011 = FRC (clock derived from the internal A/D RC oscillator) 100 = FOSC/4 101 = FOSC/16 110 = FOSC/64 111 = FRC (clock derived from the internal A/D RC oscillator) Note: The ADCS1:ADCS0 bits are located in the ADCON0 register. bit 5-4: Unimplemented: Read as '0' bit 3-0: PCFG3:PCFG0: A/D Port Configuration Control bits Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown A = Analog input D = Digital I/O Ch/Ref = # of analog input channels / # of A/D voltage references PCFG AN7 AN6 AN5 AN4 AN3 AN2 AN1 AN0 VREF+ VREF- CH/REF 0000 A A A A A A A A AVDD AVSS 8/0 0001 A A A AVREF+ A A A AN3 AVSS 7/1 0010 D D D A A A A A AVDD AVSS 5/0 0011 D D D AVREF+ A A A AN3 AVSS 4/1 0100 D D D D A D A A AVDD AVSS 3/0 0101 D D D DVREF+ D A A AN3 AVSS 2/1 011x DDDD D D DD — — 0/0 1000 A A A AVREF+ VREF- A A AN3 AN2 6 / 2 1001 D D A A A A A A AVDD AVSS 6/0 1010 D D A AVREF+ A A A AN3 AVSS 5/1 1011 D D A AVREF+ VREF- A A AN3 AN2 4 / 2 1100 D D D AVREF+ VREF- A A AN3 AN2 3 / 2 1101 D D D DVREF+ VREF- A A AN3 AN2 2 / 2 1110 D D D D D D D A AVDD AVSS 1/0 1111 D D D DVREF+ VREF- D A AN3 AN2 1 / 2 Note 1: On any device RESET, the port pins that are multiplexed with analog functions (ANx) are forced to be an analog input. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-7 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 25.3 Operation The ADRESH:ADRESL registers contain the 10-bit result of the A/D conversion. When the A/D conversion is complete, the result is loaded into this A/D result register pair (ADRESH:ADRESL), the GO/DONE bit (ADCON0) is cleared, and A/D interrupt flag bit, ADIF, is set. The block diagram of the A/D module is shown in Figure 25-1. After the A/D module has been configured, the signal on the selected channel must be acquired before the conversion is started. The analog input channels must have their corresponding TRIS bits selected as inputs. To determine acquisition time, see Subsection 25.4 “A/D Acquisition Requirements.” After this acquisition time has elapsed, the A/D conversion can be started. The following steps should be followed for doing an A/D conversion: 1. Configure the A/D module: • Configure analog pins, voltage reference, and digital I/O (ADCON1) • Select A/D input channel (ADCON0) • Select A/D conversion clock (ADCON0) • Turn on A/D module (ADCON0) 2. Configure A/D interrupt (if desired): • Clear the ADIF bit • Set the ADIE bit • Set/Clear the ADIP bit • Set the GIE/GIEH or PEIE/GIEL bit 3. Wait the required acquisition time. 4. Start conversion: • Set the GO/DONE bit (ADCON0) 5. Wait for the A/D conversion to complete, by either: • Polling for the GO/DONE bit to be cleared or the ADIF bit to be set, or • Waiting for the A/D interrupt 6. Read A/D Result register pair (ADRESH:ADRESL): clear the ADIF bit, if required. 7. For next conversion, go to step 1 or step 2 as required. Figure 25-2 shows the conversion sequence and the terms that are used. Acquisition time is the time that the A/D module’s holding capacitor is connected to the external voltage level. When the GO bit is set, the conversion time of 12 TAD is started. The sum of these two times is the sampling time. There is a minimum acquisition time to ensure that the holding capacitor is charged to a level that will give the desired accuracy for the A/D conversion. Figure 25-2: A/D Conversion Sequence Acquisition Time A/D Conversion Time A/D Sample Time When A/D holding capacitor starts to charge. After A/D conversion, or when new A/D channel is selected. When A/D conversion is started (setting the GO bit). A/D conversion complete, result is loaded in ADRES register. Holding capacitor begins acquiring voltage level on selected channel; ADIF bit is set. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-8  2000 Microchip Technology Inc. 25.4 A/D Acquisition Requirements For the A/D converter to meet its specified accuracy, the charge holding capacitor (CHOLD) must be allowed to fully charge to the input channel voltage level. The analog input model is shown in Figure 25-3. The source impedance (RS) and the internal sampling switch (RSS) impedance directly affect the time required to charge the capacitor CHOLD. The sampling switch (RSS) impedance varies over the device voltage (VDD), Figure 25-3. The source impedance affects the offset voltage at the analog input (due to pin leakage current). The maximum recommended impedance for analog sources is 2.5 kΩ. As the impedance is decreased, the acquisition time may be decreased. After the analog input channel is selected (changed), this acquisition must pass before the conversion can be started. To calculate the minimum acquisition time, Equation 25-1 may be used. This equation assumes that 1/2 LSb error is used (1024 steps for the A/D). The 1/2 LSb error is the maximum error allowed for the A/D to meet its specified resolution. Equation 25-1: Acquisition Time Equation 25-2: A/D Minimum Charging Time Example 25-1 shows the calculation of the minimum required acquisition time TACQ. This calculation is based on the following application system assumptions. CHOLD = 120 pF RS = 2.5 kΩ Conversion Error ≤ 1/2 LSb VDD = 5V → RSS =7kΩ (see graph in Figure 25-3) Temperature = 50° C (system max.) VHOLD = 0V @ time = 0 Example 25-1: Calculating the Minimum Required Acquisition Time (Case 1) Note: When the conversion is started, the holding compacitor is disconnected from the input pin. TACQ equals Amplifier Settling Time (TAMP) plus Holding Capacitor Charging Time (TC) plus Temperature Coefficient (TCOFF) TACQ = TAMP + TC + TCOFF VHOLD = (VREF - (VREF/2048)) • (1 - e(-TC/CHOLD(RIC + RSS + RS))) or Tc = -(120 pF)(1 kΩ + RSS + RS) ln(1/2047) TACQ = TAMP + TC + TCOFF Temperature coefficient is only required for temperatures > 25°C. TACQ = 2 µs + Tc + [(Temp - 25°C)(0.05 µs/°C)] TC = -CHOLD (RIC + RSS + RS) ln(1/2047) -120 pF (1 kΩ +7kΩ + 2.5 kΩ) ln(0.0004885) -120 pF (10.5 kΩ) ln(0.0004885) -1.26 µs (-7.6241) 9.61 µs TACQ = 2 µs + 9.61µs + [(50°C - 25°C)(0.05 µs/°C)] 11.61 µs + 1.25 µs 12.86 µs 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-9 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 Now to get an idea what happens to the acquisition time when the source impedance is a minimal value (RS = 50 Ω). Example 25-2 shows the same conditions as in Example 25-1 with only the source impedance changed to the minimal value. Example 25-2: Calculating the Minimum Required Acquisition Time (Case 2) Figure 25-3: Analog Input Model TACQ = TAMP + TC + TCOFF Temperature coefficient is only required for temperatures > 25°C. TACQ = 2 µs + Tc + [(Temp - 25°C)(0.05 µs/°C)] TC = -Chold (Ric + Rss + Rs) ln(1/2047) -120 pF (1 kΩ +7kΩ + 50 Ω) ln(0.0004885) -120 pF (8050 Ω) ln(0.0004885) -0.966 µs (-7.6241) 7.36 µs TACQ = 2 µs + 16.47 µs + [(50°C - 25°C)(0.05 µs/°C)] 9.36 µs + 1.25 µs 10.61 µs Note 1: The reference voltage (VREF) has no effect on the equation, since it cancels itself out. 2: The charge holding capacitor (Chold) is not discharged after each conversion. 3: The maximum recommended impedance for analog sources is 2.5 kΩ. This is required to meet the pin leakage specification. 4: After a conversion has completed, a 2 TAD delay must complete before acquisition can begin again. During this time the holding capacitor is not connected to the selected A/D input channel. VAIN Cpin Rs ANx 5 pF VDD VT = 0.6V VT = 0.6V I leakage RIC ≤ 1k Sampling Switch SS RSS CHOLD = 120 pF Vss 6V Sampling Switch 5V 4V 3V 2V 5 6 7 8 9 10 11 ( kΩ ) VDD ± 500 nA Legend CPIN VT ILEAKAGE RIC SS CHOLD = Input Capacitance = Threshold Voltage = Leakage Current at the pin due to = Interconnect Resistance = Sampling Switch = Sample/Hold Capacitance (from DAC) various junctions 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-10  2000 Microchip Technology Inc. 25.5 Selecting the A/D Conversion Clock The A/D conversion time per bit is defined as TAD. The A/D conversion requires 11.5TAD per 10-bit conversion. The source of the A/D conversion clock is software selectable. The seven possible options for TAD are: • 2TOSC • 4TOSC • 8TOSC • 16TOSC • 32TOSC • 64TOSC • Internal A/D RC oscillator For correct A/D conversions, the A/D conversion clock (TAD) must be selected to ensure a minimum TAD time of 1.6 µs as shown in Electrical Specifications parameter 130. Table 25-1 and Table 25-2 show the resultant TAD times derived from the device operating frequencies and the selected A/D clock source. Table 25-1: TAD vs. Device Operating Frequencies (for Standard, C, Devices) Table 25-2: TAD vs. Device Operating Frequencies (for Extended, LC, Devices) AD Clock Source (TAD) Device Frequency Operation ADCS2:ADCS0 20 MHz 5 MHz 1.25 MHz 333.33 kHz 2TOSC 000 100 ns (2) 400 ns (2) 1.6 µs 6 µs 4TOSC 100 200 ns (2) 800 ns (2) 3.2 µs 12 µs 8TOSC 001 400 ns (2) 1.6 µs 6.4 µs 24 µs (3) 16TOSC 101 800 ns (2) 3.2 µs 12.8 µs 48 µs (3) 32TOSC 010 1.6 µs 6.4 µs 25.6 µs (3) 96 µs (3) 64TOSC 110 3.2 µs 12.8 µs 51.2 µs (3) 192 µs (3) RC 011 2-6 µs (1,4) 2-6 µs (1,4) 2-6 µs (1,4) 2-6 µs (1) Legend: Shaded cells are outside of recommended range. Note 1: The RC source has a typical TAD of 4 µs. 2: These values violate the minimum required TAD. 3: For faster conversion times, the selection of another clock source is recommended. 4: For device frequencies above 1 MHz, the device must be in SLEEP for the entire conversion, or the A/D accuracy may be out of specification. AD Clock Source (TAD) Device Frequency Operation ADCS2:ADCS0 4 MHz 2 MHz 1.25 MHz 333.33 kHz 2TOSC 000 500 ns (2) 1.0 µs (2) 1.6 µs (2) 6 µs 4TOSC 100 1.0 µs (2) 2.0 µs (2) 3.2 µs (2) 12 µs 8TOSC 001 2.0 µs (2) 4.0 µs 6.4 µs 24 µs (3) 16TOSC 101 4.0 µs (2) 8.0 µs 12.8 µs 48 µs (3) 32TOSC 010 8.0 µs 16.0 µs 25.6 µs (3) 96 µs (3) 64TOSC 110 16.0 µs 32.0 µs 51.2 µs (3) 192 µs (3) RC 011 3-9 µs (1,4) 3-9 µs (1,4) 3-9 µs (1,4) 3-9 µs (1) Legend: Shaded cells are outside of recommended range. Note 1: The RC source has a typical TAD of 6 µs. 2: These values violate the minimum required TAD. 3: For faster conversion times, the selection of another clock source is recommended. 4: For device frequencies above 1 MHz, the device must be in SLEEP for the entire conversion, or the A/D accuracy may be out of specification. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-11 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 25.6 Configuring Analog Port Pins The ADCON1 and TRIS registers control the operation of the A/D port pins. The port pins that are desired as analog inputs must have their corresponding TRIS bits set (input). If the TRIS bit is cleared (output), the digital output level (VOH or VOL) will be converted. After a device RESET, pins that are multiplexed with analog inputs will be configured as an analog input. The corresponding TRIS bit will be set. The A/D operation is independent of the state of the CHS2:CHS0 bits and the TRIS bits. Note 1: When reading the port register, any pin configured as an analog input channel will read as cleared (a low level). Pins configured as digital inputs, will convert an analog input. Analog levels on a digitally configured input will not affect the conversion accuracy. 2: Analog levels on any pin that is defined as a digital input (including the AN7:AN0 pins), may cause the input buffer to consume current that is out of the devices specification. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-12  2000 Microchip Technology Inc. 25.7 A/D Conversions Example 25-3 shows how to perform an A/D conversion. The port pins are configured as analog inputs. The analog references (VREF+ and VREF-) are the device AVDD and AVSS. The A/D interrupt is enabled, and the A/D conversion clock is FRC. The conversion is performed on the AN0 pin (channel 0). The result of the conversion is left justified. Clearing the GO/DONE bit during a conversion will abort the current conversion. The A/D result register pair will NOT be updated with the partially completed A/D conversion sample. That is, the ADRESH:ADRESL registers will continue to contain the value of the last completed conversion (or the last value written to the ADRESH:ADRESL registers). After the A/D conversion is aborted, a 2TAD wait is required before the next acquisition is started. After this 2TAD wait, acquisition on the selected channel is automatically started. Example 25-3: A/D Conversion Figure 25-4: A/D Conversion TAD Cycles Note: The GO/DONE bit should NOT be set in the same instruction that turns on the A/D, due to the required acquisition time. CLRF ADCON1 ; Configure A/D inputs, ; result is left justified BSF IPR1, ADIP ; High priority BSF PIE1, ADIE ; Enable A/D interrupts MOVLW 0xC1 ; RC Clock, A/D is on, MOVWF ADCON0 ; Channel 0 is selected BCF PIR1, ADIF ; Clear A/D interrupt flag bit BSF INTCON, PEIE ; Enable peripheral interrupts BSF INTCON, GIE ; Enable all interrupts ; ; Ensure that the required sampling time for the selected input ; channel has elapsed. Then the conversion may be started. ; BSF ADCON0, GO ; Start A/D Conversion : ; The ADIF bit will be set and the : ; GO/DONE bit is cleared upon : ; completion of the A/D Conversion. TAD1 TAD2 TAD3 TAD4 TAD5 TAD6 TAD7 TAD8 TAD11 Set GO bit Holding capacitor is disconnected from analog input (typically 100 ns) holding capacitor is connected to analog input. b9 b8 b7 b6 b5 b4 b3 b2 TAD9 TAD10 b1 b0 Tcy - TAD GO bit is cleared, Next Q4: ADRES is loaded, ADIF bit is set, Conversion Starts b0 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-13 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 Figure 25-5: Flowchart of A/D Operation Acquire ADON = 0 ADON = 0? GO = 0? A/D Clock GO = 0, ADIF = 0 Abort Conversion SLEEP Power-down A/D Wait 2TAD Wake-up Yes No Yes No No Yes Finish Conversion GO = 0, ADIF = 1 No Yes Finish Conversion GO = 0, ADIF = 1 Wait 2TAD Stay in SLEEP Selected Channel = RC? SLEEP No Yes Instruction? Start of A/D Conversion Delayed 1 Instruction Cycle From SLEEP? Power-down A/D Yes No Wait 2TAD Finish Conversion GO = 0, ADIF = 1 SLEEP Instruction? 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-14  2000 Microchip Technology Inc. 25.7.1 Faster Conversion - Lower Resolution Trade-off Not all applications require a result with 10-bits of resolution, but may instead require a faster conversion time. The A/D module allows users to make the trade-off of conversion speed to resolution. Regardless of the resolution required, the acquisition time is the same. To speed up the conversion, the clock source of the A/D module may be switched so that the TAD time violates the minimum specified time (see electrical specification parameter 130). Once the TAD time violates the minimum specified time, all the following A/D result bits are not valid (see A/D Conversion Timing in the Electrical Specifications section). The clock sources may only be switched between the three oscillator versions (cannot be switched from/to RC). The equation to determine the time before the oscillator can be switched is as follows: Since the TAD is based from the device oscillator, the user must use some method (a timer, software loop, etc.) to determine when the A/D oscillator may be changed. Example 25-4 shows a comparison of time required for a conversion with 4-bits of resolution, versus the 10-bit resolution conversion. The example is for devices operating at 20 MHz (the A/D clock is programmed for 32TOSC), and assumes that immediately after 6TAD, the A/D clock is programmed for 2TOSC. The 2TOSC violates the minimum TAD time since the last 6 bits will not be converted to correct values. Example 25-4: 4-bit vs. 10-bit Conversion Times Equation 25-3: Resolution/Speed Conversion Trade-off Freq. (MHz)(1) Resolution 4-bit 10-bit TAD 40 1.6 µs 1.6 µs TOSC 40 25 ns 25 ns TAD + N • TAD + (11 - N)(2TOSC) 40 8.5 µs 17.7 µs Note 1: A minimum TAD time of 1.6 µs is required. 2: If the full 10-bit conversion is required, the A/D clock source should not be changed. Conversion time = TAD + N • TAD + (11 - N)(2TOSC) Where: N = number of bits of resolution required 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-15 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 25.7.2 A/D Result Registers The ADRESH:ADRESL register pair is the location where the 10-bit A/D result is loaded at the completion of the A/D conversion. This register pair is 16-bits wide. The A/D module gives the flexibility to left or right justify the 10-bit result in the 16-bit result register. The A/D Format Select bit (ADFM) controls this justification. Figure 25-6 shows the operation of the A/D result justification. The extra bits are loaded with ‘0’s’. When the A/D module is disabled these registers may be used as two general purpose 8-bit registers. Figure 25-6: A/D Result Justification 10-bit Result ADRESH ADRESL ADFM = 0 7 2107 0 10-bits RESULT ADRESH ADRESL 10-bits 7 0765 0 RESULT ADFM = 1 Right Justified Left Justified 0000 00 0000 00 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-16  2000 Microchip Technology Inc. 25.8 Operation During SLEEP The A/D module can operate during SLEEP mode. This requires that the A/D clock source be set to RC (ADCS2:ADCS0 = x11). When the RC clock source is selected, the A/D module waits one instruction cycle before starting the conversion. This allows the SLEEP instruction to be executed, which eliminates all internal digital switching noise from the conversion. When the conversion is completed, the GO/DONE bit will be cleared and the result is loaded into the ADRESH:ADRESL registers. If the A/D interrupt is enabled, the device will wake-up from SLEEP. If the A/D interrupt is not enabled, the A/D module will be turned off, although the ADON bit will remain set. When the A/D clock source is another clock option (not RC), a SLEEP instruction will cause the present conversion to be aborted and the A/D module to be turned off (to conserve power), though the ADON bit will remain set. Turning off the A/D places the A/D module in its lowest current consumption state. 25.9 Effects of a RESET A device RESET forces all registers to their RESET state. This forces the A/D module to be turned off, and any conversion is aborted. All pins that are multiplexed with analog inputs will be configured as an analog input. The corresponding TRIS bits will be set. The value that is in the ADRESH:ADRESL registers is not initialized from a Power-on Reset. The ADRESH:ADRESL registers will contain unknown data after a Power-on Reset. Note: For the A/D module to operate in SLEEP, the A/D clock source must be set to RC (ADCS2:ADCS0 = x11). To allow the conversion to occur during SLEEP, ensure the SLEEP instruction immediately follows the instruction that sets the GO/DONE bit. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-17 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 25.10 A/D Accuracy/Error In systems where the device frequency is low, use of the A/D RC clock is preferred. At moderate to high frequencies, TAD should be derived from the device oscillator. For a given range of analog inputs, the output digital code will be the same. This is due to the quantization of the analog input to a digital code. Quantization error is typically ± 1/2 LSb and is inherent in the analog to digital conversion process. The only way to reduce quantization error is to increase the resolution of the A/D converter. Offset error measures the first actual transition of a code versus the first ideal transition of a code. Offset error shifts the entire transfer function. Offset error can be calibrated out of a system or introduced into a system, through the interaction of the total leakage current and source impedance at the analog input. Gain error measures the maximum deviation of the last actual transition and the last ideal transition, adjusted for offset error. This error appears as a change in slope of the transfer function. The difference in gain error to full scale error, is that full scale does not take offset error into account. Gain error can be calibrated out in software. Linearity error refers to the uniformity of the code changes. Linearity errors cannot be calibrated out of the system. Integral non-linearity error measures the actual code transition versus the ideal code transition, adjusted by the gain error for each code. Differential non-linearity measures the maximum actual code width versus the ideal code width. This measure is unadjusted. The maximum pin leakage current is specified in Electrical Specifications parameter D060. TAD must not violate the minimum and should be minimized to reduce inaccuracies due to noise and sampling capacitor bleed off. In systems where the device will enter SLEEP mode after the start of the A/D conversion, the RC clock source selection is required. In this mode, the digital noise from the modules in SLEEP are stopped. This method gives high accuracy. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-18  2000 Microchip Technology Inc. 25.11 Connection Considerations If the input voltage exceeds the rail values (VSS or VDD) by greater than 0.3V, then the accuracy of the conversion is out of specification. An external RC filter is sometimes added for anti-aliasing of the input signal. The R component should be selected to ensure that the total source impedance is kept under the 2.5 kΩ recommended specification. Any external components connected (via hi-impedance) to an analog input pin (capacitor, zener diode, etc.) should have very little leakage current at the pin. 25.12 Transfer Function The ideal transfer function of the A/D converter is as follows: the first transition occurs when the analog input voltage (VAIN) is 1 LSb (or Analog VREF / 1024) (Figure 25-7). Figure 25-7: A/D Transfer Function Digital code output 3FEh 003h 002h 001h 000h 0.5 LSb 1 LSb 1.5 LSb 2 LSb 2.5 LSb 1022 LSb 1022.5 LSb 3 LSb Analog input voltage 3FFh 1023 LSb 1023.5 LSb 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-19 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 25.13 Initialization Example 25-5 shows an initialization of the A/D module. Example 25-5: A/D Initialization CLRF ADCON1 ; Configure A/D inputs BSF PIE1, ADIE ; Enable A/D interrupts BSF IPR1, ADIP ; High Priority MOVLW 0xC1 ; RC Clock, A/D is on, MOVWF ADCON0 ; Channel 0 is selected MOVLW 0x4E ; Left Justified, AN0 is analog MOVWF ADCON1 ; Vref comes from AVDD and AVSS BCF PIR1, ADIF ; Clear A/D interrupt flag bit BSF INTCON, PEIE ; Enable peripheral interrupts BSF INTCON, GIE ; Enable all interrupts ; ; Ensure that the required sampling time for the selected input ; channel has elapsed. Then the conversion may be started. ; BSF ADCON0, GO ; Start A/D Conversion : ; The ADIF bit will be set and the : ; GO/DONE bit is cleared upon : ; completion of the A/D conversion. 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-20  2000 Microchip Technology Inc. 25.14 Design Tips Question 1: I find that the Analog to Digital Converter result is not always accurate. What can I do to improve accuracy? Answer 1: 1. Make sure you are meeting all of the timing specifications. If you are turning the module off and on, there is a minimum delay you must wait before taking a sample. If you are changing input channels, there is a minimum delay you must wait for this as well, and finally there is TAD, which is the time selected for each bit conversion. This is selected in ADCON0 and should be between 1.6 and 6 µs. If TAD is too short, the result may not be fully converted before the conversion is terminated, and if TAD is made too long, the voltage on the sampling capacitor can decay before the conversion is complete. These timing specifications are provided in the “Electrical Specifications” section. See the device data sheet for device specific information. 2. Often the source impedance of the analog signal is high (greater than 1 kOhms), so the current drawn from the source to charge the sample capacitor can affect accuracy. If the input signal does not change too quickly, try putting a 0.1 µF capacitor on the analog input. This capacitor will charge to the analog voltage being sampled and supply the instantaneous current needed to charge the 120 pF internal holding capacitor. 3. In systems where the device frequency is low, use of the A/D clock derived from the device oscillator is preferred...this reduces, to a large extent, the effects of digital switching noise. In systems where the device will enter SLEEP mode after start of A/D conversion, the RC clock source selection is required.This method gives the highest accuracy. Question 2: After starting an A/D conversion may I change the input channel (for my next conversion)? Answer 2: After the holding capacitor is disconnected from the input channel, typically 100 ns after the GO bit is set, the input channel may be changed. Question 3: Do you know of a good reference on A/D’s? Answer 3: A good reference for understanding A/D conversions is the “Analog-Digital Conversion Handbook” third edition, published by Prentice Hall (ISBN 0-13-03-2848-0). Question 4: I migrated my code from a PIC18CXX8 device with 10-bit A/D to another device with a 10-bit A/D (such as a PIC18CXX2) and the A/D does not seem to operate the same. What’s going on? Answer 4: The 10-bit A/D on the PIC18CXX2 device is the compatible 10-bit A/D module. This module has its ADCON bits in the same locations as the PICmicro’s Mid-Range 10-bit A/D module. The standard PIC18CXXX 10-bit A/D module (as found on the PIC18CXX8 device) has optimized the bit locations to ease configuration of the module. 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39526A-page 25-21 Section 25. Compatible 10-bit A/D Converter Compatible 10-bit A/D Converter 25 25.15 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Base-Line, the Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the 10-bit A/D module are: Title Application Note # Using the Analog to Digital Converter AN546 Four Channel Digital Voltmeter with Display and Keyboard AN557 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39526A-page 25-22  2000 Microchip Technology Inc. 25.16 Revision History Revision A This is the initial released revision of the Enhanced MCU Compatible 10-bit A/D module description. 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-1 10-bit A/D Converter 26 Section 26. 10-bit A/D Converter HIGHLIGHTS This section of the manual contains the following major topics: 26.1 Introduction .................................................................................................................. 26-2 26.2 Control Register ........................................................................................................... 26-4 26.3 Operation ..................................................................................................................... 26-7 26.4 A/D Acquisition Requirements ..................................................................................... 26-8 26.5 Selecting the A/D Conversion Clock .......................................................................... 26-10 26.6 Configuring Analog Port Pins..................................................................................... 26-11 26.7 A/D Conversions ........................................................................................................ 26-12 26.8 Operation During SLEEP ........................................................................................... 26-16 26.9 Effects of a RESET .................................................................................................... 26-16 26.10 A/D Accuracy/Error .................................................................................................... 26-17 26.11 Connection Considerations........................................................................................ 26-18 26.12 Transfer Function ....................................................................................................... 26-18 26.13 Initialization ................................................................................................................ 26-19 26.14 Design Tips ................................................................................................................ 26-20 26.15 Related Application Notes.......................................................................................... 26-21 26.16 Revision History ......................................................................................................... 26-22 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-2  2000 Microchip Technology Inc. 26.1 Introduction The 10-bit Analog-to-Digital (A/D) Converter module can have up to sixteen analog inputs. The analog input charges a sample and hold capacitor. The output of the sample and hold capacitor is the input into the converter. The converter then generates a digital result of this analog level via successive approximation. This A/D conversion of the analog input signal results in a corresponding 10-bit digital number. The analog reference voltages (positive and negative supply) are software selectable to either the device’s supply voltages (AVDD, AVss) or the voltage level on the AN3/VREF+ and AN2/VREFpins. The A/D converter has the unique feature of being able to convert while the device is in SLEEP mode. The A/D module has five registers. These registers are: • A/D Result High Register (ADRESH) • A/D Result Low Register (ADRESL) • A/D Control Register0 (ADCON0) • A/D Control Register1 (ADCON1) • A/D Control Register2 (ADCON2) The ADCON0 register, shown in Register 26-1, selects the input channel of the A/D module. The ADCON1 register, shown in Register 26-2, configures the functions of the port pins and the Voltage Reference for the A/D module. The port pins can be configured as analog inputs (AN3 and AN2 can also be the Voltage References) or as digital I/O. ADCON2 selects the A/D conversion clock source and the format of the A/D result. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-3 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 Figure 26-1: 10-bit A/D Block Diagram (Input voltage) VAIN VREF- (Reference Voltage) AVDD PCFG0 CHS3:CHS0 AN7 AN6 AN5 AN4 AN3 AN2 AN1 AN0 0111 0110 0101 0100 0011 0010 0001 0000 A/D Converter AN11 AN10 AN9 AN8 1011 1010 1001 1000 VREF+ AVSS AN12 1100 AN13 1101 AN14 1110 AN15 1111 Note: Not all 16 input channels may be implemented on every device. Unimplemented selections are reserved and must not be selected. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-4  2000 Microchip Technology Inc. 26.2 Control Register ADCON0 (Register 26-1) is used to select the analog channel. ADCON1 (Register 26-2) configures the port logic to either analog or digital inputs and the voltage reference source for the A/D. ADCON2 (Register 26-3) selects the source of the A/D clock and the justification of the result. Register 26-1: ADCON0 Register U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — CHS3 CHS2 CHS1 CHS0 GO/DONE ADON bit 7 bit 0 bit 7-6: Unimplemented: Read as ’0’ bit 5-2: CHS3:CHS0: Analog Channel Select bits 0000 = channel 0, (AN0) 0001 = channel 1, (AN1) 0010 = channel 2, (AN2) 0011 = channel 3, (AN3) 0100 = channel 4, (AN4) 0101 = channel 5, (AN5) 0110 = channel 6, (AN6) 0111 = channel 7, (AN7) 1000 = channel 8, (AN8) 1001 = channel 8, (AN9) 1010 = channel 10, (AN10) 1011 = channel 11, (AN11) 1100 = channel 12, (AN12) 1101 = channel 13, (AN13) 1110 = channel 14, (AN14) 1111 = channel 15, (AN15) bit 1: GO/DONE: A/D Conversion Status bit 1 = A/D conversion in progress. Setting this bit starts an A/D conversion cycle. This bit is automatically cleared by hardware when the A/D conversion is completed. 0 = A/D conversion not in progress bit 0: ADON: A/D On bit 1 = A/D converter module is operating 0 = A/D converter module is shut off and consumes no operating current Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-5 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 Register 26-2: ADCON1 Register U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — VCFG1 VCFG0 PCFG3 PCFG2 PCFG1 PCFG0 bit 7 bit 0 bit 7-6: Unimplemented: Read as ’0’ bit 5-4: VCFG1:VCFG0: Voltage Reference Configuration bits bit 3-0: PCFG3:PCFG0: A/D Port Configuration Control bits (1) A = Analog input D = Digital I/O Note 1: Selection of an unimplemented channel produces a result of 0xFFF. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown A/D VREFH A/D VREFL 00 AVDD AVSS 01 External VREF+ AVSS 10 AVDD External VREF11 External VREF+ External VREFAN15 AN14 AN13 AN12 AN11 AN10 AN9 AN8 AN7 AN6 AN5 AN4 AN3 AN2 AN1 AN0 0000 AAAAAAAAAAAAAAAA 0001 DDAAAAAAAAAAAAAA 0010 DDDAAAAAAAAAAAAA 0011 DDDDAAAAAAAAAAAA 0100 DDDDDAAAAAAAAAAA 0101 DDDDDDAAAAAAAAAA 0110 DDDDDDDAAAAAAAAA 0111 DDDDDDDDAAAAAAAA 1000 DDDDDDDDDAAAAAAA 1001 DDDDDDDDDDAAAAAA 1010 DDDDDDDDDDDAAAAA 1011 DDDDDDDDDDDDAAAA 1100 DDDDDDDDDDDDDAAA 1101 DDDDDDDDDDDDDDAA 1110 DDDDDDDDDDDDDDDA 1111 DDDDDDDDDDDDDDDD 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-6  2000 Microchip Technology Inc. Register 26-3: ADCON2 Register R/W-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 ADFM — — — — ADCS2 ADCS1 ADCS0 bit 7 bit 0 bit 7: ADFM: A/D Result Format Select bit 1 = Right justified 0 = Left justified bit 6-3: Unimplemented: Read as ’0’ bit 2-0: ADCS2:ADCS0: A/D Conversion Clock Select bits 000 = FOSC/2 001 = FOSC/8 010 = FOSC/32 011 = FRC (clock derived from an internal RC oscillator, 1 MHz maximum frequency) 100 = FOSC/4 101 = FOSC/16 110 = FOSC/64 111 = FRC (clock derived from an RC oscillator, 1 MHz maximum frequency) Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-7 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 26.3 Operation The ADRESH:ADRESL registers contain the 10-bit result of the A/D conversion. When the A/D conversion is complete, the result is loaded into this A/D result register pair (ADRESH:ADRESL), the GO/DONE bit (ADCON0 register) is cleared, and A/D interrupt flag bit, ADIF, is set. The block diagram of the A/D module is shown in Figure 26-1. After the A/D module has been configured, the signal on the selected channel must be acquired before the conversion is started. The analog input channels must have their corresponding TRIS bits selected as inputs. To determine acquisition time, see Subsection 26.4 “A/D Acquisition Requirements.” After this acquisition time has elapsed, the A/D conversion can be started. The following steps should be followed for doing an A/D conversion: 1. Configure the A/D module: • Configure analog pins, Voltage Reference, and digital I/O (ADCON1) • Select A/D input channel (ADCON0) • Select A/D conversion clock (ADCON0) • Turn on A/D module (ADCON0) 2. Configure A/D interrupt (if desired): • Clear the ADIF bit • Set the ADIE bit • Set/Clear the ADIP bit • Set the GIE/GIEH or PEIE/GIEL bit 3. Wait the required acquisition time. 4. Start conversion: • Set the GO/DONE bit (ADCON0) 5. Wait for the A/D conversion to complete, by either: • Polling for the GO/DONE bit to be cleared or the ADIF bit to be set, or • Waiting for the A/D interrupt 6. Read A/D Result register pair (ADRESH:ADRESL): clear the ADIF bit, if required. 7. For next conversion, go to step 1 or step 2 as required. Figure 26-2 shows the conversion sequence, and the terms that are used. Acquisition time is the time that the A/D module’s holding capacitor is connected to the external voltage level. When the GO bit is set, the conversion time of 12 TAD is started. The sum of these two times is the sampling time. There is a minimum acquisition time to ensure that the holding capacitor is charged to a level that will give the desired accuracy for the A/D conversion. Figure 26-2: A/D Conversion Sequence Acquisition Time A/D Conversion Time A/D Sample Time When A/D holding capacitor starts to charge. After A/D conversion, or when new A/D channel is selected. When A/D conversion is started (setting the GO bit). A/D conversion complete, result is loaded in ADRES register. Holding capacitor begins acquiring voltage level on selected channel; ADIF bit is set. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-8  2000 Microchip Technology Inc. 26.4 A/D Acquisition Requirements For the A/D converter to meet its specified accuracy, the charge holding capacitor (CHOLD) must be allowed to fully charge to the input channel voltage level. The analog input model is shown in Figure 26-3. The source impedance (RS) and the internal sampling switch (RSS) impedance directly affect the time required to charge the capacitor CHOLD. The sampling switch (RSS) impedance varies over the device voltage (VDD), Figure 26-3. The source impedance affects the offset voltage at the analog input (due to pin leakage current). The maximum recommended impedance for analog sources is 2.5 kΩ. As the impedance is decreased, the acquisition time may be decreased. After the analog input channel is selected (changed), this acquisition must pass before the conversion can be started. To calculate the minimum acquisition time, Equation 26-1 may be used. This equation assumes that 1/2 LSb error is used (1024 steps for the A/D). The 1/2 LSb error is the maximum error allowed for the A/D to meet its specified resolution. Equation 26-1: Acquisition Time Equation 26-2: A/D Minimum Charging Time Example 26-1 shows the calculation of the minimum required acquisition time TACQ. This calculation is based on the following application system assumptions. CHOLD = 120 pF RS = 2.5 kΩ Conversion Error ≤ 1/2 LSb VDD = 5V → RSS =7kΩ (see graph in Figure 26-3) Temperature = 50° C (system max.) VHOLD = 0V @ time = 0 Example 26-1: Calculating the Minimum Required Acquisition Time (Case 1) Note: When the conversion is started, the holding capacitor is disconnected from the input pin. TACQ equals Amplifier Settling Time (TAMP) plus Holding Capacitor Charging Time (TC) plus Temperature Coefficient (TCOFF) TACQ = TAMP + TC + TCOFF VHOLD = (VREF - (VREF/2048)) • (1 - e(-TC/CHOLD(RIC + RSS + RS))) or Tc = -(120 pF)(1 kΩ + RSS + RS) ln(1/2047) TACQ = TAMP + TC + TCOFF Temperature coefficient is only required for temperatures > 25°C. TACQ = 2 µs + Tc + [(Temp - 25°C)(0.05 µs/°C)] TC = -CHOLD (RIC + RSS + RS) ln(1/2047) -120 pF (1 kΩ +7kΩ + 2.5 kΩ) ln(0.0004885) -120 pF (10.5 kΩ) ln(0.0004885) -1.26 µs (-7.6241) 9.61 µs TACQ = 2 µs + 9.61µs + [(50°C - 25°C)(0.05 µs/°C)] 11.61 µs + 1.25 µs 12.86 µs 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-9 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 Now to get an idea what happens to the acquisition time when the source impedance is a minimal value (RS = 50 Ω). Example 26-2 shows the same conditions as in Example 26-1 with only the source impedance changed to the minimal value. Example 26-2: Calculating the Minimum Required Acquisition Time (Case 2) Figure 26-3: Analog Input Model TACQ = TAMP + TC + TCOFF Temperature coefficient is only required for temperatures > 25°C. TACQ = 2 µs + Tc + [(Temp - 25°C)(0.05 µs/°C)] TC = -Chold (Ric + Rss + Rs) ln(1/2047) -120 pF (1 kΩ +7kΩ + 50 Ω) ln(0.0004885) -120 pF (8050 Ω) ln(0.0004885) -0.966 µs (-7.6241) 7.36 µs TACQ = 2 µs + 16.47 µs + [(50°C - 25°C)(0.05 µs/°C)] 9.36 µs + 1.25 µs 10.61 µs Note 1: The reference voltage (VREF) has no effect on the equation, since it cancels itself out. 2: The charge holding capacitor (CHOLD) is not discharged after each conversion. 3: The maximum recommended impedance for analog sources is 2.5 kΩ. This is required to meet the pin leakage specification. 4: After a conversion has completed, a 2 TAD delay must complete before acquisition can begin again. During this time the holding capacitor is not connected to the selected A/D input channel. VAIN Cpin Rs ANx 5 pF VDD VT = 0.6V VT = 0.6V I leakage RIC ≤ 1k Sampling Switch SS RSS CHOLD = 120 pF Vss 6V Sampling Switch 5V 4V 3V 2V 5 6 7 8 9 10 11 ( kΩ ) VDD ± 500 nA Legend CPIN VT ILEAKAGE RIC SS CHOLD = Input Capacitance = Threshold Voltage = Leakage Current at the pin due to = Interconnect Resistance = Sampling Switch = Sample/hold capacitance (from DAC) various junctions 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-10  2000 Microchip Technology Inc. 26.5 Selecting the A/D Conversion Clock The A/D conversion time per bit is defined as TAD. The A/D conversion requires 11.5TAD per 10-bit conversion. The source of the A/D conversion clock is software selectable. The seven possible options for TAD are: • 2TOSC • 4TOSC • 8TOSC • 16TOSC • 32TOSC • 64TOSC • Internal A/D RC oscillator For correct A/D conversions, the A/D conversion clock (TAD) must be selected to ensure a minimum TAD time of 1.6 µs as shown in Electrical Specifications parameter 130. Table 26-1 and Table 26-2 show the resultant TAD times derived from the device operating frequencies and the selected A/D clock source. Table 26-1: TAD vs. Device Operating Frequencies (for Standard, C, Devices) Table 26-2: TAD vs. Device Operating Frequencies (for Extended, LC, Devices) AD Clock Source (TAD) Device Frequency Operation ADCS2:ADCS0 20 MHz 5 MHz 1.25 MHz 333.33 kHz 2TOSC 000 100 ns (2) 400 ns (2) 1.6 µs 6 µs 4TOSC 100 200 ns (2) 800 ns (2) 3.2 µs 12 µs 8TOSC 001 400 ns (2) 1.6 µs 6.4 µs 24 µs (3) 16TOSC 101 800 ns (2) 3.2 µs 12.8 µs 48 µs (3) 32TOSC 010 1.6 µs 6.4 µs 25.6 µs (3) 96 µs (3) 64TOSC 110 3.2 µs 12.8 µs 51.2 µs (3) 192 µs (3) RC 011 2-6 µs (1,4) 2-6 µs (1,4) 2-6 µs (1,4) 2-6 µs (1) Legend: Shaded cells are outside of recommended range. Note 1: The RC source has a typical TAD of 4 µs. 2: These values violate the minimum required TAD. 3: For faster conversion times, the selection of another clock source is recommended. 4: For device frequencies above 1 MHz, the device must be in SLEEP for the entire conversion, or the A/D accuracy may be out of specification. AD Clock Source (TAD) Device Frequency Operation ADCS2:ADCS0 4 MHz 2 MHz 1.25 MHz 333.33 kHz 2TOSC 000 500 ns (2) 1.0 µs (2) 1.6 µs (2) 6 µs 4TOSC 100 1.0 µs (2) 2.0 µs (2) 3.2 µs (2) 12 µs 8TOSC 001 2.0 µs (2) 4.0 µs 6.4 µs 24 µs (3) 16TOSC 101 4.0 µs 8.0 µs 12.8 µs 48 µs (3) 32TOSC 010 8.0 µs 16.0 µs 25.6 µs (3) 96 µs (3) 64TOSC 110 16.0 µs 32.0 µs 51.2 µs (3) 192 µs (3) RC 011 3-9 µs (1,4) 3-9 µs (1,4) 3-9 µs (1,4) 3-9 µs (1) Legend: Shaded cells are outside of recommended range. Note 1: The RC source has a typical TAD of 6 µs. 2: These values violate the minimum required TAD. 3: For faster conversion times, the selection of another clock source is recommended. 4: For device frequencies above 1 MHz, the device must be in SLEEP for the entire conversion, or the A/D accuracy may be out of specification. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-11 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 26.6 Configuring Analog Port Pins The ADCON1 and TRIS registers control the operation of the A/D port pins. The port pins that are desired as analog inputs must have their corresponding TRIS bits set (input). If the TRIS bit is cleared (output), the digital output level (VOH or VOL) will be converted. After a device RESET, pins that are multiplexed with analog inputs will be configured as an analog input. The corresponding TRIS bit will be set. The A/D operation is independent of the state of the CHS2:CHS0 bits and the TRIS bits. Note 1: When reading the port register, any pin configured as an analog input channel will read as cleared (a low level). Pins configured as digital inputs, will convert an analog input. Analog levels on a digitally configured input will not affect the conversion accuracy. 2: Analog levels on any pin that is defined as a digital input (including the AN7:AN0 pins), may cause the input buffer to consume current that is out of the devices specification. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-12  2000 Microchip Technology Inc. 26.7 A/D Conversions Example 26-3 shows how to perform an A/D conversion. The port pins are configured as analog inputs. The analog references (VREF+ and VREF-) are the device AVDD and AVSS. The A/D interrupt is enabled, and the A/D conversion clock is FRC. The conversion is performed on the AN0 pin (channel 0). The result of the conversion is left justified. Clearing the GO/DONE bit during a conversion will abort the current conversion. The A/D result register pair will NOT be updated with the partially completed A/D conversion sample. That is, the ADRESH:ADRESL registers will continue to contain the value of the last completed conversion (or the last value written to the ADRESH:ADRESL registers). After the A/D conversion is aborted, a 2TAD wait is required before the next acquisition is started. After this 2TAD wait, acquisition on the selected channel is automatically started. Example 26-3: A/D Conversion Figure 26-4: A/D Conversion TAD Cycles Note: The GO/DONE bit should NOT be set in the instruction that turns on the A/D, due to the required acquisition time. CLRF ADCON1 ; Configure A/D inputs, ; result is left justified BSF IPR1, ADIP ; High Priority. BSF PIE1, ADIE ; Enable A/D interrupts MOVLW 0xC1 ; RC Clock, A/D is on, MOVWF ADCON0 ; Channel 0 is selected BCF PIR1, ADIF ; Clear A/D interrupt flag bit BSF INTCON, PEIE ; Enable peripheral interrupts BSF INTCON, GIE ; Enable all interrupts ; ; Ensure that the required sampling time for the selected input ; channel has elapsed. Then the conversion may be started. ; BSF ADCON0, GO ; Start A/D Conversion : ; The ADIF bit will be set and the : ; GO/DONE bit is cleared upon : ; completion of the A/D Conversion. TAD1 TAD2 TAD3 TAD4 TAD5 TAD6 TAD7 TAD8 TAD11 Set GO bit Holding capacitor is disconnected from analog input (typically 100 ns) holding capacitor is connected to analog input. b9 b8 b7 b6 b5 b4 b3 b2 TAD9 TAD10 b1 b0 Tcy - TAD GO bit is cleared, Next Q4: ADRES is loaded, ADIF bit is set, Conversion Starts b0 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-13 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 Figure 26-5: Flowchart of A/D Operation Acquire ADON = 0 ADON = 0? GO = 0? A/D Clock GO = 0, ADIF = 0 Abort Conversion SLEEP Power-down A/D Wait 2TAD Wake-up Yes No Yes No No Yes Finish Conversion GO = 0, ADIF = 1 No Yes Finish Conversion GO = 0, ADIF = 1 Wait 2TAD Stay in SLEEP Selected Channel = RC? SLEEP No Yes Instruction? Start of A/D Conversion Delayed 1 Instruction Cycle From SLEEP? Power-down A/D Yes No Wait 2TAD Finish Conversion GO = 0, ADIF = 1 SLEEP Instruction? 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-14  2000 Microchip Technology Inc. 26.7.1 Faster Conversion - Lower Resolution Trade-off Not all applications require a result with 10-bits of resolution, but may instead require a faster conversion time. The A/D module allows users to make the trade-off of conversion speed to resolution. Regardless of the resolution required, the acquisition time is the same. To speed up the conversion, the clock source of the A/D module may be switched so that the TAD time violates the minimum specified time (Electrical Specifications parameter 130). Once the TAD time violates the minimum specified time, all the following A/D result bits are not valid (see A/D Conversion Timing in the Electrical Specifications section). The clock sources may only be switched between the three oscillator versions (cannot be switched from/to RC). The equation to determine the time before the oscillator can be switched is as follows: Since the TAD is based from the device oscillator, the user must use some method (a timer, software loop, etc.) to determine when the A/D oscillator may be changed. Example 26-4 shows a comparison of time required for a conversion with 4-bits of resolution, versus the 10-bit resolution conversion. The example is for devices operating at 20 MHz (the A/D clock is programmed for 32TOSC), and assumes that immediately after 6TAD, the A/D clock is programmed for 2TOSC. The 2TOSC violates the minimum TAD time since the last 6 bits will not be converted to correct values. Example 26-4: 4-bit vs. 10-bit Conversion Times Equation 26-3: Resolution/Speed Conversion Trade-off Freq. (MHz)(1) Resolution 4-bit 10-bit TAD 40 1.6 µs 1.6 µs TOSC 40 25 ns 25 ns TAD + N • TAD + (11 - N)(2TOSC) 40 8.5 µs 17.7 µs Note 1: A minimum TAD time of 1.6 µs is required. 2: If the full 10-bit conversion is required, the A/D clock source should not be changed. Conversion time = TAD + N • TAD + (11 - N)(2TOSC) Where: N = number of bits of resolution required 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-15 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 26.7.2 A/D Result Registers The ADRESH:ADRESL register pair is the location where the 10-bit A/D result is loaded at the completion of the A/D conversion. This register pair is 16-bits wide. The A/D module gives the flexibility to left or right justify the 10-bit result in the 16-bit result register. The A/D Format Select bit (ADFM) controls this justification. Figure 26-6 shows the operation of the A/D result justification. The extra bits are loaded with ‘0’s’. When the A/D module is disabled, these registers may be used as two general purpose 8-bit registers. Figure 26-6: A/D Result Justification 10-bit Result ADRESH ADRESL ADFM = 0 7 2107 0 10-bits RESULT ADRESH ADRESL 10-bits 7 0765 0 RESULT ADFM = 1 Right Justified Left Justified 0000 00 0000 00 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-16  2000 Microchip Technology Inc. 26.8 Operation During SLEEP The A/D module can operate during SLEEP mode. This requires that the A/D clock source be set to RC (ADCS2:ADCS0 = x11). When the RC clock source is selected, the A/D module waits one instruction cycle before starting the conversion. This allows the SLEEP instruction to be executed, which eliminates all internal digital switching noise from the conversion. When the conversion is completed, the GO/DONE bit will be cleared and the result is loaded into the ADRESH:ADRESL registers. If the A/D interrupt is enabled, the device will wake-up from SLEEP. If the A/D interrupt is not enabled, the A/D module will be turned off, although the ADON bit will remain set. When the A/D clock source is another clock option (not RC), a SLEEP instruction will cause the present conversion to be aborted and the A/D module to be turned off (to conserve power), though the ADON bit will remain set. Turning off the A/D places the A/D module in its lowest current consumption state. 26.9 Effects of a RESET A device RESET forces all registers to their RESET state. This forces the A/D module to be turned off, and any conversion is aborted. All pins that are multiplexed with analog inputs will be configured as an analog input. The corresponding TRIS bits will be set. The value that is in the ADRESH:ADRESL registers is not initialized from a Power-on Reset. The ADRESH:ADRESL registers will contain unknown data after a Power-on Reset. Note: For the A/D module to operate in SLEEP, the A/D clock source must be set to RC (ADCS2:ADCS0 = x11). To allow the conversion to occur during SLEEP, ensure the SLEEP instruction immediately follows the instruction that sets the GO/DONE bit. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-17 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 26.10 A/D Accuracy/Error In systems where the device frequency is low, use of the A/D RC clock is preferred. At moderate to high frequencies, TAD should be derived from the device oscillator. For a given range of analog inputs, the output digital code will be the same. This is due to the quantization of the analog input to a digital code. Quantization error is typically ± 1/2 LSb and is inherent in the analog to digital conversion process. The only way to reduce quantization error is to increase the resolution of the A/D converter. Offset error measures the first actual transition of a code versus the first ideal transition of a code. Offset error shifts the entire transfer function. Offset error can be calibrated out of a system or introduced into a system, through the interaction of the total leakage current and source impedance at the analog input. Gain error measures the maximum deviation of the last actual transition and the last ideal transition, adjusted for offset error. This error appears as a change in slope of the transfer function. The difference in gain error to full scale error, is that full scale does not take offset error into account. Gain error can be calibrated out in software. Linearity error refers to the uniformity of the code changes. Linearity errors cannot be calibrated out of the system. Integral non-linearity error measures the actual code transition versus the ideal code transition, adjusted by the gain error for each code. Differential non-linearity measures the maximum actual code width versus the ideal code width. This measure is unadjusted. The maximum pin leakage current is specified in Electrical Specifications parameter D060. TAD must not violate the minimum and should be minimized to reduce inaccuracies due to noise and sampling capacitor bleed off. In systems where the device will enter SLEEP mode after the start of the A/D conversion, the RC clock source selection is required. In this mode, the digital noise from the modules in SLEEP are stopped. This method gives high accuracy. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-18  2000 Microchip Technology Inc. 26.11 Connection Considerations If the input voltage exceeds the rail values (VSS or VDD) by greater than 0.3V, then the accuracy of the conversion is out of specification. An external RC filter is sometimes added for anti-aliasing of the input signal. The R component should be selected to ensure that the total source impedance is kept under the 2.5 kΩ recommended specification. Any external components connected (via hi-impedance) to an analog input pin (capacitor, zener diode, etc.) should have very little leakage current at the pin. 26.12 Transfer Function The ideal transfer function of the A/D converter is as follows: the first transition occurs when the analog input voltage (VAIN) is 1 LSb (or Analog VREF / 1024) (Figure 26-7). Figure 26-7: A/D Transfer Function Digital Code Output 3FEh 003h 002h 001h 000h 0.5 LSb 1 LSb 1.5 LSb 2 LSb 2.5 LSb 1022 LSb 1022.5 LSb 3 LSb Analog Input Voltage 3FFh 1023 LSb 1023.5 LSb 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-19 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 26.13 Initialization Example 26-5 shows an initialization of the A/D module. Example 26-5: A/D Initialization CLRF ADCON1 ; Configure A/D inputs BSF PIE1, ADIE ; Enable A/D interrupts BSF IPR1, ADIP ; High Priority MOVLW 0xC1 ; RC Clock, A/D is on, MOVWF ADCON0 ; Channel 0 is selected MOVLW 0x4E ; Left Justified, AN0 is analog MOVWF ADCON1 ; Vref comes from AVDD and AVSS BCF PIR1, ADIF ; Clear A/D interrupt flag bit BSF INTCON, PEIE ; Enable peripheral interrupts BSF INTCON, GIE ; Enable all interrupts ; ; Ensure that the required sampling time for the selected input ; channel has elapsed. Then the conversion may be started. ; BSF ADCON0, GO ; Start A/D Conversion : ; The ADIF bit will be set and the : ; GO/DONE bit is cleared upon : ; completion of the A/D conversion. 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-20  2000 Microchip Technology Inc. 26.14 Design Tips Question 1: I find that the Analog to Digital Converter result is not always accurate. What can I do to improve accuracy? Answer 1: 1. Make sure you are meeting all of the timing specifications. If you are turning the module off and on, there is a minimum delay you must wait before taking a sample. If you are changing input channels, there is a minimum delay you must wait for this as well, and finally there is TAD, which is the time selected for each bit conversion. This is selected in ADCON0 and should be between 1.6 and 6 µs. If TAD is too short, the result may not be fully converted before the conversion is terminated, and if TAD is made too long, the voltage on the sampling capacitor can decay before the conversion is complete. These timing specifications are provided in the “Electrical Specifications” section. See the device data sheet for device specific information. 2. Often the source impedance of the analog signal is high (greater than 1 kOhms), so the current drawn from the source to charge the sample capacitor can affect accuracy. If the input signal does not change too quickly, try putting a 0.1 µF capacitor on the analog input. This capacitor will charge to the analog voltage being sampled and supply the instantaneous current needed to charge the 120 pF internal holding capacitor. 3. In systems where the device frequency is low, use of the A/D clock derived from the device oscillator is preferred...this reduces, to a large extent, the effects of digital switching noise. In systems where the device will enter SLEEP mode after start of A/D conversion, the RC clock source selection is required.This method gives the highest accuracy. Question 2: After starting an A/D conversion may I change the input channel (for my next conversion)? Answer 2: After the holding capacitor is disconnected from the input channel, typically 100 ns after the GO bit is set, the input channel may be changed. Question 3: Do you know of a good reference on A/D’s? Answer 3: A good reference for understanding A/D conversions is the “Analog-Digital Conversion Handbook” third edition, published by Prentice Hall (ISBN 0-13-03-2848-0). Question 4: I migrated my code from a PIC18CXX2 device with 10-bit A/D to another device with a 10-bit A/D (such as a PIC18CXX8) and the A/D does not seem to operate the same. What’s going on? Answer 4: The 10-bit A/D on the PIC18CXX2 device is the compatible 10-bit A/D module. This module has its ADCON bits in the same locations as the PICmicros Mid-Range 10-bit A/D module. The standard PIC18CXXX 10-bit A/D module (as found on the PIC18CXX8 device) has optimized the bit locations to ease configuration of the module. 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39527A-page 26-21 Section 26. 10-bit A/D Converter 10-bit A/D Converter 26 26.15 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Base-Line, the Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the 10-bit A/D module are: Title Application Note # Using the Analog to Digital Converter AN546 Four Channel Digital Voltmeter with Display and Keyboard AN557 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39527A-page 26-22  2000 Microchip Technology Inc. 26.16 Revision History Revision A This is the initial released revision of the Enhanced MCU Compatible 10-bit A/D module description. 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39528A-page 27-1 Low Voltage Detectr 27 Section 27. Low Voltage Detect HIGHLIGHTS This section of the manual contains the following major topics: 27.1 Introduction .................................................................................................................. 27-2 27.2 Control Register ........................................................................................................... 27-4 27.3 Operation ..................................................................................................................... 27-5 27.4 Operation During SLEEP ............................................................................................. 27-6 27.5 Effects of a RESET ...................................................................................................... 27-6 27.6 Initialization .................................................................................................................. 27-7 27.7 Design Tips .................................................................................................................. 27-8 27.8 Related Application Notes............................................................................................ 27-9 27.9 Revision History ......................................................................................................... 27-10 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39528A-page 27-2  2000 Microchip Technology Inc. 27.1 Introduction In many applications, the ability to determine if the device voltage (VDD) is below a specified voltage level is a desirable feature. A window of operation for the application can be created where the application software can do "housekeeping tasks" before the device voltage exits the valid operating range. This can be done using the Low Voltage Detect module. This module is software programmable circuitry, where a device voltage trip point can be specified. When the voltage of the device becomes lower than the specified point, an interrupt flag is set. If the interrupt is enabled, the program execution will branch to the interrupt vector address, and the software can then respond to that interrupt source. The Low Voltage Detect circuitry is completely under software control. This allows the circuitry to be "turned off" by the software, which minimizes the current consumption for the device. Figure 27-1 shows a possible application voltage curve (typically for batteries). Over time the device voltage decreases. When the device voltage equals voltage VA, the LVD logic generates an interrupt. This occurs at time TA. The application software then has until the device voltage is no longer in valid operating range to have shut down the system. Voltage point VB is the minimum valid operating voltage specification. This gives a time TB. The total time for shutdown is TB - TA. Figure 27-1: Typical Low Voltage Detect Application Time Voltage VA VB TA VA = LVD trip point VB = Minimum valid device operating voltage Legend TB 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39528A-page 27-3 Section 27. Low Voltage Detect Low Voltage Detect 27 Figure 27-2 shows the block diagram for the LVD module. A comparator uses an internally generated reference voltage as the set point. When the selected tap output of the device voltage crosses the set point (is lower then), the LVDIF bit is set. Each node in the resister divider represents a “trip point” voltage. The “trip point” voltage is the minimum supply voltage level at which the device can operate before the LVD module asserts an interrupt. When the supply voltage is equal to the trip point, the voltage tapped off of the resistor array is equal to the voltage generated by the internal voltage reference module. The comparator then generates an interrupt signal setting the LVDIF bit. This voltage is software programmable to any one of 16 values (see Figure 27-2). The trip point is selected by programming the LVDL3:LVDL0 bits (LVDCON<3:0>). Figure 27-2: Low Voltage Detect (LVD) Block Diagram VDD LVDIF 16 to 1 MUX LVDEN LVD Control Register Internally generated reference voltage LVDIN 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39528A-page 27-4  2000 Microchip Technology Inc. 27.2 Control Register The Low Voltage Detect Control register controls the operation of the Low Voltage Detect circuitry. Register 27-1: LVDCON Register U-0 U-0 R-0 R/W-0 R/W-0 R/W-1 R/W-0 R/W-1 — — IRVST LVDEN LVDL3 LVDL2 LVDL1 LVDL0 bit 7 bit 0 bit 7:6 Unimplemented: Read as '0' bit 5 IRVST: Internal Reference Voltage Stable Flag bit 1 = Indicates that the Low Voltage Detect logic will generate the interrupt flag at the specified voltage range. 0 = Indicates that the Low Voltage Detect logic will not generate the interrupt flag at the specified voltage range, and LVD interrupt should not be enabled bit 4 LVDEN: Low-voltage Detect Power Enable bit 1 = Enables LVD, powers up LVD circuit 0 = Disables LVD, powers down LVD circuit bit 3:0 LVDL3:LVDL0: Low Voltage Detection Limit bits The following shows the typical limits for the low voltage detect circuitry. Refer to the device data sheet electrical specifications for the actual tested limit. 1111 = External analog input is used (input comes from the LVDIN pin) 1110 = 4.5V min - 4.77V max. 1101 = 4.2V min - 4.45V max. 1100 = 4.0V min - 4.24V max. 1011 = 3.8V min - 4.03V max. 1010 = 3.6V min - 3.82V max. 1001 = 3.5V min - 3.71V max. 1000 = 3.3V min - 3.50V max. 0111 = 3.0V min - 3.18V max. 0110 = 2.8V min - 2.97V max. 0101 = 2.7V min - 2.86V max. 0100 = 2.5V min - 2.65V max. 0011 = 2.4V min - 2.54V max. 0010 = 2.2V min - 2.33V max. 0001 = 2.0V min - 2.12V max. 0000 = 1.8V min - 1.91V max. Note 1: LVDL3:LVDL0 modes which result in a trip point below the valid operating voltage of the device are not tested. 2: See the “Electrical Specifications” section, parameter 32 in the Device Data Sheet for tested limits. Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39528A-page 27-5 Section 27. Low Voltage Detect Low Voltage Detect 27 27.3 Operation The LVD module is useful to add robustness into the application. The device can monitor the state of the device voltage. When the device voltage enters the voltage window near the lower limit of the valid operating voltage range, the device can save values to ensure a "clean" shutdown through the brown-out. Depending on the power source for the device voltage, the voltage normally decreases relatively slowly. This means that the LVD module does not need to be constantly operating. To decrease the current requirements, the LVD circuitry only needs to be enabled for short periods, where the voltage is checked. After doing the check, the LVD module may be disabled. Each time that the LVD module is enabled, the circuitry requires some time to stabilize. After the circuitry has stabilized, all status flags may be cleared. The module will then indicate the proper state of the system. Steps to setup the LVD module: 1. Write the value to the LVDL3:LVDL0 bits (LVDCON register) which selects the desired LVD Trip Point. 2. Ensure that LVD interrupts are disabled (the LVDIE bit is cleared or the GIE bit is cleared). 3. Enable the LVD module (set the LVDEN bit in the LVDCON register). 4. Wait for the LVD module to stabilize (the IRVST bit to become set). 5. Clear the LVD interrupt flag which may have falsely become set while the LVD module stabilized (clear the LVDIF bit). 6. Enable the LVD interrupt (set the LVDIE and the GIE bits). Figure 27-3 shows some waveforms that the LVD module may be used to detect. Figure 27-3: Low Voltage Detect Waveforms Note: The system design should be done to ensure that the application software is given adequate time to save values before the device exits the valid operating range or is forced into a Brown-out Reset. . VLVD VDD LVDIF VLVD VDD Enable LVD Internally Generated 50 ms LVDIF may not be set Enable LVD 50 ms LVDIF LVDIF cleared in software LVDIF cleared in software LVDIF cleared in software, CASE 1: CASE 2: LVDIF remains set since LVD condition still exists Reference stable Internally Generated Reference stable 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39528A-page 27-6  2000 Microchip Technology Inc. 27.3.1 Reference Voltage Set Point The internal reference voltage of the LVD module may be used by other internal circuitry (e.g., the programmable Brown-out Reset). If these circuits are disabled (lower power consumption), the reference voltage circuit requires stabilization time before a low voltage condition can be reliably detected. This time is specified in electrical specification parameter # 36. The low-voltage interrupt flag will not be enabled until a stable reference voltage is reached. Refer to the timing diagram in Figure 27-3. 27.3.2 Current Consumption When the module is enabled the LVD comparator and voltage divider are enabled and will consume static current. The voltage divider can be tapped from multiple places in the resistor array. Total current consumption when enabled is specified in electrical specification parameter D022B (typically < 50 µA). 27.4 Operation During SLEEP When enabled, the LVD circuitry continues to operate during SLEEP. If the device voltage crosses the trip point, the LVDIF bit will be set and the device will wake-up from SLEEP. Device execution will continue from the interrupt vector address, if interrupts have been globally enabled. 27.5 Effects of a RESET A device RESET forces all registers to their RESET state. This forces the LVD module to be turned off. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39528A-page 27-7 Section 27. Low Voltage Detect Low Voltage Detect 27 27.6 Initialization Example 27-1 shows an initialization of the LVD module. Example 27-1: LVD Initialization MOVLW 0x14 ; Enable LVD, Trip point = 2.5V MOVWF LVDCON ; LVD_STABLE BTFSS LVDCON, IRVST ; Has LVD circuitry stabilized? GOTO LVD_STABLE ; NO, Wait longer BCF PIR, LVDIF ; YES, clear LVD interrupt flag BSF PIE, LVDIE ; Enable LVD interrupt 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39528A-page 27-8  2000 Microchip Technology Inc. 27.7 Design Tips Question 1: The LVD circuitry seems to be generating random interrupts? Answer 1: Ensure that the LVD circuitry is stable before enabling the LVD interrupt. This is done by monitoring the IRVST bit. Once the IRVST bit is set, the LVDIF bit should be cleared and then the LVDIE bit may be set. Question 2: How can I reduce the current consumption of the module? Answer 2: Low Voltage Detect is used to monitor the device voltage. The power source is normally a battery that ramps down slowly. This means that the LVD circuity can be disabled for most of the time, and only enabled occasionally to do the device voltage check. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39528A-page 27-9 Section 27. Low Voltage Detect Low Voltage Detect 27 27.8 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Base-Line, the Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the LVD module are: Title Application Note # No related application notes at this time Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39528A-page 27-10  2000 Microchip Technology Inc. 27.9 Revision History Revision A This is the initial released revision of the Enhanced MCU Low Voltage Detect module description. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39529A-page 28-1 and Sleep Mode Watchdog Timer 28 Section 28. WDT and SLEEP Mode HIGHLIGHTS This section of the manual contains the following major topics: 28.1 Introduction .................................................................................................................. 28-2 28.2 Control Register ........................................................................................................... 28-3 28.3 Watchdog Timer (WDT) Operation .............................................................................. 28-4 28.4 SLEEP (Power-Down) Mode........................................................................................ 28-5 28.5 Initialization ................................................................................................................ 28-11 28.6 Design Tips ................................................................................................................ 28-12 28.7 Related Application Notes.......................................................................................... 28-13 28.8 Revision History ......................................................................................................... 28-14 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39529A-page 28-2  2000 Microchip Technology Inc. 28.1 Introduction The Watchdog Timer and SLEEP functions are two functions that can enhance the system. The Watchdog Timer may be used to return to operating mode, or to cause a controller RESET if the program begins to behave erratically. This enhances the overall operation of the system. The Watchdog Timer (WDT) is a free running on-chip RC oscillator that does not require any external components. The block diagram is shown in Figure 28-1. This RC oscillator is separate from the device RC oscillator of the OSC1/CLKI pin. This means that the WDT will run, even if the clock on the OSC1/CLKI and OSC2/CLKO pins has been stopped, for example, by execution of a SLEEP instruction. The Watchdog Timer (WDT) is enabled/disabled by a device configuration bit. If the WDT is enabled, software execution may not disable this function. When the WDTEN configuration bit is cleared, the SWDTEN bit enables/disables the operation of the WDT. Figure 28-1: Watchdog Timer Block Diagram The SLEEP function halts controller activity and reduces current consumption to a minimum. The SLEEP mode is a reduced power state, where it is possible to halt almost all activity in the controller. In this mode, power consumption is very low, allowing for long term operation from battery powered applications. Normal operation may be resumed when any of several interrupts occur, the WDT times out, or a RESET occurs. WDT Timer Postscaler WDTEN 8 - to - 1 MUX WDTPS<2:0> WDT Time-out 8 SWDTEN bit Configuration bit Note: WDTPS2:WDTPS0 are bits in a configuration register. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39529A-page 28-3 Section 28. Watchdog Timer and SLEEP Mode and Sleep Mode Watchdog Timer 28 28.2 Control Register Register 28-1 shows the WDTCON register. This is a readable and writable register that contains the SWDTEN control bit. If the WDT enable configuration bit has been cleared, this software controlled bit enables or disables the WDT. Register 28-1: WDTCON Register U-0 U-0 U-0 U-0 U-0 U-0 U-0 R/W-0 — — — — — — — SWDTEN bit 7 bit 0 bit 7:1 Unimplemented: Read as ’0’ bit 0 SWDTEN: Software Controlled Watchdog Timer Enable bit 1 = Watchdog Timer is on 0 = Watchdog Timer is turned off if the WDTEN configuration bit is ’0’ Legend R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39529A-page 28-4  2000 Microchip Technology Inc. 28.3 Watchdog Timer (WDT) Operation During normal operation, a WDT time-out generates a device RESET. If the device is in SLEEP mode, a WDT time-out causes the device to wake-up and continue with normal operation. This is known as a WDT wake-up. The WDT can be permanently enabled by setting the WDTEN configuration bit. If the WDT configuration bit disables the WDT, then software can be used to enable/disable the WDT through setting/clearing the SWDTEN bit. 28.3.1 WDT Period The WDT has a nominal time-out period of 18 ms with no postscaler (see the “Electrical Specifications” section, parameter 31). The time-out period varies with temperature, VDD and process variations from part to part (see DC parameters in the “Electrical Specifications” section). If longer time-outs are desired, a postscaler with a division ratio of up to 1:128 can be assigned to the WDT. Thus, time-out periods of up to 2.3 seconds can be realized. The postscaler assignment is specified at time of device programming through the device configuration bits. The CLRWDT and SLEEP instructions clear the WDT counter and the WDT postscaler which prevents it from timing out and generating a device RESET. When a CLRWDT instruction is executed and the prescaler is assigned to the WDT, the prescaler count will be cleared, but the prescaler assignment is not changed. The TO bit in the RCON register will be cleared upon a Watchdog Timer time-out (WDT Reset and WDT wake-up). 28.3.2 Clearing the WDT Counter The CLRWDT instruction will force the count value of the WDT counter to ’0’. When the WDT is disabled (WDTEN configuration bit = ’0’ and SWDTEN is clear), the WDT counter is forced to ’0’ and the internal WDT clock source is disabled. Then, when the WDT is enabled (setting the SWDTEN bit when previously cleared), the WDT counter starts from a value of ’0’. 28.3.3 WDT Considerations It should also be taken in account that under worst case conditions (VDD = Minimum, Temperature = Maximum, WDT postscaler = Maximum), it may take several seconds before a WDT time-out occurs. 28.3.4 Effects of a RESET When a device RESET occurs, the Watchdog Timer counter and postscaler counter are cleared and the TO bit is set. Table 28-1: Summary of Watchdog Timer Registers Name Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 CONFIG2H — — — — WDTPS2 WDTPS1 WDTPS0 WDTEN WDTCON — — — — — — — SWDTEN RCON IPEN LWRT — RI TO PD POR BOR Legend: Shaded cells are not used by the Watchdog Timer. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39529A-page 28-5 Section 28. Watchdog Timer and SLEEP Mode and Sleep Mode Watchdog Timer 28 28.4 SLEEP (Power-Down) Mode SLEEP (Power-down) mode is the lowest current consumption state and is entered by executing a SLEEP instruction. The device oscillator is turned off, so no system clocks are occurring in the device. If enabled, the Watchdog Timer will be cleared but keeps running, the PD bit in the RCON register is cleared, the TO bit is set, and the oscillator driver is turned off. The I/O ports maintain the status they had before the SLEEP instruction was executed (driving high, low, or hi-impedance). For lowest current consumption in this mode, all I/O pins should be either at VDD or VSS, with no external circuitry drawing current from the I/O pin and modules that are specified to have a delta SLEEP current, should be disabled. I/O pins that are hi-impedance inputs should be pulled high or low externally, to avoid switching currents caused by floating inputs. The contribution from on-chip pull-ups on PORTB should be considered. During SLEEP, the MCLR pin must be at a valid high level. Some features of the device consume a delta current. These are enabled/disabled by device configuration bits. These features include the Watchdog Timer (WDT), LVD, and Brown-out Reset (BOR) circuitry modules. 28.4.1 Wake-up from SLEEP There are several ways to wake the controller from SLEEP. The WDT can wake-up the controller when it times out. A RESET will wake the controller and cause the program to restart, and interrupts (from peripherals or external sources) will wake the controller from SLEEP. The device can wake-up from SLEEP through one of the following events: 1. Any device RESET, such as MCLR pin = VIL, VDD = VBOR (if enabled). 2. Watchdog Timer Wake-up (if WDT was enabled). 3. Any peripheral module which can set its interrupt flag while in SLEEP, such as: - An external INT pin - Change on Port pin - Comparators - A/D - Timer1 - Timer3 - LVD - MSSP - Capture - PSP read or write - CCP1 - CCP2 - Addressable USART - PORTB Interrupt on Change - External Interrupts - Parallel Slave Port - Voltage Reference (bandgap) - WDT The first event will RESET the device upon wake-up. However, the latter two events will wake the device and then resume program execution. The TO and PD bits in the RCON register can be used to determine the cause of device RESET. The PD bit, which is set on power-up, is cleared when SLEEP is invoked. The TO bit is cleared if WDT time-out occurred (and caused a wake-up). When the SLEEP instruction is being executed, the next instruction (PC + 2) is pre-fetched. For the device to wake-up through an interrupt event, the corresponding interrupt enable bit must be set (enabled). Wake-up is regardless of the state of the GIE bit. If the GIE bit is clear (disabled), the device continues execution at the instruction after the SLEEP instruction. If the GIE bit is set (enabled), the device executes the instruction after the SLEEP instruction and then branches to the interrupt address. In cases where the execution of the instruction following SLEEP is not desirable, the user should have a NOP after the SLEEP instruction. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39529A-page 28-6  2000 Microchip Technology Inc. 28.4.2 Wake-up Using Interrupts When interrupts are globally disabled (GIE cleared) and any interrupt source has both its interrupt enable bit and interrupt flag bit set, one of the following events will occur: • If an interrupt condition (interrupt flag bit and interrupt enable bits are set) occurs before the execution of a SLEEP instruction, the SLEEP instruction will complete as a NOP. Therefore, the WDT and WDT postscaler will not be cleared, the TO bit will not be set and PD bit will not be cleared. • If the interrupt condition occurs during or after the execution of a SLEEP instruction, the device will immediately wake-up from SLEEP. The SLEEP instruction will be completely executed before the wake-up. Therefore, the WDT and WDT postscaler will be cleared, the TO bit will be set and the PD bit will be cleared. Even if the flag bits were checked before executing a SLEEP instruction, it may be possible for flag bits to become set before the SLEEP instruction completes. To determine whether a SLEEP instruction executed, test the PD bit. If the PD bit is set, the SLEEP instruction was executed as a NOP. To ensure that the WDT is clear, a CLRWDT instruction should be executed before a SLEEP instruction. Figure 28-2: Wake-up from SLEEP Through Interrupt Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 OSC1 CLKOUT(4) INT pin INTF flag (INTCON<1>) GIE bit (INTCON<7>) INSTRUCTION FLOW PC Instruction fetched Instruction executed PC PC+2 PC+4 Inst(PC) = SLEEP Inst(PC - 1) Inst(PC + 2) SLEEP Processor in SLEEP Interrupt Latency(3) Inst(PC + 4) Inst(PC + 2) Inst(INT_addr) Inst(INT_addr + 1) Dummy cycle Inst(INT_addr) PC+4 INT_addr INT_addr + 1 Dummy cycle TOST(2) PC+4 Note 1: XT, HS or LP oscillator mode assumed. 2: TOST = 1024TOSC (drawing not to scale). This delay will not occur for RC and EC osc modes. 3: GIE = '1' assumed. In this case, after wake-up, the processor jumps to the interrupt routine. If GIE = '0', execution will continue in-line. 4: CLKOUT is not available in these osc modes, but shown here for timing reference. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39529A-page 28-7 Section 28. Watchdog Timer and SLEEP Mode and Sleep Mode Watchdog Timer 28 Interrupt sources can wake the controller from SLEEP without actually causing an interrupt. The interrupt source must have its interrupt enable flag set, but GIE does not need to be set. If GIE is clear, the controller will wake without vectoring to an interrupt. If GIE is set, the controller will vector to an interrupt. If interrupt priority is not used, all interrupt priority bits are set. If interrupt priority is used (any interrupt priority bit is cleared), GIEH controls high priority interrupts and GIEL controls low priority interrupts. Table 28-2 shows the response to the interrupt flag bits depending on the state of the interrupt enable and priority bits. Table 28-2: SLEEP Mode, Interrupt Enable Bits, and Interrupt Results Interrupt Source GIE/GIEH PEIE/GIEL Interrupt Priority Peripheral Interrupt Flag Response to Interrupt Any interrupt source that operates during SLEEP X X X 0 SLEEP 10 0 low priority 1 wake 01 1 high priority 1 wake 0 0 X 1 wake 1 0 1 1 High priority vector followed 1 1 0 1 Low priority vector followed Legend: X is don’t care. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39529A-page 28-8  2000 Microchip Technology Inc. 28.4.3 Effects of SLEEP Mode on the On-Chip Oscillator When the device executes a SLEEP instruction, the Watchdog Timer and prescaler counter are cleared (if the WDT is enabled), the on-chip clocks and oscillator are turned off and the controller is held at the beginning of an instruction cycle (Q1 state). With the oscillator off, the OSC1 and OSC2 signals will stop oscillating. Since all the transistor switching currents have been removed, SLEEP mode achieves the lowest current consumption of the device (only leakage currents). Enabling any on-chip feature that will operate during SLEEP will increase the current consumed during SLEEP. The user can wake from SLEEP through external RESET, Brown-out Reset (if enabled), external interrupt, Watchdog Timer time-out or a peripheral interrupt. Table 28-3: Oscillator Selections, SLEEP Mode, and Waking from SLEEP OSC Mode OSC1 Pin in SLEEP OSC2 Pin in SLEEP Waking Delays OSC1 in Run OSC2 in Run RC Floating, pulled high At logic low None R and C set frequency CLKO (4Tosc) RCIO Floating, pulled high Configured as I/O pin None R and C set frequency Configured as I/O pin LP At quiescent voltage level At quiescent voltage level TOST (1) XTAL/res XTAL/res XT At quiescent voltage level At quiescent voltage level TOST (1) XTAL/res XTAL/res HS At quiescent voltage level At quiescent voltage level TOST (1) XTAL/res XTAL/res HS w/PLL At quiescent voltage level At quiescent voltage level TOST (1) + TPLL (2) XTAL/res XTAL/res EC Driven by external clock source At logic low None Driven by external clock source CLKO (4TOSC) ECIO Driven by external clock source Configured as I/O pin None Driven by external clock source Configured as I/O pin Note 1: OST (Oscillator Start-up Timer) counts 1024 oscillator cycles before allowing controller clocks to resume. This provides time for the oscillator to start-up and stabilize. 2: A TPLL delay is required to allow the PLL to lock to the oscillator frequency. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39529A-page 28-9 Section 28. Watchdog Timer and SLEEP Mode and Sleep Mode Watchdog Timer 28 28.4.4 Wake-up Delays Several factors affect how much time the controller requires to return to operating mode from SLEEP. These include oscillator mode and the use of the PLL. The Oscillator Start-up Timer, OST, counts 1024 oscillator cycles to allow the oscillator to start-up and stabilize before allowing system clocks to resume. The OST is not enabled for RC and EC oscillator modes. 28.4.4.1 Oscillator With PLL Enabled Time-out Sequence After Wake-up The Oscillator Start-up Timer (OST) provides a 1024 oscillator cycle delay after a wake-up from SLEEP has occurred. 1024 oscillator cycles are not a sufficient amount of time to allow the PLL to lock at high frequencies. An additional TPLL time is required to allow the PLL to lock before allowing system clocks to resume. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39529A-page 28-10  2000 Microchip Technology Inc. 28.4.5 Peripheral Module Operation During SLEEP Table 28-4 gives an overview of which devices operate during SLEEP. For further details, refer to the individual sections in this reference manual. Table 28-4: Peripheral Modules Active in SLEEP Mode 28.4.6 Effects of a WDT Time-out If the WDT has been enabled, either by the WDTEN configuration bit (=’1’) or by the SWDTEN bit being set, the WDT will wake-up the controller from SLEEP mode and clear the TO bit. 28.4.7 Effects of a Device RESET When MCLR is asserted, TO is set and PD is clear. All other bits in RCON are unchanged. The controller will resume code execution at the RESET vector address. Peripheral Module Operates During SLEEP? Mode of Operation Wakes from SLEEP? Timer1, Timer3 Yes External clock/U.S.C.G., Asynchronous Counter mode Yes A/D Yes A/D clock = RC clock Yes CCP1, CCP2 Yes Only capture available. Yes, do not rely on capture value MSSP Yes I 2C – Non-master modes SPI – Slave mode Yes Yes Addressable USART Yes Synchronous slave mode Yes PORTB Interrupt on Change Yes All Yes External Interrupts Yes All Yes Parallel Slave Port Yes All Yes LVD Yes All Yes Volt Reference (bandgap) Yes If required to support LVD, and A/D No WDT Yes All Yes 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39529A-page 28-11 Section 28. Watchdog Timer and SLEEP Mode and Sleep Mode Watchdog Timer 28 28.5 Initialization No initialization code at this time. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39529A-page 28-12  2000 Microchip Technology Inc. 28.6 Design Tips Question 1: My system voltage drops and then returns to the specified device voltage range. The device is not operating correctly and the WDT does not reset and return the device to proper operation. Answer 1: The WDT was not designed to be a recovery from a brown-out condition. It was designed to recover from errant software operation (the device remaining in the specified operating ranges). If your system can be subjected to brown-outs, either the on-chip brown-out circuitry should be enabled or an external brown-out circuit should be implemented. Question 2: Device RESETS even though I do the CLRWDT instruction in my loop. Answer 2: Make sure that the loop with the CLRWDT instruction meets the minimum specification of the WDT (not the typical). Question 3: Device never gets out of RESETS. Answer 3: On power-up, you must take into account the Oscillator Start-up time (Tost). Sometimes it helps to put the CLRWDT instruction at the beginning of the loop, since this start-up time may be variable. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39529A-page 28-13 Section 28. Watchdog Timer and SLEEP Mode and Sleep Mode Watchdog Timer 28 28.7 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range or High-End families), but the concepts are pertinent and could be used (with modification and possible limitations). The current application notes related to the WDT and SLEEP Mode are: Title Application Note # Power-up Trouble Shooting AN607 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39529A-page 28-14  2000 Microchip Technology Inc. 28.8 Revision History Revision A This is the initial released revision of the Enhanced MCU Watchdog Timer and SLEEP mode description. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39530A-page 29-1 Device Configuration Bits 29 Section 29. Device Configuration Bits HIGHLIGHTS This section of the manual contains the following major topics: 29.1 Introduction .................................................................................................................. 29-2 29.2 Configuration Word Bits ............................................................................................... 29-3 29.3 Program Verification/Code Protection ........................................................................ 29-10 29.4 ID Locations ............................................................................................................... 29-11 29.5 Device ID ................................................................................................................... 29-11 29.6 Design Tips ................................................................................................................ 29-12 29.7 Related Application Notes.......................................................................................... 29-13 29.8 Revision History ......................................................................................................... 29-14 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39530A-page 29-2  2000 Microchip Technology Inc. 29.1 Introduction The device configuration bits allow each user to customize certain aspects of the device to the needs of the application. When the device powers up, the state of these bits determines the modes that the device uses. Section 29.2 “Configuration Word Bits” discusses the configuration bits and the modes to which they can be configured. These bits are mapped in program memory locations starting at address 300000h. These locations are accessible during normal device operation. The configuration bits can be programmed (read as '0') or left unprogrammed (read as '1') to select various device configurations. The ability to change these settings once they have been programmed depends on the memory technology and the package type. This is discussed below: • Read Only Memory (ROM) devices: These bits are specified at time of ROM code submittal; once the device is masked, these bits can not be changed (would require a new mask code). • One Time Programmable (OTP) devices: Once the bit is programmed (’0’), it may not be changed. • Windowed EPROM devices: Once these bits are programmed (’0’), the device must be UV erased to return the configuration word to the erased state. UV erasing the device also erases the program memory. Window devices are for debugging purposes. • FLASH devices: These bits may be erased and reprogrammed. Note: Microchip does not recommend code-protecting windowed devices. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39530A-page 29-3 Section 29. Device Configuration Bits Device Configuration Bits 29 29.2 Configuration Word Bits These configuration bits specify some of the device modes and are programmed by a device programmer, or by using the In-Circuit Serial ProgrammingTM (ICSP) feature of the Enhanced Architecture devices. The placement of these configuration bits is automatically handled when you select the device in your device programmer. The desired state of the configuration bits may be specified in the source code (dependent on the language tool used), or through the programming interface. After the device has been programmed, the application software may read the configuration bit values through the Table read instructions. For additional information, please refer to the Programming Specification of the device. Note 1: Always ensure that your device programmer has the same device selected as you are programming. 2: Microchip recommends that the desired configuration bit states be embedded into the application source code. This is easily done in the MPASM assembler by the use of the CONFIG directive. See Subsection 29.2.1 “MPASM’s CONFIG Directive.” 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39530A-page 29-4  2000 Microchip Technology Inc. Register 29-1: Configuration Bits P/R-u Bit placement is device dependent A19DIS: Disable A19:A16 Drivers bit This bit disables the A19:A16 address lines of the system bus so that these pins may be used as general purpose I/O. 1 = Drivers enabled 0 = Drivers disabled A15DIS: Disable AD15:AD12 Drivers bit This bit disables the AD15:AD12 address lines of the system bus so that these pins may be used as general purpose I/O. The AD15:AD12 address lines may only be disabled when the system bus is configured for 8-bit data (BW16 = ’0’). When BW16 = ’1’ 1 = Drivers enabled (state of A15DIS is ignored) 0 = Drivers enabled (state of A15DIS is ignored) When BW16 = ’0’ 1 = Drivers enabled 0 = Drivers disabled A11DIS: Disable AD11:AD8 Drivers bit This bit disables the AD11:AD8 address lines of the system bus so that these pins may be used as general purpose I/O. The AD11:AD8 address lines may only be disabled when the system bus is configured for 8-bit data (BW16 = ’0’). When BW16 = ’1’ 1 = Drivers enabled (state of A11DIS is ignored) 0 = Drivers enabled (state of A11DIS is ignored) When BW16 = ’0’ 1 = Drivers enabled 0 = Drivers disabled BADIS: Byte Address BA0 Disable bit 1 = Drivers enabled 0 = Drivers disabled BSDIS: Byte Select UB,LB Disable bit 1 = Drivers enabled 0 = Drivers disabled BOREN: Brown-out Reset Enable bit 1 = Brown-out Reset enabled 0 = Brown-out Reset disabled BORV1:BORV0: Brown-out Reset Voltage bits These bits specify the trip point for the Brown-out Reset circuitry. The values shown below are for a typical device. Please refer to the device data sheet “Electrical Specifications” section for the tested range. 11 = VBOR set to 2.5V or 1.8V (device dependent) 10 = VBOR set to 2.7V 01 = VBOR set to 4.2V 00 = VBOR set to 4.5V 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39530A-page 29-5 Section 29. Device Configuration Bits Device Configuration Bits 29 BW16: 16-bit Bus Width bit This bit specifies the data width of the system bus. 1 = System Bus has 16-bit data bus 0 = System Bus has 8-bit data bus CCP2MX: CCP2 Mux bit 1 = CCP2 input/output is multiplexed with an I/O 0 = CCP2 input/output is multiplexed with a different I/O CP: Code Protection bits (apply when in Code Protected Microcontroller Mode) 1 = Program memory code protection off 0 = All of program memory code protected DP: Data EEPROM Memory Code Protection bit 1 = Code protection off 0 = Data EEPROM memory is code protected Note: This bit is used when a ROM program memory device or a ROMless device has Data EEPROM memory. FOSC2:FOSC0: Oscillator Selection bits 111 = RC oscillator w/ OSC2 configured as I/O 110 = HS oscillator with PLL enabled/clock frequency = (4 x FOSC1) 101 = EC oscillator w/ OSC2 configured as I/O 100 = EC oscillator w/ OSC2 configured as divide by 4 clock output 011 = RC oscillator 010 = HS oscillator 001 = XT oscillator 000 = LP oscillator OSCSEN: Oscillator System Clock Switch Enable bit 1 = Oscillator system clock switch option is disabled (main oscillator is source) 0 = Oscillator system clock switch option is enabled (oscillator switching is enabled) PM1:PM0: Processor Mode Select bits These bits select the processor operating mode for the device. The processor operating mode specifies how the program memory is mapped (internal/external) and the default configuration of the system bus pins. 11 = Microprocessor mode 10 = Microcontroller mode 01 = Reserved 00 = Extended microcontroller mode PWRTEN: Power-up Timer Enable bit 1 = PWRT disabled 0 = PWRT enabled STVREN: Stack Full/Underflow Reset Enable bit 1 = Stack Full/Underflow will cause RESET 0 = Stack Full/Underflow will not cause RESET 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39530A-page 29-6  2000 Microchip Technology Inc. WAIT: System Bus Wait bit This bit is used to enable wait states for table reads and table writes to external memory on the system bus 1 = Wait selections unavailable, device will not wait 0 = Wait programmed by WAIT1 and WAIT0 bit in MEMCON register WDIS: Write Select WRH, WRL Disable bit 1 = Drivers enabled 0 = Drivers disabled WDTPS2:WDTPS0: Watchdog Timer Postscale Select bits 111 = 1:1 110 = 1:2 101 = 1:4 100 = 1:8 011 = 1:16 010 = 1:32 001 = 1:64 000 = 1:128 WDTEN: Watchdog Timer Enable bit 1 = WDT enabled 0 = WDT disabled (control is placed on the SWDTEN bit, in register WDTCON) Legend R = Readable bit P = Programmable bit U = Unimplemented bit, read as ‘0’ - n = Value at POR reset ’1’ = bit is set ’0’ = bit is cleared x = bit is unknown Note 1: The position of the configuration bits is device dependent. Please refer to the device programming specification for bit placement. You are not required to know the configuration bit positions when using a Microchip device programmer. This is addressed by either the configuration direction of the software tool or MPLAB’s user interface. 2: In ROMless devices, some of the system bus configuration bits are hardwired into a set configuration. Other bits may be placed in protected SFR locations which can only be modified after properly writing to the CMLK1:CMLK0 bits. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39530A-page 29-7 Section 29. Device Configuration Bits Device Configuration Bits 29 29.2.1 MPASM’s CONFIG Directive Microchip’s assembler, MPASM, has a nice feature (directives) that allows you to specify the device configuration in the source code file. This ensures that when programming a device for an application, the required configuration is also programmed. This minimizes the risk of programming the wrong device configuration and then wondering why it no longer works in the application (unexpected operation). Example 29-1 shows a template for using the CONFIG directive. Example 29-1: Using the CONFIG Directive, a Source File Template The symbols currently in the Microchip Device Header files make using the CONFIG directive straight forward. These are shown in Table 29-1. The symbols available for your device are listed in the Microchip Include file for that device. LIST p = p18C452 ; List Directive, ; Revision History ; #INCLUDE ; Microchip Device Header File ; #INCLUDE ; File which includes my standard macros #INCLUDE ; File which includes macros specific ; to this application ; ; Specify Device Configuration Bits for ; Program Configuration Registers 0 through 6 __CONFIG _CONFIG0, CP_OFF_0 __CONFIG _CONFIG1, LPSCEN_OFF_1 & RCRA6_OSC_1 __CONFIG _CONFIG2, BORV_25_2 & BOREN_ON_2 & PWRTEN_OFF_2 __CONFIG _CONFIG3, WDPS_128_3 & WDT_ON_3 __CONFIG _CONFIG5, CCP2MX_ON_5 __CONFIG _CONFIG6, SVTREN_ON_6 ; org 0x00 ; Start of Program Memory RESET_ADDR : ; First instruction to execute after a reset end Note: As long as the correct device is specified (in the LIST and INCLUDE file directives), the correct polarity of all bits is ensured. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39530A-page 29-8  2000 Microchip Technology Inc. Table 29-1: _CONFIG Directive Symbols (from Microchip Header Files) (1) Feature Configuration Byte Symbols Comment Oscillators _CONFIG1H _LP_OSC_1 LP mode for device _XT_OSC_1 XT mode for device _HS_OSC_1 HS mode for device oscillator _RC_OSC_1 RC mode for device oscillator _RCIO_OSC_1 RC mode for device oscillator with clockout configured as I/O pin _EC_OSC_1 EC (external clock) mode for device oscillator _ECIO_OSC_1 EC (external clock) mode for device oscillator with clockout configured as I/O pin _HS4_OSC_1 HS mode with 4 x PLL for device oscillator _HSPLL_OSC_1 HS mode with 4 x PLL for device oscillator (4) Oscillator Switch _CONFIG1H _LPSCEN_ON_1 Oscillator switch enabled _LPSCEN_OFF_1 Oscillator switch disabled Code Protect _CONFIG1L _CP_ON_0 Code Protect enabled _CP_OFF_0 Code Protect disabled Watchdog Timer _CONFIG2H _WDT_ON_3 Watchdog Timer enabled _WDT_OFF_3 Watchdog Timer disabled Watchdog Timer Postscale Assignment _CONFIG2H _WDTPS_128_3 WDT prescaler set to 1:128 _WDTPS_64_3 WDT prescaler set to 1:64 _WDTPS_32_3 WDT prescaler set to 1:32 _WDTPS_16_3 WDT prescaler set to 1:16 _WDTPS_8_3 WDT prescaler set to 1:8 _WDTPS_4_3 WDT prescaler set to 1:4 _WDTPS_2_3 WDT prescaler set to 1:2 _WDTPS_1_3 WDT prescaler set to 1:1 Power-up Timer _CONFIG2L _PWRTEN_ON_2 Power-up Timer enabled _PWRTEN_OFF_2 Power-up Timer disabled Brown-out Reset _CONFIG2L _BOREN_ON_2 Brown-out Reset enabled _BOREN_OFF_2 Brown-out Reset disabled BOR Trip-Point Voltage _CONFIG2L _BORV_18_2 BOR trip point = 1.8V min (2, 3) _BORV_25_2 BOR trip point = 2.5V min (2, 3) _BORV_27_2 BOR trip point = 2.7V min (3) _BORV_42_2 BOR trip point = 4.2V min (3) _BORV_45_2 BOR trip point = 4.5V min (3) Note 1: Not all configuration bit symbols may be available on any one device. Please refer to the Microchip include file of that device for available symbols. 2: The option for a 1.8V or 2.5V BOR trip point is device dependent. Only one of these symbols will be available in the Microchip supplied header file. 3: These are the trip points for a typical device. Other trip points (symbols) may be specified for the device. 4: Symbol obsoleted and may not be available in header file. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39530A-page 29-9 Section 29. Device Configuration Bits Device Configuration Bits 29 CCP2 pin Multiplex _CONFIG3H _CCP2MX_ON_5 CCP2 out multiplexer enabled _CCP2MX_OFF_5 CCP2 out multiplexer disabled Processor Mode _CONFIG3L _MP_MODE_4 Microprocessor mode _MC_MODE_4 Microcontroller mode _XMC_MODE_4 Extended Microcontroller mode External Data Bus Wait _CONFIG3L _WAIT_ON_4 Wait on external data bus enabled _WAIT_OFF_4 Wait on external data bus disabled System Bus A19 Disable _CONFIG4H _A19DIS_ON_7 System bus A19 disabled _A19DIS_OFF_7 System bus A19 enabled System Bus A15 Disable _CONFIG4H _A15DIS_ON_7 System bus A15 disabled _A15DIS_OFF_7 System bus A15 enabled System Bus A11 Disable _CONFIG4H _A11DIS_ON_7 System bus A11 disabled _A11DIS_OFF_7 System bus A11 enabled Byte Address BA0 Disable _CONFIG4H _BADIS_ON_7 Byte Address BA0 disabled _BADIS_OFF_7 Byte Address BA0 enabled Byte Select Disable _CONFIG4H _BSDIS_ON_7 Byte Select disabled _BSDIS_OFF_7 Byte Select enabled Write Select Disable _CONFIG4H _WDIS_ON_7 Write Select disabled _WDIS_OFF_7 Write Select enabled Stack Full/Overflow _CONFIG4L _STVREN_ON_6 Stack full/overflow rest enabled _STVREN_OFF_6 Stack full/overflow rest disabled Code Protect Data EEPROM TBD _DP_ON Data EEPROM protect enabled _DP_OFF Data EEPROM protect disabled Note 1: Not all configuration bit symbols may be available on any one device. Please refer to the Microchip include file of that device for available symbols. 2: The option for a 1.8V or 2.5V BOR trip point is device dependent. Only one of these symbols will be available in the Microchip supplied header file. Table 29-1: _CONFIG Directive Symbols (from Microchip Header Files) (1) (Continued) Feature Configuration Byte Symbols Comment 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39530A-page 29-10  2000 Microchip Technology Inc. 29.3 Program Verification/Code Protection If the code protection bit(s) have not been programmed, the on-chip program memory can be read out for verification purposes. 29.3.1 ROM Devices When a ROM device also has Data EEPROM memory, an additional code protect configuration bit may be implemented. The program memory configuration bit is submitted as part of the ROM code submittal. The Data EEPROM memory code protect configuration bit will be an EEPROM bit. When ROM devices complete testing, the EEPROM data memory code protect bit will be programmed to the same state as the program memory code protect bit. That is, Data EEPROM code protect is off when program memory code protect is off and Data EEPROM code protect is on for all other selections. In applications where the device is code protected and the Data EEPROM needs to be programmed before the application can be released, the Data EEPROM memory must have the entire Data EEPROM memory erased. The device programming specification details the steps to do this. Microchip device programmers implement the specified sequence. Once this sequence is complete, the Data EEPROM memory code protect is disabled. This allows the desired data to be programmed into the device. After programming the Data EEPROM memory array, the Data EEPROM memory code protect configuration bit should be programmed as desired. Note: Microchip does not recommend code protecting windowed devices. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39530A-page 29-11 Section 29. Device Configuration Bits Device Configuration Bits 29 29.4 ID Locations Five memory locations (200000h - 200004h) are designated as ID locations where the user can store checksum or other code-identification numbers. These locations are accessible during normal execution through the TBLRD instruction, or during program/verify. The ID locations can be read when the device is code protected. 29.5 Device ID One memory location (two bytes) (3FFFFEh-3FFFFFh) is designated as the Device ID location. The value at this location is specified by Microchip and is useful in determining the device. Device ID bits can be used by a device programmer to retrieve information about what device is being programmed and what the revision of the device is. The Device ID can be accessed by a TBLRD instruction or via serial program/verify. The Device ID can be read when the part is code protected. The 5 LSbs are the device revision information, and the remaining 11 bits contain the device ID number. This is shown in Table 29-2. Table 29-2: Device ID Registers Register Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 DEVID2 DEV10 DEV9 DEV8 DEV7 DEV6 DEV5 DEV4 DEV3 DEVID1 DEV2 DEV1 DEV0 REV4 REV3 REV2 REV1 REV0 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39530A-page 29-12  2000 Microchip Technology Inc. 29.6 Design Tips Question 1: I have a JW device and I can no longer program it (reads scrambled data or all '0's). What’s wrong with the device? Answer 1: Nothing. You probably code protected the device. If this is the case, the device is no longer usable. See Section 29.3 “Program Verification/Code Protection” for more details. Question 2: In converting from a PIC16C74 to a PIC18C452, my application no longer works. Answer 2: 1. Did you re-assemble the source file specifying the PIC18C452 in the INCLUDE file and LIST directives? The use of the CONFIG directive is highly recommended. 2. On the device programmer, did you specify the PIC18C452, and were all the configuration bits as desired? Question 3: When I erase the device, the program memory is blank but the configuration word is not yet erased. Answer 3: That is by design. Also remember that Microchip does not recommend code protecting windowed devices. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39530A-page 29-13 Section 29. Device Configuration Bits Device Configuration Bits 29 29.7 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced MCU family (that is, they may be written for the Base-Line, Mid-Range or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to Configuration Word are: Title Application Note # No related Application Notes at this time. Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39530A-page 29-14  2000 Microchip Technology Inc. 29.8 Revision History Revision A This is the initial released revision of the Configuration Word description. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39531A-page 30-1 ICSP 30 Section 30. In-Circuit Serial Programming™ (ICSP™) HIGHLIGHTS This section of the manual contains the following major topics: 30.1 Introduction .................................................................................................................. 30-2 30.2 Entering In-Circuit Serial Programming Mode ............................................................. 30-3 30.3 Application Circuit ........................................................................................................ 30-4 30.4 Programmer ................................................................................................................. 30-6 30.5 Programming Environment .......................................................................................... 30-6 30.6 Other Benefits .............................................................................................................. 30-7 30.7 Field Programming of PICmicro OTP MCUs................................................................ 30-8 30.8 Field Programming of FLASH PICmicro MCUs ......................................................... 30-10 30.9 Design Tips ................................................................................................................ 30-12 30.10 Related Application Notes.......................................................................................... 30-13 30.11 Revision History ......................................................................................................... 30-14 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39531A-page 30-2  2000 Microchip Technology Inc. 30.1 Introduction All Enhanced MCU devices can be In-Circuit Serial Programmed (ICSP™) while in the end application circuit. This is simply done with two lines for clock and data, and three other lines for power, ground and the programming voltage. In-Circuit Serial Programming (ICSP™) is a great way to reduce your inventory overhead and time-to-market for your product. By assembling your product with a blank Microchip microcontroller (MCU), you can stock one design. When an order has been placed, these units can be programmed with the latest revision of firmware, tested and shipped in a very short time. This method also reduces scrapped inventory due to old firmware revisions. This type of manufacturing system can also facilitate quick turnarounds on custom orders for your product. Most people would think to use ICSP with PICmicro® OTP MCUs only on an assembly line where the device is programmed once. However, there is a method by which an OTP device can be programmed several times depending on the size of the firmware. This method, explained in Section 30.7, provides a way to field upgrade your firmware in a way similar to EEPROM- or FLASH-based devices. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39531A-page 30-3 Section 30. ICSP ICSP 30 30.2 Entering In-Circuit Serial Programming Mode The device is placed into a program/verify mode by holding the CLOCK (typically on the RB6 pin) and DATA (typically on the RB7 pin) pins low, while raising the MCLR (VPP) pin from VIL to VIHH (see programming specification) and having VDD at the programming voltage. Both the CLOCK and DATA pins are Schmitt Trigger inputs in this mode. When in I/O mode and RB7 is driving data, it is a CMOS output driver. After RESET, to place the device into programming/verify mode, the program counter (PC) is at location 00h. A command is then supplied to the device. Some commands then specify that 16-bits of program data are then supplied to or read from the device, depending on whether the command was a load or a read. For complete details of serial programming, please refer to the device specific Programming Specifications. During the In-Circuit Serial Programming Mode, the WDT circuitry is disabled from generating a device RESET. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39531A-page 30-4  2000 Microchip Technology Inc. 30.3 Application Circuit The application circuit must be designed to allow all the programming signals to be directly connected to the PICmicro MCU. Figure 30-1 shows a typical circuit that is a starting point when designing with ICSP. The application must compensate for the following: 1. Isolation of the MCLR/VPP pin from the rest of the circuit 2. Loading of pins CLOCK and DATA 3. Capacitance on each of the VDD, MCLR/VPP, CLOCK and DATA pins 4. Minimum and maximum operating voltage for VDD 5. PICmicro oscillator 30.3.1 Isolation of the MCLR/VPP Pin from the Rest of the Circuit The MCLR/VPP pin is normally connected to an RC circuit. The pull-up resistor is tied to VDD and a capacitor is tied to ground. This circuit can affect the operation of ICSP depending on the size of the capacitor, since the VPP voltage must be isolated from the rest of the circuit . The resistor (R1) should be greater than 10kΩ to provide isolation between VDD and VPP. It is, therefore, recommended that the circuit in Figure 30-1 be used when an RC is connected to MCLR/VPP. Another consideration with MCLR/VPP is that when the PICmicro device is programmed, this pin is driven to approximately 13V and also to ground. Therefore, the application circuit must be isolated from this voltage provided by the programmer. 30.3.2 Loading of Pins CLOCK and DATA The CLOCK and DATA pins are used by the PICmicro MCU for serial programming. CLOCK is driven by the programmer. DATA is a bi-directional pin that is driven by the programmer when programming, and driven by the MCU when verifying. These pins must be isolated from the rest of the application circuit so as not to affect the signals during programming. You must take into consideration the output impedance of the programmer when isolating CLOCK and DATA from the rest of the circuit. This isolation circuit must account for CLOCK being an input on the MCU and for DATA being bi-directional (can be driven by both the MCU and the programmer). For instance, PRO MATE® II has an output impedance of 1kΩ. If the design permits, these pins should not be used by the application. This is not the case with most applications, so it is recommended that the designer evaluate whether these signals need to be buffered. As a designer, you must consider what type of circuitry is connected to CLOCK and DATA and then make a decision on how to isolate these pins. Figure 30-1 does not show any circuitry to isolate CLOCK and DATA on the application circuit, because this is very application dependent. To simplify this interface, the optimal usage of these I/O pins in the application are (in order): 1. Dedicate the CLOCK/DATA pins for the ICSP interface (not connected to other circuitry). 2. Use these pins as outputs with minimal loading on the signal line. 3. Use isolation circuitry so these signals can be driven to the ICSP specifications. Figure 30-1: Typical In-Circuit Serial Programming (ICSP) Application Circuit Application PCB PIC18CXXX MCLR/VPP VDD VSS DATA CLOCK VDD/VPP VDD To application circuit Isolation circuits R2 ICSP Connector R1 C1 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39531A-page 30-5 Section 30. ICSP ICSP 30 30.3.3 Capacitance on Each of the VDD, MCLR/VPP, CLOCK and DATA Pins The total capacitance on the programming pins affects the rise rates of these signals as they are driven out of the programmer. Typical circuits use several hundred microfarads of capacitance on VDD, which helps to dampen noise and ripple. However, this capacitance requires a fairly strong driver in the programmer to meet the rise rate timings for VDD. Most programmers are designed to simply program the MCU itself and don’t have strong enough drivers to power the application circuit. One solution is to use a driver board between the programmer and the application circuit. The driver board requires a separate power supply that is capable of driving the VPP and VDD pins with the correct rise rates and should also provide enough current to power the application circuit. CLOCK and DATA are not buffered on this schematic, but may require buffering depending upon the application. A sample driver board schematic is shown in Figure 30-2. 30.3.4 Minimum and Maximum Operating Voltage for VDD The Microchip programming specification states that the device should be programmed at 5V. Special considerations must be made if your application circuit operates at 3V only. These considerations may include totally isolating the MCU during programming. Another consideration is the device must be verified at the minimum and maximum voltages at which the application circuit will be operating. For instance, a battery operated system may operate from three 1.5V cells giving an operating voltage range of 2.7V to 4.5V. The programmer must program the device at 5V and must verify the program memory contents at both 2.7V and 4.5V to ensure that proper programming margins have been achieved. This ensures the PICmicro MCU operation over the voltage range of the system. 30.3.5 PICmicro Oscillator The final consideration deals with the oscillator circuit on the application board. The voltage on MCLR/VPP must rise to the specified program mode entry voltage before the device executes any code. The crystal modes available on the device are not affected by this, because the Oscillator Start-up Timer waits for 1024 oscillations before any code is executed. However, RC or EC oscillators do not require any start-up time; therefore, the Oscillator Start-up Timer is not used. The programmer must drive MCLR/VPP to the program mode entry voltage before the RC or EC oscillator toggles four times. If the RC or EC oscillator toggles four or more times, the program counter will be incremented to some value X. When the device enters programming mode, the program counter will not be zero and the programmer will start programming your code at an offset of X. There are several alternatives that can compensate for a slow rise rate on MCLR/VPP. The first method is to not populate the resistor (R1) in Figure 30-1, program the device, and then insert the resistor (R1). The other method is to have the programming interface drive the OSC1 pin of the PICmicro MCU to ground while programming. This will prevent any oscillations from occurring during programming. Connecting the application circuit to the programmer is dependent on the programming environment. Refer to Section 30.5 "Programming Environment" for more details. Note: The driver board design MUST be tested in the user's application to determine the effects of the application circuit on the programming signals timing. Changes may be required if the application places a significant load on the VDD, VPP, CLOCK or DATA pins. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39531A-page 30-6  2000 Microchip Technology Inc. 30.4 Programmer PIC18CXXX MCUs only use serial programming and, therefore, all programmers supporting these devices will support ICSP. One area of consideration with the programmer is the drive capability. As discussed before, it must be able to provide the specified rise rates on the ICSP signals and also provide enough current to power the application circuit. Figure 30-2 shows an example driver board. This driver schematic does not show any buffer circuitry for CLOCK and DATA. It is recommended that an evaluation be performed to determine if buffering is required. Another consideration with the programmer is what VDD levels are used to verify the memory contents of the device. For instance, the PRO MATE II verifies program memory at the minimum and maximum VDD levels for the specified device and is, therefore, considered a production quality programmer. On the other hand, the PICSTART® Plus only verifies at 5V and is for prototyping use only. The Microchip programming specifications state that the program memory contents should be verified at both the minimum and maximum VDD levels that the application circuit will be operating. This implies that the application circuit must be able to handle the varying VDD voltages. There are also several third party programmers that are available. You should select a programmer based on the features it has and how it fits into your programming environment. The Microchip Development Systems Ordering Guide (DS30177) provides detailed information on all our development tools. The Microchip Third Party Guide (DS00104) provides information on all of our third party tool developers. Please consult these two references when selecting a programmer. Many options exist, including serial or parallel PC host connection, stand-alone operation, and single or gang programmers. Some of the third party developers include Advanced Transdata Corporation, BP Microsystems, Data I/O, Emulation Technology, and Logical Devices. 30.5 Programming Environment The programming environment affects the type of programmer used, the programmer cable length and the application circuit interface. Some programmers are well suited for a manual assembly line, while others are desirable for an automated assembly line. You may want to choose a gang programmer to program multiple systems at a time. The physical distance between the programmer and the application circuit affects the load capacitance on each of the programming signals. This directly affects the drive strength needed to provide the correct signal rise rates and current. This programming cable must also be as short as possible and properly terminated and shielded, or the programming signals may be corrupted by ringing or noise. Finally, the application circuit interface to the programmer depends on the size constraints of the application circuit itself and the assembly line. A simple header can be used to interface the application circuit to the programmer. This might be more desirable for a manual assembly line where a technician plugs the programmer cable into the board. A different method uses spring loaded test pins (commonly referred to as pogo pins). The application circuit has pads on the board for each of the programming signals, and there is a fixture that has pogo pins in the corresponding configuration. The application circuit or fixture is moved into position, such that the pogo pins come into contact with the board. This method might be more suitable for an automated assembly line. After taking into consideration the various points with the application circuit, the programmer and the programming environment, anyone can build a high quality, reliable manufacturing line based on ICSP. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39531A-page 30-7 Section 30. ICSP ICSP 30 30.6 Other Benefits ICSP provides other benefits, such as calibration and serialization. If program memory permits, it would be cheaper and more reliable, to store calibration constants in program memory instead of using an external serial EEPROM. For example, if your system has a thermistor that can vary from one system to another, storing some calibration information in a table format allows the microcontroller to compensate (in software) for external component tolerances. System cost can be reduced without affecting the required performance of the system by using software calibration techniques. But how does this relate to ICSP? The PICmicro MCU has already been programmed with firmware that performs a calibration cycle. The calibration data is transferred to a calibration fixture. When all calibration data has been transferred, the fixture places the PICmicro MCU in programming mode and programs the PICmicro MCU with the calibration data. Application note AN656, "In-Circuit Serial Programming of Calibration Parameters Using a PICmicro Microcontroller," shows exactly how to implement this type of calibration data programming. The other benefit of ICSP is serialization. Each individual system can be programmed with a unique or random serial number. One such application of a unique serial number would be for security systems. A typical system might use DIP switches to set the serial number. Instead, this number can be burned into program memory, thus reducing the overall system cost and lowering the risk of tampering. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39531A-page 30-8  2000 Microchip Technology Inc. 30.7 Field Programming of PICmicro OTP MCUs An OTP device is not normally capable of being reprogrammed, but the PICmicro architecture gives you this flexibility, provided the size of your firmware is at least half that of the desired device, and the device is not code protected. If your target device does not have enough program memory, Microchip provides a wide spectrum of devices from 0.5K to 16K word program memory with the same set of peripheral features that will help meet the criteria. The Enhanced MCU devices have three vectors; RESET and two interrupt vector addresses. When the PICmicro device encounters a RESET or interrupt condition, the code located at one of these locations in program memory is executed. For an example of reprogramming an OTP device, we will use an example from our Mid-Range family. This technology is applicable to all EPROM based PICmicro devices. The first listing of Example 30-1 shows the code that is first programmed into the PICmicro device. The second listing of Example 30-1 shows the code that is programmed into the PICmicro device for the second time. Example 30-1 shows that to program the device a second time, the memory location 0x0000 (originally goto Main (0x2808)), is reprogrammed to all 0’s. This happens to be a NOP instruction. This location cannot be reprogrammed to the new opcode (0x2860), because the bits that are 0’s cannot be reprogrammed to 1’s. Only bits that are 1’s can be reprogrammed to 0’s. The next memory location, 0x0001, was originally blank (all 1’s) and now becomes a goto Main (0x2860). When a RESET condition occurs, the MCU executes the instruction at location 0x0000, which is the NOP (a completely benign instruction), and then executes the goto Main to start the execution of code. The example also shows that all program memory locations after 0x005A are blank in the original program, so that the second time the PICmicro device is programmed, the revised code can be programmed at these locations. The same descriptions can be given for the interrupt vector locations. Now your one-time programmable Enhanced MCU is exhibiting EEPROM- or FLASH-like qualities. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39531A-page 30-9 Section 30. ICSP ICSP 30 Example 30-1: Programming Cycle Listing Files First Program Cycle Second Program Cycle _________________________________________________________________________________________ Prog Opcode Assembly | Prog Opcode Assembly Mem Instruction | Mem Instruction ----------------------------------------------------------------------------------------- 0000 2808 goto Main ;Main loop | 0000 0000 nop 0001 3FFF ; at 0x0008 | 0001 2860 goto Main; Main now 0002 3FFF | 0002 3FFF ; at 0x0060 0003 3FFF | 0003 3FFF 0004 2848 goto ISR ; ISR at | 0004 0000 nop 0005 3FFF ; 0x0048 | 0005 28A8 goto ISR ; ISR now at 0006 3FFF | 0006 3FFF ; 0x00A8 0007 3FFF | 0007 3FFF 0008 1683 bsf STATUS,RP0 | 0008 1683 bsf STATUS,RP0 0009 3007 movlw 0x07 | 0009 3007 movlw 0x07 000A 009F movwf ADCON1 | 000A 009F movwf ADCON1 . |. . |. . |. 0048 1C0C btfss PIR1,RBIF | 0048 1C0C btfss PIR1,RBIF 0049 284E goto EndISR | 0049 284E goto EndISR 004A 1806 btfsc PORTB,0 | 004A 1806 btfsc PORTB,0 . |. . |. . |. 0060 3FFF | 0060 1683 bsf STATUS,RP0 0061 3FFF | 0061 3005 movlw 0x05 0062 3FFF | 0062 009F movwf ADCON1 . |. . |. . |. 00A8 3FFF | 00A8 1C0C btfss PIR1,RBIF 00A9 3FFF | 00A9 28AE goto EndISR 00AA 3FFF | 00AA 1806 btfsc PORTB,0 . |. . |. . |. ----------------------------------------------------------------------------------------- 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39531A-page 30-10  2000 Microchip Technology Inc. 30.8 Field Programming of FLASH PICmicro MCUs With the ICSP interface circuitry already in place, FLASH-based PICmicro MCUs can be easily reprogrammed in the field. These FLASH devices allow you to reprogram them even if they are code protected. A portable ICSP programming station might consist of a laptop computer and programmer. The technician plugs the ICSP interface cable into the application circuit and downloads the new firmware into the device. The next thing you know, the system is up and running without those annoying “bugs.” Another instance would be that you want to add an additional feature to your system. All of your current inventory can be converted to the new firmware, and field upgrades can be performed to bring your installed base of systems up to the latest revision of firmware. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39531A-page 30-11 Section 30. ICSP ICSP 30 Figure 30-2: Example Driver Board Schematic C6 0.1 PRB6 PVDD 2 3 1 14 7 U2A 74HC126 5 6 4 U2B 74HC126 R3 1 CLOCK +8V PVDD R6 100 R7 100 3 2 1Q1 2N2907 1 2 3 Q3 2N2222 12 13 14 U1D TLE2144A R5 100 C7 0.001 VDD 3 2 1 4 11 U1A TLE2144A C3 0.1 +15V R1 5.1k R8 100 3 2 1Q2 2N2907 R4 1 PVPP 9 8 10 U2C 74HC126 12 11 13 U2D 74HC126 DATA CLOCK PVPP PVDD 1 2 3 4 5 JP3 HEADER +15V R2 5.1k R9 100 1 2 3 Q4 2N2222 10 9 8 U1C TLE2144A R10 100 C8 0.001 DATA VPP VPP VDD 1 2 3 4 5 JP1 HEADER 5 6 7 U1B TLE2144A CLOCK 1 +15V 2 JP2 HEADER C5 0.1 VIN 1 GND 3 VOUT 2 VR1 LM7808 C9 100 +15V C4 0.1 +8V Note: All resistors are in Ohms, all capacitors are in µF. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39531A-page 30-12  2000 Microchip Technology Inc. 30.9 Design Tips Question 1: When I try to do ICSP, the entire program is shifted (offset) in the device program memory. Answer 1: If the MCLR pin does not rise fast enough, while the device’s voltage is in the valid operating range, the internal Program Counter (PC) can increment. This means that the PC is no longer pointing to the address that you expected. The exact location depends on the number of device clocks that occurred in the valid operating region of the device. Question 2: I am using a PRO MATE II with a socket that I designed to bring the programming signal to my application board. Sometimes when I try to do ICSP, the program memory is programmed wrong. Answer 2: The voltages / timings may be violated at the device. This could be due to the: • Application board circuitry • Cable length from programmer to target • Large capacitance on VDD that affects levels / timings 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39531A-page 30-13 Section 30. ICSP ICSP 30 30.10 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is, they may be written for the Base-Line, the Mid-Range or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to In-Circuit Serial Programming are: Title Application Note # In-Circuit Serial Programming of Calibration Parameters using a PICmicro® Microcontroller AN656 In-Circuit Serial Programming Guide DS30277 Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39531A-page 30-14  2000 Microchip Technology Inc. 30.11 Revision History Revision A This is the initial released revision of the Enhanced MCU In-Circuit Serial Programming module description. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-1 Instruction Set 31 Section 31. Instruction Set HIGHLIGHTS This section of the manual contains the following major topics: 31.1 Introduction .................................................................................................................. 31-2 31.2 Data Memory Map ....................................................................................................... 31-3 31.3 Instruction Formats ...................................................................................................... 31-9 31.4 Special Function Registers as Source/Destination .................................................... 31-12 31.5 Fast Register Stack.................................................................................................... 31-13 31.6 Q Cycle Activity.......................................................................................................... 31-13 31.7 Instruction Descriptions ............................................................................................. 31-14 31.8 Design Tips .............................................................................................................. 31-136 31.9 Related Application Notes........................................................................................ 31-137 31.10 Revision History ....................................................................................................... 31-138 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-2  2000 Microchip Technology Inc. 31.1 Introduction The PIC18CXXX instruction set adds many enhancements to the previous PICmicro instruction sets, while maintaining an easy migration from these PICmicro instruction sets. Most instructions are a single program memory word (16-bits), but to address customer requests, some new instructions have been added that require two program memory locations. The Instruction Set Summary, shown in Table 31-1, lists the instructions recognized by the Microchip assembler (MPASM). Table 31-2 gives the instruction description conventions. Each instruction is divided into an OPCODE that specifies the instruction type and one or more operands which further specify the operation of the instruction. The instruction set is highly orthogonal and is grouped into four basic categories: • Byte-oriented operations • Bit-oriented operations • Literal operations • Control operations Most byte-oriented instructions have three operands: 1. The File Register (specified by the value of ’f’) 2. The destination of the result (specified by the value of ’d’) 3. The accessed memory (specified by the value of ’a’) 'f' represents a File Register Designator and 'd' represents a Destination Designator. The File Register Designator specifies which File Register is to be used by the instruction. The access indicator ’a’ specifies if the BSR selects the bank or if the access bank is used. The destination designator specifies where the result of the operation is to be placed. If 'd' is zero, the result is placed in the WREG Register. If 'd' is one, the result is placed in the File Register specified in the instruction. All bit-oriented instructions have three operands: 1. The File Register (specified by the value of ’f’) 2. The bit in the File Register (specified by the value of ’b’) 3. The accessed memory (specified by the value of ’a’) 'b' represents a bit field designator that selects the number of the bit affected by the operation, while 'f' represents the number of the file in which the bit is located. The access indicator ’a’ specifies if the BSR selects the bank or if the access bank is used. The literal instructions may use some of the following operands: • A literal value to be loaded into a File Register (specified by the value of ’k’) • The desired FSR Register to load the literal value into (specified by the value of ’f’) • No operand required (specified by the value of ’—’) The control instructions may use some of the following operands: • A program memory address (specified by the value of ’n’) • The mode of the CALL or RETURN instructions (specified by the value of ’s’) • The mode of the Table Read and Table Write instructions (specified by the value of ’m’) • No operand required (specified by the value of ’—’) All instructions are a single word except for three double word instructions. These three instructions were made double word instructions so that all the required information is available in these 32 bits. In the second word, the 4-MSb’s, are ’1’s. If this second word is executed as an instruction (by itself), it will execute as a NOP. All single word instructions are executed in a single instruction cycle, unless a conditional test is true or the program counter is changed as a result of the instruction. In these cases, the execution takes two instruction cycles with the additional instruction cycle(s) executed as a NOP. The double word instructions (that do not modify the PC) execute in two instruction cycles. One instruction cycle consists of four oscillator periods. Thus, for an oscillator frequency of 4 MHz, the normal instruction execution time is 1 µs. If a conditional test is true or the program counter is changed as a result of an instruction, the instruction execution time is 2 µs. Two word branch instructions (if true) would take 3 µs. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-3 Section 31. Instruction Set Instruction Set 31 31.2 Data Memory Map The Data Memory Map has 16 banks of 256 bytes. The Instruction Set and architecture allows operations across all banks (such as MOVFF). A Segment of Bank 0 and a segment of Bank 15 comprise the access bank. See Section 31.2.1 for description of the access bank. Figure 31-1: The Data Memory Map and the Access Bank 31.2.1 Access Bank The access bank is an architectural enhancement that is very useful for C compiler code optimization. The techniques used by the C compiler may also be useful for programs written in assembly. This data memory region can be used for • Intermediate computational values • Local variables of subroutine • Faster context saving/switching of variables • Common variables • Faster evaluation/control of SFRs (no banking) The access bank is comprised of 2 segments: Segment 0 and Segment 1. Segment 0 is the RAM that is mapped in Bank 0. Segment 1 is the SFRs that are mapped in Bank 15. Each Segment can be of different sizes. The sum of RAM mapped by Segment 0 and Segment 1 is 256 bytes. When forced in the access bank (a = ’0’), the last address in Segment 0 is followed by the first address in Segment 1. Segment 1 maps the Special Function Registers so that these registers can be accessed without any software overhead. This is useful for testing status flags and modifying control bits. Bank 0 Bank 1 Bank 14 Bank 15 BSR<3:0> Data Memory Map = 0000b = 0001b = 1110b = 1111b 00h FFh 00h FFh Access Bank When the instructions ’a’ bit = 0, The BSR is ignored and this Access Bank is used. The Segment 0 General Purpose RAM is from Bank 0. The Segment 1 Special Function Registers is from Bank 15. When a = 1, the BSR is used to specify the RAM location that the instruction uses. Bank n Segment 0 Segment 1 Segment 1 Segment 0 Device Dependent Segment Boundary 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-4  2000 Microchip Technology Inc. Example 31-1 shows how registers are affected depending on the value of the access bit. Register MYREG has an 8-bit address. This address specifies the location in the specified bank to perform the operation. The specified bank is either the bank specified by the Bank Select Register (BSR) (when a = 1), or the access bank (when a = 0). Example 31-1:Operation of Destination and Access Bits ; ; The following symbols are defined in the Microchip supplied ; device header file: ; ; For destination bit: ; F = 1 ; Result is placed in File Register ; W = 0 ; Result is placed in WREG Register ; ; For access bit: ; B = 1 ; Register used specified by BSR Bank Register ; A = 0 ; Register used is in Access Bank ; ; MYREG is a register with an 8-bit address value between 0h and FFh. ; For this example we will assign MYREG to bank 5, though it could ; be in any (or all) banks. ; MOVLB 5 ; BSR points to RAM bank 5 ; ; Contents of ; Addr(MYREG) in ; MYREG access bank WREG ; Starting Value 0x7F 0x5A x ; DECF MYREG, F, B ; 0x7E --- --- DECF MYREG, F, A ; --- 0x59 --- ; DECF MYREG, W, B ; --- --- 0x7D DECF MYREG, W, A ; --- --- 0x58 Note: If the register is specified with the full 12-bit address, the assembler will automatically force the access bit to a ’0’ (when the address is in the access RAM area) or a ’1’ (for all other addresses). 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-5 Section 31. Instruction Set Instruction Set 31 The common assembler usage should be that all RAM and SFR addresses are 12-bit. This means that the assembler can determine from the address of the register, whether the access bit needs to be set or cleared. Example 31-2 shows this, as well as forcing the use of the access bank. Example 31-2:Code ; ; The following symbols are defined in the Microchip supplied ; device header file: ; ; For destination bit: ; F = 1 ; Result is placed in File Register ; W = 0 ; Result is placed in WREG Register ; ; For access bit: ; B = 1 ; Register used specified by BSR Bank Register ; A = 0 ; Register used is in Access Bank ; ; Register Name Address ; Loop_CNTR 0x000 ; MYREG 0x524 ; SFR1 0xA9F ; MOVLB 5 ; BSR points to RAM bank 5 ; Addr 24 ; a-bit MYREG Loop_CNTR SFR1 WREG Bank0 ; Starting Value --- 0x7F 0x7F 0x7F x 0xA9 ; DECF Loop_CNTR, F ; 0 --- 0x7E --- --- --- DECF MYREG, F ; 1 0x7E --- --- --- --- DECF SFR1, F ; 0 --- --- 0x7E --- --- ; ; DECF Loop_CNTR, W ; 0 --- --- --- 0x7D --- DECF MYREG, W ; 1 --- --- --- 0x7D --- DECF SFR1, W ; 0 --- --- --- 0x7D --- INCF MYREG, F, A ; 0 --- --- --- --- 0xAA INCF MYREG, W, A ; 0 --- --- --- 0x7F --- 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-6  2000 Microchip Technology Inc. Table 31-1: PIC18CXXX Instruction Set Summary Mnemonic, Operands Description Cycles 16-Bit Instruction Word Status Affected Notes MSb LSb BYTE-ORIENTED FILE REGISTER OPERATIONS ADDWF ADDWFC ANDWF CLRF COMF CPFSEQ CPFSGT CPFSLT DECF DECFSZ DCFSNZ INCF INCFSZ INFSNZ IORWF MOVF MOVFF MOVWF MULWF NEGF RLCF RLNCF RRCF RRNCF SETF SUBFWB SUBWF SUBWFB SWAPF TSTFSZ XORWF f, d, a f, d, a f, d, a f, a f, d, a f, a f, a f, a f, d, a f, d, a f, d, a f, d, a f, d, a f, d, a f, d, a f, d, a fs, fd f, a f, a f, a f, d, a f, d, a f, d, a f, d, a f, a f, d, a f, d, a f, d, a f, d, a f, a f, d, a Add WREG and f Add WREG and Carry bit to f AND WREG with f Clear f Complement f Compare f with WREG, skip = Compare f with WREG, skip > Compare f with WREG, skip < Decrement f Decrement f, Skip if 0 Decrement f, Skip if Not 0 Increment f Increment f, Skip if 0 Increment f, Skip if Not 0 Inclusive OR WREG with f Move f Move fs (source) to 1st word fd (destination) 2nd word Move WREG to f Multiply WREG with f Negate f Rotate Left f through Carry Rotate Left f (No Carry) Rotate Right f through Carry Rotate Right f (No Carry) Set f Subtract f from WREG with borrow Subtract WREG from f Subtract WREG from f with borrow Swap nibbles in f Test f, skip if 0 Exclusive OR WREG with f 1 1 1 1 1 1 (2 or 3) 1 (2 or 3) 1 (2 or 3) 1 1 (2 or 3) 1 (2 or 3) 1 1 (2 or 3) 1 (2 or 3) 1 1 2 1 1 1 1 1 1 1 1 1 1 1 1 1 (2 or 3) 1 0010 0010 0001 0110 0001 0110 0110 0110 0000 0010 0100 0010 0011 0100 0001 0101 1100 1111 0110 0000 0110 0011 0100 0011 0100 0110 0101 0101 0101 0011 0110 0001 01da 00da 01da 101a 11da 001a 010a 000a 01da 11da 11da 10da 11da 10da 00da 00da ffff ffff 111a 001a 110a 01da 01da 00da 00da 100a 01da 11da 10da 10da 011a 10da ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff C, DC, Z, OV, N C, DC, Z, OV, N Z, N Z Z, N None None None C, DC, Z, OV, N None None C, DC, Z, OV, N None None Z, N Z, N None None None C, DC, Z, OV, N C, Z, N Z, N C, Z, N Z, N None C, DC, Z, OV, N C, DC, Z, OV, N C, DC, Z, OV, N None None Z, N 1, 2, 3 1, 2, 3 1,2, 3 2, 3 1, 2, 3 4 4 2 1, 2, 3, 4 1, 2, 3, 4 1, 2 1, 2, 3, 4 1, 2, 4 1, 2 1, 2 1, 2 2 2 1, 2 1, 2 1, 2 1, 2 1, 2 2 1, 2 1, 2 1, 2 1, 2, 4 2 BIT-ORIENTED FILE REGISTER OPERATIONS BCF BSF BTFSC BTFSS BTG f, b, a f, b, a f, b, a f, b, a f, d, a Bit Clear f Bit Set f Bit Test f, Skip if Clear Bit Test f, Skip if Set Bit Toggle f 1 1 1 (2 or 3) 1 (2 or 3) 1 1001 1000 1011 1010 0111 bbba bbba bbba bbba bbba ffff ffff ffff ffff ffff ffff ffff ffff ffff ffff None None None None None 1, 2 1, 2 3, 4 3, 4 1, 2 Note 1: When a PORT Register is modified as a function of itself (e.g., MOVF PORTB, 1, 0), the value used will be that value present on the pins themselves. For example, if the data latch is '1' for a pin configured as input and is driven low by an external device, the data will be written back with a '0'. 2: If this instruction is executed on the TMR0 Register (and, where applicable, d = 1), the prescaler will be cleared if assigned. 3: If Program Counter (PC) is modified or a conditional test is true, the instruction requires two cycles. The second cycle is executed as a NOP. 4: Some instructions are 2 word instructions. The second word of these instructions will be executed as a NOP, unless the first word of the instruction retrieves the information embedded in these 16-bits. This ensures that all program memory locations have a valid instruction. 5: If the table write starts the write cycle to internal program memory, the write continues until terminated. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-7 Section 31. Instruction Set Instruction Set 31 CONTROL OPERATIONS BC BN BNC BNN BNOV BNZ BOV BRA BZ CALL CLRWDT DAW GOTO NOP NOP POP PUSH RCALL RESET RETFIE RETLW RETURN SLEEP n n n n n n n n n n, s — — n — — — — n s k s — Branch if Carry Branch if Negative Branch if Not Carry Branch if Not Negative Branch if Not Overflow Branch if Not Zero Branch if Overflow Branch Unconditionally Branch if Zero Call subroutine 1st word 2nd word Clear Watchdog Timer Decimal Adjust WREG Go to address 1st word 2nd word No Operation No Operation Pop top of return stack (TOS) Push top of return stack (TOS) Relative Call Software device RESET Return from interrupt enable Return with literal in WREG Return from Subroutine Go into standby mode 1 (2) 1 (2) 1 (2) 1 (2) 1 (2) 1 (2) 1 (2) 2 1 (2) 2 1 1 2 1 1 1 1 2 1 2 2 2 1 1110 1110 1110 1110 1110 1110 1110 1101 1110 1110 1111 0000 0000 1110 1111 0000 1111 0000 0000 1101 0000 0000 0000 0000 0000 0010 0110 0011 0111 0101 0001 0100 0nnn 0000 110s kkkk 0000 0000 1111 kkkk 0000 xxxx 0000 0000 1nnn 0000 0000 1100 0000 0000 nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn kkkk kkkk 0000 0000 kkkk kkkk 0000 xxxx 0000 0000 nnnn 1111 0001 kkkk 0001 0000 nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn kkkk kkkk 0100 0111 kkkk kkkk 0000 xxxx 0110 0101 nnnn 1111 000s kkkk 001s 0011 None None None None None None None None None None TO, PD C None None None None None None All GIE/GIEH, PEIE/GIEL None None TO, PD 4 Table 31-1: PIC18CXXX Instruction Set Summary (Continued) Mnemonic, Operands Description Cycles 16-Bit Instruction Word Status Affected Notes MSb LSb Note 1: When a PORT Register is modified as a function of itself (e.g., MOVF PORTB, 1, 0), the value used will be that value present on the pins themselves. For example, if the data latch is '1' for a pin configured as input and is driven low by an external device, the data will be written back with a '0'. 2: If this instruction is executed on the TMR0 Register (and, where applicable, d = 1), the prescaler will be cleared if assigned. 3: If Program Counter (PC) is modified or a conditional test is true, the instruction requires two cycles. The second cycle is executed as a NOP. 4: Some instructions are 2 word instructions. The second word of these instructions will be executed as a NOP, unless the first word of the instruction retrieves the information embedded in these 16-bits. This ensures that all program memory locations have a valid instruction. 5: If the table write starts the write cycle to internal program memory, the write continues until terminated. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-8  2000 Microchip Technology Inc. LITERAL OPERATIONS ADDLW ANDLW IORLW LFSR MOVLB MOVLW MULLW RETLW SUBLW XORLW k k k f, k k k k k k k Add literal and WREG AND literal with WREG Inclusive OR literal with WREG Move literal (12-bit) 1st word to FSRx 2nd word Move literal to BSR<3:0> Move literal to WREG Multiply literal with WREG Return with literal in WREG Subtract WREG from literal Exclusive OR literal with WREG 1 1 1 2 1 1 1 2 1 1 0000 0000 0000 1110 1111 0000 0000 0000 0000 0000 0000 1111 1011 1001 1110 0000 0001 1110 1101 1100 1000 1010 kkkk kkkk kkkk 00ff kkkk 0000 kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk kkkk C, DC, Z, OV, N Z, N Z, N None None None None None C, DC, Z, OV, N Z, N DATA MEMORY ↔ PROGRAM MEMORY OPERATIONS TBLRD* TBLRD*+ TBLRD*- TBLRD+* TBLWT* TBLWT*+ TBLWT*- TBLWT+* Table Read Table Read with post-increment Table Read with post-decrement Table Read with pre-increment Table Write Table Write with post-increment Table Write with post-decrement Table Write with pre-increment 2 2 2 2 2 (5) 2 (5) 2 (5) 2 (5) 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 1000 1001 1010 1011 1100 1101 1110 1111 None None None None None None None None Table 31-1: PIC18CXXX Instruction Set Summary (Continued) Mnemonic, Operands Description Cycles 16-Bit Instruction Word Status Affected Notes MSb LSb Note 1: When a PORT Register is modified as a function of itself (e.g., MOVF PORTB, 1, 0), the value used will be that value present on the pins themselves. For example, if the data latch is '1' for a pin configured as input and is driven low by an external device, the data will be written back with a '0'. 2: If this instruction is executed on the TMR0 Register (and, where applicable, d = 1), the prescaler will be cleared if assigned. 3: If Program Counter (PC) is modified or a conditional test is true, the instruction requires two cycles. The second cycle is executed as a NOP. 4: Some instructions are 2 word instructions. The second word of these instructions will be executed as a NOP, unless the first word of the instruction retrieves the information embedded in these 16-bits. This ensures that all program memory locations have a valid instruction. 5: If the table write starts the write cycle to internal program memory, the write continues until terminated. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-9 Section 31. Instruction Set Instruction Set 31 31.3 Instruction Formats Figure 31-2 shows the three general formats that the instructions can have. As can be seen from the general format of the instructions, the opcode portion of the instruction word varies from 3-bits to 6-bits of information. This is what allows the Enhanced Instruction Set to have 75 instructions. All instruction examples use the following format to represent a hexadecimal number: 0xhh where h signifies a hexadecimal digit. To represent a binary number: 00000100b where b is a binary string identifier. Figure 31-2: General Format for Instructions Note: Any unused opcode is Reserved. Use of any reserved opcode may cause unexpected operation. Byte-oriented File Register operations 15 10 9 8 7 0 d = 0 for result destination to be WREG Register OPCODE d a f (FILE #) d = 1 for result destination to be File Register (f) a = 0 to force Access Bank Bit-oriented File Register operations 15 12 11 9 8 7 0 OPCODE b (BIT #) a f (FILE #) b = 3-bit position of bit in File Register (f) Literal operations 15 8 7 0 OPCODE k (literal) k = 8-bit immediate value Byte to Byte move operations (2-word) 15 12 11 0 OPCODE f (Source FILE #) CALL, GOTO, and Branch operations 15 8 7 0 OPCODE n<7:0> (literal) n = 20-bit immediate value a = 1 for BSR to select bank f = 8-bit File Register address a = 0 to force Access Bank a = 1 for BSR to select bank f = 8-bit File Register address 15 12 11 0 1111 n<19:8> (literal) 15 12 11 0 1111 f (Destination FILE #) f = 12-bit File Register address Control operations Example Instruction ADDWF MYREG, W, B MOVFF MYREG1, MYREG2 BSF MYREG, bit, B MOVLW 0x7F GOTO label 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-10  2000 Microchip Technology Inc. Table 31-2: Instruction Description Conventions Field Description a RAM access bit a = 0: RAM location in access bank (BSR Register is ignored) a = 1: RAM bank is specified by BSR Register bbb Bit address within an 8-bit File Register (0 to 7) BSR Bank Select Register. Used to select the current RAM bank. d Destination select bit; d = 0: store result in WREG, d = 1: store result in File Register f. dest Destination either the WREG Register or the specified register file location f 8-bit Register file address (0x00 to 0xFF) fs 12-bit Register file address (0x000 to 0xFFF). This is the source address. fd 12-bit Register file address (0x000 to 0xFFF). This is the destination address. k Literal field, constant data or label (may be either an 8-bit, 12-bit or a 20-bit value) label Label name mm The mode of the TBLPTR Register for the Table Read and Table Write instructions Only used with Table Read and Table Write instructions: * No Change to Register (such as TBLPTR with Table reads and writes) *+ Post-Increment Register (such as TBLPTR with Table reads and writes) *- Post-Decrement Register (such as TBLPTR with Table reads and writes) +* Pre-Increment Register (such as TBLPTR with Table reads and writes) n The relative address (2’s complement number) for relative branch instructions, or the direct address for Call/Branch and Return instructions PRODH Product of Multiply high byte PRODL Product of Multiply low byte s Fast Call / Return mode select bit. s = 0: do not update into/from Shadow Registers s = 1: certain registers loaded into/from Shadow Registers u Unused or Unchanged WREG Working Register (accumulator) x Don't care (0 or 1) The assembler will generate code with x = 0. It is the recommended form of use for compatibility with all Microchip software tools. TBLPTR 21-bit Table Pointer (points to a Program Memory location) TABLAT 8-bit Table Latch TOS Top of Stack INDF Any one of the indirect addressing registers, such as INDF0, INDF1, or INDF2 FSR Any one of the file select register pairs, such as FSR0H:FSR0L, FSR1H:FSR1L, or FSR2H:FSR2L 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-11 Section 31. Instruction Set Instruction Set 31 Table 31-3: Indirect Addressing Symbols PC Program Counter PCL Program Counter Low Byte PCH Program Counter High Byte PCLATH Program Counter High Byte Latch PCLATU Program Counter Upper Byte Latch GIE Global Interrupt Enable bit WDT Watchdog Timer TO Time-out bit PD Power-down bit C,DC, Z,OV,N ALU status bits Carry, Digit Carry, Zero, Overflow, Negative [ ] Optional ( ) Contents of → Assigned to < > Register bit field ∈ In the set of italics User defined term (font is courier) Field Description *FSRn Selects INDFn Register *FSRn++ Selects POSTINCn Register *FSRn-- Selects POSTDECn Register *(++FSRn) Selects PREINCn Register *(FSRn+W) Selects PLUSWn Register Table 31-2: Instruction Description Conventions (Continued) Field Description 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-12  2000 Microchip Technology Inc. 31.4 Special Function Registers as Source/Destination The Section 31. Instruction Set’s Orthogonal Instruction Set allows read and write of all File Registers, including Special Function Registers. The user should be aware of some special situations which are explained in the following subsections. 31.4.1 STATUS Register as Destination If an instruction writes to the STATUS Register, the Z, C, DC, OV, and N bits may be set or cleared as a result of the instruction and overwrite the original data bits. For example, executing CLRF STATUS will clear Register STATUS, and then set the Z bit leaving 0000 0100b in the register. 31.4.2 Bit Manipulation All bit manipulation instructions will first read the entire register, operate on the selected bit and then write the result back to (read-modify-write (R-M-W)) the specified register. The user should keep this in mind when operating on some Special Function Registers, such as the Port Pin Register. 31.4.3 PCL as Source or Destination Read, write or read-modify-write (R-M-W) on PCL may have the following results: Read PCL: PCL → destination ; Reading PCL causes the following PCH → PCLATH PCU → PCLATU Write PCL: 8-bit destination value → PCL ; Writing PCL causes the following PCLATH → PCH PCLATU → PCU Read-Modify-Write: PCL→ ALU operand ; R-M-W of PCL causes the following PCH → PCLATH PCU → PCLATU ; PCL data is modified 8-bit result → PCL ; result is written back to PCL PCLATH → PCH PCLATU → PCU Where PCH = program counter high byte (not an addressable register), PCLATH = Program counter high holding latch, PCU = program counter upper byte (not an addressable register), PCLATU = Program counter upper holding latch, destination = Register file ’f’. Note: Status bits that are manipulated by the device (including the interrupt flag bits) are set or cleared in the Q1 cycle, so there is no issue with executing R-M-W instructions on registers that contain these bits. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-13 Section 31. Instruction Set Instruction Set 31 31.5 Fast Register Stack At times it is desirable to be able to quickly access and return from a function. This function may be called as a subroutine, or an interrupt routine of the device. To reduce the overhead for accessing/returning from these functions, the architecture has the ability to save three key registers in a one deep Register Stack. These registers are: • WREG Register • BSR (Bank Select Register) Register • STATUS Register The two events that cause these registers to be loaded onto the Fast Register Stack are: • A fast call (CALL K, fast)(where the fast bit is set (’1’)) • Any interrupt occurs These Fast Stack Registers are not accessible for reading or writing. When doing the return from these subroutine, the values can be restored into their registers executing the fast return: • RETFIE fast (where the fast bit is set (’1’)) • RETURN fast (where the fast bit is set (’1’)) When s (fast) = ’0’, the Fast Register Stack is not used, when s (fast) = ’1’, the Fast Register Stack is used. 31.6 Q Cycle Activity Each instruction cycle (Tcy) is comprised of four Q clocks (also called Q cycles). These are referred to as Q1, Q2, Q3, or Q4. The Q cycles provide the timing/designation for the Decode, Read, Process Data, Write etc., of each instruction cycle. The Figure 31-3 shows the relationship of the Q cycles to the instruction cycle. The four Q cycles that make up an instruction cycle (Tcy) can be generalized as: Q1: Instruction Decode Cycle or forced No Operation Q2: Instruction Read Cycle or No Operation Q3: Process the Data Q4: Instruction Write Cycle or No Operation Some actions occur on the edge between the end of one Q cycle and the start of the next Q cycle. An example would be a Q2-Q3 action. This action occurs on the clock edge between the end of Q2 cycle and the beginning of the Q3 cycle. The clock source for the Q cycle is normally the device oscillator clock (TOSC). But the clock source is software selectable. So the Q cycle may be independent of the device oscillator cycle (TOSC). In the full description of each instruction, the detailed Q cycle operation for the instruction will be shown. Figure 31-3: Q Cycle Activity Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Tcy1 Tcy2 Tcy3 TOSC 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-14  2000 Microchip Technology Inc. 31.7 Instruction Descriptions ADDLW Add Literal to WREG Syntax: [ label ] ADDLW k Operands: 0 ≤ k ≤ 255 Operation: (WREG) + k → WREG Status Affected: C, DC, Z, OV, N Encoding: 0000 1111 kkkk kkkk Description: The eight bit literal ’k’ is added to the contents of the WREG and the result is placed in the WREG. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data Write to WREG Register Example1 ADDLW 0x19 ; Add 19h to value in WREG Before Instruction WREG = 0x18 C, DC, Z, OV, N = x After Instruction WREG = 0x31 C =0 DC = 1 Z =0 OV = 0 N =0 Example 2 ADDLW MYREG ; Add the value of the ; address for MYREG Register ; to WREG Before Instruction WREG = 0x60 Address of MYREG † = 0x37 † MYREG is a symbol for a data memory location C, DC, Z, OV, N = x After Instruction WREG = 0x97 C =0 DC = 0 Z =0 OV = 1 N =1 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-15 Section 31. Instruction Set Instruction Set 31 Example 3 ADDLW HIGH (LU_TABLE) ; Add high byte of address ; LU_TABLE to WREG Before Instruction WREG = 0x10 Address of LU_TABLE † = 0x9375 † LU_TABLE is a label for an address in program memory C, DC, Z, OV, N = x After Instruction WREG = 0xA3 C =0 DC = 0 Z =0 OV = 0 N =1 Example 4 ADDLW PCL ; Add value of the address ; of Program Counter Low ; byte (PCL) to WREG Before Instruction WREG = 0x02 Address of PCL † = 0xFF8 (only low 8-bits are used) † PCL is the symbol for the Program Counter low byte location C, DC, Z, OV, N = x After Instruction WREG = 0xFA C =0 DC = 0 Z =0 OV = 0 N =0 Example 5 ADDLW Offset ; Add the value of symbol ; Offset to WREG Before Instruction WREG = 0x10 Offset = 0x02 C, DC, Z, OV, N = x After Instruction WREG = 0x12 Offset = 0x02 C =0 DC = 0 Z =0 OV = 0 N =0 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-16  2000 Microchip Technology Inc. ADDWF Add WREG and f Syntax: [ label ] ADDWF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (WREG) + (f) → destination Status Affected: C, DC, Z, OV, N Encoding: 0010 01da ffff ffff Description: Add the contents of the WREG Register to the contents of Register 'f'. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 ADDWF FSR0L, 1, 1 ; Add value in WREG to ; value in the ; FSR0H:FSR0L Register Case 1: Before Instruction WREG = 0x17 FSR0H:FSR0L = 0x2C2 C, DC, Z, OV, N = x After Instruction WREG = 0x17 FSR0H:FSR0L = 0x2D9 C =0 DC = 0 Z =0 OV = 0 N =1 Case 2: Before Instruction WREG = 0x17 FSR0H:FSR0L = 0x2FF C, DC, Z, OV, N = x After Instruction WREG = 0x17 FSR0H:FSR0L = 0x316 C =0 DC = 0 Z =0 OV = 0 N =0 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-17 Section 31. Instruction Set Instruction Set 31 Example 2 ADDWF INDF0, 1, 1 ; Add value in WREG to ; value in the register ; pointed to (addressed) ; by the FSR0H:FSR0L ; Register Before Instruction WREG = 0x17 FSR0H:FSR0L = 0x6C2 Contents of Address (FSR0) = 0x20 C, DC, Z, OV, N = x After Instruction WREG = 0x17 FSR0H:FSR0L = 0x6C2 Contents of Address (FSR0) = 0x37 C =0 DC = 0 Z =0 OV = 0 N =0 Example 3 ADDWF INDF0, 1, 0 ; Add value in WREG to ; value in the register ; pointed to (addressed) ; by the FSR0H:FSR0L ; Register Before Instruction WREG = 0x17 FSR0H:FSR0L = 0x0C2 Contents of Address (FSR0) = 0x20 C, DC, Z, OV, N = x After Instruction WREG = 0x17 FSR0H:FSR0L = 0x0C2 Contents of Address (FSR0) = 0x37 C =0 DC = 0 Z =0 OV = 0 N =0 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-18  2000 Microchip Technology Inc. Example 4 ADDWF PCL, 1, 1 ; Add the value in WREG to ; the current value in the ; low byte of the program ; counter (PCL) Case 1: Before Instruction WREG = 0x10 PCL = 0x37 C, DC, Z, OV, N = x After Instruction WREG = 0x10 PCL = 0x47 C =0 DC = 0 Z =0 OV = 0 N =0 Case 2: Before Instruction WREG = 0x10 PCL = 0xF7 PCH = 0x08 C, DC, Z, OV, N = x After Instruction WREG = 0x10 PCL = 0x07 PCH = 0x08 C =1 DC = 0 Z =0 OV = 0 N =0 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-19 Section 31. Instruction Set Instruction Set 31 Example 5 ADDWF MYREG, 1 ; Add the value in WREG to ; the current value in ; MYREG ; (assembler determines ; that MYREG requires ; access bit to be set) Case 1: Before Instruction BSR = 0x01 WREG = 0x10 MYREG = 0x37 C, DC, Z, OV, N = x After Instruction BSR = 0x01 WREG = 0x10 MYREG = 0x47 C =0 DC = 0 Z =0 OV = 0 N =0 ; In Bank 1 ; In Bank 1 Case 2: Before Instruction BSR = 0x01 WREG = 0x10 MYREG = 0xF7 C, DC, Z, OV, N = x After Instruction BSR = 0x01 WREG = 0x10 MYREG = 0x07 C =1 DC = 0 Z =0 OV = 0 N =0 ; In Bank 1 ; In Bank 1 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-20  2000 Microchip Technology Inc. ADDWFC Add WREG and Carry bit to f Syntax: [ label ] ADDWF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (WREG) + (f) + (C) → destination Status Affected: C, DC, Z, OV, N Encoding: 0010 00da ffff ffff Description: Add the contents of the WREG Register and the Carry bit to the contents of Register 'f'. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 ADDWFC FSR0L, 0, 1 ; Add WREG, C bit, and FSR0L ; value (Destination WREG) Case 1: Before Instruction WREG = 0x17 FSR0H:FSR0L = 0x9C2 C =0 DC, Z, OV, N = x After Instruction WREG = 0xD9 FSR0H:FSR0L = 0x9C2 C =0 DC = 0 Z =0 OV = 0 N =1 Case 2: Before Instruction WREG = 0x17 FSR0H:FSR0L = 0x7C2 C =1 DC, Z, OV, N = x After Instruction WREG = 0xDA FSR0H:FSR0L = 0x7C2 C =0 DC = 0 Z =0 OV = 0 N =1 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-21 Section 31. Instruction Set Instruction Set 31 Example 2 ADDWFC INDF0, 1, 1 ; Add WREG and the Carry ; bit to the value pointed ; to by the FSR0H:FSR0L ; (Destination: File ; Register) Before Instruction WREG = 0x17 FSR0H:FSR0L = 0x0C2 Contents of Address (FSR0H:FSR0L) = 0x20 C =0 DC, Z, OV, N = x After Instruction WREG = 0x17 FSR0H:FSR0L = 0x0C2 Contents of Address (FSR0H:FSR0L) = 0x37 C =0 DC = 0 Z =0 OV = 0 N =0 Example 3 ADDWFC PCL, 1, 1 ; Add WREG and the Carry ; bit to the PCL Register Case 1: Before Instruction WREG = 0x10 PCL = 0x38 C =0 DC, Z, OV, N = x After Instruction WREG = 0x10 PCL = 0x48 C =0 DC = 0 Z =0 OV = 0 N =0 Case 2: Before Instruction WREG = 0x10 PCL = 0xF8 PCH = 0x08 C =0 DC, Z, OV, N = x After Instruction WREG = 0x10 PCL = 0x08 PCH = 0x08 C =1 DC = 0 Z =0 OV = 0 N =0 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-22  2000 Microchip Technology Inc. ANDLW AND Literal with WREG Syntax: [ label ] ANDLW k Operands: 0 ≤ k ≤ 255 Operation: (WREG).AND. (k) → W Status Affected: Z, N Encoding: 0000 1011 kkkk kkkk Description: The contents of WREG Register are AND’d with the eight bit literal 'k'. The result is placed in the WREG Register. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data Write to WREG Register Example 1 ANDLW 0x5F ; And constant to WREG Before Instruction WREG = 0xA3 Z, N = x After Instruction WREG = 0x03 Z =0 N =0 ; 0101 1111 (0x5F) ; 1010 0011 (0xA3) ;---------- ------ ; 0000 0011 (0x03) Example 2 ANDLW MYREG ; And address of MYREG ; to WREG Before Instruction WREG = 0xA3 Address of MYREG † = 0x37 Z, N = x † MYREG is a symbol for a data memory location After Instruction WREG = 0x23 Z =0 N =0 ; 0011 0111 (0x37) ; 1010 0011 (0xA3) ;---------- ------ ; 0010 0011 (0x23) 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-23 Section 31. Instruction Set Instruction Set 31 Example 3 ANDLW HIGH (LU_TABLE) ; And the high byte of ; address LU_TABLE ; with WREG Before Instruction WREG = 0xA3 Address of LU_TABLE † = 0x9375 Z, N = x † LU_TABLE is a label for an address in program memory After Instruction WREG = 0x83 Z =0 N =1 ; 1010 0011 (0xA3) ; 1001 0011 (0x93) ;---------- ------ ; 1000 0011 (0x83) Example 4 ANDLW LOW (LU_TABLE); And the low byte of ; address LU_TABLE ; with WREG Before Instruction WREG = 0xA3 Address of LU_TABLE † = 0x9375 Z, N = x † LU_TABLE is a label for an address in program memory After Instruction WREG = 0x21 Z =0 N =0 ; 1010 0011 (0xA3) ; 0111 0101 (0x75) ;---------- ------ ; 0010 0001 (0x21) 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-24  2000 Microchip Technology Inc. ANDWF AND WREG with f Syntax: [ label ] ANDWF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (WREG).AND. (f) → destination Status Affected: Z, N Encoding: 0001 01da ffff ffff Description: The contents of the WREG Register are AND’d with the contents of Register 'f'. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 ANDWF REG1, 1, 1 ; And WREG with REG1 Before Instruction WREG = 0x17 REG1 = 0xC2 Z, N = x After Instruction WREG = 0x17 REG1 = 0x02 Z =0 N =0 ; 0001 0111 (0x17) ; 1100 0010 (0xC2) ;---------- ------ ; 0000 0010 (0x02) Example 2 ANDWF REG1, 0, 1 ; And WREG with REG1 ; (destination WREG) Before Instruction WREG = 0x17 REG1 = 0xC2 Z, N = x After Instruction WREG = 0x02 REG1 = 0xC2 Z =0 N =0 ; 0001 0111 (0x17) ; 1100 0010 (0xC2) ;---------- ------ ; 0000 0010 (0x02) 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-25 Section 31. Instruction Set Instruction Set 31 Example 3 ANDWF INDF0, 1, 1 ; And WREG with value pointed ; by FSR0H:FSR0L (FSR0) Case 1: Before Instruction WREG = 0x17 FSR0H:FSR0L = 0xFC2 Contents of Address (FSR0) = 0x5A Z, N = x After Instruction WREG = 0x17 FSR0H:FSR0L = 0xFC2 Contents of Address (FSR0) = 0x12 Z =0 N =0 ; 0001 0111 (0x17) ; 0101 1010 (0x5A) ;---------- ------ ; 0001 0010 (0x12) Case 2: Before Instruction WREG = 0x00 FSR0H:FSR0L = 0x4C2 Contents of Address (FSR0) = 0x5A Z, N = x After Instruction WREG = 0x00 FSR0H:FSR0L = 0x4C2 Contents of Address (FSR0) = 0x00 Z =1 N =0 ; 0000 0000 (0x00) ; 0101 1010 (0x5A) ;---------- ------ ; 0000 0000 (0x00) 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-26  2000 Microchip Technology Inc. BC Branch if Carry Syntax: [ label ] BC n Operands: -128 ≤ f ≤ 127 Operation: If carry bit is ’1’ (PC + 2) + 2n → PC Status Affected: None Encoding: 1110 0010 nnnn nnnn Description: If the Carry bit is ’1’, then the program will branch. The 2’s complement number ’2n’ (the offset) is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be (PC+2)+2n. This instruction is then a two-cycle instruction. Words: 1 Cycles: 1 (2) Q Cycle Activity: If Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data Write to PC No operation No operation No operation No operation If No Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data No operation Example 1 HERE NOT_C C_CODE BC • • GOTO • • C_CODE MORE_CODE ; ; If C bit is not set ; execute this code. ; ; else if C bit is set ; this code will execute Case 1: Before Instruction PC = address HERE C =0 After Instruction PC = address NOT_C Case 2: Before Instruction PC = address HERE C =1 After Instruction PC = address C_CODE 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-27 Section 31. Instruction Set Instruction Set 31 Example 2 HERE NO_C PLUS0 PLUS1 PLUS2 PLUS3 PLUS4 PLUS5 PLUS6 BC GOTO • • • • • • • $ + OFFSET PROCESS_CODE ; If carry bit is set, ; branch to HERE+OFFSET Case 1: Before Instruction PC = address HERE C =0 After Instruction PC = address NO_C Case 2: Before Instruction PC = address HERE C =1 After Instruction PC = address HERE + OFFSET Example 3 MIN6 MIN5 MIN4 MIN3 MIN2 MIN1 MIN0 HERE NO_C • • • • • • • BC GOTO $ - OFFSET PROCESS_CODE ; If carry bit is set, ; branch to HERE-OFFSET Case 1: Before Instruction PC = address HERE C =0 After Instruction PC = address NO_C Case 2: Before Instruction PC = address HERE C =1 After Instruction PC = address HERE - OFFSET Note: Assembler will convert the specified address label into the offset to be used. 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-28  2000 Microchip Technology Inc. BCF Bit Clear f Syntax: [ label ] BCF f, b, a Operands: 0 ≤ f ≤ 255 0 ≤ b ≤ 7 a ∈ [0,1] Operation: 0 → f Status Affected: None Encoding: 1001 bbba ffff ffff Description: Bit 'b' in Register 'f' of the specified bank is cleared. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write Register 'f' Example 1 BCF MYREG, 7, 1 ; Clear bit 7 in Register ; MYREG Before Instruction MYREG = 0xC7 After Instruction MYREG = 0x47 ; 1100 0111 ; 0100 0111 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-29 Section 31. Instruction Set Instruction Set 31 Example 2 BCF INDF0, 3, 0 ; Clear bit 7 in the register ; pointed to by the FSR0 ; (FSR0H:FSR0L) Register Before Instruction FSR0 = 0x3C2 Contents of Address (FSR0) = 0x2F After Instruction FSR0 = 0x3C2 Contents of Address (FSR0) = 0x27 ; 0010 1111 ; 0010 0111 39500 18C Reference Manual.book Page 29 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-30  2000 Microchip Technology Inc. BN Branch if Negative Syntax: [ label ] BN n Operands: -128 ≤ f ≤ 127 Operation: If negative bit is ’1’ (PC + 2) + 2n → PC Status Affected: None Encoding: 1110 0110 nnnn nnnn Description: If the Negative bit is ’1’, then the program will branch. The 2’s complement number ’2n’ (the offset) is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be (PC+2)+2n. This instruction is then a two-cycle instruction. Words: 1 Cycles: 1 (2) Q Cycle Activity: If Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data Write to PC No operation No operation No operation No operation If No Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data No operation Example 1 HERE NOT_N N_CODE BN • • GOTO • • N_CODE MORE_CODE ; If N bit is not set ; execute this code. ; ; ; else if N bit is set ; this code will execute Case 1: Before Instruction PC = address HERE N =0 After Instruction PC = address NOT_N Case 2: Before Instruction PC = address HERE N =1 After Instruction PC = address N_CODE 39500 18C Reference Manual.book Page 30 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-31 Section 31. Instruction Set Instruction Set 31 Example 2 HERE NOT_N PLUS0 PLUS1 PLUS2 PLUS3 PLUS4 PLUS5 PLUS6 BN GOTO • • • • • • • $ + OFFSET PROCESS_CODE ; If negative bit is set, ; branch to HERE + OFFSET Case 1: Before Instruction PC = address HERE N =0 After Instruction PC = address NOT_N Case 2: Before Instruction PC = address HERE N =1 After Instruction PC = address HERE + OFFSET Example 3 MIN6 MIN5 MIN4 MIN3 MIN2 MIN1 MIN0 HERE NO_N • • • • • • • BN GOTO $ - OFFSET PROCESS_CODE ; If negative bit is set, ; branch to HERE - OFFSET Case 1: Before Instruction PC = address HERE N =0 After Instruction PC = address NO_N Case 2: Before Instruction PC = address HERE N =1 After Instruction PC = address HERE - OFFSET Note: Assembler will convert the specified address label into the offset to be used. 39500 18C Reference Manual.book Page 31 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-32  2000 Microchip Technology Inc. BNC Branch if Not Carry Syntax: [ label ] BNC n Operands: -128 ≤ f ≤ 127 Operation: If carry bit is ’0’ (PC + 2) + 2n → PC Status Affected: None Encoding: 1110 0011 nnnn nnnn Description: If the Carry bit is ’0’, then the program will branch. The 2’s complement number ’2n’ (the offset) is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be (PC+2)+2n. This instruction is then a two-cycle instruction. Words: 1 Cycles: 1 (2) Q Cycle Activity: If Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data Write to PC No operation No operation No operation No operation If No Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data No operation Example 1 HERE CARRY NC_CODE BNC • • GOTO • • NC_CODE MORE_CODE ; If C bit is set ; execute this code. ; ; ; else if C bit is clear ; this code will execute Case 1: Before Instruction PC = address HERE C =0 After Instruction PC = address NC_CODE Case 2: Before Instruction PC = address HERE C =1 After Instruction PC = address CARRY 39500 18C Reference Manual.book Page 32 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-33 Section 31. Instruction Set Instruction Set 31 Example 2 HERE CARRY PLUS0 PLUS1 PLUS2 PLUS3 PLUS4 PLUS5 PLUS6 BNC GOTO • • • • • • • $ + OFFSET PROCESS_CODE ; If carry bit is clear, ; branch to HERE + OFFSET Case 1: Before Instruction PC = address HERE C =0 After Instruction PC = address HERE + OFFSET Case 2: Before Instruction PC = address HERE C =1 After Instruction PC = address CARRY Example 3 MIN6 MIN5 MIN4 MIN3 MIN2 MIN1 MIN0 HERE CARRY • • • • • • • BNC GOTO $ - OFFSET PROCESS_CODE ; If carry bit is clear, ; branch to HERE - OFFSET Case 1: Before Instruction PC = address HERE C =0 After Instruction PC = address HERE - OFFSET Case 2: Before Instruction PC = address HERE C =1 After Instruction PC = address CARRY Note: Assembler will convert the specified address label into the offset to be used. 39500 18C Reference Manual.book Page 33 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-34  2000 Microchip Technology Inc. BNN Branch if Not Negative Syntax: [ label ] BNN n Operands: -128 ≤ f ≤ 127 Operation: If negative bit is ’0’ (PC + 2) + 2n → PC Status Affected: None Encoding: 1110 0111 nnnn nnnn Description: If the Negative bit is ’0’, then the program will branch. The 2’s complement number ’2n’ (the offset) is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be (PC+2)+2n. This instruction is then a two-cycle instruction. Words: 1 Cycles: 1 (2) Q Cycle Activity: If Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data Write to PC No operation No operation No operation No operation If No Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data No operation Example 1 HERE NEG POS_CODE BNN • • GOTO • • POS_CODE MORE_CODE ; If N bit is set ; execute this code. ; ; ; else if N bit is clear ; this code will execute Case 1: Before Instruction PC = address HERE N =0 After Instruction PC = address POS_CODE Case 2: Before Instruction PC = address HERE N =1 After Instruction PC = address NEG 39500 18C Reference Manual.book Page 34 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-35 Section 31. Instruction Set Instruction Set 31 Example 2 HERE NEG PLUS0 PLUS1 PLUS2 PLUS3 PLUS4 PLUS5 PLUS6 BNN GOTO • • • • • • • $ + OFFSET PROCESS_CODE ; If negative bit is clear, ; branch to HERE + OFFSET Case 1: Before Instruction PC = address HERE N =0 After Instruction PC = address HERE + OFFSET Case 2: Before Instruction PC = address HERE N =1 After Instruction PC = address NEG Example 3 MIN6 MIN5 MIN4 MIN3 MIN2 MIN1 MIN0 HERE NEG • • • • • • • BNN GOTO $ - OFFSET PROCESS_CODE ; If negative bit is clear, ; branch to HERE - OFFSET Case 1: Before Instruction PC = address HERE N =0 After Instruction PC = address HERE - OFFSET Case 2: Before Instruction PC = address HERE N =1 After Instruction PC = address NEG Note: Assembler will convert the specified address label into the offset to be used. 39500 18C Reference Manual.book Page 35 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-36  2000 Microchip Technology Inc. BNOV Branch if Not Overflow Syntax: [ label ] BNOV n Operands: -128 ≤ f ≤ 127 Operation: If overflow bit is ’0’ (PC + 2) + 2n → PC Status Affected: None Encoding: 1110 0101 nnnn nnnn Description: If the Overflow bit is ’0’, then the program will branch. The 2’s complement number ’2n’ (the offset) is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be (PC+2)+2n. This instruction is then a two-cycle instruction. Words: 1 Cycles: 1 (2) Q Cycle Activity: If Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data Write to PC No operation No operation No operation No operation If No Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data No operation Example 1 HERE OVFL NOV_CODE BNOV • • GOTO • • NOV_CODE MORE_CODE ; If overflow bit is set ; execute this code. ; ; ; else if overflow bit is ; clear this code will ; execute Case 1: Before Instruction PC = address HERE OV = 0 After Instruction PC = address NOV_CODE Case 2: Before Instruction PC = address HERE OV = 1 After Instruction PC = address OVFL 39500 18C Reference Manual.book Page 36 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-37 Section 31. Instruction Set Instruction Set 31 Example 2 HERE OVFL PLUS0 PLUS1 PLUS2 PLUS3 PLUS4 PLUS5 PLUS6 BNOV GOTO • • • • • • • $ + OFFSET PROCESS_CODE ; If overflow bit is clear, ; branch to HERE + OFFSET Case 1: Before Instruction PC = address HERE OV = 0 After Instruction PC = address HERE + OFFSET Case 2: Before Instruction PC = address HERE OV = 1 After Instruction PC = address OVFL Example 3 MIN6 MIN5 MIN4 MIN3 MIN2 MIN1 MIN0 HERE OVFL • • • • • • • BNOV GOTO $ - OFFSET PROCESS_CODE ; If overflow bit is clear, ; branch to HERE - OFFSET Case 1: Before Instruction PC = address HERE OV = 0 After Instruction PC = address HERE - OFFSET Case 2: Before Instruction PC = address HERE OV = 1 After Instruction PC = address OVFL Note: Assembler will convert the specified address label into the offset to be used. 39500 18C Reference Manual.book Page 37 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-38  2000 Microchip Technology Inc. BNZ Branch if Not Zero Syntax: [ label ] BNZ n Operands: -128 ≤ f ≤ 127 Operation: If zero bit is ’0’ (PC + 2) + 2n → PC Status Affected: None Encoding: 1110 0001 nnnn nnnn Description: If the Zero bit is ’0’, then the program will branch. The 2’s complement number ’2n’ (the offset) is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be (PC+2)+2n. This instruction is then a two-cycle instruction. Words: 1 Cycles: 1 (2) Q Cycle Activity: If Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data Write to PC No operation No operation No operation No operation If No Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data No operation Example 1 HERE ZERO Z_CODE BNZ • • GOTO • • Z_CODE MORE_CODE ; If Z bit is set ; execute this code. ; ; ; else if Z bit is clear ; this code will execute Case 1: Before Instruction PC = address HERE Z =0 After Instruction PC = address Z_CODE Case 2: Before Instruction PC = address HERE Z =1 After Instruction PC = address ZERO 39500 18C Reference Manual.book Page 38 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-39 Section 31. Instruction Set Instruction Set 31 Example 2 HERE ZERO PLUS0 PLUS1 PLUS2 PLUS3 PLUS4 PLUS5 PLUS6 BNZ GOTO • • • • • • • $ + OFFSET PROCESS_CODE ; If zero bit is clear, ; branch to HERE + OFFSET Case 1: Before Instruction PC = address HERE Z =0 After Instruction PC = address HERE + OFFSET Case 2: Before Instruction PC = address HERE Z =1 After Instruction PC = address ZERO Example 3 MIN6 MIN5 MIN4 MIN3 MIN2 MIN1 MIN0 HERE ZERO • • • • • • • BNZ GOTO $ - OFFSET PROCESS_CODE ; If zero bit is clear, ; branch to HERE - OFFSET Case 1: Before Instruction PC = address HERE Z =0 After Instruction PC = address HERE - OFFSET Case 2: Before Instruction PC = address HERE Z =1 After Instruction PC = address ZERO Note: Assembler will convert the specified address label into the offset to be used. 39500 18C Reference Manual.book Page 39 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-40  2000 Microchip Technology Inc. BOV Branch if Overflow Syntax: [ label ] BOV n Operands: -128 ≤ f ≤ 127 Operation: If overflow bit is ’1’ (PC + 2) + 2n → PC Status Affected: None Encoding: 1110 0100 nnnn nnnn Description: If the Overflow bit is ’1’, then the program will branch. The 2’s complement number ’2n’ (the offset) is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be (PC+2)+2n. This instruction is then a two-cycle instruction. Words: 1 Cycles: 1 (2) Q Cycle Activity: If Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data Write to PC No operation No operation No operation No operation If No Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data No operation Example 1 HERE OVFL OV_CODE BOV • • GOTO • • OV_CODE MORE_CODE ; If OV bit is clear ; execute this code. ; ; ; else if OV bit is set ; this code will execute Case 1: Before Instruction PC = address HERE OV = 0 After Instruction PC = address OVFL Case 2: Before Instruction PC = address HERE OV = 1 After Instruction PC = address OV_CODE 39500 18C Reference Manual.book Page 40 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-41 Section 31. Instruction Set Instruction Set 31 Example 2 HERE OVFL PLUS0 PLUS1 PLUS2 PLUS3 PLUS4 PLUS5 PLUS6 BOV GOTO • • • • • • • $ + OFFSET PROCESS_CODE ; If overflow bit is set, ; branch to HERE + OFFSET Case 1: Before Instruction PC = address HERE OV = 0 After Instruction PC = address OVFL Case 2: Before Instruction PC = address HERE OV = 1 After Instruction PC = address HERE + OFFSET Example 3 MIN6 MIN5 MIN4 MIN3 MIN2 MIN1 MIN0 HERE OVFL • • • • • • • BOV GOTO $ - OFFSET PROCESS_CODE ; If OV bit is set, ; branch to HERE - OFFSET Case 1: Before Instruction PC = address HERE OV = 0 After Instruction PC = address OVFL Case 2: Before Instruction PC = address HERE OV = 1 After Instruction PC = address HERE - OFFSET Note: Assembler will convert the specified address label into the offset to be used. 39500 18C Reference Manual.book Page 41 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-42  2000 Microchip Technology Inc. BRA Branch Unconditional Syntax: [ label ] BRA n Operands: -1024 ≤ f ≤ 1023 Operation: (PC + 2) + 2n → PC Status Affected: None Encoding: 1101 0nnn nnnn nnnn Description: The 2’s complement number ’2n’ (the offset) is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be (PC+2)+2n. This instruction is a two-cycle instruction. Words: 1 Cycles: 2 Q Cycle Activity: If Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data Write to PC No operation No operation No operation No operation If No Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data No operation Example 1 HERE THERE BRA • • • • THERE ; Branch to a program memory ; location (THERE) ; this location must be ; < 1023 locations forward Before Instruction PC = address HERE After Instruction PC = address THERE 39500 18C Reference Manual.book Page 42 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-43 Section 31. Instruction Set Instruction Set 31 Example 2 THERE HERE • • • • BRA THERE ; Branch to a program memory ; location (THERE) ; this location must be ; < 1024 locations backward Before Instruction PC = address HERE After Instruction PC = address THERE Example 3 HERE BRA $ ; Branch to program memory ; location (HERE). ; Infinite Loop Before Instruction PC = address HERE After Instruction PC = address HERE Note: Assembler will convert the specified address label into the offset to be used. 39500 18C Reference Manual.book Page 43 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-44  2000 Microchip Technology Inc. BSF Bit Set f Syntax: [ label ] BSF f, b, a Operands: 0 ≤ f ≤ 255 0 ≤ b ≤ 7 a ∈ [0,1] Operation: 1 → f Status Affected: None Encoding: 1000 bbba ffff ffff Description: Bit 'b' in Register 'f' is set. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write Register 'f' Example 1 BSF FLAG_REG, 7 ; Set bit 7 in Register ; FLAG_REG ; (assembler determines ; that FLAG_REG requires ; access bit to be set) Before Instruction FLAG_REG = 0x0A After Instruction FLAG_REG = 0x8A ; 0000 1010 ; 1000 1010 Example 2 BSF INDF0, 3, 0 ; Set bit 3 in the register ; pointed to by the FSR0 ; (FSR0H:FSR0L) Register Before Instruction WREG = 0x17 FSR0 = 0x0C2 Contents of Address (FSR0)= 0x20 After Instruction WREG = 0x17 FSR0 = 0x0C2 Contents of Address (FSR0) = 0x28 ; 0010 0000 ; 0010 1000 39500 18C Reference Manual.book Page 44 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-45 Section 31. Instruction Set Instruction Set 31 BTFSC Bit Test File, Skip if Clear Syntax: [ label ] BTFSC f, b, a Operands: 0 ≤ f ≤ 255 0 ≤ b ≤ 7 a ∈ [0,1] Operation: Skip if (f) = 0 Status Affected: None Encoding: 1011 bbba ffff ffff Description: If bit 'b' in Register 'f' is '0' then the next instruction is skipped. If bit 'b' is '0' then the next instruction (fetched during the current instruction execution) is discarded, and a NOP is executed instead, making this a 2-cycle instruction. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data No operation If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by a two word instruction: Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation Example 1 HERE FALSE TRUE BTFSC GOTO • • • FLAG, 4, 1 PROCESS_CODE ; Test bit 4 of Register ; FLAG, and skip if ; clear Case 1: Before Instruction PC = address HERE FLAG = xxx0 xxxx After Instruction Since FLAG<4> = 0 PC = address TRUE Case 2: Before Instruction PC = address HERE FLAG = xxx1 xxxx After Instruction Since FLAG<4> = 1 PC = address FALSE 39500 18C Reference Manual.book Page 45 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-46  2000 Microchip Technology Inc. BTFSS Bit Test File, Skip if Set Syntax: [ label ] BTFSS f, b, a Operands: 0 ≤ f ≤ 255 0 ≤ b<7 a ∈ [0,1] Operation: Skip if (f) = 1 Status Affected: None Encoding: 1010 bbba ffff ffff Description: If bit 'b' in Register 'f' is '1' then the next instruction is skipped. If bit 'b' is '1', then the next instruction (fetched during the current instruction execution) is discarded and a NOP is executed instead, making this a 2-cycle instruction. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data No operation If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by a two word instruction: Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation Example 1 HERE FALSE TRUE BTFSS GOTO • • • FLAG, 4, 0 PROCESS_CODE ; Test bit 4 of Register ; FLAG, and skip if set Case 1: Before Instruction PC = address HERE FLAG = xxx0 xxxx After Instruction Since FLAG<4> = 0 PC = address FALSE Case 2: Before Instruction PC = address HERE FLAG = xxx1 xxxx After Instruction Since FLAG<4> = 1 PC = address TRUE 39500 18C Reference Manual.book Page 46 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-47 Section 31. Instruction Set Instruction Set 31 BTG Bit Toggle f Syntax: [ label ] BTG f, b, a Operands: 0 ≤ f ≤ 255 0 ≤ b ≤ 7 a ∈ [0,1] Operation: (f) → f Status Affected: None Encoding: 0111 bbba ffff ffff Description: Bit 'b' in Register 'f' is toggled. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write Register 'f' Example 1 BTG LATC, 7, 1 ; Toggle the value of bit 7 ; in the LATC Register Before Instruction LATC = 0x0A After Instruction LATC = 0x8A ; 0000 1010 ; 1000 1010 Example 2 BTG INDF0, 3, 1 ; Toggle the value of bit 3 ; in the register pointed to ; by the value in the FSR0 ; (FSR0H:FSR0L) Register Before Instruction FSR0 = 0xAC2 Contents of Address (FSR0)= 0x20 After Instruction FSR0 = 0xAC2 Contents of Address (FSR0)= 0x28 ; 0010 0000 ; 0010 1000 39500 18C Reference Manual.book Page 47 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-48  2000 Microchip Technology Inc. BZ Branch if Zero Syntax: [ label ] BZ n Operands: -128 ≤ f ≤ 127 Operation: If zero bit is ’1’ (PC + 2) + 2n → PC Status Affected: None Encoding: 1110 0000 nnnn nnnn Description: If the Zero bit is ’1’, then the program will branch. The 2’s complement number ’2n’ (the offset) is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be PC+2+2n. This instruction is then a two-cycle instruction. Words: 1 Cycles: 1 (2) Q Cycle Activity: If Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data Write to PC No operation No operation No operation No operation If No Branch Q1 Q2 Q3 Q4 Decode Read literal 'n' Process data No operation Example 1 HERE ZERO Z_CODE BZ • • GOTO • • Z_CODE MORE_CODE ; If zero bit is clear ; execute this code. ; ; ; else if zero bit is set ; this code will execute Case 1: Before Instruction PC = address HERE Z =0 After Instruction PC = address ZERO Case 2: Before Instruction PC = address HERE Z =1 After Instruction PC = address Z_CODE 39500 18C Reference Manual.book Page 48 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-49 Section 31. Instruction Set Instruction Set 31 Example 2 HERE NZERO PLUS0 PLUS1 PLUS2 PLUS3 PLUS4 PLUS5 PLUS6 BZ GOTO • • • • • • • $ + OFFSET PROCESS_CODE ; If zero bit is set, ; branch to HERE + OFFSET Case 1: Before Instruction PC = address HERE Z =0 After Instruction PC = address NZERO Case 2: Before Instruction PC = address HERE Z =1 After Instruction PC = address HERE + OFFSET Example 3 MIN6 MIN5 MIN4 MIN3 MIN2 MIN1 MIN0 HERE NZERO • • • • • • • BZ GOTO $ - OFFSET PROCESS_CODE ; If zero bit is set, ; branch to HERE - OFFSET Case 1: Before Instruction PC = address HERE Z =0 After Instruction PC = address NZERO Case 2: Before Instruction PC = address HERE Z =1 After Instruction PC = address HERE - OFFSET Note: Assembler will convert the specified address label into the offset to be used. 39500 18C Reference Manual.book Page 49 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-50  2000 Microchip Technology Inc. CALL Call Subroutine Syntax: [ label ] CALL k, s Operands: 0 ≤ k ≤ 1048575 s ∈ [0,1] Operation: (PC)+ 4 → TOS, k → PC<20:1>, 0 → PC<0>, if s = 1 (WREG) → WREGS, (STATUS) → STATUSS, (BSR) → BSRS Status Affected: None Encoding: 1st word (k<7:0>) 2nd word (k<19:8>) 1110 1111 110s k19kkk k7kkk kkkk kkkk0 kkkk8 Description: Subroutine call of entire 2M byte memory range. First, return address (PC+ 4) is pushed onto the return stack (20-bits wide). If ’s’ = 1, the WREG, STATUS and BSR Registers are also pushed into their respective Shadow Registers, WREGS, STATUSS and BSRS. If 's' = 0, no update occurs. Then the 20-bit value ’k’ is loaded into PC<20:1>. CALL is a two-cycle instruction. Words: 2 Cycles: 2 Q Cycle Activity: 1st cycle: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data No operation 2nd cycle: Q1 Q2 Q3 Q4 No operation No operation No operation No operation 39500 18C Reference Manual.book Page 50 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-51 Section 31. Instruction Set Instruction Set 31 Example 1 HERE CALL THERE, 1 ; Call subroutine THERE. ; This is a fast call so ; the BSR, WREG, and STATUS ; Registers are forced onto ; the Fast Register Stack Before Instruction PC = Address HERE After Instruction TOS = Address HERE+4 PC = Address THERE WREGS = WREG BSRS = BSR STATUSS = STATUS Example 2 HERE CALL THERE, 0 ; Call subroutine THERE. ; This is NOT a fast call Before Instruction PC = Address HERE WREGS = 0x45 BSRS = 0x29 STATUSS = 0x01 After Instruction TOS = Address HERE+4 PC = Address THERE WREGS = 0x45 (unchanged) BSRS = 0x29 (unchanged) STATUSS = 0x01 (unchanged) 39500 18C Reference Manual.book Page 51 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-52  2000 Microchip Technology Inc. CLRF Clear f Syntax: [ label ] CLRF f, a Operands: 0 ≤ f ≤ 255 a ∈ [0,1] Operation: 00h → f 1 → Z Status Affected: Z Encoding: 0110 101a ffff ffff Description: The contents of Register 'f' are cleared and the Z bit is set. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write Register 'f' Example 1 CLRF FLAG_REG, 1 ; Clear Register FLAG_REG Before Instruction FLAG_REG = 0x5A Z =x After Instruction FLAG_REG = 0x00 Z =1 Example 2 CLRF INDF0, 1 ; Clear the register pointed ; to by the FSR0 ; (FSR0H:FSR0L) Register Before Instruction FSR0 = 0x0C2 Contents of Address (FSR0) = 0xAA Z =x After Instruction FSR0 = 0x0C2 Contents of Address (FSR0) = 0x00 Z =1 39500 18C Reference Manual.book Page 52 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-53 Section 31. Instruction Set Instruction Set 31 CLRWDT Clear Watchdog Timer Syntax: [ label ] CLRWDT Operands: None Operation: 00h → WDT 0 → WDT prescaler count, 1 → TO 1 → PD Status Affected: TO, PD Encoding: 0000 0000 0000 0100 Description: CLRWDT instruction clears the Watchdog Timer. It also clears the postscaler count of the WDT. Status bits TO and PD are set. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode No operation Process data Clear WDT Counter Example CLRWDT ; Clear the Watchdog ; Timer count value Before Instruction WDT counter = x WDT postscaler count = 0 WDT postscaler = 1:128 TO = x PD = x After Instruction WDT counter = 0x00 WDT postscaler count = 0 WDT postscaler = 1:128 TO = 1 PD = 1 Note: The CLRWDT instruction does not affect the assignment of the WDT postscaler. 39500 18C Reference Manual.book Page 53 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-54  2000 Microchip Technology Inc. COMF Complement f Syntax: [ label ] COMF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (f) → destination Status Affected: Z, N Encoding: 0001 11da ffff ffff Description: The contents of Register 'f' are 1’s complemented. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 COMF REG1, 0, 1 ; Complement the value in ; Register REG1 and place the ; result in the WREG Register Case 1: Before Instruction REG1 = 0x13 Z, N = x After Instruction REG1 = 0x13 WREG = 0xEC Z =0 N =1 ; 0001 0011 ; 1110 1100 Case 2: Before Instruction REG1 = 0xFF Z, N = x After Instruction REG1 = 0xFF WREG = 0x00 Z =1 N =0 ; 1111 1111 ; 0000 0000 Case 3: Before Instruction REG1 = 0x00 Z, N = x After Instruction REG1 = 0x00 WREG = 0xFF Z =0 N =1 ; 0000 0000 ; 1111 1111 39500 18C Reference Manual.book Page 54 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-55 Section 31. Instruction Set Instruction Set 31 Example 2 COMF INDF0, 1, 1 ; Complement the value in the ; register pointed to by the ; FSR0 (FSR0H:FSR0L) ; Register, placing the ; result in that register Before Instruction FSR0 = 0xFC2 Contents of Address (FSR0) = 0xAA Z, N = x After Instruction FSR0 = 0xFC2 Contents of Address (FSR0) = 0x55 Z =0 N =0 ; 1010 1010 ; 0101 0101 Example 3 COMF REG1, 1, 1 ; Complement the value in ; Register REG1 and place the ; result in Register REG1 Before Instruction REG1 = 0xFF Z, N = x After Instruction REG1 = 0x00 Z =1 N =0 ; 1111 1111 ; 0000 0000 39500 18C Reference Manual.book Page 55 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-56  2000 Microchip Technology Inc. CPFSEQ Compare f with WREG, Skip if Equal (f = WREG) Syntax: [ label ] CPFSEQ f, a Operands: 0 ≤ f ≤ 255 a ∈ [0,1] Operation: (f) - (WREG) skip if (f) = (WREG) Status Affected: None Encoding: 0110 001a ffff ffff Description: Compares the contents of Register 'f' to the contents of WREG Register by performing an unsigned subtraction. If 'f' = WREG then the fetched instruction is discarded and a NOP is executed instead, making this a two-cycle instruction. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data No operation If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by a two word instruction: Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation 39500 18C Reference Manual.book Page 56 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-57 Section 31. Instruction Set Instruction Set 31 Example HERE NEQUAL EQUAL CPFSEQ GOTO • • • FLAG, 1 PROCESS_CODE ; Compare the value in ; Register FLAG to the ; WREG Register and skip ; the next program memory ; location if they are ; equal Case 1: Before Instruction PC = address HERE FLAG = 0x5A WREG = 0x5A After Instruction PC = address EQUAL ; FLAG - WREG = 0x00 ; The two values were ; Equal Case 2: Before Instruction PC = address HERE FLAG = 0xA5 WREG = 0x5A After Instruction PC = address NEQUAL ; FLAG - WREG = 0x4B ; The two values were ; Not Equal 39500 18C Reference Manual.book Page 57 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-58  2000 Microchip Technology Inc. CPFSGT Compare f with WREG, Skip if Greater Than (f > WREG) Syntax: [ label ] CPFSGT f, a Operands: 0 ≤ f ≤ 255 a ∈ [0,1] Operation: (f) - (WREG) skip if (f) > (WREG); (unsigned comparison) Status Affected: None Encoding: 0110 010a ffff ffff Description: Compares the contents of data memory location 'f' to the contents of WREG Register by performing an unsigned subtraction. If 'f' > WREG then the fetched instruction is discarded and a NOP is executed instead, making this a two-cycle instruction. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data No operation If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by a two word instruction: Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation 39500 18C Reference Manual.book Page 58 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-59 Section 31. Instruction Set Instruction Set 31 Example HERE NGT GT CPFSGT GOTO • • • FLAG, 1 PROCESS_CODE ; Compare the value in ; Register FLAG to the ; WREG Register and skip ; the next program memory ; location if ; FLAG > WREG Case 1: Before Instruction PC = address HERE FLAG = 0x5A WREG = 0x5A After Instruction PC = address NGT ; FLAG - WREG = 0x00 ; The two values were ; Equal (Not Greater Than) Case 2: Before Instruction PC = address HERE FLAG = 0xA5 WREG = 0x5A After Instruction PC = address GT ; FLAG - WREG = 0x4B ; FLAG > WREG, Skip ; the next instruction 39500 18C Reference Manual.book Page 59 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-60  2000 Microchip Technology Inc. CPFSLT Compare f with WREG, Skip if Less Than (f < WREG) Syntax: [ label ] CPFSLT f, a Operands: 0 ≤ f ≤ 255 a ∈ [0,1] Operation: (f) - (WREG); (unsigned comparison) skip if (f) < (WREG) Status Affected: None Encoding: 0110 000a ffff ffff Description: Compares the contents of data memory location 'f' to the contents of WREG Register by performing an unsigned subtraction. If 'f' < WREG then the fetched instruction is discarded and an NOP is executed instead making this a two-cycle instruction. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data No operation If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by a two word instruction: Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation 39500 18C Reference Manual.book Page 60 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-61 Section 31. Instruction Set Instruction Set 31 Example HERE NLT LT CPFSLT GOTO • • • FLAG, 1 PROCESS_CODE ; Compare the value in ; Register FLAG to the ; WREG Register and skip ; the next program memory ; location if ; FLAG < WREG Case 1: Before Instruction PC = address HERE FLAG = 0x5A WREG = 0x5A After Instruction PC = address NLT ; FLAG - WREG = 0x00 ; the two values were ; Equal (Not less than) Case 2: Before Instruction PC = address HERE FLAG = 0x5A WREG = 0xA5 After Instruction PC = address LT ; FLAG - WREG = 0x4B ; FLAG < WREG, Skip ; the next instruction 39500 18C Reference Manual.book Page 61 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-62  2000 Microchip Technology Inc. DAW Decimal Adjust WREG Register Syntax: [ label ] DAW Operands: None Operation: If [WREG<3:0> >9] or [DC = 1] then (WREG<3:0>) + 6 → WREG<3:0>; else (WREG<3:0>) → WREG<3:0>; If [WREG<7:4> >9] or [C = 1] then (WREG<7:4>) + 6 → WREG<7:4>; else (WREG<7:4>) → WREG<7:4>; Status Affected: C Encoding: 0000 0000 0000 0111 Description: DAW adjusts the eight bit value in WREG resulting from the earlier addition of two variables (each in packed BCD format) and produces a correct packed BCD result. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register REG Process data Write to REG 39500 18C Reference Manual.book Page 62 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-63 Section 31. Instruction Set Instruction Set 31 Example HERE DAW ; Decimal Adjust WREG Case 1: Before Instruction WREG = 0x0F C =x After Instruction WREG = 0x15 C =0 ; 0x0F is 15 decimal Case 2: Before Instruction WREG = 0x68 C =x After Instruction PC = 0x04 C =1 ; 0x68 is 104 decimal ; Carry to indicate ; decimal rollover Case 3: Before Instruction WREG = C6 C =x After Instruction PC = 98 C =1 ; ; 0xC6 is 198 decimal ; Carry to indicate ; decimal rollover 39500 18C Reference Manual.book Page 63 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-64  2000 Microchip Technology Inc. DECF Decrement f Syntax: [ label ] DECF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (f) - 1 → destination Status Affected: C, DC, Z, OV, N Encoding: 0000 01da ffff ffff Description: Decrement the contents of Register 'f'. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 DECF CNT, 1, 1 ; Decrement Register CNT Before Instruction CNT = 0x01 C, DC, OV, N = x Z =0 After Instruction CNT = 0x00 C =0 DC = 0 Z =1 OV = 0 N =0 39500 18C Reference Manual.book Page 64 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-65 Section 31. Instruction Set Instruction Set 31 Example 2 DECF INDF0, 1, 1 ; Decrement the register ; pointed to by the FSR ; (FSR0H:FSR0L) Register Before Instruction FSR0 = 0x1C2 Contents of Address (FSR0) = 0x01 C, DC, OV, N = x Z =0 After Instruction FSR0 = 0x1C2 Contents of Address (FSR0) = 0x00 C =0 DC = 0 Z =1 OV = 0 N =0 Example 3 DECF CNT, 0, 1 ; Decrement Register CNT ; WREG is destination Before Instruction CNT = 0x10 WREG = x Z =0 After Instruction CNT = 0x10 WREG = 0x0F C =0 DC = 1 Z =0 OV = 0 N =0 39500 18C Reference Manual.book Page 65 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-66  2000 Microchip Technology Inc. DECFSZ Decrement f, Skip if 0 Syntax: [ label ] DECFSZ f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1]] a ∈ [0,1] Operation: (f) - 1 → destination; skip if result = 0 Status Affected: None Encoding: 0010 11da ffff ffff Description: The contents of Register 'f' are decremented. If the result is 0, then the next instruction (fetched during the current instruction execution) is discarded and a NOP is executed instead, making this a 2 cycle instruction. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by 2 word instruction Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation 39500 18C Reference Manual.book Page 66 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-67 Section 31. Instruction Set Instruction Set 31 Example HERE CONTINUE DECFSZ GOTO • • CNT, 1, 1 LOOP ; Decrement Register CNT, ; if CNT then equals 0 ; skip the next ; instruction Case 1: Before Instruction PC = address HERE CNT = 0x01 After Instruction CNT = 0x00 PC = address CONTINUE Case 2: Before Instruction PC = address HERE CNT = 0x02 After Instruction CNT = 0x01 PC = address HERE + 2 39500 18C Reference Manual.book Page 67 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-68  2000 Microchip Technology Inc. DCFSNZ Decrement f, Skip if Not 0 Syntax: [ label ] DCFSNZ f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1]] a ∈ [0,1] Operation: (f) - 1 → destination; skip if result ≠ 0 Status Affected: None Encoding: 0100 11da ffff ffff Description: The contents of Register 'f' are decremented. If the result is not 0, then the next instruction (fetched during the current instruction execution) is discarded and a NOP is executed instead, making this a 2-cycle instruction. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by 2 word instruction Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation 39500 18C Reference Manual.book Page 68 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-69 Section 31. Instruction Set Instruction Set 31 Example HERE CONTINUE DCFSNZ GOTO • • CNT, 1, 1 LOOP ; Decrement Register CNT, ; if CNT does not equal 0 ; skip the next instruction Case 1: Before Instruction PC = address HERE CNT = 0x01 After Instruction CNT = 0x00 PC = address HERE + 2 Case 2: Before Instruction PC = address HERE CNT = 0x02 After Instruction CNT = 0x01 PC = address CONTINUE 39500 18C Reference Manual.book Page 69 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-70  2000 Microchip Technology Inc. GOTO Unconditional Branch Syntax: [ label ] GOTO k Operands: 0 ≤ k ≤ 1048575 Operation: k → PC<20:1> 0 → PC<0>, Status Affected: None Encoding: 1st word (k<7:0>) 2nd word (k<19:8>) 1110 1111 1111 k19kkk k7kkk kkkk kkkk0 kkkk8 Description: GOTO allows an unconditional branch anywhere within the entire 2M byte memory range. The 20-bit immediate value ’k’ is loaded into PC<20:1>. GOTO is always a two-cycle instruction. Words: 2 Cycles: 2 Q Cycle Activity: 1st cycle: Q1 Q2 Q3 Q4 Decode Read literal 'k'<7:0> Process data No operation 2nd cycle: Q1 Q2 Q3 Q4 No operation No operation No operation No operation 39500 18C Reference Manual.book Page 70 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-71 Section 31. Instruction Set Instruction Set 31 Example 1 HERE GOTO THERE ; Goto address THERE After Instruction PC = Address THERE Example 2 HERE GOTO $-2 ; GOTO address HERE - 2 After Instruction PC = Address HERE -2 Example 3 HERE GOTO $ ; GOTO address HERE ; (infinite loop) After Instruction PC = Address HERE Example 4 HERE GOTO HERE ; GOTO address HERE ; (infinite loop) After Instruction PC = Address HERE 39500 18C Reference Manual.book Page 71 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-72  2000 Microchip Technology Inc. INCF Increment f Syntax: [ label ] INCF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (f) + 1 → destination Status Affected: C, DC, Z, OV, N Encoding: 0010 10da ffff ffff Description: The contents of Register 'f' are incremented. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 INCF CNT,1, 1 ; Increment Register CNT Before Instruction CNT = 0xFF C, DC, Z, OV, N = x After Instruction CNT = 0x00 C =1 DC = 1 Z =1 OV = 0 N =0 ; 1111 1111 ; 0000 0000 39500 18C Reference Manual.book Page 72 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-73 Section 31. Instruction Set Instruction Set 31 Example 2 INCF INDF0, 1, 1 ; Increment Register ; indirectly ; (FSR0 (FSR0H:FSR0L) points ; to address to increment) Before Instruction FSR0 = 0x0C2 Contents of Address (FSR0) = 0xFF C, DC, Z, OV, N = x After Instruction FSR0 = 0x0C2 Contents of Address (FSR0) = 0x00 C =1 DC = 1 Z =1 OV = 0 N =0 ; 1111 1111 ; 0000 0000 Example 3 INCF CNT, 0, 1 ; Increment Register CNT ; place result in WREG Before Instruction CNT = 0x10 WREG = x C, DC, OV, N = x Z =0 After Instruction CNT = 0x10 WREG = 0x11 C =0 DC = 0 Z =0 OV = 0 N =0 ; 0001 0000 ; 0001 0001 39500 18C Reference Manual.book Page 73 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-74  2000 Microchip Technology Inc. INCFSZ Increment f, Skip if 0 Syntax: [ label ] INCFSZ f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (f) + 1 → destination, skip if result = 0 Status Affected: None Encoding: 0011 11da ffff ffff Description: The contents of Register 'f' are incremented. If the result is 0, then the next instruction (fetched during the current instruction execution) is discarded and a NOP is executed instead, making this a 2-cycle instruction. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by 2 word instruction Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation 39500 18C Reference Manual.book Page 74 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-75 Section 31. Instruction Set Instruction Set 31 Example 1 HERE NZERO ZERO INCFSZ GOTO • • CNT, 1, 1 LOOP ; Increment Register CNT, ; if CNT then equals 0 ; skip the next ; instruction Case 1: Before Instruction PC = address HERE CNT = 0xFF After Instruction CNT = 0x00 PC = address ZERO Case 2: Before Instruction PC = address HERE CNT = 0x00 After Instruction CNT = 0x01 PC = address NZERO Example 2 HERE NZERO ZERO INCFSZ GOTO • • • CNT, 1, 0 LOOP ; Increment Register CNT, ; if CNT equals 0 ; skip the next ; instruction Case 1: Before Instruction PC = address HERE CNT = 0xFF ; In access bank After Instruction CNT = 0x00 PC = address ZERO Case 2: Before Instruction PC = address HERE CNT = 0x00 ; In access bank After Instruction CNT = 0x01 PC = address NZERO 39500 18C Reference Manual.book Page 75 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-76  2000 Microchip Technology Inc. INFSNZ Increment f, Skip if Not 0 Syntax: [ label ] INFSNZ f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (f) + 1 → destination, skip if result ≠ 0 Status Affected: None Encoding: 0100 10da ffff ffff Description: The contents of Register 'f' are incremented. If the result is not 0, then the next instruction (fetched during the current instruction execution) is discarded and a NOP is executed instead, making this a 2-cycle instruction. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by 2 word instruction Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation 39500 18C Reference Manual.book Page 76 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-77 Section 31. Instruction Set Instruction Set 31 Example 1 HERE ZERO NZERO INFSNZ GOTO • • CNT, 1, 1 LOOP ; Increment Register CNT, ; if CNT does not equal 0 ; skip the next instruction Case 1: Before Instruction PC = address HERE CNT = 0xFF After Instruction CNT = 0x00 PC = address ZERO Case 2: Before Instruction PC = address HERE CNT = 0x00 After Instruction CNT = 0x01 PC = address NZERO Example 2 HERE ZERO NZERO INFSNZ GOTO • • • CNT, 1, 0 LOOP ; Increment Register CNT, ; if CNT does not equal 0 ; skip the next instruction Case 1: Before Instruction PC = address HERE CNT = 0xFF ; In access bank After Instruction CNT = 0x00 PC = address ZERO Case 2: Before Instruction PC = address HERE CNT = 0x00 ; In access bank After Instruction CNT = 0x01 PC = address NZERO 39500 18C Reference Manual.book Page 77 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-78  2000 Microchip Technology Inc. IORLW Inclusive OR Literal with WREG Syntax: [ label ] IORLW k Operands: 0 ≤ k ≤ 255 Operation: (WREG).OR. k → WREG Status Affected: Z, N Encoding: 0000 1001 kkkk kkkk Description: The contents of the WREG Register is OR’d with the eight bit literal 'k'. The result is placed in the WREG Register. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data Write to WREG Register Example 1 IORLW 0x35 ; bit wise OR 35h with the ; WREG Register Before Instruction WREG = 0x9A Z, N = x After Instruction WREG = 0xBF Z =0 N =1 ; 0011 0101 (35h) ; 1001 1010 ; 1011 1111 Example 2 IORLW MYREG ; bit wise OR the value of ; the address of Register ; MYREG with the WREG ; Register Before Instruction WREG = 0x9A Address of MYREG † = 0x37 † MYREG is a symbol for a data memory location Z, N = x After Instruction WREG = 0xBF Z =0 N =1 ; ; 1001 1010 ; ; 0011 0111 ; 1011 1111 39500 18C Reference Manual.book Page 78 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-79 Section 31. Instruction Set Instruction Set 31 Example 3 IORLW HIGH (LU_TABLE) ; bit wise OR the value of ; the high byte of address ; LU_TABLE with the WREG ; Register Before Instruction WREG = 0x9A Address of LU_TABLE † = 0x9375 † LU_TABLE is a label for an address in program memory Z, N = x After Instruction WREG = 0x9B Z =0 N =1 ; 1001 1010 ; 1001 0011 (93h) ; 1001 1011 Example 4 IORLW 0x00 ; bit wise OR 00h with the ; WREG Register Before Instruction WREG = 0x00 Z, N = x After Instruction WREG = 0x00 Z =1 N =0 ; 0000 0000 (literal) ; 0000 0000 ; 0000 0000 39500 18C Reference Manual.book Page 79 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-80  2000 Microchip Technology Inc. IORWF Inclusive OR WREG with f Syntax: [ label ] IORWF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (WREG).OR. (f) → destination Status Affected: Z, N Encoding: 0001 00da ffff ffff Description: Inclusive OR the WREG Register with the contents of Register 'f'. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 IORWF INDF0, 1, 1 ; Comment Before Instruction WREG = 0x17 FSR0 = 0xDC2 Contents of Address (FSR0) = 0x30 Z, N = x After Instruction WREG = 0x17 FSR0 = 0xDC2 Contents of Address (FSR0) = 0x37 Z =0 N =0 ; 0001 0111 ; 0011 0000 ; 0011 0111 39500 18C Reference Manual.book Page 80 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-81 Section 31. Instruction Set Instruction Set 31 Example 2 IORWF RESULT, 1, 1 ; bit wise OR the WREG ; Register with the ; Register RESULT. Case 1: Before Instruction RESULT = 0x13 WREG = 0x91 Z, N = x After Instruction RESULT = 0x93 WREG = 0x91 Z =0 N =1 ; 0001 0011 ; 1001 0001 ; 1001 0011 Case 2: Before Instruction RESULT = 0x00 WREG = 0x00 Z, N = x After Instruction RESULT = 0x00 WREG = 0x00 Z =1 N =0 ; 0000 0000 ; 0000 0000 ; 0000 0000 Example 3 IORWF RESULT, 1, 0 ; bit wise OR the WREG ; Register with the ; register in the Access ; bank at address of RESULT ; Register. Case 1: Before Instruction RESULT = 0x13 (RESULT) in access bank = 0xC8 WREG = 0x91 Z, N = x After Instruction RESULT = 0x13 (RESULT) in access bank = 0xD9 WREG = 0x91 Z =0 N =1 ; 1100 1000 ; 1001 0001 ; 1101 1001 Case 2: Before Instruction RESULT = 0x00 (RESULT) in access bank = 0x11 WREG = 0x00 Z, N = x After Instruction RESULT = 0x00 (RESULT) in access bank = 0x11 WREG = 0x00 Z =0 N =0 ; 0001 0001 ; 0000 0000 ; 0001 0001 39500 18C Reference Manual.book Page 81 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-82  2000 Microchip Technology Inc. LFSR Load 12-bit Literal to FSR Syntax: [ label ] LFSR f, k Operands: 0 ≤ f ≤ 2 0 ≤ k ≤ 4095 Operation: k → FSRx Status Affected: None Encoding: 1st word 2nd word 1110 1111 1110 0000 00ff k7kkk k11kkk8 kkkk0 Description: The 12-bit literal 'k' is loaded into the File Select Register (FSR Register) pointed to by 'f': f = 00 → FSR0 f = 01 → FSR1 f = 10 → FSR2 f = 11 → Reserved Words: 2 Cycles: 2 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal k11:k8 Process data Write to FSRxH Register k11:k8 Decode Read literal k7:k0 Process data Write to FSRxL Register k7:k0 Example 1 LFSR 2, 0x123 ; Load the 12-bit FSR2 with ; 123h Before Instruction FSR0H = 0x05 FSR0L = 0xA5 FSR1H = 0x05 FSR1L = 0xA5 FSR2H = 0x05 FSR2L = 0xA5 After Instruction FSR0H = 0x05 FSR0L = 0xA5 FSR1H = 0x05 FSR1L = 0xA5 FSR2H = 0x01 FSR2L = 0x23 39500 18C Reference Manual.book Page 82 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-83 Section 31. Instruction Set Instruction Set 31 Example 2 LFSR 0, 0xFE3 ; Load the 12-bit FSR0 with ; FE3h Before Instruction FSR0H = 0x05 FSR0L = 0xA5 FSR1H = 0x05 FSR1L = 0xA5 FSR2H = 0x05 FSR2L = 0xA5 After Instruction FSR0H = 0x0F FSR0L = 0xE3 FSR1H = 0x05 FSR1L = 0xA5 FSR2H = 0x05 FSR2L = 0xA5 Example 3 LFSR 1, 0xFE3 ; Load the 12-bit FSR1 with ; FE3h Before Instruction FSR0H = 0x05 FSR0L = 0xA5 FSR1H = 0x05 FSR1L = 0xA5 FSR2H = 0x05 FSR2L = 0xA5 After Instruction FSR0H = 0x05 FSR0L = 0xA5 FSR1H = 0x0F FSR1L = 0xE3 FSR2H = 0x05 FSR2L = 0xA5 39500 18C Reference Manual.book Page 83 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-84  2000 Microchip Technology Inc. MOVF Move f Syntax: [ label ] MOVF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: f → destination Status Affected: Z, N Encoding: 0101 00da ffff ffff Description: The contents of Register 'f' is moved to a destination dependent upon the status of the ’d’ and ’a’ bits. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data Write to WREG Register Example 1 MOVF MYREG, 0, 1 ; Copy the contents of ; Register MYREG to the WREG ; Register Before Instruction MYREG = 0x22 WREG = 0xFF Z, N = x After Instruction MYREG = 0x22 WREG = 0x22 Z =0 N =0 Example 2 MOVF MYREG, 1, 1 ; Copy the contents of ; Register MYREG to itself ; (affects the status bits) Before Instruction MYREG = 0x00 WREG = 0x10 Z, N = x After Instruction MYREG = 0x00 WREG = 0x10 Z =1 N =0 39500 18C Reference Manual.book Page 84 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-85 Section 31. Instruction Set Instruction Set 31 Example 3 MOVF MYREG, 1, 0 ; Copy the contents of ; Register MYREG in the ; access bank to itself ; (affects the status bits) Case 1: Before Instruction MYREG = 0x00 WREG = 0x10 Z, N = x After Instruction MYREG = 0x00 WREG = 0x10 Z =1 N =0 ; In access bank ; In access bank Case 2: Before Instruction MYREG = 0x80 WREG = 0x10 Z, N = x After Instruction MYREG = 0x80 WREG = 0x10 Z =0 N =1 ; In access bank ; In access bank 39500 18C Reference Manual.book Page 85 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-86  2000 Microchip Technology Inc. MOVFF Move f to f Syntax: [ label ] MOVFF fs, fd Operands: 0 ≤ fs ≤ 4095 0 ≤ fd ≤ 4095 Operation: (fs) → fd Status Affected: None Encoding: 1st word (source) 2nd word (destination) 1100 1111 ffff ffff ffff ffff ffff ffff Description: The contents of Source Register 'f s' are moved to Destination Register 'fd'. Location of source 'fs' can be anywhere in the 4096 byte data space (000h to FFFh), and location of destination 'fd' can also be anywhere from 000h to FFFh. MOVFF is particularly useful for transferring a data memory location to a Peripheral Register (such as the transmit buffer or an I/O port) without affecting the WREG Register. Note: The MOVFF instruction cannot use the PCL, TOSU, TOSH, and TOSL as the Destination Register Words: 2 Cycles: 2 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Source Register f Process data No operation Decode No operation No operation Write to destination Register f Example 1 MOVFF REG1, REG2 ; Copy the contents of ; Register REG1 to Register ; REG2 Before Instruction REG1 = 0x33 REG2 = 0x11 After Instruction REG1 = 0x33 REG2 = 0x33 Example 2 MOVFF REG2, REG1 ; Copy the contents of ; Register REG2 to Register ; REG1 Before Instruction REG1 = 0x33 REG2 = 0x11 After Instruction REG1 = 0x11 REG2 = 0x11 39500 18C Reference Manual.book Page 86 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-87 Section 31. Instruction Set Instruction Set 31 MOVLB Move Literal to low nibble in BSR Syntax: [ label ] MOVLB k Operands: 0 ≤ k ≤ 15 Operation: k → BSR<3:0> Status Affected: None Encoding: 0000 0001 0000 kkkk Description: The 4-bit literal 'k' is loaded into the Bank Select Register (BSR). Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data Write literal ’k’ to BSR Example 1 MOVLB 5 ; Modify Least Significant ; nibble of BSR Register ; to value 5 Before Instruction BSR = 0x02 After Instruction BSR = 0x05 Example 2 MOVLB 9 ; Modify Least Significant ; nibble of BSR Register ; to value 9 Before Instruction BSR = 0x0F After Instruction BSR = 0x09 39500 18C Reference Manual.book Page 87 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-88  2000 Microchip Technology Inc. MOVLW Move Literal to WREG Syntax: [ label ] MOVLW k Operands: 0 ≤ k ≤ 255 Operation: k → WREG Status Affected: None Encoding: 0000 1110 kkkk kkkk Description: The eight bit literal 'k' is loaded into WREG Register. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data Write to WREG Register Example 1 MOVLW 0x5A ; Load the WREG Register ; with the value 5Ah Before Instruction WREG = x After Instruction WREG = 0x5A Example 2 MOVLW MYREG ; Load the WREG Register ; with the value of the ; address of MYREG Before Instruction WREG = 0x10 Address of MYREG † = 0x37 † MYREG is a symbol for a data memory location After Instruction WREG = 0x37 Example 3 MOVLW HIGH (LU_TABLE) ; Load the WREG Register ; with the value of the high ; byte of address LU_TABLE Before Instruction WREG = 0x10 Address of LU_TABLE † = 0x9375 † LU_TABLE is a label for an address in program memory After Instruction WREG = 0x93 39500 18C Reference Manual.book Page 88 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-89 Section 31. Instruction Set Instruction Set 31 MOVWF Move WREG to f Syntax: [ label ] MOVWF f, a Operands: 0 ≤ f ≤ 255 a ∈ [0,1] Operation: (WREG) → f Status Affected: None Encoding: 0110 111a ffff ffff Description: Move data from WREG Register to Register 'f'. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read WREG Register Process data Write Register 'f' Example 1 MOVWF OPTION_REG, 1; Copy the value in the WREG ; Register to the ; OPTION_REG Register Before Instruction OPTION_REG = 0xFF WREG = 0x4F After Instruction OPTION_REG = 0x4F WREG = 0x4F Example 2 MOVWF INDF0, 1 ; Copy the value in the WREG ; Register to the ; FSR0 (FSR0H:FSR0L) ; Register Before Instruction WREG = 0x17 FSR0 = 0x5C2 Contents of Address (FSR0) = 0x00 After Instruction WREG = 0x17 FSR0 = 0x5C2 Contents of Address (FSR0) = 0x17 39500 18C Reference Manual.book Page 89 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-90  2000 Microchip Technology Inc. MULLW Multiply Literal with WREG Syntax: [ label ] MULLW k Operands: 0 ≤ k ≤ 255 Operation: (WREG) x k → PRODH:PRODL Status Affected: None Encoding: 0000 1101 kkkk kkkk Description: An unsigned multiplication is carried out between the contents of WREG and the 8-bit literal 'k'. The 16-bit result is placed in PRODH:PRODL Register Pair. PRODH contains the high byte. WREG is unchanged. None of the status flags are affected. Neither an overflow nor carry is possible in this operation. A zero result is possible but not detected. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data Write Registers PRODH: PRODL Example 1 MULLW 0xC4 ; Multiply the WREG Register ; with the constant value ; C4h Before Instruction WREG = 0xE2 PRODH = x PRODL = x After Instruction WREG = 0xE2 PRODH = 0xAD PRODL = 0x08 Example 2 MULLW FACTOR ; Multiply the WREG Register ; with the constant value ; FACTOR Before Instruction FACTOR = 0xC4 WREG = 0xE2 PRODH = x PRODL = x After Instruction WREG = 0xE2 PRODH = 0xAD PRODL = 0x08 39500 18C Reference Manual.book Page 90 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-91 Section 31. Instruction Set Instruction Set 31 MULWF Multiply WREG with f Syntax: [ label ] MULWF f, a Operands: 0 ≤ f ≤ 255 a ∈ [0,1] Operation: (WREG) x (f) → PRODH:PRODL Status Affected: None Encoding: 0000 001a ffff ffff Description: An unsigned multiplication is carried out between the contents of WREG and the value in Register File Location 'f'. The 16-bit result is placed in the PRODH:PRODL Register Pair. PRODH contains the high byte. Both WREG and 'f' are unchanged. None of the status flags are affected. Neither an overflow nor carry is possible in this operation. A zero result is possible but not detected. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write Registers PRODH: PRODL Example MULWF MYREG, 1 ; Multiple the WREG ; Register with the value ; in MYREG Register Before Instruction WREG = 0xE2 MYREG = 0xB5 PRODH = x PRODL = x After Instruction WREG = 0xE2 MYREG = 0xB5 PRODH = 0x9F PRODL = 0xCA 39500 18C Reference Manual.book Page 91 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-92  2000 Microchip Technology Inc. NEGF Negate f Syntax: [ label ] NEGF f, a Operands: 0 ≤ f ≤ 255 a ∈ [0,1] Operation: ( f )+1 → (f) Status Affected: C, DC, Z, OV, N Encoding: 0110 110a ffff ffff Description: Location ’f’ is negated using two’s complement. The result is placed in the data memory location 'f'. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write Register ’f’ Example 1 NEGF MYREG, 1 ; 2’s complement the value in ; MYREG Case 1: Before Instruction MYREG = 0x3A C, DC, Z, OV, N = x After Instruction MYREG = 0xC6 C =0 DC = 0 Z =0 OV = 0 N =1 ; 0011 1010 ; 1100 0110 Case 2: Before Instruction MYREG = 0xB0 C, DC, Z, OV, N = x After Instruction MYREG = 0x50 C =0 DC = 1 Z =0 OV = 0 N =0 ; 1011 0000 ; 0101 0000 Case 3: Before Instruction MYREG = 0x00 C, DC, Z, OV, N = x After Instruction MYREG = 0x00 C =1 DC = 1 Z =1 OV = 0 N =0 ; 0000 0000 ; 0000 0000 39500 18C Reference Manual.book Page 92 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-93 Section 31. Instruction Set Instruction Set 31 NOP No Operation Syntax: [ label ] NOP Operands: None Operation: No operation Status Affected: None Encoding: Default Used with 2 word instructions 0000 1111 0000 xxxx 0000 xxxx 0000 xxxx Description: No operation. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode No operation No operation No operation Example HERE NOP ; This instruction cycle ; does nothing ; (No Operation) Before Instruction PC = address HERE After Instruction PC = address HERE + 2 39500 18C Reference Manual.book Page 93 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-94  2000 Microchip Technology Inc. POP POP Top of Return Stack Syntax: [ label ] POP Operands: None Operation: (TOS) → bit bucket Status Affected: None Encoding: 0000 0000 0000 0110 Description: The Top of Stack (TOS) value is pulled off the return stack and is discarded. The TOS value then becomes the previous value that was pushed onto the return stack. This instruction is provided to enable the user to manage the return stack to incorporate a software stack. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode No operation No operation POP TOS value Example HERE POP ; Modify the Top of Stack ; (TOS). The TOS points to ; what was one level down Before Instruction TOS = 0x0031A2 Stack (1 level down) = 0x014332 After Instruction TOS = 0x014332 PC = HERE + 2 39500 18C Reference Manual.book Page 94 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-95 Section 31. Instruction Set Instruction Set 31 PUSH PUSH Top of Return Stack Syntax: [ label ] PUSH Operands: None Operation: PC → (TOS) Status Affected: None Encoding: 0000 0000 0000 0101 Description: The previous Top of Stack (TOS) value is pushed down on the stack. The PC is pushed onto the top of the return stack. This instruction is provided to enable the user to manage the return stack to incorporate a software stack. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode PUSH PC onto return stack No operation No operation Example HERE PUSH ; PUSH current Program ; Counter value onto the ; hardware stack Before Instruction PC = 0x000124 TOS = 0x00345A After Instruction PC = 0x000126 TOS = 0x000124 Stack (1 level down) = 0x00345A 39500 18C Reference Manual.book Page 95 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-96  2000 Microchip Technology Inc. RCALL Relative Call Syntax: [ label ] RCALL n Operands: -1024 ≤ n ≤ 1023 Operation: (PC + 2) → TOS, (PC + 2) + 2n → PC Status Affected: None Encoding: 1101 1nnn nnnn nnnn Description: Subroutine call with a jump up to 1K from the current location. First, the return address (PC+2) is pushed onto the stack. Then the 2’s complement number ’2n’ is added to the PC. Since the PC will have incremented to fetch the next instruction, the new address will be PC+2+2n. This instruction is a two-cycle instruction. Words: 1 Cycles: 2 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal ’n’, Push PC to stack Process Data Write to PC No operation No operation No operation No operation Example 1 HERE RCALL Sub1 ; Call a program memory ; location (Sub1) ; this location must be ; < 1024 locations forward or ; > 1025 locations backward Before Instruction PC = Address (HERE) TOS = 0x0031A2 After Instruction PC = Address (Sub1) TOS = Address (HERE + 2) Stack (1 level down) = 0x0031A2 Example 2 HERE PLUS0 PLUS1 PLUS2 PLUS3 PLUS4 PLUS5 PLUS6 RCALL • • • • • • • $ + OFFSET ; Call to HERE+OFFSET Before Instruction PC = address HERE After Instruction PC = address HERE + OFFSET 39500 18C Reference Manual.book Page 96 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-97 Section 31. Instruction Set Instruction Set 31 Example 3 MIN6 MIN5 MIN4 MIN3 MIN2 MIN1 MIN0 HERE NEXT • • • • • • • RCALL $ - OFFSET ; Call to HERE-OFFSET Before Instruction PC = address HERE After Instruction PC = address HERE - OFFSET 39500 18C Reference Manual.book Page 97 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-98  2000 Microchip Technology Inc. RESET Reset Device Syntax: [ label ] RESET Operands: None Operation: Force all registers and flag bits that are affected by a MCLR reset to their reset condition. Status Affected: All Encoding: 0000 0000 1111 1111 Description: This instruction provides a way to execute a software reset. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode No operation No operation Start reset 39500 18C Reference Manual.book Page 98 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-99 Section 31. Instruction Set Instruction Set 31 Example HERE RESET ; Do a software reset Before Instruction PC = address HERE C, DC, Z, OV, N = x After Instruction PC = 0x000000 SFRs = See reset section GPRs = u (unchanged) 39500 18C Reference Manual.book Page 99 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-100  2000 Microchip Technology Inc. RETFIE Return from Interrupt Syntax: [ label ] RETFIE s Operands: s ∈ [0,1] Operation: (TOS) → PC, if IPEN = 0 (compatibility mode) 1 → GIE if IPEN = 1 GIEH GEIL 1 11 → Invalid 1 01 → GIEL 0 11 → GIEH 0 01 → GIEH if s = 1 (WREGS) → WREG (STATUSS) → STATUS (BSRS) → BSR if s = 0 (WREGS) → unchanged (STATUSS) → unchanged (BSRS) → unchanged In both cases PCLATU, PCLATH are unchanged. Status Affected: GIE/GIEH,PEIE/GIEL Encoding: 0000 0000 0001 000s Description: Return from Interrupt. Stack is popped and Top of Stack (TOS) is loaded into the PC. Interrupts are enabled by setting either the high or low priority global interrupt enable bits (GIEH or GIEL). If ’s’ = 1, the contents of the Shadow Registers WREGS, STATUSS and BSRS are loaded into their corresponding registers, WREG, STATUS and BSR. If ’s’ = 0, no update of these registers occurs (default). Words: 1 Cycles: 2 Q Cycle Activity: 1st cycle: Q1 Q2 Q3 Q4 Decode No operation Set GIEH or GIEL POP PC from stack 2nd cycle: Q1 Q2 Q3 Q4 No operation No operation No operation No operation 39500 18C Reference Manual.book Page 100 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-101 Section 31. Instruction Set Instruction Set 31 Example 1 HERE RETFIE 0 ; Return from interrupt, ; enable interrupts Before Instruction PC = address HERE GIE/GIEH, PEIE/GIEL = x WREG = x BSR = x STATUS = x After Instruction PC = TOS GIE/GIEH, PEIE/GIEL = 1 WREG = unchanged BSR = unchanged STATUS = unchanged Example 2 HERE RETFIE 1 ; Return from interrupt, ; enable interrupts. ; This is a fast return so ; the BSR, WREG, and STATUS ; Registers are restored ; with the values in the ; Fast Register Stack Before Instruction PC = address HERE GIE/GIEH, PEIE/GIEL = x WREG = x BSR = x STATUS = x After Instruction PC = TOS GIE/GIEH, PEIE/GIEL = 1 WREG = WREGS BSR = BSRS STATUS = STATUSS 39500 18C Reference Manual.book Page 101 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-102  2000 Microchip Technology Inc. RETLW Return with Literal in W Syntax: [ label ] RETLW k Operands: 0 ≤ k ≤ 255 Operation: k → WREG; TOS → PC PCLATU and PCLATH are unchanged Status Affected: None Encoding: 0000 1100 kkkk kkkk Description: The WREG Register is loaded with the eight bit literal 'k'. The program counter is loaded from the Top of Stack (the return address). The upper and high address latches (PCLATU:PCLATH) remain unchanged. This is a twocycle instruction. Words: 1 Cycles: 2 Q Cycle Activity: 1st cycle: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data POP PC from stack, write to WREG 2nd cycle: Q1 Q2 Q3 Q4 No operation No operation No operation No operation 39500 18C Reference Manual.book Page 102 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-103 Section 31. Instruction Set Instruction Set 31 Example HERE TABLE CALL • • • ADDWF RETLW RETLW • • • RETLW TABLE PC k1 k2 kn ; WREG contains table offset ; value WREG now has table ; value ; WREG = offset ; Begin table, ; Return with constant in WREG ; End of table Before Instruction WREG = x After Instruction WREG = value of kx PC = TOS = Address HERE + 2 39500 18C Reference Manual.book Page 103 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-104  2000 Microchip Technology Inc. RETURN Return from Subroutine Syntax: [ label ] RETURN s Operands: s ∈ [0,1] Operation: (TOS) → PC if s = 1 (WREGS) → WREG (STATUSS) → STATUS (BSRS) → BSR if s = 0 (WREGS) → unchanged (STATUSS) → unchanged (BSRS) → unchanged In both cases PCLATU and PCLATH are unchanged Status Affected: None Encoding: 0000 0000 0001 001s Description: Return from subroutine. The stack is popped and the Top of Stack (TOS) is loaded into the program counter. If ’s’ = 1, the contents of the Shadow Registers WREGS, STATUSS and BSRS are loaded into their corresponding registers, WREG, STATUS and BSR. If ’s’ = 0, no update of these registers occurs (default). Words: 1 Cycles: 2 Q Cycle Activity: 1st cycle: Q1 Q2 Q3 Q4 Decode No operation Process data POP PC from stack 2nd cycle: Q1 Q2 Q3 Q4 No operation No operation No operation No operation Example 1 HERE RETURN 0 ; Return from subroutine. Before Instruction PC = address HERE WREG = x BSR = x STATUS = x After Instruction PC = TOS WREG = unchanged BSR = unchanged STATUS = unchanged 39500 18C Reference Manual.book Page 104 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-105 Section 31. Instruction Set Instruction Set 31 Example 2 HERE RETURN 1 ; Return from subroutine. ; This is a fast return so ; the BSR, WREG, and STATUS ; Registers are restored ; with the values in the ; Fast Register Stack Before Instruction PC = address HERE WREG = x BSR = x STATUS = x After Instruction PC = TOS WREG = WREGS BSR = BSRS STATUS = STATUSS 39500 18C Reference Manual.book Page 105 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-106  2000 Microchip Technology Inc. RLCF Rotate Left f through Carry Syntax: [ label ] RLCF f, d, a Operands: 0 ≤ f ≤ 127 d ∈ [0,1] a ∈ [0,1] Operation: See description below Status Affected: C, Z, N Encoding: 0011 01da ffff ffff Description: The contents of Register 'f' are rotated one bit to the left through the Carry Flag. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination C Register f Example 1 RLCF REG1, 0, 1 ; Rotate the value in REG1 ; 1 bit position left and ; the carry bit loads into ; bit 0. Then place the ; result in the WREG ; Register Before Instruction REG1 = 1110 0110 C = 0 Z, N = x After Instruction REG1 = 1110 0110 WREG = 1100 1100 C = 1 Z = 0 N = 1 39500 18C Reference Manual.book Page 106 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-107 Section 31. Instruction Set Instruction Set 31 Example 2 RLF INDF0, 1, 1 ; Rotate the value in the ; register pointed by the ; FSR0 (FSR0H:FSR0L) ; Register 1 bit position ; left and place the result ; back into that register ; Carry loads into bit 0 Case 1: Before Instruction FSR0 = 0x0C2 Contents of Address (FSR0) = 0011 1010 C = 1 Z, N = x After Instruction FSR0 = 0x0C2 Contents of Address (FSR0) = 0111 0101 C = 0 Z = 0 N = 0 Case 2: Before Instruction FSR0 = 0x0C2 Contents of Address (FSR0) = 1011 1001 C = 0 Z, N = x After Instruction FSR0 = 0x0C2 Contents of Address (FSR0) = 0111 0010 C = 1 Z = 0 N = 0 39500 18C Reference Manual.book Page 107 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-108  2000 Microchip Technology Inc. RLNCF Rotate Left f (No Carry) Syntax: [ label ] RLNCF f, d, a Operands: 0 ≤ f ≤ 127 d ∈ [0,1] a ∈ [0,1] Operation: See description below Status Affected: Z, N Encoding: 0100 01da ffff ffff Description: The contents of Register 'f' are rotated one bit to the left. The Carry Flag bit is not affected. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 RLNCF REG1, 0, 1 ; Rotate the value in REG1 ; 1 bit position left and ; bit 7 loads into bit 0. ; Then place the result in ; the WREG Register Before Instruction REG1 = 1110 0110 Z, N = x After Instruction REG1 = 1110 0110 WREG = 1100 1101 Z = 0 N = 1 Register f 39500 18C Reference Manual.book Page 108 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-109 Section 31. Instruction Set Instruction Set 31 Example 2 RLNCF INDF0, 1, 1 ; Rotate the value in the ; register pointed by the ; FSR0 (FSR0H:FSR0L) ; Register 1 bit position left ; and place the result in the ; back into that register. ; bit 7 loads into bit 0. Case 1: Before Instruction FSR0 = 0x1C2 Contents of Address (FSR0) = 0011 1010 Z, N = x After Instruction FSR0 = 0x1C2 Contents of Address (FSR0) = 0111 0100 Z = 0 N = 0 Case 2: Before Instruction FSR0 = 0x1C2 Contents of Address (FSR0) = 1011 1001 Z, N = x After Instruction FSR0 = 0x1C2 Contents of Address (FSR0) = 0111 0011 Z = 0 N = 0 39500 18C Reference Manual.book Page 109 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-110  2000 Microchip Technology Inc. RRCF Rotate Right f through Carry Syntax: [ label ] RRCF f, d, a Operands: 0 ≤ f ≤ 127 d ∈ [0,1] a ∈ [0,1] Operation: See description below Status Affected: C, Z, N Encoding: 0011 00da ffff ffff Description: The contents of Register 'f' are rotated one bit to the right through the Carry Flag. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination C Register f Example 1 RRCF REG1, 0, 1 ; Rotate the value in REG1 ; 1 bit position right and ; the carry bit loads into ; bit 7. Then place the ; result in the WREG ; Register Before Instruction REG1 = 1110 0110 WREG = xxxx xxxx C = 0 Z, N = x After Instruction REG1 = 1110 0110 WREG = 0111 0011 C = 0 Z = 0 N = 0 39500 18C Reference Manual.book Page 110 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-111 Section 31. Instruction Set Instruction Set 31 Example 2 RRCF INDF0, 1, 1 ; Rotate the value in the ; register pointed by the ; FSR0 (FSR0H:FSR0L) ; Register 1 bit position ; right and place the result ; in the back into that ; register. ; Carry loads into bit 7. Case 1: Before Instruction FSR0 = 0x2C2 Contents of Address (FSR0) = 0011 1010 C =1 Z, N = x After Instruction FSR0 = 0x2C2 Contents of Address (FSR0) = 1001 1101 C =0 Z = 0 N = 1 Case 2: Before Instruction FSR0 = 0x2C2 Contents of Address (FSR0) = 0011 1001 C =0 Z, N = x After Instruction FSR0 = 0x2C2 Contents of Address (FSR0) = 0001 1100 C =1 Z =0 N =0 39500 18C Reference Manual.book Page 111 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-112  2000 Microchip Technology Inc. RRNCF Rotate Right f (No Carry) Syntax: [ label ] RRNCF f, d, a Operands: 0 ≤ f ≤ 127 d ∈ [0,1] a ∈ [0,1] Operation: See description below Status Affected: Z, N Encoding: 0100 00da ffff ffff Description: The contents of Register 'f' are rotated one bit to the right. The Carry Flag bit is not affected. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 RRNCF REG1, 0, 1 ; Rotate the value in REG1 ; 1 bit position right and ; bit 0 loads into bit 7. ; Then place the result in ; the WREG Register Before Instruction REG1 = 1110 0110 WREG = x Z, N = 1 After Instruction REG1 = 1110 0110 WREG = 0111 0011 Z =0 N =0 Register f 39500 18C Reference Manual.book Page 112 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-113 Section 31. Instruction Set Instruction Set 31 Example 2 RRNCF INDF0, 1, 1 ; Rotate the value in the ; register pointed by the ; FSR (FSR0H:FSR0L) ; Register 1 bit ; position right and place ; the result back into ; that register. ; bit 0 loads into bit 7. Case 1: Before Instruction FSR0 = 0x3C2 Contents of Address (FSR0) = 0011 1010 Z, N = x After Instruction FSR0 = 0x3C2 Contents of Address (FSR0) = 0001 1101 Z =0 N =0 Case 2: Before Instruction FSR0 = 0x3C2 Contents of Address (FSR0) = 0011 1001 Z, N = x After Instruction FSR0 = 0x3C2 Contents of Address (FSR0) = 1001 1100 Z =0 N =1 39500 18C Reference Manual.book Page 113 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-114  2000 Microchip Technology Inc. SETF Set f Syntax: [ label ] SETF f, a Operands: 0 ≤ f ≤ 255 a ∈ [0,1] Operation: FFh → f Status Affected: None Encoding: 0110 100a ffff ffff Description: The contents of the specified register are set. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write Register 'f' Example 1 SETF FLAG_REG, 1 ; Set all the bits in ; Register FLAG_REG Before Instruction FLAG_REG = 0x5A After Instruction FLAG_REG = 0xFF Example 2 SETF INDF0, 1 ; Set all the bits in the ; register pointed to by the ; FSR (FSR0H:FSR0L) Register Before Instruction FSR0 = 0x4C2 Contents of Address (FSR0) = 0xAA After Instruction FSR0 = 0x4C2 Contents of Address (FSR0) = 0xFF 39500 18C Reference Manual.book Page 114 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-115 Section 31. Instruction Set Instruction Set 31 SLEEP Enter SLEEP mode Syntax: [ label ] SLEEP Operands: None Operation: 00h → WDT, 0 → WDT prescaler count, 1 → TO, 0 → PD Status Affected: TO, PD Encoding: 0000 0000 0000 0011 Description: The power-down status bit, PD is cleared. Time-out status bit, TO is set. Watchdog Timer and its prescaler count are cleared. The processor is put into SLEEP mode with the oscillator stopped. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode No operation No operation Go to sleep Example: SLEEP ; Turn off the device ; oscillator. This is the ; lowest power mode Before Instruction TO = ? PD = ? After Instruction TO = 1 † PD = 0 † If WDT causes wake-up, this bit is cleared Note: The SLEEP instruction does not affect the assignment of the WDT prescaler. 39500 18C Reference Manual.book Page 115 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-116  2000 Microchip Technology Inc. SUBFWB Subtract f from WREG with borrow Syntax: [ label ] SUBFWB f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (WREG) – (f) – (C) → destination Status Affected: C, DC, Z, OV, N Encoding: 0101 01da ffff ffff Description: Subtract Register 'f' and carry flag (borrow) from W (2’s complement method). The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register ’f’ Process data Write to destination Example 1 SUBFWB MYREG, 1, 1 ; WREG - MYREG - borrow bit Before Instruction MYREG = 0x37 WREG = 0x10 C, DC, Z, OV, N = x C =0 After Instruction MYREG = 0xA8 WREG = 0x10 C =0 DC = 0 Z =0 OV = 0 N =1 ; result is negative 39500 18C Reference Manual.book Page 116 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-117 Section 31. Instruction Set Instruction Set 31 Example 2: SUBFWB MYREG, 1, 1 ; WREG - MYREG - borrow bit Case 1: Before Instruction MYREG = 0x03 WREG = 0x02 C =1 DC, Z, OV, N = x After Instruction MYREG = 0xFF WREG = 0x02 C =0 DC = 0 Z =0 OV = 0 N =1 ; result is negative Case 2: Before Instruction MYREG = 0x02 WREG = 0x02 C =1 DC, Z, OV, N = x After Instruction MYREG = 0x00 WREG = 0x02 C =1 DC = 1 Z =1 OV = 0 N =0 ; result is zero Case 3: Before Instruction MYREG = 0x01 WREG = 0x03 C =1 DC, Z, OV, N = x After Instruction MYREG = 0x02 WREG = 0x03 C =1 DC = 1 Z =0 OV = 0 N =0 ; result is positive 39500 18C Reference Manual.book Page 117 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-118  2000 Microchip Technology Inc. SUBLW Subtract W from Literal Syntax: [ label ] SUBLW k Operands: 0 ≤ k ≤ 255 Operation: k - (WREG) → WREG Status Affected: C, DC, Z, OV, N Encoding: 0000 1000 kkkk kkkk Description: The WREG Register is subtracted (2’s complement method) from the eight bit literal 'k'. The result is placed in the WREG Register. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data Write to WREG Register Example 1 SUBLW OFFSET ; Subtract the value in ; WREG from the constant ; OFFSET Before Instruction WREG = 0x37 OFFSET = 0x10 C, DC, Z, OV, N = x After Instruction WREG = 0xD9 C =0 DC = 0 Z =0 OV = 0 N =1 ; result is negative 39500 18C Reference Manual.book Page 118 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-119 Section 31. Instruction Set Instruction Set 31 Example 2: SUBLW 0x02 ; Subtract WREG Register ; from 2h Case 1: Before Instruction WREG = 0x01 C, DC, Z, OV, N = x After Instruction WREG = 0x01 C =1 DC = 1 Z =0 OV = 0 N =0 ; result is positive Case 2: Before Instruction WREG = 0x02 C, DC, Z, OV, N = x After Instruction WREG = 0x00 C =1 DC = 1 Z =1 OV = 0 N =0 ; result is zero Case 3: Before Instruction WREG = 0x03 C, DC, Z, OV, N = x After Instruction WREG = 0xFF C =0 DC = 0 Z =0 OV = 0 N =1 ; result is negative 39500 18C Reference Manual.book Page 119 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-120  2000 Microchip Technology Inc. SUBWF Subtract W from f Syntax: [ label ] SUBWF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (f) - (WREG) → destination Status Affected: C, DC, Z, OV, N Encoding: 0101 11da ffff ffff Description: Subtract (2’s complement method) WREG Register from Register 'f'. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1: SUBWF REG1, 1, 1 ; Subtract the value in the ; WREG Register from REG1, ; placing the result in REG1 Case 1: Before Instruction REG1 = 3 WREG = 2 C, DC, Z, OV, N = x After Instruction REG1 = 1 WREG = 2 C =1 DC = 1 Z =0 OV = 0 N =0 ; result is positive 39500 18C Reference Manual.book Page 120 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-121 Section 31. Instruction Set Instruction Set 31 Case 2: Before Instruction REG1 = 2 WREG = 2 C, DC, Z, OV, N = x After Instruction REG1 = 0 WREG = 2 C =1 DC = 1 Z =1 OV = 0 N =0 ; result is zero Case 3: Before Instruction REG1 = 1 WREG = 2 C, DC, Z, OV, N = x After Instruction REG1 = 0xFF WREG = 2 C =0 DC = 0 Z =0 OV = 0 N =1 ; result is negative 39500 18C Reference Manual.book Page 121 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-122  2000 Microchip Technology Inc. SUBWFB Subtract W from f with Borrow Syntax: [ label ] SUBWFB f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (f) - (WREG) - (C) → destination Status Affected: C, DC, Z, OV, N Encoding: 0101 10da ffff ffff Description: Subtract (2’s complement method) WREG Register from Register 'f' with borrow. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1: SUBWF REG1, 1, 1 ; Subtract the value in the ; WREG Register from REG1, ; placing the result in REG1 Case 1: Before Instruction REG1 = 3 WREG = 2 C =1 DC, Z, OV, N = x After Instruction REG1 = 1 WREG = 2 C =1 DC = 1 Z =0 OV = 0 N =0 ; result is positive 39500 18C Reference Manual.book Page 122 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-123 Section 31. Instruction Set Instruction Set 31 Case 2: Before Instruction REG1 = 2 WREG = 2 C =1 DC, Z, OV, N = x After Instruction REG1 = 0 WREG = 2 C =1 DC = 1 Z =1 OV = 0 N =0 ; result is zero Case 3: Before Instruction REG1 = 1 WREG = 2 C =1 DC, Z, OV, N = x After Instruction REG1 = 0xFF WREG = 2 C =0 DC = 0 Z =0 OV = 0 N =1 ; result is negative 39500 18C Reference Manual.book Page 123 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-124  2000 Microchip Technology Inc. SWAPF Swap Nibbles in f Syntax: [ label ] SWAPF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (f<3:0>) → destination<7:4>, (f<7:4>) → destination<3:0> Status Affected: None Encoding: 0011 10da ffff ffff Description: The upper and lower nibbles of Register 'f' are exchanged. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 SWAPF REG1, 0, 1 ; Swap the high and low ; nibble of Register REG1 ; and place the result in ; the WREG Register Before Instruction REG1 = 0xA5 WREG = x After Instruction REG1 = 0xA5 WREG = 0x5A 39500 18C Reference Manual.book Page 124 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-125 Section 31. Instruction Set Instruction Set 31 Example 2 SWAPF INDF0, 1, 1 ; Swap the high and low ; nibble of register pointed ; to by the FSR ; (FSR0H:FSR0L) Register, ; placing the result back ; into that register Before Instruction FSR0 = 0x5C2 Contents of Address (FSR0) = 0x20 After Instruction FSR0 = 0x5C2 Contents of Address (FSR0) = 0x02 Example 3 SWAPF REG1, 1, 1 ; Swap the high and low ; nibble of Register REG1 ; placing the result back ; into that register Before Instruction REG1 = 0xA5 After Instruction REG1 = 0x5A 39500 18C Reference Manual.book Page 125 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-126  2000 Microchip Technology Inc. TBLRD Table Read Syntax: [ label ] TBLRD[*, *+, *-, or +*] Operands: 0 ≤ m ≤ 3 Operation: if TBLRD *, (Prog Mem (TBLPTR)) → TABLAT; TBLPTR - No Change; if TBLRD *+, (Prog Mem (TBLPTR)) → TABLAT; (TBLPTR) +1 → TBLPTR; if TBLRD *-, (Prog Mem (TBLPTR)) → TABLAT; (TBLPTR) -1 → TBLPTR; if TBLRD +*, (TBLPTR) +1 → TBLPTR; (Prog Mem (TBLPTR)) → TABLAT; Status Affected: None Encoding: 0000 0000 0000 10mm * → mm = 00 *+ → mm = 01 *- → mm = 10 +* → mm = 11 Description: This instruction is used to read the contents of Program Memory. To address the program memory a pointer called Table Pointer (TBLPTR) is used. The TBLPTR (a 21-bit pointer) points to each byte in the program memory. TBLPTR has a 2 Mbyte address range. The LSb of the TBLPTR selects which byte of the program memory location to access. TBLPTR[0] = 0: Least Significant byte of Program Memory Word TBLPTR[0] = 1: Most Significant byte of Program Memory Word The Program Memory word address is the same as the TBLPTR address, except that the LSb of TBLPTR (TBLPTR[0]) is always forced to ’0’. The TBLRD instruction can modify the value of TBLPTR as follows: • no change • post-increment • post-decrement • pre-increment Words: 1 Cycles: 2 Q Cycle Activity: 1st cycle: Q1 Q2 Q3 Q4 Decode No operation No operation No operation 2nd cycle: No operation No operation (Table Pointer on Address bus) No operation No operation (OE goes low) 39500 18C Reference Manual.book Page 126 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-127 Section 31. Instruction Set Instruction Set 31 Example 31-3:Program Memory Contents for Examples Word Address (points to low byte) Data Word Word Address (points to low byte) Data Word MSb LSb MSb LSb 0x00A356 0x12 0x34 0x000000 0x01 0x00 0x00A358 0x56 0x28 0x000002 0x03 0x02 0x00A35A 0xAA 0x55 0x000004 0x05 0x04 0x00A35C 0xFF 0xFE 0x000006 0x07 0x06 0x00A35E 0xB1 0x00 0x000008 0x08 0x07 Example 1 TBLRD*+ ; Read byte addressed by ; TBLPTR, then increment ; TBLPTR Before Instruction TABLAT = x TBLPTR = 0x00A356 Contents of Address (TBLPTR)= 0x34 After Instruction TABLAT = 0x34 TBLPTR = 0x00A357 Example 2 TBLRD+* ; Increment TBLPTR, then ; Read byte addressed by ; TBLPTR Before Instruction TABLAT = x TBLPTR = 0x00A357 Contents of Address (TBLPTR)= 0x12 Contents of Address (TBLPTR + 1)= 0x28 After Instruction TABLAT = 0x28 TBLPTR = 0x00A358 Example 3 TBLRD*- ; Read byte addressed by ; TBLPTR, then decrement ; TBLPTR Before Instruction TABLAT = x TBLPTR = 0x00A357 Contents of Address (TBLPTR)= 0x12 After Instruction TABLAT = 0x12 TBLPTR = 0x00A356 Example 4 TBLRD* ; Read byte addressed by ; TBLPTR. TBLPTR is unchanged Before Instruction TABLAT = x TBLPTR = 0x00A357 Contents of Address (TBLPTR)= 0x12 After Instruction TABLAT = 0x12 TBLPTR = 0x00A357 39500 18C Reference Manual.book Page 127 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-128  2000 Microchip Technology Inc. TBLWT Table Write Syntax: [ label ] TBLWT[*, *+, *-, +*] Operands: 0 ≤ m ≤ 3 Operation: if TBLWT*, (TABLAT) → Prog Mem (TBLPTR) or Holding Register1; TBLPTR - No Change; if TBLWT*+, (TABLAT) → Prog Mem (TBLPTR) or Holding Register1; (TBLPTR) +1 → TBLPTR; if TBLWT*-, (TABLAT) → Prog Mem (TBLPTR) or Holding Register1; (TBLPTR) -1 → TBLPTR; if TBLWT+*, (TBLPTR) +1 → TBLPTR; (TABLAT) → Prog Mem (TBLPTR) or Holding Register1; Note 1: The use of a Holding Register(s) is device specific. Please refer to the Device Data Sheet for information on the operation of the TBLWT instruction with the Program Memory. Status Affected: None Encoding: 0000 0000 0000 11mm * → mm = 00 *+ → mm = 01 *- → mm = 10 +* → mm = 11 Description: This instruction is used to program the contents of Program Memory. To address the program memory a pointer called Table Pointer (TBLPTR) is used. The TBLPTR (a 21-bit pointer) points to each byte in the program memory. TBLPTR has a 2 MBtye address range. The LSb of the TBLPTR selects which byte of the program memory location to access. TBLPTR[0] = 0: Least Significant byte of Program Memory Word TBLPTR[0] = 1: Most Significant byte of Program Memory Word The Program Memory word address is the same as the TBLPTR address, except that the LSb of TBLPTR (TBLPTR[0]) is always forced to ’0’. The TBLWT instruction can modify the value of TBLPTR as follows: • no change • post-increment • post-decrement • pre-increment Words: 1 Cycles: 2 (many if long write to internal program memory) Q Cycle Activity: 1st cycle: Q1 Q2 Q3 Q4 Decode No operation No operation No operation 2nd cycle: No operation No operation (Table Pointer on Address bus) No operation No operation (Table Latch on Address bus, WR goes low) 39500 18C Reference Manual.book Page 128 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-129 Section 31. Instruction Set Instruction Set 31 Example 31-4:Program Memory Contents for Examples Word Address (points to low byte) Original Data Word (before) Example 1 Data Word (after) Example 2 Data Word (after) Example 3 Data Word (after) Example 4 Data Word (after) MSb LSb MSb LSb MSb LSb MSb LSb MSb LSb 0x00A356 0x12 0x34 0x12 0x55 0x12 0x34 0xAA 0x34 0x12 0x34 0x00A358 0x56 0x28 0x56 0x28 0x56 0xAA 0x56 0x28 0x5A 0x28 0x00A35A 0xAA 0x55 0xAA 0x55 0xAA 0x55 0xAA 0x55 0xAA 0x55 TABLAT 0x55 0xAA 0xAA 0x5A Example 1 TBLWT*+ ; Write byte addressed by ; TBLPTR, then increment TBLPTR Before Instruction TABLAT = 0x55 TBLPTR = 0x00A356 Contents of (TBLPTR) = 0x34 After Instruction TBLPTR = 0x00A357 Contents of (TBLPTR) = 0x55 Example 2 TBLWT+* ; Increment TBLPTR, then Write ; byte addressed by TBLPTR Before Instruction TABLAT = 0xAA TBLPTR = 0x00A357 Contents of (TBLPTR) = 0x12 Contents of (TBLPTR + 1) = 0x28 After Instruction TBLPTR = 0x00A358 Contents of (TBLPTR) = 0x12 Contents of (TBLPTR + 1) = 0xAA Example 3 TBLWT*- ; Write byte addressed by ; TBLPTR, then decrement TBLPTR Before Instruction TABLAT = 0xAA TBLPTR = 0x00A357 Contents of (TBLPTR) = 0x12 After Instruction TBLPTR = 0x00A356 Contents of (TBLPTR) = 0xAA Example 4 TBLWT* ; Write byte addressed by ; TBLPTR. TBLPTR is unchanged Before Instruction TABLAT = 0x5A TBLPTR = 0x00A359 Contents of (TBLPTR) = 0x56 After Instruction TBLPTR = 0x00A359 Contents of (TBLPTR) = 0x5A 39500 18C Reference Manual.book Page 129 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-130  2000 Microchip Technology Inc. TSTFSZ Test f, Skip if 0 Syntax: [ label ] TSTFSZ f, a Operands: 0 ≤ f ≤ 255 a ∈ [0,1] Operation: Skip if (f) = 0 Status Affected: None Encoding: 0110 011a ffff ffff Description: If Register 'f' = 0, the next instruction fetched is discarded and a NOP is executed (two NOPs if the fetched instruction is a two-cycle instruction). The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 (2 or 3) Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination If skip (2nd cycle): Q1 Q2 Q3 Q4 No operation No operation No operation No operation If skip and followed by a two word instruction: Q1 Q2 Q3 Q4 No operation No operation No operation No operation No operation No operation No operation No operation Example 1A HERE NZERO ZERO TSTFSZ • • REG1, 1 ; If Register REG1 is zero ; then skip the next ; program memory address Before Instruction REG1 = 0xAF PC = Address (HERE) After Instruction PC = Address (NZERO) 39500 18C Reference Manual.book Page 130 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-131 Section 31. Instruction Set Instruction Set 31 Example 2 HERE NZERO ZERO TSTFSZ • • REG1, 1 ; If Register REG1 is zero ; then skip the next ; program memory address Before Instruction REG1 = 0x00 PC = Address (HERE) After Instruction PC = Address (ZERO) Example 3 HERE NZERO ZERO TSTFSZ • • REG1, 0 ; If Register REG1 is zero ; then skip the next ; program memory address Case 1 Before Instruction REG1 = 0xAF Address of REG1 = 0x9A, Bank 3 0x9A, Bank 15 = 0x00 PC = Address (HERE) After Instruction PC = Address (ZERO) Case 2 Before Instruction REG1 = 0x00 Address of REG1 = 0x9A, Bank 3 0x9A, Bank 15 = 0xAF PC = Address (HERE) After Instruction PC = Address (NZERO) Example 4 HERE NZERO ZERO TSTFSZ • • INDF0, 1 ; If Register pointed to by ; FSR0 (FSR0H:FSR0L) is ; zero, then skip the next ; program memory address Case 1 Before Instruction FSR0 = 0x6C2 Contents of Address (FSR0) = 0xAF PC = Address (HERE) After Instruction FSR0 = 0x6C2 Contents of Address (FSR0) = 0xAF PC = Address (NZERO) Case 2 Before Instruction FSR0 = 0x6C2 Contents of Address (FSR0) = 0x00 PC = Address (HERE) After Instruction FSR0 = 0x6C2 Contents of Address (FSR0) = 0x00 PC = Address (ZERO) 39500 18C Reference Manual.book Page 131 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-132  2000 Microchip Technology Inc. XORLW Exclusive OR Literal with W Syntax: [ label] XORLW k Operands: 0 ≤ k ≤ 255 Operation: (WREG).XOR. k → W Status Affected: Z, N Encoding: 0000 1010 kkkk kkkk Description: The contents of the WREG Register are XOR’ed with the eight bit literal 'k'. The result is placed in the WREG Register. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read literal 'k' Process data Write to WREG Register Example 1 XORLW 0xAF ; Exclusive OR the value ; in WREG with AFh Before Instruction WREG = 0xB5 Z, N = x ; 1011 0101 (0xB5) ; 1010 1111 (0xAF) After Instruction ; --------- ------ WREG = 0x1A Z =0 N =0 ; 0001 1010 (0x1A) Example 2 XORLW MYREG ; Exclusive OR the value ; in WREG with the address ; of MYREG Before Instruction WREG = 0xAF Address of MYREG † = 0x37 Z, N = x † MYREG is a symbol for a data memory location After Instruction WREG = 0x98 Z =0 N =1 ; 1010 1111 ; ; 0011 0111 ; ---- ---- ; 1001 1000 39500 18C Reference Manual.book Page 132 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-133 Section 31. Instruction Set Instruction Set 31 Example 3 XORLW HIGH (LU_TABLE) ; Exclusive OR the value ; in WREG with the high ; byte of the address of ; LU_TABLE Before Instruction WREG = 0xAF Address of LU_TABLE † = 0x9375 Z, N = x † LU_TABLE is a label for an address in program memory After Instruction WREG = 0x3C Z =0 N =0 ; ; 1010 1111 ; ; 1001 0011 ; ---- ---- ; ; ; ; 0011 1100 39500 18C Reference Manual.book Page 133 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-134  2000 Microchip Technology Inc. XORWF Exclusive OR W with f Syntax: [ label ] XORWF f, d, a Operands: 0 ≤ f ≤ 255 d ∈ [0,1] a ∈ [0,1] Operation: (WREG).XOR. (f) → destination Status Affected: Z, N Encoding: 0001 10da ffff ffff Description: Exclusive OR the contents of the WREG Register with Register 'f'. The ’d’ bit selects the destination for the operation. If 'd' is 1; the result is stored back in the File Register 'f'. If 'd' is 0; the result is stored in the WREG Register. The ’a’ bit selects which bank is accessed for the operation. If ’a’ is 1; the bank specified by the BSR Register is used. If ’a’ is 0; the access bank is used. Words: 1 Cycles: 1 Q Cycle Activity: Q1 Q2 Q3 Q4 Decode Read Register 'f' Process data Write to destination Example 1 XORWF REG1, 1, 1 ; Exclusive OR the value ; in WREG with the value in ; REG1 Before Instruction REG1 = 0xAF WREG = 0xB5 Z, N = x ; 1010 1111 (0xAF) ; 1011 0101 (0xB5) ; --------- ------ After Instruction REG1 = 0x1A WREG = 0xB5 Z =0 N =0 ; 0001 1010 (0x1A) 39500 18C Reference Manual.book Page 134 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-135 Section 31. Instruction Set Instruction Set 31 Example 2 XORWF REG1, 0, 1 ; Exclusive OR the value ; in WREG with the value in ; REG1. Place result in ; WREG Before Instruction REG1 = 0xAF WREG = 0xB5 Z, N = x ; 1010 1111 (0xAF) ; 1011 0101 (0xB5) ; --------- ------ After Instruction REG1 = 0xAF WREG = 0x1A Z =0 N =0 ; ; 0001 1010 (0x1A) Example 3 XORWF INDF0, 1, 1 ; Exclusive OR the value ; in WREG with the value ; pointed to by the FSR0 ; (FSR0H:FSR0L) Register Before Instruction WREG = 0xB5 FSR0 = 0x7C2 Contents of Address (FSR0) = 0xAF Z, N = x After Instruction WREG = 0xB5 FSR0 = 0x7C2 Contents of Address (FSR0) = 0x1A Z =0 N =0 ; ; 1011 0101 ; ; ; 1010 1111 ; ; ; ; ; ; 0001 1010 ; ; Example 4 XORWF REG1, 1, 0 ; Exclusive OR the value ; in WREG with the value ; at address REG1 in the ; access bank. Place ; result in access bank Before Instruction WREG = 0xF8 REG1 = 0x01 Contents of Address (REG1) in access bank = 0xAA Z, N = x After Instruction WREG = 0xF8 REG1 = 0x01 Contents of Address (REG1) in access bank = 0x52 Z =0 N =0 ; ; 1111 1000 ; 0000 0001 ; ; ; 1010 1010 ; ; ; ; ; ; ; 0101 0010 ; ; 39500 18C Reference Manual.book Page 135 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-136  2000 Microchip Technology Inc. 31.8 Design Tips Question 1: I have seen references to “Read-Modify-Write” instructions in your data sheet, but I do not know what that is. Can you explain what it is and why I need to know this? Answer 1: An easy example of a Read-Modify-Write (or R-M-W) instruction is the bit clear instruction BCF. You might think that the processor just clears the bit, which on a port output pin would clear the pin. What actually happens is the whole port (or register) is first read, THEN the bit is cleared, then the new modified value is written back to the port (or register). Actually, any instruction that depends on a value currently in the register is going to be a Read-Modify-Write instruction. This includes ADDWF, SUBWF, BCF, BSF, INCF, XORWF, etc... Instructions that do not depend on the current register value, like MOVWF, CLRF, and so on are not R-M-W instructions. One situation where you would want to consider the affects of a R-M-W instruction is a port that is continuously changed from input to output and back. For example, say you have TRISB set to all outputs, and write all ones to the PORTB Register, all of the PORTB pins will go high. Now, say you turn pin RB3 into an input, which happens to go low. A BCF PORTB,6 is then executed to drive pin RB6 low. If you then turn RB3 back into an output, it will now drive low, even though the last value you put there was a one. What happened was that the BCF of the other pin (RB6) caused the whole port to be read, including the zero on RB3 when it was an input. Then, bit 6 was changed as requested, but since RB3 was read as a zero, zero will also be placed back into that port latch, overwriting the one that was there before. When the pin is turned back into an output, the new value was reflected. Try using the LATx register instead of the PORTx register for this read-modify-write operation. Question 2: When I perform a BCF, other pins get cleared in the port. Why? Answer 2: There are a few possibilities, two are: 1. Another case where a R-M-W instruction may seem to change other pin values unexpectedly can be illustrated as follows: Suppose you make PORTC all outputs and drive the pins low. On each of the port pins is an LED connected to ground, such that a high output lights it. Across each LED is a 100 µF capacitor. Let's also suppose that the processor is running very fast, say 20 MHz. Now if you go down the port setting each pin in order; BSF PORTC,0 then BSF PORTC,1 then BSF PORTC,2 and so on, you may see that only the last pin was set, and only the last LED actually turns on. This is because the capacitors take a while to charge. As each pin was set, the pin before it was not charged yet and so was read as a zero. This zero is written back out to the port latch (R-M-W, remember) which clears the bit you just tried to set the instruction before. This is usually only a concern at high speeds and for successive port operations, but it can happen, so take it into consideration. 2. If this is on a PIC16C7X device, you may not have configured the I/O pins properly in the ADCON1 Register. If a pin is configured for analog input, any read of that pin will read a zero, regardless of the voltage on the pin. This is an exception to the normal rule that the pin state is always read. You can still configure an analog pin as an output in the TRIS Register, and drive the pin high or low by writing to it, but you will always read a zero. Therefore, if you execute a Read-Modify-Write instruction (see previous question), all analog pins are read as zero, and those not directly modified by the instruction will be written back to the port latch as zero. A pin configured as analog is expected to have values that may be neither high nor low to a digital pin, or floating. Floating inputs on digital pins are a no-no, and can lead to high current draw in the input buffer, so the input buffer is disabled. 39500 18C Reference Manual.book Page 136 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39532A-page 31-137 Section 31. Instruction Set Instruction Set 31 31.9 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced family (that is they may be written for the Baseline, the Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the Instruction Set are: Title Application Note # No related Application Notes at this time. Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 137 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39532A-page 31-138  2000 Microchip Technology Inc. 31.10 Revision History Revision A This is the initial released revision of the Enhanced MCU Instruction Set description. 39500 18C Reference Manual.book Page 138 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-1 Electrical Specifications 32 Section 32. Electrical Specifications HIGHLIGHTS 32.1 Introduction .................................................................................................................. 32-2 32.2 Absolute Maximums..................................................................................................... 32-3 32.3 Voltage vs Frequency Graph........................................................................................ 32-4 32.4 Device Voltage Specifications ...................................................................................... 32-6 32.5 Device Current Specifications...................................................................................... 32-7 32.6 Input Threshold Levels............................................................................................... 32-10 32.7 I/O Current Specifications .......................................................................................... 32-11 32.8 Output Drive Levels.................................................................................................... 32-12 32.9 I/O Capacitive Loading............................................................................................... 32-13 32.10 Low Voltage Detect (LVD) .......................................................................................... 32-14 32.11 EPROM/FLASH/Data EEPROM ................................................................................ 32-15 32.12 Comparators and Voltage Reference......................................................................... 32-16 32.13 Timing Parameter Symbology.................................................................................... 32-18 32.14 Example External Clock Timing Waveforms and Requirements................................ 32-19 32.15 Example Phase Lock Loop (PLL) Timing Waveforms and Requirements ................. 32-20 32.16 Example Power-up and RESET Timing Waveforms and Requirements.................... 32-22 32.17 Example Timer0 and Timer1 Timing Waveforms and Requirements......................... 32-23 32.18 Example CCP Timing Waveforms and Requirements ............................................... 32-24 32.19 Example Parallel Slave Port (PSP) Timing Waveforms and Requirements ............... 32-25 32.20 Example SSP and Master SSP SPI Mode Timing Waveforms and Requirements.... 32-26 32.21 Example SSP I2C Mode Timing Waveforms and Requirements................................ 32-30 32.22 Example Master SSP I2C Mode Timing Waveforms and Requirements.................... 32-32 32.23 Example USART/SCI Timing Waveforms and Requirements.................................... 32-34 32.24 CAN Specifications .................................................................................................... 32-35 32.25 Example 8-bit A/D Timing Waveforms and Requirements ......................................... 32-36 32.26 Example 10-bit A/D Timing Waveforms and Requirements ....................................... 32-38 32.27 Design Tips ................................................................................................................ 32-40 32.28 Related Application Notes.......................................................................................... 32-41 32.29 Revision History ......................................................................................................... 32-42 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-2  2000 Microchip Technology Inc. 32.1 Introduction This section is intended to present the electrical specifications that may be specified in a particular device data sheet and their meaning. This section is NOT intended to give the values of these specifications. For the device specific values you must refer to the device’s data sheet. All values shown in this section should be considered as Example Values. In the description of the device and the functional modules (previous sections), there have been references to electrical specification parameters. These references have been hyperlinked in the electronic version to aid in the use of this manual. Throughout this section, certain terms will be used. Table 32-1 shows the conventions that will be used. Table 32-1: Term Conventions Note: Before starting any design, Microchip HIGHLY recommends that you acquire the most recent copy of the device data sheet and review the electrical specifications to ensure that they will meet your requirements. Term Description PIC18CXXX(1) For EPROM Program Memory devices tested to standard voltage range PIC18LCXXX(1) For EPROM Program Memory devices tested to extended voltage range PIC18FXXX(1) For FLASH Program Memory devices tested to standard voltage range PIC18LFXXX(1) For FLASH Program Memory devices tested to extended voltage range PIC18CRXXX(1) For ROM Program Memory devices tested to standard voltage range PIC18LCRXXX(1) For ROM Program Memory devices tested to extended voltage range LP osc For devices configured with the LP device oscillator selected XT osc For devices configured with the XT device oscillator selected HS osc For devices configured with the HS device oscillator selected HS+PLL osc For devices configured with the HS+PLL device oscillator selected RC osc For devices configured with the RC device oscillator selected RCIO osc For devices configured with the RCIO device oscillator selected EC osc For devices configured with the EC device oscillator selected ECIO osc For devices configured with the ECIO device oscillator selected Commercial For devices with the commercial temperature range grading (0°C ≤ TA ≤ +70°C) Industrial For devices with the industrial temperature range grading (-40°C ≤ TA ≤ +85°C) Extended For devices with the extended temperature range grading (-40°C ≤ TA ≤ +125°C) Note 1: In Electrical Specification examples, we will use PIC18CXXX for the standard voltage range devices and PIC18LCXXX for the extended voltage range devices. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-3 Section 32. Electrical Specifications Electrical Specifications 32 32.2 Absolute Maximums The Absolute Maximum Ratings specify the worst case conditions that can be applied to the device. These ratings are not meant as operational specifications. Stresses above the listed values may cause damage to the device. Specifications are not always stand-alone, that is, the specification may have other requirements as well. An example of this is the “maximum current sourced/sunk by any I/O pin”. The number of I/O pins that can be sinking/sourcing current, at any one time, is dependent upon the maximum current sunk/source by the port(s) (combined) and the maximum current into the VDD pin or out of the VSS pin. In this example, the physical reason is the Power and Ground bus width to the I/O ports and internal logic. If these specifications are exceeded, then electromigration may occur on these Power and Ground buses. Over time, electromigration would cause these buses to open (be disconnected from the pin) and, therefore, cause the logic attached to these buses to stop operating. So, exceeding the absolute specifications may cause device reliability issues. Input Clamp Current is defined as the current through the diode to VSS/VDD if pin voltage exceeds specification. Example Absolute Maximum Ratings † Ambient temperature under bias............................................................................ -55 to +125°C Storage temperature .......................................................................................... -65°C to +150°C Voltage on any pin with respect to VSS (except VDD, MCLR, and RA4)..... -0.3V to (VDD + 0.3V) Voltage on VDD with respect to VSS ........................................................................ -0.3 to +7.5V Voltage on MCLR with respect to VSS (2) ................................................................. 0 to +13.25V Voltage on RA4 with respect to Vss ............................................................................. 0 to +8.5V Total power dissipation (1) .................................................................................................... 1.0W Maximum current out of VSS pin ...................................................................................... 300 mA Maximum current into VDD pin ......................................................................................... 250 mA Input clamp current, IIK (VI < 0 or VI > VDD).................................................................... ± 20 mA Output clamp current, IOK (VO < 0 or VO > VDD) ............................................................. ± 20 mA Maximum output current sunk by any I/O pin..................................................................... 25 mA Maximum output current sourced by any I/O pin ............................................................... 25 mA Maximum current sunk by PORTA, PORTB, and PORTE (combined)............................. 200 mA Maximum current sourced by PORTA, PORTB, and PORTE (combined) ....................... 200 mA Maximum current sunk by PORTC and PORTD (combined) ........................................... 200 mA Maximum current sourced by PORTC and PORTD (combined)...................................... 200 mA Maximum current sunk by PORTF and PORTG (combined) ........................................... 100 mA Maximum current sourced by PORTF and PORTG (combined) ...................................... 100 mA Note 1: Power dissipation is calculated as follows: Pdis = VDD x {IDD - IOH} + {(VDD - VOH)xIOH} + (VOlxIOL) 2: Voltage spikes below VSS at the MCLR/VPP pin, inducing currents greater than 80 mA, may cause latch-up. Thus, a series resistor of 50-100Ω should be used when applying a “low” level to the MCLR/VPP pin, rather than pulling this pin directly to VSS. † NOTICE: Stresses above those listed under “Absolute Maximum Ratings” may cause permanent damage to the device. This is a stress rating only and functional operation of the device at those or any other conditions above those indicated in the operation listings of this specification is not implied. Exposure to maximum rating conditions for extended periods may affect device reliability. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-4  2000 Microchip Technology Inc. 32.3 Voltage vs Frequency Graph Windowed devices are superset devices with all oscillator configurations tested to the specification ranges of the C and LC devices. The temperature range that the device is tested to should be considered commercial, though at a later time, they may be tested to industrial or extended temperature levels. Figure 32-1 and Figure 32-2 show proposed voltage vs frequency graphs for the C and LC devices. Battery applications usually require an extended voltage range. Devices marked LC have an extended voltage range. Note: Devices that are designated Engineering Sample are tested to the current engineering test program at time of the device testing. There is no implied warranty that these devices have been tested to any or all specifications in the Device Data Sheet. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-5 Section 32. Electrical Specifications Electrical Specifications 32 The voltage vs frequency graphs show what is the maximum frequency of operation for a given voltage. Figure 32-1 is for a C device, while Figure 32-2 is for an LC device. Notice that for Figure 32-2, there is a slope from 6MHz to 40 MHz. An equation is given in the figure which will allow you to calculate the maximum frequency of operation for a given voltage. Figure 32-1: Example PIC18CXXX Voltage Frequency Graph Figure 32-2: Example PIC18LCXXX Voltage Frequency Graph Frequency Voltage 6.0 V 5.5 V 4.5 V 4.0 V 2.0 V 40 MHz 5.0 V 3.5 V 3.0 V 2.5 V PIC18CXXX 4.2V Frequency Voltage 6.0 V 5.5 V 4.5 V 4.0 V 2.0 V 40 MHz 5.0 V 3.5 V 3.0 V 2.5 V PIC18LCXXX FMAX = (20.0 MHz/V) (VDDAPPMIN - 2.5 V) + 6 MHz 6 MHz 4.2V Note: VDDAPPMIN is the minimum voltage of the PICmicro® device in the application. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-6  2000 Microchip Technology Inc. 32.4 Device Voltage Specifications These specifications relate to the device VDD, power-up, and function. Supply Voltage is the voltage level that must be applied to the device VDD pins for the proper functional operation. RAM Data Retention Voltage is the minimum level that the device voltage may be at and still retain the RAM’s data value. VDD Start Voltage to ensure the internal Power-on Reset signal, is the level that VDD must start from, to ensure that the POR circuitry will operate properly. VDD Rise Rate to ensure internal Power-on Reset signal, is the minimum slope that VDD must rise to cause the POR circuitry to trip. Brown-out Reset Voltage is the voltage range where the brown-out circuitry may trip. When the BOR circuitry trips, the device will either be in Brown-out Reset, or has just come out of Brown-out Reset. Table 32-2: Example DC Characteristics DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial -40°C ≤ TA ≤ +125°C for extended Param No. Symbol Characteristic Min Typ† Max Units Conditions VDD Supply Voltage D001 PIC18CXXX 4.2 — 5.5 V PIC18LCXXX 2.5 — 5.5 V HS, XT, RC and LP osc mode D002 VDR RAM Data Retention Voltage (1) 1.5 — — V D003 VPOR VDD Start Voltage to ensure internal Power-on Reset signal — — 0.7 V See section on Power-on Reset for details D004 SVDD VDD Rise Rate to ensure internal Power-on Reset signal 0.05 — — V/ms See section on Power-on Reset for details VBOR Brown-out Reset Voltage D005 BORV1:BORV0 = 11 1.8 — 1.91 V For PIC18LCxxx VDDMIN = 1.8V BORV1:BORV0 = 11 2.5 — 2.66 For PIC18LCxxx VDDMIN > 1.8V BORV1:BORV0 = 10 2.7 — 2.86 BORV1:BORV0 = 01 4.2 — 4.46 BORV1:BORV0 = 00 4.5 — 4.78 D007 VBHYS Brown-out Hysteresis 30 — 100 mV Note 1: This is the limit to which VDD can be lowered in SLEEP mode or during a device RESET without losing RAM data. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-7 Section 32. Electrical Specifications Electrical Specifications 32 32.5 Device Current Specifications IDD is referred to as supply current and is the current (I) consumed by the device when in operating mode. This test is taken with all I/O as inputs, either pulled high or low. That is, there are no floating inputs, nor are any pins driving an output (with a load). IPD is referred to as power-down current and is the current (I) consumed by the device when in SLEEP mode (power-down), referred to as power-down current. These tests are taken with all I/O as inputs, either pulled high or low. That is, there are no floating inputs, nor are any pins driving an output (with a load), weak pull-ups are disabled. A device may have certain features and modules that can operate while the device is in SLEEP mode. Some of these modules are: • Watchdog Timer (WDT) • Low Voltage Detect (LVD) • Brown-out Reset (BOR) circuitry • Timer1 Oscillator • Analog to Digital converter • Comparators • Voltage Reference • CAN Module When all features are disabled, the device will consume the lowest possible current (the leakage current). If any of these features are operating while the device is in SLEEP, a higher current will occur. The difference in current between the lowest power mode (everything off) and only that one feature enabled (such as the WDT), is what we call the Module Differential Current. If more then one feature is enabled, then the expected current can easily be calculated as: the base current (everything disabled and in SLEEP mode) plus all Module Differential Currents (delta currents). Example 32-1 shows an example of calculating the typical currents for a device at 5V, with the WDT and Timer1 oscillator enabled. Example 32-1: IPD Calculations with WDT and Timer1 Oscillator Enabled (@ 5V) Note: Some modules (such as the Brown-out Reset and Low Voltage Detect) use a common resource (an internal reference voltage generator). This resource may consume a significant percentage of the total modules current when enabled. Since 2 modules are using this, the total current will be less then the calculation. Base Current 14 nA ; Device leakage current WDT Delta Current 14 µA ; 14 µA - 14 nA = 14 µA TMR1 Delta Current 22 µA ; 22 µA - 14 nA = 22 µA Total SLEEP Current 36 µA ; 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-8  2000 Microchip Technology Inc. Table 32-3: Example DC Characteristics DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial -40°C ≤ TA ≤ +125°C for extended Param No. Symbol Characteristic Min Typ Max Units Conditions D010 IDD Supply Current (2,4) — — 4 µA XT, RC, RCIO osc configurations FOSC = 4 MHz, VDD = 4.2V D010A — — 48 mA LP osc configuration FOSC = 32 kHz, VDD = 4.2V D010C — — 45 mA EC, ECIO osc configurations, Fosc = 40 MHz, VDD = 5.5V D013 — — 50 mA HS osc configurations Fosc = 25 MHz, VDD = 5.5V D013 — — 50 mA HS4 osc configuration Fosc = 10 MHz, VDD = 5.5V D014 — — — — 48 TBD µA µA OSCB osc configuration FOSC = 32 kHz, VDD = 4.2V FOSC = 32 kHz, VDD = 4.2V, 25°C IPD Power-down Current (3) D020 — — <1 — TBD 36 µA µA VDD = 4.2V, -40°C to +85°C VDD = 5.5V, -40°C to +85°C D020A — — TBD µA VDD = 4.2V, 25°C D021B — — — — TBD 42 µA µA VDD = 4.2V, -40°C to +125°C VDD = 5.5V, -40°C to +125°C Legend: Shading of rows is to assist in readability of the table. Note 1: Not applicable. 2: The supply current is mainly a function of the operating voltage and frequency. Other factors, such as I/O pin loading and switching rate, oscillator type, internal code execution pattern and temperature, also have an impact on the current consumption. The test conditions for all IDD measurements in active operation mode are: OSC1 = external square wave, from rail to rail; all I/O pins set to inputs, pulled to VDD MCLR = VDD; WDT enabled/disabled as specified. 3: The power-down current in SLEEP mode does not depend on the oscillator type. Power-down current is measured with the part in SLEEP mode, with all I/O pins set to inputs, tied to VDD or VSS, and all features that add delta current disabled (such as WDT, Timer1 Oscillator, ...). 4: For RC osc configuration, current through REXT is not included. The current through the resistor can be estimated by the formula Ir = VDD/2REXT (mA) with REXT in kOhm. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-9 Section 32. Electrical Specifications Electrical Specifications 32 Module Differential Current D022 ∆IWDT Watchdog Timer — — — — — — — — — — 25 TBD TBD 12 TBD µA µA µA µA µA VDD = 5.5V, -40°C to +85°C VDD = 5.5V, -40°C to +125°C VDD = 4.2V, 25°C VDD = 2.5V VDD = 2.5V, +25°C D022A ∆IBOR Brown-out Reset — — — — — — — — — — 50 TBD TBD 12 TBD µA µA µA µA µA VDD = 5.5V, -40°C to +85°C VDD = 5.5V, -40°C to +125°C VDD = 4.2V, 25°C VDD = 2.5V VDD = 2.5V, +25°C D022B ∆ILVD Low Voltage Detect — — — — — — — — — — TBD TBD TBD 50 TBD µA µA µA µA µA VDD = 4.2V, -40°C to +85°C VDD = 4.2V, -40°C to +125°C VDD = 4.2V, +25°C VDD = 2.5V VDD = 2.5V, +25°C D022C ∆IDDC A/D Converter Current — — — — — — — — — — TBD TBD TBD TBD TBD µA µA µA µA µA VDD = 5.5V, -40°C to +85°C VDD = 5.5V, -40°C to +125°C VDD = 4.2V, 25°C VDD = 2.5V VDD = 2.5V, +25°C D025 ∆IOSCB Timer1 Oscillator — — — — — — — — — — TBD TBD TBD 3 TBD µA µA µA µA µA VDD = 4.2V, -40°C to +85°C VDD = 4.2V, -40°C to +125°C VDD = 4.2V, 25°C VDD = 2.5V VDD = 2.5V, +25°C Table 32-3: Example DC Characteristics (Continued) DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial -40°C ≤ TA ≤ +125°C for extended Param No. Symbol Characteristic Min Typ Max Units Conditions Legend: Shading of rows is to assist in readability of the table. Note 1: Not applicable. 2: The supply current is mainly a function of the operating voltage and frequency. Other factors, such as I/O pin loading and switching rate, oscillator type, internal code execution pattern and temperature, also have an impact on the current consumption. The test conditions for all IDD measurements in active operation mode are: OSC1 = external square wave, from rail to rail; all I/O pins set to inputs, pulled to VDD MCLR = VDD; WDT enabled/disabled as specified. 3: The power-down current in SLEEP mode does not depend on the oscillator type. Power-down current is measured with the part in SLEEP mode, with all I/O pins set to inputs, tied to VDD or VSS, and all features that add delta current disabled (such as WDT, Timer1 Oscillator, ...). 4: For RC osc configuration, current through REXT is not included. The current through the resistor can be estimated by the formula Ir = VDD/2REXT (mA) with REXT in kOhm. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-10  2000 Microchip Technology Inc. 32.6 Input Threshold Levels The Input Low Voltage (VIL) is the maximum voltage level that will be read as a logic ’0’. An input may not read a ’0’ at a voltage level above this. All designs should be to the specification, since device to device (and to a much lesser extent pin to pin) variations will cause this level to vary. The Input High Voltage (VIH) is the minimum voltage level that will be read as a logic ’1’. An input may not read a ’1’ at a voltage level below this. All designs should be to the specification, since device to device (and to a much lesser extent pin to pin) variations will cause this level to vary. The I/O pins with TTL levels are shown with two specifications. One is the industry standard TTL specification, which is specified for the voltage range of 4.5V to 5.5V. The other specifies operation over the entire voltage range of the device. The better of these two specifications may be used in the design (see Note 2 in Table 32-4). Table 32-4: Example DC Characteristics DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial -40°C ≤ TA ≤ +125°C for extended Operating voltage VDD range as described in DC spec Table 32-2. Param No. Symbol Characteristic Min Max Units Conditions VIL Input Low Voltage I/O ports: D030 with TTL buffer VSS 0.15VDD V For entire VDD range (2) D030A — 0.8 V 4.5V ≤ VDD ≤ 5.5V (2) D031 with Schmitt Trigger buffer RC3 and RC4 VSS VSS 0.2VDD 0.3VDD V V D032 MCLR VSS 0.2VDD V D032A OSC1 (in XT, HS and LP modes) and T1OSI VSS 0.3VDD V D033 OSC1 (in RC mode) (1) VSS 0.2VDD V VIH Input High Voltage I/O ports: D040 with TTL buffer 0.25VDD + 0.8V VDD V For entire VDD range (2) D040A 2.0 VDD V 4.5V ≤ VDD ≤ 5.5V (2) D041 with Schmitt Trigger buffer RC3 and RC4 0.8VDD 0.7VDD VDD VDD V V D042 MCLR 0.8VDD VDD V D042A OSC1 (in XT, HS and LP modes) and T1OSI 0.7VDD VDD V D043 OSC1 (RC mode) (1) 0.9VDD VDD V D050 VHYS Hysteresis of Schmitt Trigger Inputs TBD TBD V Note 1: In RC oscillator configuration, the OSC1/CLKIN pin is a Schmitt Trigger input. It is not recommended that the PICmicro be driven with an external clock while in RC mode. 2: The better of the two specifications may be used. For VIL, this would be the higher voltage and for VIH, this would be the lower voltage. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-11 Section 32. Electrical Specifications Electrical Specifications 32 32.7 I/O Current Specifications The PORT Weak Pull-up Current is the additional current consumed when the weak pull-ups are enabled. Leakage Currents are the currents that the device consumes, since the devices are manufactured in the real world and do not adhere to their ideal characteristics. Ideally, there should be no current on an input, but due to the real world, there is always some parasitic path that consumes negligible current. Table 32-5: Example DC Characteristics DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial and -40°C ≤ TA ≤ +125°C for extended Operating voltage VDD range as described in DC spec Table 32-2. Param No. Symbol Characteristic Min Max Units Conditions IIL Input Leakage Current (2,3) D060 I/O ports — ±1 µA Vss ≤ VPIN ≤ VDD, Pin at hi-impedance D061 MCLR — ±5 µA Vss ≤ VPIN ≤ VDD D063 OSC1 — ±5 µA Vss ≤ VPIN ≤ VDD Weak Pull-up Current D070 IPURB PORTB weak pull-up current 50 400 µA VDD = 5V, VPIN = VSS Note 1: Not applicable. 2: The leakage current on the MCLR pin is strongly dependent on the applied voltage level. The specified levels represent normal operating conditions. Higher leakage current may be measured at different input voltages. 3: Negative current is defined as current sourced by the pin. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-12  2000 Microchip Technology Inc. 32.8 Output Drive Levels The Output Low Voltage (VOL) is the pin’s output voltage for a low level. The VOL of an I/O pin is dependent on the current sunk by that pin. If an I/O pin is shorted to VDD, no matter the drive capability of the I/O pin, a low level would not be reached (and the device would consume excessive drive current). The VOL is the output voltage that the I/O pin will drive, given the I/O does not need to sink more then the IOL current (at the specified device voltage), as specified in the conditions portion of the specification. The Output High Voltage (VOH) is the pin’s output voltage for a high level. The VOH of an I/O pin is dependent on the current sourced by that pin. If an I/O pin is shorted to VSS, no matter the drive capability of the I/O pin, a high level would not be reached (and the device would consume excessive drive current). The VOH is the output voltage that the I/O pin will drive, given the I/O does not need to source more then the IOH current (at the specified device voltage), as specified in the conditions portion of the specification. Table 32-6: Example DC Characteristics DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial and -40°C ≤ TA ≤ +125°C for extended Operating voltage VDD range as described in DC spec Table 32-2. Param No. Symbol Characteristic Min Max Units Conditions VOL Output Low Voltage D080 I/O ports — 0.6 V IOL = 8.5 mA, VDD = 4.5V, -40°C to +85°C D080A — 0.6 V IOL = 7.0 mA, VDD = 4.5V, -40°C to +125°C D083 OSC2/CLKOUT (RC mode) — 0.6 V IOL = 1.6 mA, VDD = 4.5V, -40°C to +85°C D083A — 0.6 V IOL = 1.2 mA, VDD = 4.5V, -40°C to +125°C VOH Output High Voltage (1) D090 I/O ports VDD - 0.7 — V IOH = -3.0 mA, VDD = 4.5V, -40°C to +85°C D090A VDD - 0.7 — V IOH = -2.5 mA, VDD = 4.5V, -40°C to +125°C D092 OSC2/CLKOUT (RC mode) VDD - 0.7 — V IOH = -1.3 mA, VDD = 4.5V, -40°C to +85°C D092A VDD - 0.7 — V IOH = -1.0 mA, VDD = 4.5V, -40°C to +125°C D150 VOD Open-drain High Voltage — 7.5 V RA4 pin Note 1: Negative current is defined as current sourced by the pin. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-13 Section 32. Electrical Specifications Electrical Specifications 32 32.9 I/O Capacitive Loading These loadings affect the specifications for the timing specifications. If the loading in your application is different, then you will need to determine how this will affect the characteristics of the device in your system. Capacitances less then these specifications should not have an effect on a system. Table 32-7: Example DC Characteristics DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial and -40°C ≤ TA ≤ +125°C for extended Operating voltage VDD range as described in DC spec Table 32-2. Param No. Symbol Characteristic Min Typ† Max Units Conditions Capacitive Loading Specs on Output Pins D101 CIO All I/O pins and OSC2 (in RC mode) — — 50 pF To meet the Timing Specifications of the Device D102 CB SCL, SDA — — 400 pF In I2C mode 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-14  2000 Microchip Technology Inc. 32.10 Low Voltage Detect (LVD) Low Voltage Detect is internal circuitry which will set a flag when the device voltage crosses the specified trip point. Figure 32-3: Low-Voltage Detect Characteristics Table 32-8: Example Low Voltage Detect Requirements Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial and -40°C ≤ TA ≤ +125°C for extended Operating voltage VDD range as described in DC spec Table 32-2. Param No. Symbol Characteristic Min Max Units Conditions D420 VLVD LVD Voltage LVDL3:LVDL0 = 0100 2.5 2.66 V LVDL3:LVDL0 = 0101 2.7 2.86 V LVDL3:LVDL0 = 0110 2.8 2.98 V LVDL3:LVDL0 = 0111 3.0 3.2 V LVDL3:LVDL0 = 1000 3.3 3.52 V LVDL3:LVDL0 = 1001 3.5 3.72 V LVDL3:LVDL0 = 1010 3.6 3.84 V LVDL3:LVDL0 = 1011 3.8 4.04 V LVDL3:LVDL0 = 1100 4.0 4.26 V LVDL3:LVDL0 = 1101 4.2 4.46 V LVDL3:LVDL0 = 1110 4.5 4.78 V VLVD LVDIF VDD (LVDIF set by hardware) (LVDIF can be cleared in software) 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-15 Section 32. Electrical Specifications Electrical Specifications 32 32.11 EPROM/FLASH/Data EEPROM Table 32-9 shows the specifications for programming of the internal EPROM program memory. Table 32-10 shows the specifications of the FLASH program memory and Data EEPROM. Table 32-9: Example Program Memory Programming Requirements Table 32-10: Example Data EEPROM/Flash Characteristics DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +40°C Operating voltage VDD range as described in DC spec Table 32-2. Param. No. Sym Characteristic Min Max Units Conditions Internal Program Memory Programming Specs (1) D110 D111 D112 D113 D114 D115 VPP VDDP IPP IDDP TPROG TERASE Voltage on MCLR/VPP pin Supply voltage during programming Current into MCLR/VPP pin Supply current during programming Programming pulse width EPROM erase time Device operation ≤ 3V Device operation ≥ 3V 12.75 4.75 — — 100 4 TBD 13.25 5.25 50 30 1000 — — V V mA mA µs hrs hrs (Note 2) Terminated via internal/external interrupt or a RESET See Table 32-3 See Table 32-3 Note 1: These specifications are for the programming of the on-chip program memory EEPROM through the use of the table write instructions. The complete programming specifications can be found in: PIC18CXXX Programming Specifications (Literature number DS39028). 2: The MCLR/VPP pin may be kept in this range at times other than programming, but is not recommended. DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature 0°C ≤ TA ≤ +70°C for commercial, -40°C ≤ TA ≤ +85°C for industrial and -40°C ≤ TA ≤ +125°C for extended Operating voltage VDD range as described in DC spec Table 32-2. Param No. Symbol Characteristic Min Typ† Max Units Conditions Data EEPROM Memory D120 ED Endurance 1M 10M — E/W 25°C at 5V D121 VDRW VDD for read/write VMIN — VMAX V VMIN = Minimum operating voltage VMAX = Maximum operating voltage D122 TDEW Erase/Write cycle time — — 10 ms Program Flash Memory D130 EP Endurance 100 1000 — E/W D131 VPR VDD for read VMIN — VMAX V VMIN = Minimum operating voltage VMAX = Maximum operating voltage D132 VPEW VDD for erase/write 4.5 — 5.5 V D133 TPEW Erase/Write cycle time — — 10 ms † Data in “Typ” column is at 5.0V, 25°C unless otherwise stated. These parameters are for design guidance only and are not tested. Legend: E/W means Erase/Write cycles. 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-16  2000 Microchip Technology Inc. 32.12 Comparators and Voltage Reference Table 32-11: Example Comparator Characteristics Table 32-12: Example Voltage Reference Characteristics DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial and -40°C ≤ TA ≤ +125°C for extended Operating voltage VDD range as described in DC spec Table 32-2. Param No. Symbol Characteristics Min Max Units Comments D300 VIOFF Input offset voltage — ± 10 mV D301 VICM Input common mode voltage 0 VDD - 1.5 V D302 CMRR Common Mode Rejection Ratio 35 — db 300 TRESP Response Time (1) PIC18CXXX — 400 ns 300A PIC18LCXXX — 600 ns 301 TMC2OV Comparator Mode Change to Output Valid — 10 µs Note 1: Response time measured with one comparator input at (VDD - 1.5)/2, while the other input transitions from VSS to VDD. DC CHARACTERISTICS Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial and -40°C ≤ TA ≤ +125°C for extended Operating voltage VDD range as described in DC spec Table 32-2. Param No. Symbol Characteristics Min Typ Max Units Comments D310 VRES Resolution VDD/24 — VDD/32 V D311 VRAA Absolute Accuracy — — — — 1/4 1/2 LSb LSb Low Range (VRR = 1) High Range (VRR = 0) D312 VRUR Unit Resistor Value (R) — 2k — Ω 310 TSET Settling Time (1) — — 10 µs Note 1: Settling time measured while VRR = 1 and VR3:VR0 transitions from 0000 to 1111. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-17 Section 32. Electrical Specifications Electrical Specifications 32 Table 32-13: Example Fixed Voltage Reference Characteristics Standard Operating Conditions (unless otherwise stated) Operating temperature -40°C ≤ TA ≤ +85°C for industrial and -40°C ≤ TA ≤ +125°C for extended Operating voltage VDD range as described in DC spec Table 32-2. Param No. Symbol Characteristic Min Typ Max Units Conditions D400 VRL Output Voltage 2.0 2.048 2.1 V VDD ≥ 2.5V VRH 4.0 4.096 4.2 V VDD ≥ 4.5V D402 TCVOUT Ouput Voltage Drift — 15 50 ppm/°C (Note 1) D403 En Output Noise Voltage — TBD — µVp-p 0.1 Hz to 10 Hz — TBD — 10 Hz to 10 kHz D404 IVREFSO External Load Source — — 5 mA D405 IVREFSI External Load Sink — — -5 mA D406 Load Regulation — — TBD mV/mA Isource = 0 mA to 5 mA — — TBD Isink = 0 mA to 5 mA D407 Line Regulation — — 50 µV/V D401A VRL Quiescent Supply Current — 30 50 µA VRH, BOR, and LVD disabled. No load on VRL. D401B VRH Quiescent Supply Current — 30 50 µA VRL, BOR, and LVD disabled. No load on VRH. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-18  2000 Microchip Technology Inc. 32.13 Timing Parameter Symbology The timing parameter symbols have been created with one of the following formats: Figure 32-4: Example Load Conditions 1. TppS2ppS 3. TCC:ST (I2C specifications only) 2. TppS 4. Ts (I2 C specifications only) T F Frequency T Time Lowercase letters (pp) and their meanings: pp cc CCP1 osc OSC1 ck CLKOUT rd RD cs CS rw RD or WR di SDI sc SCK do SDO ss SS dt Data in t0 T0CKI io I/O port t1 T1CKI mc MCLR wr WR Uppercase letters and their meanings: S F Fall P Period H High R Rise I Invalid (Hi-impedance) V Valid L Low Z Hi-impedance I 2 C only AA Output Access High High BUF Bus free Low Low TCC:ST (I2C specifications only) CC HD Hold SU Setup ST DAT DATA input hold STO STOP condition STA START condition VDD/2 CL RL Pin Pin VSS VSS CL RL = 464Ω CL = 50 pF for all pins except OSC2/CLKOUT (works for I/O pin multiplexed on to OSC2/CLKOUT) Load Condition 1 Load Condition 2 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-19 Section 32. Electrical Specifications Electrical Specifications 32 32.14 Example External Clock Timing Waveforms and Requirements Figure 32-5: Example External Clock Timing Waveforms Table 32-14: Example External Clock Timing Requirements Param. No. Symbol Characteristic Min Max Units Conditions 1A Fosc External CLKIN Frequency (1) DC 4 MHz XT osc DC 40 MHz HS osc 4 10 MHz HS4 osc DC DC 40 40 kHz MHz LP osc EC Oscillator Frequency (1) DC 4 MHz RC osc 0.1 4 MHz XT osc 4 25 MHz HS osc 4 10 MHz HS4 osc 5 200 kHz LP osc mode 1 Tosc External CLKIN Period (1) 250 — ns XT and RC osc 40 — ns HS osc 100 — ns HS4 osc 5 5 — — µs ns LP osc EC Oscillator Period (1) 250 — ns RC osc 250 10,000 ns XT osc 100 40 10,000 100 ns ns HS osc HS4 osc 5 — µs LP osc 2 TCY Instruction Cycle Time (1) 100 — ns TCY = 4/FOSC 3 TosL, TosH External Clock in (OSC1) High or Low Time 30 — ns XT osc 2.5 — µs LP osc 10 — ns HS osc 4 TosR, TosF External Clock in (OSC1) Rise or Fall Time — 20 ns XT osc — 50 ns LP osc — 7.5 ns HS osc Note 1: Instruction cycle period (TCY) equals four times the input oscillator time-base period. All specified values are based on characterization data for that particular oscillator type under standard operating conditions with the device executing code. Exceeding these specified limits may result in an unstable oscillator operation and/or higher than expected current consumption. All devices are tested to operate at "min." values with an external clock applied to the OSC1/CLKIN pin. When an external clock input is used, the "Max." cycle time limit is "DC" (no clock) for all devices. OSC1 CLKOUT Q4 Q1 Q2 Q3 Q4 Q1 1 2 3 3 4 4 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-20  2000 Microchip Technology Inc. 32.15 Example Phase Lock Loop (PLL) Timing Waveforms and Requirements Table 32-15: Example PLL Clock Timing Specification (VDD = 4.2V - 5.5V) Param No. Symbol Characteristic Min Max Units Conditions 7 TPLL PLL Start-up Time (Lock Time) — 2 ms ∆CLK CLKOUT Stability (Jitter) using PLL -2 +2 % 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-21 Section 32. Electrical Specifications Electrical Specifications 32 Figure 32-6: Example CLKOUT and I/O Timing Waveforms Table 32-16: Example CLKOUT and I/O Timing Requirements Param. No. Symbol Characteristic Min Typ Max Units Conditions 10 TosH2ckL OSC1↑ to CLKOUT↓ — 75 200 ns (Note 1) 11 TosH2ckH OSC1↑ to CLKOUT↑ — 75 200 ns (Note 1) 12 TckR CLKOUT rise time — 35 100 ns (Note 1) 13 TckF CLKOUT fall time — 35 100 ns (Note 1) 14 TckL2ioV CLKOUT ↓ to Port out valid — — 0.5TCY + 20 ns (Note 1) 15 TioV2ckH Port in valid before CLKOUT ↑ 0.25TCY + 25 — — ns (Note 1) 16 TckH2ioI Port in hold after CLKOUT ↑ 0 — — ns (Note 1) 17 TosH2ioV OSC1↑ (Q1 cycle) to Port out valid — 50 150 ns 18 TosH2ioI OSC1↑ (Q2 cycle) to Port input invalid (I/O in hold time) PIC18CXXX 100 — — ns 18A PIC18LCXXX 200 — — ns 19 TioV2osH Port input valid to OSC1↑ (I/O in setup time) 0 — — ns 20 TioR Port output rise time PIC18CXXX — 10 25 ns 20A PIC18LCXXX — — 60 ns 21 TioF Port output fall time PIC18CXXX — 10 25 ns 21A PIC18LCXXX — — 60 ns 22†† Tinp INT pin high or low time TCY — — ns 23†† Trbp RB<7:4> change INT high or low time TCY — — ns 24†† Trcp RC<7:4> change INT high or low time 20 ns †† These parameters are asynchronous events not related to any internal clock edges. Note 1: Measurements are taken in RC Mode where CLKOUT output is 4 x TOSC. Note: Refer to Figure 32-4 for load conditions. OSC1 CLKOUT I/O Pin (input) I/O Pin (output) Q4 Q1 Q2 Q3 10 13 14 17 20, 21 19 18 15 11 12 16 old value new value 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-22  2000 Microchip Technology Inc. 32.16 Example Power-up and RESET Timing Waveforms and Requirements Figure 32-7: Example RESET, Watchdog Timer, Oscillator Start-up Timer and Power-up Timer Timing Waveforms Figure 32-8: Brown-out Reset Timing Table 32-17: Example RESET, Watchdog Timer, Oscillator Start-up Timer, Brown-out Reset, and Power-up Timer Requirements Param. No. Symbol Characteristic Min Typ Max Units Conditions 30 TmcL MCLR Pulse Width (low) 2 — — µs 31 TWDT Watchdog Timer Time-out Period (No Prescaler) 7 18 33 ms 32 TOST Oscillation Start-up Timer Period 1024TOSC — 1024TOSC ns TOSC = OSC1 period 33 TPWRT Power up Timer Period 28 72 132 ms 34 TIOZ I/O Hi-impedance from MCLR Low or Watchdog Timer Reset — 2 — µs 35 TBOR Brown-out Reset Pulse Width 200 — — µs VDD ≤ VBOR (See D005) 36 TIVRST Time for Internal Reference Voltage to become stable — 20 50 µs VDD MCLR Internal POR PWRT Time-out OSC Time-out Internal RESET Watchdog Timer RESET 33 32 30 31 34 I/O Pins 34 Note: Refer to Figure 32-4 for load conditions. VDD VBOR 35 VBGAP = 1.2V VIRVST Enable Internal Reference Voltage Internal Reference Voltage stable 36 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-23 Section 32. Electrical Specifications Electrical Specifications 32 32.17 Example Timer0 and Timer1 Timing Waveforms and Requirements Figure 32-9: Example Timer0 and Timer1 External Clock Timings Waveforms Table 32-18: Example Timer0 and Timer1 External Clock Requirements Param No. Symbol Characteristic Min Max Units Conditions 40 Tt0H T0CKI High Pulse Width No Prescaler 0.5TCY + 20 — ns With Prescaler 10 — ns 41 Tt0L T0CKI Low Pulse Width No Prescaler 0.5TCY + 20 — ns With Prescaler 10 — ns 42 Tt0P T0CKI Period No Prescaler TCY + 10 — ns With Prescaler Greater of: 20 ns or TCY + 40 N — ns N = prescale value (1, 2, 4,..., 256) 45 Tt1H T1CKI High Time Synchronous, no prescaler 0.5TCY + 20 — ns Synchronous, with prescaler PIC18CXXX 10 — ns PIC18LCXXX 25 — ns Asynchronous PIC18CXXX 30 — ns PIC18LCXXX 50 — ns 46 Tt1L T1CKI Low Time Synchronous, no prescaler 0.5TCY + 5 — ns Synchronous, with prescaler PIC18CXXX 10 — ns PIC18LCXXX 25 — ns Asynchronous PIC18CXXX 30 — ns PIC18LCXXX TBD TBD 47 Tt1P T1CKI Input Period Synchronous Greater of: 20 ns or TCY + 40 N — ns N = prescale value (1, 2, 4, 8) Asynchronous 60 — ns Ft1 T1CKI oscillator input frequency range DC 50 kHz 48 Tcke2tmrI Delay from external T1CKI clock edge to timer increment 2Tosc 7Tosc ns Note: Refer to Figure 32-4 for load conditions. 46 47 45 48 41 42 40 T0CKI T1OSO/T1CKI TMR0 or TMR1 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-24  2000 Microchip Technology Inc. 32.18 Example CCP Timing Waveforms and Requirements Figure 32-10: Example Capture/Compare/PWM Timings Waveforms Table 32-19: Example Capture/Compare/PWM Requirements Param. No. Symbol Characteristic Min Max Units Conditions 50 TccL CCPx input low time No Prescaler 0.5TCY + 20 — ns With Prescaler PIC18CXXX 10 — ns PIC18LCXXX 20 — ns 51 TccH CCPx input high time No Prescaler 0.5TCY + 20 — ns With Prescaler PIC18CXXX 10 — ns PIC18LCXXX 20 — ns 52 TccP CCPx input period 3TCY + 40 N — ns N = prescale value (1, 4 or 16) 53 TccR CCPx output rise time PIC18CXXX — 25 ns PIC18LCXXX — 45 ns 54 TccF CCPx output fall time PIC18CXXX — 25 ns PIC18LCXXX — 45 ns Note: Refer to Figure 32-4 for load conditions. (Capture Mode) 50 51 52 53 54 CCPx CCPx (Compare or PWM Mode) 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-25 Section 32. Electrical Specifications Electrical Specifications 32 32.19 Example Parallel Slave Port (PSP) Timing Waveforms and Requirements Figure 32-11: Example Parallel Slave Port Timing Waveforms Table 32-20: Example Parallel Slave Port Requirements Param. No. Symbol Characteristic Min Max Units Conditions 62 TdtV2wrH Data-in valid before WR↑ or CS↑ (setup time) 20 25 — — ns ns Extended Temp range 63 TwrH2dtI WR↑ or CS↑ to data-in invalid (hold time) PIC18CXXX 20 — ns PIC18LCXXX 35 — ns 64 TrdL2dtV RD↓ and CS↓ to data-out valid — — 80 90 ns ns Extended Temp range 65 TrdH2dtI RD↑ or CS↓ to data-out invalid 10 30 ns 66 TibfINH Inhibit of the IBF flag bit being cleared from WR↑ or CS↑ — 3TCY ns Note: Refer to Figure 32-4 for load conditions. RE2/CS RE0/RD RE1/WR RD<7:0> 62 63 64 65 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-26  2000 Microchip Technology Inc. 32.20 Example SSP and Master SSP SPI Mode Timing Waveforms and Requirements Figure 32-12: Example SPI Master Mode Timing (CKE = 0) Table 32-21: Example SPI Mode Requirements (Master Mode, CKE = 0) Param. No. Symbol Characteristic Min Max Units Conditions 70 TssL2scH, TssL2scL SS↓ to SCK↓ or SCK↑ input TCY — ns 71 TscH SCK input high time (slave mode) Continuous 1.25TCY + 30 — ns 71A Single Byte 40 — ns (Note 1) 72 TscL SCK input low time (slave mode) Continuous 1.25TCY + 30 — ns 72A Single Byte 40 — ns (Note 1) 73 TdiV2scH, TdiV2scL Setup time of SDI data input to SCK edge 100 — ns 73A TB2B Last clock edge of Byte1 to the 1st clock edge of Byte2 1.5TCY + 40 — ns (Note 2) 74 TscH2diL, TscL2diL Hold time of SDI data input to SCK edge 100 — ns 75 TdoR SDO data output rise time PIC18CXXX — 25 ns PIC18LCXXX — 45 ns 76 TdoF SDO data output fall time — 25 ns 78 TscR SCK output rise time (master mode) PIC18CXXX — 25 ns PIC18LCXXX — 45 ns 79 TscF SCK output fall time (master mode) — 25 ns 80 TscH2doV, TscL2doV SDO data output valid after SCK edge PIC18CXXX — 50 ns PIC18LCXXX — 100 ns Note 1: Requires the use of Parameter # 73A. 2: Only if Parameter #s 71A and 72A are used. SS SCK (CKP = 0) SCK (CKP = 1) SDO SDI 70 71 72 73 74 75, 76 79 78 80 78 79 MSb LSb BIT6 - - - - - -1 MSb IN BIT6 - - - -1 LSb IN Note: Refer to Figure 32-4 for load conditions. 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-27 Section 32. Electrical Specifications Electrical Specifications 32 Figure 32-13: Example SPI Master Mode Timing (CKE = 1) Table 32-22: Example SPI Mode Requirements (Master Mode, CKE = 1) Param. No. Symbol Characteristic Min Max Units Conditions 71 TscH SCK input high time (slave mode) Continuous 1.25TCY + 30 — ns 71A Single Byte 40 — ns (Note 1) 72 TscL SCK input low time (slave mode) Continuous 1.25TCY + 30 — ns 72A Single Byte 40 — ns (Note 1) 73 TdiV2scH, TdiV2scL Setup time of SDI data input to SCK edge 100 — ns 73A TB2B Last clock edge of Byte1 to the 1st clock edge of Byte2 1.5TCY + 40 — ns (Note 2) 74 TscH2diL, TscL2diL Hold time of SDI data input to SCK edge 100 — ns 75 TdoR SDO data output rise time PIC18CXXX — 25 ns PIC18LCXXX — 45 ns 76 TdoF SDO data output fall time — 25 ns 78 TscR SCK output rise time (master mode) PIC18CXXX — 25 ns PIC18LCXXX — 45 ns 79 TscF SCK output fall time (master mode) — 25 ns 80 TscH2doV, TscL2doV SDO data output valid after SCK edge PIC18CXXX — 50 ns PIC18LCXXX — 100 ns 81 TdoV2scH, TdoV2scL SDO data output setup to SCK edge TCY — ns Note 1: Requires the use of Parameter # 73A. 2: Only if Parameter #s 71A and 72A are used. SS SCK (CKP = 0) SCK (CKP = 1) SDO SDI 81 71 72 74 75, 76 78 80 MSb 79 73 MSb IN BIT6 - - - - - -1 BIT6 - - - -1 LSb IN LSb Note: Refer to Figure 32-4 for load conditions. 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-28  2000 Microchip Technology Inc. Figure 32-14: Example SPI Slave Mode Timing (CKE = 0) Table 32-23: Example SPI Mode Requirements (Slave Mode Timing (CKE = 0) Param. No. Symbol Characteristic Min Max Units Conditions 70 TssL2scH, TssL2scL SS↓ to SCK↓ or SCK↑ input TCY — ns 71 TscH SCK input high time (slave mode) Continuous 1.25TCY + 30 — ns 71A Single Byte 40 — ns (Note 1) 72 TscL SCK input low time (slave mode) Continuous 1.25TCY + 30 — ns 72A Single Byte 40 — ns (Note 1) 73 TdiV2scH, TdiV2scL Setup time of SDI data input to SCK edge 100 — ns 73A TB2B Last clock edge of Byte1 to the 1st clock edge of Byte2 1.5TCY + 40 — ns (Note 2) 74 TscH2diL, TscL2diL Hold time of SDI data input to SCK edge 100 — ns 75 TdoR SDO data output rise time PIC18CXXX — 25 ns PIC18LCXXX — 45 ns 76 TdoF SDO data output fall time — 25 ns 77 TssH2doZ SS↑ to SDO output hi-impedance 10 50 ns 78 TscR SCK output rise time (master mode) PIC18CXXX — 25 ns PIC18LCXXX — 45 ns 79 TscF SCK output fall time (master mode) — 25 ns 80 TscH2doV, TscL2doV SDO data output valid after SCK edge PIC18CXXX — 50 ns PIC18LCXXX — 100 ns 83 TscH2ssH, TscL2ssH SS ↑ after SCK edge 1.5TCY + 40 — ns Note 1: Requires the use of Parameter # 73A. 2: Only if Parameter #s 71A and 72A are used. SS SCK (CKP = 0) SCK (CKP = 1) SDO SDI 70 71 72 73 74 75, 76 77 79 78 80 78 79 SDI MSb LSb BIT6 - - - - - -1 MSb IN BIT6 - - - -1 LSb IN 83 Note: Refer to Figure 32-4 for load conditions. 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-29 Section 32. Electrical Specifications Electrical Specifications 32 Figure 32-15: Example SPI Slave Mode Timing (CKE = 1) Table 32-24: Example SPI Slave Mode Mode Requirements (CKE = 1) Param. No. Symbol Characteristic Min Max Units Conditions 70 TssL2scH, TssL2scL SS↓ to SCK↓ or SCK↑ input TCY — ns 71 TscH SCK input high time (slave mode) Continuous 1.25TCY + 30 — ns 71A Single Byte 40 — ns (Note 1) 72 TscL SCK input low time (slave mode) Continuous 1.25TCY + 30 — ns 72A Single Byte 40 — ns (Note 1) 73A TB2B Last clock edge of Byte1 to the 1st clock edge of Byte2 1.5TCY + 40 — ns (Note 2) 74 TscH2diL, TscL2diL Hold time of SDI data input to SCK edge 100 — ns 75 TdoR SDO data output rise time PIC18CXXX — 25 ns PIC18LCXXX — 45 ns 76 TdoF SDO data output fall time — 25 ns 77 TssH2doZ SS↑ to SDO output hi-impedance 10 50 ns 78 TscR SCK output rise time (master mode) PIC18CXXX — 25 ns PIC18LCXXX — 45 ns 79 TscF SCK output fall time (master mode) — 25 ns 80 TscH2doV, TscL2doV SDO data output valid after SCK edge PIC18CXXX — 50 ns PIC18LCXXX — 100 ns 82 TssL2doV SDO data output valid after SS↓ edge PIC18CXXX — 50 ns PIC18LCXXX — 100 ns 83 TscH2ssH, TscL2ssH SS ↑ after SCK edge 1.5TCY + 40 — ns Note 1: Requires the use of Parameter # 73A. 2: Only if Parameter #s 71A and 72A are used. SS SCK (CKP = 0) SCK (CKP = 1) SDO SDI 70 71 72 82 74 75, 76 MSb BIT6 - - - - - -1 LSb 77 MSb IN BIT6 - - - -1 LSb IN 80 83 Note: Refer to Figure 32-4 for load conditions. 39500 18C Reference Manual.book Page 29 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-30  2000 Microchip Technology Inc. 32.21 Example SSP I2C Mode Timing Waveforms and Requirements Figure 32-16: Example SSP I2C Bus Start/Stop Bits Timing Waveforms Table 32-25: Example SSP I2C Bus Start/Stop Bits Requirements (Slave Mode) Param. No. Symbol Characteristic Min Max Units Conditions 90 TSU:STA START condition 100 kHz mode 4700 — ns Only relevant for repeated Setup time 400 kHz mode 600 — START condition 91 THD:STA START condition 100 kHz mode 4000 — ns After this period the first Hold time 400 kHz mode 600 — clock pulse is generated 92 TSU:STO STOP condition 100 kHz mode 4700 — ns Setup time 400 kHz mode 600 — 93 THD:STO STOP condition 100 kHz mode 4000 — ns Hold time 400 kHz mode 600 — Note: Refer to Figure 32-4 for load conditions. 91 93 SCL SDA START Condition STOP Condition 90 92 39500 18C Reference Manual.book Page 30 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-31 Section 32. Electrical Specifications Electrical Specifications 32 Figure 32-17: Example SSP I2 C Bus Data Timing Waveforms Table 32-26: Example SSP I2C bus Data Requirements (Slave Mode) Param. No. Symbol Characteristic Min Max Units Conditions 100 THIGH Clock high time 100 kHz mode 4.0 — µs PIC18CXXX must operate at a minimum of 1.5 MHz 400 kHz mode 0.6 — µs PIC18CXXX must operate at a minimum of 10 MHz SSP Module 1.5TCY — ns 101 TLOW Clock low time 100 kHz mode 4.7 — µs PIC18CXXX must operate at a minimum of 1.5 MHz 400 kHz mode 1.3 — µs PIC18CXXX must operate at a minimum of 10 MHz SSP Module 1.5TCY — ns 102 TR SDA and SCL rise time 100 kHz mode — 1000 ns 400 kHz mode 20 + 0.1Cb 300 ns Cb is specified to be from 10 to 400 pF 103 TF SDA and SCL fall time 100 kHz mode — 300 ns 400 kHz mode 20 + 0.1Cb 300 ns Cb is specified to be from 10 to 400 pF 90 TSU:STA START condition setup time 100 kHz mode 4.7 — µs Only relevant for repeated 400 kHz mode 0.6 — µs START condition 91 THD:STA START condition hold time 100 kHz mode 4.0 — µs After this period the first 400 kHz mode 0.6 — µs clock pulse is generated 106 THD:DAT Data input hold time 100 kHz mode 0 — ns 400 kHz mode 0 0.9 µs 107 TSU:DAT Data input setup time 100 kHz mode 250 — ns (Note 2) 400 kHz mode 100 — ns 92 TSU:STO STOP condition setup time 100 kHz mode 4.7 — µs 400 kHz mode 0.6 — µs 109 TAA Output valid from clock 100 kHz mode — 3500 ns (Note 1) 400 kHz mode — — ns 110 TBUF Bus free time 100 kHz mode 4.7 — µs Time the bus must be free before a new transmission can start 400 kHz mode 1.3 — µs D102 Cb Bus capacitive loading — 400 pF Note 1: As a transmitter, the device must provide this internal minimum delay time to bridge the undefined region (min. 300 ns) of the falling edge of SCL to avoid unintended generation of START or STOP conditions. 2: A fast-mode I2C-bus device can be used in a standard-mode I2C-bus system, but the requirement tsu;DAT ≥ 250 ns must then be met. This will automatically be the case if the device does not stretch the LOW period of the SCL signal. If such a device does stretch the LOW period of the SCL signal, it must output the next data bit to the SDA line. TR max. + tsu;DAT = 1000 + 250 = 1250 ns (according to the standard-mode I2C bus specification) before the SCL line is released. 90 91 92 100 101 103 106 107 109 109 110 102 SCL SDA In SDA Out Note: Refer to Figure 32-4 for load conditions. 39500 18C Reference Manual.book Page 31 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-32  2000 Microchip Technology Inc. 32.22 Example Master SSP I2C Mode Timing Waveforms and Requirements Figure 32-18: Example Master SSP I2C Bus Start/Stop Bits Timing Waveforms Table 32-27: Example Master SSP I2C Bus Start/Stop Bits Requirements Param. No. Symbol Characteristic Min Max Units Conditions 90 TSU:STA START condition 100 kHz mode 2(TOSC)(BRG + 1) § — ns Only relevant for repeated START condition Setup time 400 kHz mode 2(TOSC)(BRG + 1) § — 1 MHz mode (1) 2(TOSC)(BRG + 1) § — 91 THD:STA START condition 100 kHz mode 2(TOSC)(BRG + 1) § — ns After this period the first clock pulse is generated Hold time 400 kHz mode 2(TOSC)(BRG + 1) § — 1 MHz mode (1) 2(TOSC)(BRG + 1) § — 92 TSU:STO STOP condition 100 kHz mode 2(TOSC)(BRG + 1) § — Setup time 400 kHz mode 2(TOSC)(BRG + 1) § — ns 1 MHz mode (1) 2(TOSC)(BRG + 1) § — 93 THD:STO STOP condition 100 kHz mode 2(TOSC)(BRG + 1) § — Hold time 400 kHz mode 2(TOSC)(BRG + 1) § — ns 1 MHz mode (1) 2(TOSC)(BRG + 1) § — § For the value required by the I2C specification, please refer to Figure A-11 of the “Appendix.” Note 1: Maximum pin capacitance = 10 pF for all I2C pins. Note: Refer to Figure 32-4 for load conditions. 91 93 SCL SDA START Condition STOP Condition 90 92 39500 18C Reference Manual.book Page 32 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-33 Section 32. Electrical Specifications Electrical Specifications 32 Figure 32-19: Example Master SSP I2C Bus Data Timing Table 32-28: Example Master SSP I2C Bus Data Requirements Param. No. Symbol Characteristic Min Max Units Conditions 100 THIGH Clock high time 100 kHz mode 2(TOSC)(BRG + 1) § — ms 400 kHz mode 2(TOSC)(BRG + 1) § — ms 1 MHz mode (1) 2(TOSC)(BRG + 1) § — ms 101 TLOW Clock low time 100 kHz mode 2(TOSC)(BRG + 1) § — ms 400 kHz mode 2(TOSC)(BRG + 1) § — ms 1 MHz mode (1) 2(TOSC)(BRG + 1) § — ms 102 TR SDA and SCL rise time 100 kHz mode — 1000 ns Cb is specified to be from 400 kHz mode 20 + 0.1Cb 300 ns 10 to 400 pF 1 MHz mode (1) — 300 ns 103 TF SDA and SCL fall time 100 kHz mode — 300 ns Cb is specified to be from 400 kHz mode 20 + 0.1Cb 300 ns 10 to 400 pF 1 MHz mode (1) — 100 ns 90 TSU:STA START condition setup time 100 kHz mode 2(TOSC)(BRG + 1) § — ms Only relevant for repeated START condition 400 kHz mode 2(TOSC)(BRG + 1) § — ms 1 MHz mode (1) 2(TOSC)(BRG + 1) § — ms 91 THD:STA START condition hold time 100 kHz mode 2(TOSC)(BRG + 1) § — ms After this period the first 400 kHz mode 2(TOSC)(BRG + 1) § — ms clock pulse is generated 1 MHz mode (1) 2(TOSC)(BRG + 1) § — ms 106 THD:DAT Data input hold time 100 kHz mode 0 — ns 400 kHz mode 0 0.9 ms 1 MHz mode (1) TBD — ns 107 TSU:DAT Data input setup time 100 kHz mode 250 — ns (Note 2) 400 kHz mode 100 — ns 1 MHz mode (1) TBD — ns 92 TSU:STO STOP condition setup time 100 kHz mode 2(TOSC)(BRG + 1) § — ms 400 kHz mode 2(TOSC)(BRG + 1) § — ms 1 MHz mode (1) 2(TOSC)(BRG + 1) § — ms 109 TAA Output valid from clock 100 kHz mode — 3500 ns 400 kHz mode — 1000 ns 1 MHz mode (1) — — ns 110 TBUF Bus free time 100 kHz mode 4.7 ‡ — ms Time the bus must be free before a new transmission can start 400 kHz mode 1.3 ‡ — ms 1 MHz mode (1) TBD — ms D102 Cb Bus capacitive loading — 400 pF § For the value required by the I2C specification, please refer to Figure A-11 of the “Appendix.” Note 1: Maximum pin capacitance = 10 pF for all I2C pins. 2: A fast-mode I2C-bus device can be used in a standard-mode I2C-bus system, but parameter 107 ≥ 250 ns must then be met. This will automatically be the case if the device does not stretch the LOW period of the SCL signal. If such a device does stretch the LOW period of the SCL signal, it must output the next data bit to the SDA line. Parameter 102.+ parameter 107 = 1000 + 250 = 1250 ns (for 100 kHz-mode) before the SCL line is released. 90 91 92 100 101 103 106 107 109 109 110 102 SCL SDA In SDA Out Note: Refer to Figure 32-4 for load conditions. 39500 18C Reference Manual.book Page 33 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-34  2000 Microchip Technology Inc. 32.23 Example USART/SCI Timing Waveforms and Requirements Figure 32-20: Example USART Synchronous Transmission (Master/Slave) Timing Waveforms Table 32-29: Example USART Synchronous Transmission Requirements Figure 32-21: Example USART Synchronous Receive (Master/Slave) Timing Waveforms Table 32-30: Example USART Synchronous Receive Requirements Param. No. Symbol Characteristic Min Max Units Conditions 120 TckH2dtV SYNC XMIT (MASTER & SLAVE) Clock high to data out valid PIC18CXXX — 40 ns PIC18LCXXX — 100 ns 121 Tckrf Clock out rise time and fall time (Master Mode) PIC18CXXX — 20 ns PIC18LCXXX — 50 ns 122 Tdtrf Data out rise time and fall time PIC18CXXX — 20 ns PIC18LCXXX — 50 ns Param. No. Symbol Characteristic Min Max Units Conditions 125 TdtV2ckl SYNC RCV (MASTER & SLAVE) Data hold before CK ↓ (DT hold time) 10 — ns 126 TckL2dtl Data hold after CK ↓ (DT hold time) 15 — ns Note: Refer to Figure 32-4 for load conditions. 121 121 122 TX/CK Pin RX/DT Pin 120 Note: Refer to Figure 32-4 for load conditions. 125 126 TX/CK pin RX/DT pin 39500 18C Reference Manual.book Page 34 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-35 Section 32. Electrical Specifications Electrical Specifications 32 32.24 CAN Specifications Figure 32-22: Example CAN Timing Waveforms Table 32-31: Example CAN Timing Param. No. Symbol Characteristic Min Typ † Max Units Conditions 20 20A TioR Port output rise time (1) PIC18CXXX — 10 25 ns PIC18LCXXX — — 60 ns 21 21A TioF Port output fall time (1) PIC18CXXX — 10 25 ns PIC18LCXXX — — 60 ns 500 Tcanclk2ioV CANCLK ↓ or CANCLK ↑ to Port out valid -20 — 20 ns 501 TrxcanL Wake-up noise filter 50 — — ns † These parameters are asynchronous events not related to any internal clock edges. Note 1: The CAN Clock is driven by the I/O pin drivers, so it has the same timing specification. Note: Refer to Figure 32-4 for load conditions. 13 14 20, 21 12 Bit A Bit B Bit C CANTX0 Pin (output) CANTX1 Pin (TX1SRL = 1) (TX1EN = 1) (ENDRHI = 1) 39500 18C Reference Manual.book Page 35 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-36  2000 Microchip Technology Inc. 32.25 Example 8-bit A/D Timing Waveforms and Requirements Table 32-32: Example 8-bit A/D Converter Characteristics Param No. Symbol Characteristic Min Typ Max Units Conditions A01 NR Resolution (2) — — — — 8 8 bits bits VREF = VDD ≥ 3.0V VREF = VDD = 2.5V A02 EABS Total Absolute error (2) — — — — <±1 TBD LSb LSb VREF = VDD ≥ 3.0V VREF = VDD = 2.5V A03 EIL Integral linearity error (2) — — — — <±1 TBD LSb LSb VREF = VDD ≥ 3.0V VREF = VDD = 2.5V A04 EDL Differential linearity error (2) — — — — <±1 TBD LSb LSb VREF = VDD ≥ 3.0V VREF = VDD = 2.5V A05 EFS Full scale error (2) — — — — <±1 TBD LSb LSb VREF = VDD ≥ 3.0V VREF = VDD = 2.5V A06 EOFF Offset error (2) — — — — <±1 TBD LSb LSb VREF = VDD ≥ 3.0V VREF = VDD = 2.5V A10 — Monotonicity guaranteed (3) — VSS ≤ VAIN ≤ VREF A20 VREF Reference voltage 0V — AVDD V VREF delta when changing voltage levels on VREF inputs A20A (VREFH - VREFL) 3.0V — AVDD V Absolute minimum electrical specification to ensure 10-bit accuracy A21 VREF+ Reference voltage high AVSS + 3.0 AVDD + 0.3 V A22 VREF- Reference voltage low AVSS - 0.3 AVDD - 3.0 V A25 VAIN Analog input voltage AVSS - 0.3 — AVREF + 0.3 V A30 ZAIN Impedance of analog voltage source — — 10.0 kΩ A40 IAD A/D conversion current (VDD) PIC18CXXX — 180 — µA Average current consumption when A/D is on (1) PIC18LCXXX — 90 — µA A50 IREF VREF input current (2) 10 — 1000 µA During VAIN acquisition. Based on differential of VHOLD to VAIN to charge CHOLD. See the A/D Converter section. — — 10 µA During A/D Conversion cycle Note 1: When A/D is off, it will not consume any current other than minor leakage current. The power-down current spec includes any such leakage from the A/D module. VREF current is from RA3 pin or VDD pin, whichever is selected as reference input. 2: VSS ≤ VAIN ≤ VREF 3: The A/D conversion result either increases or remains constant as the analog input increases. 39500 18C Reference Manual.book Page 36 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-37 Section 32. Electrical Specifications Electrical Specifications 32 Figure 32-23: Example 8-bit A/D Conversion Timing Waveforms Table 32-33: Example 8-bit A/D Conversion Requirements Param No. Symbol Characteristic Min Max Units Conditions 130 TAD A/D clock period PIC18CXXX 1.6 — µs TOSC based, VREF ≥ 3.0V PIC18LCXXX 2.0 — µs TOSC based, VREF full range PIC18CXXX 2.0 6.0 µs A/D RC Mode PIC18LCXXX 3.0 9.0 µs A/D RC Mode 131 TCNV Conversion time (not including S/H time) (1) 11 11 TAD 132 TACQ Acquisition time Note 2 — µs 134 TGO Q4 to A/D clock start 2TOSC 2TOSC — If the A/D clock source is selected as RC, a time of TCY is added before the A/D clock starts. This allows the SLEEP instruction to be executed. 135 TSWC Switching Time from convert → sample 1 1 TAD 136 TAMP Amplifier settling time (2) 1 (5) — µs This may be used if the “new” input voltage has not changed by more than 1LSb (i.e., 5 (20) mV @ 5.12V) from the last sampled voltage (as stated on CHOLD). Note 1: ADRES register may be read on the following TCY cycle. 2: See the A/D Converter section for minimum requirements. 131 130 132 BSF ADCON0, GO Q4 A/D CLK A/D DATA ADRES ADIF GO SAMPLE OLD_DATA SAMPLING STOPPED DONE NEW_DATA (TOSC/2) (1) 7 6 5432 10 Note 1: If the A/D clock source is selected as RC, a time of TCY is added before the A/D clock starts. This allows the SLEEP instruction to be executed. 1 TCY 39500 18C Reference Manual.book Page 37 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-38  2000 Microchip Technology Inc. 32.26 Example 10-bit A/D Timing Waveforms and Requirements Table 32-34: Example 10-bit A/D Converter Characteristics Param No. Symbol Characteristic Min Typ Max Units Conditions A01 NR Resolution — — — — 10 TBD bit bit VREF = VDD ≥ 3.0V VREF = VDD < 3.0V A03 EIL Integral linearity error — — — — < ±1 TBD LSb LSb VREF = VDD ≥ 3.0V VREF = VDD < 3.0V A04 EDL Differential linearity error — — — — < ±1 TBD LSb LSb VREF = VDD ≥ 3.0V VREF = VDD < 3.0V A05 EFS Full scale error — — — — < ±1 TBD LSb LSb VREF = VDD ≥ 3.0V VREF = VDD < 3.0V A06 EOFF Offset error — — — — < ±1 TBD LSb LSb VREF = VDD ≥ 3.0V VREF = VDD < 3.0V A10 — Monotonicity guaranteed (3) — VSS ≤ VAIN ≤ VREF A20 VREF Reference voltage (VREFH - VREFL) 0V — — V A20A 3V — — V For 10-bit resolution A21 VREFH Reference voltage High AVSS — AVDD + 0.3V V A22 VREFL Reference voltage Low AVSS - 0.3V — AVDD V A25 VAIN Analog input voltage AVSS - 0.3V — VREF + 0.3V V A30 ZAIN Recommended impedance of analog voltage source — — 10.0 kΩ A40 IAD A/D conversion current (VDD) PIC18CXXX — 180 — µA Average current consumption when A/D is on (1) PIC18LCXXX — 90 — µA A50 IREF VREF input current (Note 2) 10 — — — 1000 10 µA µA During VAIN acquisition. Based on differential of VHOLD to VAIN. To charge CHOLD see the “10-bit A/D Converter” section. During A/D conversion cycle. Note 1: When A/D is off, it will not consume any current other than minor leakage current. The power-down current spec includes any such leakage from the A/D module. VREF current is from RG0 and RG1 pins or AVDD and AVSS pins, whichever is selected as reference input. 2: VSS ≤ VAIN ≤ VREF. 3: The A/D conversion result either increases or remains constant as the analog input increases. 39500 18C Reference Manual.book Page 38 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-39 Section 32. Electrical Specifications Electrical Specifications 32 Figure 32-24: Example 10-bit A/D Conversion Timing Waveforms Table 32-35: Example 10-bit A/D Conversion Requirements Param No. Symbol Characteristic Min Max Units Conditions 130 TAD A/D clock period PIC18CXXX 1.6 20 (5) µs TOSC based, VREF ≥ 3.0V PIC18LCXXX 3.0 20 (5) µs TOSC based, VREF full range PIC18CXXX 2.0 6.0 µs A/D RC Mode PIC18LCXXX 3.0 9.0 µs A/D RC Mode 131 TCNV Conversion time (not including acquisition time) (1) 11 § 12 § TAD 132 TACQ Acquisition time (3) 15 10 — — µs µs -40°C ≤ Temp ≤ 125°C 0°C ≤ Temp ≤ 125°C 135 TSWC Switching Time from convert → sample — Note 4 136 TAMP Amplifier settling time (2) 1 — µs This may be used if the “new” input voltage has not changed by more than 1LSb (i.e., 5 mV @ 5.12V) from the last sampled voltage (as stated on CHOLD). Note 1: ADRES register may be read on the following TCY cycle. 2: See the “10-bit A/D Converter” section for minimum conditions when input voltage has changed more than 1 LSb. 3: The time for the holding capacitor to acquire the “New” input voltage when the voltage changes full scale after the conversion (AVDD to AVSS, or AVSS to AVDD). The source impedance (RS) on the input channels is 50 Ω. 4: On the next Q4 cycle of the device clock. 5: The time of the A/D clock period is dependent on the device frequency and the TAD clock divider. 131 130 132 BSF ADCON0, GO Q4 A/D CLK A/D DATA ADRES ADIF GO SAMPLE OLD_DATA SAMPLING STOPPED DONE NEW_DATA (Note 2) 9 87 2 1 0 Note 1: If the A/D clock source is selected as RC, a time of TCY is added before the A/D clock starts. This allows the SLEEP instruction to be executed. 2: This is a minimal RC delay (typically 100 nS), which also disconnects the holding capacitor from the analog input. ... ... TCY 39500 18C Reference Manual.book Page 39 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-40  2000 Microchip Technology Inc. 32.27 Design Tips No related design tips at this time. 39500 18C Reference Manual.book Page 40 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39533A-page 32-41 Section 32. Electrical Specifications Electrical Specifications 32 32.28 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced MCU family (that is, they may be written for the Base-Line, the Mid-Range, or High-End families), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to the Electrical Specifications are: Title Application Note # No related Application Notes at this time. Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 41 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39533A-page 32-42  2000 Microchip Technology Inc. 32.29 Revision History Revision A This is the initial released revision of the Electrical Specifications description. 39500 18C Reference Manual.book Page 42 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-1 Device Characteristics 33 Section 33. Device Characteristics HIGHLIGHTS 33.1 Introduction .................................................................................................................. 33-2 33.2 Characterization vs. Electrical Specification ................................................................ 33-2 33.3 DC and AC Characteristics Graphs and Tables ........................................................... 33-2 33.4 Revision History ......................................................................................................... 33-26 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-2  2000 Microchip Technology Inc. 33.1 Introduction Microchip Technology Inc. provides characterization information on the devices that it manufactures. This information becomes available after the devices have undergone a complete characterization and the data has been analyzed. This data is taken on both device testers and on bench setups. The characterization data gives the designer a better understanding of the device characteristics, to better judge the acceptability of the device to the application. 33.2 Characterization vs. Electrical Specification The difference between this information and the Electrical specifications can be classified as what the user should expect the devices to do vs. what Microchip tests the devices to do. The characterization graphs and tables provided are for design guidance and are not tested nor guaranteed. There may be differences between what the characterization shows as the limits vs. that which is tested, as shown in the Electrical Specification section. This results from capabilities of the production tester equipment, plus whatever guard band that may be necessary. 33.3 DC and AC Characteristics Graphs and Tables Each table gives specific information that may be useful design information. These values are taken under fixed circumstances. Measurements taken in your application may not lead to the same values if your circumstances are not the same. In some graphs or tables the data presented are outside specified operating range (i.e., outside specified VDD range). This is for information only and devices will operate properly only within the specified range. Note: The data presented in the device Data Sheet Characterization section is a statistical summary of data collected on units from different lots over a period of time and matrix samples. 'Typical' represents the mean of the distribution at, 25°C, while 'max' or 'min' represents (mean +3σ) and (mean -3σ) respectively, where σ is standard deviation. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-3 Section 33. Device Characteristics Device Characteristics 33 33.3.1 IPD vs. VDD IPD is the current (I) that the device consumes when the device is in SLEEP mode (power-down), referred to as Power-down Current. These tests are taken with all I/O as inputs, either pulled high or low. That is, there are no floating inputs, nor are any pins driving an output (with a load). The characterization shows graphs for both the Watchdog Timer (WDT) disabled and enabled. This is required since the WDT requires an on-chip RC oscillator which consumes additional current. The device may have certain features and modules that can operate while the device is in SLEEP mode. Some of these modules are: • Watchdog Timer (WDT) • Brown-out Reset (BOR) circuitry • Timer1 • Analog to Digital converter • LCD module • Comparators • Voltage Reference If these features are operating while the device is in SLEEP mode, a higher current will be consumed. When all features are disabled, the device will consume the lowest possible current (the leakage current). If more then one feature is enabled, then the expected current can easily be calculated as the base current (everything disabled and in SLEEP mode), plus all delta currents. Example 33-1 shows an example of calculating the typical currents for a device at 5V, with the WDT and Timer1 oscillator enabled. Example 33-1: IPD Calculations with WDT and Timer1 Oscillator Enabled (@ 5V) Base Current 14 nA ; Device leakage current WDT Delta Current 14 µA ; 14 µA - 14 nA = 14 µA Timer1 Delta Current 22 µA ; 22 µA - 14 nA = 22 µA Total SLEEP Current 36 µA ; 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-4  2000 Microchip Technology Inc. Figure 33-1: Example Typical IPD vs. VDD (WDT Disabled, RC Mode) Figure 33-2: Example Maximum IPD vs. VDD (WDT Disabled, RC Mode) 35 30 25 20 15 10 5 0 2.5 3.0 3.5 4.0 4.5 5.0 5.5 IPD (nA) VDD (Volts) IPD (µA) VDD (Volts) 10.000 1.000 0.100 0.010 0.001 2.5 3.0 3.5 4.0 4.5 5.0 5.5 85°C 70°C 25°C 0°C -40°C 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-5 Section 33. Device Characteristics Device Characteristics 33 Figure 33-3: Example Typical IPD vs. VDD @ 25°C (WDT Enabled, RC Mode) Figure 33-4: Example Maximum IPD vs. VDD (WDT Enabled, RC Mode) 25 20 15 10 5 0 2.5 3.0 3.5 4.0 4.5 5.0 5.5 IPD (µA) VDD (Volts) 35 30 25 20 15 10 5 0 2.5 3.0 3.5 4.0 4.5 5.0 5.5 IPD (µA) VDD (Volts) -40°C 0°C 70°C 85°C 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-6  2000 Microchip Technology Inc. Figure 33-5: Example Typical IPD vs. VDD Brown-out Detect Enabled (RC Mode) Figure 33-6: Example Maximum IPD vs. VDD Brown-out Detect Enabled (85°C to -40°C, RC Mode) The shaded region represents the built-in hysteresis of the Brown-out Reset circuitry. 2.5 3.0 3.5 4.0 4.5 5.0 5.5 1400 1200 1000 800 600 400 200 0 VDD (Volts) IPD (µA) Device in Brown-out Device NOT in Brown-out Reset Reset The shaded region represents the built-in hysteresis of the Brown-out Reset circuitry. 2.5 3.0 3.5 4.0 4.5 5.0 5.5 1400 1200 1000 800 600 400 200 0 VDD (Volts) IPD (µA) 4.3 1600 Device NOT in Brown-out Reset Device in Brown-out Reset 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-7 Section 33. Device Characteristics Device Characteristics 33 Figure 33-7: Example Typical IPD vs. Timer1 Enabled (32 kHz, RC0/RC1 = 33 pF/33 pF, RC Mode) Figure 33-8: Example Maximum IPD vs. Timer1 Enabled (32 kHz, RC0/RC1 = 33 pF/33 pF, -40°C to 85°C, RC Mode) 30 25 20 15 10 5 0 2.5 3.0 3.5 4.0 4.5 5.0 5.5 VDD (Volts) IPD (µA) 30 25 20 15 10 5 0 2.5 3.0 3.5 4.0 4.5 5.0 5.5 VDD (Volts) IPD (µA) 35 40 45 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-8  2000 Microchip Technology Inc. 33.3.2 IDD vs. Frequency IDD is the current (I) that the device consumes when the device is in operating mode. This test is taken with all I/O as inputs, either pulled high or low. That is, there are no floating inputs, nor are any pins driving an output (with a load). The IDD vs. Frequency charts measure the results on a Microchip automated bench setup, called the DCS (Data Collection System). The DCS accurately reflects the device and specified component values, that is, it does not add stray capacitance or current. 33.3.2.1 RC Measurements For the RC measurement, the DCS selects a resistor and capacitor value and then, varies the voltage over the specified range. As the voltage is changed, the frequency of operation changes. For a fixed RC, as VDD increases, the frequency increases. After the measurement at this RC has been taken, the RC value is changed and the measurements are taken again. Each point on the graph corresponds to a device voltage, resistor value (R), and capacitor value (C). Figure 33-9: Example Typical IDD vs. Frequency (RC Mode @ 22 pF, 25°C) 2000 1800 1600 1400 1200 800 1000 600 400 200 0 0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5 Frequency (MHz) IDD (µA) Shaded area is 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V beyond recommended range. ‡ R=5kΩ † R = 10 kΩ ‡ † 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-9 Section 33. Device Characteristics Device Characteristics 33 Figure 33-10: Example Maximum IDD vs. Frequency (RC Mode @ 22 pF, -40°C to 85°C) Figure 33-11: Example Typical IDD vs. Frequency (RC Mode @ 100 pF, 25°C) 2000 1800 1600 1400 1200 800 1000 600 400 200 0 0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5 Frequency (MHz) IDD (µA) Shaded area is 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V beyond recommended range. 1600 1400 1200 1000 800 600 400 200 0 0 200 400 600 800 1000 1200 1400 1600 1800 Frequency (kHz) IDD (µA) 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V Shaded area is beyond recommended range. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-10  2000 Microchip Technology Inc. Figure 33-12: Example Maximum IDD vs. Frequency (RC Mode @ 100 pF, -40°C to 85°C) Figure 33-13: Example Typical IDD vs. Frequency (RC Mode @ 300 pF, 25°C) 1600 1400 1200 1000 800 600 400 200 0 0 200 400 600 800 1000 1200 1400 1600 1800 Frequency (kHz) IDD (µA) 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V Shaded area is beyond recommended range. 1200 1000 800 600 400 200 0 0 100 200 300 400 500 600 700 Frequency (kHz) IDD (µA) 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-11 Section 33. Device Characteristics Device Characteristics 33 Figure 33-14: Example Maximum IDD vs. Frequency (RC Mode @ 300 pF, -40°C to 85°C) Figure 33-15:Example Typical IDD vs. Capacitance @ 500 kHz (RC Mode) 1200 1000 800 600 400 200 0 0 100 200 300 400 500 600 700 Frequency (kHz) IDD (µA) 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V Capacitance (pF) 600 IDD (µA) 500 400 300 200 100 0 20 pF 100 pF 300 pF 5.0V 4.0V 3.0V 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-12  2000 Microchip Technology Inc. 33.3.2.2 Crystal Oscillator Measurements On the Data Collection System, there are several crystals. For this test, a crystal is multiplexed into the device circuit and the crystal’s capacitance values can be varied. The capacitance and voltage values are varied to determine the best characteristics (current, oscillator waveform and oscillator start-up), and then the currents are measured over voltage. The next crystal oscillator is then switched in and the procedure is repeated. Figure 33-16: Example Typical IDD vs. Frequency (LP Mode, 25°C) Figure 33-17: Example Maximum IDD vs. Frequency (LP Mode, -40°C to 85°C) 120 100 80 60 40 20 0 0 50 100 150 200 Frequency (kHz) IDD (µA) 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V 120 100 80 60 40 20 0 0 50 100 150 200 Frequency (kHz) IDD (µA) 140 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-13 Section 33. Device Characteristics Device Characteristics 33 Figure 33-18: Example Typical IDD vs. Frequency (XT Mode, 25°C) Figure 33-19: Example Maximum IDD vs. Frequency (XT Mode, -40°C to 85°C) 1200 1000 800 600 400 200 0 0.0 0.4 Frequency (MHz) IDD (µA) 1400 1600 1800 0.8 1.2 1.6 2.0 2.4 2.8 3.2 3.6 4.0 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V 1200 1000 800 600 400 200 0 0.0 0.4 Frequency (MHz) IDD (µA) 1400 1600 1800 0.8 1.2 1.6 2.0 2.4 2.8 3.2 3.6 4.0 5.5V 5.0V 4.5V 4.0V 3.5V 3.0V 2.5V 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-14  2000 Microchip Technology Inc. Figure 33-20: Example Typical IDD vs. Frequency (HS Mode, 25°C) Figure 33-21: Example Maximum IDD vs. Frequency (HS Mode, -40°C to 85°C) 7.0 6.0 5.0 4.0 3.0 2.0 1.0 0.0 1 2 4 6 8 10 12 14 16 18 20 Frequency (MHz) IDD (mA) 5.5V 5.0V 4.5V 4.0V 7.0 6.0 5.0 4.0 3.0 2.0 1.0 0.0 1 2 4 6 8 10 12 14 16 18 20 Frequency (MHz) IDD (mA) 5.5V 5.0V 4.5V 4.0V 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-15 Section 33. Device Characteristics Device Characteristics 33 33.3.3 RC Oscillator Frequency These tables show the effects of the RC oscillator frequency as the device voltage varies. In these measurements, a capacitor and resistor value are selected and then, the frequency of the RC is measured, as the device voltage varies. The table shows the typical frequency for a R and C value at 5V, as well as the variation from this frequency that can be expected, due to device processing. Figure 33-22: Example Typical RC Oscillator Frequency vs. VDD Figure 33-23: Example Typical RC Oscillator Frequency vs. VDD 2.5 3.0 3.5 4.0 4.5 5.0 5.5 VDD (Volts) 6.0 5.5 5.0 4.5 4.0 3.5 3.0 2.5 2.0 1.5 1.0 0.5 0.0 Fosc (MHz) CEXT = 22 pF, T = 25°C R = 100k R = 10k R = 5k Shaded area is beyond recommended range. 2.5 3.0 3.5 4.0 4.5 5.0 5.5 VDD (Volts) 2.4 2.2 2.0 1.8 1.6 1.4 1.2 1.0 0.8 0.6 0.4 0.2 0.0 Fosc (MHz) CEXT = 100 pF, T = 25°C R = 100k R = 10k R = 5k R = 3.3k 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-16  2000 Microchip Technology Inc. Figure 33-24: Example Typical RC Oscillator Frequency vs. VDD Table 33-1: Example RC Oscillator Frequencies CEXT REXT Average Fosc @ 5V, 25°C 22 pF 5k 4.12 MHz ± 1.4% 10k 2.35 MHz ± 1.4% 100k 268 kHz ± 1.1% 100 pF 3.3k 1.80 MHz ± 1.0% 5k 1.27 MHz ± 1.0% 10k 688 kHz ± 1.2% 100k 77.2 kHz ± 1.0% 300 pF 3.3k 707 kHz ± 1.4% 5k 501 kHz ± 1.2% 10k 269 kHz ± 1.6% 100k 28.3 kHz ± 1.1% The percentage variation indicated here is part to part variation due to normal process distribution. The variation indicated is ±3 standard deviation from average value for VDD = 5V. 2.5 3.0 3.5 4.0 4.5 5.0 5.5 VDD (Volts) 1000 900 800 700 600 500 400 300 200 100 0 Fosc (kHz) CEXT = 300 pF, T = 25°C R = 100k R = 10k R = 5k R = 3.3k 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-17 Section 33. Device Characteristics Device Characteristics 33 33.3.4 Oscillator Transconductance Transconductance of the oscillator indicates the gain of the oscillator. As the transconductance increases, the gain of the oscillator circuit increases, which causes the current consumption of the oscillator circuit to increase. Also, as the transconductance increases, the maximum frequency that the oscillator circuit can support also increases, or the start-up time of the oscillator decreases. Figure 33-25: Example Transconductance (gm) of HS Oscillator vs. VDD Figure 33-26: Example Transconductance (gm) of LP Oscillator vs. VDD 4.0 3.0 3.5 4.0 4.5 5.0 5.5 gm (mA/V) VDD (Volts) 3.5 3.0 2.5 2.0 1.5 1.0 0.5 0.0 Typ 25°C Min 85°C Max -40°C 110 100 90 80 70 60 50 40 30 20 10 0 2.0 2.5 3.0 3.5 4.0 4.5 5.0 5.5 gm (mA/V) VDD (Volts) Typ 25°C Min 85°C Max -40°C 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-18  2000 Microchip Technology Inc. Figure 33-27: Example Transconductance (gm) of XT Oscillator vs. VDD 1000 900 800 700 600 500 400 300 200 100 0 2.0 2.5 3.0 3.5 4.0 4.5 5.0 5.5 gm (mA/V) VDD (Volts) Typ 25°C Min 85°C Shaded area is beyond recommended range. Max -40°C 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-19 Section 33. Device Characteristics Device Characteristics 33 33.3.5 Crystal Start-up Time These graphs show the start-up time that one should expect to see at the specified voltage level, for a given crystal/capacitor combination. Figure 33-28: Example Typical XTAL Start-up Time vs. VDD (LP Mode, 25°C) Figure 33-29: Example Typical XTAL Start-up Time vs. VDD (HS Mode, 25°C) 3.5 3.0 2.5 2.0 1.5 1.0 0.5 0.0 2.5 3.0 3.5 4.0 4.5 5.0 5.5 VDD (Volts) Start-up Time (Seconds) 32 kHz, 33 pF/33 pF 200 kHz, 15 pF/15 pF 7 6 5 4 3 2 1 4.0 4.5 5.0 5.5 VDD (Volts) Start-up Time (ms) 20 MHz, 33 pF/33 pF 8 MHz, 33 pF/33 pF 8 MHz, 15 pF/15 pF 20 MHz, 15 pF/15 pF 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-20  2000 Microchip Technology Inc. Figure 33-30: Example Typical XTAL Start-up Time vs. VDD (XT Mode, 25°C) 70 60 50 40 30 20 10 0 2.5 4.0 5.0 5.5 3.0 3.5 4.5 VDD (Volts) Start-up Time (ms) 200 kHz, 68 pF/68 pF 200 kHz, 47 pF/47 pF 1 MHz, 15 pF/15 pF 4 MHz, 15 pF/15 pF 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-21 Section 33. Device Characteristics Device Characteristics 33 Figure 33-31: Example VTH (Input Threshold Trip Point Voltage) of I/O Pins vs. VDD Figure 33-32: Example VIH, VIL of MCLR, T0CKI and OSC1 (in RC Mode) vs. VDD 2.00 1.80 1.60 1.40 1.20 1.00 2.5 3.0 3.5 4.0 4.5 5.0 VDD (Volts) 0.80 0.60 5.5 Typ (+25°C) VTH (Volts) 3.5 3.0 2.5 2.0 1.5 1.0 2.5 3.0 3.5 4.0 4.5 5.0 VDD (Volts) 0.5 0.0 5.5 VIH, VIL (Volts) 4.0 4.5 VIH min (–40°C to +85°C) VIH max (–40°C to +85°C) VIH typ +25°C VIL min (–40°C to +85°C) VIL max (–40°C to +85°C) VIL typ +25°C Note: These input pins have Schmitt Trigger input buffers. 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-22  2000 Microchip Technology Inc. Figure 33-33: Example VTH (Input Threshold Trip Point Voltage) of OSC1 Input (in XT, HS, and LP modes) vs. VDD Figure 33-34: Example WDT Timer Time-out Period vs. VDD 2.4 2.2 2.0 1.8 1.6 1.4 2.5 3.0 3.5 4.0 4.5 5.0 VDD (Volts) 1.2 1.0 5.5 Typ (+25°C) VTH (Volts) 2.6 2.8 3.0 3.2 3.4 45 40 35 30 25 20 2.5 3.0 3.5 4.0 4.5 5.0 VDD (Volts) 15 10 5.5 50 2.0 WDT period (ms) Typ +125°C Typ +85°C Typ +25°C Typ –40°C 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-23 Section 33. Device Characteristics Device Characteristics 33 Figure 33-35: Example IOH vs. VOH, VDD =3V Figure 33-36: Example IOH vs. VOH, VDD =5V 0 –5 –10 –15 –20 –25 0 0.5 1.0 1.5 2.0 2.5 VOH (Volts) IOH (mA) Min +85°C 3.0 Typ +25°C Max –40°C 0 –10 –20 –30 –40 1.5 2.0 2.5 3.0 3.5 4.0 VOH (Volts) IOH (mA) Typ –40°C 4.5 5.0 Typ +85°C Typ +125°C Typ +25°C 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-24  2000 Microchip Technology Inc. Figure 33-37: Example IOL vs. VOL, VDD =3V Figure 33-38: Example IOL vs. VOL, VDD =5V 45 40 35 30 25 20 15 10 5 0 0.0 0.5 1.0 1.5 2.0 2.5 VOL (Volts) IOL (mA) Min +85°C Max –40°C Typ +25°C 3.0 90 80 70 60 50 40 30 20 10 0 0.0 0.5 1.0 1.5 2.0 2.5 VOL (Volts) IOL (mA) Min +85°C Max –40°C Typ +25°C 3.0 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39534A-page 33-25 Section 33. Device Characteristics Device Characteristics 33 33.3.6 Tested Crystals and Their Capacitor Values This table shows the crystal frequency and manufacturer that was used for every test in this section, as well as the capacitor values/ranges that exhibited the best characteristics. Table 33-2: Example Capacitor Selection for Crystal Oscillators 33.3.7 Example EPROM Memory Erase Times The UV erase time of an EPROM cell depends on the geometry size of the EPROM cell and the manufacturing technology. Table 33-3 shows some of the expected erase times for each different device. Table 33-3: Example of Typical EPROM Erase Time Recommendations Osc Type Crystal Frequency Capacitor Range C1 Capacitor Range C2 LP 32 kHz 33 pF 33 pF 200 kHz 15 pF 15 pF XT 200 kHz 47-68 pF 47-68 pF 1 MHz 15 pF 15 pF 4 MHz 15 pF 15 pF HS 4 MHz 15 pF 15 pF 8 MHz 15-33 pF 15-33 pF 20 MHz 15-33 pF 15-33 pF Note: Higher capacitance increases the stability of the oscillator but also increases the start-up time. These values are for design guidance only. Rs may be required in HS mode, as well as XT mode, to avoid overdriving crystals with low drive level specification. Since each crystal has its own characteristics, the user should consult the crystal manufacturer for appropriate values of external components or verify oscillator performance. Crystals Used: 32 kHz Epson C-001R32.768K-A ± 20 PPM 200 kHz STD XTL 200.000KHz ± 20 PPM 1 MHz ECS ECS-10-13-1 ± 50 PPM 4 MHz ECS ECS-40-20-1 ± 50 PPM 8 MHz EPSON CA-301 8.000M-C ± 30 PPM 20 MHz EPSON CA-301 20.000M-C ± 30 PPM Example Device Wavelength (Angstroms) Intensity (µW/cm2) Distance from UV Lamp (inches) Typical Time (1) (minutes) 1 2537 12,000 1 60 Note 1: If these criteria are not met, the erase times will be different. 2: Refer to the device data sheet for the typical erase times for a device. 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39534A-page 33-26  2000 Microchip Technology Inc. 33.4 Revision History Revision A This is the initial released revision of the Device Characteristics description. 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39535A-page 34-1 Development Tools 34 Section 34. Development Tools HIGHLIGHTS This section of the manual contains the following major topics: 34.1 Introduction .................................................................................................................. 34-2 34.2 The Integrated Development Environment (IDE) ......................................................... 34-3 34.3 MPLAB® Software Language Support ........................................................................ 34-6 34.4 MPLAB-SIM Simulator Software.................................................................................. 34-8 34.5 MPLAB® Emulator Hardware Support ........................................................................ 34-9 34.8 MPLAB Programmer Support .................................................................................... 34-10 34.9 Supplemental Tools.................................................................................................... 34-11 34.10 Development Boards.................................................................................................. 34-12 34.11 Development Tools for Other Microchip Products ...................................................... 34-14 34.12 Related Application Notes.......................................................................................... 34-15 34.13 Revision History ......................................................................................................... 34-16 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39535A-page 34-2  2000 Microchip Technology Inc. 34.1 Introduction Microchip offers a wide range of integrated development tools to ease the application development process. These tools can be broken down into the core development tools and the supplemental tools. The core tools are as follows: • MPLAB Integrated Development Environment, including full featured editor • Language Products - MPASM Assembler - MPLAB-CXX C Compiler -MPLAB-C17 -MPLAB-C18 - MPLINK/MPLIB Linker Librarian • MPLAB-SIM Software Simulator • Real-Time In-Circuit Emulators - MPLAB-ICE Real-Time Emulator In-Circuit - ICEPIC Low-Cost Emulator with Breakpoint debug capabilities • In-Circuit Debugger - MPLAB-ICD for 16F877 • Device Programmers - PRO MATE II Universal Programmer - PICSTART Plus Entry-Level Development Programmer • Development Boards - PICDEM-1 Low-Cost Demonstration Board - PICDEM-2 Low-Cost Demonstration Board - PICDEM-3 Low-Cost Demonstration Board - PICDEM-17 Low-Cost Demonstration Board - PICDEM-14A Low-Cost Demonstration Board The minimum configuration of MPLAB is the Integrated Development Environment (IDE), the assembler (MPASM), and the software simulator (MPLAB-SIM). Other tools are added to MPLAB as they are installed. This gives a common platform for the design activity, from the writing and assembling of the source code, through the simulation/emulation, to the programming of prototype devices. In addition to Microchip, there are many third party vendors. Microchip’s Third Party Handbook gives an overview of the manufactures and their tools. Note: The most current version may be downloaded from Microchip’s web site for free. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39535A-page 34-3 Section 34. Development Tools Development Tools 34 34.2 The Integrated Development Environment (IDE) The core set of development tools operate under the IDE umbrella. The IDE is called MPLAB. This gives a consistent look and feel to all the development tools so that minimal learning of the new tool interface is required. The MPLAB IDE integrates all the following aspects of development: • Source code editing • Project management • Machine code generation (from assembly or “C”) • Device simulation • Device emulation • Device programming MPLAB is a PC based Windows® application. It has been extensively tested using Windows 95 and recommended in either of these operating environments: • Windows 2000 • Windows NT 4.0 • Windows 98 • Windows 95 • Windows 3.X This comprehensive tool suite allows the complete development of a project without leaving the MPLAB environment. Windows is a registered trademark of Microsoft Corporation. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39535A-page 34-4  2000 Microchip Technology Inc. 34.2.1 MPLAB The MPLAB IDE Software brings an ease of software development previously unseen in the 8-bit microcontroller market. MPLAB is a Windows based application that contains: • A full featured editor • Four operating modes - editor - simulator - emulator - programmer • A project manager • Customizable tool bar and key mapping • A status bar with project information • Extensive on-line help MPLAB allows you to: • Edit your source files. This includes: - MPASM assembly language - MPLAB-CXX ‘C’ language • One touch assemble (or compile) and download to PIC16/17 tools (automatically updates all project information) • Debug using: - source files - absolute listing file - program memory • Run up to four MPLAB-ICE emulators on the same PC • Run or Single-step - program memory - source file - absolute listing Microchip’s simulator, MPLAB-SIM, operates under the same platform as the MPLAB-ICE emulator. This allows the user to learn a single tool set which functions equivalently for both the simulator and the full featured emulator. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39535A-page 34-5 Section 34. Development Tools Development Tools 34 Figure 34-1 shows a typical MPLAB desktop with an open project. Some of the highlights are: • Tool bars, multiple choices and user configurable • Status, mode information, and button help on footer bar • Multiple windows, such as - Source code - Source listing (most useful for ‘C’ programs) - Register file window (RAM) - Watch windows (to look at specific register) - Stop watch window for time/cycle calculations • Programmer support (in this case PRO MATE pull down menu) Figure 34-1: MPLAB Project Window Note: This screen shot may not look exactly like the currently released MPLAB version. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39535A-page 34-6  2000 Microchip Technology Inc. 34.3 MPLAB® Software Language Support To make the PICmicro device operate as desired in the application, a software program needs to be written for the microcontroller. This software program needs to be written in one of the programming languages for the device. Currently MPLAB supports two of Microchip’s language products: • Microchip Assembler (MPASM) • Microchip ‘C’ Compiler (MPLAB-CXX) • Other language products that support Common Object Description (COD) may also work with MPLAB 34.3.1 Assembler (MPASM) The MPASM Universal Macro Assembler is a PC-hosted symbolic assembler. It supports all Microchip microcontroller families. MPASM offers full featured Macro capabilities, conditional assembly, and several source and listing formats. It generates various object code formats to support Microchip's development tools as well as third party programmers. MPASM allow full symbolic debugging from the Microchip Universal Emulator System (MPLAB-ICE). MPASM has the following features to assist in developing software for specific use applications. • Provides translation of Assembler source code to object code for all Microchip microcontrollers. • Macro assembly capability. • Produces all the files (Object, Listing, Symbol, and Special) required for symbolic debug with Microchip’s emulator systems. • Supports Hex (default), Decimal and Octal source and listing formats. MPASM provides a rich directive language to support programming of the PICmicro. Directives are helpful in making the development of your assemble source code shorter and more maintainable. 34.3.2 C Compilers The MPLAB-CXX is a complete ‘C’ compiler for Microchip’s PICmicro family of microcontrollers. The compiler provides powerful integration capabilities and ease of use not found with other compilers. For easier source level debugging, the compiler provides symbol information that is compatible with the MPLAB IDE memory display, Watch windows, and File register windows. 34.3.2.1 MPLAB-C17 C Compiler The MPLAB-C17 Code Development System is a complete ANSI ‘C’ compiler and integrated development environment for Microchip’s PIC17CXXX family of microcontrollers. This compiler provides powerful integration capabilities and ease of use not found with other compilers. For easier source level debugging, the compiler provides symbol information that is compatible with the MPLAB IDE memory display. 34.3.2.2 MPLAB-C18 C Compiler The MPLAB-C18 Code Development System is a complete ANSI ‘C’ compiler and integrated development environment for Microchip’s PIC18CXXX family of microcontrollers. This compiler provides powerful integration capabilities and ease of use not found with other compilers. For easier source level debugging, the compiler provides symbol information that is compatible with the MPLAB IDE memory display. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39535A-page 34-7 Section 34. Development Tools Development Tools 34 34.3.3 MPLINK Linker MPLINK is a linker for the Microchip C compiler, MPLAB-CXX, and the Microchip relocatable assembler, MPASM. MPLINK is a relocatable linker for MPASM and MPLAB-C17 and MPLAB-C18. It can link relocatable objects from assembly or C source files along with precompiled libraries using directives from a linker script. MPLINK allows you to produce modular, re-usable code with MPLAB-CXX and MPASM. Control over the linking process is accomplished through a linker “script” file and with command line options. MPLINK ensures that all symbolic references are resolved and that code and data fit into the available PICmicro device. MPLINK combines multiple input object modules generated by MPLAB-CXX or MPASM, into a single executable file. The actual addresses of data and the location of functions will be assigned when MPLINK is executed. This means that you will instruct MPLINK to place code and data somewhere within the named regions of memory, not to specific physical locations. Once the linker knows about the ROM and RAM memory regions available in the target PICmicro device and it analyzes all the input files, it will try to fit the application’s routines into ROM and assign it’s data variables into available RAM. If there is too much code or too many variables to fit, MPLINK will give an error message. MPLINK also provides flexibility for specifying that certain blocks of data memory are re-usable, so that different routines (which never call each other and don’t depend on this data to be retained between execution) can share limited RAM space. MPLINK features include: • MPLINK works with MPASM and MPLAB-C17 and MPLAB-C18. • MPLINK allows all memory areas to be defined as sections to provide link-time flexibility. 34.3.4 MPLIB Librarian MPLIB is a librarian for use with COFF object modules, created using either MPASM, MPASMWIN, or MPLAB-CXX or later. MPLIB is a librarian for pre-compiled code to be used with MPLINK. When a routine from a library is called from another source file, only the modules that contain that routine will be linked in with the application. This allows large libraries to be used efficiently in many different applications. MPLIB manages the creation and modification of library files. A library file is a collection of object modules that are stored in a single file. There are several reasons for creating library files: • Libraries make linking easier. Since library files can contain many object files, the name of a library file can be used instead of the names of many separate object files when linking. • Libraries help keep code small. Since a linker only uses the required object files contained in a library, not all object files which are contained in the library necessarily wind up in the linker’s output module. • Libraries make projects more maintainable. If a library is included in a project, the addition or removal of calls to that library will not require a change to the link process. • Libraries help convey the purpose of a group of object modules. Since libraries can group together several related object modules, the purpose of a library file is usually more understandable that the purpose of its individual object modules. For example, the purpose of a file named “math.lib” is more apparent that the purpose of 'power.o', 'ceiling.o', and 'floor.o'. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39535A-page 34-8  2000 Microchip Technology Inc. 34.4 MPLAB-SIM Simulator Software The software simulator is a no-cost tool with which to evaluate Microchip’s products and designs. The use of the simulator greatly helps debug software, particularly algorithms. Depending on the complexity of a design project, a time/cost benefit should be looked at comparing the simulator with an emulator. For projects that have multiple engineers in the development, the simulator in conjunction with an emulator, can keep costs down and will allow speedy debug of the tough problems. MPLAB-SIM Simulator simulates the PICmicro series microcontrollers on an instruction level. On any given instruction, the user may examine or modify any of the data areas or provide external stimulus to any of the pins. The input/output radix can be set by the user and the execution can be performed in; single step, execute until break, or in a trace mode. MPLAB-SIM supports symbolic debugging using MPLAB-CXX, and MPASM. The Software Simulator offers the low cost flexibility to develop and debug code outside of the laboratory environment making it an excellent multi-project software development tool. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39535A-page 34-9 Section 34. Development Tools Development Tools 34 34.5 MPLAB® Emulator Hardware Support Microchip offers two emulators, a high-end version (MPLAB-ICE) and a low-cost version (ICEPIC). Both versions offer a very good price/feature value, and the selection of which emulator should depend on the feature set that you wish. For people looking at doing several projects with Microchip devices (or using the high-end devices), the use of MPLAB-ICE may offset the additional investment, through time savings achieved with the sophisticated breakpoint and trace capabilities. 34.6 MPLAB® High Performance Universal In-Circuit Emulator with MPLAB IDE The MPLAB-ICE Universal In-Circuit Emulator is intended to provide the product development engineer with a complete microcontroller design tool set for PICmicro microcontrollers (MCUs). Software control of MPLAB-ICE is provided by the MPLAB Integrated Development Environment (IDE), which allows editing, “make” and download, and source debugging from a single environment. Interchangeable target probes allow the system to be easily re-configured for emulation of different processors. The universal architecture of the MPLAB-ICE allows expansion to support all new Microchip microcontrollers. The MPLAB-ICE Emulator System has been designed as a real-time emulation system with advanced features that are generally found on more expensive development tools. A CE compliant version of MPLAB-ICE is available for European Union (EU) countries. 34.6.1 ICEPIC: Low-Cost PIC16CXXX In-Circuit Emulator ICEPIC is a low-cost in-circuit emulator solution for the Microchip Base-line and Mid-Range families of 8-bit OTP microcontrollers. ICEPIC features real-time emulation. ICEPIC is available under the MPLAB environment. ICEPIC is designed by Neosoft Inc. and is manufactured under license by RF Solutions. Other emulator solutions may be available directly from RF solutions. 34.7 MPLAB-ICD In-Circuit Debugger Microchip’s In-Circuit Debugger, MPLAB-ICD, is a powerful, low-cost run-time development tool. This tool is based on the FLASH PIC16F877 and can be used to develop for this and other PICmicro microcontrollers from the PIC16CXXX family (see TB033 for more information). MPLAB-ICD utilizes the In-Circuit Debugging capability built into the PIC16F87X. This feature, along with Microchip’s In-Circuit Serial Programming protocol, offers cost-effective in-circuit FLASH programming and debugging from the graphical user interface of the MPLAB Integrated Development Environment. This enables a designer to develop and debug source code by watching variables, single-stepping and setting break points. Running at full speed enables testing hardware in real-time. The MPLAB-ICD is also a programmer for the flash PIC16F87X family. 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39535A-page 34-10  2000 Microchip Technology Inc. 34.8 MPLAB Programmer Support Microchip offers two levels of device programmer support. For most bench setups the PICSTART Plus is sufficient. When true system qualification is done, the PRO MATE II should be the minimum used, due to the validation of program memory at VDD min and VDD max for maximum reliability 34.8.1 PRO MATE® II: Universal Device Programmer The PRO MATE II Universal Programmer is a full-featured programmer capable of operating in stand-alone mode as well as PC-hosted mode. PRO MATE II operates under MPLAB or as a DOS command driven program. The PRO MATE II has programmable VDD and VPP supplies which allows it to verify programmed memory at VDD min and VDD max for maximum reliability. It has an LCD display for error messages, keys to enter commands and a modular detachable socket assembly to support various package types. In stand-alone mode, the PRO MATE II can read, verify, or program Base-Line, Mid-Range, and High-End devices. It can also set configuration and code-protect bits in this mode. The PRO MATE II programmer also supports Microchip’s Serial EEPROM and KEELOQ® Security devices. A separate In-Circuit Serial Programming (ICSP) module is available for volume programming in a manufacturing environment. See the Programming module documentation for specific application requirements. 34.8.2 PICSTART® Plus Low-Cost Development Kit The PICSTART Plus programmer is an easy-to-use, low-cost development programmer. It connects to the PC via one of the COM (RS-232) ports. MPLAB Integrated Development Environment software makes using the programmer simple and efficient. PICSTART Plus is not recommended for production programming, since it does not perform memory verification at VDDMIN and VDDMAX. PICSTART Plus supports all Base-Line, Mid-Range, and High-End devices. For devices with up to more than 40 pins, an adapter socket is required. DIP packages are the form factor that are directly supported. Other package types may be supported with adapter sockets. Note: The use of a PICSTART Plus Programmer is not recommended for ICSP. If ICSP is required, the use of the PRO MATE II Universal Programmer with the associated socket module is the recommended Microchip solution. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39535A-page 34-11 Section 34. Development Tools Development Tools 34 34.9 Supplemental Tools Microchip endeavors to provide a broad range of solutions to our customers. These tools are considered supplemental tools and may be available directly from Microchip or from another vendor. A comprehensive listing of alternate tool providers is contained in the Third Party Guide. 34.9.1 Third Party Guide Looking for something else? Microchip strongly encourages and supports it’s Third Parties. Microchip publishes the “Third Party Guide”. It is an extensive volume that provides: • Company • Product • Contact Information • Consultants For over 100 companies and 200 products. These products include Emulators, Device Programmers, Gang Programmers, Language Products, and other tool solutions. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39535A-page 34-12  2000 Microchip Technology Inc. 34.10 Development Boards Development boards give a quick start on a circuit that demonstrates the capabilities of a particular device. The device program can then be modified for your own evaluation of the device functionality and operation. 34.10.1 PICDEM-1 Low-Cost PIC16/17 Demonstration Board The PICDEM-1 is a simple board which demonstrates the capabilities of several of Microchip’s microcontrollers. The microcontrollers supported are: • PIC16C5X (PIC16C54 to PIC16C58A) • PIC16C61 • PIC16C62X • PIC16C71 • PIC16C710 • PIC16C711 • PIC16C8X • PIC17C42A • PIC17C43 • PIC17C44 All necessary hardware and software is included to run basic demo programs. The users can program the sample microcontrollers provided with the PICDEM-1 board, on a PRO MATE II or PICSTART Plus programmer, and easily test firmware. The user can also connect the PICDEM-1 board to the MPLAB-ICE emulator and download the firmware to the emulator for testing. Additional prototype area is available to build additional hardware. Some of the features include an RS-232 interface, a potentiometer for simulated analog input, push-button switches and eight LEDs connected to PORTB. 34.10.2 PICDEM-2 Low-Cost PIC16CXXX Demonstration Board The PICDEM-2 is a simple demonstration board that supports the following microcontrollers: • PIC16C62 • PIC16C63 • PIC16C64 • PIC16C65 • PIC16C66 • PIC16C67 • PIC16C72 • PIC16C73 • PIC16C74 • PIC16C76 • PIC16C77 All the necessary hardware and software is included to run the basic demonstration programs. The user can program the sample microcontrollers provided with the PICDEM-2 board, on a PRO MATE II programmer or PICSTART Plus, and easily test firmware. The MPLAB-ICE emulator may also be used with the PICDEM-2 board to test firmware. Additional prototype area has been provided for additional hardware. Some of the features include a RS-232 interface, push-button switches, a potentiometer for simulated analog input, a Serial EEPROM to demonstrate usage of the I2C bus and separate headers for connection to an LCD module and a keypad. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39535A-page 34-13 Section 34. Development Tools Development Tools 34 34.10.3 PICDEM-3 Low-Cost PIC16CXXX Demonstration Board The PICDEM-3 is a simple demonstration board that supports the PIC16C923 and PIC16C924 in the PLCC package. It will also support future 44-pin PLCC microcontrollers that have an LCD Module. All the necessary hardware and software is included to run the basic demonstration programs. The user can program the sample microcontrollers, provided with the PICDEM-3 board, on a PRO MATE II programmer or PICSTART Plus with an adapter socket, and easily test firmware. The MPLAB-ICE emulator may also be used with the PICDEM-3 board to test firmware. Additional prototype area has been provided for adding hardware. Some of the features include an RS-232 interface, push-button switches, a potentiometer for simulated analog input, a thermistor and separate headers for connection to an external LCD module and a keypad. Also provided on the PICDEM-3 board is an LCD panel, with 4 commons and 12 segments, that is capable of displaying time, temperature and day of the week. The PICDEM-3 provides an additional RS-232 interface and Windows 3.1 software for showing the de-multiplexed LCD signals on a PC. A simple serial interface allows the user to construct a hardware de-multiplexer for the LCD signals. 34.10.4 PICDEM-14A Low-Cost PIC14C000 Demonstration Board The PICDEM-14A demo board is a general purpose platform which is provided to help evaluate the PIC14C000 mixed signal microcontroller. The board runs a PIC14C000 measuring the voltage of a potentiometer and the on-chip temperature sensor. The voltages are then calibrated to the internal bandgap voltage reference. The voltage and temperature data are then transmitted to the RS-232 port. This data can be displayed using a terminal emulation program, such as Windows Terminal. This demo board also includes peripherals that allow users to display data on an LCD panel, read from and write to a serial EEPROM, and prototype custom circuitry to interface to the microcontroller. 34.10.5 PICDEM-17 The PICDEM-17 is an evaluation board that demonstrates the capabilities of several Microchip microcontrollers, including PIC17C752, PIC17C756, PIC17C762, and PIC17C766. All necessary hardware is included to run basic demo programs, which are supplied on a 3.5-inch disk. A programmed sample is included, and the user may erase it and program it with the other sample programs using the PRO MATE II or PICSTART Plus device programmers and easily debug and test sample code. In addition, PICDEM-17 supports down-loading of programs to and executing out of external FLASH memory on board. The PICDEM-17 is also usable with the MPLAB-ICE emulator, and all of the sample programs can be run and modified using that emulator. Additionally, a generous prototype area is available for user hardware. 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39535A-page 34-14  2000 Microchip Technology Inc. 34.11 Development Tools for Other Microchip Products 34.11.1 SEEVAL Evaluation and Programming System The SEEVAL Serial EEPROM Designer’s Kit supports all Microchip 2-wire and 3-wire Serial EEPROMs. The kit includes everything necessary to read, write, erase or program special features of any Microchip SEEPROM product including Smart SerialsTM and secure serials. The Total EnduranceTM Disk is included to aid in trade-off analysis and reliability calculations. The total endurance kit can significantly reduce time-to-market and results in a more optimized system. 34.11.2 KEELOQ Evaluation and Programming Tools KEELOQ evaluation and programming tools supports Microchip’s HCS Secure Data Products. The HCS evaluation kit includes an LCD display to show changing codes, a decoder to decode transmissions, and a programming interface to program test transmitters. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39535A-page 34-15 Section 34. Development Tools Development Tools 34 34.12 Related Application Notes This section lists application notes that are related to this section of the manual. These application notes may not be written specifically for the Enhanced MCU family (that is they may be written for the Base-Line, Mid-Range, or the High-End), but the concepts are pertinent, and could be used (with modification and possible limitations). The current application notes related to Microchip’s development tools are: Title Application Note # No related application notes at this time. Note: Several of the tools have tutorials which may be helpful in learning the tools. Please refer to the specific tool’s documentation for tutorial availability. Note: Please visit the Microchip Web site for additional software code examples. These code examples are stand alone examples to assist in the understanding of the PIC18CXXX. The web address for these examples is: http://www.microchip.com/10/faqs/codeex/ 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39535A-page 34-16  2000 Microchip Technology Inc. 34.13 Revision History Revision A This is the initial released revision of Microchip’s development tools description. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39536A-page 35-1 Code Development 35 Section 35. Code Development HIGHLIGHTS This section of the manual contains the following major topics: 35.1 Overview ...................................................................................................................... 35-2 35.2 Good Practice .............................................................................................................. 35-3 35.3 Diagnostic Code Techniques ....................................................................................... 35-5 35.4 Example Scenario and Implementation ....................................................................... 35-6 35.5 Implications of Using a High Level Language (HLL) .................................................... 35-7 35.6 Revision History ........................................................................................................... 35-8 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39536A-page 35-2  2000 Microchip Technology Inc. 35.1 Overview This section covers some good programming practice as well as some diagnostic techniques that can be used in both the development stage, and the production release to help diagnose unexpected operation in the field. The advantage of including diagnostic code is that the device continually displays its status and the operational flow of the program. These suggestions only scratch the surface of the possible techniques and good programming practices. Future revisions of this section will add additional suggestions on good programming practice and diagnostic techniques. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39536A-page 35-3 Section 35. Code Development Code Development 35 35.2 Good Practice The following are some recommended programming practices. These will help ensure consistent program operation based on the stimulus supplied to the application software. 35.2.1 Use of Symbolic Code Microchip supplies header files which use the register and bit name symbols specified in the device data sheets. The use of these symbols aids in several facets of software development. First, symbolic code makes the source file easier to read since the names relate to a function (as opposed to register addresses and bit positions). Example 35-1 shows two implementations. The first, though technically correct, is more difficult to follow then the second implementation. Also, the second allows for easier migration between devices (and PICmicro families) since any remapping of bit positions and register locations can automatically be handled by the software tool. Example 35-1:Hard Coding vs. Symbolic Code 35.2.2 Initialization of Data Memory All Data Memory locations (SFRs and GPRs) should be initialized after a RESET. This will ensure that they are at a known state when the application code accesses each location, and ensures consistent operation When all data memory is not initialized, there is a possibility that the application software will read a location that is an indeterminate value. This may cause unexpected results from the application software. This issue is sometimes highlighted when development moves from a windowed device (where the window was not covered) to an OTP package. BCF 0xD8, 0, 0 ; Clear the carry bit : ; BCF STATUS, C ; Clear the carry bit 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39536A-page 35-4  2000 Microchip Technology Inc. 35.2.3 Trap for Unexpected Conditions Sometimes the application software will test only for the expected conditions. This is typically seen in the Interrupt Service Routine where only the expected sources for an interrupt are tested for. Example 35-2 shows a typical way that the conditions are tested, while Example 35-3 shows a more robust version. The TrapRoutine may do more then just loop waiting for a RESET. It could output a code on an I/O pin to indicate that this unexpected condition occurred. Example 35-2:Typical ISR Code Example 35-3:Recommended ISR Code (with Trap) 35.2.4 Filling Unused Locations In most application programs, not all program memory locations are used. These unprogrammed locations (0xFFFF) execute as a NOP instruction. Since program execution is never intended to go to one of these locations, the program should trap any occurrence of this. A good way to handle this is to “fill” all unprogrammed locations with a branch which goes to its own program memory location. With this, the WDT must be enabled to cause a device RESET and restart program execution. The Microchip Assembler supplies a directive to do this. This directive is the “fill” directive. ORG ISRVectorAddress ; Address for Interrupt Service ; Routine ISRH BTFSS PIR1, ADIF ; A/D Interrupt? GOTO ADRoutine ; Yes, do A/D stuff BTFSS PIR1, RCIF ; AUSART Receive Interrupt? GOTO ReceiveRoutine ; Yes, do Receive stuff CCPRoutine ; Since not other interrupt sources : ; must be CCP interrupt ORG ISRVectorAddress ; Address for Interrupt Service ; Routine ISRH BTFSS PIR1, ADIF ; A/D Interrupt? GOTO ADRoutine ; Yes, do A/D stuff BTFSS PIR1, RCIF ; AUSART Receive Interrupt? GOTO ReceiveRoutine ; Yes, do Receive stuff BTFSS PIR1, CCPIF ; CCP Interrupt? GOTO CCPRoutine ; Yes, do CCP stuff TrapRoutine ; Should NEVER get here GOTO TrapRoutine ; If we do, loop forever and ; wait for WDT reset Note: Remember that the CLRWDT instruction should have a minimum number of occurrences in the program and that the maximum time between the CLRWDT instructions must NOT be greater than the minimum WDT time-out period, multiplied by the selected prescaler. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39536A-page 35-5 Section 35. Code Development Code Development 35 35.3 Diagnostic Code Techniques This section describes diagnostic code that can be embedded into the application code to help track the operation of the application software. Typically some mechanism is required to make the information available to the external world. This can be from a serial port (such as the Addressable USART module) or from extra I/O pins not used by the application. 35.3.1 Function Sequence Have the diagnostic code output a unique code (value) for each function that the program enters. This allows the flow of the program to be monitored from outside the device (with a logic analyzer) and assist in determining if there is some unexpected condition that is causing code to execute in the observed sequence. 35.3.2 Stack Depth A counter can be implemented that is incremented in each function that is called and each time that the program counter is at an interrupt vector address. The counter is then decremented at the end of the function or interrupt service routine. The value of the stack can then be output to indicate if the stack depth is out of its normal range (minimum and maximum). 35.3.3 A/D Operation Visibility into the operation of the A/D can help validate the operation. Monitoring if the acquisition time is the expected time delay, as well as the result generated by the module. Achieving the A/D result accuracy depends on may factors, some internal and many external. The major internal factor is that there is a sufficient amount of time once the input channel is selected, until the conversion is started. This is called the acquisition time (TACQ). 35.3.3.1 A/D Acquisition Time Use an I/O pin to indicate when the acquisition of the channel starts (toggle high) until the conversion is started (toggle high). If the input channel is changed force the I/O to toggle high. The last two I/O toggles before the A/D result is available, is acquisition time that the A/D had for that selected channel. 35.3.3.2 A/D Result Output the result so that you can determine if the program execution flow can be attributed to the result from the A/D converter. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39536A-page 35-6  2000 Microchip Technology Inc. 35.4 Example Scenario and Implementation In this example application, one I/O port is not implemented. This means that there are eight I/O pins available to indicate the operational status of the PICmicro device and the flow of the application software. Let’s say that the code implements 57 functions, the A/D is used and Addressable USART are used. Six bits (Code5:Code0) are required to uniquely specify the 57 functions. After each function gets a code, an additional 7 codes are available. Table 35-1 shows how these codes could be defined, while Table 35-2 shows how the diagnostic output port could be defined. Table 35-1: Definitions of Additional Codes Table 35-2: PORT Function assignment So, as the device exits RESET, the PORT = ‘1111 11xx’ where the xx indicates the source of the device RESET. Then the code for the main function is output on Rx7:Rx2 and Rx1:Rx0 = ‘00’. As each function gets called, the stack depth is output. This requires that the code Rx7:Rx2 = ‘1111 11’ is output, then the stack depth counter is moved to the PORT. The code for the entered function is then output. After the A/D is enabled and acquisition of the selected channel begins, the Rx1 pin is toggled high. Each event that causes the input to start a new acquisition time should cause the Rx1 pin to toggle. These events include: • Selection of a new input channel • The completion of an A/D conversion • Disabling and then re-enabling the A/D module When an A/D conversion completes or the addressable USART receives a byte, the appropriate code is output on the PORT and then the value is output. 6-bit Code Definition 1111 11 Next Byte out is stack depth 1111 10 Next Byte out is A/D Result High Byte 1111 01 Next Byte out is Addressable USART received byte 1111 00 Next Byte out is A/D Result Low Byte 0000 00 Device has exited a device RESET. Rx1:Rx0 can be used to indicate the source of the RESET. Pin Normal Mode Mode after “Additional Codes” displayed RESET Rx7 Code5 Byte value for the indicated function 0 Rx6 Code4 0 Rx5 Code3 0 Rx4 Code2 0 Rx3 Code1 0 Rx2 Code0 0 Rx1 Toggle for Start of acquisition 4 codes available to indicate source of RESET Rx0 Toggle for Stop of acquisition 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39536A-page 35-7 Section 35. Code Development Code Development 35 35.5 Implications of Using a High Level Language (HLL) The use of a High Level Language, such as a C compiler, speeds the development cycle but can increase the difficulty in the use of diagnostic code. When writing at the high level, functions may be defined, but how the C compilers will implement those functions is hidden from the user. If the function is used only once, the C complier may put that code in-line or use a GOTO to branch to the function and a GOTO to return from the function. In both these implementations, the stack is not affected. Also, if the function is called many times, but is small, it may be put inline. This again will not affect the stack used. These techniques used by the compiler may lead to efficient code generation, but may add to the difficulty in adding diagnostic code. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39536A-page 35-8  2000 Microchip Technology Inc. 35.6 Revision History Revision A This is the initial released revision for the Code Development with a PICmicro device description. 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-1 Appendix 36 Section 36. Appendix APPENDIX A: I2C OVERVIEW This appendix provides an overview of the Inter-Integrated Circuit (I2C™) bus, with Subsection A.2 “Addressing I2C Devices” discussing the operation of the SSP modules in I2C mode. The I2C bus is a two-wire serial interface. The original specification, or standard mode, is for data transfers of up to 100 Kbps. An enhanced specification, or fast mode (400 Kbps) is supported. Standard and Fast mode devices will operate when attached to the same bus, if the bus operates at the speed of the slower device. The I2C interface employs a comprehensive protocol to ensure reliable transmission and reception of data. When transmitting data, one device is the “master” which initiates transfer on the bus and generates the clock signals to permit that transfer, while the other device(s) acts as the “slave.” All portions of the slave protocol are implemented in the SSP module’s hardware, except general call support, while portions of the master protocol need to be addressed in the PIC16CXX software. The MSSP module supports the full implementation of the I2 C master protocol, the general call address, and data transfers up to 1 Mbps. The 1 Mbps data transfers are supported by some of Microchips Serial EEPROMs. Table A-1 defines some of the I2C bus terminology. In the I2C interface protocol each device has an address. When a master wishes to initiate a data transfer, it first transmits the address of the device that it wishes to “talk” to. All devices “listen” to see if this is their address. Within this address, a bit specifies if the master wishes to read-from/write-to the slave device. The master and slave are always in opposite modes (transmitter/receiver) of operation during a data transfer. That is, they can be thought of as operating in either of these two relations: • Master-transmitter and Slave-receiver • Slave-transmitter and Master-receiver In both cases the master generates the clock signal. The output stages of the clock (SCL) and data (SDA) lines must have an open-drain or open-collector in order to perform the wired-AND function of the bus. External pull-up resistors are used to ensure a high level when no device is pulling the line down. The number of devices that may be attached to the I2C bus is limited only by the maximum bus loading specification of 400 pF and addressing capability. I 2C is a trademark of Philips Corporation. 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-2  2000 Microchip Technology Inc. A.1 Initiating and Terminating Data Transfer During times of no data transfer (idle time), both the clock line (SCL) and the data line (SDA) are pulled high through the external pull-up resistors. The START and STOP conditions determine the start and stop of data transmission. The START condition is defined as a high to low transition of the SDA when the SCL is high. The STOP condition is defined as a low to high transition of the SDA when the SCL is high. Figure A-1 shows the START and STOP conditions. The master generates these conditions for starting and terminating data transfer. Due to the definition of the START and STOP conditions, when data is being transmitted, the SDA line can only change state when the SCL line is low. Figure A-1: Start and Stop Conditions SDA SCL S P START Condition Change of Data Allowed Change of Data Allowed STOP Condition 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-3 Section 36. Appendix Appendix 36 Table A-1: I2 C Bus Terminology Term Description Transmitter The device that sends the data to the bus. Receiver The device that receives the data from the bus. Master The device which initiates the transfer, generates the clock and terminates the transfer. Slave The device addressed by a master. Multi-master More than one master device in a system. These masters can attempt to control the bus at the same time without corrupting the message. Arbitration Procedure that ensures that only one of the master devices will control the bus. This ensure that the transfer data does not get corrupted. Synchronization Procedure where the clock signals of two or more devices are synchronized. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-4  2000 Microchip Technology Inc. A.2 Addressing I2C Devices There are two address formats. The simplest is the 7-bit address format with a R/W bit (Figure A-2). The more complex is the 10-bit address with a R/W bit (Figure A-3). For 10-bit address format, two bytes must be transmitted. The first five bits specify this to be a 10-bit address format. The 1st transmitted byte has 5 bits which specify a 10-bit address, the two MSbs of the address, and the R/W bit. The second byte is the remaining 8 bits of the address. Figure A-2: 7-bit Address Format Figure A-3: I2C 10-bit Address Format S R/W ACK Sent by Slave Slave Address S R/W Read/Write pulse MSb LSb START Condition ACK Acknowledge S 1 1 1 1 0 A9 A8R/W ACK A7 A6 A5 A4 A3 A2 A1 A0 ACK Sent By Slave = 0 for write S R/W ACK - START Condition - Read/Write Pulse - Acknowledge 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-5 Section 36. Appendix Appendix 36 A.3 Transfer Acknowledge All data must be transmitted per byte, with no limit to the number of bytes transmitted per data transfer. After each byte, the slave-receiver generates an acknowledge bit (ACK) (Figure A-4). When a slave-receiver doesn’t acknowledge the slave address or received data, the master must abort the transfer. The slave must leave SDA high so that the master can generate the STOP condition (Figure A-1). Figure A-4: Slave-Receiver Acknowledge If the master is receiving the data (master-receiver), it generates an acknowledge signal for each received byte of data, except for the last byte. To signal the end of data to the slave-transmitter, the master does not generate an acknowledge (not acknowledge). The slave then releases the SDA line so the master can generate the STOP condition. The master can also generate the STOP condition during the acknowledge pulse for valid termination of data transfer. If the slave needs to delay the transmission of the next byte, holding the SCL line low will force the master into a wait state. Data transfer continues when the slave releases the SCL line. This allows the slave to move the received data or fetch the data it needs to transfer before allowing the clock to start. This wait state technique can also be implemented at the bit level, Figure A-5. Figure A-5: Data Transfer Wait State S Data Output by Transmitter Data Output by Receiver SCL from Master START Condition Clock Pulse for Acknowledgment not acknowledge acknowledge 1 2 8 9 1 2 7 8 9 123 • 8 9 P SDA SCL S START Condition Address R/W ACK Wait State Data ACK MSb Acknowledgment Signal from Receiver Acknowledgment Signal from Receiver Byte Complete Interrupt with Receiver Clock Line Held Low while Interrupts are Serviced STOP Condition 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-6  2000 Microchip Technology Inc. Figure A-6 and Figure A-7 show Master-transmitter and Master-receiver data transfer sequences. Figure A-6: Master-Transmitter Sequence Figure A-7: Master-Receiver Sequence For 7-bit address: S Slave Address (Code + A9:A8) S R/W A1 Slave Address (A7:A0) A2 Data A Data P A master transmitter addresses a slave receiver with a 10-bit address. A/A Slave Address R/W A Data A Data A/A P '0' (write) data transferred (n bytes - acknowledge) A master transmitter addresses a slave receiver with a 7-bit address. The transfer direction is not changed. From master to slave From slave to master A = acknowledge (SDA low) A = not acknowledge (SDA high) S = START Condition P = STOP Condition (write) For 10-bit address: For 7-bit address: S Slave Address (Code + A9:A8) S R/W A1 Slave Address (A7:A0) A2 A master transmitter addresses a slave receiver with a 10-bit address. Slave Address R/W A Data A Data A P '1' (read) data transferred (n bytes - acknowledge) A master reads a slave immediately after the first byte. From master to slave From slave to master A = acknowledge (SDA low) A = not acknowledge (SDA high) S = START Condition P = STOP Condition (write) For 10-bit address: Slave Address (Code + A9:A8) Sr R/W A3 A Data A P Data (read) 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-7 Section 36. Appendix Appendix 36 When a master does not wish to relinquish the bus (which occurs by generating a STOP condition), a repeated START condition (Sr) must be generated. This condition is identical to the START condition (SDA goes high-to-low while SCL is high), but occurs after a data transfer acknowledge pulse (not the bus-free state). This allows a master to send “commands” to the slave and then receive the requested information or to address a different slave device. This sequence is shown in Figure A-8. Figure A-8: Combined Format Combined format: S Combined format - A master addresses a slave with a 10-bit address, then transmits Slave Address R/W A Data A/A Sr P (read) Sr = repeated Transfer direction of data and acknowledgment bits depends on R/W bits. From master to slave From slave to master A = acknowledge (SDA low) A = not acknowledge (SDA high) S = START Condition P = STOP Condition Slave Address (Code + A9:A8) Sr R/W A (write) data to this slave and reads data from this slave. Slave Address (A7:A0) Data Sr Slave Address (Code + A9:A8) A A Data A/A R/W A Data A A Data P (read) Slave Address R/W A Data A/A START Condition (write) Direction of transfer may change at this point (read or write) (n bytes + acknowledge) 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-8  2000 Microchip Technology Inc. A.4 Multi-master The I2C protocol allows a system to have more than one master. This is called a multi-master system. When two or more masters try to transfer data at the same time, arbitration and synchronization occur. A.4.1 Arbitration Arbitration takes place on the SDA line, while the SCL line is high. The master which transmits a high when the other master transmits a low, loses arbitration (Figure A-9) and turns off its data output stage. A master which lost arbitration can generate clock pulses until the end of the data byte where it lost arbitration. When the master devices are addressing the same device, arbitration continues into the data. Figure A-9: Multi-Master Arbitration (Two Masters) Masters that also incorporate the slave function, and have lost arbitration must immediately switch over to slave-receiver mode. This is because the winning master-transmitter may be addressing it. Arbitration is not allowed between: • A repeated START condition • A STOP condition and a data bit • A repeated START condition and a STOP condition Care needs to be taken to ensure that these conditions do not occur. Transmitter 1 Loses Arbitration DATA 1 SDA DATA 1 DATA 2 SDA SCL 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-9 Section 36. Appendix Appendix 36 A.4.2 Clock Synchronization Clock synchronization occurs after the devices have started arbitration. This is performed using a wired-AND connection to the SCL line. A high to low transition on the SCL line causes the concerned devices to start counting off their low period. Once a device clock has gone low, it will hold the SCL line low until its SCL high state is reached. The low to high transition of this clock may not change the state of the SCL line, if another device clock is still within its low period. The SCL line is held low by the device with the longest low period. Devices with shorter low periods enter a high wait-state, until the SCL line comes high. When the SCL line comes high, all devices start counting off their high periods. The first device to complete its high period will pull the SCL line low. The SCL line high time is determined by the device with the shortest high period, Figure A-10. Figure A-10:Clock Synchronization CLK 1 CLK 2 SCL Wait State Start Counting High Period Counter Reset 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-10  2000 Microchip Technology Inc. Table A-2 and Table A-3 show the specifications of a compliant I2 C bus. The column titled Microchip Parameter No. is provided to ease the user’s correlation to the corresponding parameter in the device data sheet. Figure A-11 and Figure A-12 show these times on the appropriate waveforms. Figure A-11: I2C Bus Start/Stop Bits Timing Specification Table A-2: I2C Bus Start/Stop Bits Timing Specification Figure A-12: I2C Bus Data Timing Specification Microchip Parameter No. Sym Characteristic Min Typ Max Units Conditions 90 TSU:STA START condition 100 kHz mode 4700 — — ns Only relevant for repeated START condition Setup time 400 kHz mode 600 — — 91 THD:STA START condition 100 kHz mode 4000 — — ns After this period the first Hold time 400 kHz mode 600 — — clock pulse is generated 92 TSU:STO STOP condition 100 kHz mode 4700 — — ns Setup time 400 kHz mode 600 — — 93 THD:STO STOP condition 100 kHz mode 4000 — — ns Hold time 400 kHz mode 600 — — 91 93 SCL SDA START Condition STOP Condition 90 92 90 91 92 100 101 103 106 107 109 109 110 102 SCL SDA In SDA Out MSb 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-11 Section 36. Appendix Appendix 36 Table A-3: I2 C Bus Data Timing Specification Microchip Parameter No. Sym Characteristic Min Max Units Conditions 100 THIGH Clock high time 100 kHz mode 4.0 — µs 400 kHz mode 0.6 — µs 101 TLOW Clock low time 100 kHz mode 4.7 — µs 400 kHz mode 1.3 — µs 102 TR SDA and SCL rise time 100 kHz mode — 1000 ns 400 kHz mode 20 + 0.1Cb 300 ns Cb is specified to be from 10 to 400 pF 103 TF SDA and SCL fall time 100 kHz mode — 300 ns 400 kHz mode 20 + 0.1Cb 300 ns Cb is specified to be from 10 to 400 pF 90 TSU:STA START condition setup time 100 kHz mode 4.7 — µs Only relevant for repeated 400 kHz mode 0.6 — µs START condition 91 THD:STA START condition hold time 100 kHz mode 4.0 — µs After this period the first 400 kHz mode 0.6 — µs clock pulse is generated 106 THD:DAT Data input hold time 100 kHz mode 0 — ns 400 kHz mode 0 0.9 µs 107 TSU:DAT Data input setup time 100 kHz mode 250 — ns Note 2 400 kHz mode 100 — ns 92 TSU:STO STOP condition setup time 100 kHz mode 4.7 — µs 400 kHz mode 0.6 — µs 109 TAA Output valid from clock 100 kHz mode — 3500 ns Note 1 400 kHz mode — 1000 ns 110 TBUF Bus free time 100 kHz mode 4.7 — µs Time the bus must be free before a new transmission can start 400 kHz mode 1.3 — µs D102 Cb Bus capacitive loading — 400 pF Note 1: As a transmitter, the device must provide this internal minimum delay time to bridge the undefined region (min. 300 ns) of the falling edge of SCL to avoid unintended generation of START or STOP conditions. 2: A fast-mode I2C-bus device can be used in a standard-mode I2C-bus system, but the requirement TSU;DAT ≥ 250 ns must then be met. This will automatically be the case if the device does not stretch the LOW period of the SCL signal. If such a device does stretch the LOW period of the SCL signal, it must output the next data bit to the SDA line TR max.+TSU;DAT = 1000 + 250 = 1250 ns (according to the standard-mode I2C bus specification) before the SCL line is released. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-12  2000 Microchip Technology Inc. APPENDIX B: CAN OVERVIEW This appendix provides an overview of the Controller Area Network (CAN) bus. The CAN Section of this reference manual discusses the implementation of the CAN protocol in that hardware module. Not available at this time. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-13 Section 36. Appendix Appendix 36 APPENDIX C: MODULE BLOCK DIAGRAMS AND REGISTERS This appendix summarizes the block diagrams of the major circuits. Not available at this time. 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-14  2000 Microchip Technology Inc. APPENDIX D: REGISTER DEFINITIONS This appendix summarizes the register definitions. Not available at this time. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-15 Section 36. Appendix Appendix 36 APPENDIX E: MIGRATION TIPS This appendix gives an overview of some things that need to be taken into account when migrating code from other PICmicro families to the PIC18CXXX. For additional information, please also refer to the following application notes: • AN716 • AN726 Three major changes Timer0 has from the mid-range family are: 1. The Timer0 no longer shares the prescaler with the Watchdog Timer. 2. Timer0 has 16-bit as well as 8-bit capability. 3. Timer0 can now be turned off. The default state for Timer0 is an 8-bit counter for downward compatibility with the mid-range Timer0. The prescaler is no longer shared between the Timer0 module and the Watchdog Timer. Each have their own separate prescalers. Thus, a prescaler assignment for the Timer0 has no effect on the Watchdog Timer, and vice-versa. T1OSCEN bit is now OSCEN. The program space is implemented as a single contiguous block, as compared to Microchip’s mid-range and high-end controllers that divided the program memory into pages. If interrupt priority is not used, all interrupts are treated as high priority, and function the same way as in mid-range and high-end controllers. If interrupt priority is not used (all interrupt priority bits are set), GIE and PEIE/GIEL function the same as mid-range and high-end controllers. Look-up tables are implemented two ways in the 18CXXX devices. The Computed Goto is compatible with the PIC16CXXX and PIC17CXXX parts. Code written for those devices will run on the PIC18CXXX devices with little or no change. Table reads are implemented on the PIC17CXXX and PIC18CXXX devices. However, table operations on the PIC18CXXX work differently than on the PIC17CXXX. Note: The Timer0 prescaler is not shared with the watchdog as a postscaler. The Watchdog Timer has its own dedicated postscaler. The control bits and prescaler select bits are implemented as EPROM configuration bits. Note: To achieve a 1:1 prescaler assignment for the TMR0 register, turn off the TMR0 prescaler (PSA is cleared). 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-16  2000 Microchip Technology Inc. E.1 Differences to the Mid-Range CCP module The CCP1 and CCP2 modules function exactly as the modules of the mid-range devices with two exceptions: 1. The time base used for capture and compare of the CCP module can come from either Timer1 or Timer3. The default time base for both CCP modules when configured as a capture or compare mode is Timer1. Timer3 can be selected by configuring the Timer3 T3CCPx control bits in the Timer3 control register. 2. A toggle on compare mode has been added to the CCP modules. E.1.1 Compatibility to PIC16CXX Interrupts When the IPE bit in the RCON register is clear, the GIE/GIEH bit (INTCON<7>) is the global interrupt enable for all interrupts. The PEIE/GIEL bit (INTCON<6>) is still used to enable peripheral interrupts. The high priority interrupt vector is the same as the PIC16CXX interrupt vector and returns will work the same way. ISR code written for the PIC16CXX devices run unchanged as long as IPE=0. 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-17 Section 36. Appendix Appendix 36 E.2 Instruction Set Comparison Table E-1 shows all the PIC18CXXX instructions and if that instruction is available in the other families (PIC17CXXX, PIC16CXX, or PIC16C5XX). Some instructions may be available, but have slightly different characteristics. Attached are notes regarding any major differences. Table E-1: PIC18CXXX Instruction Set Comparison BYTE-ORIENTED FILE REGISTER OPERATIONS PIC18CXXX Instruction Set PIC17CXX PIC16CXX PIC16C5X ADDWF Yes Yes Yes ADDWFC Yes — — ANDWF Yes Yes Yes CLRF Yes (Note 1) Yes Yes COMF Yes Yes Yes CPFSEQ Yes — — CPFSGT Yes — — CPFSLT Yes — — DAW Yes (Note 5) — — DCFSNZ Yes — — DECF Yes Yes Yes DECFSZ Yes Yes Yes INCF Yes Yes Yes INCFSZ Yes Yes Yes INFSNZ Yes — — IORWF Yes Yes Yes MOVF — Yes Yes MOVFF — —— MOVWF Yes Yes Yes MULWF Yes — — NEGF Yes (Note 6) — — NOP Yes Yes Yes Note 1: CLRF and SETF instructions do not have ’s’ bit that exists in the PIC17CXX instructions. 2: CLRW does not exist as an instruction, but since the WREG is mapped in address space, WREG can be cleared using the CLRF instruction. 3: The RLCF and RRCF instructions are functionally identical to the PIC16CXX instructions RLF and RRF. 4: CALL and GOTO instructions are now 2-word instructions. 5: DAW always has the WREG as the destination. The PIC17CXX can also have a file as the destination. 6: NEGW is replaced by NEGF with the file register always being the destination. 7: The mnemonics for 17CXX instructions TABLRD and TABLWT are changed to TBLRD and TBLWT, respectively, and these instructions are special instructions which only exchange data between the TABLAT and the program memory. 8: The lower nibble of the Bank Select Register (BSR) now specifies which bank of RAM is selected. 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-18  2000 Microchip Technology Inc. BYTE-ORIENTED FILE REGISTER OPERATIONS (Continued) Instruction Set PIC17CXX PIC16CXX PIC16C5X RLCF Yes Yes (Note 3) Yes (Note 3) RLNCF Yes — — RRCF Yes Yes (Note 3) Yes (Note 3) RRNCF Yes — — SETF Yes (Note 1) — — SUBFWB — —— SUBWF Yes Yes Yes SUBWFB Yes — — SWAPF Yes Yes Yes TABLRD Yes (Note 7) — — TABLWT Yes (Note 7) — — TSTFSZ Yes — — XORWF Yes Yes Yes BIT-ORIENTED FILE REGISTER OPERATIONS Instruction Set PIC17CXX PIC16CXX PIC16C5X BCF Yes Yes Yes BSF Yes Yes Yes BTFSC Yes Yes Yes BTFSS Yes Yes Yes BTG Yes — — Note 1: CLRF and SETF instructions do not have ’s’ bit that exists in the PIC17CXX instructions. 2: CLRW does not exist as an instruction, but since the WREG is mapped in address space, WREG can be cleared using the CLRF instruction. 3: The RLCF and RRCF instructions are functionally identical to the PIC16CXX instructions RLF and RRF. 4: CALL and GOTO instructions are now 2-word instructions. 5: DAW always has the WREG as the destination. The PIC17CXX can also have a file as the destination. 6: NEGW is replaced by NEGF with the file register always being the destination. 7: The mnemonics for 17CXX instructions TABLRD and TABLWT are changed to TBLRD and TBLWT, respectively, and these instructions are special instructions which only exchange data between the TABLAT and the program memory. 8: The lower nibble of the Bank Select Register (BSR) now specifies which bank of RAM is selected. 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-19 Section 36. Appendix Appendix 36 CONTROL OPERATIONS Instruction Set PIC17CXX PIC16CXX PIC16C5X BC — —— BN — —— BNC — —— BNN — —— BNV — —— BNZ — —— BRA — —— BV — —— BZ — —— CALL (Note 4) Yes Yes Yes CLRWDT Yes Yes Yes GOTO (Note 4) Yes Yes Yes POP — —— PUSH — —— RCALL — —— RESET — —— RETFIE Yes Yes RETURN Yes Yes Yes SLEEP Yes Yes Yes LITERAL OPERATIONS Instruction Set PIC17CXX PIC16CXX PIC16C5X ADDLW Yes Yes Yes ANDLW Yes Yes Yes IORLW Yes Yes Yes LFSR — —— MOVLB Yes (Note 8) — — MOVLW Yes Yes Yes MULLW Yes — — RETLW Yes Yes Yes SUBLW Yes Yes Yes XORLW Yes Yes Yes Note 1: CLRF and SETF instructions do not have ’s’ bit that exists in the PIC17CXX instructions. 2: CLRW does not exist as an instruction, but since the WREG is mapped in address space, WREG can be cleared using the CLRF instruction. 3: The RLCF and RRCF instructions are functionally identical to the PIC16CXX instructions RLF and RRF. 4: CALL and GOTO instructions are now 2-word instructions. 5: DAW always has the WREG as the destination. The PIC17CXX can also have a file as the destination. 6: NEGW is replaced by NEGF with the file register always being the destination. 7: The mnemonics for 17CXX instructions TABLRD and TABLWT are changed to TBLRD and TBLWT, respectively, and these instructions are special instructions which only exchange data between the TABLAT and the program memory. 8: The lower nibble of the Bank Select Register (BSR) now specifies which bank of RAM is selected. 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-20  2000 Microchip Technology Inc. Table E-2 shows the instructions that are used in the other PICmicro families, but are not used in the PIC18CXXX instruction set. Table E-2: Instructions Not Implemented or Modified From PIC18CXXX BYTE-ORIENTED FILE REGISTER OPERATIONS Instruction PIC17CXX PIC16CXX PIC16C5X Comment CLRW — Yes (Note 1) — = CLRF WREG DAW Yes (Note 6) — — MOVFP Yes (Note 7) — — = MOVFF REG1, REG2 MOVPF Yes (Note 7) — — = MOVFF REG2, REG1 NEGW Yes (Note 3) — — RLF — Yes (Note 4) Yes (Note 4) RRF — Yes (Note 4) Yes (Note 4) TLRD Yes — — TLWT Yes — — CONTROL OPERATIONS Instruction PIC17CXX PIC16CXX PIC16C5X CALL Yes (Note 2) Yes (Note 2) Yes (Note 2) GOTO Yes (Note 2) Yes (Note 2) Yes (Note 2) LCALL Yes — — MOVLR Yes — — OPTION — — (Note 5) Yes TRIS — — (Note 5) Yes LITERAL OPERATIONS Instruction PIC17CXX PIC16CXX PIC16C5X MOVLR Yes — — Note 1: CLRW does not exist as an instruction, but since the WREG is mapped in address space, WREG can be cleared using the CLRF instruction. 2: CALL and GOTO instructions are now 2-word instructions. 3: NEGW is replaced by NEGF with the file register always being the destination. 4: The mnemonics for RLF and RRF have been changed to RLCF and RRCF, respectively, but the functionality is identical. 5: This instruction is not recommended in PIC16CXX devices. 6: The PIC17CXX may also specify the file as the destination. 7: When migrating software the MOVFF instruction can be used. 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-21 Section 36. Appendix Appendix 36 APPENDIX F: ASCII CHARACTER SET The PICmicro assembler recognizes the ASCII characters shown in Table F-1. Table F-1: ASCII Character Set (7-bit Code) Least Significant nibble (LSn) Most Significant nibble (MSn) 0 (0) 1 (16) 2 (32) 3 (48) 4 (64) 5 (80) 6 (96) 7 (112) 0 NUL DLE SP 0 @ P ’ p 1 SOH DC1 ! 1 A Q a q 2 STX DC2 " 2 B R b r 3 ETX DC3 # 3 C S c s 4 EOT DC4 $ 4 D T d t 5 ENQ NAK % 5 E U e u 6 ACK SYN & 6 F V f v 7 BEL ETB ’ 7 GWg w 8 BS CAN ( 8 H X h x 9 HT EM ) 9 I Y i y A LF SUB * : J Z j z B VT ESC + ; K [ k { C FF FS , < L \ l | D CR GS — =M ] m} E SO RS . > N ^ n ~ F SI US / ? O _ o DEL Note: To obtain the decimal value, add the decimal most significant nibble (MSn) to the decimal least significant nibble (LSn). 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-22  2000 Microchip Technology Inc. APPENDIX G: COMMON SOCKET PINOUTS This appendix shows the pinouts for some of the standard sockets that are commonly used in prototype and production applications. You may use these pinouts when you wiretap your breadboard with a socket. These diagrams will make constructing, debugging, and troubleshooting with the Picmicro families quicker and easier. These figures shown in this appendix are for sockets that correspond to the following package types: PLCC-to-PGA sockets • 28-pin PLCC/CLCC • 44-pin PLCC/CLCC • 68-pin PLCC/CLCC DIP sockets • 18-pin • 28-pin • 40-pin SOIC sockets • 18-pin • 28-pin 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-23 Section 36. Appendix Appendix 36 Figure G-1: DIP Packages Pinouts (Bottom View ) 1 2 3 4 5 6 7 8 9 18 17 16 15 14 13 12 11 10 18-pin 1 2 3 4 5 6 7 8 9 10 11 12 13 14 28 27 26 25 24 23 22 21 20 19 18 17 16 15 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 40 39 38 37 36 35 34 33 32 31 30 29 28 27 26 25 24 23 22 21 28-pin 40-pin Bottom View Bottom View Bottom View 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-24  2000 Microchip Technology Inc. Figure G-2: PGA Package Pinout (Bottom View) for LCC Packages 26 28 25 27 1 3 6 5 2 4 23 24 21 22 19 20 17 15 16 14 13 12 11 10 9 18 8 7 28-pin 42 44 39 43 1 3 5 7 2 4 35 31 29 27 25 23 24 22 21 18 17 15 26 11 33 13 37 9 41 36 32 30 34 38 8 19 16 12 14 10 28 6 20 40 44-pin Bottom View Bottom View 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-25 Section 36. Appendix Appendix 36 Figure G-2: PGA Package Pinout (Bottom View) for LCC Packages (Continued) 61 63 62 64 66 2 12 65 67 35 27 25 23 24 21 20 18 17 15 41 37 33 38 36 34 32 30 8 19 14 13 28 6 22 4 16 1 44 3 579 60 68 11 10 31 29 40 39 42 43 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 26 68-pin 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-26  2000 Microchip Technology Inc. Figure G-2: PGA Package Pinout (Bottom View) for LCC Packages (Continued) 75 77 76 78 80 2 79 83 41 33 25 23 24 21 20 18 17 15 47 43 39 44 42 38 36 40 8 19 14 27 6 22 4 16 1 54 3579 74 84 10 13 37 35 46 45 48 49 50 56 57 58 59 60 61 62 63 64 65 66 67 68 69 26 84-pin Bottom View 11 12 29 28 31 30 34 32 51 52 53 55 70 71 72 73 82 81 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39537A-page 36-27 Section 36. Appendix Appendix 36 Figure G-3: SOIC Socket Pinouts (Bottom View) 18 16 14 12 10 2 4 1 17 15 11 13 5 9 8 3 6 7 28 27 25 21 23 24 20 26 22 19 15 17 1 2 4 8 6 5 9 3 7 18 16 10 14 12 11 13 18-pin 28-pin Bottom View Bottom View 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39537A-page 36-28  2000 Microchip Technology Inc. APPENDIX H: REVISION HISTORY Revision A This is the initial released revision of the Enhanced MCU Reference Guide Appendix. 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39538A-page 37-1 Glossary 37 Section 37. Glossary A A/D See description under "Analog to Digital (A/D)". Access RAM This is a region of data memory RAM that can be accessed regardless of the currently selected bank. This allows special function registers to be accessed by the instruction without changing the currently selected bank. Access RAM also contains some General Purpose Registers (GPRs). This is useful for the saving of required variables during context switching (such as during an interrupt). Acquisition Time (TACQ) This is related to Analog to Digital (A/D) converters. This is the time that the PIC18CXXX A/D’s holding capacitor acquires the analog input voltage level connected to it. When the GO bit is set, the analog input is disconnected from the holding capacitor and the A/D conversion is started. ALU Arithmetical Logical Unit. Device logic that is responsible for the mathematical (add, subtract, ...), logical (and, or, ...), and shifting operation. Analog to Digital (A/D) The conversion of an analog input voltage to a ratiometric digital equivalent value. Assembly Language A symbolic language that describes the binary machine code in a readable form. AUSART Addressable Universal Synchronous Asynchronous Receiver Transmitter. This module can either operate as a full duplex asynchronous communications port, or a half duplex synchronous communications port. When operating in the asynchronous mode, the USART can be interfaced to a PC’s serial port. 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39538A-page 37-2  2000 Microchip Technology Inc. B Bank This is a method of addressing Data Memory. Since enhanced devices have 8-bits for direct addressing, instructions can address up to 256 bytes. To allow more data memory to be present on a device, data memory is partitioned into contiguous banks of 256 bytes each. To select the desired bank, the bank selection register (BSR) needs to be appropriately configured. 16 banks can be implemented. Baud Generally this is how the communication speed of serial ports is described. Equivalent to bits per second (bps). BCD See description under "Binary Coded Decimal (BCD)". Binary Coded Decimal (BCD) Each 4-bit nibble expresses a digit from 0-9. Usually two digits are contained in a byte yielding a range of 0 - 99. BOR See description under "Brown-out Reset (BOR)". Brown-out A condition where the supply voltage of the device temporarily falls below the specified minimum operation point. This can occur when a load is switched on and causes the system/device voltage to drop. Brown-out Reset (BOR) Circuitry which will force the device to the RESET state if the device’s power supply voltage falls below a specified voltage level. Some devices have an internal BOR circuit, while other devices would require an external circuit to be created. Bus width This is the number of bits of information that a bus carries. For the Data Memory, the bus width is 8-bits. For enhanced devices the Program Memory bus width is 16-bits. 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39538A-page 37-3 Section 37. Glossary Glossary 37 C Capture A function of the CCP module in which the value of a timer/counter is “captured” into a holding register module when a predetermined event occurs. CCP Capture, Compare, Pulse Width Modulation (PWM). The CCP module can be configured to operate as an input capture, or a timer compare, or a PWM output. Compare A function of the CCP module in which the device will perform an action when a timer’s register value matches the value in the compare register. Compare Register A 16-bit register that contains a value that is compared to the 16-bit TMR1 register. The compare function triggers when the counter matches the contents of the compare register. Capture Register A 16-bit register that is loaded with the value of the 16-bit TMR1 register when a capture event occurs. Configuration Word This is a non-volatile memory location that specifies the characteristics that the device will have for operation (such as oscillator mode, WDT enable, start-up timer enables). These characteristics can be specified at the time of device programming. For EPROM memory devices, as long as the bit is a '1', it may at a later time be programmed as a '0'. The device must be erased for a '0' to be returned to a '1'. Conversion Time (Tconv) This is related to Analog to Digital (A/D) converters. This is the time that the PIC18CXXX A/D’s converter requires to convert the analog voltage level on the holding capacitor to a digital value. CPU Central Processing Unit. Decodes the instructions, and determines the operands and operations that are needed for program execution. Arithmetic, logical, or shift operations are passed to the ALU. 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39538A-page 37-4  2000 Microchip Technology Inc. D D/A See description under "Digital to Analog". DAC Digital to analog converter. Data Bus The bus which is used to transfer data to and from the data memory. Data EEPROM Data Electrically Erasable Programmable Read Only Memory. This memory is capable of being programmed and re-programmed by the CPU to ensure that in the case of a power loss, critical values/variables are retained in the non-volatile memory. Data Memory The memory that is on the Data Bus. This memory is volatile (SRAM) and contains both the Special Function Registers and General Purpose Registers. Direct Addressing When the Data Memory Address is contained in the Instruction. The execution of this type of instruction will always access the data at the embedded address. Digital to Analog The conversion of a digital value to an equivalent ratiometric analog voltage. E EEPROM Electrically Erasable Programmable Read Only Memory. This memory has the capability to be programmed and erased in-circuit. EPROM Electrically Programmable Read Only Memory. This memory has the capability to be programmed in-circuit. Erasing requires that the program memory be exposed to UV light. EXTRC External Resistor-Capacitor (RC). Some devices have a device oscillator option that allows the clock to come from an external RC. This is the same as RC mode on some devices. F FLASH Memory This memory has the capability to be programmed and erased in-circuit. Program Memory technology that is almost functionally equivalent to Program EEPROM Memory. FOSC Frequency of the device oscillator. 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39538A-page 37-5 Section 37. Glossary Glossary 37 G GIO General Input/Output. GPIO General Purpose Input/Output. GPR General Purpose Register (RAM). A portion of the data memory that can be used to store the program’s dynamic variables. H Harvard Architecture In this architecture, the Program Memory and Data Memory buses are separated. This allows concurrent accesses to Data Memory and Program Memory, which increases the performance of the device. All PICmicro devices implement a Harvard Architecture. Holding Capacitor This is a capacitor in the Analog to Digital (A/D) module which “holds” an analog input level once a conversion is started. During acquisition, the holding capacitor is charged/discharged by the voltage level on the analog input pin. Once the conversion is started, the holding capacitor is disconnected from the analog input and “holds” this voltage for the A/D conversion. HS High Speed. One of the device oscillator modes. The oscillator circuit is tuned to support the high frequency operation. Currently this allows for operation from 4 MHz to 25 MHz. 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39538A-page 37-6  2000 Microchip Technology Inc. I I 2C Inter-Integrated Circuit. This is a two wire communication interface. This feature is one of the modes of the "SSP" and "MSSP" modules. Indirect Addressing When the Data Memory Address is not contained in the Instruction, the instruction operates on the INDF address, which causes the Data Memory Address to be the value in the FSR register. The execution of the instruction will always access the data at the address pointed to by the FSR register. Instruction Bus The bus which is used to transfer instruction words from the program memory to the CPU. Instruction Fetch Due to the Harvard architecture, when one instruction is to be executed, the next location in program memory is “fetched” and ready to be decoded as soon as the currently executing instruction is completed. Instruction Cycle The events for an instruction to execute. There are four events which can generally be described as: Decode, Read, Execute, and Write. Not all events will be done by all instructions. To see the operations during the instruction cycle, please look at the description of each instruction. Four external clocks (Tosc) make one instruction cycle (TCY). Interrupt A signal to the CPU that causes the program flow to be forced to the Interrupt Vector Address (04h in program memory). Before the program flow is changed, the contents of the Program Counter (PC) are forced onto the hardware stack, so that program execution may return to the interrupted point. INTRC Internal Resistor-Capacitor (RC). Some devices have a device oscillator option that allows the clock to come from an internal RC combination. 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39538A-page 37-7 Section 37. Glossary Glossary 37 L LCD Liquid Crystal Display. Useful for giving visual status of a system. This may require the specification of custom LCD glass. LED Light Emitting Diode. Useful for giving visual status of a system. Literal This is a constant value that is embedded in an instruction word. Long Word Instruction An instruction word that embeds all the required information (opcode and data) into a single word. This ensures that every instruction is accessed and executed in a single instruction cycle. LP One of the device oscillator modes. Used for low frequency operation which allows the oscillator to be tuned for low power consumption. Operation is up to 200 kHz. LSb Least Significant Bit. LSB Least Significant Byte. M Machine cycle This is a concept where the device clock is divided down to a unit time. For PICmicro devices, this unit time is 4 times the device oscillator (4TOSC), also known as TCY. MSb Most Significant Bit. MSB Most Significant Byte. MSSP Master Synchronous Serial Port. The MSSP has two operational functions. The first is a "Serial Peripheral Interface (SPI)" and the second is the Inter-Integrated Circuit ("I2 C"). The I2C function supports both master and slave functions in hardware. 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39538A-page 37-8  2000 Microchip Technology Inc. N Non-Return to Zero (NRZ) Two-level encoding used to transmit data over a communications medium. A bit value of '1' indicates a high voltage signal. A bit value of '0' indicates a low voltage signal. The data line defaults to a high level. NRZ See description under "Non-Return to Zero (NRZ)". O Opcode The portion of the 16-bit instruction word that specifies the operation that needs to occur. The opcode is of variable length depending on the instruction that needs to be executed. The opcode varies from 4-bits to 8-bits. The remainder of the instruction word contains program or data memory information. Oscillator Start-up Timer (OST) This timer counts 1024 crystal/resonator oscillator clock cycles before releasing the internal RESET signal. OST See description under "Oscillator Start-up Timer (OST)". 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39538A-page 37-9 Section 37. Glossary Glossary 37 P Pages Method of addressing the Program Memory. Mid-range devices have 11-bit addressing for CALL and GOTO instructions, which gives these instructions a 2-Kword reach. To allow more program memory to be present on a device, program memory is partitioned into contiguous pages, where each page is 2-Kwords. To select the desired page, the page selection bits (PCLATCH<5:4>) need to be appropriately configured. Since there are presently 2 page selection bits, 4 pages can be implemented. The enhanced devices do not have paging. PIC16CXXX code migrates to the PIC18CXXX without modification (with respect to paging). Optimization may be implemented. Parallel Slave Port (PSP) A parallel communication port which is used to interface to a microprocessor’s 8-bit data bus. POP A term used to refer to the action of restoring information from a stack (software and/or hardware). See "Serial Peripheral Interface (SPI)". Postscaler A circuit that slows the rate of the interrupt generation (or WDT Reset) from a counter/timer by dividing it down. Power-on Reset (POR) Circuitry which determines if the device power supply voltage rose from a powered down level (0V). If the device power supply voltage is rising from ground, a device RESET occurs and the PWRT is started. Power-up Timer (PWRT) A timer which holds the internal RESET signal low for a timed delay to allow the device voltage to reach the valid operating voltage range. Once the timer times out, the OST circuitry is enabled (for all crystal/resonator device oscillator modes). Prescaler A circuit that slows the rate of a clocking source to a counter/timer. Program Bus The bus used to transfer instruction words from the program memory to the CPU. Program Counter A register which specifies the address in program memory that contains the next instruction to execute. Program Memory Any memory that is on the program memory bus. Static variables may be contained in program memory, such as tables. PSP See description under "Parallel Slave Port (PSP)". Pulse Width Modulation (PWM) A serial signal in which the information is contained in the width of a (high) pulse of a constant frequency signal. A PWM output, from the CCP module, of the same duty cycle requires no software overhead. PUSH A term used to refer to the action of saving information onto a stack (software and/or hardware). See "Serial Peripheral Interface (SPI)". PWM See description under "Pulse Width Modulation (PWM)". 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39538A-page 37-10  2000 Microchip Technology Inc. Q Q-cycles This is the same as a device oscillator cycle. There are 4 Q-cycles for each instruction cycle. R RC Resistor-Capacitor. The default configuration for the device oscillator. This allows a “Real-Cheap” implementation for the device clock source. This clock source does not supply an accurate time-base. Read-Modify-Write This is where a register is read, then modified, and then written back to the original register. This may be done in one instruction cycle or multiple instruction cycles. Register File This is the Data Memory. Contains the SFRs and GPRs. ROM Read Only Memory. Memory that is fixed and cannot be modified. 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39538A-page 37-11 Section 37. Glossary Glossary 37 S Sampling Time Sampling time is the complete time to get an A/D result. It includes the acquisition time and the conversion time. Serial Peripheral Interface (SPI) This is one of the modes of the "SSP" and "MSSP" modules. This is typically a 3-wire interface, with a data out line, a data in line, and a clock line. Since the clock is present, this is a synchronous interface. SFR Special Function Register. These registers contain the control bits and status information for the device. Single Cycle Instruction An instruction that executes in a “single” machine cycle (TCY). SLEEP This is a low power mode of the device, where the device’s oscillator circuitry is disabled. This reduces the current the device consumes. Certain peripherals may be placed into modes where they continue to operate. Special Function Registers (SFR) These registers contain the control bits and status information for the device. SPI See description under "Serial Peripheral Interface (SPI)". SSP Synchronous Serial Port. The SSP has two operational functions. The first is a "Serial Peripheral Interface (SPI)"and the second is the Inter-Integrated Circuit ("I2 C"). The I2C function supports the slave function in hardware and has additional status information to support a software implemented master. Stack A portion of the CPU that retains the return address for program execution. The stack gets loaded with the value in the Program Counter when a CALL instruction is executed or if an interrupt occurs. 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39538A-page 37-12  2000 Microchip Technology Inc. T TAD In the A/D Converter, the time for a single bit of the analog voltage to be converted to a digital value. TCY The time for an instruction to complete. This time is equal to Fosc/4 and is divided into four Q-cycles. Tosc The time for the single period of the device oscillator. U USART Universal Synchronous Asynchronous Receiver Transmitter. This module can either operate as a full duplex asynchronous communications port, or a half duplex synchronous communications port. When operating in the asynchronous mode, the USART can be interfaced to a PC’s serial port. 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39538A-page 37-13 Section 37. Glossary Glossary 37 V Voltage Reference (VREF) A voltage level that can be used as a reference point for A/D conversions (AVDD and AVSS) or the trip point for comparators. von Neumann Architecture In this architecture the Program Memory and Data Memory are contained in the same area and use the same bus. This means that accesses to the program memory and data memory must occur sequentially, which affects the performance of the device. W W Register See description under "Working Register (WREG)". Watchdog Timer (WDT) Used to increase the robustness of a design by recovering from software flows that were not expected in the design of the product or from other system related issues. The Watchdog Timer causes a RESET if it is not cleared prior to overflow. The clock source for a PICmicro device is an on-chip RC oscillator which enhances system reliability. WDT Watchdog Timer. Working Register (WREG) Can also be thought of as the accumulator of the device. Also used as an operand in conjunction with the ALU during two operand instructions. X XT One of the device oscillator modes. Used for operation from 100 kHz to 4 MHz. 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM PIC18C Reference Manual DS39538A-page 37-14  2000 Microchip Technology Inc. 37.1 Revision History Revision A This is the initial released revision of the Glossary. 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-1 Source Code Source Code APPENDIX I: SOURCE CODE ; Software License Agreement ; ; The software supplied herewith by Microchip Technology Incorporated ; (the “Company”) for its PICmicro® Microcontroller is intended and ; supplied to you, the Company’s customer, for use solely and ; exclusively on Microchip PICmicro Microcontroller products. The ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, ; WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED ; TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A ; PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, ; IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR ; CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. ; ;*********************************************************** ; PIC18CXX2 EXAMPLE CODE FOR PICDEM-2 ; ; TITLE: USART Demo Demonstration ; FILENAME: usart.asm ; REVISION HISTORY: A 5/13/00 jb format change ; HARDWARE: PICDEM-2 board ; FREQUENCY: 4MHz : ;************************************************************ Software License Agreement The software supplied herewith by Microchip Technology Incorporated (the “Company”) for its PICmicro® Microcontroller is intended and supplied to you, the Company’s customer, for use solely and exclusively on Microchip PICmicro Microcontroller products. The software is owned by the Company and/or its supplier, and is protected under applicable copyright laws. All rights are reserved. Any use in violation of the foregoing restrictions may subject the user to criminal sanctions under applicable laws, as well as to civil liability for the breach of the terms and conditions of this license. THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. 39500 18C Reference Manual.book Page 1 Monday, July 10, 2000 6:12 PM DS39540A-page 36-2 PIC18C Reference Manual  2000 Microchip Technology Inc. ; This program demonstrates basic functionality of the USART. ; ; Port B is connected to 8 LEDs. ; When the PIC18C452 receives a word of data from ; the USART, the value is displayed on the LEDs and ; is retransmitted to the host computer. ; ; Set terminal program to 9600 baud, 1 stop bit, no parity list p=18c452; set processor type list n=0; supress page breaks in list file include ;************************************************************ ; Reset and Interrupt Vectors org 00000h; Reset Vector gotoStart org 00008h; Interrupt vector gotoIntVector ;************************************************************ ; Program begins here org 00020h; Beginning of program EPROM Start clrfLATB; Clear PORTB output latches clrfTRISB ; Config PORTB as all outputs bcf TRISC,6; Make RC6 an output movlw19h; 9600 baud @4MHz movwfSPBRG bsf TXSTA,TXEN; Enable transmit bsf TXSTA,BRGH; Select high baud rate bsf RCSTA,SPEN; Enable Serial Port bsf RCSTA,CREN; Enable continuous reception bcf PIR1,RCIF; Clear RCIF Interrupt Flag bsf PIE1,RCIE; Set RCIE Interrupt Enable bsf INTCON,PEIE; Enable peripheral interrupts bsf INTCON,GIE; Enable global interrupts ;************************************************************ ; Main loop 39500 18C Reference Manual.book Page 2 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-3 Source Code Source Code Main gotoMain; loop to self doing nothing ;************************************************************ ; Interrupt Service Routine IntVector ; save context (WREG and STATUS registers) if needed. btfssPIR1,RCIF; Did USART cause interrupt? gotoOtherInt; No, some other interrupt movlw06h; Mask out unwanted bits andwfRCSTA,W; Check for errors btfssSTATUS,Z; Was either error status bit set? gotoRcvError; Found error, flag it movfRCREG,W; Get input data movwfLATB; Display on LEDs movwfTXREG; Echo character back gotoISREnd; go to end of ISR, restore context, return RcvError bcf RCSTA,CREN; Clear receiver status bsf RCSTA,CREN movlw0FFh; Light all LEDs movwfPORTB gotoISREnd; go to end of ISR, restore context, return OtherInt goto$ ; Find cause of interrupt and service it before returning from ; interrupt. If not, the same interrupt will re-occur as soon ; as execution returns to interrupted program. ISREnd ; Restore context if needed. retfie end 39500 18C Reference Manual.book Page 3 Monday, July 10, 2000 6:12 PM DS39540A-page 36-4 PIC18C Reference Manual  2000 Microchip Technology Inc. ; ; Software License Agreement ; ; The software supplied herewith by Microchip Technology Incorporated ; (the “Company”) for its PICmicro® Microcontroller is intended and ; supplied to you, the Company’s customer, for use solely and ; exclusively on Microchip PICmicro Microcontroller products. The ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, ; WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED ; TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A ; PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, ; IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR ; CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. ; ;************************************************************ ; PIC18CXX2 EXAMPLE CODE FOR PICDEM-2 ; ; TITLE:Button Press Demonstration ; FILENAME: bttn.asm ; REVISION HISTORY: A 5/13/00 jb format change ; HARDWARE: PICDEM-2 board ; FREQUENCY: 4MHz : ;************************************************************ ; This program demonstrates how to read a push-button and control LED's. ; ; Port B is connected to 8 LEDs. ; RA4 is connected to a switch (S2). ; This program increments a file register count every time S2 is pressed. ; The value of count is displayed on the LEDs connected to Port B. ; The LEDs should increment in a binary manner each time S2 is pressed. list p=18c452 #include ;************************************************************ ; variables Countequ0x000 39500 18C Reference Manual.book Page 4 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-5 Source Code Source Code ;************************************************************ ; reset vectors org 00000h; Reset Vector gotoStart ;************************************************************ ;program code starts here org 00020h; Beginning of program EPROM Start clrfLATB; Clear PORTB output latch clrfTRISB; Make PORTB pins all outputs clrfCount; Clear Count Loop btfscPORTA,4; Has S2 been pressed? (Normally high, goes low when pressed.) gotoLoop; No, check again IncCount incfCount,F; Increment Count movffCount,LATB; move Count to PORTB Debounce btfssPORTA,4; Has key been released? gotoDebounce; No, wait some more gotoLoop; yes, wait for next key press END ; directive indicates end of code 39500 18C Reference Manual.book Page 5 Monday, July 10, 2000 6:12 PM DS39540A-page 36-6 PIC18C Reference Manual  2000 Microchip Technology Inc. ; ; Software License Agreement ; ; The software supplied herewith by Microchip Technology Incorporated ; (the “Company”) for its PICmicro® Microcontroller is intended and ; supplied to you, the Company’s customer, for use solely and ; exclusively on Microchip PICmicro Microcontroller products. The ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, ; WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED ; TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A ; PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, ; IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR ; CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. ; ;************************************************************ ; PIC18CXX2 EXAMPLE CODE FOR PICDEM-2 ; ; TITLE:I2C hardware interface PICmicro to serial EEPROM ; FILENAME: i2c.asm ; REVISION HISTORY: A 5/13/00 jb format change ; HARDWARE: PICDEM-2 board ; FREQUENCY: 4MHz : ;************************************************************ ; This program uses the advanced features of the PIC18C452, specifically ; full hardware support for master mode I2C ; ; This program loads EEPROM address 0x00 to 0xFF with 0x00 to 0xFF ; (each location contains its own address). : ; Each location is then read out, and compared to what is expected. ; The data is displayed on the LEDS. If the data is wrong, ; the TX LED will flash briefly before proceeding to the next address. ; ; Revised Version(05-05-99). ; Note: 1) All timing is based on a reference crystal frequency of 4MHz ; which is equivalent to an instruction cycle time of 1 usec. ; 2) Address and literal values are read in hexidecimal unless ; otherwise specified. ; 3) The PIC18C452 MSSP module offers full hardware support for 39500 18C Reference Manual.book Page 6 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-7 Source Code Source Code ; master mode I2C. ;************************************************************ LIST P=18C452 #include listn=0 ; suppress list file page breaks listST=off; suppress list file symbol table ;************************************************************ ; Register File Assignment EEADDRequ0x000; Address register EEDATAequ0x001; data to read/write EESLAVE equ 0x002; Device address (1010xxxy) DelayCtr1equ0x003; delay routine counter DelayCtr2equ0x004; delay routine counter SlaveAddrequ0xA0; slave address literal ;************************************************************ ; Vector Assignment ORG 0x00000 gotoStart; Reset Vector ;************************************************************ ; Main Program ORG 0x00020; Start of Program space Start ; initialize PORTB clrfLATB; Clear PORTB output latch clrfTRISB; Set PORTB as all outputs ; configure SSP for hardware master mode I2C bsf SSPSTAT,SMP; I2C slew rate control disabled bsf SSPCON1,SSPM3; I2C master mode in hardware bsf SSPCON1,SSPEN; enable SSP module movlw0x09; set I2C clock rate to 100kHz movwfSSPADD bsf TRISC,3; I2C SCL pin is input bsf PORTC,3; (will be controlled by SSP) bsf TRISC,4; I2C SDA pin is input bsf PORTC,4; (will be controlled by SSP) movlwSlaveAddr; EEPROM I2C address 39500 18C Reference Manual.book Page 7 Monday, July 10, 2000 6:12 PM DS39540A-page 36-8 PIC18C Reference Manual  2000 Microchip Technology Inc. movwfEESLAVE Main clrfPORTB; initialize variables clrfEEDATA clrfEEADDR WrEEPROM bsf PORTB,7; indicate write, light TX LED rcallDelay bcf EESLAVE,0; write mode rcallWakeSlave; gets slave attention rcallWrADDR; sends EEPROM address rcallWrDATA; sends data to slave rcallStop; send stop bit incfPORTB,F; increment count incfEEDATA,F; increment data incfEEADDR,F; Point to next address btfssEEADDR,7; at end of EEPROM? gotoWrEEPROM; no, write more data RdLoop clrfPORTB; initialize variables clrfEEDATA clrfEEADDR RdEEPROM rcallDelay bcf EESLAVE,0; write mode rcallWakeSlave; gets slave attention rcallWrADDR; sends EEPROM address rcallStop; send stop bit bsf EESLAVE,0; read mode rcallWakeSlave; gets slave attention rcallRdDATA; receive one data byte, leaves idle movfEEDATA,W; get data movwfPORTB; move received data to PORTB xorwfEEADDR,W; compare data with address bz GoodData; branch if DATA = ADDR rcallErrorloop; DATA is wrong, indicate error 39500 18C Reference Manual.book Page 8 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-9 Source Code Source Code GoodDataincfEEADDR,F; Point to next address btfssEEADDR,7; at end of EEPROM? gotoRdEEPROM; no, read more data gotoMain; do it all over again ;************************************************************ ; TX LED flashes to indicate error while displaying received data. Errorloop rcallDelay btg PORTB,7; Toggle TX LED rcallDelay btg PORTB,7; Toggle TX LED rcallDelay btg PORTB,7; Toggle TX LED rcallDelay btg PORTB,7; Toggle TX LED rcallDelay btg PORTB,7; Toggle TX LED rcallDelay btg PORTB,7; Toggle sTX LED return ;************************************************************ ; sends start bit, slave address ; if ACK not recieved, sends restart, tries again ; execution can get stuck in this loop if slave not present ; can be used to poll slave status (retries until slave responds) WakeSlave bsf SSPCON2,SEN; Send start bit btfscSSPCON2,SEN; Has SEN cleared yet? goto$-2 ; No, loop back to test. rWakeSlave bcf PIR1,SSPIF; clear interrupt flag nop movfEESLAVE,W movwfSSPBUF; move slave address to SSPBUF btfssPIR1,SSPIF; has SSP completed sending SLAVE Address? goto$-2 ; no, loop back to test btfssSSPCON2,ACKSTAT; was ACK received from slave? return ; yes, return to calling routine bsf SSPCON2,RSEN; send repeated start bit 39500 18C Reference Manual.book Page 9 Monday, July 10, 2000 6:12 PM DS39540A-page 36-10 PIC18C Reference Manual  2000 Microchip Technology Inc. btfscSSPCON2,RSEN; has repeated start been sent yet? goto$-2 ; no, loop back to test bra rWakeSlave; send slave address again ;************************************************************ ; writes EEPROM memory address, hangs if no ACK WrADDR bcf PIR1,SSPIF; clear interrupt flag movffEEADDR,SSPBUF; move EEPROM address to SSPBUF btfssPIR1,SSPIF; has SSP completed sending EEPROM Address? goto$-2 ; no, loop back to test btfscSSPCON2,ACKSTAT; has slave sent ACK? goto$-2 ; no, try again return ;************************************************************ ; Sends one byte of data to slave, hangs if no ACK WrDATA bcf PIR1,SSPIF; clear interrupt flag movffEEDATA,SSPBUF; move data to SSPBUF btfssPIR1,SSPIF; has SSP completed sending data to EEPROM? goto$-2 ; no, loop back to test btfscSSPCON2,ACKSTAT; has slave sent ACK? goto$-2 ; no, try again return ;************************************************************ ; receive one byte from slave ; do not send ACK, send stop bit instead RdDATA bcf PIR1,SSPIF; clear interrupt flag bsf SSPCON2,RCEN; enable receive mode btfssPIR1,SSPIF; has SSP received a data byte? goto$-2 ; no, loop back to test bsf SSPCON2,ACKDT; no ACK 39500 18C Reference Manual.book Page 10 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-11 Source Code Source Code bsf SSPCON2,ACKEN; send ACKDT bit btfscSSPCON2,ACKEN; has ACKDT bit been sent yet? goto$-2 ; no, loop back to test bsf SSPCON2,PEN; send stop bit btfscSSPCON2,PEN; has stop bit been sent? goto$-2 ; no, loop back to test movffSSPBUF,EEDATA; save data to RAM bcf SSPCON2,RCEN; disable receive mode return ;************************************************************ ; Sends stop bit, waits until sent Stop bsf SSPCON2,PEN; send stop bit btfscSSPCON2,PEN; has stop bit been sent? goto$-2 ; no, loop back to test return ;************************************************************ ; a delay of 98.57mS Delay movlw0x80 movwfDelayCtr2; preset clrfDelayCtr1; clear counter Delay1 decfszDelayCtr1; decrement counter bra Delay1; back to top of loop decfszDelayCtr2; decrement counter bra Delay1; back to top of loop return END 39500 18C Reference Manual.book Page 11 Monday, July 10, 2000 6:12 PM DS39540A-page 36-12 PIC18C Reference Manual  2000 Microchip Technology Inc. ; ; Software License Agreement ; ; The software supplied herewith by Microchip Technology Incorporated ; (the “Company”) for its PICmicro® Microcontroller is intended and ; supplied to you, the Company’s customer, for use solely and ; exclusively on Microchip PICmicro Microcontroller products. The ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, ; WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED ; TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A ; PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, ; IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR ; CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. ; ;************************************************************ ; PIC18CXX2 EXAMPLE CODE FOR PICDEM-2 ; ; TITLE: Interrupt Priority Demonstration ; FILENAME: intrp_ex .asm ; REVISION HISTORY: A 5/13/00 jb format change ; HARDWARE: PICDEM-2 board ; FREQUENCY: 4MHz : ;************************************************************ ; This program uses Timer1 and Timer3 to demonstrate the use of ; interrupt priority. ; ; Timer1 is configured for high-priority interrupts ; and Timer3 is configured for low-priority interrupts. By writing ; to the PORTB LEDS, it is shown that a high-priority interrupts ; override low-priority interrupts. list p=18c452, n=48, t=ON, st=OFF #include "p18c452.inc" ;------------------BIT DEFINITIONS------------------------------------ F EQU 0x0001 ;------------------VECTORS-------------------------------------------- 39500 18C Reference Manual.book Page 12 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-13 Source Code Source Code org 0x000000; reset vector bra START org 0x000008; high priority interrupt vector bra TMR1_ISR org 0x000018; low priority interrupt vector bra TMR3_ISR ;--------------------PROGRAM----------------------------------- START rcall INIT ;Set up priority interrupts. bsf RCON,IPEN;enable priority interrupts. bsf IPR1,TMR1IP;set Timer1 as a high priority interrupt source bcf IPR2,TMR3IP;set Timer3 as a low priority interrupt source bcf PIR1,TMR1IF;clear the Timer1 interrupt flag bcf PIR2,TMR3IF;clear the Timer3 interrupt flag bsf PIE1,TMR1IE;enable Timer1 interrupts bsf PIE2,TMR3IE;enable Timer3 interrupts bsf INTCON,GIEH;set the global interrupt enable bits bsf INTCON,GIEL;" ;Timer1 setup clrfT1CON clrfTMR1H;clear Timer1 high clrfTMR1L;clear Timer1 low bsf T1CON,TMR1ON;turn on Timer1 ;Timer3 setup clrfT3CON movlw0xF0 movwfTMR3H;write 0xf000 to Timer3 clrfTMR3L bsf T3CON,TMR3ON;turn on Timer3 MLOOP gotoMLOOP ;-------------------------------SUBROUTINES--------------------------------- TMR1_ISR ; high priority isr bcf PIR1,TMR1IF;Clear the Timer1 interrupt flag. bcf PORTB,0;Turn off PORTB<0> to indicate high priority 39500 18C Reference Manual.book Page 13 Monday, July 10, 2000 6:12 PM DS39540A-page 36-14 PIC18C Reference Manual  2000 Microchip Technology Inc. ; interrupt has overridden low priority. bsf PORTB,7;Turn on PORTB<7> to indicate high priority ; interrupt is occuring. T1POLL btfssPIR1,TMR1IF;Poll TMR11 interrupt flag to wait for another ; TMR1 overflow. bra T1POLL bcf PIR1,TMR1IF;Clear the Timer1 interrupt flag again. bcf PORTB,7;Turn off PORTB<7> to indicate the ; high-priority ISR is over. retfie TMR3_ISR ;low priority isr bcf PIR2,TMR3IF;Clear the TMR3 interrupt flag. movlw0xF0;Load TMR3 with the value 0xF000 movwfTMR3H clrfTMR3L bsf PORTB,0;Turn on PORTB<0> to indicate low priority ; interrupt is occurring. T3POLL btfssPIR2,TMR3IF;Poll TMR3 interrupt flag to wait for another TMR3 overflow. bra T3POLL movlw0xF0;Load TMR3 with the value 0xF000 again. movwfTMR3H clrfTMR3L bcf PIR2,TMR3IF;Clear the Timer3 interrupt flag again. bcf PORTB,0;Turn off PORTB<0> to indicate the low-priority ISR is over. retfie INIT clrfPORTB; setup portb for outputs clrfDDRB return END 39500 18C Reference Manual.book Page 14 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-15 Source Code Source Code ; ; Software License Agreement ; ; The software supplied herewith by Microchip Technology Incorporated ; (the “Company”) for its PICmicro® Microcontroller is intended and ; supplied to you, the Company’s customer, for use solely and ; exclusively on Microchip PICmicro Microcontroller products. The ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, ; WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED ; TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A ; PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, ; IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR ; CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. ; ;************************************************************ ; PIC18CXX2 EXAMPLE CODE FOR PICDEM-2 ; ; TITLE: Oscillator Switching Demonstration ; FILENAME: osc.asm ; REVISION HISTORY: A 5/13/00 jb format change ; HARDWARE: PICDEM-2 board ; FREQUENCY: 4MHz : ;************************************************************ ; This program demonstrates the use of oscillator switching. ; ; The data held in MYDAT is periodically flashed on the PORTB ; LEDs. Each time a keypress is detected on RA4, the data is ; incremented and the oscillator source is changed. list p=18c452, n=48, t=ON, st=OFF #include "p18c452.inc" KEY EQU 4 ;-------------------18C452 RAM LOCATIONS------------------------------ COUNT0EQU 0x0000 ; used for software timing loop COUNT1EQU 0x0001 ; " 39500 18C Reference Manual.book Page 15 Monday, July 10, 2000 6:12 PM DS39540A-page 36-16 PIC18C Reference Manual  2000 Microchip Technology Inc. MYDAT EQU 0x0002 ; data storage register ;------------------BIT DEFINITIONS------------------------------------ F EQU 0x0001 ;------------------VECTORS-------------------------------------------- ORG 0x000000; reset vector BRA START ;--------------------PROGRAM----------------------------------- START rcall INIT; setup ports, etc. bsf T1CON, T1OSCEN; setup the LP oscillator MLOOP btfss PORTA,KEY rcall KEYPRESS; call keypress routine if ; button is pressed movff MYDAT,PORTB; move data to portb rcall WAIT; wait a while clrf PORTB; clear the port rcall WAIT; wait a while bra MLOOP ;-------------------------------SUBROUTINES--------------------------------- KEYPRESS btfss PORTA,KEY bra KEYPRESS incf MYDAT ; Oscillator source changes every time the subroutine is called. btg OSCCON,SCS return INIT clrf PORTA clrf PORTB 39500 18C Reference Manual.book Page 16 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-17 Source Code Source Code bsf DDRA,4 clrf DDRB return WAIT ; software time delay clrf COUNT0 movlw 0x08 movwf COUNT1 WLOOP decfsz COUNT0,F bra WLOOP decfsz COUNT1,F bra WLOOP return end 39500 18C Reference Manual.book Page 17 Monday, July 10, 2000 6:12 PM DS39540A-page 36-18 PIC18C Reference Manual  2000 Microchip Technology Inc. ; ; Software License Agreement ; ; The software supplied herewith by Microchip Technology Incorporated ; (the “Company”) for its PICmicro® Microcontroller is intended and ; supplied to you, the Company’s customer, for use solely and ; exclusively on Microchip PICmicro Microcontroller products. The ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, ; WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED ; TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A ; PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, ; IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR ; CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. ; ;************************************************************ ; PIC18CXX2 EXAMPLE CODE FOR PICDEM-2 ; ; TITLE: Pulse Width Modulation Demonstration ; FILENAME: pwm_ex .asm ; REVISION HISTORY: A 5/13/00 jb format change ; HARDWARE: PICDEM-2 board ; FREQUENCY: 4MHz : ;************************************************************ ; This program demonstrates pulse width modulation using CCP2. ; ; The PWM period is fixed and then the duty cycle is varied by ; looking up a new value in a table. When the final value of ; the table is read, the table is read in reverse. The PWM output ; is set to RC1. Parts Y3, C6 & C7 are are not installed the ; on the PICDEM 2 board. PWM signal can be observed on RC1 pin. ; list p=18c452, n=48, t=ON, st=OFF #include "p18c452.inc" ;************************************************************ ; bit definitions F EQU 0x0001 39500 18C Reference Manual.book Page 18 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-19 Source Code Source Code ;************************************************************ ; 18C452 RAM LOCATIONS DIRFLAG EQU 0x0000 ;************************************************************ ; 18C452 ROM LOCATIONS TABLADDR EQU 0x0003000 ;************************************************************ ; vectors org 0x000000; reset vector bra START org 0x000008; high priority interrupt vector bra TMR1_ISR ;************************************************************ ; program START ; Set up PWM module ; Set PWM period by writing to PR2 ; Set PWM duty cycle by writing to the CCPR2L register ; and the CCP2CON<5:4>>bits ; Make the CCP2 pin an output by clearing the TRISC<2> bit. clrfCCP2CON;CCP module is off bsf CCP2CON, CCP2M3;select PWM mode bsf CCP2CON, CCP2M2;select PWM mode movlw0x3F;Set PWM frequency to 78.12kHz movwfPR2; bcf TRISC, 1;make channel 1 an output movlw0x00 movwfCCPR2L ;Set the TMR2 prescale value and enable Timer2 by writing to T2CON ;Configure the CCP2 module for PWM operation clrfT2CON;clear T2CON clrfTMR2;clear Timer2 bsf T2CON,TMR2ON;turn on Timer2 ;initialize direction flag for table clrfDIRFLAG ; Initialize the table pointer registers 39500 18C Reference Manual.book Page 19 Monday, July 10, 2000 6:12 PM DS39540A-page 36-20 PIC18C Reference Manual  2000 Microchip Technology Inc. ; to the first location of the data stored in program memory. movlwUPPER(TABLADDR) movwfTBLPTRU movlwHIGH(TABLADDR) movwfTBLPTRH movlwLOW(TABLADDR) movwfTBLPTRL ;setup interrupt bsf RCON,IPEN;enable priority interrupts. bsf IPR1,TMR1IP;set Timer1 as a high priority interrupt source bcf PIR1,TMR1IF;clear the Timer1 interrupt flag bsf PIE1,TMR1IE;enable Timer1 interrupts bsf INTCON,GIEH;set the global interrupt enable bits bsf INTCON,GIEL;" ;Timer1 setup clrfT1CON clrfTMR1H;clear Timer1 high clrfTMR1L;clear Timer1 low bsf T1CON,TMR1ON;turn on Timer1 MLOOP gotoMLOOP ;************************************************************ ; subroutines TMR1_ISR ; high priority isr bcf PIR1,TMR1IF;Clear the Timer1 interrupt flag. rcall CHECK_ADDR btfsc DIRFLAG,0 bra RD_DOWN RD_UP ; Code here does a table read, post-increments, and writes the ; value to the CCPR2L PWM duty-cycle register. tblrd*+ movffTABLAT,CCPR2L 39500 18C Reference Manual.book Page 20 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-21 Source Code Source Code bra T1POLL RD_DOWN ; Code here does a table read, post-decrements, and writes the ; value to the CCPR2L PWM duty-cycle register. tblrd*- movffTABLAT,CCPR2L bra T1POLL T1POLL btfssPIR1,TMR1IF;Poll TMR11 interrupt flag to wait for another ; TMR1 overflow. bra T1POLL bcf PIR1,TMR1IF;Clear the Timer1 interrupt flag again. retfie CHECK_ADDR movlw LOW(TABEND) - 1 subwf TBLPTRL,W bnz CHECK_LOW setf DIRFLAG return CHECK_LOW movlw LOW(TABLADDR) subwf TBLPTRL,W bnz DONE_CHECK clrf DIRFLAG DONE_CHECK return ;-------------------------------DATA--------------------------------------- org TABLADDR DB 0x00,0x06,0x0C,0x12,0x18,0x1E,0x23,0x28 DB 0x2D,0x31,0x35,0x38,0x3A,0x3D,0x3E,0x3F TABEND END 39500 18C Reference Manual.book Page 21 Monday, July 10, 2000 6:12 PM DS39540A-page 36-22 PIC18C Reference Manual  2000 Microchip Technology Inc. ; ; Software License Agreement ; ; The software supplied herewith by Microchip Technology Incorporated ; (the “Company”) for its PICmicro® Microcontroller is intended and ; supplied to you, the Company’s customer, for use solely and ; exclusively on Microchip PICmicro Microcontroller products. The ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, ; WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED ; TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A ; PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, ; IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR ; CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. ; ;************************************************************ ; PIC18CXX2 EXAMPLE CODE FOR PICDEM-2 ; ; TITLE: Table Read Demonstration ; FILENAME: table.asm ; REVISION HISTORY: A 5/13/00 jb format change ; HARDWARE: PICDEM-2 board ; FREQUENCY: 4MHz : ;************************************************************ ; This program demonstrates the use of the TBLRD instruction ; to read program memory. ; ; A pre-defined sequence of data ; bytes is included in program memory. Each time the button ; on pin RA4 is pressed, the next byte of data is accessed ; and displayed on the PORTB LEDS. When the beginning or end of ; the data is reached, the direction of access is reversed. list p=18c452, n=48, t=ON, st=OFF #include "p18c452.inc" ;-------------------18C452 RAM LOCATIONS------------------------------ DIRFLAG EQU 0x0000 39500 18C Reference Manual.book Page 22 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-23 Source Code Source Code ;-------------------18C452 ROM LOCATIONS------------------------------ TABLADDR EQU 0x0003000 ;------------------BIT DEFINITIONS------------------------------------ KEY EQU 4 ;------------------VECTORS-------------------------------------------- ORG 0x000000; rest vector GOTOSTART ORG 0x000008; high priority interrupt vector GOTOSTART ORG 0x000018; low priority interrupt vector GOTOSTART ;--------------------PROGRAM----------------------------------- START bsfDDRA,4; porta button input clrf PORTB; setup portb for outputs clrf DDRB clrf DIRFLAG ; Code should be written here to intialize the table pointer registers ; to the first location of the data stored in program memory. Use ; the appropriate assembler directives to accomplish this. ; (Refer to the 'DATA' statements in this source code.) movlwUPPER(TABLADDR) movwfTBLPTRU movlwHIGH(TABLADDR) movwfTBLPTRH movlwLOW(TABLADDR) movwfTBLPTRL MLOOP btfsc PORTA,KEY; keypress routine bra $ - 2; decrenment PC by 2 because 39500 18C Reference Manual.book Page 23 Monday, July 10, 2000 6:12 PM DS39540A-page 36-24 PIC18C Reference Manual  2000 Microchip Technology Inc. btfss PORTA,KEY; of byte addressing! bra $ - 2 rcall CHECK_ADDR btfsc DIRFLAG,0 bra RD_DOWN RD_UP ; Code here does a table read, post-increments, and writes the ; value to the PORTB LEDS tblrd*+ movff TABLAT,PORTB bra MLOOP RD_DOWN ; Code here does a table read, post-decrements, and writes the ; value to the PORTB LEDS tblrd*- movff TABLAT,PORTB bra MLOOP ;-----------------------------SUBROUTINES-------------------------- CHECK_ADDR movlw LOW(TABEND) - 1 subwf TBLPTRL,W bnz CHECK_LOW setf DIRFLAG return CHECK_LOW movlw LOW(TABLADDR) subwf TBLPTRL,W bnz DONE_CHECK clrf DIRFLAG DONE_CHECK return ;-------------------------------DATA--------------------------------------- 39500 18C Reference Manual.book Page 24 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-25 Source Code Source Code org TABLADDR DATA 0x0201,0x0804,0x2010,0x8040 ; 0x003000 - 0x003007 DATA 0x4281,0x1824,0x2400,0x8142 ; 0x003008 - 0x00300F DATA 0x1211,0x1814,0x2818,0x8848 ; 0x003010 - 0x003017 DATA 0xaa55,0xaa55,0x0100,0x0703 ; 0x003018 - 0x00301F DATA 0x1F0F,0x7F3F,0xFFFF,0xFFFF ; 0x003020 - 0x003027 TABEND END 39500 18C Reference Manual.book Page 25 Monday, July 10, 2000 6:12 PM DS39540A-page 36-26 PIC18C Reference Manual  2000 Microchip Technology Inc. ; ; Software License Agreement ; ; The software supplied herewith by Microchip Technology Incorporated ; (the “Company”) for its PICmicro® Microcontroller is intended and ; supplied to you, the Company’s customer, for use solely and ; exclusively on Microchip PICmicro Microcontroller products. The ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, ; WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED ; TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A ; PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, ; IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR ; CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. ; ;************************************************************ ; PIC18CXX2 EXAMPLE CODE FOR PICDEM-2 ; ; TITLE: Timer Read/Write Demonstration ; FILENAME: tmrrw.asm ; REVISION HISTORY: A 5/13/00 jb format change ; HARDWARE: PICDEM-2 board ; FREQUENCY: 4MHz : ;************************************************************ ; This program uses Timer1 and Timer3 to demonstrate the use of ; 8 and 16 bit write modes. ; ; The counters are used to maintain ; overflow count registers (similar to a RTCC). The 16 bit write to ; Timer3 will introduce an error between the overflow registers. ; This error is calculated in the main program loop and displayed on ; the PORTB LEDS. list p=18c452, n=48, t=ON, st=OFF #include "p18c452.inc" ;-------------------18C452 RAM LOCATIONS------------------------------ T1COUNT EQU 0x0000 T3COUNT EQU 0x0001 39500 18C Reference Manual.book Page 26 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-27 Source Code Source Code ;------------------BIT DEFINITIONS------------------------------------ F EQU 0x0001 ;------------------VECTORS-------------------------------------------- org 0x000000; reset vector bra START org 0x000008; high priority interrupt vector bra TMR_ISR org 0x000018; low priority interrupt vector bra START ;--------------------PROGRAM----------------------------------- START rcallINIT ; Setup Timer1 clrf T1CON bsf T1CON,T1CKPS1; set prescaler 1:8 bsf T1CON,T1CKPS0; set prescaler 1:8 bsf T1CON,RD16; enable 16 bit read/write mode movlw 0x80; initialize TMR1 with 8000 movwf TMR1H; clrf TMR1L; bsf T1CON,TMR1ON; turn on TMR1 ; Setup Timer3 clrf T3CON bsf T3CON,TMR3CS bsf T3CON,RD16 bsf T3CON,T3CKPS1; set prescaler 1:8 bsf T3CON,T3CKPS0; set prescaler 1:8 bcf T3CON,RD16; enable 8 bit read/write mode movlw 0x80; initialize TMR3 with 8000 movwf TMR3H clrf TMR3L bsf T3CON,TMR3ON 39500 18C Reference Manual.book Page 27 Monday, July 10, 2000 6:12 PM DS39540A-page 36-28 PIC18C Reference Manual  2000 Microchip Technology Inc. MLOOP ; Subtract T3COUNT from T1COUNT ; and write the result to PORTB LEDS. movf T3COUNT,W subwf T1COUNT,W movwf PORTB bra MLOOP ;-------------------------------SUBROUTINES--------------------------------- TMR_ISR btfsc PIR1,TMR1IF; check which timer caused the interrupt bra T1_HANDLER btfsc PIR2,TMR3IF bra T3_HANDLER retfie T1_HANDLER ; Load Timer1 with 0x8000 by writing to the high byte only. ; Increment the T1COUNT register. ; Clear the Timer1 interrupt flag. movlw 0x80 movwf TMR1H incf T1COUNT bcf PIR1,TMR1IF retfie T3_HANDLER ; Load Timer3 with 0x8000 by performing a 16-bit timer write. ; Increment the T3COUNT register. ; Clear the Timer3 interrupt flag. movlw 0x80 movwf TMR3H clrf TMR3L incf T3COUNT 39500 18C Reference Manual.book Page 28 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-29 Source Code Source Code bcf PIR2,TMR3IF retfie ;-----------------------------SUBROUTINES---------------------------------- INIT clrf T1COUNT clrf T3COUNT bsf DDRA,4; porta clrf PORTB; setup portb for outputs clrf DDRB bsf PIE1,TMR1IE; enable interrupts bsf PIE2,TMR3IE bsf INTCON,PEIE; enable peripheral interrupts bsf INTCON,GIE; enable global interrupts return END 39500 18C Reference Manual.book Page 29 Monday, July 10, 2000 6:12 PM DS39540A-page 36-30 PIC18C Reference Manual  2000 Microchip Technology Inc. ; ; Software License Agreement ; ; The software supplied herewith by Microchip Technology Incorporated ; (the “Company”) for its PICmicro® Microcontroller is intended and ; supplied to you, the Company’s customer, for use solely and ; exclusively on Microchip PICmicro Microcontroller products. The ; software is owned by the Company and/or its supplier, and is ; protected under applicable copyright laws. All rights are reserved. ; Any use in violation of the foregoing restrictions may subject the ; user to criminal sanctions under applicable laws, as well as to ; civil liability for the breach of the terms and conditions of this ; license. ; ; THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES, ; WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED ; TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A ; PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, ; IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR ; CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. ; ;************************************************************ ; PIC18CXX2 EXAMPLE CODE FOR PICDEM-2 ; ; TITLE: A/D Converter Demonstration ; FILENAME: a2d.asm ; REVISION HISTORY: A 5/13/00 jb format change ; HARDWARE: PICDEM-2 board ; FREQUENCY: 4MHz : ;************************************************************ ; This program is a simple implementation of the ; PIC18C452's A/D. ; ; One Channel is selected (AN0). ; The hardware for this program is the PICDEM-2 board. The program ; converts the potentiometer value on RA0 and displays it as ; an 8 bit binary value on Port B. ; ; The A/D is configured as follows: ; Vref = +5V internal ; A/D Osc. = internal RC ; A/D Channel = AN0 (RA0) LIST P=18C452 #include ; File contains addresses for register and bit names 39500 18C Reference Manual.book Page 30 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39540A-page 36-31 Source Code Source Code ;************************************************************ ; reset and interrupt vectors org 0x00000; Reset Vector Address gotoStart org 0x00008; Interrupt Vector Address gotoISR ; goto Interrupt Service Routine ;************************************************************ ; program code starts here org 0x00020 Start clrfPORTB; clear all bits of PORTB clrfTRISB; Set PORTB as outputs callInitializeAD ; configure A/D module callSetupDelay; delay for 15 instruction cycles bsf ADCON0,GO; Start first A/D conversion MaingotoMain; do nothing loop ;************************************************************ ; Service A/D interrupt ; Get value and display on LEDs ISR ; Save context (WREG and STATUS) if required. btfssPIR1,ADIF; Did A/D cause interrupt? gotoOtherInt; No, check other sources movfADRESH,W; Get A/D value movwfLATB; Display on LEDs bcf PIR1,ADIF; Reset A/D int flag callSetupDelay; Delay for 15 cycles bsf ADCON0,GO; Start A/D conversion gotoEndISR; return from ISR OtherInt ; This would be replaced by code to check and service other interrupt sources 39500 18C Reference Manual.book Page 31 Monday, July 10, 2000 6:12 PM DS39540A-page 36-32 PIC18C Reference Manual  2000 Microchip Technology Inc. goto$ ; trap here, loops to self EndISR ; Restore context if saved. retfie; Return, enables GIE ;************************************************************ ; InitializeAD - initializes and sets up the A/D hardware. ; Select AN0 to AN3 as analog inputs, RC clock, and read AN0. InitializeAD movlwB'00000100'; Make RA0,RA1,RA4 analog inputs movwfADCON1 movlwB'11000001'; Select RC osc, AN0 selected, movwfADCON0; A/D enabled bcf PIR1,ADIF; Clear A/D interrupt flag bsf PIE1,ADIE; Enable A/D interrupt bsf INTCON,PEIE; Enable peripheral interrupts bsf INTCON,GIE; Enable Global interrupts return ;************************************************************ ; This is used to allow the A/D time to sample the input ; (acquisition time). ; ; This routine requires 11 cycles to complete. ; The call and return add another 4 cycles. ; ; 15 cycles with Fosc=4MHz means this delay consumes 15us. SetupDelay movlw.3 ; Load Temp with decimal 3 movwfTEMP SD decfszTEMP, F; Delay loop gotoSD return END 39500 18C Reference Manual.book Page 32 Monday, July 10, 2000 6:12 PM  2000 Microchip Technology Inc. DS39539A-page 1 PIC18C Reference Manual Index Index A A/D Accuracy/Error ............................................25-17, 26-17 ADCON0 Register...........................................25-2, 26-2 ADCON1 Register.................................................... 25-6 ADIF bit...........................................................25-7, 26-7 Analog Input Model Block Diagram.................25-9, 26-9 Configuring Analog Port Pins......................25-11, 26-11 Configuring the Interrupt .................................25-7, 26-7 Configuring the Module...................................25-7, 26-7 Connection Considerations.........................25-18, 26-18 Conversion Clock........................................25-10, 26-10 Conversions................................................25-12, 26-12 Converter Characteristics ......................................32-36 converter characteristics........................................32-14 Delays.............................................................25-9, 26-9 Effects of a Reset...............................25-16, 26-16, 27-6 Equations........................................................25-8, 26-8 Flowchart of A/D Operation.........................25-13, 26-13 GO/DONE bit ..................................................25-7, 26-7 Internal Sampling Switch (Rss) Impedence ....25-8, 26-8 Operation During Sleep .....................25-16, 26-16, 27-6 Sampling Requirements..................................25-8, 26-8 Sampling Time ................................................25-8, 26-8 Source Impedence..........................................25-8, 26-8 Time Delays....................................................25-9, 26-9 Transfer Function........................................25-18, 26-18 ACK................................................................................20-19 Acknowledge Pulse........................................................20-19 ADDLW Instruction ........................................................31-14 ADDWF Instruction .............................................31-16, 31-20 ADRES Register .....................................................25-2, 26-2 AKS ................................................................................20-37 ANDLW Instruction ........................................................31-22 ANDWF Instruction ..................... 31-24, 31-26, 31-30, 31-32, ...............................31-34, 31-36, 31-38, 31-40, 31-42, 31-48 Assembler ........................................................................34-6 B Baud Rate Generator .....................................................20-30 BCF Instruction ..............................................................31-28 BF ................................................ 19-20, 20-19, 20-37, 20-40 Block Diagrams Analog Input Model .........................................25-9, 26-9 Baud Rate Generator.............................................20-30 External Brown-out Protection Circuit (Case1) ........3-13 I 2C Master Mode....................................................20-27 I 2C Module .............................................................20-17 SSP (I2C Mode) .....................................................20-17 SSP (SPI Mode).......................................................20-9 SSP Module (I2C Master Mode) ..............................20-3 SSP Module (I2C Slave Mode) ................................ 20-3 SSP Module (SPI Mode).......................................... 20-2 Timer1......................................................................16-2 BODEN ............................................................................3-10 BRG ...............................................................................20-30 BRGH bit.......................................................................... 21-5 Brown-out Protection .......................................................3-13 BSF Instruction ...................................................31-44, 31-47 BTFSC Instruction..........................................................31-45 BTFSS Instruction ........................ 31-46, 31-56, 31-58, 31-60 Buffer Full bit, BF ...........................................................20-19 Bus Arbitration ...............................................................20-48 Bus Collision ..................................................................20-48 Bus Collision During a RESTART Condition..................20-51 Bus Collision During a Start Condition........................... 20-49 Bus Collision During a Stop Condition........................... 20-52 C C ........................................................................................ 8-3 C Compiler (MP-C) .......................................................... 34-6 CALL Instruction ............................................................ 31-50 Clock/Instruction Cycle (Figure)......................................... 4-5 Clocking Scheme/Instruction Cycle ................................... 4-5 CLRF Instruction............................................... 31-52, 31-114 CLRWDT Instruction...................................................... 31-53 Code Examples Loading the SSPBUF register ...................... 19-9, 20-10 Code Protection ............................................................. 29-10 COMF Instruction........................................................... 31-54 D DC ..................................................................................... 8-3 DC Characteristics PIC16C73 ................................................................ 32-6 PIC16C74 ................................................................ 32-6 DECF Instruction ................................................ 31-62, 31-64 DECFSZ Instruction............................................31-66, 31-68 Development Support...................................................... 34-2 F Filter/Mask Truth Table.................................................. 22-54 Flowcharts Acknowledge ......................................................... 20-44 Master Receiver .................................................... 20-41 Master Transmit..................................................... 20-38 Restart Condition................................................... 20-35 Start Condition....................................................... 20-32 Stop Condition ....................................................... 20-46 FS0 .................................................................................... 8-3 FS1 .................................................................................... 8-3 FS2 .................................................................................... 8-3 FS3 .................................................................................... 8-3 G General Call Address Sequence ................................... 20-25 General Call Address Support....................................... 20-25 GOTO Instruction........................................................... 31-70 I I 2C ................................................................................. 20-17 BF.......................................................................... 19-20 CKP ....................................................................... 19-24 I 2C Overview ........................................................... 36-1 Initiating and Terminating Data Transfer ................. 36-2 START..................................................................... 36-2 STOP....................................................................... 36-2 I 2C Master Mode Receiver Flowchart............................ 20-41 I 2C Master Mode Reception .......................................... 20-40 I 2C Master Mode Restart Condition............................... 20-33 I 2C Mode Selection........................................................ 20-18 I 2C Module 10-bit Address mode ............................................. 20-20 Acknowledge Flowchart......................................... 20-44 Acknowledge Sequence timing ............................. 20-43 Addressing............................................................. 20-20 Baud Rate Generator ............................................ 20-30 Block Diagram ....................................................... 20-27 BRG Block Diagram .............................................. 20-30 BRG Reset due to SDA Collision .......................... 20-50 BRG Timing........................................................... 20-30 Bus Arbitration ....................................................... 20-48 Bus Collision.......................................................... 20-48 Acknowledge ................................................. 20-48 Restart Condition........................................... 20-51 Restart Condition Timing (Case1) ................. 20-51 39500 18C Reference ManualIX.fm Page 1 Tuesday, July 11, 2000 8:33 AM PIC18C Reference Manual DS39539A-page 2  2000 Microchip Technology Inc. Restart Condition Timing (Case2)..................20-51 Start Condition ...............................................20-49 Start Condition Timing ........................20-49, 20-50 Stop Condition ...............................................20-52 Stop Condition Timing (Case1)......................20-52 Stop Condition Timing (Case2)......................20-52 Transmit Timing .............................................20-48 Bus Collision timing................................................20-48 Clock Arbitration.....................................................20-47 Clock Arbitration Timing (Master Transmit)............20-47 Conditions to not give ACK Pulse ..........................20-19 General Call Address Support ...............................20-25 Master Mode ..........................................................20-27 Master Mode 7-bit Reception timing ......................20-42 Master Mode Operation .........................................20-29 Master Mode Start Condition .................................20-31 Master Mode Transmission....................................20-37 Master Mode Transmit Sequence ..........................20-29 Master Transmit Flowchart ....................................20-38 Multi-Master Communication .................................20-48 Multi-master Mode .................................................20-28 Operation ...............................................................20-17 Repeat Start Condition timing ................................20-34 Restart Condition Flowchart...................................20-35 Slave Mode ............................................................20-19 Slave Reception .....................................................20-21 Slave Transmission................................................20-22 SSPBUF.................................................................20-18 Start Condition Flowchart.......................................20-32 Stop Condition Flowchart.......................................20-46 Stop Condition Receive or Transmit timing............20-45 Stop Condition timing .............................................20-45 Waveforms for 7-bit Reception ..............................20-22 Waveforms for 7-bit Transmission .........................20-22 I 2C Module Address Register, SSPADD........................20-18 I 2C Slave Mode ..............................................................20-19 INCF Instruction .............................................................31-72 INCFSZ Instruction..............................................31-74, 31-76 Instruction Flow/Pipelining .................................................4-6 Instruction Set ADDLW ..................................................................31-14 ADDWF.......................................................31-16, 31-20 ANDLW ..................................................................31-22 ANDWF....................31-24, 31-26, 31-30, 31-32, 31-34, .................................. 31-36, 31-38, 31-40, 31-42, 31-48 BCF ........................................................................31-28 BSF .............................................................31-44, 31-47 BTFSC ...................................................................31-45 BTFSS ................................. 31-46, 31-56, 31-58, 31-60 CALL ......................................................................31-50 CLRF.........................................................31-52, 31-114 CLRWDT................................................................31-53 COMF ....................................................................31-54 DECF ..........................................................31-62, 31-64 DECFSZ......................................................31-66, 31-68 GOTO ....................................................................31-70 INCF.......................................................................31-72 INCFSZ .......................................................31-74, 31-76 IORLW ...................................................................31-78 IORWF ...................................................................31-80 MOVLW .................... 31-82, 31-84, 31-86, 31-87, 31-88 MOVWF ...................31-89, 31-90, 31-91, 31-92, 31-94, ....................................................................31-95, 31-96 NOP ............................................................31-93, 31-98 RETFIE ................................................................31-100 RETLW ................................................................31-102 RETURN ..............................................................31-104 RLF .........................................................31-106, 31-108 RRF ........................................................ 31-110, 31-112 SLEEP ................................................................. 31-115 SUBLW................................................... 31-116, 31-118 SUBWF................................................... 31-120, 31-122 SWAPF......................................31-124, 31-126, 31-128 XORLW ............................................................... 31-132 XORWF ..................................................31-130, 31-134 Summary Table ................................................5-3, 31-6 Inter-Integrated Circuit (I2C) ............................................ 20-2 Internal Sampling Switch (Rss) Impedence............ 25-8, 26-8 Interrupts Flag bits TMR1IE ........................................................... 10-4 TMR1IF............................................................ 10-4 TMR2IE ........................................................... 10-4 TMR2IF............................................................ 10-4 TMR3IE ........................................................... 10-4 TMR3IF............................................................ 10-4 Logic ........................................................................ 10-4 Introduction...................................................................... 31-2 IORLW Instruction ......................................................... 31-78 IORWF Instruction ......................................................... 31-80 L Loading of PC .................................................................... 7-7 M MOVLW Instruction........... 31-82, 31-84, 31-86, 31-87, 31-88 MOVWF Instruction .....................31-89, 31-90, 31-91, 31-92, .................................................................31-94, 31-95, 31-96 MPASM Assembler................................................. 34-2, 34-6 MP-C C Compiler............................................................. 34-6 MPSIM Software Simulator.............................................. 34-3 Multi-Master Communication......................................... 20-48 Multi-Master Mode ......................................................... 20-28 Multiply Examples 16 x 16 Routine ......................................................... 6-4 16 x 16 Signed Routine ............................................. 6-5 8 x 8 Routine ............................................................. 6-3 8 x 8 Signed Routine ................................................. 6-3 N NOP Instruction .................................................. 31-93, 31-98 O OSCCON........................................................................... 2-3 OSCCON Register............................................................. 2-3 Oscillator Start-up Time (Figure) ....................................... 3-5 OV...................................................................................... 8-3 P PICDEM-1 Low-Cost PIC16/17 Demo Board .......34-2, 34-12 PICDEM-2 Low-Cost PIC16CXX Demo Board..... 34-2, 34-12 PICDEM-3 Low-Cost PIC16C9XXX Demo Board ......... 34-13 PICSTART‰ Low-Cost Development System..... 34-2, 34-10 Pin Functions MCLR/VPP ................................................................. 4-9 OSC1/CLKIN ......................................................4-8, 4-9 OSC2/CLKOUT ..................................................4-8, 4-9 RA0/AN0.................................................................... 4-9 RA1/AN1.................................................................... 4-9 RA2/AN2.................................................................... 4-9 RA3/AN3/VREF........................................................... 4-9 RA4/T0CKI ................................................................ 4-9 RA5/AN4/SS.............................................................. 4-9 RB0/INT..................................................................... 4-9 RB1............................................................................ 4-9 RB2............................................................................ 4-9 RB3............................................................................ 4-9 RB4............................................................................ 4-9 39500 18C Reference ManualIX.fm Page 2 Tuesday, July 11, 2000 8:33 AM  2000 Microchip Technology Inc. DS39539A-page 3 PIC18C Reference Manual Index RB5............................................................................ 4-9 RB6............................................................................ 4-9 RB7............................................................................ 4-9 RC0/T1OSO/T1CKI ................................................. 4-10 RC1/T1OSI/CCP2.................................................... 4-10 RC2/CCP1 ...............................................................4-10 RC3/SCK/SCL .........................................................4-10 RC4/SDI/SDA ..........................................................4-10 RC5/SDO .................................................................4-10 RC6/TX/CK ..............................................................4-10 RC7/RX/DT..............................................................4-10 RD0/PSP0................................................................ 4-10 RD1/PSP1................................................................ 4-10 RD2/PSP2................................................................ 4-10 RD3/PSP3................................................................ 4-10 RD4/PSP4................................................................ 4-10 RD5/PSP5................................................................ 4-10 RD6/PSP6................................................................ 4-10 RD7/PSP7................................................................ 4-10 RE0/RD/AN5..........................................4-10, 4-11, 4-12 RE1/WR/AN6.........................................4-10, 4-11, 4-12 RE2/CS/AN7 ..........................................4-10, 4-11, 4-12 VDD .......................................................................... 4-13 VSS...........................................................................4-13 PRO MATE‰ Universal Programmer...................34-2, 34-10 Program Verification ......................................................29-10 PSPMODE bit ..................................................................12-2 PWM (CCP Module) Example Frequencies/Resolutions ........................17-13 R R/W bit ..................................................................20-20, 36-4 R/W bit ...........................................................................20-21 Read-Modify-Write .........................................................11-37 Registers SSPSTAT.................................................................20-4 T1CON .........................................................................16-3 Diagram ........................................................... 16-3 Resets................................................................................3-4 RETFIE Instruction.......................................................31-100 RETLW Instruction.......................................................31-102 RETURN Instruction ....................................................31-104 RLF Instruction................................................31-106, 31-108 RRF Instruction ...............................................31-110, 31-112 S SCK..................................................................................20-9 SCL ................................................................................20-19 SDA................................................................................20-19 SDI ...................................................................................20-9 SDO ................................................................................. 20-9 Serial Clock, SCK ............................................................20-9 Serial Clock, SCL ...........................................................20-19 Serial Data Address, SDA..............................................20-19 Serial Data In, SDI ........................................................... 20-9 Serial Data Out, SDO.......................................................20-9 SFR ................................................................................31-12 SFR As Source/Destination ...........................................31-12 Signed Math..................................................................... 5-10 Slave Select Synchronization ........................................20-13 Slave Select, SS ..............................................................20-9 SLEEP Instruction ........................................................31-115 Special Features of the CPU ..................................29-2, 30-2 Special Function Registers ............................................31-12 SPI Master Mode ...............................................19-12, 20-12 Serial Clock.....................................................19-8, 20-9 Serial Data In.................................................. 19-8, 20-9 Serial Data Out............................................... 19-8, 20-9 Serial Peripheral Interface (SPI).............................. 20-2 Slave Select.................................................... 19-8, 20-9 SPI clock..................................................... 19-12, 20-12 SPI Mode................................................................. 20-9 SPI Master/Slave Connection........................................ 20-11 SPI Module Master/Slave Connection ...................................... 20-11 Slave Mode............................................................ 20-13 Slave Select Synchronization................................ 20-13 Slave Synch Timnig............................................... 20-14 Slave Timing with CKE = 0.................................... 20-14 Slave Timing with CKE = 1.................................... 20-15 SS.................................................................................... 20-9 SSP ................................................................................. 20-2 Block Diagram (SPI Mode) ...................................... 20-9 SPI Mode................................................................. 20-9 SSPADD..........................................19-21, 20-18, 20-20 SSPBUF ...............................19-12, 19-24, 20-12, 20-18 SSPCON1 ............................................................... 20-6 SSPCON2 ............................................................... 20-8 SSPSR ............................................19-12, 20-12, 20-19 SSPSTAT ..................................................... 20-4, 20-18 SSP I2C SSP I2C Operation ................................................ 20-17 SSP Module SPI Master Mode................................................... 20-12 SPI Master./Slave Connection............................... 20-11 SPI Slave Mode..................................................... 20-13 SSPCON1 Register............................................... 20-18 SSP Overflow Detect bit, SSPOV.................................. 20-19 SSPBUF .............................................................20-18, 20-19 SSPCON1 ............................................................ 20-6, 20-18 SSPCON2 ....................................................................... 20-8 SSPIF ............................................................................ 20-21 SSPOV ............................................................... 20-19, 20-40 SSPSTAT ............................................................. 20-4, 20-18 SUBLW Instruction ......................................... 31-116, 31-118 SUBWF Instruction ......................................... 31-120, 31-122 SWAPF Instruction ............................31-124, 31-126, 31-128 Synchronous Serial Port.................................................. 20-2 T TAD .....................................................................25-10, 26-10 Timer Modules Timer1 Block Diagram ................................................. 16-2 Timers Timer1 Capacitor Selection .............................. 14-10, 16-9 Timing Diagrams A/D Conversion ..................................................... 32-37 Acknowledge Sequence Timing ............................ 20-43 Baud Rate Generator with Clock Arbitration.......... 20-30 BRG Reset Due to SDA Collision.......................... 20-50 Bus Collision Start Condition Timing ................................... 20-49 Bus Collision During a Restart Condition (Case 1) 20-51 Bus Collision During a Restart Condition (Case2). 20-51 Bus Collision During a Start Condition (SCL = 0).. 20-50 Bus Collision During a Stop Condition................... 20-52 Bus Collision for Transmit and Acknowledge ........ 20-48 Capture/Compare/PWM ........................................ 32-24 External Clock Timing............................................ 32-19 I 2C Bus Data...............................................32-31, 32-33 I 2C Bus Start/Stop bits........................................... 32-30 I 2C Master Mode First Start bit timing ................... 20-31 39500 18C Reference ManualIX.fm Page 3 Tuesday, July 11, 2000 8:33 AM PIC18C Reference Manual DS39539A-page 4  2000 Microchip Technology Inc. I 2C Master Mode Reception timing ........................20-42 I 2C Master Mode Transmission timing...................20-39 Master Mode Transmit Clock Arbitration................20-47 Oscillator Start-up Time .............................................3-5 Parallel Slave Port .................................................32-25 Power-up Timer .....................................................32-22 Repeat Start Condition...........................................20-34 Reset......................................................................32-22 Slave Synchronization ...........................................20-14 SPI Mode Timing (Master Mode)SPI Mode Master Mode Timing Diagram........................20-12 SPI Mode Timing (Slave Mode with CKE = 0) .......20-14 SPI Mode Timing (Slave Mode with CKE = 1) .......20-15 Start-up Timer ........................................................32-22 Stop Condition Receive or Transmit ......................20-45 USART RX Pin Sampling.......................................21-17 USART Synchronous Receive ...............................32-34 USART Synchronous Transmission ......................32-34 USART, Asynchronous Reception .........................21-16 Watchdog Timer.....................................................32-22 TRISC ............................................................................19-26 TRISC Register ..............................................................19-17 TRISD Register ...................................................11-27, 11-29 U Universal Synchronous Asynchronous Receiver Transmitter (USART) Asynchronous Receiver Setting Up Reception.....................................21-15 Timing Diagram..............................................21-16 USART Asynchronous Transmitter .......................................21-9 Baud Rate Generator (BRG) Sampling..........................................................21-5 W Watchdog Timer (WDT) .................................................29-10 Waveform for General Call Address Sequence .............20-25 WCOL ............................... 20-31, 20-37, 20-40, 20-43, 20-45 WCOL Status Flag .........................................................20-31 X XORLW Instruction ......................................................31-132 XORWF Instruction .........................................31-130, 31-134 Z Z.........................................................................................8-3 39500 18C Reference ManualIX.fm Page 4 Tuesday, July 11, 2000 8:33 AM  2000 Microchip Technology Inc. DS39539A-page 5 PIC18C Reference Manual Index NOTES: 39500 18C Reference ManualIX.fm Page 5 Tuesday, July 11, 2000 8:33 AM PIC18C Reference Manual DS39539A-page 6  2000 Microchip Technology Inc. NOTES: 39500 18C Reference ManualIX.fm Page 6 Tuesday, July 11, 2000 8:33 AM  2000 Microchip Technology Inc. DS39539A-page 7 PIC18C Reference Manual Index NOTES: 39500 18C Reference ManualIX.fm Page 7 Tuesday, July 11, 2000 8:33 AM PIC18C Reference Manual DS39539A-page 8  2000 Microchip Technology Inc. NOTES: 39500 18C Reference ManualIX.fm Page 8 Tuesday, July 11, 2000 8:33 AM  2000 Microchip Technology Inc. DS39539A-page 9 PIC18C Reference Manual Index NOTES: 39500 18C Reference ManualIX.fm Page 9 Tuesday, July 11, 2000 8:33 AM PIC18C Reference Manual DS39539A-page 10  2000 Microchip Technology Inc. NOTES: 39500 18C Reference ManualIX.fm Page 10 Tuesday, July 11, 2000 8:33 AM  2000 Microchip Technology Inc. DS39539A-page 11 PIC18C Reference Manual Index NOTES: 39500 18C Reference ManualIX.fm Page 11 Tuesday, July 11, 2000 8:33 AM PIC18C Reference Manual DS39539A-page 12  2000 Microchip Technology Inc. NOTES: 39500 18C Reference ManualIX.fm Page 12 Tuesday, July 11, 2000 8:33 AM  2000 Microchip Technology Inc. DS39539A-page 13 PIC18C Reference Manual Index NOTES: 39500 18C Reference ManualIX.fm Page 13 Tuesday, July 11, 2000 8:33 AM PIC18C Reference Manual DS39539A-page 14  2000 Microchip Technology Inc. NOTES: 39500 18C Reference ManualIX.fm Page 14 Tuesday, July 11, 2000 8:33 AM  2000 Microchip Technology Inc. DS39539A-page 15 PIC18C Reference Manual Index NOTES: 39500 18C Reference ManualIX.fm Page 15 Tuesday, July 11, 2000 8:33 AM Information contained in this publication regarding device applications and the like is intended through suggestion only and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. No representation or warranty is given and no liability is assumed by Microchip Technology Incorporated with respect to the accuracy or use of such information, or infringement of patents or other intellectual property rights arising from such use or otherwise. Use of Microchip’s products as critical components in life support systems is not authorized except with express written approval by Microchip. No licenses are conveyed, implicitly or otherwise, except as maybe explicitly expressed herein, under any intellectual property rights. The Microchip logo and name are registered trademarks of Microchip Technology Inc. in the U.S.A. and other countries. All rights reserved. All other trademarks mentioned herein are the property of their respective companies. DS39500A  2000 Microchip Technology Inc. All rights reserved. © 2000 Microchip Technology Incorporated. Printed in the USA. 7/00 Printed on recycled paper. AMERICAS Corporate Office Microchip Technology Inc. 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-786-7200 Fax: 480-786-7277 Technical Support: 480-786-7627 Web Address: http://www.microchip.com Atlanta Microchip Technology Inc. 500 Sugar Mill Road, Suite 200B Atlanta, GA 30350 Tel: 770-640-0034 Fax: 770-640-0307 Boston Microchip Technology Inc. 2 LAN Drive, Suite 120 Westford, MA 01886 Tel: 508-480-9990 Fax: 508-480-8575 Chicago Microchip Technology Inc. 333 Pierce Road, Suite 180 Itasca, IL 60143 Tel: 630-285-0071 Fax: 630-285-0075 Dallas Microchip Technology Inc. 4570 Westgrove Drive, Suite 160 Addison, TX 75001 Tel: 972-818-7423 Fax: 972-818-2924 Dayton Microchip Technology Inc. Two Prestige Place, Suite 150 Miamisburg, OH 45342 Tel: 937-291-1654 Fax: 937-291-9175 Detroit Microchip Technology Inc. Tri-Atria Office Building 32255 Northwestern Highway, Suite 190 Farmington Hills, MI 48334 Tel: 248-538-2250 Fax: 248-538-2260 Los Angeles Microchip Technology Inc. 18201 Von Karman, Suite 1090 Irvine, CA 92612 Tel: 949-263-1888 Fax: 949-263-1338 New York Microchip Technology Inc. 150 Motor Parkway, Suite 202 Hauppauge, NY 11788 Tel: 631-273-5305 Fax: 631-273-5335 San Jose Microchip Technology Inc. 2107 North First Street, Suite 590 San Jose, CA 95131 Tel: 408-436-7950 Fax: 408-436-7955 AMERICAS (continued) Toronto Microchip Technology Inc. 5925 Airport Road, Suite 200 Mississauga, Ontario L4V 1W1, Canada Tel: 905-405-6279 Fax: 905-405-6253 ASIA/PACIFIC China - Beijing Microchip Technology, Beijing Unit 915, 6 Chaoyangmen Bei Dajie Dong Erhuan Road, Dongcheng District New China Hong Kong Manhattan Building Beijing, 100027, P.R.C. Tel: 86-10-85282100 Fax: 86-10-85282104 China - Shanghai Microchip Technology Unit B701, Far East International Plaza, No. 317, Xianxia Road Shanghai, 200051, P.R.C. Tel: 86-21-6275-5700 Fax: 86-21-6275-5060 Hong Kong Microchip Asia Pacific Unit 2101, Tower 2 Metroplaza 223 Hing Fong Road Kwai Fong, N.T., Hong Kong Tel: 852-2-401-1200 Fax: 852-2-401-3431 India Microchip Technology Inc. India Liaison Office No. 6, Legacy, Convent Road Bangalore, 560 025, India Tel: 91-80-229-0061 Fax: 91-80-229-0062 Japan Microchip Technology Intl. Inc. Benex S-1 6F 3-18-20, Shinyokohama Kohoku-Ku, Yokohama-shi Kanagawa, 222-0033, Japan Tel: 81-45-471- 6166 Fax: 81-45-471-6122 Korea Microchip Technology Korea 168-1, Youngbo Bldg. 3 Floor Samsung-Dong, Kangnam-Ku Seoul, Korea Tel: 82-2-554-7200 Fax: 82-2-558-5934 ASIA/PACIFIC (continued) Singapore Microchip Technology Singapore Pte Ltd. 200 Middle Road #07-02 Prime Centre Singapore, 188980 Tel: 65-334-8870 Fax: 65-334-8850 Taiwan Microchip Technology Taiwan 10F-1C 207 Tung Hua North Road Taipei, Taiwan Tel: 886-2-2717-7175 Fax: 886-2-2545-0139 EUROPE Denmark Microchip Technology Denmark ApS Regus Business Centre Lautrup hoj 1-3 Ballerup DK-2750 Denmark Tel: 45 4420 9895 Fax: 45 4420 9910 France Arizona Microchip Technology SARL Parc d’Activite du Moulin de Massy 43 Rue du Saule Trapu Batiment A - ler Etage 91300 Massy, France Tel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79 Germany Arizona Microchip Technology GmbH Gustav-Heinemann-Ring 125 D-81739 München, Germany Tel: 49-89-627-144 0 Fax: 49-89-627-144-44 Italy Arizona Microchip Technology SRL Centro Direzionale Colleoni Palazzo Taurus 1 V. Le Colleoni 1 20041 Agrate Brianza Milan, Italy Tel: 39-039-65791-1 Fax: 39-039-6899883 United Kingdom Arizona Microchip Technology Ltd. 505 Eskdale Road Winnersh Triangle Wokingham Berkshire, England RG41 5TU Tel: 44 118 921 5858 Fax: 44-118 921-5835 05/16/00 WORLDWIDE SALES AND SERVICE Microchip received QS-9000 quality system certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona in July 1999. The Company’s quality system processes and procedures are QS-9000 compliant for its PICmicro® 8-bit MCUs, KEELOQ® code hopping devices, Serial EEPROMs and microperipheral products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001 certified. 39500 18C Reference Manual.book Page 33 Monday, July 10, 2000 6:12 PM

ATWINC15x0 ATWINC15x0 Wi-Fi® Network Controller Software Design Guide Introduction Microchip’s SmartConnect ATWINC15x0 is an IEEE® 802.11 b/g/n network controller SoC for Internet of Things (IoT) applications. It is an ideal add-on to the existing microcontroller (MCU) solutions bringing WiFi and network capabilities through an SPI-to-Wi-Fi interface. The ATWINC15x0 connects to any Microchip AVR® or Microchip SMART™ MCU with minimal resource requirements. Features • Wi-Fi IEEE 802.11 b/g/n STA, and AP modes • Wi-Fi Protected Setup (WPS) • Support of WEP, WPA/WPA2 Personal, and WPA/WPA2 Enterprise Security – EAP-TLS – EAP-PEAPv0/1 with TLS – EAP-TTLSv0 with MSCHAPv2 – EAP-PEAPv0/1 with MSCHAPv2 • Embedded network stack protocols to offload work from the MCU (minimize the host CPU requirements). This allows the Wi-Fi Network Controller (WINC) to operate with a wide range of MCUs including low-end MCUs. • Embedded uIP TCP/IP stack with BSD-Style socket API • Embedded network protocols – DHCP client/server – DNS resolver client – SNTP client for UTC time synchronization • Embedded TLS security abstracted behind BSD-style socket API • HTTP server for provisioning over AP mode • Ultra-low C IEEE 802.11 b/g/n RF/PH/MAC SoC • Fast boot from On-Chip boot ROM • 8 Mb (WINC1510) and 4 Mb (WINC1500) internal Flash memory with Over-the-Air (OTA) firmware upgrade • WINC1510 support Host File Download feature which can be used for host MCU over the air firmware update • Low-power consumption with different Power Save modes • Low footprint host driver with the following capabilities: – Can run on 8-, 16-, and 32-bit MCU using SPI interface – Little- and big-endian support © 2018 Microchip Technology Inc. User Guide DS00002389B-page 1 Table of Contents Introduction......................................................................................................................1 Features.......................................................................................................................... 1 1. Host Driver Architecture............................................................................................ 5 1.1. WLAN API.................................................................................................................................... 5 1.2. Socket API....................................................................................................................................5 1.3. Host Interface (HIF)......................................................................................................................6 1.4. Board Support Package (BSP).....................................................................................................6 1.5. Serial Bus Interface......................................................................................................................6 2. ATWINC15x0 System Architecture............................................................................7 2.1. Bus Interface................................................................................................................................ 7 2.2. Nonvolatile Storage......................................................................................................................8 2.3. CPU..............................................................................................................................................8 2.4. IEEE 802.11 MAC Hardware........................................................................................................8 2.5. Program Memory..........................................................................................................................8 2.6. Data Memory................................................................................................................................8 2.7. Shared Packet Memory................................................................................................................8 2.8. IEEE 802.11 MAC Firmware........................................................................................................ 8 2.9. Memory Manager......................................................................................................................... 8 2.10. Power Management..................................................................................................................... 9 2.11. WINC RTOS.................................................................................................................................9 2.12. WINC IoT Library..........................................................................................................................9 3. WINC Initialization and Simple Application..............................................................11 3.1. BSP Initialization.........................................................................................................................11 3.2. WINC Host Driver Initialization................................................................................................... 11 3.3. Socket Layer Initialization...........................................................................................................11 3.4. WINC Event Handling................................................................................................................ 12 3.5. Example Code............................................................................................................................13 4. ATWINC15x0 Configuration.....................................................................................14 4.1. Device Parameters.....................................................................................................................14 4.2. WINC Modes of Operation......................................................................................................... 14 4.3. Network Parameters...................................................................................................................16 4.4. Power Save Modes.................................................................................................................... 17 4.5. Configuring Listen Interval and DTIM Monitoring.......................................................................18 5. Wi-Fi Station Mode.................................................................................................. 20 5.1. Scan Configuration Parameters................................................................................................. 20 5.2. Wi-Fi Scan..................................................................................................................................20 5.3. Wi-Fi Security.............................................................................................................................21 5.4. On Demand Wi-Fi Connection................................................................................................... 22 ATWINC15x0 © 2018 Microchip Technology Inc. User Guide DS00002389B-page 2 5.5. Default Connection.....................................................................................................................25 5.6. Encrypted Credential Storage.................................................................................................... 26 5.7. Simple Roaming.........................................................................................................................27 5.8. Multiple Gain Table.....................................................................................................................29 5.9. Host File Download.................................................................................................................... 30 6. Socket Programming............................................................................................... 39 6.1. Overview.................................................................................................................................... 39 6.2. Sockets API................................................................................................................................39 6.3. Socket Connection Flow.............................................................................................................47 6.4. Example Code............................................................................................................................51 7. Transport Layer Security (TLS)............................................................................... 56 7.1. TLS Overview.............................................................................................................................56 7.2. TLS Connection Establishment..................................................................................................56 7.3. Server Certificate Installation..................................................................................................... 58 7.4. WINC TLS Limitations................................................................................................................59 7.5. SSL Client Code Example..........................................................................................................60 8. Wi-Fi AP Mode........................................................................................................ 62 8.1. Overview.................................................................................................................................... 62 8.2. Setting the WINC AP Mode........................................................................................................62 8.3. Limitations.................................................................................................................................. 62 8.4. Sequence Diagram.....................................................................................................................62 8.5. AP Mode Code Example............................................................................................................63 9. Provisioning............................................................................................................. 65 9.1. HTTP Provisioning..................................................................................................................... 65 9.2. Limitations.................................................................................................................................. 68 9.3. Wi-Fi Protected Setup (WPS).....................................................................................................68 10. Over-The-Air Upgrade.............................................................................................71 10.1. Overview.................................................................................................................................... 71 10.2. OTA Image Architecture............................................................................................................. 71 10.3. OTA Download Sequence Diagram........................................................................................... 72 10.4. OTA Firmware Rollback............................................................................................................. 72 10.5. OTA Limitations..........................................................................................................................73 10.6. OTA Code Example....................................................................................................................73 11. Multicast Sockets.....................................................................................................74 11.1. Overview.................................................................................................................................... 74 11.2. How to Use Filters......................................................................................................................74 11.3. Multicast Socket Code Example.................................................................................................74 12. WINC Serial Flash Memory.....................................................................................78 12.1. Overview and Features.............................................................................................................. 78 12.2. Accessing to Serial Flash...........................................................................................................78 12.3. Read/Write/Erase Operations.................................................................................................... 78 ATWINC15x0 © 2018 Microchip Technology Inc. User Guide DS00002389B-page 3 13. Host Interface (HIF) Protocol...................................................................................81 13.1. Transfer Sequence Between the HIF Layer and the WINC Firmware........................................82 13.2. HIF Message Header Structure..................................................................................................84 13.3. HIF Layer APIs...........................................................................................................................84 13.4. Scan Code Example...................................................................................................................85 14. WINC SPI Protocol..................................................................................................90 14.1. Introduction.................................................................................................................................90 14.2. Message Flow for Basic Transactions......................................................................................101 14.3. SPI Level Protocol Example.....................................................................................................105 15. Appendix A. How to Generate Certificates............................................................128 15.1. Introduction...............................................................................................................................128 15.2. Steps........................................................................................................................................ 128 15.3. Limitations................................................................................................................................ 128 16. Appendix B. X.509 Certificate Format and Conversion.........................................129 16.1. Introduction...............................................................................................................................129 16.2. Conversion Between Different Formats................................................................................... 129 17. References............................................................................................................ 131 18. Document Revision History................................................................................... 132 The Microchip Web Site.............................................................................................. 133 Customer Change Notification Service........................................................................133 Customer Support....................................................................................................... 133 Microchip Devices Code Protection Feature............................................................... 133 Legal Notice.................................................................................................................134 Trademarks................................................................................................................. 134 Quality Management System Certified by DNV...........................................................135 Worldwide Sales and Service......................................................................................136 ATWINC15x0 © 2018 Microchip Technology Inc. User Guide DS00002389B-page 4 1. Host Driver Architecture The following figure shows the architecture of the WINC host driver software, which runs on the host MCU. Figure 1-1. Host Driver Software Architecture The ATWINC15x0 host driver software is a C library, which provides the host MCU application with necessary APIs to perform necessary WLAN and socket operations. The components of the host driver are described in the following sub-sections. 1.1 WLAN API This module provides an interface to the application for all Wi-Fi operations and any non-IP related operations. This includes the following services: • Wi-Fi STA management operations – Wi-Fi scan – Wi-Fi connection management (connect, disconnect, connection status, and so on) – WPS activation/deactivation • Wi-Fi AP enable/disable • Wi-Fi power save control API This interface is defined in the m2m_wifi.h file. 1.2 Socket API This module provides the socket communication APIs that are mostly compliant with the well-known BSD sockets to enable rapid application development. To comply with the nature of the MCU application environment, there are differences in API prototypes and in usage of some APIs between the WINC sockets and BSD sockets. This interface is defined in the socket.h file. ATWINC15x0 Host Driver Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 5 The detailed description of the socket operations is provided in Socket Programming. 1.3 Host Interface (HIF) The HIF is responsible for handling the communication between the host driver and the WINC firmware. This includes interrupt handling, DMA and HIF command/response management. The host driver communicates with the firmware in the form of commands and responses formatted by the HIF layer. The interface is defined in the m2m_hif.h file. The detailed description of the HIF design is provided in Host Interface Protocol. 1.4 Board Support Package (BSP) The Board Support Package abstracts the functionality of a specific host MCU platform. This allows the driver to be portable to a wide range of hardware and hosts. Abstraction includes: pin assignment, power on/off sequence, reset sequence and peripheral definitions (Push buttons, LEDs, and so on). The minimum required BSP functionality is defined in the nm_bsp.h file. 1.5 Serial Bus Interface The Serial Bus Interface module abstracts the hardware associated with implementing the bus between the Host and the WINC. The serial bus interface abstracts I2C, SPI, or UART bus (Currently, host driver supports only SPI bus interface). The basic bus access operations (Read and Write) are implemented in this module as appropriate for the interface type and the specific hardware. The bus interface APIs are defined in the nm_bus_wrapper.h file. ATWINC15x0 Host Driver Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 6 2. ATWINC15x0 System Architecture The following figure shows the ATWINC15x0 system architecture. In addition to its built-in Wi-Fi IEEE-802.11 physical layer and RF front end, the WINC ASIC contains an embedded APS3S-Cortus 32- bit CPU to run the WINC firmware. The firmware comprises the Wi-Fi IEEE-802.11 MAC layer and embedded protocol stacks which offload the host MCU. The components of the system are described in the following sub-sections. Figure 2-1. ATWINC15x0 System Architecture 2.1 Bus Interface Hardware logic for the supported bus types for the ATWINC15x0 communications. Note:  SPI is currently the bus interface supported by the Host Driver. ATWINC15x0 ATWINC15x0 System Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 7 2.2 Nonvolatile Storage The ATWINC1510 has an integrated 8 Mb and the ATWINC1500 has an integrated 4 Mb serial Flash inside the WINC package (SIP). This stores the WINC firmware image and can store a second image to support OTA. It also stores information used by the WINC firmware in the run-time. The detailed description of the serial Flash is provided in WINC Serial Flash Memory. 2.3 CPU The SoC contains an APS3S-Cortus 32-bit CPU running at 40 MHz clock speed which executes the embedded WINC firmware. 2.4 IEEE 802.11 MAC Hardware The SoC contains a hardware accelerator to ensure fast and compliant implementation of the IEEE 802.11 MAC layer and associated timing. It offloads IEEE 802.11 MAC functionality from firmware to improve performance and boost the MAC throughput. The accelerator includes hardware encryption/ decryption of Wi-Fi traffic and traffic filtering mechanisms to avoid unnecessary processing in software. 2.5 Program Memory 128 KB Instruction RAM is provided for execution of the ATWINC15x0 firmware code. 2.6 Data Memory 64 KB RAM is provided for the ATWINC15x0 firmware data storage. 2.7 Shared Packet Memory 128 KB memory is provided for TX/RX packet management. It is shared between the MAC hardware and the CPU. This memory is managed by the Memory Manager SW component. 2.8 IEEE 802.11 MAC Firmware The system supports IEEE 802.11 b/g/n Wi-Fi MAC including WEP and WPA/WPA2 security supplicant. Between the MAC hardware and the firmware, a full range of IEEE 802.11 features are implemented and supported including beacon generation and reception, control packet generation and reception, and packet aggregation and de-aggregation. 2.9 Memory Manager The memory manager is responsible for the allocation and de-allocation of memory chunks in both shared packet memory and data memory. ATWINC15x0 ATWINC15x0 System Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 8 2.10 Power Management The Power Management module is responsible for handling different Power Save modes supported by the WINC and coordinating these modes with the Wi-Fi transceiver. 2.11 WINC RTOS The firmware includes a low-footprint real-time scheduler which allows concurrent multi-tasking on the ATWINC15x0 CPU. The ATWINC15x0 RTOS provides semaphores and timer functionality. 2.12 WINC IoT Library The WINC IoT library provides a set of networking protocols in the WINC firmware. It offloads the host MCU from networking and transport layer protocols. The following sections describe the components of the WINC IoT library. 2.12.1 WINC TCP/IP STACK The WINC TCP/IP is an IPv4.0 stack based on the uIP (pronounced micro IP) TCP/IP stack. uIP is a low footprint TCP/IP stack which has the ability to run on a memory-constrained microcontroller platform. It was originally developed by Adam Dunkels, licensed under a BSD style license, and further developed by a wide group of developers. The WINC TCP/IP stack is a customized version of the original uIP implementation which has several enhancements to boost TCP and UDP throughput. 2.12.2 DHCP CLIENT/SERVER A DHCP client is embedded in the WINC firmware that can automatically obtain an IP configuration after connecting to a Wi-Fi network. The WINC firmware provides an instance of a DHCP server that automatically starts when the WINC AP mode is enabled. When the host MCU application activates the AP mode, it is allowed to configure the DHCP Server IP address pool range within the AP configuration parameters. 2.12.3 DNS RESOLVER The WINC firmware contains an instance of an embedded DNS resolver. This module can return an IP address by resolving the host domain names supplied with the socket API call gethostbyname. 2.12.4 SNTP The SNTP (Simple Network Time Protocol) module implements an SNTP client used to synchronize the WINC internal clock to the UTC clock. 2.12.5 Enterprise Security The Enterprise Security module implements the following authentication protocols for establishing a Wi-Fi connection with an AP by WPA/WPA2-Enterprise Security. • EAP with TLS • EAP-PEAPv0/v1 with MSCHAPV2 • EAP-TTLSv0 with MSCHAPv2 • EAP-PEAPv0/v1 with MSCHAPv2 2.12.6 TRANSPORT LAYER SECURITY For TLS implementation, refer to Section 7 “Transport Layer Security (TLS)” for details. ATWINC15x0 ATWINC15x0 System Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 9 2.12.7 WI-FI PROTECTED SETUP For WPS protocol implementation, refer to Section 10.3 “Wi-Fi Protected Setup (WPS)” for details. 2.12.8 CRYPTO LIBRARY The Crypto Library contains a set of cryptographic algorithms used by the common security protocols. This library has an implementation of the following algorithms: • MD4 Hash algorithm (used only for MsChapv2.0 digest calculation) • MD5 Hash algorithm • SHA-1 Hash algorithm • SHA-256 Hash algorithm • DES Encryption (used only for MsChapv2.0 digest calculation) • MS-CHAPv2.0 (used as the EAP-TTLS inner authentication algorithm) • MS-CHAPv2.0 (used as the EAP-PEAP and EAP-TTLS inner authentication algorithm) • AES-128, AES-256 Encryption (used for securing WPS and TLS traffic) • BigInt module for large integer arithmetic (for Public Key Cryptographic computations) • RSA Public Key cryptography algorithms (includes RSA Signature and RSA Encryption algorithms) ATWINC15x0 ATWINC15x0 System Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 10 3. WINC Initialization and Simple Application After powering-up the WINC device, a set of synchronous initialization sequences must be executed, for the correct operation of the Wi-Fi functions. This chapter aims to explain the different steps required during the initialization phase of the system. After initialization, the host MCU application is required to call the WINC driver entry point to handle events from the WINC firmware. • BSP Initialization • WINC Host Driver Initialization • Socket Layer Initialization • Call WINC Driver Entry Point Note:  The initialization sequence must be completed to successfully operate the WINC start-up procedure. 3.1 BSP Initialization The BSP is initialized by calling the nm_bsp_init API. The BSP initialization routine performs the following steps: • Resets the WINC1 using the corresponding host MCU control GPIOs. • Initializes the host MCU GPIO which connects to the WINC interrupt line. It configures the GPIO as an interrupt source to the host MCU. During runtime, the WINC interrupts the host to notify the application of events and data pending inside the WINC firmware. • Initializes the host MCU delay function used within nm_bsp_sleep implementation. 3.2 WINC Host Driver Initialization The WINC host driver is initialized by calling the m2m_wifi_init API. The host driver initialization routine performs the following steps: • Initializes the bus wrapper and SPI peripheral. The compilation flag CONF_WINC_USE_SPI must be enabled in conf_winc.h (bus interfaces CONF_WINC_USE_UART and CONF_WINC_USE_I2C are currently not supported). • Registers an application-defined Wi-Fi event handler. • Initializes the driver and ensures compatibility between the WINC firmware version and the driver version. • Initializes the host interface and the Wi-Fi layer and registers the BSP Interrupt. Note:  A Wi-Fi event handler is required for the correct operation of any WINC application. 3.3 Socket Layer Initialization Socket layer initialization is carried out by calling the socketInit API. It must be called prior to any socket activity. For more information about socket initialization and programming, refer to WINC Sockets API. 1 Refer to the ATWINC15x0-MR210xB Data Sheet (DS70005304) for more information about the hardware power-up/down sequence. ATWINC15x0 WINC Initialization and Simple Application © 2018 Microchip Technology Inc. User Guide DS00002389B-page 11 3.4 WINC Event Handling The WINC host driver API allows the host MCU application to interact with the WINC firmware. To facilitate interaction, the WINC driver implements the Host Interface (HIF) Protocol as described in Section 15 “Host Interface (HIF) Protocol”. The HIF protocol defines how to serialize and de-serialize API requests and response callbacks over the serial bus interface SPI (I2C and UART are currently not supported). Figure 3-1. WINC System Architecture The WINC host driver API provides services to the host MCU applications that are mainly divided in two major categories: Wi-Fi control services and Socket services. The Wi-Fi control services allow actions such as channel scanning, network identification, connection and disconnection. The Socket control services allow application data transfer once a Wi-Fi connection is established. 3.4.1 Asynchronous Events Some APIs in the ATWINC15x0 host driver are synchronous function calls, where the result is ready by the return of the function. However, most API functions in the ATWINC15x0 host driver are asynchronous. This means that when the application calls an API to request a service, the call is non-blocking and returns immediately, before the requested action is completed. When completed, a notification is provided in the form of a HIF protocol message from the WINC firmware to the host which, in turn, is delivered to the application via a callback2 function. Asynchronous operation is essential when the requested service such as Wi-Fi connection may take significant time to complete. In general, the ATWINC15x0 firmware uses asynchronous events to signal the host driver about status change or pending data. The HIF uses push architecture where the data and events are pushed from the ATWINC15x0 firmware to the host MCU in a First-Come First-Served (FCFS) manner. For instance, the host MCU application has two open sockets: socket 1 and socket 2. If the ATWINC15x0 receives socket 1 data followed by socket 2 data, then HIF delivers socket data in two HIF protocol messages in the order in which it is received. HIF does not allow reading socket 2 data before socket 1 data. 3.4.2 Interrupt Handling The HIF interrupts the host MCU when one or more events are pending in the ATWINC15x0 firmware. The host MCU application is a big state machine which processes received data and events when the 2 The callback is C function which contains an application-defined logic. The callback is registered using the ATWINC15x0 host driver registration API to handle the result of the requested service. ATWINC15x0 WINC Initialization and Simple Application © 2018 Microchip Technology Inc. User Guide DS00002389B-page 12 ATWINC15x0 driver calls the event callback function(s). To receive event callbacks, the host MCU application is required to call the m2m_wifi_handle_events API to let the host driver retrieve and process the pending events from the ATWINC15x0 firmware. It is recommended to call this function if any of the following events occur: • The host MCU application polls the API in main loop or a dedicated task • When the host MCU receives an interrupt from the ATWINC15x0 firmware Note:  All the application-defined event callback functions registered with the ATWINC15x0 driver run in the context m2m_wifi_handle_events API. The above HIF architecture allows the ATWINC15x0 host driver to be flexible to run in the following configurations: • Host MCU with no operating system configuration – the MCU main loop is responsible to handle deferred work from the interrupt handler • Host MCU with operating system configuration – a dedicated task or thread is required to call m2m_wifi_handle_events to handle deferred work from the interrupt handler Note:  1. Host driver entry point m2m_wifi_handle_events is non-reentrant. In the operating system configuration, it is required to protect the host driver from reentrance by a synchronization object. 2. When the host MCU is polling m2m_wifi_handle_events, the API checks for pending unhandled interrupt from the ATWINC15x0. If no interrupt is pending, it returns immediately. If an interrupt is pending, m2m_wifi_handle_events sequentially reads all the pending HIF messages and dispatches the HIF message content to the respective registered callback. If a callback is not registered to handle the type of message, the HIF message content is discarded. 3.5 Example Code The following example code shows the initialization flow, as described in the previous sections. static void wifi_cb(uint8_t u8MsgType, void *pvMsg) { } int main (void) { tstrWifiInitParam param; nm_bsp_init(); m2m_memset((uint8*)¶m, 0, sizeof(param)); param.pfAppWifiCb = wifi_cb; /*intilize the WINC Driver*/ ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret){ M2M_ERR("Driver Init Failed <%d>\n",ret); while(1); } while(1){ /* Handle the app state machine plus the WINC event handler */ while(m2m_wifi_handle_events(NULL) != M2M_SUCCESS) { } } } ATWINC15x0 WINC Initialization and Simple Application © 2018 Microchip Technology Inc. User Guide DS00002389B-page 13 4. ATWINC15x0 Configuration The ATWINC15x0 firmware offers a set of configurable parameters that control its behavior. There is a set of APIs provided to the host MCU application to configure these parameters. The configuration APIs are categorized according to their functionality, into device, network and power saving parameters. Any parameters left unset by the host MCU application use their default values assigned during the initialization of the ATWINC15x0 firmware. A host MCU application needs to configure its parameters when coming out of cold boot or when a specific configuration change is required. 4.1 Device Parameters 4.1.1 System Time It is important to set the WINC system to UTC time to ensure a proper validity check of the X509 certificate expiration date. Since the WINC does not contain a built-in Real-Time Clock (RTC), there are two ways to obtain UTC time: • Using the internal SNTP client – this is enabled by default in the WINC firmware at start-up. The SNTP client synchronizes the WINC system clock to the UTC time from the time servers. The NTP server that SNTP client uses can be configured using the API m2m_wifi_configure_sntp. The default NTP server used by the WINC is time-c.nist.gov. The SNTP client uses a default update cycle of one day. • From the host MCU RTC – if the host MCU has a RTC, the application may disable the SNTP client by calling m2m_wifi_enable_sntp(0) (by passing zero as the argument) after the WINC initialization. The application provisions the WINC system time by calling m2m_wifi_set_system_time API. 4.1.2 Firmware and Driver Version During initialization (m2m_wifi_init), the host driver checks the compatibility between the driver and the WINC firmware. The relevant parameters are: • M2M_HIF_MAJOR_VALUE • M2M_HIF_MINOR_VALUE Note:  These parameters are stated in release note version information as “Host Interface Level: X.Y”. If the driver and the WINC firmware have the same values of M2M_HIF_MAJOR_VALUE, then they are deemed compatible and m2m_wifi_init returns with M2M_SUCCESS. If the driver and the WINC firmware have different values of M2M_HIF_MAJOR_VALUE, then they are deemed incompatible and m2m_wifi_init returns with M2M_ERR_FW_VER_MISMATCH. In this case, communication is limited; the only permitted communication is for the driver to request the WINC firmware to switch to the WINC firmware image in the inactive partition of WINC flash, via m2m_wifi_check_ota_rb and m2m_ota_switch_firmware. Example code to handle this situation is available in the driver file m2m_ota.h. 4.2 WINC Modes of Operation The WINC firmware supports the following modes of operation: ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 14 • Idle mode • Wi-Fi STA mode • Wi-Fi Hotspot (AP) Figure 4-1. WINC Modes of Operation IDLE AP STA m2_wifi_connect m2m_wifi_default_connect M2M_WIFI_RESP_CON_STATE_CHANGED m2m_wifi_disconnect m2m_wifi_disable_ap m2m_wifi_enable_ap 4.2.1 Idle Mode After the host MCU application calls the ATWINC15x0 driver initialization m2m_wifi_init API, the ATWINC15x0 remains in Idle mode waiting for any command to change the mode or to update the configuration parameters. In this mode, the ATWINC15x0 enters into Power Save mode which disables the IEEE 802.11 radio and all unneeded peripherals and suspends the ATWINC15x0 CPU. If the ATWINC15x0 receives any configuration commands from the host MCU, it updates the configuration, sends back the response to the host MCU, and then returns to the Power Save mode. 4.2.2 Wi-Fi Station Mode The ATWINC15x0 enters Station (STA) mode when the host MCU requests connection to an AP using the m2m_wifi_connect or m2m_wifi_default_connect APIs. Note:  m2m_wifi_connect is deprecated from v19.6.1 and above. For more details, see 5.3 Wi-Fi Security. The ATWINC15x0 exits STA mode when it receives a disconnect request from the Wi-Fi AP conveyed to the host MCU application via the event callback M2M_WIFI_RESP_CON_STATE_CHANGED or when the host MCU application decides to terminate the connection via m2m_wifi_disconnect API. Note:  The supported API functions in this mode use the HIF command types: tenuM2mConfigCmd and tenuM2mStaCmd. See the full list of commands in the m2m_types.h header file. For more information about STA mode, refer to Wi-Fi Station Mode. 4.2.3 Wi-Fi Hotspot (AP) Mode In AP mode, the WINC allows Wi-Fi stations to connect and obtain the IP address from the WINC DHCP server. To enter AP mode, the host MCU application calls m2m_wifi_enable_ap API. To exit AP mode, the application calls m2m_wifi_disable_ap API. The supported API functions in this mode use the HIF command types: tenuM2mApCmd and tenuM2mConfigCmd. See the full list of commands in the m2m_types.h header file. For more information about this mode, refer to Wi-Fi AP Mode. ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 15 4.3 Network Parameters 4.3.1 Wi-Fi MAC Address The WINC firmware provides two methods to assign the WINC MAC address: • Assignment from the host MCU – this method occurs when the host MCU application calls the m2m_wifi_set_mac_address API after initialization using m2m_wifi_init API. • Assignment from the WINC OTP (One-Time-Programmable) memory – the WINC supports an internal MAC address assignment method through a built-in OTP memory. If MAC address is programmed in the WINC OTP memory, the WINC working MAC address defaults to the OTP MAC address unless the host MCU application programmatically sets a different MAC address after initialization using the API m2m_wifi_set_mac_address. Note:  • OTP MAC address is programmed in the WINC OTP memory at the time of manufacturing. • Use m2m_wifi_get_otp_mac_address API to check if there is a valid programmed MAC address in the WINC OTP memory. The host MCU application can also use the same API to read the OTP MAC address octets. m2m_wifi_get_otp_mac_address API not to be confused with the m2m_wifi_get_mac_address API which reads the working WINC MAC address in the WINC firmware regardless from whether it is assigned from the host MCU or from the WINC OTP. • For more details on API, refer to the Atmel Software Framework for ATWINC1500 (Wi-Fi). 4.3.2 IP Address The ATWINC15x0 firmware uses the embedded DHCP client to automatically obtain an IP configuration after a successful Wi-Fi connection. DHCP is the preferred method and therefore it is used as a default method. After the IP configuration is obtained, the host MCU application is notified by the asynchronous event M2M_WIFI_REQ_DHCP_CONF. Alternatively, the host MCU application can set a static IP configuration by calling the m2m_wifi_set_static_ip API. Before setting a static IP address, it is recommended to disable DHCP using the API m2m_wifi_enable_dhcp(0) and then set the static IP as shown below. In Main(), disable dhcp after m2m_wifi_init as shown below /* Initialize Wi-Fi driver with data and status callbacks. */ param.pfAppWifiCb = wifi_cb; ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret) { printf("main: m2m_wifi_init call error!(%d)\r\n", ret); while (1) {} } m2m_wifi_enable_dhcp(0); Set Static IP when WINC is connected to AP as shown below. static void wifi_cb(uint8_t u8MsgType, void *pvMsg) { switch (u8MsgType) { case M2M_WIFI_RESP_CON_STATE_CHANGED: { tstrM2mWifiStateChanged *pstrWifiState = (tstrM2mWifiStateChanged *)pvMsg; if (pstrWifiState->u8CurrState == M2M_WIFI_CONNECTED){ printf("Wi-Fi connected\r\n"); tstrM2MIPConfig ip_client; ip_client.u32StaticIP = _htonl(0xc0a80167); // Provide the required Static IP ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 16 ip_client.u32DNS = _htonl(0xc0a80101); // Provide DNS server details ip_client.u32SubnetMask = _htonl(0xFFFFFF00); // Provide the SubnetMask for the currently connected AP ip_client.u32Gateway = _htonl(0xc0a80101); // Provide the GAteway IP for the AP printf("Wi-Fi setting static ip\r\n"); m2m_wifi_set_static_ip(&ip_client); } } } 4.4 Power Save Modes The WINC firmware supports multiple Power Save modes which provide flexibility to the host MCU application to tweak the system power consumption. The host MCU can configure the WINC Power Saving policy using the m2m_wifi_set_sleep_mode and m2m_wifi_set_lsn_int APIs. The WINC supports the following Power Save modes: • M2M_PS_MANUAL • M2M_PS_DEEP_AUTOMATIC • M2M_PS_AUTOMATIC (deprecated, not be used in new implementations) • M2M_PS_H_AUTOMATIC (deprecated, not be used in new implementations) Note:  M2M_PS_DEEP_AUTOMATIC mode recommended for most applications. 4.4.1 M2M_PS_MANUAL This is a fully host-driven Power Save mode. • The WINC sleeps when the host uses the m2m_wifi_request_sleep API. During this period, the host MCU can also sleep for extended durations. • The WINC wakes up when the host MCU application requests services from the WINC by calling any host driver API function, for example, Wi-Fi or socket operation. Note:  In M2M_PS_MANUAL mode, when the WINC sleeps due to m2m_wifi_request_sleep API, the WINC does not wake up to receive and monitor AP beacon. Beacon monitoring is resumed when the host MCU application wakes up the WINC. For an active Wi-Fi connection, the AP may exit the connection if the WINC is unavailable due to long sleep time. If connection is dropped, the WINC detects the disconnection on the next wake-up cycle and notifies the host to reconnect to the AP again. To maintain an active Wi-Fi connection for extended durations, the host MCU application must periodically wake up the WINC in order to send a keep-alive Wi-Fi frame to the AP. The host must carefully choose the sleep period to satisfy the tradeoff between keeping the Wi-Fi connection uninterrupted and minimizing the system power consumption. This mode is useful for applications which send notifications very rarely due to a certain trigger. It also fits applications which periodically send notifications with a very long spacing between notifications. Careful power planning is required when using this mode. If the host MCU decides to sleep for a longer period, it may use M2M_PS_MANUAL or may power off the WINC3 . The advantage of this mode compared to powering off the WINC is that M2M_PS_MANUAL saves the time required for the WINC firmware to boot since the firmware is always loaded in the WINC memory. The real advantage and disadvantage depend on the nature of the application. In some applications, the sleep duration can be long enough to be a 3 Refer to the ATWINC15x0-MR210xB Data Sheet (DS70005304) for more information about the hardware power-up/down sequence. ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 17 power-efficient decision to power off the WINC and then power it on again and reconnect to the AP when the host MCU wakes up. In other situations, a latency-sensitive application may choose to use M2M_PS_MANUAL to avoid the WINC firmware boot latency on the expense of slightly increased power consumption. During the WINC Sleep mode, the WINC in M2M_PS_MANUAL mode saves more power than M2M_PS_DEEP_AUTOMATIC mode. In M2M_PS_MANUAL mode, the WINC skips beacon monitoring whereas in M2M_PS_DEEP_AUTOMATIC mode, it wakes up to receive beacons. The comparison also includes the effect of the host MCU sleep duration: if the host MCU sleeps for a longer period, the Wi-Fi connection may frequently drop and the power advantage of the M2M_PS_MANUAL mode is lost due to the power consumed in the Wi-Fi reconnection. In contrast, the M2M_PS_DEEP_AUTOMATIC mode can keep the Wi-Fi connection for long durations at the expense of waking up the WINC to monitor the AP beacon. 4.4.2 M2M_PS_AUTOMATIC This mode is deprecated and kept for backward compatibility and development reasons. It is not recommended to use in new implementations. 4.4.3 M2M_PS_H_AUTOMATIC This mode is deprecated and kept for backward compatibility and development reasons. It is not recommended to use in new implementations. 4.4.4 M2M_PS_DEEP_AUTOMATIC This mode implements the Wi-Fi standard power-saving method in the WINC module. The WINC sleeps and periodically wakes up to monitor AP beacons. The AP is required to buffer data while stations are in Power Save mode and transmit data when stations wake-up. The AP periodically transmits a beacon frame to synchronize with a network for every beacon period. A station, which is in Power Save mode, periodically wakes up to receive the beacon. The beacon conveys information to the station about pending unicast data, which are buffered inside the AP while the station was in Sleep mode. The beacon also provides information about the broadcast/multicast data. In this mode, the WINC module enters into Sleep state by turning off the IEEE 802.11 radio, MAC, and system clock. Prior to entering the Sleep mode, the ATWINC15x0 programs a hardware timer (running on an internal low-power oscillator) with a sleep period determined by the WINC firmware power management module. Any of the following events can wake-up the WINC module from Sleep state: • Expiry of the hardware sleep timer. The WINC wakes up to receive the upcoming beacon from AP. • The WINC wakes up4 when the host MCU application requests services from the WINC by calling any host driver API function, for example, Wi-Fi or socket operation. 4.5 Configuring Listen Interval and DTIM Monitoring The WINC allows the host MCU application to tweak system power consumption by configuring beacon monitoring parameters. The AP periodically send beacons for every DTIM period (for example, 100 ms). The beacon contains a TIM element which informs the station about the unicast data for the station that are buffered in the AP. The station negotiates with the AP for a listen interval. The listen interval tells the AP for how many beacon periods the station will sleep before it wakes up to receive data buffered in the 4 The wake-up sequence is internally handled in the WINC host driver by the hif_chip_wake API. Refer to Section 15 “Host Interface Protocol” for more information. ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 18 AP. Some APs might drop buffered data after Listen Interval elapses if the data is not retrieved by the station. The WINC driver allows the host MCU application to configure beacon monitoring parameters as follows: • Configure DTIM monitoring – that is to enable or disable reception of broadcast/multicast data using the following API: – m2m_wifi_set_sleep_mode(desired_mode, 1) to receive broadcast data – m2m_wifi_set_sleep_mode(desired_mode, 0) to ignore broadcast data • Configure the listen interval – using the m2m_wifi_set_lsn_int API Note:  Listen interval value provided to the m2m_wifi_set_lsn_int API is expressed in the unit of beacon period. ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 19 5. Wi-Fi Station Mode This chapter provides information about the WINC Wi-Fi Station (STA) mode as described in Wi-Fi Station Mode. The STA mode involves a scan operation; association to an AP using parameters (SSID and credentials) provided by the host MCU or using AP parameters stored in the WINC nonvolatile storage (default connection). The chapter also provides information about supported security modes along with code examples. 5.1 Scan Configuration Parameters 5.1.1 Scan Region The number of RF channels supported varies by geographical region. For example, 13 channels are supported in Asia while 11 channels are supported in North America. By default, the WINC initial region configuration is equal to 14 channels, but this can be changed by setting the scan region using the m2m_wifi_set_scan_region API. The scan region can be selected from the enum tenuM2mScanRegion. 5.1.2 Scan Options During Wi-Fi scan operation, the WINC sends probe request Wi-Fi frames and waits for the scan wait time to receive probe response frames in the current Wi-Fi channel. After the scan wait time, the WINC switches to the next channel. Increasing the scan wait time increases the possibility to detect more number of access points during scan operation but this leads to more power consumption and overall scan duration. The WINC firmware default scan wait time is optimized to provide the tradeoff between the power consumption and scan accuracy. The WINC firmware provides flexible configuration options to allow the host MCU application to set the scan time. For more details, refer to the m2m_wifi_set_scan_options API. 5.2 Wi-Fi Scan A Wi-Fi scan operation can be initiated by calling the m2m_wifi_request_scan API. The scan can be performed on all 2.4GHz Wi-Fi channels or on a specific requested channel. The scan response time depends on the scan options which can be set by calling m2m_wifi_set_scan_options(tstrM2MScanOption* ptstrM2MScanOption). For instance, if the host MCU application requests to scan all channels, the scan time is equal to NoOfChannels (13) * ptstrM2MScanOption->u8NumOfSlot * ptstrM2MScanOption->u8SlotTime. The scan operation is illustrated in the following figure. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 20 Figure 5-1. Wi-Fi Scan Operation 5.3 Wi-Fi Security The following types of security are supported in the WINC Wi-Fi STA mode. • OPEN • WEP (Wired Equivalent Protocol) • WPA/WPA2 (Wi-Fi Protected Access - Personal Security mode that is Passphrase) • 802.1X (WPA/WPA2-Enterprise security) For 802.1X Enterprise Security, the following authentication methods are supported from ATWINC1500 firmware version 19.6.1. • EAP-TLS • EAP-PEAPv0/TLS • EAP-PEAPv1/TLS • EAP-TTLSv0/MSCHAPv2 • EAP-PEAPv0/MSCHAPv2 ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 21 • EAP-PEAPv1/MSCHAPv2 The m2m_wifi_connect is deprecated from v19.6.1 and above firmware. The legacy APIs m2m_wifi_connect and m2m_wifi_connect_sc are available as wrappers for the new APIs. Functionally its behavior is unchanged from previously released drivers. The recommended API for various security type such as OPEN, WEP, WPA/WPA2, 802.1X are summarized in the Table 5-1. All new connect APIs, enable connection to a particular access point by specifying its BSSID and the SSID. To restrict connection to a specific access point, the application can specify the BSSID (in addition to SSID) in the argument tstrNetworkId -> pu8Bssid. The application can instruct the WINC whether to store the credentials or not to store in Flash and also whether the saved credentials must be encrypted or not. This is done by configuring the enum tenuCredStoreOption. For enterprise security, the application can configure WINC to send actual identity or use anonymous identity during phase 1 authentication. This can be done by setting or clearing bUnencryptedUserName in argument tstrAuth1xTls or tstrAuth1xMschap2. For more details on usage of API m2m_wifi_connect_1x_tls, refer ASF (v3.42 or above) example "WINC1500 Connecting a EAP-TLS / PEAPv0 with TLS / PEAPv1 with TLS Secured AP Example". For more details on usage of API m2m_wifi_connect_1x_mschap2, refer ASF (v3.42 or above) example "WINC1500 Connecting a EAP-TTLSv0 with MSCHAPv2 / EAP-PEAPv0 with MSCHAPv2 / EAP-PEAPv1 with MSCHAPv2 Secured AP Example". 5.4 On Demand Wi-Fi Connection The host MCU application may establish a Wi-Fi connection on demand when all the required connection parameters (SSID, security credentials, and so on.) are known to the application. To start a Wi-Fi connection on demand, the application calls the following APIs based on the security type. Table 5-1. List of APIs based on Security Type Security Type API Open m2m_wifi_connect_open WEP m2m_wifi_connect_wep WPA/WPA2 m2m_wifi_connect_psk 802.1x with MSCHAPv2 m2m_wifi_connect_1x_mschap2 802.1x with TLS m2m_wifi_connect_1x_tls Alternatively, the application can call the API m2m_wifi_connect to connect with an access point which supports Open, WEP, WPA/WPA2 and 802.1x with MSCHAPv2. m2m_wifi_connect is deprecated in v19.6.1 and is kept for legacy purpose. Note:  Using the API in the Table 5-1 implies that the host MCU application has prior knowledge of the connection parameters. For instance, connection parameters can be stored on nonvolatile storage attached to the host MCU. The Wi-Fi on demand connection operation is described in the following figure. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 22 Figure 5-2. On-demand Wi-Fi Connection 5.4.1 Example Code 5.4.1.1 Example Code for Connecting to Enterprise Network (PEAP and TTLSv0) with MSCHAPv2 as Phase2 Authentication #define MAIN_WLAN_SSID "WINC1500_ENTERPRISE" /**< Destination SSID */ #define MAIN_WLAN_802_1X_USR_NAME "DEMO_USER" /**< RADIUS user account name */ #define MAIN_WLAN_802_1X_PWD "DemoPassword" /**< RADIUS user account password */ int main(void) { int8_t ret; tstrWifiInitParam param; tstrNetworkId networkId; tstrAuth1xMschap2 mschapv2_credential; /* Initialize the board. */ system_init(); /* Initialize the UART console. */ configure_console(); printf(STRING_HEADER); /* Initialize the BSP. */ nm_bsp_init(); /* Initialize Wi-Fi parameters structure. */ memset((uint8_t *)¶m, 0, sizeof(tstrWifiInitParam)); /* Initialize Wi-Fi driver with data and status callbacks. */ param.pfAppWifiCb = wifi_cb; ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret) { printf("main: m2m_wifi_init call error!(%d)\r\n", ret); while (1) { } } ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 23 networkId.pu8Bssid = NULL; networkId.pu8Ssid = (uint8 *)MAIN_WLAN_SSID; networkId.u8SsidLen = strlen(MAIN_WLAN_SSID); networkId.enuChannel = M2M_WIFI_CH_ALL; mschapv2_credential.pu8Domain = NULL; //mschapv2_credential.u16DomainLen = strlen(mschapv2_credential.pu8Domain); mschapv2_credential.pu8UserName = (uint8 *)MAIN_WLAN_802_1X_USR_NAME; mschapv2_credential.pu8Password = (uint8 *)MAIN_WLAN_802_1X_PWD; mschapv2_credential.u16UserNameLen = strlen(MAIN_WLAN_802_1X_USR_NAME); mschapv2_credential.u16PasswordLen = strlen(MAIN_WLAN_802_1X_PWD); mschapv2_credential.bUnencryptedUserName = false; mschapv2_credential.bPrependDomain = true; printf("Connecting to %s\r\n\tUsername:%s\r\n", MAIN_WLAN_SSID, MAIN_WLAN_802_1X_USR_NAME); m2m_wifi_connect_1x_mschap2( WIFI_CRED_SAVE_ENCRYPTED, &networkId, &mschapv2_credential); /* Infinite loop to handle a event from the WINC1500. */ while (1) { while (m2m_wifi_handle_events(NULL) != M2M_SUCCESS) { } } return 0; } 5.4.1.2 Example Code for Connecting to PEAP Enterprise Network with TLS as Phase2 Authentication and EAP- TLS /** security information for Wi-Fi connection */ #define MAIN_WLAN_SSID "WINC1500_ENTERPRISE" /**< Destination SSID */ #define MAIN_WLAN_802_1X_USR_NAME "DEMO_USER" /**< RADIUS user account name */ const uint8_t modulus[] = { /** private key modulus extracted from key file */ }; const uint8_t exponent[] = { /** private key exponent coefficient extracted from key file */ }; const uint8_t certificate[] = { /** certificate coefficient corresponding to Private Key */ }; int main(void) { int8_t ret; tstrWifiInitParam param; tstrNetworkId networkId; tstrAuth1xTls tls_credential; /* Initialize the board. */ system_init(); /* Initialize the UART console. */ configure_console(); printf(STRING_HEADER); /* Initialize the BSP. */ nm_bsp_init(); /* Initialize Wi-Fi parameters structure. */ memset((uint8_t *)¶m, 0, sizeof(tstrWifiInitParam)); /* Initialize Wi-Fi driver with data and status callbacks. */ param.pfAppWifiCb = wifi_cb; ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret) { printf("main: m2m_wifi_init call error!(%d)\r\n", ret); while (1) { } } printf("Username:%s\r\n",MAIN_WLAN_802_1X_USR_NAME); /* Connect to the enterprise network. */ networkId.pu8Bssid = NULL; networkId.pu8Ssid = (uint8 *)MAIN_WLAN_SSID; networkId.u8SsidLen = strlen(MAIN_WLAN_SSID); networkId.enuChannel = M2M_WIFI_CH_ALL; ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 24 tls_credential.pu8Domain = NULL; tls_credential.pu8UserName = (uint8 *)MAIN_WLAN_802_1X_USR_NAME; tls_credential.pu8PrivateKey_Mod = (uint8 *)modulus; tls_credential.pu8PrivateKey_Exp = (uint8 *)exponent; tls_credential.pu8Certificate = (uint8 *)certificate; tls_credential.u16UserNameLen = strlen(MAIN_WLAN_802_1X_USR_NAME); tls_credential.u16PrivateKeyLen = sizeof(modulus); tls_credential.u16CertificateLen = sizeof(certificate); tls_credential.bUnencryptedUserName = true; tls_credential.bPrependDomain = true; printf("Connecting to %s...\r\n\t\tUsername:%s\r \n",networkId.pu8Ssid,tls_credential.pu8UserName); m2m_wifi_connect_1x_tls(WIFI_CRED_SAVE_ENCRYPTED, &networkId, &tls_credential); /* Infinite loop to handle a event from the WINC1500. */ while (1) { while (m2m_wifi_handle_events(NULL) != M2M_SUCCESS) { } } return 0; } 5.5 Default Connection The host MCU application establishes the default connection based on the connection profile stored in the WINC serial Flash using the m2m_wifi_default_connect API. This API does not require AP information to establish the connection. Note:  The connection profile information is automatically stored in the WINC Flash when on-demand WiFi connection API is called (see Table 5-1). Saving of this connection profile is dependent on the enum tenuCredStoreOption. The credentials such as passphrase of the AP or Enterprise certificate and other parameters like SSID, IP address, BSSID are encrypted using AES128-CBC before they are written into the serial Flash. This makes it difficult for an attacker to retrieve the sensitive information even if an attacker has physical access to the device. If there is no cached profile or if a connection cannot be established with any of the cached profile, an event of type M2M_WIFI_RESP_DEFAULT_CONNECT is delivered to the host driver indicating failure. Upon successful default connection, the host application can read the current Wi-Fi connection status by calling m2m_wifi_get_connection_info API. The m2m_wifi_get_connection_info is an asynchronous API. The actual connection information is provided in the asynchronous event M2M_WIFI_RESP_CONN_INFO in Wi-Fi callback. The callback parameter of type tstrM2MConnInfo provides information about AP SSID, RSSI (AP received power level), security type, IP address obtained by DHCP. Note:  A connection profile is cached in the serial Flash if and only if the connection is successfully established with the target AP. The Wi-Fi default connection operation is shown in the following figure. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 25 Figure 5-3. Wi-Fi Default Connection 5.6 Encrypted Credential Storage In ATWINC15x0 firmware v19.6.1 and above, the credentials such as passphrase of the AP or Enterprise certificate and other parameters like SSID, IP address, BSSID are encrypted using AES128-CBC before they are written into the serial Flash. This makes it difficult for an attacker to retrieve the sensitive information inspite of having physical access to the device. The encryption provided by this feature must not be considered secure. The encryption is only intended to prevent credentials being revealed in plain text by an opportunistic read of ATWINC15x0 Flash. Therefore, other security practices must be followed where possible, such as changing passwords regularly and deleting credentials when they are no longer required. When requesting for a connection to a network, the application can specify how the connection credentials must be stored in ATWINC15x0 Flash. The options are as follows: • Do not store credentials • Store credentials unencrypted • Store credentials encrypted The credentials consist of: • SSID • BSSID (if provided) • WEP key (for WEP connection) • Passphrase and PSK (for WPA/WPA2 PSK connection) • Domain, User name and Password (for WPA/WPA2 1x MSCHAPv2 connection) • Domain, User name, Certificate and Private Key (for WPA/WPA2 1x TLS connection) ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 26 The credentials are stored in ATWINC15x0 Flash when connection succeeds, and only one set of credentials is stored at a time; if new credentials need to be stored then the old credentials are removed (overwritten with 0’s). If credentials are stored in ATWINC15x0 Flash, then the application can request subsequent connections without providing the credentials again, using m2m_wifi_default_connect. If roaming is enabled, roaming can take place regardless of whether the credentials are stored in ATWINC15x0 Flash. (They are stored in data memory for the duration of a connection.) The application can delete credentials from ATWINC15x0 Flash using m2m_wifi_delete_sc. Note:  Version 19.6.1 firmware implements a new format for the ATWINC15x0 Flash store for connection parameters. The effects of this are: • During a firmware upgrade to v19.6.1, previously stored credentials are reformatted. After the first successful connection to an access point, these stored credentials are encrypted. • During a firmware upgrade to v19.6.1, previously stored IP address and Wi-Fi channel are deleted. • After a firmware downgrade from v19.6.1 to previous firmware, credentials stored by v19.6.1 firmware are not readable by the previous firmware. The operation of the previous firmware is otherwise unaffected. 5.7 Simple Roaming Simple Roaming is a custom feature which is supported by WINC firmware version 19.6.1 and above. With Simple Roaming feature enabled, the ATWINC1500 configured as station can move around in an ESS area with multiple access point. The WINC automatically switches to another AP which has the same SSID, authentication procedure and credentials with better signal strength. Roaming enables a station to change its AP while remaining connected to the network. The following figure explains the simple roaming feature. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 27 Figure 5-4. Simple Roaming STA AP in Range New AP Old AP (1) Probe Request (Ch 1) (2) Probe Response (Ch 1) (1) Probe Request (Ch n) (2) Probe Response (Ch n) (5) Authentication Request (6) Authentication Reply (7) Reassociation Request (12) Reassociation Reply (8) Send Security Block (9) Ack Security Block (10) Move Notify (11) Move Response In v19.6.1, the WINC roam occurs on link-loss detection with the existing AP, which is determined by tracking beacons and sending NULL frame keep-alive packets. ISO/OSI Layer 2 roaming occurs when the WINC roams from one AP to another AP, both of which are inside the same IP subnet. Layer 3 roaming occurs when the WINC roams from one AP to another AP which are in different subnets, whereby the WINC attempts to obtain a new IP address within the new subnet via DHCP. As a result of layer 3 roaming, any existing network connections is broken, and the upper layer protocols handle this IP address change if a continuous connection is required in layers 4 and above. Roaming algorithm is internal to WINC firmware. The Host MCU can enable or disable the roaming functionality using the API's m2m_wifi_enable_roaming and m2m_wifi_disable_roaming. The roaming must be called after the WINC initialization. When roaming is enabled, if the WINC successfully roamed to a new AP, then the M2M_WIFI_RESP_CON_STATE_CHANGED message with state as M2M_WIFI_ROAMED is sent to host MCU. If the WINC is not able to find a new AP, then M2M_WIFI_RESP_CON_STATE_CHANGED message with state as M2M_WIFI_DISCONNECTED is sent to the host MCU. The API call m2m_wifi_enable_roaming() sets the ATWINC15x0 to detect link-loss, and when link loss is detected with the existing access point, the following roaming steps are performed. • A precautionary de-authentication frame is sent to the old AP. • Scanning is performed to determine if there is an AP within the same ESS as the previous AP in the vicinity. • If an AP is found, authentication and re-association messages are exchanged with the new AP, followed by a normal 4-way security handshake in the case of WPA/WPA2, or an EAPOL exchange in the case of 802.1x Enterprise security. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 28 • A DHCP request is sent to the new AP to attempt to retain the same IP address. A notification event is sent to the host MCU of type M2M_WIFI_RESP_CON_STATE_CHANGE with the state of M2M_WIFI_ROAMED. Additionally, an M2M_WIFI_REQ_DHCP_CONF event conveying either the same or a new IP address is sent to the host MCU. • If there is any problem with the connection, or DHCP fails, then a de-authentication message is sent to the AP, and an M2M_WIFI_RESP_CON_STATE_CHANGED event is sent to the host MCU with the state set as M2M_WIFI_DISCONNECTED. The bEnableDhcp parameter enables control of whether or not a DHCP request is sent after roaming to a new AP. The API call m2m_wifi_disable_roaming is used to disable roaming. 5.8 Multiple Gain Table There are restrictions regarding the maximum transmit power of a wireless device according to the regulatory agencies of the region. For Wi-Fi devices, the maximum transmit power is limited according the regulation of the region in which the Wi-Fi device is used. The gain table can be used to configure the transmission power in WINC. The digital gain (DG) that are used for different channels and different data rates are stored in ATWINC15x0 Flash as a table called Gain table. In ATWINC15x0, the Power Amplifier (PA) and Pre-power Amplifier (PPA) values are configured in the firmware directly. The following figure shows the format of the gain table. Figure 5-5. Gain Table 1 2 3 4 5 6 7 8 9 10 11 12 13 14 1 -10 -9 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 2 -10 -9 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 5.5 -10 -9 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 11 -10 -9 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 6 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 9 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 12 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 18 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 24 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 36 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 48 -11 -8 -8 -8 -8 -8 -8 -8 -8 -8 -8 -8 -8 -8 54 -11 -9 -9 -9 -8 -8 -8 -8 -8 -8 -9 -8 -8 -8 mcs0 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs1 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs2 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs3 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs4 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs5 -12 -8 -8 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs6 -12 -9 -8 -8 -8 -8 -8 -8 -8 -8 -10 -8 -8 -8 mcs7 -12 -10 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 1e9c 0 1edc 0 Data Rates Channels Digital Gain Specific Configuration The Gain tables are provided as part of firmware update package in form of .csv file available at src/ firmware/Tools/gain_builder/gain_sheets folder. The gain values are downloaded as part of complete download process. For more details, see "WINC Devices – Integrated Serial Flash Memory Download Procedure" document. Prior to v19.6.1 only one gain table was supported in ATWINC15x0, with which the WINC can only operate in one regulatory region without requiring different Flash content. The ATWINC15x0 firmware version 19.6.1 or above supports multiple gain table and the Flash can store up to four gain tables. The table can be selected by the Host MCU using the API m2m_wifi_set_gain_table_idx. If the ATWINC15x0 has to operate in multiple region with maximum ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 29 transmit power allowed in that region, multiple gain table feature can be used to select gain table (by Host MCU) based on the region in which the ATWINC15x0 is operated. 5.8.1 Writing the Gain Table to ATWINC15x0 The gain builder application uses multiple .csv files (up to a maximum of 4) and perform the necessary maths operations on the gain table to calculate the gain values and write them to the Flash: gain_builder [-table ] [-index ][-no_wait] [-port] Note:  The img_path* parameters specify the separate tables, and the index parameter specifies the default table to use on power up. 5.8.2 Selecting a Specific Gain Table Setting the specific gain table index is achieved using API m2m_wifi_set_gain_table_idx. The m2m_wifi_set_gain_table_idx must be called after the initialization and before any connection request. The corresponding gain tables must be available in the Flash. Note:  The ATWINC15x0 firmware release v19.6.1 contains only one gain table that can be used in all the region. 5.9 Host File Download The Host File Download is a feature supported in the ATWINC15x0 firmware version 19.6.1 and above. This feature is supported only in the ATWINC1510 device which has 8 Mb Flash. The ATWINC1500 only has 4 Mbit of Flash memory and therefore this feature is not supported for the ATWINC1500. With Host file download feature, the Host MCU can instruct the ATWINC1510 to download a file and save it in the ATWINC1510 Flash. The ATWINC1510 can download the file from a HTTP or a HTTPS web server only. The maximum size of file that can be stored in the ATWINC1510 is 508 KB. This feature is ideal for updating the firmware of host MCU. However, the feature is not limited to MCU OTA only. When performing MCU OTA updates, there is no enforced file format, so the Application Developer can choose a strategy to perform integrity check validation on the received file. The WINC does not perform any integrity check on the downloaded file and therefore, it is recommended that the Application do it instead. The feature is designed for single file support and allows for a maximum size of 508 KB. The driver protects against invalid access to the file stored in the WINC’s Flash by using file handlers to identify each file. If a new download starts or if the file is erased, access to the file partition is denied. Also, the application can request an explicit erase to delete the file from the ATWINC’s Flash, destroying any potentially confidential data. The API m2m_ota_host_file_get is used to download file from remote location and store it in ATWINC1500 Flash. The m2m_ota_host_file_get can be used to download only one file at a time. When the get file API is called again, the previously stored file is erased and new file download is initiated. To retrieve the downloaded file from the ATWINC1510 Flash, m2m_ota_host_file_read_spi or m2m_ota_host_file_read_hif API can be used by the host MCU. The completion of file download is notified through the callback registered in m2m_ota_host_file_get API. The user can use the m2m_ota_host_file_read_spi or m2m_ota_host_file_read_hif API by passing required arguments to initiate the file read from the WINC Flash. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 30 5.9.1 Overview Whenever an application needs information which is stored in a file somewhere in a remote location, the application can use the Host File Download feature to retrieve the file from the remote location and temporarily store it in the WINC’s Flash. When a download is successfully completed, a file handler is generated and stored in NVM in the WINC, therefore it is valid even after a WINC reset. After a handler is generated, access to the file is possible via the provided APIs and reading of a file is possible via two mechanisms, HIF and SPI. In either case, the read operation requires the file handler of the file which the application is trying to access, if the handler being requested and the handler internally stored match, then the access is granted. The same procedure is valid for erasing the file. The use of a file handler avoids access to invalid data, for example when trying to concurrently access the file. The following figure depicts the steps which the WINC follows when performing a Host File Download. Figure 5-6. Host File Download Operation within the WINC OTA File Get Check Available Space Start Download OTA Get Successful OTA Get Failed Notify Host of the Result OK Failed Completed Failed The download starts only if the space available in Flash is enough to store the file which is requested to be downloaded. If Host File Download is requested in the ATWINC1500 (4 Mb Flash), the download fails since there is no Host File partition in Flash and therefore no space to store the file. The “Start Download” step causes any previously available valid file handler to be invalidated. When “OTA Get Successful” message is received, a new file handler is generated along with the status and the total size of the downloaded file, they are included in the Download completion notification sent to the host. 5.9.2 OTA Initialization To use the Host File Download feature, the WINC and the OTA driver must be initialized. The following is the procedure for OTA initialization: 1. m2m_wifi_init or m2m_wifi_reinit – this API is required to initialize the WINC and to set up the callback for the HIF communication. After this step, the WINC can be configured to connect to a network and download a file. For more details to understand when to use each of these two options, see the API documentation. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 31 2. m2m_ota_init – this API registers the OTA callback, which is required to execute any callbacks configured through the Host File Download APIs and to notify the Application of file download status. 5.9.3 Using Host File Download for MCU OTA Host File Download allows an application to download a file from a remote location. The link to the file can be through a secure connection and once the file is downloaded, it is stored in the WINC's Flash and the Application is notified about it. The files to download can be of any kind and are not limited to MCU binaries, making this feature both flexible and powerful. One example would be the download of text files, which can hold, for instance, a file checksum, which can later be used by the Application to verify the integrity of the downloaded binary. An Host MCU OTA requires the following steps: • Provide an http/https link to the file to tell WINC to download the file from a specific remote location, which can be done using API m2m_ota_host_file_get. • Read the image from the WINC using spi_flash_read. Since there is a limitation currently in which the bootloader would also need to perform m2m_wifi_init, m2m_ota_init and only then it should do m2m_ota_host_file_read_spi to read the image from WINC. m2m_ota_host_file_read_hif and m2m_ota_host_file_read_spi are not used in the ASF Example for MCU OTA to keep the driver footprint small while working around the limitation described above. However, this limitation is only present when the Application needs to be reset, or in this case switch to a bootloader, the WINC driver will lose track of the file handler and will have to load it again through the initialization process. If no reset or shutdown need to be performed and if no different Application needs to be loaded after downloading the file, these two APIs can be used. Figure 5-7. Example Host File Download for MCU OTA File Get CB Application WINC Bootloader WINC File Integrity Check Switch to Bootloader Switch to Application File Handler inval File Handler gen MCU & WINC Reset m2m_wifi_init() m2m_ota_init() **Connect to Wi-Fi network** m2m_ota_host_file_get() HIF Msg M2M_OTA_RESP_HOST_FILE_DOWNLOAD m2m_wifi_download_mode() spi_flash_read() ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 32 Other steps that must be considered by the Application Developer are: • It is recommended to verify the integrity of the image using a checksum calculation and match it against a previously known checksum. The user can design the validation mechanism since no predefined file format is enforced for MCU OTA. • There is an option to erase the file from Flash. Although this is not mandatory before requesting a new download, it can be useful for security purposes, ensuring that sensitive data is unavailable after its use. Note:  The WINC does not perform any integrity check of any of the downloaded files via Host File Download and that must be checked by the application. 5.9.4 API Description For a more detailed description of the APIs, refer to WINC1500_SW_API.chm. 5.9.4.1 OTA File Get NMI_API sint8 m2m_ota_host_file_get ( unsigned char *pcDownloadUrl, tpfFileGetCb pfHFDGetCb ); This API is used to get a file which links to the file stored remotely. The link is passed to the WINC to establish a TCP connection to retrieve the file from that location. It is also possible to use a server configured for TLS. A callback must also be provided so that it is executed when the File Get operation completes. The status of the File Get is passed onto this callback and if the status is successful, the file handler generated by the WINC and the total size of the downloaded file is passed correctly to the callback. 5.9.4.2 File Get Callback typedef void (*tpfFileGetCb) ( uint8 u8Status, uint8 u8Handler, uint32 u32Size ); The callback for the File Get receives three arguments; status of the File Get request, file handler ID and the total size of the file. If the status is OTA_STATUS_SUCCESS, then the file handler and size can be used, otherwise its values are not populated. From the Application’s point of view, they must not be considered valid. The file handler is auto-generated in the WINC and it identifies the file. Only when a download finishes successfully, the corresponding file handler is generated. The handler is required to both read from the file or erase the file. Similarly, if the download is aborted or interrupted, then the handler is not generated, instead the handler will have the value of HFD_INVALID_HANDLER, which blocks any further operation on the Flash through the APIs. When the file download completes successfully, the total size of the download file is passed to the callback to notify the application. Using which the application tracks the total size of the downloaded data and the amount of data read. 5.9.4.3 OTA File Read HIF NMI_API sint8 m2m_ota_host_file_read_hif ( uint8 u8Handler, uint32 u32Offset, uint32 u32Size, ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 33 tpfFileReadCb pfHFDReadCb ); When the download completes, the file is stored in the WINC’s Flash. This API can be used to read the file from the WINC using HIF messages. It is mandatory to have a valid handler, not having one could mean that the file has been invalidated and therefore it must be unavailable for any operation. This protects read against invalid or corrupted data. The offset marks the position in bytes of Flash to read from, counting from the beginning of the file. Therefore, an offset of zero is translated as reading from the beginning of the file. Size specifies the amount of bytes to read, starting at the offset defined. The last argument is the callback to be executed when the read is complete. Advantages (vs SPI read) • While reading a file using HIF messages, the host can continue operation, being notified by an interrupt from the WINC when data read is complete. • Does not require the WINC to be reset after the read is complete. Disadvantages (vs SPI read) • File reads via HIF are slightly slower than reads via SPI. 5.9.4.4 File Read HIF Callback typedef void (*tpfFileReadCb) ( uint8 u8Status, void *pBuff, uint32 u32Size ); The callback is only executed after a file read via HIF messages and it receives three arguments. • The first argument is the status of the read, if the read is unsuccessful, then the other arguments will have irrelevant values. • The second argument is a pointer to the buffer of data read. • The third argument is size, which indicates the amount of data read and therefore contained in the buffer (maximum 128 bytes). Specifying large amounts of data to be read via the HIF may exceed the buffer maximum size (128 bytes), therefore it is recommended to use u32Size to offset a second read from within this callback. This requires the application to track the total size of the file and the amount of bytes read, requesting the reading of each section at a time until the end of the file is reached. 5.9.4.5 OTA File Read SPI NMI_API sint8 m2m_ota_host_file_read_spi ( uint8 u8Handler, uint8 *pu8Buff, uint32 u32Offset, uint32 u32Size ); The file read via SPI is similar to the read via HIF. The use of a callback is not considered, because to access the WINC’s Flash via SPI, the WINC must be set into a certain mode to allow for safe read/write of its Flash. Therefore, it is typical to use a loop to read all the data necessary while the WINC is in that state and then restart the WINC. To use this API, the application must call m2m_wifi_download_mode to make the WINC safe for read/ write Flash access and once the read is completed, the WINC must be reinitialized (m2m_wifi_reinit, ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 34 m2m_ota_init) and to connect to the network again if the Application based on the request. pu8Buff is a pointer to a buffer provided by the Application and to where the data will be read to. Advantages (vs HIF read) • SPI read is faster than HIF Read. Disadvantages (vs HIF read) • Requires the WINC to set into a special mode and restart later. • Generally blocks as the read are done within a loop to minimize WINC reset. 5.9.4.6 OTA File Erase API NMI_API sint8 m2m_ota_host_file_erase ( uint8 u8Handler, tpfFileEraseCb pfHFDEraseCb ); The File Erase API requires the following two arguments: • The first argument is a handler of the file to erase, to ensure that it is valid to perform a Flash erase. • The second argument is a callback which executes when the erase is complete. Having a callback to tell the Application when the erase has been completed is useful to act as a trigger for a subsequent operation (example, download a second file). Note:  The file erase performs an erase of the entire host file partition and any file handler is destroyed regardless of the end result of the erase operation in the WINC. Since the data in the Flash is partially or completely destroyed, the handlers are invalidated when the process starts for safety. 5.9.4.7 File Erase Callback typedef void (*tpfFileEraseCb) ( uint8 u8Status ); The callback for a File Erase receives the erase status of the operation. A status of OTA_STATUS_SUCCESS ensures that the data has been completely erased, any other result does not ensure that the data is still valid, but also do not ensure that the data has been completely erased. 5.9.4.8 OTA Abort API NMI_API sint8 m2m_ota_abort ( void ); If a Host File Download has been started and the Application decides to cancel the download, it can issue a call to this API to do so. This does not require any input parameter. Note:  This API is shared with the WINC OTA and if issued when a WINC OTA is in progress, the WINC OTA is canceled. 5.9.5 Limitations • Out of 512 KB of Flash in the ATWINC1510, the first sector (of size 4 KB) is used by the WINC for storing the file information for host file download feature. Which means that a total of 508 KB size of Flash can be used by application to store the host file. • The feature is only supported in ATWINC1510 since the ATWINC1500 only has 4 Mbit of Flash memory, which means there is no space to store a file. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 35 • There is no file system and only one file is stored at a time. When the get file is called again, the previously stored file is erased and a new file download is initiated. • The WINC OTA firmware download and the Host OTA file download cannot run concurrently. • The WINC interprets 404 Not Found error when application attempts to download a broken or dead link and provides the OTA_STATUS_SERVER_ERROR error status. The WINC does not interpret any other message for broken link. The WINC downloads the error message into SPI Flash and indicates Host as file download. It is the application’s responsibility to check if the file is valid. 5.9.6 Built in Automated Test Equipment (ATE) Mechanism A factory flashed ATWINC15x0 module running the v19.6.1 firmware has a special ATE firmware in the Flash space reserved for OTA transfers (which is overwritten by the first OTA update). A host API can be called during WINC initialization that causes the device to boot into this special firmware (m2m_ate_init). The API to control the ATE functions provided by this firmware is detailed in \ASF\common\components\wifi\winc1500\driver\include\m2m_ate_mode.h. The following is the sample code. int main(void) { /* Initialize the board. */ system_init(); /* Initialize the UART console. */ configure_console(); printf(STRING_HEADER); /* Initialize the BSP. */ nm_bsp_init(); /*Check if initialization of ATE firmware is succeeded or not*/ if(M2M_SUCCESS == m2m_ate_init()) { /*Run TX test case if defined*/ #if (M2M_ATE_RUN_TX_TEST_CASE == ENABLE) start_tx_test(M2M_ATE_TX_RATE_1_Mbps_INDEX); #endif /*Run RX test case if defined*/ #if (M2M_ATE_RUN_RX_TEST_CASE == ENABLE) start_rx_test(); #endif /*De-Initialization of ATE firmware test mode*/ m2m_ate_deinit(); } else { M2M_ERR("Failed to initialize ATE firmware.\r\n"); while(1); } #if ((M2M_ATE_RUN_RX_TEST_CASE == ENABLE) && (M2M_ATE_RUN_TX_TEST_CASE == ENABLE)) M2M_INFO("Test cases have been finished.\r\n"); #else M2M_INFO("Test case has been finished.\r\n"); #endif while(1); } #if (M2M_ATE_RUN_TX_TEST_CASE == ENABLE) static void start_tx_test(uint8_t tx_rate) { tstrM2mAteTx tx_struct; ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 36 /*Initialize parameter structure*/ m2m_memset((uint8 *)&tx_struct, 0 , sizeof(tx_struct)); /*Set TX Configuration parameters, *refer to tstrM2mAteTx for more information about parameters*/ tx_struct.channel_num = M2M_ATE_CHANNEL_11; tx_struct.data_rate = m2m_ate_get_tx_rate(tx_rate); tx_struct.dpd_ctrl = M2M_ATE_TX_DPD_DYNAMIC; tx_struct.duty_cycle = M2M_ATE_TX_DUTY_1; tx_struct.frame_len = 1024; tx_struct.num_frames = 0; tx_struct.phy_burst_tx = M2M_ATE_TX_SRC_MAC; tx_struct.tx_gain_sel = M2M_ATE_TX_GAIN_DYNAMIC; tx_struct.use_pmu = M2M_ATE_PMU_DISBLE; tx_struct.cw_tx = M2M_ATE_TX_MODE_CW; tx_struct.xo_offset_x1000 = 0; /*Start TX Case*/ if(M2M_ATE_SUCCESS == m2m_ate_start_tx(&tx_struct)) { uint32 u32TxTimeout = M2M_ATE_TEST_DURATION_IN_SEC; M2M_INFO(">>Running TX Test case on CH<%02u>.\r\n", tx_struct.channel_num); do { nm_bsp_sleep(1000); printf("%02u\r", (unsigned int)u32TxTimeout); }while(--u32TxTimeout); if(M2M_ATE_SUCCESS == m2m_ate_stop_tx()) { M2M_INFO("Completed TX Test successfully.\r\n"); } } else { M2M_INFO("Failed to start TX Test case.\r\n"); } } #endif #if (M2M_ATE_RUN_RX_TEST_CASE == ENABLE) static void start_rx_test(void) { tstrM2mAteRx rx_struct; /*Initialize parameter structure*/ m2m_memset((uint8 *)&rx_struct, 0, sizeof(rx_struct)); /*Set RX Configuration parameters*/ rx_struct.channel_num = M2M_ATE_CHANNEL_6; rx_struct.use_pmu = M2M_ATE_PMU_DISBLE; rx_struct.xo_offset_x1000 = 0; /*Start RX Case*/ if(M2M_ATE_SUCCESS == m2m_ate_start_rx(&rx_struct)) { tstrM2mAteRxStatus rx_data; uint32 u32RxTimeout = M2M_ATE_TEST_DURATION_IN_SEC; M2M_INFO(">>Running RX Test case on CH<%02u>.\r\n", rx_struct.channel_num); do { m2m_ate_read_rx_status(&rx_data); M2M_INFO("Num Rx PKTs: %d, Num ERR PKTs: %d, PER: %1.3f", (int)rx_data.num_rx_pkts, (int)rx_data.num_err_pkts, (rx_data.num_rx_pkts>0)?((double)rx_data.num_err_pkts/ (double)rx_data.num_rx_pkts):(0)); nm_bsp_sleep(1000); }while(--u32RxTimeout); printf("\r\n"); if(M2M_ATE_SUCCESS == m2m_ate_stop_rx()) { M2M_INFO("Compeleted RX Test successfully.\r\n"); } } ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 37 else { M2M_INFO("Failed to start RX Test case.\r\n"); } } #endif ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 38 6. Socket Programming 6.1 Overview The ATWINC15x0 socket Application Programming Interface (API) allows the host MCU application to interact with intranet and remote internet hosts. The ATWINC15x0 socket API is based on the BSD (Berkeley) sockets. This chapter explains the ATWINC15x0 socket programming and how it differs from regular BSD sockets. Note:  The reader must have a basic understanding of the following topics before reading this chapter: • BSD sockets • TCP • UDP • Internet protocols 6.1.1 Socket Types The ATWINC15x0 socket API provides two types of sockets: • Datagram sockets (connectionless sockets) – uses the UDP protocol • Stream sockets (connection-oriented sockets) – uses the TCP protocol 6.1.2 Socket Properties Each ATWINC15x0 socket is identified by a unique combination of the following: • Socket ID – a unique identifier for each socket. This is the return value of the socket API. • Local socket address – a combination of the ATWINC15x0 IP address and port number assigned by the ATWINC15x0 firmware for the socket. • Protocol – transport layer protocol, either TCP or UDP. • Remote socket address – applicable only for TCP stream sockets. This is necessary since TCP is connection oriented. Each connection made to a specific IP address and port number requires a separate socket. The remote socket address can be obtained in the socket event callback which is described in the succeeding section. Note:  TCP port 53 and UDP port 53 represent two different sockets. 6.1.3 Limitations • The ATWINC15x0 sockets API support up to 7 TCP sockets and 4 UDP sockets. • The ATWINC15x0 sockets API support only IPv4. It does not support IPv6. 6.2 Sockets API 6.2.1 API Prerequisites • C header file socket.h – this includes all the necessary socket API function declarations. When using any ATWINC15x0 socket API as described in the following sections, the host MCU application must include the socket.h header file. • Initialization – the ATWINC15x0 socket API initializes once before calling any socket API function. This is done using the socketInit API described in Socket API Functions. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 39 6.2.2 Non-blocking Asynchronous Socket APIs Most ATWINC15x0 socket APIs are asynchronous function calls that do not block the host MCU application. The behavior of the ATWINC15x0 asynchronous APIs are described in Asynchronous Events. For example, the host MCU application can register an application-defined socket event callback function using the ATWINC15x0 socket API registerSocketCallback. When the host MCU application calls the socket API connect, the API returns a zero value (SUCCESS) immediately indicating that the request is accepted. The host MCU application must then wait for the ATWINC15x0 socket API to call the registered socket callback when the connection is established or if a connection time-out occurred. The socket callback function provides the necessary information to determine the connection status. 6.2.3 Socket API Functions The ATWINC15x0 socket API provides the following functions. 6.2.3.1 socketInit The host MCU application must call the API socketInit once during initialization. The API is a synchronous API. 6.2.3.2 registerSocketCallback The registerSocketCallback function allows the host MCU application to provide the ATWINC15x0 sockets with application-defined event callbacks for socket operations. The API is a synchronous API. The API registers the following callbacks: • The socket event callback • The DNS resolve callback The socket event callback is an application-defined function that is called by the ATWINC15x0 socket API whenever a socket event occurs. Within this handler, the host MCU application must provide an application-defined logic that handles the events of interest. The DNS resolve event handler is the application-defined function that is called by the ATWINC15x0 socket API to return the results of gethostbyname. By implication, this only occurs after the host MCU application has called the gethostbyname function. If successful, the callback provides the IP address for the desired domain name. 6.2.3.3 socket The socket function creates a new socket of a specified type and returns the corresponding socket ID. The API is a synchronous API. The socket ID is required by most other socket functions and is also passed as an argument to the socket event callback function to identify which socket generated the event. 6.2.3.4 connect The connect function is used with TCP sockets to establish a new connection to a TCP server. The connect function results in a SOCKET_MSG_CONNECT sent to the socket event handler callback upon completion. The connect event is sent when the TCP server accepts the connection or, if no remote host response is received, after a time-out interval of approximately 30 seconds. Note:  The SOCKET_MSG_CONNECT event callback provides a tstrSocketConnectMsg containing an error code. The error code value indicates: • Zero value to indicate the successful connection or ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 40 • Negative value to indicate an error due to a time-out condition or if connect is used with UDP socket. The following figure shows the ATWINC15x0 socket API connect to remote server host. Figure 6-1. TCP Client API Call Sequence 6.2.3.5 bind The bind function can be used for server operation for both UDP and TCP sockets. It is used to associate a socket with an address structure (port number and IP address). The bind function call results to a SOCKET_MSG_BIND event sent to the socket callback handler with the bind status. Calls to listen, send, sendto, recv, and recvfrom functions must not be issued until the bind callback is received. 6.2.3.6 listen The listen function is used for server operations with TCP stream sockets. After calling the listen API, the socket accepts a connection request from a remote host. The listen function causes a SOCKET_MSG_LISTEN event notification to be sent to the host after the socket port is ready to indicate listen operation success or failure. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 41 When a remote peer establishes a connection, a SOCKET_MSG_ACCEPT event notification is sent to the application. 6.2.3.7 accept The accept function is deprecated and calling this API has no effect. It is kept only for backward compatibility. Note:  The listen API implicitly accepts the TCP remote peer connections request. Figure 6-2. TCP Server API Call Sequence Although the accept function is deprecated, the SOCKET_MSG_ACCEPT event occurs whenever a remote host connects to the ATWINC15x0 TCP server. The event message contains the IP address and port number of the connected remote host. 6.2.3.8 send The send function is used by the application to send data to a remote host. The send function can be used to send either UDP or TCP data depending on the type of socket. • For a TCP socket a connection must be established first. • For a UDP socket, the recommended way is to use sendto API, where the destination address is defined. However, it is possible to use send API instead of sendto API. For this, at least one successful call must be made to sendto API prior to the consecutive calls of send function. This ensures that the destination address is saved in the ATWINC15x0 firmware. The send function generates a SOCKET_MSG_SEND event callback after the data is transmitted to the remote host. For TCP sockets, this event guarantees that the data is delivered to the remote host TCP/IP stack (the remote application must use the recv function to read the data). For UDP sockets, it means that the data is transmitted, but there is no guarantee that the data is delivered to the remote host as per UDP protocol. The application is responsible to guarantee data delivery in the UDP sockets case. The SOCKET_MSG_SEND event callback returns the size of the data transmitted of the transmission in the success case and zero or negative value in case of an error. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 42 6.2.3.9 sendto The sendto function is used by the application to send UDP data to a remote host. It can only be used with UDP sockets. The IP address and port of the destination remote host is included as a parameter to the sendto function. The SOCKET_MSG_SENDTO event callback returns the size of the data transmitted in the success case and zero or negative value in case of an error. 6.2.3.10 recv/recvfrom The recv and recvfrom functions are used to read data from TCP and UDP sockets, respectively, and their operation is otherwise identical. The host MCU application calls the recv or recvfrom function with a pre allocated buffer. When the SOCKET_MSG_RECV or SOCKET_MSG_RECVFROM event callback arrives, this buffer must have the received data. The received data size indicates the status as follows: • Positive – data is received • Zero – socket connection is terminated • Negative – indicates an error In the case of TCP sockets, it is recommended to call the recv function after each successful socket connection (client or server). Otherwise, the received data is buffered in the ATWINC15x0 firmware wasting the system's resources until the socket is explicitly closed using a close function call. 6.2.3.11 close The close function is used to release the resources allocated to the socket and, for a TCP stream socket, also terminate an open connection. Each call to the socket function must match with a call to the close function. In addition, sockets that are accepted on a server socket port must be closed using this function. 6.2.3.12 setsockopt The setsockopt function may be used to set socket options to control the socket behavior. The options supported are as follows: • SO_SET_UDP_SEND_CALLBACK – enables or disables the send /sendto event callbacks. The user may want to disable the sendto event callback for UDP sockets to enhance the socket connection throughput. • IP_ADD_MEMBERSHIP – enables subscribe to an IP Multicast address. • IP_DROP_MEMBERSHIP – enables unsubscribe to an IP Multicast address. • SOL_SSL_SOCKET – sets SSL Socket. The following are the options supported for SSL socket: – SO_SSL_BYPASS_X509_VERIF command allows opening of the SSL socket to bypass the X509 certification verification process. Example: struct sockaddr_in addr_in; int optVal =1; addr_in.sin_family = AF_INET; addr_in.sin_port = _htons(MAIN_HOST_PORT); addr_in.sin_addr.s_addr = gu32HostIp; /* Create secure socket */ if (tcp_client_socket < 0) { tcp_client_socket = socket(AF_INET, SOCK_STREAM, ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 43 SOCKET_FLAGS_SSL); } /* Check if socket was created successfully */ if (tcp_client_socket == -1) { printf("socket error.\r\n"); close(tcp_client_socket); return -1; } /* Enable X509 bypass verification */ setsockopt(tcp_client_socket, SOL_SSL_SOCKET,SO_SSL_BYPASS_X509_VERIF,&optVal,sizeof(optVal)); /* If success, connect to socket */ if (connect(tcp_client_socket, (struct sockaddr *)&addr_in, sizeof(struct sockaddr_in)) != SOCK_ERR_NO_ERROR) { printf("connect error.\r\n"); return SOCK_ERR_INVALID; } – SO_SSL_SNI command sets the Server Name Indicator (SNI). During TLS handshake process, client can indicate which hostname it is trying to connect by setting Server Name in (extended) client hello. SNI allows a server to present multiple certificates on the same IP address and TCP port number and hence allows multiple secure websites to be served by the same IP address without requiring all of the websites to use the same certificate. – SO_SSL_ENABLE_SNI_VALIDATION enables SNI validation functionality in case SNI is set. The server name validation is disabled by default. To enable server name validation, both SO_SSL_SNI and SO_SSL_ENABLE_SNI_VALIDATION must be set by the application through setsockopt() as shown in the example code snippet. When the SNI validation is enabled, the SNI is compared with the common name (CN) in the received server certificate. If the supplied SNI does not match the CN, the SSL connection will be forcibly closed by the ATWINC15x0 firmware. Example: #define MAIN_HOST_NAME "www.google.com" struct sockaddr_in addr_in; int optVal =1; addr_in.sin_family = AF_INET; addr_in.sin_port = _htons(MAIN_HOST_PORT); addr_in.sin_addr.s_addr = gu32HostIp; /* Create secure socket */ if (tcp_client_socket < 0) { tcp_client_socket = socket(AF_INET, SOCK_STREAM, SOCKET_FLAGS_SSL); } /* Check if socket was created successfully */ if (tcp_client_socket == -1) { printf("socket error.\r\n"); close(tcp_client_socket); return -1; } /* set SNI on SSL Socket */ setsockopt(tcp_client_socket, SOL_SSL_SOCKET,SO_SSL_SNI, MAIN_HOST_NAME,sizeof(MAIN_HOST_NAME)); /* Enable SSL SNI validation */ setsockopt(tcp_client_socket, SOL_SSL_SOCKET, SO_SSL_ENABLE_SNI_VALIDATION,&optVal,sizeof(optVal)); /* If success, connect to socket */ if (connect(tcp_client_socket, (struct sockaddr *)&addr_in, sizeof( ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 44 struct sockaddr_in)) != SOCK_ERR_NO_ERROR) { printf("connect error.\r\n"); return SOCK_ERR_INVALID; } – SO_SSL_ENABLE_SESSION_CACHING command allows the TLS to cache the session information to speed up the future TLS session establishment. Example: struct sockaddr_in addr_in; int optVal =1; addr_in.sin_family = AF_INET; addr_in.sin_port = _htons(MAIN_HOST_PORT); addr_in.sin_addr.s_addr = gu32HostIp; /* Create secure socket */ if (tcp_client_socket < 0) { tcp_client_socket = socket(AF_INET, SOCK_STREAM, SOCKET_FLAGS_SSL); } /* Check if socket was created successfully */ if (tcp_client_socket == -1) { printf("socket error.\r\n"); close(tcp_client_socket); return -1; } /* Enable SSL Session cache */ setsockopt(tcp_client_socket, SOL_SSL_SOCKET,SO_SSL_ENABLE_SESSION_CACHING,&optVal,sizeof(optVal)); /* If success, connect to socket */ if (connect(tcp_client_socket, (struct sockaddr *)&addr_in, sizeof(struct sockaddr_in)) != SOCK_ERR_NO_ERROR) { printf("connect error.\r\n"); return SOCK_ERR_INVALID; } WARNING SO_SSL_BYPASS_X509_VERIF is only provided for debugging and testing purposes. It is NOT recommended to use this socket option in production software applications. 6.2.3.13 gethostbyname The gethostbyname function is used to resolve a host name (for example, URL) to a host IP address via the Domain Name System (DNS). This is limited only to IPv4 addresses. The operation depends on the configuration of a DNS server IP address and access to the DNS hierarchy through the internet. After gethostbyname is called, a callback to the DNS resolver handler is made. If the IP address is determined, a positive value is returned. If it cannot be determined or if the DNS server is not accessible (30-second time-out), an IP address value of zero is indicated. Note:  An IP returns a zero value to indicate an error (for example, the internet connection is down or DNS is unavailable) and the host MCU application may try the function call gethostbyname again later. 6.2.4 Summary The following table summarizes the ATWINC15x0 socket API and shows its compatibility with BSD socket APIs. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 45 Table 6-1. ATWINC15x0 Socket API Summary BSD API ATWINC15x0 API ATWINC15x0 API Type Server/ Client TCP/UD P Brief socket socket Synchronous Both Both Creates a new socket. connect connect Asynchronous Client TCP Initializes a TCP connection request to a remote server. bind bind Asynchronous Server Both Binds a socket to an address (address/port). listen listen Asynchronous Server TCP Allows a bound socket to listen to remote connections for its local port. accept accept Deprecated, Implicit accept in listen. send send Asynchronous Both Both Sends packet. sendto sendto Asynchronous Both UDP Sends packet over UDP sockets. write - Not supported recv recv Asynchronous Both Both Receives packet. recvfrom recvfrom Asynchronous Both Both Receives packet. read - Not supported close close Synchronous Both Both Terminates the TCP connection and release system resources. gethostbyname gethostbyname Asynchronous Both Both Gets the IP address of a certain host name gethostbyaddr - Not supported select - Not supported poll - Not supported setsockopt setsockopt Synchronous Both Both Sets socket option. getsockopt Not supported htons/ntohs _htons/_ntohs Synchronous Both Both Converts 2 byte integer from the host representation to the Network byte order representation (and vice versa). ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 46 ...........continued BSD API ATWINC15x0 API ATWINC15x0 API Type Server/ Client TCP/UD P Brief htonl/ntohl21 _htonl/_ntohl Synchronous Both Both Converts 4 byte integer from the host representation to the Network byte order representation (and vice versa). 6.3 Socket Connection Flow In the following sub-sections, the TCP and UDP (client and server) operations are described in details. Figure 6-3. Typical Socket Connection Flow ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 47 6.3.1 TCP Client Operation The following figure shows the flow for transferring data with a TCP client. Figure 6-4. TCP Client Sequence Diagram Note:  1. The host application must register a socket notification callback function. The function must be of tpfAppSocketCb type and must handle socket event notifications appropriately. 2. If the client knows the IP of the server, it may call connect directly as shown in the figure above. If only the server URL is known, then the application must resolve the server URL first calling the gethostbyname API. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 48 6.3.2 TCP Server Operation Figure 6-5. TCP Server Sequence Diagram Note:  The host application must register a socket notification callback function. The function must be of type tpfAppSocketCb and must handle socket event notifications appropriately. 6.3.3 UDP Client Operation The following figure shows the flow for transferring data with a UDP client. Figure 6-6. UDP Client Sequence Diagram ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 49 Note:  1. The first send message must be performed with the sendto API with the destination address specified. 2. If further messages are sent to the same address, the send API can also be used. For more details, refer to send. 3. recv can be used instead of recvfrom. 6.3.4 UDP Server Operation The following figure shows the flow for transferring data after establishing a UDP server. Figure 6-7. UDP Server Sequence Diagram 6.3.5 DNS Host Name Resolution The following figure shows the flow of DNS host name resolution. Figure 6-8. DNS Resolution Sequence ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 50 Note:  1. The host application requests to resolve hostname (for example, http://www.foobar.com), by calling the function gethostbyname. 2. Before calling the gethostbyname, the application must register a DNS response callback function using the function registerSocketCallback. 3. After the ATWINC15x0 DNS_Resolver module obtains the IP Address (hostIP) corresponding to the given HostName, the dnsResolveCB is called with the hostIP. 4. If an error occurs or if the DNS request encounters a time-out, the dnsResolveCB is called with IP Address value zero indicating a failure to resolve the domain name. 6.4 Example Code This section provides code examples for different socket applications. For additional socket code examples, refer to the Wi-Fi Network Controller Software Programming Guide. 6.4.1 TCP Client Example Code SOCKET clientSocketHdl; uint8 rxBuffer[256]; /* Socket event handler. */ void tcpClientSocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if(sock == clientSocketHdl) { if(u8Msg == SOCKET_MSG_CONNECT) { // Connect Event Handler. tstrSocketConnectMsg *pstrConnect = (tstrSocketConnectMsg*)pvMsg; if(pstrConnect->s8Error == 0) { // Perform data exchange. uint8 acSendBuffer[256]; uint16 u16MsgSize; // Fill in the acSendBuffer with some data here // send data send(clientSocketHdl, acSendBuffer, u16MsgSize, 0); // Recv response from server. recv(clientSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } else { printf("TCP Connection Failed\n"); } } else if(u8Msg == SOCKET_MSG_RECV) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { // Process the received message. // Close the socket. close(clientSocketHdl); } } } } // This is the DNS callback. The response of gethostbyname is here. void dnsResolveCallback(uint8* pu8HostName, uint32 u32ServerIP) { struct sockaddr_in strAddr; ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 51 if(u32ServerIP != 0) { clientSocketHdl = socket(AF_INET,SOCK_STREAM,u8Flags); if(clientSocketHdl >= 0) { strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(443); strAddr.sin_addr.s_addr = u32ServerIP; connect(clientSocketHdl, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); } } else { printf("DNS Resolution Failed\n"); } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main. */ void tcpConnect(char *pcServerURL) { // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(tcpClientSocketEventHandler, dnsResolveCallback); // Resolve Server URL. gethostbyname((uint8*)pcServerURL); } 6.4.2 TCP Server Example Code SOCKET listenSocketHdl, acceptedSocketHdl; uint8 rxBuffer[256]; uint8 bIsfinished = 0; /* Socket event handler. */ void tcpServerSocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if(u8Msg == SOCKET_MSG_BIND) { tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg; if(pstrBind->status == 0) { listen(listenSocketHdl, 0); } else { printf("Bind Failed\n"); } } else if(u8Msg == SOCKET_MSG_LISTEN) { tstrSocketListenMsg *pstrListen = (tstrSocketListenMsg*)pvMsg; if(pstrListen->status != 0) { printf("listen Failed\n"); } } else if(u8Msg == SOCKET_MSG_ACCEPT) { // New Socket is accepted. tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg *)pvMsg; if(pstrAccept->sock >= 0) { // Get the accepted socket. acceptedSocketHdl = pstrAccept->sock; recv(acceptedSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } else ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 52 { printf("Accept Failed\n"); } } else if(u8Msg == SOCKET_MSG_RECV) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { // Process the received message // Perform data exchange uint8 acSendBuffer[256]; uint16 u16MsgSize; // Fill in the acSendBuffer with some data here // Send some data. send(acceptedSocketHdl, acSendBuffer, u16MsgSize, 0); // Recv response from client. recv(acceptedSocketHdl, rxBuffer, sizeof(rxBuffer), 0); // Close the socket when finished. if(bIsfinished) { close(acceptedSocketHdl); close(listenSocketHdl); } } } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main. */ void tcpStartServer(uint16 u16ServerPort) { struct sockaddr_in strAddr; // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(tcpServerSocketEventHandler, NULL); // Create the server listen socket. listenSocketHdl = socket(AF_INET, SOCK_STREAM, 0); if(listenSocketHdl >= 0) { strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(u16ServerPort); strAddr.sin_addr.s_addr = 0; //INADDR_ANY bind(listenSocketHdl, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); } } 6.4.3 UDP Client Example Code SOCKET clientSocketHdl; uint8 rxBuffer[256], acSendBuffer[256]; /* Socket event handler */ void udpClientSocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if((u8Msg == SOCKET_MSG_RECV) || (u8Msg == SOCKET_MSG_RECVFROM)) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { uint16 len; // Format a message in the acSendBuffer and put its length in len sendto(clientSocketHdl, acSendBuffer, len, 0, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); recvfrom(clientSocketHdl, rxBuffer, sizeof(rxBuffer), 0); ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 53 // Close the socket after finished close(clientSocketHdl); } } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main.*/ void udpClientStart(char *pcServerIP) { struct sockaddr_in strAddr; // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(udpClientSocketEventHandler, NULL); clientSocketHdl = socket(AF_INET,SOCK_STREAM,u8Flags); if(clientSocketHdl >= 0) { uint16 len; strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(1234); strAddr.sin_addr.s_addr = nmi_inet_addr(pcServerIP); // Format some message in the acSendBuffer and put its length in len sendto(clientSocketHdl, acSendBuffer, len, 0, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); recvfrom(clientSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } } 6.4.4 UDP Server Example Code SOCKET serverSocketHdl; uint8 rxBuffer[256]; /* Socket event handler.*/ void udpServerSocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if(u8Msg == SOCKET_MSG_BIND) { tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg; if(pstrBind->status == 0) { // call Recv recvfrom(serverSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } else { printf("Bind Failed\n"); } } else if(u8Msg == SOCKET_MSG_RECV) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { // Perform data exchange. uint8 acSendBuffer[256]; uint16 u16MsgSize; // Fill in the acSendBuffer with some data // Send some data to the same address. sendto(acceptedSocketHdl, acSendBuffer, u16MsgSize, 0, pstrRecvMsg-> strRemoteAddr, sizeof(pstrRecvMsg-> strRemoteAddr)); // call Recv recvfrom(serverSocketHdl, rxBuffer, sizeof(rxBuffer), 0); // Close the socket when finished. close(serverSocketHdl); } ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 54 } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main. */ void udpStartServer(uint16 u16ServerPort) { struct sockaddr_in strAddr; // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(udpServerSocketEventHandler, NULL); // Create the server listen socket. listenSocketHdl = socket(AF_INET, SOCK_DGRAM, 0); if(listenSocketHdl >= 0) { strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(u16ServerPort); strAddr.sin_addr.s_addr = 0; //INADDR_ANY bind(serverSocketHdl, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); } } ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 55 7. Transport Layer Security (TLS) Transport Layer Security (TLS) layer sits on top of TCP and provides security services including privacy, authenticity, and message integrity. Various security methods are available with TLS in the WINC firmware. 7.1 TLS Overview The ATWINC15x0 features an embedded low-memory footprint TLS protocol stack bundled within the WINC firmware. It features the following functionality: • Supports TLS versions TLS1.0, TLS1.1 and TLS1.2. • Supports TLS client operation with TLS client authentication. • Supports TLS Server mode. • A simple application interface to the TLS stack. The TLS functionality is abstracted by the ATWINC15x0 socket interface, hiding the implementation complexity from the application developer and minimizing the effort to port existing plain TCP code to TLS. 7.2 TLS Connection Establishment From the application’s point of view, the TLS functionality is wrapped behind the socket APIs. This hides the complexity of TLS from the application which can use the TLS in the same way as the TCP (non-TLS) client and server. The main difference between the TLS sockets and the regular TCP sockets is that the application sets the SOCKET_FLAGS_SSL while creating the TLS client and server listening sockets. The detailed sequence of TLS connection establishment is described in the following figure. Note:  • For proper TLS Client operation, ensure that both SOCKET_FLAGS_SSL flag and the correct port number is set in the TLS client application. For instance, an HTTP client application uses no flag when calling socket API function and connect to port 80. The same application source code becomes an HTTPS client application if you use the flag SOCKET_FLAGS_SSL and change the port number in connect API to port 433. • For proper TLS server operation, ensure that both SOCKET_FLAGS_SSL flag and the correct port number is set in the TLS server application. For instance, an HTTP server application uses no flag when calling socket API function and bind to port 80. The same application source code becomes an HTTPS server application, if you use the flag SOCKET_FLAGS_SSL and change the port number in bind API to port 443. ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 56 Figure 7-1. TLS Client Application Connection Establishment ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 57 Figure 7-2. TLS Server Application Connection Establishment 7.3 Server Certificate Installation 7.3.1 Technical Background 7.3.1.1 Public Key Infrastructure The TLS security is based on the Public Key Infrastructure PKI, in which: • A server has its public key stored in a digital certificate with X.509 standard format. • The server must have its X.509 certificate issued by Certificate Authority (CA) which in turn may be certified by another CA. ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 58 • This structure forms a chain of X.509 certificates known as chain of trust. • The top most CA of the Chain is known to be the Trusted Root Certificate Authority of the chain. 7.3.1.2 TLS Server Authentication • When a TLS client initiates a connection with a server, the server sends its X.509 certificate chain (may or may not include the root certificate) to the client. • The client must authenticate the Server (verify the Server identity) before starting data exchange. • The client must verify the entire certificate chain and also verify that the root certificate authority of the chain is in the client’s trusted root certificate store. 7.3.2 Adding a Certificate to the WINC Trusted Root Certificate Store • Before connecting to a TLS Server, the root certificate of the server must be installed on the ATWINC15x0. If this is not done, the TLS connection to the server is locally aborted by the WINC. • The root certificate must be in DER format. If it is not provided in DER format, it must be converted before installation. Refer to Section 17 “How to Generate Certificates” for certificate formats and conversion methods. • To install the certificate, execute root_certificate_downloader.exe with the following syntax: root_certificate_downloader.exe -n N File1.cer File2.cer .... FileN.cer 7.4 WINC TLS Limitations 7.4.1 Concurrent Connections Only 2 TLS concurrent connections are allowed. 7.4.2 TLS Supported Ciphers The ATWINC15x0 supports the following cipher suites (for both client and server modes). • TLS_DHE_RSA_WITH_AES_128_CBC_SHA • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 • TLS_RSA_WITH_AES_128_CBC_SHA • TLS_RSA_WITH_AES_128_CBC_SHA256 The ATWINC15x0 also optionally support the following ECC cipher suites. • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 • TLS_ECDHE_ ECDSA _WITH_AES_128_CBC_SHA256 7.4.3 Supported Hash Algorithms The current implementation (WINC firmware version 19.5.2 onwards) supports the following hash algorithms: • MD5 • SHA-1 • SHA256 • SHA384 • SHA512 • RSA 4096 ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 59 7.4.4 TLS Certificate Constraints For TLS server and TLS client authentication, the ATWINC15x0 can accept the following certificate types: • RSA certificates with key size no more than 2048 bits • ECDSA certificates only for NIST P256 EC Curve (secp256r1); conditionally supported 7.4.5 ECC Cipher Suite The ATWINC15x0 TLS library features support of ECC cipher suites. Although, the ATWINC15x0 device does not contain a built-in hardware accelerator for ECC math, the WINC TLS library leverages the ECC math from the host MCU. To perform the ECC computations needed by the ECC ciphers, an ECC hardware accelerator (or software library) on the host MCU is mandatory. The WINC TLS initializes with the ECC cipher suites disabled by default. The host MCU application can enable the ciphers via the API sslSetActiveCipherSuites. 7.5 SSL Client Code Example SOCKET sslSocketHdl; uint8 rxBuffer[256]; /* Socket event handler. */ void SSL_SocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if(sock == sslSocketHdl) { if(u8Msg == SOCKET_MSG_CONNECT) { // Connect event tstrSocketConnectMsg *pstrConnect = (tstrSocketConnectMsg*)pvMsg; if(pstrConnect->s8Error == 0) { // Perform data exchange. uint8 acSendBuffer[256]; uint16 u16MsgSize; // Fill in the acSendBuffer with some data here // Send some data. send(sock, acSendBuffer, u16MsgSize, 0); // Recv response from server. recv(sslSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } else { printf("SSL Connection Failed\n"); } } else if(u8Msg == SOCKET_MSG_RECV) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { // Process the received message here // Close the socket if finished. close(sslSocketHdl); } } } } /* This is the DNS callback. The response of gethostbyname is here. */ void dnsResolveCallback(uint8* pu8HostName, uint32 u32ServerIP) { struct sockaddr_in strAddr; if(u32ServerIP != 0) { ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 60 sslSocketHdl = socket(AF_INET,SOCK_STREAM,u8Flags); if(sslSocketHdl >= 0) { strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(443); strAddr.sin_addr.s_addr = u32ServerIP; connect(sslSocketHdl, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); } } else { printf("DNS Resolution Failed\n"); } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main.*/ void SSL_Connect(char *pcServerURL) { // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(SSL_SocketEventHandler, dnsResolveCallback); // Resolve Server URL. gethostbyname((uint8*)pcServerURL); } ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 61 8. Wi-Fi AP Mode 8.1 Overview This chapter provides an overview of the WINC Access Point (AP) mode and describes how to setup this mode and configure its parameters. In ATWINC1500 v19.6.1 firmware and above, the DHCP default gateway, DNS server and subnet mask can be customized when entering AP and provisioning modes. Earlier, the default gateway and DNS server is the same as the host IP of the WINC and the subnet mask is 255.255.255.0. Configuring these values allow the use of 0.0.0.0 for the default gateway and DNS server, allowing mobile devices to connect to the WINC AP without disconnecting from the mobile network. Using IPs other than 0.0.0.0 is possible but it is of no use since only one device can connect to the WINC AP at any time. 8.2 Setting the WINC AP Mode Set the WINC AP mode configuration parameters using the tstrM2MAPConfig structure. There are two functions to enable/disable the WINC AP mode: • sint8 m2m_wifi_enable_ap (CONST tstrM2MAPConfig* pstrM2MAPConfig) • sint8 m2m_wifi_disable_ap (void) For more details on API, refer to the Atmel Software Framework for ATWINC1500 (Wi-Fi). In ATWINC1500 v19.6.1 firmware and above, to maintain backwards compatibility with older drivers, new structures and APIs were introduced. To customize these fields when entering AP or provisioning mode the tstrM2MAPModeConfig structure must be populated and passed to the new m2m_wifi_enable_ap_ext() or m2m_wifi_start_provision_mode_ext() APIs. The tstrM2MAPModeConfig structure contains the original tstrM2MAPConfig structure for storing the AP SSID, password, and so on. and another tstrM2MAPConfigExt structure for configuring the default router, DNS server and subnet mask. 8.3 Limitations • The AP can only support a single associated station. Further connection attempts are rejected. • The ATWINC15x0 supports WPA2 security feature starting from the firmware version 19.5.x. • Concurrency (simultaneous STA and AP mode) is not supported. Prior to activating the AP mode, the host MCU application must disable the mode that is currently running. 8.4 Sequence Diagram Once AP mode is established, data interface does not exist before a station associates to the AP; therefore, the application needs to wait until it receives a notification via an event callback. This process is shown in the following figure. ATWINC15x0 Wi-Fi AP Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 62 Figure 8-1. ATWINC15x0 AP Mode Establishment 8.5 AP Mode Code Example The following example shows how to configure the ATWINC15x0 AP mode with WINC_SSID as broadcasted SSID on channel one with open security and an IP address equals 192.168.1.1. #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { switch(u8WiFiEvent) { case M2M_WIFI_REQ_DHCP_CONF: { uint8 *pu8IPAddress = (uint8*)pvMsg; printf("Associated STA has IP Address \"%u.%u.%u.%u\"\n", pu8IPAddress[0], pu8IPAddress[1], pu8IPAddress[2], pu8IPAddress[3]); } break; default: break; } } int main() { tstrWifiInitParam param; /* Platform specific initializations. */ ATWINC15x0 Wi-Fi AP Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 63 param.pfAppWifiCb = wifi_event_cb; if (!m2m_wifi_init(¶m)) { tstrM2MAPConfig apConfig; strcpy(apConfig.au8SSID, "WINC_SSID"); // Set SSID apConfig.u8SsidHide = SSID_MODE_VISIBLE; // Set SSID to be broadcasted apConfig.u8ListenChannel = 1; // Set Channel apConfig.u8SecType = M2M_WIFI_SEC_WEP; // Set Security to WEP apConfig.u8KeyIndx = 0; // Set WEP Key Index apConfig.u8KeySz = WEP_40_KEY_STRING_SIZE; // Set WEP Key Size strcpy(apConfig.au8WepKey, "1234567890"); // Set WEP Key // IP Address apConfig.au8DHCPServerIP[0] = 192; apConfig.au8DHCPServerIP[1] = 168; apConfig.au8DHCPServerIP[2] = 1; apConfig.au8DHCPServerIP[3] = 1; // Start AP mode m2m_wifi_enable_ap(&apConfig); while(1) { m2m_wifi_handle_events(NULL); } } } Note:  Power Save mode is not supported in the ATWINC15x0 AP mode. ATWINC15x0 Wi-Fi AP Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 64 9. Provisioning For normal operation the ATWINC15x0 device requires certain parameters to be loaded. In particular, when operating in Station mode, it must know the identity (SSID) and credentials of the access point to which it needs to connect. The entry of this information is facilitated through the following provisioning steps. The current ATWINC15x0 software supports the following methods of provisioning: • HTTP-based (browser) provisioning, while the WINC is in AP mode • Wi-Fi Protected Setup (WPS) 9.1 HTTP Provisioning In this method, the ATWINC15x0 is placed in AP mode and another device with a browser capability (mobile phone, tablet, PC, and so on) is instructed to connect to the ATWINC15x0 HTTP server. Once connected, the desired configuration can be entered. The HTTP Provisioning home page is as shown in the following figure. Figure 9-1. ATWINC15x0 HTTP Provisioning Page ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 65 9.1.1 Provisioning Control Flow Figure 9-2. HTTP Provisioning Sequence Diagram The preceding figure shows the provisioning operation for a WINC device. The detailed steps are described as follows: 1. The WINC device starts the HTTP Provisioning mode. 2. A user with a smartphone finds the WINC AP SSID in the Wi-Fi search list. 3. The user connects to the WINC AP. 4. The user launches the web browser and writes the WINC home page in the address bar. 5. If the HTTP redirect bit (bEnableHttpRedirect) is set in m2m_wifi_start_provision_mode API, then all http traffic (http://URL) from the associated device (Phone, PC, and so on) are redirected to the WINC HTTP Provisioning home page. Some phones display a notification message “sign in to Wi-Fi networks?” which, when accepted, automatically loads the WINC home page. The WINC home page, as shown in Figure 10.1, appears on the browser. 6. To discover the list of Wi-Fi APs in the area, the user can press “Refresh”. 7. The desired AP is then selected from the search list (by one click or one touch) and its name automatically appears in the “Network Name” text box. ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 66 8. The user must then enter the correct AP passphrase (for WPA/WPA2 personal security) in the “Pass Phrase” text box. If the desired AP uses open security, (M2M_WIFI_SEC_OPEN) then the Pass Phrase field is left empty. 9. A WINC device name may be optionally configured, if desired, by the user in the “Device Name” text box. 10. Then user should press Connect. The WINC turns off AP mode and start connecting to the provisioned AP. 9.1.2 HTTP Redirect Feature The ATWINC15x0 HTTP Provisioning server supports the HTTP redirect feature, which forces all HTTP traffic originating from the associated user device to be redirected to the ATWINC15x0 Provisioning home page. This simplifies the mechanism of loading the provisioning page instead of typing the exact web address of the HTTP Provisioning server. To enable this feature, set the redirect flag when calling the API m2m_wifi_start_provision_mode. For further details, refer to the following code example. 9.1.3 Provisioning Code Example void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { if(u8WiFiEvent == M2M_WIFI_RESP_PROVISION_INFO) { tstrM2MProvisionInfo *provInfo = (tstrM2MProvisionInfo*)pvMsg; if(provInfo->u8Status == M2M_SUCCESS) { // connect to the provisioned AP. m2m_wifi_connect((char*)provInfo->au8SSID, strlen(provInfo ->au8SSID), provInfo->u8SecType, provInfo->au8Password, M2M_WIFI_CH_ALL); printf("PROV SSID : %s\n", provInfo->au8SSID); printf("PROV PSK : %s\n", provInfo->au8Password); } else { printf("(ERR) Provisioning Failed\n"); } } } int main() { tstrWifiInitParam param; // Platform specific initializations. // Driver initialization. param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { tstrM2MAPConfig apConfig; uint8 bEnableRedirect = 1; strcpy(apConfig.au8SSID, "WINC_AP"); apConfig.u8ListenChannel = 1; apConfig.u8SecType = M2M_WIFI_SEC_OPEN; apConfig.u8SsidHide = 0; // IP Address apConfig.au8DHCPServerIP[0] = 192; apConfig.au8DHCPServerIP[1] = 168; apConfig.au8DHCPServerIP[2] = 1; apConfig.au8DHCPServerIP[0] = 1; m2m_wifi_start_provision_mode(&apConfig, "atmelconfig.com", bEnableRedirect); ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 67 while(1) { m2m_wifi_handle_events(NULL); } } } 9.2 Limitations The current implementation of the HTTP Provisioning has the following limitations: • The ATWINC15x0 AP limitations are applicable to the Provisioning mode. For a list of AP mode limitations, refer to Limitations. • Provisioning uses AP mode with open security. No Wi-Fi security nor application level security (for example, TLS) is used; therefore, the AP credentials entered by the user are sent on the clear and can be seen by eavesdroppers. • The WINC Provisioning home page is a static HTML page. No server-side scripting allowed in the WINC HTTP server. • Only APs with WPA-personal security (passphrase based) and no security (Open network) can be provisioned. WEP and WPA-Enterprise APs cannot be provisioned. • The Provisioning is responsible to deliver the connection parameters to the application, the connection procedure and the connection parameters validity are the application's responsibility. 9.3 Wi-Fi Protected Setup (WPS) Most modern Access Points support Wi-Fi Protected Setup method, typically using the push button method. From the user’s perspective WPS is a simple mechanism to make a device connect securely to an AP without remembering passwords or passphrases. WPS uses asymmetric cryptography to form a temporary secure link which is then used to transfer a passphrase (and other information) from the AP to the new station. After the transfer, secure connections are made as for normal static PSK configuration. 9.3.1 WPS Configuration Methods There are two authentication methods that can be used with WPS: 1. PBC (push button) method – A physical button is pressed on the AP which puts the AP into WPS mode for a limited period of time. WPS is initiated on the ATWINC15x0 by calling m2m_wifi_wps with input parameter WPS_PBC_TRIGGER. 2. PIN method – The AP is always available for WPS initiation but requires proof that the user has knowledge of an 8-digit PIN, usually printed on the body of the AP. Since the WINC is often used in headless devices (no user interface), it is necessary to reverse this process and force the AP to use a PIN number provided with the WINC device. Some APs allow the PIN to be changed through configuration. WPS is initiated on the ATWINC15x0 by calling m2m_wifi_wps with input parameter WPS_PIN_TRIGGER. Given the difficulty of this approach, it is not recommend for most applications. The flow of messages and actions for WPS operation is shown in the following figure. ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 68 9.3.2 WPS Control Flow Figure 9-3. WPS Operation for Push Button Trigger 9.3.3 WPS Limitations • WPS is used to transfer the WPA/WPA2 key only; other security types are not supported. • The WPS standard rejects the session (WPS response fail) if the WPS button is pressed on more than one AP in the same proximity, and the application can try again after a couple of minutes. • If no WPS button is pressed on the AP, the WPS scan will time-out after two minutes since the initial WPS trigger. • The WPS is responsible to deliver the connection parameters to the application, the connection procedure and the connection parameters’ validity is the application's responsibility. 9.3.4 WPS Code Example void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { if(u8WiFiEvent == M2M_WIFI_REQ_WPS) { tstrM2MWPSInfo *pstrWPS = (tstrM2MWPSInfo*)pvMsg; if(pstrWPS->u8AuthType != 0) { printf("WPS SSID : %s\n",pstrWPS->au8SSID); printf("WPS PSK : %s\n",pstrWPS->au8PSK); printf("WPS SSID Auth Type : %s\n", pstrWPS->u8AuthType == M2M_WIFI_SEC_OPEN ? "OPEN" : "WPA/WPA2"); printf("WPS Channel : %d\n",pstrWPS->u8Ch + 1); // Establish Wi-Fi connection m2m_wifi_connect((char*)pstrWPS->au8SSID, (uint8)m2m_strlen(pstrWPS->au8SSID), pstrWPS->u8AuthType, pstrWPS->au8PSK, pstrWPS->u8Ch); } ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 69 else { printf("(ERR) WPS Is not enabled OR Timedout\n"); } } } int main() { tstrWifiInitParam param; // Platform specific initializations. // Driver initialization. param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { // Trigger WPS in Push button mode. m2m_wifi_wps(WPS_PBC_TRIGGER, NULL); while(1) { m2m_wifi_handle_events(NULL); } } } ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 70 10. Over-The-Air Upgrade 10.1 Overview The ATWINC15x0 supports OTA upgrade of firmware on internal serial Flash. No host Flash memory resources are required to store the firmware. The ATWINC15x0 uses an internal HTTP client to retrieve the firmware from a remote server. 10.2 OTA Image Architecture The WINC serial Flash can store two copies of the firmware image: a working image and a rollback image. Upon first-time boot, the working image is the factory image and the rollback image will not be available in the WINC Flash. Instead ATE firmware will be available in rollback image firmware section. On performing the OTA firmware upgrade, the ATE firmware will be erased and the newly received firmware will be written into the Roll back image section. The WINC has insufficient internal memory to save the whole image in RAM during an OTA upgrade; therefore, each block of downloaded data is written to the Flash as it is received. In the event that the OTA fails, the existing (Working) image is retained and the rollback image is invalidated. If the transfer succeeds, the Flash control structure is updated to reflect a new working image and the existing image is marked as a valid rollback image. Figure 10-1. OTA Image Organization ATWINC15x0 Over-The-Air Upgrade © 2018 Microchip Technology Inc. User Guide DS00002389B-page 71 10.3 OTA Download Sequence Diagram Figure 10-2. OTA Image Download and Install 10.4 OTA Firmware Rollback Figure 10-3. OTA Image Rollback Sequence ATWINC15x0 Over-The-Air Upgrade © 2018 Microchip Technology Inc. User Guide DS00002389B-page 72 10.5 OTA Limitations • Rollback is allowed, only after at least one successful OTA download. • Rollback image is overwritten by any new successful or failed OTA attempt. 10.6 OTA Code Example /*! */ static void OtaUpdateCb(uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus) { if(u8OtaUpdateStatusType == DL_STATUS) { if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) { //switch to the upgraded firmware m2m_ota_switch_firmware(); } } else if(u8OtaUpdateStatusType == SW_STATUS) { if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) { M2M_INFO("Now OTA suceesfully done"); //start the host SW upgrade then system reset is required (Reintilize the driver) } } } void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { case M2M_WIFI_REQ_DHCP_CONF: { //after suceesfull connection, start the over air upgrade m2m_ota_start_update(OTA_URL); } break; default: break; } int main (void) { tstrWifiInitParam param; tstr1xAuthCredentials gstrCred1x = AUTH_CREDENTIALS; nm_bsp_init(); m2m_memset((uint8*)¶m, 0, sizeof(param)); param.pfAppWifiCb = wifi_event_cb; //intilize the WINC Driver ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret) { M2M_ERR("Driver Init Failed <%d>\n",ret); while(1); } //intilize the ota module m2m_ota_init(OtaUpdateCb,NULL); //connect to AP that provide connection to the OTA server m2m_wifi_default_connect(); while(1) { while(m2m_wifi_handle_events(NULL) != M2M_SUCCESS) {} } } Note:  For more details on example codes, refer to the Wi-Fi Network Controller Software Programming Guide. ATWINC15x0 Over-The-Air Upgrade © 2018 Microchip Technology Inc. User Guide DS00002389B-page 73 11. Multicast Sockets 11.1 Overview The purpose of the multicast filters is to provide the ability to send/receive messages to/from multicast addresses. This feature is useful for one-to-many communication over networks, whether it’s intended to send Internet Protocol (IP) datagrams to a group of interested receivers in a single transmission, participate in a zero-configuration networking or listening to a multicast stream or any other application. 11.2 How to Use Filters Whenever the application wishes to use a multicast IP address, for either sending or receiving, a filter is needed. The application can establish this through setting the IP_ADD_MEMBERSHIP option for the required socket accompanied by the multicast address that the application wants to use. If subsequently the host wants to stop receiving the multicast stream, set the IP_DROP_MEMBERSHIP option for the required socket accompanied with the multicast address. Adding or removing a multicast address filter causes the WINC chip firmware to add/remove both MAC layer filter and IP layer filter in order to pass or prevent messages from reaching to the host. 11.3 Multicast Socket Code Example To illustrate the functionality, a simple example is implemented where the host application responds to mDNS (Multicast Domain Name System) queries sent from a computer/mobile application. The computer/ mobile is looking for devices which support the zero configuration service as indicated by an mDNS response. The WINC responds, notifying its presence and its capability of sending and receiving multicast messages. The example consists of a UDP server that binds on port 5353 (mDNS port) and waits for messages, parsing them and replying with a previously saved response message. • Server Initialization: void MDNS_ServerInit() { tstrSockAddr strAddr ; unsigned int MULTICAST_IP = 0xE00000FB; //224.0.0.251 socketInit(); dns_server_sock = socket( AF_INET, SOCK_DGRAM,0); MDNS_INFO("DNS_server_init \n"); setsockopt(dns_server_sock,1,IP_ADD_MEMBERSHIP,&MULTICAST_IP,sizeof(MULTICAST_IP)); strAddr.u16Port =HTONS(MDNS_SERVER_PORT); bind(dns_server_sock,(struct sockaddr*)&strAddr,sizeof(strAddr)); registerSocketCallback(UDP_SocketEventHandler,AppServerCb); } • Sockets Events Handler: void MDNS_RecvfromCB(signed char sock,unsigned char *pu8RxBuffer,signed short s16DataSize, unsigned char *pu8IPAddr,unsigned short u16Port,void *pvArg) { MDNS_INFO("DnsServer_RecvfromCB \n"); if((pu8RxBuffer != 0) && (s16DataSize > 0)) { tstrDnsHdr strDnsHdr; strdnsquery; MDNS_INFO("DNS Packet Recieved \n"); ATWINC15x0 Multicast Sockets © 2018 Microchip Technology Inc. User Guide DS00002389B-page 74 if(MDNS_ParseQuery(&pu8RxBuffer[0], &strDnsHdr,&strDnsQuery)) MDNS_SendResp (sock,pu8IPAddr, u16Port,&strDnsHdr,&strDnsQuery ); } else { MDNS_INFO("DnsServer_RecvfromCB Error !\n"); } } • Server Socket Callback: void MDNS_RecvfromCB(signed char sock,unsigned char *pu8RxBuffer,signed short s16DataSize,unsigned char *pu8IPAddr,unsigned short u16Port,void *pvArg) { MDNS_INFO("DnsServer_RecvfromCB \n"); if((pu8RxBuffer != 0) && (s16DataSize > 0)) { tstrDnsHdr strDnsHdr ; strdnsquery ; MDNS_INFO("DNS Packet Recieved \n"); if(MDNS_ParseQuery(&pu8RxBuffer[0], &strDnsHdr,&strDnsQuery)) MDNS_SendResp (sock,pu8IPAddr, u16Port,&strDnsHdr,&strDnsQuery ); } else { MDNS_INFO("DnsServer_RecvfromCB Error !\n"); } } • Parse mDNS Query: int MDNS_ParseQuery(unsigned char * pu8RxBuffer, tstrDnsHdr *pstrDnsHdr, strdnsquery *pstrDnsQuery ) { unsigned char dot_size,temp=0; unsigned short n=0,i=0,u16index=0; int bDNSmatch = 0; /* ----Identification--------------------------|QR| Opcode |AA|TC|RD|RA|Z|AD|CD| Rcode | */ /* ----Total Questions------------------------|-----------------Total Answer RRs---------------*/ /* ----Total Authority RRs --------------------|----------------Total Additional RRs------------*/ /* --------------------------------- Questions --------------------------------- */ /* ------------------------------------ Answer RRs ------------------------------------------*/ /* ----------------------------------- Authority RRs ----------------------------------*/ /* -----------------------------------Additional RRs ----------------------------------*/ MDNS_INFO("Parsing DNS Packet\n"); pstrDnsHdr->id = (( pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("id = %.4x \n",pstrDnsHdr->id); u16index+=2; pstrDnsHdr->flags1= pu8RxBuffer[u16index++]; pstrDnsHdr->flags2= pu8RxBuffer[u16index++]; MDNS_INFO ("flags = %.2x %.2x \n",pstrDnsHdr->flags1,pstrDnsHdr->flags2); pstrDnsHdr->numquestions = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("numquestions = %.4x \n",pstrDnsHdr->numquestions); u16index+=2; pstrDnsHdr->numanswers = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("numanswers = %.4x \n",pstrDnsHdr->numanswers); u16index+=2; pstrDnsHdr->numauthrr = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("numauthrr = %.4x \n",pstrDnsHdr->numauthrr); u16index+=2; pstrDnsHdr->numextrarr = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("numextrarr = %.4x \n",pstrDnsHdr->numextrarr); u16index+=2; dot_size =pstrDnsQuery->query[n++]= pu8RxBuffer[u16index++]; pstrDnsQuery->u16size=1; ATWINC15x0 Multicast Sockets © 2018 Microchip Technology Inc. User Guide DS00002389B-page 75 while (dot_size--!=0) //(pu8RxBuffer[++u16index] != 0) { pstrDnsQuery->query[n++]=pstrDnsQuery->queryForChecking[i++]=pu8RxBuffer[u16index++] ; pstrDnsQuery->u16size++; gu8pos=temp; if (dot_size == 0 ) { pstrDnsQuery->queryForChecking[i++]= '.' ; temp=u16index; dot_size =pstrDnsQuery->query[n++]= pu8RxBuffer[u16index++]; pstrDnsQuery->u16size++; } } pstrDnsQuery->queryForChecking[--i] = 0; MDNS_INFO("parsed query <%s>\n",pstrDnsQuery->queryForChecking); // Search for any match in the local DNS table. for(n = 0; n < DNS_SERVER_CACHE_SIZE; n++) { MDNS_INFO("Saved URL <%s>\n",gpacDnsServerCache[n]); if(strcmp(gpacDnsServerCache[n], pstrDnsQuery->queryForChecking) ==0) { bDNSmatch= 1; MDNS_INFO("MATCH \n"); } else { MDNS_INFO("Mismatch\n"); } } pstrDnsQuery->u16class = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); u16index+=2; pstrDnsQuery->u16type= ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); return bDNSmatch; } • Send mDNS Response: void MDNS_SendResp (signed char sock,unsigned char * pu8IPAddr, unsigned short u16Port,tstrDnsHdr *pstrDnsHdr,strdnsquery *pstrDnsQuery) { unsigned short u16index=0; tstrSockAddr strclientAddr ; unsigned char * pu8sendBuf; char * serviceName2 = (char*)malloc(sizeof(serviceName)+1); unsigned int MULTICAST_IP = 0xFB0000E0; pu8sendBuf= gPu8Buf; memcpy(&strclientAddr.u32IPAddr,&MULTICAST_IP,IPV4_DATA_LENGTH); strclientAddr.u16Port=u16Port; MDNS_INFO("%s \n",pstrDnsQuery->query); MDNS_INFO("Query Size = %d \n",pstrDnsQuery->u16size); MDNS_INFO("class = %.4x \n",pstrDnsQuery->u16class); MDNS_INFO("type = %.4x \n",pstrDnsQuery->u16type); MDNS_INFO("PREPARING DNS ANSWER BEFORE SENDING\n"); /*----------------------------ID 2 Bytes -----------------------------*/ pu8sendBuf [u16index++] =0; //( pstrDnsHdr->id>>8); pu8sendBuf [u16index++] = 0;//( pstrDnsHdr->id)&(0xFF); MDNS_INFO ("(ResPonse) id = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*----------------------------Flags 2 Bytes----------------------------*/ pu8sendBuf [u16index++] = DNS_RSP_FLAG_1; pu8sendBuf [u16index++] = DNS_RSP_FLAG_2; MDNS_INFO ("(ResPonse) Flags = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*----------------------------No of Questions--------------------------*/ pu8sendBuf [u16index++] =0x00; pu8sendBuf [u16index++] =0x01; MDNS_INFO ("(ResPonse) Questions = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*---------------------------No of Answers----------------------------*/ pu8sendBuf [u16index++] =0x00; pu8sendBuf [u16index++] =0x01; MDNS_INFO ("(ResPonse) Answers = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); ATWINC15x0 Multicast Sockets © 2018 Microchip Technology Inc. User Guide DS00002389B-page 76 /*---------------------------No of Authority RRs------------------------*/ pu8sendBuf [u16index++] =0x00; pu8sendBuf [u16index++] =0x00; MDNS_INFO ("(ResPonse) Authority RRs = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*----------------------------No of Additional RRs----------------------*/ pu8sendBuf [u16index++] =0x00; pu8sendBuf [u16index++] =0x00; MDNS_INFO ("(ResPonse) Additional RRs = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*--------------------------------Query-----------------------------*/ memcpy(&pu8sendBuf[u16index],pstrDnsQuery->query,pstrDnsQuery->u16size); MDNS_INFO("\nsize = %d \n",pstrDnsQuery->u16size); u16index+=pstrDnsQuery->u16size; /*-------------------------------Query Type----------------------------*/ pu8sendBuf [u16index++] = ( pstrDnsQuery->u16type>>8);//MDNS_TYPE>>8; pu8sendBuf [u16index++] = ( pstrDnsQuery->u16type)&(0xFF);//(MDNS_TYPE&0xFF); MDNS_INFO ("Query Type = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*------------------------------Query Class-----------------------------------*/ pu8sendBuf [u16index++] =MDNS_CLASS>>8;//(( pstrDnsQuery->u16class>>8)|0x80); pu8sendBuf [u16index++] = (MDNS_CLASS & 0xFF);//( pstrDnsQuery->u16class)&(0xFF); MDNS_INFO ("Query Class = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*########################Answers#########################*/ /*------------------------------Name---------------------------------*/ pu8sendBuf [u16index++]= 0xC0 ; //pointer to query name location pu8sendBuf [u16index++]= 0x0C ; // instead of writing the whole query name again /*-----------------------------Type----------------------------------*/ pu8sendBuf [u16index++] =MDNS_TYPE>>8; //Type 12 PTR (domain name Pointer). pu8sendBuf [u16index++] =(MDNS_TYPE&0xFF); /*------------------------------Class-----------------------------------*/ pu8sendBuf [u16index++] =0x00;//MDNS_CLASS; //Class IN, Internet. pu8sendBuf [u16index++] =0x01;// (MDNS_CLASS & 0xFF); /*-----------------------------TTL----------------------------------*/ pu8sendBuf [u16index++] =(TIME_TO_LIVE >>24); pu8sendBuf [u16index++] =(TIME_TO_LIVE >>16); pu8sendBuf [u16index++] =(TIME_TO_LIVE >>8); pu8sendBuf [u16index++] =(TIME_TO_LIVE ); /*---------------------------Date Length----------------------------------*/ pu8sendBuf [u16index++] =(sizeof(serviceName)+2)>>8;//added 2 bytes for the pointer pu8sendBuf [u16index++] =(sizeof(serviceName)+2); /*-----------------------------DATA--------------------------------*/ convertServiceName(serviceName,sizeof(serviceName),serviceName2); memcpy(&pu8sendBuf[u16index],serviceName2,sizeof(serviceName)+1); u16index+=sizeof(serviceName); pu8sendBuf [u16index++] =0xC0;//Pointer to .local (from name) pu8sendBuf [u16index++] =gu8pos;//23 /*###########################################################*/ strclientAddr.u16Port=HTONS(MDNS_SERVER_PORT); // MultiCast RESPONSE sendto( sock, pu8sendBuf,(uint16)u16index,0,(struct sockaddr*)&strclientAddr,sizeof(strclientAddr)); strclientAddr.u16Port=u16Port; memcpy(&strclientAddr.u32IPAddr,pu8IPAddr,IPV4_DATA_LENGTH); } • Service Name: static char gpacDnsServerCache[DNS_SERVER_CACHE_SIZE][MDNS_HOSTNAME_SIZE] = { "_services._dns-sd._udp.local","_workstation._tcp.local","_http._tcp.local" }; unsigned char gPu8Buf [MDNS_BUF_SIZE]; unsigned char gu8pos ; signed char dns_server_sock ; #define serviceName "_ATMELWIFI._tcp" ATWINC15x0 Multicast Sockets © 2018 Microchip Technology Inc. User Guide DS00002389B-page 77 12. WINC Serial Flash Memory 12.1 Overview and Features The WINC has internal serial (SPI) Flash memory of 4 Mb capacity in the ATWINC1500 and 8 Mb capacity in the ATWINC1510. The Flash memory is used to store: • User configuration • Firmware • Connection Profiles During start-up and mode changes, firmware is loaded from the serial Flash into program memory (IRAM) in which the firmware is executed. The Flash is accessed at other points during run time to retrieve configuration and profile data. A minimum of 4 Mb Flash is required for OTA feature in order to store both working and rollback images. The Flash memory can be read, written and erased directly from the host without co-operation with the WINC firmware. However, if operational firmware is already loaded, it is necessary to halt any running WINC firmware first before accessing the serial Flash to avoid access conflict between the host and the WINC processor. 12.2 Accessing to Serial Flash • The host has transparent access to the serial (SPI) Flash through the WINC SPI Master. • The host can program the serial (SPI) Flash without the need for operational firmware in the WINC. The function m2m_wifi_download_mode must be called first. Figure 12-1. System Block Diagram showing SPI Flash Connection 12.3 Read/Write/Erase Operations SPI Flash can be accessed to be read, written and erased. It is required to change the WINC’s mode to Download mode first before attempting to access the SPI Flash by calling: sint32 m2m_wifi_download_mode(); ATWINC15x0 WINC Serial Flash Memory © 2018 Microchip Technology Inc. User Guide DS00002389B-page 78 All SPI Flash functions are blocking. A return of M2M_SUCCESS indicates that the requested operation is successfully completed. The following is a list of Flash functions that may be used: • Query the size of the SPI Flash: uint32 spi_flash_get_size(); This function returns with the size of the SPI Flash in Mb. • Read data from the SPI Flash: sint8 spi_flash_read(uint8 *pu8Buf, uint32 u32offset, uint32 u32Sz) Where the size of data is limited by the SPI Flash size. • Erase sectors in the SPI Flash: sint8 spi_flash_erase(uint32 u32Offset, uint32 u32Sz) Note:  The size is limited by the SPI Flash size. Prior to writing to any sector, erase this sector first. If some data needs to be changed within a sector, it is advised to read the sector first, modify the data and then erase and write the whole sector again. • Write data to the SPI Flash: sint8 spi_flash_write(uint8* pu8Buf, uint32 u32Offset, uint32 u32Sz) If the application wants to write any number of bytes within any sector, it has to erase the entire sector first. It may be necessary to read the entire sector, erase the sector and then write back with modifications. It is also recommended to verify that data is written after it returns success by reading data again and compare it with the original. 12.3.1 Flash Read, Erase, and Write Code Examples #include "spi_flash.h" #define DATA_TO_REPLACE "THIS IS A NEW SECTOR IN FLASH" int main() { uint8 au8FlashContent[FLASH_SECTOR_SZ] = {0}; uint32u32FlashTotalSize = 0, u32FlashOffset = 0; // Platform specific initializations. ret = m2m_wifi_download_mode(); if(M2M_SUCCESS != ret) { printf("Unable to enter download mode\r\n"); } else { u32FlashTotalSize = spi_flash_get_size(); } while((u32FlashTotalSize > u32FlashOffset) && (M2M_SUCCESS == ret)) { ret = spi_flash_read(au8FlashContent, u32FlashOffset, FLASH_SECTOR_SZ); if(M2M_SUCCESS != ret) { printf("Unable to read SPI sector\r\n"); break; } memcpy(au8FlashContent, DATA_TO_REPLACE, strlen(DATA_TO_REPLACE)); ATWINC15x0 WINC Serial Flash Memory © 2018 Microchip Technology Inc. User Guide DS00002389B-page 79 ret = spi_flash_erase(u32FlashOffset, FLASH_SECTOR_SZ); if(M2M_SUCCESS != ret) { printf("Unable to erase SPI sector\r\n"); break; } ret = spi_flash_write(au8FlashContent, u32FlashOffset, FLASH_SECTOR_SZ); if(M2M_SUCCESS != ret) { printf("Unable to write SPI sector\r\n"); break; } u32FlashOffset += FLASH_SECTOR_SZ; } if(M2M_SUCCESS == ret) { printf("Successful operations\r\n"); } else { printf("Failed operations\r\n"); } while(1); return M2M_SUCCESS; } ATWINC15x0 WINC Serial Flash Memory © 2018 Microchip Technology Inc. User Guide DS00002389B-page 80 13. Host Interface (HIF) Protocol Communication between the user application and the WINC device is facilitated by the driver software. This driver implements the Host Interface (HIF) Protocol and exposes an API to the application with various services. The services are broadly divided in two categories: Wi-Fi device control and IP Socket. The Wi-Fi device control services allow actions such as channel scanning, network identification, connection and disconnection. The Socket services allow data transfer once a connection is established and similar to BSD socket definitions. The host driver implements services asynchronously. This means that when the application calls an API to request a service action, the call is non-blocking and returns immediately, often before the action is completed. Where appropriate a notification that an action has completed is provided in a subsequent message from the WINC device to the host which is delivered to the application via a callback function. In general, the WINC firmware uses asynchronous events to signal the host driver of certain status changes. Asynchronous operation is essential where functions (such as Wi-Fi connection) may take significant time. When an API is called, a sequence of layers is activated to format the request and arranging to transfer it to the WINC device through the serial protocol. Note:  Dealing with HIF messages in the host MCU application is an advanced topic. For most applications, it is recommended to use Wi-Fi and socket layers. Both layers hide the complexity of the HIF APIs. After the application sends request, the Host Driver (Wi-Fi/Socket layer) formats the request and sends it to the HIF layer which then interrupts the WINC device to notify that a new request is posted. Upon receipt, the WINC firmware parses the request and starts the required operation. Figure 13-1. WINC Driver Layers The Host Interface Layer is responsible for handling communication between the host MCU and the WINC device. This includes interrupt handling, DMA control and management of the communication logic between the firmware driver in the host and the WINC firmware. The Request/Response sequence between the host and the WINC chip is shown in the following figure. ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 81 Figure 13-2. The Request/Response Sequence Diagram 13.1 Transfer Sequence Between the HIF Layer and the WINC Firmware The following section shows the individual steps taken during a HIF frame transmit (HIF message to the WINC) and a HIF frame receive (HIF message from the WINC). 13.1.1 Frame Transmit The following figure shows the steps and states involved in sending a message from the host to the WINC device. Figure 13-3. HIF Frame Transmit to WINC ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 82 Table 13-1. Steps in HIF Frame Transmit to WINC Step Description Step (1) Wake up the WINC device Wake up the device to be able to receive the host requests. Step (2) Interrupt the WINC device Prepare and set the HIF layer header to NMI_STATE_REG register (4 bytes header describing the sent packet). Set BIT [1] of WIFI_HOST_RCV_CTRL_2 register to raise an interrupt to the WINC chip. Step (3) Poll for DMA address Wait until the WINC chip clears BIT [1] of WIFI_HOST_RCV_CTRL_2 register. Get the DMA address (for the allocated memory) from register 0x150400. Step (4) Write data Write the data blocks in sequence, the HIF header then the Control buffer (if any) then the Data buffer (if any). Step (5) TX Done Interrupt Send a notification that writing the data is completed by setting BIT [1] of WIFI_HOST_RCV_CTRL_3 register. Step (6) Allow the WINC device to Sleep Allow the WINC device to enter Sleep mode again (if it wishes). 13.1.2 Frame Receive The following figure shows the steps and states involved in sending a message from the WINC device to the host. Figure 13-4. HIF Frame Receive from WINC to Host Table 13-2. Steps in HIF Frame Receive from WINC to Host Step Description Step (1) Wake up the WINC device Wake up the device to be able to receive host requests. Step (2) Check for Interrupt Monitor BIT [0] of WIFI_HOST_RCV_CTRL_0 register. Disable the host from receiving interrupts (until this interrupt is processed). Step (3) Clear interrupt Write zero to BIT [0] of WIFI_HOST_RCV_CTRL_0 register. ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 83 ...........continued Step Description Step (4) Read data Get the address of the data block from WIFI_HOST_RCV_CTRL_1 register. Read data block with size obtained from WIFI_HOST_RCV_CTRL_0 register BIT [13] <-> BIT [2]. Step (5) Process Request Parse the HIF header at the start of the data and forward the data to the appropriate registered Callback function. Step (6) HOST RX Done Raise an interrupt for the chip to free the memory holding the data by setting BIT [1] of WIFI_HOST_RCV_CTRL_0 register. Enable host interrupt reception again. Step (7) Allow the WINC device to Sleep Allow the WINC device to enter Sleep mode again (if it wishes). 13.2 HIF Message Header Structure The HIF message is the data structure exchanged back and forth between the Host Interface and the WINC firmware. The HIF message header structure consists of three fields: • The Group ID (8-bit) – a group ID is the category of the message. Valid categories are enumerated in tenuM2mReqGroup. • Op Code (8-bit) – is a command number. Valid command number is a value enumerated in: tenuM2mConfigCmd and tenuM2mStaCmd, tenuM2mApCmd, and tenuM2mP2pCmd corresponding to configuration, STA mode, AP mode, and P2P mode commands. Note:  • Refer to the m2m_types.h for the full list of commands. • The P2P mode is not supported after release v19.5.3. • Payload Length (16-bit) – the payload length is shown in bytes (does not include header). 13.3 HIF Layer APIs The interface between the application and the driver is done at the higher layer API interface (Wi-Fi / Socket.) As explained previously, the driver upper layer uses a lower layer API to access the services of the Host Interface Protocol. This section describes the Host Interface APIs that the upper layers use: The following API functions are described: ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 84 • hif_chip_wake • hif_chip_sleep • hif_register_cb • hif_isr • hif_receive • hif_send • hif_set_sleep_mode • hif_get_sleep_mode For all functions, the return value is either M2M_SUCCESS (zero) in case of success or a negative value in case of failure. • sint8 hif_chip_wake (void) – this function wakes the WINC chip from Sleep mode using clockless register access. It sets bit '1' of register 0x01 and sets the value of WAKE_REG register to WAKE_VALUE. • sint8 hif_chip_sleep (void) – this function enables Sleep mode for the WINC chip by setting the WAKE_REG register to a value of SLEEP_VALUE and clearing bit '1' of register 0x01. • sint8 hif_register_cb (uint8 u8Grp, tpfHifCallBack fn) – this function sets the callback function for different components (for example, M2M_WIFI, M2M_HIF, M2M_OTA and so on.). A callback is registered by upper layers to receive specific events of a specific message group. • sint8 hif_isr (void) – this is the host interface interrupt service routine. It handles interrupts generated by the WINC chip and parses the HIF header to call back the appropriate handler. • sint8 hif_receive (uint32 u32Addr, uint8 *pu8Buf, uint16 u16Sz, uint8 is Done) – this function causes the host driver to read data from the WINC chip. The location and length of the data must be known in advance and specified. This is typically extracted from an earlier part of a transaction. • sint8 hif_send (uint8 u8Gid, uint8 u8Opcode, uint8 *pu8CtrlBuf, uint16 u16CtrlBufSize, uint8 *pu8DataBuf, uint16 u16DataSize, uint16 16DataOffset) – this function causes the host driver to send data to the WINC chip. The WINC chip must be prepared for reception according to the flow described in the previous section. • void hif_set_sleep_mode (uint8 u8Pstype) – this function is used to set the Sleep mode of the HIF layer. • uint8 hif_get_sleep_mode (void) – this function return the Sleep mode of the HIF layer. 13.4 Scan Code Example The following code example illustrates the Request/Response flow on a Wi-Fi Scan request. Note:  For more details on example codes, refer to the Wi-Fi Network Controller Software Programming Guide. • The application requests a Wi-Fi scan. { m2m_wifi_request_scan(M2M_WIFI_CH_ALL); } • The host driver Wi-Fi layer formats the request and forward it to HIF (Host Interface) layer. sint8 m2m_wifi_request_scan(uint8 ch) { tstrM2MScan strtmp; sint8 s8Ret = M2M_ERR_SCAN_IN_PROGRESS; ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 85 strtmp.u8ChNum = ch; s8Ret = hif_send(M2M_REQ_GRP_WIFI, M2M_WIFI_REQ_SCAN, (uint8*)&strtmp, sizeof(tstrM2MScan),NULL, 0,0); return s8Ret; } • The HIF layer sends the request to the WINC chip. sint8 hif_send(uint8 u8Gid,uint8 u8Opcode,uint8 *pu8CtrlBuf,uint16 u16CtrlBufSize, uint8 *pu8DataBuf,uint16 u16DataSize, uint16 u16DataOffset) { sint8 ret = M2M_ERR_SEND; volatile tstrHifHdr strHif; strHif.u8Opcode = u8Opcode&(~NBIT7); strHif.u8Gid = u8Gid; strHif.u16Length = M2M_HIF_HDR_OFFSET; if(pu8DataBuf != NULL) { strHif.u16Length += u16DataOffset + u16DataSize; } else { strHif.u16Length += u16CtrlBufSize; } /* TX STEP (1) */ ret = hif_chip_wake(); if(ret == M2M_SUCCESS) { volatile uint32 reg, dma_addr = 0; volatile uint16 cnt = 0; reg = 0UL; reg |= (uint32)u8Gid; reg |= ((uint32)u8Opcode<<8); reg |= ((uint32)strHif.u16Length<<16); ret = nm_write_reg(NMI_STATE_REG,reg); if(M2M_SUCCESS != ret) goto ERR1; reg = 0; /* TX STEP (2) */ reg |= (1<<1); ret = nm_write_reg(WIFI_HOST_RCV_CTRL_2, reg); if(M2M_SUCCESS != ret) goto ERR1; dma_addr = 0; for(cnt = 0; cnt < 1000; cnt ++) { ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_2,(uint32 *)®); if(ret != M2M_SUCCESS) break; if (!(reg & 0x2)) { /* TX STEP (3) */ ret = nm_read_reg_with_ret(0x150400,(uint32 *)&dma_addr); if(ret != M2M_SUCCESS) { /*in case of read error clear the dma address and return error*/ dma_addr = 0; } /*in case of success break */ break; } } if (dma_addr != 0) { volatile uint32 u32CurrAddr; u32CurrAddr = dma_addr; strHif.u16Length=NM_BSP_B_L_16(strHif.u16Length); /* TX STEP (4) */ ret = nm_write_block(u32CurrAddr, (uint8*)&strHif, M2M_HIF_HDR_OFFSET); if(M2M_SUCCESS != ret) goto ERR1; u32CurrAddr += M2M_HIF_HDR_OFFSET; if(pu8CtrlBuf != NULL) { ret = nm_write_block(u32CurrAddr, pu8CtrlBuf, u16CtrlBufSize); if(M2M_SUCCESS != ret) goto ERR1; u32CurrAddr += u16CtrlBufSize; } ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 86 if(pu8DataBuf != NULL) { u32CurrAddr += (u16DataOffset - u16CtrlBufSize); ret = nm_write_block(u32CurrAddr, pu8DataBuf, u16DataSize); if(M2M_SUCCESS != ret) goto ERR1; u32CurrAddr += u16DataSize; } reg = dma_addr << 2; reg |= (1 << 1); /* TX STEP (5) */ ret = nm_write_reg(WIFI_HOST_RCV_CTRL_3, reg); if(M2M_SUCCESS != ret) goto ERR1; } else { /* ERROR STATE */ M2M_DBG("Failed to alloc rx size\r"); ret = M2M_ERR_MEM_ALLOC; goto ERR1; } } else { M2M_ERR("(HIF)Fail to wakup the chip\n"); goto ERR1; } /* TX STEP (6) */ ret = hif_chip_sleep(); ERR1: return ret; }